File types.h¶

FileList > docs > sw > include > opae > types.h

Type definitions for FPGA API. More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <opae/types_enum.h>

Classes¶

Type	Name
struct	_fpga_token_header Internal token type header.
struct	fpga_error_info
struct	fpga_metric Metric struct.
struct	fpga_metric_info Metric info struct.
struct	fpga_version Semantic version.
struct	metric_threshold
struct	threshold Threshold struct.

Public Types¶

Type	Name
typedef void *	fpga_event_handle Handle to an event object.
typedef uint8_t	fpga_guid Globally unique identifier (GUID)
typedef void *	fpga_handle Handle to an FPGA resource.
typedef struct fpga_metric	fpga_metric Metric struct.
typedef struct fpga_metric_info	fpga_metric_info Metric info struct.
typedef void *	fpga_object Object pertaining to an FPGA resource as identified by a unique name.
typedef void *	fpga_properties Object for expressing FPGA resource properties.
typedef void *	fpga_token Token for referencing FPGA resources.
typedef struct _fpga_token_header	fpga_token_header Internal token type header.
typedef struct metric_threshold	metric_threshold
union	metric_value Metric value union.
typedef struct threshold	threshold Threshold struct.

Macros¶

Type	Name
define	FPGA_ERROR_NAME_MAX 64 Information about an error register.
define	FPGA_METRIC_STR_SIZE 256 FPGA Metric string size.
define	fpga_is_parent_child (__parent_hdr, __child_hdr) Determine token parent/child relationship.

Detailed Description¶

OPAE uses the three opaque types fpga_properties, fpga_token, and fpga_handle to create a hierarchy of objects that can be used to enumerate, reference, acquire, and query FPGA resources. This object model is designed to be extensible to account for different FPGA architectures and platforms.

Initialization¶

OPAEs management of the opaque types fpga_properties, fpga_token, and fpga_handle relies on the proper initialization of variables of these types. In other words, before doing anything with a variable of one of these opaque types, you need to first initialize them.

The respective functions that initialize opaque types are:

fpgaGetProperties() and fpgaCloneProperties() for fpga_properties
fpgaEnumerate() and fpgaCloneToken() for fpga_token
fpgaOpen() for fpga_handle

This should intuitively make sense - fpgaGetProperties() creates fpga_properties objects, fpgaEnumerate() creates fpga_token objects, fpgaOpen() creates fpga_handle objects, and fpgaCloneProperties() and fpgaCloneToken() clone (create) fpga_properties and fpga_token objects, respectively.

Since these opaque types are interpreted as pointers (they are typedef'd to a void *), passing an uninitialized opaque type into any function except the respective initailzation function will result in undefined behaviour, because OPAE will try to follow an invalid pointer. Undefined behaviour in this case may include an unexpected error code, or an application crash.

Public Types Documentation¶

typedef fpga_event_handle¶

Handle to an event object.

typedef void* fpga_event_handle;

OPAE provides an interface to asynchronous events that can be generated by different FPGA resources. The event API provides functions to register for these events; associated with every event a process has registered for is an fpga_event_handle, which encapsulates the OS-specific data structure for event objects.

After use, fpga_event_handle objects should be destroyed using fpgaDestroyEventHandle() to free backing memory used by the fpga_event_handle object.

typedef fpga_guid¶

Globally unique identifier (GUID)

typedef uint8_t fpga_guid[16];

GUIDs are used widely within OPAE for helping identify FPGA resources. For example, every FPGA resource has a guid property, which can be (and in the case of FPGA_ACCELERATOR resource primarily is) used for enumerating a resource of a specific type.

fpga_guid is compatible with libuuid's uuid_t, so users can use libuuid functions like uuid_parse() to create and work with GUIDs.

typedef fpga_handle¶

Handle to an FPGA resource.

typedef void* fpga_handle;

A valid fpga_handle object, as populated by fpgaOpen(), denotes ownership of an FPGA resource. Note that ownership can be exclusive or shared, depending on the flags used in fpgaOpen(). Ownership can be released by calling fpgaClose(), which will render the underlying handle invalid.

Many OPAE C API functions require a valid token (which is synonymous with ownership of the resource).

typedef fpga_metric¶

typedef struct fpga_metric fpga_metric;

typedef fpga_metric_info¶

typedef struct fpga_metric_info fpga_metric_info;

typedef fpga_object¶

Object pertaining to an FPGA resource as identified by a unique name.

typedef void* fpga_object;

An fpga_object represents either a device attribute or a container of attributes. Similar to filesystems, a '/' may be used to seperate objects in an object hierarchy. Once on object is acquired, it may be used to read or write data in a resource attribute or to query sub-objects if the object is a container object. The data in an object is buffered and will be kept around until the object is destroyed. Additionally, the data in an attribute can by synchronized from the owning resource using the FPGA_OBJECT_SYNC flag during read operations. The name identifying the object is unique with respect to the resource that owns it. A parent resource may be identified by an fpga_token object, by an fpga_handle object, or another fpga_object object. If a handle object is used when opening the object, then the object is opened with read-write access. Otherwise, the object is read-only.

typedef fpga_properties¶

Object for expressing FPGA resource properties.

typedef void* fpga_properties;

fpga_properties objects encapsulate all enumerable information about an FPGA resources. They can be used for two purposes: selective enumeration (discovery) and querying information about existing resources.

For selective enumeration, usually an empty fpga_properties object is created (using fpgaGetProperties()) and then populated with the desired criteria for enumeration. An array of fpga_properties can then be passed to fpgaEnumerate(), which will return a list of fpga_token objects matching these criteria.

For querying properties of existing FPGA resources, fpgaGetProperties() can also take an fpga_token and will return an fpga_properties object populated with information about the resource referenced by that token.

After use, fpga_properties objects should be destroyed using fpga_destroyProperties() to free backing memory used by the fpga_properties object.

typedef fpga_token¶

Token for referencing FPGA resources.

typedef void* fpga_token;

An fpga_token serves as a reference to a specific FPGA resource present in the system. Holding an fpga_token does not constitute ownership of the FPGA resource - it merely allows the user to query further information about a resource, or to use fpgaOpen() to acquire ownership.

fpga_tokens are usually returned by fpgaEnumerate() or fpgaPropertiesGetParent(), and used by fpgaOpen() to acquire ownership and yield a handle to the resource. Some API calls also take fpga_tokens as arguments if they don't require ownership of the resource in question.

typedef fpga_token_header¶

Internal token type header.

typedef struct _fpga_token_header fpga_token_header;

Each plugin (dfl: libxfpga.so, vfio: libopae-v.so) implements its own proprietary token type. This header must appear at offset zero within that structure.

eg, see lib/plugins/xfpga/types_int.h:struct _fpga_token and lib/plugins/vfio/opae_vfio.h:struct _vfio_token.

typedef metric_threshold¶

typedef struct metric_threshold metric_threshold;

union metric_value¶

typedef threshold¶

typedef struct threshold threshold;

Macro Definition Documentation¶

define FPGA_ERROR_NAME_MAX¶

Information about an error register.

#define FPGA_ERROR_NAME_MAX 64

This data structure captures information about an error register exposed by an accelerator resource. The error API provides functions to retrieve these information structures from a particular resource.

define FPGA_METRIC_STR_SIZE¶

#define FPGA_METRIC_STR_SIZE 256

define fpga_is_parent_child¶

Determine token parent/child relationship.

#define fpga_is_parent_child (
    __parent_hdr,
    __child_hdr
) (((__parent_hdr)->objtype == FPGA_DEVICE ) && \
 ((__child_hdr)->objtype == FPGA_ACCELERATOR ) && \
 ((__parent_hdr)->segment == (__child_hdr)->segment) && \
 ((__parent_hdr)->bus == (__child_hdr)->bus) && \
 ((__parent_hdr)->device == (__child_hdr)->device))

Given pointers to two fpga_token_header structs, determine whether the first is the parent of the second. A parent will have objtype == FPGA_DEVICE. A child will have objtype == FPGA_ACCELERATOR. The PCIe address of the two headers will match in all but the function fields.

The documentation for this class was generated from the following file docs/sw/include/opae/types.h