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.
Goals¶
Simplicity¶
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
opae
¶ -
namespace
fpga
¶ -
namespace
types
¶ -
struct
guid_t
¶ - #include <pvalue.h>
Representation of the guid member of a properties object.
Public Functions
-
guid_t
(fpga_properties *p)¶ Construct the guid_t given its containing fpga_properties.
-
void
update
()¶ Update the local cached copy of the guid.
-
operator uint8_t *
()¶ Return a raw pointer to the guid.
- Return Value
nullptr
: if the guid could not be queried.
-
const uint8_t *
c_type
() const¶ Return a raw pointer to the guid.
-
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
operator==
(const fpga_guid &g)¶ Compare contents with an fpga_guid.
- Return Value
The
: result of memcmp of the two objects.
-
void
parse
(const char *str)¶ Convert a string representation of a guid to binary.
- Parameters
str
: The guid string.
-
bool
is_set
() const¶ Tracks whether the cached local copy of the guid is valid.
-
void
invalidate
()¶ Invalidate the cached local copy of the guid.
-
-
template <typename T>
structpvalue
¶ - #include <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.- Template Parameters
T
: The type of the property value being wrapped
Public Types
-
typedef std::conditional<std::is_same<T, char *>::value, fpga_result (*)(fpga_properties, T), fpga_result (*)(fpga_properties, T *)>::type
getter_t
¶ Define getter function as getter_t For
char*
types, do not use T* as the second argument but instead use T.
-
template<>
typedef fpga_result (*setter_t
)(fpga_properties, T)¶ Define the setter function as setter_t.
-
typedef std::conditional<std::is_same<T, char *>::value, typename std::string, T>::type
copy_t
¶ Define the type of our copy variable For
char*
types use std::string as the copy.
Public Functions
-
pvalue
()¶
-
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_propertiesg
: The getter functions
: The setter function
-
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
-
bool
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
-
void
update
()¶
-
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
-
fpga_result
get_value
(T &value) const¶
-
bool
is_set
() const¶ Tracks whether the cached local copy of the pvalue is valid.
-
void
invalidate
()¶ Invalidate the cached local copy of the pvalue.
-
template <>
voidupdate
()¶ - Return
- The result of the property getter function.
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 streamp
: A reference to a pvalue<T> object
-
struct
-
namespace
-
namespace
properties.h¶
-
namespace
opae
¶ -
namespace
fpga
¶ -
namespace
types
¶ -
class
properties
¶ - #include <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 std::shared_ptr<properties>
ptr_t
¶
Public Functions
-
properties
(const properties &p)¶
-
properties &
operator=
(const properties &p)¶
-
~properties
()¶
-
fpga_properties
c_type
() const¶ Get the underlying fpga_properties object.
-
operator fpga_properties
() const¶ Get the underlying fpga_properties object.
Public Members
-
pvalue<fpga_objtype>
type
¶
-
pvalue<fpga_version>
bbs_version
¶
-
pvalue<fpga_accelerator_state>
accelerator_state
¶
-
pvalue<fpga_token>
parent
¶
Public Static Functions
-
static properties::ptr_t
get
()¶ Create a new properties object.
- Return
- A properties smart pointer.
-
static properties::ptr_t
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
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
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
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.
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>
none
¶ An empty vector of properties. Useful for enumerating based on a “match all” criteria.
Private Functions
-
properties
()¶
Private Members
-
fpga_properties
props_
¶
-
typedef std::shared_ptr<properties>
-
class
-
namespace
-
namespace
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
opae
-
namespace
fpga
-
namespace
types
-
class
token
¶ - #include <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 Functions
-
~token
()¶
-
fpga_token
c_type
() const¶ Retrieve the underlying fpga_token primitive.
-
operator fpga_token
() const¶ Retrieve the underlying fpga_token primitive.
Public Static Functions
-
static std::vector<token::ptr_t>
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
-
token
(fpga_token tok)¶
Private Members
-
fpga_token
token_
¶
-
-
class
-
namespace
-
namespace
handle.h¶
-
namespace
opae
-
namespace
fpga
-
namespace
types
-
class
handle
¶ - #include <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 Functions
-
~handle
()¶
-
fpga_handle
c_type
() const¶ Retrieve the underlying OPAE handle.
-
operator fpga_handle
() const¶ Retrieve the underlying OPAE handle.
-
void
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 programbitstream
: The bitstream binary datasize
: The size of the bitstreamflags
: 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
read_csr32
(uint64_t offset, uint32_t csr_space = 0) 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 offsetcsr_space
: The CSR space to read from. Default is 0.
-
void
write_csr32
(uint64_t offset, uint32_t value, uint32_t csr_space = 0)¶ 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
read_csr64
(uint64_t offset, uint32_t csr_space = 0) 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 offsetcsr_space
: The CSR space to read from. Default is 0.
-
void
write_csr64
(uint64_t offset, uint64_t value, uint32_t csr_space = 0)¶ Write 64 bit 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.
-
uint8_t *
mmio_ptr
(uint64_t offset, uint32_t csr_space = 0) 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
reset
()¶ Reset the accelerator identified by this handle
-
fpga_result
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
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().
Private Functions
-
handle
(fpga_handle h)¶
-
-
class
-
namespace
-
namespace
events.h¶
-
namespace
opae
-
namespace
fpga
-
namespace
types
-
class
event
¶ - #include <events.h>
Wraps fpga event routines in OPAE C.
Public Functions
-
virtual
~event
()¶ Destroy event and associated resources.
-
fpga_event_handle
get
()¶ Get the fpga_event_handle contained in this object.
- Return
- The fpga_event_handle contained in this object
-
operator fpga_event_handle
()¶ Coversion operator for converting to fpga_event_handle objects.
- Return
- The fpga_event_handle contained in this object
-
int
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
Private Functions
-
event
(handle::ptr_t h, event::type_t t, fpga_event_handle event_h)¶
-
struct
type_t
¶ - #include <events.h>
C++ struct that is interchangeable with fpga_event_type enum.
Public Static Attributes
-
constexpr fpga_event_type
interrupt
= FPGA_EVENT_INTERRUPT¶
-
constexpr fpga_event_type
error
= FPGA_EVENT_ERROR¶
-
constexpr fpga_event_type
power_thermal
= FPGA_EVENT_POWER_THERMAL¶
Private Members
-
fpga_event_type
type_
¶
-
constexpr fpga_event_type
-
virtual
-
class
-
namespace
-
namespace
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
opae
-
namespace
fpga
-
namespace
types
-
class
src_location
¶ - #include <except.h>
Identify a particular line in a source file.
Public Functions
-
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.
-
src_location
(const src_location &other)¶
-
src_location &
operator=
(const src_location &other)¶
-
const char *
file
() const¶ Retrieve the file name component of the location.
-
const char *
fn
() const¶ Retrieve the function name component of the location.
-
int
line
() const¶ Retrieve the line number component of the location.
-
-
class
except
: public std::exception¶ - #include <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.
Subclassed by opae::fpga::types::busy, opae::fpga::types::exception, opae::fpga::types::invalid_param, opae::fpga::types::no_access, opae::fpga::types::no_daemon, opae::fpga::types::no_driver, opae::fpga::types::no_memory, opae::fpga::types::not_found, opae::fpga::types::not_supported, opae::fpga::types::reconf_error
Public Functions
-
except
(src_location loc)¶ except constructor The fpga_result value is FPGA_EXCEPTION.
- Parameters
loc
: Location where the exception was constructed.
-
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.
-
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 stringloc
: Location where the exception was constructed.
-
virtual const char *
what
() const¶ Convert this except to an informative string.
-
operator fpga_result
() const¶ Convert this except to its fpga_result.
Public Static Attributes
-
const std::size_t
MAX_EXCEPT
= 256¶
-
-
class
invalid_param
: public opae::fpga::types::except¶ - #include <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
-
invalid_param
(src_location loc)¶ invalid_param constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
busy
: public opae::fpga::types::except¶ - #include <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
-
busy
(src_location loc)¶ busy constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
exception
: public opae::fpga::types::except¶ - #include <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
-
exception
(src_location loc)¶ exception constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
not_found
: public opae::fpga::types::except¶ - #include <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
-
not_found
(src_location loc)¶ not_found constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
no_memory
: public opae::fpga::types::except¶ - #include <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
-
no_memory
(src_location loc)¶ no_memory constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
not_supported
: public opae::fpga::types::except¶ - #include <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
-
not_supported
(src_location loc)¶ not_supported constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
no_driver
: public opae::fpga::types::except¶ - #include <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
-
no_driver
(src_location loc)¶ no_driver constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
no_daemon
: public opae::fpga::types::except¶ - #include <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
-
no_daemon
(src_location loc)¶ no_daemon constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
no_access
: public opae::fpga::types::except¶ - #include <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
-
no_access
(src_location loc)¶ no_access constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
class
reconf_error
: public opae::fpga::types::except¶ - #include <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
-
reconf_error
(src_location loc)¶ reconf_error constructor
- Parameters
loc
: Location where the exception was constructed.
-
-
namespace
detail
¶ Typedefs
-
typedef bool (*
exception_fn
)(fpga_result, const opae::fpga::types::src_location &loc)¶ typedef function pointer that returns bool if result is FPGA_OK
Functions
-
template <typename T>
constexpr boolis_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
assert_fpga_ok
(fpga_result result, const opae::fpga::types::src_location &loc)¶
Variables
-
exception_fn
opae_exceptions
[12]= {
is_ok<opae::fpga::types::invalid_param>,
is_ok<opae::fpga::types::busy>,
is_ok<opae::fpga::types::exception>,
is_ok<opae::fpga::types::not_found>,
is_ok<opae::fpga::types::no_memory>,
is_ok<opae::fpga::types::not_supported>,
is_ok<opae::fpga::types::no_driver>,
is_ok<opae::fpga::types::no_daemon>,
is_ok<opae::fpga::types::no_access>,
is_ok<opae::fpga::types::reconf_error>}¶
-
typedef bool (*
-
class
-
namespace
-
namespace
version.h¶
-
namespace
opae
-
namespace
fpga
-
namespace
types
-
class
version
¶ - #include <version.h>
Public Static Functions
-
static fpga_version
as_struct
()¶ Get the package version information as a struct.
- Return
- The package version as an
fpga_version
struct
-
static std::string
as_string
()¶ Get the package version information as a string.
- Return
- The package version as an
std::string
object
-
static std::string
build
()¶ Get the package build information as a string.
- Return
- The package build as an
std::string
object
-
static fpga_version
-
class
-
namespace
-
namespace