X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=c586592942052210155ebd801f6742addc14bebb;hp=88d4abd9ec66007b9474b5cabd29e0dec4ce33a7;hb=0ace4d24dbdaca219741338c8c9ecb61df8dc965;hpb=8f9f5c189bc64c8cd8a14b4dfb156e3382ca050a diff --git a/doc/openocd.texi b/doc/openocd.texi index 88d4abd9ec..c586592942 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -23,6 +23,7 @@ of the Open On-Chip Debugger (OpenOCD). @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk} @item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com} @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com} +@item Copyright @copyright{} 2009 David Brownell @end itemize @quotation @@ -62,10 +63,10 @@ Free Documentation License''. * Developers:: OpenOCD Developers * Building OpenOCD:: Building OpenOCD From SVN * JTAG Hardware Dongles:: JTAG Hardware Dongles +* About JIM-Tcl:: About JIM-Tcl * Running:: Running OpenOCD * OpenOCD Project Setup:: OpenOCD Project Setup * Config File Guidelines:: Config File Guidelines -* About JIM-Tcl:: About JIM-Tcl * Daemon Configuration:: Daemon Configuration * Interface - Dongle Configuration:: Interface - Dongle Configuration * Reset Configuration:: Reset Configuration @@ -129,7 +130,7 @@ debugged via the GDB protocol. @b{Flash Programing:} Flash writing is supported for external CFI compatible NOR flashes (Intel and AMD/Spansion command set) and several -internal flashes (LPC2000, AT91SAM7, STR7x, STR9x, LM3, and +internal flashes (LPC2000, AT91SAM7, AT91SAM3U, STR7x, STR9x, LM3, and STM32x). Preliminary support for various NAND flash controllers (LPC3180, Orion, S3C24xx, more) controller is included. @@ -658,6 +659,50 @@ FlashLINK JTAG programing cable for PSD and uPSD} @end itemize +@node About JIM-Tcl +@chapter About JIM-Tcl +@cindex JIM Tcl +@cindex tcl + +OpenOCD includes a small ``Tcl Interpreter'' known as JIM-Tcl. +This programming language provides a simple and extensible +command interpreter. + +All commands presented in this Guide are extensions to JIM-Tcl. +You can use them as simple commands, without needing to learn +much of anything about Tcl. +Alternatively, can write Tcl programs with them. + +You can learn more about JIM at its website, @url{http://jim.berlios.de}. + +@itemize @bullet +@item @b{JIM vs. Tcl} +@* JIM-TCL is a stripped down version of the well known Tcl language, +which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far +fewer features. JIM-Tcl is a single .C file and a single .H file and +implements the basic Tcl command set. In contrast: Tcl 8.6 is a +4.2 MB .zip file containing 1540 files. + +@item @b{Missing Features} +@* Our practice has been: Add/clone the real Tcl feature if/when +needed. We welcome JIM Tcl improvements, not bloat. + +@item @b{Scripts} +@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's +command interpreter today is a mixture of (newer) +JIM-Tcl commands, and (older) the orginal command interpreter. + +@item @b{Commands} +@* At the OpenOCD telnet command line (or via the GDB mon command) one +can type a Tcl for() loop, set variables, etc. + +@item @b{Historical Note} +@* JIM-Tcl was introduced to OpenOCD in spring 2008. + +@item @b{Need a crash course in Tcl?} +@*@xref{Tcl Crash Course}. +@end itemize + @node Running @chapter Running @cindex command line options @@ -692,7 +737,7 @@ clients (Telnet, GDB, Other). If you are having problems, you can enable internal debug messages via the ``-d'' option. -Also it is possible to interleave commands w/config scripts using the +Also it is possible to interleave JIM-Tcl commands w/config scripts using the @option{-c} command line switch. To enable debug output (when reporting problems or working on OpenOCD @@ -807,7 +852,7 @@ single directory for your work with a given board. When you start OpenOCD from that directory, it searches there first for configuration files and for code you upload to the target board. -It is also be the natural place to write files, +It is also the natural place to write files, such as log files and data you download from the board. @section Configuration Basics @@ -847,7 +892,7 @@ openocd -f interface/signalyzer.cfg \ You could wrap such long command lines in shell scripts, each supporting a different development task. -One might re-flash the board with specific firmware version. +One might re-flash the board with a specific firmware version. Another might set up a particular debugging or run-time environment. Here we will focus on the simpler solution: one user config @@ -943,6 +988,10 @@ its @command{xscale vector_catch} sibling) can be a timesaver during some debug sessions, but don't make everyone use that either. Keep those kinds of debugging aids in your user config file. +TCP/IP port configuration is another example of something which +is environment-specific, and should only appear in +a user config file. @xref{TCP/IP Ports}. + @section Project-Specific Utilities A few project-specific utility @@ -1015,21 +1064,21 @@ including developers and integrators of OpenOCD and any user who needs to get a new board working smoothly. It provides guidelines for creating those files. -You should find the following directories under @t{$(INSTALLDIR)/lib/openocd} : +You should find the following directories under @t{$(INSTALLDIR)/scripts}: @itemize @bullet -@item @b{interface} -@*Think JTAG Dongle. Files that configure the JTAG dongle go here. -@item @b{board} -@* Think Circuit Board, PWA, PCB, they go by many names. Board files -contain initialization items that are specific to a board - for -example: The SDRAM initialization sequence for the board, or the type -of external flash and what address it is found at. Any initialization +@item @file{interface} ... +think JTAG Dongle. Files that configure JTAG adapters go here. +@item @file{board} ... +think Circuit Board, PWA, PCB, they go by many names. Board files +contain initialization items that are specific to a board. For +example, the SDRAM initialization sequence for the board, or the type +of external flash and what address it uses. Any initialization sequence to enable that external flash or SDRAM should be found in the -board file. Boards may also contain multiple targets, i.e.: Two CPUs, or +board file. Boards may also contain multiple targets: two CPUs; or a CPU and an FPGA or CPLD. -@item @b{target} -@* Think chip. The ``target'' directory represents the JTAG TAPs +@item @file{target} ... +think chip. The ``target'' directory represents the JTAG TAPs on a chip which OpenOCD should control, not a board. Two common types of targets are ARM chips and FPGA or CPLD chips. @@ -1045,7 +1094,7 @@ commands specific to their situation. @section Interface Config Files The user config file -should be able to source one of these files via a command like this: +should be able to source one of these files with a command like this: @example source [find interface/FOOBAR.cfg] @@ -1060,179 +1109,250 @@ A separate chapter gives information about how to set these up. Read the OpenOCD source code if you have a new kind of hardware interface and need to provide a driver for it. -Interface files should be found in @t{$(INSTALLDIR)/lib/openocd/interface} - @section Board Config Files @cindex config file, board @cindex board config file The user config file -should be able to source one of these files via a command like this: +should be able to source one of these files with a command like this: @example source [find board/FOOBAR.cfg] @end example -The board config file should contain one or more @command{source [find -target/FOO.cfg]} statements along with any board specific things. - +The point of a board config file is to package everything +about a given board that user config files need to know. In summary the board files should contain (if present) @enumerate -@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 -@item Reset configuration +@item One or more @command{source [target/...cfg]} statements +@item NOR flash configuration (@pxref{NOR Configuration}) +@item NAND flash configuration (@pxref{NAND Configuration}) +@item Target @code{reset} handlers for SDRAM and I/O configuration +@item JTAG adapter reset configuration (@pxref{Reset Configuration}) @item All things that are not ``inside a chip'' -@item Things inside a chip go in a 'target' file @end enumerate -@section Target Config Files -@cindex config file, target -@cindex target config file +Generic things inside target chips belong in target config files, +not board config files. So for example a @code{reset-init} event +handler should know board-specific oscillator and PLL parameters, +which it passes to target-specific utility code. + +The most complex task of a board config file is creating such a +@code{reset-init} event handler. +Define those handlers last, after you verify the rest of the board +configuration works. + +@subsection Communication Between Config files -Board config files should be able to source one or more -target config files via a command like this: +In addition to target-specific utility code, another way that +board and target config files communicate is by following a +convention on how to use certain variables. + +The full Tcl/Tk language supports ``namespaces'', but JIM-Tcl does not. +Thus the rule we follow in OpenOCD is this: Variables that begin with +a leading underscore are temporary in nature, and can be modified and +used at will within a target configuration file. + +Complex board config files can do the things like this, +for a board with three chips: @example -source [find target/FOOBAR.cfg] +# Chip #1: PXA270 for network side, big endian +set CHIPNAME network +set ENDIAN big +source [find target/pxa270.cfg] +# on return: _TARGETNAME = network.cpu +# other commands can refer to the "network.cpu" target. +$_TARGETNAME configure .... events for this CPU.. + +# Chip #2: PXA270 for video side, little endian +set CHIPNAME video +set ENDIAN little +source [find target/pxa270.cfg] +# on return: _TARGETNAME = video.cpu +# other commands can refer to the "video.cpu" target. +$_TARGETNAME configure .... events for this CPU.. + +# Chip #3: Xilinx FPGA for glue logic +set CHIPNAME xilinx +unset ENDIAN +source [find target/spartan3.cfg] @end example -In summary the target files should contain - -@enumerate -@item Set defaults -@item Add TAPs to the scan chain -@item Add CPU targets (includes GDB support) -@item CPU/Chip/CPU-Core specific features -@item On-Chip flash -@end enumerate +That example is oversimplified because it doesn't show any flash memory, +or the @code{reset-init} event handlers to initialize external DRAM +or (assuming it needs it) load a configuration into the FPGA. +Such features are usually needed for low-level work with many boards, +where ``low level'' implies that the board initialization software may +not be working. (That's a common reason to need JTAG tools. Another +is to enable working with microcontroller-based systems, which often +have no debugging support except a JTAG connector.) -As a rule of thumb, a target file sets up only one chip. -For a microcontroller, that will often include a single TAP, -which is a CPU needing a GDB target; and its on-chip flash. +Target config files may also export utility functions to board and user +config files. Such functions should use name prefixes, to help avoid +naming collisions. -More complex chips may include multiple TAPs, and the target -config file may need to define them all before OpenOCD -can talk to the chip. -For example, some phone chips have JTAG scan chains that include -an ARM core for operating system use, a DSP, -another ARM core embedded in an image processing engine, -and other processing engines. +Board files could also accept input variables from user config files. +For example, there might be a @code{J4_JUMPER} setting used to identify +what kind of flash memory a development board is using, or how to set +up other clocks and peripherals. -@subsection Important variable names +@subsection Variable Naming Convention +@cindex variable names -Most boards will have only one instance of a chip. +Most boards have only one instance of a chip. However, it should be easy to create a board with more than -one such chip. -Accordingly, we encourage some conventions for naming -variables associated with different TAPs, to promote -consistency and -so that board files can override target defaults, and +one such chip (as shown above). +Accordingly, we encourage these conventions for naming +variables associated with different @file{target.cfg} files, +to promote consistency and +so that board files can override target defaults. + +Inputs to target config files include: @itemize @bullet -@item @b{CHIPNAME} -@* This gives a name to the overall chip, and is used as part of the -tap identifier dotted name. -It's normally provided by the chip manufacturer. -@item @b{ENDIAN} -@* By default little - unless the chip or board is not normally used that way. +@item @code{CHIPNAME} ... +This gives a name to the overall chip, and is used as part of +tap identifier dotted names. +While the default is normally provided by the chip manufacturer, +board files may need to distinguish between instances of a chip. +@item @code{ENDIAN} ... +By default @option{little} - although chips may hard-wire @option{big}. Chips that can't change endianness don't need to use this variable. -@item @b{CPUTAPID} -@* When OpenOCD examines the JTAG chain, it will attempt to identify -every chip. If the @t{-expected-id} is nonzero, OpenOCD attempts -to verify the tap id number verses configuration file and may issue an -error or warning like this. The hope is that this will help to pinpoint -problems in OpenOCD configurations. +@item @code{CPUTAPID} ... +When OpenOCD examines the JTAG chain, it can be told verify the +chips against the JTAG IDCODE register. +The target file will hold one or more defaults, but sometimes the +chip in a board will use a different ID (perhaps a newer revision). +@end itemize -@example -Info: JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f - (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3) -Error: ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, - Got: 0x3f0f0f0f -Error: ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1 -Error: ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3 -@end example +Outputs from target config files include: -@item @b{_TARGETNAME} -@* By convention, this variable is created by the target configuration +@itemize @bullet +@item @code{_TARGETNAME} ... +By convention, this variable is created by the target configuration script. The board configuration file may make use of this variable to configure things like a ``reset init'' script, or other things specific to that board and that target. +If the chip has 2 targets, the names are @code{_TARGETNAME0}, +@code{_TARGETNAME1}, ... etc. +@end itemize -If the chip has 2 targets, use the names @b{_TARGETNAME0}, -@b{_TARGETNAME1}, ... etc. +@subsection The reset-init Event Handler +@cindex event, reset-init +@cindex reset-init handler -@emph{Remember:} The ``board file'' may include multiple targets. -The user (or board) config file should reasonably be able to: +Board config files run in the OpenOCD configuration stage; +they can't use TAPs or targets, since they haven't been +fully set up yet. +This means you can't write memory or access chip registers; +you can't even verify that a flash chip is present. +That's done later in event handlers, of which the target @code{reset-init} +handler is one of the most important. -@example -source [find target/FOO.cfg] -$_TARGETNAME configure ... FOO specific parameters - -source [find target/BAR.cfg] -$_TARGETNAME configure ... BAR specific parameters -@end example +Except on microcontrollers, the basic job of @code{reset-init} event +handlers is setting up flash and DRAM, as normally handled by boot loaders. +Microcontrollers rarely use boot loaders; they run right out of their +on-chip flash and SRAM memory. But they may want to use one of these +handlers too, if just for developer convenience. -@end itemize +@quotation Note +Because this is so very board-specific, and chip-specific, no examples +are included here. +Instead, look at the board config files distributed with OpenOCD. +If you have a boot loader, its source code may also be useful. +@end quotation -@subsection Tcl Variables Guide Line -The Full Tcl/Tk language supports ``namespaces'' - JIM-Tcl does not. +Some of this code could probably be shared between different boards. +For example, setting up a DRAM controller often doesn't differ by +much except the bus width (16 bits or 32?) and memory timings, so a +reusable TCL procedure loaded by the @file{target.cfg} file might take +those as parameters. +Similarly with oscillator, PLL, and clock setup; +and disabling the watchdog. +Structure the code cleanly, and provide comments to help +the next developer doing such work. +(@emph{You might be that next person} trying to reuse init code!) + +The last thing normally done in a @code{reset-init} handler is probing +whatever flash memory was configured. For most chips that needs to be +done while the associated target is halted, either because JTAG memory +access uses the CPU or to prevent conflicting CPU access. + +@subsection JTAG Clock Rate + +Before your @code{reset-init} handler has set up +the PLLs and clocking, you may need to use +a low JTAG clock rate; then you'd increase it later. +(The rule of thumb for ARM-based processors is 1/8 the CPU clock.) +If the board supports adaptive clocking, use the @command{jtag_rclk} +command, in case your board is used with JTAG adapter which +also supports it. Otherwise use @command{jtag_khz}. +Set the slow rate at the beginning of the reset sequence, +and the faster rate as soon as the clocks are at full speed. -Thus the rule we follow in OpenOCD is this: Variables that begin with -a leading underscore are temporary in nature, and can be modified and -used at will within a ?TARGET? configuration file. +@section Target Config Files +@cindex config file, target +@cindex target config file -@b{EXAMPLE:} The user config file should be able to do this: +Board config files communicate with target config files using +naming conventions as described above, and may source one or +more target config files like this: @example - # Board has 3 chips, - # PXA270 #1 network side, big endian - # PXA270 #2 video side, little endian - # Xilinx Glue logic - set CHIPNAME network - set ENDIAN big - source [find target/pxa270.cfg] - # variable: _TARGETNAME = network.cpu - # other commands can refer to the "network.cpu" tap. - $_TARGETNAME configure .... params for this CPU.. - - set ENDIAN little - set CHIPNAME video - source [find target/pxa270.cfg] - # variable: _TARGETNAME = video.cpu - # other commands can refer to the "video.cpu" tap. - $_TARGETNAME configure .... params for this CPU.. - - unset ENDIAN - set CHIPNAME xilinx - source [find target/spartan3.cfg] - - # Since $_TARGETNAME is temporal.. - # these names still work! - network.cpu configure ... params - video.cpu configure ... params +source [find target/FOOBAR.cfg] @end example +The point of a target config file is to package everything +about a given chip that board config files need to know. +In summary the target files should contain + +@enumerate +@item Set defaults +@item Add TAPs to the scan chain +@item Add CPU targets (includes GDB support) +@item CPU/Chip/CPU-Core specific features +@item On-Chip flash +@end enumerate + +As a rule of thumb, a target file sets up only one chip. +For a microcontroller, that will often include a single TAP, +which is a CPU needing a GDB target, and its on-chip flash. + +More complex chips may include multiple TAPs, and the target +config file may need to define them all before OpenOCD +can talk to the chip. +For example, some phone chips have JTAG scan chains that include +an ARM core for operating system use, a DSP, +another ARM core embedded in an image processing engine, +and other processing engines. + @subsection Default Value Boiler Plate Code -All target configuration files should start with this (or a modified form) +All target configuration files should start with code like this, +letting board config files express environment-specific +differences in how things should be set up. @example -# SIMPLE example +# Boards may override chip names, perhaps based on role, +# but the default should match what the vendor uses if @{ [info exists CHIPNAME] @} @{ set _CHIPNAME $CHIPNAME @} else @{ set _CHIPNAME sam7x256 @} +# ONLY use ENDIAN with targets that can change it. if @{ [info exists ENDIAN] @} @{ set _ENDIAN $ENDIAN @} else @{ set _ENDIAN little @} +# TAP identifiers may change as chips mature, for example with +# new revision fields (the "3" here). Pick a good default; you +# can pass several such identifiers to the "jtag newtap" command. if @{ [info exists CPUTAPID ] @} @{ set _CPUTAPID $CPUTAPID @} else @{ @@ -1240,6 +1360,19 @@ if @{ [info exists CPUTAPID ] @} @{ @} @end example +@emph{Remember:} Board config files may include multiple target +config files, or the same target file multiple times +(changing at least @code{CHIPNAME}). + +Likewise, the target configuration file should define +@code{_TARGETNAME} (or @code{_TARGETNAME0} etc) and +use it later on when defining debug targets: + +@example +set _TARGETNAME $_CHIPNAME.cpu +target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME +@end example + @subsection Adding TAPs to the Scan Chain After the ``defaults'' are set up, add the TAPs on each chip to the JTAG scan chain. @@ -1261,12 +1394,25 @@ to source such a config file twice, with different values for @code{CHIPNAME}, so it adds a different TAP each time. +If there are one or more nonzero @option{-expected-id} values, +OpenOCD attempts to verify the actual tap id against those values. +It will issue error messages if there is mismatch, which +can help to pinpoint problems in OpenOCD configurations. + +@example +JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f + (Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3) +ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f +ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1 +ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3 +@end example + There are more complex examples too, with chips that have multiple TAPs. Ones worth looking at include: @itemize -@item @file{target/omap3530.cfg} -- with a disabled ARM, and a JRC -(there's a DSP too, which is not listed) +@item @file{target/omap3530.cfg} -- with disabled ARM and DSP, +plus a JRC to enable them @item @file{target/str912.cfg} -- with flash, CPU, and boundary scan @item @file{target/ti_dm355.cfg} -- with ETM, ARM, and JRC (this JRC is not currently used) @@ -1277,7 +1423,9 @@ is not currently used) After adding a TAP for a CPU, you should set it up so that GDB and other commands can use it. @xref{CPU Configuration}. -For the at91sam7 example above, the command can look like this: +For the at91sam7 example above, the command can look like this; +note that @code{$_ENDIAN} is not needed, since OpenOCD defaults +to little endian, and this chip doesn't support changing that. @example set _TARGETNAME $_CHIPNAME.cpu @@ -1352,42 +1500,6 @@ Examples: @item pxa270 - again - CS0 flash - it goes in the board file. @end itemize -@node About JIM-Tcl -@chapter About JIM-Tcl -@cindex JIM Tcl -@cindex tcl - -OpenOCD includes a small ``TCL Interpreter'' known as JIM-TCL. You can -learn more about JIM here: @url{http://jim.berlios.de} - -@itemize @bullet -@item @b{JIM vs. Tcl} -@* JIM-TCL is a stripped down version of the well known Tcl language, -which can be found here: @url{http://www.tcl.tk}. JIM-Tcl has far -fewer features. JIM-Tcl is a single .C file and a single .H file and -impliments the basic Tcl command set along. In contrast: Tcl 8.6 is a -4.2 MB .zip file containing 1540 files. - -@item @b{Missing Features} -@* Our practice has been: Add/clone the real Tcl feature if/when -needed. We welcome JIM Tcl improvements, not bloat. - -@item @b{Scripts} -@* OpenOCD configuration scripts are JIM Tcl Scripts. OpenOCD's -command interpreter today is a mixture of (newer) -JIM-Tcl commands, and (older) the orginal command interpreter. - -@item @b{Commands} -@* At the OpenOCD telnet command line (or via the GDB mon command) one -can type a Tcl for() loop, set variables, etc. - -@item @b{Historical Note} -@* JIM-Tcl was introduced to OpenOCD in spring 2008. - -@item @b{Need a crash course in Tcl?} -@*@xref{Tcl Crash Course}. -@end itemize - @node Daemon Configuration @chapter Daemon Configuration @cindex initialization @@ -1428,6 +1540,7 @@ read/write memory on your target, @command{init} must occur before the memory read/write commands. This includes @command{nand probe}. @end deffn +@anchor{TCP/IP Ports} @section TCP/IP Ports @cindex TCP port @cindex server @@ -2572,6 +2685,7 @@ SRST, to avoid a issue with clearing the debug registers. This is fixed in Fury Rev B, DustDevil Rev B, Tempest; these revisions will be detected and the normal reset behaviour used. @end itemize +@item @code{fa526} -- resembles arm920 (w/o Thumb) @item @code{feroceon} -- resembles arm926 @item @code{mips_m4k} -- a MIPS core. This supports one variant: @itemize @minus @@ -3022,11 +3136,12 @@ bank'', and the GDB flash features be enabled. @end enumerate Many CPUs have the ablity to ``boot'' from the first flash bank. -This means that misprograming that bank can ``brick'' a system, +This means that misprogramming that bank can ``brick'' a system, so that it can't boot. JTAG tools, like OpenOCD, are often then used to ``de-brick'' the board by (re)installing working boot firmware. +@anchor{NOR Configuration} @section Flash Configuration Commands @cindex flash configuration @@ -3259,11 +3374,68 @@ flash bank aduc702x 0 0 0 0 $_TARGETNAME @end example @end deffn +@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 +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 +readers/updaters: Please remove this worrysome comment after other +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. + +@example +# Flash bank 0 - all chips +flash bank at91sam3 0x000080000 0 1 1 $_TARGETNAME +# Flash bank 1 - only 256K chips +flash bank at91sam3 0x000100000 0 1 1 $_TARGETNAME +@end example + +Internally, the AT91SAM3 flash memory is organized as follows: + +@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. +@end itemize + +The AT91SAM3 driver adds an additional command: + +@deffn Command {at91sam3 gpnvm set|clear|show all|NUMBER} +This command allows you to set, clear, or show the state of the GPNVM bits. +@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 +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 +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}. +@end deffn + +@deffn Command {at91sam3 slowclk [VALUE]} +This command shows/sets the slow clock frequency used in the +@b{at91sam3 info} command calculations above. +@end deffn + +@end deffn + @deffn {Flash Driver} at91sam7 -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. +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 @@ -3304,7 +3476,6 @@ 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. @@ -3715,6 +3886,7 @@ is larger than 0xffffffff, the largest 32-bit unsigned integer.) Some larger devices will work, since they are actually multi-chip modules with two smaller chips and individual chipselect lines. +@anchor{NAND Configuration} @section NAND Configuration Commands @cindex NAND configuration