Deshab-OS/RE/docs/tool_apps_design.md

Deshab 工具应用设计文档

1. 概述

Deshab 工具应用是独立开发、独立编译的 .elf 可执行文件，运行在桌面管理器（Desktop Manager）环境中。 每个工具在 CODE/tools/{name}/ 下拥有独立的 main.c + MAKEFILE + linker.ld， 通过 DSK 的 FAT32 + ELF loader 加载，接收 dsk_boot_context 系统上下文。

核心约束：

• 所有应用运行在 Ring0，单地址空间，无内存隔离
• 独立工具通过 dsk_entry(dsk_boot_context *ctx) 入口点启动
• 工具可以直接访问 framebuffer、PS/2 输入、kernel_api
• 网络工具依赖 kernel_api.net，文件工具依赖 FAT32 block_read
• 公共辅助代码通过 CODE/tools/desktop_app.h 共享

开发模式演进：

• 当前阶段：3 个内置应用（Bash/Editor/Calculator）使用回调模式编译在 desktop.elf 内
• 目标阶段：工具应用独立开发为单独 .elf，桌面管理器通过 ELF 加载方式载入

2. 应用 ABI

2.1 独立工具入口

独立工具 .elf 实现以下入口点：

__attribute__((visibility("default")))
void dsk_entry(const dsk_boot_context *ctx);

工具接收完整的 dsk_boot_context，包含：

typedef struct dsk_boot_context {
    u64 magic;                    /* 0x44534B31424F4F54 ("DSK1BOOT") */
    u32 abi_version;              /* 1 */
    u32 size;

    u64 flags;
    u64 hhdm_offset;
    u64 rsdp_address;

    u64 framebuffer_address;      /* 帧缓冲物理地址 (+ HHDM) */
    u64 framebuffer_width;
    u64 framebuffer_height;
    u64 framebuffer_pitch;
    u32 framebuffer_bpp;

    u64 boot_modules_response;
    u64 dkm_kernel_api;           /* DKM kernel_api 分发表 */
    u64 dkm_driver_table;
    u64 dkm_driver_count;

    u64 utsm_state;
    u64 drr_state;
    u64 memory_map;
    u64 memory_map_count;
    u64 memory_map_entry_size;
    u64 kernel_stack_top;
} dsk_boot_context;

2.2 公共辅助头文件

CODE/tools/desktop_app.h 提供所有工具共享的定义和辅助函数：

/* 类型定义 */
typedef unsigned char      u8;
typedef unsigned short     u16;
typedef unsigned int       u32;
typedef unsigned long long u64;
typedef long long          i64;

/* COM1 串口日志 */
#define COM1 0x3F8
static inline void outb(u16 port, u8 value);
static inline u8 inb(u16 port);
void sputc(char c);
void swrite(const char *s);
void slog(const char *s);

/* PS/2 键盘轮询 */
int ps2kbd_poll(u8 *scancode);    /* 返回 1=有数据 */

/* PS/2 鼠标轮询 */
int ps2mouse_poll(int *dx, int *dy, int *btn);  /* 返回 1=有数据包 */

/* scan code set 1 → ASCII 映射 */
char scan_to_ascii(u8 sc, int shift);

/* 帧缓冲绘制辅助 */
void fb_init(u64 addr, u64 w, u64 h, u64 pitch);
void fb_pixel(int x, int y, u32 color);
void fb_rect(int x, int y, int w, int h, u32 color);
void fb_string(const char *s, int x, int y, u32 fg, u32 bg, int step);

/* FAT32 文件读取辅助 */
typedef int (*block_read_fn)(u32 index, u64 lba, u32 count, void *buf);
int fat32_read_file(block_read_fn br, const char *path, u8 **data, u32 *size);

/* 窗口概念（标题栏+关闭按钮+客户区） */
#define WIN_TITLEBAR_H  28
#define WIN_BORDER_W    2
void win_draw_frame(int x, int y, int w, int h, const char *title, int focused);
int  win_hit_close(int wx, int wy, int ww, int wh, int mx, int my);

2.3 当前内置应用 ABI（回调模式）

当前 3 个内置应用编译在 desktop.elf 内，使用回调模式：

typedef struct app_ctx {
    du_context  *fb;              /* 全局帧缓冲渲染上下文 */
    desktop_win *win;             /* 关联窗口 */
    int          client_x, client_y, client_w, client_h;  /* 客户区坐标 */
    int          should_exit;     /* 退出标志 */
    desktop_block_read_fn block_read;   /* FAT32 块读取函数 */
    const void  *kernel_api;     /* DKM kernel_api 分发表 */
} app_ctx;

typedef void *(*app_create_fn)(app_ctx *ctx);
typedef void  (*app_event_fn)(void *state, app_ctx *ctx, desktop_event *ev);
typedef void  (*app_draw_fn)(void *state, app_ctx *ctx);
typedef void  (*app_destroy_fn)(void *state);

2.4 应用生命周期

回调式（当前）：

1. 用户点击图标/快速启动按钮
2. 桌面管理器创建窗口
3. 桌面调用 app->on_create(ctx) → 返回 app_state
4. 事件循环：桌面调用 app->on_event(app_state, ctx, ev)
5. 绘制：桌面调用 app->on_draw(app_state, ctx)
6. 用户关闭窗口 → 桌面调用 app->on_destroy(app_state)
7. 桌面销毁窗口，回收资源

独立 ELF 式（未来）：

1. 桌面管理器通过 FAT32 读取工具 .elf
2. PIE ELF loader 加载 + 重定位
3. 调用 dsk_entry(ctx)
4. 工具自行接管输入/渲染/主循环
5. 工具返回 → 桌面管理器恢复控制

3. 工具应用详细设计

3.1 终端 (Bash) — CODE/tools/bash/

状态：内置版本已实现（回调模式）；独立版本待开发

功能：

• 接收 dsk_boot_context，全屏暗色终端
• PS/2 键盘输入，命令历史（↑↓键）
• 内置命令：help, clear, echo, version/ver, uname, date, about, reboot, halt, pwd, whoami, id, ls, cat
• Sealed Arc 暗色主题（DS_DARK_* 色系）

UI 设计：

┌─ deshab# ────────────────────────────[✕]─┐
│ deshab# echo "Hello, Deshab!"            │
│ Hello, Deshab!                           │
│ deshab# _                                │
│                                          │
│                                          │
│                                          │
├──────────────────────────────────────────┤
│ /                          12:34         │
└──────────────────────────────────────────┘

独立版本结构：

• 标题栏：deshab# 标题 + 右侧红色 X 关闭按钮
• 主区域：暗色终端输出区 + 当前输入行 + 闪烁光标
• 状态栏（底部 20px）：左侧当前目录 /，右侧 RTC 时间

数据结构：

typedef struct {
    u8  ch[TERM_MAX_CHARS];       /* 字符缓冲 */
    u32 fg[TERM_MAX_CHARS];       /* 前景色缓冲 */
    int cols, rows;               /* 终端尺寸 */
    int cur_col, cur_row;         /* 当前光标位置 */
    char input_buf[256];          /* 当前输入行 */
    int input_len, input_cursor;  /* 输入长度和光标 */
    int prompt_len;               /* 提示符长度 */
    char history[16][256];        /* 命令历史 */
    int history_count;            /* 历史条数 */
    int history_pos;              /* 历史浏览位置 */
} bash_state;

命令实现：

命令	功能	依赖
help	显示可用命令列表	无
clear	清屏	无
echo	回显参数	无
version / ver	显示版本 "Deshab OS v0.1.0"	无
uname	显示系统名 "Deshab"	无
date	显示 RTC 日期时间	CMOS
about	显示系统信息	无
reboot	重启（0x64→0xFE）	键盘控制器
halt	停机（HLT）	无
pwd	显示当前目录 "/"	无
whoami	显示 "root"	无
id	显示 "uid=0(root) gid=0(root)"	无
ls	列出目录内容	FAT32 增强遍历
cat	显示文件内容	FAT32 读取

---

3.2 文本编辑器 (Editor) — CODE/tools/editor/

状态：内置版本已实现（回调模式）；独立版本待开发

功能：

• 全屏编辑器，行号 + 编辑区 + 状态栏
• FAT32 文件打开（通过 kernel_api block_read）
• 编辑操作：插入/删除字符、换行、光标移动（方向键/Home/End）
• PageUp/PageDown 翻页
• 文本选择：Shift+方向键
• Ctrl+S 保存（需 FAT32 write API）
• 状态栏：行:列、文件名、修改标记

UI 设计：

┌─ Editor — README.TXT ───────────────[✕]─┐
│  1│ # Deshab OS                         │
│  2│ 单地址空间 Ring0 内核实验系统         │
│  3│                                      │
│  4│ ## 概述                              │
│  5│ Deshab 是一个...█                    │
│  │ │                                     │
│  │ │                                     │
├───┴──────────────────────────────────────┤
│ L:5  C:15  README.TXT  *                 │
└──────────────────────────────────────────┘

数据结构：

typedef struct {
    char   text[EDITOR_BUF_SIZE];  /* 文本缓冲 (64KB) */
    int    text_len;                /* 文本长度 */
    int    cursor_pos;              /* 光标位置（字节偏移） */
    int    scroll_y;                /* 垂直滚动偏移（行数） */
    int    cursor_line;             /* 光标行号 */
    int    cursor_col;              /* 光标列号 */
    int    sel_start, sel_end;      /* 选择范围 */
    int    modified;                /* 修改标记 */
    char   filename[128];           /* 当前文件名 */
} editor_state;

渲染细节：

• 行号：3 位数字宽度（DS_DARK_TEXT_DIM 颜色）+ 1px 分隔线（DS_DARK_DIVIDER）
• 编辑区背景：DS_DARK_BG_SECONDARY
• 光标：2px 宽竖线，DS_DARK_CURSOR 颜色
• 状态栏：底部 20px，DP_ABYSS_800 背景，显示 L:行 C:列 文件名 *修改标记

---

3.3 文件管理器 (FileManager) — CODE/tools/fileman/

状态：占位（当前 desktop.elf 中 fileman 无回调）；独立版本待开发

功能：

• 双栏布局：左侧目录树、右侧文件列表
• FAT32 目录遍历（需增强到子目录）
• 文件图标区分：目录/ELF/TXT/CONF
• 双击打开：.txt/.conf → 编辑器，.elf → 执行
• 路径栏 + 返回按钮

UI 设计：

┌─ 文件管理器 ────────────────────────[✕]─┐
│ [←] /system/deshab64/                    │
├──────────┬───────────────────────────────┤
│ /        │ 📁 tools/          DIR        │
│ /system  │ 📄 desktop.elf    53KB  ELF   │
│ /driver  │ 📄 editor.elf     28KB  ELF   │
│          │ 📄 deshab.elf    131KB  ELF   │
│          │ 📄 README.TXT      2KB  TXT   │
│          │ 📄 user.conf       1KB  CONF  │
├──────────┴───────────────────────────────┤
│ 6 项                                     │
└──────────────────────────────────────────┘

文件图标颜色：

类型	图标	主色调
目录	📁	DP_ARC_500 (紫)
ELF	📄 + 可执行标记	DP_SEAL_300 (青)
TXT	📄 + 文本标记	DP_NEUTRAL_300 (灰)
CONF	📄 + 齿轮标记	DP_WARNING (琥珀)

依赖：FAT32 子目录遍历（当前 DSK 仅支持根目录读取，需增强）

---

3.4 浏览器 (Browser) — CODE/tools/browser/

状态：Phase 4 实现（依赖 TCP/IP + HTTP + HTML 渲染）

功能：

• 地址栏 + 导航按钮（后退/前进/刷新）
• HTTP GET 请求（通过 kernel_api.net）
• 简单 HTML 渲染：标题、段落、链接、列表
• 超链接点击导航
• 历史记录（后退/前进栈）

UI 设计：

┌─ 浏览器 ────────────────────────────[✕]─┐
│ [←][→][↻]  [http://example.com    ][Go] │
├──────────────────────────────────────────┤
│ Example Domain                           │
│                                          │
│ This domain is for use in illustrative   │
│ examples in documents. You may use this  │
│ domain in literature...                  │
│                                          │
│ More information...                      │
└──────────────────────────────────────────┘

依赖：

• TCP/IP 栈（需实现 TCP 连接、发送/接收、拥塞控制）
• HTTP/1.1 客户端（GET 请求、响应解析）
• DNS 解析（netman 已实现）
• HTML 解析器（简化版，仅处理常见标签）

---

3.5 HTTP 客户端 (curl) — CODE/tools/curl/

状态：Phase 3 实现（依赖 TCP/IP 最小实现）

功能：

• 命令行界面运行（终端风格）
• HTTP GET/HEAD 请求
• URL 解析（host:port/path）
• 响应头显示（-i 选项）
• 超时处理

命令行：

curl http://example.com
curl -i http://example.com
curl --head http://example.com

UI 设计：

┌─ curl ──────────────────────────────[✕]─┐
│ > curl http://example.com                │
│ HTTP/1.1 200 OK                          │
│ Content-Type: text/html                  │
│                                          │
│ <!doctype html>                          │
│ <html>                                   │
│ ...                                      │
└──────────────────────────────────────────┘

依赖：TCP/IP 栈 + DNS 解析

实现方式：作为窗口化终端风格应用运行，输出 HTTP 响应内容。

---

3.6 ICMP 工具 (ping) — CODE/tools/ping/

状态：Phase 3 实现（依赖 ICMP + ARP）

功能：

• 发送 ICMP Echo Request
• 接收 ICMP Echo Reply
• RTT 计算（基于 PIT 已校准计时器）
• 统计信息显示（发送/接收/丢包率/平均 RTT）

命令行：

ping 192.168.1.1
ping -c 4 10.0.2.2

UI 设计：

┌─ ping ──────────────────────────────[✕]─┐
│ PING 192.168.1.1                         │
│ 64 bytes: seq=0 time=2ms                 │
│ 64 bytes: seq=1 time=1ms                 │
│ 64 bytes: seq=2 time=3ms                 │
│                                          │
│ --- 192.168.1.1 ping statistics ---      │
│ 3 packets transmitted, 3 received, 0%    │
│ RTT min/avg/max = 1/2/3 ms              │
└──────────────────────────────────────────┘

依赖：

• ICMP 协议实现（需通过 kernel_api.net 发送原始 IP 包）
• ARP 解析（netman 已实现）
• 计时器（PIT 已校准）

---

3.7 更多应用（规划中）

应用	描述	Phase	依赖
System Monitor	CPU/内存/网络状态	2	kernel_api
Paint	简单绘图工具	2	无
Settings	系统偏好设置	2	FAT32 write
Screenshot	屏幕截图保存	3	FAT32 write
Music Player	PC 喇叭/AC97 音频	4	音频驱动

4. 依赖矩阵

           FAT32 Read | FAT32 Write | TCP/IP | ICMP | DNS | ARP | PS/2输入
bash          ✓       |             |        |      |     |     |    ✓
editor        ✓       |    (保存)    |        |      |     |     |    ✓
fileman       ✓       |             |        |      |     |     |    ✓
browser       ✓       |             |   ✓    |      |  ✓  |  ✓  |    ✓
curl          ✓       |             |   ✓    |      |  ✓  |  ✓  |    ✓
ping          ✓       |             |        |  ✓   |     |  ✓  |    ✓
calculator    |        |             |        |      |     |     |    ✓

5. 应用图标设计

每个应用使用 32×32 像素图标，程序化生成（C 函数绘制，无需位图文件）。

应用	图标描述	主色调	绘制函数
bash	终端窗口 >_	DP_SEAL_300 (亮青)	draw_icon_terminal()
editor	笔记本+文本行	DP_SEAL_500 (青)	draw_icon_editor()
fileman	文件夹	DP_ARC_500 (紫)	draw_icon_folder()
calculator	计算器按键	DP_WARNING (琥珀)	draw_icon_calc()
browser	地球/指南针	DP_SEAL_300 (亮青)	待实现
curl	箭头+网络	DP_SEAL_700 (深青)	待实现
ping	信号波	DP_SUCCESS (绿)	待实现

图标绘制规范：

• 圆角矩形背景（6px 圆角，DU_RADIUS_SM）
• 1px 描边（使用边框色）
• 前景图形使用应用主色调
• 背景色：DP_ABYSS_700

6. 构建集成

6.1 独立工具 MAKEFILE

每个工具有独立的 MAKEFILE（与 desktop.elf 相同模式）：

# tools/bash/MAKEFILE 示例
CC := clang
LD := ld.lld

ROOT := ../../..
OUT := $(ROOT)/SYSTEM/system/deshab64/tools/bash.elf

CFLAGS := -target x86_64-unknown-none -std=c11 -ffreestanding -fno-builtin \
          -fno-stack-protector -fpie -mno-red-zone -mno-sse -mno-sse2 \
          -mno-mmx -msoft-float -m64 -Wall -Wextra -I.. -I../../UTSM/include -O2
LDFLAGS := -nostdlib -static -pie -z max-page-size=0x1000 -T linker.ld

C_SOURCES := main.c
OBJECTS := $(C_SOURCES:.c=.o)

.PHONY: all clean

all: $(OUT)

$(OUT): $(OBJECTS) linker.ld
	@if not exist "$(ROOT)\SYSTEM\system\deshab64\tools" mkdir "$(ROOT)\SYSTEM\system\deshab64\tools"
	$(LD) $(LDFLAGS) -o $@ $(OBJECTS)

%.o: %.c
	$(CC) $(CFLAGS) -c $< -o $@

6.2 build.ps1 集成

在 build.ps1 中添加工具构建步骤：

# 构建工具应用
$tools = @("bash", "editor", "fileman", "curl", "ping", "browser")
foreach ($tool in $tools) {
    Push-Location "CODE/tools/$tool"
    & make -f MAKEFILE
    Pop-Location
}

6.3 FAT32 镜像更新

mkfat32.c 中添加工具 .elf 入口：

SYSTEM/system/deshab64/tools/bash.elf
SYSTEM/system/deshab64/tools/editor.elf
SYSTEM/system/deshab64/tools/fileman.elf
SYSTEM/system/deshab64/tools/curl.elf
SYSTEM/system/deshab64/tools/ping.elf
SYSTEM/system/deshab64/tools/browser.elf

7. 测试策略

• 单元测试：每个应用的事件处理回调可用模拟事件测试
• QEMU 集成测试：完整的启动→桌面→打开应用→操作→关闭流程
• 串口日志：所有应用通过 COM1 输出调试信息（[bash]、[editor] 等前缀）
• FAT32 验证：使用 driver/test.fat32 测试镜像验证文件读取功能
• 独立工具验证：DSK 直接加载工具 .elf，检查 dsk_entry 入口调用和上下文传递