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
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]
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.
@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
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
@end example
@end deffn
+@deffn {Flash Driver} msp432
+All versions of the SimpleLink MSP432 microcontrollers from Texas
+Instruments include internal flash. The msp432 flash driver automatically
+recognizes the specific version's flash parameters and autoconfigures itself.
+Main program flash (starting at address 0) is flash bank 0. Information flash
+region on MSP432P4 versions (starting at address 0x200000) is flash bank 1.
+
+@example
+flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {msp432 mass_erase} [main|all]
+Performs a complete erase of flash. By default, @command{mass_erase} will erase
+only the main program flash.
+
+On MSP432P4 versions, using @command{mass_erase all} will erase both the
+main program and information flash regions. To also erase the BSL in information
+flash, the user must first use the @command{bsl} command.
+@end deffn
+
+@deffn Command {msp432 bsl} [unlock|lock]
+On MSP432P4 versions, @command{bsl} unlocks and locks the bootstrap loader (BSL)
+region in information flash so that flash commands can erase or write the BSL.
+Leave the BSL locked to prevent accidentally corrupting the bootstrap loader.
+
+To erase and program the BSL:
+@example
+msp432 bsl unlock
+flash erase_address 0x202000 0x2000
+flash write_image bsl.bin 0x202000
+msp432 bsl lock
+@end example
+@end deffn
+@end deffn
+
@deffn {Flash Driver} niietcm4
This drivers handles the integrated NOR flash on NIIET Cortex-M4
based controllers. Flash size and sector layout are auto-configured by the driver.
Mass erases the entire stm32l4x device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+
+@deffn Command {stm32l4x option_read} num reg_offset
+Reads an option byte register from the stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the Option byte to read.
+
+For example to read the FLASH_OPTR register:
+@example
+stm32l4x option_read 0 0x20
+# Option Register: <0x40022020> = 0xffeff8aa
+@end example
+
+The above example will read out the FLASH_OPTR register which contains the RDP
+option byte, Watchdog configuration, BOR level etc.
+@end deffn
+
+@deffn Command {stm32l4x option_write} num reg_offset reg_mask
+Write an option byte register of the stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the Option byte to write, and @var{reg_mask} is the mask
+to apply when writing the register (only bits with a '1' will be touched).
+
+For example to write the WRP1AR option bytes:
+@example
+stm32l4x option_write 0 0x28 0x00FF0000 0x00FF00FF
+@end example
+
+The above example will write the WRP1AR option register configuring the Write protection
+Area A for bank 1. The above example set WRP1AR_END=255, WRP1AR_START=0.
+This will effectively write protect all sectors in flash bank 1.
+@end deffn
+
+@deffn Command {stm32l4x option_load} num
+Forces a re-load of the option byte registers. Will cause a reset of the device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
@end deffn
@deffn {Flash Driver} str7x
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}
@item @code{itmdump -f /dev/ttyUSB1 -d1}
@item OpenOCD invocation line:
@example
-openocd -f interface/stlink-v2-1.cfg \
+openocd -f interface/stlink.cfg \
-c "transport select hla_swd" \
-f target/stm32l1.cfg \
-c "tpiu config external uart off 24000000 12000000"
@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,
"timer" or any new group created with addreg command.
@end deffn
+@section RISC-V Architecture
+
+@uref{http://riscv.org/, RISC-V} is a free and open ISA. OpenOCD supports JTAG
+debug of RV32 and RV64 cores in heterogeneous multicore systems of up to 32
+harts. (It's possible to increase this limit to 1024 by changing
+RISCV_MAX_HARTS in riscv.h.) OpenOCD primarily supports 0.13 of the RISC-V
+Debug Specification, but there is also support for legacy targets that
+implement version 0.11.
+
+@subsection RISC-V Terminology
+
+A @emph{hart} is a hardware thread. A hart may share resources (eg. FPU) with
+another hart, or may be a separate core. RISC-V treats those the same, and
+OpenOCD exposes each hart as a separate core.
+
+@subsection RISC-V Debug Configuration Commands
+
+@deffn Command {riscv expose_csrs} n0[-m0][,n1[-m1]]...
+Configure a list of inclusive ranges for CSRs to expose in addition to the
+standard ones. This must be executed before `init`.
+
+By default OpenOCD attempts to expose only CSRs that are mentioned in a spec,
+and then only if the corresponding extension appears to be implemented. This
+command can be used if OpenOCD gets this wrong, or a target implements custom
+CSRs.
+@end deffn
+
+@deffn Command {riscv set_command_timeout_sec} [seconds]
+Set the wall-clock timeout (in seconds) for individual commands. The default
+should work fine for all but the slowest targets (eg. simulators).
+@end deffn
+
+@deffn Command {riscv set_reset_timeout_sec} [seconds]
+Set the maximum time to wait for a hart to come out of reset after reset is
+deasserted.
+@end deffn
+
+@deffn Command {riscv set_scratch_ram} none|[address]
+Set the address of 16 bytes of scratch RAM the debugger can use, or 'none'.
+This is used to access 64-bit floating point registers on 32-bit targets.
+@end deffn
+
+@deffn Command {riscv set_prefer_sba} on|off
+When on, prefer to use System Bus Access to access memory. When off, prefer to
+use the Program Buffer to access memory.
+@end deffn
+
+@subsection RISC-V Authentication Commands
+
+The following commands can be used to authenticate to a RISC-V system. Eg. a
+trivial challenge-response protocol could be implemented as follows in a
+configuration file, immediately following @command{init}:
+@example
+set challenge [ocd_riscv authdata_read]
+riscv authdata_write [expr $challenge + 1]
+@end example
+
+@deffn Command {riscv authdata_read}
+Return the 32-bit value read from authdata. Note that to get read value back in
+a TCL script, it needs to be invoked as @command{ocd_riscv authdata_read}.
+@end deffn
+
+@deffn Command {riscv authdata_write} value
+Write the 32-bit value to authdata.
+@end deffn
+
+@subsection RISC-V DMI Commands
+
+The following commands allow direct access to the Debug Module Interface, which
+can be used to interact with custom debug features.
+
+@deffn Command {riscv dmi_read}
+Perform a 32-bit DMI read at address, returning the value. Note that to get
+read value back in a TCL script, it needs to be invoked as @command{ocd_riscv
+dmi_read}.
+@end deffn
+
+@deffn Command {riscv dmi_write} address value
+Perform a 32-bit DMI write of value at address.
+@end deffn
+
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
@item @option{embKernel}
@item @option{mqx}
@item @option{uCOS-III}
+@item @option{nuttx}
@end itemize
@quotation Note
_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
Code Review / openocd.git / blobdiff