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

Rework the TAP creation documentation.

 - Try to use "TAP" not "tap" everywhere; it's an acronym.

 - Update the associated "target config files" section:
     * reference the "TAP Creation" chapter for details
     * simplify:  reference interesting multi-tap config files
     * let's not forget CPU configuration (*before* workspace setup)
     * streamline it a bit
     * move that workspace-vs-mmu issue to a better location

 - Clean up TAP creation doc mess
     * switch to @deffn
     * (re)organize the remaining stuff
     * reference the "Config File Guidelines" chapter

 - Tweak the "Target Configuration" chapter
     * rename as "CPU configuration"; unconfuse vs. target/*.cfg
     * bring out that it's not just there for GDB
     * move TAP events to the TAP chapter, where they belong (bugfix)


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

1 files changed, 292 insertions, 254 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index 8e8f6ead..bd4b6fcd 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -69,8 +69,8 @@ Free Documentation License''.
 * Daemon Configuration::             Daemon Configuration
 * Interface - Dongle Configuration:: Interface - Dongle Configuration
 * Reset Configuration::              Reset Configuration
-* Tap Creation::                     Tap Creation
-* Target Configuration::             Target Configuration
+* TAP Creation::                     TAP Creation
+* CPU Configuration::                CPU Configuration
 * Flash Commands::                   Flash Commands
 * NAND Flash Commands::              NAND Flash Commands
 * General Commands::                 General Commands
@@ -111,7 +111,10 @@ in-system programming and boundary-scan testing for embedded target
 devices.
 
 @b{JTAG:} OpenOCD uses a ``hardware interface dongle'' to communicate
-with the JTAG (IEEE 1149.1) compliant taps on your target board.
+with the JTAG (IEEE 1149.1) compliant TAPs on your target board.
+A @dfn{TAP} is a ``Test Access Port'', a module which processes
+special instructions and data.  TAPs are daisy-chained within and
+between chips and boards.
 
 @b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
 based, parallel port based, and other standalone boxes that run
@@ -835,9 +838,12 @@ 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
 a CPU and an FPGA or CPLD.
 @item @b{target}
-@* Think chip. The ``target'' directory represents a JTAG tap (or
-chip) OpenOCD should control, not a board. Two common types of targets
+@* 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.
+When a chip has multiple TAPs (maybe it has both ARM and DSP cores),
+the target config file defines all of them.
 @end itemize
 
 @b{If needed...} The user in their ``openocd.cfg'' file or the board
@@ -902,9 +908,9 @@ In summary the target files should contain
 
 @enumerate 
 @item Set defaults
-@item Create taps
+@item Add TAPs to the scan chain
+@item Add CPU targets
 @item Reset configuration
-@item Work areas
 @item CPU/Chip/CPU-Core specific features
 @item On-Chip flash
 @end enumerate
@@ -1002,7 +1008,6 @@ used at will within a ?TARGET? configuration file.
    #  these names still work!
    network.cpu configure ... params
    video.cpu   configure ... params
-
 @end example
 
 @subsection Default Value Boiler Plate Code
@@ -1028,72 +1033,62 @@ if @{ [info exists CPUTAPID ] @} @{
 @} else @{
    set _CPUTAPID 0x3f0f0f0f
 @}
-
 @end example
 
-@subsection Creating Taps
-After the ``defaults'' are choosen [see above] the taps are created.
+@subsection Adding TAPs to the Scan Chain
+After the ``defaults'' are set up,
+add the TAPs on each chip to the JTAG scan chain.
+@xref{TAP Creation}, and the naming convention
+for taps.
 
-@b{SIMPLE example:} such as an Atmel AT91SAM7X256
+In the simplest case the chip has only one TAP,
+probably for a CPU or FPGA.
+The config file for the Atmel AT91SAM7X256
+looks (in part) like this:
 
 @example
-# for an ARM7TDMI.
-set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
 jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
         -expected-id $_CPUTAPID
 @end example
 
-@b{COMPLEX example:}
-
-This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:
-
-@enumerate
-@item @b{Unform tap names} - See: Tap Naming Convention
-@item @b{_TARGETNAME} is created at the end where used.
-@end enumerate
+A board with two such at91sam7 chips would be able
+to source such a config file twice, with different
+values for @code{CHIPNAME} and @code{CPUTAPID}, so
+it adds a different TAP each time.
 
-@example
-if @{ [info exists FLASHTAPID ] @} @{
-   set _FLASHTAPID $FLASHTAPID
-@} else @{
-   set _FLASHTAPID 0x25966041
-@}
-jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 \
-        -expected-id $_FLASHTAPID
+There are more complex examples too, with chips that have
+multiple TAPs.  Ones worth looking at include:
 
-if @{ [info exists CPUTAPID ] @} @{
-   set _CPUTAPID $CPUTAPID
-@} else @{
-   set _CPUTAPID 0x25966041
-@}
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe \
-        -expected-id $_CPUTAPID
+@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/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)
+@end itemize
 
+@subsection Add CPU targets
 
-if @{ [info exists BSTAPID ] @} @{
-   set _BSTAPID $BSTAPID
-@} else @{
-   set _BSTAPID 0x1457f041
-@}
-jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 \
-        -expected-id $_BSTAPID
+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:
 
-set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
+@example
+target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
 @end example
 
-@b{Tap Naming Convention}
-
-See the command ``jtag newtap'' for detail, but in brief the names you should use are:
+Work areas are small RAM areas associated with CPU targets.
+They are used by OpenOCD to speed up downloads,
+and to download small snippets of code to program flash chips.
+If the chip includes a form of ``on-chip-ram'' - and many do - define
+a work area if you can.
+Again using the at91sam7 as an example, this can look like:
 
-@itemize @bullet
-@item @b{tap}
-@item @b{cpu}
-@item @b{flash}
-@item @b{bs}
-@item @b{etb}
-@item @b{jrc}
-@item @b{unknownN} - it happens :-(
-@end itemize
+@example
+$_TARGETNAME configure -work-area-phys 0x00200000 \
+	-work-area-size 0x4000 -work-area-backup 0
+@end example
 
 @subsection Reset Configuration
 
@@ -1101,17 +1096,6 @@ Some chips have specific ways the TRST and SRST signals are
 managed. If these are @b{CHIP SPECIFIC} they go here, if they are
 @b{BOARD SPECIFIC} they go in the board file.
 
-@subsection Work Areas
-
-Work areas are small RAM areas used by OpenOCD to speed up downloads,
-and to download small snippets of code to program flash chips.
-
-If the chip includes a form of ``on-chip-ram'' - and many do - define
-a reasonable work area and use the ``backup'' option.
-
-@b{PROBLEMS:} On more complex chips, this ``work area'' may become
-inaccessible if/when the application code enables or disables the MMU.
-
 @subsection ARM Core Specific Hacks
 
 If the chip has a DCC, enable it. If the chip is an ARM9 with some
@@ -1800,208 +1784,273 @@ powerup and pressing a reset button.
 @end deffn
 
 
-@node Tap Creation
-@chapter Tap Creation
-@cindex tap creation
-@cindex tap configuration
-
-In order for OpenOCD to control a target, a JTAG tap must be
-defined/created.
-
-Commands to create taps are normally found in a configuration file and
-are not normally typed by a human.
+@node TAP Creation
+@chapter TAP Creation
+@cindex TAP creation
+@cindex TAP configuration
 
-When a tap is created a @b{dotted.name} is created for the tap. Other
-commands use that dotted.name to manipulate or refer to the tap.
+@emph{Test Access Ports} (TAPs) are the core of JTAG.
+TAPs serve many roles, including:
 
-Tap Uses:
 @itemize @bullet
-@item @b{Debug Target} A tap can be used by a GDB debug target
-@item @b{Flash Programing} Some chips program the flash directly via JTAG,
-instead of indirectly by making a CPU do it.
-@item @b{Boundry Scan} Some chips support boundary scan.
+@item @b{Debug Target} A CPU TAP can be used as a GDB debug target
+@item @b{Flash Programing} Some chips program the flash directly via JTAG.
+Others do it indirectly, making a CPU do it.
+@item @b{Program Download} Using the same CPU support GDB uses,
+you can initialize a DRAM controller, download code to DRAM, and then
+start running that code.
+@item @b{Boundary Scan} Most chips support boundary scan, which
+helps test for board assembly problems like solder bridges
+and missing connections
 @end itemize
 
+OpenOCD must know about the active TAPs on your board(s).
+Setting up the TAPs is the core task of your configuration files.
+Once those TAPs are set up, you can pass their names to code
+which sets up CPUs and exports them as GDB targets,
+probes flash memory, performs low-level JTAG operations, and more.
+
+@section Scan Chains
+
+OpenOCD uses a JTAG adapter (interface) to talk to your board,
+which has a daisy chain of TAPs.
+That daisy chain is called a @dfn{scan chain}.
+Simple configurations may have a single TAP in the scan chain,
+perhaps for a microcontroller.
+Complex configurations might have a dozen or more TAPs:
+several in one chip, more in the next, and connecting
+to other boards with their own chips and TAPs.
+
+Unfortunately those TAPs can't always be autoconfigured,
+because not all devices provide good support for that.
+(JTAG doesn't require supporting IDCODE instructions.)
+The configuration mechanism currently supported by OpenOCD
+requires explicit configuration of all TAP devices using
+@command{jtag newtap} commands.
+One like this would create a tap named @code{chip1.cpu}:
 
-@anchor{jtag newtap}
-@section jtag newtap
-@b{@t{jtag newtap CHIPNAME TAPNAME  configparams ....}}
-@cindex jtag newtap
-@cindex tap
-@cindex tap order
-@cindex tap geometry
-
-@comment START options
-@itemize @bullet
-@item @b{CHIPNAME}
-@* is a symbolic name of the chip. 
-@item @b{TAPNAME}
-@* is a symbol name of a tap present on the chip.
-@item @b{Required configparams}
-@* Every tap has 3 required configparams, and several ``optional
-parameters'', the required parameters are:
-@comment START REQUIRED
-@itemize @bullet
-@item @b{-irlen NUMBER} - the length in bits of the instruction register, mostly 4 or 5 bits.
-@item @b{-ircapture NUMBER} - the IDCODE capture command, usually 0x01.
-@item @b{-irmask NUMBER} - the corresponding mask for the IR register. For
-some devices, there are bits in the IR that aren't used.  This lets you mask
-them off when doing comparisons.  In general, this should just be all ones for
-the size of the IR.
-@comment END REQUIRED
-@end itemize
-An example of a FOOBAR Tap
 @example
-jtag newtap foobar tap -irlen 7 -ircapture 0x42 -irmask 0x55
+jtag newtap chip1 cpu -irlen 7 -ircapture 0x01 -irmask 0x55
 @end example
-Creates the tap ``foobar.tap'' with the instruction register (IR) is 7
-bits long, during Capture-IR 0x42 is loaded into the IR, and bits
-[6,4,2,0] are checked.
 
-@item @b{Optional configparams}
-@comment START Optional
-@itemize @bullet
-@item @b{-expected-id NUMBER}
-@* By default it is zero. If non-zero represents the
-expected tap ID used when the JTAG chain is examined. Repeat 
-the option as many times as required if multiple id's can be
-expected. See below. 
-@item @b{-disable}
-@item @b{-enable}
-@* By default not specified the tap is enabled. Some chips have a
-JTAG route controller (JRC) that is used to enable and/or disable
-specific JTAG taps. You can later enable or disable any JTAG tap via
-the command @b{jtag tapenable DOTTED.NAME} or @b{jtag tapdisable 
-DOTTED.NAME}
-@comment END Optional
-@end itemize
-
-@comment END OPTIONS
-@end itemize
-@b{Notes:}
-@comment START NOTES
-@itemize @bullet
-@item @b{Technically}
-@* newtap is a sub command of the ``jtag'' command
-@item @b{Big Picture Background}
-@*GDB Talks to OpenOCD using the GDB protocol via
-TCP/IP. OpenOCD then uses the JTAG interface (the dongle) to
-control the JTAG chain on your board. Your board has one or more chips
-in a @i{daisy chain configuration}. Each chip may have one or more
-JTAG taps. GDB ends up talking via OpenOCD to one of the taps.
-@item @b{NAME Rules}
-@*Names follow ``C'' symbol name rules (start with alpha ...)
-@item @b{TAPNAME - Conventions}
-@itemize @bullet
-@item @b{tap} - should be used only FPGA or CPLD like devices with a single tap.
-@item @b{cpu} - the main CPU of the chip, alternatively @b{foo.arm} and @b{foo.dsp}
-@item @b{flash} - if the chip has a flash tap, example: str912.flash
-@item @b{bs} - for boundary scan if this is a seperate tap.
-@item @b{etb} - for an embedded trace buffer (example: an ARM ETB11)
-@item @b{jrc} - for JTAG route controller (example: OMAP3530 found on Beagleboards)
-@item @b{unknownN} - where N is a number if you have no idea what the tap is for
-@item @b{Other names} - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the ``sdma'' tap.
-@item @b{When in doubt} - use the chip maker's name in their data sheet.
-@end itemize
-@item @b{DOTTED.NAME}
-@* @b{CHIPNAME}.@b{TAPNAME} creates the tap name, aka: the
-@b{Dotted.Name} is the @b{CHIPNAME} and @b{TAPNAME} combined with a
-dot (period); for example: @b{xilinx.tap}, @b{str912.flash},
-@b{omap3530.jrc}, or @b{stm32.cpu} The @b{dotted.name} is used in
-numerous other places to refer to various taps.
-@item @b{ORDER}
-@* The order this command appears via the config files is
-important.
-@item @b{Multi Tap Example}
-@* This example is based on the ST Microsystems STR912. See the ST
-document titled: @b{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
+Each target configuration file lists the TAPs provided
+by a given chip.
+Board configuration files combine all the targets on a board,
+and so forth.
+Note that @emph{the order in which TAPs are created is very important.}
+It must match the order in the JTAG scan chain, both inside
+a single chip and between them.
+
+For example, the ST Microsystems STR912 chip has
+three separate TAPs@footnote{See the ST
+document titled: @emph{STR91xFAxxx, Section 3.15 Jtag Interface, Page:
 28/102, Figure 3: JTAG chaining inside the STR91xFA}.
-
 @url{http://eu.st.com/stonline/products/literature/ds/13495.pdf}
-@*@b{checked: 28/nov/2008}
-
-The diagram shows that the TDO pin connects to the flash tap, flash TDI
-connects to the CPU debug tap, CPU TDI connects to the boundary scan
-tap which then connects to the TDI pin.
+Checked: 28-Nov-2008}.
+To configure those taps, @file{target/str912.cfg}
+includes commands something like this:
 
 @example
-   # The order is...
-   # create tap: 'str912.flash'
-   jtag newtap str912 flash  ... params ...
-   # create tap: 'str912.cpu'
-   jtag newtap str912 cpu  ... params ...
-   # create tap: 'str912.bs'
-   jtag newtap str912 bs  ... params ...
+jtag newtap str912 flash ... params ...
+jtag newtap str912 cpu ... params ...
+jtag newtap str912 bs ... params ...
 @end example
 
-@item @b{Note: Deprecated} - Index Numbers
-@* Prior to 28/nov/2008, JTAG taps where numbered from 0..N this
-feature is still present, however its use is highly discouraged and
-should not be counted upon.  Update all of your scripts to use
-TAP names rather than numbers.
-@item @b{Multiple chips}
-@* If your board has multiple chips, you should be
-able to @b{source} two configuration files, in the proper order, and
-have the taps created in the proper order.
-@comment END NOTES
+Actual config files use a variable instead of literals like
+@option{str912}, to support more than one chip of each type.
+@xref{Config File Guidelines}.
+
+@section TAP Names
+
+When a TAP objects is created with @command{jtag newtap},
+a @dfn{dotted.name} is created for the TAP, combining the
+name of a module (usually a chip) and a label for the TAP.
+For example: @code{xilinx.tap}, @code{str912.flash},
+@code{omap3530.jrc}, @code{dm6446.dsp}, or @code{stm32.cpu}.
+Many other commands use that dotted.name to manipulate or
+refer to the TAP.  For example, CPU configuration uses the
+name, as does declaration of NAND or NOR flash banks.
+
+The components of a dotted name should follow ``C'' symbol
+name rules:  start with an alphabetic character, then numbers
+and underscores are OK; while others (including dots!) are not.
+
+@quotation Tip
+In older code, JTAG TAPs were numbered from 0..N.
+This feature is still present.
+However its use is highly discouraged, and
+should not be counted upon.
+Update all of your scripts to use TAP names rather than numbers.
+Using TAP numbers in target configuration scripts prevents
+reusing on boards with multiple targets.
+@end quotation
+
+@anchor{TAP Creation Commands}
+@section TAP Creation Commands
+
+@c shouldn't this be(come) a {Config Command}?
+@anchor{jtag newtap}
+@deffn Command {jtag newtap} chipname tapname configparams...
+Creates a new TAP with the dotted name @var{chipname}.@var{tapname},
+and configured according to the various @var{configparams}.
+
+The @var{chipname} is a symbolic name for the chip.
+Conventionally target config files use @code{$_CHIPNAME},
+defaulting to the model name given by the chip vendor but
+overridable.
+
+@cindex TAP naming convention
+The @var{tapname} reflects the role of that TAP,
+and should follow this convention:
+
+@itemize @bullet
+@item @code{bs} -- For boundary scan if this is a seperate TAP;
+@item @code{cpu} -- The main CPU of the chip, alternatively
+@code{arm} and @code{dsp} on chips with both ARM and DSP CPUs,
+@code{arm1} and @code{arm2} on chips two ARMs, and so forth;
+@item @code{etb} -- For an embedded trace buffer (example: an ARM ETB11);
+@item @code{flash} -- If the chip has a flash TAP, like the str912;
+@item @code{jrc} -- For JTAG route controller (example: the ICEpick modules
+on many Texas Instruments chips, like the OMAP3530 on Beagleboards);
+@item @code{tap} -- Should be used only FPGA or CPLD like devices
+with a single TAP;
+@item @code{unknownN} -- If you have no idea what the TAP is for (N is a number);
+@item @emph{when in doubt} -- Use the chip maker's name in their data sheet.
+For example, the Freescale IMX31 has a SDMA (Smart DMA) with
+a JTAG TAP; that TAP should be named @code{sdma}.
 @end itemize
-@comment at command level
 
-@section Enable/Disable Taps
-@b{Note:} These commands are intended to be used as a machine/script
-interface. Humans might find the ``scan_chain'' command more helpful
-when querying the state of the JTAG taps.
+Every TAP requires at least the following @var{configparams}:
 
-@b{By default, all taps are enabled}
+@itemize @bullet
+@item @code{-ircapture} @var{NUMBER}
+@*The IDCODE capture command, such as 0x01.
+@item @code{-irlen} @var{NUMBER}
+@*The length in bits of the
+instruction register, such as 4 or 5 bits.
+@item @code{-irmask} @var{NUMBER}
+@*A mask for the IR register.
+For some devices, there are bits in the IR that aren't used.
+This lets OpenOCD mask them off when doing IDCODE comparisons.
+In general, this should just be all ones for the size of the IR.
+@end itemize
+
+A TAP may also provide optional @var{configparams}:
 
 @itemize @bullet
-@item @b{jtag tapenable} @var{DOTTED.NAME}
-@item @b{jtag tapdisable} @var{DOTTED.NAME}
-@item @b{jtag tapisenabled} @var{DOTTED.NAME}
+@item @code{-disable} (or @code{-enable})
+@*Use the @code{-disable} paramater to flag a TAP which is not
+linked in to the scan chain when it is declared.
+You may use @code{-enable} to highlight the default state
+(the TAP is linked in).
+@xref{Enabling and Disabling TAPs}.
+@item @code{-expected-id} @var{number}
+@*A non-zero value represents the expected 32-bit IDCODE
+found when the JTAG chain is examined.
+These codes are not required by all JTAG devices.
+@emph{Repeat the option} as many times as required if more than one
+ID code could appear (for example, multiple versions).
 @end itemize
-@cindex tap enable
-@cindex tap disable
-@cindex JRC
-@cindex route controller
+@end deffn
 
-These commands are used when your target has a JTAG route controller
-that effectively adds or removes a tap from the JTAG chain in a
-non-standard way.
+@c @deffn Command {jtag arp_init-reset}
+@c ... more or less "init" ?
 
-The ``standard way'' to remove a tap would be to place the tap in
-bypass mode. But with the advent of modern chips, this is not always a
-good solution. Some taps operate slowly, others operate fast, and
-there are other JTAG clock synchronisation problems one must face. To
-solve that problem, the JTAG route controller was introduced. Rather
-than ``bypass'' the tap, the tap is completely removed from the
-circuit and skipped.
+@anchor{Enabling and Disabling TAPs}
+@section Enabling and Disabling TAPs
+@cindex TAP events
 
+In some systems, a @dfn{JTAG Route Controller} (JRC)
+is used to enable and/or disable specific JTAG TAPs.
+Many ARM based chips from Texas Instruments include
+an ``ICEpick'' module, which is a JRC.
+Such chips include DaVinci and OMAP3 processors.
 
-From OpenOCD's point of view, a JTAG tap is in one of 3 states:
+A given TAP may not be visible until the JRC has been
+told to link it into the scan chain; and if the JRC
+has been told to unlink that TAP, it will no longer
+be visible.
+Such routers address problems that JTAG ``bypass mode''
+ignores, such as:
 
-@itemize @bullet
-@item @b{Enabled - Not In ByPass} and has a variable bit length
-@item @b{Enabled - In ByPass} and has a length of exactly 1 bit.
-@item @b{Disabled} and has a length of ZERO and is removed from the circuit.
+@itemize
+@item The scan chain can only go as fast as its slowest TAP.
+@item Having many TAPs slows instruction scans, since all
+TAPs receive new instructions.
+@item TAPs in the scan chain must be powered up, which wastes
+power and prevents debugging some power management mechanisms.
 @end itemize
 
-The IEEE JTAG definition has no concept of a ``disabled'' tap.
-@b{Historical note:} this feature was added 28/nov/2008
+The IEEE 1149.1 JTAG standard has no concept of a ``disabled'' tap,
+as implied by the existence of JTAG routers.
+However, the upcoming IEEE 1149.7 framework (layered on top of JTAG)
+does include a kind of JTAG router functionality.
 
-@b{jtag tapisenabled DOTTED.NAME}
+@c (a) currently the event handlers don't seem to be able to
+@c     fail in a way that could lead to no-change-of-state.
+@c (b) eventually non-event configuration should be possible,
+@c     in which case some this documentation must move.
 
-This command returns 1 if the named tap is currently enabled, 0 if not.
-This command exists so that scripts that manipulate a JRC (like the
-OMAP3530 has) can determine if OpenOCD thinks a tap is presently
-enabled or disabled.
+@deffn Command {jtag cget} dotted.name @option{-event} name
+@deffnx Command {jtag configure} dotted.name @option{-event} name string
+At this writing this mechanism is used only for event handling,
+and the only two events relate to TAP enabling and disabling.
 
-@page
-@node Target Configuration
-@chapter Target Configuration
+The @code{configure} subcommand assigns an event handler,
+a TCL string which is evaluated when the event is triggered.
+The @code{cget} subcommand returns that handler.
+The two possible values for an event @var{name}
+are @option{tap-disable} and @option{tap-enable}.
+
+So for example, when defining a TAP for a CPU connected to
+a JTAG router, you should define TAP event handlers using
+code that looks something like this:
+
+@example
+jtag configure CHIP.cpu -event tap-enable @{
+  echo "Enabling CPU TAP"
+  ... jtag operations using CHIP.jrc
+@}
+jtag configure CHIP.cpu -event tap-disable @{
+  echo "Disabling CPU TAP"
+  ... jtag operations using CHIP.jrc
+@}
+@end example
+@end deffn
+
+@deffn Command {jtag tapdisable} dotted.name
+@deffnx Command {jtag tapenable} dotted.name
+@deffnx Command {jtag tapisenabled} dotted.name
+These three commands all return the string "1" if the tap
+specified by @var{dotted.name} is enabled,
+and "0" if it is disbabled.
+The @command{tapenable} variant first enables the tap
+by sending it a @option{tap-enable} event.
+The @command{tapdisable} variant first disables the tap
+by sending it a @option{tap-disable} event.
+
+@quotation Note
+Humans will find the @command{scan_chain} command more helpful
+than the script-oriented @command{tapisenabled}
+for querying the state of the JTAG taps.
+@end quotation
+@end deffn
+
+@node CPU Configuration
+@chapter CPU Configuration
 @cindex GDB target
 
-This chapter discusses how to create a GDB debug target.  Before
-creating a ``target'' a JTAG tap DOTTED.NAME must exist first.
+This chapter discusses how to create a GDB debug target for a CPU.
+You can also access these targets without GDB
+(@pxref{Architecture and Core Commands}) and, where relevant,
+through various kinds of NAND and NOR flash commands.
+Also, if you have multiple CPUs you can have multiple such targets.
+
+Before creating a ``target'', you must have added its TAP to the scan chain.
+When you've added that TAP, you will have a @code{dotted.name}
+which is used to set up the CPU support.
+The chip-specific configuration file will normally configure its CPU(s)
+right after it adds all of the chip's TAPs to the scan chain.
 
 @section targets [NAME]
 @b{Note:} This command name is PLURAL - not singular.
@@ -2067,7 +2116,7 @@ Example:
 @section TARGETNAME (object) commands
 @b{Use:} Once a target is created, an ``object name'' that represents the
 target is created. By convention, the target name is identical to the
-tap name. In a multiple target system, one can preceed many common
+tap name. In a multiple target system, one can precede many common
 commands with a specific target name and effect only that target.
 @example
     str912.cpu    mww 0x1234 0x42
@@ -2242,22 +2291,6 @@ multiplexing, and so on.
 @* Success
 @item @b{resumed}
 @* Target has resumed
-@item @b{tap-enable}
-@* Executed by @b{jtag tapenable DOTTED.NAME} command. Example:
-@example
-jtag configure DOTTED.NAME -event tap-enable @{
-  puts "Enabling CPU"
-  ...
-@}
-@end example
-@item @b{tap-disable}
-@*Executed by @b{jtag tapdisable DOTTED.NAME} command. Example:
-@example
-jtag configure DOTTED.NAME -event tap-disable @{
-  puts "Disabling CPU"
-  ...
-@}
-@end example
 @end itemize
 
 @anchor{Target Create}
@@ -2338,6 +2371,11 @@ Example:
   @}
 @end example
 
+@b{PROBLEM:} On more complex chips, the work area can become
+inaccessible when application code enables or disables the MMU.
+For example, the MMU context used to acess the virtual address
+will probably matter.
+
 @section Target Variants
 @itemize @bullet
 @item @b{cortex_m3}