first commit

This commit is contained in:
fewikay committed 2026-10-16 13:08:06 +02:00
commit 92cbe97616
1978 files changed
+1688498

No files matched your search

@@ -0,0 +1,266 @@
/*
* Console.h
*
* Created on: Dec 8, 2024
* Author: Thorsten
*/
/*! \file */
#ifndef INC_CONSOLE_CONSOLE_H_
#define INC_CONSOLE_CONSOLE_H_
/*!
* The ConsoleHandle_t handle is an instance pointer of the console library which is generated whenever
* the CONSOLE_CreateInstance function returns with success.
*/
typedef struct ConsoleHandle* ConsoleHandle_t;
/*!
* The CONSOLE_CommandFunc function pointer type is used to describe the arguments which are passed by the
* console processor toi the registered console function. The user gets the classical argc and argv arguments
* which are known well from a standard main in nearly any programming language. There is an additional
* context pointer, which optionally holds additional information. The pointer to this information is passed
* with the registration of the command by the user and can not be changed anymore at runtime
*
* The return value of a console function is always zero on success or any non zero number when an error occured.
* The standard is more or less a non zero number which is smaller than 0.
*/
typedef int (*CONSOLE_CommandFunc)(int argc, char** argv, void* context);
/*!
* ConsoleReadStream_t should return -1 on failure, or else the number of bytes
* read (0 on EOF). It is similar to syscall <<read>>, except that <int> rather
* than <size_t> bounds a transaction size, and <[context]> will be passed
* as the first argument.
*/
typedef int (*ConsoleReadStream_t)(void* pContext, char* pBuffer, int num);
/*!
* ConsoleWriteStream_t should return -1 on failure, or else the number of bytes
* written. It is similar to <<write>>, except that <int> rather than
* <size_t> bounds a transaction size, and <[cookie]> will be passed as
* the first argument.
*/
typedef int (*ConsoleWriteStream_t)(void* pContext, const char* pBuffer, int num);
/*!
* The CONSOLE_CreateInstance function is used to create the console processor. There is no singleton pattern implemented
* for the console but as there is no stream abstraction for the console processor, it only makes sense to have one instance
* at runtime!
*
* The return value of a console function is a null pointer in case an error occured or a pointer of type ConsoleHandle_t.
*
* @param uxStackDepth is the stack depth of the console processor thread in words
* @param xPrio is the console processor priority. This should always be on a low level because the stdlib function
* may not block and so the processor always runs whenever it can. In case the reception of the newlib is blocking and
* interrupt based, the priority could be higher!
*/
ConsoleHandle_t CONSOLE_CreateInstance( unsigned int uxStackDepth, int xPrio );
/*!
* The CONSOLE_DestroyInstance function is used to cleanup all used ressources which then stops the console processor.
* This leads to the case that no console functionallity is provided in the design anymore
*/
void CONSOLE_DestroyInstance( ConsoleHandle_t h );
/*!
* The CONSOLE_RegisterCommand function is used to register custom commands which can be called by the console processor
* when the user enters the given command string. The arguments and an additional context pointer are passed by the console
* processor to the function as well.
*
* @param h is of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
* @param cmd is of type char* which is the case sensitive name of the command
* @param help is of type char* which is the help text or description of the command when the user types help
* @param func is of type CONSOLE_CommandFunc which is the function pointer to the command
* @param context is of type void* which is an optional data pointer which is passed to the function when called
*/
int CONSOLE_RegisterCommand( ConsoleHandle_t h, char* cmd, char* help, CONSOLE_CommandFunc func, void* context );
/*!
* The CONSOLE_RegisterExitCallback function is used to get notified after the primary console task
* has stopped execution. This can be used to finally clean up ressources and to restart or reset the runtime
* or to set up a new instance of the console processor.
*
* @param h is of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
* @param clb is a function pointer which is the prototype of the callback function
* @param priv is private data forwarded to the callback
*/
void CONSOLE_RegisterExitCallback(ConsoleHandle_t h, void (*clb)(ConsoleHandle_t h, void*, int), void* priv);
/*!
* The CONSOLE_ExecCommand function is used to call custom commands asynchronously from the current input stream.
* The command is feed by a queue into the console processor and is consumed whenever the input buffer is empty
*
* @param h is of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
* @param cmd is of type char* which is the command string to execute
*/
int CONSOLE_ExecCommand( ConsoleHandle_t h, char* cmd );
/*!
* The CONSOLE_RegisterAlias function is used to register custom commands which can be mapped to other commands
* when the user enters the given alias command string. Arguments will not be passed from an alias command to
* the mapped command, so the alias should be specified with the required commands accordingly
*
* @param h is of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
* @param cmd is of type char* which is the case sensitive name of the alias command
* @param aliasCmd is of type char* which is the mapped command and its args and is visible when the user types help
*/
int CONSOLE_RegisterAlias( ConsoleHandle_t h, char* cmd, char* aliasCmd );
/*!
* The CONSOLE_RemoveAliasOrCommand function is used to remove custom commands or alias entries which are mapped
* in the console processor.
*
* @param h is of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
* @param cmd is of type char* which is the case sensitive name of the alias or command
*/
int CONSOLE_RemoveAliasOrCommand( ConsoleHandle_t h, char* cmd);
/*!
* The CONSOLE_RedirectStreams function is used to change stdin or stdout as default
* streams for the console functions. In case one or both stream function pointers are
* NULL, it will be set back to stdin respectively stdout. In case of an error, the
* last stream configuration is kept and -1 is returned, otherwise 0
*
* @param h is of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
* @param rdFunc is of type ConsoleReadStream_t which is the new stream read function for the command processor
* @param wrFunc is of type ConsoleWriteStream_t which is the new stream write function for the command processor
*
* NOTE it might be that not on all platforms it is possible to use this function, it then returns -2 if it is
* not implemented properly. So far only newlib stdlib is supported!
*/
int CONSOLE_RedirectStreams( ConsoleHandle_t h, ConsoleReadStream_t rdFunc, ConsoleWriteStream_t wrFunc,
void* rdContext, void* wrContext );
/*!
* \mainpage FreeRTOS Console Library
* \section intro_sec Introduction
*
* The following code documentation is a set of tipps and diagramms as well as function and structure descriptions
* which help when using the library. It is used to increase the implementation speed. Some examples are attached
* in this documentation as well
*
* \section static_sec static compile flags of the library
*
* CONSOLE_USERNAME: The username in the console which is printed at least on power up before changing the username<br>
* CONSOLE_USE_DYNAMIC_USERNAME: The username can be changed on runtime which is enabled with this DEFINE<br>
* CONSOLE_LINE_HISTORY: specifies the maximum number of entries of the "last commands" buffer <br>
* CONSOLE_LINE_SIZE: Specifies the number of chars per line. When exceeding this number without a newline,<br>
* the console prints a buffer overflow and clears the input. All inputs are then invalidated within<br>
* this line<br>
* CONSOLE_COMMAND_MAX_LENGTH: Specifies the maximum number of chars per command<br>
* CONSOLE_HELP_MAX_LENGTH: Specifies the maximum number of chars per command help text<br>
*
* \section state_example Examples
* The following example shows how to create a instance of the console library
* and how to attach a function for console usage. This is called registering a command
*
* \code
*
* static int CapabilityFunc( int argc, char** argv, void* ctx )
* {
* printf("%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d,%d\r\nOK",
* 1, // has spindle
* 1, // has spindle status
* 1, // has stepper
* 1, // has stepper move relative
* 1, // has stepper move speed
* 1, // has stepper move async
* 1, // has stepper status
* 1, // has stepper refrun
* 1, // has stepper refrun timeout
* 1, // has stepper refrun skip
* 1, // has stepper refrun stay enabled
* 1, // has stepper reset
* 1, // has stepper position
* 1, // has stepper config
* 1, // has stepper config torque
* 1, // has stepper config throvercurr
* 1, // has stepper config powerena
* 1, // has stepper config stepmode
* 1, // has stepper config timeoff
* 1, // has stepper config timeon
* 1, // has stepper config timefast
* 1, // has stepper config mmperturn
* 1, // has stepper config posmax
* 1, // has stepper config posmin
* 1, // has stepper config posref
* 1, // has stepper config stepsperturn
* 1 // has stepper cancel
* );
* return 0;
* }
*
* ...
*
* // create the console processor. There are no additional arguments required because it uses stdin, stderr and
* // stdout of the stdlib of the platform
* ConsoleHandle_t c = CONSOLE_CreateInstance( 4*configMINIMAL_STACK_SIZE, configMAX_PRIORITIES - 5 );
*
* // register the function, there is always a help text required, an empty string or null is not allowed!
* CONSOLE_RegisterCommand(c, "capability", "prints a specified string of capability bits",
* CapabilityFunc, NULL);
*
* ...
*
* \endcode
*
* The following example shows a really simple console function and how
* it is used to work with the console and arguments passed by the user
*
* \code
*
* static int ConsoleFunction( int argc, char** argv, void* ctx )
* {
* //possible commands are
* //(command) start
* //(command) stop
*
* // first decode the subcommand and all arguments
* if ( argc == 0 )
* {
* printf("invalid number of arguments\r\nFAIL");
* return -1;
* }
* if ( strcmp(argv[0], "stop") == 0 )
* {
* // do something
* }
* else if ( strcmp(argv[0], "start") == 0 )
* {
* // do something else
* }
* else
* {
* printf("invalid subcommand was given as argument\r\nFAIL");
* }
* }
*
* \endcode
*/
/*!
* \page lib_port_page Library porting
* \section intro_sec Introduction
*
* The library is written with a minimum set of compiler dependencies to make it portable on most toolchains
* and most compilers which are able to compile C. There are no GCC attributes or MSVC pragmas included in the code
* furthermore there are no weak functions or other non ISO-C language keywords which are not parsable from
* all compilers. To include the library in a project, the following page helps to do the job and can be used as
* a step by step quick porting guide.
*
* \section step_by_step_sec required steps to include the library
* -# include all include paths of the library folder (inc-folder) to your project or copy them into your project as needed
* -# link all C files (src-folder) to your project or copy them to your project as needed
* -# adapt your makefile in case you have one. When using eclipse project this is not required
* -# copy the template header ConsoleConfig.h file to your project or create your own and adapt the compile time @parameters as needed.
* -# compile the source code once to make sure everything builds without issues and your include paths are correct.
* -# make sure FreeRTOS is implemented properly and compiles with the defualt include paths.
* -# no error should be returned after the call of CONSOLE_CreateInstance. Porting is done.
*/
#endif /* INC_CONSOLE_CONSOLE_H_ */