339 lines
12 KiB
C
339 lines
12 KiB
C
/*
|
|
* Copyright (c) 2015, Freescale Semiconductor, Inc.
|
|
* Copyright 2016-2022 NXP
|
|
* All rights reserved.
|
|
*
|
|
* SPDX-License-Identifier: BSD-3-Clause
|
|
*/
|
|
|
|
#ifndef __FSL_SHELL_H__
|
|
#define __FSL_SHELL_H__
|
|
|
|
/*!
|
|
* @addtogroup SHELL
|
|
* @{
|
|
*/
|
|
|
|
#include "fsl_common.h"
|
|
#include "fsl_component_serial_manager.h"
|
|
#include "fsl_component_generic_list.h"
|
|
|
|
/*******************************************************************************
|
|
* Definitions
|
|
******************************************************************************/
|
|
|
|
/*! @brief Whether use non-blocking mode. */
|
|
#ifndef SHELL_NON_BLOCKING_MODE
|
|
#define SHELL_NON_BLOCKING_MODE SERIAL_MANAGER_NON_BLOCKING_MODE
|
|
#endif
|
|
|
|
/*! @brief Macro to set on/off auto-complete feature. */
|
|
#define SHELL_AUTO_COMPLETE (1U)
|
|
|
|
/*! @brief Macro to set console buffer size. */
|
|
#ifndef SHELL_BUFFER_SIZE
|
|
#define SHELL_BUFFER_SIZE (64U)
|
|
#endif
|
|
|
|
/*! @brief Macro to set maximum arguments in command. */
|
|
#define SHELL_MAX_ARGS (8U)
|
|
|
|
/*! @brief Macro to set maximum count of history commands. */
|
|
#ifndef SHELL_HISTORY_COUNT
|
|
#define SHELL_HISTORY_COUNT (3U)
|
|
#endif
|
|
|
|
/*! @brief Macro to bypass arguments check */
|
|
#define SHELL_IGNORE_PARAMETER_COUNT (0xFF)
|
|
|
|
/*! @brief The handle size of the shell module. It is the sum of the SHELL_HISTORY_COUNT * SHELL_BUFFER_SIZE +
|
|
* SHELL_BUFFER_SIZE + SERIAL_MANAGER_READ_HANDLE_SIZE + SERIAL_MANAGER_WRITE_HANDLE_SIZE*/
|
|
#define SHELL_HANDLE_SIZE \
|
|
(160U + SHELL_HISTORY_COUNT * SHELL_BUFFER_SIZE + SHELL_BUFFER_SIZE + SERIAL_MANAGER_READ_HANDLE_SIZE + \
|
|
SERIAL_MANAGER_WRITE_HANDLE_SIZE)
|
|
|
|
/*! @brief Macro to determine whether use common task. */
|
|
#ifndef SHELL_USE_COMMON_TASK
|
|
#define SHELL_USE_COMMON_TASK (0U)
|
|
#endif
|
|
|
|
/*! @brief Macro to set shell task priority. */
|
|
#ifndef SHELL_TASK_PRIORITY
|
|
#define SHELL_TASK_PRIORITY (2U)
|
|
#endif
|
|
|
|
/*! @brief Macro to set shell task stack size. */
|
|
#ifndef SHELL_TASK_STACK_SIZE
|
|
#define SHELL_TASK_STACK_SIZE (1000U)
|
|
#endif
|
|
|
|
/*! @brief Shell status */
|
|
typedef enum _shell_status
|
|
{
|
|
kStatus_SHELL_Success = kStatus_Success, /*!< Success */
|
|
kStatus_SHELL_Error = MAKE_STATUS(kStatusGroup_SHELL, 1), /*!< Failed */
|
|
kStatus_SHELL_OpenWriteHandleFailed = MAKE_STATUS(kStatusGroup_SHELL, 2), /*!< Open write handle failed */
|
|
kStatus_SHELL_OpenReadHandleFailed = MAKE_STATUS(kStatusGroup_SHELL, 3), /*!< Open read handle failed */
|
|
kStatus_SHELL_RetUsage = MAKE_STATUS(kStatusGroup_SHELL, 4), /*!< RetUsage for print cmd usage */
|
|
} shell_status_t;
|
|
|
|
/*! @brief The handle of the shell module */
|
|
typedef void *shell_handle_t;
|
|
|
|
/*! @brief User command function prototype. */
|
|
typedef shell_status_t (*cmd_function_t)(shell_handle_t shellHandle, int32_t argc, char **argv);
|
|
|
|
/*! @brief User command data configuration structure. */
|
|
typedef struct _shell_command
|
|
{
|
|
const char *pcCommand; /*!< The command that is executed. For example "help". It must be all lower case. */
|
|
char *pcHelpString; /*!< String that describes how to use the command. It should start with the command itself,
|
|
and end with "\r\n". For example "help: Returns a list of all the commands\r\n". */
|
|
const cmd_function_t
|
|
pFuncCallBack; /*!< A pointer to the callback function that returns the output generated by the command. */
|
|
uint8_t cExpectedNumberOfParameters; /*!< Commands expect a fixed number of parameters, which may be zero. */
|
|
list_element_t link; /*!< link of the element */
|
|
} shell_command_t;
|
|
|
|
/*!
|
|
* @brief Defines the shell handle
|
|
*
|
|
* This macro is used to define a 4 byte aligned shell handle.
|
|
* Then use "(shell_handle_t)name" to get the shell handle.
|
|
*
|
|
* The macro should be global and could be optional. You could also define shell handle by yourself.
|
|
*
|
|
* This is an example,
|
|
* @code
|
|
* SHELL_HANDLE_DEFINE(shellHandle);
|
|
* @endcode
|
|
*
|
|
* @param name The name string of the shell handle.
|
|
*/
|
|
#define SHELL_HANDLE_DEFINE(name) uint32_t name[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
|
|
|
|
#if defined(__ICCARM__)
|
|
/* disable misra 19.13 */
|
|
_Pragma("diag_suppress=Pm120")
|
|
#endif
|
|
/*!
|
|
* @brief Defines the shell command structure
|
|
*
|
|
* This macro is used to define the shell command structure #shell_command_t.
|
|
* And then uses the macro SHELL_COMMAND to get the command structure pointer.
|
|
* The macro should not be used in any function.
|
|
*
|
|
* This is a example,
|
|
* @code
|
|
* SHELL_COMMAND_DEFINE(exit, "\r\n\"exit\": Exit program\r\n", SHELL_ExitCommand, 0);
|
|
* SHELL_RegisterCommand(s_shellHandle, SHELL_COMMAND(exit));
|
|
* @endcode
|
|
*
|
|
* @param command The command string of the command. The double quotes do not need. Such as exit for "exit",
|
|
* help for "Help", read for "read".
|
|
* @param descriptor The description of the command is used for showing the command usage when "help" is typing.
|
|
* @param callback The callback of the command is used to handle the command line when the input command is matched.
|
|
* @param paramCount The max parameter count of the current command.
|
|
*/
|
|
#define SHELL_COMMAND_DEFINE(command, descriptor, callback, paramCount) \
|
|
\
|
|
shell_command_t g_shellCommand##command = { \
|
|
(#command), (descriptor), (callback), (paramCount), {0}, \
|
|
}
|
|
|
|
/*!
|
|
* @brief Gets the shell command pointer
|
|
*
|
|
* This macro is used to get the shell command pointer. The macro should not be used before the macro
|
|
* SHELL_COMMAND_DEFINE is used.
|
|
*
|
|
* @param command The command string of the command. The double quotes do not need. Such as exit for "exit",
|
|
* help for "Help", read for "read".
|
|
*/
|
|
#define SHELL_COMMAND(command) &g_shellCommand##command
|
|
|
|
#if defined(__ICCARM__)
|
|
_Pragma("diag_default=Pm120")
|
|
#endif
|
|
|
|
/*******************************************************************************
|
|
* API
|
|
******************************************************************************/
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C"
|
|
{
|
|
#endif /* _cplusplus */
|
|
|
|
/*!
|
|
* @name Shell functional operation
|
|
* @{
|
|
*/
|
|
|
|
/*!
|
|
* @brief Initializes the shell module
|
|
*
|
|
* This function must be called before calling all other Shell functions.
|
|
* Call operation the Shell commands with user-defined settings.
|
|
* The example below shows how to set up the Shell and
|
|
* how to call the SHELL_Init function by passing in these parameters.
|
|
* This is an example.
|
|
* @code
|
|
* static SHELL_HANDLE_DEFINE(s_shellHandle);
|
|
* SHELL_Init((shell_handle_t)s_shellHandle, (serial_handle_t)s_serialHandle, "Test@SHELL>");
|
|
* @endcode
|
|
* @param shellHandle Pointer to point to a memory space of size #SHELL_HANDLE_SIZE allocated by the caller.
|
|
* The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices.
|
|
* You can define the handle in the following two ways:
|
|
* #SHELL_HANDLE_DEFINE(shellHandle);
|
|
* or
|
|
* uint32_t shellHandle[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
|
|
* @param serialHandle The serial manager module handle pointer.
|
|
* @param prompt The string prompt pointer of Shell. Only the global variable can be passed.
|
|
* @retval kStatus_SHELL_Success The shell initialization succeed.
|
|
* @retval kStatus_SHELL_Error An error occurred when the shell is initialized.
|
|
* @retval kStatus_SHELL_OpenWriteHandleFailed Open the write handle failed.
|
|
* @retval kStatus_SHELL_OpenReadHandleFailed Open the read handle failed.
|
|
*/
|
|
shell_status_t SHELL_Init(shell_handle_t shellHandle, serial_handle_t serialHandle, char *prompt);
|
|
|
|
/*!
|
|
* @brief Registers the shell command
|
|
*
|
|
* This function is used to register the shell command by using the command configuration shell_command_config_t.
|
|
* This is a example,
|
|
* @code
|
|
* SHELL_COMMAND_DEFINE(exit, "\r\n\"exit\": Exit program\r\n", SHELL_ExitCommand, 0);
|
|
* SHELL_RegisterCommand(s_shellHandle, SHELL_COMMAND(exit));
|
|
* @endcode
|
|
* @param shellHandle The shell module handle pointer.
|
|
* @param shellCommand The command element.
|
|
* @retval kStatus_SHELL_Success Successfully register the command.
|
|
* @retval kStatus_SHELL_Error An error occurred.
|
|
*/
|
|
shell_status_t SHELL_RegisterCommand(shell_handle_t shellHandle, shell_command_t * shellCommand);
|
|
|
|
/*!
|
|
* @brief Unregisters the shell command
|
|
*
|
|
* This function is used to unregister the shell command.
|
|
*
|
|
* @param shellCommand The command element.
|
|
* @retval kStatus_SHELL_Success Successfully unregister the command.
|
|
*/
|
|
shell_status_t SHELL_UnregisterCommand(shell_command_t * shellCommand);
|
|
|
|
/*!
|
|
* @brief Sends data to the shell output stream.
|
|
*
|
|
* This function is used to send data to the shell output stream.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
* @param buffer Start address of the data to write.
|
|
* @param length Length of the data to write.
|
|
* @retval kStatus_SHELL_Success Successfully send data.
|
|
* @retval kStatus_SHELL_Error An error occurred.
|
|
*/
|
|
shell_status_t SHELL_Write(shell_handle_t shellHandle, const char *buffer, uint32_t length);
|
|
|
|
/*!
|
|
* @brief Writes formatted output to the shell output stream.
|
|
*
|
|
* Call this function to write a formatted output to the shell output stream.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
*
|
|
* @param formatString Format string.
|
|
* @return Returns the number of characters printed or a negative value if an error occurs.
|
|
*/
|
|
int SHELL_Printf(shell_handle_t shellHandle, const char *formatString, ...);
|
|
/*!
|
|
* @brief Sends data to the shell output stream with OS synchronization.
|
|
*
|
|
* This function is used to send data to the shell output stream with OS synchronization, note the function could
|
|
* not be called in ISR.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
* @param buffer Start address of the data to write.
|
|
* @param length Length of the data to write.
|
|
* @retval kStatus_SHELL_Success Successfully send data.
|
|
* @retval kStatus_SHELL_Error An error occurred.
|
|
*/
|
|
shell_status_t SHELL_WriteSynchronization(shell_handle_t shellHandle, const char *buffer, uint32_t length);
|
|
|
|
/*!
|
|
* @brief Writes formatted output to the shell output stream with OS synchronization.
|
|
*
|
|
* Call this function to write a formatted output to the shell output stream with OS synchronization, note the
|
|
* function could not be called in ISR.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
*
|
|
* @param formatString Format string.
|
|
* @return Returns the number of characters printed or a negative value if an error occurs.
|
|
*/
|
|
int SHELL_PrintfSynchronization(shell_handle_t shellHandle, const char *formatString, ...);
|
|
/*!
|
|
* @brief Change shell prompt.
|
|
*
|
|
* Call this function to change shell prompt.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
*
|
|
* @param prompt The string which will be used for command prompt
|
|
* @return NULL.
|
|
*/
|
|
void SHELL_ChangePrompt(shell_handle_t shellHandle, char *prompt);
|
|
|
|
/*!
|
|
* @brief Print shell prompt.
|
|
*
|
|
* Call this function to print shell prompt.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
*
|
|
* @return NULL.
|
|
*/
|
|
void SHELL_PrintPrompt(shell_handle_t shellHandle);
|
|
|
|
/*!
|
|
* @brief The task function for Shell.
|
|
* The task function for Shell; The function should be polled by upper layer.
|
|
* This function does not return until Shell command exit was called.
|
|
*
|
|
* @param shellHandle The shell module handle pointer.
|
|
*/
|
|
#if !(defined(SHELL_NON_BLOCKING_MODE) && (SHELL_NON_BLOCKING_MODE > 0U))
|
|
void SHELL_Task(shell_handle_t shellHandle);
|
|
#endif
|
|
|
|
/*!
|
|
* @brief Check if code is running in ISR.
|
|
*
|
|
* This function is used to check if code running in ISR.
|
|
*
|
|
* @retval TRUE if code runing in ISR.
|
|
*/
|
|
static inline bool SHELL_checkRunningInIsr(void)
|
|
{
|
|
#if (defined(__DSC__) && defined(__CW__))
|
|
return !(isIRQAllowed());
|
|
#elif defined(__GIC_PRIO_BITS)
|
|
return (0x13 == (__get_CPSR() & CPSR_M_Msk));
|
|
#elif defined(__get_IPSR)
|
|
return (0U != __get_IPSR());
|
|
#else
|
|
return false;
|
|
#endif
|
|
}
|
|
|
|
/* @} */
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
/*! @}*/
|
|
|
|
#endif /* __FSL_SHELL_H__ */
|