dt_aes.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_AES_H_
#define OPENTITAN_DT_AES_H_
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
 
/**
 * @file
 * @brief Device Tables (DT) for IP aes and top darjeeling.
 *
 * This file contains the type definitions and global functions of the aes.
 */
 
#include "hw/top/dt/dt_api.h"
#include <stdint.h>
 
 
 
/**
 * List of instances.
 */
typedef enum dt_aes {
  kDtAes = 0, /**< aes */
  kDtAesFirst = 0, /**< \internal First instance */
  kDtAesCount = 1, /**< \internal Number of instances */
} dt_aes_t;
 
/**
 * List of register blocks.
 *
 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
 */
typedef enum dt_aes_reg_block {
  kDtAesRegBlockCore = 0, /**<  */
  kDtAesRegBlockCount = 1, /**< \internal Number of register blocks */
} dt_aes_reg_block_t;
 
/** Primary register block (associated with the "primary" set of registers that control the IP). */
static const dt_aes_reg_block_t kDtAesRegBlockPrimary = kDtAesRegBlockCore;
 
/**
 * List of memories.
 *
 * Memories are guaranteed to start at 0 and to be consecutively numbered.
 */
typedef enum dt_aes_memory {
  kDtAesMemoryCount = 0, /**< \internal Number of memories */
} dt_aes_memory_t;
 
/**
 * List of Alerts.
 *
 * Alerts are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_aes_alert {
  kDtAesAlertRecovCtrlUpdateErr = 0, /**< This recoverable alert is triggered upon detecting an update error in the shadowed Control Register.
The content of the Control Register is not modified (See Control Register).
The AES unit can be recovered from such a condition by restarting the AES operation, i.e., by re-writing the Control Register.
This should be monitored by the system. */
  kDtAesAlertFatalFault = 1, /**< This fatal alert is triggered upon detecting a fatal fault inside the AES unit.
Examples for such faults include
i) storage errors in the shadowed Control Register,
ii) any internal FSM entering an invalid state,
iii) any sparsely encoded signal taking on an invalid value,
iv) errors in the internal round counter,
v) escalations triggered by the life cycle controller, and
vi) fatal integrity failures on the TL-UL bus.
The AES unit cannot recover from such an error and needs to be reset. */
  kDtAesAlertCount = 2, /**< \internal Number of Alerts */
} dt_aes_alert_t;
 
/**
 * List of clock ports.
 *
 * Clock ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_aes_clock {
  kDtAesClockClk = 0, /**< Clock port clk_i */
  kDtAesClockEdn = 1, /**< Clock port clk_edn_i */
  kDtAesClockCount = 2, /**< \internal Number of clock ports */
} dt_aes_clock_t;
 
/**
 * List of reset ports.
 *
 * Reset ports are guaranteed to be numbered consecutively from 0.
 */
typedef enum dt_aes_reset {
  kDtAesResetRst = 0, /**< Reset port rst_ni */
  kDtAesResetEdn = 1, /**< Reset port rst_edn_ni */
  kDtAesResetCount = 2, /**< \internal Number of reset ports */
} dt_aes_reset_t;
 
/**
 * List of supported hardware features.
 */
#define OPENTITAN_AES_HAS_KEY_LEN_128 1
#define OPENTITAN_AES_HAS_KEY_LEN_192 1
#define OPENTITAN_AES_HAS_KEY_LEN_256 1
#define OPENTITAN_AES_HAS_MODE_ECB 1
#define OPENTITAN_AES_HAS_MODE_CBC 1
#define OPENTITAN_AES_HAS_MODE_CFB_128 1
#define OPENTITAN_AES_HAS_MODE_OFB 1
#define OPENTITAN_AES_HAS_MODE_CTR 1
#define OPENTITAN_AES_HAS_KEY_SIDELOAD 1
#define OPENTITAN_AES_HAS_CLEAR_DATA_OUT 1
#define OPENTITAN_AES_HAS_CLEAR_KEY_IV_DATA_IN 1
#define OPENTITAN_AES_HAS_PRNG_RESEED_RATE 1
#define OPENTITAN_AES_HAS_PRNG_KEY_TOUCH_FORCES_RESEED 1
#define OPENTITAN_AES_HAS_PRNG_FORCE_MASKS 1
#define OPENTITAN_AES_HAS_MANUAL_OPERATION 1
 
 
 
/**
 * Get the aes instance from an instance ID
 *
 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
 *
 * @param inst_id Instance ID.
 * @return A aes instance.
 *
 * **Note:** This function only makes sense if the instance ID has device type aes,
 * otherwise the returned value is unspecified.
 */
dt_aes_t dt_aes_from_instance_id(dt_instance_id_t inst_id);
 
/**
 * Get the instance ID of an instance.
 *
 * @param dt Instance of aes.
 * @return The instance ID of that instance.
 */
dt_instance_id_t dt_aes_instance_id(dt_aes_t dt);
 
/**
 * Get the register base address of an instance.
 *
 * @param dt Instance of aes.
 * @param reg_block The register block requested.
 * @return The register base address of the requested block.
 */
uint32_t dt_aes_reg_block(
    dt_aes_t dt,
    dt_aes_reg_block_t reg_block);
 
/**
 * Get the primary register base address of an instance.
 *
 * This is just a convenience function, equivalent to
 * `dt_aes_reg_block(dt, kDtAesRegBlockCore)`
 *
 * @param dt Instance of aes.
 * @return The register base address of the primary register block.
 */
static inline uint32_t dt_aes_primary_reg_block(
    dt_aes_t dt) {
  return dt_aes_reg_block(dt, kDtAesRegBlockCore);
}
 
/**
 * Get the base address of a memory.
 *
 * @param dt Instance of aes.
 * @param mem The memory requested.
 * @return The base address of the requested memory.
 */
uint32_t dt_aes_memory_base(
    dt_aes_t dt,
    dt_aes_memory_t mem);
 
/**
 * Get the size of a memory.
 *
 * @param dt Instance of aes.
 * @param mem The memory requested.
 * @return The size of the requested memory.
 */
uint32_t dt_aes_memory_size(
    dt_aes_t dt,
    dt_aes_memory_t mem);
 
 
/**
 * Get the alert ID of a aes 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 aes.
 * @param alert A aes alert.
 * @return The Alert Handler alert ID of the alert of this instance.
 */
dt_alert_id_t dt_aes_alert_to_alert_id(
    dt_aes_t dt,
    dt_aes_alert_t alert);
 
/**
 * Convert a global alert ID to a local aes alert type.
 *
 * @param dt Instance of aes.
 * @param alert A global alert ID that belongs to this instance.
 * @return The aes alert, or `kDtAesAlertCount`.
 *
 * **Note:** This function assumes that the global alert ID belongs to the
 * instance of aes passed in parameter. In other words, it must be the case
 * that `dt_aes_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
 * this function will return `kDtAesAlertCount`.
 */
dt_aes_alert_t dt_aes_alert_from_alert_id(
    dt_aes_t dt,
    dt_alert_id_t alert);
 
 
 
/**
 * Get the clock signal connected to a clock port of an instance.
 *
 * @param dt Instance of aes.
 * @param clk Clock port.
 * @return Clock signal.
 */
dt_clock_t dt_aes_clock(
    dt_aes_t dt,
    dt_aes_clock_t clk);
 
/**
 * Get the reset signal connected to a reset port of an instance.
 *
 * @param dt Instance of aes.
 * @param rst Reset port.
 * @return Reset signal.
 */
dt_reset_t dt_aes_reset(
    dt_aes_t dt,
    dt_aes_reset_t rst);
 
 
 
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
 
#endif  // OPENTITAN_DT_AES_H_