API 参考

概述

本文档提供 OpenOS 内核 API 的完整参考。

系统调用 API

系统调用总表

编号	名称	参数 1	参数 2	参数 3	返回值
1	`WRITE`	`buf: *const u8`	`len: u64`	—	已写入字节数
2	`READ`	`buf: *mut u8`	`len: u64`	—	已读取字节数
3	`EXIT`	`status: u64`	—	—	（不返回）
4	`YIELD`	—	—	—	`0`
5	`PORT_CREATE`	—	—	—	端口 ID
6	`SEND`	`port: u64`	`msg: *const u8`	`len: u64`	`0`
7	`RECEIVE`	`port: u64`	`buf: *mut u8`	`len: u64`	已读取字节数

错误码

代码	名称	说明
1	`EINVAL`	无效参数（空指针、零长度）
2	`EAGAIN`	资源暂时不可用
3	`EACCES`	权限不足
4	`ENOSYS`	系统调用未实现
5	`ESRCH`	任务/端口未找到
6	`ENOMEM`	内存不足
7	`EIPC`	IPC 传递失败

内核模块 API

arch/x86_64

gdt.rs

/// 初始化 GDT 和 TSS
pub fn init();

interrupts.rs

/// 初始化 IDT
pub fn init();

/// 中断处理函数类型
pub type InterruptHandler = extern "x86-interrupt" fn(InterruptStackFrame);

/// 注册中断处理函数
pub fn register_handler(interrupt: u8, handler: InterruptHandler);

drivers

vga.rs

/// 初始化 VGA 驱动
pub fn init();

/// 清屏
pub fn clear_screen();

/// 设置颜色
pub fn set_color(foreground: Color, background: Color);

/// 写入字符
pub fn write_char(c: char);

/// 写入字符串
pub fn write_string(s: &str);

/// VGA 打印宏
#[macro_export]
macro_rules! print { ... }

#[macro_export]
macro_rules! println { ... }

serial.rs

/// 初始化串口
pub fn init();

/// 读取字节
pub fn read_byte() -> u8;

/// 写入字节
pub fn write_byte(byte: u8);

/// 写入字符串
pub fn write_string(s: &str);

/// 串口打印宏
#[macro_export]
macro_rules! serial_print { ... }

#[macro_export]
macro_rules! serial_println { ... }

memory

allocator.rs

/// 堆起始地址
pub const HEAP_START: usize = 0x4444_4444_0000;

/// 堆大小
pub const HEAP_SIZE: usize = 100 * 1024;

/// 初始化堆
pub fn init_heap();

task

task.rs

/// 任务 ID
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct TaskId(u64);

impl TaskId {
    /// 创建新的任务 ID
    pub fn new() -> Self;

    /// 获取 u64 值
    pub fn as_u64(&self) -> u64;
}

/// 任务状态
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TaskState {
    Ready,
    Running,
    Blocked,
    Terminated,
}

/// 任务控制块
pub struct Task {
    pub id: TaskId,
    pub name: String,
    pub state: TaskState,
    pub priority: u8,
}

scheduler.rs

/// 调度器
pub struct Scheduler {
    ready_queue: VecDeque<TaskId>,
    current_task: Option<TaskId>,
}

impl Scheduler {
    /// 创建新的调度器
    pub fn new() -> Self;

    /// 添加任务
    pub fn add_task(&mut self, task_id: TaskId);

    /// 调度下一个任务
    pub fn schedule(&mut self) -> Option<TaskId>;

    /// 获取当前任务
    pub fn current_task(&self) -> Option<TaskId>;
}

syscall

mod.rs

/// 系统调用号
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum SyscallNumber {
    Write = 1,
    Read = 2,
    Exit = 3,
    Yield = 4,
    PortCreate = 5,
    Send = 6,
    Receive = 7,
}

/// 处理系统调用
pub fn handle_syscall(number: u64, arg1: u64, arg2: u64, arg3: u64) -> i64;

ipc

mod.rs

/// 消息数据类型
#[derive(Debug, Clone)]
pub enum MessageData {
    Text(String),
    Bytes(Vec<u8>),
    Request { id: u64, data: Vec<u8> },
    Response { id: u64, data: Vec<u8> },
}

/// 消息
#[derive(Debug, Clone)]
pub struct Message {
    pub sender: u64,
    pub receiver: u64,
    pub data: MessageData,
}

/// 端口
pub struct Port {
    pub id: u64,
    pub inbox: VecDeque<Message>,
}

/// IPC 管理器
pub struct IpcManager {
    ports: BTreeMap<u64, Port>,
}

impl IpcManager {
    /// 创建新的 IPC 管理器
    pub fn new() -> Self;

    /// 创建端口
    pub fn create_port(&mut self) -> u64;

    /// 发送消息
    pub fn send(&mut self, port_id: u64, message: Message) -> Result<(), Error>;

    /// 接收消息
    pub fn receive(&mut self, port_id: u64) -> Result<Message, Error>;
}

类型定义

基本类型

/// 物理地址
pub type PhysAddr = u64;

/// 虚拟地址
pub type VirtAddr = u64;

/// 页大小
pub const PAGE_SIZE: usize = 4096;

/// 帧大小
pub const FRAME_SIZE: usize = 4096;

错误类型

/// 错误类型
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Error {
    InvalidArgument,
    OutOfMemory,
    PermissionDenied,
    Busy,
    NotFound,
    Timeout,
    Internal,
    BadHandle,
    BadPointer,
    UnalignedPointer,
    BufferTooLarge,
    InvalidSyscall,
    ServiceNotFound,
    PoolExhausted,
}

impl core::fmt::Display for Error {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Error::InvalidArgument => write!(f, "Invalid argument"),
            Error::OutOfMemory => write!(f, "Out of memory"),
            Error::PermissionDenied => write!(f, "Permission denied"),
            Error::Busy => write!(f, "Resource busy"),
            Error::NotFound => write!(f, "Not found"),
            Error::Timeout => write!(f, "Timeout"),
            Error::Internal => write!(f, "Internal error"),
            Error::BadHandle => write!(f, "Bad handle"),
            Error::BadPointer => write!(f, "Bad pointer"),
            Error::UnalignedPointer => write!(f, "Unaligned pointer"),
            Error::BufferTooLarge => write!(f, "Buffer too large"),
            Error::InvalidSyscall => write!(f, "Invalid syscall"),
            Error::ServiceNotFound => write!(f, "Service not found"),
            Error::PoolExhausted => write!(f, "Pool exhausted"),
        }
    }
}

常量定义

内存地址

/// 内核偏移量
pub const KERNEL_OFFSET: u64 = 0xFFFFFFFF80000000;

/// 内核加载地址
pub const KERNEL_LOAD_ADDR: u64 = 0x100000;

/// 内核虚拟地址
pub const KERNEL_VIRTUAL_ADDR: u64 = KERNEL_OFFSET + KERNEL_LOAD_ADDR;

/// 堆起始地址
pub const HEAP_START: u64 = 0x4444_4444_0000;

/// 堆大小
pub const HEAP_SIZE: usize = 100 * 1024;

/// VGA 缓冲区地址
pub const VGA_BUFFER_ADDR: u64 = 0xB8000;

系统限制

/// 最大消息大小
pub const MAX_MESSAGE_SIZE: usize = 4096;

/// 最大 Handle 数量
pub const MAX_HANDLES: usize = 1024;

/// 最大端口数量
pub const MAX_PORTS: usize = 256;

/// 最大任务数量
pub const MAX_TASKS: usize = 64;

宏定义

打印宏

/// VGA 打印
#[macro_export]
macro_rules! print {
    ($($arg:tt)*) => ($crate::drivers::vga::_print(format_args!($($arg)*)));
}

/// VGA 打印（带换行）
#[macro_export]
macro_rules! println {
    () => ($crate::print!("\n"));
    ($($arg:tt)*) => ($crate::print!("{}\n", format_args!($($arg)*)));
}

/// 串口打印
#[macro_export]
macro_rules! serial_print {
    ($($arg:tt)*) => ($crate::drivers::serial::_print(format_args!($($arg)*)));
}

/// 串口打印（带换行）
#[macro_export]
macro_rules! serial_println {
    () => ($crate::serial_print!("\n"));
    ($($arg:tt)*) => ($crate::serial_print!("{}\n", format_args!($($arg)*)));
}

特征定义

设备特征

/// 字符设备
pub trait CharDevice {
    fn read_byte(&mut self) -> Option<u8>;
    fn write_byte(&mut self, byte: u8) -> Result<(), Error>;
    fn has_data(&self) -> bool;
}

/// 块设备
pub trait BlockDevice {
    fn read_block(&mut self, block: u64, buf: &mut [u8]) -> Result<(), Error>;
    fn write_block(&mut self, block: u64, buf: &[u8]) -> Result<(), Error>;
    fn block_size(&self) -> usize;
}

/// 网络设备
pub trait NetworkDevice {
    fn send_packet(&mut self, packet: &[u8]) -> Result<(), Error>;
    fn receive_packet(&mut self, buf: &mut [u8]) -> Result<usize, Error>;
    fn mac_address(&self) -> [u8; 6];
}

API 参考

概述

系统调用 API

系统调用总表

错误码

内核模块 API

arch/x86_64

gdt.rs

interrupts.rs

drivers

vga.rs

serial.rs

memory

allocator.rs

task

task.rs

scheduler.rs

syscall

mod.rs

ipc

mod.rs

类型定义

基本类型

错误类型

常量定义

内存地址

系统限制

宏定义

打印宏

特征定义

设备特征

相关文档