Add support for environment based debug

The following environment variables can be set:
 - LIBOCXL_INFO
	print information about the version of LibOCXL in use
 - LIBOCXL_VERBOSE_ERRORS_ALL
	force verbose error reporting
 - LIBOCXL_TRACE_ALL
	force all AFU tracing

Also add ocxl_info() to return the build information as a string.

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

Author: deece

.gitignore

@@ -1,6 +1,7 @@
 *~
 *.orig
 .*.swp
+src/libocxl_info.h
 obj/*
 testobj/*
 sampleobj/*

Makefile

@@ -33,6 +33,11 @@ else
 endif
 endif
 
+src/libocxl_info.h: version.pl
+	VERSION_MAJOR=${VERSION_MAJOR} VERSION_MINOR=${VERSION_MINOR} \
+	CC="${CC}" CFLAGS="${CFLAGS}" \
+	./version.pl > src/libocxl_info.h
+
 obj:
 	mkdir obj
 

Makefile.rules

@@ -19,10 +19,10 @@ define Q
 endef
 endif
 
-obj/%.o : src/%.c src/include/libocxl.h src/libocxl_internal.h | obj
+obj/%.o : src/%.c src/include/libocxl.h src/libocxl_internal.h src/libocxl_info.h | obj
 	$(call Q,CC, $(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@ $<, $@)
 
-testobj/%.o : src/%.c src/include/libocxl.h src/libocxl_internal.h | testobj
+testobj/%.o : src/%.c src/include/libocxl.h src/libocxl_internal.h src/libocxl_info.h | testobj
 	$(call Q,CC, $(CC) $(CPPFLAGS) $(TESTCFLAGS) -c -o $@ $<, $@)
 
 testobj/%.o-test : unittests/%.c testobj/libocxl.a | testobj

README.md

@@ -71,6 +71,11 @@ A typical use of libocxl will follow this pattern:
 10. **Termination:** ocxl\_afu\_close() will free all resources associated with an AFU handle.
 
 # Development
+The following environment variables may be set (to 1 or "YES") to assist with development:
+**LIBOCXL_INFO** Print information about the LibOCXL build to stderr. This should be included in any bug reports.
+**LIBOCXL_TRACE_ALL** Force AFU interaction trace messages to be emitted for all AFUs unless explicitly disabled.
+**LIBOCXL_VERBOSE_ERRORS_ALL** Force verbose errors to be emitted for any failed LibOCXL calls, unless explicitly disabled.
+
 Patches may be submitted via Github pull requests. Please prepare your patches
 by running `make precommit` before committing your work, and addressing any warnings & errors reported.
 Patches must compile cleanly with the latest stable version of GCC to be accepted.

src/afu.c

@@ -254,10 +254,10 @@ static void afu_init(ocxl_afu *afu)
 
 	afu->pasid = UINT32_MAX;
 
-	afu->verbose_errors = false;
+	afu->verbose_errors = verbose_errors_all;
 	afu->error_handler = ocxl_default_afu_error_handler;
 
-	afu->tracing = false;
+	afu->tracing = tracing_all;
 
 	afu->attached = false;
 
@@ -540,6 +540,8 @@ static ocxl_err get_afu_by_path(const char *path, ocxl_afu_h *afu)
  */
 ocxl_err ocxl_afu_open_from_dev(const char *path, ocxl_afu_h *afu)
 {
+	libocxl_init();
+
 	ocxl_err rc = get_afu_by_path(path, afu);
 
 	if (rc != OCXL_OK) {
@@ -577,6 +579,8 @@ ocxl_err ocxl_afu_open_specific(const char *name, const char *physical_function,
 	ocxl_err ret = OCXL_INTERNAL_ERROR;
 	*afu = OCXL_INVALID_AFU;
 
+	libocxl_init();
+
 	if (afu_index == -1) {
 		snprintf(pattern, sizeof(pattern), "%s/%s.%s.*",
 		         DEVICE_PATH, name,

src/include/libocxl.h

@@ -152,6 +152,7 @@ typedef struct ocxl_event {
 void ocxl_enable_messages(uint64_t sources);
 void ocxl_set_error_message_handler(void (*handler)(ocxl_err error, const char *message));
 const char *ocxl_err_to_string(ocxl_err err);
+const char *ocxl_info();
 
 /* afu.c */
 /* AFU getters */

src/internal.c

@@ -15,6 +15,7 @@
  */
 
 #include "libocxl_internal.h"
+#include "libocxl_info.h"
 #include <stdio.h>
 #include <stdbool.h>
 #include <stdarg.h>
@@ -25,6 +26,7 @@
 #include <fcntl.h>
 #include <errno.h>
 #include <string.h>
+#include <strings.h>
 #include <stdlib.h>
 
 /// The base sysfs path for OCXL devices
@@ -33,14 +35,58 @@ const char *sys_path = NULL;
 /// The base device path for OCXL devices
 const char *dev_path = NULL;
 
+bool libocxl_inited = false;
+pthread_mutex_t libocxl_inited_mutex = PTHREAD_MUTEX_INITIALIZER;
+
 bool verbose_errors = false;
+bool verbose_errors_all = false;
 bool tracing = false;
+bool tracing_all = false;
 
 void ocxl_default_error_handler(ocxl_err error, const char *message);
 void (*error_handler)(ocxl_err error, const char *message) = ocxl_default_error_handler;
 
 pthread_mutex_t stderr_mutex = PTHREAD_MUTEX_INITIALIZER;
 
+/**
+ * Executed on first afu_open
+ *  - Check the LIBOCXL_INFO environment variable and output the info string
+ *  - Check the LIBOCXL_TRACE_ALL environment variable and enable tracing_all
+ *  - Check the LIBOCXL_VERBOSE_ERRORS_ALL environment variable and enable verbose_errors_all
+ */
+void libocxl_init()
+{
+	const char *val;
+
+	pthread_mutex_lock(&libocxl_inited_mutex);
+	if (libocxl_inited) {
+		pthread_mutex_unlock(&libocxl_inited_mutex);
+		return;
+	}
+
+	val = getenv("LIBOCXL_INFO");
+	if (val && (!strcasecmp(val, "yes") || !strcmp(val, "1"))) {
+		fprintf(stderr, "%s", libocxl_info);
+	}
+
+	val = getenv("LIBOCXL_TRACE_ALL");
+	if (val && (!strcasecmp(val, "yes") || !strcmp(val, "1"))) {
+		tracing_all = true;
+		tracing = true;
+	}
+
+	val = getenv("LIBOCXL_VERBOSE_ERRORS_ALL");
+	if (val && (!strcasecmp(val, "yes") || !strcmp(val, "1"))) {
+		verbose_errors_all = true;
+		verbose_errors = true;
+	}
+
+	libocxl_inited = true;
+
+	pthread_mutex_unlock(&libocxl_inited_mutex);
+}
+
+
 /**
  * Output a trace message
  * @param file the source filename

src/libocxl_internal.h

@@ -61,8 +61,11 @@ do {\
 } while (0)
 
 extern bool verbose_errors;
+extern bool verbose_errors_all;
 extern bool tracing;
+extern bool tracing_all;
 extern void (*error_handler)(ocxl_err error, const char *message);
+extern const char *libocxl_info;
 
 typedef struct ocxl_afu ocxl_afu;
 
@@ -186,5 +189,6 @@ struct ocxl_afu {
 };
 
 void irq_dealloc(ocxl_afu *afu, ocxl_irq *irq);
+void libocxl_init();
 
 #endif				/* _LIBOCXL_INTERNAL_H */

src/setup.c

@@ -143,6 +143,19 @@ const char *ocxl_err_to_string(ocxl_err err)
 	}
 }
 
+/**
+ * Get version & compilation information about LibOCXL. This must be included with
+ * any bug report.
+ *
+ * The format and ordering of lines in this string may change.
+ *
+ * @return containing the version information
+ */
+const char *ocxl_info()
+{
+	return libocxl_info;
+}
+
 /**
  * @}
  */

symver.map

@@ -7,6 +7,7 @@ LIBOCXL_0 {
 		ocxl_enable_messages;
 		ocxl_set_error_message_handler;
 		ocxl_err_to_string;
+		ocxl_info;
 		ocxl_afu_get_identifier;
 		ocxl_afu_get_device_path;
 		ocxl_afu_get_sysfs_path;