@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
* OpenOCD Concept Index:: Concept Index
-* OpenOCD Command Index:: Command Index
+* Command and Driver Index:: Command and Driver Index
@end menu
@node About
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
-Cortex-M3 (Luminary Stellaris LM3 and ST STM32) based cores to be
+Cortex-M3 (Stellaris LM3 and ST STM32) based cores to be
debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
@item @b{ftdi2232} libftdi (@uref{http://www.intra2net.com/opensource/ftdi/})
@item @b{ftd2xx} libftd2xx (@uref{http://www.ftdichip.com/Drivers/D2XX.htm})
@item When using the Amontec JTAGkey, you have to get the drivers from the Amontec
-homepage (@uref{http://www.amontec.com}), as the JTAGkey uses a non-standard VID/PID.
+homepage (@uref{http://www.amontec.com}). The JTAGkey uses a non-standard VID/PID.
@end itemize
libftdi is supported under Windows. Do not use versions earlier than 0.14.
@item
@option{--enable-ft2232_libftdi} - An open source (free) alternative to FTDICHIP.COM ftd2xx solution (Linux, MacOS, Cygwin).
@item
-@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c, point at the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
+@option{--with-ftd2xx-win32-zipdir=PATH} - If using FTDICHIP.COM ft2232c driver,
+give the directory where the Win32 FTDICHIP.COM 'CDM' driver zip file was unpacked.
@item
-@option{--with-ftd2xx-linux-tardir=PATH} - Linux only. Equivalent of @option{--with-ftd2xx-win32-zipdir}, where you unpacked the TAR.GZ file.
+@option{--with-ftd2xx-linux-tardir=PATH} - If using FTDICHIP.COM ft2232c driver
+on Linux, give the directory where the Linux driver's TAR.GZ file was unpacked.
@item
@option{--with-ftd2xx-lib=shared|static} - Linux only. Default: static. Specifies how the FTDICHIP.COM libftd2xx driver should be linked. Note: 'static' only works in conjunction with @option{--with-ftd2xx-linux-tardir}. The 'shared' value is supported (12/26/2008), however you must manually install the required header files and shared libraries in an appropriate place. This uses ``libusb'' internally.
@item
Below is an example build process:
-1) Check out the latest version of ``openocd'' from SVN.
+@enumerate
+@item Check out the latest version of ``openocd'' from SVN.
-2) Download & unpack either the Windows or Linux FTD2xx drivers
- (@uref{http://www.ftdichip.com/Drivers/D2XX.htm}).
+@item If you are using the FTDICHIP.COM driver, download
+and unpack the Windows or Linux FTD2xx drivers
+(@uref{http://www.ftdichip.com/Drivers/D2XX.htm}).
+If you are using the libftdi driver, install that package
+(e.g. @command{apt-get install libftdi} on systems with APT).
@example
- /home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents.
- /home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents.
+/home/duane/ftd2xx.win32 => the Cygwin/Win32 ZIP file contents
+/home/duane/libftd2xx0.4.16 => the Linux TAR.GZ file contents
@end example
-3) Configure with these options:
+@item Configure with options resembling the following.
+
+@enumerate a
+@item Cygwin FTDICHIP solution:
+@example
+./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
+@end example
+@item Linux FTDICHIP solution:
@example
-Cygwin FTDICHIP solution:
- ./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ftd2xx-win32-zipdir=/home/duane/ftd2xx.win32
-
-Linux FTDICHIP solution:
- ./configure --prefix=/home/duane/mytools \
- --enable-ft2232_ftd2xx \
- --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
-
-Cygwin/Linux LIBFTDI solution:
- Assumes:
- 1a) For Windows: The Windows port of LIBUSB is in place.
- 1b) For Linux: libusb has been built/installed and is in place.
-
- 2) And libftdi has been built and installed
- Note: libftdi - relies upon libusb.
-
- ./configure --prefix=/home/duane/mytools \
- --enable-ft2232_libftdi
-
+./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_ftd2xx \
+ --with-ft2xx-linux-tardir=/home/duane/libftd2xx0.4.16
@end example
-4) Then just type ``make'', and perhaps ``make install''.
+@item Cygwin/Linux LIBFTDI solution ... assuming that
+@itemize
+@item For Windows -- that the Windows port of LIBUSB is in place.
+@item For Linux -- that libusb has been built/installed and is in place.
+@item That libftdi has been built and installed (relies on libusb).
+@end itemize
+
+Then configure the libftdi solution like this:
+
+@example
+./configure --prefix=/home/duane/mytools \
+ --enable-ft2232_libftdi
+@end example
+@end enumerate
+
+@item Then just type ``make'', and perhaps ``make install''.
+@end enumerate
@section Miscellaneous Configure Options
There are many USB JTAG dongles on the market, many of them are based
on a chip from ``Future Technology Devices International'' (FTDI)
-known as the FTDI FT2232.
-
-See: @url{http://www.ftdichip.com} or @url{http://www.ftdichip.com/Products/FT2232H.htm}
+known as the FTDI FT2232; this is a USB full speed (12 Mbps) chip.
+See: @url{http://www.ftdichip.com} for more information.
+In summer 2009, USB high speed (480 Mbps) versions of these FTDI
+chips are starting to become available in JTAG adapters.
As of 28/Nov/2008, the following are supported:
@item @b{signalyzer}
@* See: @url{http://www.signalyzer.com}
@item @b{evb_lm3s811}
-@* See: @url{http://www.luminarymicro.com} - The Luminary Micro Stellaris LM3S811 eval board has an FTD2232C chip built in.
+@* See: @url{http://www.luminarymicro.com} - The Stellaris LM3S811 eval board has an FTD2232C chip built in.
@item @b{olimex-jtag}
@* See: @url{http://www.olimex.com}
@item @b{flyswatter}
@* See: @url{http://www.tincantools.com}
@item @b{turtelizer2}
-@* See: @url{http://www.ethernut.de}, or @url{http://www.ethernut.de/en/hardware/turtelizer/index.html}
+@* See:
+@uref{http://www.ethernut.de/en/hardware/turtelizer/index.html, Turtelizer 2}, or
+@url{http://www.ethernut.de}
@item @b{comstick}
@* Link: @url{http://www.hitex.com/index.php?id=383}
@item @b{stm32stick}
@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
@item @b{Wiggler2}
-@* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
+@*@uref{http://www.ccac.rwth-aachen.de/@/~michaels/@/index.php/hardware/@/armjtag,
+Improved parallel-port wiggler-style JTAG adapter}
@item @b{Wiggler_ntrst_inverted}
@* Yet another variation - See the source code, src/jtag/parport.c
@* Unknown.
@item @b{Lattice}
-@* ispDownload from Lattice Semiconductor @url{http://www.latticesemi.com/lit/docs/devtools/dlcable.pdf}
+@* ispDownload from Lattice Semiconductor
+@url{http://www.latticesemi.com/lit/docs/@/devtools/dlcable.pdf}
@item @b{flashlink}
-@* From ST Microsystems, link:
-@url{http://www.st.com/stonline/products/literature/um/7889.pdf}
-Title: FlashLINK JTAG programing cable for PSD and uPSD
+@* From ST Microsystems;
+@uref{http://www.st.com/stonline/@/products/literature/um/7889.pdf,
+FlashLINK JTAG programing cable for PSD and uPSD}
@end itemize
OpenOCD will read each filename in sequence, for example:
@example
- openocd -f file1.cfg -f file2.cfg -f file2.cfg
+openocd -f file1.cfg -f file2.cfg -f file2.cfg
@end example
You can also intermix various commands with the ``-c'' command line
today, that said, perhaps some interfaces have only been used by the
sole developer who created it.
-@b{FIXME/NOTE:} We need to add support for a variable like Tcl variable
-tcl_platform(platform), it should be called jim_platform (because it
-is jim, not real tcl) and it should contain 1 of 3 words: ``linux'',
-``cygwin'' or ``mingw''
-
Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface}
@section Board Config Files
problems in OpenOCD configurations.
@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
+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
@example
# for an ARM7TDMI.
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
+jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf \
+ -expected-id $_CPUTAPID
@end example
@b{COMPLEX example:}
@} else @{
set _FLASHTAPID 0x25966041
@}
-jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 -expected-id $_FLASHTAPID
+jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 \
+ -expected-id $_FLASHTAPID
if @{ [info exists CPUTAPID ] @} @{
set _CPUTAPID $CPUTAPID
@} else @{
set _CPUTAPID 0x25966041
@}
-jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe -expected-id $_CPUTAPID
+jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe \
+ -expected-id $_CPUTAPID
if @{ [info exists BSTAPID ] @} @{
@} else @{
set _BSTAPID 0x1457f041
@}
-jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 -expected-id $_BSTAPID
+jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 \
+ -expected-id $_BSTAPID
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
@end example
@* See: @xref{Tcl Crash Course}.
@end itemize
-
@node Daemon Configuration
@chapter Daemon Configuration
@cindex initialization
reset halt
@}
mychip.cpu configure -event gdb-attach my_attach_proc
- mychip.cpu configure -event gdb-attach @{ puts "Reset..." ; reset halt @}
+ mychip.cpu configure -event gdb-attach @{
+ puts "Reset..."
+ reset halt
+ @}
@end example
@section Current Events
@section Target Variants
@itemize @bullet
-@item @b{arm7tdmi}
-@* Unknown (please write me)
-@item @b{arm720t}
-@* Unknown (please write me) (similar to arm7tdmi)
-@item @b{arm9tdmi}
-@* Variants: @option{arm920t}, @option{arm922t} and @option{arm940t}
-This enables the hardware single-stepping support found on these
-cores.
-@item @b{arm920t}
-@* None.
-@item @b{arm966e}
-@* None (this is also used as the ARM946)
@item @b{cortex_m3}
-@* use variant <@var{-variant lm3s}> when debugging Luminary lm3s targets. This will cause
-OpenOCD to use a software reset rather than asserting SRST to avoid a issue with clearing
-the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest, these revisions will
+@* Use variant @option{lm3s} when debugging older Stellaris LM3S targets.
+This will cause OpenOCD to use a software reset rather than asserting
+SRST, to avoid a issue with clearing the debug registers.
+This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will
be detected and the normal reset behaviour used.
@item @b{xscale}
-@* Supported variants are @option{ixp42x}, @option{ixp45x}, @option{ixp46x},@option{pxa250}, @option{pxa255}, @option{pxa26x}.
-@item @b{arm11}
-@* Supported variants are @option{arm1136}, @option{arm1156}, @option{arm1176}
+@*Supported variants are
+@option{ixp42x}, @option{ixp45x}, @option{ixp46x},
+@option{pxa250}, @option{pxa255}, @option{pxa26x}.
@item @b{mips_m4k}
@* Use variant @option{ejtag_srst} when debugging targets that do not
provide a functional SRST line on the EJTAG connector. This causes
@*Enable (@var{on}) or disable (@var{off}) protection of flash sectors <@var{first}> to
<@var{last}> of @option{flash bank} <@var{num}>.
-@subsection mFlash commands
-@cindex mFlash commands
+@section flash bank command
+The @command{flash bank} command is used to configure one or more flash
+chips (or @emph{banks} in OpenOCD terms).
+Most CPUs have the ablity to ``boot'' from the first flash bank.
+
+@quotation Note
+This command is not available after OpenOCD initialization has completed.
+Use it in board specific configuration files, not interactively.
+@end quotation
+
+@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 @b{mflash probe}
-@cindex mflash probe
-@*Probe mflash.
-@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
-@cindex mflash write
-@*Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
-<@var{offset}> bytes from the beginning of the bank.
-@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
-@cindex mflash dump
-@*Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
-to a <@var{file}>.
-@item @b{mflash config pll} <@var{frequency}>
-@cindex mflash config pll
-@*Configure mflash pll. <@var{frequency}> is input frequency of mflash. The order is Hz.
-Issuing this command will erase mflash's whole internal nand and write new pll.
-After this command, mflash needs power-on-reset for normal operation.
-If pll was newly configured, storage and boot(optional) info also need to be update.
-@item @b{mflash config boot}
-@cindex mflash config boot
-@*Configure bootable option. If bootable option is set, mflash offer the first 8 sectors
-(4kB) for boot.
-@item @b{mflash config storage}
-@cindex mflash config storage
-@*Configure storage information. For the normal storage operation, this information must be
-written.
+@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
+@end deffn
-@section flash bank command
-The @b{flash bank} command is used to configure one or more flash chips (or banks in OpenOCD terms)
-
-@example
-@b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
-<@var{bus_width}> <@var{target}> [@var{driver_options ...}]
-@end example
-@cindex flash bank
-@*Configures a flash bank at <@var{base}> of <@var{size}> bytes and <@var{chip_width}>
-and <@var{bus_width}> bytes using the selected flash <driver>.
-
-@subsection External Flash - cfi options
-@cindex cfi options
-CFI flashes are external flash chips - often they are connected to a
-specific chip select on the CPU. By default, at hard reset, most
-CPUs have the ablity to ``boot'' from some flash chip - typically
-attached to the CPU's CS0 pin.
-
-For other chip selects: OpenOCD does not know how to configure, or
-access a specific chip select. Instead you, the human, might need to
-configure additional chip selects via other commands (like: mww) , or
+@section Flash Drivers, Options, and Commands
+@anchor{Flash Driver List}
+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.
-@b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
-<@var{target}> [@var{jedec_probe}|@var{x16_as_x8}]
-@*CFI flashes require the name or number of the target they're connected to
-as an additional
-argument. The CFI driver makes use of a working area (specified for the target)
-to significantly speed up operation.
+The CFI driver can accept the following optional parameters, in any order:
-@var{chip_width} and @var{bus_width} are specified in bytes.
+@itemize
+@item @var{jedec_probe} ... is used to detect certain non-CFI flash ROMs,
+like AM29LV010 and similar types.
+@item @var{x16_as_x8} ...
+@end itemize
-The @var{jedec_probe} option is used to detect certain non-CFI flash ROMs, like AM29LV010 and similar types.
+To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes)
+wide on a sixteen bit bus:
-@var{x16_as_x8} ???
+@example
+flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
+flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
+@end example
+@end deffn
@subsection Internal Flash (Microcontrollers)
-@subsubsection lpc2000 options
-@cindex lpc2000 options
-@b{flash bank lpc2000} <@var{base}> <@var{size}> 0 0 <@var{target}> <@var{variant}>
-<@var{clock}> [@var{calc_checksum}]
-@*LPC flashes don't require the chip and bus width to be specified. Additional
-parameters are the <@var{variant}>, which may be @var{lpc2000_v1} (older LPC21xx and LPC22xx)
-or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx),
-the name or number of the target this flash belongs to (first is 0),
-the frequency at which the core
-is currently running (in kHz - must be an integral number), and the optional keyword
-@var{calc_checksum}, telling the driver to calculate a valid checksum for the exception
-vector table.
+@deffn {Flash Driver} aduc702x
+The ADUC702x analog microcontrollers from ST Micro
+include internal flash and use ARM7TDMI cores.
+The aduc702x flash driver works with models ADUC7019 through ADUC7028.
+The setup command only requires the @var{target} argument
+since all devices in this family have the same memory layout.
+
+@example
+flash bank aduc702x 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
+
+@deffn {Flash Driver} at91sam7
+All members of the AT91SAM7 microcontroller family from Atmel
+include internal flash and use ARM7TDMI cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+@example
+flash bank at91sam7 0 0 0 0 $_TARGETNAME
+@end example
-@subsubsection at91sam7 options
-@cindex at91sam7 options
+For chips which are not recognized by the controller driver, you must
+provide additional parameters in the following order:
-@b{flash bank at91sam7} 0 0 0 0 <@var{target}>
-@*AT91SAM7 flashes only require the @var{target}, all other values are looked up after
-reading the chip-id and type.
+@itemize
+@item @var{chip_model} ... label used with @command{flash info}
+@item @var{banks}
+@item @var{sectors_per_bank}
+@item @var{pages_per_sector}
+@item @var{pages_size}
+@item @var{num_nvm_bits}
+@item @var{freq_khz} ... required if an external clock is provided,
+optional (but recommended) when the oscillator frequency is known
+@end itemize
-@subsubsection str7 options
-@cindex str7 options
+It is recommended that you provide zeroes for all of those values
+except the clock frequency, so that everything except that frequency
+will be autoconfigured.
+Knowing the frequency helps ensure correct timings for flash access.
+
+The flash controller handles erases automatically on a page (128/256 byte)
+basis, so explicit erase commands are not necessary for flash programming.
+However, there is an ``EraseAll`` command that can erase an entire flash
+plane (of up to 256KB), and it will be used automatically when you issue
+@command{flash erase_sector} or @command{flash erase_address} commands.
+
+@deffn Command {at91sam7 gpnvm} bitnum (set|clear)
+Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+bit for the processor. Each processor has a number of such bits,
+used for controlling features such as brownout detection (so they
+are not truly general purpose).
+@quotation Note
+This assumes that the first flash bank (number 0) is associated with
+the appropriate at91sam7 target.
+@end quotation
+@end deffn
+@end deffn
+
+@deffn {Flash Driver} lpc2000
+Most members of the LPC2000 microcontroller family from NXP
+include internal flash and use ARM7TDMI cores.
+The @var{lpc2000} driver defines two mandatory and one optional parameters,
+which must appear in the following order:
-@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target}> <@var{variant}>
-@*variant can be either STR71x, STR73x or STR75x.
+@itemize
+@item @var{variant} ... required, may be
+@var{lpc2000_v1} (older LPC21xx and LPC22xx)
+or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx)
+@item @var{clock_kHz} ... the frequency, in kiloHertz,
+at which the core is running
+@item @var{calc_checksum} ... optional (but you probably want to provide this!),
+telling the driver to calculate a valid checksum for the exception vector table.
+@end itemize
-@subsubsection str9 options
-@cindex str9 options
+LPC flashes don't require the chip and bus width to be specified.
-@b{flash bank str9x} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*The str9 needs the flash controller to be configured prior to Flash programming, e.g.
@example
-str9x flash_config 0 4 2 0 0x80000
+flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
+ lpc2000_v2 14765 calc_checksum
@end example
-This will setup the BBSR, NBBSR, BBADR and NBBADR registers respectively.
+@end deffn
-@subsubsection str9 options (str9xpec driver)
+@deffn {Flash Driver} stellaris
+All members of the Stellaris LM3Sxxx microcontroller family from
+Texas Instruments
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
+@footnote{Currently there is a @command{stellaris mass_erase} command.
+That seems pointless since the same effect can be had using the
+standard @command{flash erase_address} command.}
-@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Before using the flash commands the turbo mode must be enabled using str9xpec
-@option{enable_turbo} <@var{num>.}
+@example
+flash bank stellaris 0 0 0 0 $_TARGETNAME
+@end example
+@end deffn
-Only use this driver for locking/unlocking the device or configuring the option bytes.
-Use the standard str9 driver for programming. @xref{STR9 specific commands}.
+@deffn {Flash Driver} stm32x
+All members of the STM32 microcontroller family from ST Microelectronics
+include internal flash and use ARM Cortex M3 cores.
+The driver automatically recognizes a number of these chips using
+the chip identification register, and autoconfigures itself.
-@subsubsection Stellaris (LM3Sxxx) options
-@cindex Stellaris (LM3Sxxx) options
+@example
+flash bank stm32x 0 0 0 0 $_TARGETNAME
+@end example
-@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*Stellaris flash plugin only require the @var{target}.
+Some stm32x-specific commands
+@footnote{Currently there is a @command{stm32x mass_erase} command.
+That seems pointless since the same effect can be had using the
+standard @command{flash erase_address} command.}
+are defined:
-@subsubsection stm32x options
-@cindex stm32x options
+@deffn Command {stm32x lock} num
+Locks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
-@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target}>
-@*stm32x flash plugin only require the @var{target}.
+@deffn Command {stm32x unlock} num
+Unlocks the entire stm32 device.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
-@subsubsection aduc702x options
-@cindex aduc702x options
+@deffn Command {stm32x options_read} num
+Read and display the stm32 option bytes written by
+the @command{stm32x options_write} command.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
-@b{flash bank aduc702x} 0 0 0 0 <@var{target}>
-@*The aduc702x flash plugin works with Analog Devices model numbers ADUC7019 through ADUC7028. The setup command only requires the @var{target} argument (all devices in this family have the same memory layout).
+@deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
+Writes the stm32 option byte with the specified values.
+The @var{num} parameter is a value shown by @command{flash banks}.
+@end deffn
+@end deffn
-@subsection mFlash Configuration
-@cindex mFlash Configuration
-@b{mflash bank} <@var{soc}> <@var{base}> <@var{RST pin}> <@var{target}>
-@cindex mflash bank
-@*Configures a mflash for <@var{soc}> host bank at
-<@var{base}>. Pin number format is dependent on host GPIO calling convention.
-Currently, mflash bank support s3c2440 and pxa270.
+@deffn {Flash Driver} str7x
+All members of the STR7 microcontroller family from ST Microelectronics
+include internal flash and use ARM7TDMI cores.
+The @var{str7x} driver defines one mandatory parameter, @var{variant},
+which is either @code{STR71x}, @code{STR73x} or @code{STR75x}.
-(ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1.
@example
-mflash bank s3c2440 0x10000000 1b 0
+flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
@end example
-(ex. of pxa270) mflash <@var{RST pin}> is GPIO 43.
+@end deffn
+
+@deffn {Flash Driver} str9x
+Most members of the STR9 microcontroller family from ST Microelectronics
+include internal flash and use ARM966E cores.
+The str9 needs the flash controller to be configured using
+the @command{str9x flash_config} command prior to Flash programming.
+
@example
-mflash bank pxa270 0x08000000 43 0
+flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
+str9x flash_config 0 4 2 0 0x80000
@end example
-@section Microcontroller specific Flash Commands
+@deffn Command {str9x flash_config} num bbsr nbbsr bbadr nbbadr
+Configures the str9 flash controller.
+The @var{num} parameter is a value shown by @command{flash banks}.
-@subsection AT91SAM7 specific commands
-@cindex AT91SAM7 specific commands
-The flash configuration is deduced from the chip identification register. The flash
-controller handles erases automatically on a page (128/265 byte) basis, so erase is
-not necessary for flash programming. AT91SAM7 processors with less than 512K flash
-only have a single flash bank embedded on chip. AT91SAM7xx512 have two flash planes
-that can be erased separatly. Only an EraseAll command is supported by the controller
-for each flash plane and this is called with
@itemize @bullet
-@item @b{flash erase} <@var{num}> @var{first_plane} @var{last_plane}
-@*bulk erase flash planes first_plane to last_plane.
-@item @b{at91sam7 gpnvm} <@var{num}> <@var{bit}> <@option{set}|@option{clear}>
-@cindex at91sam7 gpnvm
-@*set or clear a gpnvm bit for the processor
+@item @var{bbsr} - Boot Bank Size register
+@item @var{nbbsr} - Non Boot Bank Size register
+@item @var{bbadr} - Boot Bank Start Address register
+@item @var{nbbadr} - Boot Bank Start Address register
@end itemize
+@end deffn
-@subsection STR9 specific commands
-@cindex STR9 specific commands
-@anchor{STR9 specific commands}
-These are flash specific commands when using the str9xpec driver.
-@itemize @bullet
-@item @b{str9xpec enable_turbo} <@var{num}>
-@cindex str9xpec enable_turbo
-@*enable turbo mode, will simply remove the str9 from the chain and talk
-directly to the embedded flash controller.
-@item @b{str9xpec disable_turbo} <@var{num}>
-@cindex str9xpec disable_turbo
-@*restore the str9 into JTAG chain.
-@item @b{str9xpec lock} <@var{num}>
-@cindex str9xpec lock
-@*lock str9 device. The str9 will only respond to an unlock command that will
-erase the device.
-@item @b{str9xpec unlock} <@var{num}>
-@cindex str9xpec unlock
-@*unlock str9 device.
-@item @b{str9xpec options_read} <@var{num}>
-@cindex str9xpec options_read
-@*read str9 option bytes.
-@item @b{str9xpec options_write} <@var{num}>
-@cindex str9xpec options_write
-@*write str9 option bytes.
-@end itemize
+@end deffn
+
+@subsection str9xpec driver
+@cindex str9xpec
-Note: Before using the str9xpec driver here is some background info to help
-you better understand how the drivers works. OpenOCD has two flash drivers for
-the str9.
+Here is some background info to help
+you better understand how this driver works. OpenOCD has two flash drivers for
+the str9:
@enumerate
@item
Standard driver @option{str9x} programmed via the str9 core. Normally used for
has been locked. Halting the core is not required for the @option{str9xpec} driver
as mentioned above, just issue the commands above manually or from a telnet prompt.
-@subsection STR9 configuration
-@cindex STR9 configuration
+@subsubsection str9xpec driver options
+
+@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
+@*Before using the flash commands the turbo mode must be enabled using str9xpec
+@option{enable_turbo} <@var{num>.}
+
+Only use this driver for locking/unlocking the device or configuring the option bytes.
+Use the standard str9 driver for programming.
+
+@subsubsection str9xpec specific commands
+@cindex str9xpec specific commands
+These are flash specific commands when using the str9xpec driver.
+
@itemize @bullet
-@item @b{str9x flash_config} <@var{bank}> <@var{BBSR}> <@var{NBBSR}>
-<@var{BBADR}> <@var{NBBADR}>
-@cindex str9x flash_config
-@*Configure str9 flash controller.
-@example
-e.g. str9x flash_config 0 4 2 0 0x80000
-This will setup
-BBSR - Boot Bank Size register
-NBBSR - Non Boot Bank Size register
-BBADR - Boot Bank Start Address register
-NBBADR - Boot Bank Start Address register
-@end example
+@item @b{str9xpec enable_turbo} <@var{num}>
+@cindex str9xpec enable_turbo
+@*enable turbo mode, will simply remove the str9 from the chain and talk
+directly to the embedded flash controller.
+@item @b{str9xpec disable_turbo} <@var{num}>
+@cindex str9xpec disable_turbo
+@*restore the str9 into JTAG chain.
+@item @b{str9xpec lock} <@var{num}>
+@cindex str9xpec lock
+@*lock str9 device. The str9 will only respond to an unlock command that will
+erase the device.
+@item @b{str9xpec unlock} <@var{num}>
+@cindex str9xpec unlock
+@*unlock str9 device.
+@item @b{str9xpec options_read} <@var{num}>
+@cindex str9xpec options_read
+@*read str9 option bytes.
+@item @b{str9xpec options_write} <@var{num}>
+@cindex str9xpec options_write
+@*write str9 option bytes.
@end itemize
-@subsection STR9 option byte configuration
+@subsubsection STR9 option byte configuration
@cindex STR9 option byte configuration
+
@itemize @bullet
@item @b{str9xpec options_cmap} <@var{num}> <@option{bank0}|@option{bank1}>
@cindex str9xpec options_cmap
@*configure str9 lvd reset warning source.
@end itemize
-@subsection STM32x specific commands
-@cindex STM32x specific commands
-
-These are flash specific commands when using the stm32x driver.
-@itemize @bullet
-@item @b{stm32x lock} <@var{num}>
-@cindex stm32x lock
-@*lock stm32 device.
-@item @b{stm32x unlock} <@var{num}>
-@cindex stm32x unlock
-@*unlock stm32 device.
-@item @b{stm32x options_read} <@var{num}>
-@cindex stm32x options_read
-@*read stm32 option bytes.
-@item @b{stm32x options_write} <@var{num}> <@option{SWWDG}|@option{HWWDG}>
-<@option{RSTSTNDBY}|@option{NORSTSTNDBY}> <@option{RSTSTOP}|@option{NORSTSTOP}>
-@cindex stm32x options_write
-@*write stm32 option bytes.
-@item @b{stm32x mass_erase} <@var{num}>
-@cindex stm32x mass_erase
-@*mass erase flash memory.
-@end itemize
+@section mFlash
+
+@subsection mFlash Configuration
+@cindex mFlash Configuration
+@b{mflash bank} <@var{soc}> <@var{base}> <@var{RST pin}> <@var{target}>
+@cindex mflash bank
+@*Configures a mflash for <@var{soc}> host bank at
+<@var{base}>. Pin number format is dependent on host GPIO calling convention.
+Currently, mflash bank support s3c2440 and pxa270.
+
+(ex. of s3c2440) mflash <@var{RST pin}> is GPIO B1.
+
+@example
+mflash bank s3c2440 0x10000000 1b 0
+@end example
+
+(ex. of pxa270) mflash <@var{RST pin}> is GPIO 43.
+
+@example
+mflash bank pxa270 0x08000000 43 0
+@end example
+
+@subsection mFlash commands
+@cindex mFlash commands
-@subsection Stellaris specific commands
-@cindex Stellaris specific commands
-
-These are flash specific commands when using the Stellaris driver.
@itemize @bullet
-@item @b{stellaris mass_erase} <@var{num}>
-@cindex stellaris mass_erase
-@*mass erase flash memory.
+@item @b{mflash probe}
+@cindex mflash probe
+@*Probe mflash.
+@item @b{mflash write} <@var{num}> <@var{file}> <@var{offset}>
+@cindex mflash write
+@*Write the binary <@var{file}> to mflash bank <@var{num}>, starting at
+<@var{offset}> bytes from the beginning of the bank.
+@item @b{mflash dump} <@var{num}> <@var{file}> <@var{offset}> <@var{size}>
+@cindex mflash dump
+@*Dump <size> bytes, starting at <@var{offset}> bytes from the beginning of the <@var{num}> bank
+to a <@var{file}>.
+@item @b{mflash config pll} <@var{frequency}>
+@cindex mflash config pll
+@*Configure mflash pll. <@var{frequency}> is input frequency of mflash. The order is Hz.
+Issuing this command will erase mflash's whole internal nand and write new pll.
+After this command, mflash needs power-on-reset for normal operation.
+If pll was newly configured, storage and boot(optional) info also need to be update.
+@item @b{mflash config boot}
+@cindex mflash config boot
+@*Configure bootable option. If bootable option is set, mflash offer the first 8 sectors
+(4kB) for boot.
+@item @b{mflash config storage}
+@cindex mflash config storage
+@*Configure storage information. For the normal storage operation, this information must be
+written.
@end itemize
@node NAND Flash Commands
configuration files, not interactively.
@itemize @bullet
-@item @var{controller} ... identifies a the controller driver
+@item @var{controller} ... identifies the controller driver
associated with the NAND device being declared.
@xref{NAND Driver List}.
@item @var{target} ... names the target used when issuing
@deffn Command {nand erase} num offset length
@cindex NAND erasing
+@cindex NAND programming
Erases blocks on the specified NAND device, starting at the
specified @var{offset} and continuing for @var{length} bytes.
Both of those values must be exact multiples of the device's
@deffn Command {nand write} num filename offset [option...]
@cindex NAND writing
+@cindex NAND programming
Writes binary data from the file into the specified NAND device,
starting at the specified offset. Those pages should already
have been erased; you can't change zero bits to one bits.
with the wrong ECC data can cause them to be marked as bad.
@end deffn
-@section NAND Drivers; Driver-specific Options and Commands
+@section NAND Drivers, Options, and Commands
@anchor{NAND Driver List}
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
@deffn {NAND Driver} lpc3180
These controllers require an extra @command{nand device}
parameter: the clock rate used by the controller.
-@deffn Command {nand lpc3180 select} num [mlc|slc]
+@deffn Command {lpc3180 select} num [mlc|slc]
Configures use of the MLC or SLC controller mode.
MLC implies use of hardware ECC.
The @var{num} parameter is the value shown by @command{nand list}.
change any behavior.
@end deffn
-@deffn {NAND Driver} {s3c2410, s3c2412, s3c2440, s3c2443}
+@deffn {NAND Driver} s3c2410
+@deffnx {NAND Driver} s3c2412
+@deffnx {NAND Driver} s3c2440
+@deffnx {NAND Driver} s3c2443
These S3C24xx family controllers don't have any special
@command{nand device} options, and don't define any
specialized commands.
@cindex Target Specific Commands
-@page
@section Architecture Specific Commands
@cindex Architecture Specific Commands
The way this works on the ZY1000 is to prefix a filename by
"/tftp/ip/" and append the TFTP path on the TFTP
-server (tftpd). E.g. "load_image /tftp/10.0.0.96/c:\temp\abc.elf" will
-load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
+server (tftpd). For example,
+
+@example
+load_image /tftp/10.0.0.96/c:\temp\abc.elf
+@end example
+
+will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
if the file was hosted on the embedded host.
In order to achieve decent performance, you must choose a TFTP server
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
+openocd -f interface/parport.cfg -f target/at91r40008.cfg \
+ -c "init" -c "reset"
@end example
errors, which has since been fixed: look up 1836 in
@url{http://sourceware.org/cgi-bin/gnatsweb.pl?database=gdb}
-@*OpenOCD can communicate with GDB in two ways:
+OpenOCD can communicate with GDB in two ways:
+
@enumerate
@item
A socket (TCP/IP) connection is typically started as follows:
session.
@end enumerate
-@*To see a list of available OpenOCD commands type @option{monitor help} on the
+To list the available OpenOCD commands type @command{monitor help} on the
GDB command line.
OpenOCD supports the gdb @option{qSupported} packet, this enables information
By low-level, the intent is a human would not directly use these commands.
-Low-level commands are (should be) prefixed with "openocd_", e.g. openocd_flash_banks
-is the low level API upon which "flash banks" is implemented.
+Low-level commands are (should be) prefixed with "ocd_", e.g.
+@command{ocd_flash_banks}
+is the low level API upon which @command{flash banks} is implemented.
@itemize @bullet
@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
Note: 'winxx' was choosen because today (March-2009) no distinction is made between Win32 and Win64.
+@quotation Note
+We should add support for a variable like Tcl variable
+@code{tcl_platform(platform)}, it should be called
+@code{jim_platform} (because it
+is jim, not real tcl).
+@end quotation
+
@node Upgrading
@chapter Deprecated/Removed Commands
@cindex Deprecated/Removed Commands
@itemize @bullet
@item @b{arm7_9 fast_writes}
@cindex arm7_9 fast_writes
-@*use @option{arm7_9 fast_memory_access} command with same args. @xref{arm7_9 fast_memory_access}.
+@*Use @command{arm7_9 fast_memory_access} instead.
+@xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
@cindex arm7_9 force_hw_bkpts
@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
is set to 10kHz for reset and 8MHz for post reset.
@example
-openocd -f interface/parport.cfg -f target/str710.cfg -c "init" -c "reset"
+openocd -f interface/parport.cfg -f target/str710.cfg \
+ -c "init" -c "reset"
@end example
To list the target scripts available:
@printindex cp
-@node OpenOCD Command Index
-@unnumbered OpenOCD Command Index
+@node Command and Driver Index
+@unnumbered Command and Driver Index
@printindex fn
@bye
Code Review / openocd.git / blobdiff