os/bootloader/docs/API_DOCUMENTATION.md

# NOS Bootloader API 文档

本文档提供NOS引导加载程序的公共API详细文档，包括使用示例和边界条件说明。

## 目录

- [核心模块](#核心模块)
- [基础设施层](#基础设施层)
- [应用层](#应用层)
- [领域层](#领域层)
- [图形子系统](#图形子系统)
- [引导菜单](#引导菜单)

## 核心模块

### 内存分配器 (`core::allocator`)

#### `DualLevelAllocator`

双级内存分配器，专为引导加载程序环境设计，结合了bump分配器和分离空闲列表的优势。

```rust
use nos_bootloader::core::allocator::DualLevelAllocator;

// 创建新的分配器
let allocator = DualLevelAllocator::new();

// 获取内存使用统计
let allocated = allocator.allocated();
let free = allocator.free();
let utilization = allocator.utilization();
```

**方法文档:**

- `new()`: 创建新的双级分配器实例
  - 返回: `DualLevelAllocator`
  - 注意: 分配器初始化为空堆，4MB大小

- `allocated()`: 获取已分配内存字节数
  - 返回: `usize`
  - 线程安全: 是，使用原子操作

- `free()`: 获取剩余可用内存字节数
  - 返回: `usize`
  - 计算: `BOOTLOADER_HEAP_SIZE - allocated()`

- `utilization()`: 获取内存利用率百分比
  - 返回: `f32` (0.0-100.0)
  - 公式: `(allocated / BOOTLOADER_HEAP_SIZE) * 100.0`

**边界条件:**
- 最大分配大小: 4MB
- 小块阈值: 256字节
- 对齐要求: 64字节边界
- 空闲列表最大条目: 1024

## 基础设施层

### 依赖注入容器 (`infrastructure::di_container`)

#### `BootDIContainer`

管理引导加载程序服务的生命周期和依赖关系，实现控制反转以提高可测试性。

```rust
use nos_bootloader::infrastructure::BootDIContainer;
use nos_bootloader::protocol::BootProtocolType;

// 创建并初始化容器
let mut container = BootDIContainer::new(BootProtocolType::Bios);
container.initialize()?;

// 获取服务
let hw_service = container.hardware_detection_service()?;
let graphics_backend = container.graphics_backend()?;
```

**方法文档:**

- `new(protocol_type)`: 创建新的DI容器
  - 参数: `protocol_type: BootProtocolType`
  - 返回: `BootDIContainer`
  - 说明: 根据协议类型初始化相应服务

- `initialize()`: 初始化所有服务
  - 返回: `Result<(), BootError>`
  - 错误: 初始化失败时返回错误

- `hardware_detection_service()`: 获取硬件检测服务
  - 返回: `Result<Box<dyn HardwareDetectionService>, BootError>`
  - 错误: 服务不可用时返回错误

### 图形后端 (`infrastructure::graphics_backend`)

#### `GraphicsBackend`

提供硬件无关的图形操作抽象，支持BIOS VBE和UEFI GOP。

```rust
use nos_bootloader::infrastructure::GraphicsBackend;

// 初始化图形后端
let mut backend = GraphicsBackend::new()?;

// 设置图形模式
let fb_info = backend.set_mode(1024, 768, 32)?;

// 获取帧缓冲区信息
let address = fb_info.address;
let width = fb_info.width;
let height = fb_info.height;
```

**方法文档:**

- `new()`: 创建新的图形后端实例
  - 返回: `Result<GraphicsBackend, BootError>`
  - 错误: 初始化失败时返回错误

- `set_mode(width, height, bpp)`: 设置图形模式
  - 参数:
    - `width: u16` - 宽度 (320-4096)
    - `height: u16` - 高度 (200-2160)
    - `bpp: u8` - 色深 (8, 16, 24, 32)
  - 返回: `Result<FramebufferInfo, BootError>`
  - 错误: 不支持的分辨率或色深

## 应用层

### 引导编排器 (`application::boot_orchestrator`)

#### `BootApplicationService`

高级服务，实现完整的引导序列，协调领域服务和基础设施组件。

```rust
use nos_bootloader::application::BootApplicationService;
use nos_bootloader::protocol::BootProtocolType;

// 创建引导应用服务
let mut service = BootApplicationService::new(BootProtocolType::Bios)?;

// 执行完整引导序列
let boot_info = service.boot_system(Some("quiet splash"))?;

// 获取硬件检测服务
let hw_service = service.hardware_detection_service();
let hw_info = hw_service.detect_hardware()?;
```

**方法文档:**

- `new(protocol_type)`: 创建新的引导应用服务
  - 参数: `protocol_type: BootProtocolType`
  - 返回: `Result<BootApplicationService, BootError>`
  - 错误: 初始化失败时返回错误

- `boot_system(cmdline)`: 执行完整引导序列
  - 参数: `cmdline: Option<&str>` - 内核命令行
  - 返回: `Result<BootInfo, BootError>`
  - 流程:
    1. 加载配置
    2. 检测硬件
    3. 验证先决条件
    4. 初始化图形
    5. 创建引导信息
    6. 验证引导信息

- `hardware_detection_service()`: 获取硬件检测服务引用
  - 返回: `&dyn HardwareDetectionService`
  - 说明: 遵循依赖倒置原则

## 领域层

### 引导配置 (`domain::boot_config`)

#### `BootConfig`

不可变配置值对象，封装所有引导加载程序配置。

```rust
use nos_bootloader::domain::boot_config::{BootConfig, GraphicsMode, LogLevel};

// 创建默认配置
let config = BootConfig::default();

// 验证配置
config.validate()?;

// 创建自定义图形模式
let mode = GraphicsMode::new(1920, 1080, 32)?;
```

#### `GraphicsMode`

图形显示模式值对象，表示有效的图形显示设置。

```rust
use nos_bootloader::domain::boot_config::GraphicsMode;

// 创建图形模式
let mode = GraphicsMode::new(1024, 768, 32)?;

// 检查是否为高分辨率
if mode.is_high_resolution() {
    println!("高分辨率模式");
}

// 计算帧缓冲区大小
let fb_size = mode.framebuffer_size();
let scanline_bytes = mode.scanline_bytes();
```

**方法文档:**

- `new(width, height, bpp)`: 创建新的图形模式
  - 参数:
    - `width: u16` - 宽度 (320-4096)
    - `height: u16` - 高度 (200-2160)
    - `bpp: u8` - 色深 (8, 16, 24, 32)
  - 返回: `Result<GraphicsMode, &'static str>`
  - 错误: 无效的分辨率或色深

- `is_high_resolution()`: 检查是否为高分辨率模式
  - 返回: `bool`
  - 条件: width >= 1024 && height >= 768

- `scanline_bytes()`: 获取扫描线字节数（64字节对齐）
  - 返回: `usize`
  - 计算: `((width * bytes_per_pixel + 63) / 64) * 64`

- `framebuffer_size()`: 获取总帧缓冲区大小
  - 返回: `usize`
  - 计算: `scanline_bytes() * height`

#### `MemoryRegion`

内存区域值对象，表示内存区域及其类型和属性。

```rust
use nos_bootloader::domain::boot_config::{MemoryRegion, MemoryRegionType};

// 创建可用内存区域
let region = MemoryRegion::new(0x100000, 0x1000000, MemoryRegionType::Available)?;

// 检查区域大小
let size = region.size();

// 检查是否包含特定地址
if region.contains(0x200000) {
    println!("地址在区域内");
}

// 检查与另一个区域是否重叠
let other = MemoryRegion::new(0x200000, 0x300000, MemoryRegionType::Reserved)?;
if region.overlaps(&other) {
    println!("区域重叠");
}
```

**方法文档:**

- `new(start, end, region_type)`: 创建新的内存区域
  - 参数:
    - `start: u64` - 起始物理地址
    - `end: u64` - 结束物理地址（不包含）
    - `region_type: MemoryRegionType` - 区域类型
  - 返回: `Result<MemoryRegion, &'static str>`
  - 错误: start >= end 时返回错误

- `size()`: 获取内存区域大小
  - 返回: `u64`
  - 计算: `end - start`

- `overlaps(other)`: 检查与另一个区域是否重叠
  - 参数: `other: &MemoryRegion`
  - 返回: `bool`
  - 条件: `start < other.end && other.start < end`

- `contains(addr)`: 检查是否包含特定地址
  - 参数: `addr: u64`
  - 返回: `bool`
  - 条件: `addr >= start && addr < end`

### 引导信息 (`domain::boot_info`)

#### `BootInfo`

引导信息聚合根，包含传递给内核的所有信息。

```rust
use nos_bootloader::domain::boot_info::BootInfo;
use nos_bootloader::protocol::BootProtocolType;

// 创建新的引导信息
let mut boot_info = BootInfo::new(BootProtocolType::Bios);

// 设置内核信息
boot_info.kernel_address = 0x100000;
boot_info.kernel_size = 0x500000;
boot_info.boot_timestamp = 0;

// 验证引导信息
boot_info.validate()?;
```

## 图形子系统

### 图形渲染器 (`graphics`)

#### `GraphicsRenderer`

ARGB8888帧缓冲区的图形渲染器，支持双缓冲。

```rust
use nos_bootloader::graphics::{GraphicsRenderer, FramebufferInfo, Color};

// 创建帧缓冲区信息
let fb_info = FramebufferInfo::new(0x10000000, 1024, 768, 4096, 32);

// 创建图形渲染器
let mut renderer = GraphicsRenderer::new_with_double_buffer(fb_info)?;

// 初始化帧缓冲区
renderer.initialize_framebuffer()?;

// 清屏
renderer.clear_screen(Color::black())?;

// 绘制像素
renderer.draw_pixel(100, 100, Color::red())?;

// 绘制水平线
renderer.draw_h_line(50, 50, 100, Color::green())?;

// 绘制垂直线
renderer.draw_v_line(150, 50, 100, Color::blue())?;

// 绘制填充矩形
renderer.draw_filled_rect(200, 200, 100, 50, Color::white())?;

// 开始渲染会话
renderer.begin_render()?;

// 执行绘制操作...

// 结束渲染会话
renderer.end_render()?;

// 交换缓冲区
renderer.swap_buffers()?;
```

**方法文档:**

- `new(fb)`: 创建新的图形渲染器
  - 参数: `fb: FramebufferInfo` - 帧缓冲区信息
  - 返回: `GraphicsRenderer`

- `new_with_double_buffer(fb)`: 创建带双缓冲的图形渲染器
  - 参数: `fb: FramebufferInfo` - 帧缓冲区信息
  - 返回: `Result<GraphicsRenderer, &'static str>`
  - 错误: 后台缓冲区分配失败

- `initialize_framebuffer()`: 初始化帧缓冲区（零填充）
  - 返回: `Result<(), &'static str>`
  - 错误: 帧缓冲区地址为空

- `clear_screen(color)`: 用单一颜色清屏
  - 参数: `color: Color` - 清屏颜色
  - 返回: `Result<(), &'static str>`
  - 错误: 帧缓冲区地址为空

- `draw_pixel(x, y, color)`: 在坐标处绘制单个像素
  - 参数:
    - `x: u32` - X坐标
    - `y: u32` - Y坐标
    - `color: Color` - 像素颜色
  - 返回: `Result<(), &'static str>`
  - 错误: 坐标超出边界或地址为空

- `draw_h_line(x, y, length, color)`: 绘制水平线
  - 参数:
    - `x: u32` - 起始X坐标
    - `y: u32` - Y坐标
    - `length: u32` - 线长度
    - `color: Color` - 线颜色
  - 返回: `Result<(), &'static str>`
  - 错误: 起始坐标超出边界

- `draw_v_line(x, y, length, color)`: 绘制垂直线
  - 参数:
    - `x: u32` - X坐标
    - `y: u32` - 起始Y坐标
    - `length: u32` - 线长度
    - `color: Color` - 线颜色
  - 返回: `Result<(), &'static str>`
  - 错误: 起始坐标超出边界

- `draw_filled_rect(x, y, width, height, color)`: 绘制填充矩形
  - 参数:
    - `x: u32` - 矩形X坐标
    - `y: u32` - 矩形Y坐标
    - `width: u32` - 矩形宽度
    - `height: u32` - 矩形高度
    - `color: Color` - 填充颜色
  - 返回: `Result<(), &'static str>`
  - 错误: 起始坐标超出边界

#### `Color`

ARGB8888颜色表示。

```rust
use nos_bootloader::graphics::Color;

// 创建不透明RGB颜色
let red = Color::rgb(255, 0, 0);
let green = Color::rgb(0, 255, 0);
let blue = Color::rgb(0, 0, 255);

// 创建ARGB颜色
let semi_transparent_red = Color::argb(128, 255, 0, 0);

// 转换为ARGB8888格式
let argb_value = red.as_argb8888();

// 使用预定义颜色
let black = Color::black();
let white = Color::white();
```

**方法文档:**

- `rgb(red, green, blue)`: 创建不透明RGB颜色
  - 参数:
    - `red: u8` - 红色分量 (0-255)
    - `green: u8` - 绿色分量 (0-255)
    - `blue: u8` - 蓝色分量 (0-255)
  - 返回: `Color`
  - 说明: Alpha分量自动设置为255（不透明）

- `argb(alpha, red, green, blue)`: 创建ARGB颜色
  - 参数:
    - `alpha: u8` - Alpha分量 (0-255)
    - `red: u8` - 红色分量 (0-255)
    - `green: u8` - 绿色分量 (0-255)
    - `blue: u8` - 蓝色分量 (0-255)
  - 返回: `Color`

- `as_argb8888()`: 转换为ARGB8888 u32格式
  - 返回: `u32`
  - 格式: `0xAARRGGBB`

#### `DoubleBuffer`

双缓冲管理器，提供无闪烁渲染和脏区域跟踪。

```rust
use nos_bootloader::graphics::{DoubleBuffer, FramebufferInfo};

// 创建帧缓冲区信息
let fb_info = FramebufferInfo::new(0x10000000, 1024, 768, 4096, 32);

// 创建双缓冲管理器
let mut double_buffer = DoubleBuffer::new(fb_info)?;

// 开始渲染会话
double_buffer.begin_render()?;

// 执行渲染操作...

// 结束渲染会话
double_buffer.end_render()?;

// 交换缓冲区
double_buffer.swap_buffers()?;

// 启用/禁用脏区域跟踪
double_buffer.set_dirty_tracking(true);
```

**方法文档:**

- `new(fb_info)`: 创建新的双缓冲管理器
  - 参数: `fb_info: FramebufferInfo` - 帧缓冲区信息
  - 返回: `Result<DoubleBuffer, &'static str>`
  - 错误: 帧缓冲区地址为空或后台缓冲区分配失败

- `begin_render()`: 开始渲染会话
  - 返回: `Result<(), &'static str>`
  - 错误: 已在渲染状态

- `end_render()`: 结束渲染会话
  - 返回: `Result<(), &'static str>`
  - 错误: 不在渲染状态

- `swap_buffers()`: 交换缓冲区
  - 返回: `Result<(), &'static str>`
  - 错误: 正在渲染时不能交换

- `set_dirty_tracking(enabled)`: 启用/禁用脏区域跟踪
  - 参数: `enabled: bool` - 是否启用脏区域跟踪

### VBE支持 (`graphics::vbe`)

#### `VbeController`

VESA BIOS扩展(VBE)控制器接口，支持模式缓存。

```rust
use nos_bootloader::graphics::vbe::{VbeController, VBE_MODE_1024x768x32};

// 创建VBE控制器
let mut controller = VbeController::new();

// 初始化控制器
controller.initialize()?;

// 设置图形模式
let fb_info = controller.set_graphics_mode(1024, 768, 32)?;

// 查找最佳模式
let mode = controller.find_best_mode(1920, 1080, 32);

// 获取支持的模式列表
let modes = controller.get_supported_modes();
```

**方法文档:**

- `new()`: 创建新的VBE控制器
  - 返回: `VbeController`

- `initialize()`: 初始化VBE控制器
  - 返回: `Result<(), BootError>`
  - 错误: VBE控制器信息获取失败或签名无效

- `set_graphics_mode(width, height, bpp)`: 设置图形模式
  - 参数:
    - `width: u16` - 宽度
    - `height: u16` - 高度
    - `bpp: u8` - 色深
  - 返回: `Result<FramebufferInfo, BootError>`
  - 错误: 未初始化或未找到合适模式

- `find_best_mode(width, height, bpp)`: 查找最佳VBE模式
  - 参数:
    - `width: u16` - 期望宽度
    - `height: u16` - 期望高度
    - `bpp: u8` - 期望色深
  - 返回: `Option<u16>`
  - 说明: 首先尝试精确匹配，然后尝试更高分辨率

## 引导菜单

### 统一引导菜单 (`boot_menu`)

#### `BootMenu`

统一引导菜单接口，支持图形和文本UI模式。

```rust
use nos_bootloader::boot_menu::{BootMenu, UIMode, MenuOption};

// 创建文本模式引导菜单
let mut menu = BootMenu::new(UIMode::Text);

// 初始化菜单
menu.initialize()?;

// 添加自定义选项
let custom_option = MenuOption::new(4, "Custom", "Custom boot option");
menu.add_option(custom_option)?;

// 处理输入
let selected_id = menu.process_input(b'\n');

// 获取当前选中项
if let Some(selected) = menu.get_selected() {
    println!("选中: {}", selected.name);
}
```

**方法文档:**

- `new(mode)`: 创建新的引导菜单
  - 参数: `mode: UIMode` - UI模式（图形/文本/串行）
  - 返回: `BootMenu`

- `initialize()`: 初始化菜单（延迟初始化以提高性能）
  - 返回: `Result<(), BootError>`
  - 说明: 添加默认引导选项

- `add_option(option)`: 添加菜单选项
  - 参数: `option: MenuOption` - 菜单选项
  - 返回: `Result<(), BootError>`
  - 错误: 菜单选项已满（最多8个）

- `process_input(key)`: 处理键盘输入
  - 参数: `key: u8` - 按键码
  - 返回: `Option<u8>` - 选中的选项ID
  - 说明: 支持上下箭头导航和回车选择

- `render_graphical(renderer)`: 在图形模式下渲染菜单
  - 参数: `renderer: &mut GraphicsRenderer` - 图形渲染器
  - 返回: `Result<(), BootError>`

- `render_text()`: 在文本模式下渲染菜单
  - 返回: `Result<(), BootError>`

#### `MenuOption`

引导菜单选项。

```rust
use nos_bootloader::boot_menu::MenuOption;

// 创建简单菜单选项
let option1 = MenuOption::new(1, "Boot", "Normal boot");

// 创建带回调的菜单选项
let option2 = MenuOption::with_callback(
    2,
    "Recovery",
    "Boot into recovery mode",
    || {
        println!("进入恢复模式");
        Ok(())
    }
);
```

**方法文档:**

- `new(id, name, description)`: 创建新的菜单选项
  - 参数:
    - `id: u8` - 选项ID
    - `name: &'static str` - 选项名称
    - `description: &'static str` - 选项描述
  - 返回: `MenuOption`

- `with_callback(id, name, description, callback)`: 创建带回调的菜单选项
  - 参数:
    - `id: u8` - 选项ID
    - `name: &'static str` - 选项名称
    - `description: &'static str` - 选项描述
    - `callback: fn() -> Result<()>` - 回调函数
  - 返回: `MenuOption`

## 错误处理

所有公共API都使用统一的错误处理机制：

```rust
use nos_bootloader::utils::error::{BootError, Result};

// 定义返回类型
fn example_function() -> Result<()> {
    // 可能失败的操作
    if some_condition {
        Err(BootError::HardwareError("硬件错误描述"))
    } else {
        Ok(())
    }
}

// 处理错误
match example_function() {
    Ok(_) => println!("操作成功"),
    Err(e) => println!("操作失败: {:?}", e),
}
```

### 错误类型

- `BootError::HardwareError`: 硬件相关错误
- `BootError::ProtocolInitializationFailed`: 协议初始化失败
- `BootError::NotInitialized`: 组件未初始化
- `BootError::DeviceError`: 设备错误
- `BootError::InvalidParameter`: 无效参数

## 最佳实践

1. **内存管理**:
   - 使用双缓冲避免闪烁
   - 启用脏区域跟踪提高性能
   - 注意内存对齐要求

2. **错误处理**:
   - 始终检查返回结果
   - 使用`?`操作符传播错误
   - 提供有意义的错误信息

3. **性能优化**:
   - 使用批量操作减少函数调用开销
   - 利用SIMD优化（x86_64平台）
   - 缓存频繁访问的数据

4. **安全考虑**:
   - 验证所有输入参数
   - 检查边界条件
   - 正确处理unsafe代码

## 常见陷阱

1. **坐标系统**:
   - 图形坐标从(0,0)开始
   - 注意边界检查避免越界

2. **内存对齐**:
   - 所有分配64字节对齐
   - 小块使用空闲列表重用

3. **双缓冲**:
   - 必须在渲染会话中进行绘制
   - 记得交换缓冲区显示结果

4. **VBE模式**:
   - 检查模式是否支持
   - 使用线性帧缓冲区模式