X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=18e18b98364c91e460c3208b89f76e44fd1f4b01;hp=e51de4de9108a01607e48faa8b6f5211c212eb00;hb=873774992d8739cf08095a03d55fec49cd4b5987;hpb=a87e699edf7d4d2f772bfa8f50535ad9f3086a56 diff --git a/doc/openocd.texi b/doc/openocd.texi index e51de4de91..18e18b9836 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -288,12 +288,11 @@ communication between developers: @uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel} -@section OpenOCD Bug Database +@section OpenOCD Bug Tracker -During the 0.4.x release cycle the OpenOCD project team began -using Trac for its bug database: +The OpenOCD Bug Tracker is hosted on SourceForge: -@uref{https://sourceforge.net/apps/trac/openocd} +@uref{https://sourceforge.net/p/openocd/tickets/} @node Debug Adapter Hardware @@ -2585,6 +2584,11 @@ cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204 @end example @end deffn +@deffn {Config Command} {cmsis_dap_serial} [serial] +Specifies the @var{serial} of the CMSIS-DAP device to use. +If not specified, serial numbers are not considered. +@end deffn + @deffn {Command} {cmsis-dap info} Display various device information, like hardware version, firmware version, current bus status. @end deffn @@ -2899,7 +2903,7 @@ This is a write-once setting. @end deffn @deffn {Interface Driver} {jlink} -Segger J-Link family of USB adapters. It currently supports only the JTAG transport. +Segger J-Link family of USB adapters. It currently supports JTAG and SWD transports. @quotation Compatibility Note Segger released many firmware versions for the many harware versions they @@ -3079,13 +3083,17 @@ 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 +versions of firmware where serial number is reset after first use. Suggest +using ST firmware update utility to upgrade STLINK firmware even if current +version reported is V2.J21.S4. @deffn {Config Command} {hla_device_desc} description Currently Not Supported. @end deffn @deffn {Config Command} {hla_serial} serial -Currently Not Supported. +Specifies the serial number of the adapter. @end deffn @deffn {Config Command} {hla_layout} (@option{stlink}|@option{icdi}) @@ -3096,6 +3104,11 @@ Specifies the adapter layout to use. The vendor ID and product ID of the device. @end deffn +@deffn {Command} {hla_command} command +Execute a custom adapter-specific command. The @var{command} string is +passed as is to the underlying adapter layout handler. +@end deffn + @deffn {Config Command} {trace} source_clock_hz [output_file_path] Enable SWO tracing (if supported). The source clock rate for the trace port must be specified, this is typically the CPU clock rate. If @@ -4165,10 +4178,9 @@ the given target with the given @var{name}; this is only relevant on boards which have more than one target. @end deffn -@section Target CPU Types and Variants +@section Target CPU Types @cindex target type @cindex CPU type -@cindex CPU variant Each target has a @dfn{CPU type}, as shown in the output of the @command{targets} command. You need to specify that type @@ -4181,20 +4193,13 @@ what core-specific commands may be available (@pxref{Architecture and Core Commands}), and more. -For some CPU types, OpenOCD also defines @dfn{variants} which -indicate differences that affect their handling. -For example, a particular implementation bug might need to be -worked around in some chip versions. - It's easy to see what target types are supported, since there's a command to list them. -However, there is currently no way to list what target variants -are supported (other than by reading the OpenOCD source code). @anchor{targettypes} @deffn Command {target types} Lists all supported target types. -At this writing, the supported CPU types and variants are: +At this writing, the supported CPU types are: @itemize @bullet @item @code{arm11} -- this is a generation of ARMv6 cores @@ -4214,17 +4219,9 @@ compact Thumb2 instruction set. (Support for this is still incomplete.) @item @code{fa526} -- resembles arm920 (w/o Thumb) @item @code{feroceon} -- resembles arm926 -@item @code{mips_m4k} -- a MIPS core. This supports one variant: +@item @code{mips_m4k} -- a MIPS core @item @code{xscale} -- this is actually an architecture, not a CPU type. It is based on the ARMv5 architecture. -There are several variants defined: -@itemize @minus -@item @code{ixp42x}, @code{ixp45x}, @code{ixp46x}, -@code{pxa27x} ... instruction register length is 7 bits -@item @code{pxa250}, @code{pxa255}, -@code{pxa26x} ... instruction register length is 5 bits -@item @code{pxa3xx} ... instruction register length is 11 bits -@end itemize @item @code{openrisc} -- this is an OpenRISC 1000 core. The current implementation supports three JTAG TAP cores: @itemize @minus @@ -4325,7 +4322,6 @@ and in other places the target needs to be identified. @item @var{configparams} ... all parameters accepted by @command{$target_name configure} are permitted. If the target is big-endian, set it here with @code{-endian big}. -If the variant matters, set it here with @code{-variant}. You @emph{must} set the @code{-chain-position @var{dotted.name}} here. @end itemize @@ -4339,7 +4335,7 @@ using the @command{$target_name cget} command. @emph{Warning:} changing some of these after setup is dangerous. For example, moving a target from one TAP to another; -and changing its endianness or variant. +and changing its endianness. @itemize @bullet @@ -4356,9 +4352,6 @@ Calling this twice with two different event names assigns two different handlers, but calling it twice with the same event name assigns only one handler. -@item @code{-variant} @var{name} -- specifies a variant of the target, -which OpenOCD needs to know about. - @item @code{-work-area-backup} (@option{0}|@option{1}) -- says whether the work area gets backed up; by default, @emph{it is not backed up.} @@ -4850,6 +4843,7 @@ The @var{num} parameter is a value shown by @command{flash banks}. @deffn Command {flash write_image} [erase] [unlock] filename [offset] [type] Write the image @file{filename} to the current target's flash bank(s). +Only loadable sections from the image are written. A relocation @var{offset} may be specified, in which case it is added to the base address for each section in the image. The file [@var{type}] can be specified @@ -5039,6 +5033,58 @@ flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME @end example @end deffn +@anchor{at91samd} +@deffn {Flash Driver} at91samd +@cindex at91samd + +@deffn Command {at91samd chip-erase} +Issues a complete Flash erase via the Device Service Unit (DSU). This can be +used to erase a chip back to its factory state and does not require the +processor to be halted. +@end deffn + +@deffn Command {at91samd set-security} +Secures the Flash via the Set Security Bit (SSB) command. This prevents access +to the Flash and can only be undone by using the chip-erase command which +erases the Flash contents and turns off the security bit. Warning: at this +time, openocd will not be able to communicate with a secured chip and it is +therefore not possible to chip-erase it without using another tool. + +@example +at91samd set-security enable +@end example +@end deffn + +@deffn Command {at91samd eeprom} +Shows or sets the EEPROM emulation size configuration, stored in the User Row +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 +the same as the minimum that the hardware supports. Set the EEPROM size to 0 +in order to disable this feature. + +@example +at91samd eeprom +at91samd eeprom 1024 +@end example +@end deffn + +@deffn Command {at91samd bootloader} +Shows or sets the bootloader size configuration, stored in the User Row of the +Flash. This is called the BOOTPROT region. When setting, the bootloader 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. Setting the bootloader size to 0 disables bootloader protection. + +@example +at91samd bootloader +at91samd bootloader 16384 +@end example +@end deffn + +@end deffn + @anchor{at91sam3} @deffn {Flash Driver} at91sam3 @cindex at91sam3 @@ -5505,17 +5551,28 @@ The @var{num} parameter is a value shown by @command{flash banks}. @deffn {Flash Driver} stm32lx All members of the STM32L microcontroller families from ST Microelectronics -include internal flash and use ARM Cortex-M3 cores. +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. Note that some devices have been found that have a flash size register that contains an invalid value, to workaround this issue you can override the probed value used by -the flash driver. +the flash driver. If you use 0 as the bank base address, it tells the +driver to autodetect the bank location assuming you're configuring the +second bank. @example -flash bank $_FLASHNAME stm32lx 0 0x20000 0 0 $_TARGETNAME +flash bank $_FLASHNAME stm32lx 0x08000000 0x20000 0 0 $_TARGETNAME @end example + +Some stm32lx-specific commands are defined: + +@deffn Command {stm32lx mass_erase} num +Mass erases the entire stm32lx device (all flash banks and EEPROM +data). This is the only way to unlock a protected flash (unless RDP +Level is 2 which can't be unlocked at all). +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn @end deffn @deffn {Flash Driver} str7x