dif_rram_ctrl_autogen.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
 
 
 
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_AUTOGEN_DIF_RRAM_CTRL_AUTOGEN_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_AUTOGEN_DIF_RRAM_CTRL_AUTOGEN_H_
 
// THIS FILE HAS BEEN GENERATED, DO NOT EDIT MANUALLY. COMMAND:
// util/autogen_dif.py -i hw/ip/rram_ctrl/data/rram_ctrl.hjson -o
// bazel-out/k8-fastbuild/bin/sw/device/lib/dif/autogen
 
 
/**
 * @file
 * @brief <a href="/book/hw/ip/rram_ctrl/">RRAM_CTRL</a> Device Interface Functions
 */
 
#include <stdbool.h>
#include <stdint.h>
 
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "hw/top/dt/rram_ctrl.h" // Generated.
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
 
/**
 * A handle to rram_ctrl.
 *
 * This type should be treated as opaque by users.
 */
typedef struct dif_rram_ctrl {
  /**
   * The base address for the rram_ctrl hardware registers.
   */
  mmio_region_t base_addr;
  /**
   * The instance, set to `kDtRramCtrlCount` if not initialized
   * through `dif_rram_ctrl_init_from_dt`.
   */
  dt_rram_ctrl_t dt;
} dif_rram_ctrl_t;
 
/**
 * Creates a new handle for a(n) rram_ctrl peripheral.
 *
 * This function does not actuate the hardware.
 *
 * @param base_addr The MMIO base address of the rram_ctrl peripheral.
 * @param[out] rram_ctrl Out param for the initialized handle.
 * @return The result of the operation.
 *
 * DEPRECATED This function exists solely for the transition to
 * dt-based DIFs and will be removed in the future.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_rram_ctrl_init(
  mmio_region_t base_addr,
  dif_rram_ctrl_t *rram_ctrl);
 
/**
 * Creates a new handle for a(n) rram_ctrl peripheral.
 *
 * This function does not actuate the hardware.
 *
 * @param dt The devicetable description of the device.
 * @param[out] rram_ctrl Out param for the initialized handle.
 * @return The result of the operation.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_rram_ctrl_init_from_dt(
  dt_rram_ctrl_t dt,
  dif_rram_ctrl_t *rram_ctrl);
 
/**
 * Get the DT handle from this DIF.
 *
 * If this DIF was initialized by `dif_rram_ctrl_init_from_dt(dt, ..)`
 * then this function will return `dt`. Otherwise it will return an error.
 *
 * @param rram_ctrl A rram_ctrl handle.
 * @param[out] dt DT handle.
 * @return `kDifBadArg` if the DIF has no DT information, `kDifOk` otherwise.
 */
OT_WARN_UNUSED_RESULT
dif_result_t dif_rram_ctrl_get_dt(
  const dif_rram_ctrl_t *rram_ctrl,
  dt_rram_ctrl_t *dt);
 
  /**
   * A rram_ctrl alert type.
   */
  typedef enum dif_rram_ctrl_alert {
    /**
     * RRAM recoverable errors. Fired whenever a software initiated controller operation completes with any bit set in !!ERR_CODE.
     */
      kDifRramCtrlAlertRecovErr = 0,
    /**
     * RRAM standard fatal errors. Fired whenever any bit in !!STD_FAULT_STATUS is set.
     */
      kDifRramCtrlAlertFatalStdErr = 1,
    /**
     * RRAM fatal errors. Fired whenever any bit in !!FAULT_STATUS is set, including uncorrectable ECC errors.  Note that this alert is not always fatal. The underlying error bits in the !!FAULT_STATUS register remain set until reset, meaning the alert keeps firing. This doesn't hold for !!FAULT_STATUS.PHY_RELBL_ERR. To enable firmware dealing with multi-bit ECC errors during firmware selection and verification, these error bits can be cleared. After passing this stage, it is recommended that firmware classifies the corresponding alert as fatal on the receiver end, i.e, inside the alert handler.
     */
      kDifRramCtrlAlertFatalErr = 2,
    /**
     * Fatal errors triggered inside the RRAM macro, including fatal TL-UL bus integrity faults of the test interface.
     */
      kDifRramCtrlAlertFatalMacroErr = 3,
    /**
     * Recoverable errors triggered inside the RRAM macro.
     */
      kDifRramCtrlAlertRecovMacroErr = 4,
  } dif_rram_ctrl_alert_t;
 
  /**
   * Forces a particular alert, causing it to be escalated as if the hardware
   * had raised it.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param alert The alert to force.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_alert_force(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_alert_t alert);
 
  // DEPRECATED This typedef exists solely for the transition to
  // dt-based interrupt numbers and will be removed in the future.
  typedef dt_rram_ctrl_irq_t dif_rram_ctrl_irq_t;
 
  /**
   * A rram_ctrl interrupt request type.
   *
   * DEPRECATED Use `dt_rram_ctrl_irq_t` instead.
   * This enumeration exists solely for the transition to
   * dt-based interrupt numbers and will be removed in the future.
   *
   * The following are defines to keep the types consistent with DT.
   */
    /**
     * Write FIFO empty
     */
#define kDifRramCtrlIrqWrEmpty kDtRramCtrlIrqWrEmpty
    /**
     * Write FIFO drained to level
     */
#define kDifRramCtrlIrqWrLvl kDtRramCtrlIrqWrLvl
    /**
     * Read FIFO full
     */
#define kDifRramCtrlIrqRdFull kDtRramCtrlIrqRdFull
    /**
     * Read FIFO filled to level
     */
#define kDifRramCtrlIrqRdLvl kDtRramCtrlIrqRdLvl
    /**
     * Operation complete
     */
#define kDifRramCtrlIrqOpDone kDtRramCtrlIrqOpDone
    /**
     * Correctable single-bit error encountered
     */
#define kDifRramCtrlIrqCorr1Err kDtRramCtrlIrqCorr1Err
    /**
     * Correctable double-bit error encountered
     */
#define kDifRramCtrlIrqCorr2Err kDtRramCtrlIrqCorr2Err
 
  /**
   * A snapshot of the state of the interrupts for this IP.
   *
   * This is an opaque type, to be used with the `dif_rram_ctrl_irq_get_state()`
   * and `dif_rram_ctrl_irq_acknowledge_state()` functions.
   */
  typedef uint32_t dif_rram_ctrl_irq_state_snapshot_t;
 
  /**
   * Returns the type of a given interrupt (i.e., event or status) for this IP.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param irq An interrupt request.
   * @param[out] type Out-param for the interrupt type.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_get_type(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_t,
    dif_irq_type_t *type);
 
  /**
   * Returns the state of all interrupts (i.e., pending or not) for this IP.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param[out] snapshot Out-param for interrupt state snapshot.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_get_state(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_state_snapshot_t *snapshot);
 
  /**
   * Returns whether a particular interrupt is currently pending.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param irq An interrupt request.
   * @param[out] is_pending Out-param for whether the interrupt is pending.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_is_pending(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_t,
    bool *is_pending);
 
  /**
   * Acknowledges all interrupts that were pending at the time of the state
   * snapshot.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param snapshot Interrupt state snapshot.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_acknowledge_state(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_state_snapshot_t snapshot);
 
  /**
   * Acknowledges all interrupts, indicating to the hardware that all
   * interrupts have been successfully serviced.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_acknowledge_all(
    const dif_rram_ctrl_t *rram_ctrl
    );
 
  /**
   * Acknowledges a particular interrupt, indicating to the hardware that it has
   * been successfully serviced.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param irq An interrupt request.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_acknowledge(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_t);
 
  /**
   * Forces a particular interrupt, causing it to be serviced as if hardware had
   * asserted it.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param irq An interrupt request.
   * @param val Value to be set.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_force(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_t,
    const bool val);
 
  /**
   * A snapshot of the enablement state of the interrupts for this IP.
   *
   * This is an opaque type, to be used with the
   * `dif_rram_ctrl_irq_disable_all()` and `dif_rram_ctrl_irq_restore_all()`
   * functions.
   */
  typedef uint32_t dif_rram_ctrl_irq_enable_snapshot_t;
 
  /**
   * Checks whether a particular interrupt is currently enabled or disabled.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param irq An interrupt request.
   * @param[out] state Out-param toggle state of the interrupt.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_get_enabled(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_t,
    dif_toggle_t *state);
 
  /**
   * Sets whether a particular interrupt is currently enabled or disabled.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param irq An interrupt request.
   * @param state The new toggle state for the interrupt.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_set_enabled(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_t,
    dif_toggle_t state);
 
  /**
   * Disables all interrupts, optionally snapshotting all enable states for later
   * restoration.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param[out] snapshot Out-param for the snapshot; may be `NULL`.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_disable_all(
    const dif_rram_ctrl_t *rram_ctrl,
    dif_rram_ctrl_irq_enable_snapshot_t *snapshot);
 
  /**
   * Restores interrupts from the given (enable) snapshot.
   *
   * @param rram_ctrl A rram_ctrl handle.
   * @param snapshot A snapshot to restore from.
   * @return The result of the operation.
   */
  OT_WARN_UNUSED_RESULT
  dif_result_t dif_rram_ctrl_irq_restore_all(
    const dif_rram_ctrl_t *rram_ctrl,
    const dif_rram_ctrl_irq_enable_snapshot_t *snapshot);
 
 
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
 
#endif  // OPENTITAN_SW_DEVICE_LIB_DIF_AUTOGEN_DIF_RRAM_CTRL_AUTOGEN_H_