libocxl
Data Structures | Macros | Typedefs | Enumerations | Functions
libocxl.h File Reference

Go to the source code of this file.

Data Structures

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

Macros

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

Typedefs

typedef void * ocxl_afu_h
 A handle for an AFU. More...
 
typedef uint16_t ocxl_irq_h
 A handle for an IRQ on an AFU. More...
 
typedef void * ocxl_mmio_h
 A handle for an MMIO region on an AFU. More...
 

Enumerations

enum  ocxl_endian { OCXL_MMIO_BIG_ENDIAN = 0, OCXL_MMIO_LITTLE_ENDIAN = 1, OCXL_MMIO_HOST_ENDIAN = 2 }
 Defines the endianess of an AFU MMIO area. More...
 
enum  ocxl_mmio_type { OCXL_GLOBAL_MMIO, OCXL_PER_PASID_MMIO }
 Defines the type of an MMIO area. More...
 
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. More...
 
enum  ocxl_event_type { OCXL_EVENT_IRQ = 0, OCXL_EVENT_TRANSLATION_FAULT = 1 }
 OCXL Event types. More...
 

Functions

void ocxl_enable_messages (uint64_t sources)
 Enable messages from libocxl open calls. More...
 
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. More...
 
const char * ocxl_err_to_string (ocxl_err err)
 Convert an error value to a string. More...
 
const ocxl_identifierocxl_afu_get_identifier (ocxl_afu_h afu)
 Get the identifier of the AFU. More...
 
const char * ocxl_afu_get_device_path (ocxl_afu_h afu)
 Get the canonical device path of the AFU. More...
 
const char * ocxl_afu_get_sysfs_path (ocxl_afu_h afu)
 Get the canonical sysfs path of the AFU. More...
 
void ocxl_afu_get_version (ocxl_afu_h afu, uint8_t *major, uint8_t *minor)
 Get the version of the AFU. More...
 
uint32_t ocxl_afu_get_pasid (ocxl_afu_h afu)
 Get the PASID for the currently open context. More...
 
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. More...
 
ocxl_err ocxl_afu_open_from_dev (const char *path, ocxl_afu_h *afu)
 Open an AFU context at a specified path. More...
 
ocxl_err ocxl_afu_open (const char *name, ocxl_afu_h *afu)
 Open an AFU context with a specified name. More...
 
void ocxl_afu_enable_messages (ocxl_afu_h afu, uint64_t sources)
 Enable messages from an AFU. More...
 
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. More...
 
ocxl_err ocxl_afu_close (ocxl_afu_h afu)
 Close an AFU and detach it from the context. More...
 
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. More...
 
uint64_t ocxl_irq_get_handle (ocxl_afu_h afu, ocxl_irq_h irq)
 Get the 64 bit IRQ handle for an IRQ. More...
 
int ocxl_afu_get_event_fd (ocxl_afu_h afu)
 Get a descriptor that will trigger a poll when an AFU event occurs. More...
 
int ocxl_irq_get_fd (ocxl_afu_h afu, ocxl_irq_h irq)
 Get the file descriptor associated with an IRQ. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
ocxl_err ocxl_mmio_map (ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region)
 Map an MMIO area of an AFU. More...
 
void ocxl_mmio_unmap (ocxl_mmio_h region)
 Unmap an MMIO region from an AFU. More...
 
int ocxl_mmio_get_fd (ocxl_afu_h afu, ocxl_mmio_type type)
 Get a file descriptor for an MMIO area of an AFU. More...
 
size_t ocxl_mmio_size (ocxl_afu_h afu, ocxl_mmio_type type)
 Get the size of an MMIO region for an AFU. More...
 
ocxl_err ocxl_mmio_get_info (ocxl_mmio_h region, void **address, size_t *size)
 Get the address & size of a mapped MMIO region. More...
 
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 endianess. More...
 
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 endianess. More...
 
ocxl_err ocxl_mmio_write32 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value)
 Convert endianess and write a 32-bit value to an AFU's MMIO region. More...
 
ocxl_err ocxl_mmio_write64 (ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value)
 Convert endianess and write a 64-bit value to an AFU's MMIO region. More...
 

Data Structure Documentation

◆ ocxl_identifier

struct ocxl_identifier

AFU identification information.

Definition at line 58 of file libocxl.h.

Data Fields
uint8_t afu_index The AFU Index.
const char afu_name[AFU_NAME_MAX+1] The name of the AFU.

◆ ocxl_event_irq

struct ocxl_event_irq

The data for a triggered IRQ event.

Definition at line 110 of file libocxl.h.

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.

◆ ocxl_event_translation_fault

struct ocxl_event_translation_fault

The data for a triggered translation fault error event.

Definition at line 120 of file libocxl.h.

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)

◆ ocxl_event

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.

Definition at line 135 of file libocxl.h.

Data Fields
union ocxl_event __unnamed__
ocxl_event_type type

◆ ocxl_event.__unnamed__

union ocxl_event.__unnamed__

Definition at line 137 of file libocxl.h.

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

◆ AFU_NAME_MAX

#define AFU_NAME_MAX   24

The maximum length of an AFU name.

Definition at line 53 of file libocxl.h.

◆ OCXL_ATTACH_FLAGS_NONE

#define OCXL_ATTACH_FLAGS_NONE   (0)

Definition at line 144 of file libocxl.h.

◆ OCXL_ERRORS

#define OCXL_ERRORS   (1 << 0)

Error messages requested.

Definition at line 32 of file libocxl.h.

◆ OCXL_INVALID_AFU

#define OCXL_INVALID_AFU   NULL

An invalid AFU handle.

Definition at line 68 of file libocxl.h.

◆ OCXL_NO_MESSAGES

#define OCXL_NO_MESSAGES   0

No messages requested.

Definition at line 31 of file libocxl.h.

◆ OCXL_TRACING

#define OCXL_TRACING   (1 << 1)

Tracing requested.

Definition at line 33 of file libocxl.h.

Typedef Documentation

◆ ocxl_afu_h

typedef void* ocxl_afu_h

A handle for an AFU.

Definition at line 66 of file libocxl.h.

◆ ocxl_irq_h

typedef uint16_t ocxl_irq_h

A handle for an IRQ on an AFU.

Definition at line 73 of file libocxl.h.

◆ ocxl_mmio_h

typedef void* ocxl_mmio_h

A handle for an MMIO region on an AFU.

Definition at line 78 of file libocxl.h.

Enumeration Type Documentation

◆ ocxl_endian

Defines the endianess 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 endianess as the host.

Definition at line 39 of file libocxl.h.

◆ ocxl_err

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.

Definition at line 84 of file libocxl.h.

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

Definition at line 101 of file libocxl.h.

◆ ocxl_mmio_type

Defines the type of an MMIO area.

Enumerator
OCXL_GLOBAL_MMIO 
OCXL_PER_PASID_MMIO 

Definition at line 48 of file libocxl.h.

Function Documentation

◆ ocxl_afu_attach()

ocxl_err ocxl_afu_attach ( ocxl_afu_h  afu,
uint64_t  flags 
)