dt_api.h

Go to the documentation of this file.

// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
//
// Device table API auto-generated by `dtgen`
 
#ifndef OPENTITAN_TOP_ENGLISHBREAKFAST_DT_API_H_
#define OPENTITAN_TOP_ENGLISHBREAKFAST_DT_API_H_
 
/**
 * @file
 * @brief Device Tables (DT) API for top englishbreakfast
 *
 * This file contains the type definitions and global functions of the DT.
 *
 * The DT models the chip as a collection of instances. Each instance has
 * a type (the IP block) and a number of attributes such as I/Os, IRQs
 * and so on. The DT also provides top-specific lists of global resources
 * such as I/O pads, clocks and interrupts.
 */
 
#include <stddef.h>
#include <stdint.h>
#include "hw/top_englishbreakfast/sw/autogen/top_englishbreakfast.h"
 
/**
 * List of device types.
 *
 * Device types are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_device_type {
  kDtDeviceTypeUnknown = 0, /**< Instance of unknown type */
  kDtDeviceTypeAes = 1, /**< instance of aes */
  kDtDeviceTypeAonTimer = 2, /**< instance of aon_timer */
  kDtDeviceTypeAst = 3, /**< instance of ast */
  kDtDeviceTypeClkmgr = 4, /**< instance of clkmgr */
  kDtDeviceTypeFlashCtrl = 5, /**< instance of flash_ctrl */
  kDtDeviceTypeGpio = 6, /**< instance of gpio */
  kDtDeviceTypePinmux = 7, /**< instance of pinmux */
  kDtDeviceTypePwrmgr = 8, /**< instance of pwrmgr */
  kDtDeviceTypeRomCtrl = 9, /**< instance of rom_ctrl */
  kDtDeviceTypeRstmgr = 10, /**< instance of rstmgr */
  kDtDeviceTypeRvCoreIbex = 11, /**< instance of rv_core_ibex */
  kDtDeviceTypeRvPlic = 12, /**< instance of rv_plic */
  kDtDeviceTypeRvTimer = 13, /**< instance of rv_timer */
  kDtDeviceTypeSpiDevice = 14, /**< instance of spi_device */
  kDtDeviceTypeSpiHost = 15, /**< instance of spi_host */
  kDtDeviceTypeSramCtrl = 16, /**< instance of sram_ctrl */
  kDtDeviceTypeUart = 17, /**< instance of uart */
  kDtDeviceTypeUsbdev = 18, /**< instance of usbdev */
  kDtDeviceTypeCount = 19, /**< \internal Number of instance types */
} dt_device_type_t;
 
/**
 * List of instance IDs.
 *
 * Instance IDs are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_instance_id {
  kDtInstanceIdUnknown = 0, /**< Unknown instance */
  kDtInstanceIdAes = 1, /**< instance aes of aes */
  kDtInstanceIdAonTimerAon = 2, /**< instance aon_timer_aon of aon_timer */
  kDtInstanceIdAst = 3, /**< instance ast of ast */
  kDtInstanceIdClkmgrAon = 4, /**< instance clkmgr_aon of clkmgr */
  kDtInstanceIdFlashCtrl = 5, /**< instance flash_ctrl of flash_ctrl */
  kDtInstanceIdGpio = 6, /**< instance gpio of gpio */
  kDtInstanceIdPinmuxAon = 7, /**< instance pinmux_aon of pinmux */
  kDtInstanceIdPwrmgrAon = 8, /**< instance pwrmgr_aon of pwrmgr */
  kDtInstanceIdRomCtrl = 9, /**< instance rom_ctrl of rom_ctrl */
  kDtInstanceIdRstmgrAon = 10, /**< instance rstmgr_aon of rstmgr */
  kDtInstanceIdRvCoreIbex = 11, /**< instance rv_core_ibex of rv_core_ibex */
  kDtInstanceIdRvPlic = 12, /**< instance rv_plic of rv_plic */
  kDtInstanceIdRvTimer = 13, /**< instance rv_timer of rv_timer */
  kDtInstanceIdSpiDevice = 14, /**< instance spi_device of spi_device */
  kDtInstanceIdSpiHost0 = 15, /**< instance spi_host0 of spi_host */
  kDtInstanceIdSramCtrlMain = 16, /**< instance sram_ctrl_main of sram_ctrl */
  kDtInstanceIdUart0 = 17, /**< instance uart0 of uart */
  kDtInstanceIdUart1 = 18, /**< instance uart1 of uart */
  kDtInstanceIdUsbdev = 19, /**< instance usbdev of usbdev */
  kDtInstanceIdCount = 20, /**< \internal Number of instance IDs */
} dt_instance_id_t;
 
/**
 * Get the instance type of a device instance.
 *
 * For example the instance type of `kDtUart0` is `kDtInstanceTypeUart`.
 *
 * @param id An instance ID.
 * @return The instance type, or `kDtInstanceIdUnknown` if the ID is not valid.
 */
dt_device_type_t dt_device_type(dt_instance_id_t id);
 
/** PLIC IRQ ID type.
 *
 * This type represents a raw IRQ ID from the PLIC.
 *
 * This is an alias to the top's `plic_irq_id_t` type for backward compatibility
 * with existing code.
 */
typedef top_englishbreakfast_plic_irq_id_t dt_plic_irq_id_t;
 
/** PLIC IRQ ID for no interrupt. */
static const dt_plic_irq_id_t kDtPlicIrqIdNone=kTopEnglishbreakfastPlicIrqIdNone;
 
/**
 * Get the instance ID for a given PLIC IRQ ID.
 *
 * For example, on earlgrey, the instance ID of `kTopEarlgreyPlicIrqIdUart0TxWatermark`
 * is `kDtInstanceIdUart0`. One can then use the type specific function to retrieve the
 * IRQ name, for example `dt_uart_irq_from_plic_id` for the UART.
 *
 * @param irq A PLIC ID.
 * @return The instance ID, or `kDtInstanceIdUnknown` if the PLIC ID is not valid.
 */
dt_instance_id_t dt_plic_id_to_instance_id(dt_plic_irq_id_t irq);
 
/**
 * List of clocks.
 *
 * Clocks are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_clock {
  kDtClockMain = 0, /**< clock main */
  kDtClockIo = 1, /**< clock io */
  kDtClockUsb = 2, /**< clock usb */
  kDtClockAon = 3, /**< clock aon */
  kDtClockIoDiv2 = 4, /**< clock io_div2 */
  kDtClockIoDiv4 = 5, /**< clock io_div4 */
  kDtClockCount = 6, /**< \internal Number of clocks */
} dt_clock_t;
 
/**
 * Get the frequency of a clock.
 *
 * @param clk A clock ID.
 * @return Clock frequency in Hz.
 */
uint32_t dt_clock_frequency(dt_clock_t clk);
 
/**
 * List of resets.
 *
 * Resets are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_reset {
  kDtResetUnknown = 0, /**< Unknown reset */
  kDtResetPorAon = 1, /**< Reset node por_aon */
  kDtResetLcSrc = 2, /**< Reset node lc_src */
  kDtResetSysSrc = 3, /**< Reset node sys_src */
  kDtResetPor = 4, /**< Reset node por */
  kDtResetPorIo = 5, /**< Reset node por_io */
  kDtResetPorIoDiv2 = 6, /**< Reset node por_io_div2 */
  kDtResetPorIoDiv4 = 7, /**< Reset node por_io_div4 */
  kDtResetPorUsb = 8, /**< Reset node por_usb */
  kDtResetLc = 9, /**< Reset node lc */
  kDtResetLcIoDiv4 = 10, /**< Reset node lc_io_div4 */
  kDtResetSys = 11, /**< Reset node sys */
  kDtResetSysIoDiv4 = 12, /**< Reset node sys_io_div4 */
  kDtResetSysAon = 13, /**< Reset node sys_aon */
  kDtResetSpiDevice = 14, /**< Reset node spi_device */
  kDtResetSpiHost0 = 15, /**< Reset node spi_host0 */
  kDtResetUsb = 16, /**< Reset node usb */
  kDtResetCount = 17, /**< \internal Number of resets */
} dt_reset_t;
 
/**
 * List of pads names.
 */
typedef enum dt_pad {
  kDtPadIoa0 = 0, /**< Muxed IO pad */
  kDtPadIoa1 = 1, /**< Muxed IO pad */
  kDtPadIoa2 = 2, /**< Muxed IO pad */
  kDtPadIoa3 = 3, /**< Muxed IO pad */
  kDtPadIoa4 = 4, /**< Muxed IO pad */
  kDtPadIoa5 = 5, /**< Muxed IO pad */
  kDtPadIoa6 = 6, /**< Muxed IO pad */
  kDtPadIoa7 = 7, /**< Muxed IO pad */
  kDtPadIoa8 = 8, /**< Muxed IO pad */
  kDtPadIob0 = 9, /**< Muxed IO pad */
  kDtPadIob1 = 10, /**< Muxed IO pad */
  kDtPadIob2 = 11, /**< Muxed IO pad */
  kDtPadIob3 = 12, /**< Muxed IO pad */
  kDtPadIob4 = 13, /**< Muxed IO pad */
  kDtPadIob5 = 14, /**< Muxed IO pad */
  kDtPadIob6 = 15, /**< Muxed IO pad */
  kDtPadIob7 = 16, /**< Muxed IO pad */
  kDtPadIob8 = 17, /**< Muxed IO pad */
  kDtPadIob9 = 18, /**< Muxed IO pad */
  kDtPadIob10 = 19, /**< Muxed IO pad */
  kDtPadIob11 = 20, /**< Muxed IO pad */
  kDtPadIob12 = 21, /**< Muxed IO pad */
  kDtPadIoc0 = 22, /**< Muxed IO pad */
  kDtPadIoc1 = 23, /**< Muxed IO pad */
  kDtPadIoc2 = 24, /**< Muxed IO pad */
  kDtPadIoc3 = 25, /**< Muxed IO pad */
  kDtPadIoc4 = 26, /**< Muxed IO pad */
  kDtPadIoc5 = 27, /**< Muxed IO pad */
  kDtPadIoc6 = 28, /**< Muxed IO pad */
  kDtPadIoc7 = 29, /**< Muxed IO pad */
  kDtPadIoc8 = 30, /**< Muxed IO pad */
  kDtPadIoc9 = 31, /**< Muxed IO pad */
  kDtPadIoc10 = 32, /**< Muxed IO pad */
  kDtPadIoc11 = 33, /**< Muxed IO pad */
  kDtPadIoc12 = 34, /**< Muxed IO pad */
  kDtPadIor0 = 35, /**< Muxed IO pad */
  kDtPadIor1 = 36, /**< Muxed IO pad */
  kDtPadIor2 = 37, /**< Muxed IO pad */
  kDtPadIor3 = 38, /**< Muxed IO pad */
  kDtPadIor4 = 39, /**< Muxed IO pad */
  kDtPadIor5 = 40, /**< Muxed IO pad */
  kDtPadIor6 = 41, /**< Muxed IO pad */
  kDtPadIor7 = 42, /**< Muxed IO pad */
  kDtPadIor10 = 43, /**< Muxed IO pad */
  kDtPadIor11 = 44, /**< Muxed IO pad */
  kDtPadIor12 = 45, /**< Muxed IO pad */
  kDtPadIor13 = 46, /**< Muxed IO pad */
  kDtPadSpiHost0Sd0 = 47, /**< SPI host data */
  kDtPadSpiHost0Sd1 = 48, /**< SPI host data */
  kDtPadSpiHost0Sd2 = 49, /**< SPI host data */
  kDtPadSpiHost0Sd3 = 50, /**< SPI host data */
  kDtPadSpiDeviceSd0 = 51, /**< SPI device data */
  kDtPadSpiDeviceSd1 = 52, /**< SPI device data */
  kDtPadSpiDeviceSd2 = 53, /**< SPI device data */
  kDtPadSpiDeviceSd3 = 54, /**< SPI device data */
  kDtPadUsbdevUsbDp = 55, /**<  */
  kDtPadUsbdevUsbDn = 56, /**<  */
  kDtPadSpiDeviceSck = 57, /**< SPI device clock */
  kDtPadSpiDeviceCsb = 58, /**< SPI device chip select */
  kDtPadSpiHost0Sck = 59, /**< SPI host clock */
  kDtPadSpiHost0Csb = 60, /**< SPI host chip select */
  kDtPadCount = 61, /**< \internal Number of pads */
} dt_pad_t;
 
/**
 * Pinmux types.
 *
 * These types are aliases to top-level types for backward compatibility
 * with existing code.
 */
typedef top_englishbreakfast_pinmux_peripheral_in_t dt_pinmux_peripheral_in_t;
typedef top_englishbreakfast_pinmux_insel_t dt_pinmux_insel_t;
typedef top_englishbreakfast_pinmux_outsel_t dt_pinmux_outsel_t;
typedef top_englishbreakfast_pinmux_mio_out_t dt_pinmux_mio_out_t;
typedef top_englishbreakfast_direct_pads_t dt_pinmux_direct_pad_t;
typedef top_englishbreakfast_muxed_pads_t  dt_pinmux_muxed_pad_t;
 
/** Type of peripheral I/O. */
typedef enum dt_periph_io_type {
  /** This peripheral I/O is connected to a muxed IO (MIO). */
  kDtPeriphIoTypeMio,
  /** This peripheral I/O is connected to a direct IO (DIO). */
  kDtPeriphIoTypeDio,
  /** This peripheral I/O is not connected to either a MIO or a DIO. */
  kDtPeriphIoTypeUnspecified,
} dt_periph_io_type_t;
 
 
/** Direction of a peripheral I/O. */
typedef enum dt_periph_io_dir {
  /** This peripheral I/O is an input. */
  kDtPeriphIoDirIn,
  /** This peripheral I/O is an output */
  kDtPeriphIoDirOut,
  /** This peripheral I/O is an input-output */
  kDtPeriphIoDirInout,
} dt_periph_io_dir_t;
 
/** Peripheral I/O description.
 *
 * A `dt_periph_io_t` represents a HW IP block peripheral I/O, which can be an input, output or both.
 * Importantly, this only represents how the block peripheral I/O is wired, i.e.
 * whether it is connected a MIO or a direct IO on the pinmux, and the relevant information necessary to
 * configure it.
 *
 * **Note:** The fields of this structure are internal, use the dt_periph_io_* functions to access them.
 */
typedef struct dt_periph_io {
  struct {
    dt_periph_io_type_t type; /**< Peripheral I/O type */
    dt_periph_io_dir_t dir; /**< Peripheral I/O direction */
    /**
     * For `kDtPeriphIoTypeMio`: peripheral input number. This is the index of the MIO_PERIPH_INSEL register
     * that controls this peripheral I/O.
     * 
     * For `kDtPeriphIoTypeDio`: DIO pad number. This is the index of the various DIO_PAD_* registers
     * that control this peripheral I/O.
     */
    uint16_t periph_input_or_direct_pad;
    /**
     * For `kDtPeriphIoTypeMio`: peripheral output number. This is the value to put in the MIO_OUTSEL registers
     * to connect an output to this peripheral I/O. For `kDtPeriphIoTypeDio`: the pad index (`dt_pad_t`) to which this I/O is connected.
     */
    uint16_t outsel_or_dt_pad;
  } __internal; /**< Private fields */
} dt_periph_io_t;
 
 
/** Tie constantly to zero. */
static const dt_pinmux_outsel_t kDtPinmuxOutselConstantZero = kTopEnglishbreakfastPinmuxOutselConstantZero;
 
/** Tie constantly to one. */
static const dt_pinmux_outsel_t kDtPinmuxOutselConstantOne = kTopEnglishbreakfastPinmuxOutselConstantOne;
 
/** Tie constantly to high-Z. */
static const dt_pinmux_outsel_t kDtPinmuxOutselConstantHighZ = kTopEnglishbreakfastPinmuxOutselConstantHighZ;
 
/* Peripheral I/O that is constantly tied to high-Z (output only) */
extern const dt_periph_io_t kDtPeriphIoConstantHighZ;
 
/* Peripheral I/O that is constantly tied to one (output only) */
extern const dt_periph_io_t kDtPeriphIoConstantZero;
 
/* Peripheral I/O that is constantly tied to zero (output only) */
extern const dt_periph_io_t kDtPeriphIoConstantOne;
 
/**
 * Return the type of a `dt_periph_io_t`.
 *
 * @param periph_io A peripheral I/O description.
 * @return The peripheral I/O type (MIO, DIO, etc).
 */
static inline dt_periph_io_type_t dt_periph_io_type(dt_periph_io_t periph_io) {
  return periph_io.__internal.type;
}
 
/**
 * Return the direction of a `dt_periph_io_t`.
 *
 * @param periph_io A peripheral I/O description.
 * @return The peripheral I/O direction.
 */
static inline dt_periph_io_dir_t dt_periph_io_dir(dt_periph_io_t periph_io) {
  return periph_io.__internal.dir;
}
 
/**
 * Return the peripheral input for an MIO peripheral I/O.
 *
 * This is the index of the `MIO_PERIPH_INSEL` pinmux register that controls this peripheral I/O.
 *
 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeMio`.
 * @return The peripheral input number of the MIO that this peripheral I/O is connected to.
 *
 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeMio` which are
 * inputs (`kDtPeriphIoDirIn`). For any other peripheral I/O, the return value is unspecified.
 */
static inline dt_pinmux_peripheral_in_t dt_periph_io_mio_periph_input(dt_periph_io_t periph_io) {
  return (dt_pinmux_peripheral_in_t)periph_io.__internal.periph_input_or_direct_pad;
}
 
/**
 * Return the outsel for an MIO peripheral I/O.
 *
 * This is the value to put in the `MIO_OUTSEL` pinmux registers to connect a pad to this peripheral I/O.
 *
 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeMio`.
 * @return The outsel of the MIO that this peripheral I/O is connected to.
 *
 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeMio` which are
 * outputs (`kDtPeriphIoDirOut`). For any other peripheral I/O, the return value is unspecified.
 */
static inline dt_pinmux_outsel_t dt_periph_io_mio_outsel(dt_periph_io_t periph_io) {
  return (dt_pinmux_outsel_t)periph_io.__internal.outsel_or_dt_pad;
}
 
/**
 * Return the direct pad number of a DIO peripheral I/O.
 *
 * This is the index of the various `DIO_PAD_*` pinmux registers that control this peripheral I/O.
 *
 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeDio`.
 * @return The direct pad number of the DIO that this peripheral I/O is connected to.
 *
 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeDio` which are
 * either outputs or inouts. For any other peripheral I/O type, the return value is unspecified.
 */
static inline dt_pinmux_direct_pad_t dt_periph_io_dio_pad_index(dt_periph_io_t periph_io) {
  return (dt_pinmux_direct_pad_t)periph_io.__internal.periph_input_or_direct_pad;
}
 
/**
 * Return the pad of a DIO peripheral I/O.
 *
 * @param periph_io A peripheral I/O of type `kDtPeriphIoTypeDio`.
 * @return The pad to which this peripheral I/O is connected to.
 *
 * **Note:** This function only makes sense for peripheral I/Os of type `kDtPeriphIoTypeDio` which are
 * either outputs or inouts. For any other peripheral I/O type, the return value is unspecified.
 */
static inline dt_pad_t dt_periph_io_dio_pad(dt_periph_io_t periph_io) {
  return (dt_pad_t)periph_io.__internal.outsel_or_dt_pad;
}
 
/** Type of a pad. */
typedef enum dt_pad_type {
  /** This pad is a muxed IO (MIO). */
  kDtPadTypeMio,
  /** This pad is a direct IO (DIO). */
  kDtPadTypeDio,
  /** This pad is not an MIO or a DIO. */
  kDtPadTypeUnspecified,
} dt_pad_type_t;
 
/**
 * Return the type of a `dt_pad_t`.
 *
 * @param pad A pad description.
 * @return The pad type (MIO, DIO, etc).
 */
dt_pad_type_t dt_pad_type(dt_pad_t pad);
 
/**
 * Return the pad out number for an MIO pad.
 *
 * This is the index of the `MIO_OUT` registers that control this pad
 * (or the output part of this pad).
 *
 * @param pad A pad of type `kDtPadTypeMio`.
 * @return The pad out number of the MIO.
 *
 * **Note:** This function only makes sense for pads of type `kDtPadTypeMio` which are
 * either inputs or inouts. For any other pad, the return value is unspecified.
 */
dt_pinmux_mio_out_t dt_pad_mio_out(dt_pad_t pad);
 
/**
 * Return the pad out number for an MIO pad.
 *
 * This is the index of the `MIO_PAD` registers that control this pad
 * (or the output part of this pad).
 *
 * @param pad A pad of type `kDtPadTypeMio`.
 * @return The pad out number of the MIO.
 *
 * **Note:** This function only makes sense for pads of type `kDtPadTypeMio`.
 * For any other pad, the return value is unspecified.
 */
dt_pinmux_muxed_pad_t dt_pad_mio_pad_index(dt_pad_t pad);
 
/**
 * Return the insel for an MIO pad.
 *
 * This is the value to put in the `MIO_PERIPH_INSEL` registers to connect a peripheral I/O to this pad.
 *
 * @param pad A pad of type `kDtPadTypeMio`.
 * @return The insel of the MIO that this pad is connected to.
 *
 * **Note:** This function only makes sense for pads of type `kDtPadTypeMio`.
 * For any other pad, the return value is unspecified.
 */
dt_pinmux_insel_t dt_pad_mio_insel(dt_pad_t pad);
 
/**
 * Return the direct pad number of a DIO pad.
 *
 * This is the index of the various `DIO_PAD_*` registers that control this pad.
 *
 * @param pad A pad of type `kDtPadTypeDio`.
 * @return The direct pad number of the DID that this pad is connected to.
 *
 * **Note:** This function only makes sense for pads of type `kDtPeriphIoTypeDio` which are
 * either outputs or inouts. For any other pad type, the return value is unspecified.
 */
dt_pinmux_direct_pad_t dt_pad_dio_pad_index(dt_pad_t pad);
 
#endif  // OPENTITAN_TOP_ENGLISHBREAKFAST_DT_API_H_