1 /*
2  * Arm SCP/MCP Software
3  * Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef _CLI_H_
9 #define _CLI_H_
10 
11 /*****************************************************************************/
12 /* Include Files                                                             */
13 /*****************************************************************************/
14 
15 #include <stdbool.h>
16 #include <stdint.h>
17 
18 #include "cli_config.h"
19 #include "cli_fifo.h"
20 
21 /*****************************************************************************/
22 /* Enumerated Types                                                          */
23 /*****************************************************************************/
24 
25 /*
26  * cli_state_et
27  *   Description
28  *     Describes the current state of the CLI.
29  *   Members
30  *     CLI_NOT_READY
31  *       CLI has not been initialized and is not running.
32  *     CLI_READY
33  *       Data structures have been initialized, threads can register and print,
34  *       but print operations will be slow as they will have to use the UART
35  *       hardware.
36  *     CLI_RUNNING
37  *       The CLI thread is up and running, threads can register and print, and
38  *       print operations will be fast as they will write into a FIFO buffer
39  *       rather than deal with the UART hardware.
40  */
41 typedef enum {
42     CLI_NOT_READY = 0x0,
43     CLI_READY = 0x1,
44     CLI_RUNNING = 0x2
45 } cli_state_et;
46 
47 /* Masks for formatting options. */
48 #define CLI_RESET_MASK (0x00000003)
49 #define CLI_FORMAT_MASK (0x0000FFFC)
50 #define CLI_BG_COLOR_MASK (0x00FF0000)
51 #define CLI_TEXT_COLOR_MASK (0xFF000000)
52 #define CLI_ALL_MASK (CLI_FORMAT_MASK | CLI_BG_COLOR_MASK | CLI_TEXT_COLOR_MASK)
53 #define CLI_BG_COLOR_SHIFT (16)
54 #define CLI_TEXT_COLOR_SHIFT (24)
55 
56 /*
57  * cli_option_et
58  *   Description
59  *     These values are used apply special formatting to printed text in
60  *     cli_client_printf.  Options can be OR'd together to apply more than one
61  *     at a time.  You cannot use multiple background colors and multiple text
62  *     colors together though, but a single background and a single text color
63  *     is just fine.
64  *   Members
65  *     NONE
66  *       Default terminal formatting, same as using 0.
67  *     CLEAR_DISPLAY
68  *       Deletes everything on the display before printing.
69  *     RESET_CURSOR
70  *       Moves the cursor to the top left position (1,1).
71  *     BOLD
72  *       Makes text bold or "bright" depending on the terminal application.
73  *     UNDERLINE
74  *       Underlines text.
75  *     BG_<color>
76  *       Text background color, only one of these can be used at a time.
77  *     TEXT_<color>
78  *       Text color, only one of these can be used at a time.
79  */
80 typedef enum {
81     NONE = 0x00000000,
82     CLEAR_DISPLAY = 0x00000001,
83     RESET_CURSOR = 0x00000002,
84     BOLD = 0x00000004,
85     UNDERLINE = 0x00000008,
86     BG_BLACK = 0x001E0000,
87     BG_RED = 0x001F0000,
88     BG_GREEN = 0x00200000,
89     BG_YELLOW = 0x00210000,
90     BG_BLUE = 0x00220000,
91     BG_MAGENTA = 0x00230000,
92     BG_CYAN = 0x00240000,
93     BG_WHITE = 0x00250000,
94     TEXT_BLACK = 0x1E000000,
95     TEXT_RED = 0x1F000000,
96     TEXT_GREEN = 0x20000000,
97     TEXT_YELLOW = 0x21000000,
98     TEXT_BLUE = 0x22000000,
99     TEXT_MAGENTA = 0x23000000,
100     TEXT_CYAN = 0x24000000,
101     TEXT_WHITE = 0x25000000
102 } cli_option_et;
103 
104 /*****************************************************************************/
105 /* Structure Types                                                           */
106 /*****************************************************************************/
107 
108 /*!
109  * \brief CLI commands structure cli_command_st.
110  *
111  * \details Structure that stores a CLI command, it includes a help string so
112  *      help functionality is uniform across commands as well as a string used
113  *      to define the command used to invoke the stored function pointer.
114  */
115 typedef struct {
116     /*! Pointer to string that is typed to invoke a command. */
117     const char *command;
118     /*! Pointer to string containing help information for a command. */
119     const char *help;
120     /*! Pointer to function that is invoked for this command. */
121     int32_t (*handler)(int32_t argc, char **argv);
122     /*!
123      * For complex commands that need more than a single help string, set
124      * this to true.  This will keep the CLI from intercepting the --help and
125      * -h flags and will instead pass them to the command along with the rest
126      * of the arguments.
127      */
128     bool ignore_help_flag;
129 } cli_command_st;
130 
131 /*****************************************************************************/
132 /* Public Function Prototypes                                                */
133 /*****************************************************************************/
134 
135 /*
136  * cli_init
137  *   Description
138  *     Public function used to initialize the CLI data structures but not start
139  *     the CLI main thread.  This allows other threads to register with the CLI
140  *     before the CLI idle thread has actually been created.
141  *   Return
142  *     Platform return codes defined in cli_config.h.
143  */
144 uint32_t cli_init(void);
145 
146 /*
147  * cli_start
148  *   Description
149  *     Public function used to create the CLI thread after it's data structures
150  *     have been initialized.
151  *   Return
152  *     Platform return codes defined in cli_config.h.
153  */
154 uint32_t cli_start(void);
155 
156 /*
157  * cli_bprintf
158  *   Description
159  *     Buffered formatted print function.  Prints generated here are put into a
160  *     memory buffer and sent to the UART during CPU idle time rather than
161  *     waiting for the UART to accept all the data.  This allows debug print
162  *     statements to be very minimally intrusive.
163  *   Parameters
164  *     cli_option_et
165  *       Text formatting options, see definition of cli_option_et above.
166  *     const char *format
167  *       Formatted text to be printed, like printf.
168  *     ...
169  *       Additional arguments for formatted text, like printf.
170  *   Return
171  *     Platform return codes defined in cli_config.h.
172  */
173 uint32_t cli_bprintf(cli_option_et options, const char *format, ...);
174 
175 /*
176  * cli_bprint
177  *   Description
178  *     Buffered print function that just sends a string directly to the print
179  *     buffer with no special formatting.
180  *   Parameters
181  *     const char *string
182  *       Null-terminated string to be printed.
183  *   Return
184  *     Platform return codes defined in cli_config.h.
185  */
186 uint32_t cli_bprint(const char *format);
187 
188 /*
189  * cli_printf
190  *   Description
191  *     Prints directly to the debug console without waiting for the CLI thread
192  *     to pick it up.  Do not use this in a thread except in the case of dire
193  *     errors or information that needs to be printed immediately.
194  *   Paremeters
195  *     cli_option_et
196  *       Text formatting options, see definition of cli_option_et above.
197  *     const char *format
198  *       Formatted text to be printed, like printf.
199  *     ...
200  *       Additional arguments for formatted text, like printf.
201  *   Return
202  *     Platform return codes defined in cli_config.h.
203  */
204 uint32_t cli_printf(cli_option_et options, const char *format, ...);
205 
206 /*
207  * cli_print
208  *   Description
209  *     Sends a string directly to the debug terminal with no special formatting
210  *     or extra processing.
211  *   Parameters
212  *     const char *string
213  *       Null-terminated string to be printed.
214  *   Return
215  *     Platform return codes defined in cli_config.h.
216  */
217 uint32_t cli_print(const char *string);
218 
219 /*
220  * cli_format_print
221  *   Description
222  *     Rudimentary formatted print function that takes the place of snprintf and
223  *     it's variants.
224  *   Parameters
225  *     char *s
226  *       Buffer to build new string in.
227  *     char *smax
228  *       s + len(s), points to address after the last character in s.  This
229  *       keeps the function from exceeding the boundaries of the array.
230  *     const char *fmt
231  *       Formatted text to parse.
232  *     ...
233  *       Arguments for formatted text.
234  */
235 void cli_snprintf(char *s, char *smax, const char *fmt, ...);
236 
237 /*
238  * cli_getline
239  *   Description
240  *     Retrieves input from terminal while running a CLI command.
241  *   Parameters
242  *     char *buffer
243  *       Buffer used to store typed characters.
244  *     uint32_t buffer_size
245  *       Size of the buffer, determines how many characters you can type.
246  *     char **argbuf
247  *       If not NULL, the typed string will be split up into individual
248  *       arguments.  In this case, buffer will be unusable as the parser
249  *       replaces whitespace with null characters and creates links in argbuf to
250  *       each argument.
251  *     uint32_t argbuf_size
252  *       Size of the argbuf array, determines maximum number of individual
253  *       arguments that can be entered.  Ignored if argbuf is NULL.
254  *     uint32_t cursor_position
255  *       Tells the CLI how far advanced the cursor is on a line at the time, if
256  *       in doubt, print a newline then set to 0.
257  *   Return
258  *     Platform return codes defined in cli_config.h.
259  */
260 uint32_t cli_getline(
261     char *buffer,
262     uint32_t buffer_size,
263     char **argbuf,
264     uint32_t argbuf_size,
265     uint32_t cursor_position);
266 
267 /*
268  * TBA: Replace calls to strncmp with calls to cli_strncmp.
269  * For some reason calls to strncmp crash for seemingly no reason on the
270  * FPGA, so we'll use cli_strncmp until that gets fixed or we move over to
271  * silicon.
272  */
273 int32_t cli_strncmp(const char *s1, const char *s2, uint32_t limit);
274 
275 #ifdef BUILD_HAS_DEBUGGER
276 
277 /*!
278  * \brief Register a new CLI command at run time
279  *
280  * \param new_cmd The new command to register.
281  *
282  * \retval CLI_SUCCESS Operation succeeded.
283  * \retval CLI_ERR_MEM Not enough memory.
284  */
285 int cli_command_register(cli_command_st new_cmd);
286 
287 #else
288 
289 /*!
290  * \brief Register a new CLI command at run time
291  *
292  * \param new_cmd The new command to register.
293  *
294  * \retval CLI_SUCCESS Operation succeeded.
295  * \retval CLI_ERR_MEM Not enough memory.
296  */
297 #    define cli_command_register(new_cmd) \
298         ({ \
299             (void)new_cmd; \
300             FWK_SUCCESS; \
301         })
302 #endif
303 
304 #endif /* _CLI_H_ */
305