| // Copyright lowRISC contributors. |
| // Licensed under the Apache License, Version 2.0, see LICENSE for details. |
| // SPDX-License-Identifier: Apache-2.0 |
| { name: "otbn" |
| clocking: [ |
| {clock: "clk_i", reset: "rst_ni", idle: "idle_o", primary: true}, |
| {clock: "clk_edn_i", reset: "rst_edn_ni", idle: "idle_o"}, |
| {clock: "clk_otp_i", reset: "rst_otp_ni", idle: "idle_otp_o"} |
| ] |
| bus_interfaces: [ |
| { protocol: "tlul", direction: "device" } |
| ], |
| param_list: [ |
| { name: "Stub", |
| type: "bit", |
| default: "0", |
| desc: "Stub out the core of Otbn logic" |
| local: "false", |
| expose: "true" |
| }, |
| { 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" |
| }, |
| { name: "RndCnstUrndPrngSeed", |
| type: "otbn_pkg::urnd_prng_seed_t", |
| desc: ''' |
| Default seed of the PRNG used for URND. |
| ''' |
| randcount: "256", |
| randtype: "data" |
| }, |
| { name: "RndCnstOtbnKey", |
| type: "otp_ctrl_pkg::otbn_key_t", |
| desc: ''' |
| Compile-time random reset value for IMem/DMem scrambling key. |
| ''' |
| randcount: "128", |
| randtype: "data" |
| }, |
| { name: "RndCnstOtbnNonce", |
| type: "otp_ctrl_pkg::otbn_nonce_t", |
| desc: ''' |
| Compile-time random reset value for IMem/DMem scrambling nonce. |
| ''' |
| randcount: "64", |
| randtype: "data" |
| }, |
| ] |
| 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: "recov" |
| desc: "A recoverable error. Just sent once (as the processor stops)." |
| } |
| ] |
| |
| inter_signal_list: [ |
| // Key request to OTP |
| { struct: "otbn_otp_key" |
| type: "req_rsp" |
| name: "otbn_otp_key" |
| act: "req" |
| default: "'0" |
| package: "otp_ctrl_pkg" |
| }, |
| // EDN interface for RND |
| { struct: "edn" |
| type: "req_rsp" |
| name: "edn_rnd" |
| act: "req" |
| package: "edn_pkg" |
| }, |
| |
| // EDN interface for URND |
| { struct: "edn" |
| type: "req_rsp" |
| name: "edn_urnd" |
| act: "req" |
| package: "edn_pkg" |
| }, |
| |
| // OTBN is not performing any operation and can be clock/power-gated. |
| { name: "idle", |
| type: "uni", |
| struct: "mubi4", |
| width: "1", |
| act: "req", |
| package: "prim_mubi_pkg" |
| }, |
| |
| // ram configuration |
| { struct: "ram_1p_cfg", |
| package: "prim_ram_1p_pkg", |
| type: "uni", |
| name: "ram_cfg", |
| act: "rcv" |
| }, |
| |
| // Lifecycle escalation |
| { struct: "lc_tx" |
| type: "uni" |
| name: "lc_escalate_en" |
| act: "rcv" |
| default: "lc_ctrl_pkg::Off" |
| package: "lc_ctrl_pkg" |
| }, |
| |
| // Key sideload |
| { struct: "otbn_key_req" |
| type: "uni" |
| name: "keymgr_key" |
| act: "rcv" |
| package: "keymgr_pkg" |
| }, |
| ], |
| countermeasures: [ |
| { name: "BUS.INTEGRITY", |
| desc: "End-to-end bus integrity scheme." |
| } |
| { name: "CONTROLLER.FSM.GLOBAL_ESC", |
| desc: "The controller FSM moves to a terminal error state upon global escalation." |
| } |
| { name: "CONTROLLER.FSM.LOCAL_ESC", |
| desc: ''' |
| The controller FSM moves to a terminal error state upon local escalation. |
| Can be triggered by CONTROLLER.FSM.SPARSE, SCRAMBLE_CTRL.FSM.SPARSE, and START_STOP_CTRL.FSM.SPARSE. |
| ''' |
| } |
| { name: "CONTROLLER.FSM.SPARSE", |
| desc: "The controller FSM uses a sparse state encoding." |
| } |
| { name: "SCRAMBLE.KEY.SIDELOAD", |
| desc: "The scrambling key is sideloaded from OTP and thus unreadable by SW." |
| } |
| { name: "SCRAMBLE_CTRL.FSM.LOCAL_ESC", |
| desc: ''' |
| The scramble control FSM moves to a terminal error state upon local escalation. |
| Can be triggered by SCRAMBLE_CTRL.FSM.SPARSE. |
| ''' |
| } |
| { name: "SCRAMBLE_CTRL.FSM.SPARSE", |
| desc: "The scramble control FSM uses a sparse state encoding." |
| } |
| { name: "START_STOP_CTRL.FSM.LOCAL_ESC", |
| desc: ''' |
| The start-stop control FSM moves to a terminal error state upon local escalation. |
| Can be triggered by START_STOP_CTRL.FSM.SPARSE. |
| ''' |
| } |
| { name: "START_STOP_CTRL.FSM.SPARSE", |
| desc: "The start-stop control FSM uses a sparse state encoding." |
| } |
| { name: "DATA_REG_SW.SCA", |
| desc: "Blanking of bignum data paths when unused by the executing instruction." |
| } |
| { name: "CTRL.REDUN", |
| desc: "Check pre-decoded control used for blanking matches seperately decoded control from main decoder." |
| } |
| { name: "RND.BUS.CONSISTENCY", |
| desc: "Comparison on successive bus values received over the EDN RND interface." |
| } |
| { name: "RND.RNG.DIGEST", |
| desc: "Checking that the random numbers received over the EDN RND interface have not been generated from entropy that failed the FIPS health checks in the entropy source." |
| } |
| { name: "RF_BASE.DATA_REG_SW.GLITCH_DETECT" |
| desc: ''' |
| This countermeasure checks for spurious write-enable signals on the register |
| file by monitoring the one-hot0 property of the individual write-enable strobes. |
| ''' |
| } |
| { name: "STACK_WR_PTR.CTR.REDUN" |
| desc: ''' |
| The write pointer of the stack (used for calls and loops) is redundant. If the two |
| instances of the counter mismatch, an error is emitted. |
| ''' |
| } |
| { name: "STACK_WR_PTR.CTR.GLITCH_DETECT" |
| desc: "Glitches are detected on the stack counter increment / decrement control signal." |
| } |
| { name: "RF_BIGNUM.DATA_REG_SW.GLITCH_DETECT" |
| desc: ''' |
| This countermeasure checks for spurious write-enable signals on the register |
| file by monitoring the one-hot0 property of the individual write-enable strobes. |
| ''' |
| } |
| ] |
| |
| regwidth: "32" |
| registers: [ |
| // The magic values for EXECUTE, SEC_WIPE_DMEM and SEC_WIPE_IMEM in the CMD |
| // register below were generated with the sparse-fsm-encode.py script: |
| // |
| // util/design/sparse-fsm-encode.py -d 4 -m 3 -n 8 --avoid-zero -s 1 |
| // |
| // and have a hamming distance of at least 4 from one another and the zero |
| // word. |
| { name: "CMD" |
| desc: ''' |
| Command Register |
| |
| A command initiates an OTBN operation. While performing the operation, |
| OTBN is busy; the !!STATUS register reflects that. |
| |
| All operations signal their completion by raising the done |
| interrupt; alternatively, software may poll the !!STATUS register. |
| |
| Writes are ignored if OTBN is not idle. |
| Unrecognized commands are ignored. |
| ''', |
| swaccess: "wo", |
| hwaccess: "hro", |
| hwext: "true", |
| hwqe: "true", |
| fields: [ |
| { bits: "7:0" |
| name: "cmd" |
| resval: 0, |
| desc: ''' |
| The operation to perform. |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Value</th> |
| <th>Name</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>0xd8</td> |
| <td>EXECUTE</td> |
| <td> |
| Starts the execution of the program stored in the |
| instruction memory, starting at address zero. |
| </td> |
| </tr> |
| <tr> |
| <td>0xc3</td> |
| <td>SEC_WIPE_DMEM</td> |
| <td>Securely removes all contents from the data memory.</td> |
| </tr> |
| <tr> |
| <td>0x1e</td> |
| <td>SEC_WIPE_IMEM</td> |
| <td> |
| Securely removes all contents from the instruction memory. |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| ''' |
| tags: [ |
| // Don't write this field in the automated CSR tests: it would |
| // start an operation! |
| "excl:CsrAllTests:CsrExclWrite" |
| ] |
| } |
| ], |
| } |
| { name: "CTRL", |
| desc: "Control Register", |
| hwext: "true", |
| swaccess: "rw", |
| hwaccess: "hrw", |
| hwqe: "true", |
| fields: [ |
| { bits: "0", |
| name: "software_errs_fatal", |
| resval: 0, |
| desc: ''' |
| Controls the reaction to software errors. |
| |
| When set software errors produce fatal errors, rather than |
| recoverable errors. |
| |
| Writes are ignored if OTBN is not idle. |
| ''' |
| } |
| ], |
| } |
| { name: "STATUS", |
| desc: "Status Register", |
| swaccess: "ro", |
| hwaccess: "hwo", |
| fields: [ |
| { bits: "7:0", |
| name: "status", |
| resval: 0, |
| // Note: Keep the list of status codes in sync with status_e in |
| // otbn_pkg.sv. |
| desc: ''' |
| Indicates the current operational state OTBN is in. |
| |
| All BUSY values represent an operation started by a write to the |
| !!CMD register. |
| |
| <table> |
| <thead> |
| <tr> |
| <th>Value</th> |
| <th>Name</th> |
| <th>Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>0x00</td> |
| <td>IDLE</td> |
| <td>OTBN is idle: it is not performing any action.</td> |
| </tr> |
| <tr> |
| <td>0x01</td> |
| <td>BUSY_EXECUTE</td> |
| <td>OTBN is busy executing software.</td> |
| </tr> |
| <tr> |
| <td>0x02</td> |
| <td>BUSY_SEC_WIPE_DMEM</td> |
| <td>OTBN is busy securely wiping the data memory.</td> |
| </tr> |
| <tr> |
| <td>0x03</td> |
| <td>BUSY_SEC_WIPE_IMEM</td> |
| <td>OTBN is busy securely wiping the instruction memory.</td> |
| </tr> |
| <tr> |
| <td>0xFF</td> |
| <td>LOCKED</td> |
| <td> |
| OTBN is locked as reaction to a fatal error, and must be |
| reset to unlock it again. See also the the section |
| "Reaction to Fatal Errors". |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| ''' |
| tags: [ |
| // Don't write this field in the automated CSR tests. Despite this being RO for software |
| // (so you might think we couldn't write it), the csr_hw_reset test does write this by |
| // by default (using a backdoor access). The idea of that test is to write bogus values |
| // to registers, reset the block and then check that everything has its reset value. |
| // Doing this causes various assertions to fire and it isn't really necessary: we |
| // already have strong checks between this register and the output of the model. |
| "excl:CsrAllTests:CsrExclWrite" |
| ] |
| } |
| ] |
| } |
| { name: "ERR_BITS", |
| desc: ''' |
| Operation Result Register |
| |
| Describes the errors detected during an operation. |
| |
| Refer to the "List of Errors" section for a detailed description of the |
| errors. |
| |
| The host CPU can clear this register when OTBN is not running, |
| by writing any value. Write attempts while OTBN is running are ignored. |
| ''', |
| swaccess: "rw", |
| hwaccess: "hrw", |
| hwext: "true", |
| hwqe: "true", |
| tags: [ |
| // Don't use this register in the automated CSR tests. Its behaviour is |
| // "write any value to clear", which we don't model in those tests. |
| "excl:CsrAllTests:CsrExclWrite" |
| ], |
| fields: [ |
| // Software errors |
| { bits: "0", |
| name: "bad_data_addr" |
| resval: 0, |
| desc: "A `BAD_DATA_ADDR` error was observed." |
| } |
| { bits: "1", |
| name: "bad_insn_addr" |
| resval: 0, |
| desc: "A `BAD_INSN_ADDR` error was observed." |
| } |
| { bits: "2", |
| resval: 0, |
| name: "call_stack" |
| desc: "A `CALL_STACK` error was observed." |
| } |
| { bits: "3", |
| resval: 0, |
| name: "illegal_insn" |
| desc: "An `ILLEGAL_INSN` error was observed." |
| } |
| { bits: "4", |
| name: "loop" |
| resval: 0, |
| desc: "A `LOOP` error was observed." |
| } |
| { bits: "5", |
| name: "key_invalid" |
| resval: 0, |
| desc: "A `KEY_INVALID` error was observed." |
| } |
| |
| // Recoverable errors |
| { bits: "6", |
| name: "rnd_rep_chk_fail" |
| resval: 0, |
| desc: "An `RND_REP_CHK_FAIL` error was observed." |
| } |
| { bits: "7", |
| name: "rnd_fips_chk_fail" |
| resval: 0, |
| desc: "An `RND_FIPS_CHK_FAIL` error was observed." |
| } |
| |
| // Fatal errors. Keep in sync with list in FATAL_ALERT_CAUSE. |
| { bits: "16", |
| name: "imem_intg_violation" |
| resval: 0, |
| desc: "A `IMEM_INTG_VIOLATION` error was observed." |
| } |
| { bits: "17", |
| name: "dmem_intg_violation" |
| resval: 0, |
| desc: "A `DMEM_INTG_VIOLATION` error was observed." |
| } |
| { bits: "18", |
| name: "reg_intg_violation" |
| resval: 0, |
| desc: "A `REG_INTG_VIOLATION` error was observed." |
| } |
| { bits: "19", |
| name: "bus_intg_violation" |
| resval: 0, |
| desc: "A `BUS_INTG_VIOLATION` error was observed." |
| } |
| { bits: "20", |
| name: "bad_internal_state", |
| resval: 0, |
| desc: "A `BAD_INTERNAL_STATE` error was observed." |
| } |
| { bits: "21", |
| name: "illegal_bus_access" |
| resval: 0, |
| desc: "An `ILLEGAL_BUS_ACCESS` error was observed." |
| } |
| { bits: "22", |
| name: "lifecycle_escalation" |
| resval: 0, |
| desc: "A `LIFECYCLE_ESCALATION` error was observed." |
| } |
| { bits: "23", |
| name: "fatal_software" |
| resval: 0, |
| desc: "A `FATAL_SOFTWARE` error was observed." |
| } |
| ] |
| } |
| { name: "FATAL_ALERT_CAUSE", |
| desc: ''' |
| Fatal Alert Cause Register |
| |
| Describes any errors that led to a fatal alert. |
| A fatal error puts OTBN in locked state; the value of this register |
| does not change until OTBN is reset. |
| |
| Refer to the "List of Errors" section for a detailed description of the |
| errors. |
| ''' |
| swaccess: "ro", |
| hwaccess: "hwo", |
| fields: [ |
| // Keep the list in sync with the fatal errors in ERR_BITS. |
| { bits: "0", |
| name: "imem_intg_violation", |
| resval: 0, |
| desc: "A `IMEM_INTG_VIOLATION` error was observed." |
| } |
| { bits: "1", |
| name: "dmem_intg_violation", |
| resval: 0, |
| desc: "A `DMEM_INTG_VIOLATION` error was observed." |
| } |
| { bits: "2", |
| name: "reg_intg_violation", |
| resval: 0, |
| desc: "A `REG_INTG_VIOLATION` error was observed." |
| } |
| { bits: "3", |
| name: "bus_intg_violation", |
| resval: 0, |
| desc: "A `BUS_INTG_VIOLATION` error was observed." |
| } |
| { bits: "4", |
| name: "bad_internal_state", |
| resval: 0, |
| desc: "A `BAD_INTERNAL_STATE` error was observed." |
| } |
| { bits: "5", |
| name: "illegal_bus_access" |
| resval: 0, |
| desc: "A `ILLEGAL_BUS_ACCESS` error was observed." |
| } |
| { bits: "6", |
| name: "lifecycle_escalation" |
| resval: 0, |
| desc: "A `LIFECYCLE_ESCALATION` error was observed." |
| } |
| { bits: "7", |
| name: "fatal_software" |
| resval: 0, |
| desc: "A `FATAL_SOFTWARE` error was observed." |
| } |
| ] |
| } |
| { name: "INSN_CNT", |
| desc: ''' |
| Instruction Count Register |
| |
| Returns the number of instructions executed in the current or last |
| operation. The counter saturates at 2^32-1 and is reset to 0 at the |
| start of a new operation. |
| |
| Only the EXECUTE operation counts instructions; for all other operations |
| this register remains at 0. Instructions triggering an error do not |
| count towards the total. |
| |
| Always reads as 0 if OTBN is locked. |
| |
| The host CPU can clear this register when OTBN is not running, |
| by writing any value. Write attempts while OTBN is running are ignored. |
| ''', |
| swaccess: "rw", |
| hwaccess: "hrw", |
| hwext: "true", |
| hwqe: "true", |
| fields: [ |
| { bits: "31:0", |
| name: "insn_cnt", |
| resval: 0, |
| desc: ''' |
| The number of executed instructions. |
| ''' |
| tags: [ |
| // Don't write this field in the automated CSR tests. Like |
| // ERR_BITS, its behaviour is "write any value to clear", which we |
| // don't model in those tests. |
| "excl:CsrAllTests:CsrExclWrite" |
| ] |
| } |
| ] |
| } |
| { name: "LOAD_CHECKSUM", |
| desc: ''' |
| A 32-bit CRC checksum of data written to memory |
| |
| See the "Memory Load Integrity" section of the manual for full details. |
| ''' |
| hwext: "true", |
| hwqe: "true", |
| swaccess: "rw", |
| hwaccess: "hrw", |
| fields: [ |
| { bits: "31:0", |
| name: "checksum", |
| resval: 0, |
| desc: "Checksum accumulator" |
| } |
| ] |
| tags: [ |
| // Don't read this field in any of the automated CSR tests (they |
| // will predict the value wrongly because they don't know that it |
| // updates on memory writes). |
| "excl:CsrAllTests:CsrExclAll" |
| ] |
| } |
| |
| // 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", |
| data-intg-passthru: "true", |
| byte-write: "false", |
| desc: ''' |
| Instruction Memory Access |
| |
| The instruction memory may only be accessed through this window |
| while OTBN is idle. |
| |
| If OTBN is busy or locked, read accesses return 0 and write accesses |
| are ignored. |
| If OTBN is busy, any access additionally triggers an |
| ILLEGAL_BUS_ACCESS fatal error. |
| ''' |
| } |
| } |
| |
| { skipto: "0x8000" } |
| |
| // Dmem size (given as `items` below) must be a power of two. |
| { window: { |
| name: "DMEM", |
| items: "512", // 2 kB visible over the bus |
| swaccess: "rw", |
| data-intg-passthru: "true", |
| byte-write: "false", |
| desc: ''' |
| Data Memory Access |
| |
| The data memory may only be accessed through this window while OTBN |
| is idle. |
| |
| If OTBN is busy or locked, read accesses return 0 and write accesses |
| are ignored. |
| If OTBN is busy, any access additionally triggers an |
| ILLEGAL_BUS_ACCESS fatal error. |
| |
| Note that DMEM is actually 4kiB in size, but only the first 2kiB of |
| the memory is visible through this register interface. |
| ''' |
| } |
| } |
| ] |
| } |
