Browse Source

manual: reorder flash driver info

Put all the individual driver descriptions to where they really
belong, fix sectioning etc.

Change-Id: I94dc09e9a296ec57db4475f8dfb0a7d62a754aa4
Signed-off-by: Paul Fertser <fercerpav@gmail.com>
Reviewed-on: http://openocd.zylin.com/2770
Tested-by: jenkins
Reviewed-by: Andreas Fritiofson <andreas.fritiofson@gmail.com>
tags/v0.9.0
Paul Fertser 5 years ago
parent
commit
805604058b
1 changed files with 195 additions and 199 deletions
  1. +195
    -199
      doc/openocd.texi

+ 195
- 199
doc/openocd.texi View File

@@ -73,7 +73,6 @@ Free Documentation License''.
* CPU Configuration:: CPU Configuration
* Flash Commands:: Flash Commands
* Flash Programming:: Flash Programming
* NAND Flash Commands:: NAND Flash Commands
* PLD/FPGA Commands:: PLD/FPGA Commands
* General Commands:: General Commands
* Architecture and Core Commands:: Architecture and Core Commands
@@ -4715,6 +4714,26 @@ As noted above, the @command{flash bank} command requires a driver name,
and allows driver-specific options and behaviors.
Some drivers also activate driver-specific commands.

@deffn {Flash Driver} virtual
This is a special driver that maps a previously defined bank to another
address. All bank settings will be copied from the master physical bank.

The @var{virtual} driver defines one mandatory parameters,

@itemize
@item @var{master_bank} The bank that this virtual address refers to.
@end itemize

So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to
the flash bank defined at address 0x1fc00000. Any cmds executed on
the virtual banks are actually performed on the physical banks.
@example
flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME
flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME
@end example
@end deffn

@subsection External Flash

@deffn {Flash Driver} cfi
@@ -4811,6 +4830,19 @@ flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME

@end deffn

@deffn {Flash Driver} mrvlqspi
This driver supports QSPI flash controller of Marvell's Wireless
Microcontroller platform.

The flash size is autodetected based on the table of known JEDEC IDs
hardcoded in the OpenOCD sources.

@example
flash bank $_FLASHNAME mrvlqspi 0x0 0 0 0 $_TARGETNAME 0x46010000
@end example

@end deffn

@subsection Internal Flash (Microcontrollers)

@deffn {Flash Driver} aduc702x
@@ -5466,87 +5498,14 @@ The @var{num} parameter is a value shown by @command{flash banks}.

@end deffn

@deffn {Flash Driver} tms470
Most members of the TMS470 microcontroller family from Texas Instruments
include internal flash and use ARM7TDMI cores.
This driver doesn't require the chip and bus width to be specified.

Some tms470-specific commands are defined:

@deffn Command {tms470 flash_keyset} key0 key1 key2 key3
Saves programming keys in a register, to enable flash erase and write commands.
@end deffn

@deffn Command {tms470 osc_mhz} clock_mhz
Reports the clock speed, which is used to calculate timings.
@end deffn

@deffn Command {tms470 plldis} (0|1)
Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up
the flash clock.
@end deffn
@end deffn

@deffn {Flash Driver} virtual
This is a special driver that maps a previously defined bank to another
address. All bank settings will be copied from the master physical bank.

The @var{virtual} driver defines one mandatory parameters,

@itemize
@item @var{master_bank} The bank that this virtual address refers to.
@end itemize

So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to
the flash bank defined at address 0x1fc00000. Any cmds executed on
the virtual banks are actually performed on the physical banks.
@example
flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME
flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME
@end example
@end deffn

@deffn {Flash Driver} fm3
All members of the FM3 microcontroller family from Fujitsu
include internal flash and use ARM Cortex M3 cores.
The @var{fm3} driver uses the @var{target} parameter to select the
correct bank config, it can currently be one of the following:
@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu},
@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}.

@example
flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME
@end example
@end deffn

@deffn {Flash Driver} sim3x
All members of the SiM3 microcontroller family from Silicon Laboratories
include internal flash and use ARM Cortex M3 cores. It supports both JTAG
and SWD interface.
The @var{sim3x} driver tries to probe the device to auto detect the MCU.
If this failes, it will use the @var{size} parameter as the size of flash bank.

@example
flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME
@end example

There are 2 commands defined in the @var{sim3x} driver:

@deffn Command {sim3x mass_erase}
Erases the complete flash. This is used to unlock the flash.
And this command is only possible when using the SWD interface.
@end deffn

@deffn Command {sim3x lock}
Lock the flash. To unlock use the @command{sim3x mass_erase} command.
@end deffn

@end deffn

@subsection str9xpec driver
@deffn {Flash Driver} str9xpec
@cindex str9xpec

Only use this driver for locking/unlocking the device or configuring the option bytes.
Use the standard str9 driver for programming.
Before using the flash commands the turbo mode must be enabled using the
@command{str9xpec enable_turbo} command.

Here is some background info to help
you better understand how this driver works. OpenOCD has two flash drivers for
the str9:
@@ -5584,12 +5543,6 @@ When performing a unlock remember that you will not be able to halt the str9 - i
has been locked. Halting the core is not required for the @option{str9xpec} driver
as mentioned above, just issue the commands above manually or from a telnet prompt.

@deffn {Flash Driver} str9xpec
Only use this driver for locking/unlocking the device or configuring the option bytes.
Use the standard str9 driver for programming.
Before using the flash commands the turbo mode must be enabled using the
@command{str9xpec enable_turbo} command.

Several str9xpec-specific commands are defined:

@deffn Command {str9xpec disable_turbo} num
@@ -5640,6 +5593,63 @@ unlock str9 device.

@end deffn

@deffn {Flash Driver} tms470
Most members of the TMS470 microcontroller family from Texas Instruments
include internal flash and use ARM7TDMI cores.
This driver doesn't require the chip and bus width to be specified.

Some tms470-specific commands are defined:

@deffn Command {tms470 flash_keyset} key0 key1 key2 key3
Saves programming keys in a register, to enable flash erase and write commands.
@end deffn

@deffn Command {tms470 osc_mhz} clock_mhz
Reports the clock speed, which is used to calculate timings.
@end deffn

@deffn Command {tms470 plldis} (0|1)
Disables (@var{1}) or enables (@var{0}) use of the PLL to speed up
the flash clock.
@end deffn
@end deffn

@deffn {Flash Driver} fm3
All members of the FM3 microcontroller family from Fujitsu
include internal flash and use ARM Cortex M3 cores.
The @var{fm3} driver uses the @var{target} parameter to select the
correct bank config, it can currently be one of the following:
@code{mb9bfxx1.cpu}, @code{mb9bfxx2.cpu}, @code{mb9bfxx3.cpu},
@code{mb9bfxx4.cpu}, @code{mb9bfxx5.cpu} or @code{mb9bfxx6.cpu}.

@example
flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME
@end example
@end deffn

@deffn {Flash Driver} sim3x
All members of the SiM3 microcontroller family from Silicon Laboratories
include internal flash and use ARM Cortex M3 cores. It supports both JTAG
and SWD interface.
The @var{sim3x} driver tries to probe the device to auto detect the MCU.
If this failes, it will use the @var{size} parameter as the size of flash bank.

@example
flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME
@end example

There are 2 commands defined in the @var{sim3x} driver:

@deffn Command {sim3x mass_erase}
Erases the complete flash. This is used to unlock the flash.
And this command is only possible when using the SWD interface.
@end deffn

@deffn Command {sim3x lock}
Lock the flash. To unlock use the @command{sim3x mass_erase} command.
@end deffn
@end deffn

@deffn {Flash Driver} nrf51
All members of the nRF51 microcontroller families from Nordic Semiconductor
include internal flash and use ARM Cortex-M0 core.
@@ -5659,19 +5669,6 @@ code.

@end deffn

@deffn {Flash Driver} mrvlqspi
This driver supports QSPI flash controller of Marvell's Wireless
Microcontroller platform.

The flash size is autodetected based on the table of known JEDEC IDs
hardcoded in the OpenOCD sources.

@example
flash bank $_FLASHNAME mrvlqspi 0x0 0 0 0 $_TARGETNAME 0x46010000
@end example

@end deffn

@deffn {Flash Driver} mdr
This drivers handles the integrated NOR flash on Milandr Cortex-M
based controllers. A known limitation is that the Info memory can't be
@@ -5700,102 +5697,7 @@ if @{ [info exists IMEMORY] && [string equal $IMEMORY true] @} @{
@end example
@end deffn

@section mFlash

@subsection mFlash Configuration
@cindex mFlash Configuration

@deffn {Config Command} {mflash bank} soc base RST_pin target
Configures a mflash for @var{soc} host bank at
address @var{base}.
The pin number format depends on the host GPIO naming convention.
Currently, the mflash driver supports s3c2440 and pxa270.

Example for s3c2440 mflash where @var{RST pin} is GPIO B1:

@example
mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0
@end example

Example for pxa270 mflash where @var{RST pin} is GPIO 43:

@example
mflash bank $_FLASHNAME pxa270 0x08000000 43 0
@end example
@end deffn

@subsection mFlash commands
@cindex mFlash commands

@deffn Command {mflash config pll} frequency
Configure mflash PLL.
The @var{frequency} is the mflash input frequency, in Hz.
Issuing this command will erase mflash's whole internal nand and write new pll.
After this command, mflash needs power-on-reset for normal operation.
If pll was newly configured, storage and boot(optional) info also need to be update.
@end deffn

@deffn Command {mflash config boot}
Configure bootable option.
If bootable option is set, mflash offer the first 8 sectors
(4kB) for boot.
@end deffn

@deffn Command {mflash config storage}
Configure storage information.
For the normal storage operation, this information must be
written.
@end deffn

@deffn Command {mflash dump} num filename offset size
Dump @var{size} bytes, starting at @var{offset} bytes from the
beginning of the bank @var{num}, to the file named @var{filename}.
@end deffn

@deffn Command {mflash probe}
Probe mflash.
@end deffn

@deffn Command {mflash write} num filename offset
Write the binary file @var{filename} to mflash bank @var{num}, starting at
@var{offset} bytes from the beginning of the bank.
@end deffn

@node Flash Programming
@chapter Flash Programming

OpenOCD implements numerous ways to program the target flash, whether internal or external.
Programming can be acheived by either using GDB @ref{programmingusinggdb,,Programming using GDB},
or using the cmds given in @ref{flashprogrammingcommands,,Flash Programming Commands}.

@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
OpenOCD will program/verify/reset the target and optionally shutdown.

The script is executed as follows and by default the following actions will be peformed.
@enumerate
@item 'init' is executed.
@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
@item @code{flash write_image} is called to erase and write any flash using the filename given.
@item @code{verify_image} is called if @option{verify} parameter is given.
@item @code{reset run} is called if @option{reset} parameter is given.
@item OpenOCD is shutdown if @option{exit} parameter is given.
@end enumerate

An example of usage is given below. @xref{program}.

@example
# program and verify using elf/hex/s19. verify and reset
# are optional parameters
openocd -f board/stm32f3discovery.cfg \
-c "program filename.elf verify reset exit"

# binary files need the flash address passing
openocd -f board/stm32f3discovery.cfg \
-c "program filename.bin exit 0x08000000"
@end example

@node NAND Flash Commands
@chapter NAND Flash Commands
@section NAND Flash Commands
@cindex NAND

Compared to NOR or SPI flash, NAND devices are inexpensive
@@ -5859,7 +5761,7 @@ Some larger devices will work, since they are actually multi-chip
modules with two smaller chips and individual chipselect lines.

@anchor{nandconfiguration}
@section NAND Configuration Commands
@subsection NAND Configuration Commands
@cindex NAND configuration

NAND chips must be declared in configuration scripts,
@@ -5916,7 +5818,7 @@ 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
@subsection Erasing, Reading, Writing to NAND Flash

@deffn Command {nand dump} num filename offset length [oob_option]
@cindex NAND reading
@@ -6058,7 +5960,7 @@ hardward-computed ECC before the data is written. This limitation may
be removed in a future release.
@end deffn

@section Other NAND commands
@subsection Other NAND commands
@cindex NAND other commands

@deffn Command {nand check_bad_blocks} num [offset length]
@@ -6102,7 +6004,7 @@ with the wrong ECC data can cause them to be marked as bad.
@end deffn

@anchor{nanddriverlist}
@section NAND Driver List
@subsection NAND Driver List
As noted above, the @command{nand device} command allows
driver-specific options and behaviors.
Some controllers also activate controller-specific commands.
@@ -6222,6 +6124,100 @@ or @code{read_page} methods, so @command{nand raw_access} won't
change any behavior.
@end deffn

@section mFlash

@subsection mFlash Configuration
@cindex mFlash Configuration

@deffn {Config Command} {mflash bank} soc base RST_pin target
Configures a mflash for @var{soc} host bank at
address @var{base}.
The pin number format depends on the host GPIO naming convention.
Currently, the mflash driver supports s3c2440 and pxa270.

Example for s3c2440 mflash where @var{RST pin} is GPIO B1:

@example
mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0
@end example

Example for pxa270 mflash where @var{RST pin} is GPIO 43:

@example
mflash bank $_FLASHNAME pxa270 0x08000000 43 0
@end example
@end deffn

@subsection mFlash commands
@cindex mFlash commands

@deffn Command {mflash config pll} frequency
Configure mflash PLL.
The @var{frequency} is the mflash input frequency, in Hz.
Issuing this command will erase mflash's whole internal nand and write new pll.
After this command, mflash needs power-on-reset for normal operation.
If pll was newly configured, storage and boot(optional) info also need to be update.
@end deffn

@deffn Command {mflash config boot}
Configure bootable option.
If bootable option is set, mflash offer the first 8 sectors
(4kB) for boot.
@end deffn

@deffn Command {mflash config storage}
Configure storage information.
For the normal storage operation, this information must be
written.
@end deffn

@deffn Command {mflash dump} num filename offset size
Dump @var{size} bytes, starting at @var{offset} bytes from the
beginning of the bank @var{num}, to the file named @var{filename}.
@end deffn

@deffn Command {mflash probe}
Probe mflash.
@end deffn

@deffn Command {mflash write} num filename offset
Write the binary file @var{filename} to mflash bank @var{num}, starting at
@var{offset} bytes from the beginning of the bank.
@end deffn

@node Flash Programming
@chapter Flash Programming

OpenOCD implements numerous ways to program the target flash, whether internal or external.
Programming can be acheived by either using GDB @ref{programmingusinggdb,,Programming using GDB},
or using the cmds given in @ref{flashprogrammingcommands,,Flash Programming Commands}.

@*To simplify using the flash cmds directly a jimtcl script is available that handles the programming and verify stage.
OpenOCD will program/verify/reset the target and optionally shutdown.

The script is executed as follows and by default the following actions will be peformed.
@enumerate
@item 'init' is executed.
@item 'reset init' is called to reset and halt the target, any 'reset init' scripts are executed.
@item @code{flash write_image} is called to erase and write any flash using the filename given.
@item @code{verify_image} is called if @option{verify} parameter is given.
@item @code{reset run} is called if @option{reset} parameter is given.
@item OpenOCD is shutdown if @option{exit} parameter is given.
@end enumerate

An example of usage is given below. @xref{program}.

@example
# program and verify using elf/hex/s19. verify and reset
# are optional parameters
openocd -f board/stm32f3discovery.cfg \
-c "program filename.elf verify reset exit"

# binary files need the flash address passing
openocd -f board/stm32f3discovery.cfg \
-c "program filename.bin exit 0x08000000"
@end example

@node PLD/FPGA Commands
@chapter PLD/FPGA Commands
@cindex PLD


Loading…
Cancel
Save