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

OPAE C API Reference

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

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

sections:

.. contents::

   :local:

Types

=====

The OPAE C API defines a number of types; most prominent are the types

`fpga_token`, `fpga_handle`, and `fpga_properties`. All regular types are

defined in [types.h](#types-h), while the values of enumeration types are

defined in [types_enum.h](#types-enum-h).

types.h

-------

.. doxygenfile:: include/opae/types.h

types_enum.h

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

.. doxygenfile:: include/opae/types_enum.h

Enumeration API

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

The OPAE enumeration API allows selective discovery of FPGA resources. When

enumerating resources, a list of filter criteria can be passed to the

respective function to select a subset of all resources in the system. The

fpgaEnumerate() function itself then returns a list of fpga_tokens denoting

resources, which can be used in subsequent API calls.

Filter criteria are specified using one or more fpga_properties object. These

objects need to be created using fpgaGetProperties() (defined in

<opae/properties/h>) before being passed to fpgaEnumerate(). Individual

attributes of an fpga_properties object are set using specific accessors,

which are also defined in <opae/properties.h>.

enum.h

------

.. doxygenfile:: include/opae/enum.h

properties.h

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

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

Access API

==========

The access API provides functions for opening and closing FPGA resources.

Opening a resource yields an fpga_handle, which denotes ownership and can be

used in subsequent API calls to interact with a specific resource. Ownership

can be exclusive or shared.

access.h

--------

.. doxygenfile:: include/opae/access.h

Event API

=========

The event API provides functions and types for handling asynchronous events

such as errors or accelerator interrupts.

To natively support asynchronous event, the driver for the FPGA platform

needs to support events natively (in which case the OPAE C library will

register the event directly with the driver). For some platforms that do not

support interrupt-driven event delivery, you need to run the FPGA Daemon

(fpgad) to enable asynchronous OPAE events. fpgad will act as a proxy for the

application and deliver asynchronous notifications for registered events.

event.h

-------

.. doxygenfile:: include/opae/event.h

MMIO and Shared Memory APIs

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

These APIs feature functions for mapping and accessing control registers

through memory-mapped IO (mmio.h), allocating and sharing system memory

buffers with an accelerator (buffer.h), and using low-latency notifications

(umsg.h).

mmio.h

------

.. doxygenfile:: include/opae/mmio.h

buffer.h

--------

.. doxygenfile:: include/opae/buffer.h

umsg.h

------

.. doxygenfile:: include/opae/umsg.h

Management API

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

The management APIs define functions for reconfiguring an FPGA (writing new

partial bitstreams) as well as assigning accelerators to host interfaces.

manage.h

--------

.. doxygenfile:: include/opae/manage.h

Metrics API

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

The metrics APIs define functions for discovery/enumeration of metrics information

and reading metrics values.

metrics.h

--------

.. doxygenfile:: include/opae/metrics.h

SysObject

=========

The SysObject API can be used to get system objects by name. Names used with

the SysObject API are driver-specific and may not be compatible across plugins

and/or drivers. For example, SysObject names used with the xfpga plugin will

apply to the OPAE Linux Kernel driver and refer to sysfs nodes under the sysfs

tree for the resource used with the SysObject API.

sysobject.h

-------

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

Utilities

=========

Functions for mapping fpga_result values to meaningful error strings are

provided by the utilities API.

utils.h

-------

.. doxygenfile:: include/opae/utils.h

Samples

=======

Code samples demonstrate how to use OPAE C API.

hello_fpga.c

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

.. doxygenfile:: samples/hello_fpga.c

hello_events.c

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

.. doxygenfile:: samples/hello_events.c