logging: rpc: add history usage threshold signaling

This commit introduces log history usage threshold value
indicating that the server shall send an RPC event when the
log history ring buffer usage exceeds the threshold.

Signed-off-by: Konrad Derda <[email protected]>
Signed-off-by: Damian Krolik <[email protected]>

Author: kderda

include/logging/log_rpc.h

@@ -8,6 +8,7 @@
 #define LOG_RPC_H_
 
 #include <stddef.h>
+#include <stdint.h>
 
 /**
  * @file
@@ -21,7 +22,7 @@ extern "C" {
 #endif
 
 /**
- * nRF RPC logging level.
+ * @brief nRF RPC logging level.
  */
 enum log_rpc_level {
 	LOG_RPC_LEVEL_NONE = 0,
@@ -32,55 +33,93 @@ enum log_rpc_level {
 };
 
 /**
- * Log history handler.
+ * @brief Log history handler.
  *
  * The type of a callback function that is invoked for each received log message
  * while fetching the log history from the remote device.
  *
- * @param level		The message level, see @c log_rpc_level.
+ * @param level		The message level, see @ref log_rpc_level.
  * @param msg		A pointer to the message payload.
  * @param msg_len	The message payload length.
  */
 typedef void (*log_rpc_history_handler_t)(enum log_rpc_level level, const char *msg,
 					  size_t msg_len);
 
+/** @brief Log history threshold reached handler.
+ *
+ * The type of a callback function that is invoked when the log history usage
+ * threshold configured with @ref log_rpc_set_history_level has been reached for
+ * the first time.
+ */
+typedef void (*log_rpc_history_threshold_reached_handler_t)(void);
+
 /**
- * Sets the log streaming verbosity level.
+ * @brief Sets the log streaming verbosity level.
  *
  * The log streaming is the feature of nRF RPC logging that allows receiving log
  * messages as they are generated by the application running on the remote device.
  *
  * This function issues an nRF RPC command that configures the remote device to
  * stream log messages whose level is less than or equal to the specified level.
  *
- * @param level		Logging level, see @c log_rpc_level.
+ * @param level		Logging level, see @ref log_rpc_level.
  *
  * @retval 0		On success.
  * @retval -errno	On failure.
  */
 int log_rpc_set_stream_level(enum log_rpc_level level);
 
 /**
- * Sets the log history verbosity level.
+ * @brief Sets the log history verbosity level.
  *
  * The log history is the feature of nRF RPC logging that allows saving log
  * messages generated by the application running on the remote device into
  * a ring buffer, and then retrieving the log history when needed.
  *
- * The function issues an nRF RPC command that configures the remote device to
+ * This function issues an nRF RPC command that configures the remote device to
  * save log messages whose level is less than or equal to the specified level.
  *
- * @param level		Logging level, see @c log_rpc_level.
+ * @param level		Logging level, see @ref log_rpc_level.
  *
  * @retval 0		On success.
  * @retval -errno	On failure.
  */
 int log_rpc_set_history_level(enum log_rpc_level level);
 
 /**
- * Fetches the log history.
+ * @brief Gets the current history usage threshold.
+ *
+ * This function fetches the current history usage threshold.
+ *
+ * @returns The current history usage threshold in percentage.
+ */
+uint8_t log_rpc_get_history_usage_threshold(void);
+
+/**
+ * @brief Sets the current history usage threshold.
+ *
+ * The log history is the feature of nRF RPC logging that allows saving log
+ * messages generated by the application running on the remote device into
+ * a ring buffer, and then retrieving the log history when needed.
+ *
+ * This function issues an nRF RPC command that requests the remote device to
+ * emit an nRF RPC event when the ring buffer occupancy exceeds the requested
+ * threshold for the first time after the threshold is set or the log history
+ * is flushed.
+ *
+ * @param handler	The handler that is invoked when the configured log
+ *			history usage threshold has been reached, see
+ *			@ref log_rpc_history_threshold_reached_handler_t.
+ * @param threshold	The history usage threshold in percentage (0 - 100).
+ *			Passing 0 disables this feature.
+ */
+void log_rpc_set_history_usage_threshold(log_rpc_history_threshold_reached_handler_t handler,
+					 uint8_t threshold);
+
+/**
+ * @brief Fetches the log history.
  *
- * The function issues an nRF RPC command that starts the log history transfer
+ * This function issues an nRF RPC command that starts the log history transfer
  * from the remote device. The @c handler callback function is invoked for each
  * received log message. Additionally, it is invoked with @c msg argument set to
  * NULL after all log messages have been received.
@@ -89,7 +128,7 @@ int log_rpc_set_history_level(enum log_rpc_level level);
  *       still is in progress, the process is restarted from the current oldest
  *       log message saved in the log history on the remote device.
  *
- * @param handler	History handler, see @c log_rpc_history_handler_t.
+ * @param handler	History handler, see @ref log_rpc_history_handler_t.
  *
  * @retval 0		On success.
  * @retval -errno	On failure.
@@ -99,7 +138,7 @@ int log_rpc_fetch_history(log_rpc_history_handler_t handler);
 /**
  * @brief Retrieves the crash log retained on the remote device.
  *
- * The function issues an nRF RPC command to obtain the last crash log retained
+ * This function issues an nRF RPC command to obtain the last crash log retained
  * on the remote device, and then it copies the received log chunk into the
  * specified buffer.
  *
@@ -120,7 +159,7 @@ int log_rpc_get_crash_log(size_t offset, char *buffer, size_t buffer_length);
 /**
  * @brief Generates a log message on the remote device.
  *
- * The function issues an nRF RPC command that requests the remote device to
+ * This function issues an nRF RPC command that requests the remote device to
  * generate a log message with the given level. This function can be used to
  * test other functions of Logging over nRF RPC library.
  */

samples/nrf_rpc/protocols_serialization/client/src/log_rpc_shell.c

@@ -99,6 +99,39 @@ static int cmd_log_rpc_history_fetch(const struct shell *sh, size_t argc, char *
 	return 0;
 }
 
+static void history_threshold_reached_handler(void)
+{
+	shell_print(shell, "History usage threshold reached");
+}
+
+static int cmd_log_rpc_history_threshold(const struct shell *sh, size_t argc, char *argv[])
+{
+	uint32_t threshold;
+	int rc = 0;
+
+	if (argc == 0) {
+		shell_print(sh, "%u", log_rpc_get_history_usage_threshold());
+		return 0;
+	}
+
+	threshold = shell_strtoul(argv[1], 0, &rc);
+
+	if (rc) {
+		shell_error(sh, "Invalid argument: %d", rc);
+		return -EINVAL;
+	}
+
+	if (threshold > 100) {
+		shell_error(sh, "%u exceeds max value (100)", threshold);
+		return -EINVAL;
+	}
+
+	shell = sh;
+	log_rpc_set_history_usage_threshold(history_threshold_reached_handler, (uint8_t)threshold);
+
+	return 0;
+}
+
 static int cmd_log_rpc_crash(const struct shell *sh, size_t argc, char *argv[])
 {
 	int rc;
@@ -149,6 +182,8 @@ SHELL_STATIC_SUBCMD_SET_CREATE(
 	SHELL_CMD_ARG(history_level, NULL, "Set log history level", cmd_log_rpc_history_level, 2,
 		      0),
 	SHELL_CMD_ARG(history_fetch, NULL, "Fetch log history", cmd_log_rpc_history_fetch, 1, 0),
+	SHELL_CMD_ARG(history_threshold, NULL, "Get or set history usage threshold",
+		      cmd_log_rpc_history_threshold, 1, 1),
 	SHELL_CMD_ARG(crash, NULL, "Retrieve remote device crash log", cmd_log_rpc_crash, 1, 0),
 	SHELL_CMD_ARG(echo, NULL, "Generate log message on remote", cmd_log_rpc_echo, 3, 0),
 	SHELL_SUBCMD_SET_END);

subsys/logging/Kconfig

@@ -55,6 +55,7 @@ config LOG_BACKEND_RPC_HISTORY_STORAGE_RAM
 
 config LOG_BACKEND_RPC_HISTORY_STORAGE_FCB
 	bool "Flash Circular Buffer"
+	depends on FCB
 	help
 	  Stores the log history in Flash Circular Buffer located in the "log_history"
 	  flash partition. Note that enabling this option may significantly increase

subsys/logging/log_backend_rpc.c

@@ -49,6 +49,8 @@ static enum log_rpc_level stream_level = LOG_RPC_LEVEL_NONE;
 
 #ifdef CONFIG_LOG_BACKEND_RPC_HISTORY
 static enum log_rpc_level history_level = LOG_RPC_LEVEL_NONE;
+static uint8_t history_threshold;
+static bool history_threshold_active;
 static void history_transfer_task(struct k_work *work);
 static K_MUTEX_DEFINE(history_transfer_mtx);
 static uint32_t history_transfer_id;
@@ -361,6 +363,15 @@ static void process(const struct log_backend *const backend, union log_msg_gener
 
 	if (max_level != LOG_RPC_LEVEL_NONE && level <= max_level) {
 		log_rpc_history_push(msg_generic);
+
+		if (history_threshold_active && log_rpc_history_get_usage() > history_threshold) {
+			struct nrf_rpc_cbor_ctx ctx;
+
+			NRF_RPC_CBOR_ALLOC(&log_rpc_group, ctx, 0);
+			nrf_rpc_cbor_evt_no_err(&log_rpc_group,
+						LOG_RPC_EVT_HISTORY_THRESHOLD_REACHED, &ctx);
+			history_threshold_active = false;
+		}
 	}
 #endif
 }
@@ -519,6 +530,7 @@ static void history_transfer_task(struct k_work *work)
 		log_rpc_history_free(history_cur_msg);
 		history_cur_msg = NULL;
 		log_rpc_history_set_overwriting(true);
+		history_threshold_active = history_threshold > 0;
 	}
 
 	k_mutex_unlock(&history_transfer_mtx);
@@ -552,6 +564,40 @@ static void log_rpc_fetch_history_handler(const struct nrf_rpc_group *group,
 NRF_RPC_CBOR_CMD_DECODER(log_rpc_group, log_rpc_fetch_history_handler, LOG_RPC_CMD_FETCH_HISTORY,
 			 log_rpc_fetch_history_handler, NULL);
 
+static void log_rpc_get_history_usage_threshold_handler(const struct nrf_rpc_group *group,
+							struct nrf_rpc_cbor_ctx *ctx,
+							void *handler_data)
+{
+	nrf_rpc_cbor_decoding_done(group, ctx);
+	nrf_rpc_rsp_send_uint(group, history_threshold);
+}
+
+NRF_RPC_CBOR_CMD_DECODER(log_rpc_group, log_rpc_get_history_usage_threshold_handler,
+			 LOG_RPC_CMD_GET_HISTORY_USAGE_THRESHOLD,
+			 log_rpc_get_history_usage_threshold_handler, NULL);
+
+static void log_rpc_set_history_usage_threshold_handler(const struct nrf_rpc_group *group,
+							struct nrf_rpc_cbor_ctx *ctx,
+							void *handler_data)
+{
+	uint8_t threshold = nrf_rpc_decode_uint(ctx);
+
+	if (!nrf_rpc_decoding_done_and_check(group, ctx)) {
+		nrf_rpc_err(-EBADMSG, NRF_RPC_ERR_SRC_RECV, group,
+			    LOG_RPC_CMD_SET_HISTORY_USAGE_THRESHOLD, NRF_RPC_PACKET_TYPE_CMD);
+		return;
+	}
+
+	history_threshold = threshold;
+	history_threshold_active = threshold > 0;
+
+	nrf_rpc_rsp_send_void(group);
+}
+
+NRF_RPC_CBOR_CMD_DECODER(log_rpc_group, log_rpc_set_history_usage_threshold_handler,
+			 LOG_RPC_CMD_SET_HISTORY_USAGE_THRESHOLD,
+			 log_rpc_set_history_usage_threshold_handler, NULL);
+
 #endif
 
 #ifdef CONFIG_LOG_BACKEND_RPC_ECHO

subsys/logging/log_backend_rpc_history.h

@@ -17,4 +17,6 @@ void log_rpc_history_set_overwriting(bool overwriting);
 union log_msg_generic *log_rpc_history_pop(void);
 void log_rpc_history_free(const union log_msg_generic *msg);
 
+uint8_t log_rpc_history_get_usage(void);
+
 #endif /* LOG_RPC_HISTORY_H_ */

subsys/logging/log_backend_rpc_history_fcb.c

@@ -153,3 +153,21 @@ void log_rpc_history_free(const union log_msg_generic *msg)
 {
 	k_free((void *)msg);
 }
+
+uint8_t log_rpc_history_get_usage(void)
+{
+	int num_free_sectors;
+
+	k_mutex_lock(&fcb_lock, K_FOREVER);
+
+	num_free_sectors = fcb_free_sector_cnt(&fcb);
+
+	k_mutex_unlock(&fcb_lock);
+
+	/*
+	 * This calculates the usage with the sector size granularity.
+	 * Unforunately, there is no FCB API for getting more accurate usage, but it can be
+	 * implemented by hand if the greater accuraccy turns out to be needed.
+	 */
+	return (fcb.f_sector_cnt - num_free_sectors) * 100 / fcb.f_sector_cnt;
+}

subsys/logging/log_backend_rpc_history_ram.c

@@ -81,3 +81,13 @@ void log_rpc_history_free(const union log_msg_generic *msg)
 
 	mpsc_pbuf_free(&log_history_pbuf, &msg->buf);
 }
+
+uint8_t log_rpc_history_get_usage(void)
+{
+	size_t total_size;
+	size_t current_size;
+
+	mpsc_pbuf_get_utilization(&log_history_pbuf, &total_size, &current_size);
+
+	return current_size * 100 / total_size;
+}

subsys/logging/log_forwarder_rpc.c

@@ -26,6 +26,7 @@ LOG_MODULE_REGISTER(remote, LOG_LEVEL_DBG);
 static K_MUTEX_DEFINE(history_transfer_mtx);
 static uint32_t history_transfer_id;
 static log_rpc_history_handler_t history_handler;
+static log_rpc_history_threshold_reached_handler_t history_threshold_reached_handler;
 
 static void log_rpc_msg_handler(const struct nrf_rpc_group *group, struct nrf_rpc_cbor_ctx *ctx,
 				void *handler_data)
@@ -204,3 +205,44 @@ void log_rpc_echo(enum log_rpc_level level, const char *message)
 
 	nrf_rpc_cbor_decoding_done(&log_rpc_group, &ctx);
 }
+
+static void log_rpc_history_threshold_reached_handler(const struct nrf_rpc_group *group,
+						      struct nrf_rpc_cbor_ctx *ctx,
+						      void *handler_data)
+{
+	nrf_rpc_cbor_decoding_done(&log_rpc_group, ctx);
+
+	if (history_threshold_reached_handler) {
+		history_threshold_reached_handler();
+	}
+}
+
+NRF_RPC_CBOR_EVT_DECODER(log_rpc_group, log_rpc_history_threshold_reached_handler,
+			 LOG_RPC_EVT_HISTORY_THRESHOLD_REACHED,
+			 log_rpc_history_threshold_reached_handler, NULL);
+
+uint8_t log_rpc_get_history_usage_threshold(void)
+{
+	struct nrf_rpc_cbor_ctx ctx;
+	uint8_t threshold;
+
+	NRF_RPC_CBOR_ALLOC(&log_rpc_group, ctx, 0);
+
+	nrf_rpc_cbor_cmd_no_err(&log_rpc_group, LOG_RPC_CMD_GET_HISTORY_USAGE_THRESHOLD, &ctx,
+				nrf_rpc_rsp_decode_u8, &threshold);
+
+	return threshold;
+}
+
+void log_rpc_set_history_usage_threshold(log_rpc_history_threshold_reached_handler_t handler,
+					 uint8_t threshold)
+{
+	struct nrf_rpc_cbor_ctx ctx;
+
+	history_threshold_reached_handler = handler;
+
+	NRF_RPC_CBOR_ALLOC(&log_rpc_group, ctx, 2);
+	nrf_rpc_encode_uint(&ctx, threshold);
+	nrf_rpc_cbor_cmd_no_err(&log_rpc_group, LOG_RPC_CMD_SET_HISTORY_USAGE_THRESHOLD, &ctx,
+				nrf_rpc_rsp_decode_void, NULL);
+}

subsys/logging/log_rpc_group.h

@@ -29,6 +29,7 @@ NRF_RPC_GROUP_DEFINE(log_rpc_group, "log", &log_rpc_tr, NULL, NULL, NULL);
 
 enum log_rpc_evt_forwarder {
 	LOG_RPC_EVT_MSG = 0,
+	LOG_RPC_EVT_HISTORY_THRESHOLD_REACHED = 1,
 };
 
 enum log_rpc_cmd_forwarder {
@@ -37,10 +38,12 @@ enum log_rpc_cmd_forwarder {
 
 enum log_rpc_cmd_backend {
 	LOG_RPC_CMD_SET_STREAM_LEVEL = 0,
-	LOG_RPC_CMD_SET_HISTORY_LEVEL = 1,
-	LOG_RPC_CMD_FETCH_HISTORY = 2,
-	LOG_RPC_CMD_GET_CRASH_LOG = 3,
-	LOG_RPC_CMD_ECHO = 4,
+	LOG_RPC_CMD_SET_HISTORY_LEVEL,
+	LOG_RPC_CMD_GET_HISTORY_USAGE_THRESHOLD,
+	LOG_RPC_CMD_SET_HISTORY_USAGE_THRESHOLD,
+	LOG_RPC_CMD_FETCH_HISTORY,
+	LOG_RPC_CMD_GET_CRASH_LOG,
+	LOG_RPC_CMD_ECHO,
 };
 
 #ifdef __cplusplus