Skip to content

Board File Validation and Debugging Guide

Jump to bottom
ADubeyAMD edited this page Mar 22, 2026 · 2 revisions

This document provides a pre‑submission validation checklist for contributors adding or updating platform board files. Its goal is to help contributors identify and resolve common issues locally before opening a pull request.

This guide applies to:

  • Platform board files hosted in public GitHub repositories
  • Contributors validating board structure, metadata, and consistency
  • Pull requests that introduce new boards or update existing ones

Scope

This guide covers:

  • Required board file structure
  • Common validation failures
  • Local checks contributors can perform prior to submission

This guide does not cover:

  • CI/CD or automation pipelines
  • Tooling, paths, or enterprise processes
  • Maintainer‑only or reviewer‑specific workflows

Required Board File Structure

A valid platform board directory must contain the following files, all located in the same folder:

File Description
board.xml Primary board definition
part0_pins.xml Logical‑to‑physical pin mapping
preset.xml Predefined IP configuration values

All three files are required. If any file is missing or placed in a subdirectory, the board may not be recognized correctly.

Board File Responsibilities

board.xml

  • Declares board‑level components
  • Describes supported interfaces
  • Specifies preferred IP for implementing those interfaces
  • Maps logical interface ports to physical pins
  • Includes board identification metadata

part0_pins.xml

  • Maps logical pin names referenced by the board definition
  • Resolves them to physical device package pins

preset.xml

  • Defines default IP configuration values
  • Is applied automatically when IP is instantiated from the catalog

Pre‑Submission Validation Checklist

Use the checklist below before opening a pull request.

1. File Presence and Location

✅ Verify

  • All required files exist
  • All files are located in the same directory

Correct

boards/<vendor>/<board_name>/
├── board.xml
├── part0_pins.xml
└── preset.xml

Incorrect

  • Missing preset.xml
  • Files split across multiple subdirectories

2. Board Identification Fields (board.xml)

✅ Verify

  • Root <board> element is present
  • Required identification fields are defined:
    • Vendor
    • Board name
    • Display name
    • File / schema version
  • Compatible board revisions are explicitly listed

⚠️ Common Issue

  • Missing revision compatibility information → board may be rejected during validation

3. Interface and Port Mapping

✅ Verify

  • All declared interfaces define logical ports
  • Every logical port is mapped to a physical pin
  • No unused or orphaned interfaces remain

⚠️ Common Issue

  • Logical ports declared but never mapped → connectivity validation failures

4. Pin Mapping Consistency (part0_pins.xml)

✅ Verify

  • Every pin referenced by board.xml exists in the pins file
  • Pin names resolve to valid physical package pins

⚠️ Common Issue

  • Typographical errors or mismatches in pin names between files → I/O assignment failures

5. Preset Alignment (preset.xml)

✅ Verify

  • Presets correspond to declared interfaces
  • No unused or stale preset entries remain

⚠️ Common Issue

  • Presets defined for interfaces no longer present in the board definition

6. Debug Artifact Hygiene

🚫 Do Not Include in Commits

  • Tool‑generated logs or journals (*.log, *.jou)
  • Temporary run artifacts (*.str)
  • Backup or editor‑generated files

These files are intended for local debugging only and must never be included in a pull request.

Common Reasons Pull Requests Are Rejected

Category Typical Cause
Structure Missing required files
Mapping Unmapped logical ports
Pins Pin names not defined in pins file
Presets Stale or mismatched preset data
Hygiene Debug artifacts committed

Recommended Pre‑PR Practices

  • Run linter checks on all three xml files
  • Create correct xitem.json using Python utility script
  • Validate file structure before submission
  • Review mappings carefully after interface changes
  • Keep commits minimal and focused
  • Avoid bundling unrelated changes
  • Re‑check directory layout before pushing

Contribution Expectations

By submitting a pull request, contributors are expected to:

  • Ensure required board files are complete and consistent
  • Validate basic structure and mappings locally
  • Submit only board‑relevant content

Following this guide significantly improves review turnaround time and reduces rework.

Reference Repositories

  • Xilinx / XilinxBoardStore
    https://github.com/Xilinx/XilinxBoardStore

Clone this wiki locally