gdb_server: add per target option "-gdb-port"

[openocd] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 43ebf8cb28a8b0658b646b354ea1ca3922928f9b..3eb6309027a4f1ce3e4eb610f8749e731e3cd4c4 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2114,6 +2114,7 @@ In such cases, just specify the relevant port number as "disabled".
 If you disable all access through TCP/IP, you will need to
 use the command line @option{-pipe} option.
 
+@anchor{gdb_port}
 @deffn {Command} gdb_port [number]
 @cindex GDB server
 Normally gdb listens to a TCP/IP port, but GDB can also
@@ -2139,11 +2140,15 @@ The GDB port for the first target will be the base port, the
 second target will listen on gdb_port + 1, and so on.
 When not specified during the configuration stage,
 the port @var{number} defaults to 3333.
+When @var{number} is not a numeric value, incrementing it to compute
+the next port number does not work. In this case, specify the proper
+@var{number} for each target by using the option @code{-gdb-port} of the
+commands @command{target create} or @command{$target_name configure}.
+@xref{gdbportoverride,,option -gdb-port}.
 
 Note: when using "gdb_port pipe", increasing the default remote timeout in
 gdb (with 'set remotetimeout') is recommended. An insufficient timeout may
 cause initialization to fail with "Unknown remote qXfer reply: OK".
-
 @end deffn
 
 @deffn {Command} tcl_port [number]
@@ -4087,6 +4092,18 @@ or set a new value @var{value}.
 Select AP @var{num}, defaulting to 0.
 @end deffn
 
+@deffn Command {$dap_name dpreg} reg [value]
+Displays the content of DP register at address @var{reg}, or set it to a new
+value @var{value}.
+
+In case of SWD, @var{reg} is a value in packed format
+@math{dpbanksel << 4 | addr} and assumes values 0, 4, 8 ... 0xfc.
+In case of JTAG it only assumes values 0, 4, 8 and 0xc.
+
+@emph{Note:} Consider using @command{poll off} to avoid any disturbing
+background activity by OpenOCD while you are operating at such low-level.
+@end deffn
+
 @deffn Command {$dap_name baseaddr} [num]
 Displays debug base address from MEM-AP @var{num},
 defaulting to the currently selected AP.
@@ -4429,7 +4446,7 @@ The value should normally correspond to a static mapping for the
 @item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
 @var{rtos_type} can be one of @option{auto}, @option{eCos},
 @option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
-@option{embKernel}, @option{mqx}, @option{uCOS-III}
+@option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx}
 @xref{gdbrtossupport,,RTOS Support}.
 
 @item @code{-defer-examine} -- skip target examination at initial JTAG chain
@@ -4446,6 +4463,13 @@ to the target. Currently, only the @code{aarch64} target makes use of this optio
 where it is a mandatory configuration for the target run control.
 @xref{armcrosstrigger,,ARM Cross-Trigger Interface},
 for instruction on how to declare and control a CTI instance.
+
+@anchor{gdbportoverride}
+@item @code{-gdb-port} @var{number} -- see command @command{gdb_port} for the
+possible values of the parameter @var{number}, which are not only numeric values.
+Use this option to override, for this target only, the global parameter set with
+command @command{gdb_port}.
+@xref{gdb_port,,command gdb_port}.
 @end itemize
 @end deffn
 
@@ -7390,6 +7414,19 @@ Useful in connection with script files
 Close the OpenOCD server, disconnecting all clients (GDB, telnet,
 other). If option @option{error} is used, OpenOCD will return a
 non-zero exit code to the parent process.
+
+Like any TCL commands, also @command{shutdown} can be redefined, e.g.:
+@example
+# redefine shutdown
+rename shutdown original_shutdown
+proc shutdown @{@} @{
+    puts "This is my implementation of shutdown"
+    # my own stuff before exit OpenOCD
+    original_shutdown
+@}
+@end example
+If user types CTRL-C or kills OpenOCD, either the command @command{shutdown}
+or its replacement will be automatically executed before OpenOCD exits.
 @end deffn
 
 @anchor{debuglevel}
@@ -8775,8 +8812,8 @@ Enable or disable trace output for all ITM stimulus ports.
 @deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off})
 Control masking (disabling) interrupts during target step/resume.
 
-The @option{auto} option handles interrupts during stepping a way they get
-served but don't disturb the program flow. The step command first allows
+The @option{auto} option handles interrupts during stepping in a way that they
+get served but don't disturb the program flow. The step command first allows
 pending interrupt handlers to execute, then disables interrupts and steps over
 the next instruction where the core was halted. After the step interrupts
 are enabled again. If the interrupt handlers don't complete within 500ms,
@@ -9781,6 +9818,7 @@ Currently supported rtos's include:
 @item @option{embKernel}
 @item @option{mqx}
 @item @option{uCOS-III}
+@item @option{nuttx}
 @end itemize
 
 @quotation Note
@@ -9816,6 +9854,8 @@ Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount.
 _mqx_kernel_data, MQX_init_struct.
 @item uC/OS-III symbols
 OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
+@item nuttx symbols
+g_readytorun, g_tasklisttable
 @end table
 
 For most RTOS supported the above symbols will be exported by default. However for