Keil Studio Cloud
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. */
95 } terminalCommand_t;
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 /*************************************************************************************************/
117 void TerminalRegisterUartTxFunc(terminalUartTx_t uartTxFunc);
118 
119 /*************************************************************************************************/
120 /*!
121  * \brief Register command with terminal.
122  *
123  * \param pCommand Command.
124  */
125 /*************************************************************************************************/
126 void TerminalRegisterCommand(terminalCommand_t *pCommand);
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 */
terminalCommand_t
struct terminalCommand_tag terminalCommand_t
Terminal command.
terminalCommand_tag::pHelpStr
const char * pHelpStr
Help String for command.
Definition: terminal.h:93
TERMINAL_ERROR_BAD_ARGUMENTS
ERROR: Invalid argument(s)
Definition: terminal.h:56
TerminalTxPrint
void TerminalTxPrint(const char *pStr,...)
Called by application to print formatted data.
terminalHandler_t
uint8_t(* terminalHandler_t)(uint32_t argc, char **argv)
Handler for a terminal command.
Definition: terminal.h:76
TerminalInit
void TerminalInit(wsfHandlerId_t handlerId)
Initialize terminal.
wsfEventMask_t
uint16_t wsfEventMask_t
Event handler event mask data type.
Definition: wsf_os.h:83
TERMINAL_ERROR_TOO_FEW_ARGUMENTS
ERROR: Too few arguments.
Definition: terminal.h:57
TerminalTx
void TerminalTx(const uint8_t *pData, uint16_t len)
Application function to transmit data..
TERMINAL_ERROR_EXEC
Command completed with execution error.
Definition: terminal.h:59
TerminalRegisterCommand
void TerminalRegisterCommand(terminalCommand_t *pCommand)
Register command with terminal.
TerminalRx
void TerminalRx(uint8_t dataByte)
Called by application when a data byte is received.
TerminalTxChar
void TerminalTxChar(char c)
Called by application to transmit character.
terminalCommand_tag::handler
terminalHandler_t handler
Handler for command.
Definition: terminal.h:94
terminalUartTx_t
bool_t(* terminalUartTx_t)(const uint8_t *pBuf, uint32_t len)
Handler for transmit.
Definition: terminal.h:86
terminalCommand_tag::pNext
struct terminalCommand_tag * pNext
Pointer to next command in list.
Definition: terminal.h:91
terminalCommand_tag
Terminal command.
Definition: terminal.h:89
wsf_types.h
Platform-independent data types.
TerminalRegisterUartTxFunc
void TerminalRegisterUartTxFunc(terminalUartTx_t uartTxFunc)
Register the UART Tx Function for the platform.
wsfHandlerId_t
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:80
terminalCommand_tag::pName
const char * pName
Name of command.
Definition: terminal.h:92
TERMINAL_ERROR_OK
Command completed.
Definition: terminal.h:55
TerminalTxStr
void TerminalTxStr(const char *pStr)
Called by application to transmit string.
wsf_os.h
Software foundation OS API.
wsfMsgHdr_t
Common message structure passed to event handler.
Definition: wsf_os.h:106
TERMINAL_ERROR_TOO_MANY_ARGUMENTS
ERROR: Too many arguments.
Definition: terminal.h:58
TerminalHandler
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.