1 /* 2 * Copyright (c) 2015, Freescale Semiconductor, Inc. 3 * Copyright 2016-2020 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __FSL_SHELL_H__ 10 #define __FSL_SHELL_H__ 11 12 /*! 13 * @addtogroup SHELL 14 * @{ 15 */ 16 17 #include "fsl_common.h" 18 #include "fsl_component_serial_manager.h" 19 #include "fsl_component_generic_list.h" 20 21 /******************************************************************************* 22 * Definitions 23 ******************************************************************************/ 24 25 /*! @brief Whether use non-blocking mode. */ 26 #ifndef SHELL_NON_BLOCKING_MODE 27 #define SHELL_NON_BLOCKING_MODE SERIAL_MANAGER_NON_BLOCKING_MODE 28 #endif 29 30 /*! @brief Macro to set on/off auto-complete feature. */ 31 #define SHELL_AUTO_COMPLETE (1U) 32 33 /*! @brief Macro to set console buffer size. */ 34 #ifndef SHELL_BUFFER_SIZE 35 #define SHELL_BUFFER_SIZE (64U) 36 #endif 37 38 /*! @brief Macro to set maximum arguments in command. */ 39 #define SHELL_MAX_ARGS (8U) 40 41 /*! @brief Macro to set maximum count of history commands. */ 42 #ifndef SHELL_HISTORY_COUNT 43 #define SHELL_HISTORY_COUNT (3U) 44 #endif 45 46 /*! @brief Macro to bypass arguments check */ 47 #define SHELL_IGNORE_PARAMETER_COUNT (0xFF) 48 49 /*! @brief The handle size of the shell module. It is the sum of the SHELL_HISTORY_COUNT * SHELL_BUFFER_SIZE + 50 * SHELL_BUFFER_SIZE + SERIAL_MANAGER_READ_HANDLE_SIZE + SERIAL_MANAGER_WRITE_HANDLE_SIZE*/ 51 #define SHELL_HANDLE_SIZE \ 52 (160U + SHELL_HISTORY_COUNT * SHELL_BUFFER_SIZE + SHELL_BUFFER_SIZE + SERIAL_MANAGER_READ_HANDLE_SIZE + \ 53 SERIAL_MANAGER_WRITE_HANDLE_SIZE) 54 55 /*! @brief Macro to determine whether use common task. */ 56 #ifndef SHELL_USE_COMMON_TASK 57 #define SHELL_USE_COMMON_TASK (0U) 58 #endif 59 60 /*! @brief Macro to set shell task priority. */ 61 #ifndef SHELL_TASK_PRIORITY 62 #define SHELL_TASK_PRIORITY (2U) 63 #endif 64 65 /*! @brief Macro to set shell task stack size. */ 66 #ifndef SHELL_TASK_STACK_SIZE 67 #define SHELL_TASK_STACK_SIZE (1000U) 68 #endif 69 70 /*! @brief Shell status */ 71 typedef enum _shell_status 72 { 73 kStatus_SHELL_Success = kStatus_Success, /*!< Success */ 74 kStatus_SHELL_Error = MAKE_STATUS(kStatusGroup_SHELL, 1), /*!< Failed */ 75 kStatus_SHELL_OpenWriteHandleFailed = MAKE_STATUS(kStatusGroup_SHELL, 2), /*!< Open write handle failed */ 76 kStatus_SHELL_OpenReadHandleFailed = MAKE_STATUS(kStatusGroup_SHELL, 3), /*!< Open read handle failed */ 77 } shell_status_t; 78 79 /*! @brief The handle of the shell module */ 80 typedef void *shell_handle_t; 81 82 /*! @brief User command function prototype. */ 83 typedef shell_status_t (*cmd_function_t)(shell_handle_t shellHandle, int32_t argc, char **argv); 84 85 /*! @brief User command data configuration structure. */ 86 typedef struct _shell_command 87 { 88 const char *pcCommand; /*!< The command that is executed. For example "help". It must be all lower case. */ 89 char *pcHelpString; /*!< String that describes how to use the command. It should start with the command itself, 90 and end with "\r\n". For example "help: Returns a list of all the commands\r\n". */ 91 const cmd_function_t 92 pFuncCallBack; /*!< A pointer to the callback function that returns the output generated by the command. */ 93 uint8_t cExpectedNumberOfParameters; /*!< Commands expect a fixed number of parameters, which may be zero. */ 94 list_element_t link; /*!< link of the element */ 95 } shell_command_t; 96 97 /*! 98 * @brief Defines the shell handle 99 * 100 * This macro is used to define a 4 byte aligned shell handle. 101 * Then use "(shell_handle_t)name" to get the shell handle. 102 * 103 * The macro should be global and could be optional. You could also define shell handle by yourself. 104 * 105 * This is an example, 106 * @code 107 * SHELL_HANDLE_DEFINE(shellHandle); 108 * @endcode 109 * 110 * @param name The name string of the shell handle. 111 */ 112 #define SHELL_HANDLE_DEFINE(name) uint32_t name[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))] 113 114 #if defined(__ICCARM__) 115 /* disable misra 19.13 */ 116 _Pragma("diag_suppress=Pm120") 117 #endif 118 /*! 119 * @brief Defines the shell command structure 120 * 121 * This macro is used to define the shell command structure #shell_command_t. 122 * And then uses the macro SHELL_COMMAND to get the command structure pointer. 123 * The macro should not be used in any function. 124 * 125 * This is a example, 126 * @code 127 * SHELL_COMMAND_DEFINE(exit, "\r\n\"exit\": Exit program\r\n", SHELL_ExitCommand, 0); 128 * SHELL_RegisterCommand(s_shellHandle, SHELL_COMMAND(exit)); 129 * @endcode 130 * 131 * @param command The command string of the command. The double quotes do not need. Such as exit for "exit", 132 * help for "Help", read for "read". 133 * @param descriptor The description of the command is used for showing the command usage when "help" is typing. 134 * @param callback The callback of the command is used to handle the command line when the input command is matched. 135 * @param paramCount The max parameter count of the current command. 136 */ 137 #define SHELL_COMMAND_DEFINE(command, descriptor, callback, paramCount) \ 138 \ 139 shell_command_t g_shellCommand##command = { \ 140 (#command), (descriptor), (callback), (paramCount), {0}, \ 141 } 142 143 /*! 144 * @brief Gets the shell command pointer 145 * 146 * This macro is used to get the shell command pointer. The macro should not be used before the macro 147 * SHELL_COMMAND_DEFINE is used. 148 * 149 * @param command The command string of the command. The double quotes do not need. Such as exit for "exit", 150 * help for "Help", read for "read". 151 */ 152 #define SHELL_COMMAND(command) &g_shellCommand##command 153 154 #if defined(__ICCARM__) 155 _Pragma("diag_default=Pm120") 156 #endif 157 158 /******************************************************************************* 159 * API 160 ******************************************************************************/ 161 162 #if defined(__cplusplus) 163 extern "C" 164 { 165 #endif /* _cplusplus */ 166 167 /*! 168 * @name Shell functional operation 169 * @{ 170 */ 171 172 /*! 173 * @brief Initializes the shell module 174 * 175 * This function must be called before calling all other Shell functions. 176 * Call operation the Shell commands with user-defined settings. 177 * The example below shows how to set up the Shell and 178 * how to call the SHELL_Init function by passing in these parameters. 179 * This is an example. 180 * @code 181 * static SHELL_HANDLE_DEFINE(s_shellHandle); 182 * SHELL_Init((shell_handle_t)s_shellHandle, (serial_handle_t)s_serialHandle, "Test@SHELL>"); 183 * @endcode 184 * @param shellHandle Pointer to point to a memory space of size #SHELL_HANDLE_SIZE allocated by the caller. 185 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 186 * You can define the handle in the following two ways: 187 * #SHELL_HANDLE_DEFINE(shellHandle); 188 * or 189 * uint32_t shellHandle[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]; 190 * @param serialHandle The serial manager module handle pointer. 191 * @param prompt The string prompt pointer of Shell. Only the global variable can be passed. 192 * @retval kStatus_SHELL_Success The shell initialization succeed. 193 * @retval kStatus_SHELL_Error An error occurred when the shell is initialized. 194 * @retval kStatus_SHELL_OpenWriteHandleFailed Open the write handle failed. 195 * @retval kStatus_SHELL_OpenReadHandleFailed Open the read handle failed. 196 */ 197 shell_status_t SHELL_Init(shell_handle_t shellHandle, serial_handle_t serialHandle, char *prompt); 198 199 /*! 200 * @brief Registers the shell command 201 * 202 * This function is used to register the shell command by using the command configuration shell_command_config_t. 203 * This is a example, 204 * @code 205 * SHELL_COMMAND_DEFINE(exit, "\r\n\"exit\": Exit program\r\n", SHELL_ExitCommand, 0); 206 * SHELL_RegisterCommand(s_shellHandle, SHELL_COMMAND(exit)); 207 * @endcode 208 * @param shellHandle The shell module handle pointer. 209 * @param shellCommand The command element. 210 * @retval kStatus_SHELL_Success Successfully register the command. 211 * @retval kStatus_SHELL_Error An error occurred. 212 */ 213 shell_status_t SHELL_RegisterCommand(shell_handle_t shellHandle, shell_command_t * shellCommand); 214 215 /*! 216 * @brief Unregisters the shell command 217 * 218 * This function is used to unregister the shell command. 219 * 220 * @param shellCommand The command element. 221 * @retval kStatus_SHELL_Success Successfully unregister the command. 222 */ 223 shell_status_t SHELL_UnregisterCommand(shell_command_t * shellCommand); 224 225 /*! 226 * @brief Sends data to the shell output stream. 227 * 228 * This function is used to send data to the shell output stream. 229 * 230 * @param shellHandle The shell module handle pointer. 231 * @param buffer Start address of the data to write. 232 * @param length Length of the data to write. 233 * @retval kStatus_SHELL_Success Successfully send data. 234 * @retval kStatus_SHELL_Error An error occurred. 235 */ 236 shell_status_t SHELL_Write(shell_handle_t shellHandle, char *buffer, uint32_t length); 237 238 /*! 239 * @brief Writes formatted output to the shell output stream. 240 * 241 * Call this function to write a formatted output to the shell output stream. 242 * 243 * @param shellHandle The shell module handle pointer. 244 * 245 * @param formatString Format string. 246 * @return Returns the number of characters printed or a negative value if an error occurs. 247 */ 248 int SHELL_Printf(shell_handle_t shellHandle, const char *formatString, ...); 249 250 /*! 251 * @brief Change shell prompt. 252 * 253 * Call this function to change shell prompt. 254 * 255 * @param shellHandle The shell module handle pointer. 256 * 257 * @param prompt The string which will be used for command prompt 258 * @return NULL. 259 */ 260 void SHELL_ChangePrompt(shell_handle_t shellHandle, char *prompt); 261 262 /*! 263 * @brief Print shell prompt. 264 * 265 * Call this function to print shell prompt. 266 * 267 * @param shellHandle The shell module handle pointer. 268 * 269 * @return NULL. 270 */ 271 void SHELL_PrintPrompt(shell_handle_t shellHandle); 272 273 /*! 274 * @brief The task function for Shell. 275 * The task function for Shell; The function should be polled by upper layer. 276 * This function does not return until Shell command exit was called. 277 * 278 * @param shellHandle The shell module handle pointer. 279 */ 280 #if !(defined(SHELL_NON_BLOCKING_MODE) && (SHELL_NON_BLOCKING_MODE > 0U)) 281 void SHELL_Task(shell_handle_t shellHandle); 282 #endif 283 284 /* @} */ 285 286 #if defined(__cplusplus) 287 } 288 #endif 289 290 /*! @}*/ 291 292 #endif /* __FSL_SHELL_H__ */ 293
