🐱 寒冰是喵喵的 blog

音程与和弦

Tue, 21 Jul 2026 00:00:00 GMT

音乐科学呢~

Astro、MDX 与 Shader

Mon, 20 Jul 2026 03:45:12 GMT

下面的 ShaderBox 将 GLSL 保存在 MDX 文档内，在源码下方提供内联预览，并通过 overlay 开关提供“应用到页面”按钮。

全局 Shader可应用到整个页面

#version 300 es
precision highp float;

uniform vec2 u_resolution;
uniform float u_time;

out vec4 fragment_color;

void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution;
    vec3 color = 0.5 + 0.5 * cos(u_time + uv.xyx * 6.28318 + vec3(0.0, 2.0, 4.0));

    fragment_color = vec4(color, 0.3);
}

Markdown 边注、术语与钢琴窗测试

Sat, 18 Jul 2026 14:00:00 GMT

这篇文章既是本站 Markdown 扩展的使用说明，也是文章边注、术语原文与钢琴窗的渲染测试，当前由 MDX 渲染。

MDX 组件

本站将复杂的富文本能力注册为全局 MDX 组件。文章可以直接使用手绘标注、术语、边注和钢琴窗组件，无需在每篇文章中重复导入。普通 Markdown 继续使用 Astro 默认渲染器，适合不需要组件的内容。

MDX 手绘标注

Rough Notation 的七种效果分别封装为 <Underline>、<Box>、<Circle>、<Highlight>、<StrikeThrough>、<CrossedOff> 和 <Bracket>：

<Underline>下划线</Underline>
<Box>方框</Box>
<Circle>圆圈</Circle>
<Highlight>高亮</Highlight>
<StrikeThrough>删除线</StrikeThrough>
<CrossedOff>交叉划除</CrossedOff>
这句话中，<Bracket brackets={['left', 'right']}>只有这一小部分</Bracket> 会被标注。

段落前文 <Bracket class="inline-block w-52 align-middle" brackets={['left', 'right']}>这段较长的内容会自然换行，并由同一组括号包围</Bracket> 段落后文。

<Bracket class="block" brackets={['left', 'right']}>
  这是一整个被括号包裹的段落。它可以自然换行，并始终只绘制一组左右括号。
</Bracket>

这是手绘下划线

这是方框

这是圆圈

这是高亮

这是删除线

这是交叉划除

这是一整句话，其中只有这一小部分会被标注。

段落前文这段较长的内容会自然换行，并由同一组括号包围段落后文。

这是一整个被括号包裹的段落。它使用可用的正文宽度自然换行，并始终只绘制一组左右括号。

所有组件都支持 color、strokeWidth、iterations、padding、animationDuration、animate、multiline、rtl 和 class。<Bracket> 额外支持 brackets 和 gap：brackets 可选择 left、right、top 和 bottom；gap 默认是 0.75em，用于为句内括号预留左右空间，可传入像素数字、任意 CSS 长度，或用 gap={0} 关闭。它默认将多行内容视为一个整体，避免为每一行重复绘制括号。无 JavaScript 时会保留对应的 CSS 降级效果；减少动态效果模式下会自动关闭绘制动画。

术语原文

MDX 页面可以使用全局注册的 <Term> 组件，通过 original 保留术语原文，并用 lang 标记原文语言：

<Term original="virtual memory" lang="en">
  虚拟内存
</Term>
<Term original="上下文切换" lang="zh-CN">
  context switch
</Term>

例如，操作系统中的虚拟内存virtual memory 并不等同于物理内存；Rust 的借用检查器borrow checker 则会在编译期检查引用是否有效。

标注也可以反过来使用。例如在英文段落中，context switch上下文切换上方显示的是中文原词。lang 可以省略，但在中英文混排时建议保留。

<Term> 生成标准 HTML <ruby> 和 <rt> 元素。<rt> 可用于发音、翻译、音译或短注释。若内容需要离开本站的 Markdown pipeline，也可以直接使用标准 HTML，前提是目标渲染器允许 Markdown 中的 raw HTML：

<ruby>虚拟内存<rt lang="en">virtual memory</rt></ruby>

文章附记

<Sidenote> 的内容就是卡片正文，紧跟其后的段落用 <SidenoteText> 标记对应文字。不再需要额外的卡片组、ID 或配对名称：

<Sidenote>这里是附记，也支持普通的 **Markdown**。</Sidenote>

<p>
  <SidenoteText>这里是与附记相关的正文。</SidenoteText>
</p>

这段正文用来观察附记的位置和颜色关系。鼠标停在便签或这段文字上时，文字背景会显示相同颜色。边注适合补充背景、出处或不影响主线的细节；如果内容是理解文章所必需的，就不应该藏在边注里。

自定义标题与 Markdown

title 可以修改卡片标题；组件内容支持强调、代码、链接和多个段落：

这段正文用于检查自定义标题、富文本和多段内容。

嵌套为卡片堆

在一条 <Sidenote> 中继续嵌套 <Sidenote>，就会按出现顺序组成卡片堆。对应的 <SidenoteText> 使用相同顺序嵌套：第一张卡片对应外层文字，后面的卡片对应内层文字。

<Sidenote title="整句">
  第一张附记对应整句话。

  <Sidenote title="局部">第二张附记只对应其中一部分。</Sidenote>
</Sidenote>

<p>
  <SidenoteText>
    这是整句话，其中<SidenoteText>这一部分</SidenoteText>另有一张附记。
  </SidenoteText>
</p>

这句话同时关联了背景和出处，也包含延伸阅读。

每张卡片保留自己的颜色和文字范围；点击当前卡片可以切换到下一张，把鼠标移到对应文字上也会切换到那张卡片。

钢琴窗

MDX 页面可以使用全局注册的 <Piano> 组件。它使用科学音高记号描述按下的琴键，例如中央 C 是 C4，升 C 可以写成 C#4 或 C♯4，降 D 也可以写成 Db4：

<Piano title="C 大调和弦" notes="C4 E4 G4" />

C 大调和弦

按下：C4、E4、G4

notes 可以传入字符串或字符串数组，并使用空格、逗号或顿号分隔。浏览者可以点击琴键切换按下状态，钢琴窗会实时列出当前音符；“清空”按钮会释放全部琴键。

钢琴窗默认从 C4 开始显示两个八度。可以用 octave 指定起始八度，用 octaves 指定一到四个八度：

<Piano title="低音区的 F 小调和弦" notes="F2 Ab2 C3" octave={2} octaves={2} />

低音区的 F 小调和弦

按下：F2、G♯2、C3

降号会被规范到对应的升号琴键，因此上例中的 Ab2 显示为 G♯2。如果音名无法识别，或音符不在当前琴窗的音域内，构建会直接报错。省略 notes 则会生成一架没有预先按下琴键的钢琴：

<Piano title="试着按下几个音" />

试着按下几个音

尚未按下音符

窄屏、RSS 与无障碍

<Sidenote> 生成 <aside role="note">；嵌套卡片与嵌套正文按出现顺序配对。在手机或较窄的窗口中，单条附记会成为带有标题的正文块，多条附记仍可逐张切换；术语原文则继续显示在术语上方。

钢琴窗中的每个琴键都是带有按下状态的按钮，可以通过键盘聚焦并操作。琴键较多或屏幕较窄时，键盘区域可以横向滚动；RSS 中则保留标题与初始音符文字，不依赖交互脚本。

RSS 使用同一套内容组件，并保留每一张卡片对应的 <aside>、<ruby> 与 <rt> 语义；所有附记内容都会依次出现，因此不会依赖客户端交互脚本。

Rust：使用 uefi-rs 编写一个 UEFI 应用并加载内核

Thu, 16 Jan 2025 03:02:16 GMT

本文主要介绍如何使用 Rust 和 uefi-rs 库编写一个 EFI 引导加载程序（Bootloader），该 Bootloader 实现加载并跳转到一个简单的内核，内核则负责在显示区域绘制颜色。

整个过程分为以下步骤：

加载文件系统协议；
使用文件系统协议从指定路径加载文件元数据；
从元数据中获取文件大小；
根据文件大小分配内存空间；
加载文件的实际内容；
初始化显示协议；
设置寄存器并跳转至内核代码；
在内核中绘制颜色。

使用 uefi-rs 库

UEFI

UEFI（Unified Extensible Firmware Interface），统一可扩展固件接口，是一个负责连接硬件和软件之间的接口。

本文是为了编写了一个可以加载内核的引导器，因此将对使用 uefi-rs、 Boot Service 和 Runtime Service 以及一些必要的 Handle 和 Protocol 进行说明，但不会对于 UEFI 本身进行详细的解析，如果对这一方面想要深入了解可以参考 UEFI 手册、罗冰老师的《UEFI 编程实践》和戴正华老师的《UEFI 原理与编程》。

uefi-rs

Our mission is to provide safe and performant wrappers for UEFI interfaces, and allow developers to write idiomatic Rust code. — uefi-rs

EDK2 （EFI Development Kit）是 UEFI 的开发工具包，使用 C 语言进行 UEFI 工程编程。uefi-rs 是 rust 语言下的 EDK2 封装，巧妙运用了很多 rust 语言的语言特性，使得开发效率大大提升。

现有大多数的 UEFI 编程资料是基于 C 语言的，使用了很多指针特性来实现功能。在 Rust 中我们有更好的写法抽象和隐藏或安全传递这些指针，因此这里的主要目的是记录 C 语言的写法与 Rust 写法的异同，以便应对阅读参考资料代码时的语言障碍。（如果您有 C / C++ 基础且掌握 Rust 语言那就更好了！）

在本文中我们主要针对 uefi-rs > 0.33 的版本进行代码编写

数据类型

从数据类型说起：

在 EDK2 中，为了适配多种不同架构不同位数的 CPU 而对 C 语言的数据类型系统进行了封装，这些数据类型基本能够对应到 Rust 的类型系统中，下表是从 UEFI 手册中抽取的一部分，完整表格在这里查看。

EDK2 Type	Rust / uefi-rs Type	Description
BOOLEAN	bool	Logical Boolean. 1-byte value containing a 0 for FALSE or a 1 for TRUE. Other values are undefined.
INTN	iszie	Signed value of native width. (4 bytes on supported 32-bit processor instructions, 8 bytes on supported 64-bit processor instructions, 16 bytes on supported 128-bit processor instructions)
UINTN	usize	Unsigned value of native width. (4 bytes on supported 32-bit processor instructions, 8 bytes on supported 64-bit processor instructions, 16 bytes on supported 128-bit processor instructions)
INT8	i8	1-byte signed value.
UINT8	u8	1-byte unsigned value.
INT16	i16	2-byte signed value.
UINT16	u16	2-byte unsigned value.
INT32	i32	4-byte signed value.
UINT32	u32	4-byte unsigned value.
INT64	i64	8-byte signed value.
UINT64	u64	8-byte unsigned value.
INT128	i128	16-byte signed value.
UINT128	u128	16-byte unsigned value.
CHAR8	CStr8	1-byte character. Unless otherwise specified, all 1-byte or ASCII characters and strings are stored in 8-bit ASCII encoding format, using the ISO-Latin-1 character set.
CHAR16	CStr16	2-byte Character. Unless otherwise specified all characters and strings are stored in the UCS-2 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.

其中，CStr8 和 CStr16 可以分别使用宏 cstr8 和 cstr16 进行构建。

此外常用的还有：

EFI_STATUS，用于表达函数返回状态（是否出错，是否有值）。

EFI_HANDLE，即是后续我们会提到的 Handle。

修饰符

在 UEFI 手册中的接口描述中，使用了一些助记词作为参数的修饰符，如下：

Mnemonic	Description
IN	Datum is passed to the function.
OUT	Datum is returned from the function.
OPTIONAL	Passing the datum to the function is optional, and a NULL may be passed if the value is not supplied.
CONST	Datum is read-only.
EFIAPI	Defines the calling convention for UEFI interfaces.

入口函数

EDK2：

EFI_STATUS EFIAPI main (
   IN EFI_HANDLE ImageHandle,
   IN EFI_SYSTEM_TABLE *SystemTable
) { }

uefi-rs：
fn main(image_handle: Handle, mut system_table: SystemTable<Boot>) -> Status { }
可以看到 IN 类型数据写法实际上是没有什么区别的，但在 Rust 中能够隐藏指针类型和添加准确的泛型。

在入口中 Image Handle 指向当前 Image（其实也就是当前 EFI 程序），System Table 是一个 UEFI 环境下的全局资源表，存有一些公共数据和函数。

新版本的 uefi-rs API 与旧版本有所不同，下面的新版本的主函数代码：

#[entry]
fn main() -> Status { }

其中原先作为参数传递的 image_handle 和 system_table 现在以 uefi::boot::image_handler() 和 uefi::table::system_table_raw() 或 uefi_raw::table::system 的形式提供。

调用函数

一般来说，在 EDK2 中函数的返回值为 EFISTATUS 类型，（返回的）数据地址会赋值给参数类型为指针的 _OUT 参数中，这意味着调用一个函数的步骤是：

在手册中找到函数所在的 Table、Service、Handle 和 Protocol 等对应的数据结构，以函数指针 > 的方式访问函数。
查看哪些是 IN 类型参数，哪些是 OUT 类型参数
准备好用于 OUT 类型参数的空指针
调用后判断 EFISTATUS 而得到 _OUT 类型参数的指针是否已指向数据
从 OUT 类型参数取出数据

以获取 Graphics Output Protocol 为例子：

EDK2：

使用 LocateProtocol 函数获取 Graphics Output Protocol。

其函数原型为：

typedef
EFI_STATUS
(EFIAPI *EFI_LOCATE_PROTOCOL) (
  IN EFI_GUID                            *Protocol,
  IN VOID                                *Registration OPTIONAL,
  OUT VOID                               **Interface
 );

我们需要关注的是第三个参数 Interface，可以看到是一个指针类型的 OUT 类型参数。

On return, a pointer to the first interface that matches Protocol and Registration. — EFI_LOCATE_PROTOCOL - Interface

因此有代码：

// 声明一个状态，用于接受函数表明执行状态的返回值
EFI_STATUS Status;
// 提前声明一个指针用于指向函数的返回值数据
EFI_GRAPHICS_OUTPUT_PROTOCOL *GraphicsOutput;

// gBS 是 BootService，通过 SystemTable->BootService 获取
Status = gBS->LocateProtocol(
    // gEfiGraphicsOutputProtocolGuid 定义在头文件中，是 Graphics Output Protocol 的 UUID
    &gEfiGraphicsOutputProtocolGuid,
    NULL,
    (VOID **)&GraphicsOutput
);
if (EFI_ERROR(Status)) {
    return Status;
}

uefi-rs：

基于 Rust 的特性，可以使用 Result 替换掉 EFI_STATUS 这种需要额外声明一个变量来存放状态的方式。

let graphics_output_protocol_handle = boot::get_handle_for_protocol::<GraphicsOutput>()
    // 返回类型为 Result<Handle>
    // 这里便于理解直接使用了 unwarp，但在正常编码中，应该使用 map_or 或 expect 等方式显式处理错误。
    // 尤其是在 UEFI 这类难于调试的环境下，应该尽可能地留下有用的错误信息
    .unwrap();

let mut graphics_output_protocol = boot::open_protocol_exclusive::<GraphicsOutput>(graphics_output_protocol_handle)
    // 返回类型为 Result<ScopedProtocol<GraphicsOutputProtocol>>
    .unwrap();

UEFI Application 与 UEFI Protocol

uefi::helpers::init().unwrap();

uefi-rs 包中提供了 uefi::helper::init() 对 uefi::allocator::Allocator、log 和 print! 宏进行初始化以辅助开发。

SimpleFileSystem Protocol

// load simple file system protocol
let simple_file_system_handle = 
    uefi::boot::get_handle_for_protocol::<SimpleFileSystem>().unwrap();
let mut simple_file_system_protocol = 
    uefi::boot::open_protocol_exclusive::<SimpleFileSystem>(simple_file_system_handle)
        .unwrap();
        
// open volume
let mut root = simple_file_system_protocol.open_volume().unwrap();

请注意，代码中使用了许多的 unwrap() 来展开 Option 或 Result，主要是为了避免在此处编写过多的错误处理逻辑。然而，在 uefi-rs 环境下调试较为困难，通常应显式地处理这些错误，例如打印日志或寄存器状态等。

Memory Allocator

本段内容需要使用到的常量：

static KERNEL_PATH: &str = "\\kernel";
static FILE_BUFFER_SIZE: usize = 0x400;
static PAGE_SIZE: usize = 0x1000;

// open kernel file in the root using simple file system
let mut kernel_path_buffer = [0u16; FILE_BUFFER_SIZE];
let kernel_path = CStr16::from_str_with_buf(
        KERNEL_PATH, 
        &mut kernel_path_buffer
    ).unwrap();
let kernel_file_handle = root
    .open(kernel_path, FileMode::Read, FileAttribute::empty())
    .unwrap();
let mut kernel_file = match kernel_file_handle.into_type().unwrap() {
    FileType::Regular(f) => f,
    _ => panic!("This file does not exist!"),
};
info!("Kernel file opened successfully!");

// load kernel file info and size
let mut kernel_file_info_buffer = [0u8; FILE_BUFFER_SIZE];
let kernel_file_info: &mut FileInfo =
    kernel_file.get_info(&mut kernel_file_info_buffer).unwrap();
info!("Kernel file info: {:?}", kernel_file_info);
let kernel_file_size = usize::try_from(kernel_file_info.file_size()).unwrap();
info!("Kernel file size: {:?}", kernel_file_size);

// load kernel file into memory
let mut kernel_file_address = uefi::boot::allocate_pages(
    AllocateType::AnyPages,
    MemoryType::LOADER_DATA,
    kernel_file_size / PAGE_SIZE + 1,
)
.unwrap();

let kernel_file_address = unsafe { kernel_file_address.as_mut() as *mut u8 };

let kernel_file_in_memory = unsafe {
    core::ptr::write_bytes(kernel_file_address, 0, kernel_file_size);
    core::slice::from_raw_parts_mut(kernel_file_address, kernel_file_size)
};
let kernel_file_loaded_size = kernel_file.read(kernel_file_in_memory).unwrap();
info!("Kernel file loaded into memory successfully!");

let kernel_content = &mut kernel_file_in_memory[..kernel_file_loaded_size];
let kernel_address = kernel_content.as_ptr() as *const u8 as usize;
info!("Kernel file address: 0x{:x}", kernel_address);

本步骤用于将文件加载到内存，其中需要注意的地方是文件 handle、文件 info 都不是文件本体，且文件路径本身也是需要内存空间存放的。

我们一步步来解析这一大段代码。

这里我们开辟一个栈上数组来进行存放文件路径，即以下代码：

如果您从 Java 和 Python 等高度抽象且隐藏堆栈概念的语言转到 Rust，可能会觉得理解堆栈有些困难。在本文中，堆栈均指程序运行时的内存分布：堆内存和栈内存。它们的主要区别在于数据结构的存储方式以及程序员的操作权限。

栈内存主要用于存放可执行代码和生命周期受限的局部变量。其管理由编译器处理，并通过操作系统自动分配，程序通常从栈顶开始执行代码。而堆内存则主要存储动态数据，由程序员通过向操作系统申请分配。一般情况下，长度不确定的数据会优先存放在堆内存中，并通过指针进行管理。在 Rust 中，这通常表现为使用 Box<T> 等智能指针；而对于长度固定的数据，优先存储在栈内存中，例如 let a = 0; 这样的变量声明。

所谓“在栈上开辟数组”，指的是为固定长度的数组分配栈内存空间。

本文使用栈上数组存储文件路径，但应该也可以申请堆内存完成这个工作，有兴趣可以进行尝试，后续加载内核文件的实际内容时也会使用堆内存。

// open kernel file in the root using simple file system
let mut kernel_path_buffer = [0u16; FILE_BUFFER_SIZE];
let kernel_path = CStr16::from_str_with_buf(
        KERNEL_PATH, 
        &mut kernel_path_buffer
    ).unwrap();

将路径加载到内存之后便可以加载文件的 handle ，handle 类似于 Java 中的 java.io.File 或是 C 中的 FILE，负责处理文件的读写熟悉，是否为目录等。以下代码用于加载 handle ：

let kernel_file_handle = root
    .open(kernel_path, FileMode::Read, FileAttribute::empty())
    .unwrap();
let mut kernel_file = match kernel_file_handle.into_type().unwrap() {
    FileType::Regular(f) => f,
    _ => panic!("This file does not exist!"),
};

成功获取到 handle 后则需要从 handle 中获取文件大小，用于确定需要分配存储内核文件的内存大小。

// load kernel file info and size
let mut kernel_file_info_buffer = [0u8; FILE_BUFFER_SIZE];
let kernel_file_info: &mut FileInfo =
    kernel_file.get_info(&mut kernel_file_info_buffer).unwrap();
info!("Kernel file info: {:?}", kernel_file_info);
let kernel_file_size = usize::try_from(kernel_file_info.file_size()).unwrap();
info!("Kernel file size: {:?}", kernel_file_size);

好耶！接下来是分配堆内存空间：

uefi::boot::allocate_pages() 接受三位参数，页类型、数据类型和页数量。我们需要使得数据段可执行，因此选择 AllocateType::AnyPages （任意位置的可分配内存空间）和 MemoryType::LOADER_DATA （任意位置的可分配内存空间和可执行内存）。其他的类型可以在 https://docs.rs/uefi/latest/uefi/boot/enum.AllocateType.html 和 https://docs.rs/uefi/latest/uefi/mem/memory_map/struct.MemoryType.html 中查看。

kernel_file_size / PAGE_SIZE + 1 则是按照内核文件大小向上再多取一页，保证有足够的空间来存储内核代码。

PAGE_SIZE：页大小，本文假设机器是以 4k 为分页的 UEFI 固件。

let mut kernel_file_address = uefi::boot::allocate_pages(
    AllocateType::AnyPages,
    MemoryType::LOADER_DATA,
    kernel_file_size / PAGE_SIZE + 1,
)
.unwrap();

接着使用 handle 中的 https://docs.rs/uefi/latest/uefi/proto/media/file/struct.RegularFile.html#method.read 将文件内容加载到分配出来这片内存地址即可完成加载的功能了！

let kernel_file_address = unsafe { kernel_file_address.as_mut() as *mut u8 };

let kernel_file_in_memory = unsafe {
    core::ptr::write_bytes(kernel_file_address, 0, kernel_file_size);
    core::slice::from_raw_parts_mut(kernel_file_address, kernel_file_size)
};
let kernel_file_loaded_size = kernel_file.read(kernel_file_in_memory).unwrap();
info!("Kernel file loaded into memory successfully!");

let kernel_content = &mut kernel_file_in_memory[..kernel_file_loaded_size];
let kernel_address = kernel_content.as_ptr() as *const u8 as usize;
info!("Kernel file address: 0x{:x}", kernel_address);

GraphicsOutput Protocol

// init display
let gop_handler = uefi::boot::get_handle_for_protocol::<GraphicsOutput>().unwrap();
let mut gop = 
    uefi::boot::open_protocol_exclusive::<GraphicsOutput>(gop_handler)
        .unwrap();

let graphic_info = GraphicInfo {
    frame_buffer_addr: gop.frame_buffer().as_mut_ptr() as u64,
    frame_buffer_size: gop.frame_buffer().size() as u64,
};

这段相对简单，用于加载 Protocol 来获取显示信息。

Rust Inline ASM

unsafe {
    core::arch::asm!(
        "
        jmp {}
        ", 
        in(reg) kernel_address,
        in("rdi") graphic_info.frame_buffer_addr,
        in("rcx") graphic_info.frame_buffer_size,
        options(noreturn)
    );
}

使用 jmp 指令，并提供前面一些的代码中把内核文件的内存地址，就可以跳转至内核了。

另外，为了方便内核实现绘制屏幕的功能，我们还需要将显示区域的信息提前写入到寄存器中。这里我们选择 rdi 和 rcx 两个寄存器，rdi 写入 frame buffer 的基地址，而 rcx 写入 frame buffer 的大小。

Rust 的内联汇编使用 in(reg) value 来为寄存器赋值，使用 out(reg) mutable_value 来读取寄存器的值。options(noreturn) 意味着执行这段汇编永不返回，相当于 ! 或是说 never，可能会跳入死循环或是 hlt 低能耗模式。

另外还需要注意的是，Rust 并非允许自由调整所有的寄存器，本文只是恰好使用了两个空闲的寄存器。更多内容请阅读：https://doc.rust-lang.org/reference/inline-assembly.html

frame buffer 以行优先的方式将显示器的像素映射到内存中，下一步中将使用一个汇编循环语句将它填充以显示特定的颜色。

内核部分

BITS 64

mov rax, 0xff408deb

display:
    mov [rdi], rax
    add rdi, 4
    loop display

jmp $

这就是内核的全部代码了。

正如本文开头所提到的，我们要向屏幕填充颜色 0xff408deb。

0xff408deb 的顺序为 A（Alpha）RGB，GraphicsOutput Protocol 中的颜色顺序是 BGRA，但在 x86 中以小端方式表达便是 ARGB 了。

首先，程序将 RGB 值赋给 rax 寄存器，然后在 display 代码块中进行循环写入。这里，rdi 寄存器由 Bootloader 代码设置为 graphic_info.frame_buffer_addr，即显存映射到内存的起始地址。rcx 寄存器则保存了先前设置的 graphic_info.frame_buffer_size，即显存映射的总内存大小。为了在屏幕上填充这个颜色，我们需要遍历整个显存区域。

loop 指令用于控制循环，确保每次写入后，rcx 寄存器的值会减 1，直到其值为 0，才会跳出循环并执行下一条指令。通过这种方式，程序可以连续地将颜色写入显存，直到整个屏幕都被填充。

启动！

新建 esp 目录并拷贝 uefi 的编译结果：

bootx64.efi 是约定名称，UEFI 固定会自动使用该文件，文件名不区分大小写。如果使用其他名字则需要进行 UEFI Shell 后手动执行。

mkdir -p esp/efi/boot/
cargo build --bin efi --target x86_64-unknown-uefi
mkdir -p esp/efi/boot/
cp target/x86_64-unknown-uefi/debug/efi.efi esp/efi/boot/bootx64.efi

编译和拷贝内核：

nasm kernel.asm -o kernel
cp kernel esp/

接下来启动它吧！‘

注意替换 $(OVMF_CODE_PATH) 和 $(OVMF_VARS_PATH)

qemu-system-x86_64 \
    -m 256 \
    -enable-kvm \
    -drive if=pflash,format=raw,readonly=on,file=$(OVMF_CODE_PATH) \
    -drive if=pflash,format=raw,readonly=on,file=$(OVMF_VARS_PATH) \
    -drive format=raw,file=fat:rw:esp

本文完整源码

oscamp：操作系统 Hypervisor 方向（Draft）

Fri, 20 Dec 2024 21:01:12 GMT

跪了，开发环境好麻烦哦！！！

是 OS 训练营阶段四（以前的阶段三）的虚拟化任务，借此机会来学习虚拟化相关的知识。

开发环境

我的开发环境是位于 PVE 中的虚拟机，所以如果需要虚拟机也支持 vmx 技术就需要在 PVE 上打开嵌套虚拟化。

Windows 同理，且虚拟化技术至少需要从 BIOS 打开虚拟化支持，Windows 平台中打开任务管理器切换到 CPU 详细页右下角就可以看到支持信息。WSL 本质是虚拟机，因此如果是在 WSL 中进行开发也需要打开嵌套虚拟化。

在虚拟机中使用 grep "vmx|svm" /proc/cpuinfo 如果有输出则说明已经启用了嵌套虚拟化。

# INTEL
modprobe -r kvm_intel 
modprobe kvm_intel nested=1
# 这句是添加到启动时也同时加载模块，amd 也同样是这样
echo "options kvm_intel nested=1" >> /etc/modprobe.d/modprobe.conf

# AMD
modprobe -r kvm_amd
modprobe kvm_amd nested=1
echo "options kvm_amd nested=1" >> /etc/modprobe.d/modprobe.conf

其实就这两条指令，但是 PVE 需要关闭了全部 kvm 虚拟机才可以进行操作。而我的 PVE 里同时还有软路由虚拟机（？），如果关闭了它意味着我无法通过网络连接到机器上。

完成后使用 cat /sys/module/kvm_intel/parameters/nested 查询 PVE 是否已经打开嵌套虚拟化。输出结果可能会是 1 或者 Y 。

AMD 不嘻嘻

根据 arceos-hypervisor 社区成员的反馈，arceos-umhv 暂时还不支持 AMD 平台。😣😣😣

且我换用 Intel 的 WIndows 机器也不可以，我猜这和 Windows 的内核保护有关。

AMD 不嘻嘻，Intel 也没好哪里去！

考虑到关闭 Windows 内核保护在我本机容易引起蓝屏 + 不方便在教室里写代码，尝试使用 bochs 模拟器对 vmx 进行模拟和尝试写一写 AMD svm 的兼容代码。

在 Bochs 中全仿真 vmx

# 在 umhv 中使用 make 直接进行编译
$ make

# 产生文件
# ./arceos-umhv/arceos-vmm/arceos-vmm_x86_64-qemu-q35.elf
# ./arceos-umhv/arceos-vmm/arceos-vmm_x86_64-qemu-q35.bin
# ./arceos-umhv/arceos-vmm/arceos-vmm_x86_64-qemu-q35.asm

# 从文件里查询是否具有 Multiboot 头以便使用 grub 进行引导
$ hexdump -C /home/hanbings/github/arceos-umhv/arceos-vmm/arceos-vmm_x86_64-qemu-q35.elf | grep -E '02 b0 ad 1b| d6 50 52 e8'         
00001000  89 c7 89 de eb 22 66 90  02 b0 ad 1b 02 00 01 00  |....."f.........|

# Multiboot 1 魔数：0x1BADB002
# Multiboot 2 魔数：0xE85250D6
# 说明我们这里的是 Multiboot 1 的文件

Intel VMX 指令集与 AMD SVM 指令集

特性	Intel VT-x (VMCS)	AMD V (VMCB)
数据结构名称	Virtual Machine Control Structure (VMCS)	Virtual Machine Control Block (VMCB)
数据结构存储	硬件内部（需要通过 `VMREAD` 和 `VMWRITE` 访问）	显式内存结构（直接可通过内存指针访问）
数据结构大小	不固定（硬件实现决定），通常 ≥4KB	固定大小：4 KB
访问方式	使用指令：`VMREAD`/`VMWRITE`	直接内存访问
组成部分	多个字段：控制字段、Guest 状态字段、Host 状态字段等	两部分：控制区域和状态保存区域
指令拦截机制	配置拦截字段：I/O 位图、MSR 位图、控制字段等	精细化拦截：位图支持，对指令、I/O 操作的拦截更加灵活
二级地址转换支持	使用 EPT（Extended Page Table）	使用 NPT（Nested Page Table）
灵活性	受限于硬件设计，部分功能依赖 Intel 固定的机制	更加灵活，因 VMCB 可直接通过内存访问，自定义更方便
事件注入功能	支持：通过 VMCS 的字段注入中断或异常	支持：通过控制区域注入中断或异常
性能优化	VMCS 缓存到硬件中，通过 VMCS Shadowing 提高性能	直接内存访问，无需硬件缓存，但性能略低
断点和调试支持	可在 VMCS 中设置调试寄存器和断点配置	可通过 VMCB 的状态保存区域直接设置调试寄存器
状态保存机制	使用 VMCS 的 Guest 状态字段保存虚拟机寄存器及状态	使用 VMCB 的状态保存区域存储虚拟机寄存器及状态
扩展性	添加新功能需要通过硬件升级	可通过软件扩展 VMCB 的内容
I/O 位图支持	支持，通过字段配置 I/O 位图	支持，通过控制区域设置 I/O 位图指针
MSR（Model Specific Register）管理	MSR 位图用于拦截和控制 MSR 访问	MSR 拦截由拦截字段和控制区域灵活配置
时间管理（TSC 偏移）	支持：通过 `TSC_OFFSET` 字段控制	支持：通过 TSC 偏移字段直接操作
Nested Virtualization（嵌套虚拟化）	支持（`VMCS Shadowing`）	支持（通过嵌套 VMCB 配置）
指令支持	专用指令：`VMXON`、`VMRESUME`、`VMEXIT`、`VMREAD` 等	专用指令：`VMRUN`、`VMEXIT`、`VMSAVE`、`VMLOAD`

需要做的工作为：

CPU 虚拟化支持
内存虚拟化
中断虚拟化
设备虚拟化

目前思路

为简化环境，为 https://github.com/equation314/RVM-Tutorial 适配 SVM
在 RVM 中可运行的 SVM 代码移植回 https://github.com/arceos-hypervisor/x86_vcpu
为 https://github.com/arceos-hypervisor/axvcpu 添加适配 SVM 的代码
为 https://github.com/arceos-hypervisor/arceos-umhv 添加适配 SVM 的代码
向 https://github.com/gz/rust-x86 仓库贡献 svm 代码（也许）

进度

虚拟化技术：AMD SVM Hypervisor

虚拟化技术：AMD SVM Hypervisor（Draft）

Fri, 20 Dec 2024 21:01:12 GMT

本文是基于 https://github.com/equation314/RVM-Tutorial 做的 AMD SVM 适配，尽可能展示相关代码，但限于篇幅不会完全贴入代码。以及参考了 https://web.archive.org/web/20220815132158/https://key08.com/index.php/2021/04/11/1004.html 和 https://web.archive.org/web/20241008083327/https://blog.back.engineering/04/08/2022/，感谢前辈详细的文章。

若无特殊说明，文中提及的页数均依据 2024 版本。下称 “手册”，使用 “手册 xx 页” 标注页面，作为补充下方链接还包括一份旧版本的 AMD 虚拟化技术的独立文档。本文汇编代码均使用 nasm 格式或 Rust 内联汇编。

(24593—Rev. 3.42—March 2024) AMD64 Architecture Programmer’s Manual Volumes 1–5 https://web.archive.org/web/20241114034725/https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/programmer-references/40332.pdf
(33047–Rev. 3.02–December 2005) AMD64 Virtualization Technology Secure Virtual Machine Architecture Reference Manual https://web.archive.org/web/20240828193507/http://www.0x04.net/doc/amd/33047.pdf

检查本机是否支持虚拟化技术

在 AMD 中，虚拟化技术指令集名称为 SVM，与 Intel VT-x 的 VMX 类似，但在细节上有所不同。

据手册 955 页描述，在开启虚拟化支持前需要先进行检查：

检查 CPUID 功能号 Fn 8000_0001 的 ECX[SVM] 位为 1
VM CR 寄存器的 SVMDIS 位为 0（如果 CPU 支持 SVM，但 BIOS 中有对虚拟化技术的限制这一个为 1）

然后通过将 EFER.SVME 设置为 1 即可开启虚拟化功能。

CPUID 与 SVM 特性

通过 CPUID 指令，可以从 CPU 中查询 CPU 支持的特性、CPU 厂商信息等。直接调用 cpuid 指令（eax = 0x0000_0000）会返回 CPU 的字符串标识符，这个标识符将拆分存放在 ebx、ecx、edx 中（在 Intel 通常是 GenuineIntel，AMD 通常是 AuthenticAMD）。通过改变 eax 的值，cpuid 将返回不同的内容。

Fn 8000_0001 传参给 ECX 寄存器的位说明在手册 1894 页，查看表 CPUID Fn8000_0001_ECX Feature Identifiers，看到 SVM 位会被 CPUID 放置在 ECX 的第三个位（index 2）。

因此我们要做的操作如下：

mov eax, 0x80000001
cpuid

但是在 rust 的 asm 中还需要处理与 LLVM 相关的部分，因此为了简单起见，我们使用 x86 库对 cpuid 进行读取。

// asm! 写法
fn get_cpuid_80000001_ecx() -> u32 {
    let mut ecx: u32;

    unsafe {
        asm!(
            "cpuid", 
            inout("eax") 0x80000001u32 => _,
            out("ecx") ecx,
            options(nostack, preserves_flags)
        );
    }

    ecx
}

// 使用 x86::cpuid
let cpuid = x86::cpuid::CpuIdResult::from(x86::cpuid::cpuid!(0x80000001));
let ecx = cpuid.ecx;

// 然后读取 svm 位即可
let svm = cpuid.ecx & (1 << 2);

info!("[RVM] CPUID: {:#x}, SVM Feature: {:#?}", ecx, svm != 0);
if svm == 0 {
    return rvm_err!(Unsupported, "CPU does not support feature SVM");
}

VM CR

VM CR 的描述位于手册 1039 页，SVMDIS 在第五位（index 4）。

VM CR 也需要使用指令获取，rust 的 asm 代码如下：

pub fn read_msr(msr: u32) -> u64 {
    let mut low: u32;
    let mut high: u32;

    unsafe {
        asm!(
            "rdmsr",
            in("ecx") msr,
            out("eax") low,
            out("edx") high,
        );
    }

    ((high as u64) << 32) | (low as u64)
}

// 获取
let msr_value = read_msr(0xC0010114);
let svm_disabled = msr_value & (1 << 4);

info!("[RVM] VM_CR register value: {:#x}, SVM Enabled: {:?}", msr_value, svm_disabled == 0);
if svm_disabled != 0 {
    return rvm_err!(ResourceBusy, "SVM is not enabled in VM_CR register");
}

开启 EFER.SVME

EFER 同样也是一种 MSR 寄存器：

pub fn enable_svm() {
    let mut low: u32;
    let mut high: u32;

    unsafe {
        asm!(
            "rdmsr",
            in("ecx") 0xC0000080u32,
            out("eax") low,
            out("edx") high,
        );
    }

    low |= 1 << 12;
    
    unsafe {
        asm!(
            "wrmsr",
            in("ecx") 0xC0000080u32,
            in("eax") low,
            in("edx") high,
        );
    }
}

切换到虚拟化环境

为了切换进虚拟化环境，我们需要让原先 CPU 寄存器的数据先被保存在某个区域，然后使用 vmrun 进入虚拟化环境。而保存和恢复 CPU 寄存器的工作将由 CPU 自行完成，在 AMD 中，我们只需要开辟一片用于保存当前 CPU 的内存页并设置 VM_HSAVE_PA MSR 即可。

手册 957 页：

Processor implementations may store only part or none of host state in the memory area pointed to by VM_HSAVE_PA MSR and may store some or all host state in hidden on-chip memory. Different implementations may choose to save the hidden parts of the host’s segment registers as well as the selectors. For these reasons, software must not rely on the format or contents of the host state save area, nor attempt to change host state by modifying the contents of the host save area.

明确指出，vmm 程序不应该依赖特定的主机状态保存顺序来修改这些数据。这点与 intel 不同，在 intel 的 vmx 中，需要 vmm 对主机状态进行保存。

初始化与加载 VMCB

设置退出条件

当我们用 vmrun 切换进虚拟化环境之后，

VMRUN

那么… vmrun？

这是怎么回事呢？我们返回手册，手册 956 页，在 15.5 VMRUN Instruction 的 15.5.1 Basic Operation 节有一句：

VMRUN is available only at CPL 0. A #GP(0) exception is raised if the CPL is greater than 0.

再结合 log 的 error，是一个 error code 为 0 的 #GP。是不是 CPL 不为 0 导致了这个问题出现呢？

CS 为 0x8，也就是 0b1000，低两位为 00，那么说明执行指令时特权级是 0。

Rust：实现一份 Mimalloc（Draft）

Thu, 12 Dec 2024 04:32:03 GMT

参考：

mimalloc 核心机制

分配（空间）局限性（ Locality of Allocation）

采用极端小页（mimalloc 页，与操作系统内存页有区别，前者只是在 mimalloc 系统中的页概念，除非另有声明，后文的页都指 mimalloc 页，这里的极端小页为 64 k），并为每一个页提供空闲列表。分配过程中尽可能在一个页中分配，直到本页被分配满，即优先分配本页空间。

这种机制有助于：

提高 CPU 缓存的命中率
减少内存访问的随机性
缓解内存碎片化

free_list、local_list 与 thread_list

使用分离的处理方式存储不同类别的内存。free_list 存储从未分配的内存，local_list 存储从本线程释放回来的内存空间，thread_list 存储其他线程释放回来的空间。

每一个页都有自己的 free_list、local_list 与 thread_list。

本地线程与其他线程的意思是，假设我们从 A 线程（主线程）和 B 线程（开辟的子线程）申请两次内存并释放，假设主线程释放的内存与 allocator 所处线程一致，那么这片内存将返还到 local_list，而 B 线程的释放的内存则会先到 thread_list 中，等待处理。

在 mimalloc 中，local_list 和 thread_list 并不是马上进行回收到 free_list 的，mimalloc 优先从 free_list 分配内存，然后出现两种两种情况：

快路径（fast allocation path）

free_list 还有空闲内存，直接分配。（这块在 mimalloc 的 c 语言官方实现版本仅五行代码）
慢路径（generic allocation path）

free_list 没有空闲内存了。从 local_list 分配，如果也空闲内存了，那么将触发回收机制，从 thread_list 原子性的回收其他线程释放的内存。这里的原子性，指的不仅仅是内存回收时会移动链表指针到别的链表里，且还需要锁定几个全局性的变量：使用量、本页使用量等。

为了防止存在不断申请马上又释放的内存同时占用了 free_list 和 local_list 造成了性能下降，每当固定几次申请内存（maintain a deterministic heartbeat）就会触发一次内存回收。

不使用碰撞指针

是指划分一段连续内存段，定义一根在段内的指针，指针的左边是已使用内存，右边是未使用内存。当申请了一些内存后，实际分配从指针开始，指针向右边挪一点表示已使用内存增加了，反之，如果释放了一些内存就向指针左挪一点。

缺点很明显：

内存分配和释放不一定是连续的，如果采用整理算法，又增加了整体的复杂性
安全性较低，容易被溢出攻击

Chaos HMM 实现

本实现并未过多参考 c 语言版本的官方实现，仅对论文进行实现。

简要描述

划分为堆（Heap）、段（Segment）、页（Page）。

堆由具体的用量决定，使用 std::alloc::System::alloc 分配，由 Chaos HMM 决定是否要申请或是否给系统。

当内存将用满时向系统申请当前大小 x2 的内存用量
当检测到已经长时间空闲了归还系统

段分为两种段：页段和页区域段（前者指段内存在很多页，后者一段即为一段分配出去的内存）

页大小与对象大小有关：

对于 8 K 以下的为小对象，页面大小为 64 K，一个段中有 64 个这样的页。
对于 512 K 以下的大对象，页面大小为 512 K，一个段中有 8 个这样的页。
对于大于 512 K 的超大对象，Chaos 将分配一整个段。

对于前两种段来说，第一个页总是用于记录 free_list、local_list 和 thread_list 的，但在大对象页中，第一个页存在较多的浪费，也许可以使用 slab 再优化。

而超大对象段则需要关注对齐问题，即使只使用了 513 K，也应该分配 4 M 段。

数据结构

错误的设计

一开始，思路是建立一个栈上链表，并尽可能延长它的生命周期。但经群友的提醒，发现栈结构并不允许这样子，例如 Heap 生命周期始终会比 Segment 长，Segment 始终会比 Page 长，十分容易产生垂悬指针，并不能像堆内存那样长时间驻留内存。

但栈上链表本身以下一个节点的内存地址为存储内容形成链表是可以实现的。

Rust 全局分配器

oscamp：字节分配器 Chaos

Tue, 10 Dec 2024 14:28:48 GMT

源代码

oscamp/arceos/labs/lab_allocator/src/chaos.rs

use core::{alloc::Layout, ptr::NonNull};

pub struct Chaos {
    pub vec_reserve: (usize, usize, usize),

    pub start: usize,
    pub end: usize,
    pub head: usize,
    pub tail: usize,
    pub is_even: bool,

    pub allocated: usize,
    pub total: usize,
}

impl Chaos {
    pub const fn new() -> Self {
        Chaos {
            vec_reserve: (0, 0, 0),
            start: 0,
            end: 0,
            head: 0,
            tail: 0,
            is_even: false,
            allocated: 0,
            total: 0,
        }
    }

    pub unsafe fn init(&mut self, start: usize, size: usize) {
        log::warn!("init_memory: start=0x{:x}, size=0x{:x}, end=0x{:x}", start, size, start + size);

        self.vec_reserve = (start, start + 96, start + 96 + 192);
        
        self.start = start + 96 + 192 + 384;
        self.head = start + 96 + 192 + 384;

        self.end = start + size;
        self.tail = start + size;

        self.allocated = 96 + 192 + 384;
        self.total = self.end - self.start;
    }

    pub fn add_to_heap(&mut self, start: usize, end: usize) {
        log::warn!("add_memory: start=0x{:x}, end=0x{:x}", start, end);

        self.end = end;
        self.tail = end;

        self.total += end - start;
    }

    pub fn alloc(&mut self, layout: Layout) -> Result<NonNull<u8>, ()> {
        let vec_reserve_ptr = match layout.size() {
            96 => Some(self.vec_reserve.0 as *const u8),
            192 => Some(self.vec_reserve.1 as *const u8),
            384 => Some(self.vec_reserve.2 as *const u8),
            _ => None,
        };

        if vec_reserve_ptr.is_some() && layout.align() == 8 {
            return Ok(NonNull::new(vec_reserve_ptr.unwrap() as *mut u8).unwrap());
        }

        // get as much memory as possible
        if self.end <= 0xffffffc08426d000 {
            return Err(());
        }

        // check if memory is overflow
        if self.tail - layout.size() <= self.head {
            return Err(());
        }

        log::warn!("alloc_memory: head=0x{:x}, tail=0x{:x}, size=0x{:x}", self.head, self.tail, layout.size());

        let ptr = if self.is_even {
            let mem = self.tail - layout.size();
            self.tail = mem;

            NonNull::new(mem as *mut u8).unwrap()
        } else {
            let mem = self.head;
            self.head = mem + layout.size();

            NonNull::new(mem as *mut u8).unwrap()
        };

        log::warn!("alloc_memory: ptr=0x{:x}", ptr.as_ptr() as usize);

        self.is_even = !self.is_even;
        self.allocated += layout.size();

        Ok(ptr)
    }

    pub fn dealloc(&mut self, pos: NonNull<u8>, layout: Layout) {
        log::warn!("head, tail: 0x{:x}, 0x{:x}", self.head, self.tail);
        log::warn!("dealloc_memory: pos=0x{:x}, size=0x{:x}", pos.as_ptr() as usize, layout.size());

        if (pos.as_ptr() as usize) < self.start + 96 + 192 + 384 {
            return;
        }

        self.tail +=layout.size();
        self.allocated -= layout.size();

        log::warn!("before dealloc_memory: head=0x{:x}, tail=0x{:x}, start=0x{:x}, end=0x{:x}", self.head, self.tail, self.start, self.end);
    }

    pub fn total_bytes(&self) -> usize {
        0
    }

    pub fn used_bytes(&self) -> usize {
        self.allocated
    }

    pub fn available_bytes(&self) -> usize {
        self.total - self.allocated
    }
}

oscamp/arceos/labs/lab_allocator/src/lib.rs

//! Allocator algorithm in lab.
#![no_std]
#![allow(unused_variables)]

mod buddy;
mod linked_list;
mod chaos;

use allocator::{AllocError, AllocResult, BaseAllocator, ByteAllocator};
use chaos::Chaos;
use core::alloc::Layout;
use core::ptr::NonNull;

pub struct LabByteAllocator {
    inner: Chaos,
}

impl LabByteAllocator {
    pub const fn new() -> Self {
        Self {
            inner: Chaos::new(),
        }
    }
}

impl BaseAllocator for LabByteAllocator {
    fn init(&mut self, start: usize, size: usize) {
        unsafe { self.inner.init(start, size) };
    }

    fn add_memory(&mut self, start: usize, size: usize) -> AllocResult {
        self.inner.add_to_heap(start, start + size);
        Ok(())
    }
}

impl ByteAllocator for LabByteAllocator {
    fn alloc(&mut self, layout: Layout) -> AllocResult<NonNull<u8>> {
        self.inner.alloc(layout).map_err(|_| AllocError::NoMemory)
    }

    fn dealloc(&mut self, pos: NonNull<u8>, layout: Layout) {
        self.inner.dealloc(pos, layout)
    }

    fn total_bytes(&self) -> usize {
        self.inner.total_bytes()
    }

    fn used_bytes(&self) -> usize {
        self.inner.used_bytes()
    }

    fn available_bytes(&self) -> usize {
        self.inner.available_bytes()
    }
}

oscamp/arceos/labs/lab_allocator/src/linked_list.rs

use core::marker::PhantomData;
use core::{fmt, ptr};

#[derive(Copy, Clone)]
pub struct LinkedList {
    head: *mut usize,
}

unsafe impl Send for LinkedList {}

impl LinkedList {
    pub const fn new() -> LinkedList {
        LinkedList {
            head: ptr::null_mut(),
        }
    }

    pub fn is_empty(&self) -> bool {
        self.head.is_null()
    }

    pub unsafe fn push(&mut self, item: *mut usize) {
        *item = self.head as usize;
        self.head = item;
    }

    pub fn pop(&mut self) -> Option<*mut usize> {
        match self.is_empty() {
            true => None,
            false => {
                let item = self.head;
                self.head = unsafe { *item as *mut usize };
                Some(item)
            }
        }
    }

    pub fn iter(&self) -> Iter {
        Iter {
            curr: self.head,
            list: PhantomData,
        }
    }

    pub fn iter_mut(&mut self) -> IterMut {
        IterMut {
            prev: &mut self.head as *mut *mut usize as *mut usize,
            curr: self.head,
            list: PhantomData,
        }
    }
}

impl fmt::Debug for LinkedList {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_list().entries(self.iter()).finish()
    }
}

pub struct Iter<'a> {
    curr: *mut usize,
    list: PhantomData<&'a LinkedList>,
}

impl<'a> Iterator for Iter<'a> {
    type Item = *mut usize;

    fn next(&mut self) -> Option<Self::Item> {
        if self.curr.is_null() {
            None
        } else {
            let item = self.curr;
            let next = unsafe { *item as *mut usize };
            self.curr = next;
            Some(item)
        }
    }
}

pub struct ListNode {
    prev: *mut usize,
    curr: *mut usize,
}

impl ListNode {
    pub fn pop(self) -> *mut usize {
        unsafe {
            *(self.prev) = *(self.curr);
        }
        self.curr
    }

    pub fn value(&self) -> *mut usize {
        self.curr
    }
}

pub struct IterMut<'a> {
    list: PhantomData<&'a mut LinkedList>,
    prev: *mut usize,
    curr: *mut usize,
}

impl<'a> Iterator for IterMut<'a> {
    type Item = ListNode;

    fn next(&mut self) -> Option<Self::Item> {
        if self.curr.is_null() {
            None
        } else {
            let res = ListNode {
                prev: self.prev,
                curr: self.curr,
            };
            self.prev = self.curr;
            self.curr = unsafe { *self.curr as *mut usize };
            Some(res)
        }
    }
}

分析内存结构

堆中的 `Vec<Vec<u8>>` 结构数据

使用 Slab 分配器，并在 alloc 和 dealloc 函数，中分别打印 Layout。在打印结果中可以看到一些比较特殊的内存大小分别为 96、192、384

这是什么呢？根据 lab1/src/main.rs 中的测例代码分析可得知 let mut items: Vec<Vec<u8>> = Vec::new(); 的内层 Vec 将存放在堆内存中。

而 Rust 中的堆数据结构中的一张图片展示了 Vec 的内存结构为指针、长度和容量，每一部分各占 usize，在 64 位系统中，uszie 大小为 8 字节，即一个空数组内存占用为 24 字节，这与 96 字节仍有出入。

再观察分配情况，在 Indicator: 0 时，96 字节的 alloc 是在第一次 32 字节 alloc 后产生的，猜测是在 items.push 后进行了一次扩容，alloc_pass 修改为如下代码进行验证：

fn alloc_pass(delta: usize) -> Vec<Vec<u8>> {
    let mut items = Vec::new();
    let mut base = 32;
    loop {
        let c = (delta % 256) as u8;
        let a = vec![c; base+delta];
        items.push(a);
        println!("Item Capacity: {}", items.capacity());
        if base >= 512*1024 {
            break;
        }
        base *= 2;
    }
    items
}

结果为：

Running bumb tests...
Indicator: 0
Item Capacity: 4
Item Capacity: 4
Item Capacity: 4
Item Capacity: 4
Item Capacity: 8
Item Capacity: 8
Item Capacity: 8
Item Capacity: 8
Item Capacity: 16
Item Capacity: 16
Item Capacity: 16
Item Capacity: 16
Item Capacity: 16
Item Capacity: 16
Item Capacity: 16

就对上了，24 * 4 = 96 24 * 8 = 192 24 * 16 = 384

同时，至少在这里来说，Vec 初始容量为 0，第一次扩容时为 4，扩容机制为每次容量翻倍。

存放数据的堆空间

再回到测例代码：

fn free_pass(items: &mut Vec<Vec<u8>>, delta: u8) {
    let total = items.len();
    for j in (0..total).rev() {
        if j % 2 == 0 {
            let ret = items.remove(j);
            assert_eq!(delta, ret[0]);
            assert_eq!(delta, ret[ret.len()-1]);
        }
    }
}

这段代码在检查是否为偶数项，偶数项数组才会被 free_pass 的 remove() 释放。

因此针对这段代码，可以在分配器中设置一个奇偶标志位，当标志位为奇数时将数据从内存的起始位置开始分配，偶数时分配在末尾位置且向起始位置增长。扩容时，不考虑内存扩容时传入的内存地址起始位置而只改变结尾位置时也无需多余操作。

Chaos 真的不 Chaos

整体结构

考虑：

堆中的 Vec<Vec<u8>> 数据结构，大小固定为 96 + 192 + 384 = 672 字节，位于可分配内存的起始位置
奇数项堆，动态增长，紧跟 672 字节
偶数项堆，动态增长，位于可分配内存的末尾位置

使用以下结构体来描述整个可分配内存区域

pub struct Chaos {
    pub vec_reserve: (usize, usize, usize),

    pub start: usize,
    pub end: usize,
    pub head: usize,
    pub tail: usize,
    pub is_even: bool,

    pub allocated: usize,
    pub total: usize,
}

内存结构如下：

!https://ice.frostsky.com/2024/12/04/31665acefb8e6fbfa3315cc85b607994.png

vec_reserve: (usize, usize, usize) 用作存储先前描述的三片特殊的堆中 Vec 元数据结构，vec_reserve 为固定长度：96 + 192 + 384 字节。

pub start: usize 和 pub end: usize 分别存储 init 或是 add_to_heap 时给定的可分配内存地址范围。

pub head: usize 和 pub tail: usize 分别存储当前奇数堆的末尾位置和偶数堆的起始位置，通过 head - start + vec_reserve 可以得出奇数堆大小，通过 end - tail 则可以得出偶数堆大小。

pub is_even: bool 用于记录上一次分配是奇数还是偶数，在分配的最后将其翻转。

实现

在开始之前，还要确定一个很重要的问题。目前的设计，并没有考虑扩容时分配在本程序堆内存前内存区域的地址，因此使用代码简单判断下：

pub fn add_to_heap(&mut self, start: usize, end: usize) {
    log::warn!("head: 0x{:x}, tail: 0x{:x}, start: 0x{:x}, end: 0x{:x}", self.head, self.tail, start, end);

    self.head = start;
    self.tail = end;

    panic!("add_to_heap");
}

从 add_to_heap 的输出：

Running bumb tests...
Indicator: 0
[  0.082919 0 lab_allocator::chaos:66] head, tail: 0xffffffc08026d2a0, 0xffffffc080275000
[  0.087323 0 lab_allocator::chaos:44] head: 0xffffffc08026d2a0, tail: 0xffffffc080275000, start: 0xffffffc080275000, end: 0xffffffc08027d000
[  0.091091 0 axruntime::lang_items:5] panicked at labs/lab_allocator/src/chaos.rs:49:9:
add_to_heap

可以看到后续追加的内存与当前程序的堆尾部是连续的，只需要更改 tail 字段扩容当前内存即可。

初始化以及扩容

pub unsafe fn init(&mut self, start: usize, size: usize) {
        self.vec_reserve = (start, start + 96, start + 96 + 192);

        self.start = start + 96 + 192 + 384;
        self.head = start + 96 + 192 + 384;

        self.end = start + size;
        self.tail = start + size;

        self.allocated = 96 + 192 + 384;
        self.total = self.end - self.start;
    }

    pub fn add_to_heap(&mut self, start: usize, end: usize) {
        self.end = end;
        self.tail = end;

        self.total += end - start;
    }

分配

pub fn alloc(&mut self, layout: Layout) -> Result<NonNull<u8>, ()> {
    let vec_reserve_ptr = match layout.size() {
        96 => Some(self.vec_reserve.0 as *const u8),
        192 => Some(self.vec_reserve.1 as *const u8),
        384 => Some(self.vec_reserve.2 as *const u8),
        _ => None,
    };

    if vec_reserve_ptr.is_some() {
        return Ok(NonNull::new(vec_reserve_ptr.unwrap() as *mut u8).unwrap());
    }

    // check if memory is overflow
    if self.tail - layout.size() <= self.head {
        return Err(());
    }

    let ptr = if self.is_even {
        let mem = self.tail - layout.size();
        self.tail = mem;

        NonNull::new(mem as *mut u8).unwrap()
    } else {
        let mem = self.head;
        self.head = mem + layout.size();

        NonNull::new(mem as *mut u8).unwrap()
    };

    self.is_even = !self.is_even;
    self.allocated += layout.size();

    Ok(ptr)
}

释放

pub fn dealloc(&mut self, pos: NonNull<u8>, layout: Layout) {
    if (pos.as_ptr() as usize) < self.start + 96 + 192 + 384 {
        return;
    }

    self.tail +=layout.size();
    self.allocated -= layout.size();
}

越界访问

第 32 轮分配时发生了 Unhandled Supervisor Page Fault，本机的 panic 位置为 0xffffffc0802005fc，远在可分配的起始地址 0xffffffc08026d2a0 前，猜测本次的 panic 发生在栈区或是发生在从 tail 进行分配或释放时发生的。

说起来很好笑，let mut pool = Vec::new(); 和 items 一样，也会占用一些堆区内存，但因为其只写不读，即使内部全部都是无效的堆内存地址也没有问题。但这提醒到了一点：在分配用于 items: Vec<Vec<u8>> 的堆内存时，使用了一个特判：

let vec_reserve_ptr = match layout.size() {
    96 => Some(self.vec_reserve.0 as *const u8),
    192 => Some(self.vec_reserve.1 as *const u8),
    384 => Some(self.vec_reserve.2 as *const u8),
    _ => None,
};

这几个数字并没有问题，但先前我们忽略了 let a = vec![c; base+delta]; 的 base 总是从 32 开始，每次 alloc 翻倍，delta 则每轮增加 1。恰好，第 32 轮的第二次 alloc 时那么不恰好的 base = 64 和 delta = 32，这不是 96 了嘛 uwu，所以到这时候，原本该分配给 items: Vec<Vec<u8>> 的地址被当作了 tail 堆的起始地址，又因为 tail 是 tail = tail - size 取得空闲地址，所以结果是越界了。

根据观察后，在 Layout 中存在字段 align，align 字段在 items: Vec<Vec<u8>> 分配中总是 8，而普通分配总是 1。

因此简单写个判断就可以解决了：

if vec_reserve_ptr.is_some() && layout.align() == 8 {
    return Ok(NonNull::new(vec_reserve_ptr.unwrap() as *mut u8).unwrap());
}

处理完这个问题后，算法成功跑到 152 轮。

Indicator: 152
[ 25.511024 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f352a8, tail=0xffffffc085015be2, size=0xb8
[ 25.513985 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc085015b2a
[ 25.516487 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f352a8, tail=0xffffffc085015b2a, size=0xd8
[ 25.519232 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f352a8
[ 25.521127 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f35380, tail=0xffffffc085015b2a, size=0x118
[ 25.523938 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc085015a12
[ 25.525770 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f35380, tail=0xffffffc085015a12, size=0x198
[ 25.528492 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f35380
[ 25.530458 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f35518, tail=0xffffffc085015a12, size=0x298
[ 25.533267 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc08501577a
[ 25.535172 0 lab_allocator::chaos:94] head, tail: 0xffffffc084f35518, 0xffffffc08501577a
[ 25.537270 0 lab_allocator::chaos:95] dealloc_memory: pos=0xffffffc08026f000, size=0x60
[ 25.540115 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f35518, tail=0xffffffc08501577a, size=0x498
[ 25.542925 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f35518
[ 25.544869 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f359b0, tail=0xffffffc08501577a, size=0x898
[ 25.547528 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc085014ee2
[ 25.549466 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f359b0, tail=0xffffffc085014ee2, size=0x1098
[ 25.552112 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f359b0
[ 25.554013 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f36a48, tail=0xffffffc085014ee2, size=0x2098
[ 25.558305 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc085012e4a
[ 25.560458 0 lab_allocator::chaos:94] head, tail: 0xffffffc084f36a48, 0xffffffc085012e4a
[ 25.562665 0 lab_allocator::chaos:95] dealloc_memory: pos=0xffffffc08026f060, size=0xc0
[ 25.564900 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f36a48, tail=0xffffffc085012e4a, size=0x4098
[ 25.567790 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f36a48
[ 25.569725 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f3aae0, tail=0xffffffc085012e4a, size=0x8098
[ 25.572420 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc08500adb2
[ 25.575027 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f3aae0, tail=0xffffffc08500adb2, size=0x10098
[ 25.577664 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f3aae0
[ 25.579570 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f4ab78, tail=0xffffffc08500adb2, size=0x20098
[ 25.582385 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084fead1a
[ 25.584478 0 lab_allocator::chaos:71] alloc_memory: head=0xffffffc084f4ab78, tail=0xffffffc084fead1a, size=0x40098
[ 25.587429 0 lab_allocator::chaos:85] alloc_memory: ptr=0xffffffc084f4ab78
[ 25.591690 0 axruntime::lang_items:5] panicked at modules/axalloc/src/lib.rs:124:31:
Bumb: NoMemory.

预分配：尽可能使用更多的内存

在观察 152 轮和 add_memory 的 log 时发现：

本轮的偶数区并没有得到释放。
内存从一开始分配起，每次扩容即为前一次空间 x2，最大为 32 MB。而 qemu 虚拟机分配的是 128MB，只分配到了 32MB，显然还不是极限。

pub fn alloc(&mut self, layout: Layout) -> Result<NonNull<u8>, ()> { Err(()) }

Indicator: 0
[  0.088199 0 lab_allocator::chaos:46] add_memory: start=0xffffffc080275000, end=0xffffffc08027d000 # 32768
[  0.090785 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08027d000, end=0xffffffc08028d000 # 65536
[  0.093210 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08028d000, end=0xffffffc0802ad000 # 131072
[  0.095720 0 lab_allocator::chaos:46] add_memory: start=0xffffffc0802ad000, end=0xffffffc0802ed000 # 262144
[  0.098368 0 lab_allocator::chaos:46] add_memory: start=0xffffffc0802ed000, end=0xffffffc08036d000 # 524288
[  0.100928 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08036d000, end=0xffffffc08046d000 # 1048576
[  0.103497 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08046d000, end=0xffffffc08066d000 # 2097152
[  0.106127 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08066d000, end=0xffffffc080a6d000 # 4194304
[  0.108677 0 lab_allocator::chaos:46] add_memory: start=0xffffffc080a6d000, end=0xffffffc08126d000 # 8388608
[  0.111219 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08126d000, end=0xffffffc08226d000 # 16777216
[  0.114057 0 lab_allocator::chaos:46] add_memory: start=0xffffffc08226d000, end=0xffffffc08426d000 # 33554432 byte = 32MB
[  0.117634 0 axruntime::lang_items:5] panicked at modules/axalloc/src/lib.rs:124:31:
Bumb: NoMemory.

因此，我们可以打第一次 alloc 开始就强迫系统预分配一大堆内存给测例。比如在 pub fn alloc(&mut self, layout: Layout) -> Result<NonNull<u8>, ()> 的合理位置添加下面的代码：

// get as much memory as possible
if self.end <= 0xffffffc08426d000 {
    return Err(());
}

修改后，轮数为 189。此时，内存分配量到达了 64MB，这样下来仍有很多剩余空间。

再挤一挤，内存还是有的

看一眼 axalloc 中：

let old_size = balloc.total_bytes();
let expand_size = old_size
    .max(layout.size())
    .next_power_of_two()
    .max(PAGE_SIZE);
let heap_ptr = match self.alloc_pages(expand_size / PAGE_SIZE, PAGE_SIZE) {
    Ok(ptr) => ptr,
    Err(e) => panic!("Bumb: {:?}.", e),
};

不难发现 axalloc 是依赖于 total_bytes() 来判断该扩容多少内存。

简单一些处理，只需要修改原先的 total_bytes 代码，使得 total_bytes 永远返回 0。

pub fn total_bytes(&self) -> usize {
    0
}

修改后的最终轮数为 245。

Rust：实现插件系统

Sat, 09 Nov 2024 17:50:11 GMT

目标

实现插件系统，通常有两种方式：

语言自身支持某种加载方式允许动态加载外部代码。比如加载**动态链接库，**又或是像 Java 这类语言的虚拟机允许加载中间文件甚至是源代码。
通过语言引擎运行外部代码，例如 Java 中使用 ScriptEngine 和Rust 中使用 https://github.com/boa-dev/boa 执行 JavaScript。

此外，还可以通过向外暴露 HTTP / WebSocket 等接口实现插件接口，也是一种可行的插件系统设计。

但无论是通过语言引擎运行外部代码还是暴露 HTTP / WebSocket 接口，前者会带来数据交换的损耗而后者不仅带来数据交换所耗费的空间还会带来网络传输的延迟。这样的性能损耗对于这个插件系统的应用场景：分布式计算设施 — 大部分情况下是不可接受的，因此我们选取以动态链接库作为插件的形态，并通过 FFI（Foreign Function Interface）向插件暴露接口。

本插件系统需要实现的技术目标：

以动态链接库作为插件的形态，即需要一个加载器允许在运行时加载插件。
允许插件向加载器提供元信息（允许加载器调用插件内的函数）
允许插件执行加载器提供的 API （允许插件调用加载器内的函数）

加载器侧

这里我们使用到了 https://github.com/OpenByteDev/dlopen2 作为加载动态链接库的加载器，所列代码中依赖版本为 0.7.0（dlopen2 = "0.7.0"），其主要原因是 dlopen2 允许将被加载的动态链接库自动映射到一个结构体中，免去了再手动使用函数名称查找函数的步骤。

创建一个 src/main.rs 的新文件，然后定义一个主函数 fn main() {} 。

设计一个函数 simple_add_two_numbers，它的任务是将两个参数 a 和 b 相加，并在后面的插件侧代码中输出，但是需要声明在一个看起来有点奇怪的结构体中。

#[repr(C)]
#[derive(WrapperApi)]
struct Adder {
    simple_add_two_numbers: unsafe extern "C" fn(
        a: c_int,
        b: c_int,
    ),
}

注意！其中的 #[repr(C)] 和 unsafe extern "C" ，前者是用于声明结构体按 C 语言的结构体的内存结构进行布局（是的，Rust 的结构体内存布局与 C 语言并不一样，在黑魔书中有提及：Rust Docs - nomicon - other-reprs，而 extern 是 Rust 语言专为 FFI 接口设计的向外暴露函数的关键字，extern "C” 意为按照 C 语言的 ABI （Application Binary Interface 定义了如何在汇编语言层面调用此函数）接口标准向外暴露函数。它们都是必要的写法。

关于结构体的内存布局

Rust 一些 unsafe 操作允许操作内存，例如 std::mem::transmute，可以将结构体 A 替换为结构体 B。很好玩的是，Rust 提供了结构体 A、B 的长度检查，只有两个结构体长度一致才可以通过编译，而不检查类型是否一致。也就是说：

// 是能够成功转换的
struct A {
    e: u16,
    a: u8,
    b: u8
}

struct B {
    e: u8,
    a: u8,
    b: u8,
    c: u8,
}

// 不能成功转换
struct A {
    e: u16,
    a: u8,
    b: u8
}

struct B {
    e: u16,
    a: u8,
    b: u8,
    c: u8,
}

而：

struct A {
    e: u16,
    a: u8,
    b: u8
}

struct B {
    e: bool,
    a: bool,
    b: bool,
    c: u8,
}

也是可以转换成功的，因为一个 bool 值会占用 u8 长度的内存空间。本文想要提醒的是，不同的 C 语言编译器也许会将多个 boolean 压缩到一个 8 位或是说结构体对齐长度中来优化内存。

关于 `c_int`

Rust Docs - std/ffi/type.c_int 文档中，可以看到解释为与 C 语言中（未提及具体标准或版本）的 signed int（也就是 int）相等。实际上它只是一个类型别名 pub type c_int = i32; 。

Rust Docs - std/ffi/types 可以看到更多用于在 Rust 中绑定到 C 语言（的类型）的类型别名，应该在编写 FFI 代码时候尽可能使用它们来避免不经意间使用了那些不支持的类型。

同时 Rust Docs - std/ffi/structs 还定义了一些与字符串相关的工具，使用它们可以避免不受非法字符串的攻击。比如使用 Rust Docs - std/ffi/structs.OsString 替代 String。

接着使用 dlopen2 进行动态链接库的加载：

let cont: Container<Adder> =
        unsafe { Container::load("./target/debug/luminous.dll") }
            .expect("Could not open library or load symbols");

其中 Container::load("") 将指定加载哪一个动态链接库文件，在 Windows 下后缀名为 dll，macOS 为 dylib 以及 Linux 为 so 。

别忘了，需要声明一个泛型参数并传入定义的结构体 let cont: Container<Adder> = …

好啦！然后调用它！

let a = 1;
let b = 2;

unsafe {
    cont.simple_add_two_numbers(a, b);
}

等等，还没有在插件侧编写这个函数的实现呢！

插件侧

好的，创建 src/lib.rs 文件：

use std::os::raw::c_int;

#[no_mangle]
pub unsafe extern "C" fn simple_add_two_numbers(
    a: c_int,
    b: c_int
) {
    println!("{} + {} = {}", a, b, a + b)
}

并在 cargo.toml 写上：

[lib]
crate-type = ["cdylib"]

然后使用 cargo build 即可生成动态链接库。

编译，然后运行它吧！cargo run！

关于 `#[no_mangle]`

这里的 #[no_mangle] 用于来告诉 Rust 编译器不要混淆此函数的名称。

混淆是指 Rust 编译器会将函数更改为别的名称，这个名称包含更多信息，可以给编译过程的其他部分使用，但可读性较差。每种编程语言编译器对名称的混淆都略有不同，因此，为了让 Rust 函数可以被其他语言命名，必须禁用 Rust 编译器的名称混淆。

文档：https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html#calling-rust-functions-from-other-languages

接着我们需要添加一个函数回调（Callback），其实就是加载器向插件传递函数的内存地址（也就是指针）的过程。

在 src/main.rs 中添加：

pub type AddCallback = unsafe extern "C" fn(c_int);

pub unsafe extern "C" fn on_two_numbers_added(result: c_int) {
    println!("Got {}!", result);
}
#[repr(C)]
#[derive(Debug, Copy, Clone, WrapperApi)]
struct Adder {
    simple_add_two_numbers: unsafe extern "C" fn(
        a: c_int,
        b: c_int,
        callback: AddCallback
    ),
}
unsafe {
    cont.simple_add_two_numbers(a, b, on_two_numbers_added);
}

然后在 src/lib.rs 也做出相应修改：

#[no_mangle]
pub unsafe extern "C" fn simple_add_two_numbers(
    a: c_int,
    b: c_int,
    callback: AddCallback
) {
    println!("{} + {} = {}", a, b, a + b);
    callback(a + b);
}

至此，终于完成三个技术目标啦！

完整代码：

请留意一下有关于命名的位置，比如加载侧的动态链接库名称和 cargo.toml 的包名。

src/main.rs

use std::os::raw::c_int;
use dlopen2::wrapper::{Container, WrapperApi};

pub type AddCallback = unsafe extern "C" fn(c_int);

#[repr(C)]
#[derive(Debug, Copy, Clone, WrapperApi)]
struct Adder {
    simple_add_two_numbers: unsafe extern "C" fn(
        a: c_int,
        b: c_int,
        callback: AddCallback
    ),
}

pub unsafe extern "C" fn on_two_numbers_added(result: c_int) {
    println!("Got {}!", result);
}

fn main() {
    let a = 1;
    let b = 2;

    let cont: Container<Adder> =
        unsafe { Container::load("./target/debug/luminous.dll") }
            .expect("Could not open library or load symbols");

    unsafe {
        cont.simple_add_two_numbers(a, b, on_two_numbers_added);
    }
}

lib.rs

use std::os::raw::c_int;

pub type AddCallback = unsafe extern "C" fn(c_int);

#[no_mangle]
pub unsafe extern "C" fn simple_add_two_numbers(
    a: c_int,
    b: c_int,
    callback: AddCallback
) {
    println!("{} + {} = {}", a, b, a + b);
    callback(a + b);
}
cargo.toml

cargo.toml

[package]
name = "luminous"
version = "0.1.0"
edition = "2021"

[[bin]]
name = "luminous"
path = "src/main.rs"

[lib]
crate-type = ["cdylib"]

[dependencies]
dlopen2 = "0.7.0"

参考

Foreign Function Interface

Rust Closures in FFI

Effective Rust - 类型 - 速查表（停止更新）

Thu, 25 Apr 2024 03:25:00 GMT

本文提炼于：

Types - Effective Rust

感谢作者以及出版社为广大 Rust 提供了一本这么好的 Rust 编码参考规则。

一. 使用类型系统表达数据结构

Rust isn’t a language where you’re going to be doing much in the way of converting between pointers and integers — 在 C / C++ 中是允许操作内存地址的，比如加减内存地址。
Rust 允许在数字字面量声明类型：
```
let x = 23i32;
```
Rust 的 char 字符，在内存中仍然保持为 4 字节 Unicode 值，而不是转换为 32 位整数。
在 Rust 中使用 try_into() 进行大位数的数字类型到小位数数字类型的转换，使用 into() 进行小位数到大位数的数字类型转换。
Arrays 用于聚合一个类型的多个实例。Tuple 用于聚合多个类型的多个实例，Structs 同样用于聚合多个类型的多个类型。但是允许通过名称来引用各个字段。
enum 允许携带一个数字或字符串值，并且具有类型安全检查。
使用 match 的时候建议添加 _ ⇒ {} 作为默认选项。
在 Rust 中，表达可能存在错误使用 Result<T, E>，表达可能不存在值使用 Option<T> 。

二. 使用类型系统表达共同行为

Method 方法，需要依附在 enum structs 等结构上，通常为 impl 结构体名称，在 fn 前使用 pub 表示该方法为公开方法，允许从 impl 块外的地方调用。

Rust 中呀很多很有意思的写法，根据匹配 enum 的值在一个 impl 的方法中以不同的方式进行计算，如下：

enum Shape {
    Rectangle { width: f64, height: f64 },
    Circle { radius: f64 },
}

impl Shape {
    pub fn area(&self) -> f64 {
        match self {
            Shape::Rectangle { width, height } => width * height,
            Shape::Circle { radius } => std::f64::consts::PI * radius * radius,
        }
    }
}

Rust 支持函数指针，允许将一整个函数赋值给一个变量。
Rust 支持闭包，即将函数作为另一个函数的参数进行传递，当然 lambda 表达式支持也少不了。Rust 的表达式语法为 |args…| = { … }; 。

对于 Rust 语言而言，这种基于语句（statement）和表达式（expression）的方式是非常重要的，你需要能明确的区分这两个概念, 但是对于很多其它语言而言，这两个往往无需区分。基于表达式是函数式语言的重要特征，表达式总要返回值。 — 圣经
可以使用一些 Trait 来对作为参数传入的函数类型作出限制。FnOnce 是指移交所有权的参数；FnMut 相当于 &mut T 指传入一个可变引用；Fn 相当于 &T，指传入引用。
```
pub fn modify_all<F>(data: &mut [u32], mut mutator: F)
where
    F: FnMut(u32) -> u32,
{
    for value in data {
        *value = mutator(*value);
    }
}
```
Rust 没有函数重载，函数重载有违 Rust 设计哲学之一的 Be Explicit，而大多数情况都可以改用泛型解决。
```
use num::Num;

fn plus<T: Num>(a: T, b: T) -> T {
    a + b
}
```

Rust 可以依据 Trait 限制泛型边界（Trait bounds）。

pub fn dump_sorted<T>(mut collection: T)
where
    T: Sort + IntoIterator,
    T::Item: std::fmt::Debug,
{
    // Next line requires `T: Sort` trait bound.
    collection.sort();
    // Next line requires `T: IntoIterator` trait bound.
    for item in collection {
        // Next line requires `T::Item : Debug` trait bound
        println!("{:?}", item);
    }
}

三. 使用 match 表达式转换 Option 和 Result

[Option<T>](https://doc.rust-lang.org/std/option/enum.Option.html): To express that a value (of type T) may or may not be present

[Result<T, E>](https://doc.rust-lang.org/std/result/enum.Result.html) : For when an operation to return a value (of type T) may not succeed and may instead return an error (of type E)

正如前面所提：在 Rust 中，表达可能存在错误使用 Result<T, E>，表达可能不存在值使用 Option<T> 。

我们使用 match 来匹配 Option 和 Result：

// Option
struct S {
    field: Option<i32>,
}

let s = S { field: Some(42) };
match &s.field {
    Some(i) => println!("field is {i}"),
    None => {}
}

// Result
let result = std::fs::File::open("/etc/passwd");
let f = match result {
    Ok(f) => f,
    Err(_e) => panic!("Failed to open /etc/passwd!"),
};

使用 if let 语句或是 if let else 语句简化 Option 和 Result 代码的解析

// Option
if let Some(i) = &s.field {
    println!("field is {i}");
}

// Result
if let Ok(i) = &s.field {
    println!("field is {i}");
}

应该处理或返回 Option 或 Result 而不是使用 unwarp 忽略封装直接返回结果。

However, in many situations, the right decision for error handling is to defer the decision to somebody else.

使用 unwarp 时候，如果遇到 None 或是 Err，将导致代码将在此处被 panic!，除非你清楚自己在干什么，否则不要使用它。

标记一个 #[must_use] 可以迫使使用者必须处理 Result。

warning: unused `Result` that must be used
  --> src/main.rs:63:5
   |
63 |     f.set_len(0); // Truncate the file
   |     ^^^^^^^^^^^^
   |
   = note: this `Result` may be an `Err` variant, which should be handled
   = note: `#[warn(unused_must_use)]` on by default
help: use `let _ = ...` to ignore the resulting value
   |
63 |     let _ = f.set_len(0); // Truncate the file
   |     +++++++

可以使用 ? 操作符将错误向上传播。

• In particular, use these transformations to convert result types into a form where the ? operator applies.
```
pub fn find_user(username: &str) -> Result<UserId, std::io::Error> {
    let f = std::fs::File::open("/etc/passwd")?;
    // ...
}
```

Java 实现一个简单的 EventBus

Tue, 10 Mar 2020 10:57:00 GMT

0x00 EventBus

EventBus 是一种低耦合甚至完全分离的消息传递模块设计

实现 EventBus 通常基于发布/订阅者模式或观察者模式两种设计模式例如基于前者的 Google/Guava 基于后者的 Minecraft Bukkit Event 在这个实现中 EventBus 是基于前者的，也就是发布/订阅者模式

其实写这个玩具是想给其他项目做一个插件/模组事件系统来着阿巴阿巴阿巴（小声）

0x01 发布/订阅者模式与观察者模式

前面说过了，这两个模式是常见实现设计模式，发布/订阅者模式在某种意义上是观察者模式的一个扩展和补充

观察者模式由消息发布者与消息监听者两方组成，消息发布者和消息监听者互相知晓，也就是说这样的模式只是低耦合 发布/订阅者模式由消息发布者、消息传递者和消息监听者三方组成，消息发布者和消息监听者互不相识，完全隔离，由一个第三方消息传递者来进行通知，是一个完全分离的设计

昂… 观察者模式就像课堂上老师给同学说过两天要考试，消息发布者是老师，消息监听者是同学，同学直接从老师那里得知了消息，而发布/订阅者模式就像老师把过两天要考试的消息发布在了电子消息公告栏上一样，消息监听者同学们收到了由公告栏消息传递者发布的消息，同学们是不知道消息到底是老师发的还是校长发的

0x02 结构

项目地址：https://github.com/Hanbings/Cynops-event

类与类功能描述

类名/接口名	功能描述
Event	Event模板类注册到EventBus的事件都需要继承自Event类
Listener	Listener模板类注册到EventBus的事件都需要继承自Event类
@EventHandler	事件处理器注解当在注册一个符合条件 Listener 后 EventBus 将自动扫描 Listener 中带有此注解的方法并且自动识别方法内第一个参数且只能是唯一的一个参数所要求的事件当事件向 EventBus 中发布一次事件的时候 EventBus 将通知所有订阅了这一个事件的 Listener 然后执行 Listener 中对应的 @EventHandler 方法
Cancellable	一个 Event 接口, 实现该接口标识事件可以取消如果不理解可以先阅读 Blockable 使用接口中的 setCancelled(bollean cancel) 取消一个事件后仅仅在 Event 中可能会存在的 cancel 标志位标记事件已经取消/未取消但事件将继续向下传递到 @EventHandler 的方法中 ignoreCancelled() 参数保持 false 的处理器方法在声明 @EventHandler时设置参数 ignoreCancelled 为 true 即忽略已经标记取消的事件那么将不会被执行
Blockable	一个 Event 接口实现该接口标识事件可以阻断阻断的意思是如果一个事件实现了这个接口并且一个 EventHandler 使用了接口中的 setBlocked(boolean block) 方法本次事件将会就地结束
EventBus	EventBus 提供 registerEvent() / unregisterEvent () registerListener() / unregisterListener() callEvent() 等方法注册注销发布事件等操作
EventPriority	这个枚举使用在 @EventHandler 注解的 priority 参数中 LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR 是枚举内容 LOWEST 优先级最高, 是第一个被触发的等级, MONITOR 优先级最低, 是最后一个被触发的等级
RegisteredHandler	当 @EventHandler 被扫描后注册后加载到这个类
RegisteredListener	当 Listener 被扫描后并且扫描了 @EventListener 后将 RegisteredHandler 加载到这个类事件的优先级排序是在这个过程中完成的

0x03 背后的故事

1. Event - 事件

来看看一个事件是怎么样注册和发布的

一个类继承了 Event
使用一个 EventBus 实例的 registerEvent(Event event)
EventBus 经过一些操作后注册事件到内部的一张 Map 中
使用 EventBus 实例的 callEvent(Event event) 发布事件

在第一步中，一个类继承自 Event 类，这样的设计是为了限定在 EventBus 中与 Event 相关的方法所能接受的类型

第二步和第三步，使用 EventBus 中的 registerEvent(Event event) 注册事件到一张Map中

昂… 那张 Map大概长这个样：

private final Map<Class<? extends Event>, RegisteredListener> handlers = new ConcurrentHashMap<>();

Map 的第一个参数自然是 Event 的子类而第二个参数则是集合了所有有注册到这个事件的事件处理器的监听器（有点绕）的容器，它（RegisteredListener）看上去是这样的：

package io.hanbings.cynops.event;

import java.util.ArrayList;
import java.util.List;

@SuppressWarnings("unused")
public class RegisteredListener {
    private final List<RegisteredHandler> handlerList = new ArrayList<>();
    private final List<Integer> priorityIndex = new ArrayList<>();

    public RegisteredListener() {
        for (int count = 0; count < 6; count++) {
            priorityIndex.add(0);
        }
    }

    public List<RegisteredHandler> getHandlerList() {
        return handlerList;
    }

    public void addHandler(RegisteredHandler handler) {
        // 这一处非常糟糕的说
        int priority = getPriorityShadow(handler.getPriority());
        handlerList.add(priorityIndex.get(priority), handler);
        for (int count = priority; count < 6; count++) {
            priorityIndex.set(count, priorityIndex.get(count) + 1);
        }
    }

    public void removeHandler(RegisteredHandler handler) {
        handlerList.removeIf(registeredHandler -> registeredHandler.getListener().equals(handler.getListener()));
    }
    
    private int getPriorityShadow(EventPriority priority) {
        switch (priority) {
            case LOWEST:
                return 0;
            case LOW:
                return 1;
            case HIGH:
                return 3;
            case HIGHEST:
                return 4;
            case MONITOR:
                return 5;
            default:
                return 2;
        }
    }
}

这个类当中又又又有两个列表，其中一个是 RegisteredHandler 的列表，另一个则是用于实现优先级的列表，回到事件注册，在EventBus中有：

public void registerEvent(Event event) {
    if (!handlers.containsKey(event.getClass())) {
        handlers.put(event.getClass(), new RegisteredListener());
    }
}

这样大概明了了吧，在一个 EventBus 示例中，有一张存储监听器的 Map ，Event 类的 Class 作为键，一个 RegisteredListener 实例作为值，在 RegisteredListener 实例中又存储了 RegisteredHandler 事件处理器方法列表和优先级列表

到第四步，使用 callEvent (Event event) 触发事件：

public void callEvent(Event event) {
    if (handlers.containsKey(event.getClass())) {
        for (RegisteredHandler handler : handlers.get(event.getClass()).getHandlerList()) {
            if (event instanceof Blockable && ((Blockable) event).isBlocked()) {
                return;
            }
            if (event instanceof Cancellable
                    && ((Cancellable) event).isCancelled()
                    && handler.isIgnoreCancelled()) {
                continue;
            }
            try {
                handler.getMethod().invoke(handler.getListener(), event);
            } catch (IllegalAccessException | InvocationTargetException e) {
                e.printStackTrace()
            }
        }
    }
}

首先通过 handlers.containsKey(event.getClass()) 来判断前面所说的 Map 中是否存在对应的 Event ，然后通过一个循环遍历 Map 中的 RegisteredListener 中的 HandlerList 的注册的 @EventHandler ，接着判断有没有实现 Cancellable 和 Blockable 并在判断到接口有实现时判断状态做出对应动作，最后，通过一个反射来执行注册的 @EventHandler 方法 handler.getMethod().invoke(handler.getListener(), event)

有关于 Method#invoke 的用法在：https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/reflect/Method.html

这样就完成了一个事件从注册到发布的一个过程 这一部分倚重解释如何发布事件的，接下来说说 RegisteredListener RegisteredHandler 和 @EventHandler 的处理

2. @EventHandler - 事件处理器注解

package io.hanbings.cynops.event.interfaces;

import io.hanbings.cynops.event.EventPriority;

import java.lang.annotation.*;

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@SuppressWarnings("unused")
public @interface EventHandler {
    EventPriority priority() default EventPriority.NORMAL;
    boolean ignoreCancelled() default false;
}

以上是 @EventHandler 注解的完整代码，它有两个参数，一个是 EventPriority 类型的 priority，另一个是 boolean 类型的 ignoreCancelled，此外 @Target(ElementType.METHOD) 标注了它只能用于方法，@Retention(RetentionPolicy.RUNTIME) 则标注它在运行时加载，@Documented 表示它将会生成在 Javadocs 中，至于 @SuppressWarnings(“unused”) 是为了屏蔽 idea 一直在给这个类画黄线说没有被其他类引用，如果造一个单独模块的话这样的情况会常常会出现，但这个注解是无关紧要的，只是为了屏蔽 warning

3. RegisteredHandler - 多了一层皮的事件处理器

package io.hanbings.cynops.event;

import io.hanbings.cynops.event.interfaces.Listener;

import java.lang.reflect.Method;

@SuppressWarnings("unused")
public class RegisteredHandler {
    private EventPriority priority;
    private boolean ignoreCancelled;
    private Listener listener;
    private Method method;

    private RegisteredHandler() {
    }

    public RegisteredHandler(EventPriority priority, boolean ignoreCancelled
            , Listener listener, Method method) {
        this.priority = priority;
        this.ignoreCancelled = ignoreCancelled;
        this.listener = listener;
        this.method = method;
    }

    public EventPriority getPriority() {
        return priority;
    }

    public boolean isIgnoreCancelled() {
        return ignoreCancelled;
    }

    public Listener getListener() {
        return listener;
    }

    public Method getMethod() {
        return method;
    }
}

这是 RegisterHandler 的完整代码，主要用于存储 @EventHandler 所注解代码的完整信息，优先级是否忽略已经取消的事件监听器类监听处理器方法（真的是方法，是反射扫描注解获得的监听处理器方法 Method 对象）扫描这一块我们下面 RegisterListener 说，RegisterHandler 理解起来就是一个 Java Bean，也就是对象容器，存储反射得到的内容避免重复反射浪费性能

4. RegisterListener - 监听器容器处理器列表优先级排序

RegisterListener 实际上已经在第二节里面说过了，这里主要讲讲注册一个监听器到变成 RegisterListener 的部分

先是在 EventBus 中的 registerListener

public void registerListener(Listener listener) {
    Class<?> clazz = listener.getClass();
    for (Method method : clazz.getDeclaredMethods()) {
        if (method.isAnnotationPresent(EventHandler.class)) {
            final Class<?> event;
            method.setAccessible(true);
            event = method.getParameterTypes()[0];
            if (handlers.containsKey(event)) {
                EventHandler annotation = method.getAnnotation(EventHandler.class);
                handlers.get(event).addHandler(
                        new RegisteredHandler(annotation.priority()
                                , annotation.ignoreCancelled(), listener, method));
            }
        }
    }
}

registerListener 主要是扫描 Listener 中带有 @EventHandler 注解的方法，扫描当然是大家都喜欢的反射啦

if (handlers.containsKey(event)) {
                EventHandler annotation = method.getAnnotation(EventHandler.class);
                handlers.get(event).addHandler(
                        new RegisteredHandler(annotation.priority()
                                , annotation.ignoreCancelled(), listener, method));
            }

这部分就更是重量级（代码缩进我也不知道是怎么回事，就这样先）先询问 handlers 图中有无存储 @EventHandler 方法要求的 Event，如果存在，则拿到值，也就是一个 RegisterListener 实例，然后使用 RegisterListener 的 addHandler 方法向 RegisterListener 的两个列表中添加 RegisterHandler 和优先级索引

public void addHandler(RegisteredHandler handler) {
        // 这一处非常糟糕的说
        int priority = getPriorityShadow(handler.getPriority());
        handlerList.add(priorityIndex.get(priority), handler);
        for (int count = priority; count < 6; count++) {
            priorityIndex.set(count, priorityIndex.get(count) + 1);
        }
    }

5. EventBus - 事件总线

到这里其实已经把整个 EventBus 完整的接受了一次了，再看看 EventBus 里面剩下的部分吧

public void unregisterListener(Listener listener) {
        Class<?> clazz = listener.getClass();
        for (Method method : clazz.getDeclaredMethods()) {
            if (method.isAnnotationPresent(EventHandler.class)) {
                final Class<?> event;
                method.setAccessible(true);
                event = method.getParameterTypes()[0];
                if (handlers.containsKey(event)) {
                    EventHandler annotation = method.getAnnotation(EventHandler.class);
                    handlers.get(event).removeHandler(
                            new RegisteredHandler(annotation.priority()
                                    , annotation.ignoreCancelled(), listener, method));
                }
            }
        }
    }

移除一个 Listener 是对 registerListener() 的反向操作，同样是拿到 RegisterListener 然后从里面的列表移除 RegisterHandler 然后更新索引

public void unregisterEvent(Event event) {
        handlers.remove(event.getClass());
    }

这个更简单，直接从 Map 移除 Event 完事

0x04 最后

非常感谢有耐心读到这里，至此已经是这篇文章的全部内容了，如果有错误的地方欢迎各位指出

项目的开源地址是：https://github.com/hanbings/cynops-event

我的Github是：https://github.com/hanbings

欢迎 follow ~

为 Linux 服务器 SSH 添加 TOTP 动态验证码以及 Java 实现算法

Tue, 10 Mar 2020 10:57:00 GMT

0x00 TOTP 动态验证码？

TOTP 基于时间的一次性密码算法（Time-Based One-Time Password）是一种根据预共享的密钥与当前时间计算一次性密码的算法，利用不同设备时间相同的特性，将时间作为特定算法的一部分从而达到无需网络进行安全验证的目的。该算法有两个输入，一个输出，一个输入是随机生成的密钥，密钥需要被验证方和验证器同时持有，另一个输入即系统时间，通常是 UNIX 时，输出则是两方相同的验证码。一般的验证码有效期为 30 秒，每 30

秒生成一个新的验证码。当前有很多领域和行业在使用 TOTP 作为它们的安全验证，比如银行使用的实体验证器，网易的网易将军令等。

这套算法在 RFC6238 中有详细的说明，在后面的实现算法部分详细说明。

0x01 Linux 服务器安装 Google Authenticator

服务器采用腾讯云轻量服务器 Debian Linux 系统，腾讯云轻量服务器是腾讯云基于 CVM 服务器推出以应用为中心的轻量级服务器，优点在于快速部署应用、价格便宜等。有需要在云环境练习 Linux 技能的推荐购买【腾讯云】云产品限时秒杀，爆款2核4G云服务器首年74元【腾讯云】境外1核2G服务器低至2折，半价续费券限量免费领取！

SSH 远程登录后先更新当前源列表
```
apt update
```
然后执行安装指令

当然，如果已经在腾讯云里买了一堆轻量机子了，不想做这些繁琐的步骤，可以用轻量的自动化助手一键完成安装后再进入机子进行 Authenticator 密钥设置
```
apt install libpam-google-authenticator
```

输入 google-authenticator 并按照说明进行配置

google-authenticator

图中黄线框部分为密钥，红色线框部分为备用验证码，备用验证码是在丢失验证器的情况下输入的验证码，验证码输入后将失效。请妥善保管这两个内容，它们是生成验证码的关键，也请不要泄露这个二维码

粗略翻译下选项

Do you want authentication tokens to be time-based

需要启用基于时间的认证吗？

Do you want me to update your "/root/.google_authenticator" file?

需要更新配置文件吗？

Do you want to disallow multiple uses of the same authentication
token? This restricts you to one login about every 30s, but it increases
your chances to notice or even prevent man-in-the-middle attacks ?

禁止多次使用同一个身份验证令牌吗？这将限制大约每 30 秒登录一次，它将减少中间人攻击的机会

By default, a new token is generated every 30 seconds by the mobile app.
In order to compensate for possible time-skew between the client and the server,
we allow an extra token before and after the current time. This allows for a
time skew of up to 30 seconds between authentication server and client. If you
experience problems with poor time synchronization, you can increase the window
from its default size of 3 permitted codes (one previous code, the current
code, the next code) to 17 permitted codes (the 8 previous codes, the current
code, and the 8 next codes). This will permit for a time skew of up to 4 minutes
between client and server.
Do you want to do so? 

默认情况下，移动应用程序每 30 秒生成一个新令牌。
为了补偿客户端和服务器之间可能的时间偏差，
我们允许在当前时间之前和之后一个额外的令牌。这允许一个
身份验证服务器和客户端之间的时间偏差最大为 30 秒。如果你
遇到时间同步不好的问题，可以增加窗口
从其默认大小的 3 个允许代码（一个以前的代码，当前的
代码，下一个代码）到 17 个允许的代码（前 8 个代码，当前代码
代码，以及接下来的 8 个代码）。这将允许最多 4 分钟的时间偏差
客户端和服务器之间。
要这样做吗？

If the computer that you are logging into isn't hardened against brute-force
login attempts, you can enable rate-limiting for the authentication module.
By default, this limits attackers to no more than 3 login attempts every 30s.
Do you want to enable rate-limiting?

如果您登录的计算机没有针对蛮力进行强化
登录尝试，您可以为身份验证模块启用速率限制。
默认情况下，这会将攻击者限制为每 30 秒不超过 3 次登录尝试。
您要启用速率限制吗？

这个时候二步认证是还没有生效的，还需要修改 pam 以及 ssh 配置，请仔细小心地修改配置，任何一处错误都可能导致 ssh 无法连接

鉴于操作危险性，建议提前对机子进行备份，比如腾讯云轻量的镜像备份，一个地区五个免费配额，不用白不用是吧（手动狗头）

文件 /etc/pam.d/sshd
```
+auth required pam_google_authenticator.so
```
文件 /etc/ssh/sshd_config
```
-ChallengeResponseAuthentication no
+ChallengeResponseAuthentication yes
```
保存好二维码、密钥以及备用验证码后断开连接重新登录服务器，这时输入密码后将会出现二步验证

0x02 设置验证码生成设备

目前有很多家验证器客户端比较流行的有 Google Authenticator 、 Microsoft Authenticator、Authy 等。

Microsoft Authenticator、Authy 相比 Google Authenticator 多了一套云同步系统，能防止意外清除软件数据之后丢失密钥导致的各种问题出现。但请注意，选择了带有云同步功能的应用中使用的同步账号必须设置一个高强度密码，避免同步账号被盗取泄露验证码。

因为各家 Authenticator 都不允许界面截图，所以它欠咱几张图片

这里选用 Google Authenticator 下载安装后进入软件，选择扫描条形码，然后扫描上面保存的图片即可，或选择手动输入，账户为备注名字，可随意，密钥则为保存的密钥。

0x03 算法原理

现有实现了 TOTP 的软件中的算法本质上就是 HMAC-SHA-1 算法，也就是带有盐值的 SHA-1

以 secret 密钥为盐值取当前时间的摘要，即 HMAC-SHA-1(K,C)

K 为密钥，C 为当前 UNIX 时间 / 30，之所以除以 30 就是为了取整获得一个 30 内相同的值

这样就得到了一个原始的哈希值，当然得到这个哈希值还不行，因为哈希值是 20 字节长的，对于 30 秒的验证码来说太长了，所以 HEX = HMAC-SHA-1(K,C) 等下还要用
取 HEX 的第 20 字节，也就是 **HEX[19] 的低四位（后四位）**作为偏移量 OFFEST
在 HEX 中，从偏移量 OFFEST 开始取四个字节作为验证码中间值 WIP
将 WIP mod 10^6 得到 6 位数字，不够 6 位高位补 0 即验证码

举个例子

0x04 使用 Java 实现算法

魔法时刻

核心算法 HMAC-SHA-1

/**
     * HmacSHA1 计算
     *
     * @param source 数据源
     * @param key    密钥
     * @return String 计算结果
     */
    public static String sha1(String source, String key) {
        try {
            Mac mac = Mac.getInstance("HmacSHA1");
            SecretKeySpec keySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA1");
            mac.init(keySpec);
            byte[] byteArray = mac.doFinal(source.getBytes(StandardCharsets.UTF_8));
            StringBuilder stringBuilder = new StringBuilder();
            for (byte temp : byteArray) {
                stringBuilder.append(String.format("%02x", temp));
            }
            return stringBuilder.toString();
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }

流程

package io.hanbings.cynops.extra.otpauth;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.ByteArrayInputStream;
import java.io.DataInput;
import java.io.DataInputStream;
import java.io.IOException;
import java.util.Objects;

/**
 * 实现 RFC6238 中描述的 TOTP <br>
 * Time-Based One-Time Password 基于时间的一次性密码 <br>
 * 参考 <br>
 * 1. https://datatracker.ietf.org/doc/html/rfc6238 <br>
 * 2. https://www.aqniu.com/tools-tech/4671.html
 */
@SuppressWarnings("unused")
public class Totp {
    public static String totp(byte[] secret, String algorithm, int distance, long offset) {
        // (当前时间 + 时间偏移量) / 时间片间隔
        long time = ((System.currentTimeMillis()) / 1000) / distance;
        byte[] data = sha1(longToByte(time), secret, algorithm);
        int index = Objects.requireNonNull(data)[19] & 0xf;
        int wip = byteToInt(data, index) & 0x7fffffff;
        return padding(wip);
    }

    /**
     * SHA1 计算
     *
     * @param source 数据源
     * @param key    密钥
     * @return String 计算结果
     */
    private static byte[] sha1(byte[] source, byte[] key, String algorithm) {
        try {
            Mac mac = Mac.getInstance(algorithm);
            SecretKeySpec keySpec = new SecretKeySpec(key, algorithm);
            mac.init(keySpec);
            return mac.doFinal(source);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    /**
     * long 转换为 byte
     *
     * @param time long 数据
     * @return byte 数组
     */
    private static byte[] longToByte(long time) {
        byte[] bytes = new byte[8];
        for (int count = 0; count < 8; count++) {
            int offset = 64 - (count + 1) * 8;
            bytes[count] = (byte) ((time >> offset) & 0xff);
        }
        return bytes;
    }

    /**
     * byte 转换 int
     *
     * @param bytes byte 数组
     * @param start 开始位移
     * @return int
     */
    private static int byteToInt(byte[] bytes, int start) {
        DataInput input = new DataInputStream(new ByteArrayInputStream(bytes, start, bytes.length - start));
        int temp;
        try {
            temp = input.readInt();
        } catch (IOException e) {
            throw new IllegalStateException(e);
        }
        return temp;
    }

    /**
     * 高位补0
     *
     * @param wip 已经处理好的验证码
     * @return 最终结果
     */
    private static String padding(int wip) {
        StringBuilder code = new StringBuilder(String.valueOf(wip % 1000000));
        for (; ; ) {
            if (code.length() < 6) {
                code.insert(0, "0");
            } else {
                return code.toString();
            }
        }
    }
}

处理符合 Google Authenticator 要求的 Base32 格式的密钥

注意下这里处理只是为了得到 Google Authenticator 能识别的密钥，事实上传入 HMAC-SHA-1 的还是需要解码 Base32 的原始密钥

/**
     * 编码 Base32
     *
     * @param source 原始字符
     * @return Base 编码字符
     */
    private static String encode(byte[] source) {
        char[] chars = new char[((source.length * 8) / 5) + ((source.length % 5) != 0 ? 1 : 0)];
        for (int count = 0, handle = 0, index = 0; count < chars.length; count++) {
            if (index > 3) {
                int token = source[handle] & (0xFF >> index);
                index = (index + 5) % 8;
                token <<= index;
                if (handle < source.length - 1) {
                    token |= (source[handle + 1] & 0xFF) >> (8 - index);
                }
                chars[count] = ALPHABET[token];
                handle++;
            } else {
                chars[count] = ALPHABET[((source[handle] >> (8 - (index + 5))) & 0x1F)];
                index = (index + 5) % 8;
                if (index == 0) {
                    handle++;
                }
            }
        }
        return new String(chars);
    }

    /**
     * Base32 解码
     *
     * @param source Base32 编码字符串
     * @return 原始字符
     */
    private static byte[] decode(String source) {
        char[] stringData = source.toCharArray();
        byte[] data = new byte[(stringData.length * 5) / 8];
        for (int count = 0, handle = 0, index = 0; count < stringData.length; count++) {
            int token = DECODE_TABLE[stringData[count]];
            if (index <= 3) {
                index = (index + 5) % 8;
                if (index == 0) {
                    data[handle++] |= token;
                } else {
                    data[handle] |= token << (8 - index);
                }
            } else {
                index = (index + 5) % 8;
                data[handle++] |= (token >> index);
                if (handle < data.length) {
                    data[handle] |= token << (8 - index);
                }
            }
        }
        return data;
    }

计算验证码

/**
     * 生成符合要求的密钥
     *
     * @return 密钥
     */
    public static String secret() {
        try {
            SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
            return encode(random.generateSeed(10)).toUpperCase(Locale.ROOT);
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        }
        return null;
    }

    /**
     * 获取当前验证码
     *
     * @param secret 密钥
     * @return 验证码
     */
    public static String code(String secret) {
        return Totp.totp(
                decode(secret),
                "HmacSHA1"
                , 30
                , 0);
    }

0x05 最后

文章中可能还有错误的地方，欢迎各位提出。

文中提及的代码均在我的开源 Java 中间件项目 Cynops 中，欢迎 Star ，也可以 Follow 我的 Github Hanbings 还请前辈们多多指教。

🐱 寒冰是喵喵的 blog

音程与和弦

Astro、MDX 与 Shader

Markdown 边注、术语与钢琴窗测试

MDX 组件

MDX 手绘标注

术语原文

文章附记

自定义标题与 Markdown

嵌套为卡片堆

钢琴窗

窄屏、RSS 与无障碍

相关规范与文档

Rust：使用 uefi-rs 编写一个 UEFI 应用并加载内核

使用 uefi-rs 库

UEFI

uefi-rs

数据类型

修饰符

入口函数

调用函数

UEFI Application 与 UEFI Protocol

SimpleFileSystem Protocol

Memory Allocator

GraphicsOutput Protocol

Rust Inline ASM

内核部分

启动！

oscamp：操作系统 Hypervisor 方向（Draft）

开发环境

AMD 不嘻嘻

在 Bochs 中全仿真 vmx

Intel VMX 指令集与 AMD SVM 指令集

需要做的工作为：

目前思路

进度

虚拟化技术：AMD SVM Hypervisor（Draft）

检查本机是否支持虚拟化技术

CPUID 与 SVM 特性

VM CR

开启 EFER.SVME

切换到虚拟化环境

初始化与加载 VMCB

设置退出条件

VMRUN

Rust：实现一份 Mimalloc（Draft）

mimalloc 核心机制

分配（空间）局限性（ Locality of Allocation）

free_list、local_list 与 thread_list

不使用碰撞指针

Chaos HMM 实现

简要描述

数据结构

Rust 全局分配器

oscamp：字节分配器 Chaos

分析内存结构

堆中的 Vec<Vec<u8>> 结构数据

存放数据的堆空间

Chaos 真的不 Chaos

整体结构

实现

越界访问

预分配：尽可能使用更多的内存

再挤一挤，内存还是有的

Rust：实现插件系统

目标

加载器侧

关于结构体的内存布局

关于 c_int

插件侧

关于 #[no_mangle]

完整代码：

参考

Effective Rust - 类型 - 速查表（停止更新）

一. 使用类型系统表达数据结构

二. 使用类型系统表达共同行为

三. 使用 match 表达式转换 Option 和 Result

Java 实现一个简单的 EventBus

0x00 EventBus

0x01 发布/订阅者模式与观察者模式

堆中的 `Vec<Vec<u8>>` 结构数据

关于 `c_int`

关于 `#[no_mangle]`

4. RegisterListener - 监听器容器处理器列表优先级排序