The RemoteDevice Class

The RemoteDevice class enables controlling PYNQ boards over network connections using gRPC. It provides a complete remote access solution including bitstream downloading, memory allocation, MMIO operations, and other PYNQ functionalities through remote procedure calls.

This module includes classes for remote memory management (RemoteBuffer), memory-mapped I/O (RemoteMMIO), bitstream handling, and communication channel management. The implementation handles multiple bitstream formats (.bit, .bin, .xsa), metadata parsing, and caching while maintaining compatibility with the local PYNQ API.

Remote devices can be configured through the PYNQ_REMOTE_DEVICES environment variable, which should contain a comma-separated list of IP addresses for target devices. Additionally, separate devices can be specified by directly passing the IP address to the RemoteDevice constructor.

The RemoteDevice class is complemented by PYNQ.cpp which operates on the target device, providing a C++ implementation of the PYNQ API. For more details on the C++ implementation, see the PYNQ.cpp module documentation.

class pynq.pl_server.remote_device.GrpcChannel(ip_addr, port)

Bases: object

gRPC Channel wrapper for remote device communication

Establishes and manages a gRPC channel connection to a remote PYNQ device. Includes connection timeout and error handling.

class pynq.pl_server.remote_device.RemoteBinfileHandler(filepath)

Bases: RemoteBitstreamHandler

get_bin_data()

Get the binary data of the bitstream in a form suitable for passing to FPGA manager

class pynq.pl_server.remote_device.RemoteBitfileHandler(filepath)

Bases: RemoteBitstreamHandler

get_bin_data()

Get the binary data of the bitstream in a form suitable for passing to FPGA manager

class pynq.pl_server.remote_device.RemoteBitstreamHandler(filepath)

Bases: BitstreamHandler

Remote bitstream handler for processing bitstreams on remote devices

Extends BitstreamHandler to handle bitstream parsing and metadata extraction for remote PYNQ devices. Uses default XCLBIN data for remote operations.

get_parser(partial: bool = False)

Returns a parser object for the remote bitstream

The returned object contains all of the data that was processed from both the HWH and Xclbin metadata attached to the object. For remote devices, uses default XCLBIN data instead of creating synthetic data.

Parameters:

partial (bool, optional) – Whether this is a partial reconfiguration bitstream. Default is False.

Returns:

parser – Parser object containing metadata, or None if parsing fails

Return type:

object or None

class pynq.pl_server.remote_device.RemoteBuffer(*args, stub, buffer_id, coherent=False, **kwargs)

Bases: ndarray

NumPy-compatible buffer for remote device memory

Extends numpy.ndarray to provide transparent access to memory buffers allocated on remote PYNQ devices. Supports all standard numpy operations while handling data transfer via gRPC automatically.

property cacheable

property device_address

flush()

freebuffer()

Free the remote buffer memory

Explicitly releases the buffer memory on the remote device. Called automatically by destructor.

invalidate()

property nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

See also

sys.getsizeof

Memory consumed by the object itself without parents in case view. This does include memory consumed by non-element attributes.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480

property physical_address

sync_from_device()

sync_to_device()

property virtual_address

class pynq.pl_server.remote_device.RemoteDevice(index, ip_addr, tag='remote{}')

Bases: Device

Device class for interacting with remote PYNQ devices via gRPC

This device enables control of remote PYNQ boards over network connections. It provides bitstream downloading, memory allocation, MMIO operations, and other PYNQ functionality through gRPC remote procedure calls.

The device supports multiple bitstream formats (.bit, .bin, .xsa) and handles metadata parsing, caching, and AXI port width configuration remotely.

allocate(shape, dtype, cacheable=0, **kwargs)

Allocate memory buffer on the remote device

Parameters:

• shape (int or tuple of int) – Shape of the buffer to allocate

• dtype (dtype) – Data type of the buffer elements

• cacheable (int, optional) – Whether buffer should be cacheable (0=non-cacheable, 1=cacheable). Default is 0.

• **kwargs – Additional keyword arguments (currently unused)

download(bitstream, parser=None)

Download bitstream to the remote FPGA device

This method handles the complete bitstream download process including: - Transferring bitstream file to remote device - Configuring FPGA manager flags - Setting AXI port widths - Generating metadata cache

Parameters:

• bitstream (object) – Bitstream object containing file and configuration information

• parser (object, optional) – Metadata parser object. If None, uses default XCLBIN parser.

exists_file(file_path)

Check if a file/directory exists on the remote device

Parameters:

file_path (str) – The path to the file on the remote device

gen_cache(bitstream, parser=None)

Generates the cache of the metadata even if no download occurred

get_arch()

Determine the architecture of the remote device

This method reads “/proc/version” on the target to determine its CPU architecture It also is used on device object creation to verify the IP address and gRPC connection to a PYNQ.remote device.

Returns:

The architecture of the remote device, either “aarch64” or “armv7l”

Return type:

str

get_bitfile_metadata(bitfile_name: str, partial: bool = False)

initial_global_state_file_boot_check()

Check and clear global state based on FPGA manager status

Reads the FPGA manager state and flags from the remote device to determine if global state should be cleared. Currently clears global state by default for remote devices.

mmap(address, length)

Create memory mapped I/O object for remote device

Parameters:

• address (int) – Base address for memory mapping

• length (int) – Length of memory region to map

Returns:

Memory mapped I/O object for remote access

Return type:

RemoteMMIO

read_file(file_path, output_as_string=True)

Read a file from the remote device

Parameters:

• file_path (str) – The path to the file on the remote device

• output_as_string (bool, optional) – If True, return the file content as bytes. If False, save the file locally. Default is True.

Returns:

If output_as_string is True, returns the file content as bytes. If output_as_string is False, returns the local filename where the file content was saved.

Return type:

bytes or str

set_axi_port_width(parser)

Set the AXI port width on the remote device

This method configures AXI port widths to resolve discrepancies between PS configurations during boot and those required by the bitstream. It is usually required for full bitstream reconfiguration.

For remote execution, register operations are performed via gRPC calls.

Check https://www.xilinx.com/support/answers/66295.html for more information on the meaning of register values.

Currently only Zynq UltraScale+ devices support data width changes.

shutdown()

Shutdown the AXI connections to the PL remotely

Prepares the programmable logic for reconfiguration by shutting down AXI connections using shutdown manager IP cores. This prevents potential issues during bitstream loading.

write_file(file_path, content)

Write content to a file on the remote device in chunks

Parameters:

• file_path (str) – The path to the file on the remote device

• content (bytes) – The content to be written to the file

class pynq.pl_server.remote_device.RemoteGPIO(gpio_index=None, direction=None)

Bases: object

Remote GPIO placeholder class

Placeholder implementation for GPIO operations on remote devices. GPIO functionality is not yet implemented for remote PYNQ devices.

static get_gpio_pin(gpio_user_index, target_label=None)

Get GPIO pin by user index

Placeholder method to prevent attribute errors in remote device context.

read()

release()

Release GPIO resources

No-op for remote GPIO placeholder

write(value)

class pynq.pl_server.remote_device.RemoteInterrupt(fullpath=None)

Bases: object

Remote Interrupt placeholder class

Placeholder implementation for interrupt handling on remote devices. Interrupt functionality is not yet implemented for remote PYNQ devices.

Parameters:

fullpath (str, optional) – Full path to interrupt device

wait(timeout=None)

class pynq.pl_server.remote_device.RemoteMMIO(stub, address, length)

Bases: object

Memory-mapped I/O for remote devices via gRPC

Provides memory-mapped I/O operations on remote PYNQ devices through gRPC remote procedure calls.

read(offset=0, length=4, word_order='little')

write(offset, data)

class pynq.pl_server.remote_device.RemoteUioController(device=None)

Bases: object

Remote UIO Controller placeholder class

Placeholder implementation for UIO (Userspace I/O) operations on remote devices. UIO functionality is not yet implemented for remote PYNQ devices.

Parameters:

device (Device, optional) – Device object for UIO operations

add_event(event, number)

class pynq.pl_server.remote_device.RemoteXsafileHandler(filepath)

Bases: RemoteBitstreamHandler

get_bin_data()

Get the binary data of the bitstream in a form suitable for passing to FPGA manager