diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/openocd.1 | 21 | ||||
| -rw-r--r-- | doc/openocd.texi | 189 |
3 files changed, 127 insertions, 85 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 6759203..17d051f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0-or-later + info_TEXINFOS += %D%/openocd.texi %C%_openocd_TEXINFOS = %D%/fdl.texi diff --git a/doc/openocd.1 b/doc/openocd.1 index 4278486..34ec761 100644 --- a/doc/openocd.1 +++ b/doc/openocd.1 @@ -1,24 +1,21 @@ -.TH "OPENOCD" "1" "November 24, 2009" +.TH "OPENOCD" "1" "June 18, 2024" .SH "NAME" openocd \- A free and open on\-chip debugging, in\-system programming and -boundary\-scan testing tool for ARM and MIPS systems +boundary\-scan testing tool for microcontrollers and other embedded devices .SH "SYNOPSIS" -.B openocd \fR[\fB\-fsdlcphv\fR] [\fB\-\-file\fR <filename>] [\fB\-\-search\fR <dirname>] [\fB\-\-debug\fR <debuglevel>] [\fB\-\-log_output\fR <filename>] [\fB\-\-command\fR <cmd>] [\fB\-\-pipe\fR] [\fB\-\-help\fR] [\fB\-\-version\fR] +.B openocd \fR[\fB\-fsdlchv\fR] [\fB\-\-file\fR <filename>] [\fB\-\-search\fR <dirname>] [\fB\-\-debug\fR <debuglevel>] [\fB\-\-log_output\fR <filename>] [\fB\-\-command\fR <cmd>] [\fB\-\-help\fR] [\fB\-\-version\fR] .SH "DESCRIPTION" .B OpenOCD is an on\-chip debugging, in\-system programming and boundary\-scan -testing tool for various ARM and MIPS systems. +testing tool for various microcontrollers and other embedded devices. .PP -The debugger uses an IEEE 1149\-1 compliant JTAG TAP bus master to access -on\-chip debug functionality available on ARM based microcontrollers or -system-on-chip solutions. For MIPS systems the EJTAG interface is supported. +Various different types of debug adapters as well as transport protocols like +JTAG and SWD are supported by OpenOCD, please check the \fIopenocd\fR info page +for the complete list. .PP User interaction is realized through a telnet command line interface, a gdb (the GNU debugger) remote protocol server, and a simplified RPC connection that can be used to interface with OpenOCD's Jim Tcl engine. -.PP -OpenOCD supports various different types of JTAG interfaces/programmers, -please check the \fIopenocd\fR info page for the complete list. .SH "OPTIONS" .TP .B "\-f, \-\-file <filename>" @@ -68,8 +65,6 @@ Note that you will need to explicitly invoke .I init if the command requires access to a target or flash. .TP -.B "\-p, \-\-pipe" -Use pipes when talking to gdb. .TP .B "\-h, \-\-help" Show a help text and exit. @@ -82,8 +77,6 @@ Please report any bugs on the mailing list at .SH "LICENCE" .B OpenOCD is covered by the GNU General Public License (GPL), version 2 or later. -.SH "SEE ALSO" -.BR jtag (1) .PP The full documentation for .B openocd diff --git a/doc/openocd.texi b/doc/openocd.texi index 8ffbcf3..ec862bd 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -930,8 +930,8 @@ a board with an Atmel AT91SAM7X256 microcontroller: source [find interface/ftdi/signalyzer.cfg] # GDB can also flash my flash! -gdb_memory_map enable -gdb_flash_program enable +gdb memory_map enable +gdb flash_program enable source [find target/sam7x256.cfg] @end example @@ -940,8 +940,8 @@ Here is the command line equivalent of that configuration: @example openocd -f interface/ftdi/signalyzer.cfg \ - -c "gdb_memory_map enable" \ - -c "gdb_flash_program enable" \ + -c "gdb memory_map enable" \ + -c "gdb flash_program enable" \ -f target/sam7x256.cfg @end example @@ -2179,18 +2179,16 @@ only during configuration (before those ports are opened). For reasons including security, you may wish to prevent remote access using one or more of these ports. 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. You can request the operating system to select one of the available ports for the server by specifying the relevant port number as "0". -@anchor{gdb_port} -@deffn {Config Command} {gdb_port} [number] +@anchor{gdb port} +@deffn {Config Command} {gdb port} [number] @cindex GDB server Normally gdb listens to a TCP/IP port, but GDB can also communicate via pipes(stdin/out or named pipes). The name -"gdb_port" stuck because it covers probably more than 90% of +"gdb port" stuck because it covers probably more than 90% of the normal use cases. No arguments reports GDB port. "pipe" means listen to stdin @@ -2205,7 +2203,7 @@ Output pipe is the same name as input pipe, but with 'o' appended, e.g. /var/gdb, /var/gdbo. The GDB port for the first target will be the base port, the -second target will listen on gdb_port + 1, and so on. +second target will listen on 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 @@ -2214,12 +2212,12 @@ the next port number does not work. In this case, specify the proper 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 +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 {Config Command} {tcl_port} [number] +@deffn {Config Command} {tcl port} [number] Specify or query the port used for a simplified RPC connection that can be used by clients to issue TCL commands and get the output from the Tcl engine. @@ -2248,7 +2246,7 @@ The ones listed here are static and global. @xref{targetevents,,Target Events}, about configuring target-specific event handling. @anchor{gdbbreakpointoverride} -@deffn {Command} {gdb_breakpoint_override} [@option{hard}|@option{soft}|@option{disable}] +@deffn {Command} {gdb breakpoint_override} [@option{hard}|@option{soft}|@option{disable}] Force breakpoint type for gdb @command{break} commands. This option supports GDB GUIs which don't distinguish hard versus soft breakpoints, if the default OpenOCD and @@ -2257,41 +2255,41 @@ breakpoints if the memory map has been set up for flash regions. @end deffn @anchor{gdbflashprogram} -@deffn {Config Command} {gdb_flash_program} (@option{enable}|@option{disable}) +@deffn {Config Command} {gdb flash_program} (@option{enable}|@option{disable}) Set to @option{enable} to cause OpenOCD to program the flash memory when a vFlash packet is received. The default behaviour is @option{enable}. @end deffn -@deffn {Config Command} {gdb_memory_map} (@option{enable}|@option{disable}) +@deffn {Config Command} {gdb memory_map} (@option{enable}|@option{disable}) Set to @option{enable} to cause OpenOCD to send the memory configuration to GDB when requested. GDB will then know when to set hardware breakpoints, and program flash -using the GDB load command. @command{gdb_flash_program enable} must also be enabled +using the GDB load command. @command{gdb flash_program enable} must also be enabled for flash programming to work. Default behaviour is @option{enable}. -@xref{gdbflashprogram,,gdb_flash_program}. +@xref{gdbflashprogram,,gdb flash_program}. @end deffn -@deffn {Config Command} {gdb_report_data_abort} (@option{enable}|@option{disable}) +@deffn {Config Command} {gdb report_data_abort} (@option{enable}|@option{disable}) Specifies whether data aborts cause an error to be reported by GDB memory read packets. The default behaviour is @option{disable}; use @option{enable} see these errors reported. @end deffn -@deffn {Config Command} {gdb_report_register_access_error} (@option{enable}|@option{disable}) +@deffn {Config Command} {gdb report_register_access_error} (@option{enable}|@option{disable}) Specifies whether register accesses requested by GDB register read/write packets report errors or not. The default behaviour is @option{disable}; use @option{enable} see these errors reported. @end deffn -@deffn {Config Command} {gdb_target_description} (@option{enable}|@option{disable}) +@deffn {Config Command} {gdb target_description} (@option{enable}|@option{disable}) Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet. The default behaviour is @option{enable}. @end deffn -@deffn {Command} {gdb_save_tdesc} +@deffn {Command} {gdb save_tdesc} Saves the target description file to the local file system. The file name is @i{target_name}.xml. @@ -2989,6 +2987,11 @@ Display free device internal memory. Set the JTAG command version to be used. Without argument, show the actual JTAG command version. @end deffn +@deffn {Command} {jlink targetpower} [@option{0}|@option{1}|@option{on}|@option{off}] +Switch the 5@ V target power supply on or off. +Without argument, show the state of the target power supply. +The target power supply is usually connected to pin 19 of the 20-pin connector. +@end deffn @deffn {Command} {jlink config} Display the device configuration. @end deffn @@ -3228,19 +3231,19 @@ versions of firmware where serial number is reset after first use. Suggest using ST firmware update utility to upgrade ST-LINK firmware even if current version reported is V2.J21.S4. -@deffn {Config Command} {hla_device_desc} description +@deffn {Config Command} {hla device_desc} description Currently Not Supported. @end deffn -@deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}|@option{nulink}) +@deffn {Config Command} {hla layout} (@option{stlink}|@option{icdi}|@option{nulink}) Specifies the adapter layout to use. @end deffn -@deffn {Config Command} {hla_vid_pid} [vid pid]+ +@deffn {Config Command} {hla vid_pid} [vid pid]+ Pairs of vendor IDs and product IDs of the device. @end deffn -@deffn {Config Command} {hla_stlink_backend} (usb | tcp [port]) +@deffn {Config Command} {hla stlink_backend} (usb | tcp [port]) @emph{ST-Link only:} Choose between 'exclusive' USB communication (the default backend) or 'shared' mode using ST-Link TCP server (the default port is 7184). @@ -3249,7 +3252,7 @@ available from @url{https://www.st.com/en/development-tools/st-link-server.html, ST-LINK server software module}. @end deffn -@deffn {Command} {hla_command} command +@deffn {Command} {hla command} command Execute a custom adapter-specific command. The @var{command} string is passed as is to the underlying adapter layout handler. @end deffn @@ -3719,20 +3722,18 @@ displays the names of the transports supported by this version of OpenOCD. @end deffn -@deffn {Command} {transport select} @option{transport_name} +@deffn {Command} {transport select} [transport_name] Select which of the supported transports to use in this OpenOCD session. When invoked with @option{transport_name}, attempts to select the named -transport. The transport must be supported by the debug adapter +transport. The transport must be supported by the debug adapter hardware and by the version of OpenOCD you are using (including the adapter's driver). - -If no transport has been selected and no @option{transport_name} is -provided, @command{transport select} auto-selects the first transport -supported by the debug adapter. - -@command{transport select} always returns the name of the session's selected -transport, if any. +When invoked with no transport name: +@itemize @minus +@item if no transport has been selected yet, it auto-selects the first transport supported by the debug adapter +@item it returns the name of the session's selected transport +@end itemize @end deffn @subsection JTAG Transport @@ -5190,6 +5191,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. @@ -5197,11 +5230,11 @@ where it is a mandatory configuration for the target run control. 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 +@item @code{-gdb-port} @var{number} -- @xref{gdb port,,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}. +command @command{gdb port}. +@xref{gdb port,,command gdb port}. @item @code{-gdb-max-connections} @var{number} -- EXPERIMENTAL: set the maximum number of GDB connections that are allowed for the target. Default is 1. @@ -7345,12 +7378,13 @@ flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME @end deffn @deffn {Flash Driver} {nrf5} -All members of the nRF51 microcontroller families from Nordic Semiconductor -include internal flash and use ARM Cortex-M0 core. nRF52 family powered -by ARM Cortex-M4 or M4F core is supported too. nRF52832 is fully supported -including BPROT flash protection scheme. nRF52833 and nRF52840 devices are -supported with the exception of security extensions (flash access control list -- ACL). +Supports all members of the nRF51, nRF52 and nRF53 microcontroller families from +Nordic Semiconductor. nRF91 family is supported too. One driver handles both +the main flash and the UICR area. + +Flash protection is handled on nRF51 family and nRF52805, nRF52810, nRF52811, +nRF52832 devices. Flash access control list (ACL) protection scheme of the newer +devices is not supported. @example flash bank $_FLASHNAME nrf5 0 0x00000000 0 0 $_TARGETNAME @@ -8827,8 +8861,8 @@ The file format must be inferred by the driver. @section PLD/FPGA Drivers, Options, and Commands -Drivers may support PLD-specific options to the @command{pld device} -definition command, and may also define commands usable only with +Drivers may support PLD-specific options to the @command{pld create} +command, and may also define commands usable only with that particular type of PLD. @deffn {FPGA Driver} {virtex2} [@option{-no_jstart}] @@ -8914,13 +8948,12 @@ For the option @option{-family} @var{name} is one of @var{trion|titanium}. @end deffn -@deffn {FPGA Driver} {intel} [@option{-family} <name>] +@deffn {FPGA Driver} {intel} @option{-family} <name> This driver can be used to load the bitstream into Intel (former Altera) FPGAs. -The families Cyclone III, Cyclone IV, Cyclone V, Cyclone 10, Arria II are supported. +The families Cyclone III, Cyclone IV, Cyclone V, Cyclone 10 and Arria II are supported. @c Arria V and Arria 10, MAX II, MAX V, MAX10) -For the option @option{-family} @var{name} is one of @var{cycloneiii cycloneiv cyclonev cyclone10 arriaii}. -This is needed when the JTAG ID of the device is ambiguous (same ID is used for chips in different families). +The option @option{-family} @var{name} is one of @var{cycloneiii cycloneiv cyclonev cyclone10 arriaii}. As input file format the driver supports a '.rbf' (raw bitstream file) file. The '.rbf' file can be generated from a '.sof' file with @verb{|quartus_cpf -c blinker.sof blinker.rbf|} @@ -10587,7 +10620,7 @@ the destination of the trace data: @item @option{external} -- configure TPIU/SWO to let user capture trace output externally, either with an additional UART or with a logic analyzer (default); @item @option{-} -- configure TPIU/SWO and debug adapter to gather trace data -and forward it to @command{tcl_trace} command; +and forward it to @command{tcl trace} command; @item @option{:}@var{port} -- configure TPIU/SWO and debug adapter to gather trace data, open a TCP server at port @var{port} and send the trace data to each connected client; @@ -11290,11 +11323,6 @@ 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_mem_access} method1 [method2] [method3] Specify which RISC-V memory access method(s) shall be used, and in which order of priority. At least one method must be specified. @@ -11359,10 +11387,15 @@ Display/set the current core displayed in GDB. This is needed only if @code{riscv smp} was used. @end deffn -@deffn {Command} {riscv use_bscan_tunnel} value +@deffn {Command} {riscv use_bscan_tunnel} width [type] Enable or disable use of a BSCAN tunnel to reach the Debug Module. Supply the -width of the DM transport TAP's instruction register to enable. Supply a -value of 0 to disable. +@var{width} of the DM transport TAP's instruction register to enable. The +@var{width} should fit into 7 bits. Supply a value of 0 to disable. +Pass a second argument (optional) to indicate Bscan Tunnel Type: +@enumerate +@item 0:(default) NESTED_TAP +@item 1: DATA_REGISTER +@end enumerate This BSCAN tunnel interface is specific to SiFive IP. Anybody may implement it, but currently there is no good documentation on it. In a nutshell, this @@ -11376,7 +11409,6 @@ tunneled DR scan consists of: @item A width+1 stream of bits for the tunneled TDI. The plus one is because there is a one-clock skew between TDI of Xilinx chain and TDO from tunneled chain. @item 3 bits of zero that the tunnel uses to go back to idle state. @end enumerate - @end deffn @deffn {Command} {riscv set_bscan_tunnel_ir} value @@ -11530,6 +11562,21 @@ as in the mie CSR (defined in the RISC-V Privileged Spec). For details on this trigger type, see the RISC-V Debug Specification. @end deffn +@deffn {Command} {riscv reserve_trigger} [index @option{on|off}] +Manages the set of reserved triggers. Reserving a trigger results in OpenOCD +not using it internally (e.g. skipping it when setting a watchpoint or a +hardware breakpoint), so that the user or the application has unfettered +control over the trigger. By default there are no reserved triggers. + +@enumerate +@item @var{index} specifies the index of a trigger to reserve or free up. +@item The second argument specifies whether the trigger should be reserved +(@var{on}) or a prior reservation cancelled (@var{off}). +@item If called without parameters, returns indices of reserved triggers. +@end enumerate + +@end deffn + @deffn {Command} {riscv itrigger clear} Clear the type 4 trigger that was set using @command{riscv itrigger set}. @end deffn @@ -12599,7 +12646,7 @@ target remote localhost:3333 A pipe connection is typically started as follows: @example target extended-remote | \ - openocd -c "gdb_port pipe; log_output openocd.log" + openocd -c "gdb port pipe; log_output openocd.log" @end example This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout). Using this method has the advantage of GDB starting/stopping OpenOCD for the debug @@ -12683,7 +12730,7 @@ using @command{gdb -x filename}. By default the target memory map is sent to GDB. This can be disabled by the following OpenOCD configuration option: @example -gdb_memory_map disable +gdb memory_map disable @end example For this to function correctly a valid flash configuration must also be set in OpenOCD. For faster performance you should also configure a valid @@ -12691,8 +12738,8 @@ working area. Informing GDB of the memory map of the target will enable GDB to protect any flash areas of the target and use hardware breakpoints by default. This means -that the OpenOCD option @command{gdb_breakpoint_override} is not required when -using a memory map. @xref{gdbbreakpointoverride,,gdb_breakpoint_override}. +that the OpenOCD option @command{gdb breakpoint_override} is not required when +using a memory map. @xref{gdbbreakpointoverride,,gdb breakpoint_override}. To view the configured memory map in GDB, use the GDB command @option{info mem}. All other unassigned addresses within GDB are treated as RAM. @@ -12703,7 +12750,7 @@ This can be changed to the old behaviour by using the following GDB command set mem inaccessible-by-default off @end example -If @command{gdb_flash_program enable} is also used, GDB will be able to +If @command{gdb flash_program enable} is also used, GDB will be able to program any flash memory using the vFlash interface. GDB will look at the target memory map when a load command is given, if any @@ -12742,9 +12789,9 @@ $_TARGETNAME configure -event gdb-attach @{@} @end example If any of installed flash banks does not support probe on running target, -switch off gdb_memory_map: +switch off gdb memory_map: @example -gdb_memory_map disable +gdb memory_map disable @end example Ensure GDB is configured without interrupt-on-connect. @@ -12753,7 +12800,7 @@ Some GDB versions set it by default, some does not. set remote interrupt-on-connect off @end example -If you switched gdb_memory_map off, you may want to setup GDB memory map +If you switched gdb memory_map off, you may want to setup GDB memory map manually or issue @command{set mem inaccessible-by-default off} Now you can issue GDB command @command{target extended-remote ...} and inspect memory @@ -12966,7 +13013,7 @@ OpenOCD provides a simple RPC server that allows to run arbitrary Tcl commands and receive the results. To access it, your application needs to connect to a configured TCP port -(see @command{tcl_port}). Then it can pass any string to the +(see @command{tcl port}). Then it can pass any string to the interpreter terminating it with @code{0x1a} and wait for the return value (it will be terminated with @code{0x1a} as well). This can be repeated as many times as desired without reopening the connection. @@ -12992,7 +13039,7 @@ type target_state state [state-name] type target_reset mode [reset-mode] @end verbatim -@deffn {Command} {tcl_notifications} [on/off] +@deffn {Command} {tcl notifications} [on/off] Toggle output of target notifications to the current Tcl RPC server. Only available from the Tcl RPC server. Defaults to off. @@ -13011,7 +13058,7 @@ Target trace data is emitted as a Tcl associative array in the following format. type target_trace data [trace-data-hex-encoded] @end verbatim -@deffn {Command} {tcl_trace} [on/off] +@deffn {Command} {tcl trace} [on/off] Toggle output of target trace data to the current Tcl RPC server. Only available from the Tcl RPC server. Defaults to off. |