dt_spi_device.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_DT_SPI_DEVICE_H_
#define OPENTITAN_DT_SPI_DEVICE_H_
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
 
/**
 * @file
 * @brief Device Tables (DT) for IP spi_device and top darjeeling.
 *
 * This file contains the type definitions and global functions of the spi_device.
 */
 
#include "hw/top/dt/dt_api.h"
#include <stdint.h>
 
 
 
/**
 * List of instances.
 */
typedef enum dt_spi_device {
  kDtSpiDevice = 0, /**< spi_device */
  kDtSpiDeviceFirst = 0, /**< \internal First instance */
  kDtSpiDeviceCount = 1, /**< \internal Number of instances */
} dt_spi_device_t;
 
/**
 * List of register blocks.
 *
 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
 */
typedef enum dt_spi_device_reg_block {
  kDtSpiDeviceRegBlockCore = 0, /**<  */
  kDtSpiDeviceRegBlockCount = 1, /**< \internal Number of register blocks */
} dt_spi_device_reg_block_t;
 
/** Primary register block (associated with the "primary" set of registers that control the IP). */
static const dt_spi_device_reg_block_t kDtSpiDeviceRegBlockPrimary = kDtSpiDeviceRegBlockCore;
 
/**
 * List of memories.
 *
 * Memories are guaranteed to start at 0 and to be consecutively numbered.
 */
typedef enum dt_spi_device_memory {
  kDtSpiDeviceMemoryCount = 0, /**< \internal Number of memories */
} dt_spi_device_memory_t;
 
/**
 * List of IRQs.
 *
 * IRQs are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_spi_device_irq {
  kDtSpiDeviceIrqUploadCmdfifoNotEmpty = 0, /**< Upload Command FIFO is not empty */
  kDtSpiDeviceIrqUploadPayloadNotEmpty = 1, /**< Upload payload is not empty.
 
The event occurs after SPI transaction completed */
  kDtSpiDeviceIrqUploadPayloadOverflow = 2, /**< Upload payload overflow event.
 
When a SPI Host system issues a command with payload more than 256B,
this event is reported. When it happens, SW should read the last
written payload index CSR to figure out the starting address of the
last 256B. */
  kDtSpiDeviceIrqReadbufWatermark = 3, /**< Read Buffer Threshold event.
 
The host system accesses greater than or equal to the threshold of a
buffer. */
  kDtSpiDeviceIrqReadbufFlip = 4, /**< Read buffer flipped event.
 
The host system accesses other side of buffer. */
  kDtSpiDeviceIrqTpmHeaderNotEmpty = 5, /**< TPM Header(Command/Address) buffer available */
  kDtSpiDeviceIrqTpmRdfifoCmdEnd = 6, /**< TPM RdFIFO command ended.
 
The TPM Read command targeting the RdFIFO ended.
Check TPM_STATUS.rdfifo_aborted to see if the transaction completed. */
  kDtSpiDeviceIrqTpmRdfifoDrop = 7, /**< TPM RdFIFO data dropped.
 
Data was dropped from the RdFIFO.
Data was written while a read command was not active, and it was not accepted.
This can occur when the host aborts a read command. */
  kDtSpiDeviceIrqCount = 8, /**< \internal Number of IRQs */
} dt_spi_device_irq_t;
 
/**
 * List of Alerts.
 *
 * Alerts are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_spi_device_alert {
  kDtSpiDeviceAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
  kDtSpiDeviceAlertCount = 1, /**< \internal Number of Alerts */
} dt_spi_device_alert_t;
 
/**
 * List of clock ports.
 *
 * Clock ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_spi_device_clock {
  kDtSpiDeviceClockClk = 0, /**< Clock port clk_i */
  kDtSpiDeviceClockCount = 1, /**< \internal Number of clock ports */
} dt_spi_device_clock_t;
 
/**
 * List of reset ports.
 *
 * Reset ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_spi_device_reset {
  kDtSpiDeviceResetRst = 0, /**< Reset port rst_ni */
  kDtSpiDeviceResetCount = 1, /**< \internal Number of reset ports */
} dt_spi_device_reset_t;
 
/**
 * List of peripheral I/O.
 *
 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_spi_device_periph_io {
  kDtSpiDevicePeriphIoSck = 0, /**<  */
  kDtSpiDevicePeriphIoCsb = 1, /**<  */
  kDtSpiDevicePeriphIoTpmCsb = 2, /**<  */
  kDtSpiDevicePeriphIoSd0 = 3, /**<  */
  kDtSpiDevicePeriphIoSd1 = 4, /**<  */
  kDtSpiDevicePeriphIoSd2 = 5, /**<  */
  kDtSpiDevicePeriphIoSd3 = 6, /**<  */
  kDtSpiDevicePeriphIoCount = 7, /**< \internal Number of peripheral I/O */
} dt_spi_device_periph_io_t;
 
/**
 * List of supported hardware features.
 */
#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_LANES 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_SERDES_ORDERING 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_CSB_STATUS 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_COMMANDS 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_FLASH_EMULATION_BLOCKS 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_READ_COMMAND_PROCESSOR 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_DUMMY_CYCLE 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_WRITE_ENABLE_DISABLE 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_LAST_READ_ADDR 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_CMDINFOS 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_COMMAND_UPLOAD 1
#define OPENTITAN_SPI_DEVICE_HAS_HW_3B4B_ADDRESSING 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_CMD_FILTER 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_ADDRESS_MANIPULATION 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_STATUS_MANIPULATION 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_OUTPUT_ENABLE_CONTROL 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_INTERCEPT_EN 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_MAILBOX 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_RETURN_BY_HW_REGS 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_AUTO_WAIT 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_READ_FIFO_MODE 1
#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_CAPABILITY 1
 
 
 
/**
 * Get the spi_device instance from an instance ID
 *
 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
 *
 * @param inst_id Instance ID.
 * @return A spi_device instance.
 *
 * **Note:** This function only makes sense if the instance ID has device type spi_device,
 * otherwise the returned value is unspecified.
 */
dt_spi_device_t dt_spi_device_from_instance_id(dt_instance_id_t inst_id);
 
/**
 * Get the instance ID of an instance.
 *
 * @param dt Instance of spi_device.
 * @return The instance ID of that instance.
 */
dt_instance_id_t dt_spi_device_instance_id(dt_spi_device_t dt);
 
/**
 * Get the register base address of an instance.
 *
 * @param dt Instance of spi_device.
 * @param reg_block The register block requested.
 * @return The register base address of the requested block.
 */
uint32_t dt_spi_device_reg_block(
    dt_spi_device_t dt,
    dt_spi_device_reg_block_t reg_block);
 
/**
 * Get the primary register base address of an instance.
 *
 * This is just a convenience function, equivalent to
 * `dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore)`
 *
 * @param dt Instance of spi_device.
 * @return The register base address of the primary register block.
 */
static inline uint32_t dt_spi_device_primary_reg_block(
    dt_spi_device_t dt) {
  return dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore);
}
 
/**
 * Get the base address of a memory.
 *
 * @param dt Instance of spi_device.
 * @param mem The memory requested.
 * @return The base address of the requested memory.
 */
uint32_t dt_spi_device_memory_base(
    dt_spi_device_t dt,
    dt_spi_device_memory_t mem);
 
/**
 * Get the size of a memory.
 *
 * @param dt Instance of spi_device.
 * @param mem The memory requested.
 * @return The size of the requested memory.
 */
uint32_t dt_spi_device_memory_size(
    dt_spi_device_t dt,
    dt_spi_device_memory_t mem);
 
/**
 * Get the PLIC ID of a spi_device IRQ for a given instance.
 *
 * If the instance is not connected to the PLIC, this function
 * will return `kDtPlicIrqIdNone`.
 *
 * @param dt Instance of spi_device.
 * @param irq A spi_device IRQ.
 * @return The PLIC ID of the IRQ of this instance.
 */
dt_plic_irq_id_t dt_spi_device_irq_to_plic_id(
    dt_spi_device_t dt,
    dt_spi_device_irq_t irq);
 
/**
 * Convert a global IRQ ID to a local spi_device IRQ type.
 *
 * @param dt Instance of spi_device.
 * @param irq A PLIC ID that belongs to this instance.
 * @return The spi_device IRQ, or `kDtSpiDeviceIrqCount`.
 *
 * **Note:** This function assumes that the PLIC ID belongs to the instance
 * of spi_device passed in parameter. In other words, it must be the case that
 * `dt_spi_device_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
 * will return `kDtSpiDeviceIrqCount`.
 */
dt_spi_device_irq_t dt_spi_device_irq_from_plic_id(
    dt_spi_device_t dt,
    dt_plic_irq_id_t irq);
 
 
/**
 * Get the alert ID of a spi_device alert for a given instance.
 *
 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
 * instances where the instance is not connected, the return value is unspecified.
 *
 * @param dt Instance of spi_device.
 * @param alert A spi_device alert.
 * @return The Alert Handler alert ID of the alert of this instance.
 */
dt_alert_id_t dt_spi_device_alert_to_alert_id(
    dt_spi_device_t dt,
    dt_spi_device_alert_t alert);
 
/**
 * Convert a global alert ID to a local spi_device alert type.
 *
 * @param dt Instance of spi_device.
 * @param alert A global alert ID that belongs to this instance.
 * @return The spi_device alert, or `kDtSpiDeviceAlertCount`.
 *
 * **Note:** This function assumes that the global alert ID belongs to the
 * instance of spi_device passed in parameter. In other words, it must be the case
 * that `dt_spi_device_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
 * this function will return `kDtSpiDeviceAlertCount`.
 */
dt_spi_device_alert_t dt_spi_device_alert_from_alert_id(
    dt_spi_device_t dt,
    dt_alert_id_t alert);
 
 
/**
 * Get the peripheral I/O description of an instance.
 *
 * @param dt Instance of spi_device.
 * @param sig Requested peripheral I/O.
 * @return Description of the requested peripheral I/O for this instance.
 */
dt_periph_io_t dt_spi_device_periph_io(
    dt_spi_device_t dt,
    dt_spi_device_periph_io_t sig);
 
/**
 * Get the clock signal connected to a clock port of an instance.
 *
 * @param dt Instance of spi_device.
 * @param clk Clock port.
 * @return Clock signal.
 */
dt_clock_t dt_spi_device_clock(
    dt_spi_device_t dt,
    dt_spi_device_clock_t clk);
 
/**
 * Get the reset signal connected to a reset port of an instance.
 *
 * @param dt Instance of spi_device.
 * @param rst Reset port.
 * @return Reset signal.
 */
dt_reset_t dt_spi_device_reset(
    dt_spi_device_t dt,
    dt_spi_device_reset_t rst);
 
 
 
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
 
#endif  // OPENTITAN_DT_SPI_DEVICE_H_