欢迎来到rust嵌入式书:这本书介绍怎么使用rust开发如微控制器的裸板嵌入式系统。

嵌入式rust是为需要嵌入式编程同时还需要rust语言高抽象和安全概念的人。

这本书的目的是：

• 让开发者快速的进行rust嵌入式开发，比如如何配置好开发环境。
• 分享当前最好的嵌入式rust开发练习。比如怎么最好用rust的特性去实现更多的嵌入式软件。
• 如何与c混合的开发项目

本书使用 ARM Cortex-M框架作为例子,零开发经验的也没关系，本书会细心的讲解。

这本书迎合了有一些嵌入式背景或一些Rust背景的人，但是我们相信每个对嵌入式Rust编程感兴趣的人都可以从这本书中得到一些东西。对于那些没有任何先验知识的人，我们建议你阅读“假设和先决条件”部分，弥补遗漏的知识，从书中获得更多知识，改善你的阅读体验。您可以查看“其他参考资料”部分，以找到关于您可能想要了解的主题的参考资料。

你已经有了一些开发rust程序的经验，也熟悉2018版的语法。

你已经有了些嵌入式编程经验，可以使用c ,c++,Ada等类似语言。并熟悉以下概念：

• 交叉编译
• 外围设备的内存映射
• 常用接口:I2C,SPI,串口等

如果你不是上面提及到的，或你对指定的课题还需要更多的信息，下面的资源可能很有帮助。

这本书通常假设你是从头到尾读的。后面的章节建立在前面章节的概念基础上，前面的章节可能不会深入到一个主题的细节，在后面的章节中重新审视这个主题。

这本是遵循以下的几个许可：

让我们熟悉熟悉我们将使用的硬件。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-HocoqbNd-1659849615094)(/mnt/笔记/img/f3.jpg)]

这块板中包含什么？

有几种环境比较接近于常用的PC环境。这种环境提供系统接口，系统接口为你提供与各种系统交互的方式，如文件系统、网络、内存管理、线程等。反过来，标准库通常依赖于这些方式来实现其功能。您可能还有一些sysroot和RAM/ Rom使用的限制，可能还有一些特殊的HW或I/ O。总的来说，这感觉就像在一个特殊用途的PC环境中编写代码。

正如前面提到的，使用libstd需要某种类型的系统集成，但这不仅仅是因为libstd提供了一种访问操作系统抽象的通用方法，它还提供了一个运行时。这个运行时主要负责设置堆栈溢出保护、处理命令行参数以及在调用程序的main函数之前生成主线程。
此运行时在no_std环境中也不可用。

#![no_std]是一个crate级的属性，这个属性说明crate将链接到core-crate而不是标准std-crate。libcore crate是std crate的一个与平台无关的子集，它对程序将运行的系统没有任何假设。
因此，它提供了用于语言原语(如浮点数、字符串和片)以及用于公开处理器特性(如原子操作和SIMD指令)的api。
然而，它缺乏任何涉及平台集成的api。由于这些属性，no_std和libcore代码可以用于任何类型的引导(阶段0)代码，如引导加载程序、固件或内核。

*只有当你使用alloc crate和使用一个合适的分配器，如alloc-cortex-m。

**仅当您使用collections crate并配置全局默认分配器时。

处理微控制器涉及到使用几种不同的工具，因为我们将处理与你的笔记本电脑不同的架构，我们必须在远程设备上运行和调试程序。

我们将使用下面列出的所有工具。当没有指定最小版本时，任何最近的版本都可以工作，但是我们列出了已经测试过的版本。

裸机程序是非标准的(no_std) Rust程序，它需要对链接过程进行一些调整，以获得正确的程序的内存布局。
这需要一些额外的文件(如链接脚本)和设置(如链接标志)。
我们已经将它们打包在一个模板中，这样您只需要填写缺失的信息(例如项目名称和目标硬件的特征)。

cargo-generate：是Cargo子命令，用于从模板创建新的Cargo项目。你也可以使用git，curl，wget或者web浏览器去获得模板。

cargo-binutils是cargo子命令的一个集合，它使跟随rust工具链的LLVM工具更好用。这些工具包括LLVM版本的objdump, nm 和size，这些工具是用来检查二进制文件。

用LLVM工具而不是GNU工具的优点是用一句命令就能安装全部(rustup component add llvm-tools-preview) ，不管你的OS还是二进制工具如objdump都支持，rustc支持ARM到x86_64,因为他们同用LLVM后端。

QEMU是一个模拟器。在本例中我们使用这个软件可以完全的模拟ARM系统。我们在主机中使用QEMU运行嵌入式程序。对亏这个软件你可以在没有相应硬件的情况下跟着本书的例子做实验。

调试器对于嵌入式开发是一个非常重要的部分，当你可能不总有在控制台记录东西的习惯。在某些情况下，你可能都没有能提示你程序是否正确的led灯在你的硬件中。

通常来说，LLDB在调试时与GDB是一样的，但是LLDB没有与GDB对应的load命令，load命令可以上传程序到目标硬件，所以现在我们推荐的是使用GDB。

GDB不能直接的与ST-Link交互来调试你的STM32F3DISCOVERY开发板，它需要一个转换器和开源片上调试器，Openocd就是那个转换器。OpenOCD是一个运行在你的笔记本/PC上的一个程序，它可以转换基于远程调试协议的gdbTCP/IP协议和ST-link的usb协议。

OpenOCD还执行其他重要的工作，作为其转换的一部分，用于调试STM32F3DISCOVERY开发板上基于ARM Cortex-M的微控制器:

1.它知道如何与ARM CoreSight调试外设使用的内存映射寄存器进行交互。正是这些CoreSight寄存器允许:

• 断点/检测点的操作
• 读或写CPU寄存器
• 检测CPU因调试事件而停止
• 调试事件后继续执行CPU
• 等等

2.它还知道如何擦去和写入控制器的闪存中。

这节包括一些与操作无关的工具的安装。

cargo install cargo-binutils

rustup component add llvm-tools-preview

我们一会将使用这个来生成一个项目模板。

cargo install cargo-generate

注意：在一些linux的衍生版（如ubuntu）你可能需要先安装libssl-dev和pkg-config依赖

这就是几种版本linux的命令。

• Ubuntu 18.04/Debian stretch 或更高的版本.

注意：gdb-multiarch是GDB命令，你将使用这个命令调试 ARM Cortex-M程序。

sudo apt install gdb-multiarch openocd qemu-system-arm

• Ubuntu 14.04 和 16.04

注意：arm-none-eabi-gdb是GDB命令，你将使用这个命令调试 ARM Cortex-M程序。

sudo apt install gdb-arm-none-eabi openocd qemu-system-arm

• Fedora 27 或这更高版本

注意:arm-none-eabi-gdb是GDB命令，你将使用这个命令调试 ARM Cortex-M程序。

sudo dnf install arm-none-eabi-gdb openocd qemu-system-arm

• Arch Linux

注意:arm-none-eabi-gdb是GDB命令，你将使用这个命令调试 ARM Cortex-M程序。

sudo pacman -S arm-none-eabi-gdb qemu-arch-extra openocd

udev规则让你在没有跟权限的开发板中使用OpenOCD.

创造文件/etc/udev/rules.d/70-st-link.rules内容如下：

# STM32F3DISCOVERY rev A/B - ST-LINK/V2
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", TAG+="uaccess"

# STM32F3DISCOVERY rev C+ - ST-LINK/V2-1
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", TAG+="uaccess"

然后用以下命令重新加载所有udev规则:

sudo udevadm control --reload-rules

如果你把电路板插到你的笔记本电脑上，拔掉它，然后再插上。

使用该命令查看权限:

lsusb

应该显示如下内容:

(..) 

Bus 001 Device 018: ID 0483:374b STMicroelectronics ST-LINK/V2.1 

(..)

注意总线和设备编号。使用这些数字创建如下路径

/dev/bus/usb/<bus>/<device>

然后像这样使用路径:

ls -l /dev/bus/usb/001/018

crw-------+ 1 root root 189, 17 Sep 13 12:34 /dev/bus/usb/001/018

getfacl /dev/bus/usb/001/018 | grep use

user::rw- 
user:you:rw-

权限后面的+表示扩展权限的存在。getfacl命令告诉用户可以使用该设备。

现在，去下一节。

所有工具都可以安装使用

在本节中，我们将检查一些必需的工具/驱动程序是否已正确安装和配置。

用micro USB连接笔记本和开发板。发现板有两个USB连接器;
使用一个标有“USB ST-LINK”，位于板边缘的中心。

还要检查是否填充了ST-LINK头。见下图;ST-LINK的标题用红色圆圈标出。

现在运行接下来的命令：

openocd -f interface/stlink.cfg -f target/stm32f3x.cfg

**注意：**openocd的老版本，包括2017年发布的0.10.0，不包含新的(最好)interface/stlink.cfg文件；取而代之的应该需要interface/stlink-v2.cfg 或 interface/stlink-v2-1.cfg.

你应该得到以下输出，程序应该阻塞控制台:

Open On-Chip Debugger 0.10.0
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
adapter speed: 1000 kHz
adapter_nsrst_delay: 100
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
none separate
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : Unable to match requested speed 1000 kHz, using 950 kHz
Info : clock speed 950 kHz
Info : STLINK v2 JTAG v27 API v2 SWIM v15 VID 0x0483 PID 0x374B
Info : using stlink api v2
Info : Target voltage: 2.919881
Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints

内容可能不完全匹配，但应该看到关于断点和观察点的最后一行。
如果您得到了它，那么可以终止OpenOCD进程并进入下一节

如果你没有得到"breakpoints"行，请尝试接下来的指令。

openocd -f interface/stlink-v2.cfg -f target/stm32f3x.cfg

openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg

如果其中一个命令有效，就意味着你得到了一个旧的硬件版本的发现板。这不是问题，但请记住这一事实，因为稍后您将需要配置一些不同的东西。你可以进入下一部分了。

如果这些命令都不能作为普通用户运行，那么尝试使用root权限运行它们 (e.g. sudo openocd ..)。如果命令在root权限下工作，那么检查udev规则是否设置正确。

如果你已经到达这个点，OpenOCD不工作，请打开一个问题，我们会帮助你!

在本节中，我们将带您完成编写、构建、闪烁和调试嵌入式程序的过程。
您将能够在不使用任何特殊硬件的情况下尝试大多数示例，因为我们将使用QEMU(一种流行的开源硬件模拟器)向您展示基础知识。
当然，唯一需要硬件的部分就是硬件部分，我们使用OpenOCD对STM32F3DISCOVERY进行编程。

我们将开始为LM3S6965，一个Cortex-M3编写程序控制器。我们选择它作为我们的初始目标，因为它可以使用QEMU进行模拟，因此在本节中不需要摆弄硬件，我们可以将重点放在工具和开发过程上。

重要的是：在本教程中，我们将使用“app”作为项目名称。
当你看到“app”这个词的时候，你应该把它替换成你为你的项目选择的名称。或者，你也可以将你的项目命名为“app”，避免替换。

我们将使用cortex-m-quickstart项目模板从中生成一个新项目。创建的项目将包含一个基本的应用程序:一个新的嵌入式rust应用程序的良好起点。
此外，该项目将包含一个示例目录，带有几个单独的应用程序，突出显示一些关键的嵌入式rust功能。

首先安装cargo-generate

cargo install cargo-generate

然后产生一个新的工程

cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart

 Project Name: app
 Creating project called `app`...
 Done! New project created /tmp/app

cd app

克隆库

git clone https://github.com/rust-embedded/cortex-m-quickstart app
cd app

填充以下的到Cargo.toml文件

[package]
authors = ["{{authors}}"] # "{{authors}}" -> "John Smith"
edition = "2018"
name = "{{project-name}}" # "{{project-name}}" -> "app"
version = "0.1.0"

# ..

[[bin]]
name = "{{project-name}}" # "{{project-name}}" -> "app"
test = false
bench = false

现在最新版本的cortex-m-quickstart模板的快照，然后解压它。

curl -LO https://github.com/rust-embedded/cortex-m-quickstart/archive/master.zip
unzip master.zip
mv cortex-m-quickstart-master app
cd app

为了方便这里是大部分重要的源代码,src/main.rs:

#![no_std]
#![no_main]

use panic_halt as _;

use cortex_m_rt::entry;

#[entry]
fn main() -> ! {
    loop {
        // your code goes here
    }
}

和正常的rust程序有点不同，让我们再仔细看看。

#![no_std]显示程序不会连接标准crate std。而是会连接std的子集core crate。

#![no_main]显示程序不会使用普通rust程序的标准的main函数接口这个main（没有双关语义）使用no_main的原因是使用main接口在no_std环境下需要nightly版本。

use panic_halt as _;.这个crate提供了一个panic_handler，它定义了恐慌行为的程序。我们可以恐慌这一章节找到更细节。

接下来的步骤就是交叉编译程序，目标是Cortex-M3 框架。很容易的运行cargo build --target $TRIPLE。你应该知道 $TRIPLE是什么，幸运的是，模板中的.cargo/config.toml有这个答案：

tail -n6 .cargo/config.toml

[build]
# Pick ONE of these compilation targets
# target = "thumbv6m-none-eabi"    # Cortex-M0 and Cortex-M0+
target = "thumbv7m-none-eabi"    # Cortex-M3
# target = "thumbv7em-none-eabi"   # Cortex-M4 and Cortex-M7 (no FPU)
# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)

交叉编译到Cortex-M3框架我们必须使用thumbv7m-none-eabi。目标平台不是在安装rust工具链就自动安装上的，现在正式好时候去添加目标平台到工具链：

rustup target add thumbv7m-none-eabi

因为thumbv7m-none-eabi编译目标已在.cargo/config.toml中设置为默认值。下面的两个命令执行相同的操作:

cargo build --target thumbv7m-none-eabi
cargo build

现在我们有一个非本地的ELF二进制文件在target/thumbv7m-none-eabi/debug/app.我们可以使用cargo-binutils来检查。

使用cargo-readobj，我们可以打印ELF报头来确认这是一个ARM二进制文件。

cargo readobj --bin app -- --file-headers

注意：

• --bin app是用于检查而二进制文件的魔法糖
• --bin app如果需要的话，会编译二进制文件。

ELF Header:
  Magic:   7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00
  Class:                             ELF32
  Data:                              2's complement, little endian
  Version:                           1 (current)
  OS/ABI:                            UNIX - System V
  ABI Version:                       0x0
  Type:                              EXEC (Executable file)
  Machine:                           ARM
  Version:                           0x1
  Entry point address:               0x405
  Start of program headers:          52 (bytes into file)
  Start of section headers:          153204 (bytes into file)
  Flags:                             0x5000200
  Size of this header:               52 (bytes)
  Size of program headers:           32 (bytes)
  Number of program headers:         2
  Size of section headers:           40 (bytes)
  Number of section headers:         19
  Section header string table index: 18

cargo-size可以打印链接器段的二进制文件的大小。

cargo size --bin app --release -- -A

我们使用–release来检查优化的版本

app  :
section             size        addr
.vector_table       1024         0x0
.text                 92       0x400
.rodata                0       0x45c
.data                  0  0x20000000
.bss                   0  0x20000000
.debug_str          2958         0x0
.debug_loc            19         0x0
.debug_abbrev        567         0x0
.debug_info         4929         0x0
.debug_ranges         40         0x0
.debug_macinfo         1         0x0
.debug_pubnames     2035         0x0
.debug_pubtypes     1892         0x0
.ARM.attributes       46         0x0
.debug_frame         100         0x0
.debug_line          867         0x0
Total              14570

ELF链接器段的复习

• .text 包含程序指令
• .rodata 包含类似字符串的常量
• .data 包含初始值不为零的静态分配变量
• .bss 还包含初始值为零的静态分配变量（未初始化变量）
• .vector_table是一个非标准的段，我们用来存储向量(中断)表
• .ARM.attributes和.debug_*段包含元数据和在烧写二进制文件时不被加载

**重要：**ELF文件包括像调试信息这样的元数据，它们在磁盘上的大小不能准确反应烧写在设备上占用的空间。

总是要用cargo-size来检查二进制文件的真实大小。

cargo-objdump可用于反汇编二进制文件。

cargo objdump --bin app --release -- --disassemble --no-show-raw-insn --print-imm-hex

注意: 如果上面的命令爆出Unknown command line argument的问题，见bug报告

https://github.com/rust-embedded/book/issues/269

注意：这个输出在您的系统上可能不同。
新版本的rustc、LLVM和库可以生成不同的程序集。
我们截取了一些指令，以保持代码片段较小。

app:  file format ELF32-arm-little

Disassembly of section .text:
main:
     400: bl  #0x256
     404: b #-0x4 <main+0x4>

Reset:
     406: bl  #0x24e
     40a: movw  r0, #0x0
     < .. truncated any more instructions .. >

DefaultHandler_:
     656: b #-0x4 <DefaultHandler_>

UsageFault:
     657: strb  r7, [r4, #0x3]

DefaultPreInit:
     658: bx  lr

__pre_init:
     659: strb  r7, [r0, #0x1]

__nop:
     65a: bx  lr

HardFaultTrampoline:
     65c: mrs r0, msp
     660: b #-0x2 <HardFault_>

HardFault_:
     662: b #-0x4 <HardFault_>

HardFault:
     663: <unknown>

接下来，让我们看看如何运行嵌入式程序在QEMU上！我们将使用hello例子来做一些事。

为了方便这就是源代码，examples/hello.rs:

//! Prints "Hello, world!" on the host console using semihosting

#![no_main]
#![no_std]

use panic_halt as _;

use cortex_m_rt::entry;
use cortex_m_semihosting::{debug, hprintln};

#[entry]
fn main() -> ! {
    hprintln!("Hello, world!").unwrap();

    // exit QEMU
    // NOTE do not run this on hardware; it can corrupt OpenOCD state
    debug::exit(debug::EXIT_SUCCESS);

    loop {}
}

程序使用semihosting打印文本在主机的控制台。当真正跑在硬件的时候需要调试会话，但是在QEMU这样就可以输出调试信息了。

让我们编译这个例子：

cargo build --example hello

这个输出的二进制将被放置在target/thumbv7m-none-eabi/debug/examples/hello

运行这个二进制文件在QEMU，运行

qemu-system-arm \
  -cpu cortex-m3 \
  -machine lm3s6965evb \
  -nographic \
  -semihosting-config enable=on,target=native \
  -kernel target/thumbv7m-none-eabi/debug/examples/hello

Hello, world!

在打印文本之后，命令应该会成功退出（成功退出的代码为0）.

在类unix系统上你可以检查是否成功用接下来的命令：

echo $?

0

让我们分解以下上面这个QEMU指令：

• qemu-system-arm。这是QEMU模拟器。这些QEMU二进制文件有几个变体。这是一个ARM机器的完整系统模拟，因此得名。
• -cpu cortex-m3。告诉QEMU模拟的是Cortex-M3 CPU.指定CPU模型可以让我们捕捉一些错误编译错误:举个例子，运行一个Cortex-M4F的编译程序，在QEMU在执行的时候会产生错误。
• -machine lm3s6965evb.这个命令告诉QEMU模拟LM3S6965EVB,一个包含LM3S6965单片机的评估板。
• -nographic.这个指令告诉QEMU不要使用GUI。
• -semihosting-config (..).这个指令告诉QEMU开启semihosting。semihosting允许模拟设备使用主机标准输出、标准错误和标准输入，并在主机上创建文件。
• -kernel $file.这将告诉QEMU在仿真机器上加载和运行哪个二进制文件。

输入冗长的QEMU命令工作量太大了!我们可以设置一个定制的运行器来简化这个过程。

.cargo/config.toml有一行注释掉了的运行器，它会调用QEMU；让我们取消它：

head -n3 .cargo/config.toml

[target.thumbv7m-none-eabi]
# uncomment this to make `cargo run` execute programs on QEMU
runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"

这个运行器只适用于thumbv7m-none-eabi目标，这是我们的默认编译目标。现在cargo run将编译程序并在QEMU上运行:

cargo run --example hello --release

   Compiling app v0.1.0 (file:///tmp/app)
    Finished release [optimized + debuginfo] target(s) in 0.26s
     Running `qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel target/thumbv7m-none-eabi/release/examples/hello`
Hello, world!

调试对于嵌入式开发至关重要。让我们看看是怎么做的。

调试嵌入式设备涉及到远程调试，因为我们想要调试的程序不会在运行调试程序(GDB或LLDB)的机器上运行。

远程调试调用了一个客户端和一个服务器。在QEMU设置中，客户端将是一个GDB(或LLDB)进程，服务器将是同时运行嵌入式程序的QEMU进程。

在这节我们将使用hello的例子，我们已经编译过了。

调试的第一步开启QEMU的调试模式：

qemu-system-arm \
  -cpu cortex-m3 \
  -machine lm3s6965evb \
  -nographic \
  -semihosting-config enable=on,target=native \
  -gdb tcp::3333 \
  -S \
  -kernel target/thumbv7m-none-eabi/debug/examples/hello

这个命令不会打印任何东西到控制台但会堵塞终端。这时我们要添加两个额外的flag：

• -gdb tcp::3333.这个将会告诉QEMU等待GDB的TCP连接在3333端口。
• -S。这告诉QEMU在启动时冻结机器。如果不这样做，程序就会在我们有机会启动调试器之前到达main的末尾!

接下来，我们在另一个终端启动GDB，并告诉它加载示例的调试符号:

gdb-multiarch -q target/thumbv7m-none-eabi/debug/examples/hello

注意：你可能需要另一个版本的gdb来取代gdb-multiarch，这就取决于在安装章节你安装的是哪一个。这个gdb可以是arm-none-eabi-gdb或就是gdb。

然后GDB所在的shell 我们连接QEMU，等待TCP连接到3333端口。

target remote :3333

Remote debugging using :3333
Reset () at $REGISTRY/cortex-m-rt-0.6.1/src/lib.rs:473
473     pub unsafe extern "C" fn Reset() -> ! {

您将看到进程停止，程序计数器指向一个名为Reset的函数。
这就是复位处理器:Cortex-M内核在启动时所执行的。

注意：注意，在某些设置中，不显示Reset () at $REGISTRY/cortex-m-rt-0.6.1/src/lib.rs:473如上所示，GDB可能会打印如下警告:
`

core::num::bignum::Big32x40::mul_small () at src/libcore/num/bignum.rs:254src/libcore/num/bignum.rs: No such file or directory.

这是一个众所周知的故障。您可以放心地忽略这些警告，您最可能使用的是Reset()。

这个重置终将调用我们的主函数。让我们使用断点和continue命令跳过这些步骤。在设置断点之前我们要在哪打断我们的代码。使用 list 命令。

list main

这将显示examples/hello.rs.的源代码

6       use panic_halt as _;
7
8       use cortex_m_rt::entry;
9       use cortex_m_semihosting::{debug, hprintln};
10
11      #[entry]
12      fn main() -> ! {
13          hprintln!("Hello, world!").unwrap();
14
15          // exit QEMU

我们想要添加断点在“Hello world“之前，在13行,我们使用break命令：

break 13

我们现在可以指示gdb继续运行我们的主函数，使用 continue 命令：

continue

Continuing.

Breakpoint 1, hello::__cortex_m_rt_main () at examples\hello.rs:13
13          hprintln!("Hello, world!").unwrap();

我们1现在接近 打印“Hello,world!”代码。让我们继续向后执行使用next命令。

next

16          debug::exit(debug::EXIT_SUCCESS);

使用qemu-system-arm.你将看见“Hello,world！”打印在终端上。

$ qemu-system-arm (..)
Hello, world!

再次调用next将终止QEMU进程。

next

[Inferior 1 (Remote target) exited normally]

你现在可以退出GDB会话。

quit

到目前而止，你也已经熟悉工具链和开发进程。在这节中，我们将转换到真的硬件中；在很大程度都是相同的，让我们一探究竟把。

在开始之前，你需要识别一些在目标设备上的字符，这些字符将会用来配置工程：

• ARM内核 如Cortex-M3.
• ARM内核中是否包括FPU？Cortex-M4F 和 Cortex-M7F就包括。
• 多少的闪存和RAM容量 如 256KiB的Flash 和32KiB RAM.
• 闪存和RAM映射的地址空间在哪？如 RAM 通常位于地址0x2000_0000。

在这节中，我们将使用STM32F3DISCOVERY开发板，这个开发板包括STM32F303VCT6微控制器.这个控制器有;

有一个Cortext-M4F内核包括一个单精度FPU

256KiB闪存在地址0x0800_0000.

40KiBRAM在0x2000_0000。（还有另一个RAM区域，但为了简单起见，我们忽略它）

嵌入式系统只能通过执行普通的Rust代码和在RAM中移动数据走到这一步。如果我们想让任何信号进出我们的系统（如点亮一个led灯，检测按钮按下或与某种总线上的芯片外设备通信）我们将不得不进入外设的世界和他们的“内存映射寄存器”。

你可能会发现你需要在微控制器中访问外设的代码已经写好了，在以下级别之一:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-0ecAyMyV-1659849615098)(/mnt/笔记/img/crates.png)]

如果你是嵌入式Rust的新手，crate是一个完美的起点。它们很好地抽象出了在开始学习这门学科时可能会令人不知所措的硬件细节，并使标准任务变得简单，像LED的开关。板之间展现的功能差距过大。由于本书的目标是保持硬件不可知，所以crate不在本书的讨论范围之内。
如果你想实验STM32F3DISCOVERY板，强烈建议看一下stm32f3-discovery crate，它提供了闪烁led，指南针，蓝牙等功能。

让我们看看所有基于Cortex-M的微控制器都常见的SysTick外围设备。我们可以在cortex-m crate中找到一个相当底层的API，我们可以这样使用它:

#![no_std]
#![no_main]
use cortex_m::peripheral::{syst, Peripherals};
use cortex_m_rt::entry;
use panic_halt as _;

#[entry]
fn main() -> ! {
    let peripherals = Peripherals::take().unwrap();
    let mut systick = peripherals.SYST;
    systick.set_clock_source(syst::SystClkSource::Core);
    systick.set_reload(1_000);
    systick.clear_current();
    systick.enable_counter();
    while !systick.has_wrapped() {
        // Loop
    }

    loop {}
}

如果我们把自己限制在每个Cortex-M都包含的基本外设上，我们就不会在嵌入式软件开发上走得太远。在某些情况下，我们需要编写一些特定于我们所使用的特定微控制器的代码。在这个例子中，让我们假设我们有一个Texas Instruments TM4C123 -一个中等的80MHz Cortex-M4闪存256 KiB的控制器。我们将引入tm4c123x crate来使用该芯片。

#![no_std]
#![no_main]

use panic_halt as _; // panic handler

use cortex_m_rt::entry;
use tm4c123x;

#[entry]
pub fn init() -> (Delay, Leds) {
    let cp = cortex_m::Peripherals::take().unwrap();
    let p = tm4c123x::Peripherals::take().unwrap();

    let pwm = p.PWM0;
    pwm.ctl.write(|w| w.globalsync0().clear_bit());
    // Mode = 1 => Count up/down mode
    pwm._2_ctl.write(|w| w.enable().set_bit().mode().set_bit());
    pwm._2_gena.write(|w| w.actcmpau().zero().actcmpad().one());
    // 528 cycles (264 up and down) = 4 loops per video line (2112 cycles)
    pwm._2_load.write(|w| unsafe { w.load().bits(263) });
    pwm._2_cmpa.write(|w| unsafe { w.compa().bits(64) });
    pwm.enable.write(|w| w.pwm4en().set_bit());
}

read()函数返回一个对象，它提供了对该寄存器内各个子字段的只读访问权限，由制造商的SVD文件定义的芯片。您可以在tm4c123x文档中找到这个特定寄存器的特殊R返回类型的所有可用函数，在指定的外围设备上，在指定的芯片上。

if pwm.ctl.read().globalsync0().is_set() {
    // Do a thing
}

write()函数接受一个带有单个参数的闭包。通常我们称之为w.然后，该参数提供了对该寄存器内的各个子字段的读写访问权，该寄存器由制造商针对该芯片的SVD文件定义。

如果我们只希望更改这个寄存器中的一个特定子字段，而不改变其他子字段，我们可以使用modify函数。这个函数接受一个带有两个参数的闭包—一个用于读取，一个用于写入。通常我们分别叫它们r和w.参数r可用于检查寄存器的当前内容,参数w可用于修改寄存器内容。

modify函数在这里真正展示了闭包的强大功能。在C中，我们必须读入一些临时值，修改正确的位，然后把值写回来。这意味着有相当大的误差范围:

uint32_t temp = pwm0.ctl.read();
temp |= PWM0_CTL_GLOBALSYNC0;
pwm0.ctl.write(temp);
uint32_t temp2 = pwm0.enable.read();
temp2 |= PWM0_ENABLE_PWM4EN;
pwm0.enable.write(temp); // Uh oh! Wrong variable!

芯片的HAL crate，通常通过为PAC暴露的原始结构实现自定义trait来工作。通常，这个trait会定义一个函数，叫做constraint()用于单个外设，或者split()用于像GPIO端口有多个引脚。这个函数将使用底层的原始外围设备结构，并返回一个具有更高级别API的新对象。这个API也可以做一些事情，比如串口new函数需要借用Clock结构，这只能通过调用配置锁相环和设置所有时钟频率的函数来生成。这样，不可能在没有配置时钟速率的情况下静态创建串口对象，或者串口对象错误地将波特率转换为时钟滴答声。

有些crate甚至为每个GPIO引脚可能处于的状态定义了特殊的trait，要求用户在把引脚传送到外围之前将一个引脚放入正确的状态.(例如，通过选择适当的备用功能模式)。所有这些都没有运行时成本!

让我们看看例子；

#![no_std]
#![no_main]

use panic_halt as _; // panic handler

use cortex_m_rt::entry;
use tm4c123x_hal as hal;
use tm4c123x_hal::prelude::*;
use tm4c123x_hal::serial::{NewlineMode, Serial};
use tm4c123x_hal::sysctl;

#[entry]
fn main() -> ! {
    let p = hal::Peripherals::take().unwrap();
    let cp = hal::CorePeripherals::take().unwrap();

    // Wrap up the SYSCTL struct into an object with a higher-layer API
    let mut sc = p.SYSCTL.constrain();
    // Pick our oscillation settings
    sc.clock_setup.oscillator = sysctl::Oscillator::Main(
        sysctl::CrystalFrequency::_16mhz,
        sysctl::SystemClock::UsePll(sysctl::PllOutputFrequency::_80_00mhz),
    );
    // Configure the PLL with those settings
    let clocks = sc.clock_setup.freeze();

    // Wrap up the GPIO_PORTA struct into an object with a higher-layer API.
    // Note it needs to borrow `sc.power_control` so it can power up the GPIO
    // peripheral automatically.
    let mut porta = p.GPIO_PORTA.split(&sc.power_control);

    // Activate the UART.
    let uart = Serial::uart0(
        p.UART0,
        // The transmit pin
        porta
            .pa1
            .into_af_push_pull::<hal::gpio::AF1>(&mut porta.control),
        // The receive pin
        porta
            .pa0
            .into_af_push_pull::<hal::gpio::AF1>(&mut porta.control),
        // No RTS or CTS required
        (),
        (),
        // The baud rate
        115200_u32.bps(),
        // Output handling
        NewlineMode::SwapLFtoCRLF,
        // We need the clock rates to calculate the baud rate divisors
        &clocks,
        // We need this to power up the UART peripheral
        &sc.power_control,
    );

    loop {
        writeln!(uart, "Hello, World!\r\n").unwrap();
    }
}

Semihosting 是一个允许嵌入式设备在主机上进行I/O操作，主要用于将消息记录到主机控制台的装置。Semihosting需要一个调试会话即可，所以它用起来非常的方便。但缺点是速度非常慢：由于硬件调试器的原因，每一个写入操作都会消耗几毫秒。

恐慌是Rust语言的核心部分。像索引这样的内置操作会在运行时检查内存安全性。当尝试越界索引时，这会导致恐慌。

在标准库中，恐慌有一个已定义的行为:除非用户选择在panic时中止程序，否则它会解开panic线程的堆栈。

下面是一个尝试在数组长度之外索引的例子。操作结果
导致恐慌。

#![no_main]
#![no_std]

use panic_semihosting as _;

use cortex_m_rt::entry;

#[entry]
fn main() -> ! {
    let xs = [0, 1, 2];
    let i = xs.len() + 1;
    let _y = xs[i]; // out of bounds access

    loop {}
}

这个例子使用panic-semihosting，它用semihosting在主机的控制台打印恐慌信息。

$ cargo run
     Running `qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb (..)
panicked at 'index out of bounds: the len is 3 but the index is 4', src/main.rs:12:13

你可以尝试改变到panic-halt，你将确信这个将不会有信息打印在主机控制台。

异常和中断是硬件的机制，处理器通过这种硬件机制处理异步事件和致命错误（如执行一个非法指令）。异常意味着抢占并涉及异常处理程序，即响应触发事件的信号而执行的子例程。

这个例子用系统时钟大约每秒抛出一个SysTick异常。SysTick异常处理程序在COUNT变量中跟踪它被调用的次数，然后使用semihosting将COUNT的值打印到主机控制台。

注意：你可以运行这个例子在任意Cortex-M设备；你也可以运行在QEMU上。

#![deny(unsafe_code)]
#![no_main]
#![no_std]

use panic_halt as _;

use core::fmt::Write;

use cortex_m::peripheral::syst::SystClkSource;
use cortex_m_rt::{entry, exception};
use cortex_m_semihosting::{
    debug,
    hio::{self, HStdout},
};

#[entry]
fn main() -> ! {
    let p = cortex_m::Peripherals::take().unwrap();
    let mut syst = p.SYST;

    // configures the system timer to trigger a SysTick exception every second
    syst.set_clock_source(SystClkSource::Core);
    // this is configured for the LM3S6965 which has a default CPU clock of 12 MHz
    syst.set_reload(12_000_000);
    syst.clear_current();
    syst.enable_counter();
    syst.enable_interrupt();

    loop {}
}

#[exception]
fn SysTick() {
    static mut COUNT: u32 = 0;
    static mut STDOUT: Option<HStdout> = None;

    *COUNT += 1;

    // Lazy initialization
    if STDOUT.is_none() {
        *STDOUT = hio::hstdout().ok();
    }

    if let Some(hstdout) = STDOUT.as_mut() {
        write!(hstdout, "{}", *COUNT).ok();
    }

    // IMPORTANT omit this `if` block if running on real hardware or your
    // debugger will end in an inconsistent state
    if *COUNT == 9 {
        // This will terminate the QEMU process
        debug::exit(debug::EXIT_SUCCESS);
    }
}

tail -n5 Cargo.toml

[dependencies]
cortex-m = "0.5.7"
cortex-m-rt = "0.6.3"
panic-halt = "0.2.0"
cortex-m-semihosting = "0.3.1"

$ cargo run --release
     Running `qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb (..)
123456789

如果你运行开发板的程序你将在openocd输出在控制台中。而且，当计数达到9时，程序不会停止。

exception属性的实际作用是覆盖特定异常的默认异常处理程序。如果你没有覆盖特定异常的处理程序，它将被DefaultHandler函数处理，默认为:

fn DefaultHandler() {
    loop {}
}

可以使用exception属性重写这个DefaultHandler:

#[exception]
fn DefaultHandler(irqn: i16) {
    // custom default handler
}

irqn参数表示正在处理哪个异常。负值表示正在处理一个Cortex-M异常;和0或正的值表明一个特定于设备的异常，又名中断，正在被服务。

HardFault异常有点特殊。当程序进入无效状态时触发此异常，因此其处理程序无法返回，因为这可能导致未定义的行为。此外，运行时crate在调用用户定义的HardFault处理程序之前会做一些工作，以提高可调试性。

结果是HardFault处理程序必须具有以下签名:fn(&ExceptionFrame) -> !.处理程序的参数是一个指针，指向被异常推入堆栈的寄存器。
这些寄存器是触发异常时处理器状态的快照，对于诊断硬故障非常有用。

下面是一个执行非法操作的例子:读取一个不存在的内存位置。

注意：这个程序将不会工作，它在QEMU上不会死机,因为qemu-system-arm -machine lm3s6965evb不会检查内存负载，并且在读取无效内存时愉快地返回0。

#![no_main]
#![no_std]

use panic_halt as _;

use core::fmt::Write;
use core::ptr;

use cortex_m_rt::{entry, exception, ExceptionFrame};
use cortex_m_semihosting::hio;

#[entry]
fn main() -> ! {
    // read a nonexistent memory location
    unsafe {
        ptr::read_volatile(0x3FFF_FFFE as *const u32);
    }

    loop {}
}

#[exception]
fn HardFault(ef: &ExceptionFrame) -> ! {
    if let Ok(mut hstdout) = hio::hstdout() {
        writeln!(hstdout, "{:#?}", ef).ok();
    }

    loop {}
}

HardFault处理程序输出ExceptionFrame值。
如果你运行这个，你会在OpenOCD控制台看到类似这样的东西。

$ openocd
(..)
ExceptionFrame {
    r0: 0x3ffffffe,
    r1: 0x00f00000,
    r2: 0x20000000,
    r3: 0x00000000,
    r12: 0x00000000,
    lr: 0x080008f7,
    pc: 0x0800094a,
    xpsr: 0x61000000
}

pc值是程序计数器在异常发生时的值，它指向触发异常的指令。

如果你看一下程序的拆解:

$ cargo objdump --bin app --release -- -d --no-show-raw-insn --print-imm-hex
(..)
ResetTrampoline:
 8000942:       movw    r0, #0xfffe
 8000946:       movt    r0, #0x3fff
 800094a:       ldr     r0, [r0]
 800094c:       b       #-0x4 <ResetTrampoline+0xa>

您可以在拆解程序中查找程序计数器0x0800094a的值。你将看见一个加载操作 (ldr r0, [r0] )引起异常。ExceptionFrame的r0字段将告诉您当时寄存器r0的值是0x3fff_fffe。

中断与异常在很多方面不同，但它们的操作和使用在很大程度上是相似的，而且它们也由同一个中断控制器处理。尽管异常是由Cortex-M架构定义的，但中断总是由供应商(甚至通常是芯片)特定的实现，无论是在命名还是功能上。

• 中断确实提供了很大的灵活性，这在试图以一种高级的方式使用它们时需要考虑。我们不会在本书中介绍这些用法，但是最好记住以下几点:
• 中断具有可编程的优先级，这些优先级决定了它们的处理程序的执行顺序
• 中断可以嵌套和抢占，即一个中断处理程序的执行可能会被另一个高优先级的中断中断
• 通常，需要清除导致中断触发的原因，以防止无止境地重新进入中断处理程序

运行时的一般初始化步骤总是相同的:

• 设置外设，以便在需要的场合生成中断请求
• 在中断控制器中设置所需的中断处理程序的优先级
• 在中断控制器中启用中断处理程序

与异常类似，cortex-m-rt crate提供了一个interrupt属性来声明中断处理程序。可用的中断(以及它们在中断处理程序表中的位置)通常是通过svd2rust从SVD描述自动生成的。

// Interrupt handler for the Timer2 interrupt
#[interrupt]
fn TIM2() {
    // ..
    // Clear reason for the generated interrupt request
}

中断处理程序看起来像普通函数(除了缺少参数)，类似于异常处理程序。但是由于特殊的调用约定，它们不能被固件的其他部分直接调用。然而，在软件中产生中断请求来触发中断处理程序的转移是可能的。

与异常处理程序类似，它也可以声明static mut变量在中断处理器中为了保持安全状态。

#[interrupt]
fn TIM2() {
    static mut COUNT: u32 = 0;

    // `COUNT` has type `&mut u32` and it's safe to use
    *COUNT += 1;
}

**待做：**使用寄存器覆盖内存映射I/O。

绝大部分控制器不仅有CPU,RAM,闪存，还包括用于交互的控制器外围系统，他们可以直接与传感器，电机驱动或者是人的输入输出接口（显示屏，键盘）交互。这些统称外围设备。

这些外设很有用，因为它们允许开发人员将处理工作转移到外设上，从而避免在软件中处理所有事情。
就像桌面开发人员将图形处理任务转移到显卡上一样，嵌入式开发人员也可以将一些任务转移到外围设备上，让CPU把时间花在其他重要的事情上，或者为了节省电力什么都不做。

如果你看一下20世纪70年代或80年代老式家用电脑的主板(实际上，昨天的台式电脑与今天的嵌入式系统相差不远)，你会期望看到:

• 一个处理器
• 一个RAM芯片
• 一个ROM芯片
• 一个I/O控制器

RAM芯片、ROM芯片和I/O控制器(这个系统的外围设备)将通过一系列被称为“总线”的并行轨迹与处理器连接。该总线携带地址信息，用于选择处理器与总线上希望通信的设备通信，以及携带实际数据的数据总线。在我们的嵌入式微控制器中，同样的原理也适用——只是所有的东西都被封装在一块硅片上。

然而，显卡通常有一个软件API(如Vulkan、Metal或OpenGL)，与之不同的是，外设通过一个硬件接口暴露给微控制器，这个硬件接口被映射到内存的一块上。

在微控制器上，将一些数据写入其他任意地址，如0x4000_0000或0x0000_0000，也可能是一个完全有效的动作。

在桌面系统中，对内存的访问是由MMU(内存管理单元)严格控制的。该组件有两个主要职责:强制对内存段的访问权限(防止一个进程读取或修改另一个进程的内存);并将物理内存段重新映射到软件中使用的虚拟内存范围。微控制器通常没有MMU，只在软件中使用真实的物理地址。

尽管32位微控制器的实际线性地址空间来自0x0000_0000和0xFFFF_FFFF，但它们通常只使用这一范围中的几百千字节作为实际内存。这就留下了大量的地址空间。
在前面的章节中，我们讨论了RAM位于0x2000_0000地址。如果我们的RAM是64kib长(即最大地址为0xFFFF)，那么0x2000_0000到0x2000_FFFF的地址将对应我们的RAM。当我们写入地址为0x2000_1234的变量时，内部发生的是一些逻辑检测到地址的上部(在这个例子中是0x2000)，然后激活RAM，以便它可以作用于地址的下部(在这个例子中是0x1234)。在Cortex-M上，我们还将Flash ROM映射到地址0x0000_0000到地址0x0007_FFFF(如果我们有一个512kib Flash ROM)。微控制器设计人员不是忽略这两个区域之间的所有剩余空间，而是将外设接口映射到特定的内存位置。结果是这样的:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-0GlLsvea-1659849615099)(/mnt/笔记/img/nrf52-memory-map.png)]

乍一看，与这些外设的交互很简单——将正确的数据写入正确的地址。例如，通过串行端口发送一个32位字可能与将该32位字写入某个内存地址一样直接。然后串口外围设备将接管并自动发送数据。

这些外设的配置工作原理类似。不是调用一个函数来配置外设，而是公开一块内存作为硬件API。将0x8000_0000写入SPI频率配置寄存器，SPI端口将以每秒8兆比特的速度发送数据。将0x0200_0000写入相同的地址，SPI端口将以每秒125千比特的速度发送数据。这些配置寄存器看起来有点像这样:

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-DCkKdIy0-1659849615100)(/mnt/笔记/img/nrf52-spi-frequency-register.png)]

让我们看看“SysTick”外设-一个简单的定时器，每个Cortex-M处理器核心。通常你会在芯片制造商的数据表或技术参考手册中查找这些，但是这个例子对于所有的ARM Cortex-M内核都是常见的，让我们看看ARM的参考手册。我们看到有四个寄存器:

在Rust中，我们可以用与在C中完全相同的方式来表示寄存器的集合——用一个struct。

#[repr(C)]
struct SysTick {
    pub csr: u32,
    pub rvr: u32,
    pub cvr: u32,
    pub calib: u32,
}

修饰语#[repr(C)]告诉Rust编译器像C编译器那样布局这个结构。这是非常重要的，因为Rust允许结构字段被重新排序，而C不允许。你可以想象，如果编译器默默地重新安排这些字段，我们将不得不做的调试!有了这个限定符，我们就有了四个32位字段，它们对应于上面的表。但是当然，这个结构本身是没有用的——我们需要一个变量。

let systick = 0xE000_E010 as *mut SysTick;
let time = unsafe { (*systick).cvr };

现在，上面的方法有几个问题。

1. 每次我们想要访问外围设备，我们必须使用unsafe。
2. 我们没有办法指定哪些寄存器是只读的，哪些寄存器是读写的。
3. 程序中任何地方的任何一段代码都可以通过这个结构访问硬件。
4. 最重要的是，它实际上不起作用……

现在，问题是编译器很聪明。如果对同一块RAM进行两次写操作，一个接一个，编译器会注意到这一点，并完全跳过第一次写操作。在C语言中，我们可以将变量标记为volatile，以确保每次读或写都按预期发生。在Rust中，我们将访问对象标记为volatile，而不是变量。

let systick = unsafe { &mut *(0xE000_E010 as *mut SysTick) };
let time = unsafe { core::ptr::read_volatile(&mut systick.cvr) };

我们需要将这个struct封装到一个更高层的API中，以便用户安全地调用。作为驱动程序的作者，我们手动验证不安全的代码是正确的，然后为我们的用户提供一个安全的API，这样他们就不用担心了(前提是他们相信我们能做对!)

一个例子：

use volatile_register::{RW, RO};

pub struct SystemTimer {
    p: &'static mut RegisterBlock
}

#[repr(C)]
struct RegisterBlock {
    pub csr: RW<u32>,
    pub rvr: RW<u32>,
    pub cvr: RW<u32>,
    pub calib: RO<u32>,
}

impl SystemTimer {
    pub fn new() -> SystemTimer {
        SystemTimer {
            p: unsafe { &mut *(0xE000_E010 as *mut RegisterBlock) }
        }
    }

    pub fn get_time(&self) -> u32 {
        self.p.cvr.read()
    }

    pub fn set_reload(&mut self, reload_value: u32) {
        unsafe { self.p.rvr.write(reload_value) }
    }
}

pub fn example_usage() -> String {
    let mut st = SystemTimer::new();
    st.set_reload(0x00FF_FFFF);
    format!("Time is now 0x{:08x}", st.get_time())
}

现在，这种方法的问题是，以下代码是完全可以被编译器接受的:

fn thread1() {
    let mut st = SystemTimer::new();
    st.set_reload(2000);
}

fn thread2() {
    let mut st = SystemTimer::new();
    st.set_reload(1000);
}

set_reload函数的&mut self参数检查是否没有其他引用到这个特定的SystemTimer结构体，但它们不能阻止用户创建第二个指向完全相同的外围设备的SystemTimer !如果作者足够勤奋地找出所有这些“重复”的驱动程序实例，以这种方式编写的代码将会工作，但一旦代码分散到多个模块、驱动程序、开发人员和天，就会越来越容易犯这类错误。

不幸的是，硬件基本上就是可变的全局状态，这对Rust开发人员来说是非常可怕的。硬件独立于我们所编写的代码结构而存在，并且可以在现实世界中随时修改。

我们如何才能可靠地与这些外围设备交互?

1. 总是使用volatile方法来读写外设内存，因为它随时都可能发生变化。
2. 在软件中，我们应该能够共享对这些外设的任意数量的只读访问
3. 如果某些软件应该对外设具有读写访问权限，那么它应该持有对该外设的唯一引用

最后两个规则听起来与Borrow Checker已经做的事情非常相似!

想象一下，如果我们可以传递这些外围设备的所有权，或者为它们提供不可变或可变的引用?

当然，我们可以，但是对于Borrow Checker，我们需要每个外围设备都有一个实例，这样Rust才能正确地处理这个问题。幸运的是，在硬件中，任何给定的外设都只有一个实例，但是我们如何在代码结构中暴露它呢?

在软件工程中，单例模式是一种软件设计模式，它将一个类的实例化限制为一个对象。

我们可以把一切都变成公共静态，就像这样

static mut THE_SERIAL_PORT: SerialPort = SerialPort;

fn main() {
    let _ = unsafe {
        THE_SERIAL_PORT.read_speed();
    };
}

但这有一些问题。它是一个可变的全局变量，在Rust中，与这些变量交互总是不安全的。这些变量在整个程序中也是可见的，这意味着借用检查器无法帮助您跟踪这些变量的引用和所有权。

我们不只是将外围设为一个全局变量，我们也可以设置一个全局变量，在本例中称为PERIPHERALS，它包含每个外设的Option。

struct Peripherals {
    serial: Option<SerialPort>,
}
impl Peripherals {
    fn take_serial(&mut self) -> SerialPort {
        let p = replace(&mut self.serial, None);
        p.unwrap()
    }
}
static mut PERIPHERALS: Peripherals = Peripherals {
    serial: Some(SerialPort),
};

这个结构允许我们获得外围设备的单个实例。如果多次调用take_serial()，代码就会出错!

fn main() {
    let serial_1 = unsafe { PERIPHERALS.take_serial() };
    // This panics!
    // let serial_2 = unsafe { PERIPHERALS.take_serial() };
}

虽然和这个结构交互是unsafe的，一旦包含了SerialPort，我们就不再需要使用unsafe的了，或者PERIPHERALS结构体。

这有一个小的运行时开销，因为我们必须将SerialPort结构包装在一个选项中，并且，我们需要调用一次take_serial()，然而，这个小小的前置成本允许我们在程序的其余部分中利用借用检查器。

尽管我们在上面创建了自己的Peripherals结构，但对您的代码没有必要这样做。
cortex_m crate包含一个名为singleton!()的宏，它将为你执行这个操作。

#[macro_use(singleton)]
extern crate cortex_m;

fn main() {
    // OK if `main` is executed only once
    let x: &'static mut bool =
        singleton!(: bool = false).unwrap();
}

但是这些单例如何在Rust代码的工作方式中产生明显的不同呢?

impl SerialPort {
    const SER_PORT_SPEED_REG: *mut u32 = 0x4000_1000 as _;

    fn read_speed(
        &self // <------ This is really, really important
    ) -> u32 {
        unsafe {
            ptr::read_volatile(Self::SER_PORT_SPEED_REG)
        }
    }
}

这里有两个重要因素在起作用:

• 因为我们使用的是单例，所以只有一种方法或位置可以获得SerialPort结构
• 要调用read_speed()方法，必须拥有SerialPort结构的所有权或引用

这两个因素结合在一起意味着只有在适当满足借用检查器的情况下才有可能访问硬件，这意味着我们在任何时候都不能对同一个硬件有多个可变的引用!

fn main() {
    // missing reference to `self`! Won't work.
    // SerialPort::read_speed();

    let serial_1 = unsafe { PERIPHERALS.take_serial() };

    // you can only read what you have access to
    let _ = serial_1.read_speed();
}

此外，由于一些引用是可变的，而另一些是不可变的，因此可以看到函数或方法是否可能修改硬件的状态。例如,这允许更改硬件设置:

fn setup_spi_port(
    spi: &mut SpiPort,
    cs_pin: &mut GpioPin
) -> Result<()> {
    // ...
}

不是：

fn read_button(gpio: &GpioPin) -> bool {
    // ...
}

这允许我们强制代码是否应该在编译时而不是运行时对硬件进行更改。注意，这通常只适用于一个应用程序，但对于裸机系统，我们的软件将被编译成一个应用程序，所以这通常不是限制。

因为Rust有一个强类型系统，没有简单的方法来神奇地创建一个Foo的实例，或者在不调用into_foo()方法的情况下把FooBuilder变成一个Foo。另外，调用into_foo()方法会使用原始的FooBuilder结构，这意味着如果不创建新实例，就不能重用它。

这允许我们将系统的状态表示为类型，并包括将状态转换为将一种类型转换为另一种类型的方法所需的操作。
通过创建一个FooBuilder，并将其交换为一个Foo对象，我们已经完成了基本状态机的步骤。

通常，上面列出的状态是通过向映射到GPIO外围设备的给定寄存器写入值来设置的。让我们定义一个虚拟的GPIO配置寄存器来说明:

我们可以在Rust中公开以下结构来控制GPIO:

/// GPIO interface
struct GpioConfig {
    /// GPIO Configuration structure generated by svd2rust
    periph: GPIO_CONFIG,
}

impl GpioConfig {
    pub fn set_enable(&mut self, is_enabled: bool) {
        self.periph.modify(|_r, w| {
            w.enable().set_bit(is_enabled)
        });
    }

    pub fn set_direction(&mut self, is_output: bool) {
        self.periph.modify(|_r, w| {
            w.direction().set_bit(is_output)
        });
    }

    pub fn set_input_mode(&mut self, variant: InputMode) {
        self.periph.modify(|_r, w| {
            w.input_mode().variant(variant)
        });
    }

    pub fn set_output_mode(&mut self, is_high: bool) {
        self.periph.modify(|_r, w| {
            w.output_mode.set_bit(is_high)
        });
    }

    pub fn get_input_status(&self) -> bool {
        self.periph.read().input_status().bit_is_set()
    }
}

但是，这将允许我们修改某些没有意义的寄存器。或者例如，当我们的GPIO被配置为输入时，如果我们设置output_mode字段会发生什么?

通常，使用这个结构将允许我们到达上面的状态机没有定义的状态:例如，拉低的输出，或设置高的输入。对于某些硬件来说，这可能无关紧要。在其他硬件上，它可能会导致意外或未定义的行为!

尽管这个接口编写起来很方便，但它并没有执行我们的硬件实现所设定的设计契约。

在上一章中，我们编写了一个没有执行设计契约的接口。让我们再看看我们想象中的GPIO配置寄存器:

如果我们在使用底层硬件之前检查状态，在运行时执行我们的设计契约，我们可能会写这样的代码:

/// GPIO interface
struct GpioConfig {
    /// GPIO Configuration structure generated by svd2rust
    periph: GPIO_CONFIG,
}

impl GpioConfig {
    pub fn set_enable(&mut self, is_enabled: bool) {
        self.periph.modify(|_r, w| {
            w.enable().set_bit(is_enabled)
        });
    }

    pub fn set_direction(&mut self, is_output: bool) -> Result<(), ()> {
        if self.periph.read().enable().bit_is_clear() {
            // Must be enabled to set direction
            return Err(());
        }

        self.periph.modify(|r, w| {
            w.direction().set_bit(is_output)
        });

        Ok(())
    }

    pub fn set_input_mode(&mut self, variant: InputMode) -> Result<(), ()> {
        if self.periph.read().enable().bit_is_clear() {
            // Must be enabled to set input mode
            return Err(());
        }

        if self.periph.read().direction().bit_is_set() {
            // Direction must be input
            return Err(());
        }

        self.periph.modify(|_r, w| {
            w.input_mode().variant(variant)
        });

        Ok(())
    }

    pub fn set_output_status(&mut self, is_high: bool) -> Result<(), ()> {
        if self.periph.read().enable().bit_is_clear() {
            // Must be enabled to set output status
            return Err(());
        }

        if self.periph.read().direction().bit_is_clear() {
            // Direction must be output
            return Err(());
        }

        self.periph.modify(|_r, w| {
            w.output_mode.set_bit(is_high)
        });

        Ok(())
    }

    pub fn get_input_status(&self) -> Result<bool, ()> {
        if self.periph.read().enable().bit_is_clear() {
            // Must be enabled to get status
            return Err(());
        }

        if self.periph.read().direction().bit_is_set() {
            // Direction must be input
            return Err(());
        }

        Ok(self.periph.read().input_status().bit_is_set())
    }
}

因为我们需要在硬件上执行这些限制，所以我们最终要做大量的运行时检查，这浪费了时间和资源，并且这些代码对于开发人员来说使用起来会不那么愉快。

但是，如果我们使用Rust的类型系统来执行状态转换规则呢?
把这个例子:

/// GPIO interface
struct GpioConfig<ENABLED, DIRECTION, MODE> {
    /// GPIO Configuration structure generated by svd2rust
    periph: GPIO_CONFIG,
    enabled: ENABLED,
    direction: DIRECTION,
    mode: MODE,
}

// Type states for MODE in GpioConfig
struct Disabled;
struct Enabled;
struct Output;
struct Input;
struct PulledLow;
struct PulledHigh;
struct HighZ;
struct DontCare;

/// These functions may be used on any GPIO Pin
impl<EN, DIR, IN_MODE> GpioConfig<EN, DIR, IN_MODE> {
    pub fn into_disabled(self) -> GpioConfig<Disabled, DontCare, DontCare> {
        self.periph.modify(|_r, w| w.enable.disabled());
        GpioConfig {
            periph: self.periph,
            enabled: Disabled,
            direction: DontCare,
            mode: DontCare,
        }
    }

    pub fn into_enabled_input(self) -> GpioConfig<Enabled, Input, HighZ> {
        self.periph.modify(|_r, w| {
            w.enable.enabled()
             .direction.input()
             .input_mode.high_z()
        });
        GpioConfig {
            periph: self.periph,
            enabled: Enabled,
            direction: Input,
            mode: HighZ,
        }
    }

    pub fn into_enabled_output(self) -> GpioConfig<Enabled, Output, DontCare> {
        self.periph.modify(|_r, w| {
            w.enable.enabled()
             .direction.output()
             .input_mode.set_high()
        });
        GpioConfig {
            periph: self.periph,
            enabled: Enabled,
            direction: Output,
            mode: DontCare,
        }
    }
}

/// This function may be used on an Output Pin
impl GpioConfig<Enabled, Output, DontCare> {
    pub fn set_bit(&mut self, set_high: bool) {
        self.periph.modify(|_r, w| w.output_mode.set_bit(set_high));
    }
}

/// These methods may be used on any enabled input GPIO
impl<IN_MODE> GpioConfig<Enabled, Input, IN_MODE> {
    pub fn bit_is_set(&self) -> bool {
        self.periph.read().input_status.bit_is_set()
    }

    pub fn into_input_high_z(self) -> GpioConfig<Enabled, Input, HighZ> {
        self.periph.modify(|_r, w| w.input_mode().high_z());
        GpioConfig {
            periph: self.periph,
            enabled: Enabled,
            direction: Input,
            mode: HighZ,
        }
    }

    pub fn into_input_pull_down(self) -> GpioConfig<Enabled, Input, PulledLow> {
        self.periph.modify(|_r, w| w.input_mode().pull_low());
        GpioConfig {
            periph: self.periph,
            enabled: Enabled,
            direction: Input,
            mode: PulledLow,
        }
    }

    pub fn into_input_pull_up(self) -> GpioConfig<Enabled, Input, PulledHigh> {
        self.periph.modify(|_r, w| w.input_mode().pull_high());
        GpioConfig {
            periph: self.periph,
            enabled: Enabled,
            direction: Input,
            mode: PulledHigh,
        }
    }
}

这绝对是一种方便的方式来存储pin的状态，但为什么要这样做呢?为什么这比在GpioConfig结构中以enum形式存储状态更好呢?

因为我们在编译时完全强制我们的设计约束，这不会产生运行时成本。当你有一个输入模式的引脚时，是不可能设置输出模式的。相反，您必须通过将其转换为输出引脚，然后设置输出模式来遍历这些状态。因此，在执行函数之前不会检查当前状态而造成运行时损失。而且，因为这些状态是由类型系统强制的，因此接口的使用者不再有犯错的空间。如果它们试图执行非法的状态转换，代码将无法编译!

类型状态也是零成本抽象(Zero Cost Abstractions)的一个很好的例子——将某些行为移动到编译时执行或分析的能力。这些类型状态不包含实际数据，而是用作标记。因为它们不包含数据，所以在运行时它们在内存中没有实际的表示:

use core::mem::size_of;

let _ = size_of::<Enabled>();    // == 0
let _ = size_of::<Input>();      // == 0
let _ = size_of::<PulledHigh>(); // == 0
let _ = size_of::<GpioConfig<Enabled, Input, PulledHigh>>(); // == 0

这样定义的结构称为零大小类型，因为它们不包含实际数据。虽然这些类型在编译时是“真实的”——你可以复制它们，移动它们，引用它们，等等，但是优化器会完全剥离它们。

在这段代码中:

pub fn into_input_high_z(self) -> GpioConfig<Enabled, Input, HighZ> {
    self.periph.modify(|_r, w| w.input_mode().high_z());
    GpioConfig {
        periph: self.periph,
        enabled: Enabled,
        direction: Input,
        mode: HighZ,
    }
}

我们返回运行时从不存在的GpioConfig 。调用这个函数通常会归结为一条汇编指令——将一个常量寄存器值存储到寄存器位置。这意味着我们开发的类型状态接口是零成本的抽象——它不使用CPU、RAM或代码空间来跟踪GpioConfig的状态，并将其呈现为与直接寄存器访问相同的机器码。

通常，这些抽象可以嵌套得越深越好。只要使用的所有组件都是零大小的类型，那么整个结构在运行时将不存在。

对于复杂或深度嵌套的结构，定义所有可能的状态组合可能是乏味的。在这些情况下，可以使用宏生成所有实现。

在嵌入式环境中，可移植性是一个非常重要的话题:每个供应商甚至来自同一个制造商的每个家族都提供不同的外设和功能，同样，与外设交互的方式也会有所不同。

平衡这种差异的一种常见方法是通过一个称为硬件抽象层(HAL)的层。

硬件抽象是软件中的一组例程，它们模拟一些特定于平台的细节，使程序可以直接访问硬件资源。

它们通常允许程序员通过向硬件提供标准操作系统(OS)调用来编写与设备无关的高性能应用程序。

简而言之，它是一组定义HAL实现、驱动程序和应用程序(或固件)之间实现契约的trait。这些契约包括两个功能(例如，如果一个trait是为某种类型实现的，HAL实现提供了某种功能)和方法(例如，如果你可以构造一个实现特征的类型，那么就可以保证你拥有该特征中指定的方法)。

典型的分层可能是这样的：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-3xa5biQV-1659849615102)(/mnt/笔记/img/rust_layers.svg)]

一些trait被定义在embedded-hal中：

• GPIO (输入输出引脚)
• 串行通信
• I2C
• SPI
• 定时器/计数器
• ADC（模数转换）

实现和使用embedded-hal traits和 相关crate的主要原因是为了控制复杂性。如果您考虑到应用程序可能必须在硬件中实现外设的使用，以及应用程序和附加硬件组件的潜在驱动程序，那么很容易看到可重用性非常有限。

从数学上讲，如果M是外围设备HAL实现的数量，N是驱动程序的数量，那么如果我们为每个应用重新发明轮子，那么我们最终将得到M*N个实现，而使用embedded-hal trait提供的API将使实现的复杂性达到M+N。当然，还有其他的好处，例如，由于有一个定义良好的、随时可用的api，所以可以减少试错。

如上所述，HAL有三个主要用户:

HAL实现提供了硬件和HAL特性用户之间的接口。
典型的实现包括三个部分:

• 一个或多个硬件特定类型
• 用于创建和初始化这种类型的函数，通常提供各种配置选项(速度、操作模式、使用引脚等)。
• embedded-hal trait的一个或多个trait impl为了这个类型

这样的HAL实现可以有多种形式:

• 通过低级硬件访问，例如通过寄存器
• 通过操作系统，例如在Linux下使用sysfs
• 通过适配器，例如用于单元测试的类型模拟
• 通过驱动硬件适配器，如I2C多路复用器或GPIO扩展器

驱动程序为内部或外部组件实现一组自定义功能，连接到实现embedded-hal trait的外围设备。这种驱动器的典型例子包括各种传感器(温度、磁力计、加速度计、光)、显示设备(LED阵列、LCD显示器)和执行器(电机、变送器)。

驱动程序必须用一个类型实例进行初始化，该实例实现了 embedded-hal的某个trait，这是通过trait绑定确保的，并提供了自己的类型实例和一组自定义方法，允许与驱动设备交互。

应用程序将各个部分绑定在一起，并确保实现所需的功能。当在不同的系统之间进行移植时，这是最需要调整的部分，因为应用程序需要通过HAL实现正确地初始化真实的硬件，而不同硬件的初始化有时是截然不同的。此外，用户的选择通常扮演着重要的角色，因为组件可以物理连接到不同的终端，硬件总线有时需要外部硬件来匹配配置，或者在使用内部外设时需要做出不同的权衡(例如，具有不同功能的多个计时器或外设与其他外设冲突)。

当程序的不同部分可能以不同的时间或顺序执行时，就会发生并发。嵌入式上下文中，这包括:

• 中断处理程序，当相关的中断发生时就会运行，
• 各种形式的多线程，你的微处理器定期在程序的各个部分之间交换，
• 在一些系统中，多核微处理器，每个核心可以同时独立运行程序的不同部分。

由于许多嵌入式程序需要处理中断，因此并发性通常迟早会出现，而且这也是许多微妙和困难的bug可能发生的地方。幸运的是，Rust提供了许多抽象和安全保证来帮助我们编写正确的代码。

对于嵌入式程序来说，最简单的并发性是无并发性:你的软件由一个只会一直运行的主循环组成，而且根本没有中断。有时这非常适合解决手头的问题!通常你的循环会读取一些输入，执行一些处理，并写入一些输出。

#[entry]
fn main() {
    let peripherals = setup_peripherals();
    loop {
        let inputs = read_inputs(&peripherals);
        let outputs = process(inputs);
        write_outputs(&peripherals, outputs);
    }
}

因为没有并发性，所以不需要担心在程序的各个部分之间共享数据或同步对外设的访问。如果你能摆脱这样一个简单的方法，这可能是一个很好的解决方案。

与非嵌入式的Rust不同，我们通常没有创建堆分配并将对这些数据的引用传递给新创建的线程的特权。相反，我们的中断处理程序可能在任何时候被调用，并且必须知道如何访问我们正在使用的任何共享内存。在最低级别，这意味着我们必须有静态分配的可变内存，中断处理程序和主代码都可以引用它。

在Rust中，读或写这样的static mut变量总是不安全的，因为如果不特别注意，您可能会触发一个竞争条件，其中您对变量的访问在中途被一个同时访问该变量的中断中断。

举个例子来说明这种行为是如何在你的代码中引起微妙的错误的，考虑一个嵌入式程序，它在每一秒的周期内统计一些输入信号的上升边(频率计数器):

static mut COUNTER: u32 = 0;

#[entry]
fn main() -> ! {
    set_timer_1hz();
    let mut last_state = false;
    loop {
        let state = read_signal_level();
        if state && !last_state {
            // DANGER - Not actually safe! Could cause data races.
            unsafe { COUNTER += 1 };
        }
        last_state = state;
    }
}

#[interrupt]
fn timer() {
    unsafe { COUNTER = 0; }
}

每一秒，计时器中断将计数器设置回0。同时，主循环不断测量信号，并在看到从低到高的变化时增加计数器。我们必须使用unsafe来访问COUNTER，因为它是static mut，这意味着我们要向编译器保证不会导致任何未定义的行为。你能发现竞态条件吗?COUNTER上的增量并不一定是原子的—事实上，在大多数嵌入式平台上，它将被拆分为加载、增量和存储。如果中断在加载之后，但在存储之前触发，那么在中断返回后，将忽略重置为0的操作——我们将在这段时间内计算两倍的转换次数。

那么，对于数据竞赛我们能做些什么呢?一种简单的方法是使用临界区，这是一个中断被禁用的上下文。通过将main对COUNTER的访问封装在一个关键部分中，我们可以确保计时器中断不会触发，直到我们完成COUNTER的递增:

static mut COUNTER: u32 = 0;

#[entry]
fn main() -> ! {
    set_timer_1hz();
    let mut last_state = false;
    loop {
        let state = read_signal_level();
        if state && !last_state {
            // New critical section ensures synchronised access to COUNTER
            cortex_m::interrupt::free(|_| {
                unsafe { COUNTER += 1 };
            });
        }
        last_state = state;
    }
}

#[interrupt]
fn timer() {
    unsafe { COUNTER = 0; }
}

在本例中，我们使用cortex_m::interrupt::free，但是其他平台也有类似的机制来在关键段执行代码。这与禁用中断，运行一些代码，然后重新启用中断是相同的。

注意，我们不需要在计时器中断中放入临界区，有两个原因:

• 向COUNTER写入0不会受到竞争的影响，因为我们没有读取它
• 它永远不会被主线程中断

如果COUNTER被多个中断处理程序共享，它们可能会抢占彼此，那么每个中断处理程序也可能需要一个临界区。

这解决了我们当前的问题，但我们仍然需要编写大量不安全的代码，我们需要仔细考虑这些代码，我们可能会不必要地使用关键部分。由于每个临界区都临时暂停中断处理，因此会有一些额外的代码大小和更高的中断延迟和抖动(中断可能需要更长的时间来处理，并且直到它们被处理的时间将会更加多变)相关的成本。这是否是一个问题取决于您的系统，但一般来说，我们希望避免它。

值得注意的是，虽然临界段保证不会触发中断，但它并没有在多核系统上提供排他性保证!另一个核心可以愉快地访问与你的核心相同的内存，即使没有中断。如果使用多核，则需要更强的同步原语。

在一些平台上，可以使用特殊的原子指令，这些指令提供了关于读-修改-写操作的保证。具体来说，对于Cortex-M: thumbv6 (Cortex-M0, Cortex-M0+)只提供原子加载和存储指令，而thumbv7 (Cortex-M3及以上)提供完整的比较和交换(CAS)指令。这些CAS指令为禁用所有中断提供了一种替代方法:

我们可以尝试增量操作，它在大多数情况下都会成功，但如果它被中断，它会自动重试整个增量操作。即使跨多个核，这些原子操作也是安全的。

use core::sync::atomic::{AtomicUsize, Ordering};

static COUNTER: AtomicUsize = AtomicUsize::new(0);

#[entry]
fn main() -> ! {
    set_timer_1hz();
    let mut last_state = false;
    loop {
        let state = read_signal_level();
        if state && !last_state {
            // Use `fetch_add` to atomically add 1 to COUNTER
            COUNTER.fetch_add(1, Ordering::Relaxed);
        }
        last_state = state;
    }
}

#[interrupt]
fn timer() {
    // Use `store` to write 0 directly to COUNTER
    COUNTER.store(0, Ordering::Relaxed)
}

这次COUNTER是一个安全的静态变量。由于AtomicUsize类型，COUNTER可以从中断处理程序和主线程安全地修改，而不需要禁用中断。如果可能的话，这是一个更好的解决方案—但是您的平台可能不支持它。

上述解决方案没有一个特别令人满意。他们需要unsafe的块，必须非常仔细地检查，不符合人体工程学。当然我们可以在Rust做得更好!

我们可以将计数器抽象成一个安全的接口，可以在代码的任何地方安全地使用它。在本例中，我们将使用临界区计数器，但您也可以对原子执行非常类似的操作。

use core::cell::UnsafeCell;
use cortex_m::interrupt;

// Our counter is just a wrapper around UnsafeCell<u32>, which is the heart
// of interior mutability in Rust. By using interior mutability, we can have
// COUNTER be `static` instead of `static mut`, but still able to mutate
// its counter value.
struct CSCounter(UnsafeCell<u32>);

const CS_COUNTER_INIT: CSCounter = CSCounter(UnsafeCell::new(0));

impl CSCounter {
    pub fn reset(&self, _cs: &interrupt::CriticalSection) {
        // By requiring a CriticalSection be passed in, we know we must
        // be operating inside a CriticalSection, and so can confidently
        // use this unsafe block (required to call UnsafeCell::get).
        unsafe { *self.0.get() = 0 };
    }

    pub fn increment(&self, _cs: &interrupt::CriticalSection) {
        unsafe { *self.0.get() += 1 };
    }
}

// Required to allow static CSCounter. See explanation below.
unsafe impl Sync for CSCounter {}

// COUNTER is no longer `mut` as it uses interior mutability;
// therefore it also no longer requires unsafe blocks to access.
static COUNTER: CSCounter = CS_COUNTER_INIT;

#[entry]
fn main() -> ! {
    set_timer_1hz();
    let mut last_state = false;
    loop {
        let state = read_signal_level();
        if state && !last_state {
            // No unsafe here!
            interrupt::free(|cs| COUNTER.increment(cs));
        }
        last_state = state;
    }
}

#[interrupt]
fn timer() {
    // We do need to enter a critical section here just to obtain a valid
    // cs token, even though we know no other interrupt could pre-empt
    // this one.
    interrupt::free(|cs| COUNTER.reset(cs));

    // We could use unsafe code to generate a fake CriticalSection if we
    // really wanted to, avoiding the overhead:
    // let cs = unsafe { interrupt::CriticalSection::new() };
}

我们已经将不安全的代码移到了精心规划的抽象中，现在我们的应用程序代码不再包含任何unsafe的块。

这种设计要求应用程序传入一个CriticalSection token:这些token只有由interrupt::free，因此，通过要求传入一个函数，我们可以确保操作是在临界区内部进行的，而不必自己实际执行锁操作。这个保证是由编译器静态提供的:不会有任何与cs相关的运行时开销。如果我们有多个计数器，它们都可以被赋予相同的cs，而不需要多个嵌套的临界区。

我们已经创建了一个针对计数器问题的有用的抽象，但是还有许多用于并发的通用抽象。

其中一个同步原语是互斥锁，即互斥锁。这些结构确保了对变量的独占访问，比如我们的counter。线程可以尝试锁定(或获取)互斥锁，然后要么立即成功，要么阻塞等待获得锁，要么返回无法锁定互斥锁的错误。当该线程持有锁时，它被授予对受保护数据的访问权。当线程完成时，它解锁(或释放)互斥锁，允许另一个线程锁定它。在Rust中，我们通常使用Drop trait来实现解锁，以确保当互斥量超出范围时它总是被释放。

在中断处理程序中使用互斥是很棘手的:中断处理程序阻塞通常是不可接受的，它在等待主线程释放锁时阻塞将是特别灾难性的，因为我们将会死锁(主线程永远不会释放锁，因为执行停留在中断处理程序中)。死锁并不被认为是不安全的:即使在安全的Rust，它也是可能的。

为了完全避免这种行为，我们可以实现一个需要临界区来锁定的互斥锁，就像我们的反例一样。只要临界区必须和锁的时间一样长，我们就可以确保对包装变量的独占访问，甚至不需要跟踪互斥锁的锁定/解锁状态。

这实际上是在cortex_m crate中为我们完成的!我们可以使用它来编写计数器:

use core::cell::Cell;
use cortex_m::interrupt::Mutex;

static COUNTER: Mutex<Cell<u32>> = Mutex::new(Cell::new(0));

#[entry]
fn main() -> ! {
    set_timer_1hz();
    let mut last_state = false;
    loop {
        let state = read_signal_level();
        if state && !last_state {
            interrupt::free(|cs|
                COUNTER.borrow(cs).set(COUNTER.borrow(cs).get() + 1));
        }
        last_state = state;
    }
}

#[interrupt]
fn timer() {
    // We still need to enter a critical section here to satisfy the Mutex.
    interrupt::free(|cs| COUNTER.borrow(cs).set(0));
}

使用svd2rust和类似的抽象生成的设备crate通过强制一次只能存在一个外设结构的实例来提供对外设的安全访问。这确保了安全性，但使从主线程和中断处理程序访问外设变得困难。

为了安全地共享外围设备访问，我们可以使用前面看到的互斥锁。我们还需要使用RefCell，它使用一个运行时检查来确保每次只给出一个外设的引用。这比普通Cell有更多的开销，但是由于我们给出的是引用而不是副本，我们必须确保一次只存在一个。

最后，我们还必须考虑如何在主代码中初始化外围设备后将其移到共享变量中。为此，我们可以使用Option类型，初始化为None，稍后设置为外围设备的实例。

use core::cell::RefCell;
use cortex_m::interrupt::{self, Mutex};
use stm32f4::stm32f405;

static MY_GPIO: Mutex<RefCell<Option<stm32f405::GPIOA>>> =
    Mutex::new(RefCell::new(None));

#[entry]
fn main() -> ! {
    // Obtain the peripheral singletons and configure it.
    // This example is from an svd2rust-generated crate, but
    // most embedded device crates will be similar.
    let dp = stm32f405::Peripherals::take().unwrap();
    let gpioa = &dp.GPIOA;

    // Some sort of configuration function.
    // Assume it sets PA0 to an input and PA1 to an output.
    configure_gpio(gpioa);

    // Store the GPIOA in the mutex, moving it.
    interrupt::free(|cs| MY_GPIO.borrow(cs).replace(Some(dp.GPIOA)));
    // We can no longer use `gpioa` or `dp.GPIOA`, and instead have to
    // access it via the mutex.

    // Be careful to enable the interrupt only after setting MY_GPIO:
    // otherwise the interrupt might fire while it still contains None,
    // and as-written (with `unwrap()`), it would panic.
    set_timer_1hz();
    let mut last_state = false;
    loop {
        // We'll now read state as a digital input, via the mutex
        let state = interrupt::free(|cs| {
            let gpioa = MY_GPIO.borrow(cs).borrow();
            gpioa.as_ref().unwrap().idr.read().idr0().bit_is_set()
        });

        if state && !last_state {
            // Set PA1 high if we've seen a rising edge on PA0.
            interrupt::free(|cs| {
                let gpioa = MY_GPIO.borrow(cs).borrow();
                gpioa.as_ref().unwrap().odr.modify(|_, w| w.odr1().set_bit());
            });
        }
        last_state = state;
    }
}

#[interrupt]
fn timer() {
    // This time in the interrupt we'll just clear PA0.
    interrupt::free(|cs| {
        // We can use `unwrap()` because we know the interrupt wasn't enabled
        // until after MY_GPIO was set; otherwise we should handle the potential
        // for a None value.
        let gpioa = MY_GPIO.borrow(cs).borrow();
        gpioa.as_ref().unwrap().odr.modify(|_, w| w.odr1().clear_bit());
    });
}

这是相当多的吸收，所以让我们分解重要的线。

static MY_GPIO: Mutex<RefCell<Option<stm32f405::GPIOA>>> =
    Mutex::new(RefCell::new(None));

我们的共享变量现在是一个围绕RefCell的互斥锁，其中包含一个Option。互斥锁确保我们只有在临界区才有访问权限，因此使变量Sync，即使一个普通的RefCell不是Sync。RefCell为我们提供了内部可变的引用，这是我们使用GPIOA所需要的。Option允许我们将该变量初始化为空值，并在稍后将变量移进去。我们不能静态地访问外围单例，只有在运行时，所以这是必需的。

在临界区中，我们可以对互斥对象调用borrow()，它提供了RefCell的引用。然后调用replace()将新值移动到RefCell中。

interrupt::free(|cs| {
    let gpioa = MY_GPIO.borrow(cs).borrow();
    gpioa.as_ref().unwrap().odr.modify(|_, w| w.odr1().set_bit());
});

最后，我们以一种安全并发的方式使用MY_GPIO。临界区阻止中断正常触发，并允许我们借用互斥锁。然后RefCell给我们一个&Option，并跟踪它被借了多长时间——一旦引用超出范围，RefCell将被更新以表明它不再被借了。

因为我们不能将GPIOA从&Option中移出，我们需要用as_ref()将它转换为&Option<&GPIOA>，我们最终可以打开()来获得&GPIOA，它可以让我们修改外围设备。

如果需要对共享资源的可变引用，则应该使用borrow_mut和deref_mut。下面的代码显示了一个使用TIM2计时器的示例。

use core::cell::RefCell;
use core::ops::DerefMut;
use cortex_m::interrupt::{self, Mutex};
use cortex_m::asm::wfi;
use stm32f4::stm32f405;

static G_TIM: Mutex<RefCell<Option<Timer<stm32::TIM2>>>> =
    Mutex::new(RefCell::new(None));

#[entry]
fn main() -> ! {
    let mut cp = cm::Peripherals::take().unwrap();
    let dp = stm32f405::Peripherals::take().unwrap();

    // Some sort of timer configuration function.
    // Assume it configures the TIM2 timer, its NVIC interrupt,
    // and finally starts the timer.
    let tim = configure_timer_interrupt(&mut cp, dp);

    interrupt::free(|cs| {
        G_TIM.borrow(cs).replace(Some(tim));
    });

    loop {
        wfi();
    }
}

#[interrupt]
fn timer() {
    interrupt::free(|cs| {
        if let Some(ref mut tim)) =  G_TIM.borrow(cs).borrow_mut().deref_mut() {
            tim.start(1.hz());
        }
    });
}

这是安全的，但它也有点笨拙。我们还能做什么吗?

嵌入式并发的另一个常见模型是实时操作系统(RTOS)。虽然目前在Rust中还没有得到很好的探索，但是它们在传统的嵌入式开发中被广泛使用。开源的例子包括FreeRTOS和ChibiOS。这些RTOSs支持运行多个应用程序线程，CPU可以在这些线程之间进行切换，当这些线程获得控制时(称为协作多任务处理)，或者基于常规计时器或中断(抢占多任务处理)。RTOS通常提供互斥锁和其他同步原语，并经常与硬件特性(如DMA引擎)进行互操作。

在撰写本文时，Rust RTOS的例子并不多，但这是一个有趣的领域，所以请关注这个领域!

在嵌入式处理器中使用两个或更多的核心变得越来越普遍，这为并发性增加了额外的复杂性。所有使用临界部分的例子(包括cortex_m::interrupt::Mutex)都假设唯一的其他执行线程是中断线程，但在多核系统上，这就不成立了。相反，我们需要为多核设计的同步原语(也称为SMP，用于对称多处理)。

它们通常使用我们前面看到的原子指令，因为处理系统将确保在所有核心上维护原子性。详细介绍这些主题目前超出了本书的范围，但一般模式与单核情况相同。

alloc crate是与标准的Rust分发crate。要导入crate，您可以直接使用它，而无需在Cargo.toml中声明它作为依赖项。

#![feature(alloc)]

extern crate alloc;

use alloc::vec::Vec;

heapless不需要设置，因为它的集合不依赖于全局内存分配器。只需use它的集合并继续实例化它们:

extern crate heapless; // v0.4.x

use heapless::Vec;
use heapless::consts::*;

#[entry]
fn main() -> ! {
    let mut xs: Vec<_, U8> = Vec::new();

    xs.push(42).unwrap();
    assert_eq!(xs.pop(), Some(42));
}

您将注意到这些集合与alloc中的集合之间的两个区别。

在选择堆分配的、可重定位的集合和固定容量的集合时，请记住这些。

在堆分配中，内存溢出始终是可能的，并且可能发生在集合需要增长的任何地方:例如，所有的alloc::Vec。push调用可能会生成一个OOM条件。因此，有些操作可能会隐式失败。
有些alloc集合公开try_reserve方法，允许您在增加集合时检查潜在的OOM条件，但您需要主动使用它们。

如果您专门使用heapless集合，并且您不为任何其他事情使用内存分配器，那么OOM条件是不可能的。相反，您必须根据具体情况处理集合耗尽容量的问题。也就是说，你需要处理Vec.push等方法返回的所有Result。

与打开由heapless::Vec返回的所有结果相比，OOM失败可能更难调试。推送是因为观察到的故障位置可能与问题原因的位置不匹配。例如，如果分配器几乎耗尽，甚至vec.reserve(1)也会触发OOM，因为其他一些收集正在泄漏内存(内存泄漏在安全的Rust中是可能的)。

很难推断堆分配的集合的内存使用情况，因为长生命周期集合的容量可能在运行时发生变化。一些操作可能会隐式地重新分配集合，从而增加其内存使用量，而一些集合会公开诸如shrink_to_fit这样的方法，这些方法可能会减少集合使用的内存——最终，由分配器决定是否实际收缩内存分配。此外，分配器可能必须处理内存碎片，这可能会增加明显的内存使用。

另一方面，如果您专门使用固定容量集合，将它们中的大部分存储在静态变量中，并为调用堆栈设置最大大小，那么链接器将检测您是否试图使用比物理可用内存更多的内存。

此外，在堆栈上分配的固定容量集合将通过-Z emit-stack-sizes标志报告，这意味着分析堆栈使用情况的工具(如堆栈-size)将在其分析中包括它们。

但是，固定容量收集不能缩小，这可能导致比可重定位收集所能达到的负载系数(收集大小与其容量之间的比率)更低。

如果你在构建对时间敏感的应用程序或硬实时应用程序，你可能会非常关心，程序不同部分最坏的执行时间。

alloc集合可以重新分配，因此可能增加集合的操作的WCET还包括重新分配集合所需的时间，这本身取决于集合的运行时容量。这使得确定例如alloc::Vec.push的WCET变得困难，因为它取决于所使用的分配器及其运行时容量。

另一方面，固定容量收集从不重新分配，因此所有操作都有一个可预测的执行时间。例如,heapless::Vec.push执行的时间为常数。

alloc需要设置全局分配器，而heapless则不需要。但是，heapless需要您选择实例化的每个集合的容量。

alloc API几乎为每一位rust开发者所熟悉。heapless API试图紧密模仿alloc API，但由于其显式错误处理，它永远不会完全相同——一些开发人员可能觉得显式错误处理过多或太麻烦。

本章的目的是为嵌入式Rust收集各种有用的设计模式。

命名（(crate与Rust命名约定一致)）

HAL crate应该以其目标支持的芯片或芯片家族命名。
它们的名称应该以-hal结尾，以区别于寄存器访问crate。
名称不应该包含下划线(使用破折号代替)。

HAL提供的任何非Copy包装器类型都应该提供一个free方法，该方法使用包装器并返回创建它的原始外设(可能还有其他对象)。

该方法应在必要时关闭并复位外围设备。使用free返回的原始外围设备调用new不应该因为外围设备的意外状态而失败。

如果HAL类型需要构造其他非copy对象(例如I/O引脚)，任何这样的对象也应该被free释放并返回。在这种情况下，Free应该返回一个元组。

举个例子：

#![allow(unused)]
fn main() {
pub struct TIMER0;
pub struct Timer(TIMER0);

impl Timer {
    pub fn new(periph: TIMER0) -> Self {
        Self(periph)
    }

    pub fn free(self) -> TIMER0 {
        self.0
    }
}
}

HAL添加功能的所有外设都应该包装在一个新类型中，即使该功能不需要额外的字段。

应该避免为原始外设实现的扩展trait。

默认情况下，Rust编译器不会跨crate边界执行完全内联。由于嵌入式应用程序对意外的代码大小增加很敏感，应该使用#[inline]来指导编译器，如下所示:

• 所有“小”函数都应该标记为#[inline]。所谓的“小”是主观的，但一般来说，所有被期望编译成一位数指令序列的函数都被认为是小的。

• 很可能使用常量值作为参数的函数应该标记为#[inline]。这使得编译器能够在编译时计算复杂的初始化逻辑，前提是函数输入是已知的。

由HAL公开的GPIO接口应该为每个接口或端口上的每个引脚提供专用的零大小类型，从而在所有引脚分配都是静态已知的情况下实现零成本的GPIO抽象。

每个GPIO接口或端口都应该实现一个split方法，每个引脚返回一个结构体。

举例:

#![allow(unused)]
fn main() {
pub struct PA0;
pub struct PA1;
// ...

pub struct PortA;

impl PortA {
    pub fn split(self) -> PortAPins {
        PortAPins {
            pa0: PA0,
            pa1: PA1,
            // ...
        }
    }
}

pub struct PortAPins {
    pub pa0: PA0,
    pub pa1: PA1,
    // ...
}
}

引脚应该提供类型擦除方法，将它们的属性从编译时移动到运行时，并在应用程序中允许更多的灵活性。

例子：

#![allow(unused)]
fn main() {
/// Port A, pin 0.
pub struct PA0;

impl PA0 {
    pub fn erase_pin(self) -> PA {
        PA { pin: 0 }
    }
}

/// A pin on port A.
pub struct PA {
    /// The pin number.
    pin: u8,
}

impl PA {
    pub fn erase_port(self) -> Pin {
        Pin {
            port: Port::A,
            pin: self.pin,
        }
    }
}

pub struct Pin {
    port: Port,
    pin: u8,
    // (these fields can be packed to reduce the memory footprint)
}

enum Port {
    A,
    B,
    C,
    D,
}
}

由HAL公开的GPIO接口应该为每个接口或端口上的每个引脚提供专用的零大小类型，从而在所有引脚分配都是静态已知的情况下实现零成本的GPIO抽象。

每个GPIO接口或端口都应该实现一个split方法，每个引脚返回一个结构体

举例：

#![allow(unused)]
fn main() {
pub struct PA0;
pub struct PA1;
// ...

pub struct PortA;

impl PortA {
    pub fn split(self) -> PortAPins {
        PortAPins {
            pa0: PA0,
            pa1: PA1,
            // ...
        }
    }
}

pub struct PortAPins {
    pub pa0: PA0,
    pub pa1: PA1,
    // ...
}
}

引脚应该提供类型擦除方法，将它们的属性从编译时移动到运行时，并在应用程序中允许更多的灵活性。

举例：

#![allow(unused)]
fn main() {
/// Port A, pin 0.
pub struct PA0;

impl PA0 {
    pub fn erase_pin(self) -> PA {
        PA { pin: 0 }
    }
}

/// A pin on port A.
pub struct PA {
    /// The pin number.
    pin: u8,
}

impl PA {
    pub fn erase_port(self) -> Pin {
        Pin {
            port: Port::A,
            pin: self.pin,
        }
    }
}

pub struct Pin {
    port: Port,
    pin: u8,
    // (these fields can be packed to reduce the memory footprint)
}

enum Port {
    A,
    B,
    C,
    D,
}
}

根据芯片或系列的不同，引脚可以配置为具有不同特性的输入或输出。这种状态应该在类型系统中编码，以防止在不正确的状态下使用引脚。另外，芯片特定的状态(如。
驱动强度)也可以使用附加的类型参数以这种方式进行编码。

改变引脚状态的方法应该作为into_input和into_output方法提供。另外，应该提供_{input,output}_state方法来临时重新配置一个pin到不同的状态，而不需要移动它。

以下方法应该为每一种引脚类型提供(也就是说，擦除和非擦除引脚类型应该提供相同的API):

• pub fn into_input<N: InputState>(self, input: N) -> Pin<N>
• pub fn into_output<N: OutputState>(self, output: N) -> Pin<N>

pub fn with_input_state<N: InputState, R>(
    &mut self,
    input: N,
    f: impl FnOnce(&mut PA1<N>) -> R,
) -> R

pub fn with_output_state<N: OutputState, R>(
    &mut self,
    output: N,
    f: impl FnOnce(&mut PA1<N>) -> R,
) -> R

引脚状态应以密封特性为界。HAL的用户应该不需要添加自己的状态。trait可以提供实现引脚状态API所需的hal特定方法。

举例：

#![allow(unused)]
fn main() {
use std::marker::PhantomData;
mod sealed {
    pub trait Sealed {}
}

pub trait PinState: sealed::Sealed {}
pub trait OutputState: sealed::Sealed {}
pub trait InputState: sealed::Sealed {
    // ...
}

pub struct Output<S: OutputState> {
    _p: PhantomData<S>,
}

impl<S: OutputState> PinState for Output<S> {}
impl<S: OutputState> sealed::Sealed for Output<S> {}

pub struct PushPull;
pub struct OpenDrain;

impl OutputState for PushPull {}
impl OutputState for OpenDrain {}
impl sealed::Sealed for PushPull {}
impl sealed::Sealed for OpenDrain {}

pub struct Input<S: InputState> {
    _p: PhantomData<S>,
}

impl<S: InputState> PinState for Input<S> {}
impl<S: InputState> sealed::Sealed for Input<S> {}

pub struct Floating;
pub struct PullUp;
pub struct PullDown;

impl InputState for Floating {}
impl InputState for PullUp {}
impl InputState for PullDown {}
impl sealed::Sealed for Floating {}
impl sealed::Sealed for PullUp {}
impl sealed::Sealed for PullDown {}

pub struct PA1<S: PinState> {
    _p: PhantomData<S>,
}

impl<S: PinState> PA1<S> {
    pub fn into_input<N: InputState>(self, input: N) -> PA1<Input<N>> {
        todo!()
    }

    pub fn into_output<N: OutputState>(self, output: N) -> PA1<Output<N>> {
        todo!()
    }

    pub fn with_input_state<N: InputState, R>(
        &mut self,
        input: N,
        f: impl FnOnce(&mut PA1<N>) -> R,
    ) -> R {
        todo!()
    }

    pub fn with_output_state<N: OutputState, R>(
        &mut self,
        output: N,
        f: impl FnOnce(&mut PA1<N>) -> R,
    ) -> R {
        todo!()
    }
}

// Same for `PA` and `Pin`, and other pin types.
}