Repository navigation
Board File Creation Guide: From Example to Custom Board
This guide walks you through creating a complete set of board data files for a new board, using the example board files as a starting point. Each XML element is explained inline and cross-referenced to the corresponding tag definition in the Vivado Design Suite User Guide (UG895).
Every board entry in the store requires exactly three files, placed in the directory boards/<VENDOR>/<BOARD_SHORT_NAME>/:
| File | Purpose |
|---|---|
board.xml |
Defines the board identity, FPGA part, peripheral components, and logical interfaces exposed to Vivado |
part0_pins.xml |
Maps every logical signal name to its physical FPGA package pin location and I/O standard |
preset.xml |
Provides default IP configuration parameters for each interface defined in board.xml
|
The example board models a Kintex-7 KC705. It is the most complete reference available and covers the majority of interface types you will encounter. Start by copying its three XML files into your own board directory:
# From the root of your cloned repository
cp -r boards/example_vendor/example_board boards/<YOUR_VENDOR>/<YOUR_BOARD>/Then edit each file to reflect your board. The sections below explain every element.
<board
schema_version="2.1"
vendor="xilinx.com"
name="Sample_kc705"
display_name="Sample Kintex-7 KC705 Evaluation Platform"
url="www.xilinx.com/kc705"
preset_file="preset.xml">| Attribute | Description |
|---|---|
schema_version |
Board file schema version. Use 2.1 for current Vivado releases. |
vendor |
Reverse-DNS vendor identifier (e.g., acme.com). Must be unique and consistent across all your boards. |
name |
Short internal identifier for this board. No spaces. |
display_name |
Human-readable board name shown in Vivado's board selection dialog. |
url |
Product page URL for reference. |
preset_file |
Name of the accompanying preset file. Always preset.xml. |
UG895 reference: Board
<images>
<image name="kc705_board.jpeg" display_name="SAMPLE KC705 BOARD" sub_type="board">
<description>KC705 Board File Image</description>
</image>
</images>Optional. Provides a board image displayed in the Vivado board selection dialog. The image file must be placed in the same directory as board.xml. Set sub_type="board".
<compatible_board_revisions>
<revision id="0">1.1</revision>
</compatible_board_revisions>Lists the physical hardware revisions of the board that this file supports. Use the revision number printed on the board's silkscreen (e.g., 1.0, 2.1). Each revision gets its own <revision> entry with a unique id starting from 0.
UG895 reference: Compatible Board Revisions
<file_version>1.5</file_version>
<description>Sample Kintex-7 KC705 Evaluation Platform</description><file_version> tracks the revision of the board data file itself (not the hardware). Increment this whenever you update the file. <description> is a free-text description of the board.
<parameters>
<parameter name="heat_sink_type" value="medium" value_type="string"/>
<parameter name="heat_sink_temperature" value_type="range" value_min="20.0" value_max="30.0"/>
</parameters>Optional board-level metadata. Common uses include heat sink type, PCB revision, and temperature ranges. Most boards do not require these. Remove the section if unused.
UG895 reference: Parameters
<jumpers>
<jumper name="SW13_M0" default_value="false">
<description>If true, flash_qspi is enabled instead of flash_bpi</description>
</jumper>
<jumper name="J29_P1_P2" default_value="true">
<description>Configures PHY for MII/GMII/RGMII mode</description>
</jumper>
</jumpers>Declares any hardware jumpers or DIP switches that affect which interfaces are active. These are referenced later in <enablement_dependencies> sections to conditionally enable or disable specific interfaces depending on the jumper setting.
If your board has no such mode-switching hardware, remove the section entirely.
UG895 reference: Jumpers
The <components> section is the core of board.xml. It lists every chip or connector on the board — including the FPGA itself. There are two categories:
| Component type |
type attribute |
Examples |
|---|---|---|
| FPGA | fpga |
Kintex-7, Zynq, Versal |
| Peripheral chip/connector |
chip or connector
|
DDR, Ethernet PHY, GPIO LEDs, FMC connector |
The FPGA component is always named part0 and uses type="fpga". This is the central element — all interface definitions live here.
<component name="part0"
display_name="Kintex-7 KC705 Evaluation Platform"
type="fpga"
part_name="xc7k325tffg900-2"
pin_map_file="part0_pins.xml"
vendor="xilinx"
spec_url="www.xilinx.com/kc705">
<description>FPGA part on the board</description>
<interfaces>
<!-- Interface definitions go here -->
</interfaces>
</component>| Attribute | Description |
|---|---|
part_name |
The exact Vivado part string (e.g., xc7k325tffg900-2). Must match Vivado's part database exactly. |
pin_map_file |
Always part0_pins.xml. |
UG895 reference: Components
Each <interface> inside part0 exposes one logical connection (e.g., DDR3, UART, GPIO) to Vivado's IP Catalog and IP Integrator.
<interface
mode="master"
name="rs232_uart"
type="xilinx.com:interface:uart_rtl:1.0"
of_component="rs232_uart"
preset_proc="rs232_uart_preset">| Attribute | Description |
|---|---|
mode |
master if the FPGA drives this interface; slave if it receives (e.g., clock inputs, reset). |
name |
Unique name for this interface within the board file. |
type |
AXI4-Stream/AXI/interface type identifier from Vivado's interface catalog. |
of_component |
Name of the peripheral <component> that this interface connects to. |
preset_proc |
Name of the preset function in preset.xml that configures IP for this interface. |
Common interface types:
| Interface |
type value |
|---|---|
| UART | xilinx.com:interface:uart_rtl:1.0 |
| GPIO | xilinx.com:interface:gpio_rtl:1.0 |
| GMII Ethernet | xilinx.com:interface:gmii_rtl:1.0 |
| RGMII Ethernet | xilinx.com:interface:rgmii_rtl:1.0 |
| DDR3 | xilinx.com:interface:ddrx_rtl:1.0 |
| Differential clock | xilinx.com:interface:diff_clock_rtl:1.0 |
| Reset | xilinx.com:signal:reset_rtl:1.0 |
| IIC | xilinx.com:interface:iic_rtl:1.0 |
| SPI | xilinx.com:interface:spi_rtl:1.0 |
| PCIe (7-series) | xilinx.com:interface:pcie_7x_mgt_rtl:1.0 |
UG895 reference: Interface
<preferred_ips>
<preferred_ip vendor="xilinx.com" library="ip" name="axi_uartlite" order="0"/>
</preferred_ips>Lists the Vivado IP cores that Vivado should suggest when a user connects this interface. order="0" is the default/first suggestion. You can list multiple IPs with ascending order values.
This is where you map the interface's logical signal names (as defined by the interface type standard) to the actual net names on your board.
<port_maps>
<port_map logical_port="TxD" physical_port="rs232_uart_txd" dir="out">
<pin_maps>
<pin_map port_index="0" component_pin="USB_TX"/>
</pin_maps>
</port_map>
<port_map logical_port="RxD" physical_port="rs232_uart_rxd" dir="in">
<pin_maps>
<pin_map port_index="0" component_pin="USB_RX"/>
</pin_maps>
</port_map>
</port_maps>| Attribute | Description |
|---|---|
logical_port |
Signal name as defined by the interface standard (e.g., TxD, RxD for UART). |
physical_port |
The net name as it appears in your design's top-level port list. You choose this name. |
dir |
Signal direction from the FPGA's perspective: in, out, or inout. |
left / right
|
For buses, specifies the bit range (e.g., left="7" right="0" for 8-bit). |
port_index |
Bit index within the bus (0-based). |
component_pin |
The logical signal name defined in part0_pins.xml that maps to the physical package pin. |
If an interface is only active when certain jumpers are set, declare its dependencies here. Vivado will show or hide the interface based on the jumper state.
<enablement_dependencies>
<jumpers>
<jumper name="SW13_M0">true</jumper>
<jumper name="SW13_M1">false</jumper>
</jumpers>
</enablement_dependencies>If your board does not have mode-switching jumpers, omit this element entirely.
Each peripheral chip or connector on the board (DDR, Ethernet PHY, LED bank, etc.) gets its own <component> entry. These are simpler than the FPGA component — they declare the chip's identity and any mode-specific behavior.
Simple component (no modes):
<component name="led_8bits"
display_name="LED"
type="chip"
sub_type="led"
major_group="General Purpose Input or Output">
<description>LEDs 7 to 0, Active High</description>
</component>Component with modes (e.g., Ethernet PHY that supports GMII/SGMII/RGMII):
<component name="phy_onboard"
display_name="Onboard PHY"
type="chip"
sub_type="ethernet"
major_group="Ethernet Configurations"
part_name="M88E1111_BAB1C000"
vendor="Marvell"
spec_url="www.marvell.com">
<description>PHY on the board</description>
<component_modes>
<component_mode name="gmii" display_name="GMII mode">
<description>Requires jumpers J29_P1_P2=true, J30_P1_P2=true, J64=false</description>
<interfaces>
<interface name="gmii"/>
<interface name="mdio_mdc"/>
<interface name="phy_reset_out" optional="true"/>
</interfaces>
<preferred_ips>
<preferred_ip vendor="xilinx.com" library="ip" name="axi_ethernet" order="0"/>
</preferred_ips>
</component_mode>
</component_modes>
</component>Common sub_type values: ddr, ethernet, led, push_button, switch, uart, system_clock, mgt_clock, system_reset, memory_flash_bpi, memory_flash_qspi, sfp, connector, fmc_lpc, fmc_hpc.
UG895 reference: Component Modes
<jtag_chains>
<jtag_chain name="chain1">
<position name="0" component="part0"/>
</jtag_chain>
</jtag_chains>Declares the JTAG scan chain. For single-FPGA boards, this is always a single chain with part0 at position 0. If other devices (e.g., a second FPGA or JTAG bridge) are in the chain, add them as additional <position> entries.
UG895 reference: JTAG Chains
<connections>
<connection name="part0_rs232_uart" component1="part0" component2="rs232_uart">
<connection_map name="part0_rs232_uart_1" typical_delay="5"
c1_st_index="94" c1_end_index="95"
c2_st_index="0" c2_end_index="1"/>
</connection>
</connections>Declares the physical wiring between the FPGA (component1) and peripheral chips/connectors (component2). The index ranges (c1_st_index through c1_end_index, c2_st_index through c2_end_index) refer to the index attributes of <pin> entries in part0_pins.xml and in the peripheral component's <pins> list, respectively.
For simple chips with no explicit <pins> in the component definition, the indices are sequential starting from 0.
typical_delay, min_delay, and max_delay are optional routing delay hints in nanoseconds.
UG895 reference: Connections
<ip_associated_rules>
<ip_associated_rule name="default">
<ip vendor="xilinx.com" library="ip" name="axi_ethernet" version="*"
ip_interface="mgt_clk">
<associated_board_interfaces>
<associated_board_interface name="sgmii_mgt_clk" order="1"/>
<associated_board_interface name="sma_mgt_clk" order="0"/>
</associated_board_interfaces>
</ip>
</ip_associated_rule>
</ip_associated_rules>Optional. Guides Vivado's IP Integrator to automatically suggest the correct board interface when a user instantiates a specific IP core. Most boards do not need this section unless you want to fine-tune interface auto-connection behavior. Remove it if unused.
UG895 reference: IP Associated Rules
This file maps every logical signal name used in board.xml's <pin_map component_pin="..."> references to the actual physical FPGA package pin and its I/O standard.
<part_info part_name="xc7k325tffg900-2">
<pins>
<!-- pin entries -->
</pins>
</part_info>part_name must exactly match the part_name attribute on the part0 component in board.xml.
<pin index="94" name="USB_TX" loc="K24"/>
<pin index="95" name="USB_RX" loc="M19"/>
<pin index="130" name="SYSCLK_P" iostandard="DIFF_SSTL15" loc="AD12"/>
<pin index="131" name="SYSCLK_N" iostandard="DIFF_SSTL15" loc="AD11" diff_term="true"/>
<pin index="26" name="IIC_SCL_MAIN" iostandard="LVCMOS25" loc="K21" drive="8" slew="SLOW"/>| Attribute | Required | Description |
|---|---|---|
index |
Yes | Sequential integer, unique per pin. Referenced by c1_st_index/c1_end_index in <connections>. |
name |
Yes | Logical signal name. Must exactly match component_pin values used in board.xml. |
loc |
Yes | Physical package pin location (e.g., K24). From the board schematic or XDC constraints. |
iostandard |
No* | I/O standard (e.g., LVCMOS25, DIFF_SSTL15, LVDS). Required for most pins. Can be omitted when it is specified in the component's <pins> section instead. |
drive |
No | Drive strength in mA (e.g., 8, 12). For outputs only. |
slew |
No | Output slew rate: SLOW or FAST. |
diff_term |
No | Set "true" to enable on-chip differential termination for differential input pairs. |
Tip: Pins in a differential pair should be consecutive index entries. The positive (
_P) and negative (_N) sides of a clock or data pair must both be declared.
UG895 reference: Pins
The preset file provides default IP parameter values that Vivado applies when a user connects an IP core to a board interface via IP Integrator. For example, the DDR3 preset pre-fills the MIG configuration with the correct memory part, data width, and timing parameters for the specific DRAM chip on your board.
Each <ip_preset> block in the file corresponds to a preset_proc attribute value declared on an <interface> in board.xml.
<ip_presets schema="1.0">
<ip_preset preset_proc_name="rs232_uart_preset">
<ip vendor="xilinx.com" library="ip" name="axi_uartlite" version="*">
<user_parameters>
<user_parameter name="CONFIG.C_BAUDRATE" value="9600"/>
<user_parameter name="CONFIG.C_DATA_BITS" value="8"/>
</user_parameters>
</ip>
</ip_preset>
</ip_presets>For each interface that has a preset_proc attribute in board.xml, create a matching <ip_preset> block in preset.xml. The preset_proc_name must match exactly.
UG895 reference: Understanding Preset Files
Before running the linter or opening a pull request, verify the following:
| Check | What to look for |
|---|---|
| Part name |
part_name in board.xml and part0_pins.xml match exactly and are valid Vivado part strings |
| Pin names | Every component_pin value in board.xml's <pin_map> entries exists as a name in part0_pins.xml
|
| Preset coverage | Every preset_proc value in board.xml has a matching preset_proc_name in preset.xml
|
| Index continuity |
part0_pins.xml indices are sequential and match the c1_st_index/c1_end_index ranges in <connections>
|
| Interface types | All type attributes in <interface> use valid Vivado interface type strings |
| No debug artifacts | No .log, .jou, or .str files in the directory |
Run the Board File Linter on all three files after making changes:
# In the Vivado Tcl Console
set_param board.repoPaths [list <path_to_your_board_directory>]
xhub::refresh_catalog [xhub::get_xstores xilinx_board_store]
report_property [lindex [xhub::get_xitems *<YOUR_BOARD_SHORT_NAME>*] 0]For complete linter usage instructions, see Steps to Use the Board File Linter.