From c9f22c79dfecf61a7160a324a8b9f4fce695c67c Mon Sep 17 00:00:00 2001 From: Antonio Borneo Date: Sat, 3 Feb 2024 19:25:21 +0100 Subject: [PATCH] doc: document 'target create' flags '-dbgbase' and '-coreid' Add to the command 'target create' the description for the flags '-dbgbase' and '-coreid'. Report that '-coreid' is currently used for purposes other than CPU detection/examination, and that such uses are going to be re-considered. Change-Id: I25c839e3653101234c5862ce9da77019a5bb3249 Signed-off-by: Antonio Borneo Reviewed-on: https://review.openocd.org/c/openocd/+/8129 Reviewed-by: Tomas Vanek Tested-by: jenkins --- doc/openocd.texi | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/doc/openocd.texi b/doc/openocd.texi index e46e6004b..667c7a693 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -5161,6 +5161,38 @@ On ADIv6 DAP @var{ap_number} is the base address of the DAP AP the target is con Use this option with systems where multiple, independent cores are connected to separate access ports of the same DAP. +@item @code{-dbgbase} @var{dbg_base_address} -- set the base address of the +debug controller. +This is ignored and not required for target types that have the debug controller +at fixed addresses, like @code{cortex_m}. +On DAP based SoC, OpenOCD can parse the ROM table in the DAP access port to +identify the base address of the debug controller, but the parsing can be slow +on devices with big ROM tables. +While using @code{-dbgbase} is suggested to speed up the target examination, +it is often the only viable solution for devices with incorrect ROM table +content or with ROM table partially not accessible due to clock gating or +power management. + +@item @code{-coreid} @var{coreid} -- set an index to identify the CPU or its +debug controller. + +@itemize @minus +@item When @code{-dbgbase} option is not provided on devices with multiple +CPUs on the same DAP access port +(e.g. @code{cortex_a}, @code{cortex_r4}, @code{aarch64} and @code{armv8r}), +this option specifies that the ROM table parsing should select the CPU in +position @var{coreid}. + +@item On target type @code{riscv}, @var{coreid} specifies the hart +(HARdware Threads) on the DM (Debug Module). It is used on multi-hart +devices to index a specific hart ID. +When not present, it's default value is zero. + +@item This value @var{coreid} is currently also used in other contexts as a +general CPU index, e.g. in SMP nodes or to select a specific CPU in a chip. +To avoid confusion, these additional use cases are going to be dropped. +@end itemize + @item @code{-cti} @var{cti_name} -- set Cross-Trigger Interface (CTI) connected to the target. Currently, only the @code{aarch64} target makes use of this option, where it is a mandatory configuration for the target run control.