@item @b{Keil ULINK v1}
@* Link: @url{http://www.keil.com/ulink1/}
+
+@item @b{TI XDS110 Debug Probe}
+@* The XDS110 is included as the embedded debug probe on many Texas Instruments
+LaunchPad evaluation boards.
+@* Link: @url{http://processors.wiki.ti.com/index.php/XDS110}
+@* Link: @url{http://processors.wiki.ti.com/index.php/XDS_Emulation_Software_Package#XDS110_Support_Utilities}
@end itemize
@section IBM PC Parallel Printer Port Based
@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
@item @b{flashlink}
-@* From ST Microsystems;
+@* From STMicroelectronics;
@* Link: @url{http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf}
@end itemize
Likewise, the @command{arm9 vector_catch} command (or
@cindex vector_catch
its siblings @command{xscale vector_catch}
-and @command{cortex_m vector_catch}) can be a timesaver
+and @command{cortex_m vector_catch}) can be a time-saver
during some debug sessions, but don't make everyone use that either.
Keep those kinds of debugging aids in your user config file,
along with messaging and tracing setup.
@itemize @bullet
@item @b{Watchdog Timers}...
-Watchog timers are typically used to automatically reset systems if
+Watchdog timers are typically used to automatically reset systems if
some application task doesn't periodically reset the timer. (The
assumption is that the system has locked up if the task can't run.)
When a JTAG debugger halts the system, that task won't be able to run
board files may need to distinguish between instances of a chip.
@item @code{ENDIAN} ...
By default @option{little} - although chips may hard-wire @option{big}.
-Chips that can't change endianness don't need to use this variable.
+Chips that can't change endianess don't need to use this variable.
@item @code{CPUTAPID} ...
When OpenOCD examines the JTAG chain, it can be told verify the
chips against the JTAG IDCODE register.
configuration stage, @xref{configurationstage,,Configuration Stage},) or they can contain a special
procedure called @code{init_targets}, which will be executed when entering run stage
(after parsing all config files or after @code{init} command, @xref{enteringtherunstage,,Entering the Run Stage}.)
-Such procedure can be overriden by ``next level'' script (which sources the original).
-This concept faciliates code reuse when basic target config files provide generic configuration
-procedures and @code{init_targets} procedure, which can then be sourced and enchanced or changed in
+Such procedure can be overridden by ``next level'' script (which sources the original).
+This concept facilitates code reuse when basic target config files provide generic configuration
+procedures and @code{init_targets} procedure, which can then be sourced and enhanced or changed in
a ``more specific'' target config file. This is not possible with ``linear'' config scripts,
because sourcing them executes every initialization commands they provide.
become available.
A number of these relate to the debug targets you may have declared.
For example, the @command{mww} command will not be available until
-a target has been successfuly instantiated.
+a target has been successfully instantiated.
If you want to use those commands, you may need to force
entry to the run stage.
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 {Command} gdb_save_tdesc
-Saves the target descripton file to the local file system.
+Saves the target description file to the local file system.
The file name is @i{target_name}.xml.
@end deffn
The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device,
bypassing intermediate libraries like libftdi or D2XX.
-Support for new FTDI based adapters can be added competely through
+Support for new FTDI based adapters can be added completely through
configuration files, without the need to patch and rebuild OpenOCD.
The driver uses a signal abstraction to enable Tcl configuration files to
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
-peculiar at high JTAG clock speeds. However, FTDI chips offer a possiblity to sample
+peculiar at high JTAG clock speeds. However, FTDI chips offer a possibility to sample
TDO on falling edge of TCK. With some board/adapter configurations, this may increase
stability at higher JTAG clocks.
@itemize @minus
transports.
@quotation Compatibility Note
-SEGGER released many firmware versions for the many harware versions they
+SEGGER released many firmware versions for the many hardware versions they
produced. OpenOCD was extensively tested and intended to run on all of them,
but some combinations were reported as incompatible. As a general
recommendation, it is advisable to use the latest firmware version
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 STLINK and TI ICDI.
-STLINK firmware version >= V2.J21.S4 recommended due to issues with earlier
+Currently supported adapters include the ST 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 STLINK firmware even if current
+using ST firmware update utility to upgrade ST-LINK firmware even if current
version reported is V2.J21.S4.
@deffn {Config Command} {hla_device_desc} description
expected to change.
@end deffn
@deffn Command {swd wcr trn prescale}
-Updates TRN (turnaraound delay) and prescaling.fields of the
+Updates TRN (turnaround delay) and prescaling.fields of the
Wire Control Register (WCR).
No parameters: displays current settings.
@end deffn
@item
The @var{gates} tokens control flags that describe some cases where
-JTAG may be unvailable during reset.
+JTAG may be unavailable during reset.
@option{srst_gates_jtag} (default)
indicates that asserting SRST gates the
JTAG clock. This means that no communication can happen on JTAG
are the default @option{srst_open_drain}, and @option{srst_push_pull}.
Most boards connect this signal to a pullup, and allow the
signal to be pulled low by various events including system
-powerup and pressing a reset button.
+power-up and pressing a reset button.
@end itemize
@end deffn
both inside a single chip and between them.
@xref{faqtaporder,,FAQ TAP Order}.
-For example, the ST Microsystems STR912 chip has
+For example, the STMicroelectronics STR912 chip has
three separate TAPs@footnote{See the ST
document titled: @emph{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
28/102, Figure 3: JTAG chaining inside the STR91xFA}.
Select AP @var{num}, defaulting to 0.
@end deffn
+@deffn Command {$dap_name dpreg} reg [value]
+Displays the content of DP register at address @var{reg}, or set it to a new
+value @var{value}.
+
+In case of SWD, @var{reg} is a value in packed format
+@math{dpbanksel << 4 | addr} and assumes values 0, 4, 8 ... 0xfc.
+In case of JTAG it only assumes values 0, 4, 8 and 0xc.
+
+@emph{Note:} Consider using @command{poll off} to avoid any disturbing
+background activity by OpenOCD while you are operating at such low-level.
+@end deffn
+
@deffn Command {$dap_name baseaddr} [num]
Displays debug base address from MEM-AP @var{num},
defaulting to the currently selected AP.
@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
this key point: @emph{ARM is a technology licencing company}.
(See: @url{http://www.arm.com}.)
The CPU name used by OpenOCD will reflect the CPU design that was
-licenced, not a vendor brand which incorporates that design.
+licensed, not a vendor brand which incorporates that design.
Name prefixes like arm7, arm9, arm11, and cortex
reflect design generations;
while names like ARMv4, ARMv5, ARMv6, ARMv7 and ARMv8
inaccessible when application code
(such as an operating system)
enables or disables the MMU.
-For example, the particular MMU context used to acess the virtual
+For example, the particular MMU context used to access the virtual
address will probably matter ... and that context might not have
easy access to other addresses needed.
At this writing, OpenOCD doesn't have much MMU intelligence.
@item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
@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{embKernel}, @option{mqx}, @option{uCOS-III}, @option{nuttx}
@xref{gdbrtossupport,,RTOS Support}.
@item @code{-defer-examine} -- skip target examination at initial JTAG chain
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
@xref{gdbconfiguration,,GDB Configuration}.
@end enumerate
-Many CPUs have the ablity to ``boot'' from the first flash bank.
+Many CPUs have the ability to ``boot'' from the first flash bank.
This means that misprogramming that bank can ``brick'' a system,
so that it can't boot.
JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
@anchor{flashprogrammingcommands}
One feature distinguishing NOR flash from NAND or serial flash technologies
-is that for read access, it acts exactly like any other addressible memory.
+is that for read access, it acts exactly like any other addressable memory.
This means you can use normal memory read commands like @command{mdw} or
@command{dump_image} with it, with no special @command{flash} subcommands.
@xref{memoryaccess,,Memory access}, and @ref{imageaccess,,Image access}.
JTAG target, and map from an address in that target's address space
back to a flash bank.
@comment In May 2009, those mappings may fail if any bank associated
-@comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
+@comment with that target doesn't successfully autoprobe ... bug worth fixing?
A few commands use abstract addressing based on bank and sector numbers,
and don't depend on searching the current target and its address space.
Avoid confusing the two command models.
@deffn Command {flash padded_value} num value
Sets the default value used for padding any image sections, This should
normally match the flash bank erased value. If not specified by this
-comamnd or the flash driver then it defaults to 0xff.
+command or the flash driver then it defaults to 0xff.
@end deffn
@anchor{program}
@end itemize
So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to
-the flash bank defined at address 0x1fc00000. Any cmds executed on
-the virtual banks are actually performed on the physical banks.
+the flash bank defined at address 0x1fc00000. Any command executed on
+the virtual banks is actually performed on the physical banks.
@example
flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
flash bank vbank0 virtual 0xbfc00000 0 0 0 \
@item @var{x16_as_x8} ... when a 16-bit flash is hooked up to an 8-bit bus.
@item @var{bus_swap} ... when data bytes in a 16-bit flash needs to be swapped.
@item @var{data_swap} ... when data bytes in a 16-bit flash needs to be
-swapped when writing data values (ie. not CFI commands).
+swapped when writing data values (i.e. not CFI commands).
@end itemize
To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
@cindex STMicroelectronics Serial Memory Interface
@cindex SMI
@cindex stmsmi
-Some devices form STMicroelectronics (e.g. STR75x MCU family,
+Some devices from STMicroelectronics (e.g. STR75x MCU family,
SPEAr MPU family) include a proprietary
``Serial Memory Interface'' (SMI) controller able to drive external
SPI flash devices.
The @var{ambiqmicro} driver reads the Chip Information Register detect
the device class of the MCU.
-The Flash and Sram sizes directly follow device class, and are used
+The Flash and SRAM sizes directly follow device class, and are used
to set up the flash banks.
If this fails, the driver will use default values set to the minimum
sizes of an Apollo chip.
@end deffn
@deffn Command {ambiqmicro program_otp} <bank> <offset> <count>
Program OTP is a one time operation to create write protected flash.
-The user writes sectors to sram starting at 0x10000010.
-Program OTP will write these sectors from sram to flash, and write protect
+The user writes sectors to SRAM starting at 0x10000010.
+Program OTP will write these sectors from SRAM to flash, and write protect
the flash.
@end deffn
@end deffn
@cindex at91samd
All members of the ATSAMD, ATSAMR, ATSAML and ATSAMC microcontroller
families from Atmel include internal flash and use ARM's Cortex-M0+ core.
-This driver uses the same cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
@deffn Command {at91samd chip-erase}
Issues a complete Flash erase via the Device Service Unit (DSU). This can be
of the Flash. When setting, the EEPROM size must be specified in bytes and it
must be one of the permitted sizes according to the datasheet. Settings are
written immediately but only take effect on MCU reset. EEPROM emulation
-requires additional firmware support and the minumum EEPROM size may not be
+requires additional firmware support and the minimum EEPROM size may not be
the same as the minimum that the hardware supports. Set the EEPROM size to 0
in order to disable this feature.
that the driver was orginaly developed and tested using the
AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
the family was cribbed from the data sheet. @emph{Note to future
-readers/updaters: Please remove this worrysome comment after other
+readers/updaters: Please remove this worrisome comment after other
chips are confirmed.}
The AT91SAM3U4[E/C] (256K) chips have two flash banks; most other chips
@cindex at91sam4
All members of the AT91SAM4 microcontroller family from
Atmel include internal flash and use ARM's Cortex-M4 core.
-This driver uses the same cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
@end deffn
@deffn {Flash Driver} at91sam4l
@cindex at91sam4l
All members of the AT91SAM4L microcontroller family from
Atmel include internal flash and use ARM's Cortex-M4 core.
-This driver uses the same cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
The AT91SAM4L driver adds some additional commands:
@deffn Command {at91sam4l smap_reset_deassert}
@cindex atsamv
All members of the ATSAMV, ATSAMS, and ATSAME families from
Atmel include internal flash and use ARM's Cortex-M7 core.
-This driver uses the same cmd names/syntax as @xref{at91sam3}.
+This driver uses the same command names/syntax as @xref{at91sam3}.
@end deffn
@deffn {Flash Driver} at91sam7
@end example
Triggering a mass erase is also useful when users want to disable readout protection.
+@end deffn
+
+@deffn {Flash Driver} cc26xx
+All versions of the SimpleLink CC13xx and CC26xx microcontrollers from Texas
+Instruments include internal flash. The cc26xx flash driver supports both the
+CC13xx and CC26xx family of devices. The driver automatically recognizes the
+specific version's flash parameters and autoconfigures itself. Flash bank 0
+starts at address 0.
+@example
+flash bank $_FLASHNAME cc26xx 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} cc3220sf
+The CC3220SF version of the SimpleLink CC32xx microcontrollers from Texas
+Instruments includes 1MB of internal flash. The cc3220sf flash driver only
+supports the internal flash. The serial flash on SimpleLink boards is
+programmed via the bootloader over a UART connection. Security features of
+the CC3220SF may erase the internal flash during power on reset. Refer to
+documentation at @url{www.ti.com/cc3220sf} for details on security features
+and programming the serial flash.
+
+@example
+flash bank $_FLASHNAME cc3220sf 0 0 0 0 $_TARGETNAME
+@end example
@end deffn
@deffn {Flash Driver} efm32
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.
The index sector of the flash is a @emph{write-only} sector. It cannot be
erased! In order to guard against unintentional write access, all following
-commands need to be preceeded by a successful call to the @code{password}
+commands need to be preceded by a successful call to the @code{password}
command:
@deffn Command {lpc2900 password} bank password
@end example
@end deffn
+@deffn {Flash Driver} msp432
+All versions of the SimpleLink MSP432 microcontrollers from Texas
+Instruments include internal flash. The msp432 flash driver automatically
+recognizes the specific version's flash parameters and autoconfigures itself.
+Main program flash (starting at address 0) is flash bank 0. Information flash
+region on MSP432P4 versions (starting at address 0x200000) is flash bank 1.
+
+@example
+flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME
+@end example
+
+@deffn Command {msp432 mass_erase} [main|all]
+Performs a complete erase of flash. By default, @command{mass_erase} will erase
+only the main program flash.
+
+On MSP432P4 versions, using @command{mass_erase all} will erase both the
+main program and information flash regions. To also erase the BSL in information
+flash, the user must first use the @command{bsl} command.
+@end deffn
+
+@deffn Command {msp432 bsl} [unlock|lock]
+On MSP432P4 versions, @command{bsl} unlocks and locks the bootstrap loader (BSL)
+region in information flash so that flash commands can erase or write the BSL.
+Leave the BSL locked to prevent accidentally corrupting the bootstrap loader.
+
+To erase and program the BSL:
+@example
+msp432 bsl unlock
+flash erase_address 0x202000 0x2000
+flash write_image bsl.bin 0x202000
+msp432 bsl lock
+@end example
+@end deffn
+@end deffn
+
@deffn {Flash Driver} niietcm4
This drivers handles the integrated NOR flash on NIIET Cortex-M4
based controllers. Flash size and sector layout are auto-configured by the driver.
There is additional not memory mapped flash called "Userflash", which
also have division into regions: main and info.
Purpose of userflash - to store system and user settings.
-Driver has special commands to perform operations with this memmory.
+Driver has special commands to perform operations with this memory.
@example
flash bank $_FLASHNAME niietcm4 0 0 0 0 $_TARGETNAME
@end deffn
@end deffn
+@deffn {Flash Driver} psoc5lp
+All members of the PSoC 5LP microcontroller family from Cypress
+include internal program flash and use ARM Cortex-M3 cores.
+The driver probes for a number of these chips and autoconfigures itself,
+apart from the base address.
+
+@example
+flash bank $_FLASHNAME psoc5lp 0x00000000 0 0 0 $_TARGETNAME
+@end example
+
+@b{Note:} PSoC 5LP chips can be configured to have ECC enabled or disabled.
+@quotation Attention
+If flash operations are performed in ECC-disabled mode, they will also affect
+the ECC flash region. Erasing a 16k flash sector in the 0x00000000 area will
+then also erase the corresponding 2k data bytes in the 0x48000000 area.
+Writing to the ECC data bytes in ECC-disabled mode is not implemented.
+@end quotation
+
+Commands defined in the @var{psoc5lp} driver:
+
+@deffn Command {psoc5lp mass_erase}
+Erases all flash data and ECC/configuration bytes, all flash protection rows,
+and all row latches in all flash arrays on the device.
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} psoc5lp_eeprom
+All members of the PSoC 5LP microcontroller family from Cypress
+include internal EEPROM and use ARM Cortex-M3 cores.
+The driver probes for a number of these chips and autoconfigures itself,
+apart from the base address.
+
+@example
+flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} psoc5lp_nvl
+All members of the PSoC 5LP microcontroller family from Cypress
+include internal Nonvolatile Latches and use ARM Cortex-M3 cores.
+The driver probes for a number of these chips and autoconfigures itself.
+
+@example
+flash bank $_CHIPNAME.nvl psoc5lp_nvl 0 0 0 0 $_TARGETNAME
+@end example
+
+PSoC 5LP chips have multiple NV Latches:
+
+@itemize
+@item Device Configuration NV Latch - 4 bytes
+@item Write Once (WO) NV Latch - 4 bytes
+@end itemize
+
+@b{Note:} This driver only implements the Device Configuration NVL.
+
+The @var{psoc5lp} driver reads the ECC mode from Device Configuration NVL.
+@quotation Attention
+Switching ECC mode via write to Device Configuration NVL will require a reset
+after successful write.
+@end quotation
+@end deffn
+
@deffn {Flash Driver} psoc6
Supports PSoC6 (CY8C6xxx) family of Cypress microcontrollers.
PSoC6 is a dual-core device with CM0+ and CM4 cores. Both cores share
include internal flash and use ARM Cortex-M3 cores. It supports both JTAG
and SWD interface.
The @var{sim3x} driver tries to probe the device to auto detect the MCU.
-If this failes, it will use the @var{size} parameter as the size of flash bank.
+If this fails, it will use the @var{size} parameter as the size of flash bank.
@example
flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 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
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
flash programming as it is faster than the @option{str9xpec} driver.
@item
Direct programming @option{str9xpec} using the flash controller. This is an
-ISC compilant (IEEE 1532) tap connected in series with the str9 core. The str9
+ISC compliant (IEEE 1532) tap connected in series with the str9 core. The str9
core does not need to be running to program using this flash driver. Typical use
for this driver is locking/unlocking the target and programming the option bytes.
@end enumerate
every 512 bytes of data.
You will need to make sure that any data you write using
-OpenOCD includes the apppropriate kind of ECC. For example,
+OpenOCD includes the appropriate kind of ECC. For example,
that may mean passing the @code{oob_softecc} flag when
writing NAND data, or ensuring that the correct hardware
ECC mode is used.
@itemize @bullet
@item no oob_* parameter
@*File has only page data, which is written.
-If raw acccess is in use, the OOB area will not be written.
+If raw access is in use, the OOB area will not be written.
Otherwise, if the underlying NAND controller driver has
a @code{write_page} routine, that routine may write the OOB
with hardware-computed ECC data.
@b{NOTE:} This will not work when the underlying NAND controller
driver's @code{write_page} routine must update the OOB with a
-hardward-computed ECC before the data is written. This limitation may
+hardware-computed ECC before the data is written. This limitation may
be removed in a future release.
@end deffn
@deffn {NAND Driver} mx3
This driver handles the NAND controller in i.MX31. The mxc driver
-should work for this chip aswell.
+should work for this chip as well.
@end deffn
@deffn {NAND Driver} mxc
nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap
@end example
@deffn Command {mxc biswap} bank_num [enable|disable]
-Turns on/off bad block information swaping from main area,
+Turns on/off bad block information swapping from main area,
without parameter query status.
@end deffn
@end deffn
@chapter Flash Programming
OpenOCD implements numerous ways to program the target flash, whether internal or external.
-Programming can be acheived by either using GDB @ref{programmingusinggdb,,Programming using GDB},
-or using the cmds given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
+Programming can be achieved by either using GDB @ref{programmingusinggdb,,Programming using GDB},
+or using the commands given in @ref{flashprogrammingcommands,,Flash Programming Commands}.
-@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
+@*To simplify using the flash commands directly a jimtcl script is available that handles the programming and verify stage.
OpenOCD will program/verify/reset the target and optionally shutdown.
-The script is executed as follows and by default the following actions will be peformed.
+The script is executed as follows and by default the following actions will be performed.
@enumerate
@item 'init' is executed.
@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
@itemize @bullet
@item @b{Source Of Commands}
@* OpenOCD commands can occur in a configuration script (discussed
-elsewhere) or typed manually by a human or supplied programatically,
+elsewhere) or typed manually by a human or supplied programmatically,
or via one of several TCP/IP Ports.
@item @b{From the human}
Close the OpenOCD server, disconnecting all clients (GDB, telnet,
other). If option @option{error} is used, OpenOCD will return a
non-zero exit code to the parent process.
+
+Like any TCL commands, also @command{shutdown} can be redefined, e.g.:
+@example
+# redefine shutdown
+rename shutdown original_shutdown
+proc shutdown @{@} @{
+ puts "This is my implementation of shutdown"
+ # my own stuff before exit OpenOCD
+ original_shutdown
+@}
+@end example
+If user types CTRL-C or kills OpenOCD, either the command @command{shutdown}
+or its replacement will be automatically executed before OpenOCD exits.
@end deffn
@anchor{debuglevel}
A more complete workaround is to not use that operation while you
work with a JTAG debugger.
-Tasking environments generaly have idle loops where the body is the
+Tasking environments generally have idle loops where the body is the
@emph{wait for interrupt} operation.
(On older cores, it is a coprocessor action;
newer cores have a @option{wfi} instruction.)
@deffn Command {fast_load}
Loads an image stored in memory by @command{fast_load_image} to the
-current target. Must be preceeded by fast_load_image.
+current target. Must be preceded by fast_load_image.
@end deffn
@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}]
Load image from file @var{filename} to target memory offset by @var{address} from its load address.
The file format may optionally be specified
(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}).
-In addition the following arguments may be specifed:
+In addition the following arguments may be specified:
@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address})
@var{max_length} - maximum number of bytes to load.
@example
with a given trace port @var{driver}. @xref{traceportdrivers,,Trace Port Drivers}.
Several of the parameters must reflect the trace port capabilities,
-which are a function of silicon capabilties (exposed later
+which are a function of silicon capabilities (exposed later
using @command{etm info}) and of what hardware is connected to
that port (such as an external pod, or ETB).
The @var{width} must be either 4, 8, or 16,
@deffn Command {arm semihosting_cmdline} [@option{enable}|@option{disable}]
@cindex ARM semihosting
-Set the command line to be passed to the debuggee.
+Set the command line to be passed to the debugger.
@example
arm semihosting_cmdline argv0 argv1 argv2 ...
debugger.
@end deffn
+@deffn Command {arm semihosting_resexit} [@option{enable}|@option{disable}]
+@cindex ARM semihosting
+Enable resumable SEMIHOSTING_SYS_EXIT.
+
+When SEMIHOSTING_SYS_EXIT is called outside a debug session,
+things are simple, the openocd process calls exit() and passes
+the value returned by the target.
+
+When SEMIHOSTING_SYS_EXIT is called during a debug session,
+by default execution returns to the debugger, leaving the
+debugger in a HALT state, similar to the state entered when
+encountering a break.
+
+In some use cases, it is useful to have SEMIHOSTING_SYS_EXIT
+return normally, as any semihosting call, and do not break
+to the debugger.
+The standard allows this to happen, but the condition
+to trigger it is a bit obscure ("by performing an RDI_Execute
+request or equivalent").
+
+To make the SEMIHOSTING_SYS_EXIT call return normally, enable
+this option (default: disabled).
+@end deffn
+
@section ARMv4 and ARMv5 Architecture
@cindex ARMv4
@cindex ARMv5
handlers from the mini-IC, ignoring the code in RAM.
To address this situation, OpenOCD provides the @code{xscale
-vector_table} command, which allows the user to explicity write
+vector_table} command, which allows the user to explicitly write
individual entries to either the high or low vector table stored in
the mini-IC.
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"
@deffn Command {cortex_m maskisr} (@option{auto}|@option{on}|@option{off})
Control masking (disabling) interrupts during target step/resume.
-The @option{auto} option handles interrupts during stepping a way they get
-served but don't disturb the program flow. The step command first allows
+The @option{auto} option handles interrupts during stepping in a way that they
+get served but don't disturb the program flow. The step command first allows
pending interrupt handlers to execute, then disables interrupts and steps over
the next instruction where the core was halted. After the step interrupts
are enabled again. If the interrupt handlers don't complete within 500ms,
the step command leaves with the core running.
-Note that a free breakpoint is required for the @option{auto} option. If no
-breakpoint is available at the time of the step, then the step is taken
-with interrupts enabled, i.e. the same way the @option{off} option does.
+Note that a free hardware (FPB) breakpoint is required for the @option{auto}
+option. If no breakpoint is available at the time of the step, then the step
+is taken with interrupts enabled, i.e. the same way the @option{off} option
+does.
Default is @option{auto}.
@end deffn
@end itemize
Using @option{vectreset} is a safe option for all current Cortex-M cores.
This however has the disadvantage of only resetting the core, all peripherals
-are uneffected. A solution would be to use a @code{reset-init} event handler to manually reset
+are unaffected. A solution would be to use a @code{reset-init} event handler to manually reset
the peripherals.
@xref{targetevents,,Target Events}.
@end deffn
@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
"timer" or any new group created with addreg command.
@end deffn
+@section RISC-V Architecture
+
+@uref{http://riscv.org/, RISC-V} is a free and open ISA. OpenOCD supports JTAG
+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
+
+A @emph{hart} is a hardware thread. A hart may share resources (eg. FPU) with
+another hart, or may be a separate core. RISC-V treats those the same, and
+OpenOCD exposes each hart as a separate core.
+
+@subsection RISC-V Debug Configuration Commands
+
+@deffn Command {riscv expose_csrs} n0[-m0][,n1[-m1]]...
+Configure a list of inclusive ranges for CSRs to expose in addition to the
+standard ones. This must be executed before `init`.
+
+By default OpenOCD attempts to expose only CSRs that are mentioned in a spec,
+and then only if the corresponding extension appears to be implemented. This
+command can be used if OpenOCD gets this wrong, or a target implements custom
+CSRs.
+@end deffn
+
+@deffn Command {riscv set_command_timeout_sec} [seconds]
+Set the wall-clock timeout (in seconds) for individual commands. The default
+should work fine for all but the slowest targets (eg. simulators).
+@end deffn
+
+@deffn Command {riscv set_reset_timeout_sec} [seconds]
+Set the maximum time to wait for a hart to come out of reset after reset is
+deasserted.
+@end deffn
+
+@deffn Command {riscv set_scratch_ram} none|[address]
+Set the address of 16 bytes of scratch RAM the debugger can use, or 'none'.
+This is used to access 64-bit floating point registers on 32-bit targets.
+@end deffn
+
+@deffn Command {riscv set_prefer_sba} on|off
+When on, prefer to use System Bus Access to access memory. When off, prefer to
+use the Program Buffer to access memory.
+@end deffn
+
+@subsection RISC-V Authentication Commands
+
+The following commands can be used to authenticate to a RISC-V system. Eg. a
+trivial challenge-response protocol could be implemented as follows in a
+configuration file, immediately following @command{init}:
+@example
+set challenge [ocd_riscv authdata_read]
+riscv authdata_write [expr $challenge + 1]
+@end example
+
+@deffn Command {riscv authdata_read}
+Return the 32-bit value read from authdata. Note that to get read value back in
+a TCL script, it needs to be invoked as @command{ocd_riscv authdata_read}.
+@end deffn
+
+@deffn Command {riscv authdata_write} value
+Write the 32-bit value to authdata.
+@end deffn
+
+@subsection RISC-V DMI Commands
+
+The following commands allow direct access to the Debug Module Interface, which
+can be used to interact with custom debug features.
+
+@deffn Command {riscv dmi_read}
+Perform a 32-bit DMI read at address, returning the value. Note that to get
+read value back in a TCL script, it needs to be invoked as @command{ocd_riscv
+dmi_read}.
+@end deffn
+
+@deffn Command {riscv dmi_write} address value
+Perform a 32-bit DMI write of value at address.
+@end deffn
+
@anchor{softwaredebugmessagesandtracing}
@section Software Debug Messages and Tracing
@cindex Linux-ARM DCC support
@item @option{-tap @var{tapname}} ignore IR and DR headers and footers
specified by the SVF file with HIR, TIR, HDR and TDR commands;
instead, calculate them automatically according to the current JTAG
-chain configuration, targetting @var{tapname};
+chain configuration, targeting @var{tapname};
@item @option{[-]quiet} do not log every command before execution;
@item @option{[-]nil} ``dry run'', i.e., do not perform any operations
on the real interface;
@item @option{embKernel}
@item @option{mqx}
@item @option{uCOS-III}
+@item @option{nuttx}
@end itemize
@quotation Note
_mqx_kernel_data, MQX_init_struct.
@item uC/OS-III symbols
OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty
+@item nuttx symbols
+g_readytorun, g_tasklisttable
@end table
For most RTOS supported the above symbols will be exported by default. However for
@itemize @bullet
@item @b{cygwin} Running under Cygwin
-@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem.
+@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 sytem
+@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 choosen because today (March-2009) no distinction is made between Win32 and Win64.
+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
@cindex adaptive clocking
@*
-In digital circuit design it is often refered to as ``clock
+In digital circuit design it is often referred to as ``clock
synchronisation'' the JTAG interface uses one clock (TCK or TCLK)
operating at some speed, your CPU target is operating at another.
The two clocks are not synchronised, they are ``asynchronous''
claims to come with all the necessary DLLs. When using Cygwin, try launching
OpenOCD from the Cygwin shell.
-@item @b{Breakpoint Issue} I'm trying to set a breakpoint using GDB (or a frontend like Insight or
+@item @b{Breakpoint Issue} I'm trying to set a breakpoint using GDB (or a front-end like Insight or
Eclipse), but OpenOCD complains that "Info: arm7_9_common.c:213
arm7_9_add_breakpoint(): sw breakpoint requested, but software breakpoints not enabled".
gracefully stops.
@b{Debugging Interrupt Service Routines} - In your ISR before you call
-your C code, do the same - artifically push some zeros onto the stack,
+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
Yes; whenever you have more than one, you must declare them in
the same order used by the hardware.
-Many newer devices have multiple JTAG TAPs. For example: ST
-Microsystems STM32 chips have two TAPs, a ``boundary scan TAP'' and
+Many newer devices have multiple JTAG TAPs. For example:
+STMicroelectronics STM32 chips have two TAPs, a ``boundary scan TAP'' and
``Cortex-M3'' TAP. Example: The STM32 reference manual, Document ID:
RM0008, Section 26.5, Figure 259, page 651/681, the ``TDI'' pin is
connected to the boundary scan TAP, which then connects to the
@section Per Rule #1 - All Results are strings
Every Tcl command results in a string. The word ``result'' is used
-deliberatly. No result is just an empty string. Remember: @i{Rule #1 -
+deliberately. No result is just an empty string. Remember: @i{Rule #1 -
Everything is a string}
@section Tcl Quoting Operators
By now you should know $VARIABLES always start with a $DOLLAR
sign. BTW: To set a variable, you actually use the command ``set'', as
-in ``set VARNAME VALUE'' much like the ancient BASIC langauge ``let x
+in ``set VARNAME VALUE'' much like the ancient BASIC language ``let x
= 1'' statement, but without the equal sign.
@itemize @bullet
As a script is parsed, each (multi) line in the script file is
tokenised and according to the quoting rules. After tokenisation, that
-line is immedatly executed.
+line is immediately executed.
Multi line statements end with one or more ``still-open''
@{curly-braces@} which - eventually - closes a few lines later.
@end example
Real Tcl is nearly identical. Although the newer versions have
-introduced a byte-code parser and intepreter, but at the core, it
+introduced a byte-code parser and interpreter, but at the core, it
still operates in the same basic way.
@subsection FOR command implementation
Remember Rule #1 - You are a string.
The @b{first} helper parses and executes commands found in an ascii
-string. Commands can be seperated by semicolons, or newlines. While
+string. Commands can be separated by semicolons, or newlines. While
parsing, variables are expanded via the quoting rules.
The @b{second} helper evaluates an ascii string as a numerical
@}
$_TARGETNAME configure -event FOO someproc
#2 Good - no variables
- $_TARGETNAME confgure -event foo "this ; that;"
+ $_TARGETNAME configure -event foo "this ; that;"
#3 Good Curly Braces
$_TARGETNAME configure -event FOO @{
puts "Time: [date]"
@*There are 4 examples:
@enumerate
@item The TCLBODY is a simple string that happens to be a proc name
-@item The TCLBODY is several simple commands seperated by semicolons
+@item The TCLBODY is several simple commands separated by semicolons
@item The TCLBODY is a multi-line @{curly-brace@} quoted string
@item The TCLBODY is a string with variables that get expanded.
@end enumerate
Code Review / openocd.git / blobdiff