.TH "libocxl.h" 3 "Tue Sep 11 2018" "libocxl" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libocxl.h \- library functions to implement userspace drivers for OpenCAPI accelerators  

.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBocxl_identifier\fP"
.br
.RI "AFU identification information\&. "
.ti -1c
.RI "struct \fBocxl_event_irq\fP"
.br
.RI "The data for a triggered IRQ event\&. "
.ti -1c
.RI "struct \fBocxl_event_translation_fault\fP"
.br
.RI "The data for a triggered translation fault error event\&. "
.ti -1c
.RI "struct \fBocxl_event\fP"
.br
.RI "An OCXL event\&. "
.ti -1c
.RI "union \fBocxl_event\&.__unnamed__\fP"
.br
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBOCXL_NO_MESSAGES\fP   0"
.br
.RI "No messages requested\&. "
.ti -1c
.RI "#define \fBOCXL_ERRORS\fP   (1 << 0)"
.br
.RI "Error messages requested\&. "
.ti -1c
.RI "#define \fBOCXL_TRACING\fP   (1 << 1)"
.br
.RI "Tracing requested\&. "
.ti -1c
.RI "#define \fBAFU_NAME_MAX\fP   24"
.br
.RI "The maximum length of an AFU name\&. "
.ti -1c
.RI "#define \fBOCXL_INVALID_AFU\fP   NULL"
.br
.RI "An invalid AFU handle\&. "
.ti -1c
.RI "#define \fBOCXL_ATTACH_FLAGS_NONE\fP   (0)"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct \fBocxl_identifier\fP \fBocxl_identifier\fP"
.br
.RI "AFU identification information\&. "
.ti -1c
.RI "typedef struct ocxl_afu * \fBocxl_afu_h\fP"
.br
.RI "A handle for an AFU\&. "
.ti -1c
.RI "typedef uint16_t \fBocxl_irq_h\fP"
.br
.RI "A handle for an IRQ on an AFU\&. "
.ti -1c
.RI "typedef struct ocxl_mmio_area * \fBocxl_mmio_h\fP"
.br
.RI "A handle for an MMIO region on an AFU\&. "
.ti -1c
.RI "typedef struct \fBocxl_event\fP \fBocxl_event\fP"
.br
.RI "An OCXL event\&. "
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBocxl_endian\fP { \fBOCXL_MMIO_BIG_ENDIAN\fP = 0, \fBOCXL_MMIO_LITTLE_ENDIAN\fP = 1, \fBOCXL_MMIO_HOST_ENDIAN\fP = 2 }
.RI "Defines the endianness of an AFU MMIO area\&. ""
.br
.ti -1c
.RI "enum \fBocxl_mmio_type\fP { \fBOCXL_GLOBAL_MMIO\fP, \fBOCXL_PER_PASID_MMIO\fP }
.RI "Defines the type of an MMIO area\&. ""
.br
.ti -1c
.RI "enum \fBocxl_err\fP { \fBOCXL_OK\fP = 0, \fBOCXL_NO_MEM\fP = -1, \fBOCXL_NO_DEV\fP = -2, \fBOCXL_NO_CONTEXT\fP = -3, \fBOCXL_NO_IRQ\fP = -4, \fBOCXL_INTERNAL_ERROR\fP = -5, \fBOCXL_ALREADY_DONE\fP = -6, \fBOCXL_OUT_OF_BOUNDS\fP = -7, \fBOCXL_NO_MORE_CONTEXTS\fP = -8, \fBOCXL_INVALID_ARGS\fP = -9 }
.RI "Potential return values from ocxl_* functions\&. ""
.br
.ti -1c
.RI "enum \fBocxl_event_type\fP { \fBOCXL_EVENT_IRQ\fP = 0, \fBOCXL_EVENT_TRANSLATION_FAULT\fP = 1 }
.RI "OCXL Event types\&. ""
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBocxl_enable_messages\fP (uint64_t sources)"
.br
.RI "Enable messages from libocxl open calls\&. "
.ti -1c
.RI "void \fBocxl_set_error_message_handler\fP (void(*handler)(\fBocxl_err\fP error, const char *message))"
.br
.RI "Override the default handler for emitting error messages from open calls\&. "
.ti -1c
.RI "const char * \fBocxl_err_to_string\fP (\fBocxl_err\fP err)"
.br
.RI "Convert an error value to a string\&. "
.ti -1c
.RI "const char * \fBocxl_info\fP ()"
.br
.RI "Get version & compilation information about LibOCXL\&. "
.ti -1c
.RI "const \fBocxl_identifier\fP * \fBocxl_afu_get_identifier\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Get the identifier of the AFU\&. "
.ti -1c
.RI "const char * \fBocxl_afu_get_device_path\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Get the canonical device path of the AFU\&. "
.ti -1c
.RI "const char * \fBocxl_afu_get_sysfs_path\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Get the canonical sysfs path of the AFU\&. "
.ti -1c
.RI "void \fBocxl_afu_get_version\fP (\fBocxl_afu_h\fP afu, uint8_t *major, uint8_t *minor)"
.br
.RI "Get the version of the AFU\&. "
.ti -1c
.RI "uint32_t \fBocxl_afu_get_pasid\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Get the PASID for the currently open context\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_open_specific\fP (const char *name, const char *physical_function, int16_t afu_index, \fBocxl_afu_h\fP *afu)"
.br
.RI "Open an AFU context with a specified name on a specific card/afu index\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_open_from_dev\fP (const char *path, \fBocxl_afu_h\fP *afu)"
.br
.RI "Open an AFU context at a specified path\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_open\fP (const char *name, \fBocxl_afu_h\fP *afu)"
.br
.RI "Open an AFU context with a specified name\&. "
.ti -1c
.RI "void \fBocxl_afu_enable_messages\fP (\fBocxl_afu_h\fP afu, uint64_t sources)"
.br
.RI "Enable messages from an AFU\&. "
.ti -1c
.RI "void \fBocxl_afu_set_error_message_handler\fP (\fBocxl_afu_h\fP afu, void(*handler)(\fBocxl_afu_h\fP afu, \fBocxl_err\fP error, const char *message))"
.br
.RI "Override the default handler for emitting error messages for an AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_close\fP (\fBocxl_afu_h\fP afu)"
.br
.RI "Close an AFU and detach it from the context\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_attach\fP (\fBocxl_afu_h\fP afu, uint64_t flags)"
.br
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_irq_alloc\fP (\fBocxl_afu_h\fP afu, void *info, \fBocxl_irq_h\fP *irq_handle)"
.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_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_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_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\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_afu_set_ppc64_amr\fP (\fBocxl_afu_h\fP afu, uint64_t amr)"
.br
.RI "Set the PPC64-specific PSL AMR register value for restricting access to the AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_map_advanced\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type, size_t size, int prot, uint64_t flags, off_t offset, \fBocxl_mmio_h\fP *region)"
.br
.RI "Map an MMIO area of an AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_map\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type, \fBocxl_mmio_h\fP *region)"
.br
.RI "Map an MMIO area of an AFU\&. "
.ti -1c
.RI "void \fBocxl_mmio_unmap\fP (\fBocxl_mmio_h\fP region)"
.br
.RI "Unmap an MMIO region from an AFU\&. "
.ti -1c
.RI "int \fBocxl_mmio_get_fd\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type)"
.br
.RI "Get a file descriptor for an MMIO area of an AFU\&. "
.ti -1c
.RI "size_t \fBocxl_mmio_size\fP (\fBocxl_afu_h\fP afu, \fBocxl_mmio_type\fP type)"
.br
.RI "Get the size of an MMIO region for an AFU\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_get_info\fP (\fBocxl_mmio_h\fP region, void **address, size_t *size)"
.br
.RI "Get the address & size of a mapped MMIO region\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_read32\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint32_t *out)"
.br
.RI "Read a 32-bit value from an AFU's MMIO region & convert endianness\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_read64\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint64_t *out)"
.br
.RI "Read a 64-bit value from an AFU's MMIO region & convert endianness\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_write32\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint32_t value)"
.br
.RI "Convert endianness and write a 32-bit value to an AFU's MMIO region\&. "
.ti -1c
.RI "\fBocxl_err\fP \fBocxl_mmio_write64\fP (\fBocxl_mmio_h\fP mmio, off_t offset, \fBocxl_endian\fP endian, uint64_t value)"
.br
.RI "Convert endianness and write a 64-bit value to an AFU's MMIO region\&. "
.in -1c
.SH "Detailed Description"
.PP 
library functions to implement userspace drivers for OpenCAPI accelerators 

Define LIBOCXL_LIVE_DANGEROUSLY before including this header to suppress optional compiler warnings, such as warnings on unused return values\&. 
.SH "Data Structure Documentation"
.PP 
.SH "struct ocxl_identifier"
.PP 
AFU identification information\&. 
.PP
\fBData Fields:\fP
.RS 4
uint8_t \fIafu_index\fP The AFU Index\&. 
.br
.PP
const char \fIafu_name[\fBAFU_NAME_MAX\fP+1]\fP The name of the AFU\&. 
.br
.PP
.RE
.PP
.SH "struct ocxl_event_irq"
.PP 
The data for a triggered IRQ event\&. 
.PP
\fBData Fields:\fP
.RS 4
uint64_t \fIcount\fP The number of times the interrupt has been triggered since last checked\&. 
.br
.PP
uint64_t \fIhandle\fP The 64 bit handle of the triggered IRQ\&. 
.br
.PP
void * \fIinfo\fP An opaque pointer associated with the IRQ\&. 
.br
.PP
uint16_t \fIirq\fP The IRQ number of the AFU\&. 
.br
.PP
.RE
.PP
.SH "struct ocxl_event_translation_fault"
.PP 
The data for a triggered translation fault error event\&. 
.PP
\fBData Fields:\fP
.RS 4
void * \fIaddr\fP The address that triggered the fault\&. 
.br
.PP
uint64_t \fIcount\fP The number of times this address has triggered the fault\&. 
.br
.PP
uint64_t \fIdsisr\fP The value of the PPC64 specific DSISR (Data storage interrupt status register) 
.br
.PP
.RE
.PP
.SH "struct ocxl_event"
.PP 
An OCXL event\&. 

This may be an AFU interrupt, or a translation error, as determined by \fBocxl_event\&.type\fP\&.
.PP
Once the type in known, the appropriate member of the anonymous union may be accessed\&. 
.PP
\fBData Fields:\fP
.RS 4
union \fBocxl_event\fP \fI__unnamed__\fP 
.br
.PP
\fBocxl_event_type\fP \fItype\fP 
.br
.PP
.RE
.PP
.SH "union ocxl_event\&.__unnamed__"
.PP 
\fBData Fields:\fP
.RS 4
\fBocxl_event_irq\fP \fIirq\fP Usable only when the type is OCXL_EVENT_IRQ\&. 
.br
.PP
uint64_t \fIpadding[16]\fP 
.br
.PP
\fBocxl_event_translation_fault\fP \fItranslation_fault\fP Usable only when the type is OCXL_OCXL_EVENT_TRANSLATION_FAULT\&. 
.br
.PP
.RE
.PP
.SH "Macro Definition Documentation"
.PP 
.SS "#define AFU_NAME_MAX   24"

.PP
The maximum length of an AFU name\&. 
.SS "#define OCXL_ATTACH_FLAGS_NONE   (0)"

.SS "#define OCXL_ERRORS   (1 << 0)"

.PP
Error messages requested\&. 
.SS "#define OCXL_INVALID_AFU   NULL"

.PP
An invalid AFU handle\&. 
.SS "#define OCXL_NO_MESSAGES   0"

.PP
No messages requested\&. 
.SS "#define OCXL_TRACING   (1 << 1)"

.PP
Tracing requested\&. 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct ocxl_afu* \fBocxl_afu_h\fP"

.PP
A handle for an AFU\&. 
.SS "typedef struct \fBocxl_event\fP  \fBocxl_event\fP"

.PP
An OCXL event\&. This may be an AFU interrupt, or a translation error, as determined by \fBocxl_event\&.type\fP\&.
.PP
Once the type in known, the appropriate member of the anonymous union may be accessed\&. 
.SS "typedef struct \fBocxl_identifier\fP  \fBocxl_identifier\fP"

.PP
AFU identification information\&. 
.SS "typedef uint16_t \fBocxl_irq_h\fP"

.PP
A handle for an IRQ on an AFU\&. 
.SS "typedef struct ocxl_mmio_area* \fBocxl_mmio_h\fP"

.PP
A handle for an MMIO region on an AFU\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBocxl_endian\fP"

.PP
Defines the endianness of an AFU MMIO area\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIOCXL_MMIO_BIG_ENDIAN \fP\fP
AFU data is big-endian\&. 
.TP
\fB\fIOCXL_MMIO_LITTLE_ENDIAN \fP\fP
AFU data is little-endian\&. 
.TP
\fB\fIOCXL_MMIO_HOST_ENDIAN \fP\fP
AFU data is the same endianness as the host\&. 
.SS "enum \fBocxl_err\fP"

.PP
Potential return values from ocxl_* functions\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIOCXL_OK \fP\fP
The call succeeded\&. 
.TP
\fB\fIOCXL_NO_MEM \fP\fP
An out of memory error occurred\&. 
.TP
\fB\fIOCXL_NO_DEV \fP\fP
The OpenCAPI device is not available\&. 
.TP
\fB\fIOCXL_NO_CONTEXT \fP\fP
The call requires an open context on the AFU\&. 
.TP
\fB\fIOCXL_NO_IRQ \fP\fP
no further interrupts are available, or the interrupt is invalid 
.TP
\fB\fIOCXL_INTERNAL_ERROR \fP\fP
an internal error has occurred 
.TP
\fB\fIOCXL_ALREADY_DONE \fP\fP
The action requested has already been performed\&. 
.TP
\fB\fIOCXL_OUT_OF_BOUNDS \fP\fP
The action requested falls outside the permitted area\&. 
.TP
\fB\fIOCXL_NO_MORE_CONTEXTS \fP\fP
No more contexts can be opened on the AFU\&. 
.TP
\fB\fIOCXL_INVALID_ARGS \fP\fP
One or more arguments are invalid\&. 
.SS "enum \fBocxl_event_type\fP"

.PP
OCXL Event types\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIOCXL_EVENT_IRQ \fP\fP
An AFU IRQ\&. 
.TP
\fB\fIOCXL_EVENT_TRANSLATION_FAULT \fP\fP
A memory translation fault occurred on the AFU\&. 
.SS "enum \fBocxl_mmio_type\fP"

.PP
Defines the type of an MMIO area\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIOCXL_GLOBAL_MMIO \fP\fP
.TP
\fB\fIOCXL_PER_PASID_MMIO \fP\fP
.SH "Function Documentation"
.PP 
.SS "\fBocxl_err\fP ocxl_afu_attach (\fBocxl_afu_h\fP afu, uint64_t flags)"

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