shellmatta/api/shellmatta.h

/*
 * Copyright (c) 2019 - 2021 Stefan Strobel <stefan.strobel@shimatta.net>
 *
 * 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 <stefan.strobel@shimatta.net>
 */

/**
 * @addtogroup shellmatta_api Shellmatta API description
 * @{
 */

#ifndef _SHELLMATTA_H_
#define _SHELLMATTA_H_

#include <stdint.h>
#include <stdbool.h>

/* 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

/** @} */