X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=0c1714e49468c9246b24732b0df4a1ae90df93fe;hb=dc7b32ea4a00;hp=dba2a0afa00e157c0faf1d398e6d6f774120922e;hpb=b68674a1da7249c52b00b511fe0ceb20ace5ae4d;p=fw%2Fopenocd diff --git a/doc/openocd.texi b/doc/openocd.texi index dba2a0afa..0c1714e49 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -30,9 +30,9 @@ of the Open On-Chip Debugger (OpenOCD). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License''. @end quotation @end copying @@ -79,7 +79,6 @@ Free Documentation License''. * JTAG Commands:: JTAG Commands * Boundary Scan Commands:: Boundary Scan Commands * Utility Commands:: Utility Commands -* TFTP:: TFTP * GDB and OpenOCD:: Using GDB and OpenOCD * Tcl Scripting API:: Tcl Scripting API * FAQ:: Frequently Asked Questions @@ -624,6 +623,13 @@ emulation model of target hardware. @item @b{xlnx_pcie_xvc} @* A JTAG driver exposing Xilinx Virtual Cable over PCI Express to OpenOCD as JTAG/SWD interface. +@item @b{linuxgpiod} +@* A bitbang JTAG driver using Linux GPIO through library libgpiod. + +@item @b{sysfsgpio} +@* A bitbang JTAG driver using Linux legacy sysfs GPIO. +This is deprecated from Linux v5.3; prefer using @b{linuxgpiod}. + @end itemize @node About Jim-Tcl @@ -828,7 +834,7 @@ using Eclipse or some other GUI. Today's most common case is a dongle with a JTAG cable on one side (such as a ribbon cable with a 10-pin or 20-pin IDC connector) and a USB cable on the other. -Instead of USB, some cables use Ethernet; +Instead of USB, some dongles use Ethernet; older ones may use a PC parallel port, or even a serial port. @enumerate @@ -2430,7 +2436,8 @@ and a specific set of GPIOs is used. @end deffn @deffn {Interface Driver} {cmsis-dap} -ARM CMSIS-DAP compliant based adapter. +ARM CMSIS-DAP compliant based adapter v1 (USB HID based) +or v2 (USB bulk). @deffn {Config Command} {cmsis_dap_vid_pid} [vid pid]+ The vendor ID and product ID of the CMSIS-DAP device. If not specified @@ -2446,6 +2453,23 @@ Specifies the @var{serial} of the CMSIS-DAP device to use. If not specified, serial numbers are not considered. @end deffn +@deffn {Config Command} {cmsis_dap_backend} [@option{auto}|@option{usb_bulk}|@option{hid}] +Specifies how to communicate with the adapter: + +@itemize @minus +@item @option{hid} Use HID generic reports - CMSIS-DAP v1 +@item @option{usb_bulk} Use USB bulk - CMSIS-DAP v2 +@item @option{auto} First try USB bulk CMSIS-DAP v2, if not found try HID CMSIS-DAP v1. +This is the default if @command{cmsis_dap_backend} is not specified. +@end itemize +@end deffn + +@deffn {Config Command} {cmsis_dap_usb interface} [number] +Specifies the @var{number} of the USB interface to use in v2 mode (USB bulk). +In most cases need not to be specified and interfaces are searched by +interface string or for user class interface. +@end deffn + @deffn {Command} {cmsis-dap info} Display various device information, like hardware version, firmware version, current bus status. @end deffn @@ -2881,8 +2905,8 @@ The following example shows how to read 4 bytes from the EMUCOM channel 0x0: @deffn {Config} {jlink usb} <@option{0} to @option{3}> Set the USB address of the interface, in case more than one adapter is connected to the host. If not specified, USB addresses are not considered. Device -selection via USB address is deprecated and the serial number should be used -instead. +selection via USB address is not always unambiguous. It is recommended to use +the serial number instead, if possible. As a configuration command, it can be used only before 'init'. @end deffn @@ -3102,6 +3126,15 @@ Specifies the adapter layout to use. Pairs of vendor IDs and product IDs of the device. @end deffn +@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). + +@emph{Note:} ST-Link TCP server is a binary application provided by ST +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 Execute a custom adapter-specific command. The @var{command} string is passed as is to the underlying adapter layout handler. @@ -3122,6 +3155,17 @@ An error is returned for any AP number above the maximum allowed value. @emph{Note:} Either these same adapters and their older versions are also supported by @ref{hla_interface, the hla interface driver}. +@deffn {Config Command} {st-link backend} (usb | tcp [port]) +Choose between 'exclusive' USB communication (the default backend) or +'shared' mode using ST-Link TCP server (the default port is 7184). + +@emph{Note:} ST-Link TCP server is a binary application provided by ST +available from @url{https://www.st.com/en/development-tools/st-link-server.html, +ST-LINK server software module}. + +@emph{Note:} ST-Link TCP server does not support the SWIM transport. +@end deffn + @deffn {Config Command} {st-link serial} serial Specifies the serial number of the adapter. @end deffn @@ -3223,6 +3267,22 @@ pinout. @end deffn +@deffn {Interface Driver} {linuxgpiod} +Linux provides userspace access to GPIO through libgpiod since Linux kernel version v4.6. +The driver emulates either JTAG and SWD transport through bitbanging. + +See @file{interface/dln-2-gpiod.cfg} for a sample config. +@end deffn + + +@deffn {Interface Driver} {sysfsgpio} +Linux legacy userspace access to GPIO through sysfs is deprecated from Linux kernel version v5.3. +Prefer using @b{linuxgpiod}, instead. + +See @file{interface/sysfsgpio-raspberrypi.cfg} for a sample config. +@end deffn + + @deffn {Interface Driver} {openjtag} OpenJTAG compatible USB adapter. This defines some driver-specific commands: @@ -4507,8 +4567,10 @@ The current implementation supports three JTAG TAP cores: @end itemize And two debug interfaces cores: @itemize @minus -@item @code{Advanced debug interface} (See: @url{http://opencores.org/project@comma{}adv_debug_sys}) -@item @code{SoC Debug Interface} (See: @url{http://opencores.org/project@comma{}dbg_interface}) +@item @code{Advanced debug interface} +@*(See: @url{http://opencores.org/project@comma{}adv_debug_sys}) +@item @code{SoC Debug Interface} +@*(See: @url{http://opencores.org/project@comma{}dbg_interface}) @end itemize @item @code{quark_d20xx} -- an Intel Quark D20xx core. @item @code{quark_x10xx} -- an Intel Quark X10xx core. @@ -4694,6 +4756,11 @@ 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}. + +@item @code{-gdb-max-connections} @var{number} -- EXPERIMENTAL: set the maximum +number of GDB connections that are allowed for the target. Default is 1. +A negative value for @var{number} means unlimited connections. +See @xref{gdbmeminspect,,Using GDB as a non-intrusive memory inspector}. @end itemize @end deffn @@ -4988,6 +5055,19 @@ when reset disables PLLs needed to use a fast clock. @* After target hardware trace configuration was changed @end itemize +@quotation Note +OpenOCD events are not supposed to be preempt by another event, but this +is not enforced in current code. Only the target event @b{resumed} is +executed with polling disabled; this avoids polling to trigger the event +@b{halted}, reversing the logical order of execution of their handlers. +Future versions of OpenOCD will prevent the event preemption and will +disable the schedule of polling during the event execution. Do not rely +on polling in any event handler; this means, don't expect the status of +a core to change during the execution of the handler. The event handler +will have to enable polling or use @command{$target_name arp_poll} to +check if the core has changed status. +@end quotation + @node Flash Commands @chapter Flash Commands @@ -5249,6 +5329,18 @@ it has been removed by the @option{unlock} flag. @end deffn +@deffn Command {flash verify_image} filename [offset] [type] +Verify the image @file{filename} to the current target's flash bank(s). +Parameters follow the description of 'flash write_image'. +In contrast to the 'verify_image' command, for banks with specific +verify method, that one is used instead of the usual target's read +memory methods. This is necessary for flash banks not readable by +ordinary memory reads. +This command gives only an overall good/bad result for each bank, not +addresses of individual failed bytes as it's intended only as quick +check for successful programming. +@end deffn + @section Other Flash commands @cindex flash protection @@ -5507,6 +5599,121 @@ flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME @end deffn +@deffn {Flash Driver} stmqspi +@cindex STMicroelectronics QuadSPI/OctoSPI Interface +@cindex QuadSPI +@cindex OctoSPI +@cindex stmqspi +Some devices from STMicroelectronics include a proprietary ``QuadSPI Interface'' +(e.g. STM32F4, STM32F7, STM32L4) or ``OctoSPI Interface'' (e.g. STM32L4+) +controller able to drive one or even two (dual mode) external SPI flash devices. +The OctoSPI is a superset of QuadSPI, its presence is detected automatically. +Currently only the regular command mode is supported, whereas the HyperFlash +mode is not. + +QuadSPI/OctoSPI makes the flash contents directly accessible in the CPU address +space; in case of dual mode both devices must be of the same type and are +mapped in the same memory bank (even and odd addresses interleaved). +CPU can directly read data, execute code (but not boot) from QuadSPI bank. + +The 'flash bank' command only requires the @var{base} parameter and the extra +parameter @var{io_base} in order to identify the memory bank. Both are fixed +by hardware, see datasheet or RM. All other parameters are ignored. + +The controller must be initialized after each reset and properly configured +for memory-mapped read operation for the particular flash chip(s), for the full +list of available register settings cf. the controller's RM. This setup is quite +board specific (that's why booting from this memory is not possible). The +flash driver infers all parameters from current controller register values when +'flash probe @var{bank_id}' is executed. + +Normal OpenOCD commands like @command{mdw} can be used to display the flash content, +but only after proper controller initialization as decribed above. However, +due to a silicon bug in some devices, attempting to access the very last word +should be avoided. + +It is possible to use two (even different) flash chips alternatingly, if individual +bank chip selects are available. For some package variants, this is not the case +due to limited pin count. To switch from one to another, adjust FSEL bit accordingly +and re-issue 'flash probe bank_id'. Note that the bank base address will @emph{not} +change, so the address spaces of both devices will overlap. In dual flash mode +both chips must be identical regarding size and most other properties. + +Block or sector protection internal to the flash chip is not handled by this +driver at all, but can be dealt with manually by the 'cmd' command, see below. +The sector protection via 'flash protect' command etc. is completely internal to +openocd, intended only to prevent accidental erase or overwrite and it does not +persist across openocd invocations. + +OpenOCD contains a hardcoded list of flash devices with their properties, +these are auto-detected. If a device is not included in this list, SFDP discovery +is attempted. If this fails or gives inappropriate results, manual setting is +required (see 'set' command). + +@example +flash bank $_FLASHNAME stmqspi 0x90000000 0 0 0 \ + $_TARGETNAME 0xA0001000 +flash bank $_FLASHNAME stmqspi 0x70000000 0 0 0 \ + $_TARGETNAME 0xA0001400 +@end example + +There are three specific commands +@deffn Command {stmqspi mass_erase} bank_id +Clears sector protections and performs a mass erase. Works only if there is no +chip specific write protection engaged. +@end deffn + +@deffn Command {stmqspi set} bank_id name total_size page_size read_cmd fread_cmd pprg_cmd mass_erase_cmd sector_size sector_erase_cmd +Set flash parameters: @var{name} human readable string, @var{total_size} size +in bytes, @var{page_size} is write page size. @var{read_cmd}, @var{fread_cmd} and @var{pprg_cmd} +are commands for reading and page programming. @var{fread_cmd} is used in DPI and QPI modes, +@var{read_cmd} in normal SPI (single line) mode. @var{mass_erase_cmd}, @var{sector_size} +and @var{sector_erase_cmd} are optional. + +This command is required if chip id is not hardcoded yet and e.g. for EEPROMs or FRAMs +which don't support an id command. + +In dual mode parameters of both chips are set identically. The parameters refer to +a single chip, so the whole bank gets twice the specified capacity etc. +@end deffn + +@deffn Command {stmqspi cmd} bank_id resp_num cmd_byte ... +If @var{resp_num} is zero, sends command @var{cmd_byte} and following data +bytes. In dual mode command byte is sent to @emph{both} chips but data bytes are +sent @emph{alternatingly} to chip 1 and 2, first to flash 1, second to flash 2, etc., +i.e. the total number of bytes (including cmd_byte) must be odd. + +If @var{resp_num} is not zero, cmd and at most four following data bytes are +sent, in dual mode @emph{simultaneously} to both chips. Then @var{resp_num} bytes +are read interleaved from both chips starting with chip 1. In this case +@var{resp_num} must be even. + +Note the hardware dictated subtle difference of those two cases in dual-flash mode. + +To check basic communication settings, issue +@example +stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 1 0x05 +stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 1 0x05 +@end example +for single flash mode or +@example +stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 2 0x05 +stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 2 0x05 +@end example +for dual flash mode. This should return the status register contents. + +In 8-line mode, @var{cmd_byte} is sent twice - first time as given, second time +complemented. Additionally, in 8-line mode only, some commands (e.g. Read Status) +need a dummy address, e.g. +@example +stmqspi cmd bank_id 1 0x05 0x00 0x00 0x00 0x00 +@end example +should return the status register contents. + +@end deffn + +@end deffn + @deffn {Flash Driver} mrvlqspi This driver supports QSPI flash controller of Marvell's Wireless Microcontroller platform. @@ -5549,9 +5756,9 @@ CS1/CS2 is routed to on the given SoC. @example flash bank $_FLASHNAME ath79 0xbf000000 0 0 0 $_TARGETNAME -# When using multiple chipselects the base should be different for each, -# otherwise the write_image command is not able to distinguish the -# banks. +# When using multiple chipselects the base should be different +# for each, otherwise the write_image command is not able to +# distinguish the banks. flash bank flash0 ath79 0xbf000000 0 0 0 $_TARGETNAME cs0 flash bank flash1 ath79 0x10000000 0 0 0 $_TARGETNAME cs1 flash bank flash2 ath79 0x20000000 0 0 0 $_TARGETNAME cs2 @@ -5712,7 +5919,8 @@ reserved-bits are masked out and cannot be changed. NVMUSERROW: 0xFFFFFC5DD8E0C788 # Write 0xFFFFFC5DD8E0C788 to user row >at91samd nvmuserrow 0xFFFFFC5DD8E0C788 -# Write 0x12300 to user row but leave other bits and low byte unchanged +# Write 0x12300 to user row but leave other bits and low +# byte unchanged >at91samd nvmuserrow 0x12345 0xFFF00 @end example @end deffn @@ -5860,8 +6068,9 @@ The reserved fields are always masked out and cannot be changed. USER PAGE: 0xAEECFF80FE9A9239 # Write >atsame5 userpage 0xAEECFF80FE9A9239 -# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other bits unchanged -# (setup SmartEEPROM of virtual size 8192 bytes) +# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other +# bits unchanged (setup SmartEEPROM of virtual size 8192 +# bytes) >atsame5 userpage 0x4200000000 0x7f00000000 @end example @end deffn @@ -6620,7 +6829,8 @@ The driver probes for a number of these chips and autoconfigures itself, apart from the base address. @example -flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 $_TARGETNAME +flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 \ + $_TARGETNAME @end example @end deffn @@ -6674,19 +6884,31 @@ automatically by parsing data in SPCIF_GEOMETRY register. PSoC6 is equipped with NOR Flash so erased Flash reads as 0x00. @example -flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm0 -flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm0 -flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm0 -flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm0 -flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm0 -flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm0 - -flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 $@{TARGET@}.cm4 -flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 $@{TARGET@}.cm4 -flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 $@{TARGET@}.cm4 -flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 $@{TARGET@}.cm4 -flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 $@{TARGET@}.cm4 -flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 $@{TARGET@}.cm4 +flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 \ + $@{TARGET@}.cm0 +flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 \ + $@{TARGET@}.cm0 +flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 \ + $@{TARGET@}.cm0 +flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 \ + $@{TARGET@}.cm0 +flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 \ + $@{TARGET@}.cm0 +flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 \ + $@{TARGET@}.cm0 + +flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 \ + $@{TARGET@}.cm4 +flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 \ + $@{TARGET@}.cm4 +flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 \ + $@{TARGET@}.cm4 +flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 \ + $@{TARGET@}.cm4 +flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 \ + $@{TARGET@}.cm4 +flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 \ + $@{TARGET@}.cm4 @end example psoc6-specific commands @@ -6942,7 +7164,8 @@ will be touched). Example usage: @example -# swap bank 1 and bank 2 in dual bank devices, by setting SWAP_BANK_OPT bit in OPTSR_PRG +# swap bank 1 and bank 2 in dual bank devices +# by setting SWAP_BANK_OPT bit in OPTSR_PRG stm32h7x option_write 0 0x20 0x8000000 0x8000000 @end example @end deffn @@ -6989,10 +7212,9 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @deffn {Flash Driver} stm32l4x -All members of the STM32L4, STM32L4+, STM32WB, STM32WL and STM32G4 +All members of the STM32 G0, G4, L4, L4+, L5, WB and WL microcontroller families from STMicroelectronics include internal flash -and use ARM Cortex-M4 cores. -Additionally this driver supports STM32G0 family with ARM Cortex-M0+ core. +and use ARM Cortex-M0+, M4 and M33 cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -8279,6 +8501,94 @@ the watchpoint should trigger. The value may be first be masked using @var{mask} to mark ``don't care'' fields. @end deffn + +@section Real Time Transfer (RTT) + +Real Time Transfer (RTT) is an interface specified by SEGGER based on basic +memory reads and writes to transfer data bidirectionally between target and host. +The specification is independent of the target architecture. +Every target that supports so called "background memory access", which means +that the target memory can be accessed by the debugger while the target is +running, can be used. +This interface is especially of interest for targets without +Serial Wire Output (SWO), such as ARM Cortex-M0, or where semihosting is not +applicable because of real-time constraints. + +@quotation Note +The current implementation supports only single target devices. +@end quotation + +The data transfer between host and target device is organized through +unidirectional up/down-channels for target-to-host and host-to-target +communication, respectively. + +@quotation Note +The current implementation does not respect channel buffer flags. +They are used to determine what happens when writing to a full buffer, for +example. +@end quotation + +Channels are exposed via raw TCP/IP connections. One or more RTT servers can be +assigned to each channel to make them accessible to an unlimited number +of TCP/IP connections. + +@deffn Command {rtt setup} address size ID +Configure RTT for the currently selected target. +Once RTT is started, OpenOCD searches for a control block with the +identifier @var{ID} starting at the memory address @var{address} within the next +@var{size} bytes. +@end deffn + +@deffn Command {rtt start} +Start RTT. +If the control block location is not known, OpenOCD starts searching for it. +@end deffn + +@deffn Command {rtt stop} +Stop RTT. +@end deffn + +@deffn Command {rtt polling_interval [interval]} +Display the polling interval. +If @var{interval} is provided, set the polling interval. +The polling interval determines (in milliseconds) how often the up-channels are +checked for new data. +@end deffn + +@deffn Command {rtt channels} +Display a list of all channels and their properties. +@end deffn + +@deffn Command {rtt channellist} +Return a list of all channels and their properties as Tcl list. +The list can be manipulated easily from within scripts. +@end deffn + +@deffn Command {rtt server start} port channel +Start a TCP server on @var{port} for the channel @var{channel}. +@end deffn + +@deffn Command {rtt server stop} port +Stop the TCP sever with port @var{port}. +@end deffn + +The following example shows how to setup RTT using the SEGGER RTT implementation +on the target device. + +@example +resume + +rtt setup 0x20000000 2048 "SEGGER RTT" +rtt start + +rtt server start 9090 0 +@end example + +In this example, OpenOCD searches the control block with the ID "SEGGER RTT" +starting at 0x20000000 for 2048 bytes. The RTT channel 0 is exposed through the +TCP/IP port 9090. + + @section Misc Commands @cindex profiling @@ -8593,7 +8903,7 @@ CTI is mandatory for core run control and each core has an individual CTI instance attached to it. OpenOCD has limited support for CTI using the @emph{cti} group of commands. -@deffn Command {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-ctibase} base_address +@deffn Command {cti create} cti_name @option{-dap} dap_name @option{-ap-num} apn @option{-baseaddr} base_address Creates a CTI instance @var{cti_name} on the DAP instance @var{dap_name} on MEM-AP @var{apn}. The @var{base_address} must match the base address of the CTI on the respective MEM-AP. All arguments are mandatory. This creates a @@ -9193,55 +9503,145 @@ Selects whether interrupts will be processed when single stepping @end deffn -@subsection ARMv7-M specific commands +@subsection ARM CoreSight TPIU and SWO specific commands @cindex tracing @cindex SWO @cindex SWV @cindex TPIU -@cindex ITM -@cindex ETM -@deffn Command {tpiu config} (@option{disable} | ((@option{external} | @option{internal (@var{filename} | -)}) @ - (@option{sync @var{port_width}} | ((@option{manchester} | @option{uart}) @var{formatter_enable})) @ - @var{TRACECLKIN_freq} [@var{trace_freq}])) - -ARMv7-M architecture provides several modules to generate debugging +ARM CoreSight provides several modules to generate debugging information internally (ITM, DWT and ETM). Their output is directed -through TPIU to be captured externally either on an SWO pin (this +through TPIU or SWO modules to be captured externally either on an SWO pin (this configuration is called SWV) or on a synchronous parallel trace port. -This command configures the TPIU module of the target and, if internal -capture mode is selected, starts to capture trace output by using the -debugger adapter features. +ARM CoreSight provides independent HW blocks named TPIU and SWO each with its +own functionality. Embedded in Cortex-M3 and M4, ARM provides an optional HW +block that includes both TPIU and SWO functionalities and is again named TPIU, +which causes quite some confusion. +The registers map of all the TPIU and SWO implementations allows using a single +driver that detects at runtime the features available. -Some targets require additional actions to be performed in the -@b{trace-config} handler for trace port to be activated. +The @command{tpiu} is used for either TPIU or SWO. +A convenient alias @command{swo} is available to help distinguish, in scripts, +the commands for SWO from the commands for TPIU. -Command options: +@deffn Command {swo} ... +Alias of @command{tpiu ...}. Can be used in scripts to distinguish the commands +for SWO from the commands for TPIU. +@end deffn + +@deffn Command {tpiu create} tpiu_name configparams... +Creates a TPIU or a SWO object. The two commands are equivalent. +Add the object in a list and add new commands (@command{@var{tpiu_name}}) +which are used for various purposes including additional configuration. + +@itemize @bullet +@item @var{tpiu_name} -- the name of the TPIU or SWO object. +This name is also used to create the object's command, referred to here +as @command{$tpiu_name}, and in other places where the TPIU or SWO needs to be identified. +@item @var{configparams} -- all parameters accepted by @command{$tpiu_name configure} are permitted. + +You @emph{must} set here the AP and MEM_AP base_address through @code{-dap @var{dap_name}}, +@code{-ap-num @var{ap_number}} and @code{-baseaddr @var{base_address}}. +@end itemize +@end deffn + +@deffn Command {tpiu names} +Lists all the TPIU or SWO objects created so far. The two commands are equivalent. +@end deffn + +@deffn Command {tpiu init} +Initialize all registered TPIU and SWO. The two commands are equivalent. +These commands are used internally during initialization. They can be issued +at any time after the initialization, too. +@end deffn + +@deffn Command {$tpiu_name cget} queryparm +Each configuration parameter accepted by @command{$tpiu_name configure} can be +individually queried, to return its current value. +The @var{queryparm} is a parameter name accepted by that command, such as @code{-dap}. +@end deffn + +@deffn Command {$tpiu_name configure} configparams... +The options accepted by this command may also be specified as parameters +to @command{tpiu create}. Their values can later be queried one at a time by +using the @command{$tpiu_name cget} command. + +@itemize @bullet +@item @code{-dap} @var{dap_name} -- names the DAP used to access this +TPIU. @xref{dapdeclaration,,DAP declaration}, on how to create and manage DAP instances. + +@item @code{-ap-num} @var{ap_number} -- sets DAP access port for TPIU, +@var{ap_number} is the numeric index of the DAP AP the TPIU is connected to. + +@item @code{-baseaddr} @var{base_address} -- sets the TPIU @var{base_address} where +to access the TPIU in the DAP AP memory space. + +@item @code{-protocol} (@option{sync}|@option{uart}|@option{manchester}) -- sets the +protocol used for trace data: +@itemize @minus +@item @option{sync} -- synchronous parallel trace output mode, using @var{port_width} + data bits (default); +@item @option{uart} -- use asynchronous SWO mode with NRZ (same as regular UART 8N1) coding; +@item @option{manchester} -- use asynchronous SWO mode with Manchester coding. +@end itemize + +@item @code{-event} @var{event_name} @var{event_body} -- assigns an event handler, +a TCL string which is evaluated when the event is triggered. The events +@code{pre-enable}, @code{post-enable}, @code{pre-disable} and @code{post-disable} +are defined for TPIU/SWO. +A typical use case for the event @code{pre-enable} is to enable the trace clock +of the TPIU. + +@item @code{-output} (@option{external}|@option{:}@var{port}|@var{filename}|@option{-}) -- specifies +the destination of the trace data: @itemize @minus -@item @option{disable} disable TPIU handling; -@item @option{external} configure TPIU to let user capture trace -output externally (with an additional UART or logic analyzer hardware); -@item @option{internal @var{filename}} configure TPIU and debug adapter to -gather trace data and append it to @var{filename} (which can be -either a regular file or a named pipe); -@item @option{internal -} configure TPIU and debug adapter to -gather trace data, but not write to any file. Useful in conjunction with the @command{tcl_trace} command; -@item @option{sync @var{port_width}} use synchronous parallel trace output -mode, and set port width to @var{port_width}; -@item @option{manchester} use asynchronous SWO mode with Manchester -coding; -@item @option{uart} use asynchronous SWO mode with NRZ (same as -regular UART 8N1) coding; -@item @var{formatter_enable} is @option{on} or @option{off} to enable -or disable TPIU formatter which needs to be used when both ITM and ETM -data is to be output via SWO; -@item @var{TRACECLKIN_freq} this should be specified to match target's -current TRACECLKIN frequency (usually the same as HCLK); -@item @var{trace_freq} trace port frequency. Can be omitted in -internal mode to let the adapter driver select the maximum supported -rate automatically. +@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; +@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; +@item @var{filename} -- configure TPIU/SWO and debug adapter to +gather trace data and append it to @var{filename}, which can be +either a regular file or a named pipe. +@end itemize + +@item @code{-traceclk} @var{TRACECLKIN_freq} -- mandatory parameter. +Specifies the frequency in Hz of the trace clock. For the TPIU embedded in +Cortex-M3 or M4, this is usually the same frequency as HCLK. For protocol +@option{sync} this is twice the frequency of the pin data rate. + +@item @code{-pin-freq} @var{trace_freq} -- specifies the expected data rate +in Hz of the SWO pin. Parameter used only on protocols @option{uart} and +@option{manchester}. Can be omitted to let the adapter driver select the +maximum supported rate automatically. + +@item @code{-port-width} @var{port_width} -- sets to @var{port_width} the width +of the synchronous parallel port used for trace output. Parameter used only on +protocol @option{sync}. If not specified, default value is @var{1}. + +@item @code{-formatter} (@option{0}|@option{1}) -- specifies if the formatter +should be enabled. Parameter used only on protocol @option{sync}. If not specified, +default value is @var{0}. @end itemize +@end deffn + +@deffn Command {$tpiu_name enable} +Uses the parameters specified by the previous @command{$tpiu_name configure} +to configure and enable the TPIU or the SWO. +If required, the adapter is also configured and enabled to receive the trace +data. +This command can be used before @command{init}, but it will take effect only +after the @command{init}. +@end deffn + +@deffn Command {$tpiu_name disable} +Disable the TPIU or the SWO, terminating the receiving of the trace data. +@end deffn + + Example usage: @enumerate @@ -9270,12 +9670,20 @@ baud with our custom divisor to get 12MHz) @item OpenOCD invocation line: @example openocd -f interface/stlink.cfg \ - -c "transport select hla_swd" \ - -f target/stm32l1.cfg \ - -c "tpiu config external uart off 24000000 12000000" +-c "transport select hla_swd" \ +-f target/stm32l1.cfg \ +-c "stm32l1.tpiu configure -protocol uart" \ +-c "stm32l1.tpiu configure -traceclk 24000000 -pin-freq 12000000" \ +-c "stm32l1.tpiu enable" @end example @end enumerate -@end deffn + +@subsection ARMv7-M specific commands +@cindex tracing +@cindex SWO +@cindex SWV +@cindex ITM +@cindex ETM @deffn Command {itm port} @var{port} (@option{0}|@option{1}|@option{on}|@option{off}) Enable or disable trace output for ITM stimulus @var{port} (counting @@ -9809,7 +10217,7 @@ Perform a 32-bit DMI write of value at address. Synopsys DesignWare ARC Processors are a family of 32-bit CPUs that SoC designers can optimize for a wide range of uses, from deeply embedded to high-performance host applications in a variety of market segments. See more -at: http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx. +at: @url{http://www.synopsys.com/IP/ProcessorIP/ARCProcessors/Pages/default.aspx}. OpenOCD currently supports ARC EM processors. There is a set ARC-specific OpenOCD commands that allow low-level access to the core and provide necessary support for ARC extensibility and @@ -10361,28 +10769,6 @@ For quickstart instructions run: openocd -f tools/firmware-recovery.tcl -c firmware_help @end example -@node TFTP -@chapter TFTP -@cindex TFTP -If OpenOCD runs on an embedded host (as ZY1000 does), then TFTP can -be used to access files on PCs (either the developer's PC or some other PC). - -The way this works on the ZY1000 is to prefix a filename by -"/tftp/ip/" and append the TFTP path on the TFTP -server (tftpd). For example, - -@example -load_image /tftp/10.0.0.96/c:\temp\abc.elf -@end example - -will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as -if the file was hosted on the embedded host. - -In order to achieve decent performance, you must choose a TFTP server -that supports a packet size bigger than the default packet size (512 bytes). There -are numerous TFTP servers out there (free and commercial) and you will have to do -a bit of googling to find something that fits your requirements. - @node GDB and OpenOCD @chapter GDB and OpenOCD @cindex GDB @@ -10443,7 +10829,8 @@ target remote localhost:3333 @item A pipe connection is typically started as follows: @example -target extended-remote | openocd -c "gdb_port pipe; log_output openocd.log" +target extended-remote | \ + 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 @@ -10606,7 +10993,13 @@ of a running target. Do not use GDB commands @command{continue}, and GDB would require stopping the target to get the prompt back. Do not use this mode under an IDE like Eclipse as it caches values of -previously shown varibles. +previously shown variables. + +It's also possible to connect more than one GDB to the same target by the +target's configuration option @code{-gdb-max-connections}. This allows, for +example, one GDB to run a script that continuously polls a set of variables +while other GDB can be used interactively. Be extremely careful in this case, +because the two GDB can easily get out-of-sync. @section RTOS Support @cindex RTOS Support @@ -10651,17 +11044,11 @@ Cyg_Thread::thread_list, Cyg_Scheduler_Base::current_thread. @item ThreadX symbols _tx_thread_current_ptr, _tx_thread_created_ptr, _tx_thread_created_count. @item FreeRTOS symbols -@c The following is taken from recent texinfo to provide compatibility -@c with ancient versions that do not support @raggedright -@tex -\begingroup -\rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax +@raggedright pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1, xDelayedTaskList2, pxDelayedTaskList, pxOverflowDelayedTaskList, xPendingReadyList, uxCurrentNumberOfTasks, uxTopUsedPriority. -\par -\endgroup -@end tex +@end raggedright @item linux symbols init_task. @item ChibiOS symbols @@ -10672,11 +11059,14 @@ Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount. @item mqx symbols _mqx_kernel_data, MQX_init_struct. @item uC/OS-III symbols -OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty +OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty. @item nuttx symbols -g_readytorun, g_tasklisttable +g_readytorun, g_tasklisttable. @item RIOT symbols -sched_threads, sched_num_threads, sched_active_pid, max_threads, _tcb_name_offset +@raggedright +sched_threads, sched_num_threads, sched_active_pid, max_threads, +_tcb_name_offset. +@end raggedright @end table For most RTOS supported the above symbols will be exported by default. However for