===========================

OPAE C++ Core API Reference

===========================

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

sections:

.. contents::

   :local:

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

--------

.. doxygenfile:: include/opae/cxx/core/pvalue.h

properties.h

------------

.. doxygenfile:: include/opae/cxx/core/properties.h

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

--------

.. doxygenfile:: include/opae/cxx/core/token.h

handle.h

--------

.. doxygenfile:: include/opae/cxx/core/handle.h

shared_buffer.h

--------

.. doxygenfile:: include/opae/cxx/core/shared_buffer.h

errors.h

-------

.. doxygenfile:: include/opae/cxx/core/errors.h

events.h

-------

.. doxygenfile:: include/opae/cxx/core/events.h

sysobject.h

-------

.. doxygenfile:: include/opae/cxx/core/sysobject.h

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

--------

.. doxygenfile:: include/opae/cxx/core/except.h

Misc

----

The `version` class wraps the OPAE C version API.

version.h

--------

.. doxygenfile:: include/opae/cxx/core/version.h