1 /* 2 * FreeRTOS V202212.00 3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy of 6 * this software and associated documentation files (the "Software"), to deal in 7 * the Software without restriction, including without limitation the rights to 8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 * the Software, and to permit persons to whom the Software is furnished to do so, 10 * subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included in all 13 * copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 * 22 * https://www.FreeRTOS.org 23 * https://github.com/FreeRTOS 24 * 25 */ 26 27 #ifndef COMMAND_INTERPRETER_H 28 #define COMMAND_INTERPRETER_H 29 30 /* *INDENT-OFF* */ 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 /* *INDENT-ON* */ 35 36 /* The prototype to which callback functions used to process command line 37 * commands must comply. pcWriteBuffer is a buffer into which the output from 38 * executing the command can be written, xWriteBufferLen is the length, in bytes of 39 * the pcWriteBuffer buffer, and pcCommandString is the entire string as input by 40 * the user (from which parameters can be extracted).*/ 41 typedef BaseType_t (* pdCOMMAND_LINE_CALLBACK)( char * pcWriteBuffer, 42 size_t xWriteBufferLen, 43 const char * pcCommandString ); 44 45 /* The structure that defines command line commands. A command line command 46 * should be defined by declaring a const structure of this type. */ 47 typedef struct xCOMMAND_LINE_INPUT 48 { 49 const char * const pcCommand; /* The command that causes pxCommandInterpreter to be executed. For example "help". Must be all lower case. */ 50 const char * const pcHelpString; /* String that describes how to use the command. Should start with the command itself, and end with "\r\n". For example "help: Returns a list of all the commands\r\n". */ 51 const pdCOMMAND_LINE_CALLBACK pxCommandInterpreter; /* A pointer to the callback function that will return the output generated by the command. */ 52 int8_t cExpectedNumberOfParameters; /* Commands expect a fixed number of parameters, which may be zero. */ 53 } CLI_Command_Definition_t; 54 55 /* The structure that defines a command line list entry. */ 56 typedef struct xCOMMAND_INPUT_LIST 57 { 58 const CLI_Command_Definition_t * pxCommandLineDefinition; 59 struct xCOMMAND_INPUT_LIST * pxNext; 60 } CLI_Definition_List_Item_t; 61 62 /* For backward compatibility. */ 63 #define xCommandLineInput CLI_Command_Definition_t 64 65 /* 66 * Register the command passed in using the pxCommandToRegister parameter. 67 * Registering a command adds the command to the list of commands that are 68 * handled by the command interpreter. Once a command has been registered it 69 * can be executed from the command line. 70 */ 71 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) 72 BaseType_t FreeRTOS_CLIRegisterCommand( const CLI_Command_Definition_t * const pxCommandToRegister ); 73 #endif 74 75 /* 76 * Static version of the above function which allows the application writer 77 * to supply the memory used for a command line list entry. 78 */ 79 #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) 80 BaseType_t FreeRTOS_CLIRegisterCommandStatic( const CLI_Command_Definition_t * const pxCommandToRegister, 81 CLI_Definition_List_Item_t * pxCliDefinitionListItemBuffer ); 82 #endif 83 84 /* 85 * Runs the command interpreter for the command string "pcCommandInput". Any 86 * output generated by running the command will be placed into pcWriteBuffer. 87 * xWriteBufferLen must indicate the size, in bytes, of the buffer pointed to 88 * by pcWriteBuffer. 89 * 90 * FreeRTOS_CLIProcessCommand should be called repeatedly until it returns pdFALSE. 91 * 92 * pcCmdIntProcessCommand is not reentrant. It must not be called from more 93 * than one task - or at least - by more than one task at a time. 94 */ 95 BaseType_t FreeRTOS_CLIProcessCommand( const char * const pcCommandInput, 96 char * pcWriteBuffer, 97 size_t xWriteBufferLen ); 98 99 /*-----------------------------------------------------------*/ 100 101 /* 102 * A buffer into which command outputs can be written is declared in the 103 * main command interpreter, rather than in the command console implementation, 104 * to allow application that provide access to the command console via multiple 105 * interfaces to share a buffer, and therefore save RAM. Note, however, that 106 * the command interpreter itself is not re-entrant, so only one command 107 * console interface can be used at any one time. For that reason, no attempt 108 * is made to provide any mutual exclusion mechanism on the output buffer. 109 * 110 * FreeRTOS_CLIGetOutputBuffer() returns the address of the output buffer. 111 */ 112 char * FreeRTOS_CLIGetOutputBuffer( void ); 113 114 /* 115 * Return a pointer to the xParameterNumber'th word in pcCommandString. 116 */ 117 const char * FreeRTOS_CLIGetParameter( const char * pcCommandString, 118 UBaseType_t uxWantedParameter, 119 BaseType_t * pxParameterStringLength ); 120 121 /* *INDENT-OFF* */ 122 #ifdef __cplusplus 123 } 124 #endif 125 /* *INDENT-ON* */ 126 127 #endif /* COMMAND_INTERPRETER_H */ 128