David Brownell <david-b@pacbell.net> Fix formatting bug in at91sam7 doc added with the at91sam3 support;

and some formatting issues with sam7 and stm32 keyword params.

Tweak at91sam3 docs.  Remove ninth nibble from flash bank addresses,
clarify "at91sam3 show" variants and that the flash bank layout is
not needed as a parameter (unlike with sam7); formatting fixes.

git-svn-id: svn://svn.berlios.de/openocd/trunk@2400 b42882b7-edfa-0310-969c-e2dbd0fdcd60

1 files changed, 35 insertions, 27 deletions

diff --git a/doc/openocd.texi b/doc/openocd.texi
index c5865929..5b485c4c 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -3376,57 +3376,66 @@ flash bank aduc702x 0 0 0 0 $_TARGETNAME
 
 @deffn {Flash Driver} at91sam3
 @cindex at91sam3
-All members of the AT91SAM3 (cortex-M3) microcontroller family from
-atmel include internal flash and use the Cortex-M3 core. The driver
+All members of the AT91SAM3 microcontroller family from
+Atmel include internal flash and use ARM's Cortex-M3 core. The driver
 currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips. Note
 that the driver was orginaly developed and tested using the
 AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips in
-the family where cribbed from the data sheet [Note to future
+the family was cribbed from the data sheet. @emph{Note to future
 readers/updaters: Please remove this worrysome comment after other
-chips are confirmed].
+chips are confirmed.}
 
 The AT91SAM3U4[E/C] (256K) chips have 2 flash banks, the other chips
-(3U[1/2][E/C]) have 1 flash bank, in all cases the flash banks are at
-the following fixed locations. 
+(3U[1/2][E/C]) have 1 flash bank.  In all cases the flash banks are at
+the following fixed locations:
 
 @example
 # Flash bank 0 - all chips
-flash bank at91sam3 0x000080000 0 1 1 $_TARGETNAME
+flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME
 # Flash bank 1 - only 256K chips
-flash bank at91sam3 0x000100000 0 1 1 $_TARGETNAME
+flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME
 @end example
 
-Internally, the AT91SAM3 flash memory is organized as follows:
+Internally, the AT91SAM3 flash memory is organized as follows.
+Unlike the AT91SAM7 chips, these are not used as parameters
+to the @command{flash bank} command:
 
 @itemize
-@item @var{N-Banks:} 256K chips have 2 banks, others have 1 bank.
-@item @var{Bank Size:}  128K/64K Per flash bank
-@item @var{Sectors:} 16 or 8 per bank
-@item @var{SectorSize:} 8K Per Sector
-@item @var{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
+@item @emph{N-Banks:} 256K chips have 2 banks, others have 1 bank.
+@item @emph{Bank Size:}  128K/64K Per flash bank
+@item @emph{Sectors:} 16 or 8 per bank
+@item @emph{SectorSize:} 8K Per Sector
+@item @emph{PageSize:} 256 bytes per page. Note that OpenOCD operates on 'sector' sizes, not page sizes.
 @end itemize
 
-The AT91SAM3 driver adds an additional command:
+The AT91SAM3 driver adds some additional commands:
 
-@deffn Command {at91sam3 gpnvm set|clear|show all|NUMBER}
-This command allows you to set, clear, or show the state of the GPNVM bits.
+@deffn Command {at91sam3 gpnvm}
+@deffnx Command {at91sam3 gpnvm clear} number
+@deffnx Command {at91sam3 gpnvm set} number
+@deffnx Command {at91sam3 gpnvm show} [@option{all}|number]
+With no parameters, @command{show} or @command{show all},
+shows the status of all GPNVM bits.
+With @command{show} @var{number}, displays that bit.
+
+With @command{set} @var{number} or @command{clear} @var{number},
+modifies that GPNVM bit.
 @end deffn
 
 @deffn Command {at91sam3 info}
 This command attempts to display information about the AT91SAM3
-chip. @b{First} it read the @var{CHIPID_CIDR} [address 0x400e0740, see
+chip. @emph{First} it read the @code{CHIPID_CIDR} [address 0x400e0740, see
 Section 28.2.1, page 505 of the AT91SAM3U 29/may/2009 datasheet,
-document id: doc6430A] and decodes the values. @b{Second} it reads the
+document id: doc6430A] and decodes the values. @emph{Second} it reads the
 various clock configuration registers and attempts to display how it
 believes the chip is configured. By default, the SLOWCLK is assumed to
-be 32768 Hz, see the command @b{at91sam3 slowclk}.
+be 32768 Hz, see the command @command{at91sam3 slowclk}.
 @end deffn
 
-@deffn Command {at91sam3 slowclk [VALUE]}
+@deffn Command {at91sam3 slowclk} [value]
 This command shows/sets the slow clock frequency used in the
-@b{at91sam3 info} command calculations above.
+@command{at91sam3 info} command calculations above.
 @end deffn
-
 @end deffn
 
 @deffn {Flash Driver} at91sam7
@@ -3434,8 +3443,6 @@ All members of the AT91SAM7 microcontroller family from Atmel include
 internal flash and use ARM7TDMI cores.  The driver automatically
 recognizes a number of these chips using the chip identification
 register, and autoconfigures itself.
-@end deffn
-
 
 @example
 flash bank at91sam7 0 0 0 0 $_TARGETNAME
@@ -3466,7 +3473,7 @@ However, there is an ``EraseAll`` command that can erase an entire flash
 plane (of up to 256KB), and it will be used automatically when you issue
 @command{flash erase_sector} or @command{flash erase_address} commands.
 
-@deffn Command {at91sam7 gpnvm} bitnum (set|clear)
+@deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
 Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
 bit for the processor.   Each processor has a number of such bits,
 used for controlling features such as brownout detection (so they
@@ -3476,6 +3483,7 @@ This assumes that the first flash bank (number 0) is associated with
 the appropriate at91sam7 target.
 @end quotation
 @end deffn
+@end deffn
 
 @deffn {Flash Driver} avr
 The AVR 8-bit microcontrollers from Atmel integrate flash memory.
@@ -3601,7 +3609,7 @@ the @command{stm32x options_write} command.
 The @var{num} parameter is a value shown by @command{flash banks}.
 @end deffn
 
-@deffn Command {stm32x options_write} num (SWWDG|HWWDG) (RSTSTNDBY|NORSTSTNDBY) (RSTSTOP|NORSTSTOP)
+@deffn Command {stm32x options_write} num (@option{SWWDG}|@option{HWWDG}) (@option{RSTSTNDBY}|@option{NORSTSTNDBY}) (@option{RSTSTOP}|@option{NORSTSTOP})
 Writes the stm32 option byte with the specified values.
 The @var{num} parameter is a value shown by @command{flash banks}.
 @end deffn