/* * 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 definition of shellmatta transport layer states */ typedef enum { STATE_GET_SOH =0u, /**< start of header state of transport layer */ STATE_MANUAL_INPUT , /**< state for manual input => transport layer disabled */ STATE_GET_PROTOCOL_VERSION , /**< protocol version state of transport layer */ STATE_GET_PACKET_TYPE , /**< packet type state of transport layer */ STATE_GET_PAYLOAD_LENGTH , /**< payload length state of transport layer */ STATE_GET_SOURCE , /**< source state of transport layer */ STATE_GET_DESTINATION , /**< destination state of transport layer */ STATE_GET_H2S_SEQUENCE_CNT , /**< host to shellmatta sequence counter state of transport layer */ STATE_GET_S2H_SEQUENCE_CNT , /**< shellmatta to host sequence counter state of transport layer */ STATE_GET_PAYLOAD , /**< payload state of transport layer */ STATE_GET_CRC , /**< crc state of transport layer */ STATE_PROCESS_PAYLOAD } shellmatta_transport_state_t; /** * @brief definition of shellmatta transport layer packet types */ typedef enum { PACKET_DATA = 0x00u, /**< packet type to send plain data */ PACKET_SEQ_CNT_REQUEST = 0x01u, /**< packet type to request sequence counters */ PACKET_SEQ_CNT_RESPOND = 0x81u, /**< packet type to respond with sequence counters */ PACKET_MAX_BUFFERSIZE_REQUEST = 0x02u, /**< packet type to set and request max buffersize */ PACKET_MAX_BUFFERSIZE_RESPOND = 0x82u, /**< packet type to respond with max buffersize */ PACKET_SEARCH_DEVICE_REQUEST = 0x03u, /**< UNUSED: packet type to request search for a device by unique id */ PACKET_SEARCH_DEVICE_RESPOND = 0x83u, /**< UNUSED: packet type to respond with search results */ PACKET_SET_ADDRESS_REQUEST = 0x04u, /**< UNUSED: packet type to set and request an address */ PACKET_SET_ADDRESS_RESPOND = 0x84u /**< UNUSED: packet type to respond with a set address */ } shellmatta_transport_packet_t; /* payload length defines */ /** @brief max length of a plain data payload */ #define SHELLMATTA_PAYLOAD_MAXLENGTH ((uint8_t)(255)) /** * @brief structure of one shellmatta transport layer instance */ typedef struct { uint8_t h2s_sequenceCnt; /**< TODO */ uint8_t s2h_sequenceCnt; /**< */ shellmatta_transport_state_t state; /**< */ bool mandatory; /**< */ bool active; /**< */ bool continueStep; /**< */ shellmatta_write_t originalWrite; /**< */ uint8_t protocolVersion; /**< */ shellmatta_transport_packet_t packetType; /**< */ uint32_t payloadLength; /**< */ uint8_t source; /**< */ uint8_t destination; /**< */ uint32_t crc32; /**< */ uint8_t payloadCounter; /**< */ uint8_t crcCounter; /**< */ uint8_t packetSequenceCounter_h2s; /**< */ uint8_t packetSequenceCounter_s2h; /**< */ char payloadBuffer[SHELLMATTA_PAYLOAD_MAXLENGTH]; /**< */ } shellmatta_transport_layer_t; /** * @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_transport_layer_t transportLayer; /**< transport layer instance */ } shellmatta_instance_t; /** * @brief helper macro for the send function */ #define SHELLMATTA_WRITE(data, length) inst->transportLayer.active == true ? \ shellmatta_write_transport((shellmatta_transport_layer_t*)&inst->transportLayer, (data), (length)) : \ inst->write((data), (length)) 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); #ifndef SHELLMATTA_STRIP_PRINTF shellmatta_retCode_t shellmatta_printf( shellmatta_handle_t handle, const char *fmt, ...); #endif #endif /** @} */