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

Rework the "Simple Configuration Files" chapter so it's more
of a quick-start "how to set up your project" tutorial:

 - Say how to hook up the JTAG adapter.  This will help new
   users, and in any case is worth spelling out somewhere.

 - Streamline the previous rather haphazard presentation,
   filling in some missing holes along the way:

     * Suggest "project directory" structure
     * Introduce new term, "user config" file (openocd.cfg)
     * Talk about more options for openocd.cfg contents
     * ... and about creating new config files
     * Add new topic, project-specific utilities (+examples)

 - Remove too-short, yet duplicative, chapter 19

Nudge packagers a bit more strongly to send patches (including
config files) upstream.


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

1 files changed, 256 insertions, 95 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 5c3883f0..baabc3cc 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -63,7 +63,7 @@ Free Documentation License''.
 * Building OpenOCD::                 Building OpenOCD From SVN
 * JTAG Hardware Dongles::            JTAG Hardware Dongles
 * Running::                          Running OpenOCD
-* Simple Configuration Files::       Simple Configuration Files
+* OpenOCD Project Setup::            OpenOCD Project Setup
 * Config File Guidelines::           Config File Guidelines
 * About JIM-Tcl::                    About JIM-Tcl
 * Daemon Configuration::             Daemon Configuration
@@ -76,7 +76,6 @@ Free Documentation License''.
 * General Commands::                 General Commands
 * Architecture and Core Commands::   Architecture and Core Commands
 * JTAG Commands::                    JTAG Commands
-* Sample Scripts::                   Sample Target Scripts
 * TFTP::                             TFTP
 * GDB and OpenOCD::                  Using GDB and OpenOCD
 * Tcl Scripting API::                Tcl Scripting API
@@ -239,6 +238,7 @@ That said, the OpenOCD developers would also like you to follow a few
 suggestions:
 
 @enumerate
+@item @b{Send patches, including config files, upstream.}
 @item @b{Always build with printer ports enabled.}
 @item @b{Try to use LIBFTDI + LIBUSB where possible. You cover more bases.}
 @end enumerate
@@ -718,28 +718,114 @@ establish a connection with the target. In general, it is possible for
 the JTAG controller to be unresponsive until the target is set up
 correctly via e.g. GDB monitor commands in a GDB init script.
 
-@node Simple Configuration Files
-@chapter Simple Configuration Files
-@cindex configuration
+@node OpenOCD Project Setup
+@chapter OpenOCD Project Setup
 
-@section Outline
-There are 4 basic ways of ``configurating'' OpenOCD to run, they are:
+To use OpenOCD with your development projects, you need to do more than
+just connecting the JTAG adapter hardware (dongle) to your development board
+and then starting the OpenOCD server.
+You also need to configure that server so that it knows
+about that adapter and board, and helps your work.
+
+@section Hooking up the JTAG Adapter
+
+Today's most common case is a dongle with a JTAG cable on one side
+(such as a ribbon cable with a 10-pin or 20-pin IDC connector)
+and a USB cable on the other.
+Instead of USB, some cables use Ethernet;
+older ones may use a PC parallel port, or even a serial port.
 
 @enumerate
-@item A small openocd.cfg file which ``sources'' other configuration files
-@item A monolithic openocd.cfg file
-@item Many -f filename options on the command line
-@item Your Mixed Solution
+@item @emph{Start with power to your target board turned off},
+and nothing connected to your JTAG adapter.
+If you're particularly paranoid, unplug power to the board.
+It's important to have the ground signal properly set up,
+unless you are using a JTAG adapter which provides
+galvanic isolation between the target board and the
+debugging host.
+
+@item @emph{Be sure it's the right kind of JTAG connector.}
+If your dongle has a 20-pin ARM connector, you need some kind
+of adapter (or octopus, see below) to hook it up to
+boards using 14-pin or 10-pin connectors ... or to 20-pin
+connectors which don't use ARM's pinout.
+
+In the same vein, make sure the voltage levels are compatible.
+Not all JTAG adapters have the level shifters needed to work
+with 1.2 Volt boards.
+
+@item @emph{Be certain the cable is properly oriented} or you might
+damage your board.  In most cases there are only two possible
+ways to connect the cable.
+Connect the JTAG cable from your adapter to the board.
+Be sure it's firmly connected.
+
+In the best case, the connector is keyed to physically
+prevent you from inserting it wrong.
+This is most often done using a slot on the board's male connector
+housing, which must match a key on the JTAG cable's female connector.
+If there's no housing, then you must look carefully and
+make sure pin 1 on the cable hooks up to pin 1 on the board.
+Ribbon cables are frequently all grey except for a wire on one
+edge, which is red.  The red wire is pin 1.
+
+Sometimes dongles provide cables where one end is an ``octopus'' of
+color coded single-wire connectors, instead of a connector block.
+These are great when converting from one JTAG pinout to another,
+but are tedious to set up.
+Use these with connector pinout diagrams to help you match up the
+adapter signals to the right board pins.
+
+@item @emph{Connect the adapter's other end} once the JTAG cable is connected.
+A USB, parallel, or serial port connector will go to the host which
+you are using to run OpenOCD.
+For Ethernet, consult the documentation and your network administrator.
+
+For USB based JTAG adapters you have an easy sanity check at this point:
+does the host operating system see the JTAG adapter?
+
+@item @emph{Connect the adapter's power supply, if needed.}
+This step is primarily for non-USB adapters,
+but sometimes USB adapters need extra power.
+
+@item @emph{Power up the target board.}
+Unless you just let the magic smoke escape,
+you're now ready to set up the OpenOCD server
+so you can use JTAG to work with that board.
+
 @end enumerate
 
-@section Small configuration file method
+Talk with the OpenOCD server using
+telnet (@code{telnet localhost 4444} on many systems) or GDB.
+@xref{GDB and OpenOCD}.
+
+@section Project Directory
 
-This is the preferred method. It is simple and works well for many
-people. The developers of OpenOCD would encourage you to use this
-method. If you create a new configuration please email new
-configurations to the development list.
+There are many ways you can configure OpenOCD and start it up.
 
-Here is an example of an openocd.cfg file for an ATMEL at91sam7x256
+A simple way to organize them all involves keeping a
+single directory for your work with a given board.
+When you start OpenOCD from that directory,
+it searches there first for configuration files
+and for code you upload to the target board.
+It is also be the natural place to write files,
+such as log files and data you download from the board.
+
+@section Configuration Basics
+
+There are two basic ways of configuring OpenOCD, and
+a variety of ways you can mix them.
+Think of the difference as just being how you start the server:
+
+@itemize
+@item Many @option{-f file} or @option{-c command} options on the command line
+@item No options, but a @dfn{user config file}
+in the current directory named @file{openocd.cfg}
+@end itemize
+
+Here is an example @file{openocd.cfg} file for a setup
+using a Signalyzer FT2232-based JTAG adapter to talk to
+a board with an Atmel AT91SAM7X256 microcontroller:
 
 @example
 source [find interface/signalyzer.cfg]
@@ -751,66 +837,172 @@ gdb_flash_program enable
 source [find target/sam7x256.cfg]
 @end example
 
-There are many example configuration scripts you can work with. You
-should look in the directory: @t{$(INSTALLDIR)/lib/openocd}. You
-should find:
+Here is the command line equivalent of that configuration:
 
-@enumerate
-@item @b{board} - eval board level configurations
-@item @b{interface} - specific dongle configurations
-@item @b{target} - the target chips
-@item @b{tcl} - helper scripts 
-@item @b{xscale} - things specific to the xscale.
-@end enumerate
+@example
+openocd -f interface/signalyzer.cfg \
+        -c "gdb_memory_map enable" \
+        -c "gdb_flash_program enable" \
+        -f target/sam7x256.cfg
+@end example
+
+You could wrap such long command lines in shell scripts,
+each supporting a different development task.
+One might re-flash the board with specific firmware version.
+Another might set up a particular debugging or run-time environment.
 
-Look first in the ``boards'' area, then the ``targets'' area. Often a board
-configuration is a good example to work from.
+Here we will focus on the simpler solution:  one user config
+file, including basic configuration plus any TCL procedures
+to simplify your work.
 
-@section Many -f filename options
-Some believe this is a wonderful solution, others find it painful.
+@section User Config Files
+@cindex config file
+@cindex user config file
 
-You can use a series of ``-f filename'' options on the command line,
-OpenOCD will read each filename in sequence, for example:
+A user configuration file ties together all the parts of a project
+in one place.
+One of the following will match your situation best:
+
+@itemize
+@item Ideally almost everything comes from configuration files
+provided by someone else.
+For example, OpenOCD distributes a @file{scripts} directory
+(probably in @file{/usr/share/openocd/scripts} on Linux);
+board and tool vendors can provide these too.
+The AT91SAM7X256 example above works this way.
+
+Three main types of non-user configuration file each have their
+own subdirectory in the @file{scripts} directory:
+
+@enumerate
+@item @b{interface} -- one for each kind of JTAG adapter/dongle
+@item @b{board} -- one for each different board
+@item @b{target} -- the chips which integrate CPUs and other JTAG TAPs
+@end enumerate
+
+Best case:  include just two files, and they handle everything else.
+The first is an interface config file.
+The second is board-specific, and it sets up the JTAG TAPs and
+their GDB targets (by deferring to some @file{target.cfg} file),
+declares all flash memory, and leaves you nothing to do except
+meet your deadline:
 
 @example
-openocd -f file1.cfg -f file2.cfg -f file2.cfg
+source [find interface/olimex-jtag-tiny.cfg]
+source [find board/csb337.cfg]
 @end example
 
-You can also intermix various commands with the ``-c'' command line
-option.
+Boards with a single microcontroller often won't need more
+than the target config file, as in the AT91SAM7X256 example.
+That's because there is no external memory (flash, DDR RAM), and
+the board differences are encapsulated by application code.
 
-@section Monolithic file
-The ``Monolithic File'' dispenses with all ``source'' statements and
-puts everything in one self contained (monolithic) file. This is not
-encouraged. 
+@item You can often reuse some standard config files but
+need to write a few new ones, probably a @file{board.cfg} file.
+You will be using commands described later in this User's Guide,
+and working with the guidelines in the next chapter.
 
-Please try to ``source'' various files or use the multiple -f
-technique.
+For example, there may be configuration files for your JTAG adapter
+and target chip, but you need a new board-specific config file
+giving access to your particular flash chips.
+Or you might need to write another target chip configuration file
+for a new chip built around the Cortex M3 core.
 
-@section Advice for you
-Often, one uses a ``mixed approach''. Where possible, please try to
-``source'' common things, and if needed cut/paste parts of the
-standard distribution configuration files as needed.
+@quotation Note
+When you write new configuration files, please submit
+them for inclusion in the next OpenOCD release.
+For example, a @file{board/newboard.cfg} file will help the
+next users of that board, and a @file{target/newcpu.cfg}
+will help support users of any board using that chip.
+@end quotation
 
-@b{REMEMBER:} The ``important parts'' of your configuration file are:
+@item
+You may may need to write some C code.
+It may be as simple as a supporting a new new ft2232 or parport
+based dongle; a bit more involved, like a NAND or NOR flash
+controller driver; or a big piece of work like supporting
+a new chip architecture.
+@end itemize
 
-@enumerate
-@item @b{Interface} - Defines the dongle
-@item @b{Taps} - Defines the JTAG Taps
-@item @b{GDB Targets} - What GDB talks to
-@item @b{Flash Programing} - Very Helpful
-@end enumerate
+Reuse the existing config files when you can.
+Look first in the @file{scripts/boards} area, then @file{scripts/targets}.
+You may find a board configuration that's a good example to follow.
 
-Some key things you should look at and understand are:
+When you write config files, separate the reusable parts
+(things every user of that interface, chip, or board needs)
+from ones specific to your environment and debugging approach.
 
-@enumerate
-@item The reset configuration of your debug environment as a whole
-@item Is there a ``work area'' that OpenOCD can use?
-@* For ARM - work areas mean up to 10x faster downloads.
-@item For MMU/MPU based ARM chips (i.e.: ARM9 and later) will that work area still be available?
-@item For complex targets (multiple chips) the JTAG SPEED becomes an issue.
-@end enumerate
+For example, a @code{gdb-attach} event handler that invokes
+the @command{reset init} command will interfere with debugging
+early boot code, which performs some of the same actions
+that the @code{reset-init} event handler does.
+Likewise, the @command{arm9tdmi vector_catch} command (or
+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.
+
+@section Project-Specific Utilities
+
+A few project-specific utility
+routines may well speed up your work.
+Write them, and keep them in your project's user config file.
+
+For example, if you are making a boot loader work on a
+board, it's nice to be able to debug the ``after it's
+loaded to RAM'' parts separately from the finicky early
+code which sets up the DDR RAM controller and clocks.
+A script like this one, or a more GDB-aware sibling,
+may help:
+
+@example
+proc ramboot @{ @} @{
+    # Reset, running the target's "reset-init" scripts
+    # to initialize clocks and the DDR RAM controller.
+    # Leave the CPU halted.
+    reset init
+
+    # Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
+    load_image u-boot.bin 0x20000000
 
+    # Start running.
+    resume 0x20000000
+@}
+@end example
+
+Then once that code is working you will need to make it
+boot from NOR flash; a different utility would help.
+Alternatively, some developers write to flash using GDB.
+(You might use a similar script if you're working with a flash
+based microcontroller application instead of a boot loader.)
+
+@example
+proc newboot @{ @} @{
+    # Reset, leaving the CPU halted.  The "reset-init" event
+    # proc gives faster access to the CPU and to NOR flash;
+    # "reset halt" would be slower.
+    reset init
+
+    # Write standard version of U-Boot into the first two
+    # sectors of NOR flash ... the standard version should
+    # do the same lowlevel init as "reset-init".
+    flash protect 0 0 1 off
+    flash erase_sector 0 0 1
+    flash write_bank 0 u-boot.bin 0x0
+    flash protect 0 0 1 on
+
+    # Reboot from scratch using that new boot loader.
+    reset run
+@}
+@end example
+
+You may need more complicated utility procedures when booting
+from NAND.
+That often involves an extra bootloader stage,
+running from on-chip SRAM to perform DDR RAM setup so it can load
+the main bootloader code (which won't fit into that SRAM).
+
+Other helper scripts might be used to write production system images,
+involving considerably more than just a three stage bootloader.
 
 
 @node Config File Guidelines
@@ -852,6 +1044,7 @@ setting a variable or two before sourcing the target file. Or adding
 various commands specific to their situation.
 
 @section Interface Config Files
+@cindex config file
 
 The user should be able to source one of these files via a command like this:
 
@@ -868,6 +1061,7 @@ sole developer who created it.
 Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
 
 @section Board Config Files
+@cindex config file
 
 @b{Note: BOARD directory NEW as of 28/nov/2008} 
 
@@ -896,6 +1090,7 @@ In summary the board files should contain (if present)
 @end enumerate
 
 @section Target Config Files
+@cindex config file
 
 The user should be able to source one of these files via a command like this:
 
@@ -1113,13 +1308,6 @@ register to report that JTAG debugging is being done.
 If the chip has a DCC, enable it. If the chip is an ARM9 with some
 special high speed download features - enable it.
 
-If the chip supports the @command{arm9tdmi vector_catch},
-@command{xscale vector_catch}, or similar features,
-consider enabling it in your user-specific configuration file.
-Experience has shown the ``vector_catch'' can be
-helpful for catching programming errors
-like Undefined Instructions, Data Abort, and Prefetch Abort.
-
 If present, the MMU, the MPU and the CACHE should be disabled.
 
 Some ARM cores are equipped with trace support, which permits
@@ -4885,33 +5073,6 @@ that supports a packet size bigger than the default packet size (512 bytes). The
 are numerous TFTP servers out there (free and commercial) and you will have to do
 a bit of googling to find something that fits your requirements.
 
-@node Sample Scripts
-@chapter Sample Scripts
-@cindex scripts
-
-This page shows how to use the Target Library.
-
-The configuration script can be divided into the following sections:
-@itemize @bullet
-@item Daemon configuration
-@item Interface
-@item JTAG scan chain
-@item Target configuration
-@item Flash configuration 
-@end itemize
-
-Detailed information about each section can be found at OpenOCD configuration. 
-
-@section AT91R40008 example
-@cindex AT91R40008 example
-To start OpenOCD with a target script for the AT91R40008 CPU and reset
-the CPU upon startup of the OpenOCD daemon.
-@example
-openocd -f interface/parport.cfg -f target/at91r40008.cfg \
-        -c "init" -c "reset"
-@end example
-
-
 @node GDB and OpenOCD
 @chapter GDB and OpenOCD
 @cindex GDB