libocxl
Loading...
Searching...
No Matches
Typedefs | Functions
OpenCAPI IRQ, Event & Wake Functions

These functions allow the allocation and handling of AFU IRQs, OpenCAPI events, and wakes. More...

Typedefs

typedef struct ocxl_kernel_event_header ocxl_kernel_event_header
 
typedef struct ocxl_kernel_event_xsl_fault_error ocxl_kernel_event_xsl_fault_error
 

Functions

ocxl_err ocxl_irq_alloc (ocxl_afu_h afu, void *info, ocxl_irq_h *irq)
 Allocate an IRQ for an open AFU.
 
uint64_t ocxl_irq_get_handle (ocxl_afu_h afu, ocxl_irq_h irq)
 Get the 64 bit IRQ handle for an IRQ.
 
int ocxl_irq_get_fd (ocxl_afu_h afu, ocxl_irq_h irq)
 Get the file descriptor associated with an IRQ.
 
int ocxl_afu_get_event_fd (ocxl_afu_h afu)
 Get a descriptor that will trigger a poll when an AFU event occurs.
 
int ocxl_afu_event_check_versioned (ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count, uint16_t event_api_version)
 Check for pending IRQs and other events.
 
ocxl_err ocxl_afu_get_p9_thread_id (ocxl_afu_h afu, uint16_t *thread_id)
 Get the thread ID required to wake up a Power 9 wait instruction.
 
void ocxl_wait ()
 A wrapper around the the POWER9 wait instruction.
 
int ocxl_afu_event_check (ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count)
 Check for pending IRQs and other events.
 

Detailed Description

These functions allow the allocation and handling of AFU IRQs, OpenCAPI events, and wakes.

IRQs can be handled either via requesting an array of triggered IRQ handles (via ocxl_afu_check), or by issuing callbacks via ocxl_afu_handle_callbacks().

Each IRQ has an opaque pointer attached, which is communicated to the caller via the event struct passed back from ocxl_afu_event_check(). This pointer can be used by the caller to save identifying information against the IRQ.

Typedef Documentation

◆ ocxl_kernel_event_header

Definition at line 244 of file irq.c.

◆ ocxl_kernel_event_xsl_fault_error

Definition at line 245 of file irq.c.

Function Documentation

◆ ocxl_afu_event_check()

int ocxl_afu_event_check ( ocxl_afu_h  afu,
int  timeout,
ocxl_event events,
uint16_t  event_count 
)
inline

Check for pending IRQs and other events.

Waits for the AFU to report an event or IRQs. On return, events will be populated with the reported number of events. Each event may be either an AFU event, or an IRQ, which can be determined by checking the value of events[i].type:

Value Action
OCXL_EVENT_IRQ An IRQ was triggered, and events[i].irq is populated with the IRQ information identifying which IRQ was triggered
OCXL_EVENT_TRANSLATION_FAULT An OpenCAPI translation fault error has been issued, that is, the system has been unable to resolve an effective address. Events[i].translation_fault will be populated with the details of the error
Parameters
afuthe AFU holding the interrupts
timeouthow long to wait (in milliseconds) for interrupts to arrive, set to -1 to wait indefinitely, or 0 to return immediately if no events are available
[out]eventsthe triggered events (caller allocated)
event_countthe number of triggered events
Returns
the number of events triggered, if this is the same as event_count, you should call ocxl_afu_event_check again
Return values
-1if an error occurred

Definition at line 269 of file libocxl.h.

◆ ocxl_afu_event_check_versioned()

int ocxl_afu_event_check_versioned ( ocxl_afu_h  afu,
int  timeout,
ocxl_event events,
uint16_t  event_count,
uint16_t  event_api_version 
)

Check for pending IRQs and other events.

This function should not be called directly, instead, use the ocxl_afu_event_check() wrapper.

Waits for the AFU to report an event or IRQs. On return, events will be populated with the reported number of events. Each event may be either an AFU event, or an IRQ, which can be determined by checking the value of events[i].type:

Value Action
OCXL_EVENT_IRQ An IRQ was triggered, and events[i].irq is populated with the IRQ information identifying which IRQ was triggered
OCXL_EVENT_TRANSLATION_FAULT An OpenCAPI translation fault error has been issued, that is, the system has been unable to resolve an effective address. Events[i].translation_fault will be populated with the details of the error
See also
ocxl_afu_event_check
Parameters
afuthe AFU holding the interrupts
timeouthow long to wait (in milliseconds) for interrupts to arrive, set to -1 to wait indefinitely, or 0 to return immediately if no events are available
[out]eventsthe triggered events (caller allocated)
event_countthe number of events that can fit into the events array
event_api_versionthe version of the event API that the caller wants to see
Returns
the number of events triggered, if this is the same as event_count, you should call ocxl_afu_event_check again
Return values
-1if an error occurred

Definition at line 395 of file irq.c.

◆ ocxl_afu_get_event_fd()

int ocxl_afu_get_event_fd ( ocxl_afu_h  afu)

Get a descriptor that will trigger a poll when an AFU event occurs.

When triggered, call ocxl_read_afu_event() to extract the event information.

See also
ocxl_afu_event_check()
Precondition
the AFU has been opened
Parameters
afuthe AFU the IRQ belongs to
Returns
the handle

Definition at line 239 of file irq.c.

◆ ocxl_afu_get_p9_thread_id()

ocxl_err ocxl_afu_get_p9_thread_id ( ocxl_afu_h  afu,
uint16_t *  thread_id 
)

Get the thread ID required to wake up a Power 9 wait instruction.

The thread ID should be provided to the AFU, along with a condition variable to indicate a true wake condition.

Note that multiple AFU contexts within the same thread will share the same thread ID. Thread IDs are cached within a context, and are requested from the kernel the first time this function is called for an AFU context.

If sharing AFU contexts between threads, the thread ID should be requested only in the thread that will be waiting for the AFU context.

Parameters
afuthe AFU to get the thread ID for
[out]thread_idthe thread ID
Return values
OCXL_OKif the thread ID was retrieved successfully
OCXL_NO_DEVif the OpenCAPI device is not capable of Power 9 notify/wake
See also
ocxl_wait()

Definition at line 497 of file irq.c.

◆ ocxl_irq_alloc()

ocxl_err ocxl_irq_alloc ( ocxl_afu_h  afu,
void *  info,
ocxl_irq_h irq 
)

Allocate an IRQ for an open AFU.

Once allocated, the IRQ handle can be retrieved with ocxl_irq_get_handle(), and written into an AFU specific register in the AFU's MMIO area. The AFU can then trigger the IRQ, which can be listened for with ocxl_afu_event_check(), or by obtaining an event descriptor via ocxl_irq_get_fd() and using it with poll(), select(), etc.

Parameters
afuthe AFU to allocate IRQs for
infouser information to associate with the handle (may be NULL)
[out]irqthe 0 indexed IRQ number that was allocated. This will be monotonically incremented by each subsequent call.
Return values
OCXL_OKif the IRQs have been allocated
OCXL_NO_MEMif a memory allocation error occurred

Definition at line 164 of file irq.c.

◆ ocxl_irq_get_fd()

int ocxl_irq_get_fd ( ocxl_afu_h  afu,
ocxl_irq_h  irq 
)

Get the file descriptor associated with an IRQ.

This descriptor may be used with select/poll to determine if an IRQ is triggered.

Parameters
afuthe AFU the IRQ belongs to
irqthe IRQ to get the descriptor of
Returns
the handle, or -1 if the descriptor is invalid

Definition at line 216 of file irq.c.

◆ ocxl_irq_get_handle()

uint64_t ocxl_irq_get_handle ( ocxl_afu_h  afu,
ocxl_irq_h  irq 
)

Get the 64 bit IRQ handle for an IRQ.

This handle can be written to the AFU's MMIO area to allow the AFU to trigger the IRQ.

Parameters
afuthe AFU the IRQ belongs to
irqthe IRQ to get the handle of
Returns
the handle, or 0 if the handle is invalid

Definition at line 197 of file irq.c.

◆ ocxl_wait()

void ocxl_wait ( )
inline

A wrapper around the the POWER9 wait instruction.

The wake_host_thread/wait mechanism provide a low-latency way for an AFU to signal to the calling thread that a condition has been met (eg. work has been completed).

This function will cause the thread to wait until woken by the AFU via wake_host_thread. As the thread may be woken for reasons other than wake_host_thread, a condition variable must be set by the AFU before issuing the wake.

In order to successfully wake a waiting thread, the AFU must know the address of the condition variable, and the thread ID of the application (via ocxl_afu_get_p9_thread_id()).

A typical usage will be:

while (!condition_variable_is_set()) {
} // Pause execution until the condition variable is set
clear_condition_variable();
// Execution continues here
void ocxl_wait()
A wrapper around the the POWER9 wait instruction.
Definition libocxl.h:237
See also
ocxl_afu_get_p9_thread_id()

Definition at line 237 of file libocxl.h.