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
8Description of Files
9
10  cli_commands_core.c
11    Contains all code implementing core executable commands for the debug
12    console. If you wish to add new commands, create a new command structure and
13    add links to the command functions in the structure then call the command
14    registration function cli_command_register.
15
16  cli_config.h
17    Definitions of compile-time command line interface settings, such as buffer
18    sizes, default prompt text, platform return codes, etc.
19
20  cli_fifo.c
21    Function definitions for creating and accessing a FIFO buffer.  Used to
22    store characters from the keyboard before they can be read by the CLI
23    thread as well as acting as a print buffer to store characters before
24    they can be sent to the UART.
25
26  cli_fifo.h
27    Header file containing function prototypes and descriptions for cli_fifo.c.
28
29  cli_platform.h
30    Function prototypes and descriptions for platform-specific functions.  If
31    you wish to port this CLI, start by reading this file and then implement
32    the functions in the platform directory.
33
34  cli.c
35    Core CLI function definitions.  Contains both public and private CLI
36    functions.  Private function prototypes and descriptions are also here.
37
38  cli.h
39    CLI enumerated types, structure types, and public function prototypes and
40    descriptions.  To access CLI functionality from other files, you only
41    need to include this file.
42
43Using the Console
44
45  There are two mechanisms to enter the console. At compile time using
46  checkpoints and at run time using Ctrl+E press. To exit the console, Ctrl+D
47  should be pressed. Note that CTRL+E only works once the modules have been
48  started, as the module monitoring the keystrokes starts last.
49  Once inside the console, all dequeuing of events in the queue is blocked. The
50  framework will resume handling events after exiting the console.
51  By default the CLI is in command mode, to exit command mode and enter debug,
52  mode press Ctrl+C. To return to command mode, press Ctrl+C again.  Know that,
53  while in command mode, the print buffers can fill up quickly.
54  Once this happens, all debug data from the time the print buffers fill up to
55  the time you reenter debug mode and the CLI can empty the buffers will be lost
56  If a buffer fills up, you will see a message like "CONSOLE ERROR: Print buffer
57  overflow."
58
59Printing From Other Threads
60
61  cli_printf and cli_bprintf are formatted printing functions, and cli_print and
62  cli_bprint are non-formatted basic printing functions.  The cli_bprint
63  functions are buffered, meaning print data is placed into a FIFO buffer rather
64  than immediately put on the UART.  This allows the print functions to return
65  very quickly rather than having to wait on the UART, but prints are delayed
66  until the processor has time to print them.
67
68  Note that the maximum size of individual print text is limited by the
69  size of the scratch buffer (defined in cli_config.h) and how much space your
70  print buffer has.  Text style options take up more space still.
71
72  Also, to use this CLI to print from a thread will require enough extra stack
73  space to allocate the scratch buffer.
74
75CLI formatted print options
76
77  This CLI is not 100% compliant with typical C formatted print strings, it is
78  based on a very lightweight but rudimentary version of snprintf, so some fancy
79  formatting options will not work as intended. (or at all)  Basic specifiers
80  supported are listed below.
81
82    Specifier   Output                                               Example
83      d/i         Signed decimal integer                               -438
84      u           Unsigned decimal integer                             2841
85      x/X         Uppercase hex value (lower case not implemented)     4AB1
86      c           Single character                                     e
87      s           Null-terminated string of characters                 example
88      l           Used within a specifier, indicates 64 bit value.
89      0<width>    Left-pads with zeros, width is required with this.   00004AB1
90
91  These all work in the simplest use case, but things like right-justifying,
92  floating point values, and anything not fairly simple probably won't work so
93  make sure to test things first.
94
95  If you want to know exactly how strings are parsed, see the function
96  'cli_snprintf_arg' in cli_module.c.
97