OPAE C++ Core API Reference¶

The reference documentation for the OPAE C++ Core API is grouped into the following sections:

Overview ¶

The OPAE C++ API enables C++ developers with the means to use FPGA resources by integrating the OPAE software stack into C++ applications.

Keep the API as small and lightweight as possible. Although features such as system validation and orchestration are beyond the scope of this API, using this API for their development should be relatively easy.

Extensibility and Interoperability ¶

While keeping to the goal of simplicity, the OPAE C++ API is designed to allow for better reuse by either extending the API or by integrating with other languages.

Modern C++ Coding Practices ¶

The OPAE C++ API uses the C++ 11 standard library and makes use of its features whenever practical. The OPAE C++ API is also designed to require the minimum number of third-party libraries/dependencies.

Error Handling ¶

The OPAE C++ API is designed to throw exceptions when appropriate. The structure of OPAE C++ exceptions is similar to the error codes in the OPAE C API. This gives users of the API more freedom on error handling while providing better debug information in cases of failure.

Coding Style ¶

For formatting of the OPAE C++ API complies with most of the recommendations of the Google C++ style. For example, the OPAE C++ API uses:

opening braces on the same line as their scope definition
spaces instead of tabs for indentation
indentation of two spaces

Fundamental Types ¶

Basic types for the OPAE C++ API are found in the opae::fpga::types namespace. They serve as an adapter layer between the OPAE C API and the OPAE C++ layer. Aside from providing a C++ binding to the C fundamental types, these types also:

manage the lifetime and scope of the corresponding C struct.

For example a C++ destructor will take care of calling the appropriate C function to release the data structure being wrapped.

provide a friendly syntax for using the OPAE C type.

Most classes in this namespace have a c_type() method that returns the C data structure being wrapped, making it easy to use the OPAE C++ type with the OPAE C API. Alternatively, most classes in this namespace have implicit conversion operators that enable interoperability with the OPAE C API.

Properties ¶

C++ class properties wraps fpga_properties and uses pvalue and guid_t to get and set properties stored in an instance of an fpga_properties. pvalue and guid_t are designed to call an accessor method in the OPAE C API to either read property values or write them. Most accessor methods in the OPAE C API share a similar signature, so pvalue generalizes them into common operations that translate into calling the corresponding C API function. guid_t follows similar patterns when reading or assigning values.

pvalue.h ¶

namespace

struct

#include <opae/cxx/core/pvalue.h>

Representation of the guid member of a properties object.

Public Functions

opae::fpga::types::guid_t::guid_t(fpga_properties *p)¶: Construct the guid_t given its containing fpga_properties.

void opae::fpga::types::guid_t::update()¶: Update the local cached copy of the guid.

opae::fpga::types::guid_t::operator uint8_t *()¶

Return a raw pointer to the guid.

Return Value

nullptr -
if the guid could not be queried.

const uint8_t *opae::fpga::types::guid_t::c_type()¶ const: Return a raw pointer to the guid.

guid_t &opae::fpga::types::guid_t::operator=(fpga_guid g)¶

Assign from fpga_guid Sets the guid field of the associated properties object using the OPAE properties API.

Return

a reference to this guid_t.

Parameters

g -
The given fpga_guid.

bool opae::fpga::types::guid_t::operator==(const fpga_guid &g)¶

Compare contents with an fpga_guid.

Return Value

The -
result of memcmp of the two objects.

void opae::fpga::types::guid_t::parse(const char *str)¶

Convert a string representation of a guid to binary.

Parameters

str -
The guid string.

bool opae::fpga::types::guid_t::is_set()¶ const: Tracks whether the cached local copy of the guid is valid.

void opae::fpga::types::guid_t::invalidate()¶: Invalidate the cached local copy of the guid.

Private Members

fpga_properties *opae::fpga::types::guid_t::props_¶

bool opae::fpga::types::guid_t::is_set_¶

std::array<uint8_t, 16> opae::fpga::types::guid_t::data_¶

Friends

std::ostream &operator<<(std::ostream &ostr, const guid_t &g)¶: Send the string representation of the guid_t to the given stream.

template <typename T>

struct

#include <opae/cxx/core/pvalue.h>

Wraps OPAE properties defined in the OPAE C API by associating an fpga_properties reference with the getters and setters defined for a property.

Templates

T -
The type of the property value being wrapped

Public Types

typedef typedef std::conditional<std::is_same<T, char *>::value, fpga_result (*)(fpga_properties, T), fpga_result (*)(fpga_properties, T *)>::type opae::fpga::types::pvalue<T>::getter_t¶: Define getter function as getter_t For char* types, do not use T* as the second argument but instead use T.

typedef typedef fpga_result (*opae::fpga::types::pvalue<T>::setter_t)(fpga_properties, T)¶: Define the setter function as setter_t.

typedef typedef std::conditional<std::is_same<T, char *>::value, typename std::string, T>::type opae::fpga::types::pvalue<T>::copy_t¶: Define the type of our copy variable For char* types use std::string as the copy.

Public Functions

template<> opae::fpga::types::pvalue<T>::pvalue()¶

template<> opae::fpga::types::pvalue<T>::pvalue(fpga_properties *p, getter_t g, setter_t s)¶

pvalue contructor that takes in a reference to fpga_properties and corresponding accessor methods for a property

Parameters

p -
A reference to an fpga_properties
g -
The getter function
s -
The setter function

template<> pvalue<T> &opae::fpga::types::pvalue<T>::operator=(const T &v)¶

Overload of = operator that calls the wrapped setter.

Return

A reference to itself

Parameters

v -
The value to set

template<> bool opae::fpga::types::pvalue<T>::operator==(const T &other)¶

Compare a property for equality with a value.

Return

Whether or not the property is equal to the value

Parameters

other -
The value being compared to

template<> void opae::fpga::types::pvalue<T>::update()¶

template<> opae::fpga::types::pvalue<T>::operator copy_t()¶

Implicit converter operator - calls the wrapped getter.

Return: The property value after calling the getter or a default value of the value type

template<> fpga_result opae::fpga::types::pvalue<T>::get_value(T &value)¶ const

template<> bool opae::fpga::types::pvalue<T>::is_set()¶ const: Tracks whether the cached local copy of the pvalue is valid.

template<> void opae::fpga::types::pvalue<T>::invalidate()¶: Invalidate the cached local copy of the pvalue.

template <>

template<> void opae::fpga::types::pvalue<char *>::update()¶

Template specialization of char* type property updater.

Return: The result of the property getter function.

Private Members

template<> fpga_properties *opae::fpga::types::pvalue<T>::props_¶

template<> bool opae::fpga::types::pvalue<T>::is_set_¶

template<> getter_t opae::fpga::types::pvalue<T>::get_¶

template<> setter_t opae::fpga::types::pvalue<T>::set_¶

template<> copy_t opae::fpga::types::pvalue<T>::copy_¶

Friends

std::ostream &operator<<(std::ostream &ostr, const pvalue<T> &p)¶

Stream overalod operator.

Return

The stream operator after streaming the property value

Parameters

ostr -
The output stream
p -
A reference to a pvalue<T> object

properties.h ¶

namespace

class

#include <opae/cxx/core/properties.h>

Wraps an OPAE fpga_properties object.

properties are information describing an accelerator resource that is identified by its token. The properties are used during enumeration to narrow the search for an accelerator resource, and after enumeration to provide the configuration of that resource.

Public Types

typedef

Public Functions

opae::fpga::types::properties::properties(const properties &p)¶

properties &opae::fpga::types::properties::operator=(const properties &p)¶

opae::fpga::types::properties::~properties()¶

fpga_properties opae::fpga::types::properties::c_type()¶ const: Get the underlying fpga_properties object.

opae::fpga::types::properties::operator fpga_properties()¶ const: Get the underlying fpga_properties object.

Public Members

pvalue<fpga_objtype> opae::fpga::types::properties::type¶

pvalue<uint32_t> opae::fpga::types::properties::num_errors¶

pvalue<uint16_t> opae::fpga::types::properties::segment¶

pvalue<uint8_t> opae::fpga::types::properties::bus¶

pvalue<uint8_t> opae::fpga::types::properties::device¶

pvalue<uint8_t> opae::fpga::types::properties::function¶

pvalue<uint8_t> opae::fpga::types::properties::socket_id¶

pvalue<uint32_t> opae::fpga::types::properties::num_slots¶

pvalue<uint64_t> opae::fpga::types::properties::bbs_id¶

pvalue<fpga_version> opae::fpga::types::properties::bbs_version¶

pvalue<uint16_t> opae::fpga::types::properties::vendor_id¶

pvalue<uint16_t> opae::fpga::types::properties::device_id¶

pvalue<char *> opae::fpga::types::properties::model¶

pvalue<uint64_t> opae::fpga::types::properties::local_memory_size¶

pvalue<uint64_t> opae::fpga::types::properties::capabilities¶

pvalue<uint32_t> opae::fpga::types::properties::num_mmio¶

pvalue<uint32_t> opae::fpga::types::properties::num_interrupts¶

pvalue<fpga_accelerator_state> opae::fpga::types::properties::accelerator_state¶

pvalue<uint64_t> opae::fpga::types::properties::object_id¶

pvalue<fpga_token> opae::fpga::types::properties::parent¶

guid_t opae::fpga::types::properties::guid¶

Public Static Functions

static properties::ptr_t opae::fpga::types::properties::get()¶

Create a new properties object.

Return: A properties smart pointer.

static properties::ptr_t opae::fpga::types::properties::get(fpga_guid guid_in)¶

Create a new properties object from a guid.

Return

A properties smart pointer with its guid initialized to guid_in

Parameters

guid_in -
A guid to set in the properties

static properties::ptr_t opae::fpga::types::properties::get(fpga_objtype objtype)¶

Create a new properties object from an fpga_objtype.

Return

A properties smart pointer with its object type set to objtype.

Parameters

objtype -
An object type to set in the properties

static properties::ptr_t opae::fpga::types::properties::get(std::shared_ptr<token> t)¶

Retrieve the properties for a given token object.

Return

A properties smart pointer for the given token.

Parameters

t -
A token identifying the accelerator resource.

static properties::ptr_t opae::fpga::types::properties::get(fpga_token t)¶

Retrieve the properties for a given fpga_token.

Return

A properties smart pointer for the given fpga_token.

Parameters

t -
An fpga_token identifying the accelerator resource.

static properties::ptr_t opae::fpga::types::properties::get(std::shared_ptr<handle> h)¶

Retrieve the properties for a given handle object.

Return

A properties smart pointer for the given handle.

Parameters

h -
A handle identifying the accelerator resource.

Public Static Attributes

const std::vector<properties::ptr_t> opae::fpga::types::properties::none¶: An empty vector of properties. Useful for enumerating based on a “match all” criteria.

Private Functions

opae::fpga::types::properties::properties(bool alloc_props)¶

Private Members

fpga_properties opae::fpga::types::properties::props_¶

Resource Classes ¶

The token, handle, and shared_buffer classes are used to enumerate and access FPGA resources. properties are used to narrow the search space for token’s. Before enumerating the accelerator resources in the system, applications can produce one or more properties objects whose values are set to the desired characteristics for the resource. For example, an application may search for an accelerator resource based on its guid.

Once one or more token’s have been enumerated, the application must choose which token’s to request. The token is then converted to a handle by requesting that a handle object be allocated and opened for it.

Once a handle has been successfully opened, the application can read and write the associated configuration and status space. Additionally, the application may use the handle to allocate shared_buffer’s or to register event’s. The shared_buffer and event objects retain a reference to their owning handle so that the handle does not lose scope before freeing the shared_buffer and event objects.

token.h ¶

namespace

class

#include <opae/cxx/core/token.h>

Wraps the OPAE fpga_token primitive. token’s are created from an enumeration operation that uses properties describing an accelerator resource as search criteria.

Public Types

typedef

Public Functions

opae::fpga::types::token::~token()¶

fpga_token opae::fpga::types::token::c_type()¶ const: Retrieve the underlying fpga_token primitive.

opae::fpga::types::token::operator fpga_token()¶ const: Retrieve the underlying fpga_token primitive.

Public Static Functions

static std::vector<token::ptr_t> opae::fpga::types::token::enumerate(const std::vector<properties::ptr_t> &props)¶

Obtain a vector of token smart pointers for given search criteria.

Return

A set of known tokens that match the search.

Parameters

props -
The search criteria.

Private Functions

opae::fpga::types::token::token(fpga_token tok)¶

Private Members

fpga_token opae::fpga::types::token::token_¶

handle.h ¶

namespace

class

#include <opae/cxx/core/handle.h>

An allocated accelerator resource

Represents an accelerator resource that has been allocated by OPAE. Depending on the type of resource, its register space may be read/written using a handle object.

Public Types

typedef

Public Functions

opae::fpga::types::handle::handle(const handle&)¶

handle &opae::fpga::types::handle::operator=(const handle&)¶

virtual opae::fpga::types::handle::~handle()¶

fpga_handle opae::fpga::types::handle::c_type()¶ const: Retrieve the underlying OPAE handle.

opae::fpga::types::handle::operator fpga_handle()¶ const: Retrieve the underlying OPAE handle.

void opae::fpga::types::handle::reconfigure(uint32_t slot, const uint8_t *bitstream, size_t size, int flags)¶

Load a bitstream into an FPGA slot.

Parameters

slot -
The slot number to program
bitstream -
The bitstream binary data
size -
The size of the bitstream
flags -
Flags that control behavior of reconfiguration. Value of 0 indicates no flags. FPGA_RECONF_FORCE indicates that the bitstream is programmed into the slot without checking if the resource is currently in use.

Exceptions

invalid_param -
if the handle is not an FPGA device handle or if the other parameters are not valid.
exception -
if an internal error is encountered.
busy -
if the accelerator for the given slot is in use.
reconf_error -
if errors are reported by the driver (CRC or protocol errors).

uint32_t opae::fpga::types::handle::read_csr32(uint64_t offset, uint32_t csr_space)¶ const

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

Return

The 32-bit value read from the CSR

Parameters

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

void opae::fpga::types::handle::write_csr32(uint64_t offset, uint32_t value, uint32_t csr_space)¶

Write 32 bit to a CSR belonging to a resource associated with a handle.

Parameters

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

uint64_t opae::fpga::types::handle::read_csr64(uint64_t offset, uint32_t csr_space)¶ const

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

Return

The 64-bit value read from the CSR

Parameters

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

void opae::fpga::types::handle::write_csr64(uint64_t offset, uint64_t value, uint32_t csr_space)¶

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

Parameters

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

void opae::fpga::types::handle::write_csr512(uint64_t offset, const void *value, uint32_t csr_space)¶

Write 512 bits to a CSR belonging to a resource associated with a handle.

Parameters

offset -
The register offset.
value -
Pointer to the 512-bit value to write to the register.
csr_space -
The CSR space to read from. Default is 0.

uint8_t *opae::fpga::types::handle::mmio_ptr(uint64_t offset, uint32_t csr_space)¶ const

Retrieve a pointer to the MMIO region.

Return

MMIO base + offset

Parameters

offset -
The byte offset to add to MMIO base.
csr_space -
The desired CSR space. Default is 0.

virtual void opae::fpga::types::handle::reset()¶: Reset the accelerator identified by this handle

fpga_result opae::fpga::types::handle::close()¶

Close an accelerator resource (if opened)

Return: fpga_result indication the result of closing the handle or FPGA_EXCEPTION if handle is not opened
Note: This is available for explicitly closing a handle. The destructor for handle will call close.

Public Static Functions

static handle::ptr_t opae::fpga::types::handle::open(fpga_token token, int flags)¶

Open an accelerator resource, given a raw fpga_token

Return

pointer to the mmio base + offset for the given csr space

Parameters

token -
A token describing the accelerator resource to be allocated.
flags -
The flags parameter to fpgaOpen().

static handle::ptr_t opae::fpga::types::handle::open(token::ptr_t token, int flags)¶

Open an accelerator resource, given a token object

Return

shared ptr to a handle object

Parameters

token -
A token object describing the accelerator resource to be allocated.
flags -
The flags parameter to fpgaOpen().

Private Functions

opae::fpga::types::handle::handle(fpga_handle h)¶

Private Members

fpga_handle opae::fpga::types::handle::handle_¶

fpga_token opae::fpga::types::handle::token_¶

shared_buffer.h ¶

namespace

class

#include <opae/cxx/core/shared_buffer.h>

Host/AFU shared memory blocks

shared_buffer abstracts a memory block that may be shared between the host cpu and an accelerator. The block may be allocated by the shared_buffer class itself (see allocate), or it may be allocated elsewhere and then attached to a shared_buffer object via attach.

Public Types

typedef

typedef

Public Functions

opae::fpga::types::shared_buffer::shared_buffer(const shared_buffer&)¶

shared_buffer &opae::fpga::types::shared_buffer::operator=(const shared_buffer&)¶

virtual opae::fpga::types::shared_buffer::~shared_buffer()¶: shared_buffer destructor.

void opae::fpga::types::shared_buffer::release()¶: Disassociate the shared_buffer object from the resource used to create it. If the buffer was allocated using the allocate function then the buffer is freed.

volatile uint8_t *opae::fpga::types::shared_buffer::c_type()¶ const

Retrieve the virtual address of the buffer base.

Note: Instances of a shared buffer can only be created using either ‘allocate’ or ‘attach’ static factory function. Because these functions return a shared pointer (std::shared_ptr) to the instance, references to an instance are counted automatically by design of the shared_ptr class. Calling ‘c_type()’ function is provided to get access to the raw data but isn’t used in tracking its reference count. Assigning this to a variable should be done in limited scopes as this variable can be defined in an outer scope and may outlive the shared_buffer object. Once the reference count in the shared_ptr reaches zero, the shared_buffer object will be released and deallocated, turning any variables assigned from a call to ‘c_type()’ into dangling pointers.

handle::ptr_t opae::fpga::types::shared_buffer::owner()¶ const: Retrieve the handle smart pointer associated with this buffer.

size_t opae::fpga::types::shared_buffer::size()¶ const: Retrieve the length of the buffer in bytes.

uint64_t opae::fpga::types::shared_buffer::wsid()¶ const: Retrieve the underlying buffer’s workspace id.

uint64_t opae::fpga::types::shared_buffer::io_address()¶ const: Retrieve the address of the buffer suitable for programming into the accelerator device.

void opae::fpga::types::shared_buffer::fill(int c)¶: Write c to each byte location in the buffer.

int opae::fpga::types::shared_buffer::compare(ptr_t other, size_t len)¶ const: Compare this shared_buffer (the first len bytes) to that held in other, using memcmp().

template <typename T>

T opae::fpga::types::shared_buffer::read(size_t offset)¶ const

Read a T-sized block of memory at the given location.

Return

A T from buffer base + offset.

Parameters

offset -
The byte offset from the start of the buffer.

template <typename T>

void opae::fpga::types::shared_buffer::write(const T &value, size_t offset)¶

Write a T-sized block of memory to the given location.

Parameters

value -
The value to write.
offset -
The byte offset from the start of the buffer.

Public Static Functions

static shared_buffer::ptr_t opae::fpga::types::shared_buffer::allocate(handle::ptr_t handle, size_t len, bool read_only)¶

shared_buffer factory method - allocate a shared_buffer.

Return

A valid shared_buffer smart pointer on success, or an empty smart pointer on failure.

Parameters

handle -
The handle used to allocate the buffer.
len -
The length in bytes of the requested buffer.

static shared_buffer::ptr_t opae::fpga::types::shared_buffer::attach(handle::ptr_t handle, uint8_t *base, size_t len, bool read_only)¶

Attach a pre-allocated buffer to a shared_buffer object.

Return

A valid shared_buffer smart pointer on success, or an empty smart pointer on failure.

Parameters

handle -
The handle used to attach the buffer.
base -
The base of the pre-allocated memory.
len -
The size of the pre-allocated memory, which must be a multiple of the page size.

Protected Functions

opae::fpga::types::shared_buffer::shared_buffer(handle::ptr_t handle, size_t len, uint8_t *virt, uint64_t wsid, uint64_t io_address)¶

Protected Attributes

handle::ptr_t opae::fpga::types::shared_buffer::handle_¶

size_t opae::fpga::types::shared_buffer::len_¶

uint8_t *opae::fpga::types::shared_buffer::virt_¶

uint64_t opae::fpga::types::shared_buffer::wsid_¶

uint64_t opae::fpga::types::shared_buffer::io_address_¶

errors.h ¶

namespace

class

#include <opae/cxx/core/errors.h>

An error object represents an error register for a resource. This is used to read out the raw value in the register. No parsing is done by this class.

Public Types

typedef

Public Functions

opae::fpga::types::error::error(const error &e)¶

error &opae::fpga::types::error::operator=(const error &e)¶

std::string opae::fpga::types::error::name()¶

Get the error register name.

Return: A std::string object set to the error name.

bool opae::fpga::types::error::can_clear()¶

Indicates whether an error register can be cleared.

Return: A boolean value indicating if the error register can be cleared.

uint64_t opae::fpga::types::error::read_value()¶

Read the raw value contained in the associated error register.

Return: A 64-bit value (unparsed) read from the error register

opae::fpga::types::error::~error()¶

fpga_error_info opae::fpga::types::error::c_type()¶ const

Get the C data structure.

Return: The fpga_error_info that contains the name and the can_clear boolean.

Public Static Functions

static error::ptr_t opae::fpga::types::error::get(token::ptr_t tok, uint32_t num)¶

Factory function for creating an error object.

Return

A shared_ptr containing the error object

Parameters

tok -
The token object representing a resource.
num -
The index of the error register. This must be lower than the num_errors property of the resource.

Private Functions

opae::fpga::types::error::error(token::ptr_t token, uint32_t num)¶

Private Members

token::ptr_t opae::fpga::types::error::token_¶

fpga_error_info opae::fpga::types::error::error_info_¶

uint32_t opae::fpga::types::error::error_num_¶

events.h ¶

namespace

class

#include <opae/cxx/core/events.h>

Wraps fpga event routines in OPAE C.

Public Types

typedef

Public Functions

virtual opae::fpga::types::event::~event()¶: Destroy event and associated resources.

fpga_event_handle opae::fpga::types::event::get()¶

Get the fpga_event_handle contained in this object.

Return: The fpga_event_handle contained in this object

opae::fpga::types::event::operator fpga_event_handle()¶

Coversion operator for converting to fpga_event_handle objects.

Return: The fpga_event_handle contained in this object

int opae::fpga::types::event::os_object()¶ const

Get OS Object from the event object.

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.

Return: An integer object representing the OS object

Public Static Functions

static event::ptr_t opae::fpga::types::event::register_event(handle::ptr_t h, event::type_t t, int flags)¶

Factory function to create event objects.

Return

A shared ptr to an event object

Parameters

h -
A shared ptr of a resource handle
t -
The resource type
flags -
Event registration flags passed on to fpgaRegisterEvent

Private Functions

opae::fpga::types::event::event(handle::ptr_t h, event::type_t t, fpga_event_handle event_h)¶

Private Members

handle::ptr_t opae::fpga::types::event::handle_¶

event::type_t opae::fpga::types::event::type_¶

fpga_event_handle opae::fpga::types::event::event_handle_¶

int opae::fpga::types::event::os_object_¶

struct

#include <opae/cxx/core/events.h>

C++ struct that is interchangeable with fpga_event_type enum.

Public Functions

opae::fpga::types::event::type_t::type_t(fpga_event_type c_type)¶

opae::fpga::types::event::type_t::operator fpga_event_type()¶

Public Static Attributes

constexpr fpga_event_type opae::fpga::types::event::type_t::interrupt¶

constexpr fpga_event_type opae::fpga::types::event::type_t::error¶

constexpr fpga_event_type opae::fpga::types::event::type_t::power_thermal¶

Private Members

fpga_event_type opae::fpga::types::event::type_t::type_¶

sysobject.h ¶

namespace

class

#include <opae/cxx/core/sysobject.h>

Wraps the OPAE fpga_object primitive. sysobject’s are created from a call to fpgaTokenGetObject, fpgaHandleGetObject, or fpgaObjectGetObject

Public Types

typedef

Public Functions

opae::fpga::types::sysobject::sysobject()¶

opae::fpga::types::sysobject::sysobject(const sysobject &o)¶

sysobject &opae::fpga::types::sysobject::operator=(const sysobject &o)¶

sysobject::ptr_t opae::fpga::types::sysobject::get(const std::string &name, int flags)¶

Get a sysobject from an object. This will be read-write if its parent was created from a handle..

Return

A shared_ptr to a sysobject instance.

Parameters

name -
An identifier representing an object belonging to this object.
flags -
Control behavior of object identification and creation. FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be created for objects one level down from the object identified by name. FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all objects. Flags are defaulted to 0 meaning no flags.

sysobject::ptr_t opae::fpga::types::sysobject::get(int index)¶

Get a sysobject from a container object. This will be read-write if its parent was created from a handle..

Return

A shared_ptr to a sysobject instance.

Parameters

index -
An index number to get.

virtual opae::fpga::types::sysobject::~sysobject()¶

uint32_t opae::fpga::types::sysobject::size()¶ const

Get the size (in bytes) of the object.

Return: The number of bytes that the object occupies in memory.

uint64_t opae::fpga::types::sysobject::read64(int flags)¶ const

Read a 64-bit value from an FPGA object. The value is assumed to be in string format and will be parsed. See flags below for changing that behavior.

Return

A 64-bit value from the object.

Parameters

flags -
Flags that control how the object is read If FPGA_OBJECT_SYNC is used then object will update its buffered copy before retrieving the data. If FPGA_OBJECT_RAW is used, then the data will be read as raw bytes into the uint64_t pointer variable. Flags are defaulted to 0 meaning no flags.

void opae::fpga::types::sysobject::write64(uint64_t value, int flags)¶ const

Write 64-bit value to an FPGA object. The value will be converted to string before writing. See flags below for changing that behavior.

Note

This operation will force a sync operation to update its cached buffer

Parameters

value -
The value to write to the object.
flags -
Flags that control how the object is written If FPGA_OBJECT_RAW is used, then the value will be written as raw bytes. Flags are defaulted to 0 meaning no flags.

std::vector<uint8_t> opae::fpga::types::sysobject::bytes(int flags)¶ const

Get all raw bytes from the object.

Return

A vector of all bytes in the object.

Parameters

flags -
Flags that control how object is read If FPGA_OBJECT_SYNC is used then object will update its buffered copy before retrieving the data.

std::vector<uint8_t> opae::fpga::types::sysobject::bytes(uint32_t offset, uint32_t size, int flags)¶ const

Get a subset of raw bytes from the object.

Return

A vector of size bytes in the object starting at offset.

Parameters

offset -
The bytes offset for the start of the returned vector.
size -
The number of bytes for the returned vector.
flags -
Flags that control how object is read If FPGA_OBJECT_SYNC is used then object will update its buffered copy before retrieving the data.

enum fpga_sysobject_type opae::fpga::types::sysobject::type()¶ const: Get the object type (attribute or container)

fpga_object opae::fpga::types::sysobject::c_type()¶ const: Retrieve the underlying fpga_object primitive.

opae::fpga::types::sysobject::operator fpga_object()¶ const: Retrieve the underlying fpga_object primitive.

Public Static Functions

static sysobject::ptr_t opae::fpga::types::sysobject::get(token::ptr_t t, const std::string &name, int flags)¶

Get a sysobject from a token. This will be read-only.

Return

A shared_ptr to a sysobject instance.

Parameters

t -
Token object representing a resource.
name -
An identifier representing an object belonging to a resource represented by the token.
flags -
Control behavior of object identification and creation. FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be created for objects one level down from the object identified by name. FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all objects below the current object identified by name.

static sysobject::ptr_t opae::fpga::types::sysobject::get(handle::ptr_t h, const std::string &name, int flags)¶

Get a sysobject from a handle. This will be read-write.

Return

A shared_ptr to a sysobject instance.

Parameters

h -
Handle object representing an open resource.
name -
An identifier representing an object belonging to a resource represented by the handle.
flags -
Control behavior of object identification and creation. FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be created for objects one level down from the object identified by name. FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all objects below the current object identified by name.

Private Functions

opae::fpga::types::sysobject::sysobject(fpga_object sysobj, token::ptr_t token, handle::ptr_t hnd)¶

Private Members

fpga_object opae::fpga::types::sysobject::sysobject_¶

token::ptr_t opae::fpga::types::sysobject::token_¶

handle::ptr_t opae::fpga::types::sysobject::handle_¶

Exceptions ¶

When the OPAE C++ API encounters an error from the OPAE C API, it captures the current source code location and the error code into an object of type except, then throws the except. Applications should implement the appropriate catch blocks required to respond to runtime exceptions.

except.h ¶

Defines

OPAECXX_HERE¶: Construct a src_location object for the current source line.

ASSERT_FPGA_OK(r)¶: Macro to check of result is FPGA_OK If not, throw exception that corresponds to the result code.

namespace

class

#include <opae/cxx/core/except.h>

busy exception

busy tracks the source line of origin for exceptions thrown when the error code FPGA_BUSY is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::busy::busy(src_location loc)¶

busy constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

Generic OPAE exception

An except tracks the source line of origin and an optional fpga_result. If no fpga_result is given, then FPGA_EXCEPTION is used.

Public Functions

opae::fpga::types::except::except(src_location loc)¶

except constructor The fpga_result value is FPGA_EXCEPTION.

Parameters

loc -
Location where the exception was constructed.

opae::fpga::types::except::except(fpga_result res, src_location loc)¶

except constructor

Parameters

res -
The fpga_result value associated with this exception.
loc -
Location where the exception was constructed.

opae::fpga::types::except::except(fpga_result res, const char *msg, src_location loc)¶

except constructor

Parameters

res -
The fpga_result value associated with this exception.
msg -
The error message as a string
loc -
Location where the exception was constructed.

virtual const char *opae::fpga::types::except::what()¶ const: Convert this except to an informative string.

opae::fpga::types::except::operator fpga_result()¶ const: Convert this except to its fpga_result.

Public Static Attributes

const std::size_t opae::fpga::types::except::MAX_EXCEPT¶

Protected Attributes

fpga_result opae::fpga::types::except::res_¶

const char *opae::fpga::types::except::msg_¶

src_location opae::fpga::types::except::loc_¶

char opae::fpga::types::except::buf_[MAX_EXCEPT]¶

class

#include <opae/cxx/core/except.h>

exception exception

exception tracks the source line of origin for exceptions thrown when the error code FPGA_EXCEPTION is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::exception::exception(src_location loc)¶

exception constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

invalid_param exception

invalid_param tracks the source line of origin for exceptions thrown when the error code FPGA_INVALID_PARAM is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::invalid_param::invalid_param(src_location loc)¶

invalid_param constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

no_access exception

no_access tracks the source line of origin for exceptions thrown when the error code FPGA_NO_ACCESS is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::no_access::no_access(src_location loc)¶

no_access constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

no_daemon exception

no_daemon tracks the source line of origin for exceptions thrown when the error code FPGA_NO_DAEMON is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::no_daemon::no_daemon(src_location loc)¶

no_daemon constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

no_driver exception

no_driver tracks the source line of origin for exceptions thrown when the error code FPGA_NO_DRIVER is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::no_driver::no_driver(src_location loc)¶

no_driver constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

no_memory exception

no_memory tracks the source line of origin for exceptions thrown when the error code FPGA_NO_MEMORY is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::no_memory::no_memory(src_location loc)¶

no_memory constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

not_found exception

not_found tracks the source line of origin for exceptions thrown when the error code FPGA_NOT_FOUND is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::not_found::not_found(src_location loc)¶

not_found constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

not_supported exception

not_supported tracks the source line of origin for exceptions thrown when the error code FPGA_NOT_SUPPORTED is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::not_supported::not_supported(src_location loc)¶

not_supported constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

reconf_error exception

reconf_error tracks the source line of origin for exceptions thrown when the error code FPGA_RECONF_ERROR is returned from a call to an OPAE C API function

Public Functions

opae::fpga::types::reconf_error::reconf_error(src_location loc)¶

reconf_error constructor

Parameters

loc -
Location where the exception was constructed.

class

#include <opae/cxx/core/except.h>

Identify a particular line in a source file.

Public Functions

opae::fpga::types::src_location::src_location(const char *file, const char *fn, int line)¶

src_location constructor

Parameters

file -
The source file name, typically FILE.
fn -
The current function, typically func.
line -
The current line number, typically LINE.

opae::fpga::types::src_location::src_location(const src_location &other)¶

src_location &opae::fpga::types::src_location::operator=(const src_location &other)¶

const char *opae::fpga::types::src_location::file()¶ const: Retrieve the file name component of the location.

const char *opae::fpga::types::src_location::fn()¶ const: Retrieve the function name component of the location.

int opae::fpga::types::src_location::line()¶ const: Retrieve the line number component of the location.

Private Members

const char *opae::fpga::types::src_location::file_¶

const char *opae::fpga::types::src_location::fn_¶

int opae::fpga::types::src_location::line_¶

namespace

Typedefs

typedef: typedef function pointer that returns bool if result is FPGA_OK

Functions

template <typename T>
constexpr bool opae::fpga::types::detail::is_ok(fpga_result result, const opae::fpga::types::src_location &loc)¶: is_ok is a template function that throws an excpetion of its template argument type if the result code is not FPGA_OK. Otherwise it returns true.

static void opae::fpga::types::detail::assert_fpga_ok(fpga_result result, const opae::fpga::types::src_location &loc)¶

Variables

exception_fn opae::fpga::types::detail::opae_exceptions[12]¶

Misc ¶

The version class wraps the OPAE C version API.

version.h ¶

namespace

class

#include <opae/cxx/core/version.h>

Public Static Functions

static fpga_version opae::fpga::types::version::as_struct()¶

Get the package version information as a struct.

Return: The package version as an fpga_version struct

static std::string opae::fpga::types::version::as_string()¶

Get the package version information as a string.

Return: The package version as an std::string object

static std::string opae::fpga::types::version::build()¶

Get the package build information as a string.

Return: The package build as an std::string object

OPAE C++ Core API Reference¶

Overview ¶

Goals ¶

Simplicity ¶

Extensibility and Interoperability ¶

Modern C++ Coding Practices ¶

Error Handling ¶

Coding Style ¶

Fundamental Types ¶

Properties ¶

pvalue.h ¶

properties.h ¶

Resource Classes ¶

token.h ¶

handle.h ¶

shared_buffer.h ¶

errors.h ¶

events.h ¶

sysobject.h ¶

Exceptions ¶

except.h ¶

Misc ¶

version.h ¶