API Reference

Overview

This document provides a complete reference for all API functions of the XWSH module. APIs are divided into two categories:

• Public API: Declared in mi.h, used by module consumers
• Internal API: Declared in core.h, used internally by the module or by advanced users

Public API

The public API provides the basic integration interface of the XWSH module, located in xwmd/cli/xwsh/mi.h.

Data Structures

struct xwsh_cmd

Command structure, used to define XWSH commands.

Definition (mi.h:21):

struct xwsh_cmd {
        char * name;                               /**< Command name */
        xwer_t (*func)(xwsz_t argc, char ** argv); /**< Command function */
        char * desc;                               /**< Command description */
};

Field Descriptions:

Usage Example:

const struct xwsh_cmd my_cmd = {
        .name = "test",
        .func = my_test_func,
        .desc = "test command description"
};

Macro Definitions

XWSH_MAXINPUT

Maximum number of characters that can be input in one command line.

Definition (mi.h:27):

#define XWSH_MAXINPUT 128U

Description:

• Value: 128 (bytes)
• Includes the terminator \0
• Input exceeding this length will be truncated or cause an error

Function Reference

xwsh_start()

Creates a new thread to run XWSH.

Prototype (mi.h:39):

xwer_t xwsh_start(xwstk_t * stack, xwsz_t stack_size);

Parameters:

Return Value:

Context Restrictions:

• Interrupt: Allowed
• Interrupt Bottom Half: Allowed
• Thread: Allowed

Note:

• This API cannot be used together with xwsh_init() and xwsh_loop()
• Thread priority is XWSH_THD_PRIORITY (realtime priority, downgraded 0 levels)
• Thread name is “xwsh.thd”, in detached state, with privileges

Example:

xwstk_t stack[1024];
xwer_t rc = xwsh_start(stack, sizeof(stack));
if (rc < 0) {
        printf("Failed to start XWSH: %d\r\n", rc);
}

xwsh_init()

Initializes XWSH (displays logo, initializes readline).

Prototype (mi.h:49):

void xwsh_init(void);

Parameters: None

Return Value: None

Context Restrictions:

• Interrupt: Not allowed
• Interrupt Bottom Half: Not allowed
• Thread: Allowed

Note:

• This API cannot be used together with xwsh_start()
• Before using this API, xwsh_set_ext_cmd_table() should be called to set external commands
• After calling this API, the system logo and version information will be displayed

Example:

xwsh_init();  // Displays "Welcome to the XWOS-Vx.x.x!"

xwsh_loop()

Runs the XWSH main loop in an existing thread.

Prototype (mi.h:59):

void xwsh_loop(char * buf);

Parameters:

Return Value: None

Context Restrictions:

• Interrupt: Not allowed
• Interrupt Bottom Half: Not allowed
• Thread: Allowed

Note:

• This API cannot be used together with xwsh_start()
• Before using this API, xwsh_init() must be called first
• The function blocks waiting for user input until a complete command line is received

Example:

char buf[XWSH_MAXINPUT];
xwsh_init();
while (1) {
        xwsh_loop(buf);  // Blocks waiting for command input
}

xwsh_set_ext_cmd_table()

Sets the external command table.

Prototype (mi.h:77):

xwer_t xwsh_set_ext_cmd_table(const struct xwsh_cmd cmd[], xwsz_t num);

Parameters:

Return Value:

Context Restrictions:

• Interrupt: Not allowed
• Interrupt Bottom Half: Not allowed
• Thread: Allowed

Note:

• This function should be called before XWSH starts (xwsh_start() or xwsh_init())
• External commands must not have the same name as built-in commands, and external commands must not have duplicate names among themselves
• If cmd is NULL and num is 0, the external command table is cleared
• Repeated calls are allowed; new settings overwrite the old command table

Example:

const struct xwsh_cmd my_cmds[] = {
        { .name = "test", .func = test_func, .desc = "test" },
};
xwer_t rc = xwsh_set_ext_cmd_table(my_cmds, 1);
if (rc < 0) {
        printf("Failed to set command table: %d\r\n", rc);
}

Internal API

The internal API provides access to XWSH core functionality, located in xwmd/cli/xwsh/core.h. These APIs are primarily for internal module use but can also be used by advanced users.

Macro Definitions

XWSH_MAX_PARAM_NUM

Maximum number of arguments supported by a single command.

Definition (core.h:18):

#define XWSH_MAX_PARAM_NUM 16U

Description:

• Value: 16 (including the command name itself)
• Arguments exceeding this count will result in -E2BIG error

Function Reference

xwsh_run_cmdline()

Parses and executes a single command line.

Prototype (core.h:20):

xwer_t xwsh_run_cmdline(char * line);

Parameters:

Return Value:

Context Restrictions:

• Interrupt: Allowed (but command functions may have restrictions)
• Interrupt Bottom Half: Allowed
• Thread: Allowed

Note:

• The function modifies the input string (replaces spaces with \0)
• Command lookup order: built-in commands → external commands
• If a command is not found, a message is output

Example:

char line[] = "help";
xwer_t rc = xwsh_run_cmdline(line);  // Execute the help command

xwsh_show_all_cmds()

Displays all available commands (built-in + external).

Prototype (core.h:21):

void xwsh_show_all_cmds(void);

Parameters: None

Return Value: None

Context Restrictions:

• Interrupt: Allowed (but output may be interrupted)
• Interrupt Bottom Half: Allowed
• Thread: Allowed

Note:

• Output format: command_name\tdescription\r\n
• Built-in commands are displayed first, then external commands
• This is the internal implementation of the help command

Example:

xwsh_show_all_cmds();
// Output:
// help    show this help
// clear   clear screen
// rd      read memory
// wr      write memory

xwsh_show_logo()

Displays the XWOS logo and version information.

Prototype (core.h:22):

void xwsh_show_logo(void);

Parameters: None

Return Value: None

Context Restrictions:

• Interrupt: Allowed (but output may be interrupted)
• Interrupt Bottom Half: Allowed
• Thread: Allowed

Note:

• Displays the XWOS ASCII art logo
• Displays welcome message and version number
• Displays compilation time (__DATE__ and __TIME__)

Example:

xwsh_show_logo();
// Output:
// [XWOS ASCII logo]
// Welcome to the XWOS-V1.0.0! Build time Feb 17 2026 10:30:00

CherryRL-related APIs

These APIs are declared in readline.h and are used to interact with the CherryRL library.

xwsh_cherryrl_init()

Initializes the CherryRL readline library.

Prototype (readline.h:18):

void xwsh_cherryrl_init(void);

Parameters: None

Return Value: None

Context Restrictions:

• Interrupt: Not allowed
• Interrupt Bottom Half: Not allowed
• Thread: Allowed

Note:

• Sets the colored prompt: “xwsh@xwos:>”
• Initializes the history buffer (1024 bytes)
• Sets input/output callback functions

xwsh_cherryrl_readline()

Reads a line of user input using CherryRL.

Prototype (readline.h:19):

char * xwsh_cherryrl_readline(char buffer[]);

Parameters:

Return Value:

Context Restrictions:

• Interrupt: Not allowed
• Interrupt Bottom Half: Not allowed
• Thread: Allowed

Note:

• The function blocks waiting for user input
• Supports history, line editing, auto-completion
• Buffer size should be at least XWSH_MAXINPUT

Command Handler Function Signature

All XWSH command handler functions must follow the following signature:

Prototype:

xwer_t command_handler(xwsz_t argc, char ** argv);

Parameters:

Return Value:

Context Restrictions: Determined by the specific command implementation

Example:

xwer_t my_command(xwsz_t argc, char ** argv)
{
        if (argc < 2) {
                printf("Usage: %s <param>\r\n", argv[0]);
                return -EINVAL;
        }
        
        printf("Parameter: %s\r\n", argv[1]);
        return XWOK;
}

Error Code Reference

XWSH uses standard XWOS error codes, defined in xwos/lib/errno.h.

Common Error Codes

Error Handling Pattern

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

Context Restriction Reference

Context Type Definitions

API Context Restriction Rules

1. Interrupt-safe API: Can be called in interrupt context, typically meeting the following conditions:

   • Non-blocking
   • No memory allocation
   • No thread synchronization primitives

2. Thread-safe API: Can be called in thread context, may:

   • Block and wait
   • Use synchronization mechanisms such as mutexes
   • Perform memory allocation

3. Mixed-context API: Allowed in some contexts, not allowed in others

Specific API Context Restrictions

Usage Examples

Complete Integration Example

#include <xwos/standard.h>
#include "xwmd/cli/xwsh/mi.h"
#include "xwmd/cli/xwsh/core.h"

/* Custom command */
xwer_t custom_cmd(xwsz_t argc, char ** argv)
{
        printf("Custom command executed\r\n");
        printf("argc: %d\r\n", argc);
        for (xwsz_t i = 0; i < argc; i++) {
                printf("argv[%d]: %s\r\n", i, argv[i]);
        }
        return XWOK;
}

/* Command table */
const struct xwsh_cmd ext_cmds[] = {
        { .name = "custom", .func = custom_cmd, .desc = "custom command" },
};

int main(void)
{
        xwer_t rc;
        
        /* 1. Set external command table (must be done before startup) */
        rc = xwsh_set_ext_cmd_table(ext_cmds, 
                                   sizeof(ext_cmds) / sizeof(ext_cmds[0]));
        if (rc < 0) {
                printf("Failed to set command table: %d\r\n", rc);
                return rc;
        }
        
        /* 2. Choose running mode */
#ifdef USE_STANDALONE_THREAD
        /* Standalone thread mode */
        xwstk_t stack[1024];
        rc = xwsh_start(stack, sizeof(stack));
        if (rc < 0) {
                printf("Failed to start XWSH: %d\r\n", rc);
                return rc;
        }
#else
        /* Embedded mode */
        char buf[XWSH_MAXINPUT];
        xwsh_init();
        while (1) {
                xwsh_loop(buf);
        }
#endif
        
        return 0;
}

Direct Command Execution Example

/* Directly execute commands without interactive Shell */
void execute_command_directly(void)
{
        char cmd1[] = "help";
        char cmd2[] = "rd 0x20000000 16";
        
        /* Execute help command */
        xwer_t rc = xwsh_run_cmdline(cmd1);
        if (rc < 0) {
                printf("Command failed: %d\r\n", rc);
        }
        
        /* Execute memory read command */
        rc = xwsh_run_cmdline(cmd2);
        if (rc < 0) {
                printf("Memory read failed: %d\r\n", rc);
        }
}

Version Compatibility

API Stability

Version History

Migration Guide

When migrating from older versions, please note:

1. Check if API signatures have changed
2. Update include paths (if changed)
3. Verify error handling logic
4. Test custom command compatibility