X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=d4e60a8042bd049bce7387dbb2e6a52e1c32588c;hp=285603a9588e1c88d6b97d2720c111a6e97dde0e;hb=3ea9e62189205cfa84a04ec6955aaf1f5184a937;hpb=e7965cd3eb6204e618f9555331b7172e3dba7df8 diff --git a/doc/openocd.texi b/doc/openocd.texi index 285603a958..d4e60a8042 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -23,7 +23,7 @@ of the Open On-Chip Debugger (OpenOCD). @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk} @item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com} @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com} -@item Copyright @copyright{} 2009 David Brownell +@item Copyright @copyright{} 2009-2010 David Brownell @end itemize @quotation @@ -60,7 +60,7 @@ Free Documentation License''. @menu * About:: About OpenOCD -* Developers:: OpenOCD Developers +* Developers:: OpenOCD Developer Resources * JTAG Hardware Dongles:: JTAG Hardware Dongles * About JIM-Tcl:: About JIM-Tcl * Running:: Running OpenOCD @@ -223,9 +223,16 @@ communication between developers: @uref{https://lists.berlios.de/mailman/listinfo/openocd-development} Discuss and submit patches to this list. -The @file{PATCHES} file contains basic information about how +The @file{PATCHES.txt} file contains basic information about how to prepare patches. +@section OpenOCD Bug Database + +During the 0.4.x release cycle the OpenOCD project team began +using Trac for its bug database: + +@uref{https://sourceforge.net/apps/trac/openocd} + @node JTAG Hardware Dongles @chapter JTAG Hardware Dongles @@ -513,9 +520,10 @@ bash$ openocd --help --pipe | -p use pipes when talking to gdb @end verbatim -By default OpenOCD reads the configuration file @file{openocd.cfg}. -To specify a different (or multiple) -configuration file, you can use the @option{-f} option. For example: +If you don't give any @option{-f} or @option{-c} options, +OpenOCD tries to read the configuration file @file{openocd.cfg}. +To specify one or more different +configuration files, use @option{-f} options. For example: @example openocd -f config1.cfg -f config2.cfg -f config3.cfg @@ -942,6 +950,33 @@ handling issues like: @itemize @bullet +@item @b{Watchdog Timers}... +Watchog 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 +and reset the timer ... potentially causing resets in the middle of +your debug sessions. + +It's rarely a good idea to disable such watchdogs, since their usage +needs to be debugged just like all other parts of your firmware. +That might however be your only option. + +Look instead for chip-specific ways to stop the watchdog from counting +while the system is in a debug halt state. It may be simplest to set +that non-counting mode in your debugger startup scripts. You may however +need a different approach when, for example, a motor could be physically +damaged by firmware remaining inactive in a debug halt state. That might +involve a type of firmware mode where that "non-counting" mode is disabled +at the beginning then re-enabled at the end; a watchdog reset might fire +and complicate the debug session, but hardware (or people) would be +protected.@footnote{Note that many systems support a "monitor mode" debug +that is a somewhat cleaner way to address such issues. You can think of +it as only halting part of the system, maybe just one task, +instead of the whole thing. +At this writing, January 2010, OpenOCD based debugging does not support +monitor mode debug, only "halt mode" debug.} + @item @b{ARM Semihosting}... @cindex ARM semihosting When linked with a special runtime library provided with many @@ -964,7 +999,12 @@ via the @code{WFI} instruction (or its coprocessor equivalent, before ARMv7). You may want to @emph{disable that instruction} in source code, or otherwise prevent using that state, -to ensure you can get JTAG access at any time. +to ensure you can get JTAG access at any time.@footnote{As a more +polite alternative, some processors have special debug-oriented +registers which can be used to change various features including +how the low power states are clocked while debugging. +The STM32 DBGMCU_CR register is an example; at the cost of extra +power consumption, JTAG can be used during low power states.} For example, the OpenOCD @command{halt} command may not work for an idle processor otherwise. @@ -995,6 +1035,86 @@ various kinds of message. @end itemize +@section Target Hardware Setup + +Chip vendors often provide software development boards which +are highly configurable, so that they can support all options +that product boards may require. @emph{Make sure that any +jumpers or switches match the system configuration you are +working with.} + +Common issues include: + +@itemize @bullet + +@item @b{JTAG setup} ... +Boards may support more than one JTAG configuration. +Examples include jumpers controlling pullups versus pulldowns +on the nTRST and/or nSRST signals, and choice of connectors +(e.g. which of two headers on the base board, +or one from a daughtercard). +For some Texas Instruments boards, you may need to jumper the +EMU0 and EMU1 signals (which OpenOCD won't currently control). + +@item @b{Boot Modes} ... +Complex chips often support multiple boot modes, controlled +by external jumpers. Make sure this is set up correctly. +For example many i.MX boards from NXP need to be jumpered +to "ATX mode" to start booting using the on-chip ROM, when +using second stage bootloader code stored in a NAND flash chip. + +Such explicit configuration is common, and not limited to +booting from NAND. You might also need to set jumpers to +start booting using code loaded from an MMC/SD card; external +SPI flash; Ethernet, UART, or USB links; NOR flash; OneNAND +flash; some external host; or various other sources. + + +@item @b{Memory Addressing} ... +Boards which support multiple boot modes may also have jumpers +to configure memory addressing. One board, for example, jumpers +external chipselect 0 (used for booting) to address either +a large SRAM (which must be pre-loaded via JTAG), NOR flash, +or NAND flash. When it's jumpered to address NAND flash, that +board must also be told to start booting from on-chip ROM. + +Your @file{board.cfg} file may also need to be told this jumper +configuration, so that it can know whether to declare NOR flash +using @command{flash bank} or instead declare NAND flash with +@command{nand device}; and likewise which probe to perform in +its @code{reset-init} handler. + +A closely related issue is bus width. Jumpers might need to +distinguish between 8 bit or 16 bit bus access for the flash +used to start booting. + +@item @b{Peripheral Access} ... +Development boards generally provide access to every peripheral +on the chip, sometimes in multiple modes (such as by providing +multiple audio codec chips). +This interacts with software +configuration of pin multiplexing, where for example a +given pin may be routed either to the MMC/SD controller +or the GPIO controller. It also often interacts with +configuration jumpers. One jumper may be used to route +signals to an MMC/SD card slot or an expansion bus (which +might in turn affect booting); others might control which +audio or video codecs are used. + +@end itemize + +Plus you should of course have @code{reset-init} event handlers +which set up the hardware to match that jumper configuration. +That includes in particular any oscillator or PLL used to clock +the CPU, and any memory controllers needed to access external +memory and peripherals. Without such handlers, you won't be +able to access those resources without working target firmware +which can do that setup ... this can be awkward when you're +trying to debug that target firmware. Even if there's a ROM +bootloader which handles a few issues, it rarely provides full +access to all board-specific capabilities. + + @node Config File Guidelines @chapter Config File Guidelines @@ -1721,17 +1841,17 @@ In such cases, just specify the relevant port number as zero. If you disable all access through TCP/IP, you will need to use the command line @option{-pipe} option. -@deffn {Command} gdb_port (number) +@deffn {Command} gdb_port [number] @cindex GDB server Specify or query the first port used for incoming GDB connections. The GDB port for the first target will be gdb_port, the 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 specified as zero, this port is not activated. +When specified as zero, GDB remote access ports are not activated. @end deffn -@deffn {Command} tcl_port (number) +@deffn {Command} tcl_port [number] Specify or query the port used for a simplified RPC connection that can be used by clients to issue TCL commands and get the output from the Tcl engine. @@ -1741,7 +1861,7 @@ the port @var{number} defaults to 6666. When specified as zero, this port is not activated. @end deffn -@deffn {Command} telnet_port (number) +@deffn {Command} telnet_port [number] Specify or query the port on which to listen for incoming telnet connections. This port is intended for interaction with one human through TCL commands. @@ -2073,9 +2193,11 @@ $_TARGETNAME configure -event reset-assert \ Gateworks GW16012 JTAG programmer. This has one driver-specific command: -@deffn {Config Command} {parport_port} number -Specifies either the address of the I/O port (default: 0x378 for LPT1) or -the number of the @file{/dev/parport} device. +@deffn {Config Command} {parport_port} [port_number] +Display either the address of the I/O port +(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device. +If a parameter is provided, first switch to use that port. +This is a write-once setting. @end deffn @end deffn @@ -2094,7 +2216,8 @@ These interfaces have several commands, used to configure the driver before initializing the JTAG scan chain: @deffn {Config Command} {parport_cable} name -The layout of the parallel port cable used to connect to the target. +Set the layout of the parallel port cable used to connect to the target. +This is a write-once setting. Currently valid cable @var{name} values include: @itemize @minus @@ -2122,9 +2245,11 @@ several clones, such as the Olimex ARM-JTAG @end itemize @end deffn -@deffn {Config Command} {parport_port} number -Either the address of the I/O port (default: 0x378 for LPT1) or the number of -the @file{/dev/parport} device +@deffn {Config Command} {parport_port} [port_number] +Display either the address of the I/O port +(default: 0x378 for LPT1) or the number of the @file{/dev/parport} device. +If a parameter is provided, first switch to use that port. +This is a write-once setting. When using PPDEV to access the parallel port, use the number of the parallel port: @option{parport_port 0} (the default). If @option{parport_port 0x378} is specified @@ -2167,25 +2292,26 @@ match for the jtag_khz rate you specified; be conservative. @end quotation @end deffn -@deffn {Config Command} {parport_write_on_exit} (on|off) +@deffn {Config Command} {parport_write_on_exit} (@option{on}|@option{off}) This will configure the parallel driver to write a known -cable-specific value to the parallel interface on exiting OpenOCD +cable-specific value to the parallel interface on exiting OpenOCD. @end deffn For example, the interface configuration file for a -classic ``Wiggler'' cable might look something like this: +classic ``Wiggler'' cable on LPT2 might look something like this: @example interface parport -parport_port 0xc8b8 +parport_port 0x278 parport_cable wiggler @end example @end deffn @deffn {Interface Driver} {presto} ASIX PRESTO USB JTAG programmer. -@c command: presto_serial str -@c sets serial number +@deffn {Config Command} {presto_serial} serial_string +Configures the USB serial number of the Presto device to use. +@end deffn @end deffn @deffn {Interface Driver} {rlink} @@ -3737,7 +3863,7 @@ see the driver-specific documentation. @itemize @bullet @item @var{name} ... may be used to reference the flash bank -in other flash commands. +in other flash commands. A number is also available. @item @var{driver} ... identifies the controller driver associated with the flash bank being declared. This is usually @code{cfi} for external flash, or else @@ -3835,8 +3961,12 @@ specifies "to the end of the flash bank". The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {flash erase_address} address length +@deffn Command {flash erase_address} [@option{pad}] address length Erase sectors starting at @var{address} for @var{length} bytes. +Unless @option{pad} is specified, @math{address} must begin a +flash sector, and @math{address + length - 1} must end a sector. +Specifying @option{pad} erases extra data at the beginning and/or +end of the specified region, as needed to erase only full sectors. The flash bank to use is inferred from the @var{address}, and the specified length must stay within that bank. As a special case, when @var{length} is zero and @var{address} is @@ -3910,17 +4040,14 @@ it has been removed by the @option{unlock} flag. Check erase state of sectors in flash bank @var{num}, and display that status. The @var{num} parameter is a value shown by @command{flash banks}. -This is the only operation that -updates the erase state information displayed by @option{flash info}. That means you have -to issue a @command{flash erase_check} command after erasing or programming the device -to get updated information. -(Code execution may have invalidated any state records kept by OpenOCD.) @end deffn @deffn Command {flash info} num Print info about flash bank @var{num} The @var{num} parameter is a value shown by @command{flash banks}. -The information includes per-sector protect status. +The information includes per-sector protect status, which may be +incorrect (outdated) unless you first issue a +@command{flash protect_check num} command. @end deffn @anchor{flash protect} @@ -3937,6 +4064,8 @@ The @var{num} parameter is a value shown by @command{flash banks}. Check protection state of sectors in flash bank @var{num}. The @var{num} parameter is a value shown by @command{flash banks}. @comment @option{flash erase_sector} using the same syntax. +This updates the protection information displayed by @option{flash info}. +(Code execution may have invalidated any state records kept by OpenOCD.) @end deffn @anchor{Flash Driver List} @@ -4103,7 +4232,7 @@ plane (of up to 256KB), and it will be used automatically when you issue @command{flash erase_sector} or @command{flash erase_address} commands. @deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear}) -Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM) +Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM) bit for the processor. Each processor has a number of such bits, used for controlling features such as brownout detection (so they are not truly general purpose). @@ -4143,13 +4272,19 @@ which must appear in the following order: @itemize @item @var{variant} ... required, may be -@var{lpc2000_v1} (older LPC21xx and LPC22xx) -@var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx) -or @var{lpc1700} (LPC175x and LPC176x) +@option{lpc2000_v1} (older LPC21xx and LPC22xx) +@option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx) +or @option{lpc1700} (LPC175x and LPC176x) @item @var{clock_kHz} ... the frequency, in kiloHertz, at which the core is running -@item @var{calc_checksum} ... optional (but you probably want to provide this!), +@item @option{calc_checksum} ... optional (but you probably want to provide this!), telling the driver to calculate a valid checksum for the exception vector table. +@quotation Note +If you don't provide @option{calc_checksum} when you're writing the vector +table, the boot ROM will almost certainly ignore your flash image. +However, if you do provide it, +with most tool chains @command{verify_image} will fail. +@end quotation @end itemize LPC flashes don't require the chip and bus width to be specified. @@ -4673,7 +4808,7 @@ NAND chips must be declared in configuration scripts, plus some additional configuration that's done after OpenOCD has initialized. -@deffn {Config Command} {nand device} name controller target [configparams...] +@deffn {Config Command} {nand device} name driver target [configparams...] Declares a NAND device, which can be read and written to after it has been configured through @command{nand probe}. In OpenOCD, devices are single chips; this is unlike some @@ -4688,8 +4823,8 @@ configuration files, not interactively. @itemize @bullet @item @var{name} ... may be used to reference the NAND bank -in other commands. -@item @var{controller} ... identifies the controller driver +in most other NAND commands. A number is also available. +@item @var{driver} ... identifies the NAND controller driver associated with the NAND device being declared. @xref{NAND Driver List}. @item @var{target} ... names the target used when issuing @@ -4999,7 +5134,8 @@ change any behavior. @deffnx {NAND Driver} s3c2412 @deffnx {NAND Driver} s3c2440 @deffnx {NAND Driver} s3c2443 -These S3C24xx family controllers don't have any special +@deffnx {NAND Driver} s3c6400 +These S3C family controllers don't have any special @command{nand device} options, and don't define any specialized commands. At this writing, their drivers don't include @code{write_page} @@ -6030,6 +6166,10 @@ and ARM9 commands. @deffn Command {arm966e cp15} regnum [value] Display cp15 register @var{regnum}; else if a @var{value} is provided, that value is written to that register. +The six bit @var{regnum} values are bits 37..32 from table 7-2 of the +ARM966E-S TRM. +There is no current control over bits 31..30 from that table, +as required for BIST support. @end deffn @subsection XScale specific commands @@ -6685,8 +6825,10 @@ to debug remote targets. Setting up GDB to work with OpenOCD can involve several components: @itemize -@item OpenOCD itself may need to be configured. @xref{GDB Configuration}. -@item GDB itself may need configuration, as shown in this chapter. +@item The OpenOCD server support for GDB may need to be configured. +@xref{GDB Configuration}. +@item GDB's support for OpenOCD may need configuration, +as shown in this chapter. @item If you have a GUI environment like Eclipse, that also will probably need to be configured. @end itemize @@ -6789,6 +6931,24 @@ With that particular hardware (Cortex-M3) the hardware breakpoints only work for code running from flash memory. Most other ARM systems do not have such restrictions. +Another example of useful GDB configuration came from a user who +found that single stepping his Cortex-M3 didn't work well with IRQs +and an RTOS until he told GDB to disable the IRQs while stepping: + +@example +define hook-step +mon cortex_m3 maskisr on +end +define hookpost-step +mon cortex_m3 maskisr off +end +@end example + +Rather than typing such commands interactively, you may prefer to +save them in a file and have GDB execute them as it starts, perhaps +using a @file{.gdbinit} in your project directory or starting GDB +using @command{gdb -x filename}. + @section Programming using GDB @cindex Programming using GDB @@ -6903,11 +7063,12 @@ variables. JimTCL, as implemented in OpenOCD creates $ocd_HOSTOS which holds one of the following values: @itemize @bullet -@item @b{winxx} Built using Microsoft Visual Studio -@item @b{linux} Linux is the underlying operating sytem -@item @b{darwin} Darwin (mac-os) is the underlying operating sytem. @item @b{cygwin} Running under Cygwin +@item @b{darwin} Darwin (Mac-OS) is the underlying operating sytem. +@item @b{freebsd} Running under FreeBSD +@item @b{linux} Linux is the underlying operating sytem @item @b{mingw32} Running under MingW32 +@item @b{winxx} Built using Microsoft Visual Studio @item @b{other} Unknown, none of the above. @end itemize @@ -6932,36 +7093,48 @@ is jim, not real tcl). In digital circuit design it is often refered to as ``clock synchronisation'' the JTAG interface uses one clock (TCK or TCLK) -operating at some speed, your target is operating at another. The two -clocks are not synchronised, they are ``asynchronous'' +operating at some speed, your CPU target is operating at another. +The two clocks are not synchronised, they are ``asynchronous'' -In order for the two to work together they must be synchronised. Otherwise -the two systems will get out of sync with each other and nothing will -work. There are 2 basic options: +In order for the two to work together they must be synchronised +well enough to work; JTAG can't go ten times faster than the CPU, +for example. There are 2 basic options: @enumerate @item -Use a special circuit. +Use a special "adaptive clocking" circuit to change the JTAG +clock rate to match what the CPU currently supports. @item -One clock must be some multiple slower than the other. +The JTAG clock must be fixed at some speed that's enough slower than +the CPU clock that all TMS and TDI transitions can be detected. @end enumerate @b{Does this really matter?} For some chips and some situations, this -is a non-issue (i.e.: A 500MHz ARM926) but for others - for example some -Atmel SAM7 and SAM9 chips start operation from reset at 32kHz - -program/enable the oscillators and eventually the main clock. It is in -those critical times you must slow the JTAG clock to sometimes 1 to -4kHz. - -Imagine debugging a 500MHz ARM926 hand held battery powered device -that ``deep sleeps'' at 32kHz between every keystroke. It can be -painful. +is a non-issue, like a 500MHz ARM926 with a 5 MHz JTAG link; +the CPU has no difficulty keeping up with JTAG. +Startup sequences are often problematic though, as are other +situations where the CPU clock rate changes (perhaps to save +power). + +For example, Atmel AT91SAM chips start operation from reset with +a 32kHz system clock. Boot firmware may activate the main oscillator +and PLL before switching to a faster clock (perhaps that 500 MHz +ARM926 scenario). +If you're using JTAG to debug that startup sequence, you must slow +the JTAG clock to sometimes 1 to 4kHz. After startup completes, +JTAG can use a faster clock. + +Consider also debugging a 500MHz ARM926 hand held battery powered +device that enters a low power ``deep sleep'' mode, at 32kHz CPU +clock, between keystrokes unless it has work to do. When would +that 5 MHz JTAG clock be usable? @b{Solution #1 - A special circuit} -In order to make use of this, your JTAG dongle must support the RTCK +In order to make use of this, +both your CPU and your JTAG dongle must support the RTCK feature. Not all dongles support this - keep reading! -The RTCK signal often found in some ARM chips is used to help with +The RTCK ("Return TCK") signal in some ARM chips is used to help with this problem. ARM has a good description of the problem described at this link: @url{http://www.arm.com/support/faqdev/4170.html} [checked 28/nov/2008]. Link title: ``How does the JTAG synchronisation logic @@ -6998,8 +7171,9 @@ ARM11 cores use an 8:1 division. Note: Many FTDI2232C based JTAG dongles are limited to 6MHz. You can still debug the 'low power' situations - you just need to -manually adjust the clock speed at every step. While painful and -tedious, it is not always practical. +either use a fixed and very slow JTAG clock rate ... or else +manually adjust the clock speed at every step. (Adjusting is painful +and tedious, and is not always practical.) It is however easy to ``code your way around it'' - i.e.: Cheat a little, have a special debug mode in your application that does a ``high power