File enum.h¶

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

APIs for resource enumeration and managing tokens. More...

#include <opae/types.h>

Public Functions¶

Type	Name
fpga_result	fpgaCloneToken (fpga_token src, fpga_token * dst) Clone a fpga_token object.
fpga_result	fpgaDestroyToken (fpga_token * token) Destroy a Token.
fpga_result	fpgaEnumerate (const fpga_properties * filters, uint32_t num_filters, fpga_token * tokens, uint32_t max_tokens, uint32_t * num_matches) Enumerate FPGA resources present in the system.

Detailed Description¶

These APIs are the first step for any application using OPAE to discover resources that are present on the system. They allow selective enumeration (i.e. getting a list of resources that match a given list of criteria) and methods to manage the lifecycle of tokens generated by fpgaEnumerate().

Public Functions Documentation¶

function fpgaCloneToken¶

Clone a fpga_token object.

fpga_result fpgaCloneToken (
    fpga_token src,
    fpga_token * dst
)

Creates a copy of an fpga_token object.

Note:

This call creates a new token object and allocates memory for it. It is the responsibility of the using application to free this memory after use by calling fpgaDestroyToken() for the cloned token.

Parameters:

src fpga_token object to copy
dst New fpga_token object cloned from 'src'

Returns:

FPGA_OK on success

function fpgaDestroyToken¶

Destroy a Token.

fpga_result fpgaDestroyToken (
    fpga_token * token
)

This function destroys a token created by fpgaEnumerate() and frees the associated memory.

Note:

fpgaDestroyToken() requires the address of an fpga_token as previously created by fpgaEnumerate() or fpgaCloneToken(). Passing any other value results in undefined behavior.

Parameters:

token fpga_token to destroy

Returns:

FPGA_OK on success

function fpgaEnumerate¶

Enumerate FPGA resources present in the system.

fpga_result fpgaEnumerate (
    const fpga_properties * filters,
    uint32_t num_filters,
    fpga_token * tokens,
    uint32_t max_tokens,
    uint32_t * num_matches
)

This call allows the user to query the system for FPGA resources that match a certain set of criteria, e.g. all accelerators that are assigned to a host interface and available, all FPGAs of a specific type, etc.

fpgaEnumerate() will create a number of fpga_tokens to represent the matching resources and populate the array tokens with these tokens. The max_tokens argument can be used to limit the number of tokens allocated/returned by fpgaEnumerate(); i.e., the number of tokens in the returned tokens array will be either max_tokens or num_matches (the number of resources matching the filter), whichever is smaller. Use fpgaDestroyToken() to destroy tokens that are no longer needed.

To query the number of matches for a particular set of filters (e.g. to allocate a tokens array of the appropriate size), call fpgaEnumerate() with the parameter tokens set to NULL; this will only return the number of matches in num_matches.

Note:

fpgaEnumerate() will allocate memory for the created tokens returned in tokens. It is the responsibility of the using application to free this memory after use by calling fpgaDestroyToken() for each of the returned tokens.

Parameters:

filters Array of fpga_properties objects describing the properties of the objects that should be returned. A resource is considered matching if its properties match any one of the supplied filters. To match all FPGA resources, pass an empty filters object (one without any filter criteria set) or pass a NULL filters parameter with num_filters set to 0.
num_filters Number of entries in the filters array, or 0 to match all FPGA resources when filters is NULL.
tokens Pointer to an array of fpga_token variables to be populated. If NULL is supplied, fpgaEnumerate() will not create any tokens, but it will return the number of possible matches in num_match.
max_tokens Maximum number of tokens that fpgaEnumerate() shall return (length of tokens array). There may be more or fewer matches than this number; num_matches is set to the number of actual matches.
num_matches Number of resources matching the filter criteria. This number can be higher than the number of tokens returned in the tokens array (depending on the value of max_tokens).

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if invalid pointers or objects are passed into the function. FPGA_NO_DRIVER if OPAE can't find the respective enumeration data structures usually provided by the driver. FPGA_NO_MEMORY if there was not enough memory to create tokens.

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