David Brownell <david-b@pacbell.net>:

This should be my last significant update of the User's Guide for
this release.  Mostly it's a rework of the config file chapter's
presentation of board and target config files.

 - Give the new path for scripts!
 - Move board-config material out of the target-config section
 - Add more board-config info, notably for reset-init events
 - Link out of the board-config section to NAND, NOR, and Reset chapters
 - Emphasize target input vs. output naming conventions
 - Other textual improvements

Plus some other updates, like adding my copyright (now that I've
basically rewritten much of this).


git-svn-id: svn://svn.berlios.de/openocd/trunk@2354 b42882b7-edfa-0310-969c-e2dbd0fdcd60

1 files changed, 235 insertions, 128 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 36e3616a..b443ce3b 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -23,6 +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
 @end itemize
 
 @quotation
@@ -943,6 +944,10 @@ its @command{xscale vector_catch} sibling) can be a timesaver
 during some debug sessions, but don't make everyone use that either.
 Keep those kinds of debugging aids in your user config file.
 
+TCP/IP port configuration is another example of something which
+is environment-specific, and should only appear in
+a user config file.  @xref{TCP/IP Ports}.
+
 @section Project-Specific Utilities
 
 A few project-specific utility
@@ -1015,21 +1020,21 @@ including developers and integrators of OpenOCD and any user who
 needs to get a new board working smoothly.
 It provides guidelines for creating those files.
 
-You should find the following directories under @t{$(INSTALLDIR)/lib/openocd} :
+You should find the following directories under @t{$(INSTALLDIR)/scripts}:
 
 @itemize @bullet
-@item @b{interface}
-@*Think JTAG Dongle. Files that configure the JTAG dongle go here.
-@item @b{board}
-@* Think Circuit Board, PWA, PCB, they go by many names.  Board files
-contain initialization items that are specific to a board - for
-example: The SDRAM initialization sequence for the board, or the type
-of external flash and what address it is found at. Any initialization
+@item @file{interface} ...
+think JTAG Dongle. Files that configure JTAG adapters go here.
+@item @file{board} ...
+think Circuit Board, PWA, PCB, they go by many names.  Board files
+contain initialization items that are specific to a board.  For
+example, the SDRAM initialization sequence for the board, or the type
+of external flash and what address it uses.  Any initialization
 sequence to enable that external flash or SDRAM should be found in the
-board file. Boards may also contain multiple targets, i.e.: Two CPUs, or
+board file. Boards may also contain multiple targets:  two CPUs; or
 a CPU and an FPGA or CPLD.
-@item @b{target}
-@* Think chip. The ``target'' directory represents the JTAG TAPs
+@item @file{target} ...
+think chip. The ``target'' directory represents the JTAG TAPs
 on a chip
 which OpenOCD should control, not a board. Two common types of targets
 are ARM chips and FPGA or CPLD chips.
@@ -1045,7 +1050,7 @@ commands specific to their situation.
 @section Interface Config Files
 
 The user config file
-should be able to source one of these files via a command like this:
+should be able to source one of these files with a command like this:
 
 @example
 source [find interface/FOOBAR.cfg]
@@ -1060,179 +1065,250 @@ A separate chapter gives information about how to set these up.
 Read the OpenOCD source code if you have a new kind of hardware interface
 and need to provide a driver for it.
 
-Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
-
 @section Board Config Files
 @cindex config file, board
 @cindex board config file
 
 The user config file
-should be able to source one of these files via a command like this:
+should be able to source one of these files with a command like this:
 
 @example
 source [find board/FOOBAR.cfg]
 @end example
 
-The board config file should contain one or more @command{source [find
-target/FOO.cfg]} statements along with any board specific things.
-
+The point of a board config file is to package everything
+about a given board that user config files need to know.
 In summary the board files should contain (if present)
 
 @enumerate
-@item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
-@item SDRAM configuration (size, speed, etc.
-@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
-@item Multiple TARGET source statements
-@item Reset configuration
+@item One or more @command{source [target/...cfg]} statements
+@item NOR flash configuration (@pxref{NOR Configuration})
+@item NAND flash configuration (@pxref{NAND Configuration})
+@item Target @code{reset} handlers for SDRAM and I/O configuration
+@item JTAG adapter reset configuration (@pxref{Reset Configuration})
 @item All things that are not ``inside a chip''
-@item Things inside a chip go in a 'target' file
 @end enumerate
 
-@section Target Config Files
-@cindex config file, target
-@cindex target config file
+Generic things inside target chips belong in target config files,
+not board config files.  So for example a @code{reset-init} event
+handler should know board-specific oscillator and PLL parameters,
+which it passes to target-specific utility code.
 
-Board config files should be able to source one or more
-target config files via a command like this:
+The most complex task of a board config file is creating such a
+@code{reset-init} event handler.
+Define those handlers last, after you verify the rest of the board
+configuration works.
+
+@subsection Communication Between Config files
+
+In addition to target-specific utility code, another way that
+board and target config files communicate is by following a
+convention on how to use certain variables.
+
+The full Tcl/Tk language supports ``namespaces'', but JIM-Tcl does not.
+Thus the rule we follow in OpenOCD is this: Variables that begin with
+a leading underscore are temporary in nature, and can be modified and
+used at will within a target configuration file.
+
+Complex board config files can do the things like this,
+for a board with three chips:
 
 @example
-source [find target/FOOBAR.cfg]
+# Chip #1: PXA270 for network side, big endian
+set CHIPNAME network
+set ENDIAN big
+source [find target/pxa270.cfg]
+# on return: _TARGETNAME = network.cpu
+# other commands can refer to the "network.cpu" target.
+$_TARGETNAME configure .... events for this CPU..
+
+# Chip #2: PXA270 for video side, little endian
+set CHIPNAME video
+set ENDIAN little
+source [find target/pxa270.cfg]
+# on return: _TARGETNAME = video.cpu
+# other commands can refer to the "video.cpu" target.
+$_TARGETNAME configure .... events for this CPU..
+
+# Chip #3: Xilinx FPGA for glue logic
+set CHIPNAME xilinx
+unset ENDIAN
+source [find target/spartan3.cfg]
 @end example
 
-In summary the target files should contain
-
-@enumerate 
-@item Set defaults
-@item Add TAPs to the scan chain
-@item Add CPU targets (includes GDB support)
-@item CPU/Chip/CPU-Core specific features
-@item On-Chip flash
-@end enumerate
+That example is oversimplified because it doesn't show any flash memory,
+or the @code{reset-init} event handlers to initialize external DRAM
+or (assuming it needs it) load a configuration into the FPGA.
+Such features are usually needed for low-level work with many boards,
+where ``low level'' implies that the board initialization software may
+not be working.  (That's a common reason to need JTAG tools.  Another
+is to enable working with microcontroller-based systems, which often
+have no debugging support except a JTAG connector.)
 
-As a rule of thumb, a target file sets up only one chip.
-For a microcontroller, that will often include a single TAP,
-which is a CPU needing a GDB target; and its on-chip flash.
+Target config files may also export utility functions to board and user
+config files.  Such functions should use name prefixes, to help avoid
+naming collisions.
 
-More complex chips may include multiple TAPs, and the target
-config file may need to define them all before OpenOCD
-can talk to the chip.
-For example, some phone chips have JTAG scan chains that include
-an ARM core for operating system use, a DSP,
-another ARM core embedded in an image processing engine,
-and other processing engines.
+Board files could also accept input variables from user config files.
+For example, there might be a @code{J4_JUMPER} setting used to identify
+what kind of flash memory a development board is using, or how to set
+up other clocks and peripherals.
 
-@subsection Important variable names
+@subsection Variable Naming Convention
+@cindex variable names
 
-Most boards will have only one instance of a chip.
+Most boards have only one instance of a chip.
 However, it should be easy to create a board with more than
-one such chip.
-Accordingly, we encourage some conventions for naming
-variables associated with different TAPs, to promote
-consistency and
-so that board files can override target defaults, and
+one such chip (as shown above).
+Accordingly, we encourage these conventions for naming
+variables associated with different @file{target.cfg} files,
+to promote consistency and
+so that board files can override target defaults.
+
+Inputs to target config files include:
 
 @itemize @bullet
-@item @b{CHIPNAME}
-@* This gives a name to the overall chip, and is used as part of the
-tap identifier dotted name.
-It's normally provided by the chip manufacturer.
-@item @b{ENDIAN}
-@* By default little - unless the chip or board is not normally used that way.
+@item @code{CHIPNAME} ...
+This gives a name to the overall chip, and is used as part of
+tap identifier dotted names.
+While the default is normally provided by the chip manufacturer,
+board files may need to distinguish between instances of a chip.
+@item @code{ENDIAN} ...
+By default @option{little} - although chips may hard-wire @option{big}.
 Chips that can't change endianness don't need to use this variable.
-@item @b{CPUTAPID}
-@* When OpenOCD examines the JTAG chain, it will attempt to identify
-every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts
-to verify the tap id number verses configuration file and may issue an
-error or warning like this. The hope is that this will help to pinpoint
-problems in OpenOCD configurations.
+@item @code{CPUTAPID} ...
+When OpenOCD examines the JTAG chain, it can be told verify the
+chips against the JTAG IDCODE register.
+The target file will hold one or more defaults, but sometimes the
+chip in a board will use a different ID (perhaps a newer revision).
+@end itemize
 
-@example
-Info:   JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
-                (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
-Error:  ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678,
-                Got: 0x3f0f0f0f
-Error:  ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
-Error:  ERROR:      got: mfg: 0x787, part: 0xf0f0, ver: 0x3
-@end example
+Outputs from target config files include:
 
-@item @b{_TARGETNAME}
-@* By convention, this variable is created by the target configuration
+@itemize @bullet
+@item @code{_TARGETNAME} ...
+By convention, this variable is created by the target configuration
 script. The board configuration file may make use of this variable to
 configure things like a ``reset init'' script, or other things
 specific to that board and that target.
+If the chip has 2 targets, the names are @code{_TARGETNAME0},
+@code{_TARGETNAME1}, ... etc.
+@end itemize
 
-If the chip has 2 targets, use the names @b{_TARGETNAME0},
-@b{_TARGETNAME1}, ... etc.
+@subsection The reset-init Event Handler
+@cindex event, reset-init
+@cindex reset-init handler
 
-@emph{Remember:} The ``board file'' may include multiple targets.
-The user (or board) config file should reasonably be able to:
+Board config files run in the OpenOCD configuration stage;
+they can't use TAPs or targets, since they haven't been
+fully set up yet.
+This means you can't write memory or access chip registers;
+you can't even verify that a flash chip is present.
+That's done later in event handlers, of which the target @code{reset-init}
+handler is one of the most important.
 
-@example
-source [find target/FOO.cfg]
-$_TARGETNAME configure ... FOO specific parameters
+Except on microcontrollers, the basic job of @code{reset-init} event
+handlers is setting up flash and DRAM, as normally handled by boot loaders.
+Microcontrollers rarely use boot loaders; they run right out of their
+on-chip flash and SRAM memory.  But they may want to use one of these
+handlers too, if just for developer convenience.
 
-source [find target/BAR.cfg]
-$_TARGETNAME configure ... BAR specific parameters
-@end example
-
-@end itemize
+@quotation Note
+Because this is so very board-specific, and chip-specific, no examples
+are included here.
+Instead, look at the board config files distributed with OpenOCD.
+If you have a boot loader, its source code may also be useful.
+@end quotation
 
-@subsection Tcl Variables Guide Line
-The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not.
+Some of this code could probably be shared between different boards.
+For example, setting up a DRAM controller often doesn't differ by
+much except the bus width (16 bits or 32?) and memory timings, so a
+reusable TCL procedure loaded by the @file{target.cfg} file might take
+those as parameters.
+Similarly with oscillator, PLL, and clock setup;
+and disabling the watchdog.
+Structure the code cleanly, and provide comments to help
+the next developer doing such work.
+(@emph{You might be that next person} trying to reuse init code!)
+
+The last thing normally done in a @code{reset-init} handler is probing
+whatever flash memory was configured.  For most chips that needs to be
+done while the associated target is halted, either because JTAG memory
+access uses the CPU or to prevent conflicting CPU access.
+
+@subsection JTAG Clock Rate
+
+Before your @code{reset-init} handler has set up
+the PLLs and clocking, you may need to use
+a low JTAG clock rate; then you'd increase it later.
+(The rule of thumb for ARM-based processors is 1/8 the CPU clock.)
+If the board supports adaptive clocking, use the @command{jtag_rclk}
+command, in case your board is used with JTAG adapter which
+also supports it.  Otherwise use @command{jtag_khz}.
+Set the slow rate at the beginning of the reset sequence,
+and the faster rate as soon as the clocks are at full speed.
 
-Thus the rule we follow in OpenOCD is this: Variables that begin with
-a leading underscore are temporary in nature, and can be modified and
-used at will within a ?TARGET? configuration file.
+@section Target Config Files
+@cindex config file, target
+@cindex target config file
 
-@b{EXAMPLE:} The user config file should be able to do this:
+Board config files communicate with target config files using
+naming conventions as described above, and may source one or
+more target config files like this:
 
 @example
-   # Board has 3 chips,
-   #    PXA270 #1 network side, big endian
-   #    PXA270 #2 video side, little endian
-   #    Xilinx    Glue logic
-   set CHIPNAME network
-   set ENDIAN big
-   source [find target/pxa270.cfg]
-   # variable: _TARGETNAME = network.cpu
-   # other commands can refer to the "network.cpu" tap.
-   $_TARGETNAME configure .... params for this CPU..
-
-   set ENDIAN little
-   set CHIPNAME video
-   source [find target/pxa270.cfg]
-   # variable: _TARGETNAME = video.cpu
-   # other commands can refer to the "video.cpu" tap.
-   $_TARGETNAME configure .... params for this CPU..
-
-   unset ENDIAN
-   set CHIPNAME xilinx
-   source [find target/spartan3.cfg]
-
-   # Since $_TARGETNAME is temporal..
-   #  these names still work!
-   network.cpu configure ... params
-   video.cpu   configure ... params
+source [find target/FOOBAR.cfg]
 @end example
 
+The point of a target config file is to package everything
+about a given chip that board config files need to know.
+In summary the target files should contain
+
+@enumerate
+@item Set defaults
+@item Add TAPs to the scan chain
+@item Add CPU targets (includes GDB support)
+@item CPU/Chip/CPU-Core specific features
+@item On-Chip flash
+@end enumerate
+
+As a rule of thumb, a target file sets up only one chip.
+For a microcontroller, that will often include a single TAP,
+which is a CPU needing a GDB target, and its on-chip flash.
+
+More complex chips may include multiple TAPs, and the target
+config file may need to define them all before OpenOCD
+can talk to the chip.
+For example, some phone chips have JTAG scan chains that include
+an ARM core for operating system use, a DSP,
+another ARM core embedded in an image processing engine,
+and other processing engines.
+
 @subsection Default Value Boiler Plate Code
 
-All target configuration files should start with this (or a modified form)
+All target configuration files should start with code like this,
+letting board config files express environment-specific
+differences in how things should be set up.
 
 @example
-# SIMPLE example
+# Boards may override chip names, perhaps based on role,
+# but the default should match what the vendor uses
 if @{ [info exists CHIPNAME] @} @{
    set  _CHIPNAME $CHIPNAME
 @} else @{
    set  _CHIPNAME sam7x256
 @}
 
+# ONLY use ENDIAN with targets that can change it.
 if @{ [info exists ENDIAN] @} @{
    set  _ENDIAN $ENDIAN
 @} else @{
    set  _ENDIAN little
 @}
 
+# TAP identifiers may change as chips mature, for example with
+# new revision fields (the "3" here).  Pick a good default; you
+# can pass several such identifiers to the "jtag newtap" command.
 if @{ [info exists CPUTAPID ] @} @{
    set _CPUTAPID $CPUTAPID
 @} else @{
@@ -1240,6 +1316,19 @@ if @{ [info exists CPUTAPID ] @} @{
 @}
 @end example
 
+@emph{Remember:} Board config files may include multiple target
+config files, or the same target file multiple times
+(changing at least @code{CHIPNAME}).
+
+Likewise, the target configuration file should define
+@code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and
+use it later on when defining debug targets:
+
+@example
+set _TARGETNAME $_CHIPNAME.cpu
+target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
+@end example
+
 @subsection Adding TAPs to the Scan Chain
 After the ``defaults'' are set up,
 add the TAPs on each chip to the JTAG scan chain.
@@ -1261,12 +1350,25 @@ to source such a config file twice, with different
 values for @code{CHIPNAME}, so
 it adds a different TAP each time.
 
+If there are one or more nonzero @option{-expected-id} values,
+OpenOCD attempts to verify the actual tap id against those values.
+It will issue error messages if there is mismatch, which
+can help to pinpoint problems in OpenOCD configurations.
+
+@example
+JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
+                (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
+ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
+ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
+ERROR:      got: mfg: 0x787, part: 0xf0f0, ver: 0x3
+@end example
+
 There are more complex examples too, with chips that have
 multiple TAPs.  Ones worth looking at include:
 
 @itemize
-@item @file{target/omap3530.cfg} -- with a disabled ARM, and a JRC
-(there's a DSP too, which is not listed)
+@item @file{target/omap3530.cfg} -- with disabled ARM and DSP,
+plus a JRC to enable them
 @item @file{target/str912.cfg} -- with flash, CPU, and boundary scan
 @item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC
 is not currently used)
@@ -1277,7 +1379,9 @@ is not currently used)
 After adding a TAP for a CPU, you should set it up so that
 GDB and other commands can use it.
 @xref{CPU Configuration}.
-For the at91sam7 example above, the command can look like this:
+For the at91sam7 example above, the command can look like this;
+note that @code{$_ENDIAN} is not needed, since OpenOCD defaults
+to little endian, and this chip doesn't support changing that.
 
 @example
 set _TARGETNAME $_CHIPNAME.cpu
@@ -1428,6 +1532,7 @@ read/write memory on your target, @command{init} must occur before
 the memory read/write commands.  This includes @command{nand probe}.
 @end deffn
 
+@anchor{TCP/IP Ports}
 @section TCP/IP Ports
 @cindex TCP port
 @cindex server
@@ -3023,11 +3128,12 @@ bank'', and the GDB flash features be enabled.
 @end enumerate
 
 Many CPUs have the ablity to ``boot'' from the first flash bank.
-This means that misprograming that bank can ``brick'' a system,
+This means that misprogramming that bank can ``brick'' a system,
 so that it can't boot.
 JTAG tools, like OpenOCD, are often then used to ``de-brick'' the
 board by (re)installing working boot firmware.
 
+@anchor{NOR Configuration}
 @section Flash Configuration Commands
 @cindex flash configuration
 
@@ -3716,6 +3822,7 @@ is larger than 0xffffffff, the largest 32-bit unsigned integer.)
 Some larger devices will work, since they are actually multi-chip
 modules with two smaller chips and individual chipselect lines.
 
+@anchor{NAND Configuration}
 @section NAND Configuration Commands
 @cindex NAND configuration