Expose IRQ & event descriptors

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

Author: deece

src/include/libocxl.h

@@ -139,7 +139,6 @@ typedef struct ocxl_event {
 	};
 } ocxl_event;
 
-
 /* setup.c */
 void ocxl_enable_messages(uint64_t sources);
 void ocxl_set_error_message_handler(void (*handler)(ocxl_err error, const char *message));
@@ -169,9 +168,12 @@ ocxl_err ocxl_afu_attach(ocxl_afu_h afu);
 ocxl_err ocxl_afu_irq_alloc(ocxl_afu_h afu, void *info, ocxl_irq_h * irq_handle);
 uint64_t ocxl_afu_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq);
 int ocxl_afu_get_event_fd(ocxl_afu_h afu);
+int ocxl_afu_irq_get_descriptor(ocxl_afu_h afu, ocxl_irq_h irq);
+int ocxl_afu_get_event_descriptor(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);
 
+
 /**
  * @addtogroup ocxl_irq
  * @{

src/irq.c

@@ -204,10 +204,37 @@ uint64_t ocxl_afu_irq_get_handle(ocxl_afu_h afu, ocxl_irq_h irq)
 	return (uint64_t)my_afu->irqs[irq].addr;
 }
 
+/**
+ * Get the file descriptor associated with an IRQ
+ *
+ * This descriptor may be used with select/poll to determine if an IRQ is triggered
+ *
+ * @param afu the AFU the IRQ belongs to
+ * @param irq the IRQ to get the descriptor of
+ * @return the handle, or -1 if the descriptor is invalid
+ */
+int ocxl_afu_irq_get_descriptor(ocxl_afu_h afu, ocxl_irq_h irq)
+{
+	ocxl_afu *my_afu = (ocxl_afu *) afu;
+
+	if (irq > my_afu->irq_count) {
+		return -1;
+	}
+
+	return my_afu->irqs[irq].event.eventfd;
+}
+
+
 /**
  * Get a descriptor that will trigger a poll when an AFU event occurs
  *
+<<<<<<< HEAD
  * When triggered, call ocxl_read_afu_event() to extract the event information
+=======
+ * When triggered, call ocxl_afu_event_check() to extract the event information.
+ *
+ * @see ocxl_afu_event_check()
+>>>>>>> 4339b2e... Make ocxl_read_afu_event internal
  *
  * @pre the AFU has been opened
  * @see ocxl_afu_event_check()
@@ -250,61 +277,83 @@ static void populate_xsl_fault_error(ocxl_afu *afu, ocxl_event *event, void *bod
 
 /**
  * @internal
- * Read events from the main AFU descriptor
+ *
+ * Read a single AFU event from the main AFU descriptor.
+ *
+ * An AFU may report OpenCAPI events independently from it's IRQs. When an event is
+ * available, as notified by the descriptor returned by ocxl_afu_get_event_fd()
+ * triggering a poll() or select(), this function will extract the information
+ * and notify the caller if there are any further events to be queried.
+ *
+ * If an event is available and should be handled by the caller,
+ * OCXL_EVENT_ACTION_SUCCESS is returned, and the event struct populated. The event struct
+ * should be parsed by first checking the type:
+ *   Value							| Action
+ *   ------------------------------ | -------
+ *   OCXL_EVENT_IRQ					| This value cannot be generated by this function
+ *   OCXL_EVENT_TRANSLATION_FAULT	| An OpenCAPI translation fault error has been issued, that is, the system has been unable to resolve an effective address. Events[i].translation_fault will be populated with the details of the error
+ *
+ * @see ocxl_afu_get_event_fd()
  *
  * @param afu the AFU to read the event from
- * @param max_supported_event the id of the maximum supported kernel event, events with an ID higher than this will be ignored
+ * @param event_api_version the version of the event API that the caller wants to see
  * @param[out] event event to populate
  * @param[out] last true if this was the last event to read from the kernel for now
  * @retval OCXL_EVENT_ACTION_SUCCESS if the event should be handled
  * @retval OCXL_EVENT_ACTION_FAIL if the event read failed (fatal)
  * @retval OCXL_EVENT_ACTION_NONE if there was no event to read
  * @retval OCXL_EVENT_ACTION_IGNORE if the read was successful but should be ignored
  */
-static ocxl_event_action read_afu_event(ocxl_afu *afu, uint16_t max_supported_event,
-                                        ocxl_event *event, bool *last) // hack to allow static symbol extraction
+static ocxl_event_action read_afu_event(ocxl_afu_h afu, uint16_t event_api_version, ocxl_event *event, int *last)
 {
+	ocxl_afu *my_afu = (ocxl_afu *) afu;
+
 	size_t event_size = sizeof(ocxl_kernel_event_header);
-	*last = true;
+	*last = 0;
 
-	switch (max_supported_event) {
-	case OCXL_AFU_EVENT_XSL_FAULT_ERROR:
+	uint16_t max_supported_event = 0;
+
+	switch (event_api_version) {
+	case 0:
 		event_size += sizeof(ocxl_kernel_event_xsl_fault_error);
+		max_supported_event = OCXL_AFU_EVENT_XSL_FAULT_ERROR;
 		break;
 	default:
-		errmsg(afu, OCXL_INTERNAL_ERROR, "Unknown maximum supported event type %u", max_supported_event);
+		errmsg(afu, OCXL_INTERNAL_ERROR, "Unsupported event API version %u, your libocxl library may be too old",
+		       event_api_version);
 		return OCXL_EVENT_ACTION_FAIL;
 	}
 
 	char buf[event_size];
 
 	int buf_used;
-	if ((buf_used = read(afu->fd, buf, event_size)) < 0) {
+	if ((buf_used = read(my_afu->fd, buf, event_size)) < 0) {
 		if (errno == EAGAIN || errno == EWOULDBLOCK) {
+			*last = 1;
 			return OCXL_EVENT_ACTION_NONE;
 		}
 
 		errmsg(afu, OCXL_INTERNAL_ERROR, "read of event header from fd %d for AFU '%s' failed: %d: %s",
-		       afu->fd, afu->identifier.afu_name, errno, strerror(errno));
+		       my_afu->fd, my_afu->identifier.afu_name, errno, strerror(errno));
 		return OCXL_EVENT_ACTION_FAIL;
 	} else if (buf_used < sizeof(ocxl_kernel_event_header)) {
 		errmsg(afu, OCXL_INTERNAL_ERROR, "short read of event header from fd %d for AFU '%s'",
-		       afu->fd, afu->identifier.afu_name);
+		       my_afu->fd, my_afu->identifier.afu_name);
 		return OCXL_EVENT_ACTION_FAIL;
 	}
 
 	ocxl_kernel_event_header *header = (ocxl_kernel_event_header *)buf;
 
 	if (header->type > max_supported_event) {
-		TRACE(afu, "Unknown event received from kernel of type %u", header->type);
+		TRACE(my_afu, "Unknown event received from kernel of type %u", header->type);
 		*last = !! (header->flags & OCXL_KERNEL_EVENT_FLAG_LAST);
 		return OCXL_EVENT_ACTION_IGNORE;
 	}
 
 	switch (header->type) {
 	case OCXL_AFU_EVENT_XSL_FAULT_ERROR:
 		if (buf_used != sizeof(ocxl_kernel_event_header) + sizeof(ocxl_kernel_event_xsl_fault_error)) {
-			errmsg(afu, OCXL_INTERNAL_ERROR,
+			errmsg(my_afu, OCXL_INTERNAL_ERROR,
 			       "Incorrectly sized buffer received from kernel for XSL fault error, expected %d, got %d",
 			       sizeof(ocxl_kernel_event_header) + sizeof(ocxl_kernel_event_xsl_fault_error),
 			       buf_used);
@@ -314,7 +363,7 @@ static ocxl_event_action read_afu_event(ocxl_afu *afu, uint16_t max_supported_ev
 		break;
 
 	default:
-		errmsg(afu, OCXL_INTERNAL_ERROR, "Unknown event %d, max_supported_event %d",
+		errmsg(my_afu, OCXL_INTERNAL_ERROR, "Unknown event %d, max_supported_event %d",
 		       header->type, max_supported_event);
 		return OCXL_EVENT_ACTION_FAIL;
 	}
@@ -323,7 +372,6 @@ static ocxl_event_action read_afu_event(ocxl_afu *afu, uint16_t max_supported_ev
 	return OCXL_EVENT_ACTION_SUCCESS;
 }
 
-
 /**
  * Check for pending IRQs and other events
  *
@@ -340,19 +388,6 @@ int ocxl_afu_event_check_versioned(ocxl_afu_h afu, int timeout, ocxl_event *even
                                    uint16_t event_api_version)
 {
 	ocxl_afu *my_afu = (ocxl_afu *) afu;
-	uint16_t max_supported_event;
-
-	switch (event_api_version) {
-	case 0:
-		max_supported_event = OCXL_AFU_EVENT_XSL_FAULT_ERROR;
-		break;
-
-	default:
-		errmsg(my_afu, OCXL_INTERNAL_ERROR, "Unsupported event API version %u, your libocxl library may be too old",
-		       event_api_version);
-		return -1;
-	}
-
 	TRACE(my_afu, "Waiting up to %dms for AFU events", timeout);
 
 	if (event_count > my_afu->epoll_event_count) {
@@ -382,11 +417,11 @@ int ocxl_afu_event_check_versioned(ocxl_afu_h afu, int timeout, ocxl_event *even
 		epoll_fd_source *info = (epoll_fd_source *)my_afu->epoll_events[event].data.ptr;
 		ocxl_event_action ret;
 		uint64_t count;
-		bool last;
+		int last;
 
 		switch (info->type) {
 		case EPOLL_SOURCE_OCXL:
-			while ((ret = read_afu_event(my_afu, max_supported_event, &events[triggered], &last)),
+			while ((ret = read_afu_event(my_afu, event_api_version, &events[triggered], &last)),
 			       ret == OCXL_EVENT_ACTION_SUCCESS || ret == OCXL_EVENT_ACTION_IGNORE) {
 				if (ret == OCXL_EVENT_ACTION_SUCCESS) {
 					triggered++;

src/libocxl_internal.h

@@ -94,6 +94,20 @@ typedef struct ocxl_irq ocxl_irq;
 
 /**
  * @internal
+ *
+ * The type of action to be taken upon return from the ocxl_read_afu_event() function
+ */
+typedef enum ocxl_event_action {
+	OCXL_EVENT_ACTION_SUCCESS,	/**< The event read was successful and should be handled */
+	OCXL_EVENT_ACTION_FAIL,		/**< The event read failed */
+	OCXL_EVENT_ACTION_NONE,		/**< There was no event to read */
+	OCXL_EVENT_ACTION_IGNORE,	/**< The event read was successful, but should be ignored */
+} ocxl_event_action;
+
+
+/**
+ * @internal
+ *
  * Metadata for determining which source triggered an epoll fd
  */
 typedef struct epoll_fd_source {
@@ -108,6 +122,7 @@ typedef struct epoll_fd_source {
 
 /**
  * @internal
+ *
  * AFU IRQ information
  */
 struct ocxl_irq {
@@ -122,6 +137,7 @@ struct ocxl_irq {
 
 /**
  * @internal
+ *
  * Represents an AFU
  */
 struct ocxl_afu {
@@ -160,17 +176,6 @@ struct ocxl_afu {
 #endif
 };
 
-/**
- * @internal
- * The type of action of the read_afu_event() function
- */
-typedef enum ocxl_event_action {
-	OCXL_EVENT_ACTION_SUCCESS,	/**< The event read was successful and should be handled */
-	OCXL_EVENT_ACTION_FAIL,		/**< The event read failed */
-	OCXL_EVENT_ACTION_NONE,		/**< There was no event to read */
-	OCXL_EVENT_ACTION_IGNORE,	/**< The event read was successful, but should be ignored */
-} ocxl_event_action;
-
 void irq_dealloc(ocxl_afu * afu, ocxl_irq * irq);
 
 #endif				/* _LIBOCXL_INTERNAL_H */

symver.map

@@ -19,9 +19,10 @@ LIBOCXL_0 {
 		ocxl_afu_open_specific;
 		ocxl_afu_attach;
 		ocxl_afu_irq_alloc;
-        ocxl_afu_irq_get_handle;
+		ocxl_afu_irq_get_handle;
         ocxl_afu_get_event_fd;
-		ocxl_afu_event_check;
+		ocxl_afu_irq_get_descriptor;
+		ocxl_afu_get_event_descriptor;
 		ocxl_afu_event_check_versioned;
 		ocxl_afu_set_ppc64_amr;
 		ocxl_mmio_map;

unittests/unittests.c

@@ -839,7 +839,7 @@ static void test_read_afu_event() {
 
 	ocxl_afu * my_afu = (ocxl_afu *)afu;
 	ocxl_event event;
-	bool last = false;
+	int last = 0;
 	ASSERT(OCXL_EVENT_ACTION_NONE == read_afu_event(my_afu, 0, &event, &last));
 	ASSERT(last);
 
@@ -849,7 +849,7 @@ static void test_read_afu_event() {
 	force_translation_fault((void *)0xfeeddeadbeeff00d, 16);
 #endif
 
-	last = false;
+	last = 0;
 	ASSERT(OCXL_EVENT_ACTION_SUCCESS == read_afu_event(my_afu, 0, &event, &last));
 	ASSERT(last);
 	ASSERT(event.type == OCXL_EVENT_TRANSLATION_FAULT);
@@ -865,7 +865,7 @@ static void test_read_afu_event() {
 	force_translation_fault((void *)0xfeeddeadbeeff00d, 16);
 #endif
 
-	last = false;
+	last = 0;
 	ASSERT(OCXL_EVENT_ACTION_SUCCESS == read_afu_event(my_afu, 0, &event, &last));
 	ASSERT(last);
 	ASSERT(event.type == OCXL_EVENT_TRANSLATION_FAULT);
@@ -875,7 +875,7 @@ static void test_read_afu_event() {
 #endif
 	ASSERT(event.translation_fault.count == 16);
 
-	last = false;
+	last = 0;
 	ASSERT(OCXL_EVENT_ACTION_NONE == read_afu_event(my_afu, 0, &event, &last));
 	ASSERT(last);