Scroll to navigation

libocxl.h(3) Library Functions Manual libocxl.h(3)

NAME

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

SYNOPSIS

Data Structures


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.__unnamed__

Macros


#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)

Typedefs


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.

Enumerations


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. "

Functions


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.

Detailed Description

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.

Data Structure Documentation

struct ocxl_identifier

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.

struct ocxl_event_irq

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.

struct ocxl_event_translation_fault

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)

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

Data Fields:

union ocxl_event __unnamed__

ocxl_event_type type

union ocxl_event.__unnamed__

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.

Macro Definition Documentation

#define AFU_NAME_MAX 24

The maximum length of an AFU name.

#define OCXL_ATTACH_FLAGS_NONE (0)

#define OCXL_ERRORS (1 << 0)

Error messages requested.

#define OCXL_INVALID_AFU NULL

An invalid AFU handle.

#define OCXL_NO_MESSAGES 0

No messages requested.

#define OCXL_TRACING (1 << 1)

Tracing requested.

Typedef Documentation

typedef struct ocxl_afu* ocxl_afu_h

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.

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.

Enumeration Type Documentation

enum ocxl_endian

Defines the endianness of an AFU MMIO area.

Enumerator

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

enum ocxl_err

Potential return values from ocxl_* functions.

Enumerator

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

enum ocxl_event_type

OCXL Event types.

Enumerator

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

enum ocxl_mmio_type

Defines the type of an MMIO area.

Enumerator

OCXL_GLOBAL_MMIO
OCXL_PER_PASID_MMIO

Function Documentation

ocxl_err ocxl_afu_attach (ocxl_afu_h afu, uint64_t flags)

Author

Generated automatically by Doxygen for libocxl from the source code.
Tue Sep 11 2018 libocxl