=========================== 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 events.h ------- .. doxygenfile:: include/opae/cxx/core/events.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