[dpdk-dev] [PATCH v6 03/33] eal/trace: define the public API for trace support

[<jerinj@marvell.com>]

From: Jerin Jacob <jerinj@marvell.com>

Define the public API for trace support.
This patch also adds support for the build infrastructure and
update the MAINTAINERS file for the trace subsystem.

The tracepoint object is of size 8B, it a global variable and used in
fastpath. Created a new __rte_trace_point section to store the
tracepoint objects as,
- It is a mostly read-only data and not to mix with other "write"
global variables.
- Chances that the same subsystem Fast path variables come in the same
fast path cache line. i.e, it will enable a more predictable
performance number from build to build.

Signed-off-by: Jerin Jacob <jerinj@marvell.com>
Signed-off-by: Sunil Kumar Kori <skori@marvell.com>
---
 MAINTAINERS                               |   6 +
 config/common_base                        |   1 +
 config/meson.build                        |   1 +
 doc/api/doxy-api-index.md                 |   4 +-
 doc/guides/prog_guide/build-sdk-meson.rst |   5 +
 lib/librte_eal/common/eal_common_trace.c  |   7 +
 lib/librte_eal/common/meson.build         |   1 +
 lib/librte_eal/freebsd/Makefile           |   1 +
 lib/librte_eal/include/meson.build        |   2 +
 lib/librte_eal/include/rte_trace.h        | 141 +++++++++++++
 lib/librte_eal/include/rte_trace_point.h  | 234 ++++++++++++++++++++++
 lib/librte_eal/linux/Makefile             |   1 +
 meson_options.txt                         |   2 +
 13 files changed, 405 insertions(+), 1 deletion(-)
 create mode 100644 lib/librte_eal/common/eal_common_trace.c
 create mode 100644 lib/librte_eal/include/rte_trace.h
 create mode 100644 lib/librte_eal/include/rte_trace_point.h

diff --git a/MAINTAINERS b/MAINTAINERS
index 1bf00d7e5..bd76ec23f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -194,6 +194,12 @@ F: app/test/test_string_fns.c
 F: app/test/test_tailq.c
 F: app/test/test_version.c
 
+Trace - EXPERIMENTAL
+M: Jerin Jacob <jerinj@marvell.com>
+M: Sunil Kumar Kori <skori@marvell.com>
+F: lib/librte_eal/include/rte_trace*.h
+F: lib/librte_eal/common/eal_common_trace*.c
+
 Memory Allocation
 M: Anatoly Burakov <anatoly.burakov@intel.com>
 F: lib/librte_eal/include/rte_fbarray.h
diff --git a/config/common_base b/config/common_base
index c31175f9d..ac5257b8e 100644
--- a/config/common_base
+++ b/config/common_base
@@ -99,6 +99,7 @@ CONFIG_RTE_MAX_MEMZONE=2560
 CONFIG_RTE_MAX_TAILQ=32
 CONFIG_RTE_ENABLE_ASSERT=n
 CONFIG_RTE_LOG_DP_LEVEL=RTE_LOG_INFO
+CONFIG_RTE_ENABLE_TRACE_FP=n
 CONFIG_RTE_LOG_HISTORY=256
 CONFIG_RTE_BACKTRACE=y
 CONFIG_RTE_LIBEAL_USE_HPET=n
diff --git a/config/meson.build b/config/meson.build
index 8a4c692a9..f416be23e 100644
--- a/config/meson.build
+++ b/config/meson.build
@@ -230,6 +230,7 @@ dpdk_conf.set('RTE_MAX_LCORE', get_option('max_lcores'))
 dpdk_conf.set('RTE_MAX_NUMA_NODES', get_option('max_numa_nodes'))
 dpdk_conf.set('RTE_MAX_ETHPORTS', get_option('max_ethports'))
 dpdk_conf.set('RTE_LIBEAL_USE_HPET', get_option('use_hpet'))
+dpdk_conf.set('RTE_ENABLE_TRACE_FP', get_option('enable_trace_fp'))
 # values which have defaults which may be overridden
 dpdk_conf.set('RTE_MAX_VFIO_GROUPS', 64)
 dpdk_conf.set('RTE_DRIVER_MEMPOOL_BUCKET_SIZE_KB', 64)
diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md
index dff496be0..845a53491 100644
--- a/doc/api/doxy-api-index.md
+++ b/doc/api/doxy-api-index.md
@@ -174,7 +174,9 @@ The public API headers are grouped by topics:
   [hexdump]            (@ref rte_hexdump.h),
   [debug]              (@ref rte_debug.h),
   [log]                (@ref rte_log.h),
-  [errno]              (@ref rte_errno.h)
+  [errno]              (@ref rte_errno.h),
+  [trace]              (@ref rte_trace.h),
+  [trace_point]        (@ref rte_trace_point.h)
 
 - **misc**:
   [EAL config]         (@ref rte_eal.h),
diff --git a/doc/guides/prog_guide/build-sdk-meson.rst b/doc/guides/prog_guide/build-sdk-meson.rst
index e34daab91..a036299da 100644
--- a/doc/guides/prog_guide/build-sdk-meson.rst
+++ b/doc/guides/prog_guide/build-sdk-meson.rst
@@ -87,6 +87,9 @@ Project-specific options are passed used -Doption=value::
 	meson -Ddisable_drivers=event/*,net/tap  # disable tap driver and all
 					# eventdev PMDs for a smaller build
 
+	meson -Denable_trace_fp=true tracebuild # build with fastpath trace
+					#enabled
+
 Examples of setting some of the same options using meson configure::
 
 	meson configure -Dwerror=true
@@ -97,6 +100,8 @@ Examples of setting some of the same options using meson configure::
 
 	meson configure -Dmax_lcores=8
 
+	meson configure -Denable_trace_fp=true
+
 NOTE: once meson has been run to configure a build in a directory, it
 cannot be run again on the same directory. Instead ``meson configure``
 should be used to change the build settings within the directory, and when
diff --git a/lib/librte_eal/common/eal_common_trace.c b/lib/librte_eal/common/eal_common_trace.c
new file mode 100644
index 000000000..33a6e563a
--- /dev/null
+++ b/lib/librte_eal/common/eal_common_trace.c
@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(C) 2020 Marvell International Ltd.
+ */
+
+#include <rte_trace.h>
+#include <rte_trace_point.h>
+
diff --git a/lib/librte_eal/common/meson.build b/lib/librte_eal/common/meson.build
index 02d9280cc..429e89f99 100644
--- a/lib/librte_eal/common/meson.build
+++ b/lib/librte_eal/common/meson.build
@@ -42,6 +42,7 @@ sources += files(
 	'eal_common_tailqs.c',
 	'eal_common_thread.c',
 	'eal_common_timer.c',
+	'eal_common_trace.c',
 	'eal_common_uuid.c',
 	'hotplug_mp.c',
 	'malloc_elem.c',
diff --git a/lib/librte_eal/freebsd/Makefile b/lib/librte_eal/freebsd/Makefile
index 2d53ce9ee..500afc578 100644
--- a/lib/librte_eal/freebsd/Makefile
+++ b/lib/librte_eal/freebsd/Makefile
@@ -59,6 +59,7 @@ SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += eal_common_thread.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += eal_common_proc.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += eal_common_fbarray.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += eal_common_uuid.c
+SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += eal_common_trace.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += rte_malloc.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += hotplug_mp.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_FREEBSD) += malloc_elem.c
diff --git a/lib/librte_eal/include/meson.build b/lib/librte_eal/include/meson.build
index 6fd427494..126455d1c 100644
--- a/lib/librte_eal/include/meson.build
+++ b/lib/librte_eal/include/meson.build
@@ -40,6 +40,8 @@ headers += files(
 	'rte_string_fns.h',
 	'rte_tailq.h',
 	'rte_time.h',
+	'rte_trace.h',
+	'rte_trace_point.h',
 	'rte_uuid.h',
 	'rte_version.h',
 	'rte_vfio.h',
diff --git a/lib/librte_eal/include/rte_trace.h b/lib/librte_eal/include/rte_trace.h
new file mode 100644
index 000000000..a7ff4590b
--- /dev/null
+++ b/lib/librte_eal/include/rte_trace.h
@@ -0,0 +1,141 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(C) 2020 Marvell International Ltd.
+ */
+
+#ifndef _RTE_TRACE_H_
+#define _RTE_TRACE_H_
+
+/**
+ * @file
+ *
+ * RTE Trace API
+ *
+ * This file provides the trace API to RTE applications.
+ *
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdbool.h>
+#include <stdio.h>
+
+#include <rte_common.h>
+#include <rte_compat.h>
+
+/**
+ * Enumerate trace mode operation.
+ */
+enum rte_trace_mode {
+	/**
+	 * In this mode, When no space left in trace buffer, the subsequent
+	 * events overwrite the old events in the trace buffer.
+	 */
+	RTE_TRACE_MODE_OVERWRITE,
+	/**
+	 * In this mode, When no space left on trace buffer, the subsequent
+	 * events shall not be recorded in the trace buffer.
+	 */
+	RTE_TRACE_MODE_DISCARD,
+};
+
+/**
+ *  Test if trace is enabled.
+ *
+ *  @return
+ *     true if trace is enabled, false otherwise.
+ */
+__rte_experimental
+bool rte_trace_is_enabled(void);
+
+/**
+ * Set the trace mode.
+ *
+ * @param mode
+ *   Trace mode.
+ */
+__rte_experimental
+void rte_trace_mode_set(enum rte_trace_mode mode);
+
+/**
+ * Get the trace mode.
+ *
+ * @return
+ *   The current trace mode.
+ */
+__rte_experimental
+enum rte_trace_mode rte_trace_mode_get(void);
+
+/**
+ * Enable/Disable a set of tracepoints based on globbing pattern.
+ *
+ * @param pattern
+ *   The match pattern identifying the tracepoint.
+ * @param enable
+ *    true to enable tracepoint, false to disable the tracepoint, upon match.
+ * @return
+ *   - 0: Success and no pattern match.
+ *   - 1: Success and found pattern match.
+ *   - (-ERANGE): Tracepoint object is not registered.
+ */
+__rte_experimental
+int rte_trace_pattern(const char *pattern, bool enable);
+
+/**
+ * Enable/Disable a set of tracepoints based on regular expression.
+ *
+ * @param regex
+ *   A regular expression identifying the tracepoint.
+ * @param enable
+ *    true to enable tracepoint, false to disable the tracepoint, upon match.
+ * @return
+ *   - 0: Success and no pattern match.
+ *   - 1: Success and found pattern match.
+ *   - (-ERANGE): Tracepoint object is not registered.
+ *   - (-EINVAL): Invalid regular expression rule.
+ */
+__rte_experimental
+int rte_trace_regexp(const char *regex, bool enable);
+
+/**
+ * Save the trace buffer to the trace directory.
+ *
+ * By default, trace directory will be created at $HOME directory and this can
+ * be overridden by --trace-dir EAL parameter.
+ *
+ * @return
+ *   - 0: Success.
+ *   - <0 : Failure.
+ */
+__rte_experimental
+int rte_trace_save(void);
+
+/**
+ * Dump the trace metadata to a file.
+ *
+ * @param f
+ *   A pointer to a file for output
+ * @return
+ *   - 0: Success.
+ *   - <0 : Failure.
+ */
+__rte_experimental
+int rte_trace_metadata_dump(FILE *f);
+
+/**
+ * Dump the trace subsystem status to a file.
+ *
+ * @param f
+ *   A pointer to a file for output
+ */
+__rte_experimental
+void rte_trace_dump(FILE *f);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _RTE_TRACE_H_ */
diff --git a/lib/librte_eal/include/rte_trace_point.h b/lib/librte_eal/include/rte_trace_point.h
new file mode 100644
index 000000000..9d11830f6
--- /dev/null
+++ b/lib/librte_eal/include/rte_trace_point.h
@@ -0,0 +1,234 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(C) 2020 Marvell International Ltd.
+ */
+
+#ifndef _RTE_TRACE_POINT_H_
+#define _RTE_TRACE_POINT_H_
+
+/**
+ * @file
+ *
+ * RTE Tracepoint API
+ *
+ * This file provides the tracepoint API to RTE applications.
+ *
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdbool.h>
+#include <stdio.h>
+
+#include <rte_common.h>
+#include <rte_compat.h>
+
+/** The tracepoint object. */
+typedef uint64_t rte_trace_point_t;
+
+/** Macro to define the tracepoint. */
+#define RTE_TRACE_POINT_DEFINE(tp)\
+rte_trace_point_t __attribute__((section("__rte_trace_point"))) __##tp
+
+/**
+ * Macro to define the tracepoint arguments in RTE_TRACE_POINT macro.
+
+ * @see RTE_TRACE_POINT, RTE_TRACE_POINT_FP
+ */
+#define RTE_TRACE_POINT_ARGS
+
+/** @internal Helper Macro to support RTE_TRACE_POINT and RTE_TRACE_POINT_FP */
+#define __RTE_TRACE_POINT(_mode, _tp, _args, ...)\
+extern rte_trace_point_t __##_tp;\
+static __rte_always_inline void \
+_tp _args \
+{\
+	__rte_trace_point_emit_header_##_mode(&__##_tp);\
+	__VA_ARGS__\
+}
+
+/**
+ * Create a tracepoint definition.
+ *
+ * A tracepoint definition defines, for a given tracepoint:
+ * - Its input arguments. They are the C function style parameters to define
+ * the arguments of tracepoint function. These input arguments embedded using
+ * RTE_TRACE_POINT_ARGS macro.
+ * - Its output event fields. They are the sources of event fields that form
+ * the payload of any event that the execution of the tracepoint macro emits
+ * for this particular tracepoint. The application uses rte_trace_point_emit_*
+ * macros to emit the output event fields.
+ *
+ * @param tp
+ *   Tracepoint object. Before using the tracepoint, an application needs to
+ * define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
+ * @param args
+ *   C function style input arguments to define the arguments to tracepoint
+ * function.
+ * @param ...
+ *   Define the payload of trace function. The payload will be formed using
+ * rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
+ *
+ * @see RTE_TRACE_POINT_ARGS, RTE_TRACE_POINT_DEFINE, rte_trace_point_emit_*
+ */
+#define RTE_TRACE_POINT(tp, args, ...)\
+	__RTE_TRACE_POINT(generic, tp, args, __VA_ARGS__)
+
+/**
+ * Create a tracepoint definition for the data path.
+ *
+ * Similar to RTE_TRACE_POINT, except that it is removed at compilation time
+ * using RTE_ENABLE_TRACE_FP configuration parameter.
+ *
+ * @param tp
+ *   Tracepoint object. Before using the tracepoint, an application needs to
+ * define the tracepoint using RTE_TRACE_POINT_DEFINE macro.
+ * @param args
+ *   C function style input arguments to define the arguments to tracepoint.
+ * function.
+ * @param ...
+ *   Define the payload of trace function. The payload will be formed using
+ * rte_trace_point_emit_* macros, Use ";" delimiter between two payloads.
+ *
+ * @see RTE_TRACE_POINT
+ */
+#define RTE_TRACE_POINT_FP(tp, args, ...)\
+	__RTE_TRACE_POINT(fp, tp, args, __VA_ARGS__)
+
+#ifdef __DOXYGEN__
+
+/**
+ * Macro to select rte_trace_point_emit_* definition for trace register function
+ *
+ * rte_trace_point_emit_* emits different definitions for trace function.
+ * Application must define RTE_TRACE_POINT_REGISTER_SELECT before including
+ * rte_trace_point.h in the C file where RTE_TRACE_POINT_REGISTER used.
+ *
+ * @see RTE_TRACE_POINT_REGISTER
+ */
+#define RTE_TRACE_POINT_REGISTER_SELECT
+
+/**
+ * Register a dynamic tracepoint.
+ *
+ * @param trace
+ *   The tracepoint object created using RTE_TRACE_POINT_DEFINE.
+ * @param name
+ *   The name of the tracepoint object.
+ * @return
+ *   - 0: Successfully registered the tracepoint.
+ *   - <0: Failure to register the tracepoint.
+ *
+ * @see RTE_TRACE_POINT_REGISTER_SELECT
+ */
+#define RTE_TRACE_POINT_REGISTER(trace, name)
+
+/** Tracepoint function payload for uint64_t datatype */
+#define rte_trace_point_emit_u64(val)
+/** Tracepoint function payload for int64_t datatype */
+#define rte_trace_point_emit_i64(val)
+/** Tracepoint function payload for uint32_t datatype */
+#define rte_trace_point_emit_u32(val)
+/** Tracepoint function payload for int32_t datatype */
+#define rte_trace_point_emit_i32(val)
+/** Tracepoint function payload for uint16_t datatype */
+#define rte_trace_point_emit_u16(val)
+/** Tracepoint function payload for int16_t datatype */
+#define rte_trace_point_emit_i16(val)
+/** Tracepoint function payload for uint8_t datatype */
+#define rte_trace_point_emit_u8(val)
+/** Tracepoint function payload for int8_t datatype */
+#define rte_trace_point_emit_i8(val)
+/** Tracepoint function payload for int datatype */
+#define rte_trace_point_emit_int(val)
+/** Tracepoint function payload for long datatype */
+#define rte_trace_point_emit_long(val)
+/** Tracepoint function payload for float datatype */
+#define rte_trace_point_emit_float(val)
+/** Tracepoint function payload for double datatype */
+#define rte_trace_point_emit_double(val)
+/** Tracepoint function payload for pointer datatype */
+#define rte_trace_point_emit_ptr(val)
+/** Tracepoint function payload for string datatype */
+#define rte_trace_point_emit_string(val)
+
+#endif /* __DOXYGEN__ */
+
+/** @internal Macro to define maximum emit length of string datatype. */
+#define __RTE_TRACE_EMIT_STRING_LEN_MAX 32
+/** @internal Macro to define event header size. */
+#define __RTE_TRACE_EVENT_HEADER_SZ sizeof(uint64_t)
+
+/**
+ * Enable recording of the given tracepoint in the trace buffer.
+ *
+ * @param tp
+ *   The tracepoint object to enable.
+ * @return
+ *   - 0: Success.
+ *   - (-ERANGE): Trace object is not registered.
+ */
+__rte_experimental
+int rte_trace_point_enable(rte_trace_point_t *tp);
+
+/**
+ * Disable recording of the given tracepoint in the trace buffer.
+ *
+ * @param tp
+ *   The tracepoint object to disable.
+ * @return
+ *   - 0: Success.
+ *   - (-ERANGE): Trace object is not registered.
+ */
+__rte_experimental
+int rte_trace_point_disable(rte_trace_point_t *tp);
+
+/**
+ * Test if given tracepoint is enabled.
+ *
+ * @param tp
+ *    The tracepoint object.
+ * @return
+ *    true if tracepoint is enabled, false otherwise.
+ */
+__rte_experimental
+bool rte_trace_point_is_enabled(rte_trace_point_t *tp);
+
+/**
+ * Lookup a tracepoint object from its name.
+ *
+ * @param name
+ *   The name of the tracepoint.
+ * @return
+ *   The tracepoint object or NULL if not found.
+ */
+__rte_experimental
+rte_trace_point_t *rte_trace_point_lookup(const char *name);
+
+/**
+ * @internal
+ *
+ * Test if the tracepoint fastpath compile-time option is enabled.
+ *
+ * @return
+ *   true if tracepoint fastpath enabled, false otherwise.
+ */
+__rte_experimental
+static __rte_always_inline bool
+__rte_trace_point_fp_is_enabled(void)
+{
+#ifdef RTE_ENABLE_TRACE_FP
+	return true;
+#else
+	return false;
+#endif
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _RTE_TRACE_POINT_H_ */
diff --git a/lib/librte_eal/linux/Makefile b/lib/librte_eal/linux/Makefile
index fc2316667..2ced2085b 100644
--- a/lib/librte_eal/linux/Makefile
+++ b/lib/librte_eal/linux/Makefile
@@ -66,6 +66,7 @@ SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += eal_common_thread.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += eal_common_proc.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += eal_common_fbarray.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += eal_common_uuid.c
+SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += eal_common_trace.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += rte_malloc.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += hotplug_mp.c
 SRCS-$(CONFIG_RTE_EXEC_ENV_LINUX) += malloc_elem.c
diff --git a/meson_options.txt b/meson_options.txt
index 9e4923a4f..3578a23ab 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -30,6 +30,8 @@ option('max_lcores', type: 'integer', value: 128,
 	description: 'maximum number of cores/threads supported by EAL')
 option('max_numa_nodes', type: 'integer', value: 4,
 	description: 'maximum number of NUMA nodes supported by EAL')
+option('enable_trace_fp', type: 'boolean', value: false,
+	description: 'enable fastpath trace points.')
 option('tests', type: 'boolean', value: true,
 	description: 'build unit tests')
 option('use_hpet', type: 'boolean', value: false,
-- 
2.25.1