File event.h¶

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

Functions for registering events and managing the lifecycle for fpga_event_handle s.More...

#include <opae/types.h>

Public Functions¶

Type	Name
fpga_result	fpgaCreateEventHandle (fpga_event_handle * event_handle) Initialize an event_handle.
fpga_result	fpgaDestroyEventHandle (fpga_event_handle * event_handle) Destroy an event_handle.
fpga_result	fpgaGetOSObjectFromEventHandle (const fpga_event_handle eh, int * fd) Get OS object from event handle.
fpga_result	fpgaRegisterEvent (fpga_handle handle, fpga_event_type event_type, fpga_event_handle event_handle, uint32_t flags) Register an FPGA event.
fpga_result	fpgaUnregisterEvent (fpga_handle handle, fpga_event_type event_type, fpga_event_handle event_handle) Unregister an FPGA event.

Detailed Description¶

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. On Linux, an fpga_event_handle can be used as a file descriptor and passed to select(), poll(), epoll() and similar functions to wait for asynchronous events.

Public Functions Documentation¶

function fpgaCreateEventHandle¶

Initialize an event_handle.

fpga_result fpgaCreateEventHandle (
    fpga_event_handle * event_handle
)

Platform independent way to initialize an event_handle used for notifications from the driver to application. For Linux, this function creates an eventfd and returns the eventfd file descriptor in *event_handle.

Parameters:

event_handle Pointer to event handle variable.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if event_handle is NULL. FPGA_NOT_SUPPORTED if platform does not support events.

function fpgaDestroyEventHandle¶

Destroy an event_handle.

fpga_result fpgaDestroyEventHandle (
    fpga_event_handle * event_handle
)

Destroy handle and free resources. On Linux this corresponds to closing the file descriptor pointed to by handle

Note:

fpgaDestroyEventHandle() requires the address of an event_handle as created by fpgaCreateEventHandle(). Passing any other value results in undefined behavior.

Parameters:

event_handle Pointer to handle to be destroyed

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if event_handle is NULL.

function fpgaGetOSObjectFromEventHandle¶

Get OS object from event handle.

fpga_result fpgaGetOSObjectFromEventHandle (
    const fpga_event_handle eh,
    int * fd
)

Check validity of event handle, and get the OS object used to subscribe and unsubscribe to events. On Linux, the object corresponds to a file descriptor.

Parameters:

eh Event handle to get the descriptor value from
fd integer to store the descriptor value

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if event_handle is invalid.

function fpgaRegisterEvent¶

Register an FPGA event.

fpga_result fpgaRegisterEvent (
    fpga_handle handle,
    fpga_event_type event_type,
    fpga_event_handle event_handle,
    uint32_t flags
)

This function tells the driver that the caller is interested in notification for the event specified by the type and flags pair.

The event_handle points to an OS specific mechanism for event notification. An event_handle is associated with only a single event.

In case of user interrupts, the flags parameter will be used to specify the vector ID. The value of the flags parameter indicates the vector ID, no bit encoding is used.

Todo

define if calling fpgaRegisterEvent multiple times with the same event_handle is an error condition or if it is silently ignored.

Parameters:

handle Handle to previously opened FPGA resource.
event_type Type of event
event_handle Handle to previously opened resource for event notification.
flags Optional argument for specifying additional information about event. For example irq number for interrupt events.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if handle does not refer to a resource supporting the requested event, or if event_handle is not valid. FPGA_EXCEPTION if an internal exception occurred while accessing the handle or the event_handle. On Linux: FPGA_NO_DAEMON if the driver does not support the requested event and there is no FPGA Daemon (fpgad) running to proxy it.

function fpgaUnregisterEvent¶

Unregister an FPGA event.

fpga_result fpgaUnregisterEvent (
    fpga_handle handle,
    fpga_event_type event_type,
    fpga_event_handle event_handle
)

This function tells the driver that the caller is no longer interested in notification for the event associated with the event_handle

The event_handle points to an OS specific mechanism for event notification. An event_handle is associated with only a single event.

Todo

define if calling fpgaUnregisterEvent multiple times with the same event_handle is an error condition or if it is silently ignored.

Parameters:

handle Handle to previously opened FPGA resource.
event_type Type of event to unregister.
event_handle Handle to previously registered resource for event notification.

Returns:

FPGA_OK on success. FPGA_INVALID_PARAM if handle does not refer to a resource supporting the requested event, or if event_handle is not valid. FPGA_EXCEPTION if an internal error occurred accessing the handle or the event_handle.

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