Software APIs
dt_dma.h
Go to the documentation of this file.
1
// Copyright lowRISC contributors (OpenTitan project).
2
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3
// SPDX-License-Identifier: Apache-2.0
4
//
5
// Device table API auto-generated by `dtgen`
6
7
#ifndef OPENTITAN_DT_DMA_H_
8
#define OPENTITAN_DT_DMA_H_
9
10
#ifdef __cplusplus
11
extern
"C"
{
12
#endif
// __cplusplus
13
14
/**
15
* @file
16
* @brief Device Tables (DT) for IP dma and top darjeeling.
17
*
18
* This file contains the type definitions and global functions of the dma.
19
*/
20
21
#include "hw/top/dt/dt_api.h"
22
#include <stdint.h>
23
24
25
26
/**
27
* List of instances.
28
*/
29
typedef
enum
dt_dma
{
30
kDtDma
= 0,
/**< dma */
31
kDtDmaFirst = 0,
/**< \internal First instance */
32
kDtDmaCount = 1,
/**< \internal Number of instances */
33
}
dt_dma_t
;
34
35
/**
36
* List of register blocks.
37
*
38
* Register blocks are guaranteed to start at 0 and to be consecutively numbered.
39
*/
40
typedef
enum
dt_dma_reg_block
{
41
kDtDmaRegBlockCore = 0,
/**< */
42
kDtDmaRegBlockCount = 1,
/**< \internal Number of register blocks */
43
}
dt_dma_reg_block_t
;
44
45
/**
46
* List of memories.
47
*
48
* Memories are guaranteed to start at 0 and to be consecutively numbered.
49
*/
50
typedef
enum
dt_dma_memory
{
51
kDtDmaMemoryCount = 0,
/**< \internal Number of memories */
52
}
dt_dma_memory_t
;
53
54
/** Primary register block (associated with the "primary" set of registers that control the IP). */
55
static
const
dt_dma_reg_block_t
kDtDmaRegBlockPrimary = kDtDmaRegBlockCore;
56
57
/**
58
* List of IRQs.
59
*
60
* IRQs are guaranteed to be numbered consecutively from 0.
61
*/
62
typedef
enum
dt_dma_irq
{
63
kDtDmaIrqDmaDone
= 0,
/**< DMA operation has been completed. */
64
kDtDmaIrqDmaChunkDone
= 1,
/**< Indicates the transfer of a single chunk has been completed. */
65
kDtDmaIrqDmaError
= 2,
/**< DMA error has occurred. DMA_STATUS.error_code register shows the details. */
66
kDtDmaIrqCount = 3,
/**< \internal Number of IRQs */
67
}
dt_dma_irq_t
;
68
69
/**
70
* List of Alerts.
71
*
72
* Alerts are guaranteed to be numbered consecutively from 0.
73
*/
74
typedef
enum
dt_dma_alert
{
75
kDtDmaAlertFatalFault
= 0,
/**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
76
kDtDmaAlertCount = 1,
/**< \internal Number of Alerts */
77
}
dt_dma_alert_t
;
78
79
/**
80
* List of clock ports.
81
*
82
* Clock ports are guaranteed to be numbered consecutively from 0.
83
*/
84
typedef
enum
dt_dma_clock
{
85
kDtDmaClockClk
= 0,
/**< Clock port clk_i */
86
kDtDmaClockCount = 1,
/**< \internal Number of clock ports */
87
}
dt_dma_clock_t
;
88
89
/**
90
* List of reset ports.
91
*
92
* Reset ports are guaranteed to be numbered consecutively from 0.
93
*/
94
typedef
enum
dt_dma_reset
{
95
kDtDmaResetRst
= 0,
/**< Reset port rst_ni */
96
kDtDmaResetCount = 1,
/**< \internal Number of reset ports */
97
}
dt_dma_reset_t
;
98
99
100
/**
101
* Get the dma instance from an instance ID
102
*
103
* For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
104
*
105
* @param inst_id Instance ID.
106
* @return A dma instance.
107
*
108
* **Note:** This function only makes sense if the instance ID has device type dma,
109
* otherwise the returned value is unspecified.
110
*/
111
dt_dma_t
dt_dma_from_instance_id
(
dt_instance_id_t
inst_id);
112
113
/**
114
* Get the instance ID of an instance.
115
*
116
* @param dt Instance of dma.
117
* @return The instance ID of that instance.
118
*/
119
dt_instance_id_t
dt_dma_instance_id
(
dt_dma_t
dt);
120
121
/**
122
* Get the register base address of an instance.
123
*
124
* @param dt Instance of dma.
125
* @param reg_block The register block requested.
126
* @return The register base address of the requested block.
127
*/
128
uint32_t
dt_dma_reg_block
(
129
dt_dma_t
dt,
130
dt_dma_reg_block_t
reg_block);
131
132
/**
133
* Get the primary register base address of an instance.
134
*
135
* This is just a convenience function, equivalent to
136
* `dt_dma_reg_block(dt, kDtDmaRegBlockCore)`
137
*
138
* @param dt Instance of dma.
139
* @return The register base address of the primary register block.
140
*/
141
static
inline
uint32_t dt_dma_primary_reg_block(
142
dt_dma_t
dt) {
143
return
dt_dma_reg_block
(dt, kDtDmaRegBlockCore);
144
}
145
146
/**
147
* Get the base address of a memory.
148
*
149
* @param dt Instance of dma.
150
* @param mem The memory requested.
151
* @return The base address of the requested memory.
152
*/
153
uint32_t
dt_dma_memory_base
(
154
dt_dma_t
dt,
155
dt_dma_memory_t
mem);
156
157
/**
158
* Get the size of a memory.
159
*
160
* @param dt Instance of dma.
161
* @param mem The memory requested.
162
* @return The size of the requested memory.
163
*/
164
uint32_t
dt_dma_memory_size
(
165
dt_dma_t
dt,
166
dt_dma_memory_t
mem);
167
168
/**
169
* Get the PLIC ID of a dma IRQ for a given instance.
170
*
171
* If the instance is not connected to the PLIC, this function
172
* will return `kDtPlicIrqIdNone`.
173
*
174
* @param dt Instance of dma.
175
* @param irq A dma IRQ.
176
* @return The PLIC ID of the IRQ of this instance.
177
*/
178
dt_plic_irq_id_t
dt_dma_irq_to_plic_id
(
179
dt_dma_t
dt,
180
dt_dma_irq_t
irq);
181
182
/**
183
* Convert a global IRQ ID to a local dma IRQ type.
184
*
185
* @param dt Instance of dma.
186
* @param irq A PLIC ID that belongs to this instance.
187
* @return The dma IRQ, or `kDtDmaIrqCount`.
188
*
189
* **Note:** This function assumes that the PLIC ID belongs to the instance
190
* of dma passed in parameter. In other words, it must be the case that
191
* `dt_dma_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
192
* will return `kDtDmaIrqCount`.
193
*/
194
dt_dma_irq_t
dt_dma_irq_from_plic_id
(
195
dt_dma_t
dt,
196
dt_plic_irq_id_t
irq);
197
198
199
/**
200
* Get the alert ID of a dma alert for a given instance.
201
*
202
* **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
203
* instances where the instance is not connected, the return value is unspecified.
204
*
205
* @param dt Instance of dma.
206
* @param alert A dma alert.
207
* @return The Alert Handler alert ID of the alert of this instance.
208
*/
209
dt_alert_id_t
dt_dma_alert_to_alert_id
(
210
dt_dma_t
dt,
211
dt_dma_alert_t
alert);
212
213
/**
214
* Convert a global alert ID to a local dma alert type.
215
*
216
* @param dt Instance of dma.
217
* @param alert A global alert ID that belongs to this instance.
218
* @return The dma alert, or `kDtDmaAlertCount`.
219
*
220
* **Note:** This function assumes that the global alert ID belongs to the
221
* instance of dma passed in parameter. In other words, it must be the case
222
* that `dt_dma_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
223
* this function will return `kDtDmaAlertCount`.
224
*/
225
dt_dma_alert_t
dt_dma_alert_from_alert_id
(
226
dt_dma_t
dt,
227
dt_alert_id_t
alert);
228
229
230
231
/**
232
* Get the clock signal connected to a clock port of an instance.
233
*
234
* @param dt Instance of dma.
235
* @param clk Clock port.
236
* @return Clock signal.
237
*/
238
dt_clock_t
dt_dma_clock
(
239
dt_dma_t
dt,
240
dt_dma_clock_t
clk);
241
242
/**
243
* Get the reset signal connected to a reset port of an instance.
244
*
245
* @param dt Instance of dma.
246
* @param rst Reset port.
247
* @return Reset signal.
248
*/
249
dt_reset_t
dt_dma_reset
(
250
dt_dma_t
dt,
251
dt_dma_reset_t
rst);
252
253
254
255
#ifdef __cplusplus
256
}
// extern "C"
257
#endif
// __cplusplus
258
259
#endif
// OPENTITAN_DT_DMA_H_
(darjeeling)
hw
top
dt
dt_dma.h
Return to
OpenTitan Documentation