cleonos/docs/syscall.md

CLeonOS Syscall 文档

本文档描述 CLeonOS 用户态通过 int 0x80 进入内核的 syscall ABI 与当前实现行为。

1. 调用约定（x86_64）

用户态统一通过：

u64 cleonos_syscall(u64 id, u64 arg0, u64 arg1, u64 arg2);

寄存器约定：

• rax = syscall id
• rbx = arg0
• rcx = arg1
• rdx = arg2
• 返回值在 rax

中断向量：

• int 0x80

头文件位置：

• cleonos/c/include/cleonos_syscall.h

内核分发位置：

• clks/kernel/runtime/syscall.c

2. 全局返回规则

• 成功时通常返回非负值（如长度、计数、状态）。
• 失败时多数接口返回 0xFFFFFFFFFFFFFFFF（即 u64 的 -1）。
• 部分接口失败返回 0（例如 FS_READ / FS_WRITE / FS_APPEND / FS_REMOVE / LOG_JOURNAL_READ）。

进程退出状态补充（EXEC_PATH* / WAITPID）：

• 普通退出：返回值即用户程序退出码。
• 异常终止：返回值最高位为 1（1<<63），并编码：
• bits 7:0 = signal
• bits 15:8 = CPU exception vector
• bits 31:16 = exception error code 低 16 位

进程状态值（proc_snapshot.state）：

• 0 = UNUSED
• 1 = PENDING
• 2 = RUNNING
• 3 = EXITED
• 4 = STOPPED

常用信号值（PROC_KILL）：

• SIGKILL = 9
• SIGTERM = 15
• SIGCONT = 18
• SIGSTOP = 19

3. 当前实现中的长度/路径限制

以下限制由内核 clks/kernel/runtime/syscall.c 当前实现决定：

• 日志写入 LOG_WRITE：最大拷贝 191 字节。
• TTY 文本写入 TTY_WRITE：最大拷贝 2048 字节。
• 文件读取 FS_READ：最多读取 min(file_size, buffer_size) 字节。
• 文件写入 FS_WRITE / FS_APPEND：内核按 65536 字节分块搬运；这是实现分块大小，不是文件大小上限。
• log journal 行读取缓冲：256 字节。
• 路径缓冲上限：192 字节（包含 \0）。
• 文件名输出上限：96 字节（与 CLEONOS_FS_NAME_MAX 对齐）。

文件系统写入类 syscall 的权限限制：

• FS_MKDIR / FS_WRITE / FS_APPEND / FS_REMOVE 仅允许 /temp 树下路径，或已挂载磁盘路径树下（默认挂载点通常为 /temp/disk）。

UserSafeController（USC）危险 syscall 确认：

• USC 拦截到危险 syscall 时仍支持“仅本次 / 本会话 / 永久 / 拒绝”四种结果。
• 如果内核窗口管理器已初始化且桌面 TTY 正在前台，确认请求会以置顶桌面弹窗显示；可点击按钮，也可按 1/O、2/S、3/P、N/Esc/Enter 选择。
• 如果当前不在桌面环境、键盘被禁用，或弹窗创建失败，则回退到原 TTY/串口确认流程。

/proc 虚拟目录（由 syscall 层动态导出）：

• /proc：目录（children = self、list、以及全部 PID 名称）
• /proc/self：当前进程快照文本
• /proc/list：所有进程列表文本
• /proc/<pid>：指定 PID 快照文本
• /proc 为只读；写入类 syscall 不支持。

4. Syscall 列表（0~115）

0 CLEONOS_SYSCALL_LOG_WRITE

• 参数：
• arg0: const char *message
• arg1: u64 length
• 返回：实际写入长度
• 说明：写入内核日志通道（tag 为 SYSCALL），长度会被截断到 191。

1 CLEONOS_SYSCALL_TIMER_TICKS

• 参数：无
• 返回：系统 timer tick 计数

2 CLEONOS_SYSCALL_TASK_COUNT

• 参数：无
• 返回：任务总数

3 CLEONOS_SYSCALL_CUR_TASK

• 参数：无
• 返回：当前任务 ID

4 CLEONOS_SYSCALL_SERVICE_COUNT

• 参数：无
• 返回：服务总数

5 CLEONOS_SYSCALL_SERVICE_READY_COUNT

• 参数：无
• 返回：ready 服务数

6 CLEONOS_SYSCALL_CONTEXT_SWITCHES

• 参数：无
• 返回：上下文切换计数

7 CLEONOS_SYSCALL_KELF_COUNT

• 参数：无
• 返回：内核态 ELF 应用计数

8 CLEONOS_SYSCALL_KELF_RUNS

• 参数：无
• 返回：内核态 ELF 累计运行次数

9 CLEONOS_SYSCALL_FS_NODE_COUNT

• 参数：无
• 返回：VFS 节点总数

10 CLEONOS_SYSCALL_FS_CHILD_COUNT

• 参数：
• arg0: const char *dir_path
• 返回：子节点数量
• 说明：当 dir_path=/proc 时，返回 2 + proc_count（self、list、PID 子项）。

11 CLEONOS_SYSCALL_FS_GET_CHILD_NAME

• 参数：
• arg0: const char *dir_path
• arg1: u64 index
• arg2: char *out_name
• 返回：成功 1，失败 0
• 说明：最多写入 96 字节（含终止符）。
• 说明：当 dir_path=/proc 时，index=0/1 分别为 self/list，后续索引为 PID 文本。

12 CLEONOS_SYSCALL_FS_READ

• 参数：
• arg0: const char *path
• arg1: char *out_buffer
• arg2: u64 buffer_size
• 返回：实际读取字节数，失败/文件空返回 0
• 说明：不会自动追加 \0，调用方应自行处理文本终止。
• 说明：支持读取 /proc/self、/proc/list、/proc/<pid>。

13 CLEONOS_SYSCALL_EXEC_PATH

• 参数：
• arg0: const char *path
• 返回：
• -1：请求失败
• 其他：由内核执行器返回状态（通常 0 表示 accepted）

14 CLEONOS_SYSCALL_EXEC_REQUESTS

• 参数：无
• 返回：执行请求累计数

15 CLEONOS_SYSCALL_EXEC_SUCCESS

• 参数：无
• 返回：执行成功累计数

16 CLEONOS_SYSCALL_USER_SHELL_READY

• 参数：无
• 返回：用户 shell ready（1/0）

17 CLEONOS_SYSCALL_USER_EXEC_REQUESTED

• 参数：无
• 返回：是否发起过用户侧 exec 请求（1/0）

18 CLEONOS_SYSCALL_USER_LAUNCH_TRIES

• 参数：无
• 返回：用户态启动尝试次数

19 CLEONOS_SYSCALL_USER_LAUNCH_OK

• 参数：无
• 返回：用户态启动成功次数

20 CLEONOS_SYSCALL_USER_LAUNCH_FAIL

• 参数：无
• 返回：用户态启动失败次数

21 CLEONOS_SYSCALL_TTY_COUNT

• 参数：无
• 返回：TTY 总数

22 CLEONOS_SYSCALL_TTY_ACTIVE

• 参数：无
• 返回：当前 active TTY 索引

23 CLEONOS_SYSCALL_TTY_SWITCH

• 参数：
• arg0: u64 tty_index
• 返回：切换后的 active TTY 索引

24 CLEONOS_SYSCALL_TTY_WRITE

• 参数：
• arg0: const char *text
• arg1: u64 length
• 返回：实际写入长度
• 说明：长度会被截断到 512。

25 CLEONOS_SYSCALL_TTY_WRITE_CHAR

• 参数：
• arg0: u64 ch（低 8 位有效）
• 返回：当前实现固定返回 1

26 CLEONOS_SYSCALL_KBD_GET_CHAR

• 参数：无
• 返回：
• 无输入时 -1
• 有输入时返回字符值（低 8 位；按当前进程/TTY 上下文读取）

27 CLEONOS_SYSCALL_FS_STAT_TYPE

• 参数：
• arg0: const char *path
• 返回：1=FILE，2=DIR，失败 -1
• 说明：/proc 返回目录，/proc/self、/proc/list、/proc/<pid> 返回文件。

28 CLEONOS_SYSCALL_FS_STAT_SIZE

• 参数：
• arg0: const char *path
• 返回：文件大小；目录通常为 0；失败 -1
• 说明：/proc/* 文件大小按生成文本长度返回。

29 CLEONOS_SYSCALL_FS_MKDIR

• 参数：
• arg0: const char *path
• 返回：成功 1，失败 0
• 说明：仅允许 /temp 下创建目录。

30 CLEONOS_SYSCALL_FS_WRITE

• 参数：
• arg0: const char *path
• arg1: const char *data
• arg2: u64 size
• 返回：成功 1，失败 0
• 说明：覆盖写；仅允许 /temp 下文件。

31 CLEONOS_SYSCALL_FS_APPEND

• 参数：
• arg0: const char *path
• arg1: const char *data
• arg2: u64 size
• 返回：成功 1，失败 0
• 说明：追加写；仅允许 /temp 下文件。

32 CLEONOS_SYSCALL_FS_REMOVE

• 参数：
• arg0: const char *path
• 返回：成功 1，失败 0
• 说明：仅允许 /temp 下删除；目录需为空。

33 CLEONOS_SYSCALL_LOG_JOURNAL_COUNT

• 参数：无
• 返回：日志 journal 条目数量

34 CLEONOS_SYSCALL_LOG_JOURNAL_READ

• 参数：
• arg0: u64 index_from_oldest
• arg1: char *out_line
• arg2: u64 out_size
• 返回：成功 1，失败 0
• 说明：内核会保证输出字符串有 \0 终止。

35 CLEONOS_SYSCALL_KBD_BUFFERED

• 参数：无
• 返回：当前键盘队列中的字符数量

36 CLEONOS_SYSCALL_KBD_PUSHED

• 参数：无
• 返回：键盘累计入队计数

37 CLEONOS_SYSCALL_KBD_POPPED

• 参数：无
• 返回：键盘累计出队计数

38 CLEONOS_SYSCALL_KBD_DROPPED

• 参数：无
• 返回：键盘队列溢出丢弃计数

39 CLEONOS_SYSCALL_KBD_HOTKEY_SWITCHES

• 参数：无
• 返回：ALT+F1..F4 热键切换计数

40 CLEONOS_SYSCALL_GETPID

• 参数：无
• 返回：当前进程 PID（无活动进程时为 0）

41 CLEONOS_SYSCALL_SPAWN_PATH

• 参数：
• arg0: const char *path
• 返回：
• 成功：子进程 PID
• 失败：-1
• 说明：当前实现为异步 spawn（进入 pending 队列，后续由调度 tick 派发执行）。

42 CLEONOS_SYSCALL_WAITPID

• 参数：
• arg0: u64 pid
• arg1: u64 *out_status（可为 0）
• 返回：
• -1：PID 不存在
• 0：目标进程仍未退出（PENDING / RUNNING / STOPPED）
• 1：目标进程已退出
• 说明：当返回 1 且 arg1!=0 时，会写入退出码。

43 CLEONOS_SYSCALL_EXIT

• 参数：
• arg0: u64 status
• 返回：
• 1：已记录退出请求
• 0：当前上下文不支持退出请求

44 CLEONOS_SYSCALL_SLEEP_TICKS

• 参数：
• arg0: u64 ticks
• 返回：实际休眠 tick 数

45 CLEONOS_SYSCALL_YIELD

• 参数：无
• 返回：当前 tick

46 CLEONOS_SYSCALL_SHUTDOWN

• 参数：无
• 返回：理论上不返回；成功路径会触发关机流程（当前 x86_64 走 QEMU/ACPI 关机端口）
• 说明：若关机流程未生效，内核会进入 halt 循环。

47 CLEONOS_SYSCALL_RESTART

• 参数：无
• 返回：理论上不返回；成功路径会触发重启流程（当前 x86_64 走 8042 reset）
• 说明：若重启流程未生效，内核会进入 halt 循环。

48 CLEONOS_SYSCALL_AUDIO_AVAILABLE

• 参数：无
• 返回：
• 1：音频输出可用
• 0：当前平台无音频输出

49 CLEONOS_SYSCALL_AUDIO_PLAY_TONE

• 参数：
• arg0: u64 hz（频率，0 表示静音等待）
• arg1: u64 ticks（持续 tick）
• 返回：成功 1，失败 0
• 说明：当前实现基于 PC Speaker（x86_64），用于最小音频链路。

50 CLEONOS_SYSCALL_AUDIO_STOP

• 参数：无
• 返回：当前实现固定返回 1
• 说明：立即停止当前音频输出。

51 CLEONOS_SYSCALL_EXEC_PATHV

• 参数：
• arg0: const char *path
• arg1: const char *argv_line（可为 0）
• arg2: const char *env_line（可为 0）
• 返回：
• -1：请求失败
• 其他：目标程序退出状态
• 说明：argv_line 以空白分词，env_line 以 ; 或换行分隔条目。

52 CLEONOS_SYSCALL_SPAWN_PATHV

• 参数：
• arg0: const char *path
• arg1: const char *argv_line（可为 0）
• arg2: const char *env_line（可为 0）
• 返回：成功为子进程 PID，失败 -1

53 CLEONOS_SYSCALL_PROC_ARGC

• 参数：无
• 返回：当前进程 argc

54 CLEONOS_SYSCALL_PROC_ARGV

• 参数：
• arg0: u64 index
• arg1: char *out_value
• arg2: u64 out_size
• 返回：成功 1，失败 0
• 说明：单条参数字符串最大写入 128 字节（含终止符）。

55 CLEONOS_SYSCALL_PROC_ENVC

• 参数：无
• 返回：当前进程 envc

56 CLEONOS_SYSCALL_PROC_ENV

• 参数：
• arg0: u64 index
• arg1: char *out_value
• arg2: u64 out_size
• 返回：成功 1，失败 0
• 说明：单条环境变量字符串最大写入 128 字节（含终止符）。

57 CLEONOS_SYSCALL_PROC_LAST_SIGNAL

• 参数：无
• 返回：当前进程最近一次异常映射的信号号（无则 0）

58 CLEONOS_SYSCALL_PROC_FAULT_VECTOR

• 参数：无
• 返回：当前进程最近一次 CPU 异常向量号（无则 0）

59 CLEONOS_SYSCALL_PROC_FAULT_ERROR

• 参数：无
• 返回：当前进程最近一次 CPU 异常错误码（无则 0）

60 CLEONOS_SYSCALL_PROC_FAULT_RIP

• 参数：无
• 返回：当前进程最近一次 CPU 异常 RIP（无则 0）

61 CLEONOS_SYSCALL_PROC_COUNT

• 参数：无
• 返回：当前进程表中已使用槽位数量

62 CLEONOS_SYSCALL_PROC_PID_AT

• 参数：
• arg0: u64 index
• arg1: u64 *out_pid
• 返回：成功 1，失败 0
• 说明：用于枚举进程；index 超出范围返回 0。

63 CLEONOS_SYSCALL_PROC_SNAPSHOT

• 参数：
• arg0: u64 pid
• arg1: struct cleonos_proc_snapshot *out_snapshot
• arg2: u64 out_size（需 >= sizeof(cleonos_proc_snapshot)）
• 返回：成功 1，失败 0
• 说明：返回 PID/PPID/状态（含 STOPPED）/运行 tick/内存估算/TTY/路径等快照信息。

64 CLEONOS_SYSCALL_PROC_KILL

• 参数：
• arg0: u64 pid
• arg1: u64 signal（0 时按 SIGTERM(15) 处理）
• 返回：
• 1：请求成功
• 0：当前不可终止（例如非当前上下文中的 running 进程）
• -1：PID 不存在
• 语义：
• SIGTERM/SIGKILL（以及其它非 STOP/CONT 信号）：终止目标进程。
• SIGSTOP：将 PENDING 进程置为 STOPPED；对已 STOPPED 目标返回成功。
• SIGCONT：将 STOPPED 进程恢复为 PENDING。

65 CLEONOS_SYSCALL_KDBG_SYM

• 参数：
• arg0: u64 addr
• arg1: char *out_line
• arg2: u64 out_size
• 返回：写入字节数（含截断）
• 说明：将地址符号化为文本（含偏移与可选源码位置）。

66 CLEONOS_SYSCALL_KDBG_BT

• 参数：
• arg0: struct { u64 rbp; u64 rip; u64 out_ptr; u64 out_size; } *req
• 返回：写入字节数
• 说明：输出回溯文本；x86_64 下会尝试沿帧指针遍历。

67 CLEONOS_SYSCALL_KDBG_REGS

• 参数：
• arg0: char *out_text
• arg1: u64 out_size
• 返回：写入字节数
• 说明：输出最近一次 syscall 进入内核时的寄存器快照。

68 CLEONOS_SYSCALL_STATS_TOTAL

• 参数：无
• 返回：自启动以来的 syscall 总调用次数

69 CLEONOS_SYSCALL_STATS_ID_COUNT

• 参数：
• arg0: u64 id
• 返回：指定 syscall ID 的累计调用次数（ID 越界返回 0）

70 CLEONOS_SYSCALL_STATS_RECENT_WINDOW

• 参数：无
• 返回：最近窗口内样本数量
• 说明：当前内核实现窗口大小为 256 次 syscall。

71 CLEONOS_SYSCALL_STATS_RECENT_ID

• 参数：
• arg0: u64 id
• 返回：指定 syscall ID 在“最近窗口”中的出现次数（ID 越界返回 0）

72 CLEONOS_SYSCALL_FD_OPEN

• 参数：
• arg0: const char *path
• arg1: u64 flags
• arg2: u64 mode（当前保留）
• 返回：成功返回 fd，失败返回 -1
• 说明：
• 当前支持普通文件与设备文件：/dev/tty、/dev/null、/dev/zero、/dev/random、/dev/urandom。
• 默认进程会预置 fd 0/1/2（stdin/stdout/stderr）。
• 标志位兼容子集：O_RDONLY/O_WRONLY/O_RDWR/O_CREAT/O_TRUNC/O_APPEND。

73 CLEONOS_SYSCALL_FD_READ

• 参数：
• arg0: u64 fd
• arg1: void *out_buffer
• arg2: u64 size
• 返回：读取字节数；错误返回 -1
• 说明：
• 对 tty fd（如 stdin）为非阻塞读取：无输入时返回 0。
• 对文件 fd 为顺序读取，内部维护偏移。

74 CLEONOS_SYSCALL_FD_WRITE

• 参数：
• arg0: u64 fd
• arg1: const void *buffer
• arg2: u64 size
• 返回：写入字节数；错误返回 -1
• 说明：
• tty fd 输出到终端。
• 文件 fd 支持顺序写；O_APPEND 下始终追加。

75 CLEONOS_SYSCALL_FD_CLOSE

• 参数：
• arg0: u64 fd
• 返回：成功 0，失败 -1

76 CLEONOS_SYSCALL_FD_DUP

• 参数：
• arg0: u64 oldfd
• 返回：新 fd；失败 -1
• 说明：当前为“按值复制”语义（复制 flags/offset/目标对象）。

77 CLEONOS_SYSCALL_DL_OPEN

• 参数：
• arg0: const char *path
• 返回：动态库句柄（handle）；失败 -1
• 说明：将用户态动态库（ELF）加载到当前进程地址空间，供 DL_SYM 查询符号。

78 CLEONOS_SYSCALL_DL_CLOSE

• 参数：
• arg0: u64 handle
• 返回：成功 0，失败 -1
• 说明：关闭/释放由 DL_OPEN 返回的动态库句柄。

79 CLEONOS_SYSCALL_DL_SYM

• 参数：
• arg0: u64 handle
• arg1: const char *symbol
• 返回：符号地址（u64）；失败返回 0
• 说明：用于查询库导出符号入口地址。

80 CLEONOS_SYSCALL_EXEC_PATHV_IO

• 参数：
• arg0: const char *path
• arg1: const char *argv_line（可为 0）
• arg2: struct { u64 env_line_ptr; u64 stdin_fd; u64 stdout_fd; u64 stderr_fd; } *req
• 返回：与 EXEC_PATHV 一致（成功返回子进程退出状态，失败 -1）
• 说明：在 EXEC_PATHV 基础上增加 I/O 句柄重定向（用于管道与重定向）。

81 CLEONOS_SYSCALL_FB_INFO

• 参数：
• arg0: cleonos_fb_info *out_info
• 返回：成功 1，失败 0
• 说明：获取 framebuffer 信息（width/height/pitch/bpp）。out_info 为空或 framebuffer 未就绪时失败。

82 CLEONOS_SYSCALL_FB_BLIT

• 参数：
• arg0: const cleonos_fb_blit_req *req
• 返回：成功 1，失败 0
• 说明：
• 从用户态 pixels_ptr 指向的 32bpp 源缓冲拷贝到 framebuffer。
• src_pitch_bytes=0 时按 src_width*4 推导。
• 当前实现限制：src_width<=4096、src_height<=4096、scale<=8，且目标坐标需落在屏幕内。

83 CLEONOS_SYSCALL_FB_CLEAR

• 参数：
• arg0: u64 rgb（低 32 位有效）
• 返回：成功 1，失败 0
• 说明：用纯色清屏。

84 CLEONOS_SYSCALL_KERNEL_VERSION

• 参数：
• arg0: char *out_version
• arg1: u64 out_size
• 返回：实际写入字节数（不含终止符），失败返回 0
• 说明：返回 CLKS 内核版本字符串（当前默认 1.0.0-alpha），内核会保证输出以 \0 结尾。

85 CLEONOS_SYSCALL_DISK_PRESENT

• 参数：无
• 返回：1 表示存在可用磁盘后端，0 表示不存在。
• 说明：在 QEMU 运行时，磁盘后端来自模拟物理硬盘（-drive），不是 ISO/Limine module。

86 CLEONOS_SYSCALL_DISK_SIZE_BYTES

• 参数：无
• 返回：磁盘容量（字节）；无磁盘时返回 0。

87 CLEONOS_SYSCALL_DISK_SECTOR_COUNT

• 参数：无
• 返回：扇区总数（按 512 字节扇区）；无磁盘时返回 0。

88 CLEONOS_SYSCALL_DISK_FORMATTED

• 参数：无
• 返回：1 表示当前磁盘已识别为 FAT32，0 表示未格式化/不识别。

89 CLEONOS_SYSCALL_DISK_FORMAT_FAT32

• 参数：
• arg0: const char *label（可为 0 或空字符串）
• 返回：成功 1，失败 0
• 说明：将当前磁盘格式化为 FAT32；此操作会清空已有磁盘数据。该 syscall 在 USC 策略中默认视为高风险操作。

90 CLEONOS_SYSCALL_DISK_MOUNT

• 参数：
• arg0: const char *mount_path（绝对路径）
• 返回：成功 1，失败 0
• 说明：将 FAT32 磁盘挂载到指定路径（不能是 /）。挂载成功后，FS_* 接口可通过该路径访问磁盘内容。

91 CLEONOS_SYSCALL_DISK_MOUNTED

• 参数：无
• 返回：1 表示已挂载，0 表示未挂载。

92 CLEONOS_SYSCALL_DISK_MOUNT_PATH

• 参数：
• arg0: char *out_path
• arg1: u64 out_size
• 返回：实际写入字节数（不含终止符），失败返回 0
• 说明：查询当前挂载点路径；返回值为写入长度，且内核保证 \0 终止。

93 CLEONOS_SYSCALL_DISK_READ_SECTOR

• 参数：
• arg0: u64 lba
• arg1: void *out_sector（512 字节缓冲区）
• 返回：成功 1，失败 0
• 说明：按 LBA 读取单个扇区（512B）到用户缓冲区，常用于分区表/低级磁盘工具。

94 CLEONOS_SYSCALL_DISK_WRITE_SECTOR

• 参数：
• arg0: u64 lba
• arg1: const void *sector_data（512 字节缓冲区）
• 返回：成功 1，失败 0
• 说明：按 LBA 写入单个扇区（512B）。该 syscall 在 USC 策略中默认视为高风险操作。

95 CLEONOS_SYSCALL_NET_AVAILABLE

• 参数：无
• 返回：1 表示网络栈可用（e1000 初始化成功），0 表示不可用。

96 CLEONOS_SYSCALL_NET_IPV4_ADDR

• 参数：无
• 返回：当前 IPv4 地址（u32，以网络字节序放在返回值低 32 位）。
• 说明：优先使用 DHCP 自动获取地址；若 DHCP 失败回退到 10.0.2.15（QEMU usernet 常见默认值）。

97 CLEONOS_SYSCALL_NET_PING

• 参数：
• arg0: u64 dst_ipv4_be（目标 IPv4，网络字节序）
• arg1: u64 poll_budget（轮询预算；0 使用内核默认）
• 返回：成功收到 echo reply 返回 1，否则返回 0。

98 CLEONOS_SYSCALL_NET_UDP_SEND

• 参数：
• arg0: const struct { u64 dst_ipv4_be; u64 dst_port; u64 src_port; u64 payload_ptr; u64 payload_len; } *req
• 返回：实际发送 payload 字节数；失败返回 0。
• 说明：当前实现为最小 UDP 能力，payload_len 建议不超过 MTU 可承载范围。

99 CLEONOS_SYSCALL_NET_UDP_RECV

• 参数：
• arg0: struct { u64 out_payload_ptr; u64 payload_capacity; u64 out_src_ipv4_ptr; u64 out_src_port_ptr; u64 out_dst_port_ptr; } *req
• 返回：实际拷贝到 out_payload_ptr 的字节数；无数据/失败返回 0。
• 说明：out_src_*/out_dst_* 指针可为 0（表示不关心该字段）。

100 CLEONOS_SYSCALL_NET_NETMASK

• 参数：无
• 返回：当前 IPv4 子网掩码（u32，网络字节序，位于返回值低 32 位）。
• 说明：优先使用 DHCP 下发值；若 DHCP 未提供则按回退策略填充。

101 CLEONOS_SYSCALL_NET_GATEWAY

• 参数：无
• 返回：当前 IPv4 默认网关（u32，网络字节序，位于返回值低 32 位）。
• 说明：优先使用 DHCP 下发值；若 DHCP 未提供则按回退策略填充。

102 CLEONOS_SYSCALL_NET_DNS_SERVER

• 参数：无
• 返回：当前 DNS 服务器 IPv4（u32，网络字节序，位于返回值低 32 位）。
• 说明：优先使用 DHCP 下发值；若 DHCP 未提供则按回退策略填充。

103 CLEONOS_SYSCALL_NET_TCP_CONNECT

• 参数：
• arg0: const struct { u64 dst_ipv4_be; u64 dst_port; u64 src_port; u64 poll_budget; } *req
• 返回：连接成功返回 1，失败返回 0。
• 说明：最小 TCP 客户端连接能力（SYN/SYN-ACK/ACK）；src_port=0 时内核自动分配临时端口。

104 CLEONOS_SYSCALL_NET_TCP_SEND

• 参数：
• arg0: const struct { u64 payload_ptr; u64 payload_len; u64 poll_budget; } *req
• 返回：实际发送并确认的字节数；失败返回 0。
• 说明：当前实现为单连接发送路径，内部按分片发送并等待 ACK。

105 CLEONOS_SYSCALL_NET_TCP_RECV

• 参数：
• arg0: struct { u64 out_payload_ptr; u64 payload_capacity; u64 poll_budget; } *req
• 返回：实际拷贝到用户缓冲区的字节数；无数据/超时/失败返回 0。
• 说明：接收缓冲区上限受内核实现限制（当前 64 KiB）。

106 CLEONOS_SYSCALL_NET_TCP_CLOSE

• 参数：
• arg0: u64 poll_budget
• 返回：关闭成功返回 1，失败返回 0。
• 说明：最小关闭流程支持 FIN/ACK 轮询等待，超时会强制回收连接状态。

107 CLEONOS_SYSCALL_MOUSE_STATE

• 参数：
• arg0: struct { u64 x; u64 y; u64 buttons; u64 packet_count; u64 ready; } *out_state
• 返回：成功返回 1，失败返回 0。
• 说明：
• 读取当前鼠标状态快照，坐标为 framebuffer 像素坐标系（左上角为原点）。
• buttons 位掩码：bit0=left、bit1=right、bit2=middle。
• ready=1 表示鼠标设备已上线；ready=0 时坐标/按键可能为默认值。

108 CLEONOS_SYSCALL_WM_CREATE

• 参数：
• arg0: const struct { u64 x; u64 y; u64 width; u64 height; u64 flags; } *req
• 返回：成功返回非零 window_id，失败返回 0
• 说明：
• 创建一个由内核合成的窗口（当前在 TTY2 桌面合成器上显示）。
• x/y 为有符号坐标（按 i64 解释），width/height 为像素尺寸。

109 CLEONOS_SYSCALL_WM_DESTROY

• 参数：
• arg0: u64 window_id
• 返回：成功 1，失败 0
• 说明：销毁窗口并回收其事件队列与内核缓冲。

110 CLEONOS_SYSCALL_WM_PRESENT

• 参数：
• arg0: const struct { u64 window_id; u64 pixels_ptr; u64 src_width; u64 src_height; u64 src_pitch_bytes; } *req
• 返回：成功 1，失败 0
• 说明：
• 将用户态 ARGB/RGB32 像素缓冲提交到指定窗口内容区。
• 当前要求 src_width/src_height 与创建窗口时一致。

111 CLEONOS_SYSCALL_WM_POLL_EVENT

• 参数：
• arg0: u64 window_id
• arg1: struct cleonos_wm_event *out_event
• 返回：有事件时返回 1 并写入事件；无事件或失败返回 0
• 事件类型：
• 1 = FOCUS_GAINED
• 2 = FOCUS_LOST
• 3 = KEY（arg0 为按键值）
• 4 = MOUSE_MOVE（arg0/arg1 为全局坐标，arg2/arg3 为窗口局部坐标）
• 5 = MOUSE_BUTTON（arg0 为按钮状态位掩码，arg1 为变化掩码）

112 CLEONOS_SYSCALL_WM_MOVE

• 参数：
• arg0: const struct { u64 window_id; u64 x; u64 y; } *req
• 返回：成功 1，失败 0
• 说明：移动窗口到目标坐标（坐标按 i64 解释，内核会进行边界裁剪）。

113 CLEONOS_SYSCALL_WM_SET_FOCUS

• 参数：
• arg0: u64 window_id
• 返回：成功 1，失败 0
• 说明：将目标窗口置为焦点并提升到顶层 z-order。

114 CLEONOS_SYSCALL_WM_SET_FLAGS

• 参数：
• arg0: u64 window_id
• arg1: u64 flags
• 返回：成功 1，失败 0
• 说明：
• 设置窗口协议标志；当前支持 CLEONOS_WM_FLAG_TOPMOST（bit0），置位后窗口保持在普通窗口之上。

115 CLEONOS_SYSCALL_WM_RESIZE

• 参数：
• arg0: const struct { u64 window_id; u64 width; u64 height; } *req
• 返回：成功 1，失败 0
• 说明：
• 调整窗口尺寸并保持 window_id 不变；调整后用户态应重新 WM_PRESENT 一次提交新尺寸内容。

116 CLEONOS_SYSCALL_PTY_OPEN

• 参数：无
• 返回：成功返回一个可读写 FD，失败返回 (u64)-1
• 说明：
• 创建桌面伪 tty 输出端。用户态可把该 FD 传给 EXEC_PATHV_IO 的 stdout/stderr，然后通过 FD_READ 从同一 FD 读取子进程输出。
• 当前 PTY 是“命令输出捕获型”最小实现，不提供完整主从终端会话语义；阻塞式交互 shell 仍应继续使用普通 TTY。

5. 用户态封装函数

用户态封装位于：

• cleonos/c/src/syscall.c

常用封装示例：

• cleonos_sys_fs_read()
• cleonos_sys_fs_write() / cleonos_sys_fs_append() / cleonos_sys_fs_remove()
• cleonos_sys_log_journal_count() / cleonos_sys_log_journal_read()
• cleonos_sys_exec_path()
• cleonos_sys_exec_pathv()
• cleonos_sys_tty_write()
• cleonos_sys_kbd_get_char() / cleonos_sys_kbd_buffered()
• cleonos_sys_getpid() / cleonos_sys_spawn_path() / cleonos_sys_wait_pid()
• cleonos_sys_spawn_pathv()
• cleonos_sys_exit() / cleonos_sys_sleep_ticks() / cleonos_sys_yield() / cleonos_sys_shutdown() / cleonos_sys_restart()
• cleonos_sys_audio_available() / cleonos_sys_audio_play_tone() / cleonos_sys_audio_stop()
• cleonos_sys_proc_argc() / cleonos_sys_proc_argv() / cleonos_sys_proc_envc() / cleonos_sys_proc_env()
• cleonos_sys_proc_last_signal() / cleonos_sys_proc_fault_vector() / cleonos_sys_proc_fault_error() / cleonos_sys_proc_fault_rip()
• cleonos_sys_proc_count() / cleonos_sys_proc_pid_at() / cleonos_sys_proc_snapshot() / cleonos_sys_proc_kill()
• cleonos_sys_kdbg_sym() / cleonos_sys_kdbg_bt() / cleonos_sys_kdbg_regs()
• cleonos_sys_stats_total() / cleonos_sys_stats_id_count() / cleonos_sys_stats_recent_window() / cleonos_sys_stats_recent_id()
• cleonos_sys_fd_open() / cleonos_sys_fd_read() / cleonos_sys_fd_write() / cleonos_sys_fd_close() / cleonos_sys_fd_dup()
• cleonos_sys_dl_open() / cleonos_sys_dl_close() / cleonos_sys_dl_sym()
• cleonos_sys_exec_pathv_io()
• cleonos_sys_fb_info() / cleonos_sys_fb_blit() / cleonos_sys_fb_clear()
• cleonos_sys_kernel_version()
• cleonos_sys_disk_present() / cleonos_sys_disk_size_bytes() / cleonos_sys_disk_sector_count()
• cleonos_sys_disk_formatted() / cleonos_sys_disk_format_fat32() / cleonos_sys_disk_mount() / cleonos_sys_disk_mounted() / cleonos_sys_disk_mount_path()
• cleonos_sys_disk_read_sector() / cleonos_sys_disk_write_sector()
• cleonos_sys_net_available() / cleonos_sys_net_ipv4_addr() / cleonos_sys_net_netmask() / cleonos_sys_net_gateway() / cleonos_sys_net_dns_server() / cleonos_sys_net_ping()
• cleonos_sys_net_udp_send() / cleonos_sys_net_udp_recv()
• cleonos_sys_net_tcp_connect() / cleonos_sys_net_tcp_send() / cleonos_sys_net_tcp_recv() / cleonos_sys_net_tcp_close()
• cleonos_sys_mouse_state()
• cleonos_sys_wm_create() / cleonos_sys_wm_destroy() / cleonos_sys_wm_present()
• cleonos_sys_wm_poll_event() / cleonos_sys_wm_move() / cleonos_sys_wm_set_focus()
• cleonos_sys_pty_open()

6. 开发注意事项

• 传入的字符串/缓冲指针目前按“同地址空间可直接访问”模型处理，后续若引入严格用户态地址隔离，需要补充用户内存校验。
• FS_READ 不保证文本终止符；读取文本请预留 1 字节并手动 buf[n] = '\0'。
• FS_WRITE/FS_APPEND 仅允许 /temp 或已挂载磁盘路径；大数据写入由内核自动分块处理。
• /proc 由 syscall 层虚拟导出，不占用 RAMDISK 节点，也不能通过写入类 syscall 修改。

7. Wine 兼容说明

• wine/cleonos_wine_lib/runner.py 当前已覆盖到 0..116（含 DL_*、FB_*、KERNEL_VERSION、DISK_*、NET_*、MOUSE_STATE、WM_*、PTY_OPEN）。
• DL_*（77..79）在 Wine 中为“可运行兼容”实现：
• DL_OPEN：加载 guest ELF 到当前 Unicorn 地址空间，返回稳定 handle，并做引用计数。
• DL_SYM：解析 ELF SYMTAB/DYNSYM 并返回 guest 可调用地址。
• DL_CLOSE：引用计数归零后释放句柄。
• DL_* 兼容限制：未实现完整动态链接器语义（例如完整重定位/依赖库链），但对 CLeonOS 现有用户态库调用场景可工作。
• framebuffer syscall（81..83）在 Wine 中已实现兼容：
• FB_INFO 返回 framebuffer 参数（默认 1280x800x32，可用环境变量 CLEONOS_WINE_FB_WIDTH/HEIGHT 调整）。
• FB_BLIT 实现内核同类参数校验并支持 scale>=1 绘制。
• 配合 Wine 参数 --fb-window 可将 framebuffer 实时显示到主机窗口（pygame 后端）；未启用时保持内存缓冲模式。
• FB_CLEAR 支持清屏颜色写入。
• KERNEL_VERSION（84）在 Wine 中返回内核版本字符串（当前默认 1.0.0-alpha）。
• DISK_*（85..94）在 Wine 中已实现：
• 提供虚拟磁盘容量信息与 FAT32 格式化状态查询。
• DISK_FORMAT_FAT32 会初始化/重置 Wine rootfs 下的虚拟磁盘目录。
• DISK_MOUNT/DISK_MOUNT_PATH 支持挂载点管理，并与 FS_MKDIR/WRITE/APPEND/REMOVE 的路径规则联动。
• DISK_READ_SECTOR/DISK_WRITE_SECTOR（93..94）在 Wine 中已实现为 512B 原始扇区读写（host 文件后端）。
• 网络 syscall（95..106）在 Wine 当前为兼容占位实现（统一返回 0）；即 Wine 运行模式下不会提供真实网络收发。
• MOUSE_STATE（107）在 Wine 中为基础兼容实现：可返回指针数据结构；未启用窗口鼠标事件时 ready 可能为 0。
• WM_*（108..115）在 Wine 当前为兼容占位实现（统一返回 0）；不会创建真实窗口服务。
• PTY_OPEN（116）在 Wine 中创建内存缓冲 FD；写入端通过 FD_WRITE 追加，读取端通过 FD_READ 消费，用于桌面 Terminal 捕获子进程输出。
• Wine 在运行时崩溃场景下会生成与内核一致格式的“信号编码退出状态”，可通过 WAITPID 读取。
• Wine 当前音频 syscall 为占位实现：AUDIO_AVAILABLE=0，AUDIO_PLAY_TONE=0，AUDIO_STOP=1。
• Wine 版本号策略固定为 85.0.0-wine（历史兼容号；不会随 syscall 扩展继续增长）。