.TH "ocxl_irq" 3 "Tue Sep 11 2018" "libocxl" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ocxl_irq \- These functions allow the allocation and handling of AFU IRQs, OpenCAPI events, and wakes\&.  

.SH SYNOPSIS
.br
.PP
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct \fBocxl_kernel_event_header\fP \fBocxl_kernel_event_header\fP"
.br
.ti -1c
.RI "typedef struct \fBocxl_kernel_event_xsl_fault_error\fP \fBocxl_kernel_event_xsl_fault_error\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_irq_alloc\fP (\fBocxl_afu_h\fP afu, void *info, \fBocxl_irq_h\fP *irq)"
.br
.RI "Allocate an IRQ for an open AFU\&. "
.ti -1c
.RI "uint64_t \fBocxl_irq_get_handle\fP (\fBocxl_afu_h\fP afu, \fBocxl_irq_h\fP irq)"
.br
.RI "Get the 64 bit IRQ handle for an IRQ\&. "
.ti -1c
.RI "int \fBocxl_irq_get_fd\fP (\fBocxl_afu_h\fP afu, \fBocxl_irq_h\fP irq)"
.br
.RI "Get the file descriptor associated with an IRQ\&. "
.ti -1c
.RI "int \fBocxl_afu_get_event_fd\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Get a descriptor that will trigger a poll when an AFU event occurs\&. "
.ti -1c
.RI "int \fBocxl_afu_event_check_versioned\fP (\fBocxl_afu_h\fP afu, int timeout, \fBocxl_event\fP *events, uint16_t event_count, uint16_t event_api_version)"
.br
.RI "Check for pending IRQs and other events\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_get_p9_thread_id\fP (\fBocxl_afu_h\fP afu, uint16_t *thread_id)"
.br
.RI "Get the thread ID required to wake up a Power 9 wait instruction\&. "
.ti -1c
.RI "void \fBocxl_wait\fP ()"
.br
.RI "A wrapper around the the POWER9 wait instruction\&. "
.ti -1c
.RI "int \fBocxl_afu_event_check\fP (\fBocxl_afu_h\fP afu, int timeout, \fBocxl_event\fP *events, uint16_t event_count)"
.br
.RI "Check for pending IRQs and other events\&. "
.in -1c
.SH "Detailed Description"
.PP 
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()\&.
.PP
Each IRQ has an opaque pointer attached, which is communicated to the caller via the event struct passed back from \fBocxl_afu_event_check()\fP\&. This pointer can be used by the caller to save identifying information against the IRQ\&. 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBocxl_kernel_event_header\fP \fBocxl_kernel_event_header\fP"

.SS "typedef struct \fBocxl_kernel_event_xsl_fault_error\fP \fBocxl_kernel_event_xsl_fault_error\fP"

.SH "Function Documentation"
.PP 
.SS "int ocxl_afu_event_check (\fBocxl_afu_h\fP afu, int timeout, \fBocxl_event\fP * events, uint16_t event_count)\fC [inline]\fP"

.PP
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 
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU holding the interrupts 
.br
\fItimeout\fP 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 
.br
\fIevents\fP the triggered events (caller allocated) 
.br
\fIevent_count\fP the number of triggered events
.RE
.PP
\fBReturns:\fP
.RS 4
the number of events triggered, if this is the same as event_count, you should call ocxl_afu_event_check again 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI-1\fP if an error occurred 
.RE
.PP

.SS "int ocxl_afu_event_check_versioned (\fBocxl_afu_h\fP afu, int timeout, \fBocxl_event\fP * events, uint16_t event_count, uint16_t event_api_version)"

.PP
Check for pending IRQs and other events\&. This function should not be called directly, instead, use the \fBocxl_afu_event_check()\fP wrapper\&.
.PP
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 
.PP
\fBSee also:\fP
.RS 4
\fBocxl_afu_event_check\fP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU holding the interrupts 
.br
\fItimeout\fP 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 
.br
\fIevents\fP the triggered events (caller allocated) 
.br
\fIevent_count\fP the number of events that can fit into the events array 
.br
\fIevent_api_version\fP the version of the event API that the caller wants to see
.RE
.PP
\fBReturns:\fP
.RS 4
the number of events triggered, if this is the same as event_count, you should call ocxl_afu_event_check again 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI-1\fP if an error occurred 
.RE
.PP

.SS "int ocxl_afu_get_event_fd (\fBocxl_afu_h\fP afu)"

.PP
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\&.
.PP
\fBSee also:\fP
.RS 4
\fBocxl_afu_event_check()\fP
.RE
.PP
\fBPrecondition:\fP
.RS 4
the AFU has been opened
.RE
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU the IRQ belongs to
.RE
.PP
\fBReturns:\fP
.RS 4
the handle 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_afu_get_p9_thread_id (\fBocxl_afu_h\fP afu, uint16_t * thread_id)"

.PP
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\&.
.PP
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\&.
.PP
If sharing AFU contexts between threads, the thread ID should be requested only in the thread that will be waiting for the AFU context\&.
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to get the thread ID for 
.br
\fIthread_id\fP the thread ID 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the thread ID was retrieved successfully 
.br
\fIOCXL_NO_DEV\fP if the OpenCAPI device is not capable of Power 9 notify/wake
.RE
.PP
\fBSee also:\fP
.RS 4
\fBocxl_wait()\fP 
.RE
.PP

.SS "\fBocxl_err\fP ocxl_irq_alloc (\fBocxl_afu_h\fP afu, void * info, \fBocxl_irq_h\fP * irq)"

.PP
Allocate an IRQ for an open AFU\&. Once allocated, the IRQ handle can be retrieved with \fBocxl_irq_get_handle()\fP, 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 \fBocxl_afu_event_check()\fP, or by obtaining an event descriptor via \fBocxl_irq_get_fd()\fP and using it with poll(), select(), etc\&.
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU to allocate IRQs for 
.br
\fIinfo\fP user information to associate with the handle (may be NULL) 
.br
\fIirq\fP the 0 indexed IRQ number that was allocated\&. This will be monotonically incremented by each subsequent call\&.
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIOCXL_OK\fP if the IRQs have been allocated 
.br
\fIOCXL_NO_MEM\fP if a memory allocation error occurred 
.RE
.PP

.SS "int ocxl_irq_get_fd (\fBocxl_afu_h\fP afu, \fBocxl_irq_h\fP irq)"

.PP
Get the file descriptor associated with an IRQ\&. This descriptor may be used with select/poll to determine if an IRQ is triggered\&.
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU the IRQ belongs to 
.br
\fIirq\fP the IRQ to get the descriptor of
.RE
.PP
\fBReturns:\fP
.RS 4
the handle, or -1 if the descriptor is invalid 
.RE
.PP

.SS "uint64_t ocxl_irq_get_handle (\fBocxl_afu_h\fP afu, \fBocxl_irq_h\fP irq)"

.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fIafu\fP the AFU the IRQ belongs to 
.br
\fIirq\fP the IRQ to get the handle of
.RE
.PP
\fBReturns:\fP
.RS 4
the handle, or 0 if the handle is invalid 
.RE
.PP

.SS "void ocxl_wait ()\fC [inline]\fP"

.PP
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)\&.
.PP
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\&.
.PP
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 \fBocxl_afu_get_p9_thread_id()\fP)\&.
.PP
A typical usage will be: 
.PP
.nf
while (!condition_variable_is_set()) {
  ocxl_wait();
} // Pause execution until the condition variable is set

clear_condition_variable();

// Execution continues here

.fi
.PP
.PP
\fBSee also:\fP
.RS 4
\fBocxl_afu_get_p9_thread_id()\fP 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libocxl from the source code\&.