Core

Command Parsing Algorithm

XWSH uses the xwsh_split_cmdline() function (xwmd/cli/xwsh/core.c:126) to split a command line string into an argument array. The algorithm employs a single-pass strategy, modifying the input string in place to avoid additional memory allocation.

Algorithm Principle

xwer_t xwsh_split_cmdline(char * line, xwsz_t * argc, char * argv[], xwsz_t argvsize)
{
        char * p = line;
        xwsz_t count = 0;
        char * start = NULL;
        xwer_t rc = XWOK;

        while (*p) {
                if ((NULL == start) && (' ' == *p)) {
                        p++;  // Skip leading spaces
                } else {
                        if (NULL == start) {
                                start = p;  // Record argument start position
                        }
                        if (*p == ' ') {
                                if (count < argvsize) {
                                        *p = '\0';           // Terminate current argument
                                        argv[count] = start; // Save argument pointer
                                        count++;
                                } else {
                                        rc = -E2BIG;        // Too many arguments error
                                        break;
                                }
                                start = NULL;               // Reset start position
                        }
                        p++;
                }
        }
        // ... Handle the last argument
}

Algorithm Characteristics

1. Time complexity O(n): Only traverses the string once
2. In-place modification: Replaces spaces with \0, does not copy the string
3. Argument pointer array: The argv array stores pointers to parts of the original string
4. Error detection:
   • Returns -E2BIG when argument count exceeds argvsize
   • Maximum argument count: XWSH_MAX_PARAM_NUM (16)

Argument Format Limitations

• No quote support: Cannot handle arguments with spaces (e.g. "file name")
• Simple splitting: Splits only by spaces; consecutive spaces are treated as a single delimiter
• Trailing spaces: Automatically ignores trailing spaces at the end of the command

Thread Model

XWSH provides two thread running modes to suit different application scenarios.

Mode Comparison

Standalone Thread Mode

// xwmd/cli/xwsh/mi.c:24
#define XWSH_THD_PRIORITY XWOS_SKD_PRIORITY_DROP(XWOS_SKD_PRIORITY_RT_MAX, 0)

xwer_t xwsh_start(xwstk_t * stack, xwsz_t stack_size)
{
        struct xwos_thd_attr attr;
        xwos_thd_attr_init(&attr);
        attr.name = "xwsh.thd";
        attr.stack = stack;
        attr.stack_size = stack_size;
        attr.priority = XWSH_THD_PRIORITY;
        attr.detached = true;
        attr.privileged = true;
        return xwos_thd_init(&xwsh_thd, &xwsh_thdd, &attr,
                             xwsh_thd_mainfunc, NULL);
}

Thread main function (xwsh_thd_mainfunc):

• Displays system logo and version information
• Initializes CherryRL readline library
• Loops reading and executing commands
• Supports thread freeze (xwos_cthd_freeze())

Embedded Mode

void xwsh_init(void)
{
        xwsh_show_logo();      // Display logo
        xwsh_cherryrl_init();  // Initialize readline
}

void xwsh_loop(char * buf)
{
        char * line = xwsh_cherryrl_readline(buf);
        if (line != NULL) {
                xwsh_run_cmdline(line);  // Execute command
        }
}

Usage Pattern:

xwsh_init();
while (!exit_condition) {
    char buf[XWSH_MAXINPUT];
    xwsh_loop(buf);
    // Other task logic can be added here
}

Error Handling

XWSH follows the XWOS error handling specification; all APIs return xwer_t type error codes.

Common Error Codes

Error Handling Pattern

xwer_t example_function(type param)
{
        xwer_t rc = XWOK;
        
        if (!param) {
                rc = -EINVAL;
                goto err_param;
        }
        
        // Main logic
        // ...
        
        return XWOK;
        
err_param:
        return rc;
}

MISRA-C Compliance:

• At most two return statements per function
• Use goto for error cleanup
• Label naming: err_<reason>

Internal State Management

Command Table Management

// xwmd/cli/xwsh/core.c:36-37
static const struct xwsh_cmd * xwsh_ext_cmd_table = NULL;
static xwsz_t xwsh_ext_cmd_table_size = 0;

Lookup priority (xwsh_find_cmd()):

1. Internal command table (xwsh_cmd_table)
2. External command table (xwsh_ext_cmd_table)

Duplicate name check (xwsh_set_ext_cmd_table()):

1. External commands vs internal commands
2. Mutual check among external commands

Buffer Management

Resource Footprint Statistics

• Code size: Approximately 3-5 KB (depending on configuration)
• Stack space: Standalone mode requires 1-2 KB stack space
• Static memory: Approximately 1.2 KB (buffers)
• No dynamic memory allocation: Suitable for resource-constrained embedded environments

Performance Characteristics

Time Complexity Analysis

Memory Access Patterns

• Sequential access: Linear traversal of the string during command parsing
• Pointer reference: The argv array stores pointers without copying string content
• Cache-friendly: Contiguous memory layout, reducing cache misses

Design Constraints

Hard Limits

1. Input length: Single command line no more than 128 characters (XWSH_MAXINPUT)
2. Argument count: No more than 16 arguments (XWSH_MAX_PARAM_NUM)
3. History: At most 1024 bytes of history
4. Command name: No length limit, but must end with \0

Soft Constraints

1. Thread safety: External command table should be set before startup and is read-only at runtime
2. Context restrictions:
   • xwsh_start(): Interrupt, Interrupt Bottom Half, Thread
   • xwsh_init() / xwsh_loop(): Thread
3. Standard library dependency: Requires stdio.h for input/output