Cordio Stack and Cordio Profiles  r2p3-02rel0
terminal.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file terminal.h
4  *
5  * \brief Terminal handler.
6  *
7  * Copyright (c) 2015-2018 Arm Ltd. All Rights Reserved.
8  * Arm Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact Arm Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 
20 #ifndef TERMINAL_H
21 #define TERMINAL_H
22 
23 #include <stdarg.h>
24 
25 #include "wsf_types.h"
26 #include "wsf_os.h"
27 
28 /*! \addtogroup WSF_UTIL_API
29  * \{ */
30 
31 /**************************************************************************************************
32  Macros
33 **************************************************************************************************/
34 
35 #define TERMINAL_MAX_ARGC 8u /*!< \brief Maximum number of arguments to any command. */
36 #define TERMINAL_MAX_COMMAND_LEN 100u /*!< \brief Maximum length of command line. */
37 #define TERMINAL_PRINTF_MAX_LEN 128u /*!< \brief Maximum length of any printed output. */
38 #define TERMINAL_STRING_PROMPT "> " /*!< \brief Prompt string. */
39 #define TERMINAL_STRING_ERROR "ERROR: " /*!< \brief Error prefix. */
40 #define TERMINAL_STRING_USAGE "USAGE: " /*!< \brief Usage prefix. */
41 #define TERMINAL_STRING_NEW_LINE "\r\n" /*!< \brief New line string. */
42 
43 /*! \brief Terminal command error codes. */
44 enum
45 {
46  TERMINAL_ERROR_OK = 0, /*!< \brief Command completed. */
47  TERMINAL_ERROR_BAD_ARGUMENTS = 1, /*!< \brief ERROR: Invalid argument(s) */
48  TERMINAL_ERROR_TOO_FEW_ARGUMENTS = 2, /*!< \brief ERROR: Too few arguments */
49  TERMINAL_ERROR_TOO_MANY_ARGUMENTS = 3, /*!< \brief ERROR: Too many arguments */
50  TERMINAL_ERROR_EXEC = 4 /*!< \brief Command completed with execution error. */
51 };
52 
53 /**************************************************************************************************
54  Data Types
55 **************************************************************************************************/
56 
57 /*************************************************************************************************/
58 /*!
59  * \brief Handler for a terminal command.
60  *
61  * \param argc The number of arguments passed to the command.
62  * \param argv The array of arguments; the 0th argument is the command.
63  *
64  * \return Error code.
65  */
66 /*************************************************************************************************/
67 typedef uint8_t (*terminalHandler_t)(uint32_t argc, char **argv);
68 
69 /*************************************************************************************************/
70 /*!
71  * \brief Handler for transmit.
72  *
73  * \param pBuf Buffer to transmit.
74  * \param len Number of bytes to transmit.
75  *
76  * \return None.
77  */
78 /*************************************************************************************************/
79 typedef void (*terminalUartTx_t)(const uint8_t *pBuf, uint32_t len);
80 
81 /*! \brief Terminal command. */
82 typedef struct terminalCommand_tag
83 {
84  struct terminalCommand_tag *pNext; /*!< \brief Pointer to next command in list. */
85  const char *pName; /*!< \brief Name of command. */
86  const char *pHelpStr; /*!< \brief Help String for command. */
87  terminalHandler_t handler; /*!< \brief Handler for command. */
89 
90 /**************************************************************************************************
91  Function Prototypes
92 **************************************************************************************************/
93 
94 /*************************************************************************************************/
95 /*!
96  * \brief Initialize terminal.
97  *
98  * \param handlerId Handler ID for TerminalHandler().
99  *
100  * \return None.
101  */
102 /*************************************************************************************************/
103 void TerminalInit(wsfHandlerId_t handlerId);
104 
105 /*************************************************************************************************/
106 /*!
107  * \brief Register the UART Tx Function for the platform.
108  *
109  * \param uartTxFunc UART Tx callback function.
110  *
111  * \return None.
112  */
113 /*************************************************************************************************/
115 
116 /*************************************************************************************************/
117 /*!
118  * \brief Register command with terminal.
119  *
120  * \param pCommand Command.
121  *
122  * \return None.
123  */
124 /*************************************************************************************************/
126 
127 /*************************************************************************************************/
128 /*!
129  * \brief Handler for terminal messages.
130  *
131  * \param event WSF event mask.
132  * \param pMsg WSF message.
133  *
134  * \return None.
135  */
136 /*************************************************************************************************/
137 void TerminalHandler(wsfEventMask_t event, wsfMsgHdr_t *pMsg);
138 
139 /*************************************************************************************************/
140 /*!
141  * \brief Called by application when a data byte is received.
142  *
143  * \param dataByte received byte
144  *
145  * \return None.
146  */
147 /*************************************************************************************************/
148 void TerminalRx(uint8_t dataByte);
149 
150 /*************************************************************************************************/
151 /*!
152  * \brief Called by application to transmit string.
153  *
154  * \param pStr String.
155  *
156  * \return None.
157  */
158 /*************************************************************************************************/
159 void TerminalTxStr(const char *pStr);
160 
161 /*************************************************************************************************/
162 /*!
163  * \brief Called by application to transmit character.
164  *
165  * \param c Character.
166  *
167  * \return None.
168  */
169 /*************************************************************************************************/
170 void TerminalTxChar(char c);
171 
172 /*************************************************************************************************/
173 /*!
174  * \brief Called by application to print formatted data.
175  *
176  * \param pStr Message format string
177  * \param ... Additional arguments, printf-style
178  *
179  * \return None.
180  */
181 /*************************************************************************************************/
182 void TerminalTxPrint(const char *pStr, ...);
183 
184 /*************************************************************************************************/
185 /*!
186  * \brief Application function to transmit data..
187  *
188  * \param pData Data.
189  * \param len Length of data, in bytes.
190  *
191  * \return None.
192  */
193 /*************************************************************************************************/
194 void TerminalTx(const uint8_t *pData, uint16_t len);
195 
196 /*! \} */ /* WSF_UTIL_API */
197 
198 #endif /* TERMINAL_H */
uint8_t wsfEventMask_t
Event handler event mask data type.
Definition: wsf_os.h:77
Command completed with execution error.
Definition: terminal.h:50
ERROR: Invalid argument(s)
Definition: terminal.h:47
Terminal command.
Definition: terminal.h:82
void TerminalTxPrint(const char *pStr,...)
Called by application to print formatted data.
uint8_t(* terminalHandler_t)(uint32_t argc, char **argv)
Handler for a terminal command.
Definition: terminal.h:67
void TerminalInit(wsfHandlerId_t handlerId)
Initialize terminal.
ERROR: Too many arguments.
Definition: terminal.h:49
const char * pName
Name of command.
Definition: terminal.h:85
void TerminalTx(const uint8_t *pData, uint16_t len)
Application function to transmit data..
void TerminalRegisterCommand(terminalCommand_t *pCommand)
Register command with terminal.
void TerminalRx(uint8_t dataByte)
Called by application when a data byte is received.
void TerminalTxChar(char c)
Called by application to transmit character.
struct terminalCommand_tag * pNext
Pointer to next command in list.
Definition: terminal.h:84
Platform-independent data types.
unsigned long uint32_t
Unsigned 32-bit value.
Definition: wsf_types.h:71
void TerminalRegisterUartTxFunc(terminalUartTx_t uartTxFunc)
Register the UART Tx Function for the platform.
const char * pHelpStr
Help String for command.
Definition: terminal.h:86
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:74
Command completed.
Definition: terminal.h:46
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
void(* terminalUartTx_t)(const uint8_t *pBuf, uint32_t len)
Handler for transmit.
Definition: terminal.h:79
ERROR: Too few arguments.
Definition: terminal.h:48
void TerminalTxStr(const char *pStr)
Called by application to transmit string.
Software foundation OS API.
terminalHandler_t handler
Handler for command.
Definition: terminal.h:87
Common message structure passed to event handler.
Definition: wsf_os.h:97
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
void TerminalHandler(wsfEventMask_t event, wsfMsgHdr_t *pMsg)
Handler for terminal messages.