X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=817c4f93f3f258fe205b83eeef5c7c4e3f8641cd;hp=353daa4f4b24a3363feaba8be5fe3834c6b72582;hb=cf692abe83a90f74cb21b1864f348cd52fe26454;hpb=0eed61b7c4cb31338562db426cea0d1a999e0d9f diff --git a/doc/openocd.texi b/doc/openocd.texi index 353daa4f4b..817c4f93f3 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -168,7 +168,7 @@ STM32x). Preliminary support for various NAND flash controllers The OpenOCD web site provides the latest public news from the community: -@uref{http://openocd.berlios.de/web/} +@uref{http://openocd.sourceforge.net/web/} @section Latest User's Guide: @@ -176,11 +176,11 @@ The user's guide you are now reading may not be the latest one available. A version for more recent code may be available. Its HTML form is published irregularly at: -@uref{http://openocd.berlios.de/doc/html/index.html} +@uref{http://openocd.sourceforge.net/doc/html/index.html} PDF form is likewise published at: -@uref{http://openocd.berlios.de/doc/pdf/openocd.pdf} +@uref{http://openocd.sourceforge.net/doc/pdf/openocd.pdf} @section OpenOCD User's Forum @@ -241,7 +241,7 @@ providing a Doxygen reference manual. This document contains more technical information about the software internals, development processes, and similar documentation: -@uref{http://openocd.berlios.de/doc/doxygen/index.html} +@uref{http://openocd.sourceforge.net/doc/doxygen/index.html} This document is a work-in-progress, but contributions would be welcome to fill in the gaps. All of the source files are provided in-tree, @@ -252,7 +252,7 @@ listed in the Doxyfile configuration in the top of the source tree. The OpenOCD Developer Mailing List provides the primary means of communication between developers: -@uref{https://lists.berlios.de/mailman/listinfo/openocd-development} +@uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel} Discuss and submit patches to this list. The @file{PATCHES.txt} file contains basic information about how @@ -526,7 +526,7 @@ OpenOCD mailing list. @item @b{Jim vs. Tcl} @* Jim-Tcl is a stripped down version of the well known Tcl language, which can be found here: @url{http://www.tcl.tk}. Jim-Tcl has far -fewer features. Jim-Tcl is a single .C file and a single .H file and +fewer features. Jim-Tcl is several dozens of .C files and .H files and implements the basic Tcl command set. In contrast: Tcl 8.6 is a 4.2 MB .zip file containing 1540 files. @@ -632,7 +632,7 @@ If all goes well you'll see output something like @example Open On-Chip Debugger 0.4.0 (2010-01-14-15:06) For bug reports, read - http://openocd.berlios.de/doc/doxygen/bugs.html + http://openocd.sourceforge.net/doc/doxygen/bugs.html Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3) @end example @@ -676,8 +676,6 @@ setting from within a telnet or gdb session using @command{debug_level You can redirect all output from the daemon to a file using the @option{-l } switch. -For details on the @option{-p} option. @xref{Connecting to GDB}. - Note! OpenOCD will launch the GDB & telnet server even if it can not establish a connection with the target. In general, it is possible for the JTAG controller to be unresponsive until the target is set up @@ -1279,7 +1277,7 @@ at91sam3u4c.cfg lm3s9b9x.cfg samsung_s3c6410.cfg at91sam3u4e.cfg lpc1768.cfg sharp_lh79532.cfg at91sam3uXX.cfg lpc2103.cfg smdk6410.cfg at91sam7sx.cfg lpc2124.cfg smp8634.cfg -at91sam9260.cfg lpc2129.cfg stm32.cfg +at91sam9260.cfg lpc2129.cfg stm32f1x.cfg c100.cfg lpc2148.cfg str710.cfg c100config.tcl lpc2294.cfg str730.cfg c100helper.tcl lpc2378.cfg str750.cfg @@ -1680,6 +1678,64 @@ $_TARGETNAME configure -work-area-phys 0x00200000 \ -work-area-size 0x4000 -work-area-backup 0 @end example +@anchor{Define CPU targets working in SMP} +@subsection Define CPU targets working in SMP +@cindex SMP +After setting targets, you can define a list of targets working in SMP. + +@example +set _TARGETNAME_1 $_CHIPNAME.cpu1 +set _TARGETNAME_2 $_CHIPNAME.cpu2 +target create $_TARGETNAME_1 cortex_a8 -chain-position $_CHIPNAME.dap \ +-coreid 0 -dbgbase $_DAP_DBG1 +target create $_TARGETNAME_2 cortex_a8 -chain-position $_CHIPNAME.dap \ +-coreid 1 -dbgbase $_DAP_DBG2 +#define 2 targets working in smp. +target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1 +@end example +In the above example on cortex_a8, 2 cpus are working in SMP. +In SMP only one GDB instance is created and : +@itemize @bullet +@item a set of hardware breakpoint sets the same breakpoint on all targets in the list. +@item halt command triggers the halt of all targets in the list. +@item resume command triggers the write context and the restart of all targets in the list. +@item following a breakpoint: the target stopped by the breakpoint is displayed to the GDB session. +@item dedicated GDB serial protocol packets are implemented for switching/retrieving the target +displayed by the GDB session @pxref{Using openocd SMP with GDB}. +@end itemize + +The SMP behaviour can be disabled/enabled dynamically. On cortex_a8 following +command have been implemented. +@itemize @bullet +@item cortex_a8 smp_on : enable SMP mode, behaviour is as described above. +@item cortex_a8 smp_off : disable SMP mode, the current target is the one +displayed in the GDB session, only this target is now controlled by GDB +session. This behaviour is useful during system boot up. +@item cortex_a8 smp_gdb : display/fix the core id displayed in GDB session see +following example. +@end itemize + +@example +>cortex_a8 smp_gdb +gdb coreid 0 -> -1 +#0 : coreid 0 is displayed to GDB , +#-> -1 : next resume triggers a real resume +> cortex_a8 smp_gdb 1 +gdb coreid 0 -> 1 +#0 :coreid 0 is displayed to GDB , +#->1 : next resume displays coreid 1 to GDB +> resume +> cortex_a8 smp_gdb +gdb coreid 1 -> 1 +#1 :coreid 1 is displayed to GDB , +#->1 : next resume displays coreid 1 to GDB +> cortex_a8 smp_gdb -1 +gdb coreid 1 -> -1 +#1 :coreid 1 is displayed to GDB, +#->-1 : next resume triggers a real resume +@end example + + @subsection Chip Reset Setup As a rule, you should put the @command{reset_config} command @@ -2265,6 +2321,43 @@ ft2232_vid_pid 0x0403 0xbdc8 @end example @end deffn +@deffn {Interface Driver} {remote_bitbang} +Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection +with a remote process and sends ASCII encoded bitbang requests to that process +instead of directly driving JTAG. + +The remote_bitbang driver is useful for debugging software running on +processors which are being simulated. + +@deffn {Config Command} {remote_bitbang_port} number +Specifies the TCP port of the remote process to connect to or 0 to use UNIX +sockets instead of TCP. +@end deffn + +@deffn {Config Command} {remote_bitbang_host} hostname +Specifies the hostname of the remote process to connect to using TCP, or the +name of the UNIX socket to use if remote_bitbang_port is 0. +@end deffn + +For example, to connect remotely via TCP to the host foobar you might have +something like: + +@example +interface remote_bitbang +remote_bitbang_port 3335 +remote_bitbang_host foobar +@end example + +To connect to another process running locally via UNIX sockets with socket +named mysocket: + +@example +interface remote_bitbang +remote_bitbang_port 0 +remote_bitbang_host mysocket +@end example +@end deffn + @deffn {Interface Driver} {usb_blaster} USB JTAG/USB-Blaster compatibles over one of the userspace libraries for FTDI chips. These interfaces have several commands, used to @@ -2319,6 +2412,26 @@ This is a write-once setting. @deffn {Interface Driver} {jlink} Segger jlink USB adapter +@c command: jlink caps +@c dumps jlink capabilities +@c command: jlink config +@c access J-Link configurationif no argument this will dump the config +@c command: jlink config kickstart [val] +@c set Kickstart power on JTAG-pin 19. +@c command: jlink config mac_address [ff:ff:ff:ff:ff:ff] +@c set the MAC Address +@c command: jlink config ip [A.B.C.D[/E] [F.G.H.I]] +@c set the ip address of the J-Link Pro, " +@c where A.B.C.D is the ip, +@c E the bit of the subnet mask +@c F.G.H.I the subnet mask +@c command: jlink config reset +@c reset the current config +@c command: jlink config save +@c save the current config +@c command: jlink config usb_address [0x00 to 0x03 or 0xff] +@c set the USB-Address, +@c This will change the product id @c command: jlink info @c dumps status @c command: jlink hw_jtag (2|3) @@ -3526,14 +3639,7 @@ At this writing, the supported CPU types and variants are: (Support for this is preliminary and incomplete.) @item @code{cortex_a8} -- this is an ARMv7 core with an MMU @item @code{cortex_m3} -- this is an ARMv7 core, supporting only the -compact Thumb2 instruction set. It supports one variant: -@itemize @minus -@item @code{lm3s} ... Use this when debugging older Stellaris LM3S targets. -This will cause OpenOCD to use a software reset rather than asserting -SRST, to avoid a issue with clearing the debug registers. -This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will -be detected and the normal reset behaviour used. -@end itemize +compact Thumb2 instruction set. @item @code{dragonite} -- resembles arm966e @item @code{dsp563xx} -- implements Freescale's 24-bit DSP. (Support for this is still incomplete.) @@ -4686,44 +4792,51 @@ applied to all of them. @end quotation @end deffn -@deffn {Flash Driver} stm32x -All members of the STM32 microcontroller family from ST Microelectronics +@deffn {Flash Driver} stm32f1x +All members of the STM32f1x microcontroller family from ST Microelectronics include internal flash and use ARM Cortex M3 cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @example -flash bank $_FLASHNAME stm32x 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME @end example -Some stm32x-specific commands -@footnote{Currently there is a @command{stm32x mass_erase} command. +Some stm32f1x-specific commands +@footnote{Currently there is a @command{stm32f1x mass_erase} command. That seems pointless since the same effect can be had using the standard @command{flash erase_address} command.} are defined: -@deffn Command {stm32x lock} num +@deffn Command {stm32f1x lock} num Locks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {stm32x unlock} num +@deffn Command {stm32f1x unlock} num Unlocks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {stm32x options_read} num +@deffn Command {stm32f1x options_read} num Read and display the stm32 option bytes written by -the @command{stm32x options_write} command. +the @command{stm32f1x options_write} command. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP}) +@deffn Command {stm32f1x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP}) Writes the stm32 option byte with the specified values. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @end deffn +@deffn {Flash Driver} stm32f2x +All members of the STM32f2x microcontroller family from ST Microelectronics +include internal flash and use ARM Cortex M3 cores. +The driver automatically recognizes a number of these chips using +the chip identification register, and autoconfigures itself. +@end deffn + @deffn {Flash Driver} str7x All members of the STR7 microcontroller family from ST Microelectronics include internal flash and use ARM7TDMI cores. @@ -4806,6 +4919,19 @@ flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME @end example @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 @var{fm3} driver uses the @var{target} parameter to select the +correct bank config, it can currently be one of the following: +@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu}, +@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}. + +@example +flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME +@end example +@end deffn + @subsection str9xpec driver @cindex str9xpec @@ -5768,7 +5894,7 @@ Loads an image stored in memory by @command{fast_load_image} to the current target. Must be preceeded by fast_load_image. @end deffn -@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}] +@deffn Command {fast_load_image} filename address [@option{bin}|@option{ihex}|@option{elf}|@option{s19}] Normally you should be using @command{load_image} or GDB load. However, for testing purposes or when I/O overhead is significant(OpenOCD running on an embedded host), storing the image in memory and uploading the image to the target @@ -5780,10 +5906,10 @@ separately. @end deffn @anchor{load_image} -@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}] @option{min_addr} @option{max_length}] +@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}|@option{s19}] @option{min_addr} @option{max_length}] 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}, or @option{elf}). +(@option{bin}, @option{ihex}, @option{elf}, or @option{s19}). In addition the following arguments may be specifed: @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. @@ -6642,8 +6768,21 @@ If @var{value} is defined, first assigns that. @subsection Cortex-M3 specific commands @cindex Cortex-M3 -@deffn Command {cortex_m3 maskisr} (@option{on}|@option{off}) +@deffn Command {cortex_m3 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 +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. + +Default is @option{auto}. @end deffn @deffn Command {cortex_m3 vector_catch} [@option{all}|@option{none}|list] @@ -7255,6 +7394,55 @@ $_TARGETNAME configure -event EVENTNAME BODY To verify any flash programming the GDB command @option{compare-sections} can be used. +@anchor{Using openocd SMP with GDB} +@section Using openocd SMP with GDB +@cindex SMP +For SMP support following GDB serial protocol packet have been defined : +@itemize @bullet +@item j - smp status request +@item J - smp set request +@end itemize + +OpenOCD implements : +@itemize @bullet +@item @option{jc} packet for reading core id displayed by +GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or + @option{E01} for target not smp. +@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue +(core id -1 is reserved for returning to normal resume mode). Reply @option{E01} +for target not smp or @option{OK} on success. +@end itemize + +Handling of this packet within GDB can be done : +@itemize @bullet +@item by the creation of an internal variable (i.e @option{_core}) by mean +of function allocate_computed_value allowing following GDB command. +@example +set $_core 1 +#Jc01 packet is sent +print $_core +#jc packet is sent and result is affected in $ +@end example + +@item by the usage of GDB maintenance command as described in following example (2 +cpus in SMP with core id 0 and 1 @pxref{Define CPU targets working in SMP}). + +@example +# toggle0 : force display of coreid 0 +define toggle0 +maint packet Jc0 +continue +main packet Jc-1 +end +# toggle1 : force display of coreid 1 +define toggle1 +maint packet Jc1 +continue +main packet Jc-1 +end +@end example +@end itemize + @node Tcl Scripting API @chapter Tcl Scripting API