| // Copyright lowRISC contributors. | |
| // Licensed under the Apache License, Version 2.0, see LICENSE for details. | |
| // SPDX-License-Identifier: Apache-2.0 | |
| { | |
| name: "edn", | |
| human_name: "Entropy Distribution Network", | |
| one_line_desc: "Distributes random numbers produced by CSRNG to hardware blocks", | |
| one_paragraph_desc: ''' | |
| Entropy Distribution Network (EDN) interfaces various hardware blocks consuming random numbers to CSRNG. | |
| Besides adapting bus widths, it provides a set of registers for firmware to manage the corresponding CSRNG application interface. | |
| This allows configuring EDN to automatically send reseed and generate commands to the connected CSRNG context in order to continuously supply consumers with entropy of defined quality. | |
| Additionally, EDN supports a boot-time request mode, in which it supplies a limited amount of potentially lower-quality entropy with less firmware interaction immediately at boot-time or after reset. | |
| ''' | |
| design_spec: "../doc", | |
| dv_doc: "../doc/dv", | |
| hw_checklist: "../doc/checklist", | |
| sw_checklist: "/sw/device/lib/dif/dif_edn", | |
| version: "1.0", | |
| life_stage: "L1", | |
| design_stage: "D2S", | |
| verification_stage: "V2S", | |
| dif_stage: "S2", | |
| clocking: [{clock: "clk_i", reset: "rst_ni"}], | |
| bus_interfaces: [ | |
| { protocol: "tlul", direction: "device" } | |
| ], | |
| interrupt_list: [ | |
| { name: "edn_cmd_req_done" | |
| desc: "Asserted when a software CSRNG request has completed."} | |
| { name: "edn_fatal_err" | |
| desc: "Asserted when a FIFO error occurs."} | |
| ], | |
| alert_list: [ | |
| { name: "recov_alert", | |
| desc: "This alert is triggered when entropy bus data matches on consecutive clock cycles." | |
| } | |
| { name: "fatal_alert", | |
| desc: ''' | |
| This alert triggers (i) if an illegal state machine state is reached, or | |
| (ii) if a fatal integrity failure is detected on the TL-UL bus. | |
| ''', | |
| } | |
| ], | |
| inter_signal_list: [ | |
| { struct: "csrng", // csrng_req_t, csrng_rsp_t | |
| type: "req_rsp", | |
| name: "csrng_cmd", | |
| act: "req", | |
| width: "1", | |
| package: "csrng_pkg", | |
| desc: ''' | |
| EDN supports a signal CSRNG application interface. | |
| ''', | |
| } | |
| { struct: "edn", // edn_req_t, edn_rsp_t | |
| type: "req_rsp", | |
| name: "edn", | |
| act: "rsp", | |
| width: "8", | |
| default: "'0", | |
| desc: ''' | |
| The collection of peripheral ports supported by edn. The width (4) | |
| indicates the number of peripheral ports on a single instance. | |
| Due to limitations in the parametrization of top-level interconnects | |
| this value is not currently parameterizable. However, the number | |
| of peripheral ports may change in a future revision. | |
| ''', | |
| package: "edn_pkg", | |
| } | |
| ], | |
| countermeasures: [ | |
| { name: "CONFIG.REGWEN" | |
| desc: "Registers are protected from writes." | |
| } | |
| { name: "CONFIG.MUBI" | |
| desc: "Registers have multi-bit encoded fields." | |
| } | |
| { name: "MAIN_SM.FSM.SPARSE" | |
| desc: "The EDN main state machine uses a sparse state encoding." | |
| } | |
| { name: "ACK_SM.FSM.SPARSE" | |
| desc: "The EDN ACK state machine uses a sparse state encoding." | |
| } | |
| { name: "CTR.REDUN" | |
| desc: "Counter hardening on the generate command maximum requests counter." | |
| } | |
| { name: "MAIN_SM.CTR.LOCAL_ESC" | |
| desc: "A mismatch detected inside any EDN counter moves the main state machine into a terminal error state." | |
| } | |
| { name: "CS_RDATA.BUS.CONSISTENCY" | |
| desc: "Comparison on successive bus values for genbits returned from csrng that will distribute over the endpoint buses." | |
| } | |
| { name: "TILE_LINK.BUS.INTEGRITY" | |
| desc: "Tilelink end-to-end bus integrity scheme." | |
| } | |
| ], | |
| regwidth: "32", | |
| registers: [ | |
| { name: "REGWEN", | |
| desc: "Register write enable for all control registers", | |
| swaccess: "rw0c", | |
| hwaccess: "none", | |
| fields: [ | |
| { bits: "0", | |
| desc: ''' | |
| When true, the CTRL can be written by software. | |
| When false, this field read-only. Defaults true, write zero to clear. | |
| Note that this needs to be cleared after initial configuration at boot in order to | |
| lock in the listed register settings. | |
| ''' | |
| resval: 1 | |
| }, | |
| ] | |
| }, | |
| { name: "CTRL", | |
| desc: "EDN control register", | |
| swaccess: "rw", | |
| hwaccess: "hro", | |
| regwen: "REGWEN", | |
| tags: [// Keep HW from affecting other registers. | |
| "excl:CsrAllTests:CsrExclWrite"] | |
| fields: [ | |
| { bits: "3:0", | |
| name: "EDN_ENABLE", | |
| mubi: true, | |
| desc: ''' | |
| Setting this field to kMultiBitBool4True enables the EDN module. The modules of the | |
| entropy complex may only be enabled and disabled in a specific order, see | |
| Programmers Guide for details. | |
| ''' | |
| resval: false | |
| }, | |
| { bits: "7:4", | |
| name: "BOOT_REQ_MODE", | |
| mubi: true, | |
| desc: ''' | |
| Setting this field to kMultiBitBool4True will enable the feature where the EDN block | |
| will automatically send a boot-time request to the CSRNG application interface. | |
| The purpose of this feature is to request entropy as fast as possible after reset, | |
| and during chip boot-time. | |
| ''' | |
| resval: false | |
| }, | |
| { bits: "11:8", | |
| name: "AUTO_REQ_MODE", | |
| mubi: true, | |
| desc: ''' | |
| Setting this field to kMultiBitBool4True will enable the EDN block to automatically | |
| send another request to CSRNG application interface. It is assumed that a CSRNG | |
| instantiate command will be issued using the !!SW_CMD_REQ register interface. | |
| When this command has an command ack returned from CSRNG, a | |
| new generate command will be send out again without software intervention. It is | |
| expected that the generate command will be sent repeatedly so that a continuous | |
| supply of entropy can be delivered to the endpoints. Reseed commands will be sent | |
| on a programmable basic between generate commands. | |
| The !!GENERATE_CMD, !!RESEED_CMD, and !!MAX_NUM_REQS_BETWEEN_RESEEDS registers must | |
| set up before the !!SW_CMD_REQ register command is issued. | |
| ''' | |
| resval: false | |
| }, | |
| { bits: "15:12", | |
| name: "CMD_FIFO_RST", | |
| mubi: true, | |
| desc: ''' | |
| Setting this field to kMultiBitBool4True clears the two command FIFOs: the | |
| RESEED_CMD FIFO and the GENERATE_CMD FIFO. This field must be | |
| set to the reset state by software before any further commands can be issued to | |
| these FIFOs. | |
| ''' | |
| resval: false | |
| }, | |
| ] | |
| }, | |
| { name: "BOOT_INS_CMD", | |
| desc: "EDN boot instantiate command register", | |
| swaccess: "rw", | |
| hwaccess: "hro", | |
| tags: [// Keep HW from affecting other registers. | |
| "excl:CsrAllTests:CsrExclWrite"] | |
| fields: [ | |
| { bits: "31:0", | |
| name: "BOOT_INS_CMD", | |
| desc: ''' | |
| This field is used as the value for Instantiate command at boot time. | |
| ''' | |
| resval: 0x0000_0901 | |
| } | |
| ] | |
| }, | |
| { name: "BOOT_GEN_CMD", | |
| desc: "EDN boot generate command register", | |
| swaccess: "rw", | |
| hwaccess: "hro", | |
| tags: [// Keep HW from affecting other registers. | |
| "excl:CsrAllTests:CsrExclWrite"] | |
| fields: [ | |
| { bits: "31:0", | |
| name: "BOOT_GEN_CMD", | |
| desc: ''' | |
| This field is used as the value for generate command at boot time. | |
| ''' | |
| resval: 0x00ff_f003 | |
| } | |
| ] | |
| }, | |
| { name: "SW_CMD_REQ", | |
| desc: "EDN csrng app command request register", | |
| swaccess: "wo", | |
| hwaccess: "hro", | |
| hwext: "true", | |
| hwqe: "true", | |
| fields: [ | |
| { bits: "31:0", | |
| name: "SW_CMD_REQ", | |
| desc: ''' | |
| Any CSRNG action can be initiated by writing a CSRNG command to this | |
| register. The application interface must wait for the "ack" to | |
| return before issuing new commands. This interface is intended | |
| to be controlled solely by software. | |
| If !!CTRL.AUTO_REQ_MODE is set, only the first instantiate command has any | |
| effect. After that command has been processed, writes to this register | |
| register will have no effect on operation. | |
| Note that CSRNG command format details can be found | |
| in the CSRNG documentation. | |
| ''' | |
| } | |
| ] | |
| }, | |
| { name: "SW_CMD_STS", | |
| desc: "EDN command status register", | |
| swaccess: "ro", | |
| hwaccess: "hwo", | |
| tags: [// Internal HW can modify status register | |
| "excl:CsrNonInitTests:CsrExclCheck"] | |
| fields: [ | |
| { bits: "0", | |
| name: "CMD_RDY", | |
| desc: ''' | |
| This bit indicates when the command interface is ready to accept commands. | |
| ''' | |
| resval: "0" | |
| } | |
| { bits: "1", | |
| name: "CMD_STS", | |
| desc: ''' | |
| This one bit field is the status code returned with the application command ack. | |
| It is updated each time a command ack is asserted on the CSRNG interface. | |
| 0b0: Request completed successfully | |
| 0b1: Request completed with an error | |
| ''' | |
| resval: "0" | |
| } | |
| ] | |
| }, | |
| { name: "RESEED_CMD", | |
| desc: "EDN csrng reseed command register", | |
| swaccess: "wo", | |
| hwaccess: "hro", | |
| hwext: "true", | |
| hwqe: "true", | |
| fields: [ | |
| { bits: "31:0", | |
| name: "RESEED_CMD", | |
| desc: ''' | |
| Writing this register will fill a FIFO with up to 13 command words (32b words). | |
| This FIFO will be used to automatically send out a reseed command to the CSRNG | |
| application interface when in !!CTRL.AUTO_REQ_MODE. This command will be sent only after | |
| the MAX_NUM_REQS_BETWEEN_RESEEDS counter value has reached zero. | |
| If more than 13 entires are written to the FIFO, the design will automatically generate | |
| a fatal alert. | |
| Note that CSRNG command format details can be found | |
| in the CSRNG documentation. | |
| ''' | |
| } | |
| ] | |
| }, | |
| { name: "GENERATE_CMD", | |
| desc: "EDN csrng generate command register", | |
| swaccess: "wo", | |
| hwaccess: "hro", | |
| hwext: "true", | |
| hwqe: "true", | |
| fields: [ | |
| { bits: "31:0", | |
| name: "GENERATE_CMD", | |
| desc: ''' | |
| Writing this register will fill a FIFO with up to 13 command words (32b words). | |
| This FIFO will be used to automatically send out a generate command to the CSRNG | |
| appl interface when in !!CTRL.AUTO_REQ_MODE. This command will be sent only after | |
| receiving a command ack from the previous command. | |
| If more than 13 entires are written to the FIFO, the design will automatically generate | |
| a fatal alert. | |
| Note that CSRNG command format details can be found | |
| in the CSRNG documentation. | |
| ''' | |
| } | |
| ] | |
| }, | |
| { name: "MAX_NUM_REQS_BETWEEN_RESEEDS", | |
| desc: "EDN maximum number of requests between reseeds register", | |
| swaccess: "rw", | |
| hwaccess: "hro", | |
| hwqe: "true", | |
| fields: [ | |
| { bits: "31:0", | |
| name: "MAX_NUM_REQS_BETWEEN_RESEEDS", | |
| desc: ''' | |
| Setting this field will set the number of generate requests that can be made | |
| to CSRNG before a reseed request is made. This value only has meaning when in | |
| !!CTRL.AUTO_REQ_MODE. This register supports a maximum of 2^32 requests between reseeds. | |
| This register will be used by a counter that counts down, triggering an | |
| automatic reseed when it reaches zero. | |
| ''' | |
| } | |
| ] | |
| }, | |
| { | |
| name: "RECOV_ALERT_STS", | |
| desc: "Recoverable alert status register", | |
| swaccess: "rw0c", | |
| hwaccess: "hwo", | |
| tags: [ // The internal HW can modify the error code registers | |
| "excl:CsrAllTests:CsrExclCheck"] | |
| fields: [ | |
| { bits: "0", | |
| name: "EDN_ENABLE_FIELD_ALERT", | |
| desc: ''' | |
| This bit is set when the EDN_ENABLE field is set to an illegal value, | |
| something other than kMultiBitBool4True or kMultiBitBool4False. | |
| Writing a zero resets this status bit. | |
| ''' | |
| } | |
| { bits: "1", | |
| name: "BOOT_REQ_MODE_FIELD_ALERT", | |
| desc: ''' | |
| This bit is set when the BOOT_REQ_MODE field is set to an illegal value, | |
| something other than kMultiBitBool4True or kMultiBitBool4False. | |
| Writing a zero resets this status bit. | |
| ''' | |
| } | |
| { bits: "2", | |
| name: "AUTO_REQ_MODE_FIELD_ALERT", | |
| desc: ''' | |
| This bit is set when the !!CTRL.AUTO_REQ_MODE field is set to an illegal value, | |
| something other than kMultiBitBool4True or kMultiBitBool4False. | |
| Writing a zero resets this status bit. | |
| ''' | |
| } | |
| { bits: "3", | |
| name: "CMD_FIFO_RST_FIELD_ALERT", | |
| desc: ''' | |
| This bit is set when the CMD_FIFO_RST field is set to an illegal value, | |
| something other than kMultiBitBool4True or kMultiBitBool4False. | |
| Writing a zero resets this status bit. | |
| ''' | |
| } | |
| { bits: "12", | |
| name: "EDN_BUS_CMP_ALERT", | |
| desc: ''' | |
| This bit is set when the interal entropy bus value is equal to the prior | |
| valid value on the bus, indicating a possible attack. | |
| Writing a zero resets this status bit. | |
| ''' | |
| } | |
| ] | |
| }, | |
| { | |
| name: "ERR_CODE", | |
| desc: "Hardware detection of fatal error conditions status register", | |
| swaccess: "ro", | |
| hwaccess: "hwo", | |
| fields: [ | |
| { bits: "0", | |
| name: "SFIFO_RESCMD_ERR", | |
| desc: ''' | |
| This bit will be set to one when an error has been detected for the | |
| reseed command FIFO. The type of error is reflected in the type status | |
| bits (bits 28 through 30 of this register). | |
| When this bit is set, a fatal error condition will result. | |
| ''' | |
| } | |
| { bits: "1", | |
| name: "SFIFO_GENCMD_ERR", | |
| desc: ''' | |
| This bit will be set to one when an error has been detected for the | |
| generate command FIFO. The type of error is reflected in the type status | |
| bits (bits 28 through 30 of this register). | |
| When this bit is set, a fatal error condition will result. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| { bits: "2", | |
| name: "SFIFO_OUTPUT_ERR", | |
| desc: ''' | |
| This bit will be set to one when an error has been detected for the | |
| output FIFO. The type of error is reflected in the type status | |
| bits (bits 28 through 30 of this register). | |
| When this bit is set, a fatal error condition will result. | |
| ''' | |
| } | |
| { bits: "20", | |
| name: "EDN_ACK_SM_ERR", | |
| desc: ''' | |
| This bit will be set to one when an illegal state has been detected for the | |
| EDN ack stage state machine. This error will signal a fatal alert. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| { bits: "21", | |
| name: "EDN_MAIN_SM_ERR", | |
| desc: ''' | |
| This bit will be set to one when an illegal state has been detected for the | |
| EDN main stage state machine. This error will signal a fatal alert. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| { bits: "22", | |
| name: "EDN_CNTR_ERR", | |
| desc: ''' | |
| This bit will be set to one when a hardened counter has detected an error | |
| condition. This error will signal a fatal alert. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| { bits: "28", | |
| name: "FIFO_WRITE_ERR", | |
| desc: ''' | |
| This bit will be set to one when any of the source bits (bits 0 through 1 of this | |
| this register) are asserted as a result of an error pulse generated from | |
| any full FIFO that has been recieved a write pulse. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| { bits: "29", | |
| name: "FIFO_READ_ERR", | |
| desc: ''' | |
| This bit will be set to one when any of the source bits (bits 0 through 1 of this | |
| this register) are asserted as a result of an error pulse generated from | |
| any empty FIFO that has recieved a read pulse. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| { bits: "30", | |
| name: "FIFO_STATE_ERR", | |
| desc: ''' | |
| This bit will be set to one when any of the source bits (bits 0 through 1 of this | |
| this register) are asserted as a result of an error pulse generated from | |
| any FIFO where both the empty and full status bits are set. | |
| This bit will stay set until the next reset. | |
| ''' | |
| } | |
| ] | |
| }, | |
| { name: "ERR_CODE_TEST", | |
| desc: "Test error conditions register", | |
| swaccess: "rw", | |
| hwaccess: "hro", | |
| hwqe: "true", | |
| tags: [// Keep HW from affecting other registers. | |
| "excl:CsrAllTests:CsrExclWrite"] | |
| fields: [ | |
| { | |
| bits: "4:0", | |
| name: "ERR_CODE_TEST", | |
| desc: ''' | |
| Setting this field will set the bit number for which an error | |
| will be forced in the hardware. This bit number is that same one | |
| found in the !!ERR_CODE register. The action of writing this | |
| register will force an error pulse. The sole purpose of this | |
| register is to test that any error properly propagates to either | |
| an interrupt or an alert. | |
| ''' | |
| }, | |
| ] | |
| }, | |
| { name: "MAIN_SM_STATE", | |
| desc: "Main state machine state debug register", | |
| swaccess: "ro", | |
| hwaccess: "hwo", | |
| fields: [ | |
| { bits: "8:0", | |
| name: "MAIN_SM_STATE", | |
| desc: '''This is the state of the EDN main state machine. | |
| See the RTL file `edn_main_sm` for the meaning of the values. | |
| ''' | |
| resval: 0x185 | |
| } | |
| ] | |
| }, | |
| ] | |
| } |