diff --git a/docs/datasheet/on_chip_debugger.adoc b/docs/datasheet/on_chip_debugger.adoc index 40b8b5a27..bd2def5e1 100644 --- a/docs/datasheet/on_chip_debugger.adoc +++ b/docs/datasheet/on_chip_debugger.adoc @@ -16,7 +16,7 @@ to `true`. * execution of arbitrary programs via the program buffer * compatible with upstream OpenOCD and GDB * optional trigger module for hardware breakpoints -* optional authentication for increased security +* optional authentication for advanced security .Hands-On Tutorial [TIP] @@ -58,6 +58,31 @@ or resume the halted application. Furthermore, the CPU uses this register to sig request or to signal that an exception has been raised while being in debug mode. +<<< +// #################################################################################################################### +:sectnums: +=== openOCD + +By default, the free and open-source openOCD (https://openocd.org/) is used to establish a debugger connection. +However, other interfaces can be used (like Segger or Lauterbach tools) if they support the RISC-V debug specification. + +openOCD is configured by single configuration script. Currently, two scripts are provided - one for the single-core +processor configuration and another one for the SMP dual-core configuration: + +* `neorv32/sw/openocd/openocd_neorv32.cfg`: openOCD script for the single-core configuration +* `neorv32/sw/openocd/openocd_neorv32.dual-core.cfg`: openOCD script for the dual-core configuration + +Both scripts include several helper scripts (located in the same folder) that are used to hide some complexity. +Two of these scripts may be modified to adjust openOCD for the actual setup: + +* `interface.cfg`: physical JTAG adapter configuration; by default this is configured +for a simple FTDI USB converter; **adjust this for your specific JTAG adapter**. +* `authentication.cfg`: optional authentication process; the +<<_default_authentication_mechanism>> is implemented as example; **adjust this when using a custom authentication +mechanism**. +* `target.cfg`: main NEORV32 target configuration; end users should not alter this file. + + <<< // #################################################################################################################### :sectnums: @@ -603,14 +628,23 @@ The default authentication mechanism is not secure at all. Replace it by a custo The default authenticator hardware implements a very simple authentication mechanism: a single read/write bit is implemented that directly corresponds to the `authenticated` bit in <<_dmstatus>>. This bit can be read/written as bit zero (LSB) of the -<<_authdata>> CSR. Writing 1 to this register will result in a successful authentication. The default openOCD configuration -script for the NEORV32 implements this basic authentication mechanism: +<<_authdata>> CSR. Writing 1 to this register will result in a successful authentication. + +The default openOCD configuration script provides a helper script for authentication. This script also provides +several helper functions for interaction with the RISC-V debug mechanism. Additionally, the default authentication +mechanism is implemented there (as example): -.Default authentication process (`sw/openocd/openocd_neorv32.cfg`) +.Default authentication process (`sw/openocd/authentication.cfg`) [source,tcl] ---- -set challenge [riscv authdata_read] # read authdata; not required, just an example -riscv authdata_write [expr {$challenge | 1}] # set LSB to authenticate +# read challenge +set CHALLENGE [authenticator_read] +# compute response (default authenticator module) +set RESPONSE [expr {$CHALLENGE | 1}] +# send response +authenticator_write $RESPONSE +# success? +authenticator_check ----