X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=27a552286f1cb7445c851473414edba0ed09163e;hb=ace028262ba0bda0e921afb11e6eb7d87708d889;hp=f678621ee00decfbfc313c2ec3e670cc37c410fa;hpb=2053120ba10d68339c61cd2b247bde01bda41ab7;p=fw%2Fopenocd diff --git a/doc/openocd.texi b/doc/openocd.texi index f678621ee..27a552286 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -594,8 +594,8 @@ produced, PDF schematics are easily found and it is easy to make. @item @b{vdebug} @* A driver for Cadence virtual Debug Interface to emulated or simulated targets. It implements a client connecting to the vdebug server, which in turn communicates -with the emulated or simulated RTL model through a transactor. The current version -supports only JTAG as a transport, but other virtual transports, like DAP are planned. +with the emulated or simulated RTL model through a transactor. The driver supports +JTAG and DAP-level transports. @item @b{jtag_dpi} @* A JTAG driver acting as a client for the SystemVerilog Direct Programming @@ -613,6 +613,9 @@ emulation model of target hardware. @* A bitbang JTAG driver using Linux legacy sysfs GPIO. This is deprecated from Linux v5.3; prefer using @b{linuxgpiod}. +@item @b{esp_usb_jtag} +@* A JTAG driver to communicate with builtin debug modules of Espressif ESP32-C3 and ESP32-S3 chips using OpenOCD. + @end itemize @node About Jim-Tcl @@ -2409,7 +2412,57 @@ when external configuration (such as jumpering) changes what the hardware can support. @end deffn +@anchor{adapter gpio} +@deffn {Config Command} {adapter gpio [ @ + @option{tdo} | @option{tdi} | @option{tms} | @option{tck} | @option{trst} | @ + @option{swdio} | @option{swdio_dir} | @option{swclk} | @option{srst} | @ + @option{led} @ + [ @ + gpio_number | @option{-chip} chip_number | @ + @option{-active-high} | @option{-active-low} | @ + @option{-push-pull} | @option{-open-drain} | @option{-open-source} | @ + @option{-pull-none} | @option{-pull-up} | @option{-pull-down} | @ + @option{-init-inactive} | @option{-init-active} | @option{-init-input} @ + ] ]} + +Define the GPIO mapping that the adapter will use. The following signals can be +defined: + +@itemize @minus +@item @option{tdo}, @option{tdi}, @option{tms}, @option{tck}, @option{trst}: +JTAG transport signals +@item @option{swdio}, @option{swclk}: SWD transport signals +@item @option{swdio_dir}: optional swdio buffer control signal +@item @option{srst}: system reset signal +@item @option{led}: optional activity led + +@end itemize +Some adapters require that the GPIO chip number is set in addition to the GPIO +number. The configuration options enable signals to be defined as active-high or +active-low. The output drive mode can be set to push-pull, open-drain or +open-source. Most adapters will have to emulate open-drain or open-source drive +modes by switching between an input and output. Input and output signals can be +instructed to use a pull-up or pull-down resistor, assuming it is supported by +the adaptor driver and hardware. The initial state of outputs may also be set, +"active" state means 1 for active-high outputs and 0 for active-low outputs. +Bidirectional signals may also be initialized as an input. If the swdio signal +is buffered the buffer direction can be controlled with the swdio_dir signal; +the active state means that the buffer should be set as an output with respect +to the adapter. The command options are cumulative with later commands able to +override settings defined by earlier ones. The two commands @command{gpio led 7 +-active-high} and @command{gpio led -chip 1 -active-low} sent sequentially are +equivalent to issuing the single command @command{gpio led 7 -chip 1 +-active-low}. It is not permissible to set the drive mode or initial state for +signals which are inputs. The drive mode for the srst and trst signals must be +set with the @command{adapter reset_config} command. It is not permissible to +set the initial state of swdio_dir as it is derived from the initial state of +swdio. The command @command{adapter gpio} prints the current configuration for +all GPIOs while the command @command{adapter gpio gpio_name} prints the current +configuration for gpio_name. Not all adapters support this generic GPIO mapping, +some require their own commands to define the GPIOs used. Adapters that support +the generic mapping may not support all of the listed options. +@end deffn @deffn {Command} {adapter name} Returns the name of the debug adapter driver being used. @@ -3334,86 +3387,16 @@ registers directly. The memory mapping requires read and write permission to kernel memory; if /dev/gpiomem exists it will be used, otherwise /dev/mem will be used. The driver restores the GPIO state on exit. -All four GPIO ports are available. GPIOs numbered 0 to 31 are mapped to GPIO port -0, GPIO numbers 32 to 63 are mapped to GPIO port 1 and so on. - -See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file. - -@deffn {Config Command} {am335xgpio 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} {am335xgpio tck_num} @var{tck} -Set TCK GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command @command{am335xgpio jtag_nums}. -@end deffn - -@deffn {Config Command} {am335xgpio tms_num} @var{tms} -Set TMS GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command @command{am335xgpio jtag_nums}. -@end deffn - -@deffn {Config Command} {am335xgpio tdo_num} @var{tdo} -Set TDO GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command @command{am335xgpio jtag_nums}. -@end deffn - -@deffn {Config Command} {am335xgpio tdi_num} @var{tdi} -Set TDI GPIO number. Must be specified to enable JTAG transport. Can also be -specified using the configuration command @command{am335xgpio jtag_nums}. -@end deffn - -@deffn {Config Command} {am335xgpio 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} {am335xgpio swclk_num} @var{swclk} -Set SWCLK GPIO number. Must be specified to enable SWD transport. Can also be -specified using the configuration command @command{am335xgpio swd_nums}. -@end deffn - -@deffn {Config Command} {am335xgpio swdio_num} @var{swdio} -Set SWDIO GPIO number. Must be specified to enable SWD transport. Can also be -specified using the configuration command @command{am335xgpio swd_nums}. -@end deffn - -@deffn {Config Command} {am335xgpio swdio_dir_num} @var{swdio_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. The direction -control state can be set with the command @command{am335xgpio -swdio_dir_output_state}. If not specified this feature is disabled. -@end deffn - -@deffn {Config Command} {am335xgpio swdio_dir_output_state} @var{output_state} -Set the state required for an external SWDIO buffer to be an output. Valid -values are @option{on} (default) and @option{off}. -@end deffn - -@deffn {Config Command} {am335xgpio srst_num} @var{srst} -Set SRST GPIO number. Must be specified to enable SRST. -@end deffn - -@deffn {Config Command} {am335xgpio trst_num} @var{trst} -Set TRST GPIO number. Must be specified to enable TRST. -@end deffn - -@deffn {Config Command} {am335xgpio led_num} @var{led} -Set activity LED GPIO number. If not specified an activity LED is not enabled. -@end deffn - -@deffn {Config Command} {am335xgpio led_on_state} @var{on_state} -Set required logic level for the LED to be on. Valid values are @option{on} -(default) and @option{off}. -@end deffn +All four GPIO ports are available. GPIO configuration is handled by the generic +command @ref{adapter gpio, @command{adapter gpio}}. @deffn {Config Command} {am335xgpio speed_coeffs} @var{speed_coeff} @var{speed_offset} Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If unspecified speed_coeff defaults to 600000 and speed_offset defaults to 575. @end deffn +See @file{interface/beaglebone-swd-native.cfg} for a sample configuration file. + @end deffn @@ -3643,6 +3626,44 @@ buspirate led 1 @end deffn +@deffn {Interface Driver} {esp_usb_jtag} +Espressif JTAG driver to communicate with ESP32-C3, ESP32-S3 chips and ESP USB Bridge board using OpenOCD. +These chips have built-in JTAG circuitry and can be debugged without any additional hardware. +Only an USB cable connected to the D+/D- pins is necessary. + +@deffn {Config Command} {espusbjtag tdo} +Returns the current state of the TDO line +@end deffn + +@deffn {Config Command} {espusbjtag setio} setio +Manually set the status of the output lines with the order of (tdi tms tck trst srst) +@example +espusbjtag setio 0 1 0 1 0 +@end example +@end deffn + +@deffn {Config Command} {espusbjtag vid_pid} vid_pid +Set vendor ID and product ID for the ESP usb jtag driver +@example +espusbjtag vid_pid 0x303a 0x1001 +@end example +@end deffn + +@deffn {Config Command} {espusbjtag caps_descriptor} caps_descriptor +Set the jtag descriptor to read capabilities of ESP usb jtag driver +@example +espusbjtag caps_descriptor 0x2000 +@end example +@end deffn + +@deffn {Config Command} {espusbjtag chip_id} chip_id +Set chip id to transfer to the ESP USB bridge board +@example +espusbjtag chip_id 1 +@end example +@end deffn + +@end deffn @section Transport Configuration @cindex Transport @@ -4795,6 +4816,10 @@ Set/get quirks mode for TI TMS450/TMS570 processors Disabled by default @end deffn +@deffn {Config Command} {$dap_name nu_npcx_quirks} [@option{enable}] +Set/get quirks mode for Nuvoton NPCX/NPCD MCU families +Disabled by default +@end deffn @node CPU Configuration @chapter CPU Configuration @@ -5104,7 +5129,7 @@ The value should normally correspond to a static mapping for the @anchor{rtostype} @item @code{-rtos} @var{rtos_type} -- enable rtos support for target, -@var{rtos_type} can be one of @option{auto}, @option{eCos}, +@var{rtos_type} can be one of @option{auto}, @option{none}, @option{eCos}, @option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS}, @option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx}, @option{RIOT}, @option{Zephyr} @@ -11803,6 +11828,11 @@ Currently supported rtos's include: @item @option{Zephyr} @end itemize +At any time, it's possible to drop the selected RTOS using: +@example +$_TARGETNAME configure -rtos none +@end example + Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot be used by OpenOCD. Below is a list of the required symbols for each supported RTOS.