View source for How To Write a Board Configuration Script

== Overview ==

The following instructions describe how to create a very simple new [[Board Config]] and [[Target Config]] file for [[OpenOCD]].  It is a ''best case scenario'' in that documentation is readily available for the unsupported board the CPU on the board.

The following assumptions are made:
#Debugging hardware is supported by [[OpenOCD]] as described by an [[Interface Config]].  For the example below, a [[Flyswatter2]] JTAG debugger is used, described by [[flyswatter2.cfg]].
#OpenOCD is built and configured on Linux as described here: [[Compiling_OpenOCD_v06_Linux]].
#The steps to run OpenOCD on Linux have been followed as described here: [[Running_OpenOCD_on_Linux]].
#The [[PandaBoard]], [[Flyswatter2]] are both connected to your host system as described here: [[Flyswatter2_Pandaboard_How_To]].

== Step One: Information Gathering ==

Reading the [http://openocd.sourceforge.net/documentation/online-docs/ OpenOCD User Guide] Section 6.2 describes a [[Board Config]] as follows:
<pre>
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)

1. One or more source [target/...cfg] statements
2. NOR flash configuration (see [NOR Configuration], page 65)
3. NAND flash configuration (see [NAND Configuration], page 79)
4. Target reset handlers for SDRAM and I/O configuration
5. JTAG adapter reset configuration (see Chapter 9 [Reset Configuration], page 45)
6. All things that are not “inside a chip”.  

Generic things inside target chips belong in target config files, not board config files. So
for example a 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 reset-init event handler.
Define those handlers last, after you verify the rest of the board configuration works.</pre>

Sources of information you may require moving forward:
* Board Specification.  This documentation is typically provided by the manufacturer of your hardware.  For example, Texas Instruments provides the [[PandaBoard]] specification here: [http://omappedia.org/wiki/PandaBoard PandaBoard Platform Information].
* CPU, FPGA, or CPLD Specification.  This documentation is typically provided by the manufacturer of the CPU, FPGA, or CPLD silicon on the board.  For example, the 

Always verify that you have the specifications applicable to the hardware versions you are working with.  For example, this ''howto'' uses:
*PandaBoard version A1
*OMAP4430 ES2.1 silicon

== Step Two: Board Config Requirements ==

Given the [[OpenOCD]] documentation referenced above, step through each item listed and determine whether it is required in the [[Board Config]] file or can be deferred to the [[Target Config]] file.

#One or more source [target/...cfg] statements.
#:Given that the OMAP4430 CPU is not currently supported (for demonstration purposes) we can conclude that a source statement will be required in our new [[Board Config]] file.  This is a great time to start writing the config file.  In your editor of choice, open a new file called pandaboard.cfg and seed it with a few comments and the line to source the new [[Target Config]] file that you'll create later:<br/>
#:
#:  [[File:1_pandaboardcfg.png|thumb|center]]
#:
#NOR flash configuration (see [NOR Configuration], page 65).
#:The referenced section of the User Guide is for ''Chapter 12 Flash Commands''.  This would apply when NOR Flash is found on the board.  A very simple way to determine whether NOR Flash exists on a board, external of the CPU, FPGA, or CPLD is to review the board's block diagram.  For the PandaBoard, the block diagram looks like this:
#:
#:  [[File:PandaBoard_block_diagram.png|thumb|center]]
#:
#:Perusing the image, we can see that there is no NOR Flash referenced at all.  NOR Flash does not apply to this board.  This method of peripheral determination may not work in all cases.  Block Diagrams may not be available or be undecipherable.  When this is the case, leave NOR Flash statements out of the [[Board Config]].
#:
#NAND flash configuration (see [NAND Configuration], page 79).
#:The referenced section of the User Guide is for ''Chapter 13 NAND Flash Commands''.  This would apply when NAND Flash is found on the board.  Repeating the method used to locate NOR Flash, the PandaBoard proves to not have NAND Flash either.
#:
#Target reset handlers for SDRAM and I/O configuration.
#: