File sysobject.h¶

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

Functions to read/write from system objects. More...

#include <opae/types.h>

Public Functions¶

Type	Name
fpga_result	fpgaDestroyObject (fpga_object * obj) Free memory used for the fpga_object data structure.
fpga_result	fpgaHandleGetObject (fpga_handle handle, const char * name, fpga_object * object, int flags) Create an `fpga_object` data structure from a handle.
fpga_result	fpgaObjectGetObject (fpga_object parent, const char * name, fpga_object * object, int flags) Create an `fpga_object` data structure from a parent object.
fpga_result	fpgaObjectGetObjectAt (fpga_object parent, size_t idx, fpga_object * object) Create an `fpga_object` data structure from a parent object using a given index.
fpga_result	fpgaObjectGetSize (fpga_object obj, uint32_t * value, int flags) Retrieve the size of the object.
fpga_result	fpgaObjectGetType (fpga_object obj, enum fpga_sysobject_type * type) Get the sysobject type (container or attribute)
fpga_result	fpgaObjectRead (fpga_object obj, uint8_t * buffer, size_t offset, size_t len, int flags) Read bytes from an FPGA object.
fpga_result	fpgaObjectRead64 (fpga_object obj, uint64_t * value, int flags) Read a 64-bit value from an FPGA object.
fpga_result	fpgaObjectWrite64 (fpga_object obj, uint64_t value, int flags) Write 64-bit value to an FPGA object.
fpga_result	fpgaTokenGetObject (fpga_token token, const char * name, fpga_object * object, int flags) Create an `fpga_object` data structures.

Detailed Description¶

On Linux systems with the OPAE kernel driver, this is used to access sysfs nodes created by the driver.

Public Functions Documentation¶

function fpgaDestroyObject¶

Free memory used for the fpga_object data structure.

fpga_result fpgaDestroyObject (
    fpga_object * obj
)

Note:

fpgaDestroyObject() requires the address of an fpga_object as created by fpgaTokenGetObject(), fpgaHandleGetObject(), or fpgaObjectGetObject(). Passing any other value results in undefind behavior.

Parameters:

obj Pointer to the fpga_object instance to destroy

Returns:

FPGA_OK on success, FPGA_INVALID_PARAM if the object is NULL, FPGA_EXCEPTION if an internal error is encountered.

function fpgaHandleGetObject¶

Create an fpga_object data structure from a handle.

fpga_result fpgaHandleGetObject (
    fpga_handle handle,
    const char * name,
    fpga_object * object,
    int flags
)

An fpga_object is a handle to an FPGA resource which can be an attribute, register, or container. This object has read/write access..

Parameters:

handle Handle identifying a resource (accelerator or device)
name A key identifying an object belonging to a resource.
object Pointer to memory to store the object in
flags Control behavior of object identification and creation FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be created for objects one level down from the object identified by name. FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all objects below the current object identified by name.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied parameters is invalid. FPGA_NOT_FOUND if an object cannot be found with the given key. FPGA_NOT_SUPPORTED if this function is not supported by the current implementation of this API.

Note:

Names that begin with '.' or '/' or contain '..' are not allowed and result in FPGA_INVALID_PARAM being returned

function fpgaObjectGetObject¶

Create an fpga_object data structure from a parent object.

fpga_result fpgaObjectGetObject (
    fpga_object parent,
    const char * name,
    fpga_object * object,
    int flags
)

An fpga_object is a handle to an FPGA resource which can be an attribute, register, or container. If the parent object was created with a handle, then the new object will inherit the handle allowing it to have read-write access to the object data.

Parameters:

parent A parent container fpga_object.
name A key identifying a sub-object of the parent container.
object Pointer to memory to store the object in.
flags Control behavior of object identification and creation. FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be created for objects one level down from the object identified by name. FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all objects below the current object identified by name.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied parameters is invalid - this includes a parent object that is not a container object. FPGA_NOT_FOUND if an object cannot be found with the given key. FPGA_NOT_SUPPORTED if this function is not supported by the current implementation of this API.

Note:

Names that begin with '.' or '/' or contain '..' are not allowed and result in FPGA_INVALID_PARAM being returned

function fpgaObjectGetObjectAt¶

Create an fpga_object data structure from a parent object using a given index.

fpga_result fpgaObjectGetObjectAt (
    fpga_object parent,
    size_t idx,
    fpga_object * object
)

An fpga_object is a handle to an FPGA resource which can be an attribute, register, or container. If the parent object was created with a handle, then the new object will inherit the handle allowing it to have read-write access to the object data.

Parameters:

parent A parent container 'fpga_object'
idx A positive index less than the size reported by the parent.
object Pointer to memory to store the object in.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied parameters is invalid - this includes a parent object that is not a container object. FPGA_NOT_FOUND if an object cannot be found with the given key. FPGA_NOT_SUPPORTED if this function is not supported by the current implementation of this API.

function fpgaObjectGetSize¶

Retrieve the size of the object.

fpga_result fpgaObjectGetSize (
    fpga_object obj,
    uint32_t * value,
    int flags
)

Parameters:

obj An fpga_object instance.
value Pointer to variable to store size in.
flags Flags that control how the object is read If FPGA_OBJECT_SYNC is used then object will update its buffered copy before retrieving the size.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if any of supplied parameters is invalid. FPGA_EXCEPTION if error occurred.

function fpgaObjectGetType¶

Get the sysobject type (container or attribute)

fpga_result fpgaObjectGetType (
    fpga_object obj,
    enum fpga_sysobject_type * type
)

Parameters:

obj An fpga_object instance
type The type of object (FPGA_OBJECT_CONTAINER or FPGA_OBJECT_ATTRIBUTE)

Returns:

FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied parameters are null or invalid

function fpgaObjectRead¶

Read bytes from an FPGA object.

fpga_result fpgaObjectRead (
    fpga_object obj,
    uint8_t * buffer,
    size_t offset,
    size_t len,
    int flags
)

Parameters:

obj An fpga_object instance.
buffer Pointer to a buffer to read bytes into.
offset Byte offset relative to objects internal buffer where to begin reading bytes from.
len The length, in bytes, to read from the object.
flags Flags that control how object is read If FPGA_OBJECT_SYNC is used then object will update its buffered copy before retrieving the data.

Returns:

FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied parameters is invalid

function fpgaObjectRead64¶

Read a 64-bit value from an FPGA object.

fpga_result fpgaObjectRead64 (
    fpga_object obj,
    uint64_t * value,
    int flags
)

The value is assumed to be in string format and will be parsed. See flags below for changing that behavior.

Parameters:

obj An fpga_object instance
value Pointer to a 64-bit variable to store the value in
flags Flags that control how the object is read If FPGA_OBJECT_SYNC is used then object will update its buffered copy before retrieving the data. If FPGA_OBJECT_RAW is used, then the data will be read as raw bytes into the uint64_t pointer variable.

Returns:

FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied parameters is invalid

function fpgaObjectWrite64¶

Write 64-bit value to an FPGA object.

fpga_result fpgaObjectWrite64 (
    fpga_object obj,
    uint64_t value,
    int flags
)

The value will be converted to string before writing. See flags below for changing that behavior.

Parameters:

obj An fpga_object instance.
value The value to write to the object
flags Flags that control how the object is written If FPGA_OBJECT_RAW is used, then the value will be written as raw bytes.

Returns:

FPGA_OK on success, FPGA_INVALID_PARAM if any of the supplied parameters is invalid

Note:

The object must have been created using a handle to a resource.

function fpgaTokenGetObject¶

Create an fpga_object data structures.

fpga_result fpgaTokenGetObject (
    fpga_token token,
    const char * name,
    fpga_object * object,
    int flags
)

An fpga_object is a handle to an FPGA resource which can be an attribute, register or a container. This object is read-only.

Parameters:

token Token identifying a resource (accelerator or device)
name A key identifying an object belonging to a resource.
object Pointer to memory to store the object in
flags Control behavior of object identification and creation. FPGA_OBJECT_GLOB is used to indicate that the name should be treated as a globbing expression. FPGA_OBJECT_RECURSE_ONE indicates that subobjects be created for objects one level down from the object identified by name. FPGA_OBJECT_RECURSE_ALL indicates that subobjects be created for all objects below the current object identified by name.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if any of the supplied parameters is invalid. FPGA_NOT_FOUND if an object cannot be found with the given key. FPGA_NOT_SUPPORTED if this function is not supported by the current implementation of this API.

Note:

Names that begin with '.' or '/' or contain '..' are not allowed and result in FPGA_INVALID_PARAM being returned

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