X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=b495505117cbb0969acaf1c80dc7274dcc5770dc;hb=1d4b252bb16ef823d8e98bd70fc323099033898b;hp=4dd3a3389d62a9006d3c0cf30b6f0b6ba7d03147;hpb=642cdae32167df80d4dc757f0da5f204e0298088;p=openocd.git

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 4dd3a3389d..b495505117 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -315,7 +315,7 @@ There are several things you should keep in mind when choosing a dongle.
 
 @enumerate
 @item @b{Transport} Does it support the kind of communication that you need?
-OpenOCD focusses mostly on JTAG. Your version may also support
+OpenOCD focuses mostly on JTAG. Your version may also support
 other ways to communicate with target devices.
 @item @b{Voltage} What voltage is your target - 1.8, 2.8, 3.3, or 5V?
 Does your dongle support it? You might need a level converter.
@@ -2466,10 +2466,10 @@ configuration files, without the need to patch and rebuild OpenOCD.
 
 The driver uses a signal abstraction to enable Tcl configuration files to
 define outputs for one or several FTDI GPIO. These outputs can then be
-controlled using the @command{ftdi_set_signal} command. Special signal names
+controlled using the @command{ftdi set_signal} command. Special signal names
 are reserved for nTRST, nSRST and LED (for blink) so that they, if defined,
 will be used for their customary purpose. Inputs can be read using the
-@command{ftdi_get_signal} command.
+@command{ftdi get_signal} command.
 
 To support SWD, a signal named SWD_EN must be defined. It is set to 1 when the
 SWD protocol is selected. When set, the adapter should route the SWDIO pin to
@@ -2494,21 +2494,21 @@ signal. The following output buffer configurations are supported:
 These interfaces have several commands, used to configure the driver
 before initializing the JTAG scan chain:
 
-@deffn {Config Command} {ftdi_vid_pid} [vid pid]+
+@deffn {Config Command} {ftdi vid_pid} [vid pid]+
 The vendor ID and product ID of the adapter. Up to eight
 [@var{vid}, @var{pid}] pairs may be given, e.g.
 @example
-ftdi_vid_pid 0x0403 0xcff8 0x15ba 0x0003
+ftdi vid_pid 0x0403 0xcff8 0x15ba 0x0003
 @end example
 @end deffn
 
-@deffn {Config Command} {ftdi_device_desc} description
+@deffn {Config Command} {ftdi device_desc} description
 Provides the USB device description (the @emph{iProduct string})
 of the adapter. If not specified, the device description is ignored
 during device selection.
 @end deffn
 
-@deffn {Config Command} {ftdi_serial} serial-number
+@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.
@@ -2517,12 +2517,12 @@ If not specified, serial numbers are not considered.
 and are not restricted to containing only decimal digits.)
 @end deffn
 
-@deffn {Config Command} {ftdi_channel} channel
+@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.
 @end deffn
 
-@deffn {Config Command} {ftdi_layout_init} data direction
+@deffn {Config Command} {ftdi layout_init} data direction
 Specifies the initial values of the FTDI GPIO data and direction registers.
 Each value is a 16-bit number corresponding to the concatenation of the high
 and low FTDI GPIO registers. The values should be selected based on the
@@ -2531,7 +2531,7 @@ minimal impact on the target system. Avoid floating inputs, conflicting outputs
 and initially asserted reset signals.
 @end deffn
 
-@deffn {Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-input}|@option{-ninput} input_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name]
+@deffn {Command} {ftdi layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-input}|@option{-ninput} input_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name]
 Creates a signal with the specified @var{name}, controlled by one or more FTDI
 GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO
 register bitmasks to tell the driver the connection and type of the output
@@ -2541,7 +2541,7 @@ used with inverting data inputs and @option{-data} with non-inverting inputs.
 The @option{-oe} (or @option{-noe}) option tells where the output-enable (or
 not-output-enable) input to the output buffer is connected. The options
 @option{-input} and @option{-ninput} specify the bitmask for pins to be read
-with the method @command{ftdi_get_signal}.
+with the method @command{ftdi get_signal}.
 
 Both @var{data_mask} and @var{oe_mask} need not be specified. For example, a
 simple open-collector transistor driver would be specified with @option{-oe}
@@ -2562,7 +2562,7 @@ identical (or with data inverted) to an already specified signal
 @var{name}.
 @end deffn
 
-@deffn {Command} {ftdi_set_signal} name @option{0}|@option{1}|@option{z}
+@deffn {Command} {ftdi set_signal} name @option{0}|@option{1}|@option{z}
 Set a previously defined signal to the specified level.
 @itemize @minus
 @item @option{0}, drive low
@@ -2571,11 +2571,11 @@ Set a previously defined signal to the specified level.
 @end itemize
 @end deffn
 
-@deffn {Command} {ftdi_get_signal} name
+@deffn {Command} {ftdi get_signal} name
 Get the value of a previously defined signal.
 @end deffn
 
-@deffn {Command} {ftdi_tdo_sample_edge} @option{rising}|@option{falling}
+@deffn {Command} {ftdi tdo_sample_edge} @option{rising}|@option{falling}
 Configure TCK edge at which the adapter samples the value of the TDO signal
 
 Due to signal propagation delays, sampling TDO on rising TCK can become quite
@@ -3264,6 +3264,68 @@ Specifies the TCP/IP address of the SystemVerilog DPI server interface.
 @end deffn
 
 
+@deffn {Interface Driver} {buspirate}
+
+This driver is for the Bus Pirate (see @url{http://dangerousprototypes.com/docs/Bus_Pirate}) and compatible devices.
+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
+Specify the serial port's filename. For example:
+@example
+buspirate_port /dev/ttyUSB0
+@end example
+@end deffn
+
+@deffn {Config Command} {buspirate_speed} (normal|fast)
+Set the communication speed to 115k (normal) or 1M (fast). For example:
+@example
+buspirate_mode normal
+@end example
+@end deffn
+
+@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.
+@item In open drain mode, you will then need to enable the pull-ups.
+@end itemize
+For example:
+@example
+buspirate_mode normal
+@end example
+@end deffn
+
+@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
+@end example
+@end deffn
+
+@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
+@end example
+@end deffn
+
+@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
+@end example
+
+@end deffn
+
+
 @section Transport Configuration
 @cindex Transport
 As noted earlier, depending on the version of OpenOCD you use,
@@ -4500,7 +4562,7 @@ a CPU, through which bus read and write cycles can be generated; it may be
 useful for working with non-CPU hardware behind an AP or during development of
 support for new CPUs.
 It's possible to connect a GDB client to this target (the GDB port has to be
-specified, @xref{gdbportoverride,,option -gdb-port}), and a fake ARM core will
+specified, @xref{gdbportoverride,,option -gdb-port}.), and a fake ARM core will
 be emulated to comply to GDB remote protocol.
 @item @code{mips_m4k} -- a MIPS core.
 @item @code{mips_mips64} -- a MIPS64 core.
@@ -4681,7 +4743,7 @@ The value should normally correspond to a static mapping for the
 @var{rtos_type} can be one of @option{auto}, @option{eCos},
 @option{ThreadX}, @option{FreeRTOS}, @option{linux}, @option{ChibiOS},
 @option{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx},
-@option{RIOT}
+@option{RIOT}, @option{Zephyr}
 @xref{gdbrtossupport,,RTOS Support}.
 
 @item @code{-defer-examine} -- skip target examination at initial JTAG chain
@@ -4759,8 +4821,8 @@ They are not otherwise documented here.
 @deffn {Command} {$target_name array2mem} arrayname width address count
 @deffnx {Command} {$target_name mem2array} arrayname width address count
 These provide an efficient script-oriented interface to memory.
-The @code{array2mem} primitive writes bytes, halfwords, or words;
-while @code{mem2array} reads them.
+The @code{array2mem} primitive writes bytes, halfwords, words
+or double-words; while @code{mem2array} reads them.
 In both cases, the TCL side uses an array, and
 the target side uses raw memory.
 
@@ -4773,7 +4835,7 @@ and neither store nor return those values.
 
 @itemize
 @item @var{arrayname} ... is the name of an array variable
-@item @var{width} ... is 8/16/32 - indicating the memory access size
+@item @var{width} ... is 8/16/32/64 - indicating the memory access size
 @item @var{address} ... is the target memory address
 @item @var{count} ... is the number of elements to process
 @end itemize
@@ -5577,7 +5639,7 @@ 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,
+but only after proper controller initialization as described above. However,
 due to a silicon bug in some devices, attempting to access the very last word
 should be avoided.
 
@@ -6876,6 +6938,17 @@ Note: only Main and Work flash regions support Erase operation.
 @end deffn
 @end deffn
 
+@deffn {Flash Driver} {rp2040}
+Supports RP2040 "Raspberry Pi Pico" microcontroller.
+RP2040 is a dual-core device with two CM0+ cores. Both cores share the same
+Flash/RAM/MMIO address space.  Non-volatile storage is achieved with an
+external QSPI flash; a Boot ROM provides helper functions.
+
+@example
+flash bank $_FLASHNAME rp2040_flash $_FLASHBASE $_FLASHSIZE 1 32 $_TARGETNAME
+@end example
+@end deffn
+
 @deffn {Flash Driver} {sim3x}
 All members of the SiM3 microcontroller family from Silicon Laboratories
 include internal flash and use ARM Cortex-M3 cores. It supports both JTAG
@@ -6927,7 +7000,8 @@ applied to all of them.
 
 @deffn {Flash Driver} {stm32f1x}
 All members of the STM32F0, STM32F1 and STM32F3 microcontroller families
-from STMicroelectronics include internal flash and use ARM Cortex-M0/M3/M4 cores.
+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.
 The driver automatically recognizes a number of these chips using
 the chip identification register, and autoconfigures itself.
 
@@ -8079,7 +8153,6 @@ file (which is normally the server's standard output).
 
 @deffn {Command} {echo} [-n] message
 Logs a message at "user" priority.
-Output @var{message} to stdout.
 Option "-n" suppresses trailing newline.
 @example
 echo "Downloading kernel -- please wait"
@@ -10167,7 +10240,7 @@ startbit endbit}.
 
 @deffn {Command} {arc get-reg-field} reg-name field-name
 Returns value of bit-field in a register. Register must be ``struct'' register
-type, @xref{add-reg-type-struct} command definition.
+type, @xref{add-reg-type-struct}. command definition.
 @end deffn
 
 @deffn {Command} {arc set-reg-exists} reg-names...
@@ -10573,6 +10646,49 @@ If @emph{xsvfdump} shows a file is using those opcodes, it
 probably will not be usable with other XSVF tools.
 
 
+@section IPDBG: JTAG-Host server
+@cindex IPDBG JTAG-Host server
+@cindex IPDBG
+
+IPDBG is a set of tools to debug IP-Cores. It comprises, among others, a logic analyzer and an arbitrary
+waveform generator. These are synthesize-able hardware descriptions of
+logic circuits in addition to software for control, visualization and further analysis.
+In a session using JTAG for its transport protocol, OpenOCD supports the function
+of a JTAG-Host. The JTAG-Host is needed to connect the circuit over JTAG to the
+control-software. For more details see @url{http://ipdbg.org}.
+
+@deffn {Command} {ipdbg} [@option{-start|-stop}] @option{-tap @var{tapname}} @option{-hub @var{ir_value} [@var{dr_length}]} [@option{-port @var{number}}] [@option{-tool @var{number}}] [@option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]}]
+Starts or stops a IPDBG JTAG-Host server. Arguments can be specified in any order.
+
+Command options:
+@itemize @bullet
+@item @option{-start|-stop} starts or stops a IPDBG JTAG-Host server (default: start).
+@item @option{-tap @var{tapname}} targeting the TAP @var{tapname}.
+@item @option{-hub @var{ir_value}} states that the JTAG hub is
+reachable with dr-scans while the JTAG instruction register has the value @var{ir_value}.
+@item @option{-port @var{number}} tcp port number where the JTAG-Host is listening.
+@item @option{-tool @var{number}} number of the tool/feature. These corresponds to the ports "data_(up/down)_(0..6)" at the JtagHub.
+@item @option{-vir [@var{vir_value} [@var{length} [@var{instr_code}]]]} On some devices, the user data-register is only reachable if there is a
+specific value in a second dr. This second dr is called vir (virtual ir). With this parameter given, the IPDBG satisfies this condition prior an
+access to the IPDBG-Hub. The value shifted into the vir is given by the first parameter @var{vir_value} (default: 0x11). The second
+parameter @var{length} is the length of the vir data register (default: 5). With the @var{instr_code} (default: 0x00e) parameter the ir value to
+shift data through vir can be configured.
+@end itemize
+@end deffn
+
+Examples:
+@example
+ipdbg -start -tap xc6s.tap -hub 0x02 -port 4242 -tool 4
+@end example
+Starts a server listening on tcp-port 4242 which connects to tool 4.
+The connection is through the TAP of a Xilinx Spartan 6 on USER1 instruction (tested with a papillion pro board).
+
+@example
+ipdbg -start -tap 10m50.tap -hub 0x00C -vir -port 60000 -tool 1
+@end example
+Starts a server listening on tcp-port 60000 which connects to tool 1 (data_up_1/data_down_1).
+The connection is through the TAP of a Intel MAX10 virtual jtag component (sld_instance_index is 0; sld_ir_width is smaller than 5).
+
 @node Utility Commands
 @chapter Utility Commands
 @cindex Utility Commands
@@ -10895,6 +11011,7 @@ Currently supported rtos's include:
 @item @option{nuttx}
 @item @option{RIOT}
 @item @option{hwthread} (This is not an actual RTOS. @xref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.)
+@item @option{Zephyr}
 @end itemize
 
 Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot
@@ -10929,12 +11046,17 @@ g_readytorun, g_tasklisttable.
 sched_threads, sched_num_threads, sched_active_pid, max_threads,
 _tcb_name_offset.
 @end raggedright
+@item Zephyr symbols
+_kernel, _kernel_openocd_offsets, _kernel_openocd_size_t_size
 @end table
 
 For most RTOS supported the above symbols will be exported by default. However for
-some, eg. FreeRTOS and uC/OS-III, extra steps must be taken.
+some, eg. FreeRTOS, uC/OS-III and Zephyr, extra steps must be taken.
 
-These RTOSes may require additional OpenOCD-specific file to be linked
+Zephyr must be compiled with the DEBUG_THREAD_INFO option. This will generate some symbols
+with information needed in order to build the list of threads.
+
+FreeRTOS and uC/OS-III RTOSes may require additional OpenOCD-specific file to be linked
 along with the project:
 
 @table @code
@@ -11058,7 +11180,7 @@ should be passed in to the proc in question.
 
 @section Internal low-level Commands
 
-By "low-level," we mean commands that a human would typically not
+By "low-level", we mean commands that a human would typically not
 invoke directly.
 
 @itemize @bullet
@@ -11087,34 +11209,6 @@ OpenOCD commands can consist of two words, e.g. "flash banks". The
 @file{startup.tcl} "unknown" proc will translate this into a Tcl proc
 called "flash_banks".
 
-@section OpenOCD specific Global Variables
-
-Real Tcl has ::tcl_platform(), and platform::identify, and many other
-variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which
-holds one of the following values:
-
-@itemize @bullet
-@item @b{cygwin}   Running under Cygwin
-@item @b{darwin}   Darwin (Mac-OS) is the underlying operating system.
-@item @b{freebsd}  Running under FreeBSD
-@item @b{openbsd}  Running under OpenBSD
-@item @b{netbsd}   Running under NetBSD
-@item @b{linux}    Linux is the underlying operating system
-@item @b{mingw32}  Running under MingW32
-@item @b{winxx}    Built using Microsoft Visual Studio
-@item @b{ecos}     Running under eCos
-@item @b{other}    Unknown, none of the above.
-@end itemize
-
-Note: 'winxx' was chosen because today (March-2009) no distinction is made between Win32 and Win64.
-
-@quotation Note
-We should add support for a variable like Tcl variable
-@code{tcl_platform(platform)}, it should be called
-@code{jim_platform} (because it
-is jim, not real tcl).
-@end quotation
-
 @section Tcl RPC server
 @cindex RPC
 
@@ -11359,7 +11453,7 @@ your C code, do the same - artificially push some zeros onto the stack,
 remember to pop them off when the ISR is done.
 
 @b{Also note:} If you have a multi-threaded operating system, they
-often do not @b{in the intrest of saving memory} waste these few
+often do not @b{in the interest of saving memory} waste these few
 bytes. Painful...