Software APIs
dt_api.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_TOP_ENGLISHBREAKFAST_DT_API_H_
8#define OPENTITAN_TOP_ENGLISHBREAKFAST_DT_API_H_
9
10#ifdef __cplusplus
11extern "C" {
12#endif // __cplusplus
13
14/**
15 * @file
16 * @brief Device Tables (DT) API for top englishbreakfast
17 *
18 * This file contains the type definitions and global functions of the DT.
19 *
20 * The DT models the chip as a collection of instances. Each instance has
21 * a type (the IP block) and a number of attributes such as I/Os, IRQs
22 * and so on. The DT also provides top-specific lists of global resources
23 * such as I/O pads, clocks and interrupts.
24 */
25
26#include <stddef.h>
27#include <stdint.h>
29
30/**
31 * List of device types.
32 *
33 * Device types are guaranteed to be numbered consecutively from 0.
34 */
35typedef enum dt_device_type {
36 kDtDeviceTypeUnknown = 0, /**< Instance of unknown type */
37 kDtDeviceTypeAes = 1, /**< instance of aes */
38 kDtDeviceTypeAonTimer = 2, /**< instance of aon_timer */
39 kDtDeviceTypeAst = 3, /**< instance of ast */
40 kDtDeviceTypeClkmgr = 4, /**< instance of clkmgr */
41 kDtDeviceTypeFlashCtrl = 5, /**< instance of flash_ctrl */
42 kDtDeviceTypeGpio = 6, /**< instance of gpio */
43 kDtDeviceTypePinmux = 7, /**< instance of pinmux */
44 kDtDeviceTypePwrmgr = 8, /**< instance of pwrmgr */
45 kDtDeviceTypeRomCtrl = 9, /**< instance of rom_ctrl */
46 kDtDeviceTypeRstmgr = 10, /**< instance of rstmgr */
47 kDtDeviceTypeRvCoreIbex = 11, /**< instance of rv_core_ibex */
48 kDtDeviceTypeRvPlic = 12, /**< instance of rv_plic */
49 kDtDeviceTypeRvTimer = 13, /**< instance of rv_timer */
50 kDtDeviceTypeSpiDevice = 14, /**< instance of spi_device */
51 kDtDeviceTypeSpiHost = 15, /**< instance of spi_host */
52 kDtDeviceTypeSramCtrl = 16, /**< instance of sram_ctrl */
53 kDtDeviceTypeUart = 17, /**< instance of uart */
54 kDtDeviceTypeUsbdev = 18, /**< instance of usbdev */
55 kDtDeviceTypeCount = 19, /**< \internal Number of instance types */
57
58/**
59 * List of instance IDs.
60 *
61 * Instance IDs are guaranteed to be numbered consecutively from 0.
62 */
63typedef enum dt_instance_id {
64 kDtInstanceIdUnknown = 0, /**< Unknown instance */
65 kDtInstanceIdAes = 1, /**< instance aes of aes */
66 kDtInstanceIdAonTimerAon = 2, /**< instance aon_timer_aon of aon_timer */
67 kDtInstanceIdAst = 3, /**< instance ast of ast */
68 kDtInstanceIdClkmgrAon = 4, /**< instance clkmgr_aon of clkmgr */
69 kDtInstanceIdFlashCtrl = 5, /**< instance flash_ctrl of flash_ctrl */
70 kDtInstanceIdGpio = 6, /**< instance gpio of gpio */
71 kDtInstanceIdPinmuxAon = 7, /**< instance pinmux_aon of pinmux */
72 kDtInstanceIdPwrmgrAon = 8, /**< instance pwrmgr_aon of pwrmgr */
73 kDtInstanceIdRomCtrl = 9, /**< instance rom_ctrl of rom_ctrl */
74 kDtInstanceIdRstmgrAon = 10, /**< instance rstmgr_aon of rstmgr */
75 kDtInstanceIdRvCoreIbex = 11, /**< instance rv_core_ibex of rv_core_ibex */
76 kDtInstanceIdRvPlic = 12, /**< instance rv_plic of rv_plic */
77 kDtInstanceIdRvTimer = 13, /**< instance rv_timer of rv_timer */
78 kDtInstanceIdSpiDevice = 14, /**< instance spi_device of spi_device */
79 kDtInstanceIdSpiHost0 = 15, /**< instance spi_host0 of spi_host */
80 kDtInstanceIdSramCtrlMain = 16, /**< instance sram_ctrl_main of sram_ctrl */
81 kDtInstanceIdUart0 = 17, /**< instance uart0 of uart */
82 kDtInstanceIdUart1 = 18, /**< instance uart1 of uart */
83 kDtInstanceIdUsbdev = 19, /**< instance usbdev of usbdev */
84 kDtInstanceIdCount = 20, /**< \internal Number of instance IDs */
86
87/**
88 * Get the instance type of a device instance.
89 *
90 * For example the instance type of `kDtUart0` is `kDtInstanceTypeUart`.
91 *
92 * @param id An instance ID.
93 * @return The instance type, or `kDtInstanceIdUnknown` if the ID is not valid.
94 */
96
97/** PLIC IRQ ID type.
98 *
99 * This type represents a raw IRQ ID from the PLIC.
100 *
101 * This is an alias to the top's `plic_irq_id_t` type for backward compatibility
102 * with existing code.
103 */
105
106/** PLIC IRQ ID for no interrupt. */
107static const dt_plic_irq_id_t kDtPlicIrqIdNone = kTopEnglishbreakfastPlicIrqIdNone;
108
109/**
110 * Get the instance ID for a given PLIC IRQ ID.
111 *
112 * For example, on earlgrey, the instance ID of `kTopEarlgreyPlicIrqIdUart0TxWatermark`
113 * is `kDtInstanceIdUart0`. One can then use the type specific function to retrieve the
114 * IRQ name, for example `dt_uart_irq_from_plic_id` for the UART.
115 *
116 * @param irq A PLIC ID.
117 * @return The instance ID, or `kDtInstanceIdUnknown` if the PLIC ID is not valid.
118 */
120
121/**
122 * List of clocks.
123 *
124 * Clocks are guaranteed to be numbered consecutively from 0.
125 */
126typedef enum dt_clock {
127 kDtClockMain = 0, /**< clock main */
128 kDtClockIo = 1, /**< clock io */
129 kDtClockUsb = 2, /**< clock usb */
130 kDtClockAon = 3, /**< clock aon */
131 kDtClockIoDiv2 = 4, /**< clock io_div2 */
132 kDtClockIoDiv4 = 5, /**< clock io_div4 */
133 kDtClockCount = 6, /**< \internal Number of clocks */
135
136/**
137 * Get the frequency of a clock.
138 *
139 * @param clk A clock ID.
140 * @return Clock frequency in Hz.
141 */
143
144/**
145 * List of resets.
146 *
147 * Resets are guaranteed to be numbered consecutively from 0.
148 */
149typedef enum dt_reset {
150 kDtResetUnknown = 0, /**< Unknown reset */
151 kDtResetPorAon = 1, /**< Reset node por_aon */
152 kDtResetLcSrc = 2, /**< Reset node lc_src */
153 kDtResetSysSrc = 3, /**< Reset node sys_src */
154 kDtResetPor = 4, /**< Reset node por */
155 kDtResetPorIo = 5, /**< Reset node por_io */
156 kDtResetPorIoDiv2 = 6, /**< Reset node por_io_div2 */
157 kDtResetPorIoDiv4 = 7, /**< Reset node por_io_div4 */
158 kDtResetPorUsb = 8, /**< Reset node por_usb */
159 kDtResetLc = 9, /**< Reset node lc */
160 kDtResetLcIoDiv4 = 10, /**< Reset node lc_io_div4 */
161 kDtResetSys = 11, /**< Reset node sys */
162 kDtResetSysIoDiv4 = 12, /**< Reset node sys_io_div4 */
163 kDtResetSysAon = 13, /**< Reset node sys_aon */
164 kDtResetSpiDevice = 14, /**< Reset node spi_device */
165 kDtResetSpiHost0 = 15, /**< Reset node spi_host0 */
166 kDtResetUsb = 16, /**< Reset node usb */
167 kDtResetCount = 17, /**< \internal Number of resets */
169
170/**
171 * List of pads names.
172 */
173typedef enum dt_pad {
174 kDtPadIoa0 = 0, /**< Muxed IO pad */
175 kDtPadIoa1 = 1, /**< Muxed IO pad */
176 kDtPadIoa2 = 2, /**< Muxed IO pad */
177 kDtPadIoa3 = 3, /**< Muxed IO pad */
178 kDtPadIoa4 = 4, /**< Muxed IO pad */
179 kDtPadIoa5 = 5, /**< Muxed IO pad */
180 kDtPadIoa6 = 6, /**< Muxed IO pad */
181 kDtPadIoa7 = 7, /**< Muxed IO pad */
182 kDtPadIoa8 = 8, /**< Muxed IO pad */
183 kDtPadIob0 = 9, /**< Muxed IO pad */
184 kDtPadIob1 = 10, /**< Muxed IO pad */
185 kDtPadIob2 = 11, /**< Muxed IO pad */
186 kDtPadIob3 = 12, /**< Muxed IO pad */
187 kDtPadIob4 = 13, /**< Muxed IO pad */
188 kDtPadIob5 = 14, /**< Muxed IO pad */
189 kDtPadIob6 = 15, /**< Muxed IO pad */
190 kDtPadIob7 = 16, /**< Muxed IO pad */
191 kDtPadIob8 = 17, /**< Muxed IO pad */
192 kDtPadIob9 = 18, /**< Muxed IO pad */
193 kDtPadIob10 = 19, /**< Muxed IO pad */
194 kDtPadIob11 = 20, /**< Muxed IO pad */
195 kDtPadIob12 = 21, /**< Muxed IO pad */
196 kDtPadIoc0 = 22, /**< Muxed IO pad */
197 kDtPadIoc1 = 23, /**< Muxed IO pad */
198 kDtPadIoc2 = 24, /**< Muxed IO pad */
199 kDtPadIoc3 = 25, /**< Muxed IO pad */
200 kDtPadIoc4 = 26, /**< Muxed IO pad */
201 kDtPadIoc5 = 27, /**< Muxed IO pad */
202 kDtPadIoc6 = 28, /**< Muxed IO pad */
203 kDtPadIoc7 = 29, /**< Muxed IO pad */
204 kDtPadIoc8 = 30, /**< Muxed IO pad */
205 kDtPadIoc9 = 31, /**< Muxed IO pad */
206 kDtPadIoc10 = 32, /**< Muxed IO pad */
207 kDtPadIoc11 = 33, /**< Muxed IO pad */
208 kDtPadIoc12 = 34, /**< Muxed IO pad */
209 kDtPadIor0 = 35, /**< Muxed IO pad */
210 kDtPadIor1 = 36, /**< Muxed IO pad */
211 kDtPadIor2 = 37, /**< Muxed IO pad */
212 kDtPadIor3 = 38, /**< Muxed IO pad */
213 kDtPadIor4 = 39, /**< Muxed IO pad */
214 kDtPadIor5 = 40, /**< Muxed IO pad */
215 kDtPadIor6 = 41, /**< Muxed IO pad */
216 kDtPadIor7 = 42, /**< Muxed IO pad */
217 kDtPadIor10 = 43, /**< Muxed IO pad */
218 kDtPadIor11 = 44, /**< Muxed IO pad */
219 kDtPadIor12 = 45, /**< Muxed IO pad */
220 kDtPadIor13 = 46, /**< Muxed IO pad */
221 kDtPadSpiHost0Sd0 = 47, /**< SPI host data */
222 kDtPadSpiHost0Sd1 = 48, /**< SPI host data */
223 kDtPadSpiHost0Sd2 = 49, /**< SPI host data */
224 kDtPadSpiHost0Sd3 = 50, /**< SPI host data */
225 kDtPadSpiDeviceSd0 = 51, /**< SPI device data */
226 kDtPadSpiDeviceSd1 = 52, /**< SPI device data */
227 kDtPadSpiDeviceSd2 = 53, /**< SPI device data */
228 kDtPadSpiDeviceSd3 = 54, /**< SPI device data */
229 kDtPadUsbdevUsbDp = 55, /**< */
230 kDtPadUsbdevUsbDn = 56, /**< */
231 kDtPadSpiDeviceSck = 57, /**< SPI device clock */
232 kDtPadSpiDeviceCsb = 58, /**< SPI device chip select */
233 kDtPadSpiHost0Sck = 59, /**< SPI host clock */
234 kDtPadSpiHost0Csb = 60, /**< SPI host chip select */
235 kDtPadCount = 61, /**< \internal Number of pads */
237
238/** Type of peripheral I/O. */
239typedef enum dt_periph_io_type {
240 /** This peripheral I/O is connected to a muxed IO (MIO). */
242 /** This peripheral I/O is connected to a direct IO (DIO). */
244 /** This peripheral I/O is not connected to either a MIO or a DIO. */
247
248
249/** Direction of a peripheral I/O. */
250typedef enum dt_periph_io_dir {
251 /** This peripheral I/O is an input. */
253 /** This peripheral I/O is an output */
255 /** This peripheral I/O is an input-output */
258
259/** Peripheral I/O description.
260 *
261 * A `dt_periph_io_t` represents a HW IP block peripheral I/O, which can be an input, output or both.
262 * Importantly, this only represents how the block peripheral I/O is wired, i.e.
263 * whether it is connected a MIO or a direct IO on the pinmux, and the relevant information necessary to
264 * configure it.
265 *
266 * **Note:** The fields of this structure are internal, use the dt_periph_io_* functions to access them.
267 */
268typedef struct dt_periph_io {
269 struct {
270 dt_periph_io_type_t type; /**< Peripheral I/O type */
271 dt_periph_io_dir_t dir; /**< Peripheral I/O direction */
272 /**
273 * For `kDtPeriphIoTypeMio`: peripheral input number. This is the index of the MIO_PERIPH_INSEL register
274 * that controls this peripheral I/O.
275 *
276 * For `kDtPeriphIoTypeDio`: DIO pad number. This is the index of the various DIO_PAD_* registers
277 * that control this peripheral I/O.
278 */
280 /**
281 * For `kDtPeriphIoTypeMio`: peripheral output number. This is the value to put in the MIO_OUTSEL registers
282 * to connect an output to this peripheral I/O. For `kDtPeriphIoTypeDio`: the pad index (`dt_pad_t`) to which this I/O is connected.
283 */
284 uint16_t outsel_or_dt_pad;
285 } __internal; /**< Private fields */
287
288
289/* Peripheral I/O that is constantly tied to high-Z (output only) */
290extern const dt_periph_io_t kDtPeriphIoConstantHighZ;
291
292/* Peripheral I/O that is constantly tied to one (output only) */
293extern const dt_periph_io_t kDtPeriphIoConstantZero;
294
295/* Peripheral I/O that is constantly tied to zero (output only) */
296extern const dt_periph_io_t kDtPeriphIoConstantOne;
297
298/**
299 * Return the type of a `dt_periph_io_t`.
300 *
301 * @param periph_io A peripheral I/O description.
302 * @return The peripheral I/O type (MIO, DIO, etc).
303 */
305 return periph_io.__internal.type;
306}
307
308/**
309 * Return the direction of a `dt_periph_io_t`.
310 *
311 * @param periph_io A peripheral I/O description.
312 * @return The peripheral I/O direction.
313 */
314static inline dt_periph_io_dir_t dt_periph_io_dir(dt_periph_io_t periph_io) {
315 return periph_io.__internal.dir;
316}
317
318/**
319 * Pinmux types.
320 *
321 * These types are aliases to top-level types for backward compatibility
322 * with existing code.
323 */
325typedef top_englishbreakfast_pinmux_insel_t dt_pinmux_insel_t;
326typedef top_englishbreakfast_pinmux_outsel_t dt_pinmux_outsel_t;
327typedef top_englishbreakfast_pinmux_mio_out_t dt_pinmux_mio_out_t;
328typedef top_englishbreakfast_direct_pads_t dt_pinmux_direct_pad_t;
329typedef top_englishbreakfast_muxed_pads_t dt_pinmux_muxed_pad_t;
330
331/** Tie constantly to zero. */
332static const dt_pinmux_outsel_t kDtPinmuxOutselConstantZero = kTopEnglishbreakfastPinmuxOutselConstantZero;
333
334/** Tie constantly to one. */
335static const dt_pinmux_outsel_t kDtPinmuxOutselConstantOne = kTopEnglishbreakfastPinmuxOutselConstantOne;
336
337/** Tie constantly to high-Z. */
338static const dt_pinmux_outsel_t kDtPinmuxOutselConstantHighZ = kTopEnglishbreakfastPinmuxOutselConstantHighZ;
339
340/**
341 * Return the peripheral input for an MIO peripheral I/O.
342 *
343 * This is the index of the `MIO_PERIPH_INSEL` pinmux register that controls this peripheral I/O.
344 *
345 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeMio`.
346 * @return The peripheral input number of the MIO that this peripheral I/O is connected to.
347 *
348 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeMio` which are
349 * inputs (`kDtPeriphIoDirIn`). For any other peripheral I/O, the return value is unspecified.
350 */
351static inline dt_pinmux_peripheral_in_t dt_periph_io_mio_periph_input(dt_periph_io_t periph_io) {
352 return (dt_pinmux_peripheral_in_t)periph_io.__internal.periph_input_or_direct_pad;
353}
354
355/**
356 * Return the outsel for an MIO peripheral I/O.
357 *
358 * This is the value to put in the `MIO_OUTSEL` pinmux registers to connect a pad to this peripheral I/O.
359 *
360 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeMio`.
361 * @return The outsel of the MIO that this peripheral I/O is connected to.
362 *
363 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeMio` which are
364 * outputs (`kDtPeriphIoDirOut`). For any other peripheral I/O, the return value is unspecified.
365 */
366static inline dt_pinmux_outsel_t dt_periph_io_mio_outsel(dt_periph_io_t periph_io) {
367 return (dt_pinmux_outsel_t)periph_io.__internal.outsel_or_dt_pad;
368}
369
370/**
371 * Return the direct pad number of a DIO peripheral I/O.
372 *
373 * This is the index of the various `DIO_PAD_*` pinmux registers that control this peripheral I/O.
374 *
375 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeDio`.
376 * @return The direct pad number of the DIO that this peripheral I/O is connected to.
377 *
378 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeDio` which are
379 * either outputs or inouts. For any other peripheral I/O type, the return value is unspecified.
380 */
381static inline dt_pinmux_direct_pad_t dt_periph_io_dio_pad_index(dt_periph_io_t periph_io) {
382 return (dt_pinmux_direct_pad_t)periph_io.__internal.periph_input_or_direct_pad;
383}
384
385/**
386 * Return the pad of a DIO peripheral I/O.
387 *
388 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeDio`.
389 * @return The pad to which this peripheral I/O is connected to.
390 *
391 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeDio` which are
392 * either outputs or inouts. For any other peripheral I/O type, the return value is unspecified.
393 */
394static inline dt_pad_t dt_periph_io_dio_pad(dt_periph_io_t periph_io) {
395 return (dt_pad_t)periph_io.__internal.outsel_or_dt_pad;
396}
397
398/** Type of a pad. */
399typedef enum dt_pad_type {
400 /** This pad is a muxed IO (MIO). */
402 /** This pad is a direct IO (DIO). */
404 /** This pad is not an MIO or a DIO. */
407
408/**
409 * Return the type of a `dt_pad_t`.
410 *
411 * @param pad A pad description.
412 * @return The pad type (MIO, DIO, etc).
413 */
415
416/**
417 * Return the pad out number for an MIO pad.
418 *
419 * This is the index of the `MIO_OUT` registers that control this pad
420 * (or the output part of this pad).
421 *
422 * @param pad A pad of type `kDtPadTypeMio`.
423 * @return The pad out number of the MIO.
424 *
425 * **Note:** This function only makes sense for pads of type `kDtPadTypeMio` which are
426 * either inputs or inouts. For any other pad, the return value is unspecified.
427 */
428dt_pinmux_mio_out_t dt_pad_mio_out(dt_pad_t pad);
429
430/**
431 * Return the pad out number for an MIO pad.
432 *
433 * This is the index of the `MIO_PAD` registers that control this pad
434 * (or the output part of this pad).
435 *
436 * @param pad A pad of type `kDtPadTypeMio`.
437 * @return The pad out number of the MIO.
438 *
439 * **Note:** This function only makes sense for pads of type `kDtPadTypeMio`.
440 * For any other pad, the return value is unspecified.
441 */
442dt_pinmux_muxed_pad_t dt_pad_mio_pad_index(dt_pad_t pad);
443
444/**
445 * Return the insel for an MIO pad.
446 *
447 * This is the value to put in the `MIO_PERIPH_INSEL` registers to connect a peripheral I/O to this pad.
448 *
449 * @param pad A pad of type `kDtPadTypeMio`.
450 * @return The insel of the MIO that this pad is connected to.
451 *
452 * **Note:** This function only makes sense for pads of type `kDtPadTypeMio`.
453 * For any other pad, the return value is unspecified.
454 */
455dt_pinmux_insel_t dt_pad_mio_insel(dt_pad_t pad);
456
457/**
458 * Return the direct pad number of a DIO pad.
459 *
460 * This is the index of the various `DIO_PAD_*` registers that control this pad.
461 *
462 * @param pad A pad of type `kDtPadTypeDio`.
463 * @return The direct pad number of the DID that this pad is connected to.
464 *
465 * **Note:** This function only makes sense for pads of type `kDtPeriphIoTypeDio` which are
466 * either outputs or inouts. For any other pad type, the return value is unspecified.
467 */
468dt_pinmux_direct_pad_t dt_pad_dio_pad_index(dt_pad_t pad);
469
470#ifdef __cplusplus
471} // extern "C"
472#endif // __cplusplus
473
474#endif // OPENTITAN_TOP_ENGLISHBREAKFAST_DT_API_H_