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 "
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
/** Primary register block (associated with the "primary" set of registers that control the IP). */
46
static
const
dt_dma_reg_block_t
kDtDmaRegBlockPrimary = kDtDmaRegBlockCore;
47
48
/**
49
* List of IRQs.
50
*
51
* IRQs are guaranteed to be numbered consecutively from 0.
52
*/
53
typedef
enum
dt_dma_irq
{
54
kDtDmaIrqDmaDone
= 0,
/**< DMA operation has been completed. */
55
kDtDmaIrqDmaChunkDone
= 1,
/**< Indicates the transfer of a single chunk has been completed. */
56
kDtDmaIrqDmaError
= 2,
/**< DMA error has occurred. DMA_STATUS.error_code register shows the details. */
57
kDtDmaIrqCount = 3,
/**< \internal Number of IRQs */
58
}
dt_dma_irq_t
;
59
60
/**
61
* List of Alerts.
62
*
63
* Alerts are guaranteed to be numbered consecutively from 0.
64
*/
65
typedef
enum
dt_dma_alert
{
66
kDtDmaAlertFatalFault
= 0,
/**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
67
kDtDmaAlertCount = 1,
/**< \internal Number of Alerts */
68
}
dt_dma_alert_t
;
69
70
/**
71
* List of clock ports.
72
*
73
* Clock ports are guaranteed to be numbered consecutively from 0.
74
*/
75
typedef
enum
dt_dma_clock
{
76
kDtDmaClockClk
= 0,
/**< Clock port clk_i */
77
kDtDmaClockCount = 1,
/**< \internal Number of clock ports */
78
}
dt_dma_clock_t
;
79
80
/**
81
* List of reset ports.
82
*
83
* Reset ports are guaranteed to be numbered consecutively from 0.
84
*/
85
typedef
enum
dt_dma_reset
{
86
kDtDmaResetRst
= 0,
/**< Reset port rst_ni */
87
kDtDmaResetCount = 1,
/**< \internal Number of reset ports */
88
}
dt_dma_reset_t
;
89
90
91
/**
92
* Get the dma instance from an instance ID
93
*
94
* For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
95
*
96
* @param inst_id Instance ID.
97
* @return A dma instance.
98
*
99
* **Note:** This function only makes sense if the instance ID has device type dma,
100
* otherwise the returned value is unspecified.
101
*/
102
dt_dma_t
dt_dma_from_instance_id
(
dt_instance_id_t
inst_id);
103
104
/**
105
* Get the instance ID of an instance.
106
*
107
* @param dt Instance of dma.
108
* @return The instance ID of that instance.
109
*/
110
dt_instance_id_t
dt_dma_instance_id
(
dt_dma_t
dt);
111
112
/**
113
* Get the register base address of an instance.
114
*
115
* @param dt Instance of dma.
116
* @param reg_block The register block requested.
117
* @return The register base address of the requested block.
118
*/
119
uint32_t
dt_dma_reg_block
(
120
dt_dma_t
dt,
121
dt_dma_reg_block_t
reg_block);
122
123
/**
124
* Get the primary register base address of an instance.
125
*
126
* This is just a convenience function, equivalent to
127
* `dt_dma_reg_block(dt, kDtDmaRegBlockCore)`
128
*
129
* @param dt Instance of dma.
130
* @return The register base address of the primary register block.
131
*/
132
static
inline
uint32_t dt_dma_primary_reg_block(
133
dt_dma_t
dt) {
134
return
dt_dma_reg_block
(dt, kDtDmaRegBlockCore);
135
}
136
137
/**
138
* Get the PLIC ID of a dma IRQ for a given instance.
139
*
140
* If the instance is not connected to the PLIC, this function
141
* will return `kDtPlicIrqIdNone`.
142
*
143
* @param dt Instance of dma.
144
* @param irq A dma IRQ.
145
* @return The PLIC ID of the IRQ of this instance.
146
*/
147
dt_plic_irq_id_t
dt_dma_irq_to_plic_id
(
148
dt_dma_t
dt,
149
dt_dma_irq_t
irq);
150
151
/**
152
* Convert a global IRQ ID to a local dma IRQ type.
153
*
154
* @param dt Instance of dma.
155
* @param irq A PLIC ID that belongs to this instance.
156
* @return The dma IRQ, or `kDtDmaIrqCount`.
157
*
158
* **Note:** This function assumes that the PLIC ID belongs to the instance
159
* of dma passed in parameter. In other words, it must be the case that
160
* `dt_dma_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
161
* will return `kDtDmaIrqCount`.
162
*/
163
dt_dma_irq_t
dt_dma_irq_from_plic_id
(
164
dt_dma_t
dt,
165
dt_plic_irq_id_t
irq);
166
167
168
/**
169
* Get the alert ID of a dma alert for a given instance.
170
*
171
* **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
172
* instances where the instance is not connected, the return value is unspecified.
173
*
174
* @param dt Instance of dma.
175
* @param alert A dma alert.
176
* @return The Alert Handler alert ID of the alert of this instance.
177
*/
178
dt_alert_id_t
dt_dma_alert_to_alert_id
(
179
dt_dma_t
dt,
180
dt_dma_alert_t
alert);
181
182
/**
183
* Convert a global alert ID to a local dma alert type.
184
*
185
* @param dt Instance of dma.
186
* @param alert A global alert ID that belongs to this instance.
187
* @return The dma alert, or `kDtDmaAlertCount`.
188
*
189
* **Note:** This function assumes that the global alert ID belongs to the
190
* instance of dma passed in parameter. In other words, it must be the case
191
* that `dt_dma_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
192
* this function will return `kDtDmaAlertCount`.
193
*/
194
dt_dma_alert_t
dt_dma_alert_from_alert_id
(
195
dt_dma_t
dt,
196
dt_alert_id_t
alert);
197
198
199
200
/**
201
* Get the clock signal connected to a clock port of an instance.
202
*
203
* @param dt Instance of dma.
204
* @param clk Clock port.
205
* @return Clock signal.
206
*/
207
dt_clock_t
dt_dma_clock
(
208
dt_dma_t
dt,
209
dt_dma_clock_t
clk);
210
211
/**
212
* Get the reset signal connected to a reset port of an instance.
213
*
214
* @param dt Instance of dma.
215
* @param rst Reset port.
216
* @return Reset signal.
217
*/
218
dt_reset_t
dt_dma_reset
(
219
dt_dma_t
dt,
220
dt_dma_reset_t
rst);
221
222
223
224
#ifdef __cplusplus
225
}
// extern "C"
226
#endif
// __cplusplus
227
228
#endif
// OPENTITAN_DT_DMA_H_
(darjeeling)
hw
top
dt
dt_dma.h
Return to
OpenTitan Documentation