Next: About JIM-Tcl, Previous: Simple Configuration Files, Up: Top
This section/chapter is aimed at developers and integrators of OpenOCD. These are guidelines for creating new boards and new target configurations as of 28/Nov/2008.
However, you the user of OpenOCD should be some what familiar with this section as it should help explain some of the internals of what you might be looking at.
The user should find under $(INSTALLDIR)/lib/openocd the following directories:
If needed... The user in their “openocd.cfg” file or the board file might override a specific feature in any of the above files by setting a variable or two before sourcing the target file. Or adding various commands specific to their situation.
The user should be able to source one of these files via a command like this:
source [find interface/FOOBAR.cfg]
Or:
openocd -f interface/FOOBAR.cfg
A preconfigured interface file should exist for every interface in use today, that said, perhaps some interfaces have only been used by the sole developer who created it.
FIXME/NOTE: We need to add support for a variable like TCL variable tcl_platform(platform), it should be called jim_platform (because it is jim, not real tcl) and it should contain 1 of 3 words: “linux”, “cygwin” or “mingw”
Interface files should be found in $(INSTALLDIR)/lib/openocd/interface
Note: BOARD directory NEW as of 28/nov/2008
The user should be able to source one of these files via a command like this:
source [find board/FOOBAR.cfg]
Or:
openocd -f board/FOOBAR.cfg
The board file should contain one or more source [find target/FOO.cfg] statements along with any board specific things.
In summery the board files should contain (if present)
The user should be able to source one of these files via a command like this:
source [find target/FOOBAR.cfg]
Or:
openocd -f target/FOOBAR.cfg
In summery the target files should contain
By default, the end user should never need to set these variables. However, if the user needs to override a setting they only need to set the variable in a simple way.
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
If the chip has 2 targets, use the names _TARGETNAME0, _TARGETNAME1, ... etc.
Remember: The “board file” may include multiple targets.
At no time should the name “target0” (the default target name if none was specified) be used. The name “target0” is a hard coded name - the next target on the board will be some other number.
The user (or board file) should reasonably be able to:
source [find target/FOO.cfg]
$_TARGETNAME configure ... FOO specific parameters
source [find target/BAR.cfg]
$_TARGETNAME configure ... BAR specific parameters
The Full Tcl/Tk language supports “namespaces” - JIM-Tcl does not.
Thus the rule we follow in OpenOCD is this: Variables that begin with a leading underscore are temporal in nature, and can be modified and used at will within a ?TARGET? configuration file
EXAMPLE: The user should be able to do this:
# 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
All target configuration files should start with this (or a modified form)
# SIMPLE example
if { [info exists CHIPNAME] } {
set _CHIPNAME $CHIPNAME
} else {
set _CHIPNAME sam7x256
}
if { [info exists ENDIAN] } {
set _ENDIAN $ENDIAN
} else {
set _ENDIAN little
}
if { [info exists CPUTAPID ] } {
set _CPUTAPID $CPUTAPID
} else {
set _CPUTAPID 0x3f0f0f0f
}
After the “defaults” are choosen, [see above], the taps are created.
SIMPLE example: such as an Atmel AT91SAM7X256
# for an ARM7TDMI.
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0x1 -irmask 0xf -expected-id $_CPUTAPID
COMPLEX example:
This is an SNIP/example for an STR912 - which has 3 internal taps. Key features shown:
if { [info exists FLASHTAPID ] } {
set _FLASHTAPID $FLASHTAPID
} else {
set _FLASHTAPID 0x25966041
}
jtag newtap $_CHIPNAME flash -irlen 8 -ircapture 0x1 -irmask 0x1 -expected-id $_FLASHTAPID
if { [info exists CPUTAPID ] } {
set _CPUTAPID $CPUTAPID
} else {
set _CPUTAPID 0x25966041
}
jtag newtap $_CHIPNAME cpu -irlen 4 -ircapture 0xf -irmask 0xe -expected-id $_CPUTAPID
if { [info exists BSTAPID ] } {
set _BSTAPID $BSTAPID
} else {
set _BSTAPID 0x1457f041
}
jtag newtap $_CHIPNAME bs -irlen 5 -ircapture 0x1 -irmask 0x1 -expected-id $_BSTAPID
set _TARGETNAME [format "%s.cpu" $_CHIPNAME]
Tap Naming Convention
See the command “jtag newtap” for detail, but in breif the names you should use are:
Some chips have specific ways the TRST and SRST signals are managed. If these are CHIP SPECIFIC they go here, if they are BOARD SPECIFIC they go in the board file.
Work areas are small RAM areas used by OpenOCD to speed up downloads, and to download small snippits of code to program flash chips.
If the chip includes an form of “on-chip-ram” - and many do - define a reasonable work area and use the “backup” option.
PROBLEMS: On more complex chips, this “work area” may become inaccessable if/when the application code enables or disables the MMU.
If the chip has a DCC, enable it. If the chip is an arm9 with some special high speed download - enable it.
If the chip has an ARM “vector catch” feature - by defeault enable it for Undefined Instructions, Data Abort, and Prefetch Abort, if the user is really writing a handler for those situations - they can easily disable it. Experiance has shown the “vector catch” is helpful - for common programing errors.
If present, the MMU, the MPU and the CACHE should be disabled.
This applies ONLY TO MICROCONTROLLERS that have flash built in.
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 the TARGET (chip) file.
Examples: