X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=e4220d3a84c1251d8f161ec2441170d6cca470f0;hb=045362d74a4450efe0943e8adb6a6397028780ae;hp=84400fce1036526bebb8d4283f16c43fa137ca7e;hpb=aed582e4228f3ca60d47bc79f86447c01ba686b5;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 84400fce10..e4220d3a84 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -65,6 +65,7 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger * 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 @@ -80,13 +81,22 @@ This manual documents edition @value{EDITION} of the Open On-Chip Debugger @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. @@ -96,7 +106,7 @@ with the JTAG (IEEE 1149.1) compliant taps on your target board. @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 @@ -104,63 +114,69 @@ Cortex-M3 (Luminary Stellaris LM3 and ST STM32) based cores to be 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 (@xref{Building}) provides +instructions to retrieve and and build the latest version of the OpenOCD +source code. -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 + +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 -@chapter Building -@cindex building OpenOCD +@chapter Building OpenOCD +@cindex building @section Pre-Built Tools If you are interested in getting actual work done rather than building @@ -179,10 +195,16 @@ You are a @b{PACKAGER} of OpenOCD if you @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 @@ -812,7 +834,7 @@ target/FOO.cfg]} statements along with any board specific things. 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 @@ -881,6 +903,8 @@ If the chip has 2 targets, use the names @b{_TARGETNAME0}, At no time should the name ``target0'' (the default target name if none was specified) be used. The name ``target0'' is a hard coded name - the next target on the board will be some other number. +In the same way, avoid using target numbers even when they are +permitted; use the right target name(s) for your board. The user (or board file) should reasonably be able to: @@ -1014,6 +1038,7 @@ See the command ``jtag newtap'' for detail, but in brief the names you should us @item @b{cpu} @item @b{flash} @item @b{bs} +@item @b{etb} @item @b{jrc} @item @b{unknownN} - it happens :-( @end itemize @@ -1048,13 +1073,34 @@ helpful - for common programing errors. If present, the MMU, the MPU and the CACHE should be disabled. +Some ARM cores are equipped with trace support, which permits +examination of the instruction and data bus activity. Trace +activity is controlled through an ``Embedded Trace Module'' (ETM) +on one of the core's scan chains. The ETM emits voluminous data +through a ``trace port''. The trace port is accessed in one +of two ways. When its signals are pinned out from the chip, +boards may provide a special high speed debugging connector; +software support for this is not configured by default, use +the ``--enable-oocd_trace'' option. Alternatively, trace data +may be stored an on-chip SRAM which is packaged as an ``Embedded +Trace Buffer'' (ETB). An ETB has its own TAP, usually right after +its associated ARM core. OpenOCD supports the ETM, and your +target configuration should set it up with the relevant trace +port: ``etb'' for chips which use that, else the board-specific +option will be either ``oocd_trace'' or ``dummy''. + +@example +etm config $_TARGETNAME 16 normal full etb +etb config $_TARGETNAME $_CHIPNAME.etb +@end example + @subsection Internal Flash Configuration 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: @@ -1124,7 +1170,7 @@ configuration files and/or command line options. 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 @@ -1561,7 +1607,8 @@ commands use that dotted.name to manipulate or refer to the tap. 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 @@ -1606,7 +1653,9 @@ bits long, during Capture-IR 0x42 is loaded into the IR, and bits @itemize @bullet @item @b{-expected-id NUMBER} @* By default it is zero. If non-zero represents the -expected tap ID used when the JTAG chain is examined. See below. +expected tap ID used when the JTAG chain is examined. Repeat +the option as many times as required if multiple id's can be +expected. See below. @item @b{-disable} @item @b{-enable} @* By default not specified the tap is enabled. Some chips have a @@ -1638,6 +1687,7 @@ JTAG taps. GDB ends up talking via OpenOCD to one of the taps. @item @b{cpu} - the main CPU of the chip, alternatively @b{foo.arm} and @b{foo.dsp} @item @b{flash} - if the chip has a flash tap, example: str912.flash @item @b{bs} - for boundary scan if this is a seperate tap. +@item @b{etb} - for an embedded trace buffer (example: an ARM ETB11) @item @b{jrc} - for JTAG route controller (example: OMAP3530 found on Beagleboards) @item @b{unknownN} - where N is a number if you have no idea what the tap is for @item @b{Other names} - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the ``sdma'' tap. @@ -1677,7 +1727,8 @@ tap which then connects to the TDI pin. @item @b{Note: Deprecated} - Index Numbers @* Prior to 28/nov/2008, JTAG taps where numbered from 0..N this feature is still present, however its use is highly discouraged and -should not be counted upon. +should not be counted upon. Update all of your scripts to use +TAP names rather than numbers. @item @b{Multiple chips} @* If your board has multiple chips, you should be able to @b{source} two configuration files, in the proper order, and @@ -1975,7 +2026,10 @@ The following events are available: @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} @@ -2020,8 +2074,8 @@ jtag configure DOTTED.NAME -event tap-disable @{ @itemize @bullet @item @b{NAME} @* Is the name of the debug target. By convention it should be the tap -DOTTED.NAME, this name is also used to create the target object -command. +DOTTED.NAME. This name is also used to create the target object +command, and in other places the target needs to be identified. @item @b{TYPE} @* Specifies the target type, i.e.: ARM7TDMI, or Cortex-M3. Currently supported targets are: @comment START types @@ -2054,13 +2108,23 @@ command. @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. @@ -2116,19 +2180,20 @@ still use this that need to be converted. @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. @@ -2229,7 +2294,7 @@ The @b{flash bank} command is used to configure one or more flash chips (or bank @example @b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> -<@var{bus_width}> <@var{target#}> [@var{driver_options ...}] +<@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}> @@ -2249,8 +2314,9 @@ perhaps configure a GPIO pin that controls the ``write protect'' pin on the flash chip. @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 number of the target they're connected to as an additional +<@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. @@ -2264,12 +2330,13 @@ The @var{jedec_probe} option is used to detect certain non-CFI flash ROMs, like @subsubsection lpc2000 options @cindex lpc2000 options -@b{flash bank lpc2000} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}> +@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 number -of the target this flash belongs to (first is 0), the frequency at which the core +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. @@ -2278,20 +2345,20 @@ vector table. @subsubsection at91sam7 options @cindex at91sam7 options -@b{flash bank at91sam7} 0 0 0 0 <@var{target#}> -@*AT91SAM7 flashes only require the @var{target#}, all other values are looked up after +@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. @subsubsection str7 options @cindex str7 options -@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}> +@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target}> <@var{variant}> @*variant can be either STR71x, STR73x or STR75x. @subsubsection str9 options @cindex str9 options -@b{flash bank str9x} <@var{base}> <@var{size}> 0 0 <@var{target#}> +@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 @@ -2300,7 +2367,7 @@ This will setup the BBSR, NBBSR, BBADR and NBBADR registers respectively. @subsubsection str9 options (str9xpec driver) -@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target#}> +@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>.} @@ -2310,25 +2377,25 @@ Use the standard str9 driver for programming. @xref{STR9 specific commands}. @subsubsection Stellaris (LM3Sxxx) options @cindex Stellaris (LM3Sxxx) options -@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target#}> -@*Stellaris flash plugin only require the @var{target#}. +@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target}> +@*Stellaris flash plugin only require the @var{target}. @subsubsection stm32x options @cindex stm32x options -@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target#}> -@*stm32x flash plugin only require the @var{target#}. +@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target}> +@*stm32x flash plugin only require the @var{target}. @subsubsection aduc702x options @cindex aduc702x options -@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). +@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). @subsection mFlash Configuration @cindex mFlash Configuration @b{mflash bank} <@var{soc}> <@var{base}> <@var{chip_width}> <@var{bus_width}> -<@var{RST pin}> <@var{WP pin}> <@var{DPD pin}> <@var{target #}> +<@var{RST pin}> <@var{WP pin}> <@var{DPD pin}> <@var{target}> @cindex mflash bank @*Configures a mflash for <@var{soc}> host bank at <@var{base}>. <@var{chip_width}> and <@var{bus_width}> are bytes @@ -2494,6 +2561,286 @@ These are flash specific commands when using the Stellaris driver. @*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 +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 @@ -2557,6 +2904,10 @@ Typically the "fast enable" is specified first on the command line: 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 (default: stderr) @@ -2780,7 +3131,7 @@ speeds, like the 32kHz startup clock of an AT91RM9200. @*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 @@ -3495,6 +3846,11 @@ references a jtag newtap and a flash bank references a target). 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 @@ -3921,13 +4277,17 @@ at91sam9260.cfg nslu2.cfg sam7x256.cfg wi-9c.cfg @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