dt_usbdev.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_USBDEV_H_
#define OPENTITAN_DT_USBDEV_H_
 
/**
 * @file
 * @brief Device Tables (DT) for IP usbdev and top earlgrey.
 *
 * This file contains the type definitions and global functions of the usbdev.
 */
 
#include "dt_api.h"
#include <stdint.h>
 
/**
 * List of instances.
 */
typedef enum dt_usbdev {
  kDtUsbdev = 0, /**< usbdev */
  kDtUsbdevFirst = 0, /**< \internal First instance */
  kDtUsbdevCount = 1, /**< \internal Number of instances */
} dt_usbdev_t;
 
/**
 * List of register blocks.
 *
 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
 */
typedef enum dt_usbdev_reg_block {
  kDtUsbdevRegBlockCore = 0, /**<  */
  kDtUsbdevRegBlockCount = 1, /**< \internal Number of register blocks */
} dt_usbdev_reg_block_t;
 
/** Primary register block (associated with the "primary" set of registers that control the IP). */
static const dt_usbdev_reg_block_t kDtUsbdevRegBlockPrimary = kDtUsbdevRegBlockCore;
 
/**
 * List of IRQs.
 *
 * IRQs are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_usbdev_irq {
  kDtUsbdevIrqPktReceived = 0, /**< Raised if a packet was received using an OUT or SETUP transaction.
This interrupt is directly tied to whether the RX FIFO is empty, so it should be cleared only after handling the FIFO entry. */
  kDtUsbdevIrqPktSent = 1, /**< Raised if a packet was sent as part of an IN transaction.
This interrupt is directly tied to whether a sent packet has not been acknowledged in the !!in_sent register.
It should be cleared only after clearing all bits in the !!in_sent register. */
  kDtUsbdevIrqDisconnected = 2, /**< Raised if VBUS is lost, thus the link is disconnected. */
  kDtUsbdevIrqHostLost = 3, /**< Raised if link is active but SOF was not received from host for 4.096 ms. The SOF should be every 1 ms. */
  kDtUsbdevIrqLinkReset = 4, /**< Raised if the link is at SE0 longer than 3 us indicating a link reset (host asserts for min 10 ms, device can react after 2.5 us). */
  kDtUsbdevIrqLinkSuspend = 5, /**< Raised if the line has signaled J for longer than 3ms and is therefore in suspend state. */
  kDtUsbdevIrqLinkResume = 6, /**< Raised when the link becomes active again after being suspended. */
  kDtUsbdevIrqAvOutEmpty = 7, /**< Raised when the Available OUT Buffer FIFO is empty and the device interface is enabled.
This interrupt is directly tied to the FIFO status, so the Available OUT Buffer FIFO must be provided with a free buffer before the interrupt can be cleared. */
  kDtUsbdevIrqRxFull = 8, /**< Raised when the RX FIFO is full and the device interface is enabled.
This interrupt is directly tied to the FIFO status, so the RX FIFO must have an entry removed before the interrupt is cleared.
If the condition is not cleared, the interrupt can re-assert. */
  kDtUsbdevIrqAvOverflow = 9, /**< Raised if a write was done to either the Available OUT Buffer FIFO or the Available SETUP Buffer FIFO when the FIFO was full. */
  kDtUsbdevIrqLinkInErr = 10, /**< Raised if a packet to an IN endpoint started to be received but was
then dropped due to an error. After transmitting the IN payload,
the USB device expects a valid ACK handshake packet. This error is
raised if either the packet or CRC is invalid, leading to a NAK instead,
or if a different token was received. */
  kDtUsbdevIrqRxCrcErr = 11, /**< Raised if a CRC error occurred on a received packet. */
  kDtUsbdevIrqRxPidErr = 12, /**< Raised if an invalid Packet IDentifier (PID) was received. */
  kDtUsbdevIrqRxBitstuffErr = 13, /**< Raised if an invalid bitstuffing was received. */
  kDtUsbdevIrqFrame = 14, /**< Raised when the USB frame number is updated with a valid SOF. */
  kDtUsbdevIrqPowered = 15, /**< Raised if VBUS is applied. */
  kDtUsbdevIrqLinkOutErr = 16, /**< Raised if a packet to an OUT endpoint started to be received but was then dropped due to an error.
This error is raised if the data toggle, token, packet and/or CRC are invalid, or if the appropriate Available OUT Buffer FIFO is empty and/or the Received Buffer FIFO is full when a packet should have been received. */
  kDtUsbdevIrqAvSetupEmpty = 17, /**< Raised when the Available SETUP Buffer FIFO is empty and the device interface is enabled.
This interrupt is directly tied to the FIFO status, so the Available SETUP Buffer FIFO must be provided with a free buffer before the interrupt can be cleared. */
  kDtUsbdevIrqCount = 18, /**< \internal Number of IRQs */
} dt_usbdev_irq_t;
 
/**
 * List of Alerts.
 *
 * Alerts are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_usbdev_alert {
  kDtUsbdevAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
  kDtUsbdevAlertCount = 1, /**< \internal Number of Alerts */
} dt_usbdev_alert_t;
 
/**
 * List of clock ports.
 *
 * Clock ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_usbdev_clock {
  kDtUsbdevClockClk = 0, /**< Clock port clk_i */
  kDtUsbdevClockAon = 1, /**< Clock port clk_aon_i */
  kDtUsbdevClockCount = 2, /**< \internal Number of clock ports */
} dt_usbdev_clock_t;
 
/**
 * List of reset ports.
 *
 * Reset ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_usbdev_reset {
  kDtUsbdevResetRst = 0, /**< Reset port rst_ni */
  kDtUsbdevResetAon = 1, /**< Reset port rst_aon_ni */
  kDtUsbdevResetCount = 2, /**< \internal Number of reset ports */
} dt_usbdev_reset_t;
 
/**
 * List of peripheral I/O.
 *
 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_usbdev_periph_io {
  kDtUsbdevPeriphIoSense = 0, /**<  */
  kDtUsbdevPeriphIoUsbDp = 1, /**<  */
  kDtUsbdevPeriphIoUsbDn = 2, /**<  */
  kDtUsbdevPeriphIoCount = 3, /**< \internal Number of peripheral I/O */
} dt_usbdev_periph_io_t;
 
/**
 * List of supported hardware features.
 */
#define OPENTITAN_USBDEV_HAS_CONN_VBUS 1
#define OPENTITAN_USBDEV_HAS_CONN_PULLUP 1
#define OPENTITAN_USBDEV_HAS_CONN_REF_PULSE 1
#define OPENTITAN_USBDEV_HAS_CONN_PIN_CONFIG 1
#define OPENTITAN_USBDEV_HAS_CONN_RESET 1
#define OPENTITAN_USBDEV_HAS_BUFFER_MEMORY 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_CONTROL_RX 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_CONTROL_TX 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_ENDPOINTS 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_BULK 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_ISOCHRONOUS 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_CONTROL 1
#define OPENTITAN_USBDEV_HAS_TRANSFER_INTERRUPT 1
#define OPENTITAN_USBDEV_HAS_POWER_SUSPEND 1
#define OPENTITAN_USBDEV_HAS_POWER_RESUME 1
#define OPENTITAN_USBDEV_HAS_POWER_AON 1
#define OPENTITAN_USBDEV_HAS_POWER_WAKE_DISCONNECT 1
#define OPENTITAN_USBDEV_HAS_POWER_WAKE_RESUME 1
#define OPENTITAN_USBDEV_HAS_POWER_WAKE_BUS_RESET 1
#define OPENTITAN_USBDEV_HAS_POWER_TOGGLE_RESTORE 1
 
 
 
/**
 * Get the usbdev instance from an instance ID
 *
 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
 *
 * @param inst_id Instance ID.
 * @return A usbdev instance.
 *
 * **Note:** This function only makes sense if the instance ID has device type usbdev,
 * otherwise the returned value is unspecified.
 */
dt_usbdev_t dt_usbdev_from_instance_id(dt_instance_id_t inst_id);
 
/**
 * Get the instance ID of an instance.
 *
 * @param dt Instance of usbdev.
 * @return The instance ID of that instance.
 */
dt_instance_id_t dt_usbdev_instance_id(dt_usbdev_t dt);
 
/**
 * Get the register base address of an instance.
 *
 * @param dt Instance of usbdev.
 * @param reg_block The register block requested.
 * @return The register base address of the requested block.
 */
uint32_t dt_usbdev_reg_block(
    dt_usbdev_t dt,
    dt_usbdev_reg_block_t reg_block);
 
/**
 * Get the primary register base address of an instance.
 *
 * This is just a convenience function, equivalent to
 * `dt_usbdev_reg_block(dt, kDtUsbdevRegBlockCore)`
 *
 * @param dt Instance of usbdev.
 * @return The register base address of the primary register block.
 */
static inline uint32_t dt_usbdev_primary_reg_block(
    dt_usbdev_t dt) {
  return dt_usbdev_reg_block(dt, kDtUsbdevRegBlockCore);
}
 
/**
 * Get the PLIC ID of a usbdev IRQ for a given instance.
 *
 * If the instance is not connected to the PLIC, this function
 * will return `kDtPlicIrqIdNone`.
 *
 * @param dt Instance of usbdev.
 * @param irq A usbdev IRQ.
 * @return The PLIC ID of the IRQ of this instance.
 */
dt_plic_irq_id_t dt_usbdev_irq_to_plic_id(
    dt_usbdev_t dt,
    dt_usbdev_irq_t irq);
 
/**
 * Convert a global IRQ ID to a local usbdev IRQ type.
 *
 * @param dt Instance of usbdev.
 * @param irq A PLIC ID that belongs to this instance.
 * @return The usbdev IRQ, or `kDtUsbdevIrqCount`.
 *
 * **Note:** This function assumes that the PLIC ID belongs to the instance
 * of usbdev passed in parameter. In other words, it must be the case that
 * `dt_usbdev_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
 * will return `kDtUsbdevIrqCount`.
 */
dt_usbdev_irq_t dt_usbdev_irq_from_plic_id(
    dt_usbdev_t dt,
    dt_plic_irq_id_t irq);
 
 
/**
 * Get the alert ID of a usbdev 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 usbdev.
 * @param alert A usbdev alert.
 * @return The Alert Handler alert ID of the alert of this instance.
 */
dt_alert_id_t dt_usbdev_alert_to_alert_id(
    dt_usbdev_t dt,
    dt_usbdev_alert_t alert);
 
/**
 * Convert a global alert ID to a local usbdev alert type.
 *
 * @param dt Instance of usbdev.
 * @param alert A global alert ID that belongs to this instance.
 * @return The usbdev alert, or `kDtUsbdevAlertCount`.
 *
 * **Note:** This function assumes that the global alert ID belongs to the
 * instance of usbdev passed in parameter. In other words, it must be the case
 * that `dt_usbdev_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
 * this function will return `kDtUsbdevAlertCount`.
 */
dt_usbdev_alert_t dt_usbdev_alert_from_alert_id(
    dt_usbdev_t dt,
    dt_alert_id_t alert);
 
 
/**
 * Get the peripheral I/O description of an instance.
 *
 * @param dt Instance of usbdev.
 * @param sig Requested peripheral I/O.
 * @return Description of the requested peripheral I/O for this instance.
 */
dt_periph_io_t dt_usbdev_periph_io(
    dt_usbdev_t dt,
    dt_usbdev_periph_io_t sig);
 
/**
 * Get the clock signal connected to a clock port of an instance.
 *
 * @param dt Instance of usbdev.
 * @param clk Clock port.
 * @return Clock signal.
 */
dt_clock_t dt_usbdev_clock(
    dt_usbdev_t dt,
    dt_usbdev_clock_t clk);
 
/**
 * Get the reset signal connected to a reset port of an instance.
 *
 * @param dt Instance of usbdev.
 * @param rst Reset port.
 * @return Reset signal.
 */
dt_reset_t dt_usbdev_reset(
    dt_usbdev_t dt,
    dt_usbdev_reset_t rst);
 
 
 
#endif  // OPENTITAN_DT_USBDEV_H_