From cbb7d586d315a4b53dacd5d6a0c5ee3b7d4dd30c Mon Sep 17 00:00:00 2001 From: Tarek El-Sherbiny Date: Thu, 2 Jan 2020 17:02:26 +0000 Subject: dbg: Import the CLI code This patch imports existing CLI implementaion. Change-Id: I65c79811e90f866980ded22dde82fbfe3c01f853 Signed-off-by: Tarek El-Sherbiny --- debugger/include/cli.h | 275 ++++++++++++++++++++++++++++++++++++++++ debugger/include/cli_config.h | 60 +++++++++ debugger/include/cli_fifo.h | 145 +++++++++++++++++++++ debugger/include/cli_platform.h | 123 ++++++++++++++++++ 4 files changed, 603 insertions(+) create mode 100644 debugger/include/cli.h create mode 100644 debugger/include/cli_config.h create mode 100644 debugger/include/cli_fifo.h create mode 100644 debugger/include/cli_platform.h (limited to 'debugger/include') 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 +#include + +#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_ + * Text background color, only one of these can be used at a time. + * TEXT_ + * 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 + +/* + * 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 +#include + +/* + * 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_ */ -- cgit v1.2.3