// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
//
# AES register template
{
  name:               "aes",
  human_name:         "AES Accelerator",
  one_line_desc:      "AES encryption and decryption engine with SCA and FI countermeasures",
  one_paragraph_desc: '''
  [Advanced Encryption Standard (AES)][nist-aes] is the primary symmetric encryption and decryption mechanism used in OpenTitan protocols.
  AES Accelerator supports encryption/decryption using AES-128/192/256 in ECB, CBC, CFB, OFB, and CTR block cipher modes.
  Its cipher core uses first-order domain-oriented masking (DOM) to deter side-channel analysis (SCA).
  To save area, the masking can optionally be disabled using a compile-time Verilog parameter.
  In addition, AES Accelerator features several countermeasures to deter fault injection (FI) attacks on the control path.

  [nist-aes]: https://www.nist.gov/publications/advanced-encryption-standard-aes
  '''
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_aes",
  version:            "1.0",
  life_stage:         "L1",
  design_stage:       "D2S",
  verification_stage: "V2S",
  dif_stage:          "S2",
  clocking: [
    {clock: "clk_i", reset: "rst_ni", idle: "idle_o", primary: true},
    {clock: "clk_edn_i", reset: "rst_edn_ni", idle: "idle_o"}
  ]
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],

  ////////////////
  // Parameters //
  ////////////////

  param_list: [
    # Regular parameters
    { name:    "AES192Enable",
      type:    "bit",
      default: "1'b1",
      desc:    '''
        Disable (0) or enable (1) support for 192-bit key lengths (AES-192).
      '''
      local:   "false",
      expose:  "false"
    },
    { name:    "SecMasking",
      type:    "bit",
      default: "1'b1",
      desc:    '''
        Disable (0) or enable (1) first-order masking of the AES cipher core.
        Masking requires the use of a masked S-Box, see SecSBoxImpl parameter.
      '''
      local:   "false",
      expose:  "true"
    },
    { name:    "SecSBoxImpl",
      type:    "aes_pkg::sbox_impl_e",
      default: "aes_pkg::SBoxImplDom",
      desc:    '''
        Selection of the S-Box implementation. See aes_pkg.sv.
      '''
      local:   "false",
      expose:  "true"
    },
    { name:    "SecStartTriggerDelay",
      type:    "int unsigned",
      default: "0",
      desc:    '''
        Manual start trigger delay, useful for SCA measurements.
        A value of e.g. 40 allows the processor to go into sleep before AES starts operation.
      '''
      local:   "false",
      expose:  "true"
    },
    { name:    "SecAllowForcingMasks",
      type:    "bit",
      default: "1'b0",
      desc:    '''
        Forbid (0) or allow (1) forcing the masking PRNG output to a constant value via FORCE_MASKS bit in the Auxiliary Control Register.
        Useful for SCA measurements.
        Meaningful only if masking is enabled.
      '''
      local:   "false",
      expose:  "true"
    },
    { name:    "SecSkipPRNGReseeding",
      type:    "bit",
      default: "1'b0",
      desc:    '''
        Perform (0) or skip (1) PRNG reseeding requests, useful for SCA measurements only.
        The current SCA setup doesn't provide sufficient resources to implement the infrastructure required for PRNG reseeding (CSRNG, EDN).
        To enable SCA resistance evaluations, we need to skip reseeding requests on the SCA platform.
      '''
      local:   "false",
      expose:  "true"
    },
    # Random netlist constants
    { name:    "RndCnstClearingLfsrSeed",
      type:    "aes_pkg::clearing_lfsr_seed_t",
      desc:    '''
        Default seed of the PRNG used for register clearing.
      '''
      randcount: "64",
      randtype:  "data"
    },
    { name:    "RndCnstClearingLfsrPerm",
      type:    "aes_pkg::clearing_lfsr_perm_t",
      desc:    '''
        Permutation applied to the LFSR of the PRNG used for clearing.
      '''
      randcount: "64",
      randtype:  "perm"
    },
    { name:    "RndCnstClearingSharePerm",
      type:    "aes_pkg::clearing_lfsr_perm_t",
      desc:    '''
        Permutation applied to the clearing PRNG output for clearing the second share of registers.
      '''
      randcount: "64",
      randtype:  "perm"
    },
    { name:    "RndCnstMaskingLfsrSeed",
      type:    "aes_pkg::masking_lfsr_seed_t",
      desc:    '''
        Default seed of the PRNG used for masking.
      '''
      randcount: "160",
      randtype:  "data"
    },
    { name:    "RndCnstMaskingLfsrPerm",
      type:    "aes_pkg::masking_lfsr_perm_t",
      desc:    '''
        Permutation applied to the concatenated LFSRs of the PRNG used for masking.
      '''
      randcount: "160",
      randtype:  "perm"
    },
    # Note: All parameters below are local, they are not actually configurable.
    # Selecting values different from the default values below might cause undefined behavior.
    { name:    "NumRegsKey",
      type:    "int",
      default: "8",
      desc:    "Number registers for key",
      local:   "true"
    },
    { name:    "NumRegsIv",
      type:    "int",
      default: "4",
      desc:    "Number registers for initialization vector",
      local:   "true"
    },
    { name:    "NumRegsData",
      type:    "int",
      default: "4",
      desc:    "Number registers for input and output data",
      local:   "true"
    }
  ],

  /////////////////////////////
  // Intermodule Connections //
  /////////////////////////////

  inter_signal_list: [
    { name:    "idle",
      type:    "uni",
      act:     "req",
      package: "prim_mubi_pkg",
      struct:  "mubi4",
      width:   "1"
    },
    { struct:  "lc_tx"
      type:    "uni"
      name:    "lc_escalate_en"
      act:     "rcv"
      default: "lc_ctrl_pkg::Off"
      package: "lc_ctrl_pkg"
    }
    { struct:  "edn"
      type:    "req_rsp"
      name:    "edn"
      act:     "req"
      package: "edn_pkg"
    }
    { struct:  "hw_key_req"
      type:    "uni"
      name:    "keymgr_key"
      act:     "rcv"
      package: "keymgr_pkg"
    }
  ],

  ///////////////////////////
  // Interrupts and Alerts //
  ///////////////////////////

  alert_list: [
    //{ name: "informative",
    //  desc: '''
    //    The informative alert can currently not be triggered.
    //    The AES unit recovers from such a condition automatically.
    //    No further action needs to be taken but this should be monitored by the system.
    //  '''
    //}
    { name: "recov_ctrl_update_err",
      desc: '''
        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.
      '''
    }
    { name: "fatal_fault",
      desc: '''
        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.
      '''
    }
  ],

  /////////////////////
  // Countermeasures //
  /////////////////////

  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
    { name: "LC_ESCALATE_EN.INTERSIG.MUBI",
      desc: "The global escalation input signal from life cycle is multibit encoded."
    }
    { name: "MAIN.CONFIG.SHADOW",
      desc: "Main control register shadowed."
    }
    { name: "MAIN.CONFIG.SPARSE",
      desc: "Critical fields in main control register one-hot encoded."
    }
    { name: "AUX.CONFIG.SHADOW",
      desc: "Auxiliary control register shadowed."
    }
    { name: "AUX.CONFIG.REGWEN",
      desc: "Auxiliary control register can be locked until reset."
    }
    { name: "KEY.SIDELOAD",
      desc: "The key can be loaded from a key manager via sideload interface without exposing it to software."
    }
    { name: "KEY.SW_UNREADABLE",
      desc: "Key registers are not readable by software."
    }
    { name: "DATA_REG.SW_UNREADABLE",
      desc: "Data input and internal state registers are not readable by software."
    }
    { name: "KEY.SEC_WIPE",
      desc: "Key registers are cleared with pseudo-random data."
    }
    { name: "IV.CONFIG.SEC_WIPE",
      desc: "IV registers are cleared with pseudo-random data."
    }
    { name: "DATA_REG.SEC_WIPE",
      desc: "Data input/output and internal state registers are cleared with pseudo-random data."
    }
    { name: "DATA_REG.KEY.SCA",
      desc: '''
        Internal state register cleared with pseudo-random data at the end of the last round.
        This uses the same mechanism as KEY.SEC_WIPE and is active independent of KEY.MASKING.
      '''
    }
    { name: "KEY.MASKING",
      desc: '''
        1st-order domain-oriented masking of the cipher core including data path and key expand.
        Can optionally be disabled via compile-time Verilog parameter for instantiations that don't need SCA hardening.
      '''
    }
    { name: "MAIN.FSM.SPARSE",
      desc: "The main control FSM uses a sparse state encoding."
    }
    { name: "MAIN.FSM.REDUN",
      desc: "The main control FSM uses multiple, independent logic rails."
    }
    { name: "CIPHER.FSM.SPARSE",
      desc: "The cipher core FSM uses a sparse state encoding."
    }
    { name: "CIPHER.FSM.REDUN",
      desc: "The cipher core FSM uses multiple, independent logic rails."
    }
    { name: "CIPHER.CTR.REDUN",
      desc: "The AES round counter inside the cipher core FSM is protected with multiple, independent logic rails."
    }
    { name: "CTR.FSM.SPARSE",
      desc: "The CTR mode FSM uses a sparse state encoding."
    }
    { name: "CTR.FSM.REDUN",
      desc: "The CTR mode FSM uses multiple, independent logic rails."
    }
    { name: "CTRL.SPARSE",
      desc: "Critical control signals such as handshake and MUX control signals use sparse encodings."
    }
    { name: "MAIN.FSM.GLOBAL_ESC",
      desc: "The main control FSM moves to a terminal error state upon global escalation."
    }
    { name: "MAIN.FSM.LOCAL_ESC",
      desc: '''
        The main control FSM moves to a terminal error state upon local escalation.
        Can be triggered by MAIN.FSM.SPARSE, MAIN.FSM.REDUN, CTRL.SPARSE, as well as CIPHER.FSM.LOCAL_ESC, CTR.FSM.LOCAL_ESC.
      '''
    }
    { name: "CIPHER.FSM.LOCAL_ESC",
      desc: '''
        The cipher core FSM moves to a terminal error state upon local escalation.
        Can be triggered by CIPHER.FSM.SPARSE, CIPHER.FSM.REDUN, CIPHER.CTR.REDUN, CTRL.SPARSE as well as MAIN.FSM.LOCAL_ESC.
      '''
    }
    { name: "CTR.FSM.LOCAL_ESC",
      desc: '''
        The CTR mode FSM moves to a terminal error state upon local escalation.
        Can be triggered by CTR.FSM.SPARSE, CTR.FSM.REDUN, and CTRL.SPARSE.
      '''
    }
    { name: "DATA_REG.LOCAL_ESC",
      desc: "Upon local escalation, the module doesn't output intermediate state."
    }
    // This is work in progress.
    // Datapath FI hardening hasn't been a strict requirement but with the current cipher core architecture it can be done at relatively low area/performance overhead and therefore is a nice-to-have.
    //{ name: "DATA_REG.INTEGRITY",
    //  desc: "Datapath FI hardening."
    //}
  ]

  ///////////////
  // Registers //
  ///////////////

  regwidth: "32",
  registers: [
##############################################################################
# initial key registers
    { multireg: {
      name: "KEY_SHARE0",
      resval: "0",
      desc: '''
        Initial Key Registers Share 0.

        The actual initial key corresponds to Initial Key Registers Share 0 XORed with Initial Key Registers Share 1.
        Loaded into the internal Full Key register upon starting encryption/decryption of the next block.
        All key registers (Share 0 and Share 1) must be written at least once when the key is changed, regardless of key length (write random data for unused bits).
        The order in which the registers are updated does not matter.
        Can only be updated when the AES unit is idle.
        If the AES unit is non-idle, writes to these registers are ignored.
        Upon reset, these registers are cleared with pseudo-random data.
      '''
      count: "NumRegsKey",
      cname: "KEY_SHARE0",
      swaccess: "wo",
      hwaccess: "hrw",
      hwext:    "true",
      hwqe:     "true",
      fields: [
        { bits: "31:0", name: "key_share0", desc: "Initial Key Share 0" }
      ],
      tags: [// Updates based on writes to other regs.
             // These registers are reset to 0, but the reset also triggers internal operations that clear these registers with pseudo-random data shortly afterwards (See Trigger Register).
             "excl:CsrHwResetTest:CsrExclCheck"]
      }
    },
    { multireg: {
      name: "KEY_SHARE1",
      resval: "0",
      desc: '''
        Initial Key Registers Share 1.

        The actual initial key corresponds to Initial Key Registers Share 0 XORed with Initial Key Registers Share 1.
        Loaded into the internal Full Key register upon starting encryption/decryption of the next block.
        All key registers (Share 0 and Share 1) must be written at least once when the key is changed, regardless of key length (write random data for unused bits).
        The order in which the registers are updated does not matter.
        Can only be updated when the AES unit is idle.
        If the AES unit is non-idle, writes to these registers are ignored.
        Upon reset, these registers are cleared with pseudo-random data.
      '''
      count: "NumRegsKey",
      cname: "KEY_SHARE1",
      swaccess: "wo",
      hwaccess: "hrw",
      hwext:    "true",
      hwqe:     "true",
      fields: [
        { bits: "31:0", name: "key_share1", desc: "Initial Key Share 1" }
      ],
      tags: [// Updates based on writes to other regs.
             // These registers are reset to 0, but the reset also triggers internal operations that clear these registers with pseudo-random data shortly afterwards (See Trigger Register).
             "excl:CsrHwResetTest:CsrExclCheck"]
      }
    },
##############################################################################
# initialization vector registers
    { multireg: {
      name: "IV",
      resval: "0",
      desc: '''
        Initialization Vector Registers.

        The initialization vector (IV) or initial counter value must be written to these registers when starting a new message in CBC or CTR mode (see Control Register), respectively.
        In CBC and CTR modes, the AES unit does not start encryption/decryption with a partially updated IV.
        Each register has to be written at least once.
        The order in which the registers are written does not matter.
        If the AES unit is non-idle, writes to these registers are ignored.
        Whenever starting a new message, the corresponding IV value must be provided by the processor.
        Once started, the AES unit automatically updates the contents of these registers.
        In ECB mode, the IV registers are not used and do not need to be configured.
        Upon reset, these registers are cleared with pseudo-random data.
      '''
      count: "NumRegsIv",
      cname: "IV",
      swaccess: "rw",
      hwaccess: "hrw",
      hwext:    "true",
      hwqe:     "true",
      fields: [
        { bits: "31:0", name: "iv", desc: "Initialization Vector" }
      ],
      tags: [// Updated by the HW.
             // Updates based on writes to other regs.
             // These registers are reset to 0, but the reset also triggers internal operations that clear these registers with pseudo-random data shortly afterwards (See Trigger Register).
             "excl:CsrAllTests:CsrExclCheck"]
      }
    },
##############################################################################
# input data registers
    { multireg: {
      name: "DATA_IN",
      resval: "0",
      desc: '''
        Input Data Registers.

        If MANUAL_OPERATION=0 (see Control Register), the AES unit automatically starts encryption/decryption after all Input Data registers have been written.
        Each register has to be written at least once.
        The order in which the registers are written does not matter.
        Loaded into the internal State register upon starting encryption/decryption of the next block.
        After that, the processor can update the Input Data registers (See INPUT_READY field of Status Register).
        Upon reset, these registers are cleared with pseudo-random data.
      '''
      count: "NumRegsData",
      cname: "DATA_IN",
      swaccess: "wo",
      hwaccess: "hrw",
      hwqe:     "true",
      fields: [
        { bits: "31:0", name: "data_in", desc: "Input Data" }
      ],
      tags: [// Updates based on writes to other regs.
             // These registers are reset to 0, but the reset also triggers internal operations that clear these registers with pseudo-random data shortly afterwards (See Trigger Register).
             "excl:CsrHwResetTest:CsrExclCheck"]
      }
    },
##############################################################################
# output data registers
    { multireg: {
      name: "DATA_OUT",
      resval: "0",
      desc: '''
        Output Data Register.

        Holds the output data produced by the AES unit during the last encryption/decryption operation.
        If MANUAL_OPERATION=0 (see Control Register), the AES unit is stalled when the previous output data has not yet been read and is about to be overwritten.
        Each register has to be read at least once.
        The order in which the registers are read does not matter.
        Upon reset, these registers are cleared with pseudo-random data.
      '''
      count: "NumRegsData",
      cname: "DATA_OUT",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext:    "true",
      hwre:     "true",
      fields: [
        { bits: "31:0", name: "data_out", desc: "Output Data" }
      ]
      tags: [// Updated by the HW.
             // Updates based on writes to other regs.
             // These registers are reset to 0, but the reset also triggers internal operations that clear these registers with pseudo-random data shortly afterwards (See Trigger Register).
             // Exclude from init and write-read checks.
             "excl:CsrAllTests:CsrExclCheck"]
      }
    },
##############################################################################
# control and status registers
  { name: "CTRL_SHADOWED",
    desc: '''
      Control Register.

      Can only be updated when the AES unit is idle.
      If the AES unit is non-idle, writes to this register are ignored.
      This register is shadowed, meaning two subsequent write operations are required to change its content.
      If the two write operations try to set a different value, a recoverable alert is triggered (See Status Register).
      A read operation clears the internal phase tracking: The next write operation is always considered a first write operation of an update sequence.
      Any write operation to this register will clear the status tracking required for automatic mode (See MANUAL_OPERATION field).
      A write to the Control Register is considered the start of a new message.
      Hence, software needs to provide new key, IV and input data afterwards.
    '''
    swaccess: "rw",
    hwaccess: "hrw",
    hwext:    "true",
    hwqe:     "true",
    shadowed: "true",
    update_err_alert: "recov_ctrl_update_err",
    storage_err_alert: "fatal_fault",
    fields: [
      { bits: "1:0",
        name: "OPERATION",
        resval: "0x1",
        hwaccess: "hrw",
        desc:  '''
          2-bit one-hot field to select the operation of AES unit.
          Invalid input values, i.e., values with multiple bits set and value 2'b00, are mapped to AES_ENC (2'b01).
        '''
        enum: [
          { value: "1",
            name: "AES_ENC",
            desc: '''
              2'b01: Encryption.
              Invalid input values, i.e., 2'b00 and 2'b11, are mapped to AES_ENC.
            '''
          },
          { value: "2",
            name: "AES_DEC",
            desc: '''
              2'b10: Decryption.
            '''
          },
        ]
        tags: ["shadowed_reg_path:u_aes_core.u_ctrl_reg_shadowed.u_ctrl_reg_shadowed_operation"]
      }
      { bits: "7:2",
        name: "MODE",
        resval: "0x20",
        hwaccess: "hrw",
        desc:  '''
          6-bit one-hot field to select AES block cipher mode.
          Invalid input values, i.e., values with multiple bits set and value 6'b00_0000, are mapped to AES_NONE (6'b10_0000).
        '''
        enum: [
          { value: "1",
            name: "AES_ECB",
            desc: '''
              6'b00_0001: Electronic Codebook (ECB) mode.
            '''
          },
          { value: "2",
            name: "AES_CBC",
            desc: '''
              6'b00_0010: Cipher Block Chaining (CBC) mode.
            '''
          },
          { value: "4",
            name: "AES_CFB",
            desc: '''
              6'b00_0100: Cipher Feedback (CFB) mode.
            '''
          },
          { value: "8",
            name: "AES_OFB",
            desc: '''
              6'b00_1000: Output Feedback (OFB) mode.
            '''
          },
          { value: "16",
            name: "AES_CTR",
            desc: '''
              6'b01_0000: Counter (CTR) mode.
            '''
          },
          { value: "32",
            name: "AES_NONE",
            desc: '''
              6'b10_0000: Invalid input values, i.e., value with multiple bits set and value 6'b00_0000, are mapped to AES_NONE.
            '''
          }
        ]
        tags: ["shadowed_reg_path:u_aes_core.u_ctrl_reg_shadowed.u_ctrl_reg_shadowed_mode"]
      }
      { bits: "10:8",
        name: "KEY_LEN",
        resval: "1",
        hwaccess: "hrw",
        desc: '''
          3-bit one-hot field to select AES key length.
          Invalid input values, i.e., values with multiple bits set, value 3'b000, and value 3'b010 in case 192-bit keys are not supported (because disabled at compile time) are mapped to AES_256 (3'b100).
        '''
        enum: [
          { value: "1",
            name: "AES_128",
            desc: '''
              3'b001: 128-bit key length.
            '''
          },
          { value: "2",
            name: "AES_192",
            desc: '''
              3'b010: 192-bit key length.
              In case support for 192-bit keys has been disabled at compile time, setting this value results in configuring AES_256 (3'b100).
            '''
          },
          { value: "4",
            name: "AES_256",
            desc: '''
              3'b100: 256-bit key length.
              Invalid input values, i.e., values with multiple bits set, value 3'b000, and value 3'b010 in case 192-bit keys are not supported (because disabled at compile time) are mapped to AES_256.
            '''
          }
        ]
        tags: ["shadowed_reg_path:u_aes_core.u_ctrl_reg_shadowed.u_ctrl_reg_shadowed_key_len"]
      }
      { bits: "11",
        name: "SIDELOAD",
        resval: "0",
        desc: '''
          Controls whether the AES unit uses the key provided by the key manager via key sideload interface (1) or the key provided by software via Initial Key Registers KEY_SHARE1_0 - KEY_SHARE1_7 (0).
        '''
        tags: ["shadowed_reg_path:u_aes_core.u_ctrl_reg_shadowed.u_ctrl_reg_shadowed_sideload"]
      }
      { bits: "14:12",
        name: "PRNG_RESEED_RATE",
        resval: "1",
        hwaccess: "hrw",
        desc: '''
          3-bit one-hot field to control the reseeding rate of the internal pseudo-random number generator (PRNG) used for masking.
          Invalid input values, i.e., values with multiple bits set and value 3'b000 are mapped to the highest reseeding rate PER_1 (3'b001).
        '''
        enum: [
          { value: "1",
            name: "PER_1",
            desc: '''
              3'b001: Reseed the masking PRNG once per block.
              Invalid input values, i.e., values with multiple bits set and value 3'b000 are mapped to PER_1 (3'b001).
              This results in a max entropy consumption rate of ~286 Mbit/s.
            '''
          },
          { value: "2",
            name: "PER_64",
            desc: '''
              3'b010: Reseed the masking PRNG approximately once per every 64 blocks.
              This results in a max entropy consumption rate of ~4.5 Mbit/s.
            '''
          },
          { value: "4",
            name: "PER_8K",
            desc: '''
              3'b100: Reseed the masking PRNG approximately once per every 8192 blocks.
              This results in an max entropy consumption rate of ~0.035 Mbit/s.
            '''
          }
        ]
        tags: ["shadowed_reg_path:u_aes_core.u_ctrl_reg_shadowed.u_ctrl_reg_shadowed_prng_reseed_rate"]
      }
      { bits: "15",
        name: "MANUAL_OPERATION",
        resval: "0"
        desc:  '''
          Controls whether the AES unit is operated in normal/automatic mode (0) or fully manual mode (1).
          In automatic mode (0), the AES unit automatically i) starts to encrypt/decrypt when it receives new input data, and ii) stalls during the last encryption/decryption cycle if the previous output data has not yet been read.
          This is the most efficient mode to operate in.
          Note that the corresponding status tracking is automatically cleared upon a write to the Control Register.
          In manual mode (1), the AES unit i) only starts to encrypt/decrypt after receiving a start trigger (see Trigger Register), and ii) overwrites previous output data irrespective of whether it has been read out or not.
          This mode is useful if software needs full control over the AES unit.
        '''
        tags: ["shadowed_reg_path:u_aes_core.u_ctrl_reg_shadowed.u_ctrl_reg_shadowed_manual_operation"]
      }
    ]
    tags: [// Updated by the HW.
           // Updates based on writes to this reg (reset test possible).
           // Exclude from write-read checks.
           "excl:CsrNonInitTests:CsrExclWriteCheck"]
  },
  { name: "CTRL_AUX_SHADOWED",
    desc: '''
      Auxiliary Control Register.

      This register is shadowed, meaning two subsequent write operations are required to change its content.
      If the two write operations try to set a different value, a recoverable alert is triggered (See Status Register).
      A read operation clears the internal phase tracking: The next write operation is always considered a first write operation of an update sequence.
    '''
    swaccess: "rw",
    hwaccess: "hro",
    shadowed: "true",
    regwen:   "CTRL_AUX_REGWEN",
    update_err_alert: "recov_ctrl_update_err",
    storage_err_alert: "fatal_fault",
    fields: [
      { bits:   "0",
        name:   "KEY_TOUCH_FORCES_RESEED",
        desc:   '''
                Controls whether providing a new key triggers the reseeding of internal pseudo-random number generators used for clearing and masking (1) or not (0).
                ''',
        resval: 1,
      }
      { bits:   "1",
        name:   "FORCE_MASKS",
        desc:   '''
                Allow the internal masking PRNG to advance (0) or force its internal state (1) leading to constant masks.
                Setting all masks to constant value can be useful when performing SCA.
                To completely disable the masking, the second key share (KEY_SHARE1_0 - KEY_SHARE1_7) must be zero as well.
                In addition, a special seed needs to be loaded into the masking PRNG using the EDN interface.
                Only applicable if both the Masking parameter and the SecAllowForcingMasks parameter are set to one.
                '''
        resval: "0"
      }
    ]
  },
  { name:     "CTRL_AUX_REGWEN",
    desc:     '''
              Lock bit for Auxiliary Control Register.
              '''
    swaccess: "rw0c",
    hwaccess: "none",
    fields: [
    {   bits:   "0",
        desc:   '''
                Auxiliary Control Register configuration enable bit.
                If this is cleared to 0, the Auxiliary Control Register cannot be written anymore.
                ''',
        resval: 1,
      }
    ]
  },
  { name: "TRIGGER",
    desc: '''
      Trigger Register.

      Each bit is individually cleared to zero when executing the corresponding trigger.
      While executing any of the triggered operations, the AES unit will set the IDLE bit in the Status Register to zero.
      The processor must check the Status Register before triggering further actions.
      For example, writes to Initial Key and IV Registers are ignored while the AES unit is busy.
      Writes to the Input Data Registers are not ignored but the data will be cleared if a KEY_IV_DATA_IN_CLEAR operation is pending.
    '''
    swaccess: "wo",
    hwaccess: "hrw",
    # Tag info (CSR test exclusions):
    #  Updated by the HW.
    #  Updates based on writes to this reg.
    #  -> Exclude all fields from write-read checks.
    #  Upon reset, the non-zero values trigger internal operations that clear this reg to zero.
    #  -> Exclude fields with non-zero reset value from init and write-read checks (also in reset test).
    fields: [
      { bits: "0",
        name: "START",
        resval: "0"
        desc:  '''
          Keep AES unit paused (0) or trigger the encryption/decryption of one data block (1).
          This trigger is cleared to `0` if MANUAL_OPERATION=0 or if MODE=AES_NONE (see Control Register).
        '''
        tags: ["excl:CsrNonInitTests:CsrExclWriteCheck"]
      }
      { bits: "1",
        name: "KEY_IV_DATA_IN_CLEAR",
        resval: "1"
        desc:  '''
          Keep current values in Initial Key, internal Full Key and Decryption Key registers, IV registers and Input Data registers (0) or clear all those registers with pseudo-random data (1).
        '''
        tags: ["excl:CsrAllTests:CsrExclCheck"]
      }
      { bits: "2",
        name: "DATA_OUT_CLEAR",
        resval: "1"
        desc:  '''
          Keep current values in Output Data registers (0) or clear those registers with pseudo-random data (1).
        '''
        tags: ["excl:CsrAllTests:CsrExclCheck"]
      }
      { bits: "3",
        name: "PRNG_RESEED",
        resval: "1"
        desc:  '''
          Keep continuing with the current states of the internal pseudo-random number generators used for register clearing and masking (0) or perform a reseed of the internal states from the connected entropy source (1).
          If the KEY_TOUCH_FORCES_RESEED bit in the Auxiliary Control Register is set to one, this trigger will automatically get set after providing a new initial key.
        '''
        tags: ["excl:CsrAllTests:CsrExclCheck"]
      }
    ]
  },
  { name: "STATUS",
    desc: "Status Register",
    swaccess: "ro",
    hwaccess: "hwo",
    # Tag info (CSR test exclusions):
    #  Updated by the HW.
    #  Updates based on writes to other regs.
    #  -> Exclude all fields (except ALERT_FATAL_FAULT) from init and write-read checks.
    #  Upon reset, internal operations are triggered at the end of which IDLE and INPUT_READY will be 1.
    #  -> Exclude IDLE and INPUT_READY field from init and write-read checks (also in reset test).
    fields: [
      { bits: "0",
        name: "IDLE",
        resval: "0",
        hwaccess: "hrw",
        desc:  '''
          The AES unit is idle (1) or busy (0).
          This flag is `0` if one of the following operations is currently running: i) encryption/decryption, ii) register clearing or iii) PRNG reseeding.
          This flag is also `0` if an encryption/decryption is running but the AES unit is stalled.
        '''
        tags: ["excl:CsrAllTests:CsrExclCheck"]
      }
      { bits: "1",
        name: "STALL",
        resval: "0"
        desc:  '''
          The AES unit is not stalled (0) or stalled (1) because there is previous
          output data that must be read by the processor before the AES unit can
          overwrite this data.
          This flag is not meaningful if MANUAL_OPERATION=1 (see Control Register).
        '''
        tags: ["excl:CsrNonInitTests:CsrExclCheck"]
      }
      { bits: "2",
        name: "OUTPUT_LOST",
        resval: "0"
        hwaccess: "hrw",
        desc:  '''
          All previous output data has been fully read by the processor (0) or at least one previous output data block has been lost (1).
          It has been overwritten by the AES unit before the processor could fully read it.
          Once set to `1`, this flag remains set until AES operation is restarted by re-writing the Control Register.
          The primary use of this flag is for design verification.
          This flag is not meaningful if MANUAL_OPERATION=0 (see Control Register).
        '''
        tags: ["excl:CsrNonInitTests:CsrExclCheck"]
      }
      { bits: "3",
        name: "OUTPUT_VALID",
        resval: "0"
        desc:  '''
          The AES unit has no valid output (0) or has valid output data (1).
        '''
        tags: ["excl:CsrNonInitTests:CsrExclCheck"]
      }
      { bits: "4",
        name: "INPUT_READY",
        resval: "0",
        desc:  '''
          The AES unit is ready (1) or not ready (0) to receive new data input via the DATA_IN registers.
          If the present values in the DATA_IN registers have not yet been loaded into the
          module this flag is `0` (not ready).
        '''
        tags: ["excl:CsrAllTests:CsrExclCheck"]
      }
      { bits: "5",
        name: "ALERT_RECOV_CTRL_UPDATE_ERR",
        resval: "0",
        desc:  '''
          An update error has not occurred (0) or has occurred (1) in the shadowed Control Register.
          AES operation needs to be restarted by re-writing the Control Register.
        '''
        tags: ["excl:CsrNonInitTests:CsrExclCheck"]
      }
      { bits: "6",
        name: "ALERT_FATAL_FAULT",
        resval: "0",
        desc:  '''
          No fatal fault has occurred inside the AES unit (0).
          A fatal fault has occurred and the AES unit needs to be reset (1).
          Examples for fatal faults include
          i) storage errors in the Control Register,
          ii) if any internal FSM enters an invalid state,
          iii) if any sparsely encoded signal takes 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.
        '''
      }
    ]
  },
  ],
}