OPAE Python API Reference¶

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

Module Types, Methods, and Constants
Fundamental Types
- Properties
- Token
- Handle
- Event
- Shared Buffer
- Error
- SysObject

Module Types, Methods, and Constants ¶

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

Overloaded function.

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.
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.open(tok: opae.fpga._opae.token, flags: int=0L) → 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=0L) → 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.

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.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.

Fundamental Types ¶

Properties ¶

class opae.fpga.properties¶

properties class is a container class for OPAE resource properties.

__init__(*args, **kwargs)¶

Overloaded function.

__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.
__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.
__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.

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

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

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

bus¶: Get or set the PCIe bus property of a resource.

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

device¶: Get or set the PCIe device property of a resource.

function¶: Get or set the PCIe function property of a resource.

model¶: Get or set the model property of a resource.

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

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

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

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

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

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

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: unicode, flags: int=0L) → 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=0L) → 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=0L) → 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=0L) → 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=0L) → 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.

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.

can_clear¶: Indicates if the error register can be cleared - read-only 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: unicode) → 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.

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

Get a sysobject instance from a valid sysobject. The parent sysobject must be a container type object.
__getitem__(self: opae.fpga._opae.sysobject, arg0: int) -> int

Get a byte from the sysobject at a given index. Raises RuntimeError if the sysobject instance is a container type.
__getitem__(self: opae.fpga._opae.sysobject, arg0: slice) -> unicode

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) → unicode¶: Get bytes from the sysobject. Raises RuntimeError if the sysobject instance is a container type.

find(self: opae.fpga._opae.sysobject, name: unicode, flags: int=0L) → 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¶