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