@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
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:
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.
+the memory read/write commands. This includes @command{nand probe}.
@section TCP/IP Ports
@itemize @bullet
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
@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}
@section Target Config/Cget Options
These options can be specified when the target is created, or later
via the configure option or to query the target via cget.
+
+You should specify a working area if you can; typically it uses some
+on-chip SRAM. Such a working area can speed up many things, including bulk
+writes to target memory; flash operations like checking to see if memory needs
+to be erased; GDB memory checksumming; and may help perform otherwise
+unavailable operations (like some coprocessor operations on ARM7/9 systems).
@itemize @bullet
@item @b{-type} - returns the target type
@item @b{-event NAME BODY} see Target events
-@item @b{-work-area-virt [ADDRESS]} specify/set the work area
-@item @b{-work-area-phys [ADDRESS]} specify/set the work area
+@item @b{-work-area-virt [ADDRESS]} specify/set the work area base address
+which will be used when an MMU is active.
+@item @b{-work-area-phys [ADDRESS]} specify/set the work area base address
+which will be used when an MMU is inactive.
@item @b{-work-area-size [ADDRESS]} specify/set the work area
-@item @b{-work-area-backup [0|1]} does the work area get backed up
+@item @b{-work-area-backup [0|1]} does the work area get backed up;
+by default, it doesn't. When possible, use a working_area that doesn't
+need to be backed up, since performing a backup slows down operations.
@item @b{-endian [big|little]}
@item @b{-variant [NAME]} some chips have variants OpenOCD needs to know about
@item @b{-chain-position DOTTED.NAME} the tap name this target refers to.
@end example
@* The target# is a the 0 based target numerical index.
-This command specifies a working area for the debugger to use. This
-may be used to speed-up downloads to target memory and flash
-operations, or to perform otherwise unavailable operations (some
-coprocessor operations on ARM7/9 systems, for example). The last
-parameter decides whether the memory should be preserved
-(<@var{backup}>) or can simply be overwritten (<@var{nobackup}>). If
-possible, use a working_area that doesn't need to be backed up, as
-performing a backup slows down operation.
-
@node Flash Configuration
@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.
@*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
+
+@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 ...
+@cindex NAND erasing
+@b{NOTE:} Syntax is in flux.
+@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} num ...
+@b{NOTE:} Syntax is in flux.
+@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} 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
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)
@*Enable the use of the debug communications channel (DCC) to write larger (>128 byte)
amounts of memory. DCC downloads offer a huge speed increase, but might be potentially
unsafe, especially with targets running at very low speeds. This command was introduced
-with OpenOCD rev. 60.
+with OpenOCD rev. 60, and requires a few bytes of working area.
@end itemize
@subsection ARM720T specific commands
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