instrumentation: Add instrumentation subsystem

This commit adds the instrumentation subsystem.

Signed-off-by: Gustavo Romero <[email protected]>
Signed-off-by: Kevin Townsend <[email protected]>
Signed-off-by: Maciej Sobkowski <[email protected]>

Author: gromero

include/zephyr/instrumentation/instrumentation.h

@@ -0,0 +1,191 @@
+/*
+ * Copyright 2023 Linaro
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_INSTRUMENTATION_INSTRUMENTATION_H_
+#define ZEPHYR_INCLUDE_INSTRUMENTATION_INSTRUMENTATION_H_
+
+#include <zephyr/kernel.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if !defined(__no_instrumentation__)
+#error "No toolchain support for __no_instrumentation__"
+#endif
+
+/**
+ * @brief Instrumentation event record types.
+ */
+enum instr_event_types {
+	INSTR_EVENT_ENTRY = 0,	/**< Callee entry event record, followed by instr_event. */
+	INSTR_EVENT_EXIT,	/**< Callee exit event record, followed by instr_event. */
+	INSTR_EVENT_PROFILE,	/**< Profile events */
+	INSTR_EVENT_SCHED_IN,	/**< Thread switched in scheduler event */
+	INSTR_EVENT_SCHED_OUT,	/**< Thread switched out scheduler event */
+	INSTR_EVENT_NUM,	/**< Add more events above this one */
+	INSTR_EVENT_INVALID	/**< Invalid or no event generated after promotion */
+} __packed;
+
+/**
+ * @brief Header for the event records.
+ */
+struct instr_header {
+	/** Event type */
+	enum instr_event_types type;
+} __packed;
+
+/**
+ * @brief Context-specific data of an event.
+ */
+struct instr_event_context {
+	/** Arch-specific mode indicator (thread mode, interrupt mode, etc.). */
+	uint8_t mode: 3;
+	/** CPU number. */
+	uint8_t cpu: 5;
+	/** Thread ID (correlate values with thread lookup table). */
+	void *thread_id;
+#ifdef CONFIG_THREAD_NAME
+	/** Thread name (that can be compacted with the correlate lookup table). */
+	char thread_name[CONFIG_THREAD_MAX_NAME_LEN];
+#endif
+} __packed;
+
+/**
+ * @brief Event records and associated payloads. Payloads are determined based
+ *        on the code and additional fields in the header.
+ */
+struct instr_record {
+	struct instr_header header;
+	void *callee;
+	void *caller;
+	uint64_t timestamp;
+	union {
+		struct instr_event_context context; /* Context data */
+		/* Add more payloads here */
+	};
+} __packed;
+
+/**
+ * @brief Checks if tracing feature is available.
+ *
+ */
+bool instr_tracing_supported(void);
+
+/**
+ * @brief Checks if profiling feature is available.
+ *
+ */
+bool instr_profiling_supported(void);
+
+/**
+ * @brief Checks if subsystem is ready to be initialized. Must called be before
+ *        instr_init().
+ */
+bool instr_fundamentals_initialized(void);
+
+/**
+ * @brief Performs initialisation required by the system.
+ */
+int instr_init(void);
+
+/**
+ * @brief Tells if instrumentation subsystem is properly initialized.
+ */
+bool instr_initialized(void);
+
+/**
+ * @brief Tells if instrumentation is enabled, i.e. can be turned on.
+ */
+bool instr_enabled(void);
+
+/**
+ * @brief Enables instrumentation.
+ */
+int instr_enable(void);
+
+/**
+ * @brief Disables instrumentation.
+ */
+int instr_disable(void);
+
+/**
+ * @brief Turns on instrumentation (start recording events).
+ */
+int instr_turn_on(void);
+
+/**
+ * @brief Turns off instrumentation (stop recording events).
+ */
+int instr_turn_off(void);
+
+/**
+ * @brief Tells if instrumentation is turned on.
+ */
+bool instr_turned_on(void);
+
+/**
+ * @brief Tells if instrumentation can collect traces.
+ */
+bool instr_trace_enabled(void);
+
+/**
+ * @brief Tells if instrumentation can collect profile info.
+ */
+bool instr_profile_enabled(void);
+
+/**
+ * @brief Dumps the buffered contents via UART (tracing).
+ */
+void instr_dump_buffer_uart(void);
+
+/**
+ * @brief Dumps the delta accumulator array via UART (profiling).
+ */
+void instr_dump_deltas_uart(void);
+
+/**
+ * @brief Shared callback handler to process entry/exit events.
+ *
+ * @param opcode The type of event to process.
+ * @param func   Address of the function being called.
+ * @param caller Address of the function caller.
+ */
+void instr_event_handler(enum instr_event_types opcode, void *func, void *caller);
+
+/**
+ * @brief Given a function address, set it as the trigger function, i.e. when
+ *        the function is called it will turn on the instrumentation.
+ *
+ * @param callee The function address
+ */
+void instr_set_trigger_func(void *callee);
+
+/**
+ * @brief Given a function address, set it as the stopper function, i.e. when
+ *        the function exits it will turn off the instrumentation.
+ *
+ * @param callee The function address
+ */
+void instr_set_stop_func(void *callee);
+
+/**
+ * @brief Get the trigger function address.
+ *
+ */
+void *instr_get_trigger_func(void);
+
+/**
+ * @brief Get the stopper function address.
+ *
+ */
+void *instr_get_stop_func(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_INSTRUMENTATION_INSTRUMENTATION_H_ */

subsys/CMakeLists.txt

@@ -17,6 +17,7 @@ add_subdirectory(debug)
 add_subdirectory(fb)
 add_subdirectory(fs)
 add_subdirectory(gnss)
+add_subdirectory(instrumentation)
 add_subdirectory(ipc)
 add_subdirectory(logging)
 add_subdirectory(mem_mgmt)

subsys/Kconfig

@@ -25,6 +25,7 @@ source "subsys/fb/Kconfig"
 source "subsys/fs/Kconfig"
 source "subsys/gnss/Kconfig"
 source "subsys/input/Kconfig"
+source "subsys/instrumentation/Kconfig"
 source "subsys/ipc/Kconfig"
 source "subsys/jwt/Kconfig"
 source "subsys/llext/Kconfig"

subsys/instrumentation/CMakeLists.txt

@@ -0,0 +1,24 @@
+# Copyright 2023 Linaro
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_sources_ifdef(CONFIG_INSTRUMENTATION
+  common/instr_common.c
+  timestamp/timestamp.c
+  transport/uart.c
+)
+
+zephyr_sources_ifdef(CONFIG_INSTRUMENTATION_MODE_CALLGRAPH ringbuffer/ringbuffer.c)
+
+if(CONFIG_INSTRUMENTATION)
+  if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+    zephyr_sources(handlers/instr_handlers_gcc.c)
+  else()
+    message(WARNING "CONFIG_INSTRUMENTATION unsupported by this compiler: ${CMAKE_C_COMPILER_ID}.")
+  endif()
+
+  configure_file(${CMAKE_CURRENT_LIST_DIR}/ctf/metadata.template ${CMAKE_BINARY_DIR}/ctf_metadata @ONLY)
+endif()
+
+zephyr_compile_definitions_ifdef(CONFIG_INSTRUMENTATION INSTR_TRIGGER_FUNCTION=${CONFIG_INSTRUMENTATION_TRIGGER_FUNCTION})
+zephyr_compile_definitions_ifdef(CONFIG_INSTRUMENTATION INSTR_STOPPER_FUNCTION=${CONFIG_INSTRUMENTATION_STOPPER_FUNCTION})
+zephyr_include_directories_ifdef(CONFIG_INSTRUMENTATION include)

subsys/instrumentation/Kconfig

@@ -0,0 +1,122 @@
+# Copyright 2023 Linaro
+# SPDX-License-Identifier: Apache-2.0
+
+# Instrumentation configuration options
+
+config INSTRUMENTATION
+	bool "Compiler Instrumentation Support"
+	select REBOOT
+	select RETAINED_MEM
+	select RETAINED_MEM_ZEPHYR_RAM
+	select RETAINED_MEM_MUTEX_FORCE_DISABLE
+	select RETENTION
+	select RETENTION_MUTEX_FORCE_DISABLE
+	select UART_INTERRUPT_DRIVEN
+	help
+	  Enable compiler-managed runtime system instrumentation. This requires
+	  a compiler that supports function instrumentation, and a backend for
+	  capturing and processing those instrumentation events from the target,
+	  like a serial port.
+
+if INSTRUMENTATION
+
+config INSTRUMENTATION_MODE_CALLGRAPH
+	bool "Call graph mode (Tracing)"
+	default y
+	select THREAD_NAME
+	select TRACING
+	select TIMING_FUNCTIONS
+	help
+	  Enables reconstruction of function call graphs and the observation
+	  of context switches (threads), within the limits of the trace buffer
+	  size.
+
+config INSTRUMENTATION_MODE_CALLGRAPH_TRACE_BUFFER_SIZE
+	int "Size of the trace buffer (bytes)"
+	depends on INSTRUMENTATION_MODE_CALLGRAPH
+	default 12000
+	# Lower limit (in bytes) must match the biggest record item size. For
+	# details about the sizes, please see instrumentation.h for the record
+	# struct sizes.
+	range 20 4294967296
+	help
+	  Size of the trace buffer. The trace buffer is used to buffer the
+	  tracing events and has two working modes: it can be configure either
+	  as a simple buffer or as a ring buffer (overwriting mode).
+
+config INSTRUMENTATION_MODE_CALLGRAPH_BUFFER_OVERWRITE
+	bool "Trace buffer overwriting mode"
+	depends on INSTRUMENTATION_MODE_CALLGRAPH
+	default y
+	help
+	  If the trace buffer is set as overwriting it works as a ring buffer.
+	  In this working mode if the buffer gets full old records will be
+	  overwritten by the newer records. This mode allows recording the most
+	  recent tracing events at the expense of losing the old ones. If this
+	  mode is not selected, then once the buffer is full tracing stops.
+
+config INSTRUMENTATION_MODE_STATISTICAL
+	bool "Statistical mode (Profiling)"
+	select TIMING_FUNCTIONS
+	default y
+	help
+	  Enables statistical profiling of the runtime system, tracking total
+	  execution time of the number of functions equal to
+	  INSTRUMENTATION_MODE_STATISTICAL_MAX_NUM_FUNC.
+
+config INSTRUMENTATION_MODE_STATISTICAL_MAX_NUM_FUNC
+	int "Maximum number of functions to collect statistics from"
+	depends on INSTRUMENTATION_MODE_STATISTICAL
+	default 256
+	range 1 4096
+	help
+	  Maximum number of functions to collect statistics from. Set the
+	  maximum number of functions to collect the total execution time for
+	  each function called in the region defined by 'trigger' and 'stopper'
+	  instrumentation points.
+
+config INSTRUMENTATION_MODE_STATISTICAL_MAX_CALL_DEPTH
+	int "Maximum call depth"
+	depends on INSTRUMENTATION_MODE_STATISTICAL
+	default 65535
+	range 1 65535
+	help
+	  The maximum number of times a function can be recursively called
+	  before profile data (delta time) stops being collected.
+
+config INSTRUMENTATION_TRIGGER_FUNCTION
+	string "Default trigger function used to turn on instrumentation"
+	default "main"
+	help
+	  Sets the trigger function. Instrumentation (tracing and profiling) is
+	  only turned on when the trigger function is called. The trigger
+	  function can be changed at runtime via the 'zaru' CLI tool.
+
+config INSTRUMENTATION_STOPPER_FUNCTION
+	string "Default stopper function used to turn off instrumentation"
+	default "main"
+	help
+	  Sets the stopper function. Instrumentation (tracing and profiling) is
+	  only turned off when the trigger function returns. The stopper
+	  function can be changed at runtime via the 'zaru' CLI tool.
+
+config INSTRUMENTATION_EXCLUDE_FUNCTION_LIST
+	string "Exclude function list"
+	depends on INSTRUMENTATION_MODE_CALLGRAPH || INSTRUMENTATION_MODE_STATISTICAL
+	help
+	  Set the list of function names to be excluded from instrumentation.
+	  The function name to be matched is its user-visible name. The match is
+	  done on substrings: if the function name in the list is a substring of
+	  a function name, it is considered to be a match. The function names in
+	  the list are separate by a comma, for instance: sym0, sym1, ...
+
+config INSTRUMENTATION_EXCLUDE_FILE_LIST
+	string "Exclude file list"
+	depends on INSTRUMENTATION_MODE_CALLGRAPH || INSTRUMENTATION_MODE_STATISTICAL
+	help
+	  Set the list of files that are excluded from instrumentation. The
+	  match is done on substrings: if the file parameter is a substring of
+	  the file name, it is considered to be a match. The files in the list
+	  are separate by a comma, for instance: file0, file1, ...
+
+endif