6.10. Board File Syntax
Prev | Chapter 6. Sourcery CodeBench Debug Sprite | Next

## 6.10. Board File Syntax

The `board-file` can be a user-written XML file to describe a non-standard board. The Sourcery CodeBench Debug Sprite searches for board files in the `arm-none-eabi/lib/boards` directory in the installation. Refer to the files in that directory for examples.

The file's DTD is:

    <!-- Board description files

         Copyright (c) 2007-2009 CodeSourcery, Inc.

         THIS FILE CONTAINS PROPRIETARY, CONFIDENTIAL, AND TRADE
         SECRET INFORMATION OF CODESOURCERY AND/OR ITS LICENSORS.

         You may not use or distribute this file without the express
         written permission of CodeSourcery or its authorized
         distributor.  This file is licensed only for use with
         Sourcery CodeBench.  No other use is permitted.
         -->

    <!ELEMENT board
    	(category?, properties?, feature?, initialize?, memory-map?, debuggerDefaults?)>

    <!-- Board category to group boards list into the tree -->
    <!ELEMENT category (#PCDATA)>

    <!ELEMENT properties
    	(description?, property*)>

    <!ELEMENT initialize
    	(write-register | write-memory | delay
    	 | wait-until-memory-equal | wait-until-memory-not-equal)* >
    <!ELEMENT write-register EMPTY>
    <!ATTLIST write-register
    		        address CDATA   #REQUIRED
                            value   CDATA   #REQUIRED
                            bits    CDATA   #IMPLIED>
    <!ELEMENT write-memory EMPTY>
    <!ATTLIST write-memory
    		        address CDATA   #REQUIRED
                            value   CDATA   #REQUIRED
                            bits    CDATA   #IMPLIED>
    <!ELEMENT delay EMPTY>
    <!ATTLIST delay
    		        time CDATA   #REQUIRED>
    <!ELEMENT wait-until-memory-equal EMPTY>
    <!ATTLIST wait-until-memory-equal
    		        address CDATA   #REQUIRED
                            value   CDATA   #REQUIRED
                            timeout CDATA   #IMPLIED
                            bits    CDATA   #IMPLIED>
    <!ELEMENT wait-until-memory-not-equal EMPTY>
    <!ATTLIST wait-until-memory-not-equal
    		        address CDATA   #REQUIRED
                            value   CDATA   #REQUIRED
                            timeout CDATA   #IMPLIED
                            bits    CDATA   #IMPLIED>

    <!ELEMENT memory-map (memory-device)*>
    <!ELEMENT memory-device (property*, description?, sectors*)>
    <!ATTLIST memory-device
                            address CDATA   #REQUIRED
    		        size    CDATA   #REQUIRED
    		        type    CDATA   #REQUIRED
                            device  CDATA   #IMPLIED>

    <!ELEMENT description (#PCDATA)>
    <!ELEMENT property (#PCDATA)>
    <!ATTLIST property name CDATA #REQUIRED>
    <!ELEMENT sectors EMPTY>
    <!ATTLIST sectors
    	size CDATA #REQUIRED
    	count CDATA #REQUIRED>

    <!-- Definition of default option values for each debug interface -->
    <!ELEMENT debuggerDefaults (debugInterface*)>
    <!ELEMENT debugInterface (option*)>
    <!ATTLIST debugInterface
    	name CDATA #REQUIRED
    >
    <!ELEMENT option EMPTY>
    <!ATTLIST option
    	name CDATA #REQUIRED
    	defaultValue CDATA #REQUIRED
    >

    <!ENTITY % gdbtarget SYSTEM "gdb-target.dtd">
    %gdbtarget;

All values can be provided in decimal, hex (with a `0x` prefix) or octal (with a `0` prefix). Addresses and memory sizes can use a `K`, `KB`, `M`, `MB`, `G` or `GB` suffix to denote a unit of memory. Times must use a `ms` or `us` suffix.

The following elements are available:

`<board>`

  This top-level element encapsulates the entire description of the board. It can contain `<properties>`, `<feature>`, `<initialize>` and `<memory-map>` elements.

`<properties>`

  The `<properties>` element specifies specific properties of the target system. This element can occur at most once. It can contain a `<description>` element.

  It can also contain `<property>` elements with the following names:

  `banked-regs`

    The `banked-regs` property specifies that the CPU of the target board has banked registers for different processor modes (supervisor, IRQ, etc.).

  `has-vfp`

    The `has-vfp` property specifies that the CPU of the target board has VFP registers.

  `system-v6-m`

    The `system-v6-m` property specifies that the CPU of the target board has ARMv6-M architecture system registers.

  `system-v7-m`

    The `system-v7-m` property specifies that the CPU of the target board has ARMv7-M architecture system registers.

  `core-family`

    The `core-family` property specifies the ARM family of the target. The body of the `<property>` element may be one of `arm7`, `arm9`, `arm11`, and `cortex`.

  `system-clock`

    This property specifies the target clock frequency (in Hertz) after reset. It is used to configure flash programming algorithms.

`<initialize>`

  The `<initialize>` element defines an initialization sequence for the board, which the Sprite performs before downloading a program. It can contain `<write-register>`, `<write-memory>` and `<delay>` elements.

`<feature>`

  This element is used to inform GDB about additional registers and peripherals available on the board. It is passed directly to GDB; see the GDB manual for further details.

`<memory-map>`

  This element describes the memory map of the target board. It is used by GDB to determine where software breakpoints may be used and when flash programming sequences must be used. This element can occur at most once. It can contain `<memory-device>` elements.

`<memory-device>`

  This element specifies a region of memory. It has four attributes: `address`, `size`, `type` and `device`. The `address` and `size` attributes specify the location of the memory device. The `type` attribute specifies that device as `ram`, `rom` or `flash`. The `device` attribute is required for `flash` regions; it specifies the flash device type. The `<memory-device>` element can contain a `<description>` element.

`<write-register>`

  This element writes a value to a control register. It has three attributes: `address`, `value` and `bits`. The `bits` attribute, specifying the bit width of the write operation, is optional; it defaults to 32.

`<write-memory>`

  This element writes a value to a memory location. It has three attributes: `address`, `value` and `bits`. The `bits` attribute is optional and defaults to 32. Bit widths of 8, 16 and 32 bits are supported. The address written to must be naturally aligned for the size of the write being done.

`<delay>`

  This element introduces a delay. It has one attribute, `time`, which specifies the number of milliseconds, or microseconds to delay by.

`<description>`

  This element encapsulates a human-readable description of its enclosing element.

`<property>`

  The `<property>` element allows additional name/value pairs to be specified. The property name is specified in a `name` attribute. The property value is the body of the `<property>` element.

Prev | Up | Next
6.9. Supported Board Files | Home | Chapter 7. Next Steps with Sourcery CodeBench