@item @b{ST-LINK/V2}
@* This is available standalone and as part of some kits, eg. STM32F4DISCOVERY.
@* Link: @url{http://www.st.com/internet/evalboard/product/251168.jsp}
+@item @b{STLINK-V3}
+@* This is available standalone and as part of some kits.
+@* Link: @url{http://www.st.com/stlink-v3}
@end itemize
For info the original ST-LINK enumerates using the mass storage usb class; however,
If you disable all access through TCP/IP, you will need to
use the command line @option{-pipe} option.
+@anchor{gdb_port}
@deffn {Command} gdb_port [number]
@cindex GDB server
Normally gdb listens to a TCP/IP port, but GDB can also
second target will listen on gdb_port + 1, and so on.
When not specified during the configuration stage,
the port @var{number} defaults to 3333.
+When @var{number} is not a numeric value, incrementing it to compute
+the next port number does not work. In this case, specify the proper
+@var{number} for each target by using the option @code{-gdb-port} of the
+commands @command{target create} or @command{$target_name configure}.
+@xref{gdbportoverride,,option -gdb-port}.
Note: when using "gdb_port pipe", increasing the default remote timeout in
gdb (with 'set remotetimeout') is recommended. An insufficient timeout may
cause initialization to fail with "Unknown remote qXfer reply: OK".
-
@end deffn
@deffn {Command} tcl_port [number]
@end deffn
@deffn {Interface Driver} {ft232r}
-This driver is implementing synchronous bitbang mode of an FTDI FT232R
-USB UART bridge IC.
+This driver is implementing synchronous bitbang mode of an FTDI FT232R,
+FT230X, FT231X and similar USB UART bridge ICs by reusing RS232 signals as GPIO.
+It currently doesn't support using CBUS pins as GPIO.
-List of connections (pin numbers for SSOP):
+List of connections (default physical pin numbers for FT232R in 28-pin SSOP package):
@itemize @minus
@item RXD(5) - TDI
@item TXD(1) - TCK
@item DCD(10) - SRST
@end itemize
+User can change default pinout by supplying configuration
+commands with GPIO numbers or RS232 signal names.
+GPIO numbers correspond to bit numbers in FTDI GPIO register.
+They differ from physical pin numbers.
+For details see actual FTDI chip datasheets.
+Every JTAG line must be configured to unique GPIO number
+different than any other JTAG line, even those lines
+that are sometimes not used like TRST or SRST.
+
+FT232R
+@itemize @minus
+@item bit 7 - RI
+@item bit 6 - DCD
+@item bit 5 - DSR
+@item bit 4 - DTR
+@item bit 3 - CTS
+@item bit 2 - RTS
+@item bit 1 - RXD
+@item bit 0 - TXD
+@end itemize
+
These interfaces have several commands, used to configure the driver
before initializing the JTAG scan chain:
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}
+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}
+Set TCK GPIO number. If not specified, default 0 or TXD is used.
+@end deffn
+
+@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}
+Set TDI GPIO number. If not specified, default 1 or RXD is used.
+@end deffn
+
+@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}
+Set TRST GPIO number. If not specified, default 4 or DTR is used.
+@end deffn
+
+@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}
+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:
+0x15 for TXD RTS DTR as outputs (1), others as inputs (0). Higher
+byte is usually 0 to disable bitbang mode.
+When kernel driver reattaches, serial port should continue to work.
+Value 0xFFFF disables sending control word and serial port,
+then kernel driver will not reattach.
+If not specified, default 0xFFFF is used.
+@end deffn
+
@end deffn
@deffn {Interface Driver} {remote_bitbang}
@item @code{dragonite} -- resembles arm966e
@item @code{dsp563xx} -- implements Freescale's 24-bit DSP.
(Support for this is still incomplete.)
+@item @code{esirisc} -- this is an EnSilica eSi-RISC core.
+The current implementation supports eSi-32xx cores.
@item @code{fa526} -- resembles arm920 (w/o Thumb)
@item @code{feroceon} -- resembles arm926
@item @code{mips_m4k} -- a MIPS core
where it is a mandatory configuration for the target run control.
@xref{armcrosstrigger,,ARM Cross-Trigger Interface},
for instruction on how to declare and control a CTI instance.
+
+@anchor{gdbportoverride}
+@item @code{-gdb-port} @var{number} -- see command @command{gdb_port} for the
+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}.
@end itemize
@end deffn
supported.}
@end deffn
+@deffn {Flash Driver} esirisc
+Members of the eSi-RISC family may optionally include internal flash programmed
+via the eSi-TSMC Flash interface. Additional parameters are required to
+configure the driver: @option{cfg_address} is the base address of the
+configuration register interface, @option{clock_hz} is the expected clock
+frequency, and @option{wait_states} is the number of configured read wait states.
+
+@example
+flash bank $_FLASHNAME esirisc base_address size_bytes 0 0 $_TARGETNAME cfg_address clock_hz wait_states
+@end example
+
+@deffn Command {esirisc_flash mass_erase} (bank_id)
+Erases all pages in data memory for the bank identified by @option{bank_id}.
+@end deffn
+
+@deffn Command {esirisc_flash ref_erase} (bank_id)
+Erases the reference cell for the bank identified by @option{bank_id}. This is
+an uncommon operation.
+@end deffn
+@end deffn
+
@deffn {Flash Driver} fm3
All members of the FM3 microcontroller family from Fujitsu
include internal flash and use ARM Cortex-M3 cores.
Some stm32f1x-specific commands are defined:
@deffn Command {stm32f1x lock} num
-Locks the entire stm32 device.
+Locks the entire stm32 device against reading.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@deffn Command {stm32f1x unlock} num
-Unlocks the entire stm32 device.
+Unlocks the entire stm32 device for reading. This command will cause
+a mass erase of the entire stm32 device if previously locked.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@deffn Command {stm32f1x mass_erase} num
-Mass erases the entire stm32f1x device.
+Mass erases the entire stm32 device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
@deffn Command {stm32f1x options_read} num
-Read and display the stm32 option bytes written by
-the @command{stm32f1x options_write} command.
+Reads and displays active stm32 option bytes loaded during POR
+or upon executing the @command{stm32f1x options_load} command.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
Writes the stm32 option byte with the specified values.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+
+@deffn Command {stm32f1x options_load} num
+Generates a special kind of reset to re-load the stm32 option bytes written
+by the @command{stm32f1x options_write} or @command{flash protect} commands
+without having to power cycle the target. Not applicable to stm32f1x devices.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
@end deffn
@deffn {Flash Driver} stm32f2x
Mass erases the entire stm32l4x device.
The @var{num} parameter is a value shown by @command{flash banks}.
@end deffn
+
+@deffn Command {stm32l4x option_read} num reg_offset
+Reads an option byte register from the stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+is the register offset of the Option byte to read.
+
+For example to read the FLASH_OPTR register:
+@example
+stm32l4x option_read 0 0x20
+# Option Register: <0x40022020> = 0xffeff8aa
+@end example
+
+The above example will read out the FLASH_OPTR register which contains the RDP
+option byte, Watchdog configuration, BOR level etc.
+@end deffn
+
+@deffn Command {stm32l4x option_write} num reg_offset reg_mask
+Write an option byte register of the stm32l4x device.
+The @var{num} parameter is a value shown by @command{flash banks}, @var{reg_offset}
+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).
+
+For example to write the WRP1AR option bytes:
+@example
+stm32l4x option_write 0 0x28 0x00FF0000 0x00FF00FF
+@end example
+
+The above example will write the WRP1AR option register configuring the Write protection
+Area A for bank 1. The above example set WRP1AR_END=255, WRP1AR_START=0.
+This will effectively write protect all sectors in flash bank 1.
+@end deffn
+
+@deffn Command {stm32l4x option_load} num
+Forces a re-load of the option byte registers. Will cause a reset of the device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
@end deffn
@deffn {Flash Driver} str7x
configure l2x cache
@end deffn
+@deffn Command {cortex_a mmu dump} [@option{0}|@option{1}|@option{addr} address [@option{num_entries}]]
+Dump the MMU translation table from TTB0 or TTB1 register, or from physical
+memory location @var{address}. When dumping the table from @var{address}, print at most
+@var{num_entries} page table entries. @var{num_entries} is optional, if omitted, the maximum
+possible (4096) entries are printed.
+@end deffn
@subsection ARMv7-R specific commands
@cindex Cortex-R
@item @code{itmdump -f /dev/ttyUSB1 -d1}
@item OpenOCD invocation line:
@example
-openocd -f interface/stlink-v2-1.cfg \
+openocd -f interface/stlink.cfg \
-c "transport select hla_swd" \
-f target/stm32l1.cfg \
-c "tpiu config external uart off 24000000 12000000"
@option{on}.
@end deffn
+@section EnSilica eSi-RISC Architecture
+
+eSi-RISC is a highly configurable microprocessor architecture for embedded systems
+provided by EnSilica. (See: @url{http://www.ensilica.com/risc-ip/}.)
+
+@subsection esirisc specific commands
+@deffn Command {esirisc cache_arch} (@option{harvard}|@option{von_neumann})
+Configure the caching architecture. Targets with the @code{UNIFIED_ADDRESS_SPACE}
+option disabled employ a Harvard architecture. By default, @option{von_neumann} is assumed.
+@end deffn
+
+@deffn Command {esirisc flush_caches}
+Flush instruction and data caches. This command requires that the target is halted
+when the command is issued and configured with an instruction or data cache.
+@end deffn
+
+@deffn Command {esirisc hwdc} (@option{all}|@option{none}|mask ...)
+Configure hardware debug control. The HWDC register controls which exceptions return
+control back to the debugger. Possible masks are @option{all}, @option{none},
+@option{reset}, @option{interrupt}, @option{syscall}, @option{error}, and @option{debug}.
+By default, @option{reset}, @option{error}, and @option{debug} are enabled.
+@end deffn
+
@section Intel Architecture
Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32
@section RISC-V Architecture
@uref{http://riscv.org/, RISC-V} is a free and open ISA. OpenOCD supports JTAG
-debug of targets that implement version 0.11 and 0.13 of the RISC-V Debug
-Specification.
+debug of RV32 and RV64 cores in heterogeneous multicore systems of up to 32
+harts. (It's possible to increase this limit to 1024 by changing
+RISCV_MAX_HARTS in riscv.h.) OpenOCD primarily supports 0.13 of the RISC-V
+Debug Specification, but there is also support for legacy targets that
+implement version 0.11.
@subsection RISC-V Terminology