From 1017e62c97fd84e5c171474d3b3b35ec8f68bf6e Mon Sep 17 00:00:00 2001 From: zwelch Date: Mon, 22 Jun 2009 22:36:53 +0000 Subject: David Brownell : This should be my last significant update of the User's Guide for this release. Mostly it's a rework of the config file chapter's presentation of board and target config files. - Give the new path for scripts! - Move board-config material out of the target-config section - Add more board-config info, notably for reset-init events - Link out of the board-config section to NAND, NOR, and Reset chapters - Emphasize target input vs. output naming conventions - Other textual improvements Plus some other updates, like adding my copyright (now that I've basically rewritten much of this). git-svn-id: svn://svn.berlios.de/openocd/trunk@2354 b42882b7-edfa-0310-969c-e2dbd0fdcd60 --- doc/openocd.texi | 363 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 235 insertions(+), 128 deletions(-) (limited to 'doc') diff --git a/doc/openocd.texi b/doc/openocd.texi index 36e3616a..b443ce3b 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 @@ -943,6 +944,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 +1020,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 +1050,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 +1065,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. -Board config files should be able to source one or more -target config files via a command like this: +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 + +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 +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. -source [find target/BAR.cfg] -$_TARGETNAME configure ... BAR specific parameters -@end example - -@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 +1316,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 +1350,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 +1379,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 @@ -1428,6 +1532,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 @@ -3023,11 +3128,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 @@ -3716,6 +3822,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 -- cgit v1.2.3