shellmatta.h 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462
  1. /*
  2. * Copyright (c) 2019 - 2024 Stefan Strobel <stefan.strobel@shimatta.net>
  3. *
  4. * This Source Code Form is subject to the terms of the Mozilla Public
  5. * License, v. 2.0. If a copy of the MPL was not distributed with this
  6. * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  7. */
  8. /**
  9. * @file shellmatta.h
  10. * @brief API definition of the Shellmatta terminal implementation
  11. * @author Stefan Strobel <stefan.strobel@shimatta.net>
  12. */
  13. /**
  14. * @addtogroup shellmatta_api Shellmatta API description
  15. * @{
  16. */
  17. #ifndef _SHELLMATTA_H_
  18. #define _SHELLMATTA_H_
  19. #include <stdint.h>
  20. #include <stdbool.h>
  21. /* global defines */
  22. /*
  23. * Define the printf format specifier for all GCC versions > 3.3
  24. * This will let the compiler know that shellmatta_printf() is a function taking printf-like format specifiers.
  25. */
  26. #ifndef SHELLMATTA_ATTR_FORMAT
  27. # if ((__GNUC__ > 3) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 3)))
  28. # define SHELLMATTA_ATTR_FORMAT(fmt, args) __attribute__((__format__(__printf__, fmt, args)))
  29. # else
  30. # define SHELLMATTA_ATTR_FORMAT(fmt, args)
  31. # endif
  32. #else
  33. # define SHELLMATTA_ATTR_FORMAT(fmt, args)
  34. #endif
  35. /**
  36. * @brief definition of a shellmatta handle
  37. */
  38. typedef void* shellmatta_handle_t;
  39. /**
  40. * @brief definition of shellmatta return codes
  41. */
  42. typedef enum
  43. {
  44. SHELLMATTA_OK = 0u, /**< everything is OK */
  45. SHELLMATTA_ERROR , /**< error occured */
  46. SHELLMATTA_CONTINUE , /**< the function is not over */
  47. SHELLMATTA_USE_FAULT , /**< parameter error - wrong usage */
  48. SHELLMATTA_DUPLICATE , /**< duplicate command */
  49. SHELLMATTA_BUSY /**< command is busy keep calling */
  50. } shellmatta_retCode_t;
  51. /**
  52. * @brief definition of shellmatta insert mode
  53. */
  54. typedef enum
  55. {
  56. SHELLMATTA_MODE_INSERT = 0u, /**< insert mode */
  57. SHELLMATTA_MODE_OVERWRITE , /**< overwrite mode */
  58. } shellmatta_mode_t;
  59. /**
  60. * @brief definition of shellmatta optionparser agument type
  61. */
  62. typedef enum
  63. {
  64. SHELLMATTA_OPT_ARG_NONE = 0u, /**< no argument expected */
  65. SHELLMATTA_OPT_ARG_REQUIRED, /**< argument is required */
  66. SHELLMATTA_OPT_ARG_OPTIONAL, /**< argument is optional */
  67. } shellmatta_opt_argtype_t;
  68. /**
  69. * @brief definition of shellmatta optionparser agument type
  70. */
  71. typedef struct
  72. {
  73. const char *paramLong; /**< long parameter string */
  74. const char paramShort; /**< short parameter char */
  75. shellmatta_opt_argtype_t argtype; /**< argument type expected */
  76. } shellmatta_opt_long_t;
  77. /**
  78. * @brief definition of shellmatta optionparser structure
  79. */
  80. typedef struct
  81. {
  82. uint32_t argStart; /**< start of the arguments of the command */
  83. uint32_t offset; /**< current offset of the option parser */
  84. uint32_t nextOffset; /**< offset of the next hunk */
  85. uint32_t len; /**< length of the current hunk */
  86. } shellmatta_opt_t;
  87. /**
  88. * @brief shellmatta command function definition
  89. * @param[in] handle pointer to the instance which is calling the cmd
  90. * @param[in] arguments argument string called to run this command beginning
  91. * with the command itself
  92. * @param[in] length length of the argument string
  93. */
  94. typedef shellmatta_retCode_t (*shellmatta_cmdFct_t)(const shellmatta_handle_t handle,
  95. const char *arguments,
  96. uint32_t length);
  97. /**
  98. * @brief shellmatta write function definition
  99. * @param[in] data data to be written to the output
  100. * @param[in] length length of the data to be written
  101. */
  102. typedef shellmatta_retCode_t (*shellmatta_write_t)(const char* data, uint32_t length);
  103. #ifdef SHELLMATTA_AUTHENTICATION
  104. /**
  105. * @brief user role matrix
  106. */
  107. typedef struct
  108. {
  109. uint32_t userId; /**< id of the user (!= 0) */
  110. bool superuser; /**< allow the user to access all commands */
  111. const char *username; /**< name of the user role */
  112. const char *password; /**< password of the user role or NULL (custom auth) */
  113. } shellmatta_auth_user_t;
  114. /**
  115. * @brief typedefinition of one line of the authentication table
  116. */
  117. typedef struct
  118. {
  119. const char* cmd; /**< command to grand access to */
  120. const uint32_t *userIds; /**< list of user ids with access to the cmd */
  121. const uint32_t userIdslength; /**< length of the user list */
  122. } shellmatta_auth_perm_t;
  123. /**
  124. * @brief login states
  125. */
  126. typedef enum
  127. {
  128. SHELLMATTA_AUTH_IDLE, /**< authentication system waits */
  129. SHELLMATTA_AUTH_USERNAME, /**< input of username */
  130. SHELLMATTA_AUTH_PASSWORD /**< input of password */
  131. } shellmatta_auth_state_t;
  132. /**
  133. * @brief log actions - passed to the log function
  134. */
  135. typedef enum
  136. {
  137. SHELLMATTA_AUTH_EVENT_NONE, /**< no event (init value) */
  138. SHELLMATTA_AUTH_EVENT_LOGIN, /**< successful login event */
  139. SHELLMATTA_AUTH_EVENT_LOGIN_FAILED, /**< failed login event */
  140. SHELLMATTA_AUTH_EVENT_LOGOUT, /**< succesful logout event */
  141. } shellmatta_auth_log_event_t;
  142. /**
  143. * @brief custom shellmatta authentication method
  144. * @param[in] userId user id to log in (name of the user role)
  145. * @param[in] password password for the login
  146. * @return userId if password was correct - otherwise 0
  147. */
  148. typedef shellmatta_retCode_t (*shellmatta_auth_check_t)(const uint32_t userId, const char* password);
  149. /**
  150. * @brief shellmatta authentication log method - will be called whenever a login attempt is done
  151. * @param[in] userId userId to be logged in (0 on unknown user)
  152. * @param[in] event event type to be logged (e.g. successful login)
  153. */
  154. typedef void (*shellmatta_auth_log_t)(const uint32_t userId, shellmatta_auth_log_event_t event);
  155. #endif
  156. /**
  157. * @brief structure of one shellmatta command
  158. */
  159. typedef struct shellmatta_cmd
  160. {
  161. char *cmd; /**< command name */
  162. char *cmdAlias; /**< command alias */
  163. char *helpText; /**< help text to print in "help" command */
  164. char *usageText; /**< usage text - printed on "help cmd" */
  165. shellmatta_cmdFct_t cmdFct; /**< pointer to the cmd callack function */
  166. #ifdef SHELLMATTA_AUTHENTICATION
  167. shellmatta_auth_perm_t *authLink; /**< internally used - pointer to perm list */
  168. #endif
  169. struct shellmatta_cmd *next; /**< pointer to next command or NULL */
  170. } shellmatta_cmd_t;
  171. /**
  172. * @brief state enumeration for ymodem receive state machine
  173. */
  174. typedef enum
  175. {
  176. INACTIVE, /* YModem module not initialised */
  177. WAIT_FOR_START, /* waiting for start of header */
  178. RECEIVE_PACKET, /* currently receiving a packet */
  179. } shellmatta_ymodem_state_t;
  180. typedef struct
  181. {
  182. void (*yModemCancelCallback)(void);
  183. void (*yModemRecvPacketCallback)(void);
  184. void (*ymodemTransmissionCompleteCallback)(void);
  185. } shellmatta_ymodem_callbacks_t;
  186. #ifdef SHELLMATTA_TRANSPORT
  187. /**
  188. * @brief definition of shellmatta transport layer states
  189. */
  190. typedef enum
  191. {
  192. SHELLMATTA_TRANSPORT_STATE_WAIT = 0u , /**< wait for start of header */
  193. SHELLMATTA_TRANSPORT_STATE_GET_HEADER , /**< read in header */
  194. SHELLMATTA_TRANSPORT_STATE_GET_PAYLOAD , /**< read in payload */
  195. SHELLMATTA_TRANSPORT_STATE_GET_CRC , /**< read crc and process data */
  196. } shellmatta_transport_state_t;
  197. /** @brief max length of a plain data payload */
  198. #define SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH ((uint8_t)(255))
  199. /**
  200. * @brief shellmatta transport crc function definition for custom crcs
  201. * @param[in] data data to calculate the crc of
  202. * @param[in] size size of the data in bytes
  203. */
  204. typedef uint32_t (*shellmatta_transport_crc_t)(const char* data, const uint32_t size);
  205. /**
  206. * @brief structure of one shellmatta transport header
  207. */
  208. typedef struct __attribute__((__packed__))
  209. {
  210. uint8_t startOfHeader; /** start of header field */
  211. uint8_t protocolVersion; /** protocol version of the packet */
  212. uint8_t packetType; /** type of the packet */
  213. uint8_t payloadLength; /** length of the payload */
  214. uint8_t source; /** source of the packet */
  215. uint8_t destination; /** destination of the packet */
  216. uint8_t sequenceH2S; /** sequence counter host to shellmatta */
  217. uint8_t sequenceS2H; /** sequence counter shellmatta to host */
  218. } shellmatta_transport_header_t;
  219. /**
  220. * @brief structure of one shellmatta transport packet
  221. */
  222. typedef struct __attribute__((__packed__))
  223. {
  224. shellmatta_transport_header_t header; /**< header of the packet */
  225. char payload[SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH]; /**< payload of the packet */
  226. uint32_t crc; /**< crc of the packet */
  227. } shellmatta_transport_packet_t;
  228. /**
  229. * @brief structure of one shellmatta transport layer instance
  230. */
  231. typedef struct
  232. {
  233. shellmatta_transport_state_t state; /**< current state of the transport layer reception */
  234. bool active; /**< is transport layer communication active */
  235. bool disableAutoFlush; /**< enforce manual flushing */
  236. bool mandatory; /**< is the transport layer enforced */
  237. uint8_t sequenceH2S; /**< sequence counter host to shellmatta */
  238. uint8_t sequenceS2H; /**< sequenc counter shellmatta to host */
  239. uint32_t headerIndex; /**< read index of the header */
  240. uint32_t payloadIndex; /**< read index of the payload */
  241. uint32_t crcIndex; /**< read index of the checksum */
  242. shellmatta_transport_packet_t inPacket; /**< buffer for the received packets */
  243. shellmatta_transport_packet_t outPacket; /**< buffer for the sent packets */
  244. shellmatta_write_t writeFct; /**< shellmatta write function */
  245. shellmatta_transport_crc_t customCrcFct; /**< use this function to calculate crcs */
  246. } shellmatta_transport_layer_t;
  247. #endif
  248. /**
  249. * @brief structure of one shellmatta instance
  250. */
  251. typedef struct
  252. {
  253. uint32_t magic; /**< magic number to check if initialized */
  254. char *buffer; /**< input buffer */
  255. uint32_t bufferSize; /**< size of the input buffer */
  256. uint32_t inputCount; /**< offset of the current write operation */
  257. uint32_t byteCounter; /**< counter used to loop over input data */
  258. uint32_t lastNewlineIdx; /**< index of the lest newline */
  259. uint32_t cursor; /**< offset where the cursor is at */
  260. uint32_t stdinIdx; /**< start index of stdin in buffer */
  261. uint32_t stdinLength; /**< length of the stdin data */
  262. char *historyBuffer; /**< buffer to store the last commands */
  263. uint32_t historyBufferSize; /**< size of the history buffer */
  264. uint32_t historyStart; /**< index of the oldest stored command */
  265. uint32_t historyEnd; /**< index of the newest stored command */
  266. uint32_t historyRead; /**< index of the current search */
  267. bool historyReadUp; /**< flag to show the last history dir */
  268. uint32_t tabCounter; /**< counts the tabulator key presses */
  269. uint32_t escapeCounter; /**< counts the characters of an escape seq */
  270. char escapeChars[4u]; /**< buffer to save the escape characters */
  271. uint32_t hereStartIdx; /**< heredoc start of "<<" */
  272. uint32_t hereDelimiterIdx; /**< heredoc delimiter index in input */
  273. uint32_t hereLength; /**< length of the heredoc delimiter */
  274. bool echoEnabled; /**< if true the input is printed */
  275. bool dirty; /**< dirty flag to show changes */
  276. const char *prompt; /**< prompt is printed after every command */
  277. char delimiter; /**< delimiter (return) to terminate a cmd */
  278. shellmatta_mode_t mode; /**< mode of the shell */
  279. shellmatta_write_t write; /**< pointer to write function */
  280. shellmatta_cmd_t helpCmd; /**< help command structure */
  281. shellmatta_cmd_t *cmdList; /**< pointer to the first command */
  282. shellmatta_cmd_t *continuousCmd; /**< command to be called continuously */
  283. shellmatta_cmd_t *busyCmd; /**< command to be polled (busy mode) */
  284. bool cmdListIsConst; /**< true if the #cmdList was passed during
  285. initialization */
  286. shellmatta_opt_t optionParser; /**< option parser sructure */
  287. shellmatta_ymodem_state_t ymodemState; /**< current state of the ymodem module */
  288. #ifdef SHELLMATTA_AUTHENTICATION
  289. shellmatta_auth_state_t loginState; /**< state variable of the login cmd */
  290. shellmatta_cmd_t loginCmd; /**< login command structure */
  291. shellmatta_cmd_t logoutCmd; /**< logout command structure */
  292. uint32_t userId; /**< user ID of the current session */
  293. uint32_t tmpUserId; /**< remporary user ID during input */
  294. shellmatta_auth_user_t *userPointer; /**< pointer to the user in the user list */
  295. shellmatta_auth_user_t *userList; /**< user list */
  296. uint32_t userListLength; /**< length of the user list */
  297. shellmatta_auth_perm_t *permList; /**< permission list */
  298. uint32_t permListLength; /**< length of the permission list */
  299. shellmatta_auth_check_t checkFct; /**< custom credential check function */
  300. shellmatta_auth_log_t logFct; /**< auth log function */
  301. #endif
  302. #ifdef SHELLMATTA_TRANSPORT
  303. bool transportEnabled; /**< if true the transport layer is enabled */
  304. uint32_t transportBusyMark; /**< transport processing position during
  305. busy cmd execution */
  306. shellmatta_transport_layer_t transportLayer; /**< transport layer instance */
  307. #endif
  308. } shellmatta_instance_t;
  309. /**
  310. * @brief helper macro for the send function
  311. */
  312. #ifdef SHELLMATTA_TRANSPORT
  313. #define SHELLMATTA_WRITE(data, length) inst->transportLayer.active == true ? \
  314. shellmatta_transport_write((shellmatta_transport_layer_t*)&inst->transportLayer, (data), (length)) : \
  315. inst->write((data), (length))
  316. #else
  317. #define SHELLMATTA_WRITE(data, length) inst->write((data), (length))
  318. #endif
  319. shellmatta_retCode_t shellmatta_doInit( shellmatta_instance_t *inst,
  320. shellmatta_handle_t *handle,
  321. char *buffer,
  322. uint32_t bufferSize,
  323. char *historyBuffer,
  324. uint32_t historyBufferSize,
  325. const char *prompt,
  326. const shellmatta_cmd_t *cmdList,
  327. shellmatta_write_t writeFct);
  328. shellmatta_retCode_t shellmatta_resetShell( shellmatta_handle_t handle,
  329. bool printPrompt);
  330. shellmatta_retCode_t shellmatta_addCmd( shellmatta_handle_t handle,
  331. shellmatta_cmd_t *cmd);
  332. shellmatta_retCode_t shellmatta_removeCmd( shellmatta_handle_t handle,
  333. const shellmatta_cmd_t *cmd);
  334. shellmatta_retCode_t shellmatta_configure( shellmatta_handle_t handle,
  335. shellmatta_mode_t mode,
  336. bool echoEnabled,
  337. char delimiter);
  338. shellmatta_retCode_t shellmatta_processData(shellmatta_handle_t handle,
  339. char *data,
  340. uint32_t size);
  341. shellmatta_retCode_t shellmatta_write( shellmatta_handle_t handle,
  342. char *data,
  343. uint32_t length);
  344. shellmatta_retCode_t shellmatta_read( shellmatta_handle_t handle,
  345. char **data,
  346. uint32_t *length);
  347. shellmatta_retCode_t shellmatta_opt( shellmatta_handle_t handle,
  348. const char *optionString,
  349. char *option,
  350. char **argument,
  351. uint32_t *argLen);
  352. shellmatta_retCode_t shellmatta_opt_long( shellmatta_handle_t handle,
  353. const shellmatta_opt_long_t *longOptions,
  354. char *option,
  355. char **argument,
  356. uint32_t *argLen);
  357. #ifdef SHELLMATTA_TRANSPORT
  358. shellmatta_retCode_t shellmatta_transport_configure(shellmatta_handle_t handle,
  359. bool mandatory,
  360. bool disableAutoFlush,
  361. shellmatta_transport_crc_t customCrcFct);
  362. shellmatta_retCode_t shellmatta_transport_reset(shellmatta_handle_t handle);
  363. shellmatta_retCode_t shellmatta_transport_flush(shellmatta_handle_t handle);
  364. #endif
  365. #ifndef SHELLMATTA_STRIP_PRINTF
  366. shellmatta_retCode_t shellmatta_printf( shellmatta_handle_t handle,
  367. const char *fmt,
  368. ...)
  369. SHELLMATTA_ATTR_FORMAT(2, 3);
  370. #endif
  371. #ifdef SHELLMATTA_AUTHENTICATION
  372. shellmatta_retCode_t shellmatta_auth_init( shellmatta_handle_t handle,
  373. shellmatta_auth_user_t *userList,
  374. uint32_t userListLength,
  375. shellmatta_auth_perm_t *permList,
  376. uint32_t permListLength,
  377. bool customLogin,
  378. shellmatta_auth_check_t checkFct,
  379. shellmatta_auth_log_t logFct);
  380. shellmatta_retCode_t shellmatta_auth_login( shellmatta_handle_t handle,
  381. uint32_t userId);
  382. shellmatta_retCode_t shellmatta_auth_logout( shellmatta_handle_t handle);
  383. uint32_t shellmatta_auth_getLoggedInUserId( shellmatta_handle_t handle);
  384. shellmatta_retCode_t shellmatta_auth_getLoggedInUserName( shellmatta_handle_t handle,
  385. char *data,
  386. uint32_t *length);
  387. shellmatta_retCode_t shellmatta_auth_chpasswd( shellmatta_handle_t handle,
  388. const char *username,
  389. const char *password);
  390. #endif
  391. uint8_t shellmatta_ymodem( shellmatta_handle_t handle,
  392. uint8_t* buffer,
  393. uint32_t* fileSize,
  394. uint16_t* packetSize,
  395. shellmatta_ymodem_callbacks_t callbacks);
  396. void shellmatta_ymodem_end( shellmatta_handle_t handle,
  397. bool doCancel);
  398. void shellmatta_ymodem_set_enable(bool doEnable);
  399. bool shellmatta_ymodem_is_active(void);
  400. #endif
  401. /** @} */