X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=a97ad85679034fa6f46cbf4cd179d763c4dbe214;hp=76e335b8f23c2466606b37baaa65a18b4b759223;hb=97c96ac13ff2d900345b71e12d1ac5c22417832f;hpb=1338cf60b91c582fa4b27d5226ab4374117be415 diff --git a/doc/openocd.texi b/doc/openocd.texi index 76e335b8f2..a97ad85679 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 @@ -666,7 +665,9 @@ to benefit from new features and bugfixes in Jim-Tcl. Properly installing OpenOCD sets up your operating system to grant it access to the debug adapters. On Linux, this usually involves installing a file -in @file{/etc/udev/rules.d,} so OpenOCD has permissions. MS-Windows needs +in @file{/etc/udev/rules.d,} so OpenOCD has permissions. An example rules file +that works for many common adapters is shipped with OpenOCD in the +@file{contrib} directory. MS-Windows needs complex and confusing driver configuration for every peripheral. Such issues are unique to each operating system, and are not detailed in this User's Guide. @@ -2107,6 +2108,17 @@ For an example of this scheme see LPC2000 target config files. The @code{init_boards} procedure is a similar concept concerning board config files (@xref{theinitboardprocedure,,The init_board procedure}.) +@anchor{theinittargeteventsprocedure} +@subsection The init_target_events procedure +@cindex init_target_events procedure + +A special procedure called @code{init_target_events} is run just after +@code{init_targets} (@xref{theinittargetsprocedure,,The init_targets +procedure}.) and before @code{init_board} +(@xref{theinitboardprocedure,,The init_board procedure}.) It is used +to set up default target events for the targets that do not have those +events already assigned. + @subsection ARM Core Specific Hacks If the chip has a DCC, enable it. If the chip is an ARM9 with some @@ -2572,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 @@ -2754,7 +2771,7 @@ minimal impact on the target system. Avoid floating inputs, conflicting outputs and initially asserted reset signals. @end deffn -@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask] +@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name] Creates a signal with the specified @var{name}, controlled by one or more FTDI GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO register bitmasks to tell the driver the connection and type of the output @@ -2777,6 +2794,10 @@ target without any buffer. The FTDI pin is then switched between output and input as necessary to provide the full set of low, high and Hi-Z characteristics. In all other cases, the pins specified in a signal definition are always driven by the FTDI. + +If @option{-alias} or @option{-nalias} is used, the signal is created +identical (or with data inverted) to an already specified signal +@var{name}. @end deffn @deffn {Command} {ftdi_set_signal} name @option{0}|@option{1}|@option{z} @@ -2882,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 @@ -3062,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}) @@ -3079,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 @@ -4148,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 @@ -4164,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 @@ -4197,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 @@ -4308,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 @@ -4322,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 @@ -4339,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.} @@ -4575,13 +4585,14 @@ depending on whether the breakpoint is in RAM or read only memory. @item @b{gdb-end} @* When the target has halted and GDB is not doing anything (see early halt) @item @b{gdb-flash-erase-start} -@* Before the GDB flash process tries to erase the flash +@* Before the GDB flash process tries to erase the flash (default is +@code{reset init}) @item @b{gdb-flash-erase-end} @* After the GDB flash process has finished erasing the flash @item @b{gdb-flash-write-start} @* Before GDB writes to the flash @item @b{gdb-flash-write-end} -@* After GDB writes to the flash +@* After GDB writes to the flash (default is @code{reset halt}) @item @b{gdb-start} @* Before the target steps, gdb is trying to start/resume the target @item @b{halted} @@ -4832,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 @@ -5021,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 @@ -5159,9 +5223,10 @@ supported.} @end deffn @deffn {Flash Driver} lpc2000 -Most members of the LPC1700, LPC1800, LPC2000 and LPC4300 microcontroller -families from NXP include internal flash and use Cortex-M3 (LPC1700, LPC1800), -Cortex-M4 (LPC4300) or ARM7TDMI (LPC2000) cores. +All members of the LPC11(x)00 and LPC1300 microcontroller families and most members +of the LPC1700, LPC1800, LPC2000 and LPC4300 microcontroller families from NXP +include internal flash and use Cortex-M0 (LPC11(x)00), Cortex-M3 (LPC1300, LPC1700, +LPC1800), Cortex-M4 (LPC4300) or ARM7TDMI (LPC2000) cores. @quotation Note There are LPC2000 devices which are not supported by the @var{lpc2000} @@ -5178,8 +5243,11 @@ which must appear in the following order: @option{lpc2000_v1} (older LPC21xx and LPC22xx) @option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx) @option{lpc1700} (LPC175x and LPC176x) -or @option{lpc4300} - available also as @option{lpc1800} alias (LPC18x[2357] and +@option{lpc4300} - available also as @option{lpc1800} alias (LPC18x[2357] and LPC43x[2357]) +@option{lpc1100} (LPC11(x)xx and LPC13xx) +or @option{auto} - automatically detects flash variant and size for LPC11(x)00, +LPC1300 and LPC1700 @item @var{clock_kHz} ... the frequency, in kiloHertz, at which the core is running @item @option{calc_checksum} ... optional (but you probably want to provide this!), @@ -5494,6 +5562,15 @@ the flash driver. @example flash bank $_FLASHNAME stm32lx 0 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 @@ -5687,6 +5764,23 @@ unlock str9 device. @end deffn +@deffn {Flash Driver} nrf51 +All members of the nRF51 microcontroller families from Nordic Semiconductor +include internal flash and use ARM Cortex-M0 core. + +@example +flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME +@end example + +Some nrf51-specific commands are defined: + +@deffn Command {nrf51 mass_erase} +Erases the contents of the code memory and user information +configuration registers as well. It must be noted that this command +works only for chips that do not have factory pre-programmed region 0 +code. +@end deffn +@end deffn @section mFlash @@ -6692,10 +6786,12 @@ using @var{mask} to mark ``don't care'' fields. @section Misc Commands @cindex profiling -@deffn Command {profile} seconds filename +@deffn Command {profile} seconds filename [start end] Profiling samples the CPU's program counter as quickly as possible, which is useful for non-intrusive stochastic profiling. -Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format. +Saves up to 10000 samples in @file{filename} using ``gmon.out'' +format. Optional @option{start} and @option{end} parameters allow to +limit the address range. @end deffn @deffn Command {version} @@ -8410,7 +8506,7 @@ should be passed in to the proc in question. By "low-level," we mean commands that a human would typically not invoke directly. -Low-level commands are (should be) prefixed with "ocd_"; e.g. +Some low-level commands need to be prefixed with "ocd_"; e.g. @command{ocd_flash_banks} is the low-level API upon which @command{flash banks} is implemented. @@ -8424,6 +8520,16 @@ Convert a Tcl array to memory locations and write the values @item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...] Return information about the flash banks + +@item @b{capture} <@var{command}> + +Run <@var{command}> and return full log output that was produced during +its execution. Example: + +@example +> capture "reset init" +@end example + @end itemize OpenOCD commands can consist of two words, e.g. "flash banks". The @@ -8458,6 +8564,24 @@ We should add support for a variable like Tcl variable is jim, not real tcl). @end quotation +@section Tcl RPC server +@cindex RPC + +OpenOCD provides a simple RPC server that allows to run arbitrary Tcl +commands and receive the results. + +To access it, your application needs to connect to a configured TCP port +(see @command{tcl_port}). Then it can pass any string to the +interpreter terminating it with @code{0x1a} and wait for the return +value (it will be terminated with @code{0x1a} as well). This can be +repeated as many times as desired without reopening the connection. + +Remember that most of the OpenOCD commands need to be prefixed with +@code{ocd_} to get the results back. Sometimes you might also need the +@command{capture} command. + +See @file{contrib/rpc_examples/} for specific client implementations. + @node FAQ @chapter FAQ @cindex faq