libocxl
Loading...
Searching...
No Matches
libocxl.h
Go to the documentation of this file.
1/*
2 * Copyright 2017 International Business Machines
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
25#ifndef _LIBOCXL_H
26#define _LIBOCXL_H
27
28#include <stdint.h>
29#include <stdio.h>
30#include <limits.h>
31#include <sys/select.h>
32#include <sys/mman.h> // Required for PROT_* for MMIO map calls
33#include <endian.h> // Required for htobe32 & friends in MMIO access wrappers
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39#define OCXL_NO_MESSAGES 0
40#define OCXL_ERRORS (1 << 0)
41#define OCXL_TRACING (1 << 1)
52
60
61#define AFU_NAME_MAX 24
66typedef struct ocxl_identifier {
67 uint8_t afu_index;
68 const char afu_name[AFU_NAME_MAX + 1];
70
74typedef struct ocxl_afu *ocxl_afu_h;
75
76#define OCXL_INVALID_AFU NULL
81typedef uint16_t ocxl_irq_h;
82
86typedef struct ocxl_mmio_area *ocxl_mmio_h;
87
88
92typedef enum {
93 OCXL_OK = 0,
103 /* Adding something? Update setup.c: ocxl_err_to_string too */
104} ocxl_err;
105
113
114
118typedef struct {
119 uint16_t irq;
120 uint64_t handle;
121 void *info;
122 uint64_t count;
124
128typedef struct {
129 void *addr;
130#ifdef _ARCH_PPC64
131 uint64_t dsisr;
132#endif
133 uint64_t count;
135
136
137#ifndef _DOXYGEN_
138#if defined(LIBOCXL_LIVE_DANGEROUSLY)
139#define LIBOCXL_WARN_UNUSED
140#elif defined(__clang__) && __clang_major__ < 3 || __clang_major__ == 3 && __clang_minor__ <= 8
141#define LIBOCXL_WARN_UNUSED
142#else
143#define LIBOCXL_WARN_UNUSED __attribute__ ((warn_unused_result))
144#endif
145#endif /* _DOXYGEN_ */
146
154typedef struct ocxl_event {
156 union {
157 ocxl_event_irq irq;
158 ocxl_event_translation_fault translation_fault;
159 uint64_t padding[16];
160 };
161} ocxl_event;
162
163#define OCXL_ATTACH_FLAGS_NONE (0)
164
165/* setup.c */
166void ocxl_enable_messages(uint64_t sources);
167void ocxl_set_error_message_handler(void (*handler)(ocxl_err error, const char *message));
168const char *ocxl_err_to_string(ocxl_err err) LIBOCXL_WARN_UNUSED;
169const char *ocxl_info() LIBOCXL_WARN_UNUSED;
170
171/* afu.c */
172/* AFU getters */
173const ocxl_identifier *ocxl_afu_get_identifier(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
174const char *ocxl_afu_get_device_path(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
175const char *ocxl_afu_get_sysfs_path(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
176void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor);
177uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
178
179/* AFU operations */
180ocxl_err ocxl_afu_open_specific(const char *name, const char *physical_function, int16_t afu_index,
181 ocxl_afu_h *afu) LIBOCXL_WARN_UNUSED;
182ocxl_err ocxl_afu_open_from_dev(const char *path, ocxl_afu_h *afu) LIBOCXL_WARN_UNUSED;
183ocxl_err ocxl_afu_open(const char *name, ocxl_afu_h *afu) LIBOCXL_WARN_UNUSED;
184void ocxl_afu_enable_messages(ocxl_afu_h afu, uint64_t sources);
185void ocxl_afu_set_error_message_handler(ocxl_afu_h afu, void (*handler)(ocxl_afu_h afu, ocxl_err error,
186 const char *message));
188ocxl_err ocxl_afu_attach(ocxl_afu_h afu, uint64_t flags) LIBOCXL_WARN_UNUSED;
189
190/* irq.c */
191/* AFU IRQ functions */
192ocxl_err ocxl_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h *irq_handle) LIBOCXL_WARN_UNUSED;
193uint64_t ocxl_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq) LIBOCXL_WARN_UNUSED;
194int ocxl_afu_get_event_fd(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
195int ocxl_irq_get_fd(ocxl_afu_h afu, ocxl_irq_h irq) LIBOCXL_WARN_UNUSED;
196int ocxl_afu_event_check_versioned(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count,
197 uint16_t event_api_version) LIBOCXL_WARN_UNUSED;
198#ifdef _ARCH_PPC64
199ocxl_err ocxl_afu_get_p9_thread_id(ocxl_afu_h afu, uint16_t *thread_id);
200#endif
201
207#if defined(_ARCH_PPC64) && !defined(__STRICT_ANSI__)
234#ifndef _DOXYGEN_
235static
236#endif
237inline void ocxl_wait()
238{
239 /* This would be just 'asm volatile ("wait")', but clang produces invalid machine code */
240 asm volatile (".long 0x7c00003c");
241}
242#elif defined(_ARCH_PPC64) && !defined(LIBOCXL_SUPPRESS_INACCESSIBLE_WARNINGS)
243#warning LibOCXL ocxl_wait() will not be available while ANSI C mode is enabled
244#endif
245
265LIBOCXL_WARN_UNUSED
266#ifndef _DOXYGEN_
267static
268#endif
269inline int ocxl_afu_event_check(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count)
270{
271 uint16_t event_api_version = 0;
272 return ocxl_afu_event_check_versioned(afu, timeout, events, event_count, event_api_version);
273}
274
279/* Platform specific: PPC64 */
280#ifdef _ARCH_PPC64
282#endif
283
284/* mmio.c */
285ocxl_err ocxl_mmio_map_advanced(ocxl_afu_h afu, ocxl_mmio_type type, size_t size, int prot, uint64_t flags,
286 off_t offset, ocxl_mmio_h *region) LIBOCXL_WARN_UNUSED;
287ocxl_err ocxl_mmio_map(ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region) LIBOCXL_WARN_UNUSED;
288void ocxl_mmio_unmap(ocxl_mmio_h region);
289int ocxl_mmio_get_fd(ocxl_afu_h afu, ocxl_mmio_type type) LIBOCXL_WARN_UNUSED;
290size_t ocxl_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type) LIBOCXL_WARN_UNUSED;
291ocxl_err ocxl_mmio_get_info(ocxl_mmio_h region, void **address, size_t *size);
292ocxl_err ocxl_mmio_read32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t *out);
293ocxl_err ocxl_mmio_read64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t *out);
294ocxl_err ocxl_mmio_write32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value);
295ocxl_err ocxl_mmio_write64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value);
296
297#ifdef __cplusplus
298}
299#endif
300#endif /* _LIBOCXL_H */
301
uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu)
Get the PASID for the currently open context.
Definition afu.c:60
const char * ocxl_afu_get_sysfs_path(ocxl_afu_h afu)
Get the canonical sysfs path of the AFU.
Definition afu.c:105
const char * ocxl_afu_get_device_path(ocxl_afu_h afu)
Get the canonical device path of the AFU.
Definition afu.c:91
const ocxl_identifier * ocxl_afu_get_identifier(ocxl_afu_h afu)
Get the identifier of the AFU.
Definition afu.c:75
void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor)
Get the version of the AFU.
Definition afu.c:121
ocxl_err ocxl_afu_open(const char *name, ocxl_afu_h *afu)
Open an AFU context with a specified name.
Definition afu.c:631
ocxl_err ocxl_afu_close(ocxl_afu_h afu)
Close an AFU and detach it from the context.
Definition afu.c:692
ocxl_err ocxl_afu_open_from_dev(const char *path, ocxl_afu_h *afu)
Open an AFU context at a specified path.
Definition afu.c:528
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.
Definition afu.c:562
void ocxl_wait()
A wrapper around the the POWER9 wait instruction.
Definition libocxl.h:237
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.
Definition irq.c:395
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.
Definition irq.c:497
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.
Definition libocxl.h:269
uint64_t ocxl_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq)
Get the 64 bit IRQ handle for an IRQ.
Definition irq.c:197
ocxl_err ocxl_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h *irq_handle)
Allocate an IRQ for an open AFU.
Definition irq.c:164
int ocxl_irq_get_fd(ocxl_afu_h afu, ocxl_irq_h irq)
Get the file descriptor associated with an IRQ.
Definition irq.c:216
int ocxl_afu_get_event_fd(ocxl_afu_h afu)
Get a descriptor that will trigger a poll when an AFU event occurs.
Definition irq.c:239
const char * ocxl_err_to_string(ocxl_err err)
Convert an error value to a string.
Definition setup.c:111
void ocxl_enable_messages(uint64_t sources)
Enable messages from libocxl open calls.
Definition setup.c:70
const char * ocxl_info()
Get version & compilation information about LibOCXL.
Definition setup.c:154
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.
Definition setup.c:93
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.
Definition afu.c:175
void ocxl_afu_enable_messages(ocxl_afu_h afu, uint64_t sources)
Enable messages from an AFU.
Definition afu.c:151
size_t ocxl_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type)
Get the size of an MMIO region for an AFU.
Definition mmio.c:383
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.
Definition mmio.c:753
int ocxl_mmio_get_fd(ocxl_afu_h afu, ocxl_mmio_type type)
Get a file descriptor for an MMIO area of an AFU.
Definition mmio.c:360
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.
Definition mmio.c:263
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.
Definition mmio.c:674
void ocxl_mmio_unmap(ocxl_mmio_h region)
Unmap an MMIO region from an AFU.
Definition mmio.c:336
ocxl_err ocxl_mmio_map(ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region)
Map an MMIO area of an AFU.
Definition mmio.c:324
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.
Definition mmio.c:718
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.
Definition mmio.c:630
ocxl_err ocxl_mmio_get_info(ocxl_mmio_h region, void **address, size_t *size)
Get the address & size of a mapped MMIO region.
Definition mmio.c:411
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.
Definition afu.c:769
ocxl_err
Potential return values from ocxl_* functions.
Definition libocxl.h:92
@ OCXL_NO_MORE_CONTEXTS
No more contexts can be opened on the AFU.
Definition libocxl.h:101
@ OCXL_NO_IRQ
no further interrupts are available, or the interrupt is invalid
Definition libocxl.h:97
@ OCXL_NO_DEV
The OpenCAPI device is not available.
Definition libocxl.h:95
@ OCXL_INVALID_ARGS
One or more arguments are invalid.
Definition libocxl.h:102
@ OCXL_OUT_OF_BOUNDS
The action requested falls outside the permitted area.
Definition libocxl.h:100
@ OCXL_INTERNAL_ERROR
an internal error has occurred
Definition libocxl.h:98
@ OCXL_OK
The call succeeded.
Definition libocxl.h:93
@ OCXL_ALREADY_DONE
The action requested has already been performed.
Definition libocxl.h:99
@ OCXL_NO_MEM
An out of memory error occurred.
Definition libocxl.h:94
@ OCXL_NO_CONTEXT
The call requires an open context on the AFU.
Definition libocxl.h:96
ocxl_mmio_type
Defines the type of an MMIO area.
Definition libocxl.h:56
@ OCXL_GLOBAL_MMIO
Definition libocxl.h:57
@ OCXL_PER_PASID_MMIO
Definition libocxl.h:58
struct ocxl_afu * ocxl_afu_h
A handle for an AFU.
Definition libocxl.h:74
ocxl_event_type type
Definition libocxl.h:155
uint16_t ocxl_irq_h
A handle for an IRQ on an AFU.
Definition libocxl.h:81
struct ocxl_mmio_area * ocxl_mmio_h
A handle for an MMIO region on an AFU.
Definition libocxl.h:86
uint16_t irq
The IRQ number of the AFU.
Definition libocxl.h:119
uint64_t handle
The 64 bit handle of the triggered IRQ.
Definition libocxl.h:120
ocxl_event_type
OCXL Event types.
Definition libocxl.h:109
@ OCXL_EVENT_TRANSLATION_FAULT
A memory translation fault occurred on the AFU.
Definition libocxl.h:111
@ OCXL_EVENT_IRQ
An AFU IRQ.
Definition libocxl.h:110
ocxl_endian
Defines the endianness of an AFU MMIO area.
Definition libocxl.h:47
@ OCXL_MMIO_HOST_ENDIAN
AFU data is the same endianness as the host.
Definition libocxl.h:50
@ OCXL_MMIO_LITTLE_ENDIAN
AFU data is little-endian.
Definition libocxl.h:49
@ OCXL_MMIO_BIG_ENDIAN
AFU data is big-endian.
Definition libocxl.h:48
#define AFU_NAME_MAX
The maximum length of an AFU name.
Definition libocxl.h:61
ocxl_err ocxl_afu_attach(ocxl_afu_h afu, uint64_t flags)
void * info
An opaque pointer associated with the IRQ.
Definition libocxl.h:121
uint8_t afu_index
The AFU Index.
Definition libocxl.h:67
const char afu_name[AFU_NAME_MAX+1]
The name of the AFU.
Definition libocxl.h:68
void * addr
The address that triggered the fault.
Definition libocxl.h:129
uint64_t dsisr
The value of the PPC64 specific DSISR (Data storage interrupt status register)
Definition libocxl.h:131
uint64_t count
The number of times the interrupt has been triggered since last checked.
Definition libocxl.h:122
An OCXL event.
Definition libocxl.h:154
The data for a triggered IRQ event.
Definition libocxl.h:118
The data for a triggered translation fault error event.
Definition libocxl.h:128
AFU identification information.
Definition libocxl.h:66