@menu
* About:: About OpenOCD
* Developers:: OpenOCD Developers
-* Building:: Building OpenOCD
+* Building OpenOCD:: Building OpenOCD From SVN
* JTAG Hardware Dongles:: JTAG Hardware Dongles
* Running:: Running OpenOCD
* Simple Configuration Files:: Simple Configuration Files
* Tap Creation:: Tap Creation
* Target Configuration:: Target Configuration
* Flash Configuration:: Flash Configuration
+* NAND Flash Commands:: NAND Flash Commands
* General Commands:: General Commands
* JTAG Commands:: JTAG Commands
* Sample Scripts:: Sample Target Scripts
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
-* OpenOCD Index:: Main Index
+* OpenOCD Concept Index:: Concept Index
+* OpenOCD Command Index:: Command Index
@end menu
@node About
@unnumbered About
@cindex about
+OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
+University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
+Since that time, the project has grown into an active open-source project,
+supported by a diverse community of software and hardware developers from
+around the world.
+
+@section What is OpenOCD?
+
The Open On-Chip Debugger (OpenOCD) aims to provide debugging,
in-system programming and boundary-scan testing for embedded target
devices.
@b{Dongles:} OpenOCD currently supports many types of hardware dongles: USB
based, parallel port based, and other standalone boxes that run
-OpenOCD internally. See the section titled: @xref{JTAG Hardware Dongles}.
+OpenOCD internally. @xref{JTAG Hardware Dongles}.
@b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and
debugged via the GDB protocol.
@b{Flash Programing:} Flash writing is supported for external CFI
-compatible flashes (Intel and AMD/Spansion command set) and several
+compatible NOR flashes (Intel and AMD/Spansion command set) and several
internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and
-STM32x). Preliminary support for using the LPC3180's NAND flash
-controller is included.
+STM32x). Preliminary support for various NAND flash controllers
+(LPC3180, Orion, S3C24xx, more) controller is included.
+
+@section OpenOCD Web Site
+
+The OpenOCD web site provides the latest public news from the community:
+
+@uref{http://openocd.berlios.de/web/}
+
@node Developers
-@chapter Developers
+@chapter OpenOCD Developer Resources
@cindex developers
-OpenOCD was created by Dominic Rath as part of a diploma thesis written at the
-University of Applied Sciences Augsburg (@uref{http://www.fh-augsburg.de}).
-Others interested in improving the state of free and open debug and testing technology
-are welcome to participate.
+If you are interested in improving the state of OpenOCD's debugging and
+testing support, new contributions will be welcome. Motivated developers
+can produce new target, flash or interface drivers, improve the
+documentation, as well as more conventional bug fixes and enhancements.
-Other developers have contributed support for additional targets and flashes as well
-as numerous bugfixes and enhancements. See the AUTHORS file for regular contributors.
+The resources in this chapter are available for developers wishing to explore
+or expand the OpenOCD source code.
-The main OpenOCD web site is available at @uref{http://openocd.berlios.de/web/}.
+@section OpenOCD Subversion Repository
-@section Coding Style
-@cindex Coding Style
+The ``Building From Source'' section provides instructions to retrieve
+and and build the latest version of the OpenOCD source code.
+@xref{Building OpenOCD}.
-The following rules try to describe formatting and naming conventions that should be
-followed to make the whole OpenOCD code look more consistent. The ultimate goal of
-coding style should be readability, and these rules may be ignored for a particular
-(small) piece of code if that makes it more readable.
+Developers that want to contribute patches to the OpenOCD system are
+@b{strongly} encouraged to base their work off of the most recent trunk
+revision. Patches created against older versions may require additional
+work from their submitter in order to be updated for newer releases.
-@subsection Formatting rules:
-@itemize @bullet
-@item remove any trailing white space
-@item use TAB characters for indentation, not spaces
-@item displayed TAB width is 4 characters
-@item make sure NOT to use DOS '\r\n' line feeds
-@item do not add more than 2 empty lines to source files
-@item do not add trailing empty lines to source files
-@item do not use C++ style comments (//)
-@item lines may be reasonably wide - there's no anachronistic 80 characters limit
-@end itemize
+@section Doxygen Developer Manual
-@subsection Naming rules:
-@itemize @bullet
-@item identifiers use lower-case letters only
-@item identifiers consisting of multiple words use underline characters between consecutive words
-@item macros use upper-case letters only
-@item structure names shall be appended with '_s'
-@item typedefs shall be appended with '_t'
-@end itemize
+During the development of the 0.2.0 release, the OpenOCD project began
+providing a Doxygen reference manual. This document contains more
+technical information about the software internals, development
+processes, and similar documentation:
-@subsection Function calls:
-@itemize @bullet
-@item function calls have no space between the functions name and the parameter
-list: my_func(param1, param2, ...)
-@end itemize
+@uref{http://openocd.berlios.de/doc/doxygen/index.html}
+
+This document is a work-in-progress, but contributions would be welcome
+to fill in the gaps. All of the source files are provided in-tree,
+listed in the Doxyfile configuration in the top of the repository trunk.
+
+@section OpenOCD Developer Mailing List
-@node Building
-@chapter Building
-@cindex building OpenOCD
+The OpenOCD Developer Mailing List provides the primary means of
+communication between developers:
+
+ @uref{https://lists.berlios.de/mailman/listinfo/openocd-development}
+
+All drivers developers are enouraged to also subscribe to the list of
+SVN commits to keep pace with the ongoing changes:
+
+ @uref{https://lists.berlios.de/mailman/listinfo/openocd-svn}
+
+@node Building OpenOCD
+@chapter Building OpenOCD
+@cindex building
@section Pre-Built Tools
If you are interested in getting actual work done rather than building
@item @b{Build packages} i.e.: RPM files, or DEB files for a Linux Distro
@end enumerate
-As a @b{PACKAGER} - you are at the top of the food chain. You solve
-problems for downstream users. What you fix or solve - solves hundreds
-if not thousands of user questions. If something does not work for you
-please let us know. That said, would also like you to follow a few
+As a @b{PACKAGER}, you will experience first reports of most issues.
+When you fix those problems for your users, your solution may help
+prevent hundreds (if not thousands) of other questions from other users.
+
+If something does not work for you, please work to inform the OpenOCD
+developers know how to improve the system or documentation to avoid
+future problems, and follow-up to help us ensure the issue will be fully
+resolved in our future releases.
+
+That said, the OpenOCD developers would also like you to follow a few
suggestions:
@enumerate
@example
source [find interface/signalyzer.cfg]
-# Change the default telnet port...
-telnet_port 4444
-# GDB connects here
-gdb_port 3333
# GDB can also flash my flash!
gdb_memory_map enable
gdb_flash_program enable
In summary the board files should contain (if present)
@enumerate
-@item External flash configuration (i.e.: the flash on CS0)
+@item External flash configuration (i.e.: NOR flash on CS0, two NANDs on CS2)
@item SDRAM configuration (size, speed, etc.
@item Board specific IO configuration (i.e.: GPIO pins might disable a 2nd flash)
@item Multiple TARGET source statements
This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
@b{Never ever} in the ``target configuration file'' define any type of
-flash that is external to the chip. (For example the BOOT flash on
-Chip Select 0). The BOOT flash information goes in a board file - not
+flash that is external to the chip. (For example a BOOT flash on
+Chip Select 0.) Such flash information goes in a board file - not
the TARGET (chip) file.
Examples:
@node Daemon Configuration
@chapter Daemon Configuration
+@cindex initialization
The commands here are commonly found in the openocd.cfg file and are
used to specify what TCP/IP ports are used, and how GDB should be
supported.
-@section init
-@cindex init
+
+@section Configuration Stage
+@cindex configuration stage
+@cindex configuration command
+
+When the OpenOCD server process starts up, it enters a
+@emph{configuration stage} which is the only time that
+certain commands, @emph{configuration commands}, may be issued.
+Those configuration commands include declaration of TAPs
+and other basic setup.
+The server must leave the configuration stage before it
+may access or activate TAPs.
+After it leaves this stage, configuration commands may no
+longer be issued.
+
+@deffn {Config Command} init
This command terminates the configuration stage and
enters the normal command mode. This can be useful to add commands to
the startup scripts and commands such as resetting the target,
@b{NOTE:} This command normally occurs at or near the end of your
openocd.cfg file to force OpenOCD to ``initialize'' and make the
targets ready. For example: If your openocd.cfg file needs to
-read/write memory on your target - the init command must occur before
-the memory read/write commands.
+read/write memory on your target, @command{init} must occur before
+the memory read/write commands. This includes @command{nand probe}.
+@end deffn
@section TCP/IP Ports
-@itemize @bullet
-@item @b{telnet_port} <@var{number}>
-@cindex telnet_port
-@*Intended for a human. Port on which to listen for incoming telnet connections.
-
-@item @b{tcl_port} <@var{number}>
-@cindex tcl_port
-@*Intended as a machine interface. Port on which to listen for
-incoming Tcl syntax. This port is intended as a simplified RPC
-connection that can be used by clients to issue commands and get the
+@cindex TCP port
+@cindex server
+@cindex port
+The OpenOCD server accepts remote commands in several syntaxes.
+Each syntax uses a different TCP/IP port, which you may specify
+only during configuration (before those ports are opened).
+
+@deffn {Command} gdb_port (number)
+@cindex GDB server
+Specify or query the first port used for incoming GDB connections.
+The GDB port for the
+first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
+When not specified during the configuration stage,
+the port @var{number} defaults to 3333.
+@end deffn
+
+@deffn {Command} tcl_port (number)
+Specify or query the port used for a simplified RPC
+connection that can be used by clients to issue TCL commands and get the
output from the Tcl engine.
-
-@item @b{gdb_port} <@var{number}>
-@cindex gdb_port
-@*First port on which to listen for incoming GDB connections. The GDB port for the
-first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
-@end itemize
-
-@section GDB Items
-@itemize @bullet
-@item @b{gdb_breakpoint_override} <@var{hard|soft|disable}>
-@cindex gdb_breakpoint_override
+Intended as a machine interface.
+When not specified during the configuration stage,
+the port @var{number} defaults to 6666.
+@end deffn
+
+@deffn {Command} telnet_port (number)
+Specify or query the
+port on which to listen for incoming telnet connections.
+This port is intended for interaction with one human through TCL commands.
+When not specified during the configuration stage,
+the port @var{number} defaults to 4444.
+@end deffn
+
+@section GDB Configuration
+@anchor{GDB Configuration}
+@cindex GDB
+@cindex GDB configuration
+You can reconfigure some GDB behaviors if needed.
+The ones listed here are static and global.
+@xref{Target Create}, about declaring individual targets.
+@xref{Target Events}, about configuring target-specific event handling.
+
+@deffn {Command} gdb_breakpoint_override <hard|soft|disable>
@anchor{gdb_breakpoint_override}
-@*Force breakpoint type for gdb 'break' commands.
-The raison d'etre for this option is to support GDB GUI's without
-a hard/soft breakpoint concept where the default OpenOCD and
-GDB behaviour is not sufficient. Note that GDB will use hardware
+Force breakpoint type for gdb @command{break} commands.
+The raison d'etre for this option is to support GDB GUI's which don't
+distinguish hard versus soft breakpoints, if the default OpenOCD and
+GDB behaviour is not sufficient. GDB normally uses hardware
breakpoints if the memory map has been set up for flash regions.
This option replaces older arm7_9 target commands that addressed
the same issue.
+@end deffn
+
+@deffn {Config command} gdb_detach <resume|reset|halt|nothing>
+Configures what OpenOCD will do when GDB detaches from the daemon.
+Default behaviour is @var{resume}.
+@end deffn
-@item @b{gdb_detach} <@var{resume|reset|halt|nothing}>
-@cindex gdb_detach
-@*Configures what OpenOCD will do when GDB detaches from the daemon.
-Default behaviour is <@var{resume}>
+@deffn {Config command} gdb_flash_program <enable|disable>
+@anchor{gdb_flash_program}
+Set to @var{enable} to cause OpenOCD to program the flash memory when a
+vFlash packet is received.
+The default behaviour is @var{enable}.
+@end deffn
-@item @b{gdb_memory_map} <@var{enable|disable}>
-@cindex gdb_memory_map
-@*Set to <@var{enable}> to cause OpenOCD to send the memory configuration to GDB when
+@deffn {Config command} gdb_memory_map <enable|disable>
+Set to @var{enable} to cause OpenOCD to send the memory configuration to GDB when
requested. GDB will then know when to set hardware breakpoints, and program flash
-using the GDB load command. @option{gdb_flash_program enable} must also be enabled
+using the GDB load command. @command{gdb_flash_program enable} must also be enabled
for flash programming to work.
-Default behaviour is <@var{enable}>
+Default behaviour is @var{enable}.
@xref{gdb_flash_program}.
+@end deffn
-@item @b{gdb_flash_program} <@var{enable|disable}>
-@cindex gdb_flash_program
-@anchor{gdb_flash_program}
-@*Set to <@var{enable}> to cause OpenOCD to program the flash memory when a
-vFlash packet is received.
-Default behaviour is <@var{enable}>
-@comment END GDB Items
-@end itemize
+@deffn {Config command} gdb_report_data_abort <enable|disable>
+Specifies whether data aborts cause an error to be reported
+by GDB memory read packets.
+The default behaviour is @var{disable};
+use @var{enable} see these errors reported.
+@end deffn
@node Interface - Dongle Configuration
@chapter Interface - Dongle Configuration
Currently, there are no options available for the ep93xx interface.
@section JTAG Speed
-@itemize @bullet
-@item @b{jtag_khz} <@var{reset speed kHz}>
-@cindex jtag_khz
-
-It is debatable if this command belongs here - or in a board
-configuration file. In fact, in some situations the JTAG speed is
-changed during the target initialisation process (i.e.: (1) slow at
-reset, (2) program the CPU clocks, (3) run fast)
-
-Speed 0 (khz) selects RTCK method. A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
-
-Not all interfaces support ``rtck''. If the interface device can not
-support the rate asked for, or can not translate from kHz to
-jtag_speed, then an error is returned.
-
-Make sure the JTAG clock is no more than @math{1/6th CPU-Clock}. This is
-especially true for synthesized cores (-S). Also see RTCK.
-
-@b{NOTE: Script writers} If the target chip requires/uses RTCK -
-please use the command: 'jtag_rclk FREQ'. This Tcl proc (in
-startup.tcl) attempts to enable RTCK, if that fails it falls back to
-the specified frequency.
-
+@anchor{JTAG Speed}
+JTAG clock setup is part of system setup.
+It @emph{does not belong with interface setup} since any interface
+only knows a few of the constraints for the JTAG clock speed.
+Sometimes the JTAG speed is
+changed during the target initialization process: (1) slow at
+reset, (2) program the CPU clocks, (3) run fast.
+Both the "slow" and "fast" clock rates are functions of the
+oscillators used, the chip, the board design, and sometimes
+power management software that may be active.
+
+The speed used during reset can be adjusted using pre_reset
+and post_reset event handlers.
+@xref{Target Events}.
+
+If your system supports adaptive clocking (RTCK), configuring
+JTAG to use that is probably the most robust approach.
+However, it introduces delays to synchronize clocks; so it
+may not be the fastest solution.
+
+@b{NOTE:} Script writers should consider using @command{jtag_rclk}
+instead of @command{jtag_khz}.
+
+@deffn {Command} jtag_khz max_speed_kHz
+A non-zero speed is in KHZ. Hence: 3000 is 3mhz.
+JTAG interfaces usually support a limited number of
+speeds. The speed actually used won't be faster
+than the speed specified.
+
+As a rule of thumb, if you specify a clock rate make
+sure the JTAG clock is no more than @math{1/6th CPU-Clock}.
+This is especially true for synthesized cores (ARMxxx-S).
+
+Speed 0 (khz) selects RTCK method.
+@xref{FAQ RTCK}.
+If your system uses RTCK, you won't need to change the
+JTAG clocking after setup.
+Not all interfaces, boards, or targets support ``rtck''.
+If the interface device can not
+support it, an error is returned when you try to use RTCK.
+@end deffn
+
+@defun jtag_rclk fallback_speed_kHz
+@cindex RTCK
+This Tcl proc (defined in startup.tcl) attempts to enable RTCK/RCLK.
+If that fails (maybe the interface, board, or target doesn't
+support it), falls back to the specified frequency.
@example
- # Fall back to 3mhz if RCLK is not supported
- jtag_rclk 3000
+# Fall back to 3mhz if RTCK is not supported
+jtag_rclk 3000
@end example
-
-@item @b{DEPRECATED} @b{jtag_speed} - please use jtag_khz above.
-@cindex jtag_speed
-@*Limit the maximum speed of the JTAG interface. Usually, a value of zero means maximum
-speed. The actual effect of this option depends on the JTAG interface used.
-
-The speed used during reset can be adjusted using setting jtag_speed during
-pre_reset and post_reset events.
-@itemize @minus
-
-@item wiggler: maximum speed / @var{number}
-@item ft2232: 6MHz / (@var{number}+1)
-@item amt jtagaccel: 8 / 2**@var{number}
-@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
-@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
-@comment end speed list.
-@end itemize
-
-@comment END command list
-@end itemize
+@end defun
@node Reset Configuration
@chapter Reset Configuration
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 via JTAG
+@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.
@end itemize
@page
@node Target Configuration
@chapter Target 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.
@end itemize
@section Target Events
+@cindex events
+@anchor{Target Events}
At various times, certain things can happen, or you want them to happen.
Examples:
@item @b{reset-halt-pre}
@* Currently not used
@item @b{reset-init}
-@* Currently not used
+@* Used by @b{reset init} command for board-specific initialization.
+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}
@* Currently not used
@item @b{reset-wait-pos}
@end example
@end itemize
-@section target create
+@section Target Create
+@anchor{Target Create}
@cindex target
@cindex target creation
@chapter Flash programming
@cindex Flash Configuration
+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''.
+
@b{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.
flash on your board.
@item GDB Flashing
@* Flashing via GDB requires the flash be configured via ``flash
-bank'', and the GDB flash features be enabled. See the daemon
-configuration section for more details.
+bank'', and the GDB flash features be enabled.
+@xref{GDB Configuration}.
@end enumerate
@section Flash commands
@*mass erase flash memory.
@end itemize
+@node NAND Flash Commands
+@chapter NAND Flash Commands
+@cindex NAND
+
+Compared to NOR or SPI flash, NAND devices are inexpensive
+and high density. Today's NAND chips, and multi-chip modules,
+commonly hold multiple GigaBytes of data.
+
+NAND chips consist of a number of ``erase blocks'' of a given
+size (such as 128 KBytes), each of which is divided into a
+number of pages (of perhaps 512 or 2048 bytes each). Each
+page of a NAND flash has an ``out of band'' (OOB) area to hold
+Error Correcting Code (ECC) and other metadata, usually 16 bytes
+of OOB for every 512 bytes of page data.
+
+One key characteristic of NAND flash is that its error rate
+is higher than that of NOR flash. In normal operation, that
+ECC is used to correct and detect errors. However, NAND
+blocks can also wear out and become unusable; those blocks
+are then marked "bad". NAND chips are even shipped from the
+manufacturer with a few bad blocks. The highest density chips
+use a technology (MLC) that wears out more quickly, so ECC
+support is increasingly important as a way to detect blocks
+that have begun to fail, and help to preserve data integrity
+with techniques such as wear leveling.
+
+Software is used to manage the ECC. Some controllers don't
+support ECC directly; in those cases, software ECC is used.
+Other controllers speed up the ECC calculations with hardware.
+Single-bit error correction hardware is routine. Controllers
+geared for newer MLC chips may correct 4 or more errors for
+every 512 bytes of data.
+
+You will need to make sure that any data you write using
+OpenOCD includes the apppropriate kind of ECC. For example,
+that may mean passing the @code{oob_softecc} flag when
+writing NAND data, or ensuring that the correct hardware
+ECC mode is used.
+
+The basic steps for using NAND devices include:
+@enumerate
+@item Declare via the command @command{nand device}
+@* Do this in a board-specific configuration file,
+passing parameters as needed by the controller.
+@item Configure each device using @command{nand probe}.
+@* Do this only after the associated target is set up,
+such as in its reset-init script or in procures defined
+to access that device.
+@item Operate on the flash via @command{nand subcommand}
+@* Often commands to manipulate the flash are typed by a human, or run
+via a script in some automated way. Common task include writing a
+boot loader, operating system, or other data needed to initialize or
+de-brick a board.
+@end enumerate
+
+@b{NOTE:} At the time this text was written, the largest NAND
+flash fully supported by OpenOCD is 2 GiBytes (16 GiBits).
+This is because the variables used to hold offsets and lengths
+are only 32 bits wide.
+(Larger chips may work in some cases, unless an offset or length
+is larger than 0xffffffff, the largest 32-bit unsigned integer.)
+Some larger devices will work, since they are actually multi-chip
+modules with two smaller chips and individual chipselect lines.
+
+@section NAND Configuration Commands
+@cindex NAND configuration
+
+NAND chips must be declared in configuration scripts,
+plus some additional configuration that's done after
+OpenOCD has initialized.
+
+@deffn {Config Command} {nand device} controller target [configparams...]
+Declares a NAND device, which can be read and written to
+after it has been configured through @command{nand probe}.
+In OpenOCD, devices are single chips; this is unlike some
+operating systems, which may manage multiple chips as if
+they were a single (larger) device.
+In some cases, configuring a device will activate extra
+commands; see the controller-specific documentation.
+
+@b{NOTE:} This command is not available after OpenOCD
+initialization has completed. Use it in board specific
+configuration files, not interactively.
+
+@itemize @bullet
+@item @var{controller} ... identifies a the controller driver
+associated with the NAND device being declared.
+@xref{NAND Driver List}.
+@item @var{target} ... names the target used when issuing
+commands to the NAND controller.
+@comment Actually, it's currently a controller-specific parameter...
+@item @var{configparams} ... controllers may support, or require,
+additional parameters. See the controller-specific documentation
+for more information.
+@end itemize
+@end deffn
+
+@deffn Command {nand list}
+Prints a one-line summary of each device declared
+using @command{nand device}, numbered from zero.
+Note that un-probed devices show no details.
+@end deffn
+
+@deffn Command {nand probe} num
+Probes the specified device to determine key characteristics
+like its page and block sizes, and how many blocks it has.
+The @var{num} parameter is the value shown by @command{nand list}.
+You must (successfully) probe a device before you can use
+it with most other NAND commands.
+@end deffn
+
+@section Erasing, Reading, Writing to NAND Flash
+
+@deffn Command {nand dump} num filename offset length [oob_option]
+@cindex NAND reading
+Reads binary data from the NAND device and writes it to the file,
+starting at the specified offset.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} and @var{length} must be exact multiples of the
+device's page size. They describe a data region; the OOB data
+associated with each such page may also be accessed.
+
+@b{NOTE:} At the time this text was written, no error correction
+was done on the data that's read, unless raw access was disabled
+and the underlying NAND controller driver had a @code{read_page}
+method which handled that error correction.
+
+By default, only page data is saved to the specified file.
+Use an @var{oob_option} parameter to save OOB data:
+@itemize @bullet
+@item no oob_* parameter
+@*Output file holds only page data; OOB is discarded.
+@item @code{oob_raw}
+@*Output file interleaves page data and OOB data;
+the file will be longer than "length" by the size of the
+spare areas associated with each data page.
+Note that this kind of "raw" access is different from
+what's implied by @command{nand raw_access}, which just
+controls whether a hardware-aware access method is used.
+@item @code{oob_only}
+@*Output file has only raw OOB data, and will
+be smaller than "length" since it will contain only the
+spare areas associated with each data page.
+@end itemize
+@end deffn
+
+@deffn Command {nand erase} num offset length
+@cindex NAND erasing
+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
+block size, and the region they specify must fit entirely in the chip.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+@b{NOTE:} This command will try to erase bad blocks, when told
+to do so, which will probably invalidate the manufacturer's bad
+block marker.
+For the remainder of the current server session, @command{nand info}
+will still report that the block ``is'' bad.
+@end deffn
+
+@deffn Command {nand write} num filename offset [option...]
+@cindex NAND writing
+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.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+Use a complete path name for @var{filename}, so you don't depend
+on the directory used to start the OpenOCD server.
+
+The @var{offset} must be an exact multiple of the device's page size.
+All data in the file will be written, assuming it doesn't run
+past the end of the device.
+Only full pages are written, and any extra space in the last
+page will be filled with 0xff bytes. (That includes OOB data,
+if that's being written.)
+
+@b{NOTE:} At the time this text was written, bad blocks are
+ignored. That is, this routine will not skip bad blocks,
+but will instead try to write them. This can cause problems.
+
+Provide at most one @var{option} parameter. With some
+NAND drivers, the meanings of these parameters may change
+if @command{nand raw_access} was used to disable hardware ECC.
+@itemize @bullet
+@item no oob_* parameter
+@*File has only page data, which is written.
+If raw acccess is in use, the OOB area will not be written.
+Otherwise, if the underlying NAND controller driver has
+a @code{write_page} routine, that routine may write the OOB
+with hardware-computed ECC data.
+@item @code{oob_only}
+@*File has only raw OOB data, which is written to the OOB area.
+Each page's data area stays untouched. @i{This can be a dangerous
+option}, since it can invalidate the ECC data.
+You may need to force raw access to use this mode.
+@item @code{oob_raw}
+@*File interleaves data and OOB data, both of which are written
+If raw access is enabled, the data is written first, then the
+un-altered OOB.
+Otherwise, if the underlying NAND controller driver has
+a @code{write_page} routine, that routine may modify the OOB
+before it's written, to include hardware-computed ECC data.
+@item @code{oob_softecc}
+@*File has only page data, which is written.
+The OOB area is filled with 0xff, except for a standard 1-bit
+software ECC code stored in conventional locations.
+You might need to force raw access to use this mode, to prevent
+the underlying driver from applying hardware ECC.
+@item @code{oob_softecc_kw}
+@*File has only page data, which is written.
+The OOB area is filled with 0xff, except for a 4-bit software ECC
+specific to the boot ROM in Marvell Kirkwood SoCs.
+You might need to force raw access to use this mode, to prevent
+the underlying driver from applying hardware ECC.
+@end itemize
+@end deffn
+
+@section Other NAND commands
+@cindex NAND other commands
+
+@deffn Command {nand check_bad_blocks} [offset length]
+Checks for manufacturer bad block markers on the specified NAND
+device. If no parameters are provided, checks the whole
+device; otherwise, starts at the specified @var{offset} and
+continues for @var{length} bytes.
+Both of those values must be exact multiples of the device's
+block size, and the region they specify must fit entirely in the chip.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+@b{NOTE:} Before using this command you should force raw access
+with @command{nand raw_access enable} to ensure that the underlying
+driver will not try to apply hardware ECC.
+@end deffn
+
+@deffn Command {nand info} num
+The @var{num} parameter is the value shown by @command{nand list}.
+This prints the one-line summary from "nand list", plus for
+devices which have been probed this also prints any known
+status for each block.
+@end deffn
+
+@deffn Command {nand raw_access} num <enable|disable>
+Sets or clears an flag affecting how page I/O is done.
+The @var{num} parameter is the value shown by @command{nand list}.
+
+This flag is cleared (disabled) by default, but changing that
+value won't affect all NAND devices. The key factor is whether
+the underlying driver provides @code{read_page} or @code{write_page}
+methods. If it doesn't provide those methods, the setting of
+this flag is irrelevant; all access is effectively ``raw''.
+
+When those methods exist, they are normally used when reading
+data (@command{nand dump} or reading bad block markers) or
+writing it (@command{nand write}). However, enabling
+raw access (setting the flag) prevents use of those methods,
+bypassing hardware ECC logic.
+@i{This can be a dangerous option}, since writing blocks
+with the wrong ECC data can cause them to be marked as bad.
+@end deffn
+
+@section NAND Drivers; Driver-specific Options and Commands
+@anchor{NAND Driver List}
+As noted above, the @command{nand device} command allows
+driver-specific options and behaviors.
+Some controllers also activate controller-specific commands.
+
+@deffn {NAND Driver} davinci
+This driver handles the NAND controllers found on DaVinci family
+chips from Texas Instruments.
+It takes three extra parameters:
+address of the NAND chip;
+hardware ECC mode to use (hwecc1, hwecc4, hwecc4_infix);
+address of the AEMIF controller on this processor.
+@example
+nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
+@end example
+All DaVinci processors support the single-bit ECC hardware,
+and newer ones also support the four-bit ECC hardware.
+The @code{write_page} and @code{read_page} methods are used
+to implement those ECC modes, unless they are disabled using
+the @command{nand raw_access} command.
+@end deffn
+
+@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]
+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}.
+@end deffn
+
+At this writing, this driver includes @code{write_page}
+and @code{read_page} methods. Using @command{nand raw_access}
+to disable those methods will prevent use of hardware ECC
+in the MLC controller mode, but won't change SLC behavior.
+@end deffn
+@comment current lpc3180 code won't issue 5-byte address cycles
+
+@deffn {NAND Driver} orion
+These controllers require an extra @command{nand device}
+parameter: the address of the controller.
+@example
+nand device orion 0xd8000000
+@end example
+These controllers don't define any specialized commands.
+At this writing, their drivers don't include @code{write_page}
+or @code{read_page} methods, so @command{nand raw_access} won't
+change any behavior.
+@end deffn
+
+@deffn {NAND Driver} {s3c2410, s3c2412, s3c2440, s3c2443}
+These S3C24xx family controllers don't have any special
+@command{nand device} options, and don't define any
+specialized commands.
+At this writing, their drivers don't include @code{write_page}
+or @code{read_page} methods, so @command{nand raw_access} won't
+change any behavior.
+@end deffn
+
@node General Commands
@chapter General Commands
@cindex commands
or via one of several TCP/IP Ports.
@item @b{From the human}
-@* A human should interact with the telnet interface (default port: 4444,
-or via GDB, default port 3333)
+@* A human should interact with the telnet interface (default port: 4444)
+or via GDB (default port 3333).
To issue commands from within a GDB session, use the @option{monitor}
command, e.g. use @option{monitor poll} to issue the @option{poll}
openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
@end example
+@subsection echo <@var{message}>
+@cindex echo
+@*Output message to stdio. e.g. echo "Programming - please wait"
+
@subsection log_output <@var{file}>
@cindex log_output
@*Redirect logging to <file> (default: stderr)
@node GDB and OpenOCD
@chapter GDB and OpenOCD
-@cindex GDB and OpenOCD
+@cindex GDB
OpenOCD complies with the remote gdbserver protocol, and as such can be used
to debug remote targets.
Informing GDB of the memory map of the target will enable GDB to protect any
flash areas of the target and use hardware breakpoints by default. This means
-that the OpenOCD option @option{gdb_breakpoint_override} is not required when
+that the OpenOCD option @command{gdb_breakpoint_override} is not required when
using a memory map. @xref{gdb_breakpoint_override}.
To view the configured memory map in GDB, use the GDB command @option{info mem}
set mem inaccessible-by-default off
@end example
-If @option{gdb_flash_program enable} is also used, GDB will be able to
+If @command{gdb_flash_program enable} is also used, GDB will be able to
program any flash memory using the vFlash interface.
GDB will look at the target memory map when a load command is given, if any
@*use @option{arm7_9 fast_memory_access} command with same args. @xref{arm7_9 fast_memory_access}.
@item @b{arm7_9 force_hw_bkpts}
@cindex arm7_9 force_hw_bkpts
-@*Use @option{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
+@*Use @command{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
for flash if the GDB memory map has been set up(default when flash is declared in
target configuration). @xref{gdb_breakpoint_override}.
@item @b{arm7_9 sw_bkpts}
@cindex arm7_9 sw_bkpts
-@*On by default. See also @option{gdb_breakpoint_override}. @xref{gdb_breakpoint_override}.
+@*On by default. @xref{gdb_breakpoint_override}.
@item @b{daemon_startup}
@cindex daemon_startup
@*this config option has been removed, simply adding @option{init} and @option{reset halt} to
@item @b{flash auto_erase}
@cindex flash auto_erase
@*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
+
+@item @b{jtag_speed} value
+@*@xref{JTAG Speed}.
+Usually, a value of zero means maximum
+speed. The actual effect of this option depends on the JTAG interface used.
+@itemize @minus
+@item wiggler: maximum speed / @var{number}
+@item ft2232: 6MHz / (@var{number}+1)
+@item amt jtagaccel: 8 / 2**@var{number}
+@item jlink: maximum speed in kHz (0-12000), 0 will use RTCK
+@item rlink: 24MHz / @var{number}, but only for certain values of @var{number}
+@comment end speed list.
+@end itemize
+
@item @b{load_binary}
@cindex load_binary
@*use @option{load_image} command with same args. @xref{load_image}.
@cindex faq
@enumerate
@item @b{RTCK, also known as: Adaptive Clocking - What is it?}
+@anchor{FAQ RTCK}
@cindex RTCK
@cindex adaptive clocking
@*
You can use the ``scan_chain'' command to verify and display the tap order.
+Also, some commands can't execute until after @command{init} has been
+processed. Such commands include @command{nand probe} and everything
+else that needs to write to controller registers, perhaps for setting
+up DRAM and loading it with code.
+
@item @b{JTAG Tap Order} JTAG tap order - command order
Many newer devices have multiple JTAG taps. For example: ST
@include fdl.texi
-@node OpenOCD Index
+@node OpenOCD Concept Index
@comment DO NOT use the plain word ``Index'', reason: CYGWIN filename
@comment case issue with ``Index.html'' and ``index.html''
@comment Occurs when creating ``--html --no-split'' output
@comment This fix is based on: http://sourceware.org/ml/binutils/2006-05/msg00215.html
-@unnumbered OpenOCD Index
+@unnumbered OpenOCD Concept Index
@printindex cp
+@node OpenOCD Command Index
+@unnumbered OpenOCD Command Index
+@printindex fn
+
@bye
Code Review / openocd.git / blobdiff