From 27db82c709dc466537b8437b0dec0619880d59c9 Mon Sep 17 00:00:00 2001 From: Jerin Jacob Date: Thu, 23 Apr 2020 00:33:19 +0530 Subject: [PATCH] trace: introduce new subsystem 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 8 bytes tracepoint object is a global variable, and can be used in fast path. 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 Signed-off-by: Sunil Kumar Kori Acked-by: David Marchand --- 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 7b81e2d1bb..52bbff6233 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 +M: Sunil Kumar Kori +F: lib/librte_eal/include/rte_trace*.h +F: lib/librte_eal/common/eal_common_trace*.c + Memory Allocation M: Anatoly Burakov F: lib/librte_eal/include/rte_fbarray.h diff --git a/config/common_base b/config/common_base index 9ec689dde1..d26eebbba2 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 224d29e1ce..e851b407b2 100644 --- a/config/meson.build +++ b/config/meson.build @@ -229,6 +229,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 dff496be09..845a53491e 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 e34daab91b..7679c049af 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 fast path traces + # 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 0000000000..33a6e563a1 --- /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 +#include + diff --git a/lib/librte_eal/common/meson.build b/lib/librte_eal/common/meson.build index 02d9280cc3..429e89f999 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 2d53ce9eef..500afc5785 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 6fd4274941..126455d1cf 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 0000000000..a6e991fad3 --- /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 +#include + +#include +#include + +/** + * Test if trace is enabled. + * + * @return + * true if trace is enabled, false otherwise. + */ +__rte_experimental +bool rte_trace_is_enabled(void); + +/** + * Enumerate trace mode operation. + */ +enum rte_trace_mode { + /** + * In this mode, when no space is left in the trace buffer, the + * subsequent events overwrite the old events. + */ + RTE_TRACE_MODE_OVERWRITE, + /** + * In this mode, when no space is left in the trace buffer, the + * subsequent events shall not be recorded. + */ + RTE_TRACE_MODE_DISCARD, +}; + +/** + * 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 globbing 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 0000000000..3c2f8805e8 --- /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 +#include + +#include +#include + +/** 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. + * + * A tracepoint is defined by specifying: + * - its input arguments: they are the C function style parameters to define + * the arguments of tracepoint function. These input arguments are embedded + * using the 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 for fast path. + * + * Similar to RTE_TRACE_POINT, except that it is removed at compilation time + * unless the RTE_ENABLE_TRACE_FP configuration parameter is set. + * + * @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 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 events 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 events 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 recording events from the 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 fast path compile-time option is enabled. + * + * @return + * true if tracepoint fast path 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 fc2316667a..2ced2085b9 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 9e4923a4f1..9bf18ab6b1 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 fast path trace points.') option('tests', type: 'boolean', value: true, description: 'build unit tests') option('use_hpet', type: 'boolean', value: false, -- 2.20.1