shell: Allow extension of shell APIs

include/zephyr/shell/shell.h

@@ -1008,9 +1008,10 @@ int shell_stop(const struct shell *sh);
  * @param[in] fmt	Format string.
  * @param[in] ...	List of parameters to print.
  */
-void __printf_like(3, 4) shell_fprintf(const struct shell *sh,
-				       enum shell_vt100_color color,
-				       const char *fmt, ...);
+void __printf_like(3, 4) shell_fprintf_impl(const struct shell *sh, enum shell_vt100_color color,
+					    const char *fmt, ...);
+
+#define shell_fprintf(sh, color, fmt, ...) shell_fprintf_impl(sh, color, fmt, ##__VA_ARGS__)
 
 /**
  * @brief vprintf-like function which sends formatted data stream to the shell.
@@ -1277,4 +1278,9 @@ int shell_get_return_value(const struct shell *sh);
 }
 #endif
 
+#ifdef CONFIG_SHELL_CUSTOM_HEADER
+/* This include must always be at the end of shell.h */
+#include <zephyr_custom_shell.h>
+#endif
+
 #endif /* SHELL_H__ */

subsys/shell/Kconfig

@@ -297,6 +297,14 @@ config SHELL_CMDS_RETURN_VALUE
 	  This option enables the retval command. It is used to retrieve
 	  the return value from the most recently executed command.
 
+config SHELL_CUSTOM_HEADER
+	bool "Include Custom Shell Header"
+	help
+	  When enabled, a custom application provided header, named
+	  "zephyr_custom_shell.h", is included at the end of shell.h. This enables
+	  extension of the shell APIs at the macro level. Please use cautiously!
+	  The internal shell API may change in future releases.
+
 source "subsys/shell/modules/Kconfig"
 
 endif # SHELL

subsys/shell/shell.c

@@ -1548,7 +1548,7 @@ void shell_vfprintf(const struct shell *sh, enum shell_vt100_color color,
 /* This function mustn't be used from shell context to avoid deadlock.
  * However it can be used in shell command handlers.
  */
-void shell_fprintf(const struct shell *sh, enum shell_vt100_color color,
+void shell_fprintf_impl(const struct shell *sh, enum shell_vt100_color color,
 		   const char *fmt, ...)
 {
 	va_list args;

tests/subsys/shell/shell_custom_header/CMakeLists.txt

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(shell_custom_header)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})
+
+zephyr_include_directories(src)

tests/subsys/shell/shell_custom_header/prj.conf

@@ -0,0 +1,11 @@
+CONFIG_SHELL=y
+CONFIG_SHELL_BACKEND_SERIAL=n
+CONFIG_SHELL_BACKEND_DUMMY=y
+CONFIG_SHELL_CMDS_SELECT=y
+CONFIG_SHELL_CMD_BUFF_SIZE=90
+CONFIG_SHELL_PRINTF_BUFF_SIZE=15
+CONFIG_SHELL_METAKEYS=n
+CONFIG_SHELL_CUSTOM_HEADER=y
+CONFIG_LOG=n
+CONFIG_ZTEST=y
+CONFIG_TEST_LOGGING_DEFAULTS=n

tests/subsys/shell/shell_custom_header/src/main.c

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2024 Google, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @file
+ *  @brief Custom header shell test suite
+ *
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/ztest.h>
+
+#include <zephyr/shell/shell.h>
+#include <zephyr/shell/shell_dummy.h>
+
+static void *shell_setup(void)
+{
+	const struct shell *sh = shell_backend_dummy_get_ptr();
+
+	/* Wait for the initialization of the shell dummy backend. */
+	WAIT_FOR(shell_ready(sh), 20000, k_msleep(1));
+	zassert_true(shell_ready(sh), "timed out waiting for dummy shell backend");
+
+	return NULL;
+}
+
+ZTEST_SUITE(sh, NULL, shell_setup, NULL, NULL, NULL);
+
+ZTEST(sh, test_shell_fprintf)
+{
+	static const char expect[] = "[CUSTOM_PREFIX]testing 1 2 3";
+	const struct shell *sh;
+	const char *buf;
+	size_t size;
+
+	sh = shell_backend_dummy_get_ptr();
+	zassert_not_null(sh, "Failed to get shell");
+
+	/* Clear the output buffer */
+	shell_backend_dummy_clear_output(sh);
+
+	shell_fprintf(sh, SHELL_VT100_COLOR_DEFAULT, "testing %d %s %c",
+		      1, "2", '3');
+	buf = shell_backend_dummy_get_output(sh, &size);
+	zassert_true(size >= sizeof(expect), "Expected size > %u, got %d",
+		     sizeof(expect), size);
+
+	/*
+	 * There are prompts and various ANSI characters in the output, so just
+	 * check that the string is in there somewhere.
+	 */
+	zassert_true(strstr(buf, expect),
+		     "Expected string to contain '%s', got '%s'", expect, buf);
+}

tests/subsys/shell/shell_custom_header/src/zephyr_custom_shell.h

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2024 Google, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef __ZEPHYR_CUSTOM_SHELL_H
+#define __ZEPHYR_CUSTOM_SHELL_H
+
+#define CUSTOM_SHELL_PREFIX "[CUSTOM_PREFIX]"
+
+#undef shell_fprintf
+
+#define shell_fprintf(sh, color, fmt, ...)                                                         \
+	shell_fprintf_impl(sh, color, CUSTOM_SHELL_PREFIX fmt, ##__VA_ARGS__)
+
+#endif /* __ZEPHYR_CUSTOM_SHELL_H */

tests/subsys/shell/shell_custom_header/testcase.yaml

@@ -0,0 +1,9 @@
+common:
+  integration_platforms:
+    - native_sim
+
+tests:
+  shell.shell_custom_header:
+    tags:
+      - shell_custom_header
+      - shell