X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=711ef4d54ad0851ad7beefdde9fbe74cca562a52;hp=3eb6309027a4f1ce3e4eb610f8749e731e3cd4c4;hb=32aec3b5c87c08bda681a5d8abf74efa2e2f3535;hpb=ab858febb6ca6e5dada1492e96c00d8b12c575c0 diff --git a/doc/openocd.texi b/doc/openocd.texi index 3eb6309027..711ef4d54a 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -156,8 +156,8 @@ OpenOCD internally. @xref{Debug Adapter Hardware}. @b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T, ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x), Cortex-M3 -(Stellaris LM3, ST STM32 and Energy Micro EFM32) and Intel Quark (x10xx) -based cores to be debugged via the GDB protocol. +(Stellaris LM3, STMicroelectronics STM32 and Energy Micro EFM32) and +Intel Quark (x10xx) based cores to be debugged via the GDB protocol. @b{Flash Programming:} Flash writing is supported for external CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and several @@ -477,8 +477,8 @@ SWD and not JTAG, thus not supported. @end itemize @section USB ST-LINK based -ST Micro has an adapter called @b{ST-LINK}. -They only work with ST Micro chips, notably STM32 and STM8. +STMicroelectronics has an adapter called @b{ST-LINK}. +They only work with STMicroelectronics chips, notably STM32 and STM8. @itemize @bullet @item @b{ST-LINK} @@ -487,6 +487,9 @@ They only work with ST Micro chips, notably STM32 and STM8. @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, @@ -2578,10 +2581,11 @@ For example adapter definitions, see the configuration files shipped in the @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 @@ -2591,6 +2595,27 @@ List of connections (pin numbers for SSOP): @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: @@ -2605,6 +2630,47 @@ 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} +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} @@ -2981,7 +3047,7 @@ This is a driver that supports multiple High Level Adapters. This type of adapter does not expose some of the lower level api's that OpenOCD would normally use to access the target. -Currently supported adapters include the ST ST-LINK and TI ICDI. +Currently supported adapters include the STMicroelectronics ST-LINK and TI ICDI. ST-LINK firmware version >= V2.J21.S4 recommended due to issues with earlier versions of firmware where serial number is reset after first use. Suggest using ST firmware update utility to upgrade ST-LINK firmware even if current @@ -4275,6 +4341,8 @@ compact Thumb2 instruction set. @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 @@ -5647,6 +5715,27 @@ Note that in order for this command to take effect, the target needs to be reset 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. @@ -6381,7 +6470,7 @@ applied to all of them. @deffn {Flash Driver} stm32f1x All members of the STM32F0, STM32F1 and STM32F3 microcontroller families -from ST Microelectronics include internal flash and use ARM Cortex-M0/M3/M4 cores. +from STMicroelectronics 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. @@ -6406,23 +6495,24 @@ flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME 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 @@ -6430,10 +6520,17 @@ The @var{num} parameter is a value shown by @command{flash banks}. 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 -All members of the STM32F2, STM32F4 and STM32F7 microcontroller families from ST Microelectronics +All members of the STM32F2, STM32F4 and STM32F7 microcontroller families from STMicroelectronics include internal flash and use ARM Cortex-M3/M4/M7 cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -6487,7 +6584,7 @@ The @var{num} parameter is a value shown by @command{flash banks}, @var{optcr2} @end deffn @deffn {Flash Driver} stm32h7x -All members of the STM32H7 microcontroller families from ST Microelectronics +All members of the STM32H7 microcontroller families from STMicroelectronics include internal flash and use ARM Cortex-M7 core. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -6523,7 +6620,7 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @deffn {Flash Driver} stm32lx -All members of the STM32L microcontroller families from ST Microelectronics +All members of the STM32L microcontroller families from STMicroelectronics include internal flash and use ARM Cortex-M3 and Cortex-M0+ cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -6563,7 +6660,7 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @deffn {Flash Driver} stm32l4x -All members of the STM32L4 microcontroller families from ST Microelectronics +All members of the STM32L4 microcontroller families from STMicroelectronics include internal flash and use ARM Cortex-M4 cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -6596,10 +6693,46 @@ The @var{num} parameter is a value shown by @command{flash banks}. 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 -All members of the STR7 microcontroller family from ST Microelectronics +All members of the STR7 microcontroller family from STMicroelectronics include internal flash and use ARM7TDMI cores. The @var{str7x} driver defines one mandatory parameter, @var{variant}, which is either @code{STR71x}, @code{STR73x} or @code{STR75x}. @@ -6616,7 +6749,7 @@ for the specified flash bank. @end deffn @deffn {Flash Driver} str9x -Most members of the STR9 microcontroller family from ST Microelectronics +Most members of the STR9 microcontroller family from STMicroelectronics include internal flash and use ARM966E cores. The str9 needs the flash controller to be configured using the @command{str9x flash_config} command prior to Flash programming. @@ -8699,6 +8832,12 @@ Selects whether interrupts will be processed when single stepping 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 @@ -8789,7 +8928,7 @@ baud with our custom divisor to get 12MHz) @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" @@ -8897,6 +9036,29 @@ Selects whether interrupts will be processed when single stepping. The default c @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 @@ -8986,8 +9148,11 @@ Display all registers in @emph{group}. @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