Mistake on this page?
Report an issue in GitHub or email us
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  *
9  * Copyright (c) 2019-2020 Packetcraft, Inc.
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 /*************************************************************************************************/
24 
25 #ifndef TERMINAL_H
26 #define TERMINAL_H
27 
28 #include <stdarg.h>
29 
30 #include "wsf_types.h"
31 #include "wsf_os.h"
32 
33 /*! \addtogroup WSF_UTIL_API
34  * \{ */
35 
36 /**************************************************************************************************
37  Macros
38 **************************************************************************************************/
39 
40 #ifndef TERMINAL_MAX_ARGC
41 #define TERMINAL_MAX_ARGC 8u /*!< \brief Maximum number of arguments to any command. */
42 #endif
43 #ifndef TERMINAL_MAX_COMMAND_LEN
44 #define TERMINAL_MAX_COMMAND_LEN 100u /*!< \brief Maximum length of command line. */
45 #endif
46 #define TERMINAL_PRINTF_MAX_LEN 256u /*!< \brief Maximum length of any printed output. */
47 #define TERMINAL_STRING_PROMPT "> " /*!< \brief Prompt string. */
48 #define TERMINAL_STRING_ERROR "ERROR: " /*!< \brief Error prefix. */
49 #define TERMINAL_STRING_USAGE "USAGE: " /*!< \brief Usage prefix. */
50 #define TERMINAL_STRING_NEW_LINE "\r\n" /*!< \brief New line string. */
51 
52 /*! \brief Terminal command error codes. */
53 enum
54 {
55  TERMINAL_ERROR_OK = 0, /*!< \brief Command completed. */
56  TERMINAL_ERROR_BAD_ARGUMENTS = 1, /*!< \brief ERROR: Invalid argument(s) */
57  TERMINAL_ERROR_TOO_FEW_ARGUMENTS = 2, /*!< \brief ERROR: Too few arguments */
58  TERMINAL_ERROR_TOO_MANY_ARGUMENTS = 3, /*!< \brief ERROR: Too many arguments */
59  TERMINAL_ERROR_EXEC = 4 /*!< \brief Command completed with execution error. */
60 };
61 
62 /**************************************************************************************************
63  Data Types
64 **************************************************************************************************/
65 
66 /*************************************************************************************************/
67 /*!
68  * \brief Handler for a terminal command.
69  *
70  * \param argc The number of arguments passed to the command.
71  * \param argv The array of arguments; the 0th argument is the command.
72  *
73  * \return Error code.
74  */
75 /*************************************************************************************************/
76 typedef uint8_t (*terminalHandler_t)(uint32_t argc, char **argv);
77 
78 /*************************************************************************************************/
79 /*!
80  * \brief Handler for transmit.
81  *
82  * \param pBuf Buffer to transmit.
83  * \param len Number of bytes to transmit.
84  */
85 /*************************************************************************************************/
86 typedef bool_t (*terminalUartTx_t)(const uint8_t *pBuf, uint32_t len);
87 
88 /*! \brief Terminal command. */
89 typedef struct terminalCommand_tag
90 {
91  struct terminalCommand_tag *pNext; /*!< \brief Pointer to next command in list. */
92  const char *pName; /*!< \brief Name of command. */
93  const char *pHelpStr; /*!< \brief Help String for command. */
94  terminalHandler_t handler; /*!< \brief Handler for command. */
96 
97 /**************************************************************************************************
98  Function Prototypes
99 **************************************************************************************************/
100 
101 /*************************************************************************************************/
102 /*!
103  * \brief Initialize terminal.
104  *
105  * \param handlerId Handler ID for TerminalHandler().
106  */
107 /*************************************************************************************************/
108 void TerminalInit(wsfHandlerId_t handlerId);
109 
110 /*************************************************************************************************/
111 /*!
112  * \brief Register the UART Tx Function for the platform.
113  *
114  * \param uartTxFunc UART Tx callback function.
115  */
116 /*************************************************************************************************/
118 
119 /*************************************************************************************************/
120 /*!
121  * \brief Register command with terminal.
122  *
123  * \param pCommand Command.
124  */
125 /*************************************************************************************************/
127 
128 /*************************************************************************************************/
129 /*!
130  * \brief Handler for terminal messages.
131  *
132  * \param event WSF event mask.
133  * \param pMsg WSF message.
134  */
135 /*************************************************************************************************/
136 void TerminalHandler(wsfEventMask_t event, wsfMsgHdr_t *pMsg);
137 
138 /*************************************************************************************************/
139 /*!
140  * \brief Called by application when a data byte is received.
141  *
142  * \param dataByte received byte
143  */
144 /*************************************************************************************************/
145 void TerminalRx(uint8_t dataByte);
146 
147 /*************************************************************************************************/
148 /*!
149  * \brief Called by application to transmit string.
150  *
151  * \param pStr String.
152  */
153 /*************************************************************************************************/
154 void TerminalTxStr(const char *pStr);
155 
156 /*************************************************************************************************/
157 /*!
158  * \brief Called by application to transmit character.
159  *
160  * \param c Character.
161  */
162 /*************************************************************************************************/
163 void TerminalTxChar(char c);
164 
165 /*************************************************************************************************/
166 /*!
167  * \brief Called by application to print formatted data.
168  *
169  * \param pStr Message format string
170  * \param ... Additional arguments, printf-style
171  */
172 /*************************************************************************************************/
173 void TerminalTxPrint(const char *pStr, ...);
174 
175 /*************************************************************************************************/
176 /*!
177  * \brief Application function to transmit data..
178  *
179  * \param pData Data.
180  * \param len Length of data, in bytes.
181  */
182 /*************************************************************************************************/
183 void TerminalTx(const uint8_t *pData, uint16_t len);
184 
185 /*! \} */ /* WSF_UTIL_API */
186 
187 #endif /* TERMINAL_H */
struct terminalCommand_tag terminalCommand_t
Terminal command.
const char * pHelpStr
Help String for command.
Definition: terminal.h:93
ERROR: Invalid argument(s)
Definition: terminal.h:56
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:76
void TerminalInit(wsfHandlerId_t handlerId)
Initialize terminal.
uint16_t wsfEventMask_t
Event handler event mask data type.
Definition: wsf_os.h:83
ERROR: Too few arguments.
Definition: terminal.h:57
void TerminalTx(const uint8_t *pData, uint16_t len)
Application function to transmit data..
Command completed with execution error.
Definition: terminal.h:59
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.
terminalHandler_t handler
Handler for command.
Definition: terminal.h:94
bool_t(* terminalUartTx_t)(const uint8_t *pBuf, uint32_t len)
Handler for transmit.
Definition: terminal.h:86
struct terminalCommand_tag * pNext
Pointer to next command in list.
Definition: terminal.h:91
Terminal command.
Definition: terminal.h:89
Platform-independent data types.
void TerminalRegisterUartTxFunc(terminalUartTx_t uartTxFunc)
Register the UART Tx Function for the platform.
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:80
const char * pName
Name of command.
Definition: terminal.h:92
Command completed.
Definition: terminal.h:55
void TerminalTxStr(const char *pStr)
Called by application to transmit string.
Software foundation OS API.
Common message structure passed to event handler.
Definition: wsf_os.h:106
ERROR: Too many arguments.
Definition: terminal.h:58
void TerminalHandler(wsfEventMask_t event, wsfMsgHdr_t *pMsg)
Handler for terminal messages.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.