@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
@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
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
--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
@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
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}
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}
@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.
@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}
Code Review / openocd.git / blobdiff