+The programmer's model matches the @code{-command} option used in Tcl/Tk
+buttons and events. The two examples below act the same, but one creates
+and invokes a small procedure while the other inlines it.
+
+@example
+proc my_attach_proc @{ @} @{
+ echo "Reset..."
+ reset halt
+@}
+mychip.cpu configure -event gdb-attach my_attach_proc
+mychip.cpu configure -event gdb-attach @{
+ echo "Reset..."
+ reset halt
+@}
+@end example
+
+The following target events are defined:
+
+@itemize @bullet
+@item @b{debug-halted}
+@* The target has halted for debug reasons (i.e.: breakpoint)
+@item @b{debug-resumed}
+@* The target has resumed (i.e.: gdb said run)
+@item @b{early-halted}
+@* Occurs early in the halt process
+@ignore
+@item @b{examine-end}
+@* Currently not used (goal: when JTAG examine completes)
+@item @b{examine-start}
+@* Currently not used (goal: when JTAG examine starts)
+@end ignore
+@item @b{gdb-attach}
+@* When GDB connects
+@item @b{gdb-detach}
+@* When GDB disconnects
+@item @b{gdb-end}
+@* When the target has halted and GDB is not doing anything (see early halt)
+@item @b{gdb-flash-erase-start}
+@* Before the GDB flash process tries to erase the flash
+@item @b{gdb-flash-erase-end}
+@* After the GDB flash process has finished erasing the flash
+@item @b{gdb-flash-write-start}
+@* Before GDB writes to the flash
+@item @b{gdb-flash-write-end}
+@* After GDB writes to the flash
+@item @b{gdb-start}
+@* Before the target steps, gdb is trying to start/resume the target
+@item @b{halted}
+@* The target has halted
+@ignore
+@item @b{old-gdb_program_config}
+@* DO NOT USE THIS: Used internally
+@item @b{old-pre_resume}
+@* DO NOT USE THIS: Used internally
+@end ignore
+@item @b{reset-assert-pre}
+@* Issued as part of @command{reset} processing
+after SRST and/or TRST were activated and deactivated,
+but before reset is asserted on the tap.
+@item @b{reset-assert-post}
+@* Issued as part of @command{reset} processing
+when reset is asserted on the tap.
+@item @b{reset-deassert-pre}
+@* Issued as part of @command{reset} processing
+when reset is about to be released on the tap.
+
+For some chips, this may be a good place to make sure
+the JTAG clock is slow enough to work before the PLL
+has been set up to allow faster JTAG speeds.
+@item @b{reset-deassert-post}
+@* Issued as part of @command{reset} processing
+when reset has been released on the tap.
+@item @b{reset-end}
+@* Issued as the final step in @command{reset} processing.
+@ignore
+@item @b{reset-halt-post}
+@* Currently not used
+@item @b{reset-halt-pre}
+@* Currently not used
+@end ignore
+@item @b{reset-init}
+@* Used by @b{reset init} command for board-specific initialization.
+This event fires after @emph{reset-deassert-post}.
+
+This is where you would configure PLLs and clocking, set up DRAM so
+you can download programs that don't fit in on-chip SRAM, set up pin
+multiplexing, and so on.
+@item @b{reset-start}
+@* Issued as part of @command{reset} processing
+before either SRST or TRST are activated.
+@ignore
+@item @b{reset-wait-pos}
+@* Currently not used
+@item @b{reset-wait-pre}
+@* Currently not used
+@end ignore
+@item @b{resume-start}
+@* Before any target is resumed
+@item @b{resume-end}
+@* After all targets have resumed
+@item @b{resume-ok}
+@* Success
+@item @b{resumed}
+@* Target has resumed
+@end itemize
+
+
+@node Flash Commands
+@chapter Flash Commands
+
+OpenOCD has different commands for NOR and NAND flash;
+the ``flash'' command works with NOR flash, while
+the ``nand'' command works with NAND flash.
+This partially reflects different hardware technologies:
+NOR flash usually supports direct CPU instruction and data bus access,
+while data from a NAND flash must be copied to memory before it can be
+used. (SPI flash must also be copied to memory before use.)
+However, the documentation also uses ``flash'' as a generic term;
+for example, ``Put flash configuration in board-specific files''.
+
+@quotation Note
+As of 28-nov-2008 OpenOCD does not know how to program a SPI
+flash that a micro may boot from. Perhaps you, the reader, would like to
+contribute support for this.
+@end quotation
+
+Flash Steps:
+@enumerate
+@item Configure via the command @command{flash bank}
+@* Do this in a board-specific configuration file,
+passing parameters as needed by the driver.
+@item Operate on the flash via @command{flash subcommand}
+@* Often commands to manipulate the flash are typed by a human, or run
+via a script in some automated way. Common tasks include writing a
+boot loader, operating system, or other data.
+@item GDB Flashing
+@* Flashing via GDB requires the flash be configured via ``flash
+bank'', and the GDB flash features be enabled.
+@xref{GDB Configuration}.
+@end enumerate
+
+Many CPUs have the ablity to ``boot'' from the first flash bank.
+This means that misprograming 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.
+
+@section Flash Configuration Commands
+@cindex flash configuration
+
+@deffn {Config Command} {flash bank} driver base size chip_width bus_width target [driver_options]
+Configures a flash bank which provides persistent storage
+for addresses from @math{base} to @math{base + size - 1}.
+These banks will often be visible to GDB through the target's memory map.
+In some cases, configuring a flash bank will activate extra commands;
+see the driver-specific documentation.
+
+@itemize @bullet
+@item @var{driver} ... identifies the controller driver
+associated with the flash bank being declared.
+This is usually @code{cfi} for external flash, or else
+the name of a microcontroller with embedded flash memory.
+@xref{Flash Driver List}.
+@item @var{base} ... Base address of the flash chip.
+@item @var{size} ... Size of the chip, in bytes.
+For some drivers, this value is detected from the hardware.
+@item @var{chip_width} ... Width of the flash chip, in bytes;
+ignored for most microcontroller drivers.
+@item @var{bus_width} ... Width of the data bus used to access the
+chip, in bytes; ignored for most microcontroller drivers.
+@item @var{target} ... Names the target used to issue
+commands to the flash controller.
+@comment Actually, it's currently a controller-specific parameter...
+@item @var{driver_options} ... drivers may support, or require,
+additional parameters. See the driver-specific documentation
+for more information.
+@end itemize
+@quotation Note
+This command is not available after OpenOCD initialization has completed.
+Use it in board specific configuration files, not interactively.
+@end quotation
+@end deffn
+
+@comment the REAL name for this command is "ocd_flash_banks"
+@comment less confusing would be: "flash list" (like "nand list")
+@deffn Command {flash banks}
+Prints a one-line summary of each device declared
+using @command{flash bank}, numbered from zero.
+Note that this is the @emph{plural} form;
+the @emph{singular} form is a very different command.
+@end deffn
+
+@deffn Command {flash probe} num
+Identify the flash, or validate the parameters of the configured flash. Operation
+depends on the flash type.
+The @var{num} parameter is a value shown by @command{flash banks}.
+Most flash commands will implicitly @emph{autoprobe} the bank;
+flash drivers can distinguish between probing and autoprobing,
+but most don't bother.
+@end deffn
+
+@section Erasing, Reading, Writing to Flash
+@cindex flash erasing
+@cindex flash reading
+@cindex flash writing
+@cindex flash programming
+
+One feature distinguishing NOR flash from NAND or serial flash technologies
+is that for read access, it acts exactly like any other addressible memory.
+This means you can use normal memory read commands like @command{mdw} or
+@command{dump_image} with it, with no special @command{flash} subcommands.
+@xref{Memory access}, and @ref{Image access}.
+
+Write access works differently. Flash memory normally needs to be erased
+before it's written. Erasing a sector turns all of its bits to ones, and
+writing can turn ones into zeroes. This is why there are special commands
+for interactive erasing and writing, and why GDB needs to know which parts
+of the address space hold NOR flash memory.
+
+@quotation Note
+Most of these erase and write commands leverage the fact that NOR flash
+chips consume target address space. They implicitly refer to the current
+JTAG target, and map from an address in that target's address space
+back to a flash bank.
+@comment In May 2009, those mappings may fail if any bank associated
+@comment with that target doesn't succesfuly autoprobe ... bug worth fixing?
+A few commands use abstract addressing based on bank and sector numbers,
+and don't depend on searching the current target and its address space.
+Avoid confusing the two command models.
+@end quotation
+
+Some flash chips implement software protection against accidental writes,
+since such buggy writes could in some cases ``brick'' a system.
+For such systems, erasing and writing may require sector protection to be
+disabled first.
+Examples include CFI flash such as ``Intel Advanced Bootblock flash'',
+and AT91SAM7 on-chip flash.
+@xref{flash protect}.
+
+@anchor{flash erase_sector}
+@deffn Command {flash erase_sector} num first last
+Erase sectors in bank @var{num}, starting at sector @var{first} up to and including
+@var{last}. Sector numbering starts at 0.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {flash erase_address} address length
+Erase sectors starting at @var{address} for @var{length} bytes.
+The flash bank to use is inferred from the @var{address}, and
+the specified length must stay within that bank.
+As a special case, when @var{length} is zero and @var{address} is
+the start of the bank, the whole flash is erased.
+@end deffn
+
+@deffn Command {flash fillw} address word length
+@deffnx Command {flash fillh} address halfword length
+@deffnx Command {flash fillb} address byte length
+Fills flash memory with the specified @var{word} (32 bits),
+@var{halfword} (16 bits), or @var{byte} (8-bit) pattern,
+starting at @var{address} and continuing
+for @var{length} units (word/halfword/byte).
+No erasure is done before writing; when needed, that must be done
+before issuing this command.
+Writes are done in blocks of up to 1024 bytes, and each write is
+verified by reading back the data and comparing it to what was written.
+The flash bank to use is inferred from the @var{address} of
+each block, and the specified length must stay within that bank.
+@end deffn
+@comment no current checks for errors if fill blocks touch multiple banks!
+
+@anchor{flash write_bank}
+@deffn Command {flash write_bank} num filename offset
+Write the binary @file{filename} to flash bank @var{num},
+starting at @var{offset} bytes from the beginning of the bank.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@anchor{flash write_image}
+@deffn Command {flash write_image} [erase] filename [offset] [type]
+Write the image @file{filename} to the current target's flash bank(s).
+A relocation @var{offset} may be specified, in which case it is added
+to the base address for each section in the image.
+The file [@var{type}] can be specified
+explicitly as @option{bin} (binary), @option{ihex} (Intel hex),
+@option{elf} (ELF file), @option{s19} (Motorola s19).
+@option{mem}, or @option{builder}.
+The relevant flash sectors will be erased prior to programming
+if the @option{erase} parameter is given.
+The flash bank to use is inferred from the @var{address} of
+each image segment.
+@end deffn
+
+@section Other Flash commands
+@cindex flash protection
+
+@deffn Command {flash erase_check} num
+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 an @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.
+@end deffn
+
+@anchor{flash protect}
+@deffn Command {flash protect} num first last (on|off)
+Enable (@var{on}) or disable (@var{off}) protection of flash sectors
+@var{first} to @var{last} of flash bank @var{num}.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+
+@deffn Command {flash protect_check} num
+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.
+@end deffn
+
+@anchor{Flash Driver List}
+@section Flash Drivers, Options, and Commands
+As noted above, the @command{flash bank} command requires a driver name,
+and allows driver-specific options and behaviors.
+Some drivers also activate driver-specific commands.
+
+@subsection External Flash
+
+@deffn {Flash Driver} cfi
+@cindex Common Flash Interface
+@cindex CFI
+The ``Common Flash Interface'' (CFI) is the main standard for
+external NOR flash chips, each of which connects to a
+specific external chip select on the CPU.
+Frequently the first such chip is used to boot the system.
+Your board's @code{reset-init} handler might need to
+configure additional chip selects using other commands (like: @command{mww} to
+configure a bus and its timings) , or
+perhaps configure a GPIO pin that controls the ``write protect'' pin
+on the flash chip.
+The CFI driver can use a target-specific working area to significantly
+speed up operation.
+
+The CFI driver can accept the following optional parameters, in any order: