X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=19ec31b34326abfc5decb2822220771ed94a642f;hb=c6460ea36d7eeaf4a0fe4fb1a4c65bb21547afbe;hp=40f4ab28419a8c60d878d34170161b4829d7527f;hpb=1549bad5b3de2c64b106475cfc23cfbccba2b8a3;p=fw%2Fopenocd diff --git a/doc/openocd.texi b/doc/openocd.texi index 40f4ab284..19ec31b34 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -265,7 +265,7 @@ listed in the Doxyfile configuration at the top of the source tree. All changes in the OpenOCD Git repository go through the web-based Gerrit Code Review System: -@uref{http://openocd.zylin.com/} +@uref{https://review.openocd.org/} After a one-time registration and repository setup, anyone can push commits from their local Git repository directly into Gerrit. @@ -2367,6 +2367,13 @@ The USB bus topology can be queried with the command @emph{lsusb -t} or @emph{dm This command is only available if your libusb1 is at least version 1.0.16. @end deffn +@deffn {Config Command} {adapter serial} serial_string +Specifies the @var{serial_string} of the adapter to use. +If this command is not specified, serial strings are not checked. +Only the following adapter drivers use the serial string from this command: +cmsis_dap, ft232r, ftdi, hla, jlink, kitprog, presto, st-link, vsllink, xds110. +@end deffn + @section Interface Drivers Each of the interface drivers listed here must be explicitly @@ -2419,11 +2426,6 @@ cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204 @end example @end deffn -@deffn {Config Command} {cmsis_dap_serial} [serial] -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: @@ -2459,7 +2461,7 @@ This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H. The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device, -bypassing intermediate libraries like libftdi or D2XX. +bypassing intermediate libraries like libftdi. Support for new FTDI based adapters can be added completely through configuration files, without the need to patch and rebuild OpenOCD. @@ -2508,15 +2510,6 @@ of the adapter. If not specified, the device description is ignored during device selection. @end deffn -@deffn {Config Command} {ftdi serial} serial-number -Specifies the @var{serial-number} of the adapter to use, -in case the vendor provides unique IDs and more than one adapter -is connected to the host. -If not specified, serial numbers are not considered. -(Note that USB serial numbers can be arbitrary Unicode strings, -and are not restricted to containing only decimal digits.) -@end deffn - @deffn {Config Command} {ftdi channel} channel Selects the channel of the FTDI device to use for MPSSE operations. Most adapters use the default, channel 0, but there are exceptions. @@ -2632,47 +2625,41 @@ FT232R These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain: -@deffn {Config Command} {ft232r_vid_pid} @var{vid} @var{pid} +@deffn {Config Command} {ft232r vid_pid} @var{vid} @var{pid} The vendor ID and product ID of the adapter. If not specified, default 0x0403:0x6001 is used. @end deffn -@deffn {Config Command} {ft232r_serial_desc} @var{serial} -Specifies the @var{serial} of the adapter to use, in case the -vendor provides unique IDs and more than one adapter is connected to -the host. If not specified, serial numbers are not considered. -@end deffn - -@deffn {Config Command} {ft232r_jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo} +@deffn {Config Command} {ft232r jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo} Set four JTAG GPIO numbers at once. If not specified, default 0 3 1 2 or TXD CTS RXD RTS is used. @end deffn -@deffn {Config Command} {ft232r_tck_num} @var{tck} +@deffn {Config Command} {ft232r tck_num} @var{tck} Set TCK GPIO number. If not specified, default 0 or TXD is used. @end deffn -@deffn {Config Command} {ft232r_tms_num} @var{tms} +@deffn {Config Command} {ft232r tms_num} @var{tms} Set TMS GPIO number. If not specified, default 3 or CTS is used. @end deffn -@deffn {Config Command} {ft232r_tdi_num} @var{tdi} +@deffn {Config Command} {ft232r tdi_num} @var{tdi} Set TDI GPIO number. If not specified, default 1 or RXD is used. @end deffn -@deffn {Config Command} {ft232r_tdo_num} @var{tdo} +@deffn {Config Command} {ft232r tdo_num} @var{tdo} Set TDO GPIO number. If not specified, default 2 or RTS is used. @end deffn -@deffn {Config Command} {ft232r_trst_num} @var{trst} +@deffn {Config Command} {ft232r trst_num} @var{trst} Set TRST GPIO number. If not specified, default 4 or DTR is used. @end deffn -@deffn {Config Command} {ft232r_srst_num} @var{srst} +@deffn {Config Command} {ft232r srst_num} @var{srst} Set SRST GPIO number. If not specified, default 6 or DCD is used. @end deffn -@deffn {Config Command} {ft232r_restore_serial} @var{word} +@deffn {Config Command} {ft232r restore_serial} @var{word} Restore serial port after JTAG. This USB bitmode control word (16-bit) will be sent before quit. Lower byte should set GPIO direction register to a "sane" state: @@ -2728,13 +2715,6 @@ USB JTAG/USB-Blaster compatibles over one of the userspace libraries for FTDI chips. These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain: -@deffn {Config Command} {usb_blaster device_desc} description -Provides the USB device description (the @emph{iProduct string}) -of the FTDI FT245 device. If not -specified, the FTDI default value is used. This setting is only valid -if compiled with FTD2XX support. -@end deffn - @deffn {Config Command} {usb_blaster vid_pid} vid pid The vendor ID and product ID of the FTDI FT245 device. If not specified, default values are used. @@ -2840,7 +2820,7 @@ Reset the current configuration. @deffn {Command} {jlink config write} Write the current configuration to the internal persistent storage. @end deffn -@deffn {Command} {jlink emucom write } +@deffn {Command} {jlink emucom write} Write data to an EMUCOM channel. The data needs to be encoded as hexadecimal pairs. @@ -2850,7 +2830,7 @@ the EMUCOM channel 0x10: > jlink emucom write 0x10 aa0b23 @end example @end deffn -@deffn {Command} {jlink emucom read } +@deffn {Command} {jlink emucom read} Read data from an EMUCOM channel. The read data is encoded as hexadecimal pairs. @@ -2866,12 +2846,6 @@ to the host. If not specified, USB addresses are not considered. Device 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 -@deffn {Config Command} {jlink serial} -Set the serial number of the interface, in case more than one adapter is -connected to the host. If not specified, serial numbers are not considered. - As a configuration command, it can be used only before 'init'. @end deffn @end deffn @@ -2914,11 +2888,6 @@ Indicate that a PSoC acquisition sequence needs to be run during adapter init. Please be aware that the acquisition sequence hard-resets the target. @end deffn -@deffn {Config Command} {kitprog_serial} serial -Select a KitProg device by its @var{serial}. If left unspecified, the first -device detected by OpenOCD will be used. -@end deffn - @deffn {Command} {kitprog acquire_psoc} Run a PSoC acquisition sequence immediately. Typically, this should not be used outside of the target-specific configuration scripts since it hard-resets the @@ -3033,9 +3002,6 @@ parport cable wiggler @deffn {Interface Driver} {presto} ASIX PRESTO USB JTAG programmer. -@deffn {Config Command} {presto serial} serial_string -Configures the USB serial number of the Presto device to use. -@end deffn @end deffn @deffn {Interface Driver} {rlink} @@ -3072,10 +3038,6 @@ version reported is V2.J21.S4. Currently Not Supported. @end deffn -@deffn {Config Command} {hla_serial} serial -Specifies the serial number of the adapter. -@end deffn - @deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}|@option{nulink}) Specifies the adapter layout to use. @end deffn @@ -3124,13 +3086,29 @@ 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 - @deffn {Config Command} {st-link vid_pid} [vid pid]+ Pairs of vendor IDs and product IDs of the device. @end deffn + +@deffn {Command} {st-link cmd} rx_n (tx_byte)+ +Sends an arbitrary command composed by the sequence of bytes @var{tx_byte} +and receives @var{rx_n} bytes. + +For example, the command to read the target's supply voltage is one byte 0xf7 followed +by 15 bytes zero. It returns 8 bytes, where the first 4 bytes represent the ADC sampling +of the reference voltage 1.2V and the last 4 bytes represent the ADC sampling of half +the target's supply voltage. +@example +> st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0xf1 0x05 0x00 0x00 0x0b 0x08 0x00 0x00 +@end example +The result can be converted to Volts (ignoring the most significant bytes, always zero) +@example +> set a [st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0] +> echo [expr 2*1.2*([lindex $a 4]+256*[lindex $a 5])/([lindex $a 0]+256*[lindex $a 1])] +3.24891518738 +@end example +@end deffn @end deffn @deffn {Interface Driver} {opendous} @@ -3147,11 +3125,6 @@ LaunchPad evaluation boards. The XDS110 is also available as a stand-alone USB debug probe with the added capability to supply power to the target board. The following commands are supported by the XDS110 driver: -@deffn {Config Command} {xds110 serial} serial_string -Specifies the serial number of which XDS110 probe to use. Otherwise, the first -XDS110 found will be used. -@end deffn - @deffn {Config Command} {xds110 supply} voltage_in_millivolts Available only on the XDS110 stand-alone probe. Sets the voltage level of the XDS110 power supply. A value of 0 leaves the supply off. Otherwise, the supply @@ -3194,6 +3167,8 @@ able to coexist nicely with both sysfs bitbanging and various peripherals' kernel drivers. The driver restores the previous configuration on exit. +GPIO numbers >= 32 can't be used for performance reasons. + See @file{interface/raspberrypi-native.cfg} for a sample config and pinout. @@ -3456,11 +3431,6 @@ Declares a single DAP which uses SWD transport. Parameters are currently the same as "jtag newtap" but this is expected to change. @end deffn -@deffn {Command} {swd wcr trn prescale} -Updates TRN (turnaround delay) and prescaling.fields of the -Wire Control Register (WCR). -No parameters: displays current settings. -@end deffn @subsection SPI Transport @cindex SPI @@ -4389,6 +4359,20 @@ A DAP may also provide optional @var{configparams}: register during initial examination and when checking the sticky error bit. This bit is normally checked after setting the CSYSPWRUPREQ bit, but some devices do not set the ack bit until sometime later. + +@item @code{-dp-id} @var{number} +@*Debug port identification number for SWD DPv2 multidrop. +The @var{number} is written to bits 0..27 of DP TARGETSEL during DP selection. +To find the id number of a single connected device read DP TARGETID: +@code{device.dap dpreg 0x24} +Use bits 0..27 of TARGETID. + +@item @code{-instance-id} @var{number} +@*Instance identification number for SWD DPv2 multidrop. +The @var{number} is written to bits 28..31 of DP TARGETSEL during DP selection. +To find the instance number of a single connected device read DP DLPIDR: +@code{device.dap dpreg 0x34} +The instance number is in bits 28..31 of DLPIDR value. @end itemize @end deffn @@ -5565,6 +5549,10 @@ will not work. These include all @command{*_image} and functionality is available through the @command{flash write_bank}, @command{flash read_bank}, and @command{flash verify_bank} commands. +According to device size, 1- to 4-byte addresses are sent. However, some +flash chips additionally have to be switched to 4-byte addresses by an extra +command, see below. + @itemize @item @var{ir} ... is loaded into the JTAG IR to map the flash as the JTAG DR. For the bitstreams generated from @file{xilinx_bscan_spi.py} this is the @@ -5577,6 +5565,29 @@ set _XILINX_USER1 0x02 flash bank $_FLASHNAME spi 0x0 0 0 0 \ $_TARGETNAME $_XILINX_USER1 @end example + +@deffn Command {jtagspi set} bank_id name total_size page_size read_cmd unused pprg_cmd mass_erase_cmd sector_size sector_erase_cmd +Sets flash parameters: @var{name} human readable string, @var{total_size} +size in bytes, @var{page_size} is write page size. @var{read_cmd} and @var{pprg_cmd} +are commands for read and page program, respectively. @var{mass_erase_cmd}, +@var{sector_size} and @var{sector_erase_cmd} are optional. +@example +jtagspi set 0 w25q128 0x1000000 0x100 0x03 0 0x02 0xC7 0x10000 0xD8 +@end example +@end deffn + +@deffn Command {jtagspi cmd} bank_id resp_num cmd_byte ... +Sends command @var{cmd_byte} and at most 20 following bytes and reads +@var{resp_num} bytes afterwards. E.g. for 'Enter 4-byte address mode' +@example +jtagspi cmd 0 0 0xB7 +@end example +@end deffn + +@deffn Command {jtagspi always_4byte} bank_id [ on | off ] +Some devices use 4-byte addresses for all commands except the legacy 0x03 read +regardless of device size. This command controls the corresponding hack. +@end deffn @end deffn @deffn {Flash Driver} {xcf} @@ -6777,6 +6788,17 @@ Show information about flash driver. @end deffn +@deffn {Flash Driver} {npcx} +All versions of the NPCX microcontroller families from Nuvoton include internal +flash. The NPCX flash driver supports the NPCX family of devices. The driver +automatically recognizes the specific version's flash parameters and +autoconfigures itself. The flash bank starts at address 0x64000000. + +@example +flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME +@end example +@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. @@ -7067,8 +7089,8 @@ applied to all of them. @deffn {Flash Driver} {stm32f1x} All members of the STM32F0, STM32F1 and STM32F3 microcontroller families -from STMicroelectronics and all members of the GD32F1x0 and GD32F3x0 microcontroller -families from GigaDevice include internal flash and use ARM Cortex-M0/M3/M4 cores. +from STMicroelectronics and all members of the GD32F1x0, GD32F3x0 and GD32E23x microcontroller +families from GigaDevice include internal flash and use ARM Cortex-M0/M3/M4/M23 cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -7144,7 +7166,7 @@ as per the following example. flash bank $_FLASHNAME stm32f2x 0x1FFF7800 0 0 0 $_TARGETNAME @end example -@deffn {Command} {stm32f2x otp } num (@option{enable}|@option{disable}|@option{show}) +@deffn {Command} {stm32f2x otp} num (@option{enable}|@option{disable}|@option{show}) Enables or disables OTP write commands for bank @var{num}. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @@ -7302,7 +7324,7 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @deffn {Flash Driver} {stm32l4x} -All members of the STM32 G0, G4, L4, L4+, L5, WB and WL +All members of the STM32 G0, G4, L4, L4+, L5, U5, WB and WL microcontroller families from STMicroelectronics include internal flash and use ARM Cortex-M0+, M4 and M33 cores. The driver automatically recognizes a number of these chips using @@ -7337,11 +7359,15 @@ Some stm32l4x-specific commands are defined: @deffn {Command} {stm32l4x lock} num Locks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. + +@emph{Note:} To apply the protection change immediately, use @command{stm32l4x option_load}. @end deffn @deffn {Command} {stm32l4x unlock} num Unlocks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. + +@emph{Note:} To apply the protection change immediately, use @command{stm32l4x option_load}. @end deffn @deffn {Command} {stm32l4x mass_erase} num @@ -7372,6 +7398,8 @@ The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offs 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). +@emph{Note:} To apply the option bytes change immediately, use @command{stm32l4x option_load}. + For example to write the WRP1AR option bytes: @example stm32l4x option_write 0 0x28 0x00FF0000 0x00FF00FF @@ -7400,6 +7428,14 @@ write protected areas in a specific @var{device_bank} Forces a re-load of the option byte registers. Will cause a system reset of the device. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn + +@deffn Command {stm32l4x trustzone} num [@option{enable} | @option{disable}] +Enables or disables Global TrustZone Security, using the TZEN option bit. +If neither @option{enabled} nor @option{disable} are specified, the command will display +the TrustZone status. +@emph{Note:} This command works only with devices with TrustZone, eg. STM32L5. +@emph{Note:} This command will perform an OBL_Launch after modifying the TZEN. +@end deffn @end deffn @deffn {Flash Driver} {str7x} @@ -7567,7 +7603,7 @@ Some tms470-specific commands are defined: Saves programming keys in a register, to enable flash erase and write commands. @end deffn -@deffn {Command} {tms470 osc_mhz} clock_mhz +@deffn {Command} {tms470 osc_megahertz} clock_mhz Reports the clock speed, which is used to calculate timings. @end deffn @@ -8602,7 +8638,7 @@ If the control block location is not known, OpenOCD starts searching for it. Stop RTT. @end deffn -@deffn {Command} {rtt polling_interval [interval]} +@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 @@ -8950,7 +8986,7 @@ Enable (@option{on}) or disable (@option{off}) the CTI. Displays a register dump of the CTI. @end deffn -@deffn {Command} {$cti_name write } @var{reg_name} @var{value} +@deffn {Command} {$cti_name write} @var{reg_name} @var{value} Write @var{value} to the CTI register with the symbolic name @var{reg_name}. @end deffn @@ -9457,7 +9493,7 @@ cores @emph{except the ARM1176} use the same six bits. display information about target caches @end deffn -@deffn {Command} {cortex_a dacrfixup [@option{on}|@option{off}]} +@deffn {Command} {cortex_a dacrfixup} [@option{on}|@option{off}] Work around issues with software breakpoints when the program text is mapped read-only by the operating system. This option sets the CP15 DACR to "all-manager" to bypass MMU permission checks on memory access. @@ -9495,12 +9531,12 @@ possible (4096) entries are printed. @subsection ARMv7-R specific commands @cindex Cortex-R -@deffn {Command} {cortex_r dbginit} +@deffn {Command} {cortex_r4 dbginit} Initialize core debug Enables debug by unlocking the Software Lock and clearing sticky powerdown indications @end deffn -@deffn {Command} {cortex_r maskisr} [@option{on}|@option{off}] +@deffn {Command} {cortex_r4 maskisr} [@option{on}|@option{off}] Selects whether interrupts will be processed when single stepping @end deffn @@ -10063,14 +10099,6 @@ included in the generated target descriptor file. addreg rtest 0x1234 org.gnu.gdb.or1k.group0 system @end example - -@end deffn -@deffn {Command} {readgroup} (@option{group}) -Display all registers in @emph{group}. - -@emph{group} can be "system", - "dmmu", "immu", "dcache", "icache", "mac", "debug", "perf", "power", "pic", - "timer" or any new group created with addreg command. @end deffn @section RISC-V Architecture @@ -10118,11 +10146,6 @@ 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 (default), prefer to use the Program Buffer to access memory.