/* * Copyright (c) 2019 - 2021 Stefan Strobel * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at https://mozilla.org/MPL/2.0/. */ /** * @file shellmatta.h * @brief API definition of the Shellmatta terminal implementation * @author Stefan Strobel */ /** * @addtogroup shellmatta_api Shellmatta API description * @{ */ #ifndef _SHELLMATTA_H_ #define _SHELLMATTA_H_ #include #include /* global defines */ /** * @brief definition of a shellmatta handle */ typedef void* shellmatta_handle_t; /** * @brief definition of shellmatta return codes */ typedef enum { SHELLMATTA_OK = 0u, /**< everything is OK */ SHELLMATTA_ERROR , /**< error occured */ SHELLMATTA_CONTINUE , /**< the function is not over */ SHELLMATTA_USE_FAULT , /**< parameter error - wrong usage */ SHELLMATTA_DUPLICATE , /**< duplicate command */ SHELLMATTA_BUSY /**< command is busy keep calling */ } shellmatta_retCode_t; /** * @brief definition of shellmatta insert mode */ typedef enum { SHELLMATTA_MODE_INSERT = 0u, /**< insert mode */ SHELLMATTA_MODE_OVERWRITE , /**< overwrite mode */ } shellmatta_mode_t; /** * @brief definition of shellmatta optionparser agument type */ typedef enum { SHELLMATTA_OPT_ARG_NONE = 0u, /**< no argument expected */ SHELLMATTA_OPT_ARG_REQUIRED, /**< argument is required */ SHELLMATTA_OPT_ARG_OPTIONAL, /**< argument is optional */ } shellmatta_opt_argtype_t; /** * @brief definition of shellmatta optionparser agument type */ typedef struct { const char *paramLong; /**< long parameter string */ const char paramShort; /**< short parameter char */ shellmatta_opt_argtype_t argtype; /**< argument type expected */ } shellmatta_opt_long_t; /** * @brief definition of shellmatta optionparser structure */ typedef struct { uint32_t argStart; /**< start of the arguments of the command */ uint32_t offset; /**< current offset of the option parser */ uint32_t nextOffset; /**< offset of the next hunk */ uint32_t len; /**< length of the current hunk */ } shellmatta_opt_t; /** * @brief shellmatta command function definition * @param[in] handle pointer to the instance which is calling the cmd * @param[in] arguments argument string called to run this command beginning * with the command itself * @param[in] length length of the argument string */ typedef shellmatta_retCode_t (*shellmatta_cmdFct_t)(const shellmatta_handle_t handle, const char *arguments, uint32_t length); /** * @brief shellmatta write function definition * @param[in] data data to be written to the output * @param[in] length length of the data to be written */ typedef shellmatta_retCode_t (*shellmatta_write_t)(const char* data, uint32_t length); /** * @brief structure of one shellmatta command */ typedef struct shellmatta_cmd { char *cmd; /**< command name */ char *cmdAlias; /**< command alias */ char *helpText; /**< help text to print in "help" command */ char *usageText; /**< usage text - printed on "help cmd" */ shellmatta_cmdFct_t cmdFct; /**< pointer to the cmd callback function */ struct shellmatta_cmd *next; /**< pointer to next command or NULL */ } shellmatta_cmd_t; /** * @brief state enumeration for ymodem receive state machine */ typedef enum { INACTIVE, /* YModem module not initialised */ WAIT_FOR_START, /* waiting for start of header */ RECEIVE_PACKET, /* currently receiving a packet */ } shellmatta_ymodem_state_t; typedef struct { void (*yModemCancelCallback)(void); void (*yModemRecvPacketCallback)(void); void (*ymodemTransmissionCompleteCallback)(void); } shellmatta_ymodem_callbacks_t; #ifdef SHELLMATTA_TRANSPORT_ENABLE /** * @brief definition of shellmatta transport layer states */ typedef enum { SHELLMATTA_TRANSPORT_STATE_WAIT = 0u , /**< wait for start of header */ SHELLMATTA_TRANSPORT_STATE_GET_HEADER , /**< read in header */ SHELLMATTA_TRANSPORT_STATE_GET_PAYLOAD , /**< read in payload */ SHELLMATTA_TRANSPORT_STATE_GET_CRC , /**< read crc and process data */ } shellmatta_transport_state_t; /** @brief max length of a plain data payload */ #define SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH ((uint8_t)(255)) /** * @brief shellmatta transport crc function definition for custom crcs * @param[in] data data to calculate the crc of * @param[in] size size of the data in bytes */ typedef uint32_t (*shellmatta_transport_crc_t)(const char* data, const uint32_t size); /** * @brief structure of one shellmatta transport header */ typedef struct __attribute__((__packed__)) { uint8_t startOfHeader; /** start of header field */ uint8_t protocolVersion; /** protocol version of the packet */ uint8_t packetType; /** type of the packet */ uint8_t payloadLength; /** length of the payload */ uint8_t source; /** source of the packet */ uint8_t destination; /** destination of the packet */ uint8_t sequenceH2S; /** sequence counter host to shellmatta */ uint8_t sequenceS2H; /** sequence counter shellmatta to host */ } shellmatta_transport_header_t; /** * @brief structure of one shellmatta transport packet */ typedef struct __attribute__((__packed__)) { shellmatta_transport_header_t header; /**< header of the packet */ char payload[SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH]; /**< payload of the packet */ uint32_t crc; /**< crc of the packet */ } shellmatta_transport_packet_t; /** * @brief structure of one shellmatta transport layer instance */ typedef struct { shellmatta_transport_state_t state; /**< current state of the transport layer reception */ bool active; /**< is transport layer communication active */ bool disableAutoFlush; /**< enforce manual flushing */ bool mandatory; /**< is the transport layer enforced */ uint8_t sequenceH2S; /**< sequence counter host to shellmatta */ uint8_t sequenceS2H; /**< sequenc counter shellmatta to host */ uint32_t headerIndex; /**< read indey of the header */ uint32_t payloadIndex; /**< read index of the payload */ uint32_t crcIndex; /**< read index of the checmsum */ shellmatta_transport_packet_t inPacket; /**< buffer for the received packets */ shellmatta_transport_packet_t outPacket; /**< buffer for the sent packets */ shellmatta_write_t writeFct; /**< shellmatta write function */ shellmatta_transport_crc_t customCrcFct; /**< use this function to calculate crcs */ } shellmatta_transport_layer_t; #endif /** * @brief structure of one shellmatta instance */ typedef struct { uint32_t magic; /**< magic number to check if initialized */ char *buffer; /**< input buffer */ uint32_t bufferSize; /**< size of the input buffer */ uint32_t inputCount; /**< offset of the current write operation */ uint32_t byteCounter; /**< counter used to loop over input data */ uint32_t lastNewlineIdx; /**< index of the lest newline */ uint32_t cursor; /**< offset where the cursor is at */ uint32_t stdinIdx; /**< start index of stdin in buffer */ uint32_t stdinLength; /**< length of the stdin data */ char *historyBuffer; /**< buffer to store the last commands */ uint32_t historyBufferSize; /**< size of the history buffer */ uint32_t historyStart; /**< index of the oldest stored command */ uint32_t historyEnd; /**< index of the newest stored command */ uint32_t historyRead; /**< index of the current search */ bool historyReadUp; /**< flag to show the last history dir */ uint32_t tabCounter; /**< counts the tabulator key presses */ uint32_t escapeCounter; /**< counts the characters of an escape seq */ char escapeChars[4u]; /**< buffer to save the escape characters */ uint32_t hereStartIdx; /**< heredoc start of "<<" */ uint32_t hereDelimiterIdx; /**< heredoc delimiter index in input */ uint32_t hereLength; /**< length of the heredoc delimiter */ bool echoEnabled; /**< if true the input is printed */ bool dirty; /**< dirty flag to show changes */ const char *prompt; /**< prompt is printed after every command */ char delimiter; /**< delimiter (return) to terminate a cmd */ shellmatta_mode_t mode; /**< mode of the shell */ shellmatta_write_t write; /**< pointer to write function */ shellmatta_cmd_t helpCmd; /**< help command structure */ shellmatta_cmd_t *cmdList; /**< pointer to the first command */ shellmatta_cmd_t *continuousCmd; /**< command to be called continuously */ shellmatta_cmd_t *busyCmd; /**< command to be polled (busy mode) */ bool cmdListIsConst; /**< true if the #cmdList was passed during initialization */ shellmatta_opt_t optionParser; /**< option parser sructure */ shellmatta_ymodem_state_t ymodemState; /**< current state of the ymodem module */ #ifdef SHELLMATTA_TRANSPORT_ENABLE bool transportEnabled; /**< if true the transport layer is enabled */ uint32_t transportBusyMark; /**< transport processing position during busy cmd execution */ shellmatta_transport_layer_t transportLayer; /**< transport layer instance */ #endif } shellmatta_instance_t; /** * @brief helper macro for the send function */ #ifdef SHELLMATTA_TRANSPORT_ENABLE #define SHELLMATTA_WRITE(data, length) inst->transportLayer.active == true ? \ shellmatta_transport_write((shellmatta_transport_layer_t*)&inst->transportLayer, (data), (length)) : \ inst->write((data), (length)) #else #define SHELLMATTA_WRITE(data, length) inst->write((data), (length)) #endif shellmatta_retCode_t shellmatta_doInit( shellmatta_instance_t *inst, shellmatta_handle_t *handle, char *buffer, uint32_t bufferSize, char *historyBuffer, uint32_t historyBufferSize, const char *prompt, const shellmatta_cmd_t *cmdList, shellmatta_write_t writeFct); shellmatta_retCode_t shellmatta_resetShell( shellmatta_handle_t handle, bool printPrompt); shellmatta_retCode_t shellmatta_addCmd( shellmatta_handle_t handle, shellmatta_cmd_t *cmd); shellmatta_retCode_t shellmatta_removeCmd( shellmatta_handle_t handle, shellmatta_cmd_t *cmd); shellmatta_retCode_t shellmatta_configure( shellmatta_handle_t handle, shellmatta_mode_t mode, bool echoEnabled, char delimiter); shellmatta_retCode_t shellmatta_processData(shellmatta_handle_t handle, char *data, uint32_t size); shellmatta_retCode_t shellmatta_write( shellmatta_handle_t handle, char *data, uint32_t length); shellmatta_retCode_t shellmatta_read( shellmatta_handle_t handle, char **data, uint32_t *length); shellmatta_retCode_t shellmatta_opt( shellmatta_handle_t handle, const char *optionString, char *option, char **argument, uint32_t *argLen); shellmatta_retCode_t shellmatta_opt_long( shellmatta_handle_t handle, const shellmatta_opt_long_t *longOptions, char *option, char **argument, uint32_t *argLen); #ifdef SHELLMATTA_TRANSPORT_ENABLE shellmatta_retCode_t shellmatta_transport_configure(shellmatta_handle_t handle, bool mandatory, bool disableAutoFlush, shellmatta_transport_crc_t customCrcFct); shellmatta_retCode_t shellmatta_transport_reset(shellmatta_handle_t handle); shellmatta_retCode_t shellmatta_transport_flush(shellmatta_handle_t handle); #endif #ifndef SHELLMATTA_STRIP_PRINTF shellmatta_retCode_t shellmatta_printf( shellmatta_handle_t handle, const char *fmt, ...); #endif uint8_t shellmatta_ymodem( shellmatta_handle_t handle, uint8_t* buffer, uint32_t* fileSize, uint16_t* packetSize, shellmatta_ymodem_callbacks_t callbacks); void shellmatta_ymodem_end( shellmatta_handle_t handle, bool doCancel); #endif /** @} */