LeonMMcoset/cleonos
1
0
Fork 0
mirror of https://github.com/Leonmmcoset/cleonos.git synced 2026-04-21 18:44:01 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
775a2f435d5217f98791bf21e836c79163c39258
cleonos/docs/syscall.md

316 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# CLeonOS Syscall 文档
本文档描述 CLeonOS 用户态通过 `int 0x80` 进入内核的 syscall ABI 与当前实现行为。
## 1. 调用约定（x86_64）
用户态统一通过：
```c
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/syscall.c`
## 2. 全局返回规则
- 成功时通常返回非负值（如长度、计数、状态）。
- 失败时多数接口返回 `0xFFFFFFFFFFFFFFFF`（即 `u64` 的 `-1`）。
- 部分接口失败返回 `0`（例如 `FS_READ` / `FS_WRITE` / `FS_APPEND` / `FS_REMOVE` / `LOG_JOURNAL_READ`）。
## 3. 当前实现中的长度/路径限制
以下限制由内核 `clks/kernel/syscall.c` 当前实现决定：
- 日志写入 `LOG_WRITE`：最大拷贝 `191` 字节。
- TTY 文本写入 `TTY_WRITE`：最大拷贝 `512` 字节。
- 文件读取 `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` 树下路径。
## 4. Syscall 列表（0~39）
### 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`
- 返回：子节点数量
### 11 `CLEONOS_SYSCALL_FS_GET_CHILD_NAME`
- 参数：
- `arg0`: `const char *dir_path`
- `arg1`: `u64 index`
- `arg2`: `char *out_name`
- 返回：成功 `1`，失败 `0`
- 说明：最多写入 96 字节（含终止符）。
### 12 `CLEONOS_SYSCALL_FS_READ`
- 参数：
- `arg0`: `const char *path`
- `arg1`: `char *out_buffer`
- `arg2`: `u64 buffer_size`
- 返回：实际读取字节数，失败/文件空返回 `0`
- 说明：不会自动追加 `\0`，调用方应自行处理文本终止。
### 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 位）
### 27 `CLEONOS_SYSCALL_FS_STAT_TYPE`
- 参数：
- `arg0`: `const char *path`
- 返回：`1=FILE`，`2=DIR`，失败 `-1`
### 28 `CLEONOS_SYSCALL_FS_STAT_SIZE`
- 参数：
- `arg0`: `const char *path`
- 返回：文件大小；目录通常为 `0`；失败 `-1`
### 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 热键切换计数
## 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_tty_write()`
- `cleonos_sys_kbd_get_char()` / `cleonos_sys_kbd_buffered()`
## 6. 开发注意事项
- 传入的字符串/缓冲指针目前按“同地址空间可直接访问”模型处理，后续若引入严格用户态地址隔离，需要补充用户内存校验。
- `FS_READ` 不保证文本终止符；读取文本请预留 1 字节并手动 `buf[n] = '\0'`。
- `FS_WRITE`/`FS_APPEND` 仅允许 `/temp`，并有单次长度上限。
Reference in New Issue View Git Blame Copy Permalink