console_rust/

lib.rs

// Copyright 2026 The Fuchsia Authors
//
// Use of this source code is governed by a MIT-style
// license that can be found in the LICENSE file or at
// https://opensource.org/licenses/MIT

#![no_std]
#![allow(unsafe_op_in_unsafe_fn)]
#![allow(unused_crate_dependencies)]
#![cfg(console_enabled)]

use core::ffi::{c_char, c_int, c_void};
use core::sync::atomic::{AtomicBool, Ordering};
use zx_status::Status;

// Converts a Status to its raw FFI representation for the C boundary.
macro_rules! zx_status {
    ($status:expr) => {
        $status.into_raw()
    };
}

pub const CMD_AVAIL_NORMAL: u8 = 1 << 0;
pub const CMD_AVAIL_PANIC: u8 = 1 << 1;
pub const CMD_AVAIL_ALWAYS: u8 = CMD_AVAIL_NORMAL | CMD_AVAIL_PANIC;

// Command is happening at crash time.
pub const CMD_FLAG_PANIC: u32 = 1 << 0;

const BOOT_TEST_SUCCESS_STRING: &core::ffi::CStr = unsafe {
    core::ffi::CStr::from_bytes_with_nul_unchecked(
        concat!(env!("BOOT_TEST_SUCCESS_STRING"), "\0").as_bytes(),
    )
};

pub static ECHO: AtomicBool = AtomicBool::new(true);
pub static EXIT_CONSOLE: AtomicBool = AtomicBool::new(false);

#[repr(C)]
#[derive(Clone, Copy)]
pub struct CmdArgs {
    pub arg_str: *const c_char,
    pub arg_uint: core::ffi::c_ulong,
    pub arg_ptr: *mut c_void,
    pub arg_int: core::ffi::c_long,
    pub arg_bool: bool,
}

pub type CmdCallback = unsafe extern "C" fn(argc: c_int, argv: *const CmdArgs, flags: u32) -> c_int;

#[repr(C)]
pub struct Cmd {
    pub cmd_str: *const c_char,
    pub help_str: *const c_char,
    pub cmd_callback: CmdCallback,
    pub availability_mask: u8,
}

// Safety: Cmd structures placed in the commands section are read-only
// after boot and safe to share between threads.
unsafe impl Sync for Cmd {}

// Verify size and alignment compatibility with C++ structs.
zr::static_assert!(core::mem::size_of::<CmdArgs>() == 40);
zr::static_assert!(core::mem::align_of::<CmdArgs>() == 8);
zr::static_assert!(core::mem::size_of::<Cmd>() == 32);
zr::static_assert!(core::mem::align_of::<Cmd>() == 8);

#[cfg(console_enabled)]
#[macro_export]
macro_rules! commands_section {
    () => {
        ".data.rel.ro.commands"
    };
}

#[macro_export]
macro_rules! static_command {
    ($var_name:ident, $cmd:expr, $help:expr, $func:expr, $mask:expr) => {
        #[cfg(console_enabled)]
        #[used]
        #[unsafe(link_section = $crate::commands_section!())]
        pub static $var_name: $crate::Cmd = $crate::Cmd {
            cmd_str: $cmd,
            help_str: $help,
            cmd_callback: $func,
            availability_mask: $mask,
        };
    };
}

// FFI imports.
unsafe extern "C" {
    // Used to print directly to the kernel console without stack-allocated formatting buffers.
    fn printf(format: *const c_char, ...) -> c_int;
    fn cpp_console_get_lastresult() -> c_int;
}

// Statically registered commands.
static_command!(CMD_ECHO, c"echo".as_ptr(), core::ptr::null(), cmd_echo, CMD_AVAIL_ALWAYS);

static_command!(
    CMD_EXIT,
    c"exit".as_ptr(),
    c"exit the command processor".as_ptr(),
    cmd_exit,
    CMD_AVAIL_NORMAL
);

static_command!(
    CMD_TEST,
    c"test".as_ptr(),
    c"test the command processor".as_ptr(),
    cmd_test,
    CMD_AVAIL_ALWAYS
);

static_command!(
    CMD_GRACEFUL_SHUTDOWN,
    c"graceful-shutdown".as_ptr(),
    c"shut the system down gracefully".as_ptr(),
    cmd_graceful_shutdown,
    CMD_AVAIL_ALWAYS
);

static_command!(
    CMD_BOOT_TEST_SUCCESS,
    c"boot-test-success".as_ptr(),
    c"report boot-test success".as_ptr(),
    cmd_boot_test_success,
    CMD_AVAIL_ALWAYS
);

static_command!(
    CMD_AND,
    c"and".as_ptr(),
    c"execute command if last command succeeded".as_ptr(),
    cmd_and,
    CMD_AVAIL_ALWAYS
);

static_command!(
    CMD_REPEAT,
    c"repeat".as_ptr(),
    c"execute command in a loop for N loops or until error".as_ptr(),
    cmd_repeat,
    CMD_AVAIL_ALWAYS
);

static_command!(CMD_HELP, c"help".as_ptr(), c"this list".as_ptr(), cmd_help, CMD_AVAIL_ALWAYS);

// Callback implementations.
unsafe extern "C" fn cmd_echo(argc: c_int, argv: *const CmdArgs, _flags: u32) -> c_int {
    if argc > 1 {
        let args = core::slice::from_raw_parts(argv, argc as usize);
        ECHO.store(args[1].arg_bool, Ordering::Relaxed);
    }
    zx_status!(Status::OK)
}

unsafe extern "C" fn cmd_exit(_argc: c_int, _argv: *const CmdArgs, _flags: u32) -> c_int {
    rust_console_set_exit(true);
    zx_status!(Status::OK)
}

unsafe extern "C" fn cmd_test(argc: c_int, argv: *const CmdArgs, _flags: u32) -> c_int {
    let args = core::slice::from_raw_parts(argv, argc as usize);
    printf(c"argc %d, argv %p\n".as_ptr(), argc, argv);
    for (i, arg) in args.iter().enumerate() {
        printf(
            c"\t%d: str '%s', int %ld, uint %#lx, ptr %p, bool %d\n".as_ptr(),
            i as c_int,
            arg.arg_str,
            arg.arg_int,
            arg.arg_uint,
            arg.arg_ptr,
            arg.arg_bool as c_int,
        );
    }
    zx_status!(Status::OK)
}

unsafe extern "C" fn cmd_graceful_shutdown(
    _argc: c_int,
    _argv: *const CmdArgs,
    _flags: u32,
) -> c_int {
    // We use %c and format arguments here to prevent the compiler from optimizing the printf call
    // into puts or putchar, which are not defined in the kernel.
    printf(c"%c** Performing graceful shutdown from kernel shell... ***\n".as_ptr(), b'*' as c_int);
    const ZX_SEC_10: i64 = 10 * 1_000_000_000;
    let dlog_deadline = platform_rs::current_mono_time() + ZX_SEC_10;
    if let Err(status) = debuglog_rs::dlog_shutdown(dlog_deadline) {
        printf(c"debuglog shutdown failed: %d\n".as_ptr(), status.into_raw());
        // Proceed to platform_halt() even if debuglog_rs::dlog_shutdown() fails.
    }
    // Does not return.
    platform_rs::power::platform_halt(
        platform_rs::power::PlatformHaltAction::Shutdown,
        platform_rs::power::ZirconCrashReason::NoCrash,
    );
}

unsafe extern "C" fn cmd_boot_test_success(
    _argc: c_int,
    _argv: *const CmdArgs,
    _flags: u32,
) -> c_int {
    let last = cpp_console_get_lastresult();
    printf(c"*** Last script command result: %d ***\n".as_ptr(), last);
    if last == 0 {
        printf(c"%s%c".as_ptr(), BOOT_TEST_SUCCESS_STRING.as_ptr(), b'\n' as c_int);
    }
    last
}

unsafe fn get_commands() -> &'static [Cmd] {
    unsafe extern "C" {
        #[link_name = "__start_commands"]
        static __start_commands: Cmd;
        #[link_name = "__stop_commands"]
        static __stop_commands: Cmd;
    }
    let start = &__start_commands as *const Cmd;
    let stop = &__stop_commands as *const Cmd;
    let count = (stop as usize - start as usize) / core::mem::size_of::<Cmd>();
    unsafe { core::slice::from_raw_parts(start, count) }
}

unsafe fn match_command(name: *const c_char, availability_mask: u8) -> Option<&'static Cmd> {
    let commands = unsafe { get_commands() };
    let name_cstr = unsafe { core::ffi::CStr::from_ptr(name) };
    for cmd in commands {
        if (availability_mask & cmd.availability_mask) != 0 {
            let cmd_str_cstr = unsafe { core::ffi::CStr::from_ptr(cmd.cmd_str) };
            if cmd_str_cstr == name_cstr {
                return Some(cmd);
            }
        }
    }
    None
}

unsafe extern "C" fn cmd_and(argc: c_int, argv: *const CmdArgs, flags: u32) -> c_int {
    if argc < 2 {
        printf(c"Usage: and COMMAND...%c".as_ptr(), b'\n' as c_int);
        return zx_status!(Status::INVALID_ARGS);
    }

    let last = cpp_console_get_lastresult();
    if last != 0 {
        return last;
    }

    let args = core::slice::from_raw_parts(argv, argc as usize);
    let cmd = match match_command(args[1].arg_str, CMD_AVAIL_NORMAL) {
        Some(cmd) => cmd,
        None => {
            printf(c"command \"%s\" not found%c".as_ptr(), args[1].arg_str, b'\n' as c_int);
            return zx_status!(Status::NOT_FOUND);
        }
    };

    (cmd.cmd_callback)(argc - 1, argv.add(1), flags)
}

unsafe extern "C" fn cmd_repeat(argc: c_int, argv: *const CmdArgs, flags: u32) -> c_int {
    const MIN_ARGS: c_int = 3;
    if argc < MIN_ARGS {
        printf(c"Usage: repeat <iterations | -1> COMMAND...%c".as_ptr(), b'\n' as c_int);
        return zx_status!(Status::INVALID_ARGS);
    }

    let args = core::slice::from_raw_parts(argv, argc as usize);
    let cmd = match match_command(args[2].arg_str, CMD_AVAIL_NORMAL) {
        Some(cmd) => cmd,
        None => {
            printf(c"command \"%s\" not found%c".as_ptr(), args[2].arg_str, b'\n' as c_int);
            return zx_status!(Status::NOT_FOUND);
        }
    };

    // Negative arguments will cause it to effectively loop forever
    let iterations = if args[1].arg_int >= 0 { args[1].arg_uint as usize } else { usize::MAX };
    for i in 0..iterations {
        if iterations == usize::MAX {
            printf(c"repeat (%zu): %s".as_ptr(), i + 1, args[2].arg_str);
        } else {
            printf(c"repeat (%zu/%zu): %s".as_ptr(), i + 1, iterations, args[2].arg_str);
        }
        for arg in MIN_ARGS..argc {
            printf(c" %s".as_ptr(), args[arg as usize].arg_str);
        }
        // We use %c and format arguments here to prevent the compiler from optimizing the printf
        // call into puts or putchar, which are not defined in the kernel.
        printf(c"%c%s".as_ptr(), b'\n' as c_int, c"".as_ptr());

        let err = (cmd.cmd_callback)(argc - 2, argv.add(2), flags);
        if err != zx_status!(Status::OK) {
            printf(c"stopping repeat due to nonzero status %d%c".as_ptr(), err, b'\n' as c_int);
            return err;
        }
    }

    zx_status!(Status::OK)
}

unsafe extern "C" fn cmd_help(_argc: c_int, _argv: *const CmdArgs, flags: u32) -> c_int {
    let commands = unsafe { get_commands() };
    let count = commands.len();

    // Filter out commands based on if we're called at normal or panic time.
    let availability_mask =
        if (flags & CMD_FLAG_PANIC) != 0 { CMD_AVAIL_PANIC } else { CMD_AVAIL_NORMAL };

    unsafe {
        printf(c"command list:%c".as_ptr(), b'\n' as c_int);
    }

    // If we're not panicking (and are free to allocate memory), sort the
    // commands alphabetically before printing.
    if (flags & CMD_FLAG_PANIC) != 0 {
        for cmd in commands {
            if (availability_mask & cmd.availability_mask) != 0 {
                if !cmd.help_str.is_null() {
                    unsafe {
                        printf(
                            c"\t%-16s: %s%c".as_ptr(),
                            cmd.cmd_str,
                            cmd.help_str,
                            b'\n' as c_int,
                        );
                    }
                }
            }
        }
    } else {
        let mut ptrs_slice = match kalloc::Box::<[*const Cmd]>::try_new_zeroed_slice(count) {
            Ok(s) => s,
            Err(_) => return zx_status!(Status::NO_MEMORY),
        };
        for (i, cmd) in commands.iter().enumerate() {
            ptrs_slice[i] = cmd;
        }

        ptrs_slice.sort_unstable_by(|&a, &b| {
            let a_str = unsafe { core::ffi::CStr::from_ptr((*a).cmd_str) };
            let b_str = unsafe { core::ffi::CStr::from_ptr((*b).cmd_str) };
            a_str.cmp(b_str)
        });

        for &cmd_ptr in ptrs_slice.iter() {
            let cmd = unsafe { &*cmd_ptr };
            if (availability_mask & cmd.availability_mask) != 0 {
                if !cmd.help_str.is_null() {
                    unsafe {
                        printf(
                            c"\t%-16s: %s%c".as_ptr(),
                            cmd.cmd_str,
                            cmd.help_str,
                            b'\n' as c_int,
                        );
                    }
                }
            }
        }
    }

    zx_status!(Status::OK)
}

// FFI exports.
#[unsafe(no_mangle)]
pub extern "C" fn rust_console_get_echo() -> bool {
    ECHO.load(Ordering::Relaxed)
}

#[unsafe(no_mangle)]
pub extern "C" fn rust_console_get_exit() -> bool {
    EXIT_CONSOLE.load(Ordering::Relaxed)
}

#[unsafe(no_mangle)]
pub extern "C" fn rust_console_set_exit(val: bool) {
    EXIT_CONSOLE.store(val, Ordering::Relaxed);
}

/// # Safety
///
/// `name` must be a valid pointer to a null-terminated C string.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn rust_console_match_command(
    name: *const c_char,
    availability_mask: u8,
) -> *const Cmd {
    match match_command(name, availability_mask) {
        Some(cmd) => cmd,
        None => core::ptr::null(),
    }
}