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 
22 #ifndef _LIBOCXL_H
23 #define _LIBOCXL_H
24 
25 #include <stdint.h>
26 #include <stdio.h>
27 #include <limits.h>
28 #include <sys/select.h>
29 #include <sys/mman.h> // Required for PROT_* for MMIO map calls
30 #include <endian.h> // Required for htobe32 & friends in MMIO access wrappers
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 #define OCXL_NO_MESSAGES 0
37 #define OCXL_ERRORS (1 << 0)
38 #define OCXL_TRACING (1 << 1)
44 typedef enum {
48 } ocxl_endian;
49 
53 typedef enum {
57 
58 #define AFU_NAME_MAX 24
63 typedef struct ocxl_identifier {
64  uint8_t afu_index;
65  const char afu_name[AFU_NAME_MAX + 1];
67 
71 typedef void *ocxl_afu_h;
72 
73 #define OCXL_INVALID_AFU NULL
78 typedef uint16_t ocxl_irq_h;
79 
83 typedef void *ocxl_mmio_h;
84 
85 
89 typedef enum {
90  OCXL_OK = 0,
91  OCXL_NO_MEM = -1,
92  OCXL_NO_DEV = -2,
94  OCXL_NO_IRQ = -4,
100  /* Adding something? Update setup.c: ocxl_err_to_string too */
101 } ocxl_err;
102 
106 typedef enum {
110 
111 
115 typedef struct {
116  uint16_t irq;
117  uint64_t handle;
118  void *info;
119  uint64_t count;
121 
125 typedef struct {
126  void *addr;
127 #ifdef _ARCH_PPC64
128  uint64_t dsisr;
129 #endif
130  uint64_t count;
132 
140 typedef struct ocxl_event {
142  union {
143  ocxl_event_irq irq;
144  ocxl_event_translation_fault translation_fault;
145  uint64_t padding[16];
146  };
147 } ocxl_event;
148 
149 #define OCXL_ATTACH_FLAGS_NONE (0)
150 
151 /* setup.c */
152 void ocxl_enable_messages(uint64_t sources);
153 void ocxl_set_error_message_handler(void (*handler)(ocxl_err error, const char *message));
154 const char *ocxl_err_to_string(ocxl_err err);
155 const char *ocxl_info();
156 
157 /* afu.c */
158 /* AFU getters */
160 const char *ocxl_afu_get_device_path(ocxl_afu_h afu);
161 const char *ocxl_afu_get_sysfs_path(ocxl_afu_h afu);
162 void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor);
163 uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu);
164 
165 /* AFU operations */
166 ocxl_err ocxl_afu_open_specific(const char *name, const char *physical_function, int16_t afu_index, ocxl_afu_h *afu);
167 ocxl_err ocxl_afu_open_from_dev(const char *path, ocxl_afu_h *afu);
168 ocxl_err ocxl_afu_open(const char *name, ocxl_afu_h *afu);
169 void ocxl_afu_enable_messages(ocxl_afu_h afu, uint64_t sources);
170 void ocxl_afu_set_error_message_handler(ocxl_afu_h afu, void (*handler)(ocxl_afu_h afu, ocxl_err error,
171  const char *message));
173 ocxl_err ocxl_afu_attach(ocxl_afu_h afu, uint64_t flags);
174 
175 /* irq.c */
176 /* AFU IRQ functions */
177 ocxl_err ocxl_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h *irq_handle);
178 uint64_t ocxl_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq);
181 int ocxl_afu_event_check_versioned(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count,
182  uint16_t event_api_version);
183 
184 
209 #ifndef _DOXYGEN_
210 static
211 #endif
212 inline int ocxl_afu_event_check(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count)
213 {
214  uint16_t event_api_version = 0;
215  return ocxl_afu_event_check_versioned(afu, timeout, events, event_count, event_api_version);
216 }
217 
222 /* Platform specific: PPC64 */
223 #ifdef _ARCH_PPC64
224 ocxl_err ocxl_afu_set_ppc64_amr(ocxl_afu_h afu, uint64_t amr);
225 #endif
226 
227 /* mmio.c */
228 ocxl_err ocxl_mmio_map_advanced(ocxl_afu_h afu, ocxl_mmio_type type, size_t size, int prot, uint64_t flags,
229  off_t offset, ocxl_mmio_h *region);
231 void ocxl_mmio_unmap(ocxl_mmio_h region);
233 size_t ocxl_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type);
234 ocxl_err ocxl_mmio_get_info(ocxl_mmio_h region, void **address, size_t *size);
235 ocxl_err ocxl_mmio_read32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t *out);
236 ocxl_err ocxl_mmio_read64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t *out);
237 ocxl_err ocxl_mmio_write32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value);
238 ocxl_err ocxl_mmio_write64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value);
239 
240 #ifdef __cplusplus
241 }
242 #endif
243 #endif /* _LIBOCXL_H */
244 
An AFU IRQ.
Definition: libocxl.h:107
const char * ocxl_err_to_string(ocxl_err err)
Convert an error value to a string.
Definition: setup.c:111
AFU data is little-endian.
Definition: libocxl.h:46
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:786
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:262
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&#39;s MMIO region & convert endianness.
Definition: mmio.c:650
void * info
An opaque pointer associated with the IRQ.
Definition: libocxl.h:118
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:419
int ocxl_irq_get_fd(ocxl_afu_h afu, ocxl_irq_h irq)
Get the file descriptor associated with an IRQ.
Definition: irq.c:221
#define AFU_NAME_MAX
The maximum length of an AFU name.
Definition: libocxl.h:58
const ocxl_identifier * ocxl_afu_get_identifier(ocxl_afu_h afu)
Get the identifier of the AFU.
Definition: afu.c:77
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:246
ocxl_err
Potential return values from ocxl_* functions.
Definition: libocxl.h:89
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:389
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
uint16_t ocxl_irq_h
A handle for an IRQ on an AFU.
Definition: libocxl.h:78
The action requested falls outside the permitted area.
Definition: libocxl.h:97
The call requires an open context on the AFU.
Definition: libocxl.h:93
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&#39;s MMIO region & convert endianness.
Definition: mmio.c:694
void * addr
The address that triggered the fault.
Definition: libocxl.h:126
void ocxl_mmio_unmap(ocxl_mmio_h region)
Unmap an MMIO region from an AFU.
Definition: mmio.c:336
uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu)
Get the PASID for the currently open context.
Definition: afu.c:60
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
void * ocxl_mmio_h
A handle for an MMIO region on an AFU.
Definition: libocxl.h:83
One or more arguments are invalid.
Definition: libocxl.h:99
an internal error has occurred
Definition: libocxl.h:95
uint8_t afu_index
The AFU Index.
Definition: libocxl.h:64
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:165
ocxl_err ocxl_afu_open(const char *name, ocxl_afu_h *afu)
Open an AFU context with a specified name.
Definition: afu.c:644
ocxl_endian
Defines the endianness of an AFU MMIO area.
Definition: libocxl.h:44
uint64_t handle
The 64 bit handle of the triggered IRQ.
Definition: libocxl.h:117
const char * ocxl_afu_get_device_path(ocxl_afu_h afu)
Get the canonical device path of the AFU.
Definition: afu.c:95
The OpenCAPI device is not available.
Definition: libocxl.h:92
ocxl_event_type type
Definition: libocxl.h:141
The data for a triggered IRQ event.
Definition: libocxl.h:115
A memory translation fault occurred on the AFU.
Definition: libocxl.h:108
uint64_t dsisr
The value of the PPC64 specific DSISR (Data storage interrupt status register)
Definition: libocxl.h:128
void ocxl_afu_enable_messages(ocxl_afu_h afu, uint64_t sources)
Enable messages from an AFU.
Definition: afu.c:161
AFU identification information.
Definition: libocxl.h:63
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:541
const char * ocxl_info()
Get version & compilation information about LibOCXL.
Definition: setup.c:154
void ocxl_enable_messages(uint64_t sources)
Enable messages from libocxl open calls.
Definition: setup.c:70
void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor)
Get the version of the AFU.
Definition: afu.c:129
const char * ocxl_afu_get_sysfs_path(ocxl_afu_h afu)
Get the canonical sysfs path of the AFU.
Definition: afu.c:111
no further interrupts are available, or the interrupt is invalid
Definition: libocxl.h:94
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:200
ocxl_mmio_type
Defines the type of an MMIO area.
Definition: libocxl.h:53
ocxl_err ocxl_afu_close(ocxl_afu_h afu)
Close an AFU and detach it from the context.
Definition: afu.c:707
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&#39;s MMIO region.
Definition: mmio.c:738
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:212
AFU data is big-endian.
Definition: libocxl.h:45
void * ocxl_afu_h
A handle for an AFU.
Definition: libocxl.h:71
AFU data is the same endianness as the host.
Definition: libocxl.h:47
An out of memory error occurred.
Definition: libocxl.h:91
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&#39;s MMIO region.
Definition: mmio.c:773
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:362
An OCXL event.
Definition: libocxl.h:140
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:187
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:406
The data for a triggered translation fault error event.
Definition: libocxl.h:125
No more contexts can be opened on the AFU.
Definition: libocxl.h:98
ocxl_err ocxl_afu_attach(ocxl_afu_h afu, uint64_t flags)
The action requested has already been performed.
Definition: libocxl.h:96
uint16_t irq
The IRQ number of the AFU.
Definition: libocxl.h:116
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:575
uint64_t count
The number of times the interrupt has been triggered since last checked.
Definition: libocxl.h:119
ocxl_event_type
OCXL Event types.
Definition: libocxl.h:106
The call succeeded.
Definition: libocxl.h:90