hw/ip/otbn/data/otbn.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{ name: "otbn"
  clock_primary: "clk_i"
  bus_device: "tlul"
  bus_host: "none"
  param_list: [
    { name:    "RegFile",
      type:    "otbn_pkg::regfile_e",
      default: "otbn_pkg::RegFileFF",
      desc:    "Selection of the register file implementation. See otbn_pkg.sv."
      local:   "false",
      expose:  "true"
    }
  ]
  interrupt_list: [
    { name: "done"
      desc: "OTBN has completed the operation"
    }
  ]
  alert_list: [
    { name: "fatal"
      desc: "A fatal error. Fatal alerts are non-recoverable and will be asserted until a hard reset."
    }
    { name: "recoverable"
      desc: "A recoverable error. Just sent once (as the processor stops)."
    }
  ]

  inter_signal_list: [
    // TODO: CSRNG isn't committed yet, depends on assumed interface done for
    // AES in https://github.com/lowRISC/opentitan/pull/2140.
    /*{ name:    "entropy",
      type:    "req_rsp",
      act:     "req",
      package: "csrng_pkg",
      struct:  "csrng_entropy",
      width:   "1"
    },*/

    // OTBN is not performing any operation and can be clock/power-gated.
    { name:    "idle",
      type:    "uni",
      struct:  "logic",
      width:   "1",
      act:     "req",
    },
  ],

  regwidth: "32"
  registers: [
    { name: "CMD"
      desc: "command register",
      swaccess: "r0w1c",
      hwaccess: "hro",
      hwext: "true",
      hwqe:  "true",
      fields: [
        { bits: "0"
          name: "start"
          desc: '''
            Start the operation

            The completion is signalled by the done interrupt.
          '''
          tags: [
            // Don't write this field in the automated CSR tests. Doing so will
            // start OTBN, but we won't have initialised its memory with any
            // code, so we'll get Xs on its interfaces and everything will be
            // a bit of a mess!
            "excl:CsrAllTests:CsrExclWrite"
          ]
        }
        { bits: "1",
          name: "dummy",
          desc: '''
            Reggen doesn't generate sub-fields with only a single field
            specified; instead, the whole register is taken as a field, leading
            to signals like `hw2reg.status.d` instead of
            `hw2reg.status.start.d`. Since we expect to add more commands later,
            we force the generation of fields with this dummy field for now.
          '''
        }
      ],
    }
    { name: "STATUS",
      desc: "Status",
      swaccess: "ro",
      hwaccess: "hwo",
      hwext: "true",
      fields: [
        { bits: "0",
          name: "busy",
          desc: "OTBN is performing an operation."
        }
        { bits: "1",
          name: "dummy",
          desc: '''
            See !!CMD.dummy for details.
          '''
        }
      ]
    } // register : status
    { name: "ERR_CODE",
      desc: "Error Code",
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "31:0",
          name: "err_code",
          desc: '''
            The error cause if an error occurred.

            This is set to zero (ErrCodeNoError) when OTBN successfully
            completes an operation or a positive value when OTBN stops on an
            error.

            While OTBN is running (!!CMD.busy set), this has no meaning. When
            OTBN stops this will be set to indicate the outcome. It is
            guaranteed not to change until OTBN is run again (with !!CMD.start).

            See <a href='#error-conditions'>Error Conditions</a> for
            details on the possible values.
          '''
        }
      ]
    } // register : err_code
    { name: "START_ADDR",
      desc: "Start byte address in the instruction memory",
      swaccess: "wo",
      hwaccess: "hro",
      fields: [
        { bits: "31:0",
          name: "start_addr",
          resval: 0,
          desc: '''
            Byte address in the instruction memory OTBN starts to execute from
            when instructed to do so with the !!CMD.start .
          '''
        }
      ]
    } // register : start_addr
    { name: "FATAL_ALERT_CAUSE",
      desc: '''
        The cause of a fatal alert.

        The bits of this register correspond to errors that can cause a fatal
        alert. Software can read these bits to see what went wrong. Once set,
        these bits cannot be cleared.
      '''
      swaccess: "ro",
      hwaccess: "hwo",
      fields: [
        { bits: "0",
          name: "imem_error",
          resval: 0,
          desc: "Set on any ECC error in IMEM"
        }
        { bits: "1",
          name: "dmem_error",
          resval: 0,
          desc: "Set on any ECC error in DMEM"
        }
        { bits: "2",
          name: "reg_error",
          resval: 0,
          desc: "Set on any ECC error in a register file"
        }
      ]
    }

    // Give IMEM and DMEM 16 KiB address space, each, to allow for easy expansion
    // of the actual IMEM and DMEM sizes without changing the address map.
    { skipto: "0x4000" }

    // Imem size (given as `items` below) must be a power of two.
    { window: {
        name: "IMEM"
        items: "1024" // 4 kB
        swaccess: "rw",
        byte-write: "false",
        desc: '''
          Instruction Memory.

          This register should only be accesed while OTBN is not busy, as indicated by the !!STATUS.busy flag.
          Accesses while OTBN is busy are blocking.

          TODO: The exact behavior is yet to be determined, see https://github.com/lowRISC/opentitan/issues/2696 for details.
        '''
      }
    }

    { skipto: "0x8000" }

    // Dmem size (given as `items` below) must be a power of two.
    { window: {
        name: "DMEM"
        items: "1024" // 4 kB
        swaccess: "rw",
        byte-write: "false",
        desc: '''
          Data Memory.

          This register should only be accesed while OTBN is not busy, as indicated by the !!STATUS.busy flag.
          Accesses while OTBN is busy are blocking.

          TODO: The exact behavior is yet to be determined, see https://github.com/lowRISC/opentitan/issues/2696 for details.
        '''
      }
    }
  ]
}