interesting
/
riscv-openocd
mirror of https://github.com/riscv/riscv-openocd.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Submitted by David Brownell <david-b@pacbell.net>: 

Add a "NAND Commands" section to to the TEXI docs, covering the basic
commands except for those previously discussed as being due for removal
("nand copy") or switching to use byte offsets not block numbers.

This uses the "@deffn..." syntax for defining commands, as somewhat
suggested by the TEXI documentation, and adds a new "Command Index".
We might prefer to merge those indexes for the near term, but I think
the "@deffn" approch is probably worth switching to.

Updates a few other bits to clarify that "flash" doesn't just mean NOR.  
And to fix one niggling falsity:  the "reset-init" event *is* used, and
in fact it's quite important.


git-svn-id: svn://svn.berlios.de/openocd/trunk@1879 b42882b7-edfa-0310-969c-e2dbd0fdcd60
This commit is contained in:
zwelch 2009-05-22 02:25:18 +00:00
parent 2f8c6015ba
commit 61c77af0ab
1 changed files with 317 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

329
doc/openocd.texi
View File

@ -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,7 +81,8 @@ 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
@ -104,10 +106,10 @@ 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.
@node Developers
@chapter Developers
@ -812,7 +814,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
@ -1077,8 +1079,8 @@ etb config $_TARGETNAME $_CHIPNAME.etb
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:
@ -1148,7 +1150,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
@ -1585,7 +1587,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
@ -2003,7 +2006,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}
@ -2158,6 +2164,16 @@ still use this that need to be converted.
@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.
@ -2525,6 +2541,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 <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
@ -3530,6 +3826,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
@ -3956,13 +4257,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