Refactor MMIO API

 - Allow multiple regions to be mapped
 - Expose the MMIO pointer to allow the protection to be altered and to
facilitate unsafe accesses
 - Expose MMIO file descriptors to allow manual MMAP calls
 - Specify endianess at access time rather than when mapped to allow
or differing endianess registers
  - Combine global/per-PASID MMIO map calls

Signed-off-by: Alastair D'Silva <alastair@d-silva.org>

Author: deece

README.md

@@ -50,8 +50,8 @@ A typical use of libocxl will follow this pattern:
    handle in which the caller can store additional information. This is not used by OpenCAPI,
    but is passed as part of the event information to provide additional context to the IRQ handler.
 4. **Configure global MMIO:** Some AFUs may have a global MMIO area, which will contain configuration
-   information that will affect all PASIDs on the AFU. Use ocxl\_global\_mmio\_map to make the area available,
-   then use ocxl\_global\_mmio\_write32() and ocxl\_global\_mmio\_write64() to write the information.
+   information that will affect all PASIDs on the AFU. Use ocxl\_mmio\_map to make the area available,
+   then use ocxl\_mmio\_write32() and ocxl\_mmio\_write64() to write the information.
 5. **Configure the per-PASID MMIO:** Some AFUs support multiple contexts, and each context will
    get it's own MMIO area for configuration and communication. Typical information that may
    be communicated across the MMIO interface include IRQ handles (obtained with
@@ -64,10 +64,10 @@ A typical use of libocxl will follow this pattern:
 8. **Handle AFU IRQs:** Pending IRQs can be queried using ocxl\_afu\_event\_check(). An IRQ event
    contains the IRQ number, the info pointer assigned when activated, the 64 bit IRQ handle, and
    the number of times the IRQ has been triggered since last checked.
-9. **Read results:** Work completion may be signally by the AFU via an IRQ, or by writing to
+9. **Read results:** Work completion may be signalled by the AFU via an IRQ, or by writing to
    the MMIO area. Typically, bulk data should be written to a pointer passed to the AFU, however,
-   small quantities of data may be read from the MMIO area using ocxl\_global\_mmio\_read32() and
-   ocxl\_global\_mmio\_read64().
+   small quantities of data may be read from an MMIO area using ocxl\_mmio\_read32() and
+   ocxl\_mmio\_read64().
 10. **Termination:** ocxl\_afu\_free() will free all resources associated with an AFU handle.
 
 # Development

src/afu.c

@@ -116,44 +116,6 @@ void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor)
 	*minor = my_afu->version_minor;
 }
 
-/**
- * Get the file descriptor of an opened AFU
- * @param afu The AFU to get the descriptor of
- * @return the file descriptor
- */
-int ocxl_afu_get_fd(ocxl_afu_h afu)
-{
-	ocxl_afu *my_afu = (ocxl_afu *) afu;
-
-	return my_afu->fd;
-}
-
-/**
- * Get the size of the global MMIO region for an AFU
- *
- * @param afu the AFU to get the MMIO size of
- * @return the size of the global MMIO region
- */
-size_t ocxl_afu_get_global_mmio_size(ocxl_afu_h afu)
-{
-	ocxl_afu *my_afu = (ocxl_afu *) afu;
-
-	return my_afu->global_mmio.length;
-}
-
-/**
- * Get the size of the per-PASID MMIO region for an AFU
- *
- * @param afu the AFU to get the MMIO size of
- * @return the size of the per-PASID MMIO region
- */
-size_t ocxl_afu_get_mmio_size(ocxl_afu_h afu)
-{
-	ocxl_afu *my_afu = (ocxl_afu *) afu;
-
-	return my_afu->per_pasid_mmio.length;
-}
-
 /**
  * @}
  *
@@ -250,19 +212,23 @@ static void afu_init(ocxl_afu * afu)
 	afu->epoll_event_count = 0;
 	afu->global_mmio_fd = -1;
 
-	afu->global_mmio.endianess = OCXL_MMIO_HOST_ENDIAN;
 	afu->global_mmio.start = NULL;
 	afu->global_mmio.length = 0;
+	afu->global_mmio.type = OCXL_GLOBAL_MMIO;
 
-	afu->per_pasid_mmio.endianess = OCXL_MMIO_HOST_ENDIAN;
 	afu->per_pasid_mmio.start = NULL;
 	afu->per_pasid_mmio.length = 0;
+	afu->per_pasid_mmio.type = OCXL_PER_PASID_MMIO;
 
 	afu->page_size = sysconf(_SC_PAGESIZE);
 
 	afu->irqs = NULL;
 	afu->irq_count = 0;
-	afu->irq_size = 0;
+	afu->irq_max_count = 0;
+
+	afu->mmios = NULL;
+	afu->mmio_count = 0;
+	afu->mmio_max_count = 0;
 
 	afu->pasid = UINT32_MAX;
 
@@ -422,22 +388,30 @@ static ocxl_err afu_open(ocxl_afu *afu)
 		return OCXL_ALREADY_DONE;
 	}
 
+	ocxl_err rc;
+
 	int fd = open(afu->device_path, O_RDWR | O_CLOEXEC | O_NONBLOCK);
 	if (fd < 0) {
 		if (errno == ENOSPC) {
-			ocxl_err rc = OCXL_NO_MORE_CONTEXTS;
+			rc = OCXL_NO_MORE_CONTEXTS;
 			errmsg(afu, rc, "Could not open AFU device '%s', the maximum number of contexts has been reached: Error %d: %s",
 			       afu->device_path, errno, strerror(errno));
 			return rc;
 		}
 
-		ocxl_err rc = OCXL_NO_DEV;
+		rc = OCXL_NO_DEV;
 		errmsg(afu, rc, "Could not open AFU device '%s': Error %d: %s", afu->device_path, errno, strerror(errno));
 		return rc;
 	}
 
 	afu->fd = fd;
 
+	rc = global_mmio_open(afu);
+	if (rc != OCXL_OK) {
+		errmsg(afu, rc, "Could not open global MMIO descriptor");
+		return rc;
+	}
+
 	fd = epoll_create1(EPOLL_CLOEXEC);
 	if (fd < 0) {
 		ocxl_err rc = OCXL_NO_DEV;
@@ -597,7 +571,6 @@ ocxl_err ocxl_afu_open_specific(const char *name, const char *physical_function,
 		goto end;
 	}
 
-
 	for (int dev = 0; dev < glob_data.gl_pathc; dev++) {
 		const char *dev_path = glob_data.gl_pathv[dev];
 		ret = ocxl_afu_open_from_dev(dev_path, afu);
@@ -684,8 +657,14 @@ ocxl_err ocxl_afu_close(ocxl_afu_h afu)
 		return OCXL_ALREADY_DONE;
 	}
 
-	ocxl_mmio_unmap(afu);
-	ocxl_global_mmio_unmap(afu);
+	for (uint16_t mmio_idx = 0; mmio_idx < my_afu->mmio_count; mmio_idx++) {
+		ocxl_mmio_unmap((ocxl_mmio_h)&my_afu->mmios[mmio_idx]);
+	}
+
+	if (my_afu->global_mmio_fd) {
+		close(my_afu->global_mmio_fd);
+		my_afu->global_mmio_fd = -1;
+	}
 
 	if (my_afu->irqs) {
 		for (uint16_t irq = 0; irq < my_afu->irq_count; irq++) {
@@ -695,7 +674,7 @@ ocxl_err ocxl_afu_close(ocxl_afu_h afu)
 		free(my_afu->irqs);
 		my_afu->irqs = NULL;
 		my_afu->irq_count = 0;
-		my_afu->irq_size = 0;
+		my_afu->irq_max_count = 0;
 	}
 
 	if (my_afu->epoll_events) {

src/include/libocxl.h

@@ -21,6 +21,8 @@
 #include <stdio.h>
 #include <limits.h>
 #include <sys/select.h>
+#include <sys/mman.h>  // Required for PROT_* for MMIO map calls
+#include <endian.h> // Required for htobe32 & friends in MMIO access wrappers
 
 #ifdef __cplusplus
 extern "C" {
@@ -40,6 +42,14 @@ typedef enum {
 	OCXL_MMIO_HOST_ENDIAN = 2,		/**< AFU data is the same endianess as the host */
 } ocxl_endian;
 
+/**
+ * Defines the type of an MMIO area
+ */
+typedef enum {
+	OCXL_GLOBAL_MMIO,
+	OCXL_PER_PASID_MMIO
+} ocxl_mmio_type;
+
 #define AFU_NAME_MAX	24 /**< The maximum length of an AFU name */
 
 /**
@@ -62,6 +72,12 @@ typedef void *ocxl_afu_h;
  */
 typedef uint16_t ocxl_irq_h;
 
+/**
+ * A handle for an MMIO region on an AFU
+ */
+typedef void *ocxl_mmio_h;
+
+
 /**
  * Potential return values from ocxl_* functions
  */
@@ -75,6 +91,7 @@ typedef enum {
 	OCXL_ALREADY_DONE = -6,		/**< The action requested has already been performed */
 	OCXL_OUT_OF_BOUNDS = -7,	/**< The action requested falls outside the permitted area */
 	OCXL_NO_MORE_CONTEXTS = -8, /**< No more contexts can be opened on the AFU */
+	OCXL_INVALID_ARGS = -9,		/**< One or more arguments are invalid */
 	/* Adding something? Update setup.c: ocxl_err_to_string too */
 } ocxl_err;
 
@@ -134,9 +151,6 @@ const ocxl_identifier *ocxl_afu_get_identifier(ocxl_afu_h afu);
 const char *ocxl_afu_get_device_path(ocxl_afu_h afu);
 const char *ocxl_afu_get_sysfs_path(ocxl_afu_h afu);
 void ocxl_afu_get_version(ocxl_afu_h afu, uint8_t *major, uint8_t *minor);
-int ocxl_afu_get_fd(ocxl_afu_h afu);
-size_t ocxl_afu_get_global_mmio_size(ocxl_afu_h afu);
-size_t ocxl_afu_get_mmio_size(ocxl_afu_h afu);
 uint32_t ocxl_afu_get_pasid(ocxl_afu_h afu);
 
 /* AFU operations */
@@ -154,6 +168,7 @@ ocxl_err ocxl_afu_attach(ocxl_afu_h afu);
 /* AFU IRQ functions */
 ocxl_err ocxl_afu_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h * irq_handle);
 uint64_t ocxl_afu_irq_get_id(ocxl_afu_h afu, ocxl_irq_h irq);
+int ocxl_afu_get_event_fd(ocxl_afu_h afu);
 int ocxl_afu_event_check_versioned(ocxl_afu_h afu, int timeout, ocxl_event *events, uint16_t event_count,
                                    uint16_t event_api_version);
 
@@ -188,22 +203,18 @@ ocxl_err ocxl_afu_set_ppc64_amr(ocxl_afu_h afu, uint64_t amr);
 #endif
 
 /* mmio.c */
-ocxl_err ocxl_global_mmio_map(ocxl_afu_h afu, ocxl_endian endian);
-ocxl_err ocxl_mmio_map(ocxl_afu_h afu, ocxl_endian endian);
-
-ocxl_err ocxl_global_mmio_read32(ocxl_afu_h afu, size_t offset, uint32_t * out);
-ocxl_err ocxl_global_mmio_read64(ocxl_afu_h afu, size_t offset, uint64_t * out);
-ocxl_err ocxl_global_mmio_write32(ocxl_afu_h afu, size_t offset, uint32_t val);
-ocxl_err ocxl_global_mmio_write64(ocxl_afu_h afu, size_t offset, uint64_t val);
-
-ocxl_err ocxl_mmio_read32(ocxl_afu_h afu, size_t offset, uint32_t * out);
-ocxl_err ocxl_mmio_read64(ocxl_afu_h afu, size_t offset, uint64_t * out);
-ocxl_err ocxl_mmio_write32(ocxl_afu_h afu, size_t offset, uint32_t val);
-ocxl_err ocxl_mmio_write64(ocxl_afu_h afu, size_t offset, uint64_t val);
-
-/* MMIO low level API */
-void ocxl_global_mmio_unmap(ocxl_afu_h afu);
-void ocxl_mmio_unmap(ocxl_afu_h afu);
+size_t ocxl_afu_get_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type);
+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);
+ocxl_err ocxl_mmio_map(ocxl_afu_h afu, ocxl_mmio_type type, ocxl_mmio_h *region);
+void ocxl_mmio_unmap(ocxl_mmio_h region);
+int ocxl_mmio_get_fd(ocxl_afu_h afu, ocxl_mmio_type type);
+size_t ocxl_mmio_size(ocxl_afu_h afu, ocxl_mmio_type type);
+ocxl_err ocxl_mmio_get_info(ocxl_mmio_h region, void **address, size_t *size);
+ocxl_err ocxl_mmio_read32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t * out);
+ocxl_err ocxl_mmio_read64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t * out);
+ocxl_err ocxl_mmio_write32(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint32_t value);
+ocxl_err ocxl_mmio_write64(ocxl_mmio_h mmio, off_t offset, ocxl_endian endian, uint64_t value);
 
 #ifdef __cplusplus
 }

src/internal.c

@@ -131,3 +131,29 @@ void ocxl_default_afu_error_handler(ocxl_afu_h afu, ocxl_err error, const char *
 	fprintf(stderr, "ERROR: %s\t%s: %s\n", dev, ocxl_err_to_string(error), message);
 	pthread_mutex_unlock(&stderr_mutex);
 }
+
+/**
+ * Grow a buffer geometrically
+ *
+ * @param afu the AFU that owns the buffer
+ * @param buffer [in/out] the buffer to grow
+ * @param [in/out] the number of elements in the buffer
+ * @param size the size of a buffer element
+ * @param initial_count the initial number of elements in the buffer
+ */
+ocxl_err grow_buffer(ocxl_afu *afu, void **buffer, uint16_t *count, size_t size, size_t initial_count)
+{
+	size_t new_count = (*count > 0) ? 2 * *count : initial_count;
+	void *temp = realloc(*buffer, new_count * size);
+	if (temp == NULL) {
+		ocxl_err rc = OCXL_NO_MEM;
+		errmsg(afu, rc, "Could not realloc buffer to %lu elements of %lu bytes (%lu bytes total): %d '%s'",
+		       new_count, size, new_count * size, errno, strerror(errno));
+		return rc;
+	}
+
+	*buffer = temp;
+	*count = new_count;
+
+	return OCXL_OK;
+}

src/irq.c

@@ -163,17 +163,12 @@ ocxl_err ocxl_afu_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h * irq)
 {
 	ocxl_afu *my_afu = (ocxl_afu *) afu;
 
-	if (my_afu->irq_count == my_afu->irq_size) {
-		size_t new_size = (my_afu->irq_size > 0) ? 2 * my_afu->irq_size : INITIAL_IRQ_COUNT;
-		ocxl_irq *irqs = realloc(my_afu->irqs, new_size * sizeof(ocxl_irq));
-		if (irqs == NULL) {
-			ocxl_err rc = OCXL_NO_MEM;
-			errmsg(my_afu, rc, "Could not realloc IRQs for afu '%s' to %d IRQs",
-			       my_afu->identifier.afu_name, new_size);
+	if (my_afu->irq_count == my_afu->irq_max_count) {
+		ocxl_err rc = grow_buffer(my_afu, (void **)&my_afu->irqs, &my_afu->irq_max_count, sizeof(ocxl_irq), INITIAL_IRQ_COUNT);
+		if (rc != OCXL_OK) {
+			errmsg(my_afu, rc, "Could not grow IRQ buffer for AFU '%s'", my_afu->identifier.afu_name);
 			return rc;
 		}
-		my_afu->irqs = irqs;
-		my_afu->irq_size = new_size;
 	}
 
 	ocxl_err rc = irq_allocate(my_afu, &my_afu->irqs[my_afu->irq_count], info);
@@ -209,6 +204,23 @@ uint64_t ocxl_afu_irq_get_id(ocxl_afu_h afu, ocxl_irq_h irq)
 	return (uint64_t)my_afu->irqs[irq].addr;
 }
 
+/**
+ * Get a descriptor that will trigger a poll when an AFU event occurs
+ *
+ * When triggered, call ocxl_read_afu_event() to extract the event information
+ *
+ * @pre the AFU has been opened
+ * @see ocxl_afu_event_check()
+ * @param afu the AFU the IRQ belongs to
+ * @return the handle
+ */
+int ocxl_afu_get_event_fd(ocxl_afu_h afu)
+{
+	ocxl_afu *my_afu = (ocxl_afu *) afu;
+
+	return my_afu->fd;
+}
+
 typedef struct ocxl_kernel_event_header ocxl_kernel_event_header;
 typedef struct ocxl_kernel_event_xsl_fault_error ocxl_kernel_event_xsl_fault_error;
 

src/libocxl_internal.h

@@ -63,6 +63,8 @@ void trace_message(const char *label, const char *file, int line, const char *fu
 void errmsg(ocxl_afu *afu, ocxl_err error, const char *format, ...);
 void ocxl_default_error_handler(ocxl_err error, const char *message);
 void ocxl_default_afu_error_handler(ocxl_afu_h afu, ocxl_err error, const char *message);
+ocxl_err grow_buffer(ocxl_afu *afu, void **buffer, uint16_t *count, size_t size, size_t initial_count);
+ocxl_err global_mmio_open(ocxl_afu *afu);
 
 extern const char *sys_path;
 #define SYS_PATH_DEFAULT "/sys/class/ocxl"
@@ -73,6 +75,7 @@ extern const char *dev_path;
 #define DEVICE_PATH ((UNLIKELY(dev_path != NULL)) ? dev_path : DEV_PATH_DEFAULT)
 
 #define INITIAL_IRQ_COUNT 64
+#define INITIAL_MMIO_COUNT 4
 
 /**
  * @internal
@@ -81,7 +84,8 @@ extern const char *dev_path;
 typedef struct ocxl_mmio_area {
 	char *start; /**< The first addressable byte of the area */
 	size_t length; /**< The size of the area in bytes */
-	ocxl_endian endianess; /**< The endianess of the MMIO area */
+	ocxl_mmio_type type; /**< The type of the area */
+	ocxl_afu *afu; /**< The AFU this MMIO area belongs to */
 } ocxl_mmio_area;
 
 
@@ -109,7 +113,7 @@ typedef struct epoll_fd_source {
 struct ocxl_irq {
 	struct ocxl_ioctl_irq_fd event; /**< The event descriptor */
 	uint16_t irq_number; /**< The 0 indexed IRQ number */
-	void *addr; /**< The mmaped address of the IRQ page */
+	void *addr; /**< The mmapped address of the IRQ page */
 	void *info; /**< Additional info to pass to the user */
 	epoll_fd_source fd_info; /**< Epoll information for this IRQ */
 };
@@ -137,7 +141,12 @@ struct ocxl_afu {
 	size_t page_size;
 	ocxl_irq *irqs;
 	uint16_t irq_count; /**< The number of valid IRQs */
-	uint16_t irq_size; /**< The maximum number of IRQs available */
+	uint16_t irq_max_count; /**< The maximum number of IRQs available */
+
+	ocxl_mmio_area *mmios;
+	uint16_t mmio_count; /**< The number of valid MMIO regions */
+	uint16_t mmio_max_count; /**< The maximum number of MMIO regions available */
+
 	uint32_t pasid;
 
 	bool verbose_errors;
@@ -162,7 +171,6 @@ typedef enum ocxl_event_action {
 	OCXL_EVENT_ACTION_IGNORE,	/**< The event read was successful, but should be ignored */
 } ocxl_event_action;
 
-bool ocxl_afu_mmio_sizes(ocxl_afu * afu);
 void irq_dealloc(ocxl_afu * afu, ocxl_irq * irq);
 
 #endif				/* _LIBOCXL_INTERNAL_H */