Event Machine (EM) on ODP v3.7.0

See changes in CHANGE_NOTES, README and include/event_machine/README_API

CHANGE_NOTES

@@ -52,6 +52,32 @@ Examples:
 - See em-odp/README for usage and compilation instructions.
 - See em-odp/include/event_machine/README_API for API changes
 
+--------------------------------------------------------------------------------
+Event Machine (EM) on ODP v3.7.0
+--------------------------------------------------------------------------------
+- Support for EM API v3.7 (em-odp/include/),
+  see API additions and changes in em-odp/include/event_machine/README_API.
+  Summary:
+  * Timer: em_timer_get_all() update
+  * Helper APIs: em_version_print(), em_info_print()
+
+- Startup printouts changed
+  The EM startup printouts / logging has been changed to reduce startup clutter
+  and give more control to the user about what is being printed and when.
+  EM will print the version information at startup (wuth the same content as
+  produced by the new helper API em_version_print()) but further printouts with
+  info about the running instance has been moved into another new helper API
+  em_info_print(), which the user can now call on demand
+  (as is done by the EM example applications, see programs/common/cm_setup.c).
+
+- configure, build: disable strict-aliasing (use -fno-strict-aliasing)
+
+  Don't allow the compiler to assume the strictest aliasing rules.
+  Unless turned off, the -fstrict-aliasing option is enabled at
+  optimization levels -O2, -O3, -Os.
+
+  EM contains some type casting that might violate C strict aliasing rules.
+
 --------------------------------------------------------------------------------
 Event Machine (EM) on ODP v3.6.0
 --------------------------------------------------------------------------------

configure.ac

@@ -3,7 +3,7 @@ AC_PREREQ([2.69])
 # Version
 ############################
 m4_define([em_version_api_major], [3])
-m4_define([em_version_api_minor], [6])
+m4_define([em_version_api_minor], [7])
 m4_define([em_version_implementation], [0])
 m4_define([em_version_fix], [0])
 
@@ -82,7 +82,6 @@ AM_SILENT_RULES([yes])
 AC_PROG_CXX
 AC_PROG_CC
 AC_PROG_CPP
-AM_PROG_CC_C_O
 AM_PROG_AR
 
 # Use libtool
@@ -144,7 +143,7 @@ AC_ARG_WITH([config-file],
 	    [default_config_file="${withval/#\~/$HOME}"], dnl replace ~ with $HOME
 	    [])
 
-rel_default_config_file=`realpath --relative-to=$(pwd) ${default_config_file}`
+rel_default_config_file=$(realpath --relative-to=$(pwd) ${default_config_file})
 AC_SUBST([default_config_file])
 AC_SUBST([rel_default_config_file])
 
@@ -154,6 +153,7 @@ EM_LIBCONFIG([$rel_default_config_file])
 # Default warning setup
 ##########################################################################
 EM_CFLAGS="$EM_CFLAGS -W -Wall -Werror"
+EM_CXXFLAGS="$EM_CXXFLAGS -W -Wall -Werror"
 
 # Additional warnings:
 EM_CHECK_CFLAG([-Wstrict-prototypes])
@@ -174,7 +174,7 @@ EM_CHECK_CFLAG([-Wshadow=local])
 # GCC 10,11 sometimes gets confused about object sizes and gives bogus warnings.
 # Make the affected warnings generate only warnings, not errors.
 AS_IF([test "$GCC" == yes],
-      AS_IF([test `$CC -dumpversion | cut -d '.' -f 1` -ge 10],
+      AS_IF([test $($CC -dumpversion | cut -d '.' -f 1) -ge 10],
 	    EM_CHECK_CFLAG([-Wno-error=array-bounds])
 	    EM_CHECK_CFLAG([-Wno-error=stringop-overflow])
 	    EM_CHECK_CXXFLAG([-Wno-error=stringop-overflow])
@@ -184,7 +184,21 @@ AS_IF([test "$GCC" == yes],
       )
 )
 
+##########################################################################
+# Compiler optimization flags
+##########################################################################
+
+# Don't allow the compiler to assume the strictest aliasing rules.
+# Unless turned off, the -fstrict-aliasing option is enabled at
+# optimization levels -O2, -O3, -Os.
+EM_CHECK_CFLAG([-fno-strict-aliasing])
+EM_CHECK_CXXFLAG([-fno-strict-aliasing])
+
+##########################################################################
+# Set default C and C++ standard version to be used
+##########################################################################
 EM_CFLAGS="$EM_CFLAGS -std=c11"
+EM_CXXFLAGS="$EM_CXXFLAGS -std=c++11"
 
 # Extra flags for example to suppress certain warning types
 EM_CFLAGS="$EM_CFLAGS $EM_CFLAGS_EXTRA"
@@ -463,7 +477,7 @@ AC_SUBST([EM_SCHED_WAIT_ENABLE])
 # Default include setup
 ##########################################################################
 AM_CFLAGS="$AM_CFLAGS $EM_CFLAGS"
-AM_CXXFLAGS="-std=c++11"
+AM_CXXFLAGS="$AM_CXXFLAGS $EM_CXXFLAGS"
 AM_CPPFLAGS="$AM_CPPFLAGS $EM_CPPFLAGS"
 
 AC_CONFIG_FILES([

include/event_machine/README_API

@@ -5,6 +5,56 @@ EM API Release Notes
 - See em-odp/CHANGE_NOTES for changed and added features other than API changes.
 - See em-odp/README for usage and compilation instructions.
 
+--------------------------------------------------------------------------------
+API 3.7 (EM_VERSION_API_MAJOR=3, EM_VERSION_API_MINOR=7)
+--------------------------------------------------------------------------------
+1. Timer, fix: em_timer_get_all() always returns the actual number of timers.
+   (see include/event_machine/api/event_machine_timer.h)
+
+   The API em_timer_get_all(*tmr_list, max) should, according to the API spec,
+   always return the actual number of timers regardless of the value of 'max'.
+   The prev implementation returned a value from 0 to 'max' even if there was
+   more timers - this is now fixed and the API documentation has been updated.
+
+  num_timers = em_timer_get_all(NULL, 0);
+  would now always return the number of timers.
+
+  When you also need a list of the timer handles:
+  num_timers = em_timer_get_all(tmr_list, max);
+  if (num_timers > max) {
+	/* more timers exist than could be filled into 'tmr_list' */
+  }
+
+2. Helper: Print EM information
+   (see include/event_machine/helper/event_machine_helper.h)
+
+   Two new helper APIs were added to enable printing EM version information
+   as well as various information about the running EM instance.
+
+   Helper APIs:
+   void em_version_print(void) - Print EM related version information
+   void em_info_print(void)    - Print miscellaneous EM information
+
+   Both em_init() and em_version_print() will output version information:
+     ===========================================================
+     EM version information: em-odp
+     ===========================================================
+     EM API version:         3.7
+     EM version:             3.7.0, 64 bit (EM_CHECK_LEVEL:3, EM_ESV_ENABLE:1)
+     EM build info:          v3.7.0-18-g7ea320af 2024-08-21 14:36
+     ODP API version:        1.45.0
+     ODP impl name:          odp-linux
+     ODP impl details:       odp-linux 1.45.0-0 (v1.45.0) 1.45.0.0
+     CPU model:              Intel(R) Xeon(R) Gold 6212U CPU
+     CPU arch:               x86
+     CPU ISA version:        Unknown
+      SW ISA version (ODP):  x86_64
+      SW ISA version (EM):   x86_64
+
+   The helper API em_info_print() prints various data about the running
+   EM instance that previously were part of the em_init() printouts (removed
+   from em_init() to reduce startup clutter, printed now only on demand).
+
 --------------------------------------------------------------------------------
 API 3.6 (EM_VERSION_API_MAJOR=3, EM_VERSION_API_MINOR=6)
 --------------------------------------------------------------------------------

include/event_machine/api/event_machine_timer.h

@@ -928,16 +928,26 @@ em_status_t em_tmo_ack(em_tmo_t tmo, em_event_t next_tmo_ev);
 /**
  * Get a list of currently active timers.
  *
- * Returned timer handles can be used to query more information or to
- * destroy all existing timers.
+ * The timer handles returned via 'tmr_list' can be used for further timer
+ * queries or to destroy existing timers.
  *
- * The actual number of timers is always returned but 'tmr_list' will only be
- * written up to the given 'max' length.
+ * The return value always reflects the actual number of timers in the
+ * EM instance but the output parameter 'tmr_list' is only written up to the
+ * given 'max' length.
  *
- * @param [out] tmr_list  Pointer to array of timer handles
- * @param max             Max number of handles that can written into tmr_list
+ * Note that the return value (number of timers) can be greater than the given
+ * 'max'. It is the user's responsibility to check the return value against the
+ * given 'max'.
  *
- * @return number of active timers
+ * To only get the current number of active timers, without any timer handles
+ * output, use the following: num_timers = em_timer_get_all(NULL, 0);
+ *
+ * @param[out] tmr_list  Pointer to an array of timer handles.
+ *                       Use NULL if only interested in the return value.
+ * @param      max       Max number of handles that can be written into tmr_list
+ *                       'max' is ignored if 'tmr_list' is NULL.
+ *
+ * @return The number of active timers
  */
 int em_timer_get_all(em_timer_t *tmr_list, int max);
 

include/event_machine/helper/event_machine_helper.h

@@ -50,20 +50,43 @@ extern "C" {
 /**
  * Format error string
  *
- * Creates an implementation dependent error report string from EM
- * internal errors.
+ * Creates an error report string from EM internal errors.
+ * Main use case: application error handlers to create an error report from
+ * EM internal errors.
  *
  * @param[out] str     Output string pointer
  * @param      size    Maximum string length in characters
- * @param      eo      EO id
+ * @param      eo      EO handle
  * @param      error   Error code (EM internal)
  * @param      escope  Error scope (EM internal)
- * @param      args    Variable arguments
+ * @param      args    Variable arguments as passed to the error handler
  *
  * @return Output string length.
  */
 int em_error_format_string(char *str /*out*/, size_t size, em_eo_t eo,
 			   em_status_t error, em_escope_t escope, va_list args);
+/**
+ * @brief Print EM related version information
+ *
+ * Prints the EM version information, as well as version information for the
+ * used ODP and HW etc. (similar to what EM prints at startup).
+ *
+ * For EM API version strings, defines and macros see
+ * include/event_machine/api/event_machine_version.h
+ *
+ * The printed content may vary from one EM release to the next.
+ */
+void em_version_print(void);
+
+/**
+ * @brief Print miscellaneous EM information
+ *
+ * Print information about the running EM instance.
+ * Mainly for debug or startup logging needs.
+ *
+ * The printed content may vary from one EM release to the next.
+ */
+void em_info_print(void);
 
 /*
  * Physical core ids

m4/em_libconfig.m4

@@ -31,7 +31,7 @@ AS_IF([test -z "$1"] || [test ! -f $1],
       [AC_MSG_ERROR([Default configuration file not found: $1])], [])
 
 conf_ver=_em_config_version
-file_ver=`$SED 's/ //g' $1 | $GREP -oP '(?<=config_file_version=").*?(?=")'`
+file_ver=$($SED 's/ //g' $1 | $GREP -oP '(?<=config_file_version=").*?(?=")')
 
 AS_IF([test "x$conf_ver" = "x$file_ver"], [],
       [AC_MSG_ERROR([Configuration file version mismatch:

programs/common/cm_setup.c

@@ -856,6 +856,13 @@ static void startup_all_cores(sync_t *sync, const appl_conf_t *appl_conf,
 
 	odp_barrier_wait(&sync->start_barrier);
 
+	int core_id = em_core_id();
+
+	if (core_id == 0)
+		em_info_print();
+
+	odp_barrier_wait(&sync->start_barrier);
+
 	if (appl_conf->pktio.if_count > 0)
 		pktio_mem_lookup(is_thread_per_core);
 
@@ -871,7 +878,6 @@ static void startup_all_cores(sync_t *sync, const appl_conf_t *appl_conf,
 	 * where they are ready to process events as soon as the EOs have been
 	 * started and queues enabled.
 	 */
-	int core_id = em_core_id();
 	uint64_t cores = appl_conf->core_count;
 
 	/* Ensure all EM cores can find the default event pool */
@@ -1053,6 +1059,9 @@ static void startup_one_core_first(sync_t *sync, const appl_conf_t *appl_conf,
 		if (core_id == 0)
 			env_atomic64_inc(&sync->enter_count);
 	} while (env_atomic64_get(&sync->enter_count) <= 2 * cores);
+
+	if (core_id == 0)
+		em_info_print();
 }
 
 /*

programs/performance/.gitignore

@@ -1,5 +1,8 @@
 atomic_processing_end
 loop
+loop_multircv
+loop_refs
+loop_vectors
 pairs
 queue_groups
 queues
@@ -8,6 +11,5 @@ queues_output
 queues_unscheduled
 send_multi
 timer_test
-timer_test_ring
 timer_test_periodic
-loop_multircv
+timer_test_ring

programs/performance/Makefile.am

@@ -5,6 +5,7 @@ noinst_PROGRAMS = atomic_processing_end \
 		  loop \
 		  loop_multircv \
 		  loop_refs \
+		  loop_vectors \
 		  queue_groups \
 		  queues \
 		  queues_unscheduled \
@@ -32,6 +33,9 @@ loop_multircv_CFLAGS = $(AM_CFLAGS)
 loop_refs_LDFLAGS = $(AM_LDFLAGS)
 loop_refs_CFLAGS = $(AM_CFLAGS)
 
+loop_vectors_LDFLAGS = $(AM_LDFLAGS)
+loop_vectors_CFLAGS = $(AM_CFLAGS)
+
 queue_groups_LDFLAGS = $(AM_LDFLAGS)
 queue_groups_CFLAGS = $(AM_CFLAGS)
 
@@ -70,6 +74,7 @@ dist_pairs_SOURCES = pairs.c
 dist_loop_SOURCES = loop.c
 dist_loop_multircv_SOURCES = loop_multircv.c
 dist_loop_refs_SOURCES = loop_refs.c
+dist_loop_vectors_SOURCES = loop_vectors.c
 dist_queue_groups_SOURCES = queue_groups.c
 dist_queues_SOURCES = queues.c
 dist_queues_unscheduled_SOURCES = queues_unscheduled.c