X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=cd64c7aecbd34d600af1283f52dd378889e7b420;hp=c3963d6cbd9aac82a46ad99120981b18e9b097cc;hb=4afd8852bb320deea553504161bd2c79c434bb1b;hpb=de5c752102b54ca91895094fa6b867f0c20d21ac diff --git a/doc/openocd.texi b/doc/openocd.texi index c3963d6cbd..cd64c7aecb 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. @@ -2459,7 +2459,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. @@ -2632,47 +2632,47 @@ 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} +@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: @@ -2694,14 +2694,14 @@ instead of directly driving JTAG. The remote_bitbang driver is useful for debugging software running on processors which are being simulated. -@deffn {Config Command} {remote_bitbang_port} number +@deffn {Config Command} {remote_bitbang port} number Specifies the TCP port of the remote process to connect to or 0 to use UNIX sockets instead of TCP. @end deffn -@deffn {Config Command} {remote_bitbang_host} hostname +@deffn {Config Command} {remote_bitbang host} hostname Specifies the hostname of the remote process to connect to using TCP, or the -name of the UNIX socket to use if remote_bitbang_port is 0. +name of the UNIX socket to use if remote_bitbang port is 0. @end deffn For example, to connect remotely via TCP to the host foobar you might have @@ -2709,8 +2709,8 @@ something like: @example adapter driver remote_bitbang -remote_bitbang_port 3335 -remote_bitbang_host foobar +remote_bitbang port 3335 +remote_bitbang host foobar @end example To connect to another process running locally via UNIX sockets with socket @@ -2718,8 +2718,8 @@ named mysocket: @example adapter driver remote_bitbang -remote_bitbang_port 0 -remote_bitbang_host mysocket +remote_bitbang port 0 +remote_bitbang host mysocket @end example @end deffn @@ -2728,28 +2728,21 @@ 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 +@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. Currently, only one @var{vid}, @var{pid} pair may be given, e.g. for Altera USB-Blaster (default): @example -usb_blaster_vid_pid 0x09FB 0x6001 +usb_blaster vid_pid 0x09FB 0x6001 @end example The following VID/PID is for Kolja Waschk's USB JTAG: @example -usb_blaster_vid_pid 0x16C0 0x06AD +usb_blaster vid_pid 0x16C0 0x06AD @end example @end deffn -@deffn {Command} {usb_blaster_pin} (@option{pin6}|@option{pin8}) (@option{0}|@option{1}|@option{s}|@option{t}) +@deffn {Command} {usb_blaster pin} (@option{pin6}|@option{pin8}) (@option{0}|@option{1}|@option{s}|@option{t}) Sets the state or function of the unused GPIO pins on USB-Blasters (pins 6 and 8 on the female JTAG header). These pins can be used as SRST and/or TRST provided the appropriate connections are made on the @@ -2757,18 +2750,18 @@ target board. For example, to use pin 6 as SRST: @example -usb_blaster_pin pin6 s +usb_blaster pin pin6 s reset_config srst_only @end example @end deffn -@deffn {Config Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@option{ublast2}) +@deffn {Config Command} {usb_blaster lowlevel_driver} (@option{ftdi}|@option{ublast2}) Chooses the low level access method for the adapter. If not specified, @option{ftdi} is selected unless it wasn't enabled during the configure stage. USB-Blaster II needs @option{ublast2}. @end deffn -@deffn {Config Command} {usb_blaster_firmware} @var{path} +@deffn {Config Command} {usb_blaster firmware} @var{path} This command specifies @var{path} to access USB-Blaster II firmware image. To be used with USB-Blaster II only. @end deffn @@ -3033,7 +3026,7 @@ parport cable wiggler @deffn {Interface Driver} {presto} ASIX PRESTO USB JTAG programmer. -@deffn {Config Command} {presto_serial} serial_string +@deffn {Config Command} {presto serial} serial_string Configures the USB serial number of the Presto device to use. @end deffn @end deffn @@ -3131,6 +3124,26 @@ Specifies the serial number of the adapter. @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} @@ -3172,7 +3185,7 @@ exposed via extended capability registers in the PCI Express configuration space For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG mode). -@deffn {Config Command} {xlnx_pcie_xvc_config} device +@deffn {Config Command} {xlnx_pcie_xvc config} device Specifies the PCI Express device via parameter @var{device} to use. The correct value for @var{device} can be obtained by looking at the output @@ -3197,67 +3210,67 @@ configuration on exit. See @file{interface/raspberrypi-native.cfg} for a sample config and pinout. -@deffn {Config Command} {bcm2835gpio_jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo} +@deffn {Config Command} {bcm2835gpio jtag_nums} @var{tck} @var{tms} @var{tdi} @var{tdo} Set JTAG transport GPIO numbers for TCK, TMS, TDI, and TDO (in that order). Must be specified to enable JTAG transport. These pins can also be specified individually. @end deffn -@deffn {Config Command} {bcm2835gpio_tck_num} @var{tck} +@deffn {Config Command} {bcm2835gpio tck_num} @var{tck} Set TCK GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command bcm2835gpio_jtag_nums. +specified using the configuration command @command{bcm2835gpio jtag_nums}. @end deffn -@deffn {Config Command} {bcm2835gpio_tms_num} @var{tms} +@deffn {Config Command} {bcm2835gpio tms_num} @var{tms} Set TMS GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command bcm2835gpio_jtag_nums. +specified using the configuration command @command{bcm2835gpio jtag_nums}. @end deffn -@deffn {Config Command} {bcm2835gpio_tdo_num} @var{tdo} +@deffn {Config Command} {bcm2835gpio tdo_num} @var{tdo} Set TDO GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command bcm2835gpio_jtag_nums. +specified using the configuration command @command{bcm2835gpio jtag_nums}. @end deffn -@deffn {Config Command} {bcm2835gpio_tdi_num} @var{tdi} +@deffn {Config Command} {bcm2835gpio tdi_num} @var{tdi} Set TDI GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command bcm2835gpio_jtag_nums. +specified using the configuration command @command{bcm2835gpio jtag_nums}. @end deffn -@deffn {Config Command} {bcm2835gpio_swd_nums} @var{swclk} @var{swdio} +@deffn {Config Command} {bcm2835gpio swd_nums} @var{swclk} @var{swdio} Set SWD transport GPIO numbers for SWCLK and SWDIO (in that order). Must be specified to enable SWD transport. These pins can also be specified individually. @end deffn -@deffn {Config Command} {bcm2835gpio_swclk_num} @var{swclk} +@deffn {Config Command} {bcm2835gpio swclk_num} @var{swclk} Set SWCLK GPIO number. Must be specified to enable SWD transport. Can also be -specified using the configuration command bcm2835gpio_swd_nums. +specified using the configuration command @command{bcm2835gpio swd_nums}. @end deffn -@deffn {Config Command} {bcm2835gpio_swdio_num} @var{swdio} +@deffn {Config Command} {bcm2835gpio swdio_num} @var{swdio} Set SWDIO GPIO number. Must be specified to enable SWD transport. Can also be -specified using the configuration command bcm2835gpio_swd_nums. +specified using the configuration command @command{bcm2835gpio swd_nums}. @end deffn -@deffn {Config Command} {bcm2835gpio_swdio_dir_num} @var{swdio} @var{dir} +@deffn {Config Command} {bcm2835gpio swdio_dir_num} @var{swdio} @var{dir} Set SWDIO direction control pin GPIO number. If specified, this pin can be used to control the direction of an external buffer on the SWDIO pin (set=output mode, clear=input mode). If not specified, this feature is disabled. @end deffn -@deffn {Config Command} {bcm2835gpio_srst_num} @var{srst} +@deffn {Config Command} {bcm2835gpio srst_num} @var{srst} Set SRST GPIO number. Must be specified to enable SRST. @end deffn -@deffn {Config Command} {bcm2835gpio_trst_num} @var{trst} +@deffn {Config Command} {bcm2835gpio trst_num} @var{trst} Set TRST GPIO number. Must be specified to enable TRST. @end deffn -@deffn {Config Command} {bcm2835gpio_speed_coeffs} @var{speed_coeff} @var{speed_offset} +@deffn {Config Command} {bcm2835gpio speed_coeffs} @var{speed_coeff} @var{speed_offset} Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified, speed_coeff defaults to 113714, and speed_offset defaults to 28. @end deffn -@deffn {Config Command} {bcm2835gpio_peripheral_base} @var{base} +@deffn {Config Command} {bcm2835gpio peripheral_base} @var{base} Set the peripheral base register address to access GPIOs. For the RPi1, use 0x20000000. For RPi2 and RPi3, use 0x3F000000. For RPi4, use 0xFE000000. A full list can be found in the @@ -3321,11 +3334,11 @@ SystemVerilog Direct Programming Interface (DPI) compatible driver for JTAG devices in emulation. The driver acts as a client for the SystemVerilog DPI server interface. -@deffn {Config Command} {jtag_dpi_set_port} port +@deffn {Config Command} {jtag_dpi set_port} port Specifies the TCP/IP port number of the SystemVerilog DPI server interface. @end deffn -@deffn {Config Command} {jtag_dpi_set_address} address +@deffn {Config Command} {jtag_dpi set_address} address Specifies the TCP/IP address of the SystemVerilog DPI server interface. @end deffn @end deffn @@ -3339,21 +3352,21 @@ It uses a simple data protocol over a serial port connection. Most hardware development boards have a UART, a real serial port, or a virtual USB serial device, so this driver allows you to start building your own JTAG adapter without the complexity of a custom USB connection. -@deffn {Config Command} {buspirate_port} serial_port +@deffn {Config Command} {buspirate port} serial_port Specify the serial port's filename. For example: @example -buspirate_port /dev/ttyUSB0 +buspirate port /dev/ttyUSB0 @end example @end deffn -@deffn {Config Command} {buspirate_speed} (normal|fast) +@deffn {Config Command} {buspirate speed} (normal|fast) Set the communication speed to 115k (normal) or 1M (fast). For example: @example -buspirate_mode normal +buspirate speed normal @end example @end deffn -@deffn {Config Command} {buspirate_mode} (normal|open-drain) +@deffn {Config Command} {buspirate mode} (normal|open-drain) Set the Bus Pirate output mode. @itemize @minus @item In normal mode (push/pull), do not enable the pull-ups, and do not connect I/O header pin VPU to JTAG VREF. @@ -3361,33 +3374,33 @@ Set the Bus Pirate output mode. @end itemize For example: @example -buspirate_mode normal +buspirate mode normal @end example @end deffn -@deffn {Config Command} {buspirate_pullup} (0|1) +@deffn {Config Command} {buspirate pullup} (0|1) Whether to connect (1) or not (0) the I/O header pin VPU (JTAG VREF) to the pull-up/pull-down resistors on MOSI (JTAG TDI), CLK (JTAG TCK), MISO (JTAG TDO) and CS (JTAG TMS). For example: @example -buspirate_pullup 0 +buspirate pullup 0 @end example @end deffn -@deffn {Config Command} {buspirate_vreg} (0|1) +@deffn {Config Command} {buspirate vreg} (0|1) Whether to enable (1) or disable (0) the built-in voltage regulator, which can be used to supply power to a test circuit through I/O header pins +3V3 and +5V. For example: @example -buspirate_vreg 0 +buspirate vreg 0 @end example @end deffn -@deffn {Command} {buspirate_led} (0|1) +@deffn {Command} {buspirate led} (0|1) Turns the Bus Pirate's LED on (1) or off (0). For example: @end deffn @example -buspirate_led 1 +buspirate led 1 @end example @end deffn @@ -6777,6 +6790,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. @@ -7302,7 +7326,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 +7361,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 +7400,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 +7430,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}