hw/ip/aes/data/aes.hjson

// 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",
  clock_primary: "clk_i",
  bus_device: "tlul",
  regwidth: "32",
  param_list: [
    { name:    "NumRegsKey",
      type:    "int",
      default: "8",
      desc:    "Number registers for key",
      local:   "true"
    },
    { name:    "NumRegsData",
      type:    "int",
      default: "4",
      desc:    "Number registers for input and output data",
      local:   "true"
    }
  ],
  registers: [
##############################################################################
# initial key registers
    { multireg: {
      name: "KEY",
      desc: '''
        Initial Key Registers.
        Loaded into the internal Full Key register upon starting encryption/decryption of the next block.
        All key registers must be written at least once when the key is changed, regardless of key length (write 0 for unusued 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.
      '''
      count: "NumRegsKey",
      cname: "KEY",
      swaccess: "wo",
      hwaccess: "hrw",
      hwext:    "true",
      hwqe:     "true",
      fields: [
        { bits: "31:0", name: "key", desc: "Initial Key" }
      ],
      }
    },
##############################################################################
# input data registers
    { multireg: {
      name: "DATA_IN",
      desc: '''
        Input Data Registers.
        If MANUAL_OPERATION=0 (see Control Register), the AES unit automatically starts encryption/decryption after these register 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 Register.
      '''
      count: "NumRegsData",
      cname: "DATA_IN",
      swaccess: "wo",
      hwaccess: "hrw",
      hwqe:     "true",
      fields: [
        { bits: "31:0", name: "data_in", desc: "Input Data" }
      ],
      }
    },
##############################################################################
# output data registers
    { multireg: {
      name: "DATA_OUT",
      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.
      '''
      count: "NumRegsData",
      cname: "DATA_OUT",
      swaccess: "ro",
      hwaccess: "hrw",
      hwext:    "true",
      hwre:     "true",
      fields: [
        { bits: "31:0", name: "data_out", desc: "Output Data" }
      ],
      }
    },
##############################################################################
# control and status registers
  { name: "CTRL",
    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.
    '''
    swaccess: "rw",
    hwaccess: "hrw",
    hwext:    "true",
    hwqe:     "true",
    fields: [
      { bits: "0",
        name: "OPERATION",
        desc:  '''
          Select encryption(0) or decryption(1) operation of AES unit.
        '''
      }
      { bits: "3:1",
        name: "KEY_LEN",
        resval: "1",
        hwaccess: "hrw",
        desc:  '''
          3-bit one-hot field to select AES key length: 128 bit (3'b001), 192 bit (3'b010)
          or 256 bit (3'b100). Invalid input values, i.e., value 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 3'b001.
        '''
      }
      { bits: "4",
        name: "MANUAL_OPERATION",
        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.
          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.
        '''
      }
    ]
  },
  { name: "TRIGGER",
    desc: '''
      Trigger Register.
      Each bit is individually cleared to 0 when executing the corresponding trigger.
    '''
    swaccess: "wo",
    hwaccess: "hrw",
    fields: [
      { bits: "0",
        name: "START",
        desc:  '''
          Keep AES unit paused (0) or trigger the encryption/decryption of one data block (1).
          This trigger is ignored if MANUAL_OPERATION=0 (see Control Register).
        '''
      }
      { bits: "1",
        name: "KEY_CLEAR",
        desc:  '''
          Keep current values in Initial Key, internal Full Key and Decryption Key registers (0)
          or clear those registers (1).
        '''
      }
      { bits: "2",
        name: "DATA_IN_CLEAR",
        desc:  '''
          Keep current values in input registers (0) or clear those registers (1).
        '''
      }
      { bits: "3",
        name: "DATA_OUT_CLEAR",
        desc:  '''
          Keep current values in output registers (0) or clear those registers (1).
        '''
      }
    ]
  },
  { name: "STATUS",
    desc: "Status Register",
    swaccess: "ro",
    hwaccess: "hwo",
    fields: [
      { bits: "0",
        name: "IDLE",
        resval: "1",
        desc:  '''
          The AES unit is idle (1) or busy (0).
        '''
      }
      { bits: "1",
        name: "STALL",
        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.
        '''
      }
      { bits: "2",
        name: "OUTPUT_VALID",
        desc:  '''
          The AES unit has no valid output (0) or has valid output data (1).
        '''
      }
      { bits: "3",
        name: "INPUT_READY",
        resval: "1",
        desc:  '''
          The AES unit is ready (1) to receive new data input via the DATA_IN registers or
          the present values in the DATA_IN registers have not yet been loaded into the
          module (0).
        '''
      }
    ]
  },
  ],
}