X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=95c20541924246d7b691c83f45f5a52836bbf552;hb=b01952d78cc82b192c66664b7c59df728c4f22fe;hp=15965dabb6f388055d1e54c271466c46c814e27d;hpb=7568a91c8e2398a113f0b40a2a24a1b91ed12c95;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 15965dabb6..95c2054192 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 @@ -3100,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 @@ -4169,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 @@ -4185,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 @@ -4218,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 @@ -4329,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 @@ -4343,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 @@ -4360,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.} @@ -4854,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 @@ -5043,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 @@ -5398,6 +5440,40 @@ This will remove any Code Protection. @end deffn @end deffn +@deffn {Flash Driver} psoc4 +All members of the PSoC 41xx/42xx microcontroller family from Cypress +include internal flash and use ARM Cortex M0 cores. +The driver automatically recognizes a number of these chips using +the chip identification register, and autoconfigures itself. + +Note: Erased internal flash reads as 00. +System ROM of PSoC 4 does not implement erase of a flash sector. + +@example +flash bank $_FLASHNAME psoc4 0 0 0 0 $_TARGETNAME +@end example + +psoc4-specific commands +@deffn Command {psoc4 flash_autoerase} num (on|off) +Enables or disables autoerase mode for a flash bank. + +If flash_autoerase is off, use mass_erase before flash programming. +Flash erase command fails if region to erase is not whole flash memory. + +If flash_autoerase is on, a sector is both erased and programmed in one +system ROM call. Flash erase command is ignored. +This mode is suitable for gdb load. + +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {psoc4 mass_erase} num +Erases the contents of the flash memory, protection and security lock. + +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn +@end deffn + @deffn {Flash Driver} stellaris All members of the Stellaris LM3Sxxx microcontroller family from Texas Instruments @@ -5509,17 +5585,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