DOKK / manpages / debian 12 / libocxl-dev / OCXL_EVENT_IRQ.3.en
libocxl.h(3) Library Functions Manual libocxl.h(3)

libocxl.h - library functions to implement userspace drivers for OpenCAPI accelerators


struct ocxl_identifier
AFU identification information. struct ocxl_event_irq
The data for a triggered IRQ event. struct ocxl_event_translation_fault
The data for a triggered translation fault error event. struct ocxl_event
An OCXL event. union ocxl_event.__unnamed1__


#define OCXL_NO_MESSAGES 0
No messages requested. #define OCXL_ERRORS (1 << 0)
Error messages requested. #define OCXL_TRACING (1 << 1)
Tracing requested. #define AFU_NAME_MAX 24
The maximum length of an AFU name. #define OCXL_INVALID_AFU NULL
An invalid AFU handle. #define OCXL_ATTACH_FLAGS_NONE (0)


typedef struct ocxl_identifier ocxl_identifier
AFU identification information. typedef struct ocxl_afu * ocxl_afu_h
A handle for an AFU. typedef uint16_t ocxl_irq_h
A handle for an IRQ on an AFU. typedef struct ocxl_mmio_area * ocxl_mmio_h
A handle for an MMIO region on an AFU. typedef struct ocxl_event ocxl_event
An OCXL event.


enum ocxl_endian { OCXL_MMIO_BIG_ENDIAN = 0, OCXL_MMIO_LITTLE_ENDIAN = 1, OCXL_MMIO_HOST_ENDIAN = 2 }
Defines the endianness of an AFU MMIO area. enum ocxl_mmio_type { OCXL_GLOBAL_MMIO, OCXL_PER_PASID_MMIO }
Defines the type of an MMIO area. enum ocxl_err { OCXL_OK = 0, OCXL_NO_MEM = -1, OCXL_NO_DEV = -2, OCXL_NO_CONTEXT = -3, OCXL_NO_IRQ = -4, OCXL_INTERNAL_ERROR = -5, OCXL_ALREADY_DONE = -6, OCXL_OUT_OF_BOUNDS = -7, OCXL_NO_MORE_CONTEXTS = -8, OCXL_INVALID_ARGS = -9 }
Potential return values from ocxl_* functions. enum ocxl_event_type { OCXL_EVENT_IRQ = 0, OCXL_EVENT_TRANSLATION_FAULT = 1 }
OCXL Event types.


void ocxl_enable_messages (uint64_t sources)
Enable messages from libocxl open calls. void ocxl_set_error_message_handler (void(*handler)(ocxl_err error, const char *message))
Override the default handler for emitting error messages from open calls. const char * ocxl_err_to_string (ocxl_err err)
Convert an error value to a string. const char * ocxl_info ()
Get version & compilation information about LibOCXL. const ocxl_identifier * ocxl_afu_get_identifier (ocxl_afu_h afu)
Get the identifier of the AFU. const char * ocxl_afu_get_device_path (ocxl_afu_h afu)
Get the canonical device path of the AFU. const char * ocxl_afu_get_sysfs_path (ocxl_afu_h afu)
Get the canonical sysfs path of the AFU. void ocxl_afu_get_version (ocxl_afu_h afu, uint8_t *major, uint8_t *minor)
Get the version of the AFU. uint32_t ocxl_afu_get_pasid (ocxl_afu_h afu)
Get the PASID for the currently open context. ocxl_err ocxl_afu_open_specific (const char *name, const char *physical_function, int16_t afu_index, ocxl_afu_h *afu)
Open an AFU context with a specified name on a specific card/afu index. ocxl_err ocxl_afu_open_from_dev (const char *path, ocxl_afu_h *afu)
Open an AFU context at a specified path. ocxl_err ocxl_afu_open (const char *name, ocxl_afu_h *afu)
Open an AFU context with a specified name. void ocxl_afu_enable_messages (ocxl_afu_h afu, uint64_t sources)
Enable messages from an AFU. void ocxl_afu_set_error_message_handler (ocxl_afu_h afu, void(*handler)(ocxl_afu_h afu, ocxl_err error, const char *message))
Override the default handler for emitting error messages for an AFU. ocxl_err ocxl_afu_close (ocxl_afu_h afu)
Close an AFU and detach it from the context. ocxl_err ocxl_afu_attach (ocxl_afu_h afu, uint64_t flags)
ocxl_err ocxl_irq_alloc (ocxl_afu_h afu, void *info, ocxl_irq_h *irq_handle)
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_afu_get_event_fd (ocxl_afu_h afu)
Get a descriptor that will trigger a poll when an AFU event occurs. int ocxl_irq_get_fd (ocxl_afu_h afu, ocxl_irq_h irq)
Get the file descriptor associated with an IRQ. 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. ocxl_err ocxl_afu_set_ppc64_amr (ocxl_afu_h afu, uint64_t amr)
Set the PPC64-specific PSL AMR register value for restricting access to the AFU. ocxl_err ocxl_mmio_map_advanced (ocxl_afu_h afu, ocxl_mmio_type type, size_t size, int prot, uint64_t flags, off_t offset, ocxl_mmio_h *region)
Map an MMIO area of an AFU. ocxl_err ocxl_mmio_map (ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region)
Map an MMIO area of an AFU. void ocxl_mmio_unmap (ocxl_mmio_h region)
Unmap an MMIO region from an AFU. int ocxl_mmio_get_fd (ocxl_afu_h afu, ocxl_mmio_type type)
Get a file descriptor for an MMIO area of an AFU. size_t ocxl_mmio_size (ocxl_afu_h afu, ocxl_mmio_type type)
Get the size of an MMIO region for an AFU. ocxl_err ocxl_mmio_get_info (ocxl_mmio_h region, void **address, size_t *size)
Get the address & size of a mapped MMIO region. ocxl_err ocxl_mmio_read32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t *out)
Read a 32-bit value from an AFU's MMIO region & convert endianness. ocxl_err ocxl_mmio_read64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t *out)
Read a 64-bit value from an AFU's MMIO region & convert endianness. ocxl_err ocxl_mmio_write32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value)
Convert endianness and write a 32-bit value to an AFU's MMIO region. ocxl_err ocxl_mmio_write64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value)
Convert endianness and write a 64-bit value to an AFU's MMIO region.

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.

AFU identification information.

Data Fields:

uint8_t afu_index The AFU Index.

const char afu_name[AFU_NAME_MAX+1] The name of the AFU.

The data for a triggered IRQ event.

Data Fields:

uint64_t count The number of times the interrupt has been triggered since last checked.

uint64_t handle The 64 bit handle of the triggered IRQ.

void * info An opaque pointer associated with the IRQ.

uint16_t irq The IRQ number of the AFU.

The data for a triggered translation fault error event.

Data Fields:

void * addr The address that triggered the fault.

uint64_t count The number of times this address has triggered the fault.

uint64_t dsisr The value of the PPC64 specific DSISR (Data storage interrupt status register)

An OCXL event.

This may be an AFU interrupt, or a translation error, as determined by ocxl_event.type.

Once the type in known, the appropriate member of the anonymous union may be accessed.

Data Fields:

union ocxl_event.__unnamed1__ __unnamed__

ocxl_event_type type

Data Fields:

ocxl_event_irq irq Usable only when the type is OCXL_EVENT_IRQ.

uint64_t padding[16]

ocxl_event_translation_fault translation_fault Usable only when the type is OCXL_OCXL_EVENT_TRANSLATION_FAULT.

The maximum length of an AFU name.

_define_OCXL_ATTACH_FLAGS_NONE___(0)">">#define OCXL_ATTACH_FLAGS_NONE (0)

_define_OCXL_ERRORS___(1____0)">">#define OCXL_ERRORS (1 << 0)

Error messages requested.

An invalid AFU handle.

No messages requested.

_define_OCXL_TRACING___(1____1)">">#define OCXL_TRACING (1 << 1)

Tracing requested.

A handle for an AFU.

typedef struct ocxl_event ocxl_event

An OCXL event. This may be an AFU interrupt, or a translation error, as determined by ocxl_event.type.

Once the type in known, the appropriate member of the anonymous union may be accessed.

typedef struct ocxl_identifier ocxl_identifier

AFU identification information.

A handle for an IRQ on an AFU.

A handle for an MMIO region on an AFU.

enum ocxl_endian

Defines the endianness of an AFU MMIO area.

Enumerator

AFU data is big-endian.
AFU data is little-endian.
AFU data is the same endianness as the host.

enum ocxl_err

Potential return values from ocxl_* functions.

Enumerator

The call succeeded.
An out of memory error occurred.
The OpenCAPI device is not available.
The call requires an open context on the AFU.
no further interrupts are available, or the interrupt is invalid
an internal error has occurred
The action requested has already been performed.
The action requested falls outside the permitted area.
No more contexts can be opened on the AFU.
One or more arguments are invalid.

enum ocxl_event_type

OCXL Event types.

Enumerator

An AFU IRQ.
A memory translation fault occurred on the AFU.

enum ocxl_mmio_type

Defines the type of an MMIO area.

Enumerator

ocxl_err ocxl_afu_attach (ocxl_afu_h afu, uint64_t flags)

Generated automatically by Doxygen for libocxl from the source code.

Mon Sep 19 2022 libocxl