BSP and standalone drivers

Understand the embedded C library, BSP structure and the two driver levels used by a Vitis application.

What the BSP provides

An embedded application should not guess the hardware configuration. The Board Support Package describes the services available to one processor and one software domain.

A standalone domain targets a bare-metal application. The program runs directly on the processor, without a complete operating system. The BSP therefore supplies the minimum startup code, libraries and drivers required by that application.

In Vitis, a platform associates the XSA file with one or more domains. Each domain selects a processor, an operating system and a BSP. A hardware change therefore requires the platform to be updated before the application is rebuilt.

The standalone C library relies on Newlib, a compact implementation of the standard C library for embedded systems. It supplies common functions such as memcpy, printf and dynamic allocation. Calls that normally depend on an operating system must be adapted to the platform.

Reading xparameters.h

xparameters.h is generated from the exported hardware. It contains base addresses, device identifiers, interrupt identifiers and some clock frequencies.

#include "xparameters.h"
 
#define LED_BASEADDR XPAR_FPT_LED_BANK_BASEADDR
#define TIMER_ID     XPAR_XTTCPS_0_DEVICE_ID

These symbols are safer than hard-coded addresses. They are tied to the instance names in the Block Design. After an IP or address change, regenerate the XSA and BSP.

Level 0 and level 1 drivers

Level 0 supplies register-oriented macros. It is compact, but the program must know the base address and offsets.

void leds_write(UINTPTR base, u32 value)
{
    XGpio_WriteReg(base, XGPIO_TRI_OFFSET, 0x0U);
    XGpio_WriteReg(base, XGPIO_DATA_OFFSET, value & 0xFFU);
}

Level 1 uses an instance structure. A lookup function retrieves the configuration and an initialization function binds it to the software object.

XGpio gpio;
 
int gpio_init(void)
{
    int status = XGpio_Initialize(&gpio, XPAR_FPT_LED_BANK_DEVICE_ID);
 
    if (status != XST_SUCCESS) {
        return XST_FAILURE;
    }
 
    XGpio_SetDataDirection(&gpio, 1, 0x0U);
    return XST_SUCCESS;
}

Level 0 suits a loader, a short test or a small critical path. Level 1 makes multiple instances, callbacks and error handling easier.

Libraries and application structure

The BSP can include additional components. XilFFS provides a FAT file system for SD or eMMC. lwIP supplies a lightweight network stack. Other libraries handle Flash and storage interfaces.

Every library uses code space and may require buffers. Select it from the actual requirement and the available memory.

A reliable application checks every return value and stops when a driver cannot find its configuration.

The program below is a complete example provided by this course. init_platform() calls the preparation code defined in platform.c. Its exact behavior depends on the target and may include cache handling or 16550 UART setup. It does not automatically configure AXI GPIO, which remains the responsibility of gpio_init().

cleanup_platform() runs the shutdown code defined in platform.c, usually cache disabling in a standalone project. The program calls it on the error path and before normal return. It does not automatically release every peripheral initialized by the application.

int main(void)
{
    int status;
 
    init_platform();
    status = gpio_init();
 
    if (status != XST_SUCCESS) {
        xil_printf("GPIO initialization failed\r\n");
        cleanup_platform();
        return XST_FAILURE;
    }
 
    XGpio_DiscreteWrite(&gpio, 1, 0x55U);
    cleanup_platform();
    return XST_SUCCESS;
}

In this program, the platform code prepares only the services implemented by platform.c. The driver configures GPIO. main() then applies the application logic and handles each error before returning.

Official references

The current platform, domain and BSP structure is documented in the Vitis Embedded Software Development Guide UG1400. Official driver sources and examples are in the AMD embeddedsw repository.

Key points

The XSA describes hardware. In the Vitis platform project, the engineer creates software domains and selects their target processor. BSP generation then provides the drivers and libraries for each domain. Level 0 accesses registers directly. Level 1 provides an instance and a safer interface.

Test your knowledge - Chapter quiz