libocxl
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
36 extern "C" {
37 #endif
38 
39 #define OCXL_NO_MESSAGES 0
40 #define OCXL_ERRORS (1 << 0)
41 #define OCXL_TRACING (1 << 1)
47 typedef enum {
51 } ocxl_endian;
52 
56 typedef enum {
60 
61 #define AFU_NAME_MAX 24
66 typedef struct ocxl_identifier {
67  uint8_t afu_index;
68  const char afu_name[AFU_NAME_MAX + 1];
70 
74 typedef struct ocxl_afu *ocxl_afu_h;
75 
76 #define OCXL_INVALID_AFU NULL
81 typedef uint16_t ocxl_irq_h;
82 
86 typedef struct ocxl_mmio_area *ocxl_mmio_h;
87 
88 
92 typedef enum {
93  OCXL_OK = 0,
94  OCXL_NO_MEM = -1,
95  OCXL_NO_DEV = -2,
97  OCXL_NO_IRQ = -4,
103  /* Adding something? Update setup.c: ocxl_err_to_string too */
104 } ocxl_err;
105 
109 typedef enum {
113 
114 
118 typedef struct {
119  uint16_t irq;
120  uint64_t handle;
121  void *info;
122  uint64_t count;
124 
128 typedef 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 
154 typedef 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 */
166 void ocxl_enable_messages(uint64_t sources);
167 void ocxl_set_error_message_handler(void (*handler)(ocxl_err error, const char *message));
168 const char *ocxl_err_to_string(ocxl_err err) LIBOCXL_WARN_UNUSED;
169 const char *ocxl_info() LIBOCXL_WARN_UNUSED;
170 
171 /* afu.c */
172 /* AFU getters */
173 const ocxl_identifier *ocxl_afu_get_identifier(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
174 const char *ocxl_afu_get_device_path(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
175 const char *ocxl_afu_get_sysfs_path(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
176 void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor);
177 uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
178 
179 /* AFU operations */
180 ocxl_err ocxl_afu_open_specific(const char *name, const char *physical_function, int16_t afu_index,
181  ocxl_afu_h *afu) LIBOCXL_WARN_UNUSED;
182 ocxl_err ocxl_afu_open_from_dev(const char *path, ocxl_afu_h *afu) LIBOCXL_WARN_UNUSED;
183 ocxl_err ocxl_afu_open(const char *name, ocxl_afu_h *afu) LIBOCXL_WARN_UNUSED;
184 void ocxl_afu_enable_messages(ocxl_afu_h afu, uint64_t sources);
185 void ocxl_afu_set_error_message_handler(ocxl_afu_h afu, void (*handler)(ocxl_afu_h afu, ocxl_err error,
186  const char *message));
188 ocxl_err ocxl_afu_attach(ocxl_afu_h afu, uint64_t flags) LIBOCXL_WARN_UNUSED;
189 
190 /* irq.c */
191 /* AFU IRQ functions */
192 ocxl_err ocxl_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h *irq_handle) LIBOCXL_WARN_UNUSED;
193 uint64_t ocxl_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq) LIBOCXL_WARN_UNUSED;
194 int ocxl_afu_get_event_fd(ocxl_afu_h afu) LIBOCXL_WARN_UNUSED;
195 int ocxl_irq_get_fd(ocxl_afu_h afu, ocxl_irq_h irq) LIBOCXL_WARN_UNUSED;
196 int 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
199 ocxl_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_
235 static
236 #endif
237 inline 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 
265 LIBOCXL_WARN_UNUSED
266 #ifndef _DOXYGEN_
267 static
268 #endif
269 inline 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
281 ocxl_err ocxl_afu_set_ppc64_amr(ocxl_afu_h afu, uint64_t amr);
282 #endif
283 
284 /* mmio.c */
285 ocxl_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;
287 ocxl_err ocxl_mmio_map(ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region) LIBOCXL_WARN_UNUSED;
288 void ocxl_mmio_unmap(ocxl_mmio_h region);
289 int ocxl_mmio_get_fd(ocxl_afu_h afu, ocxl_mmio_type type) LIBOCXL_WARN_UNUSED;
290 size_t ocxl_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type) LIBOCXL_WARN_UNUSED;
291 ocxl_err ocxl_mmio_get_info(ocxl_mmio_h region, void **address, size_t *size);
292 ocxl_err ocxl_mmio_read32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t *out);
293 ocxl_err ocxl_mmio_read64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t *out);
294 ocxl_err ocxl_mmio_write32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value);
295 ocxl_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 
const ocxl_identifier * ocxl_afu_get_identifier(ocxl_afu_h afu)
Get the identifier of the AFU.
Definition: afu.c:75
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_device_path(ocxl_afu_h afu)
Get the canonical device path of the AFU.
Definition: afu.c:91
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
const char * ocxl_afu_get_sysfs_path(ocxl_afu_h afu)
Get the canonical sysfs path of the AFU.
Definition: afu.c:105
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
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
const char * ocxl_info()
Get version & compilation information about LibOCXL.
Definition: setup.c:154
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:380
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:750
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:357
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:260
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:671
void ocxl_mmio_unmap(ocxl_mmio_h region)
Unmap an MMIO region from an AFU.
Definition: mmio.c:333
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:321
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:715
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:627
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:408
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