DOKK / manpages / debian 10 / libocxl-dev / ocxl_irq.3.en
ocxl_irq(3) Library Functions Manual ocxl_irq(3)

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


typedef struct ocxl_kernel_event_header ocxl_kernel_event_header
typedef struct ocxl_kernel_event_xsl_fault_error ocxl_kernel_event_xsl_fault_error


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.

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 struct ocxl_kernel_event_header ocxl_kernel_event_header

typedef struct ocxl_kernel_event_xsl_fault_error ocxl_kernel_event_xsl_fault_error

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:

afu the AFU holding the interrupts
timeout how 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
events the triggered events (caller allocated)
event_count the 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:

-1 if an error occurred

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:

afu the AFU holding the interrupts
timeout how 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
events the triggered events (caller allocated)
event_count the number of events that can fit into the events array
event_api_version the 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:

-1 if an error occurred

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:

afu the AFU the IRQ belongs to

Returns:

the handle

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:

afu the AFU to get the thread ID for
thread_id the thread ID

Return values:

OCXL_OK if the thread ID was retrieved successfully
OCXL_NO_DEV if the OpenCAPI device is not capable of Power 9 notify/wake

See also:

ocxl_wait()

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:

afu the AFU to allocate IRQs for
info user information to associate with the handle (may be NULL)
irq the 0 indexed IRQ number that was allocated. This will be monotonically incremented by each subsequent call.

Return values:

OCXL_OK if the IRQs have been allocated
OCXL_NO_MEM if a memory allocation error occurred

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

Parameters:

afu the AFU the IRQ belongs to
irq the IRQ to get the descriptor of

Returns:

the handle, or -1 if the descriptor is invalid

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:

afu the AFU the IRQ belongs to
irq the IRQ to get the handle of

Returns:

the handle, or 0 if the handle is invalid

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()) {


  ocxl_wait();
} // Pause execution until the condition variable is set
clear_condition_variable();
// Execution continues here

See also:

ocxl_afu_get_p9_thread_id()

Generated automatically by Doxygen for libocxl from the source code.

Tue Sep 11 2018 libocxl