====================
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


