summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/openocd.texi351
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