✨🔒 add optional on-chip debugger authentication (#1053)

CHANGELOG.md

@@ -29,6 +29,7 @@ mimpid = 0x01040312 -> Version 01.04.03.12 -> v1.4.3.12
 
 | Date | Version | Comment | Ticket |
 |:----:|:-------:|:--------|:------:|
+| 11.10.2024 | 1.10.5.5 | :sparkles: :lock: add optional support for on-chip debugger authentication; :warning: rename OCD-related top generics | [#](https://github.com/stnolting/neorv32/pull/1053) |
 | 06.10.2024 | 1.10.5.4 | :warning: rework PWM module | [#1049](https://github.com/stnolting/neorv32/pull/1049) |
 | 05.10.2024 | 1.10.5.3 | upgrade neoTRNG to version 3.2 | [#1048](https://github.com/stnolting/neorv32/pull/1048) |
 | 03.10.2024 | 1.10.5.2 | :warning: remove `A` ISA extensions; replaced by new `Zalrsc` ISA extension | [#1047](https://github.com/stnolting/neorv32/pull/1047) |

README.md

@@ -198,6 +198,7 @@ data integrity (CRC8/16/32)
 * compatible to the "Minimal RISC-V Debug Specification Version 1.0"
 * compatible with **OpenOCD**, **GDB** and **Segger Embedded Studio**
 * RISC-V [trigger module](https://stnolting.github.io/neorv32/#_trigger_module) for hardware-assisted breakpoints
+* optional authentication module to implement custom security mechanisms
 
 
 ## 3. FPGA Implementation Results

docs/datasheet/cpu.adoc

@@ -455,8 +455,8 @@ This chapter gives a brief overview of all available ISA extensions.
 | <<_zmmul_isa_extension,`Zmmul`>>       | Integer multiplication-only instructions                      | <<_processor_top_entity_generics, `RISCV_ISA_Zmmul`>>
 | <<_zxcfu_isa_extension,`Zcfu`>>        | Custom / user-defined instructions                            | <<_processor_top_entity_generics, `RISCV_ISA_Zxcfu`>>
 | <<_smpmp_isa_extension,`Smpmp`>>       | Physical memory protection (PMP) extension                    | <<_processor_top_entity_generics, `RISCV_ISA_Smpmp`>>
-| <<_sdext_isa_extension,`Sdext`>>       | External debug support extension                              | <<_processor_top_entity_generics, `ON_CHIP_DEBUGGER_EN`>>
-| <<_sdtrig_isa_extension,`Sdtrig`>>     | Trigger module extension                                      | <<_processor_top_entity_generics, `ON_CHIP_DEBUGGER_EN`>>
+| <<_sdext_isa_extension,`Sdext`>>       | External debug support extension                              | <<_processor_top_entity_generics, `OCD_EN`>>
+| <<_sdtrig_isa_extension,`Sdtrig`>>     | Trigger module extension                                      | <<_processor_top_entity_generics, `OCD_EN`>>
 |=======================
 
 .RISC-V ISA Specification

docs/datasheet/overview.adoc

@@ -94,7 +94,7 @@ include::rationale.adoc[]
 * optional execute in-place (XIP) module to execute code directly form an external SPI flash
 * optional DMA controller for CPU-independent data transfers
 * optional CRC module to check data integrity
-* on-chip debugger compatible with OpenOCD and gdb including hardware trigger module
+* on-chip debugger compatible with OpenOCD and GDB including hardware trigger module and optional authentication
 
 **Software framework**
 
@@ -206,6 +206,7 @@ neorv32_top.vhd                 - NEORV32 PROCESSOR/SOC TOP ENTITY
 ├neorv32_clockgate.vhd          - Generic clock gating switch
 ├neorv32_crc.vhd                - Cyclic redundancy check unit
 ├neorv32_debug_dm.vhd           - on-chip debugger: debug module
+├neorv32_debug_auth.vhd         - on-chip debugger: authentication module
 ├neorv32_debug_dtm.vhd          - on-chip debugger: debug transfer module
 ├neorv32_dma.vhd                - Direct memory access controller
 ├neorv32_dmem.vhd               - Generic processor-internal data memory

docs/datasheet/soc.adoc

@@ -209,8 +209,9 @@ The generic type "`suv(x:y)`" is an abbreviation for "`std_ulogic_vector(x downt
 | `HART_ID`               | suv(31:0) | 0x00000000    | The hart thread ID of the CPU (passed to <<_mhartid>> CSR).
 | `JEDEC_ID`              | suv(10:0) | 0b00000000000 | JEDEC ID; continuation codes plus vendor ID (passed to <<_mvendorid>> CSR and to the <<_debug_transport_module_dtm>>).
 4+^| **<<_on_chip_debugger_ocd>>**
-| `ON_CHIP_DEBUGGER_EN`   | boolean   | false         | Implement the on-chip debugger and the CPU debug mode.
-| `DM_LEGACY_MODE`        | boolean   | false         | Debug module spec. version: `false` = v1.0, `true` = v0.13 (legacy mode).
+| `OCD_EN`                | boolean   | false         | Implement the on-chip debugger and the CPU debug mode.
+| `OCD_DM_LEGACY_MODE`    | boolean   | false         | Debug module spec. version: `false` = v1.0, `true` = v0.13 (legacy mode).
+| `OCD_AUTHENTICATION`    | boolean   | false         | Implement <<_debug_authentication>> module.
 4+^| **CPU <<_instruction_sets_and_extensions>>**
 | `RISCV_ISA_C`           | boolean   | false         | Enable <<_c_isa_extension>> (compressed instructions).
 | `RISCV_ISA_E`           | boolean   | false         | Enable <<_e_isa_extension>> (reduced register file size).

docs/datasheet/soc_sysinfo.adoc

@@ -77,14 +77,15 @@ Bit fields in this register are set to all-zero if the according memory system i
 | `1`     | `SYSINFO_SOC_XBUS`           | set if external Wishbone bus interface is implemented (via top's `XBUS_EN` generic)
 | `2`     | `SYSINFO_SOC_MEM_INT_IMEM`   | set if processor-internal DMEM implemented (via top's `MEM_INT_DMEM_EN` generic)
 | `3`     | `SYSINFO_SOC_MEM_INT_DMEM`   | set if processor-internal IMEM is implemented (via top's `MEM_INT_IMEM_EN` generic)
-| `4`     | `SYSINFO_SOC_OCD`            | set if on-chip debugger is implemented (via top's `ON_CHIP_DEBUGGER_EN` generic)
+| `4`     | `SYSINFO_SOC_OCD`            | set if on-chip debugger is implemented (via top's `OCD_EN` generic)
 | `5`     | `SYSINFO_SOC_ICACHE`         | set if processor-internal instruction cache is implemented (via top's `ICACHE_EN` generic)
 | `6`     | `SYSINFO_SOC_DCACHE`         | set if processor-internal data cache is implemented (via top's `DCACHE_EN` generic)
 | `7`     | `SYSINFO_SOC_CLOCK_GATING`   | set if CPU clock gating is implemented (via top's `CLOCK_GATING_EN` generic)
 | `8`     | `SYSINFO_SOC_XBUS_CACHE`     | set if external bus interface cache is implemented (via top's `XBUS_CACHE_EN` generic)
 | `9`     | `SYSINFO_SOC_XIP`            | set if XIP module is implemented (via top's `XIP_EN` generic)
 | `10`    | `SYSINFO_SOC_XIP_CACHE`      | set if XIP cache is implemented (via top's `XIP_CACHE_EN` generic)
-| `13:11` | -                            | _reserved_, read as zero
+| `11`    | `SYSINFO_SOC_OCD_AUTH`       | set if on-chip debugger authentication is implemented (via top's `OCD_AUTHENTICATION` generic)
+| `13:12` | -                            | _reserved_, read as zero
 | `14`    | `SYSINFO_SOC_IO_DMA`         | set if direct memory access controller is implemented (via top's `IO_DMA_EN` generic)
 | `15`    | `SYSINFO_SOC_IO_GPIO`        | set if GPIO is implemented (via top's `IO_GPIO_EN` generic)
 | `16`    | `SYSINFO_SOC_IO_MTIME`       | set if MTIME is implemented (via top's `IO_MTIME_EN` generic)

rtl/core/neorv32_debug_auth.vhd

@@ -0,0 +1,75 @@
+-- ================================================================================ --
+-- NEORV32 SoC - RISC-V-Compatible Authentication Module for the On-Chip Debugger   --
+-- -------------------------------------------------------------------------------- --
+-- Note that this module (in its default state) just provides a very simple and     --
+-- UNSECUR authentication mechanism that is meant as an example to showcase the     --
+-- interface. Users should replace this module to implement a custom authentication --
+-- (and SECURE) mechanism.                                                          --
+-- -------------------------------------------------------------------------------- --
+-- The NEORV32 RISC-V Processor - https://github.com/stnolting/neorv32              --
+-- Copyright (c) NEORV32 contributors.                                              --
+-- Copyright (c) 2020 - 2024 Stephan Nolting. All rights reserved.                  --
+-- Licensed under the BSD-3-Clause license, see LICENSE for details.                --
+-- SPDX-License-Identifier: BSD-3-Clause                                            --
+-- ================================================================================ --
+
+library ieee;
+use ieee.std_logic_1164.all;
+
+library neorv32;
+use neorv32.neorv32_package.all;
+
+entity neorv32_debug_auth is
+  port (
+    -- global control --
+    clk_i    : in  std_ulogic; -- global clock
+    rstn_i   : in  std_ulogic; -- global reset, low-active, asynchronous
+    -- register interface --
+    we_i     : in  std_ulogic; -- write data when high
+    re_i     : in  std_ulogic; -- read data has been consumed by the debugger when high
+    wdata_i  : in  std_ulogic_vector(31 downto 0); -- write data (from debugger)
+    rdata_o  : out std_ulogic_vector(31 downto 0); -- read data (to debugger)
+    -- status --
+    enable_i : in  std_ulogic; -- authenticator enabled when high; reset & clear authentication when low
+    busy_o   : out std_ulogic; -- authenticator is busy when high; no further read/write accesses
+    valid_o  : out std_ulogic  -- high when authentication passed; unlocks the on-chip debugger
+  );
+end neorv32_debug_auth;
+
+architecture neorv32_debug_auth_rtl of neorv32_debug_auth is
+
+  signal authenticated : std_ulogic;
+
+begin
+
+  -- Warn about Default Authenticator -------------------------------------------------------
+  -- -------------------------------------------------------------------------------------------
+  assert false report "[NEORV32] OCD: using DEFAULT authenticator. Replace by custom module." severity warning;
+
+
+  -- Exemplary Authentication Mechanism -----------------------------------------------------
+  -- -------------------------------------------------------------------------------------------
+  dm_controller: process(rstn_i, clk_i)
+  begin
+    if (rstn_i = '0') then
+      authenticated <= '0';
+    elsif rising_edge(clk_i) then
+      if (enable_i = '0') then
+        authenticated <= '0'; -- clear authentication when disabled
+      elsif (we_i = '1') then
+        authenticated <= wdata_i(0); -- just write a 1 to authenticate
+      end if;
+    end if;
+  end process dm_controller;
+
+  -- authenticator busy --
+  busy_o <= '0'; -- this simple authenticator is always ready
+
+  -- authentication passed --
+  valid_o <= authenticated;
+
+  -- read data --
+  rdata_o <= (others => '0'); -- there is nothing to read here
+
+
+end neorv32_debug_auth_rtl;