rt-thread-official/bsp/imxrt/libraries/MIMXRT1170/MIMXRT1176/utilities/fsl_shell.h

338 lines
12 KiB
C

/*
* Copyright (c) 2015, Freescale Semiconductor, Inc.
* Copyright 2016-2020 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 */
} 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__ */