OPAE Python API Reference

The reference documentation for the OPAE Python API and is grouped into the following sections:

Module Types, Methods, and Constants

opae.fpga.allocate_shared_buffer(arg0: opae.fpga._opae.handle, arg1: int) → opae::fpga::types::shared_buffer

shared_buffer factory method - allocate a shared buffer object. Args:

handle: An accelerator handle object that identifies an open accelerator obect to share the buffer with. len: The length in bytes of the requested buffer.

opae.fpga.enumerate(*args, **kwargs)

Overloaded function.

1. enumerate(arg0: List[opae.fpga._opae.properties]) -> List[opae::fpga::types::token]

   Get a list of tokens for the given search criteria.

   Args:

   props(list): A list of properties objects that define the search criteria.

   All OPAE properties in each properties object make up one filter. All properties objects are combined in a union.

2. enumerate(**kwargs) -> List[opae::fpga::types::token]

   Get a list of tokens from zero or one filters as defined by kwargs. If kwargs is empty, then no filter is used. If kwargs is not empty, then one properties object is created using the kwargs.

opae.fpga.errors(arg0: opae.fpga._opae.token) → List[opae.fpga._opae.error]

Get a list of error objects in an FPGA resource. Each error object represents an error register contained in the resource.

Args:

tok(token): Token representing an FPGA resource.

opae.fpga.open(tok: opae.fpga._opae.token, flags: int = 0) → opae::fpga::types::handle

Create a new handle object from a token.

opae.fpga.register_event(handle: opae.fpga._opae.handle, event_type: opae.fpga._opae.fpga_event_type, flags: int = 0) → opae::fpga::types::event

Factory method used to create events registered to a particular event type.

Args:

handle: A handle to an OPAE resource. type(fpga_event_type): The event type to register for. Valid event types are:

EVENT_ERROR, EVENT_INTERRUPT, EVENT_POWER_THERMAL

flags: Event registration flags that control registration behavior.

Fundamental Types

Properties

class opae.fpga.properties

properties class is a container class for OPAE resource properties.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: opae.fpga._opae.properties, **kwargs) -> None

   Create a new properties object. If kwargs is not included then the properties object is created with no property values set. If one of the kwargs keys is an OPAE property name then the kwargs value is used to initialize the corresponding value in the properties object.

   Kwargs:

   parent (token): Token object representing parent resource.

   guid (str): GUID (as a string) of the resource.

   type (fpga_objtype): The object type - DEVICE or ACCELERATOR.

   segment (uint16_t) : The PCIe segment (or domain) number.

   bus (uint8_t) : The PCIe bus number.

   device (uint8_t) : The PCIe device number.

   function (uint8_t) : The PCIe function number.

   socket_id (uint8_t): The socket ID encoded in the FIM.

   num_slots (uint32_t): Number of slots available in the FPGA.

   num_errors (uint32_t): Number of error registers in the resource.

   bbs_id (uint64_t): The BBS ID encoded in the FIM.

   bbs_version (tuple): The version of the BBS.

   vendor_id (uint16_t): The vendor ID in PCI config space.

   device_id (uint16_t): The device ID in PCI config space.

   model (str): The model of the FPGA.

   local_memory_size (uint64_t): The size (in bytes) of the FPGA local memory.

   num_mmio (uint32_t): The number of mmio spaces.

   num_interrupts (uint32_t): The number of interrupts supported by an accelerator.

   accelerator_state (fpga_accelerator_state): The state of the accelerator - ASSIGNED or UNASSIGNED.

   object_id (uint64_t): The 64-bit number unique within a single node or system.

   interface (fpga_interface): The interface type - IFC_DFL, IFC_VFIO, or IFC_SIM.

2. __init__(self: opae.fpga._opae.properties, arg0: opae::fpga::types::token) -> None

   Get properties from a token object. Args:

   tok (token): The token to read properties from.

3. __init__(self: opae.fpga._opae.properties, arg0: opae::fpga::types::handle) -> None

   Get properties from a handle object. Args:

   h (handle): The handle to read properties from.

property accelerator_state

Get or set the state of an accelerator. The accelerator state is of type fpga_accelerator_state.

property bbs_id

Get or set the BBS ID property of a resource. The resource must be of type DEVICE

property bbs_version

Get or set the BBS version property of a resource. The resource must be of type DEVICE

property bus

Get or set the PCIe bus property of a resource.

property capabilities

Get or set the capabilities property of a resource. This is taken directly from the capabilities CSR in the FIM.

property device

Get or set the PCIe device property of a resource.

property function

Get or set the PCIe function property of a resource.

property model

Get or set the model property of a resource.

property num_interrupts

Get or set the number of interrupt vectors supported by a resource.

property num_mmio

Get or set the number of mmio spaces in a resource.

property num_slots

Get or set the number of slots property of a resource. The resource must be of type DEVICE

property object_id

Get or set the Object ID property of a resource. The object id is a 64-bit identifier that is unique within a single node or system. I represents a similar concept as the token but can be serialized for use across processes

property parent

Get or set the token representing a parent object of a resource. The resource must be of type ACCELERATOR

property socket_id

Get or set the Socket ID property of a resource. The socket id is encoded in of the FIM CSRs

property vendor_id

Get or set the vendor ID property of a resource. The vendor ID is part of the PCI ID and is assigned by the PCI SIG consortium.

Token

class opae.fpga.token

Token for referencing an OPAE resource.

A token object serves as a reference so a specific resource in the system. Holding a token does not constitute ownership of an OPAE resource. It is used to query information about a resource, or to acquire ownership by calling fpga.open module method.

find(self: opae.fpga._opae.token, name: str, flags: int = <fpga_sysobject_flags.SYSOBJECT_GLOB: 2>) → opae::fpga::types::sysobject

Find a sysobject instance from a valid token object. Args:

flags: Flags that control behavior of finding sub-objects. SYSOBJECT_GLOB is used to indicate that wildcard patterns (*) are allowed. SYSOBJECT_RECURSE_ONE is used to indicate that the find routine should recurse one level. SYSOBJECT_RECURSE_ALL is used to indicate that the find routine should recurse to all children.

Handle

class opae.fpga.handle

__enter__(self: opae.fpga._opae.handle) → opae.fpga._opae.handle

Context manager protocol enter function. Simply returns the handle object.

__exit__(self: opae.fpga._opae.handle, *args) → None

Context manager protocol exit function. Closes the resource identified by this handle and currently does nothing with the exit arguments.

close(self: opae.fpga._opae.handle) → opae.fpga._opae.fpga_result

“Close an accelerator associated with handle.”

read_csr32(self: opae.fpga._opae.handle, offset: int, csr_space: int = 0) → int

Read 32 bits from a CSR belonging to a resource associated with a handle. Args:

offset: The register offset. csr_space: The CSR space to read from. Default is 0.

read_csr64(self: opae.fpga._opae.handle, offset: int, csr_space: int = 0) → int

Read 64 bits from a CSR belonging to a resource associated with a handle. Args:

offset: The register offset. csr_space: The CSR space to read from. Default is 0.

reset(self: opae.fpga._opae.handle) → None

Reset the accelerator associated with this handle. The accelerator must be opened.

write_csr32(self: opae.fpga._opae.handle, offset: int, value: int, csr_space: int = 0) → None

Write 32 bits to a CSR belonging to a resource associated with a handle. Args:

offset: The register offset. value: The 32-bit value to write to the register. csr_space: The CSR space to write from. Default is 0.

write_csr64(self: opae.fpga._opae.handle, offset: int, value: int, csr_space: int = 0) → None

Write 64 bits to a CSR belonging to a resource associated with a handle. Args:

offset: The register offset. value: The 64-bit value to write to the register. csr_space: The CSR space to write from. Default is 0.

Event

class opae.fpga.event

event object are used to register for OPAE events. Currently, the event types are:

EVENT_ERROR EVENT_INTERRUPT EVENT_POWER_THERMAL

os_object(self: opae.fpga._opae.event) → int

Get an OS specific object from the event which can be used to subscribe for events. On Linux, the object corresponds to a file descriptor that can be used with select/poll/epoll calls.

Shared Buffer

class opae.fpga.shared_buffer

shared_buffer represents a system memory buffer that can be shared with the accelerator. It implements the Python buffer protocol and can be converted to a native bytearray object.

compare(self: opae.fpga._opae.shared_buffer, arg0: opae.fpga._opae.shared_buffer, arg1: int) → int

Compare this shared_buffer (the first len bytes) object with another one. Returns 0 if the two buffers (up to len) are equal.

fill(self: opae.fpga._opae.shared_buffer, arg0: int) → None

Fill the buffer with a given value.

Args:

value: The value to use when filling the buffer.

io_address(self: opae.fpga._opae.shared_buffer) → int

Get the address of the buffer suitable for programming into the accelerator device.

size(self: opae.fpga._opae.shared_buffer) → int

Get the length of the buffer in bytes.

wsid(self: opae.fpga._opae.shared_buffer) → int

Get the underlying buffer’s workspace ID.

Error

class opae.fpga.error

error object is used to represent an error register in an FPGA resource. It holds two read-only properties, name and can_clear and it can also be used to read the raw register value from its corresponding error register.

property can_clear

Indicates if the error register can be cleared - read-only property

property name

Error register name - read-only property

read_value(self: opae.fpga._opae.error) → int

Read the raw value from the error register.

SysObject

class opae.fpga.sysobject

Wraps the OPAE fpga_object primitive as a Python object.

__getattr__(self: opae.fpga._opae.sysobject, arg0: str) → opae.fpga._opae.sysobject

Get a sysobject instance from a valid sysobject. The parent sysobject must be a container type object.

__getitem__(*args, **kwargs)

Overloaded function.

1. __getitem__(self: opae.fpga._opae.sysobject, arg0: str) -> opae.fpga._opae.sysobject

   Get a sysobject instance from a valid sysobject. The parent sysobject must be a container type object.

2. __getitem__(self: opae.fpga._opae.sysobject, arg0: int) -> object

   Get a byte from the sysobject at a given index. Raises RuntimeError if the sysobject instance is a container type.

3. __getitem__(self: opae.fpga._opae.sysobject, arg0: slice) -> str

   Get a slice of bytes from the sysobject at a given offset. Raises RuntimeError if the sysobject instance is a container type.

bytes(self: opae.fpga._opae.sysobject) → str

Get bytes from the sysobject. Raises RuntimeError if the sysobject instance is a container type.

find(self: opae.fpga._opae.sysobject, name: str, flags: int = 0) → opae.fpga._opae.sysobject

Find a sysobject instance from a valid sysobject. The parent sysobject must be a container type object.

read64(self: opae.fpga._opae.sysobject) → int

size(self: opae.fpga._opae.sysobject) → int

write64(self: opae.fpga._opae.sysobject, arg0: int, arg1: int) → None