otp_ctrl.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_OTP_CTRL_H_
#define OPENTITAN_DT_OTP_CTRL_H_
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
 
/**
 * @file
 * @brief Device Tables (DT) for IP otp_ctrl and top egret.
 *
 * This file contains the type definitions and global functions of the otp_ctrl.
 */
 
#include "hw/top/dt/api.h"
#include <stdint.h>
 
 
 
 
 
/**
 * List of instances.
 */
typedef enum dt_otp_ctrl {
  kDtOtpCtrlFirst = 0, /**< First instance */
  kDtOtpCtrl = 0, /**< otp_ctrl */
} dt_otp_ctrl_t;
 
enum {
  kDtOtpCtrlCount = 1, /**< Number of instances */
};
 
 
/**
 * List of register blocks.
 *
 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
 */
typedef enum dt_otp_ctrl_reg_block {
  kDtOtpCtrlRegBlockCore = 0, /**<  */
} dt_otp_ctrl_reg_block_t;
 
enum {
  kDtOtpCtrlRegBlockCount = 1, /**< Number of register blocks */
};
 
 
/** Primary register block (associated with the "primary" set of registers that control the IP). */
static const dt_otp_ctrl_reg_block_t kDtOtpCtrlRegBlockPrimary = kDtOtpCtrlRegBlockCore;
 
/**
 * List of IRQs.
 *
 * IRQs are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_otp_ctrl_irq {
  kDtOtpCtrlIrqOtpOperationDone = 0, /**< A direct access command or digest calculation operation has completed. */
  kDtOtpCtrlIrqOtpError = 1, /**< An error has occurred in the OTP controller. Check the !!ERR_CODE register to get more information. */
} dt_otp_ctrl_irq_t;
 
enum {
  kDtOtpCtrlIrqCount = 2, /**< Number of IRQs */
};
 
 
/**
 * List of Alerts.
 *
 * Alerts are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_otp_ctrl_alert {
  kDtOtpCtrlAlertFatalMacroError = 0, /**< This alert triggers if hardware detects an uncorrectable error during an OTP transaction, for example an uncorrectable ECC error in the OTP array. */
  kDtOtpCtrlAlertFatalCheckError = 1, /**< This alert triggers if any of the background checks fails. This includes the digest checks and concurrent ECC checks in the buffer registers. */
  kDtOtpCtrlAlertFatalBusIntegError = 2, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
  kDtOtpCtrlAlertFatalPrimOtpAlert = 3, /**< Fatal alert triggered inside the OTP primitive, including fatal TL-UL bus integrity faults of the test interface. */
  kDtOtpCtrlAlertRecovPrimOtpAlert = 4, /**< Recoverable alert triggered inside the OTP primitive. */
} dt_otp_ctrl_alert_t;
 
enum {
  kDtOtpCtrlAlertCount = 5, /**< Number of Alerts */
};
 
 
/**
 * List of clock ports.
 *
 * Clock ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_otp_ctrl_clock {
  kDtOtpCtrlClockClk = 0, /**< Clock port clk_i */
  kDtOtpCtrlClockEdn = 1, /**< Clock port clk_edn_i */
} dt_otp_ctrl_clock_t;
 
enum {
  kDtOtpCtrlClockCount = 2, /**< Number of clock ports */
};
 
 
/**
 * List of reset ports.
 *
 * Reset ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_otp_ctrl_reset {
  kDtOtpCtrlResetRst = 0, /**< Reset port rst_ni */
  kDtOtpCtrlResetEdn = 1, /**< Reset port rst_edn_ni */
} dt_otp_ctrl_reset_t;
 
enum {
  kDtOtpCtrlResetCount = 2, /**< Number of reset ports */
};
 
 
/**
 * List of supported hardware features.
 */
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_VENDOR_TEST 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_CREATOR_SW_CFG 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_OWNER_SW_CFG 1
#define OPENTITAN_OTP_CTRL_HAS_INIT 1
#define OPENTITAN_OTP_CTRL_HAS_ENTROPY_READ 1
#define OPENTITAN_OTP_CTRL_HAS_KEY_DERIVATION 1
#define OPENTITAN_OTP_CTRL_HAS_PROGRAM 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_SECRET0 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_SECRET1 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_SECRET2 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITION_LIFE_CYCLE 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITIONS_FEATURE_READ_LOCK 1
#define OPENTITAN_OTP_CTRL_HAS_PARTITIONS_FEATURE_WRITE_LOCK 1
#define OPENTITAN_OTP_CTRL_HAS_ERROR_HANDLING_RECOVERABLE 1
#define OPENTITAN_OTP_CTRL_HAS_ERROR_HANDLING_FATAL 1
#define OPENTITAN_OTP_CTRL_HAS_BACKGROUND_CHECK_CHECK_TIMEOUT 1
#define OPENTITAN_OTP_CTRL_HAS_BACKGROUND_CHECK_INTEGRITY_CHECK_PERIOD 1
#define OPENTITAN_OTP_CTRL_HAS_BACKGROUND_CHECK_CONSISTENCY_CHECK_PERIOD 1
 
 
 
/**
 * Get the otp_ctrl instance from an instance ID
 *
 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
 *
 * @param inst_id Instance ID.
 * @return A otp_ctrl instance.
 *
 * **Note:** This function only makes sense if the instance ID has device type otp_ctrl,
 * otherwise the returned value is unspecified.
 */
dt_otp_ctrl_t dt_otp_ctrl_from_instance_id(dt_instance_id_t inst_id);
 
/**
 * Get the instance ID of an instance.
 *
 * @param dt Instance of otp_ctrl.
 * @return The instance ID of that instance.
 */
dt_instance_id_t dt_otp_ctrl_instance_id(dt_otp_ctrl_t dt);
 
/**
 * Get the register base address of an instance.
 *
 * @param dt Instance of otp_ctrl.
 * @param reg_block The register block requested.
 * @return The register base address of the requested block.
 */
uint32_t dt_otp_ctrl_reg_block(
    dt_otp_ctrl_t dt,
    dt_otp_ctrl_reg_block_t reg_block);
 
/**
 * Get the primary register base address of an instance.
 *
 * This is just a convenience function, equivalent to
 * `dt_otp_ctrl_reg_block(dt, kDtOtpCtrlRegBlockCore)`
 *
 * @param dt Instance of otp_ctrl.
 * @return The register base address of the primary register block.
 */
static inline uint32_t dt_otp_ctrl_primary_reg_block(
    dt_otp_ctrl_t dt) {
  return dt_otp_ctrl_reg_block(dt, kDtOtpCtrlRegBlockCore);
}
 
/**
 * Get the PLIC ID of a otp_ctrl IRQ for a given instance.
 *
 * If the instance is not connected to the PLIC, this function
 * will return `kDtPlicIrqIdNone`.
 *
 * @param dt Instance of otp_ctrl.
 * @param irq A otp_ctrl IRQ.
 * @return The PLIC ID of the IRQ of this instance.
 */
dt_plic_irq_id_t dt_otp_ctrl_irq_to_plic_id(
    dt_otp_ctrl_t dt,
    dt_otp_ctrl_irq_t irq);
 
/**
 * Convert a global IRQ ID to a local otp_ctrl IRQ type.
 *
 * @param dt Instance of otp_ctrl.
 * @param irq A PLIC ID that belongs to this instance.
 * @return The otp_ctrl IRQ, or `kDtOtpCtrlIrqCount`.
 *
 * **Note:** This function assumes that the PLIC ID belongs to the instance
 * of otp_ctrl passed in parameter. In other words, it must be the case that
 * `dt_otp_ctrl_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
 * will return `kDtOtpCtrlIrqCount`.
 */
dt_otp_ctrl_irq_t dt_otp_ctrl_irq_from_plic_id(
    dt_otp_ctrl_t dt,
    dt_plic_irq_id_t irq);
 
 
/**
 * Get the alert ID of a otp_ctrl 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 otp_ctrl.
 * @param alert A otp_ctrl alert.
 * @return The Alert Handler alert ID of the alert of this instance.
 */
dt_alert_id_t dt_otp_ctrl_alert_to_alert_id(
    dt_otp_ctrl_t dt,
    dt_otp_ctrl_alert_t alert);
 
/**
 * Convert a global alert ID to a local otp_ctrl alert type.
 *
 * @param dt Instance of otp_ctrl.
 * @param alert A global alert ID that belongs to this instance.
 * @return The otp_ctrl alert, or `kDtOtpCtrlAlertCount`.
 *
 * **Note:** This function assumes that the global alert ID belongs to the
 * instance of otp_ctrl passed in parameter. In other words, it must be the case
 * that `dt_otp_ctrl_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
 * this function will return `kDtOtpCtrlAlertCount`.
 */
dt_otp_ctrl_alert_t dt_otp_ctrl_alert_from_alert_id(
    dt_otp_ctrl_t dt,
    dt_alert_id_t alert);
 
 
 
/**
 * Get the clock signal connected to a clock port of an instance.
 *
 * @param dt Instance of otp_ctrl.
 * @param clk Clock port.
 * @return Clock signal.
 */
dt_clock_t dt_otp_ctrl_clock(
    dt_otp_ctrl_t dt,
    dt_otp_ctrl_clock_t clk);
 
/**
 * Get the reset signal connected to a reset port of an instance.
 *
 * @param dt Instance of otp_ctrl.
 * @param rst Reset port.
 * @return Reset signal.
 */
dt_reset_t dt_otp_ctrl_reset(
    dt_otp_ctrl_t dt,
    dt_otp_ctrl_reset_t rst);
 
 
 
/**
 * Description of an OTP partition.
 *
 */
typedef struct dt_otp_partition_info {
  uint32_t start_addr; /**< The absolute OTP address at which this partition starts */
  size_t size; /**< Size of the partition (bytes), excluding the digest / zeroization fields. */
  uint8_t sw_readable; /**< Set to true iff the partition is readable by software. */
  uint8_t sw_digest; /**< Set to true iff the partition has a software digest. */
  uint8_t hw_digest; /**< Set to true iff the partition has a hardware digest. */
  uint32_t digest_reg_offset; /**< The OTP digest CSR (where the digest is buffered) offset for this partition. */
  uint8_t read_lockable; /**< Whether the partition can be locked for reading by software. */
  uint32_t lock_reg_offset; /**< The OTP lock CSR offset for this partition. */
  uint32_t read_lock_bit; /**< The bit-offset of the read lock in the OTP lock CSR for this partition. */
  uint8_t zeroizable; /**< Whether this partition is zeroizable. */
  uint8_t is_lifecycle; /**< Whether this partition stores the chip life cycle state. */
  uint32_t align_mask; /**< The alignment mask for this partition */
} dt_otp_partition_info_t;
 
 
/**
 * SW readable OTP partition identifier.
 */
typedef enum otp_partition {
  kOtpPartitionVendorTest = 0, /**<  */
  kOtpPartitionCreatorSwCfg = 1, /**<  */
  kOtpPartitionOwnerSwCfg = 2, /**<  */
  kOtpPartitionRotCreatorAuthCodesign = 3, /**<  */
  kOtpPartitionRotCreatorAuthState = 4, /**<  */
  kOtpPartitionHwCfg0 = 5, /**<  */
  kOtpPartitionHwCfg1 = 6, /**<  */
  kOtpPartitionSecret0 = 7, /**<  */
  kOtpPartitionSecret1 = 8, /**<  */
  kOtpPartitionSecret2 = 9, /**<  */
  kOtpPartitionLifeCycle = 10, /**<  */
  kOtpPartitionCount = 11, /**< \internal  */
} otp_partition_t;
 
/**
 * Get a SW readable OTP partition information.
 *
 * @param dt Instance of otp_ctrl.
 * @param partition OTP partition identifier.
 * @return OTP partition information.
 */
dt_otp_partition_info_t
dt_otp_ctrl_partition(dt_otp_ctrl_t dt, otp_partition_t partition);
 
 
 
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
 
#endif  // OPENTITAN_DT_OTP_CTRL_H_