| ocxl_irq(3) | Library Functions Manual | ocxl_irq(3) |
ocxl_irq - OpenCAPI IRQ, Event & Wake Functions
- 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.
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
Returns
Return values
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
Parameters
Returns
Return values
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
Precondition
Parameters
Returns
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
Return values
See also
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
Return values
Get the file descriptor associated with an IRQ. This descriptor may be used with select/poll to determine if an IRQ is triggered.
Parameters
Returns
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
Returns
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
Generated automatically by Doxygen for libocxl from the source code.
| Mon Sep 19 2022 | libocxl |