PYNQ.cpp C++ API

This section documents the PYNQ.cpp C++ API, which is used in PYNQ.remote to provide a Python interface from a networked host machine to the PYNQ platform.

This C++ code handles low-level operations such as device management, memory-mapped I/O, and buffer management. The following classes provide device abstraction, MMIO, and remote buffer management for supported AMD PYNQ-enabled platforms, and can be used in independent C++ applications on PYNQ devices.

Device Class

class Device

Contains functionality for managing the PYNQ device. Interacts with the local filesystem and device drivers.

Public Functions

Device()

void set_bitstream_attrs(const std::string &binfile_name, bool partial)

Sets the name of the file to be downloaded to the device. This is to be run before the download function.

Parameters:

binfile_name – Name of the bitstream (.bin) file.
partial – Indicates if the bitstream is partial. Partial Bitstreams are used for dynamic partial reconfiguration and are not yet tested.

std::pair<std::string, bool> get_bitstream_attrs() const

Gets attributes for the bitstream file. Use this function to confirm the bitstream file name and partial flag before downloading.

Returns:: A pair containing the name of the bitstream file that is stored in the device object, and the partial bitstream flag.

bool download(std::string binfile_name)

Downloads the bitstream data to the FPGA. Ensure that the file exists in /lib/firmware by using write_to_file().

Parameters:: binfile_name – Name of the bitstream file.
Returns:: True if the download is successful, false otherwise. Will return {filename} does not exist if the file is not found in /lib/firmware.

Private Functions

void write_to_file(const std::string &filename, const std::string &content)

Writes content to a file. Writes the given content to the specified filepath.

Parameters:

filename – Name of the file.
content – Content to write.

Private Members

std::string binfile_name: Name of the bitstream file.

bool partial: Indicates if the bitstream is partial.

const std::string FIRMWARE: Directory for bitstream files.

const std::string BS_FPGA_MAN: FPGA manager firmware path.

const std::string BS_FPGA_MAN_FLAGS: FPGA manager flags path.

MMIO Class

class MMIO

Manages memory-mapped I/O (MMIO) operations. Each instance of this class represents a memory-mapped region for reading and writing data.

Public Functions

MMIO(off_t base_address, size_t length_p)

Constructor for MMIO. Initializes memory mapping for the given base address and length.

Parameters:

base_address – Base address for memory mapping.
length_p – Length of the memory region.

~MMIO(): Destructor for MMIO. Cleans up memory mapping and file descriptor.

uint32_t read(uint64_t offset)

Reads a 32-bit value from the mapped memory.

Parameters:: offset – Offset from the base address.
Returns:: 32-bit value read from memory.

void write(uint32_t data, uint64_t offset)

Writes a 32-bit value to the mapped memory.

Parameters:

data – 32-bit value to write.
offset – Offset from the base address.

Private Members

int mem_fd: File descriptor for memory access.

off_t virt_base: Base address for virtual memory.

off_t virt_offset: Offset from the base address.

size_t length: Length of the memory region.

void *mapped_base: Pointer to the mapped memory region.

BufferRemote Class

class BufferRemote

A class that provides an interface for individual contiguous memory buffers using the XrtBufferManager.

This class provides an instance to of contiguous memory buffers, including wrapped functionality for buffer allocation, synchronization, and cache management. This class is designed to be used with the XrtBufferManager, which manages the underlying buffer operations on the XRT device.

Param size:: A value representing the shape of the buffer in bytes.
Param dtype:: A string representing the data type of the buffer elements.
Param xrt_manager:: A reference to the XrtBufferManager for buffer management.
Param cacheable:: A boolean indicating if the buffer is cacheable.

Public Functions

BufferRemote(const size_t size, const std::string &dtype, XrtBufferManager &xrt_manager, bool cacheable)

Constructor for BufferRemote. This class wraps the XRT buffer management functionality and provides a convenient interface for buffer operations.

Create an instance of this class and provide the XrtBufferManager, and a buffer will be allocated on the device. The data_ member of this instance will point to the memory mapped region of the allocated buffer, allowing for direct access to the buffer data. This class includes some other functions to wrap management of the individual buffers, such as flushing, invalidating, and synchronizing the buffer to/from the device.

Parameters:

size – A value representing the size of the buffer in bytes.
dtype – A string representing the data type of the buffer elements.
xrt_manager – A reference to the XrtBufferManager for buffer management.
cacheable – A boolean indicating if the buffer is cacheable.

~BufferRemote(): Destructor for BufferRemote.

uintptr_t virtual_address() const

Get the virtual address of the buffer.

Returns:: The virtual address of the buffer.

uint64_t physical_address() const

Get the physical address of the buffer.

Returns:: The physical address of the buffer.

void flush(): Flush the buffer to ensure data is written to the device.

void invalidate(): Invalidate the buffer to ensure data is read from the device.

void sync_to_device(): Synchronize the buffer to the device.

void sync_from_device(): Synchronize the buffer from the device.

void free(): Free the buffer resources.

bool cacheable()

Check if the buffer is cacheable.

Returns:: True if the buffer is cacheable, false otherwise.

Public Members

size_t size_

uint8_t *data_

bool cacheable_

Private Functions

size_t get_element_size(const std::string &dtype)

Get the size of an element based on its data type.

Parameters:: dtype – The data type of the element.
Returns:: The size of the element.

Private Members

std::vector<size_t> shape_

size_t element_size_

XrtBufferManager &manager_

xrt::bo bo_

bool freed_

XrtBufferManager Class

class XrtBufferManager

Manages buffer operations for XRT (Xilinx Runtime) devices.

This class provides methods to allocate, free, write, read, map, and manage properties of contiguous memory buffers on XRT devices. It also provides methods for flushing and invalidating the contents of buffers to ensure data consistency between the host and device. Initialise it with the device handle obtained from xrt::device::open() or similar methods.

This class is designed to be used by the BufferRemote class, which provides a higher-level interface for managing individual buffers.

Public Functions

XrtBufferManager(const xrt::device &device_p)

Constructs a new XrtBufferManager object. Use this constructor to initialize the buffer manager with a specific XRT device obtained from xrt::device::open() or similar methods.

Parameters:: device – The handle to the XRT device.

xrt::bo allocate_bo(size_t size, bool cacheable)

Allocates a buffer object (BO) on the device.

Parameters:

size – The size of the buffer to allocate in bytes.
cacheable – Indicates if the buffer should have the cacheable flag enabled.

Returns:

The handle to the allocated buffer.

void free_bo(xrt::bo &bo)

Frees a previously allocated buffer object (BO).

Parameters:

bo – The handle to the buffer to free.
nbytes – The size of the buffer.
virtual_address – The virtual address of the buffer.

void write_bo(xrt::bo &bo, const uint8_t *data, size_t size)

Writes data to a buffer object (BO).

Parameters:

bo – The handle to the buffer.
data – The data to write to the buffer.
size – The size of the data to write.

std::vector<uint8_t> read_bo(xrt::bo &bo, size_t size)

Reads data from a buffer object (BO).

Parameters:

bo – The handle to the buffer.
size – The size of the data to read in bytes.

Returns:

A vector containing the read data.

char *map_bo(xrt::bo &bo, bool write = false)

Maps a buffer object (BO) to the host’s address space.

Parameters:

bo – The handle to the buffer.
write – Indicates if the buffer should be mapped for writing.

Returns:

A pointer to the mapped buffer.

xrt::memory_group get_bo_properties(const xrt::bo &bo) const

Retrieves the memory_group of a buffer object (BO).

Parameters:: bo – The handle to the buffer.
Returns:: The memory_group of the buffer.

void flush_bo(xrt::bo &bo)

Flushes the contents of a buffer object (BO) to the device.

Parameters:: bo – The handle to the buffer.

void invalidate_bo(xrt::bo &bo)

Invalidates the contents of a buffer object (BO) in the cache.

Parameters:: bo – The handle to the buffer.

Private Members

xrt::device device