dbg: Import the CLI code

This patch imports existing CLI implementaion.

Change-Id: I65c79811e90f866980ded22dde82fbfe3c01f853
Signed-off-by: Tarek El-Sherbiny <tarek.el-sherbiny@arm.com>

4 files changed, 603 insertions, 0 deletions

diff --git a/debugger/include/cli.h b/debugger/include/cli.h
new file mode 100644
index 00000000..74e89fed
--- /dev/null
+++ b/debugger/include/cli.h
@@ -0,0 +1,275 @@
+/*
+ * Arm SCP/MCP Software
+ * Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _CLI_H_
+#define _CLI_H_
+
+/*****************************************************************************/
+/* Include Files                                                             */
+/*****************************************************************************/
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "cli_config.h"
+#include "cli_fifo.h"
+
+/*****************************************************************************/
+/* Enumerated Types                                                          */
+/*****************************************************************************/
+
+/*
+ * cli_state_et
+ *   Description
+ *     Describes the current state of the CLI.
+ *   Members
+ *     CLI_NOT_READY
+ *       CLI has not been initialized and is not running.
+ *     CLI_READY
+ *       Data structures have been initialized, threads can register and print,
+ *       but print operations will be slow as they will have to use the UART
+ *       hardware.
+ *     CLI_RUNNING
+ *       The CLI thread is up and running, threads can register and print, and
+ *       print operations will be fast as they will write into a FIFO buffer
+ *       rather than deal with the UART hardware.
+ */
+typedef enum {
+    CLI_NOT_READY = 0x0,
+    CLI_READY = 0x1,
+    CLI_RUNNING = 0x2
+} cli_state_et;
+
+/* Masks for formatting options. */
+#define CLI_RESET_MASK (0x00000003)
+#define CLI_FORMAT_MASK (0x0000FFFC)
+#define CLI_BG_COLOR_MASK (0x00FF0000)
+#define CLI_TEXT_COLOR_MASK (0xFF000000)
+#define CLI_ALL_MASK (CLI_FORMAT_MASK | CLI_BG_COLOR_MASK | CLI_TEXT_COLOR_MASK)
+#define CLI_BG_COLOR_SHIFT (16)
+#define CLI_TEXT_COLOR_SHIFT (24)
+
+/*
+ * cli_option_et
+ *   Description
+ *     These values are used apply special formatting to printed text in
+ *     cli_client_printf.  Options can be OR'd together to apply more than one
+ *     at a time.  You cannot use multiple background colors and multiple text
+ *     colors together though, but a single background and a single text color
+ *     is just fine.
+ *   Members
+ *     NONE
+ *       Default terminal formatting, same as using 0.
+ *     CLEAR_DISPLAY
+ *       Deletes everything on the display before printing.
+ *     RESET_CURSOR
+ *       Moves the cursor to the top left position (1,1).
+ *     BOLD
+ *       Makes text bold or "bright" depending on the terminal application.
+ *     UNDERLINE
+ *       Underlines text.
+ *     BG_<color>
+ *       Text background color, only one of these can be used at a time.
+ *     TEXT_<color>
+ *       Text color, only one of these can be used at a time.
+ */
+typedef enum {
+    NONE = 0x00000000,
+    CLEAR_DISPLAY = 0x00000001,
+    RESET_CURSOR = 0x00000002,
+    BOLD = 0x00000004,
+    UNDERLINE = 0x00000008,
+    BG_BLACK = 0x001E0000,
+    BG_RED = 0x001F0000,
+    BG_GREEN = 0x00200000,
+    BG_YELLOW = 0x00210000,
+    BG_BLUE = 0x00220000,
+    BG_MAGENTA = 0x00230000,
+    BG_CYAN = 0x00240000,
+    BG_WHITE = 0x00250000,
+    TEXT_BLACK = 0x1E000000,
+    TEXT_RED = 0x1F000000,
+    TEXT_GREEN = 0x20000000,
+    TEXT_YELLOW = 0x21000000,
+    TEXT_BLUE = 0x22000000,
+    TEXT_MAGENTA = 0x23000000,
+    TEXT_CYAN = 0x24000000,
+    TEXT_WHITE = 0x25000000
+} cli_option_et;
+
+/*****************************************************************************/
+/* Structure Types                                                           */
+/*****************************************************************************/
+
+/*!
+ * \brief CLI commands structure cli_command_st.
+ *
+ * \details Structure that stores a CLI command, it includes a help string so
+ *      help functionality is uniform across commands as well as a string used
+ *      to define the command used to invoke the stored function pointer.
+ */
+typedef struct {
+    /*! Pointer to string that is typed to invoke a command. */
+    const char *command;
+    /*! Pointer to string containing help information for a command. */
+    const char *help;
+    /*! Pointer to function that is invoked for this command. */
+    int32_t (*handler)(int32_t argc, char **argv);
+    /*!
+     * For complex commands that need more than a single help string, set
+     * this to true.  This will keep the CLI from intercepting the --help and
+     * -h flags and will instead pass them to the command along with the rest
+     * of the arguments.
+     */
+    bool ignore_help_flag;
+} cli_command_st;
+
+/*****************************************************************************/
+/* Public Function Prototypes                                                */
+/*****************************************************************************/
+
+/*
+ * cli_init
+ *   Description
+ *     Public function used to initialize the CLI data structures but not start
+ *     the CLI main thread.  This allows other threads to register with the CLI
+ *     before the CLI idle thread has actually been created.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_init(void);
+
+/*
+ * cli_start
+ *   Description
+ *     Public function used to create the CLI thread after it's data structures
+ *     have been initialized.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_start(void);
+
+/*
+ * cli_bprintf
+ *   Description
+ *     Buffered formatted print function.  Prints generated here are put into a
+ *     memory buffer and sent to the UART during CPU idle time rather than
+ *     waiting for the UART to accept all the data.  This allows debug print
+ *     statements to be very minimally intrusive.
+ *   Parameters
+ *     cli_option_et
+ *       Text formatting options, see definition of cli_option_et above.
+ *     const char *format
+ *       Formatted text to be printed, like printf.
+ *     ...
+ *       Additional arguments for formatted text, like printf.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_bprintf(cli_option_et options, const char *format, ...);
+
+/*
+ * cli_bprint
+ *   Description
+ *     Buffered print function that just sends a string directly to the print
+ *     buffer with no special formatting.
+ *   Parameters
+ *     const char *string
+ *       Null-terminated string to be printed.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_bprint(const char *format);
+
+/*
+ * cli_printf
+ *   Description
+ *     Prints directly to the debug console without waiting for the CLI thread
+ *     to pick it up.  Do not use this in a thread except in the case of dire
+ *     errors or information that needs to be printed immediately.
+ *   Paremeters
+ *     cli_option_et
+ *       Text formatting options, see definition of cli_option_et above.
+ *     const char *format
+ *       Formatted text to be printed, like printf.
+ *     ...
+ *       Additional arguments for formatted text, like printf.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_printf(cli_option_et options, const char *format, ...);
+
+/*
+ * cli_print
+ *   Description
+ *     Sends a string directly to the debug terminal with no special formatting
+ *     or extra processing.
+ *   Parameters
+ *     const char *string
+ *       Null-terminated string to be printed.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_print(const char *string);
+
+/*
+ * cli_format_print
+ *   Description
+ *     Rudimentary formatted print function that takes the place of snprintf and
+ *     it's variants.
+ *   Parameters
+ *     char *s
+ *       Buffer to build new string in.
+ *     char *smax
+ *       s + len(s), points to address after the last character in s.  This
+ *       keeps the function from exceeding the boundaries of the array.
+ *     const char *fmt
+ *       Formatted text to parse.
+ *     ...
+ *       Arguments for formatted text.
+ */
+void cli_snprintf(char *s, char *smax, const char *fmt, ...);
+
+/*
+ * cli_getline
+ *   Description
+ *     Retrieves input from terminal while running a CLI command.
+ *   Parameters
+ *     char *buffer
+ *       Buffer used to store typed characters.
+ *     uint32_t buffer_size
+ *       Size of the buffer, determines how many characters you can type.
+ *     char **argbuf
+ *       If not NULL, the typed string will be split up into individual
+ *       arguments.  In this case, buffer will be unusable as the parser
+ *       replaces whitespace with null characters and creates links in argbuf to
+ *       each argument.
+ *     uint32_t argbuf_size
+ *       Size of the argbuf array, determines maximum number of individual
+ *       arguments that can be entered.  Ignored if argbuf is NULL.
+ *     uint32_t cursor_position
+ *       Tells the CLI how far advanced the cursor is on a line at the time, if
+ *       in doubt, print a newline then set to 0.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t cli_getline(
+    char *buffer,
+    uint32_t buffer_size,
+    char **argbuf,
+    uint32_t argbuf_size,
+    uint32_t cursor_position);
+
+/*
+ * TBA: Replace calls to strncmp with calls to cli_strncmp.
+ * For some reason calls to strncmp crash for seemingly no reason on the
+ * FPGA, so we'll use cli_strncmp until that gets fixed or we move over to
+ * silicon.
+ */
+int32_t cli_strncmp(const char *s1, const char *s2, uint32_t limit);
+
+#endif /* _CLI_H_ */
diff --git a/debugger/include/cli_config.h b/debugger/include/cli_config.h
new file mode 100644
index 00000000..9a5d6197
--- /dev/null
+++ b/debugger/include/cli_config.h
@@ -0,0 +1,60 @@
+/*
+ * Arm SCP/MCP Software
+ * Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _CLI_CONFIG_H_
+#define _CLI_CONFIG_H_
+
+#include <fwk_status.h>
+
+/*
+ * Descriptions of console configuration macros.
+ *
+ * CLI_CONFIG_COMMAND_BUF_SIZE
+ *   The maximum number of characters that can be entered as a single command.
+ *
+ * CLI_CONFIG_MAX_NUM_ARGUMENTS
+ *   The maximum number of individual arguments in a single command.
+ *
+ * CLI_CONFIG_HISTORY_LENGTH
+ *   The number of past commands stored by the console.  Can be accessed with
+ *   the up/down arrow keys.
+ *
+ * CLI_CONFIG_PROMPT_BUF_SIZE
+ *   Size of the CLI prompt text buffer.
+ *
+ * CLI_CONFIG_DEFAULT_TERM_W
+ *   Default assumed terminal window width.
+ *
+ * CLI_CONFIG_DEFAULT_TERM_H
+ *   Default assumed terminal window height.
+ *
+ * CLI_CONFIG_STACK_SIZE
+ *   Number of stack bytes requested when thread is defined.
+ *
+ * CLI_CONFIG_PRINT_BUFFER_SIZE
+ *   Size of the debug print buffer used to store characters before they can
+ *   be sent to the UART.
+ *
+ * CLI_CONFIG_SCRATCH_BUFFER_SIZE
+ *   Number of stack bytes used as scratch space by print statements, size of
+ *   this buffer determines the maximum length of a single print.  Threads using
+ *   CLI print functionality must have this much extra stack space.
+ */
+
+#define CLI_CONFIG_COMMAND_BUF_SIZE (256)
+#define CLI_CONFIG_MAX_NUM_ARGUMENTS (16)
+#define CLI_CONFIG_HISTORY_LENGTH (16)
+#define CLI_CONFIG_PROMPT_BUF_SIZE (16)
+#define CLI_CONFIG_DEFAULT_TERM_W (80)
+#define CLI_CONFIG_DEFAULT_TERM_H (24)
+#define CLI_CONFIG_STACK_SIZE (2048)
+#define CLI_CONFIG_PRINT_BUFFER_SIZE (1024)
+#define CLI_CONFIG_SCRATCH_BUFFER_SIZE (256)
+
+#define CLI_PROMPT  "> "
+
+#endif /* _CLI_CONFIG_H_ */
diff --git a/debugger/include/cli_fifo.h b/debugger/include/cli_fifo.h
new file mode 100644
index 00000000..d9277aea
--- /dev/null
+++ b/debugger/include/cli_fifo.h
@@ -0,0 +1,145 @@
+/*
+ * Arm SCP/MCP Software
+ * Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _CLI_FIFO_H_
+#define _CLI_FIFO_H_
+
+/*****************************************************************************/
+/* Structure Types                                                           */
+/*****************************************************************************/
+
+typedef struct {
+    uint32_t put_ptr;
+    uint32_t get_ptr;
+    uint32_t count;
+    uint32_t high_water;
+    bool reset_high_water;
+    uint32_t buf_size;
+    char *buf;
+} fifo_st;
+
+/*****************************************************************************/
+/* Function Prototypes                                                       */
+/*****************************************************************************/
+
+/*
+ * fifo_init
+ *   Description
+ *     Initializes a FIFO structure, the caller must supply the buffer memory.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Pointer to a pre-allocated fifo_st structure.
+ *     char *buf
+ *       Pointer to memory to store FIFO entries.
+ *     uint32_t buf_size
+ *       Size of the buffer in bytes.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t fifo_init(fifo_st *fifo, char *buf, uint32_t buf_size);
+
+/*
+ * fifo_get
+ *   Description
+ *     Gets a byte from a FIFO and places into the address supplied.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Pointer to fifo_st structure to get the byte from.
+ *     char *val
+ *       Pointer to location in which to place the retrieved byte.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t fifo_get(fifo_st *fifo, char *val);
+
+/*
+ * fifo_put
+ *   Description
+ *     Places a byte into a FIFO buffer.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Pointer to fifo_st structure to put the byte into.
+ *     char *val
+ *       Pointer to location from which to get the byte.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t fifo_put(fifo_st *fifo, char *val);
+
+/*
+ * fifo_free_space
+ *   Description
+ *     Returns the number of unused entries in the FIFO buffer.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Pointer to fifo_st structure to get the free space from.
+ *   Return
+ *     Number of free spaces in the FIFO.
+ */
+uint32_t fifo_free_space(fifo_st *fifo);
+
+/*
+ * fifo_count
+ *   Description
+ *     Returns the number of bytes currently in a FIFO.
+ *   Paremeters
+ *     fifo_st *fifo
+ *       Buffer from which to get the count.
+ *   Return
+ *     Number of bytes in the FIFO.
+ */
+uint32_t fifo_count(fifo_st *fifo);
+
+/*
+ * fifo_capacity
+ *   Description
+ *     Gets the maximum number of bytes that can be stored by a FIFO.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Pointer to FIFO structure from which to get the capacity.
+ *   Return
+ *     Total capacity of the FIFO, this will be one less than the buffer size.
+ */
+uint32_t fifo_capacity(fifo_st *fifo);
+
+/*
+ * fifo_high_water
+ *   Description
+ *     Returns the high-water point from the FIFO buffer.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Buffer structure to get the high-water count from.
+ *   Return
+ *     High water mark from FIFO.
+ */
+uint32_t fifo_high_water(fifo_st *fifo);
+
+/*
+ * fifo_high_water_reset
+ *   Description
+ *     Resets the high water counter by freezing it until the buffer is empty.
+ *   Paremeters
+ *     fifo_st *fifo
+ *       Buffer structure to reset the high-water count in.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t fifo_high_water_reset(fifo_st *fifo);
+
+/*
+ * fifo_empty
+ *   Description
+ *     Removes every item from the FIFO buffer.
+ *   Parameters
+ *     fifo_st *fifo
+ *       Pointer to fifo_st structure to empty.
+ *   Return
+ *     Platform return codes defined in cli_config.h.
+ */
+uint32_t fifo_empty(fifo_st *fifo);
+
+#endif /* _CLI_FIFO_H_ */
diff --git a/debugger/include/cli_platform.h b/debugger/include/cli_platform.h
new file mode 100644
index 00000000..f9ae03f7
--- /dev/null
+++ b/debugger/include/cli_platform.h
@@ -0,0 +1,123 @@
+/*
+ * Arm SCP/MCP Software
+ * Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef _CLI_PLATFORM_H_
+#define _CLI_PLATFORM_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+
+/*
+ * cli_timestamp_t
+ *   Description
+ *     Stores timestamp information in human-readable format.
+ *   Members
+ *     uint32_t days
+ *       Number of days elapsed since restart.
+ *     uint8_t hours
+ *       Hours portion of time since restart.
+ *     uint8_t minutes
+ *       Minutes portion of time since restart.
+ *     uint8_t seconds
+ *       Seconds portion of time since restart.
+ *     uint8_t fraction
+ *       Value from 0-99 containing hundredths of seconds.
+ */
+typedef struct {
+    uint32_t days;
+    uint8_t hours;
+    uint8_t minutes;
+    uint8_t seconds;
+    uint8_t fraction;
+} cli_timestamp_t;
+
+/*****************************************************************************/
+/* CLI Platform-Specific Function Prototypes                                 */
+/*****************************************************************************/
+
+/*
+ * cli_platform_get_time
+ *   Description
+ *     Fills out a cli_timestamp_t structure, this can be real time or time
+ *     since system startup.
+ *   Parameters
+ *     cli_timestamp_t *t
+ *       Pointer to structure to fill out.
+ */
+void cli_platform_get_time(cli_timestamp_t *t);
+
+/*
+ * cli_platform_delay_ms
+ *   Descriptions
+ *     Delays execution for a number of milliseconds.
+ *   Parameters
+ *     uint32_t ms
+ *       Number of milliseconds to delay.
+ */
+void cli_platform_delay_ms(uint32_t ms);
+
+/*****************************************************************************/
+/* CLI Platform-Specific UART Functions                                      */
+/*****************************************************************************/
+
+/*
+ * cli_platform_uart_init
+ *   Description
+ *     Initializes the necessary hardware to send and receive characters.
+ *   Return
+ *     cli_ret_et: success if it works, something else if it fails.
+ */
+uint32_t cli_platform_uart_init(void);
+
+/*
+ * cli_platform_uid_notify
+ *   Description
+ *     If system has a UID light, this function notifies it of activity on
+ *     the console.
+ *   Return
+ *     cli_ret_et: success if it works, something else if it fails.
+ */
+uint32_t cli_platform_uid_notify(void);
+
+/*
+ * cli_platform_uart_get
+ *   Description
+ *     Receives a single character from the UART.  Must support blocking and
+ *     non-blocking receive operations.
+ *   Parameters
+ *     char *c
+ *       Pointer to a char in which to place the received character.
+ *     bool block
+ *       If true, this function must not return until a character is
+ *       received or the UART generates an error.  If false, this function
+ *       returns immediately regardless of whether or not a character was
+ *       received.
+ *   Return
+ *     cli_ret_et: success if a character is read with no errors, error_empty
+ *     if block==true and no characters are available, or some other error
+ *     from the UART.
+ */
+uint32_t cli_platform_uart_get(char *c, bool block);
+
+/*
+ * cli_platform_uart_put
+ *   Description
+ *     Sends a single character on the UART.  This function is blocking.
+ *   Parameters
+ *     char *c
+ *       Pointer to character to send.
+ *     bool block
+ *       If true, this function must not return until a character is
+ *       output or the UART generates an error.  If false, this function
+ *       returns immediately regardless of whether or not a character was
+ *       output.
+ *   Return
+ *     cli_ret_et: success if it works, some other error if it doesn't.
+ */
+uint32_t cli_platform_uart_put(const char *c, bool block);
+
+#endif /* _CLI_PLATFORM_H_ */