[cli] support adding vendor command list to cli apps (#9001)

include/openthread/cli.h

@@ -148,6 +148,15 @@ void otCliAppendResult(otError aError);
  */
 void otCliPlatLogv(otLogLevel aLogLevel, otLogRegion aLogRegion, const char *aFormat, va_list aArgs);
 
+/**
+ * Callback to allow vendor specific commands to be added to the user command table.
+ *
+ * Available when `OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE` is enabled and
+ * `OPENTHREAD_CONFIG_CLI_MAX_USER_CMD_ENTRIES` is greater than 1.
+ *
+ */
+extern void otCliVendorSetUserCommands(void);
+
 /**
  * @}
  *

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (321)
+#define OPENTHREAD_API_VERSION (322)
 
 /**
  * @addtogroup api-instance

script/check-simulation-build-cmake

@@ -96,6 +96,11 @@ build_all_features()
     # Build with RAM settings
     reset_source
     "$(dirname "$0")"/cmake-build simulation -DOT_SETTINGS_RAM=ON
+
+    # Build with Vendor CLI commands
+    reset_source
+    "$(dirname "$0")"/cmake-build simulation \
+        -DOT_CLI_VENDOR_EXTENSION=../../src/cli/cli_extension_example.cmake
 }
 
 build_toranj()

src/cli/CMakeLists.txt

@@ -48,6 +48,13 @@ set(COMMON_SOURCES
     cli_udp.cpp
 )
 
+set(OT_CLI_VENDOR_EXTENSION "" CACHE STRING "Path to CMake file to define and link cli vendor extension")
+if(OT_CLI_VENDOR_EXTENSION)
+    set(OT_CLI_VENDOR_TARGET "" CACHE STRING "Name of vendor extension CMake target to link with cli app")
+    include(${OT_CLI_VENDOR_EXTENSION})
+    target_compile_definitions(ot-config INTERFACE "OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE=1")
+endif()
+
 if(OT_FTD)
     include(ftd.cmake)
 endif()

src/cli/cli.cpp

@@ -8711,6 +8711,10 @@ otError Interpreter::ProcessCommand(Arg aArgs[])
 extern "C" void otCliInit(otInstance *aInstance, otCliOutputCallback aCallback, void *aContext)
 {
     Interpreter::Initialize(aInstance, aCallback, aContext);
+
+#if OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE && OPENTHREAD_CONFIG_CLI_MAX_USER_CMD_ENTRIES > 1
+    otCliVendorSetUserCommands();
+#endif
 }
 
 extern "C" void otCliInputLine(char *aBuf) { Interpreter::GetInterpreter().ProcessLine(aBuf); }

src/cli/cli_config.h

@@ -97,6 +97,18 @@
 #define OPENTHREAD_CONFIG_CLI_MAX_USER_CMD_ENTRIES 1
 #endif
 
+/**
+ * @def OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE
+ *
+ * Indicates whether or not an externally provided list of cli commands is defined.
+ *
+ * This is to be used only when `OPENTHREAD_CONFIG_CLI_MAX_USER_CMD_ENTRIES` is greater than 1.
+ *
+ */
+#ifndef OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE
+#define OPENTHREAD_CONFIG_CLI_VENDOR_COMMANDS_ENABLE 0
+#endif
+
 /**
  * @def OPENTHREAD_CONFIG_CLI_LOG_INPUT_OUTPUT_ENABLE
  *

src/cli/cli_extension_example.c

@@ -0,0 +1,57 @@
+/*
+ *  Copyright (c) 2023, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * @file
+ * @brief # This file provides an example on how to implement a CLI vendor extension.
+ */
+
+#include <openthread/cli.h>
+#include "common/code_utils.hpp"
+
+static otError helloWorldCommand(void *aContext, uint8_t aArgsLength, char *aArgs[])
+{
+    otCliOutputFormat("Hello world!\r\n");
+    return OT_ERROR_NONE;
+}
+
+static otError threadCommand(void *aContext, uint8_t aArgsLength, char *aArgs[])
+{
+    otCliOutputFormat("Thread is great!\r\n");
+    return OT_ERROR_NONE;
+}
+
+static const otCliCommand sExtensionCommands[] = {
+    {"extensionhello", helloWorldCommand},
+    {"extensionthread", threadCommand},
+};
+
+void otCliVendorSetUserCommands(void)
+{
+    IgnoreError(otCliSetUserCommands(sExtensionCommands, OT_ARRAY_LENGTH(sExtensionCommands), NULL));
+}

src/cli/cli_extension_example.cmake

@@ -0,0 +1,39 @@
+#
+#  Copyright (c) 2023, The OpenThread Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+# This file provides an example on how to implement a CLI vendor extension.
+
+target_compile_definitions(ot-config INTERFACE "OPENTHREAD_CONFIG_CLI_MAX_USER_CMD_ENTRIES=2")
+
+add_library(cli-extension-example cli_extension_example.c)
+
+target_link_libraries(cli-extension-example PRIVATE ot-config)
+
+target_include_directories(cli-extension-example PUBLIC ${OT_PUBLIC_INCLUDES} PRIVATE ${COMMON_INCLUDES})
+
+set(OT_CLI_VENDOR_TARGET cli-extension-example)

src/cli/ftd.cmake

@@ -49,3 +49,7 @@ target_link_libraries(openthread-cli-ftd
         ot-config-ftd
         ot-config
 )
+
+if(OT_CLI_VENDOR_TARGET)
+    target_link_libraries(openthread-cli-ftd PRIVATE ${OT_CLI_VENDOR_TARGET})
+endif()

src/cli/mtd.cmake

@@ -49,3 +49,7 @@ target_link_libraries(openthread-cli-mtd
         ot-config-mtd
         ot-config
 )
+
+if(OT_CLI_VENDOR_TARGET)
+    target_link_libraries(openthread-cli-mtd PRIVATE ${OT_CLI_VENDOR_TARGET})
+endif()

src/cli/radio.cmake

@@ -58,3 +58,7 @@ target_link_libraries(openthread-cli-radio
         ot-config-radio
         ot-config
 )
+
+if(OT_CLI_VENDOR_TARGET)
+    target_link_libraries(openthread-cli-radio PRIVATE ${OT_CLI_VENDOR_TARGET})
+endif()