X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=d4e60a8042bd049bce7387dbb2e6a52e1c32588c;hp=3e0b5db7c8c43e94f0fd54e1c67ff7118e24211d;hb=3ea9e62189205cfa84a04ec6955aaf1f5184a937;hpb=73566405b6e105b0a8b7f21db48331926bec97ad diff --git a/doc/openocd.texi b/doc/openocd.texi index 3e0b5db7c8..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 @@ -226,6 +226,13 @@ Discuss and submit patches to this list. 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 @@ -3920,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} @@ -3947,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} @@ -4153,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. @@ -5009,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} @@ -6699,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 @@ -6803,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 @@ -6947,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 @@ -7013,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