readme.txt
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