Z的日志

Orin AGX 64G 中模型常驻指南

Mon, 06 Apr 2026 20:30:25 GMT

私有化部署一个中等大小的模型，用于常驻一个agent，做日常对话服务，而且不能功耗太高，毕竟烧的是自家的电费……

0 网络准备

这台设备是在Gemini的帮助下，使用一台X86 PVE下的Ubuntu刷的，过程艰险无法描述，是非曲直难以论说。总之刷的时候为了防止任何以外，仅执行了最小化安装，除了系统啥都没有。

第一步得把命令行的代理配好：

# 设置apt代理
sudo vim /etc/apt/apt.conf.d/proxy.conf
Acquire::http::Proxy "http://127.0.0.1:7897/";
Acquire::https::Proxy "http://127.0.0.1:7897/";

vim ~/.zshrc
# 设置系统代理
function proxy_on() {
    export http_proxy="http://127.0.0.1:7897"
    export https_proxy=$http_proxy
    export ftp_proxy=$http_proxy
    export no_proxy="localhost,127.0.0.1,localaddress,.localdomain.com"
    export HTTP_PROXY=$http_proxy
    export HTTPS_PROXY=$http_proxy
    export FTP_PROXY=$http_proxy
    echo -e "Proxy environment variable set."
}

# 关闭系统代理
function proxy_off() {
    unset http_proxy https_proxy ftp_proxy no_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY
    echo -e "Proxy environment variable removed."
}

# 设置git代理
git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897

# 对付顽固分子
git clone https://github.com/rofl0r/proxychains-ng.git && cd proxychains-ng
./configure --prefix=/usr --sysconfdir=/etc
make
sudo make install
sudo make install-config

sudo vim /etc/proxychains.conf
socks5  127.0.0.1 7897

1 NVIDIA工具

使用jtop管理设备状态：

# 最小化安装甚至没有pip
sudo apt update
sudo apt install python3-pip
sudo -H pip3 install -U jetson-stats # 这玩意需要监控底层传感器，不能用uv装，需要重启

此时jtop会显示：

Jetpack NOT DETECTED，说明系统裸的很彻底，适合容器化部署
NV Power[3]: MODE_50W，表明功耗还没开到最大
Jetson Clocks: inactive，表明风扇和核心频率没有锁定在最高状态

性能释放开最大：

sudo nvpmodel -m 0
sudo jetson_clocks

然后jtop会显示：

NV Power[0]: MAXN
Jetson Clocks: running

2 Docker

这个裸奔的系统连docker都省了：

# 记得 proxy_on
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

配置当前用户免sudo，然后退出ssh再重新登陆：

sudo usermod -aG docker $USER

安装 nvidia 容器工具包

sudo apt update
sudo apt install -y nvidia-container-toolkit

配置 Docker 默认使用 NVIDIA 运行时并重启服务：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

验证：

docker info | grep Runtimes
 Runtimes: io.containerd.runc.v2 nvidia runc

为docker配置代理：

因为英伟达定制系统精简了TUN模块，只能开系统代理，所以最好为docker手动配置系统代理：

# 设置配置文件
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"
Environment="NO_PROXY=localhost,127.0.0.1,::1,nvcr.io"
EOF
# 重启服务
sudo systemctl daemon-reload
sudo systemctl restart docker

如果docker手动拉取的时候报错：

❯ docker pull --platform linux/arm64 node:24
Error response from daemon: failed to resolve reference "docker.io/library/node:24": failed to do request: Head "https://registry-1.docker.io/v2/library/node/manifests/24": EOF

这是 containerd 的错误格式，不是经典 dockerd 的。走 containerd 拉镜像是独立的 systemd 服务，需要再设置一个环境变量：

# 验证，没有代理
agx in 🌐 agx2 in llama.cpp on  master [⇡] is 📦 v0.0.0 via △ via 🐍 v3.10.12
❯ sudo cat /proc/$(pgrep -x containerd)/environ | tr '\0' '\n' | grep -i proxy

# 设置代理
agx in 🌐 agx2 in llama.cpp on  master [⇡] is 📦 v0.0.0 via △ via 🐍 v3.10.12
❯ sudo mkdir -p /etc/systemd/system/containerd.service.d
sudo tee /etc/systemd/system/containerd.service.d/proxy.conf > /dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"
Environment="NO_PROXY=localhost,127.0.0.1,::1,nvcr.io"
EOF

sudo systemctl daemon-reload
sudo systemctl restart containerd
sudo systemctl restart docker

# 再验证
sudo cat /proc/$(pgrep -x containerd)/environ | tr '\0' '\n' | grep -i proxy

HTTP_PROXY=http://127.0.0.1:7897
HTTPS_PROXY=http://127.0.0.1:7897
NO_PROXY=localhost,127.0.0.1,::1,nvcr.io

3 llama.cpp测试

下个测试用的小模型：

# 创建模型存放目录
mkdir -p ~/ai-models/gguf
cd ~/ai-models/gguf

# 使用 wget 直接下载 huggingface 镜像站的 GGUF 模型
wget https://hf-mirror.com/QuantFactory/Meta-Llama-3-8B-Instruct-GGUF/resolve/main/Meta-Llama-3-8B-Instruct.Q4_K_M.gguf

构建专用的的 ARM64 CUDA 镜像：

cd ~
# 克隆最新源码
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# 此时运行构建会报错，因为docker的buildkit的网络行为很诡异，普通的梯子代理不了，Tegra默认内核没有TUN，而我又暂时没有能用的代理路由
❯ sudo docker build -t llama-cpp-cuda -f .devops/cuda.Dockerfile .
[+] Building 30.1s (3/3) FINISHED                                                                                            docker:default
 => [internal] load build definition from cuda.Dockerfile                                                                              0.0s
 => => transferring dockerfile: 2.74kB                                                                                                 0.0s
 => ERROR [internal] load metadata for docker.io/nvidia/cuda:12.8.1-runtime-ubuntu24.04                                               30.0s
 => CANCELED [internal] load metadata for docker.io/nvidia/cuda:12.8.1-devel-ubuntu24.04                                              30.0s
------
 > [internal] load metadata for docker.io/nvidia/cuda:12.8.1-runtime-ubuntu24.04:
------
cuda.Dockerfile:41
--------------------
  39 |
  40 |     ## Base image
  41 | >>> FROM ${BASE_CUDA_RUN_CONTAINER} AS base
  42 |
  43 |     RUN apt-get update \
--------------------
ERROR: failed to build: failed to solve: DeadlineExceeded: failed to fetch anonymous token: Get "https://auth.docker.io/token?scope=repository%3Anvidia%2Fcuda%3Apull&service=registry.docker.io": dial tcp [2a03:2880:f10d:183:face:b00c:0:25de]:443: i/o timeout

这里有几个坑：

网络方面，因为docker的buildkit有自己独立的网络请求和dns查找行为，系统代理无法辅助下载。因此，最好是看到报错中的镜像，记下来再手动拉取、构建。
cuda版本方面，可以看到上面的镜像默认使用了 cuda 12.8.1版本，实际上在jtop中可以看到本机为L4T 36.5.0，刷机的Jetpack版本为6.2.2。去 catalog.ngc.nvidia.com 搜索l4t-cuda出来的结果是：nvcr.io/nvidia/l4t-cuda:12.6.11-runtime、nvcr.io/nvidia/12.6.11-devel:12.6.11-devel-aarch64-ubuntu22.04 ，把构建底座改成tegra专用的，否则构建出来的镜像再运行moe模型时，batch.n_token>32 就会出现cuBLAS报错：
```
ARG UBUNTU_VERSION=22.04
# This needs to generally match the container host's environment.
ARG CUDA_VERSION=12.6.11
# Target the CUDA build image
ARG BASE_CUDA_DEV_CONTAINER=nvcr.io/nvidia/12.6.11-devel:12.6.11-devel-aarch64-ubuntu22.04

ARG BASE_CUDA_RUN_CONTAINER=nvcr.io/nvidia/l4t-cuda:12.6.11-runtime
```
既然改了22.04，那就出现新问题了，llama.cpp默认目标系统是24.04，因此.devops/cuda.Dockerfile中使用了gcc-14和g++-14，而22.04默认是11，不过最好用12，因此需要改一下构建文件使用gcc-12、g++-12，让系统走默认编译器：
```
RUN apt-get update && \
    apt-get install -y gcc-12 g++-12 build-essential cmake python3 python3-pip git libssl-dev libgomp1

ENV CC=gcc-12 CXX=g++-12 CUDAHOSTCXX=g++-12
```
此外，构建过程中包含很多无意义的编译：
- 因为llama.cpp的docker构建默认行为是编译所有NVIDIA卡的PTX汇编内核，而我只需要编译AGX ORIN，其架构代号是专门的嵌入式架构sm_87，用-DCMAKE_CUDA_ARCHITECTURES=87指定编译平台，可节省90%的编译时间；
- -DGGML_CPU_ALL_VARIANTS=ON参数会让 CMake 尝试去编译包括 SVE (可伸缩矢量扩展) 在内的高级 CPU 算子，就是它需要gcc-12和g++-12，但 Orin 的 Carmel CPU 是基于 ARMv8.2-A 架构的，不支持最激进的 SVE 指令集，可以关掉；

最后，再加两个编译开关，避开tegra这种统一内存设备的架构坑。如果不开，在 Qwen3.5-35B-A3B-Uncensored-HauhauCS-Aggressive-Q8_0.gguf 这种模型上会出现不带 mmproj 时一切正常，加上 mmproj 输入图片就报cuMemAddressReserve的错误。

-DGGML_CUDA_ENABLE_UNIFIED_MEMORY=ON，以统一内存架构调度；
-DGGML_CUDA_NO_VMM=ON，禁止预申请一大块连续内存。

# 原来的
  23   │ RUN if [ "${CUDA_DOCKER_ARCH}" != "default" ]; then \
  24   │     export CMAKE_ARGS="-DCMAKE_CUDA_ARCHITECTURES=${CUDA_DOCKER_ARCH}"; \
  25   │     fi && \
  26   │     cmake -B build -DGGML_NATIVE=OFF -DGGML_CUDA=ON -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=ON LLAMA_BUILD_TESTS=OFF ${CMAKE_ARGS} -DCMAKE_EXE_LINKER_FLAGS=-Wl,--allow-shlib-undefined . && \
  27   │     cmake --build build --config Release -j$(nproc)
# 替换为
  28   │ RUN cmake -B build -DGGML_NATIVE=ON -DGGML_CUDA=ON -DGGML_CUDA_NO_VMM=ON -DGGML_CUDA_ENABLE_UNIFIED_MEMORY=ON -DGGML_BACKEND_DL=ON -DGGML_CPU_ALL_VARIANTS=OFF -DLLAMA_BUILD_TESTS=OFF -DCMAKE_CUDA_ARCHITECTURES=87 -DCMAKE_EXE_LINKER_FLAGS=-Wl,--allow-shlib-undefined . && \
  29   │     cmake --build build --config Release -j$(nproc)

正确的安装姿势（如果有自己的路由可以省略手动拉取这一步）：

# 手动拉镜像：
docker pull nvcr.io/nvidia/12.6.11-devel:12.6.11-devel-aarch64-ubuntu22.04
docker pull nvcr.io/nvidia/l4t-cuda:12.6.11-runtime

cd ~/llama.cpp

# 绕开buildkit，约十分钟
DOCKER_BUILDKIT=0 sudo docker build --network host \
  --build-arg HTTP_PROXY=http://127.0.0.1:7897 \
  --build-arg HTTPS_PROXY=http://127.0.0.1:7897 \
  --build-arg NO_PROXY="localhost,127.0.0.1,ports.ubuntu.com,archive.ubuntu.com,security.ubuntu.com" \
  -t llama-cpp-tegra -f .devops/cuda.Dockerfile .

测试编译好的镜像：

sudo docker run -d \
  --name llama-server \
  --runtime nvidia \
  --gpus all \
  -e NVIDIA_DISABLE_REQUIRE=1 \
  -v ~/ai-models/gguf:/models \
  -p 8080:8080 \
  llama-cpp-tegra \
  -m /models/Meta-Llama-3-8B-Instruct.Q4_K_M.gguf \
  -c 8192 \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 999

访问 localhost:8080 就可以看到llama.cpp的对话页面了。

4 llama.cpp部署中模型

最近看上一款模型，是qwen3.5用opus指令蒸馏过的27b稠密模型：Jackrong/Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled-GGUF。既然agx orin有64g统一内存，所以可以试试Q8_0.gguf（约27G）奢侈一把。

sudo docker run -d \
  --name llama-server \
  --runtime nvidia \
  --gpus all \
  -e NVIDIA_DISABLE_REQUIRE=1 \
  -v ~/ai-models/gguf:/models \
  -p 8080:8080 \
  llama-cpp-tegra \
  -m /models/Qwen3.5-27B.Q4_K_M.gguf \
  -c 32768 \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 999

内存绰绰有余，但是生成速度堪忧，设备统一内存带宽也就是204GB/s，然鹅，面对27G的模型，计算速度的物理上限也就是 204 ÷ 26 ≈ 7.8 tokens/s，再去掉总线调度损耗和KV Cache损耗，实际生成速度就是极限的50%~70%，于是我观察到的速度大概为 4 token/s，对于阅读速度稍快的中国人来说，不能忍，得换Q4_K_M的。

不过这两天谷歌有发布了gemma-4，这是个原生多模态，搞一个试试：

# 加载大号模型前可以先清一下内存
sudo sync && sudo sysctl -w vm.drop_caches=3

sudo docker run -d \
  --name llama-cpp-gemma-4-26B-A4B-it-UD-Q8_K_XL \
  --runtime nvidia \
  --gpus all \
  --ulimit memlock=-1:-1 \
  -e NVIDIA_DISABLE_REQUIRE=1 \
  -e GGML_CUDA_NO_PINNED=1 \
  -e GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 \
  -e GGML_CUDA_FORCE_MMQ=1 \
  -v ~/ai-models/gguf:/models \
  -p 8081:8080 \
  llama-cpp-tegra \
  -m /models/gemma-4-26B-A4B-it-UD-Q8_K_XL.gguf \
  --mmproj /models/gemma-4-26B-A4B-it-mmproj-BF16.gguf \
  -c 131072 \
  -fa on \
  -ctk q8_0 \
  -ctv q8_0 \
  -np 1 \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 999

再测试千问：

sudo docker run -d \
  --name llama-cpp-Qwen3.5-35B-A3B-Q8_K_XL \
  --runtime nvidia \
  --gpus all \
  --ulimit memlock=-1:-1 \
  -e NVIDIA_DISABLE_REQUIRE=1 \
  -e GGML_CUDA_NO_PINNED=1 \
  -e GGML_CUDA_ENABLE_UNIFIED_MEMORY=1 \
  -e GGML_CUDA_FORCE_MMQ=1 \
  -v ~/ai-models/gguf:/models \
  -p 8081:8080 \
  llama-cpp-tegra \
  -m /models/Qwen3.5-35B-A3B-UD-Q8_K_XL.gguf \
  --mmproj /models/Qwen3.5-35B-A3B-UD-Q8_K_XL-mmproj-BF16.gguf \
  -c 65536 \
  -fa on \
  -ctk q8_0 \
  -ctv q8_0 \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 999

5 LiteLLM模型汇聚网关

为了物尽其用，每个 Orin AGX 64G 都耗尽了显存，我需要在第三个设备上搭一个模型汇聚网关，做成类似 OpenAI API 那样可以选择模型，并把请求分发到各个 end point 上的的网关，Gemini 推荐使用 LiteLLM 的 docker 部署。就是个转发代理，还需要长期开，就把这玩意放在 rock 5b 上了。

写好网关配置vim ~/litellm/config.yaml：

model_list:
  - model_name: gemma-4-26B-A4B-it-UD-Q8_K_XL
    litellm_params:
      model: openai/gemma-4-26B-A4B-it-UD-Q8_K_XL
      api_base: http://192.168.1.138:8081/v1
      api_key: sk-1234

  - model_name: Qwen3.5-35B-A3B-Q8_K_XL
    litellm_params:
      model: openai/Qwen3.5-35B-A3B-Q8_K_XL
      api_base: http://192.168.1.139:8081/v1
      api_key: sk-1234

加载配置即可：

# 网不好可以先 pull
docker pull docker.litellm.ai/berriai/litellm:main-latest

docker run -d \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -p 4001:4000 \
  --name litellm-proxy \
  docker.litellm.ai/berriai/litellm:main-latest \
  --config /app/config.yaml \
  --detailed_debug

测试模型列表：

curl http://localhost:4001/v1/models
{"data":[{"id":"gemma-4-26B-A4B-it-UD-Q8_K_XL","object":"model","created":1677610602,"owned_by":"openai"},{"id":"Qwen3.5-35B-A3B-Q8_K_XL","object":"model","created":1677610602,"owned_by":"openai"}],"object":"list"}%

测试gemma-4反应：

 curl -X POST "http://localhost:4001/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-1234" \
  -d '{
    "model": "gemma-4-26B-A4B-it-UD-Q8_K_XL",
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍一下你自己。"}
    ]
  }'
{"id":"chatcmpl-5RXTGa6ZQ5aW57JGlsDzxOylaWptEVhE","created":1775988908,"model":"gemma-4-26B-A4B-it-UD-Q8_K_XL","object":"chat.completion","system_fingerprint":"b8764-8fe78a7ca","choices":[{"finish_reason":"stop","index":0,"message":{"content":"我是 Gemma 4，是由 Google DeepMind  开发的开源权重大型语言模型。","role":"assistant","reasoning_content":"*   Language: Chinese (\"你好，请用一句话介绍一下你自己。\")\n    *   Content: \"Hello, please introduce yourself in one sentence.\"\n\n    *   Identity: Gemma 4.\n    *   Developer: Google DeepMind.\n    *   Nature: Large Language Model (LLM) with open weights.\n    *   Capabilities: Text and image processing (audio for 2B/4B), text-only output.\n    *   Knowledge Cutoff: January 2025.\n\n    *   *Draft 1 (Literal):* 我是 Gemma 4，由 Google DeepMind 开发的大型语言模型。 (I am Gemma 4, a large language model developed by Google DeepMind.)\n    *   *Draft 2 (More descriptive):* 我是 Gemma 4，由 Google DeepMind 开发的开源权 重的多模态大语言模型。 (I am Gemma 4, an open-weights multimodal LLM developed by Google DeepMind.)\n    *   *Refining for \"one sentence\" and \"identity\":* The prompt asks for an introduction in one sentence.\n\n    *   \"我是 Gemma 4，是由 Google DeepMind 开发的开源权重大型语言模型。\" (I am Gemma 4, an open-weights large language model developed by Google DeepMind.)\n\n    *   Identify as Gemma 4? Yes.\n    *   Mention Google DeepMind? Yes.\n    *   One sentence? Yes.\n\n    \"我是 Gemma 4，是由 Google DeepMind 开发的开源权重大型语言模型。\"","provider_specific_fields":{"refusal":null,"reasoning_content":"*   Language: Chinese (\"你好，请用一句话介绍一下你自己。\")\n    *   Content: \"Hello, please introduce yourself in one sentence.\"\n\n    *   Identity: Gemma 4.\n    *   Developer: Google DeepMind.\n    *   Nature: Large Language Model (LLM) with open weights.\n    *   Capabilities: Text and image processing (audio for 2B/4B), text-only output.\n    *   Knowledge Cutoff: January 2025.\n\n    *   *Draft 1 (Literal):* 我是 Gemma 4，由 Google DeepMind 开发的大型语言模型。 (I am Gemma 4, a large language model developed by Google DeepMind.)\n    *   *Draft 2 (More descriptive):* 我是 Gemma 4，由 Google DeepMind 开发的开源权重的多模态大 语言模型。 (I am Gemma 4, an open-weights multimodal LLM developed by Google DeepMind.)\n    *   *Refining for \"one sentence\" and \"identity\":* The prompt asks for an introduction in one sentence.\n\n    *   \"我是 Gemma 4，是由 Google DeepMind 开发的开源权重大型语言模型。\" (I am Gemma 4, an open-weights large language model developed by Google DeepMind.)\n\n    *   Identify as Gemma 4? Yes.\n    *   Mention Google DeepMind? Yes.\n    *   One sentence? Yes.\n\n    \"我是 Gemma 4，是由 Google DeepMind 开发的开源权重大型语言模型。\""}},"provider_specific_fields":{}}],"usage":{"completion_tokens":353,"prompt_tokens":25,"total_tokens":378,"prompt_tokens_details":{"cached_tokens":0}},"timings":{"cache_n":0,"prompt_n":25,"prompt_ms":254.532,"prompt_per_token_ms":10.181280000000001,"prompt_per_second":98.21947731522953,"predicted_n":353,"predicted_ms":16617.949,"predicted_per_token_ms":47.076342776203965,"predicted_per_second":21.242091909176036}}%

测试qwen3.5反应：

curl -X POST "http://localhost:4001/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-1234" \
  -d '{
    "model": "Qwen3.5-35B-A3B-Q8_K_XL",
    "messages": [
      {"role": "user", "content": "Hello, please write a very short python script to print hello world."}
    ]
  }'
{"id":"chatcmpl-gCLU58UkI3h51hgucpWwucmTJ1yX7qox","created":1775988956,"model":"Qwen3.5-35B-A3B-Q8_K_XL","object":"chat.completion","system_fingerprint":"b8762-073bb2c20","choices":[{"finish_reason":"stop","index":0,"message":{"content":"```python\nprint(\"hello world\")\n```","role":"assistant","reasoning_content":"Thinking Process:\n\n1.  **Analyze the Request:**\n    *   Task: Write a very short Python script.\n    *   Functionality: Print \"hello world\".\n    *   Constraint: \"very short\".\n\n2.  **Determine the Solution:**\n    *   The standard way to print in Python is `print(\"hello world\")`.\n    *   This is already one line and very short.\n\n3.  **Draft the Code:**\n    ```python\n    print(\"hello world\")\n    ```\n\n4.  **Review against Constraints:**\n    *   Is it Python? Yes.\n    *   Is it very short? Yes (one line).\n    *   Does it print \"hello world\"? Yes.\n\n5.  **Final Output Generation:** (Just the code block).\n","provider_specific_fields":{"refusal":null,"reasoning_content":"Thinking Process:\n\n1.  **Analyze the Request:**\n    *   Task: Write a very short Python script.\n    *   Functionality: Print \"hello world\".\n    *   Constraint: \"very short\".\n\n2.  **Determine the Solution:**\n    *   The standard way to print in Python is `print(\"hello world\")`.\n    *   This is already one line and very short.\n\n3.  **Draft the Code:**\n    ```python\n    print(\"hello world\")\n    ```\n\n4.  **Review against Constraints:**\n    *   Is it Python? Yes.\n    *   Is it very short? Yes (one line).\n    *   Does it print \"hello world\"? Yes.\n\n5.  **Final Output Generation:** (Just the code block).\n"}},"provider_specific_fields":{}}],"usage":{"completion_tokens":188,"prompt_tokens":24,"total_tokens":212,"prompt_tokens_details":{"cached_tokens":0}},"timings":{"cache_n":0,"prompt_n":24,"prompt_ms":290.856,"prompt_per_token_ms":12.119,"prompt_per_second":82.5150589982672,"predicted_n":188,"predicted_ms":10157.401,"predicted_per_token_ms":54.02872872340426,"predicted_per_second":18.508671657247756}}%

6 部署 Hermes

我不喜欢龙虾，一个性格使然不喜欢凑热闹，另外就是那个项目几个月前就已经出现项目管理崩溃的迹象了，issue和pr数量极度扭曲。这两天看到 hermes-agent 倒是想试试。

Pre-Requisites

firecrawl 是个网页清洗工具，这玩意是基于 Playwright 的相当重型，CPU和内存压力都不会小，rk3588 大概率受不了，CIX P1在办公室还关机了，只能暂时装我电脑上了，脚本参考 Hermes Agent Full Setup Tutorial: How to Setup Your First AI Agent (Gemma 4)：

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl

cat > .env << 'EOF'
PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false
BULL_AUTH_KEY=somePASSword
EOF

sed -i 's|# image: ghcr.io/firecrawl/firecrawl|image: ghcr.io/firecrawl/firecrawl|' ./docker-compose.yaml
sed -i 's|  build: apps/api|  # build: apps/api|' docker-compose.yaml
sed -i 's|# image: ghcr.io/firecrawl/playwright-service:latest|image: ghcr.io/firecrawl/playwright-service:latest|' docker-compose.yaml
sed -i 's|    build: apps/playwright-service-ts|    # build: apps/playwright-service-ts|' docker-compose.yaml

docker compose up -d

安装 Hermes

目前装在我电脑的wsl2里，有时间得弄到o6n上，这个服务需要长时间开机，我舍不得电费。

安装过程需要注意的是：

配置模型 API 时，写上面的 LiteLLM 的 URL http://192.168.1.120:4001/v1，接下来模型可以选1或2，粗略测了一下，gemma-4的日常任务比qwen3.5强，但qwen3.5写代码比gemma-4强不少：

API base URL [e.g. https://api.example.com/v1]: http://192.168.1.120:4001/v1
API key [optional]:
Verified endpoint via http://192.168.1.120:4001/v1/models (2 model(s) visible)
  Available models:
    1. gemma-4-26B-A4B-it-UD-Q8_K_XL
    2. Qwen3.5-35B-A3B-Q8_K_XL
  Select model [1-2] or type name: 1
Context length in tokens [leave blank for auto-detect]:
Default model set to: 1 (via http://192.168.1.120:4001/v1)
  💾 Saved to custom providers as "192.168.1.120:4001" (edit in config.yaml)

这玩意支持微信，在选 Messaging Platforms时选上，然后扫码，微信会出来一个 ClawBot。
配置 Firecrawl 时，因为我把 hermes 跟 firecrawl 的 docker compose 装一起了，直接回车用默认的 http://localhost:3002 即可。

附：Orin AGX 64G的PVE刷机指南：

Orin进入Recovery模式分两种状况，一是当Orin处于未开机状态，二是当Orin处于开机状态。

当处于未开机状态时，需要先长按住②键(Force Recovery键)，然后给Orin接上电源线通电，此时白色指示灯亮起，但进入Recovery模式后是黑屏的，所以此时连接Orin的显示屏不会有什么反应。
当处于已开机状态时，需要先长按住②键，然后按下③键(Reset键)，先松开③键，再松开②键。

进入刷机状态时，Ubuntu 上应该出现 recovery 状态的设备（0955:7023）：

agx-flash@agx-flash:~$ lsusb
Bus 002 Device 002: ID 0627:0001 Adomax Technology Co., Ltd QEMU USB Tablet
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 008 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 007 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 009 Device 003: ID 0955:7023 NVIDIA Corp. APX
Bus 009 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
Bus 009 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 010 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 005 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

为以防万一，配上代理：

export http_proxy="http://192.168.1.125:7897"
export https_proxy="http://192.168.1.125:7897"
export HTTP_PROXY="http://192.168.1.125:7897"
export HTTPS_PROXY="http://192.168.1.125:7897"

什么组件都不装，只刷一个Linux进去，等进了系统要用什么再装什么：

sdkmanager --cli --action install --login-type devzone --product Jetson --target-os Linux --version 6.2.2 --target JETSON_AGX_ORIN_TARGETS --select 'Jetson Linux' --flash --license accept

刷完会问“SDK Manager is about to install SDK components on your Jetson AGX, To install SDK components on your Jetson AGX Orin modules:...”，只刷系统就选择 2. Skip。

新年要用新系统

Sun, 08 Mar 2026 17:30:25 GMT

这个blog两年没更新过了啊！靠着AI打气又拾起来了！

起因是节前Fusion 360警告我win10不受支持了，Gemini也建议我换个系统，并且疯狂安利Win11，安抚我说Win11已经不是几年前那种费拉不堪的状态了。

再信AI一次。

0 备份

尤其是wsl2！：

mkdir -p ~/wsl_backup/manifests
cd ~/wsl_backup/manifests

#######
# apt #
#######
# 导出所有手动安装的包（排除依赖包）
comm -23 <(apt-mark showmanual | sort -u) <(gzip -dc /var/log/installer/initial-status.gz | sed -n 's/^Package: //p' | sort -u) > apt-manual-packages.txt
# 如果上面命令报错或太复杂，用这个简单的版本（会包含一些基础包）：
apt-mark showmanual > apt-manual-list.txt

###################
# python 和 conda #
###################
# 激活主环境，比如 base 或 pytorch
conda env export --no-builds > conda_environment.yml
pip freeze > requirements.txt

########
# rust #
########
cargo install --list > cargo-crates.txt

########
# node #
########
npm list -g --depth=0 > npm-global-packages.txt

##############
# shell conf #
##############
cd ~
tar -czvf ~/wsl_backup/dotfiles.tar.gz \
    .zshrc \
    .bashrc \
    .profile \
    .zsh_history \
    .bash_history
    .ssh \
    .tmux.conf \
    .fzf.zsh \
    .gitconfig \
    .vimrc \
    .config/nvim \
    .gnupg \
    .condarc \
    .pip \
    .cargo/config.toml \

1 装系统

装专业版即可，需要注意，分区别在跟Linux似的一块/用到底，2T盘可以先给C盘384G（$384 \times 1024 = 393216 \text{ MB}$），剩下的给D盘。使用的时候：

wsl2放D盘
尽量用protable软件，全放D盘，那些死皮赖脸要待在C盘的软件再放C盘。

如此，重装的时候不会一锅端。

另外，装好了第一次见到Windows初始化配置的时候，微软强制登录Microsoft账号。此时Shift + F10，输入OOBE\BYPASSNRO自动重启，就可以选“我没有 Internet 连接”跳过账号登录。好处是可以完全自己决定user文件夹的名字。

进了系统先装驱动，尤其是显卡驱动，先装完驱动再装wsl2，但是主板带的什么MSI Center装完驱动可以卸了。

NVIDIA APP 选 NVIDIA studio 驱动，对跑CUDA的场景来说，Game Ready 驱动更新过于频繁。

2 清理微软的垃圾

第一时间防火防盗防微软。

彻底禁止 Windows 自动更新驱动： Win + R 输入 gpedit.msc：计算机配置 -> 管理模板 -> Windows 组件 -> Windows 更新 -> 管理从 Windows 更新提供的更新，右侧的 “Windows 更新不包括驱动程序”，选择 “已启用”。如此，让 Windows Update 只推安全补丁和功能更新，绝不会动显卡、网卡、声卡驱动。
保留 Defender，配置“码农豁免区” 打开 Windows 安全中心 -> 病毒和威胁防护 -> 管理设置，下拉找到 “排除项” -> 添加或删除排除项，酌情加入：
- D:\WSL (放 WSL 镜像，防止扫描 vhdx 读写)；
- D:\DEV (放代码)；
- D:\MOEDL (放模型)；
- etc.
左下角“天气新闻”等等是 小组件” (Widgets)：Win + R 输入 gpedit.msc：计算机配置 -> 管理模板 -> Windows 组件 -> 小组件，右侧的 “允许小组件”，选择 “已禁用”。
锁屏时“天气新闻”等待是 Windows 聚焦 (Windows Spotlight) ：
- 右键桌面 -> “个性化” -> 选择 “锁屏界面”，在个 性化锁屏界面 中选择 “图片” (Picture) 。
- 再往下看，如果有 “在锁屏界面上获取花絮、提示、技巧和更多内容”，选择关闭。
- 如果有 “锁屏界面状态”，改为 无 (None) 。
开始菜单里的垃圾，右键桌面 -> “个性化” -> “开始”：
- 显示最近添加的应用 -> 关。
- 显示最常用的应用 -> 关。
- 在“开始”菜单中……显示最近打开的项目 -> 关
开始菜单的搜索 强行把本地搜索和 Bing 搜索混合：
- Win + R 输入 gpedit.msc：用户配置 (User Configuration) -> 管理模板 (Administrative Templates) -> Windows 组件 (Windows Components) -> 文件资源管理器 (File Explorer)，右侧找：“关闭文件资源管理器搜索框中的最近搜索条目显示” (Turn off display of recent search entries in the Windows Search box) ，选择 “已启用” (Enabled) 。重启资源管理器即可，taskkill /f /im explorer.exe; start explorer.exe。注意：微软经常改这个策略的名字，比如也可能叫“关闭搜索框建议”。
- 也可以执行 reg add "HKCU\Software\Policies\Microsoft\Windows\Explorer" /v "DisableSearchBoxSuggestions" /t REG_DWORD /d 1 /f 修改。
- 关闭 “搜索要点” (Search Highlights)：设置 -> 隐私和安全性 -> 搜索权限，往下找到 “更多设置”，关掉 “显示搜索要点” (Show search highlights) 。
任务栏的搜索框，任务栏空白处右键 -> “任务栏设置”，第一项就是 “搜索”，选择 “隐藏”。
Steam/Epic党可以把XBox相关都端了：
- 关闭 Xbox Game Bar：在设置 -> 游戏 -> Xbox Game Bar，关闭 “允许控制器打开 Game Bar”。
- 开始菜单搜 "Xbox"，右键 -> 卸载。
- 唯一例外：游戏模式 (Game Mode) ，留着，在设置 -> 游戏 -> 游戏模式 里，保持 开 (ON)。
关闭 OneDrive：
- 解除“文件夹备份”，任务栏右下角的那个“云朵”图标，右上角齿轮进入设置，找到 “同步并备份” (Sync and backup) -> “管理备份” (Manage backup)，把“文档”、“图片”、“桌面”全部关掉（Stop backup）。，此时系统会把这些文件夹的路径从 C:\Users\<username>\OneDrive\Desktop 恢复为 C:\Users\<username>\Desktop
- 取消链接：设置里 -> “账户” (Account)，点击 “取消链接此电脑” (Unlink this PC)。
- 卸载：设置 -> 应用 -> 安装的应用，搜 "OneDrive" -> 卸载。
至于 基于虚拟化的安全性 (VBS)” / HVCI，模型和网上的说法都没定论。
- Win 键搜索 "内核隔离" -> “内存完整性”，收益有限，关不关无所谓。
- 网上流传的 bcdedit /set hypervisorlaunchtype off 不能设置， wsl2 要用。

找回Win10右键菜单：

reg add "HKCU\Software\Classes\CLSID\{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}\InprocServer32" /f /ve

重启资源管理器即可。后悔的话：

reg delete "HKCU\Software\Classes\CLSID\{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}" /f

3 清理其他垃圾，装Windows下的常用工具

搜狗自带桌面壁纸和汪仔，记得删掉和关闭。
取消WPS的云盘资源管理器图标、取消传输助手自启。
装cherrystudio。
装no machine。
Snipaste用portable。
Motrix用portable。

装Git：

winget install --id Git.Git

装微信QQ：

winget install Tencent.WeChat
winget install Tencent.QQ

PotPlayer：

winget install Daum.PotPlayer

装powertoys：

winget install Microsoft.PowerToys

装Everything和Listary：

winget install voidtools.Everything
winget install -e --id Bopsoft.Listary

4 安装wsl2

有显卡驱动了再装wsl2。

先装 WSL 本体，管理员 PowerShell：
```
wsl --install
```
装完建议重启，确认 WSL 版本：
```
wsl --version
```
在 D 盘准备一个专门目录 D:\WSL，安装一个临时 Ubuntu（会默认在 C 盘），启动一次 Ubuntu，完成用户名/密码初始化后退出。
```
wsl --install -d Ubuntu
```
把迁移到 D 盘：
- 先关掉 WSL：
```
wsl --shutdown
```
- 导出为 tar（临时文件建议也放 D 盘）：
```
wsl --export Ubuntu D:\WSL\ubuntu.tar
```
- 注销原来的 Ubuntu（这一步会删除 C 盘那个实例的注册与磁盘）：
```
wsl --unregister Ubuntu
```
- 导入到 D 盘（强制 WSL2）：
```
wsl --import Ubuntu D:\WSL D:\WSL\ubuntu.tar --version 2
```
现在 Ubuntu 的 ext4.vhdx 就在 D:\WSL\ 下面了。
wsl2网络配置：建议按老方法，默认NAT，不要配自动代理、DNS隧道等配置。装个clash-verge，用自己写的订阅发布程序让Windows、wsl、PVE、rock5b、o6n等设备同步订阅配置，虽然heavy但是最稳妥：
```
[wsl2]
networkingMode=nat
autoProxy=false
dnsTunneling=false
dnsProxy=false
```
新wsl2支持mirror，直接走Windows的网卡，别的没什么问题，但是gemini-cli或codex可能会用不了：
```
[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true
```
此时wget下载chrome会自动拿到autoproxy配置走clash，但是apt不行，还得手动指定proxy
```
sudo tee /etc/apt/apt.conf.d/99proxy <<'EOF'
Acquire::http::Proxy "http://127.0.0.1:7897";
Acquire::https::Proxy "http://127.0.0.1:7897";
EOF
```

5 初始化wsl2

建议先改主机名：

sudo hostnamectl set-hostname new_name

用gemini和chatgpt写了个一键安装脚本，也可以一步一步执行。

#!/usr/bin/env bash
set -e

# ==========================================
#  WSL2 Development Environment Bootstrap
#  Target: Debian/Ubuntu
#  Role:   System, Shell, Rust, Node, Python, Git
# ==========================================

# 颜色定义，方便看日志
GREEN='\033[0;32m'
BLUE='\033[0;34m'
RED='\033[0;31m'
NC='\033[0m'

log() { echo -e "${GREEN}[SETUP] $1${NC}"; }
info() { echo -e "${BLUE}[INFO] $1${NC}"; }
error() { echo -e "${RED}[ERROR] $1${NC}"; }

# 0. 基础检查
# ------------------------------------------
if [ "$EUID" -eq 0 ]; then
  error "请不要使用 root 运行此脚本，请使用普通用户运行！"
  error "脚本内部会在需要时请求 sudo 权限。"
  exit 1
fi

# 保持 sudo 权限活跃，防止脚本运行中途因为超时等待输入密码
sudo -v
while true; do sudo -n true; sleep 60; kill -0 "$$" || exit; done 2>/dev/null &

# 先把文件建好，后面的 Rust/NVM/Conda 就会以为你已经在使用 zsh 了，
# 它们会自动把 export PATH... 写入这两个文件。
touch "$HOME/.bashrc"
touch "$HOME/.zshrc"

### ========================================
### 1. 系统基础 (System Base)
### ========================================
log "📦 1. 更新系统并安装基础依赖..."

sudo apt update && sudo apt upgrade -y

# 安装必备工具
# build-essential: 编译环境
# software-properties-common:以此支持 add-apt-repository
sudo apt install -y \
  git git-lfs curl wget ca-certificates \
  build-essential pkg-config libssl-dev \
  zip unzip btop tmux zsh vim \
  net-tools iproute2 dnsutils \
  jq tree procps make \
  direnv rsync shellcheck \
  software-properties-common ffmpeg \
  fonts-noto-cjk fonts-wqy-microhei \
  language-pack-zh-hans

# 注：如果要装yq，直接装go版二进制文件。
# 获取并转换系统架构名称 (匹配 mikefarah/yq 的命名规则)
ARCH=$(uname -m)
case $ARCH in
    x86_64) YQ_ARCH="amd64" ;;
    aarch64) YQ_ARCH="arm64" ;;
    *) echo "不支持的架构"; exit 1 ;;
esac

# 下载最新版的二进制文件并安装到 /usr/local/bin
wget "https://github.com/mikefarah/yq/releases/latest/download/yq_linux_${YQ_ARCH}"
sudo mv "yq_linux_${YQ_ARCH}" /usr/local/bin/yq
sudo chmod +x /usr/local/bin/yq

# 安装fastfetch，因为sudo后常用 gpg/dirmngr 去连 keyserver，
# gpg/dirmngr 不读 apt 的代理配置，
# 而且 sudo 默认还会把 shell 里的 http_proxy/https_proxy 环境变量“清掉”，
# 导致直连 keyserver，然后被墙阻断，表现为“没反应”。
export http_proxy="http://127.0.0.1:7897"
export https_proxy="http://127.0.0.1:7897"

# 或永久添加代理
echo 'export http_proxy="http://127.0.0.1:7897"' >> ~/.bashrc
echo 'export https_proxy="http://127.0.0.1:7897"' >> ~/.bashrc
echo 'export http_proxy="http://127.0.0.1:7897"' >> ~/.zshrc
echo 'export https_proxy="http://127.0.0.1:7897"' >> ~/.zshrc

sudo --preserve-env=http_proxy,https_proxy add-apt-repository ppa:zhangsongcui3371/fastfetch -y
sudo apt update
sudo apt install fastfetch -y

### ========================================
### 2. Rust 工具链 (Rust & Modern CLI)
### ========================================
log "🦀 2. 安装 Rust 环境..."

if ! command -v rustup >/dev/null 2>&1; then
  # 安装 Rustup
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
else
  info "Rustup 已安装，跳过."
fi

# 【关键】加载环境变量，确保 cargo 命令可用
# 如果你分步运行，请务必执行这一行
source "$HOME/.cargo/env"

log "🦀 安装 Cargo Binstall (加速工具安装)..."
if ! command -v cargo-binstall >/dev/null 2>&1; then
  curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
fi

log "🦀 安装现代命令行工具 (Rust编写)..."
# 以用户token登录方式，解除 GitHub API 速率限制 (Rate Limiting)  
# cargo-binstall 匿名查询API每小时仅60次，
# 不登录超过将报403，登录将提升到5000次
# Settings -> Developer settings -> Personal access tokens -> Tokens (classic)，
# Expiration 选 "No expiration"，Scopes (权限) 一个都不用勾
export GITHUB_TOKEN="ghp_xxx"

# bob-nvim: Neovim 版本管理器
# starship: 跨 Shell 提示符
# eza(ls), bat(cat), fd(find), ripgrep(grep), zoxide(cd)
cargo binstall -y \
  eza bat fd-find ripgrep du-dust procs zoxide hyperfine \
  cargo-watch cargo-nextest cargo-update cargo-audit \
  starship bob-nvim topgrade tealdeer zellij

# atuin本地编译更不容易报错glibc的错误
cargo install atuin

# 装了tealdeer可以卸载 ubuntu 自带的 haskell tldr-hs
sudo apt remove -y tldr

### ========================================
### 3. Neovim (via Bob)
### ========================================
log "📝 3. 使用 Bob 安装最新 Neovim..."

# 确保 bob 在路径中
export PATH="$HOME/.cargo/bin:$PATH"

if command -v bob >/dev/null 2>&1; then
  # 安装最新的稳定版
  bob install stable
  bob use stable
  
  # 这一步是为了确保 nvim 能被系统找到
  # Bob 默认把 nvim 放在 ~/.local/share/bob/nvim-bin
  if [[ ":$PATH:" != *":$HOME/.local/share/bob/nvim-bin:"* ]]; then
      info "提示: 请将 $HOME/.local/share/bob/nvim-bin 添加到你的 PATH 中"
  fi
else
  error "Bob 安装失败，跳过 Neovim 安装。"
fi

# 1. 让当前终端立刻生效（临时）
export PATH="$HOME/.local/share/bob/nvim-bin:$PATH"
# 2. 写入 .bashrc（永久生效，防止下次进 bash 找不到 nvim）
echo 'export PATH="$HOME/.local/share/bob/nvim-bin:$PATH"' >> ~/.bashrc
echo 'export PATH="$HOME/.local/share/bob/nvim-bin:$PATH"' >> ~/.zshrc

# 如果我觉得 neovim 过于毛坯，可以安装 lazyvim: https://www.lazyvim.org/installation
# 备份
for dir in ~/.config/nvim ~/.local/share/nvim ~/.local/state/nvim ~/.cache/nvim; do
    [ -d "$dir" ] && mv "$dir" "${dir}.bak"
done

git clone https://github.com/LazyVim/starter ~/.config/nvim
rm -rf ~/.config/nvim/.git

# 第一次打开 nvim 要装东西，会比较慢，记得梯子

### ========================================
### 4. Node.js (NVM)
### ========================================
log "🟢 4. 安装 Node.js 环境..."

export NVM_DIR="$HOME/.nvm"

if [ ! -d "$NVM_DIR" ]; then
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
fi

# 【关键】加载 NVM 环境
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

log "🟢 安装 Node LTS..."
nvm install --lts
nvm use --lts
nvm alias default lts/*

log "🟢 安装 pnpm 和常用全局包..."
if ! command -v pnpm >/dev/null 2>&1; then
  curl -fsSL https://get.pnpm.io/install.sh | sh -
fi
pnpm setup

# 临时加载 pnpm 路径
export PATH="$HOME/.local/share/pnpm:$PATH"

# 安装常用开发工具 
pnpm add -g typescript tsx eslint prettier @google/gemini-cli @openai/codex
# pnpm 交互式构建批准
pnpm approve-builds -g
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

### ========================================
### 5. Python uv and miniconda
### ========================================
log "🐍 5. 安装 Python 环境 (uv)..."

if ! command -v uv >/dev/null 2>&1; then
  curl -Ls https://astral.sh/uv/install.sh | sh
fi

# 临时加载 uv 路径
export PATH="$HOME/.local/bin:$PATH"

log "🐍 安装 Python 工具链..."
# uv tool install 类似于 pipx，安装到隔离环境
for tool in ruff mypy black poetry httpie; do
    uv tool install "$tool" || true
done

log "🐍 5.5 安装 Miniconda..."

# 定义安装路径 (通常在 ~/miniconda3 或 ~/.miniconda3)
MINICONDA_PATH="$HOME/miniconda3"

if [ ! -d "$MINICONDA_PATH" ]; then
  # 1. 下载最新的 Linux 安装脚本
  wget "https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-$(uname -m).sh" -O miniconda.sh
  
  # 2. 静默安装 (-b: batch mode, -p: prefix path)
  bash miniconda.sh -b -p "$MINICONDA_PATH"
  
  # 3. 删除安装包
  rm miniconda.sh
  
  # 4. 【关键配置】初始化 Shell (bash 和 zsh)
  # 这步会自动把 conda 的路径写入 .bashrc 和 .zshrc
  "$MINICONDA_PATH/bin/conda" init bash
  "$MINICONDA_PATH/bin/conda" init zsh

  # 5. 【强力推荐】禁止 Conda 默认激活 base 环境
  # 否则每次打开终端前面都有个 (base)，会干扰 uv 和系统 Python
  "$MINICONDA_PATH/bin/conda" config --set auto_activate_base false
  
  log "✅ Miniconda 安装完成 (Base 环境已禁用自动激活)"
else
  info "Miniconda 已存在，跳过安装。"
fi

### ========================================
### 6. Git & GitHub
### ========================================
log "🐙 6. 安装 Git 工具..."

# 6.1 GitHub CLI (gh)
if ! command -v gh >/dev/null 2>&1; then
  info "安装 gh cli..."
  sudo mkdir -p -m 755 /etc/apt/keyrings
  wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
  sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
  sudo apt update
  sudo apt install -y gh
fi

# 6.2 Lazygit (自动架构检测)
if ! command -v lazygit >/dev/null 2>&1; then
  info "安装 lazygit..."
  LAZYGIT_VERSION=$(curl -s "https://api.github.com/repos/jesseduffield/lazygit/releases/latest" | grep -Po '"tag_name": "v\K[^"]*')
  ARCH=$(uname -m)
  case $ARCH in
    x86_64) LG_ARCH="x86_64" ;;
    aarch64) LG_ARCH="arm64" ;;
    *) error "不支持的架构: $ARCH"; exit 1 ;;
  esac
  
  curl -Lo lazygit.tar.gz "https://github.com/jesseduffield/lazygit/releases/download/v${LAZYGIT_VERSION}/lazygit_${LAZYGIT_VERSION}_Linux_${LG_ARCH}.tar.gz"
  tar xf lazygit.tar.gz lazygit
  sudo install lazygit /usr/local/bin
  rm -f lazygit lazygit.tar.gz
fi

### ========================================
### 7. Shell (Oh-My-Zsh + Starship)
### ========================================
log "💻 7. 配置 Shell 环境..."

# 安装 OMZ
if [ ! -d "$HOME/.oh-my-zsh" ]; then
  info "安装 Oh-My-Zsh..."
  # --unattended: 不自动进入 zsh
  # --keep-zshrc: 如果你已经有配置文件，不覆盖
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended --keep-zshrc
fi

# 安装 fzf
if [ ! -d "$HOME/.fzf" ]; then
  info "安装 FZF (命令行模糊搜索)..."
  git clone --depth 1 https://github.com/junegunn/fzf.git "$HOME/.fzf"
  # --all: 自动启用 key-bindings (Ctrl+R/T) 和 fuzzy-completion
  # --no-bash/--no-fish: 我们只配 zsh，不让它乱改其他 shell
  "$HOME/.fzf/install" --all 
else
  info "FZF 已安装，跳过."
fi

ZSHRC="$HOME/.zshrc"

# # 3.1 禁用 OMZ 主题 (让位给 Starship)
# # 我们用 sed 查找并替换 ZSH_THEME="..." 为 ZSH_THEME=""
# if grep -q 'ZSH_THEME=' "$ZSHRC"; then
#   sed -i 's/^ZSH_THEME=".*"/ZSH_THEME=""/' "$ZSHRC"
# fi

# A. 备份现有的 .zshrc (里面有 Conda 和 FZF 的配置，不能丢！)
if [ -f "$ZSHRC" ]; then
  cp "$ZSHRC" "$ZSHRC.pre-bootstrap"
  info "已备份现有配置到 .zshrc.pre-bootstrap"
fi

# B. 获取 OMZ 官方模板 (作为地基)
# 我们把模板下载下来，追加到现有的 .zshrc 后面，这样既保留了 Conda/FZF，又有了 OMZ 的功能
if [ ! -f "$HOME/.oh-my-zsh/templates/zshrc.zsh-template" ]; then
    # 万一模板没下载下来，手动抓取
    curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/templates/zshrc.zsh-template > temp_zshrc
else
    cp "$HOME/.oh-my-zsh/templates/zshrc.zsh-template" temp_zshrc
fi

# C. 合并配置 (关键一步！)
# 1. 保留 Conda/FZF (在文件头部)
# 2. 插入 OMZ 模板 (在中间)
# 3. 插入我们自定义的 PATH 和 Tool (在底部)

# 读取现有内容 (Conda + FZF)
CURRENT_CONTENT=$(cat "$ZSHRC")

# 覆写 .zshrc：先放 OMZ 模板，再放 原内容
cat temp_zshrc > "$ZSHRC"
echo "" >> "$ZSHRC"
echo "$CURRENT_CONTENT" >> "$ZSHRC"
rm temp_zshrc

# D. 修改配置 (现在里面有东西了，可以改了)

# 1. 禁用 OMZ 主题 (让 Starship 接管)
# 使用 sed 将 ZSH_THEME="robbyrussell" 替换为 ZSH_THEME=""
sed -i 's/^ZSH_THEME=".*"/ZSH_THEME=""/' "$ZSHRC"

# 2. 启用常用插件 (git, extract, sudo)
# 这是 OMZ 的精华，必须开
sed -i 's/^plugins=(git)/plugins=(git git-extras debian tmux screen history extract colorize web-search docker sudo)/' "$ZSHRC"

# 3. 注入环境变量 (把之前漏在 bashrc 里的补回来)
cat <<EOT >> "$ZSHRC"

# --- Bootstrap Generated Config (PATHs & Tools) ---

# 1. PATH 补全 (Rust, Node, Bob, Local Bin)
# 注意：Miniconda 已经在文件头部配好了，这里不需要重复
export PATH="\$HOME/.local/bin:\$HOME/.cargo/bin:\$HOME/.local/share/bob/nvim-bin:\$HOME/.local/share/pnpm:\$PATH"

. "\$HOME/.cargo/env"

# 2. 工具启动
eval "\$(atuin init zsh)"     # 启动 atuin (需要在 fzf 初始化之后)
eval "\$(starship init zsh)"  # 启动 Starship
eval "\$(zoxide init zsh)"    # 启动 Zoxide (z 命令)

# 3. 别名 (Aliases)
alias cat='bat'
alias ls='eza --icons'                        # 基础 ls 变彩色+图标
alias ll='eza -lah --icons --git '            # ll 显示详情、Git状态、隐藏文件
alias lt='eza -lah --tree --level=2 --icons'  # lt 显示目录树(2层)
alias vi='nvim'
alias vim='nvim'
alias zj='zellij'
alias ra='ranger' # 如果装了 ranger

# 4. NVM
export NVM_DIR="\$HOME/.nvm"
[ -s "\$NVM_DIR/nvm.sh" ] && . "\$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "\$NVM_DIR/bash_completion" ] && \. "\$NVM_DIR/bash_completion"  # This loads nvm bash_completion

# 5. pnpm
export PNPM_HOME="\$HOME/.local/share/pnpm"
case ":\$PATH:" in
  *":\$PNPM_HOME:"*) ;;
  *) export PATH="\$PNPM_HOME:\$PATH" ;;
esac
# pnpm end

EOT

# 1. 删掉顶部的那行 FZF 配置 (使用 sed)
#sed -i '/\[ -f ~\/.fzf.zsh \] && source ~\/.fzf.zsh/d' "$ZSHRC"
# 2. 把它追加到文件最末尾
#echo '[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh' >> "$ZSHRC"

# 修改系统shell
chsh -s $(which zsh)

log "✅ .zshrc 修复完成！(Conda + FZF + OMZ + Tools 全部合体)"
log "👉 现在输入 'zsh' 进入新环境吧！"

# 安装 ohmytmux
curl -fsSL "https://github.com/gpakosz/.tmux/raw/refs/heads/master/install.sh#$(date +%s)" | bash

# 安装docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

5.1 关于`yt-dlp`

# 建议使用default安装
# 直接`uv tool install yt-dlp --with curl_cffi --with pycryptodomex --upgrade --force`会导致curl_cffi变成最新版
# 但yt-dlp可能不支持这么高版本的curl_cffi，而default的extra会自动补齐requests、urllib3、websockets、mutagen、brotli、pycryptodomex
uv tool install 'yt-dlp[default,curl-cffi]' --upgrade --force

# 记得装ffmpeg和nvm node，配置node变量
mkdir -p ~/.config/yt-dlp && cat <<EOF >> ~/.config/yt-dlp/config
--js-runtimes node
--remote-components ejs:github
EOF

arm设备可能会遇到curl_cffi安装了也没有伪装的问题，转回x86平台吧，暂时无解，像这样：

yt-dlp --list-impersonate-targets
[info] Available impersonate targets
Client    OS   Source
--------------------------------------------
Tor       -    curl_cffi>=0.11 (unavailable)
Edge      -    curl_cffi (unavailable)
Firefox   -    curl_cffi>=0.10 (unavailable)
Safari    -    curl_cffi (unavailable)
Chrome    -    curl_cffi (unavailable)

5.2 关于恢复备份的.ssh文件夹

拷过去权限得改对

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub
# 如果有
chmod 600 ~/.ssh/config

5.3 关于nomachine

安装时如果遇到60%卡住终端没响应，关掉重开一个终端修复一下安装即可，其实是已经装好，之是post install脚本可能有问题挂起了：

sudo killall apt apt-get dpkg
sudo dpkg --configure -a

arm上有时会遇到wayland桌面环境nomachine连上是黑底各种乱七八糟的竖条纹的情况，改回x11就会好：

sudo vim /etc/gdm3/custom.conf
WaylandEnable=false

重启gdm3，或直接重启系统更稳妥。

5.4 关于中文环境，上面装了字体和中文编码，需要配置语言环境：

sudo dpkg-reconfigure locales

选zh_CN.UTF-8 UTF-8即可，echo $LANG还不行的话：

echo "export LANGUAGE=zh_CN.zh" >> ~/.bashrc
echo "export LC_ALL=zh_CN.UTF-8" >> ~/.bashrc
echo "export LANG=zh_CN.UTF-8" >> ~/.bashrc
echo "export LANGUAGE=zh_CN.zh" >> ~/.zshrc
echo "export LC_ALL=zh_CN.UTF-8" >> ~/.zshrc
echo "export LANG=zh_CN.UTF-8" >> ~/.zshrc

关于输入法，就用 Fcitx5 默认，省事：

# 安装 Fcitx5 核心、中文拼音插件及图形化配置工具
sudo apt update
sudo apt install fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk3 fcitx5-frontend-gtk2 fcitx5-frontend-qt5 kde-config-fcitx5 fcitx5-config-qt

# 将环境变量写入 ~/.xprofile 或 /etc/profile
echo 'export GTK_IM_MODULE=fcitx' >> ~/.xprofile
echo 'export QT_IM_MODULE=fcitx' >> ~/.xprofile
echo 'export XMODIFIERS=@im=fcitx' >> ~/.xprofile

运行im-config，选择fcitx5，重启，右上角出现 Fcitx5 的小键盘图标，右键点击选择 配置 (Configure)，在右侧列表中找到 拼音 (Pinyin) 并添加到左侧。

现在使用topgrade自动感知并更新安装工具。

5.5 关于starship

配置文件可以改好看点：

cat > ~/.config/starship.toml << 'EOF'
# ==========================
# 1. 机器身份识别 (防错核心)
# ==========================
[hostname]
ssh_only = false    # 即使是本地终端也显示主机名
format = '在 [$hostname]($style) '
style = "bold purple" # 建议：不同机器改成不同颜色，比如测试板用红色，生产环境用紫色

# IP 显示 (仅限 SSH)
[localip]
ssh_only = true     # 性能优化：只有在你通过 SSH 连入时才去查 IP，本地直连时不查
disabled = false
format = '🌐 [$localipv4]($style) '
style = "bold blue"

# ==========================
# 2. 资源报警 (阈值触发，零延迟感知)
# ==========================
# 内存使用率
[memory_usage]
disabled = false
threshold = 80      # 性能优化：内存占用没超过 80% 时完全不渲染此模块，节省算力
format = '🐏 [$ram]($style) '
style = "bold red"

# ==========================
# 3. 运维排障辅助
# ==========================
# 命令执行耗时 (仅当命令执行超过 2 秒时显示)
[cmd_duration]
min_time = 2000
format = '耗时 [$duration]($style) '
style = "bold yellow"

# 退出码状态 (命令报错时变红)
[status]
disabled = false
format = '[$symbol$status]($style) '
success_symbol = "🟢 "
symbol = "🔴 "
style = "bold red"
EOF

6 tailscale 与 ipv6

节后移动给的GPON坏了，运营商换了一个后发现有ipv6了。家里的rock5b、PVE工作站都可以用ipv6直连了。

PVE装tailscale

需要注意的是，PVE默认没打开ipv6支持，所以需要手动设置：

vi /etc/sysctl.conf 

net.ipv6.conf.all.disable_ipv6 = 0
net.ipv6.conf.default.disable_ipv6 = 0
net.ipv6.conf.lo.disable_ipv6 = 0

net.ipv6.conf.all.forwarding = 1

vi /etc/sysctl.d/99-tailscale.conf
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
# 或：
echo 'net.ipv4.ip_forward = 1' | tee -a /etc/sysctl.d/99-tailscale.conf
echo 'net.ipv6.conf.all.forwarding = 1' | tee -a /etc/sysctl.d/99-tailscale.conf

# 应用网络配置
ifreload -a

此时用ip -6 addr show会发现vmbr0上多出来一个2409（移动）开头的地址，再用手机等公网设备打开tailscale去ping这台PVE就会从relay转到direct了。

5: vmbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 state UP qlen 1000
    inet6 2409:xxxx:xxx:xxxx:xxxx:xxxx:xxxx:xxxx/64 scope global dynamic mngtmpaddr proto kernel_ra 
       valid_lft 86181sec preferred_lft 14181sec

全家搬到tailscale

通过rock5b转发流量，可以把家里的192.168.1.x/24都放在tailscale上。在rock5b上配置系统转发：

echo 'net.ipv4.ip_forward = 1' | sudo tee -a /etc/sysctl.conf
echo 'net.ipv6.conf.all.forwarding = 1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

sudo tailscale up --advertise-routes=192.168.1.0/24 --accept-dns=false

出于安全考虑，被“广播”的网段 Tailscale 默认不信任，需要手动确认：

登录 Tailscale Admin Console。
Rock 5B 点击右侧的 三个点 (...)。
选择 Edit route settings。
在弹出的窗口中，勾选广播的网段 192.168.1.0/24。
点击 Save。

此时，手机用运营商的网，打开tailscale，也可以使用192.168.1.0/24的IP控制家里的设备了。

6.1 tailscale可能存在的坑1 - 外带设备o6n回家后只能单向ping

6.1.1 现象

在家里的局域网 (192.168.1.0/24) 有：

开发板 A (o6n): 192.168.1.140
开发板 B (Rock5B): 192.168.1.120
Windows 11 (含 WSL2): 192.168.1.125

症状： 开发板 A (140) 可以正常 Ping 通局域网内的 B (120) 和 Windows (125)，但是 B 和 Windows 无法 Ping 通 A。呈现典型的 “单向失联” 状态。

6.1.2 排查

遇到单向不通，通常的排查链路是：物理连接 -> 防火墙 -> ARP 解析 -> 路由表。

排除防火墙与物理隔离： 检查了 ufw 和 iptables，未发现拦截规则。
检查 ARP 缓存 (ip neigh show)： 开发板 A 上能成功获取到 B 和 Windows 的 MAC 地址，说明物理层和数据链路层通信正常。
排查代理软件： 怀疑是 Windows 端的 Clash TUN 模式劫持了局域网流量。关闭 TUN 模式并使用 ping -S 192.168.1.125 192.168.1.140 强制指定源 IP，依然不通，排除发件端代理问题。
定位核心问题——策略路由 (ip rule)： 在开发板 A (140) 上执行 ip rule 发现异常：
```
5270:   from all lookup 52
32766:  from all lookup main
```
执行 ip route show table 52 发现：
```
192.168.1.0/24 dev tailscale0
```

6.1.3 原因

网络中存在另一台设备——开发板 B (Rock5B, 192.168.1.120) 通过 Tailscale 执行了 --advertise-routes=192.168.1.0/24，广播了该局域网的 Subnet Route（子网路由），而开发板 A (140) 默认接受了该路由。

Tailscale 会接管系统的策略路由，创建一个高优先级（5270）的路由表 52。当开发板 A (140) 收到局域网（比如来自 Windows 或 Rock5B 本身）发来的 Ping 请求时，它需要发送 ICMP Echo Reply（回包）。在查找路由时，它优先命中了表 52 的规则，导致本该通过物理网卡（wlan0/eth0）发回本地局域网的数据包，被错误地塞进了 Tailscale 的虚拟隧道 (tailscale0) 中，造成了“有去无回”的路由黑洞。

6.1.4 解决

由于既需要在家时局域网直连，又需要带开发板外出时能通过 Tailscale 访问家里的内网，直接关闭 accept-routes 并不符合需求。

最优解：基于源 IP 的智能分流 (Smart Routing) 在开发板 A (140) 上添加一条比 Tailscale 优先级更高（例如 2500）的策略路由规则：

sudo ip rule add from 192.168.1.140 to 192.168.1.0/24 priority 2500 lookup main

原理解析：

在家时： 开发板 A 分配到的物理 IP 是 192.168.1.140。当局域网设备 Ping 它时，它使用该 IP 作为源 IP 回包，精确命中此规则，流量直接走 main 表（物理网卡），瞬间连通。
外出时： 开发板 A 连接其他网络，物理 IP 改变（不再是 192.168.1.140）。该规则失效，系统继续往下匹配，命中 Tailscale 的表 52，从而实现正常的异地组网访问。

避坑尽量避免将家中的主路由网段设置为 192.168.1.0/24 或 192.168.0.0/24 这种极其常见的默认网段。如果携带开启了异地组网的设备去酒店或单位，一旦公共 Wi-Fi 也是这个网段，就会引发严重的子网冲突（Overlapping Subnets）。建议改成类似 10.88.99.0/24 的冷门私有网段。

6.1.5 进阶固化：使用 systemd 实现路由规则开机自启

为了在 Armbian/Debian 12 等现代 Linux 环境下一劳永逸地解决此问题，最稳妥的方案是创建一个标准的 systemd 服务，确保在网络和 Tailscale 均就绪后，自动注入我们的高优先级本地路由规则。

Step 1: 编写路由修复脚本

创建一个专门的 Shell 脚本，采用“先清理后添加”的逻辑，防止因网络服务重启导致规则重复堆叠。

sudo vim /usr/local/bin/fix-lan-route.sh

内容为：

#!/bin/bash
# 忽略报错删除可能存在的旧规则，避免重复
ip rule del from 192.168.1.140 to 192.168.1.0/24 priority 2500 lookup main 2>/dev/null

# 添加本地局域网高优先级规则
ip rule add from 192.168.1.140 to 192.168.1.0/24 priority 2500 lookup main

赋予执行权限：

sudo chmod +x /usr/local/bin/fix-lan-route.sh

Step 2: 编写 systemd 服务文件

配置服务依赖，确保脚本在网络连通 (network-online.target) 且 Tailscale 服务启动 (tailscaled.service) 之后再执行。

sudo vim /etc/systemd/system/fix-lan-route.service

内容为：

[Unit]
Description=Fix LAN routing conflict with Tailscale
After=network-online.target tailscaled.service
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/fix-lan-route.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Step 3: 激活服务并验证

重载 systemd 守护进程，并将该服务设为开机自启：

# 重载系统配置
sudo systemctl daemon-reload

# 设置为开机自启
sudo systemctl enable fix-lan-route.service

# 立即启动该服务进行验证
sudo systemctl start fix-lan-route.service

最终验证： 在终端执行 ip rule 命令。如果列表中清晰地出现了 2500: from 192.168.1.140 to 192.168.1.0/24 lookup main，即代表配置大功告成。从此，无论设备重启还是随时启停 Tailscale，本地局域网的通信策略都将稳如泰山。

6.2 tailscale可能存在的坑2 - 子网发布网关rock5b开启TUN导致tailscale无法链接

6.2.1 现象：

Clash开TUN以后，tailscale启动报错。

开启TUN时的异常日志：

➜  ~ sudo systemctl status tailscaled.service
● tailscaled.service - Tailscale node agent
     Loaded: loaded (/lib/systemd/system/tailscaled.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-03-28 10:00:48 CST; 28s ago
       Docs: https://tailscale.com/docs/
   Main PID: 578694 (tailscaled)
      Tasks: 15 (limit: 18526)
     Memory: 54.6M
        CPU: 878ms
     CGroup: /system.slice/tailscaled.service
             └─578694 /usr/sbin/tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/run/tailscale/tailscaled.sock --port=41641

Mar 28 10:00:48 rock-5b tailscaled[578694]: logpolicy: using $STATE_DIRECTORY, "/var/lib/tailscale"
Mar 28 10:00:48 rock-5b tailscaled[578694]: linkChange: in state NoState; PAC or proxyConfig changed; updating routes
Mar 28 10:00:48 rock-5b tailscaled[578694]: got LocalBackend in 56ms
Mar 28 10:00:48 rock-5b tailscaled[578694]: Start
Mar 28 10:00:48 rock-5b tailscaled[578694]: ipnext: active extensions: conn25, portlist, posture, clientupdate, relayserver, taildrop
Mar 28 10:00:48 rock-5b tailscaled[578694]: Backend: logs: be:de27a4d50030bb2fa9eba85172884903b5e6894feb434ee6ece1a4b0f407b618 fe:
Mar 28 10:00:48 rock-5b tailscaled[578694]: control: client.Login(0)
Mar 28 10:00:48 rock-5b tailscaled[578694]: health(warnable=warming-up): error: Tailscale is starting. Please wait.
Mar 28 10:00:48 rock-5b tailscaled[578694]: control: doLogin(regen=false, hasUrl=false)
Mar 28 10:00:53 rock-5b tailscaled[578694]: health(warnable=warming-up): ok

此时：

➜  ~ tailscale status
unexpected state: NoState

关闭tun后的正常日志：

➜  ~ sudo systemctl status tailscaled.service
● tailscaled.service - Tailscale node agent
     Loaded: loaded (/lib/systemd/system/tailscaled.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-03-28 10:01:28 CST; 3s ago
       Docs: https://tailscale.com/docs/
   Main PID: 579582 (tailscaled)
      Tasks: 15 (limit: 18526)
     Memory: 42.3M
        CPU: 708ms
     CGroup: /system.slice/tailscaled.service
             └─579582 /usr/sbin/tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/run/tailscale/tailscaled.sock --port=41641

Mar 28 10:01:31 rock-5b tailscaled[579582]: monitor: RTM_DELROUTE: src=198.18.0.1/0, dst=198.18.0.1/32, gw=, outif=16, table=255
Mar 28 10:01:31 rock-5b tailscaled[579582]: LinkChange: major, rebinding: old: interfaces.State{defaultRoute=enP4p65s0 ifs={Meta:[198.18.0.>
Mar 28 10:01:31 rock-5b tailscaled[579582]: dns: Set: {DefaultResolvers:[] Routes:{} SearchDomains:[] Hosts:6}
Mar 28 10:01:31 rock-5b tailscaled[579582]: dns: Resolvercfg: {Routes:{} Hosts:6 LocalDomains:[]}
Mar 28 10:01:31 rock-5b tailscaled[579582]: dns: OScfg: {}
Mar 28 10:01:31 rock-5b tailscaled[579582]: wgengine: set DNS config again after major link change
Mar 28 10:01:31 rock-5b tailscaled[579582]: router: portUpdate(port=41641, network=udp6)
Mar 28 10:01:31 rock-5b tailscaled[579582]: Rebind; defIf="enP4p65s0", ips=[192.168.1.120/24 2409:8a70:b61:b91::1005/128 2409:8a70:b61:b91:>
Mar 28 10:01:31 rock-5b tailscaled[579582]: magicsock: 0 active derp conns
Mar 28 10:01:31 rock-5b tailscaled[579582]: router: portUpdate(port=41641, network=udp4)

此时：

➜  ~ tailscale status
100.xx.xx.xx     rock-5b              xxx@  linux    -
100.xx.xx.xx     server               xxx@  linux    offline, last seen xxd ago
100.xx.xx.xx     phone1               xxx@  android  offline, last seen xxd ago
100.xx.xx.xx     orion-o6             xxx@  linux    offline, last seen xxh ago
100.xx.xx.xx     phone2               xxx@  android  offline, last seen xxh ago
100.xx.xx.xx     macbook-pro          xxx@  macOS    offline, last seen xxd ago

6.2.2 原因

简单来说，Clash 的 TUN 模式把 Tailscale 的建连流量给“劫持”了。

Clash TUN 的霸道机制：当开启 Clash TUN 模式时，它会在系统里建一个虚拟网卡（比如 Mihomo），并通过修改系统路由表（下发 0.0.0.0/1 这种默认路由）或者用 fwmark（防火墙标记）把机器上所有的流量都强行吸进自己的核心里。同时，它通常还会开启 Fake-IP 来劫持 DNS 请求（日志里关闭 TUN 时出现的 198.18.0.1 就是 Clash 的 Fake-IP 网段）。
Tailscale 的迷失：tailscaled 服务启动时，需要向它自己的控制面板（login.tailscale.com）和分布在全球的 DERP 中继服务器发送 UDP 握手包来建立状态。
死锁形成：开启 TUN 后，Tailscale 刚发出建连请求，就被 Clash 一把抓走。如果这些流量被 Clash 丢到了错误的代理节点，或者由于 Fake-IP 导致 Tailscale 拿不到中继服务器的真实 IP，它的握手包就永远发不出去，一直卡在 NoState 等待响应。

6.2.3 解决

思路很简单：给 Clash 设个规矩，让它对 Tailscale 相关的 IP、域名和进程“高抬贵手”，直接放行。

添加 Merge (合并) 路由规则

为了万无一失，我们需要让 Mihomo 核心彻底放行 tailscaled 进程和相关域名的流量。

将以下规则添加到直连规则（Direct）中，并且要放在规则列表的 最前面：

rules:
  # 直连 Tailscale 后台守护进程
  - PROCESS-NAME,tailscaled,DIRECT
  # 直连 Tailscale 的内网网段
  - IP-CIDR,100.64.0.0/10,DIRECT
  # 直连 Tailscale 的控制面域名
  - DOMAIN-SUFFIX,tailscale.com,DIRECT
  - DOMAIN-SUFFIX,tailscale.io,DIRECT

修复 Fake-IP 污染（关键）：如果 Clash 配置里开启了 Fake-IP，必须把 Tailscale 的域名加入 fake-ip-filter，否则它连不上中继。在配置（实际配置位于dns_config.yaml）中补充：

dns:
  fake-ip-filter:
    - '*.tailscale.com'
    - '*.tailscale.io'

应用这些设置并重启 Clash 的 TUN 开关后，Clash 就会把 Tailscale 的建连流量和 100.x.x.x 的内网流量原封不动地交还给系统路由表，两边就能和平共处了。

注：关于如何查找配置文件位置

在 Linux 中，要查看一个进程在启动时到底读取了哪些文件，最强大且标准的工具是 strace。它可以追踪进程调用的所有系统 API，包括打开文件的操作。

因为 clash-verge 是基于 Tauri 的应用，它会启动多个子进程（前端渲染、后端服务等），所以需要加上特定参数来追踪所有子进程，并过滤出跟配置文件相关的操作。

Step1: 进程追踪

安装 strace ，用 strace 运行组合命令并输出日志，将 strace 加在 clash 环境变量之后、 clash-verge 之前。为了防止终端输出被海量的系统调用淹没，把日志重定向到一个文本文件中：

sudo apt install strace

WEBKIT_DISABLE_COMPOSITING_MODE=1 WEBKIT_DISABLE_DMABUF_RENDERER=1 WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS=1 GDK_BACKEND=x11 strace -f -e trace=open,openat clash-verge 2> startup_trace.log

参数解释：

-f：告诉 strace 追踪所有由 clash-verge 派生出来的子进程（关键，因为配置通常是核心子进程读取的）。
-e trace=open,openat：只监听“打开文件”相关的系统调用，过滤掉网络、内存等无关操作。
2> startup_trace.log：将 strace 的标准错误输出（它的追踪日志默认输出到这里）保存到 startup_trace.log 文件中。

运行上面这条命令后，等终端停留在之前的状态（说明应用已经启动并转入后台监听），按 Ctrl + C 结束它。

Step2: 分析追踪日志

现在当前目录下生成了一个 startup_trace.log 文件。可以用 grep 过滤出所有常见的配置文件后缀（如 .yaml, .yml, .json）：

grep -i -E '\.yaml|\.yml|\.json' startup_trace.log | grep -v "ENOENT"

参数解释：

-i -E '\.yaml|\.yml|\.json'：忽略大小写，匹配这三种常见的配置文件格式。

grep -v "ENOENT"：过滤掉“文件不存在（Error No Entry）”的记录。程序在启动时通常会按照一定顺序去多个默认目录“试探性”地寻找配置文件，过滤掉找不到的记录，剩下的就是它真正成功读取到的文件路径:

➜  ~ grep -i -E '\.yaml|\.yml|\.json' startup_trace.log | grep -v "ENOENT"
[pid 568056] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/verge.yaml", O_RDONLY|O_CLOEXEC) = 19
[pid 568057] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/config.yaml", O_RDONLY|O_CLOEXEC) = 19
[pid 568057] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/verge.yaml", O_RDONLY|O_CLOEXEC) = 19
[pid 568056] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/profiles.yaml", O_RDONLY|O_CLOEXEC) = 19
[pid 568036] openat(AT_FDCWD, "/home/pi/.config/io.github.clash-verge-rev.clash-verge-rev/window_state.json", O_RDONLY|O_CLOEXEC) = 20
[pid 568057] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/profiles/RrCXXb9eVReP.yaml", O_RDONLY|O_CLOEXEC) = 30
[pid 568058] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/profiles/Merge.yaml", O_RDONLY|O_CLOEXEC <unfinished ...>
[pid 568058] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/dns_config.yaml", O_RDONLY|O_CLOEXEC) = 21
[pid 568057] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/clash-verge.yaml", O_WRONLY|O_CREAT|O_TRUNC|O_CLOEXEC, 0666) = 21
[pid 568058] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/clash-verge-check.yaml", O_WRONLY|O_CREAT|O_TRUNC|O_CLOEXEC, 0666) = 21
[pid 568095] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/clash-verge-check.yaml", O_RDONLY|O_CLOEXEC) = 3
[pid 568057] openat(AT_FDCWD, "/home/pi/.local/share/io.github.clash-verge-rev.clash-verge-rev/clash-verge.yaml", O_WRONLY|O_CREAT|O_TRUNC|O_CLOEXEC, 0666) = 21```

7 self host atuin

atuin 的主机间 sync 命令行历史记录非常有用，按照官方说明 Self Hosting - Docker Compose 用 Docker Compose 的方式可以很容易的拉起来一个私有服务。之后，在任意需要 atuin sync 的主机上，修改 atuin 的配置文件 ~/.config/atuin/config.toml：sync_address = "http://<server-ip:port>"即可。

将本地的shell命令导入 atuin 管理，运行atuin import auto或atuin import zsh。注：如果要 atuin 接管 ctrl-r，则要保证.zshrc中 atuin 在 fzf 之后初始化。

接下来，在第一台要同步的主机命令行里，运行首次用户注册：atuin register -u <username> -e <email>，此时 atuin 会让你运行atuin key拿到助记词，用来在之后的登录时使用。注册完毕后运行atuin sync向服务器同步历史记录。完成注册后，再在其他主机上只需要执行登录即可：atuin login -u <username>再输入助记词即可，成功后atuin sync。

此时ctrl-r打开 atuin ，多次按ctrl-r就会在全局、本机、本次会话、此目录等环境中切换。在全局环境，选中命令按ctrl-o进入检视页会看到此命令所属的主机。

最后设置系统服务，新建sudo vim /etc/systemd/system/atuin.service，把官方说明中systemd那段脚本贴进去，然后将WorkingDirectory换成刚才docker-compose.yml所在的绝对路径即可，再sudo systemctl daemon-reload、sudo systemctl enable --now atuin.service、sudo systemctl status atuin.service即可看到开机自启的 atuin 服务。

firefox esr apt安装说明

8 启用 rock 5b 的 pwm

风扇的pwm线插在pin 27上，sudo armbian-config进入TUI界面 -> System -> Kernel -> DTO01 - Manage device tree overlays -> 选 rk3588-pwm7-m3。或者在/boot/armbianEnv.txt里overlays后面续上字符串rk3588-pwm7-m3。

重启。

PWM 子系统的 pwmchipN 编号是按 probe 顺序生成的，每次启动可能不一样，必须看一下：

sudo cat /sys/kernel/debug/pwm
platform/febd0030.pwm, 1 PWM device
 pwm-0   ((null)              ): period: 0 ns duty: 0 ns polarity: normal

platform/fd8b0010.pwm, 1 PWM device
 pwm-0   (pwm-fan             ): requested period: 60000 ns duty: 0 ns polarity: normal

febd0030 这个地址就是 PWM7（RK3588 PWM7 寄存器基址）。然后看哪个 pwmchip 链接到它：

ls -l /sys/class/pwm/
lrwxrwxrwx - root 29 4月  18:51  pwmchip0 -> ../../devices/platform/fd8b0010.pwm/pwm/pwmchip0
lrwxrwxrwx - root 29 4月  18:51  pwmchip1 -> ../../devices/platform/febd0030.pwm/pwm/pwmchip1

记住这个pwmchip1

先写个脚本测试：

uv init pwm7-m3
cd pwm7-m3
uv add python-periphery

写一个python脚本 fan_pwm.py 测试：

"""Hardware PWM fan control on Rock 5B PIN_27 (GPIO4_C6 / PWM7_IR_M3).

需先启用 rk3588-pwm7-m3 overlay 并重启。
通过 /sys/kernel/debug/pwm 找到 febd0030.pwm 对应的 pwmchip 号。
"""

import signal
import sys
import time

from periphery import PWM

# === 改成你机器上实际看到的 pwmchip 号 ===
PWM_CHIP = 1          # pwmchipN 中的 N
PWM_CHANNEL = 0       # Rockchip 每个 chip 只有一个 channel，固定为 0
# =====================================

FREQ_HZ = 25000       # 4 线 PC 风扇标准 PWM 频率
DUTY = 0.30           # 30% 占空比


def main() -> None:
    pwm = PWM(PWM_CHIP, PWM_CHANNEL)
    try:
        pwm.frequency = FREQ_HZ        # 25 kHz
        pwm.duty_cycle = DUTY          # 0.0 ~ 1.0
        pwm.polarity = "normal"
        pwm.enable()

        print(f"PWM7 on PIN_27: {DUTY * 100:.0f}% @ {FREQ_HZ} Hz "
              f"(pwmchip{PWM_CHIP})")
        print("Ctrl+C 退出")

        def shutdown(_sig, _frame):
            print("\n停止 PWM...")
            pwm.disable()
            pwm.close()
            sys.exit(0)

        signal.signal(signal.SIGINT, shutdown)
        signal.signal(signal.SIGTERM, shutdown)

        while True:
            time.sleep(1)
    except Exception:
        pwm.close()
        raise


if __name__ == "__main__":
    main()

运行脚本测试 sudo $(which uv) run python fan_pwm.py，此时风扇应该降速了。

成功后封装为系统服务，服务运行时不能依赖家目录（特别是如果以 root 跑），放到 /opt：

sudo mv ~/pwm7-m3 /opt/pwm7-m3
sudo chown -R root:root /opt/pwm7-m3
cd /opt/pwm7-m3

确认依赖装好（uv 会在 /opt/pwm7-m3/.venv 建虚拟环境）：

sudo $(which uv) sync

记下 uv 的绝对路径，service 里要用：

which uv
/home/radxa/.local/bin/uv

由于 uv 装在家目录下（~/.local/bin/uv），root 跑服务时找不到，把 uv 放到系统路径：

sudo cp ~/.local/bin/uv /usr/local/bin/uv

微调一下脚本，让它对 SIGTERM（systemd stop 发的信号）也能干净退出，并且把输出冲到日志里（journald 会自动收）：

"""Hardware PWM fan control on Rock 5B PIN_27 (PWM7_IR_M3)."""

import signal
import sys
import time

from periphery import PWM

PWM_CHIP = 1          # 改成你机器上 febd0030.pwm 对应的 pwmchipN
PWM_CHANNEL = 0
FREQ_HZ = 25000
DUTY = 0.30


def main() -> None:
    pwm = PWM(PWM_CHIP, PWM_CHANNEL)
    pwm.frequency = FREQ_HZ
    pwm.duty_cycle = DUTY
    pwm.polarity = "normal"
    pwm.enable()

    print(f"pwm7-m3: {DUTY * 100:.0f}% @ {FREQ_HZ} Hz on pwmchip{PWM_CHIP}",
          flush=True)

    stopping = False

    def shutdown(_sig, _frame):
        nonlocal stopping
        stopping = True

    signal.signal(signal.SIGINT, shutdown)
    signal.signal(signal.SIGTERM, shutdown)

    try:
        while not stopping:
            time.sleep(1)
    finally:
        print("pwm7-m3: stopping", flush=True)
        try:
            pwm.disable()
        finally:
            pwm.close()


if __name__ == "__main__":
    sys.exit(main())

flush=True 是为了让 print 立刻被 systemd 抓到日志里，不然 Python 默认会做行缓冲/块缓冲，停服务前可能看不到输出。

创建 systemd service 文件：

sudo vim /etc/systemd/system/pwm7-m3.service

[Unit]
Description=Rock 5B PWM fan control (PIN_27 / PWM7)
After=multi-user.target

[Service]
Type=simple
WorkingDirectory=/opt/fan-pwm
ExecStart=/usr/local/bin/uv run python fan_pwm.py
Restart=on-failure
RestartSec=3
User=root
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

几个要点：

Type=simple：脚本本身就是常驻进程，不 fork，所以 simple 即可。
ExecStart 里 uv 必须用绝对路径——systemd 不读的 shell PATH。
WorkingDirectory 让 uv 找得到项目里的 pyproject.toml 和 .venv。
Restart=on-failure：脚本异常退出就重启，但 systemctl stop 主动停的时候不会重启。
User=root：因为 PWM sysfs 默认只有 root 能写。

启用 + 启动，enable --now 等于 enable（开机自启）+ start（立刻启动）一起做。

sudo systemctl daemon-reload
sudo systemctl enable --now pwm7-m3.service

常用操作：

# 看状态
sudo systemctl status pwm7-m3

# 看实时日志
sudo journalctl -u pwm7-m3 -f

# 停止 / 重启
sudo systemctl stop pwm7-m3
sudo systemctl restart pwm7-m3

# 改完占空比想生效，重启服务即可
sudo systemctl restart pwm7-m3

# 不要开机自启了
sudo systemctl disable pwm7-m3

成功后也可以把脚本改成自动控温的模式：

"""Temperature-based PWM fan control for Rock 5B (PIN_27 / PWM7_IR_M3)."""

import signal
import sys
import time

from periphery import PWM

# === 硬件配置 ===
PWM_CHIP = 1          # febd0030.pwm 对应的 pwmchipN
PWM_CHANNEL = 0
FREQ_HZ = 25000
THERMAL_ZONE = "/sys/class/thermal/thermal_zone0/temp"  # CPU 温度
POLL_INTERVAL = 3.0   # 秒，温度采样间隔

# === 风扇曲线 ===
# (温度 °C, 占空比 0.0~1.0)
# 大风扇没必要跑全速，最高也就 60%
FAN_CURVE = [
    (45.0, 0.30),   # 45°C 以下30%
    (50.0, 0.35),   # 起转点
    (60.0, 0.40),
    (70.0, 0.45),
    (80.0, 0.60),   # 80°C 以上也只到 60%
]

# 滞回，避免在阈值附近反复启停
HYSTERESIS_C = 2.0

# 起转辅助：从 0% 跳到目标值时，先全力踹一下让风扇转起来
KICKSTART_DUTY = 0.50
KICKSTART_SEC = 1.0


def read_temp_c() -> float:
    with open(THERMAL_ZONE) as f:
        return int(f.read().strip()) / 1000.0


def duty_for_temp(temp_c: float, curve: list[tuple[float, float]]) -> float:
    """在曲线上做线性插值。"""
    if temp_c <= curve[0][0]:
        return curve[0][1]
    if temp_c >= curve[-1][0]:
        return curve[-1][1]
    for (t0, d0), (t1, d1) in zip(curve, curve[1:]):
        if t0 <= temp_c <= t1:
            ratio = (temp_c - t0) / (t1 - t0)
            return d0 + (d1 - d0) * ratio
    return curve[-1][1]


def main() -> int:
    pwm = PWM(PWM_CHIP, PWM_CHANNEL)
    pwm.frequency = FREQ_HZ
    pwm.duty_cycle = 0.0
    pwm.polarity = "normal"
    pwm.enable()

    print(f"fan-pwm: started, curve={FAN_CURVE}", flush=True)

    stopping = False

    def shutdown(_sig, _frame):
        nonlocal stopping
        stopping = True

    signal.signal(signal.SIGINT, shutdown)
    signal.signal(signal.SIGTERM, shutdown)

    last_temp = read_temp_c()
    current_duty = 0.0

    try:
        while not stopping:
            temp = read_temp_c()

            # 滞回：温度变化小于 HYSTERESIS_C 时不动
            if abs(temp - last_temp) < HYSTERESIS_C:
                target = current_duty
            else:
                target = duty_for_temp(temp, FAN_CURVE)
                last_temp = temp

            if target != current_duty:
                # 从停转到要起转 → 先 kickstart
                if current_duty == 0.0 and target > 0.0:
                    pwm.duty_cycle = max(target, KICKSTART_DUTY)
                    print(f"fan-pwm: {temp:.1f}°C  kickstart "
                          f"-> {pwm.duty_cycle * 100:.0f}%", flush=True)
                    time.sleep(KICKSTART_SEC)

                pwm.duty_cycle = target
                current_duty = target
                print(f"fan-pwm: {temp:.1f}°C  duty -> {target * 100:.0f}%",
                      flush=True)

            time.sleep(POLL_INTERVAL)
    finally:
        print("fan-pwm: stopping", flush=True)
        try:
            pwm.duty_cycle = 0.0
            pwm.disable()
        finally:
            pwm.close()
    return 0


if __name__ == "__main__":
    sys.exit(main())

学习Widevine服务

Fri, 01 Mar 2024 18:24:00 GMT

我不理解，为什么像Netflix、Spotify流媒体服务提供商，包括苹果、谷歌等公司，会使用数字版权管理。他们在我买的设备上，浪费我的硬件算力，加密我买的数字内容，以阻止我下载。君子也防？[doge]

本文尝试欺骗DRM License Server获取秘钥，来解密被DRM加密的多媒体内容。

了解Google Widevine

通过阅读文章大致了解了widevine的工作原理，以及DRM（Digital Rights Management，数字版权管理）系统的执行过程：

获取CDM Device验证文件

CDM（内容解密模块）是嵌入在Chrome浏览器或Android操作系统中用来加解密流媒体的闭源模块。因此，我们可以模拟一个安卓设备。

使用pywidevine创建CDM Device。创建设备需要两个关键文件，client_id.bin和private_key.pem。

按照帖子Dumping Your own L3 CDM with Android Studio的操作，下载并安装Android Studio，再使用frida-server获取关键文件。
在Android Studio的Device Manager中新建设备，选一台更帖子描述一样的设备，Pixel 6、Pie，生成了Pixel 6 API 28设备，启动后显示emulator-5554。（我的Andriod Studio装好时，Device Manager中已经有了一部虚拟手机Pixel_3A_API_34_extension_level_7_x86_64（注意这是一台x86_64的设备），这个设备浏览器解析CDM时貌似有问题）
在Windows下的conda中新开一个环境安装pip install frida frida-tools，并确定frida版本（我使用了16.2.1），frida与frida-server版本需一致。
将下载的frida-server-16.2.1-android-x86放到C:\Users\<YourUserName>\AppData\Local\Android\Sdk\platform-tools\目录中，命令行进入该目录，执行：

> .\adb.exe devices
List of devices attached
emulator-5554   device

可以看到虚拟设备已被识别。

将frida-server上传到虚拟设备：

> .\adb.exe push .\frida-server-16.2.1-android-x86 /sdcard
.\frida-server-16.2.1-android-x86: 1 file pushed, 0 skipped. 152.8 MB/s (51807740 bytes in 0.323s)

连接虚拟设备，将frida-server放在正确的位置，赋予执行权限并启动：

> .\adb.exe shell
su
mv /sdcard/frida-server-16.2.1-android-x86 /data/local/tmp/
chmod +x /data/local/tmp/frida-server-16.2.1-android-x86
/data/local/tmp/frida-server-16.2.1-android-x86

此时server启动，保持终端运行。

下载dumper，进入目录并安装依赖pip install -r requirements.txt。

运行时报错提示：

python .\dump_keys.py
Traceback (most recent call last):
  File "C:\Users\qinzi\pyws\wdevof\dumper\dump_keys.py", line 6, in <module>
    from Helpers.Scanner import Scan
  File "C:\Users\qinzi\pyws\wdevof\dumper\Helpers\Scanner.py", line 7, in <module>
    from Helpers.wv_proto2_pb2 import SignedLicenseRequest
  File "C:\Users\qinzi\pyws\wdevof\dumper\Helpers\wv_proto2_pb2.py", line 33, in <module>
    _descriptor.EnumValueDescriptor(
  File "C:\Users\qinzi\anaconda3\envs\wdev\Lib\site-packages\google\protobuf\descriptor.py", line 789, in __new__
    _message.Message._CheckCalledFromGeneratedFile()
TypeError: Descriptors cannot be created directly.
If this call came from a _pb2.py file, your generated code is out of date and must be regenerated with protoc >= 3.19.0.
If you cannot immediately regenerate your protos, some other possible workarounds are:
 1. Downgrade the protobuf package to 3.20.x or lower.
 2. Set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python (but this will use pure-Python parsing and will be much slower).

因此安装建议为PowerShell添加环境变量，再次运行python .\dump_keys.py即可：

> $env:PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION = 'python'
> $env:PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION
python

> python .\dump_keys.py
2024-03-02 12:22:36 PM - root - 16 - INFO - Connected to Android Emulator 5554
2024-03-02 12:22:36 PM - root - 17 - INFO - scanning all processes for the following libraries
...
2024-03-02 02:17:06 PM - Helpers.Scanner - 82 - INFO - Running libwvhidl.so at 0xec717000
2024-03-02 02:17:06 PM - Helpers.Scanner - 75 - DEBUG - {
    "from": "Dynamic Function",
    "message": "L3 RSA Key export function found: cwkfcplc"
}
...
2024-03-02 12:22:37 PM - root - 25 - INFO - Hooks completed

此时dumper启动，保持终端运行。

创建CDM设备

此时可以使用client_id.bin和private_key.pem，通过pywidevine命令行工具来生成wvd设备文件了：

pywidevine create-device -k ./private_key.pem -c ./client_id.bin -t "ANDROID" -l 3

得到一个名为google_aosp_on_ia_emulator_14.0.0_67016d30_4464_l3.wvd的设备文件。

获取秘钥

使用pywidevine的例程即可获取秘钥：

pssh在希望下载的视频描述文件中，可能是浏览器请求的一个https://a.com/b/c.mpdxml文件或是一个https://a.com/b/c.m3u8list文件。
device的路径即为刚才创建的设备文件路径。
licence请求的地址，是浏览器加载视频时发出的一次或两次（aduio和video各一次）秘钥请求，URL特征应当非常明显，通常为POST方式，带有二进制负载。

另外需要注意的是，CDM秘钥的请求原理上是独立于媒体提供平台的，或是与媒体服务API不同的一套API，因此要使得licence请求成功，可能还需要从浏览器中复制秘钥请求headers一并加入requests.post（如使用浏览器复制为cURL (bash)）。

from pywidevine.cdm import Cdm
from pywidevine.device import Device
from pywidevine.pssh import PSSH

import requests

# prepare pssh
pssh = PSSH("AAAAW3Bzc2gAAAAA7e+LqXnWSs6jyCfc1R0h7QAAADsIARIQ62dqu8s0Xpa"
            "7z2FmMPGj2hoNd2lkZXZpbmVfdGVzdCIQZmtqM2xqYVNkZmFsa3IzaioCSEQyAA==")

# load device
device = Device.load("C:/Path/To/A/Provision.wvd")

# load cdm
cdm = Cdm.from_device(device)

# open cdm session
session_id = cdm.open()

# get license challenge
challenge = cdm.get_license_challenge(session_id, pssh)

# send license challenge (assuming a generic license server SDK with no API front)
licence = requests.post("https://...", data=challenge)
licence.raise_for_status()

# parse license challenge
cdm.parse_license(session_id, licence.content)

# print keys
for key in cdm.get_keys(session_id):
    print(f"[{key.type}] {key.kid.hex}:{key.key.hex()}")

# close session, disposes of session data
cdm.close(session_id)

请求成功后会打印SIGNING和CONTENT，这个CONTENT就是我们需要用来解密音视频的秘钥对kid:key，我的请求输出大致格式为：

[SIGNING] <32bit-hex>:<128bit-hex>
[CONTENT] <32bit-hex-kid>:<32bit-hex-key>

解密多媒体文件

解密工具有现成的，比如mp4decrypt、shaka，我用的是mp4decrypt，使用刚才拿到的`kid:key。

mp4decrypt --key <kid>:<key> my_encrypted_file.mp4 my_decrypted_file.mp4

也可以直接使用支持DRM解密的下载工具，如使用rust编写的dash-mpd-cli，只需要在参数中指定解密工具和秘钥即可：

dash-mpd-cli https://url_of_.mpd_file.mpd --output my_decrypted_file.mp4
  -H cURL_format_headers
  -H ...
  --decryption-application mp4decrypt \
  --mp4decrypt-location /home/wsl/devof/Bento4/cmakebuild/mp4decrypt \
  --key d2afe67c226cf2e932ac9b4c0c13432d:c5cf130ddf1087ca2f134725e82f1c1e

理解Transformer模型2：训练Transformer

Sat, 13 Jan 2024 18:20:00 GMT

接着上一篇文章，任务目标依然是通过使用Transformer将英语翻译为意大利语，来理解Transformer是如何编写和训练的，同时本文还将通过可视化观察注意力模型的细节。文中将使用Hugging Face的opus_books作为训练集，通过Hugging Face的工具链完成数据集的下载，和将文本转换为词表的工作。

1 Tokenizer

观察数据集，可以发现Hugging Face提供的数据都是成对出现的原文（英语）-译文（意大利语）字典。第一步是下载数据集，并创建tokenizer（也译为分词）。

<br>

Tokenizer在Input Embedding的输入之前，用于将句子拆分成token从而构建词表（其中还将包括用于让模型识别的特殊token，如用于padding的、用于标识句子起止位置的等等），tokenizer的种类有很多，如BPE tokenizer（按频度统计分出词根）、Word tokenizer（按空格和标点分词）、Subword tokenizer（高频词不分，低频词分出有意义的subword或词根）。本文以教学为目标，因此选择使用最简单的Word tokenizer。

新建文件train.py用于训练模型。

安装Hugging Face的datasets和tokenizer库用于下载数据集和调用分词器（pip和conda都可以）。

编写函数用于创建分词器：

import torch
import torch.nn as nn
from torch.utils.data import Dataset, DataLoader, random_split

from datasets import load_dataset
from tokenizers import Tokenizer

from tokenizers.models import WordLevel
from tokenizers.trainers import WordLevelTrainer # tokenizer相对应的trainer，通过给定的句子创建词表
from tokenizers.pre_tokenizers import Whitespace # 按空格分词

from pathlib import Path


def get_or_build_tokenizer(config, ds, lang):
    """
    创建分词器
    
    参数: 
        `config`: 模型的配置
        `ds`: 数据集
        `lang`: 分词器的语言
    返回: 
        `Tokenizer`分词器实例
    """
    # config['tokenizer_file'] = '../tokenizer/tokenizer_{0}.json'
    tokenizer_path = Path(config['tokenizer_file'].format(lang))
    if not Path.exists(tokenizer_path):
        tokenizer = Tokenizer(WordLevel(unk_token='[UNK]')) # 分词器在遇到不在词表中的词时将其替换为`[UNK]`
        tokenizer.pre_tokenizer = Whitespace()
        trainer = WordLevelTrainer(special_tokens=["[UNK]", "[PAD]", "[SOS]", "[EOS]"], min_frequency=2) # 一个词要出现在词表中，需要至少在句子中出现两次
        tokenizer.train_from_iterator(get_all_sentences(ds, lang), trainer=trainer)
    else:
        tokenizer = Tokenizer.from_file(str(tokenizer_path))
    
    return tokenizer

以及从数据集中生成句子的工具函数：

def get_all_sentences(ds, lang):
    """
    从数据集中取指定语言的句子

    参数: 
        `ds`: 数据集
        `lang`: 指定语言 `"en"`或`"it"`
    """
    for item in ds:
        yield item['translation'][lang]

在Hugging Face中下载数据集：

def get_ds(config):
    """
    加载数据集并创建分词器
    """
    # 在Hugging Face中下载opus_books数据集中的`en-it`子集，选择`train`部分，我们之后将自行再分出validation部分
    ds_raw = load_dataset('opus_books', f'{config["lang_src"]}-{config["lang_tgt"]}', split='train')

    # 创建分词器
    tokenizer_src = get_or_build_tokenizer(config, ds_raw, config['lang_src'])
    tokenizer_tgt = get_or_build_tokenizer(config, ds_raw, config['lang_tgt'])

    # 将数据集分为90%的训练集和10%的验证集
    train_ds_size = int(0.9 * len(ds_raw))
    val_ds_size = len(ds_raw) - train_ds_size
    train_ds_raw, val_ds_raw = random_split(ds_raw, [train_ds_size, val_ds_size])

此时需要处理数据集训练模型，我们先编写dataset.py为模型准备数据。

2 Dataset

新建文件dataset.py，以生成用于输入模型的由张量组成的数据集。初始化BilingualDataset：

class BilingualDataset(Dataset):

    def __init__(self, ds, tokenizer_src, tokenizer_tgt, src_lang, tgt_lang, seq_len) -> None:
        super().__init__()

        self.ds = ds
        self.tokenizer_src = tokenizer_src
        self.tokenizer_tgt = tokenizer_tgt
        self.src_lang = src_lang
        self.tgt_lang = tgt_lang
        self.seq_len = seq_len

        self.sos_token = torch.tensor([tokenizer_tgt.token_to_id("[SOS]")], dtype=torch.int64)
        self.eos_token = torch.tensor([tokenizer_tgt.token_to_id("[EOS]")], dtype=torch.int64)
        self.pad_token = torch.tensor([tokenizer_tgt.token_to_id("[PAD]")], dtype=torch.int64)

    def __len__(self): # 数据集大小
        return len(self.ds)

然后编写关键的函数__getitem__，用于将原始数据转换为张量。

    def __getitem__(self, index):
        src_target_pair = self.ds[index]
        src_text = src_target_pair['translation'][self.src_lang]
        tgt_text = src_target_pair['translation'][self.tgt_lang]

先将文本转换为token，再转换成id，即tokenizer先将句子拆分成词，再将词转换成词表中的id：

        # 将文本转换成token，再转换成id，即tokenizer先将句子拆分成词，再将词转换成词表中的id
        enc_input_tokens = self.tokenizer_src.encode(src_text).ids
        dec_input_tokens = self.tokenizer_tgt.encode(tgt_text).ids

然后计算需要填充（padding）的token数量，以使句子长度总能达到seq_len。此外，因为decoder的输入只有[SOS]没有[EOS]，而decoder的输出（也叫做label，即期望的翻译结果）只有[EOS]没有[SOS]，所以此处的padding会多一个token：

        # 填充句子，使其长度达到seq_len
        enc_num_padding_tokens = self.seq_len - len(enc_input_tokens) - 2
        # 因为decoder的输入只有sos没有eos，所以padding要多一个token
        dec_num_padding_tokens = self.seq_len - len(dec_input_tokens) - 1

这里需要确保确保选择的seq_len长度满足所有样本，即填充的token数量应该不为负数：

        # 确保选择的seq_len长度满足所有样本，即padding应该不为负数
        if enc_num_padding_tokens < 0 or dec_num_padding_tokens < 0:
            raise ValueError('Sentence is too long')

为encoder的输入组装tensor，依次为：'[SOS]'、输入tensor、'[EOS]'和填充'[PAD]'*enc_num_padding_tokens：

        # 为encoder的输入填充tensor，添加'[SOS]'、'[EOS]'、'[PAD]'
        encoder_input = torch.cat([
            self.sos_token,
            torch.tensor(enc_input_tokens, dtype=torch.int64),
            self.eos_token,
            torch.tensor([self.pad_token] * enc_num_padding_tokens, dtype=torch.int64)
        ])

为decoder的输入组装tensor，依次为：'[SOS]'、输入tensor和填充'[PAD]'*enc_num_padding_tokens（没有'[EOS]'）：

        # 为decoder的输入填充tensor，只添加'[SOS]'和'[PAD]'
        decoder_input = torch.cat([
            self.sos_token,
            torch.tensor(dec_input_tokens, dtype=torch.int64),
            torch.tensor([self.pad_token] * dec_num_padding_tokens, dtype=torch.int64)
        ])

为decoder的输出（即label）组装tensor，依次为：输入tensor、'[EOS]'和填充'[PAD]'*enc_num_padding_tokens（没有'[SOS]'）：

        # 为decoder的输出（也叫做label，即期望的翻译结果）填充tensor，只添加'[EOS]'
        label = torch.cat([
            torch.tensor(dec_input_tokens, dtype=torch.int64),
            self.eos_token,
            torch.tensor([self.pad_token] * dec_num_padding_tokens, dtype=torch.int64)
        ])

此处再次检查填充后的tensor长度是否满足seq_len，并返回结果。其中，encoder的mask仅用于屏蔽掉填充的token，而decoder的mask用于屏蔽掉填充的token和未来的token：

        # 再次检测填充后的tensor长度是否满足seq_len
        assert encoder_input.size(0) == self.seq_len
        assert decoder_input.size(0) == self.seq_len
        assert label.size(0) == self.seq_len

        return {
            'encoder_input': encoder_input, # (seq_len)
            'decoder_input': decoder_input, # (seq_len)
            'encoder_mask': (encoder_input != self.pad_token).unsqueeze(0).unsqueeze(0).int(), # (1, 1, seq_len)
            'decoder_mask': (decoder_input != self.pad_token).unsqueeze(0).unsqueeze(0).int() & causal_mask(decoder_input.size(0)), # (1, seq_len, seq_len)) 
            'label': label, # (seq_len)
            'src_text': src_text, # 原文，用于可视化
            'tgt_text': tgt_text, # 译文，用于可视化
        }

我们在上面使用了一个叫做causal_mask的函数，用于创建decoder的mask。该函数的作用是使得decoder只能看到之前的token，而不能看到未来的token。回顾一下Self-Attention的细节：

<br>

这个矩阵表示$Q\times K^T$，我们希望每个词只能看到它之前的词，因此需要使用mask隐藏矩阵对角元素之上的部分。在这个例子中，我们不希望YOUR看到CAT、IS、A、LOVELY、CAT，我们希望YOUR只能看到YOUR自己；而LOVELY则应该能看到它之前的词，即YOUR、CAT、IS、LOVELY，但看不到最后的词CAT。使用Pytorch可以方便的创建一个下三角矩阵：

def causal_mask(size):
    # triu函数中的diagonal=1表示主对角线+1，即生成上三角矩阵后主对角线再置为0
    mask = torch.triu(torch.ones(1, size, size), diagonal=1).type(torch.int)
    # 再将矩阵取反，即生成下三角矩阵
    return mask == 0

我们完成了dataset.py中准备数据集的工作，接下来可以继续完成train.py中的训练模型的循环。

from dataset import BilingualDataset, causal_mask


def get_ds(config):
    """
    加载数据集并创建分词器
    """
    # 在Hugging Face中下载opus_books数据集中的`en-it`子集，选择`train`部分，我们之后将自行再分出validation部分
    ds_raw = load_dataset('opus_books', f'{config["lang_src"]}-{config["lang_tgt"]}', split='train')

    # 创建分词器
    tokenizer_src = get_or_build_tokenizer(config, ds_raw, config['lang_src'])
    tokenizer_tgt = get_or_build_tokenizer(config, ds_raw, config['lang_tgt'])

    # 将数据集分为90%的训练集和10%的验证集
    train_ds_size = int(0.9 * len(ds_raw))
    val_ds_size = len(ds_raw) - train_ds_size
    train_ds_raw, val_ds_raw = random_split(ds_raw, [train_ds_size, val_ds_size])

    train_ds = BilingualDataset(train_ds_raw, tokenizer_src, tokenizer_tgt, config['lang_src'], config['lang_tgt'], config['seq_len'])
    val_ds = BilingualDataset(val_ds_raw, tokenizer_src, tokenizer_tgt, config['lang_src'], config['lang_tgt'], config['seq_len'])

    # 找出训练集中源语言和目标语言里最长的句子长度分别是多少
    max_len_src = 0
    max_len_tgt = 0

    for item in ds_raw:
        src_ids = tokenizer_src.encode(item['translation'][config['lang_src']]).ids
        tgt_ids = tokenizer_tgt.encode(item['translation'][config['lang_tgt']]).ids
        max_len_src = max(max_len_src, len(src_ids))
        max_len_tgt = max(max_len_tgt, len(tgt_ids))

    print(f"Max length of source language: {max_len_src}")
    print(f"Max length of target language: {max_len_tgt}")

    train_dataloader = DataLoader(train_ds, batch_size=config['batch_size'], shuffle=True)
    val_dataloader = DataLoader(val_ds, batch_size=1, shuffle=True)

    return train_dataloader, val_dataloader, tokenizer_src, tokenizer_tgt

3 Trainning Loop

到这里，我们已经准备好了模型和数据集，可以开始训练模型了。首先是创建模型：

from model import build_transformer


def get_model(config, vocab_src_len, vocab_tgt_len):
    """
    创建模型
    """
    model = build_transformer(vocab_src_len, vocab_tgt_len, config['seq_len'], config['seq_len'], config['d_model'])
    return model

在前面的文章中，我们只是使用了很多次config但是从来没有定义这个模型配置文件，现在我们来定义这个配置文件，新建config.py：

from pathlib import Path

def get_config():
    return {
        "batch_size": 8,
        "num_epochs": 20,
        # 在实际的训练中，lr应该根据实际情况调整，比如一开始设置较大的lr，然后在训练过程中逐渐减小lr
        # 但本文的目的在于展示Transformer的原理，使用可变的lr会增加代码复杂度，因此这里使用固定的lr
        "lr": 10**-4,
        "seq_len": 350,
        "d_model": 512,
        "lang_src": "en",
        "lang_tgt": "it",
        "model_folder": "weights",
        "model_basename": "tmodel_",
        # 预加载模型，如果不为空，则从预加载模型中加载参数（如在训练过程中程序意外中断），否则从头开始训练
        "preload": None,
        # 分词文件，如`_en.json`和`_it.json`
        "tokenizer_file": "tokenizer_{0}.json",
        # 为tensorboard提供的log路径
        "experiment_name": "runs/tmodel"
    }


def get_weights_file_path(config, epoch: str):
    model_folder = config["model_folder"]
    model_basename = config["model_basename"]
    model_filename = f"{model_basename}{epoch}.pt"
    # Path重载了`/`操作符，可以直接使用`/`创建子目录
    return str(Path('.') / model_folder / model_filename)

接下来开始编写训练模型的代码。本文使用tensorboard观察模型训练细节，要在本地使用tensorboard，可以安装tensorboard和torch_tb_profiler：

pip install tensorboard torch_tb_profiler

然后在命令行中运行：

tensorboard --logdir runs

即可打开tensorboard，在浏览器中访问http://localhost:6006/即可查看tensorboard的界面。或是在vscode中安装tensorboard插件，然后点击代码中的“启动TensorBoard会话”按钮，即可打开tensorboard。

为预加载权重编写代码，若指定了预加载的模型，则直接加载。此外，指定loss函数，声明padding不参与loss计算。同时，使用label smoothing，让模型降低对计算结果的确定性，即减少本次推理结果的概率，并把减少的部分分配到其他可能的推理结果上。实测可以提升模型的泛化能力，降低过拟合。

from torch.utils.tensorboard import SummaryWriter
from config import get_weights_file_path, get_config
from tqdm import tqdm


def train_model(config):
    """
    训练模型
    """

    # 选择设备
    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
    print(f"Using device: {device}")

    # 确定权重文件目录存在
    Path(config['model_folder']).mkdir(parents=True, exist_ok=True)

    # 加载数据集和分词器
    train_dataloader, val_dataloader, tokenizer_src, tokenizer_tgt = get_ds(config)
    model = get_model(config, tokenizer_src.get_vocab_size(), tokenizer_tgt.get_vocab_size()).to(device)

    # 启动Tensorboard以可视化loss
    writer = SummaryWriter(config['experiment_name'])

    optimizer = torch.optim.Adam(model.parameters(), lr=config['lr'], eps=1e-9)

    # 若指定了预加载权重，则加载预加载权重
    initial_epoch = 0
    global_step = 0
    if config['preload']:
        model_filename = get_weights_file_path(config, config['preload'])
        print(f'Preloading model {model_filename}')
        state = torch.load(model_filename)
        initial_epoch = state['epoch'] + 1
        optimizer.load_state_dict(state['optimizer_state_dict'])
        global_step = state['global_step']
    
    # 定义loss函数，声明padding不参与loss计算。同时，使用label smoothing，让模型降低对计算结果的确定性，
    # 即减少本次推理结果的概率，并把减少的部分分配到其他可能的推理结果上。实测可以提升模型的泛化能力，降低过拟合。
    # 这里的label smoothing的系数设置为0.1，即将最高概率标签的概率降低0.1，再并分配给其他标签的概率。
    loss_fn = nn.CrossEntropyLoss(ignore_index=tokenizer_src.token_to_id('[PAD]'), label_smoothing=0.1).to(device)

编写trainning loop，并在每个epoch结束时保存模型：

    for epoch in range(initial_epoch, config['num_epochs']):
        model.train()
        # 画进度条
        batch_iterator = tqdm(train_dataloader, desc=f"Processing epoch {epoch:02d}")
        for batch in batch_iterator:

            encoder_input = batch['encoder_input'].to(device) # (batch, seq_len)
            decoder_input = batch['decoder_input'].to(device) # (batch, seq_len)
            encoder_mask = batch['encoder_mask'].to(device) # (batch, 1, 1, seq_len) 只隐藏padding tokens
            decoder_mask = batch['decoder_mask'].to(device) # (batch, 1, seq_len, seq_len) 隐藏padding tokens和未来的tokens

            # 将tensor输入Transformer模型并计算
            encoder_output = model.encode(encoder_input, encoder_mask) # (batch, seq_len, d_model)
            decoder_output = model.decode(encoder_output, encoder_mask, decoder_input, decoder_mask) # (batch, seq_len, d_model)
            proj_output = model.project(decoder_output) # (batch, seq_len, tgt_vocab_size)

            label = batch['label'].to(device) # (batch, seq_len)

            # (batch, seq_len, tgt_vocab_size) -[view]-> (batch * seq_len, tgt_vocab_size)
            # (batch, seq_len) -[view]-> (batch * seq_len)
            loss = loss_fn(proj_output.view(-1, tokenizer_tgt.get_vocab_size()), label.view(-1))
            batch_iterator.set_postfix({f"loss": f"{loss.item():6.3f}"})

            # 为TensorBoard记录loss
            writer.add_scalar('train loss', loss.item(), global_step)
            writer.flush()

            # loss反向传播
            loss.backward()

            # 更新参数
            optimizer.step()
            optimizer.zero_grad()

            global_step += 1

        # 在每个epoch结束后保存模型
        # 保存模型是个好习惯，否则每次训练都需要从零开始
        model_filename = get_weights_file_path(config, f"{epoch:02d}")
        torch.save({
            'epoch': epoch,
            'model_state_dict': model.state_dict(),
            'optimizer_state_dict': optimizer.state_dict(),
            'global_step': global_step,
        }, model_filename)

编写__main__函数执行训练：

import warnings

if __name__ == '__main__':
    warnings.filterwarnings('ignore')
    config = get_config()
    train_model(config)

此时就可以正常的开始模型训练了，如果编写正确的话，程序就会自动下载数据集并开始训练了。

在训练之前，我们还可以可视化训练的效果，比如查看模型预测的结果是否与真实结果是否一致，也就是validation，即观察模型在训练时是如何演化的。

4 Validation Loop

接下来编写validation loop，以便我们可以实时评估模型推理结果，观察模型是如何翻译数据集中并不在训练集当中的句子的。

def run_validation(model, validation_ds, tokenizer_src, tokenizer_tgt, max_len, device, print_msg, global_state, writer, num_examples=2):

    # 告诉pytorch将模型置于eval模式，关闭dropout、batchnorm中的随机因素
    model.eval()
    # 测试2个句子看看模型输出的翻译结果是什么
    count = 0

    srouce_texts = []
    expected = []
    predicted = []

    # 终端宽度
    console_width = 80

    # 关闭pytorch的梯度计算，在这个`with`中我们只需要推理结果，不需要训练，因此不需要计算tensor的梯度
    with torch.no_grad():
        for batch in validation_ds:
            count += 1
            encoder_input = batch['encoder_input'].to(device) # (batch, seq_len)
            encoder_mask = batch['encoder_mask'].to(device) # (batch, 1, 1, seq_len) 只隐藏padding tokens

            # 确定validation的batch应为1
            assert encoder_input.size(0) == 1, "Batch size must be 1 for validation"

            # 当模型进行推理时，只需要计算一次`encoder_output`，然后重复使用它来为每个token计算`decoder_output`

回忆Transformer模型，当我们想用模型进行推理时，只需要计算一次encoder_output，然后重复使用它来为每个token计算decoder_output，现在编写greedy_decode函数，用于生成翻译结果：

def greedy_decode(model, source, source_mask, tokenizer_src, tokenizer_tgt, max_len, device):
    """
    使用贪婪策略，缓存encoder输出，计算decoder输出

    参数: 
        `model`: 模型
        `source`: 源语言句子
        `source_mask`: 源语言句子的padding mask
        `tokenizer_src`: 源语言的分词器
        `tokenizer_tgt`: 目标语言的分词器
        `max_len`: 句子最大长度
        `device`: 运行模型的设备
    """
    # 告诉pytorch将模型置于eval模式，关闭dropout、batchnorm中的随机因素
    sos_idx = tokenizer_tgt.token_to_id('[SOS]')
    eos_idx = tokenizer_tgt.token_to_id('[EOS]')
    
    # 计算encoder输出，并将结果重用于计算每个token的decoder输出
    encoder_output = model.encode(source, source_mask)
    
    # 模型推理计算过程如下：首先输入句子的起始符[SOS]作为decoder的第一个输入，然后得到模型输出的翻译句子的第一个词；
    # 接下在每一步迭代中将上一步的输出附加在输入中，使模型继续输出再下一个词，直到遇到[EOS]或达到句子的最大长度。

    # 使用[SOS]初始化decoder输入
    decoder_input = torch.empty(1, 1).fill_(sos_idx).type_as(source).to(device)
    # 接下来让decoder循环输出下一个词，知道遇到[EOS]或达到句子最大长度
    while True:

        # 判断是否达到句子最大长度
        if decoder_input.size(1) == max_len:
            break

        # 为target（即decoder input）创建mask，使模型只能看到当前时刻之前的词
        # 对比`dataset.py`中使用的`causal_mask`，这里使用的是`decoder_input.size(1)`作为`tgt_mask`的长度，并不需要使用额外的padding
        decoder_mask = causal_mask(decoder_input.size(1)).type_as(source_mask).to(device)

        # 计算decoder输出，这里复用了`encoder_output`
        out = model.decode(encoder_output, source_mask, decoder_input, decoder_mask) # (1, seq_len, d_model)

        # 计算下一个词：使用projection层计算下一个token的概率分布，只取最后一个词的projection，out[:, -1]为(1, 1, d_model)，prob为(1, 1, vocab_size)
        prob = model.project(out[:, -1])
        # 取概率最大的词作为下一个token（这里使用贪婪策略，即只取概率最大的词，而不是所有词的概率之和）
        _, next_word = torch.max(prob, dim=1)
        # 再将next_word添加到decoder_input的末尾
        decoder_input = torch.cat([decoder_input, torch.empty(1, 1).type_as(source).fill_(next_word.item()).to(device)], dim=1)

        # 如果遇到[EOS]，则停止循环
        if next_word == eos_idx:
            break
        
    return decoder_input.squeeze(0) # 输出翻译句子

继续编写run_validation函数：

            # 确定validation的batch应为1
            assert encoder_input.size(0) == 1, "Batch size must be 1 for validation"

            # 当我们想要模型进行推理时，我们只需要计算一次`encoder_output`，然后重复使用它来为每个token计算`decoder_output`
            model_out = greedy_decode(model, encoder_input, encoder_mask, tokenizer_src, tokenizer_tgt, max_len, device)

            source_text = batch['src_text'][0]
            target_text = batch['tgt_text'][0]
            # 用目标语言的分词器将模型输出的token序列转换为文本
            model_out_text = tokenizer_tgt.decode(model_out.detach().cpu().numpy())

            source_texts.append(source_text)
            expected.append(target_text)
            predicted.append(model_out_text)

            # 打印输出，为了不影响`tqdm`进度条正常刷新，我们使用`print_msg`而不是`print`来打印输出。
            print_msg('-'*console_width)
            print_msg(f"Source text: {source_text}")
            print_msg(f"TARGET text: {target_text}")
            print_msg(f"PREDICTED text: {model_out_text}")
            print_msg('-'*console_width)

            # 如果预测了足够的句子，则停止循环
            if count >= num_examples:
                break

最后，我们可以将run_validation函数添加到train_model函数中，放在每个epoch结束后：

            global_step += 1

        run_validation(model, val_dataloader, tokenizer_src, tokenizer_tgt, config['seq_len'], device, lambda msg: batch_iterator.write(msg), global_step, writer)

        # 在每个epoch结束后保存模型
        # 保存模型是个好习惯，否则每次训练都需要从零开始
        model_filename = get_weights_file_path(config, f"{epoch:02d}")

5 Attention Visualization

可视化的代码中的大部分功能都不需要我们自己实现，前人已经帮我们完成了很多工作。这里使用jupyter notebook，新建attention_visual.ipynb文件。

这里除了之前我们自己写的模型和训练库以外，还使用了altair可视化库。

import torch
import torch.nn as nn

from model import Transformer
from config import get_config, get_weights_file_path
from train import get_model, get_ds, greedy_decode

import altair as alt
import pandas as pd
import numpy as np
import warnings


warnings.filterwarnings('ignore')

同之前一样，选择计算设备：

# 从`train_model`中拷贝选择设备的代码即可
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(f'Using device: {device}')

加载预训练模型的权重：

config = get_config()
train_dataloader, val_dataloader, vocab_src, vocab_tgt = get_ds(config)
model = get_model(config, vocab_src.get_vocab_size(), vocab_tgt.get_vocab_size()).to(device)

# 加载预训练权重
model_filename = get_weights_file_path(config, f"03")
state = torch.load(model_filename)
model.load_state_dict(state['model_state_dict'])

从验证集中选择一对样本：

def load_next_batch():
    # Load a sample batch from the validation set
    batch = next(iter(val_dataloader))
    encoder_input = batch["encoder_input"].to(device)
    encoder_mask = batch["encoder_mask"].to(device)
    decoder_input = batch["decoder_input"].to(device)
    decoder_mask = batch["decoder_mask"].to(device)

    encoder_input_tokens = [vocab_src.id_to_token(idx) for idx in encoder_input[0].cpu().numpy()]
    decoder_input_tokens = [vocab_tgt.id_to_token(idx) for idx in decoder_input[0].cpu().numpy()]

    # check that the batch size is 1
    assert encoder_input.size(
        0) == 1, "Batch size must be 1 for validation"

    model_out = greedy_decode(
        model, encoder_input, encoder_mask, vocab_src, vocab_tgt, config['seq_len'], device)
    
    return batch, encoder_input_tokens, decoder_input_tokens

可视化注意力矩阵的函数，这些函数基本都能从网上找到：

def mtx2df(m, max_row, max_col, row_tokens, col_tokens):
    """
    生成一个可视化矩阵
    """
    return pd.DataFrame(
        [
            (
                r,
                c,
                float(m[r, c]),
                "%.3d %s" % (r, row_tokens[r] if len(row_tokens) > r else "<blank>"),
                "%.3d %s" % (c, col_tokens[c] if len(col_tokens) > c else "<blank>"),
            )
            for r in range(m.shape[0])
            for c in range(m.shape[1])
            if r < max_row and c < max_col
        ],
        columns=["row", "column", "value", "row_token", "col_token"],
    )

def get_attn_map(attn_type: str, layer: int, head: int):
    """
    从指定的层和头获取attention map
    """

    # 我们在`model.py`的`MultiHeadAttentionBlock`中，定义`attention`函数的返回值时，同时返回了`attention_scores`，
    # 之后又在`forward`中将其保存在`self.attention_scores`中。
    # 因此，可以通过`model.encoder.layers[layer].self_attention_block.attention_scores`
    # 来获取encoder的self-attention的attention_scores。
    if attn_type == "encoder":
        attn = model.encoder.layers[layer].self_attention_block.attention_scores
    elif attn_type == "decoder":
        attn = model.decoder.layers[layer].self_attention_block.attention_scores
    elif attn_type == "encoder-decoder":
        attn = model.decoder.layers[layer].cross_attention_block.attention_scores
    return attn[0, head].data

def attn_map(attn_type, layer, head, row_tokens, col_tokens, max_sentence_len):
    """
    使用altair绘制attention map
    """
    df = mtx2df(
        get_attn_map(attn_type, layer, head),
        max_sentence_len,
        max_sentence_len,
        row_tokens,
        col_tokens,
    )
    return (
        alt.Chart(data=df)
        .mark_rect()
        .encode(
            x=alt.X("col_token", axis=alt.Axis(title="")),
            y=alt.Y("row_token", axis=alt.Axis(title="")),
            color="value",
            tooltip=["row", "column", "value", "row_token", "col_token"],
        )
        #.title(f"Layer {layer} Head {head}")
        .properties(height=400, width=400, title=f"Layer {layer} Head {head}")
        .interactive()
    )

def get_all_attention_maps(attn_type: str, layers: list[int], heads: list[int], row_tokens: list, col_tokens, max_sentence_len: int):
    charts = []
    for layer in layers:
        rowCharts = []
        for head in heads:
            rowCharts.append(attn_map(attn_type, layer, head, row_tokens, col_tokens, max_sentence_len))
        charts.append(alt.hconcat(*rowCharts))
    return alt.vconcat(*charts)

获取一对样本：

batch, encoder_input_tokens, decoder_input_tokens = load_next_batch()
print(f'Source: {batch["src_text"][0]}')
print(f'Target: {batch["tgt_text"][0]}')
sentence_len = encoder_input_tokens.index("[PAD]")

绘制Encoder的self-attention：

layers = [0, 1, 2]
heads = [0, 1, 2, 3, 4, 5, 6, 7]

# 可视化Encoder的Self-Attention
get_all_attention_maps("encoder", layers, heads, encoder_input_tokens, encoder_input_tokens, min(20, sentence_len))

绘制Decoder的self-attention：

# 可视化Decoder的Self-Attention
get_all_attention_maps("decoder", layers, heads, decoder_input_tokens, decoder_input_tokens, min(20, sentence_len))

绘制Encoder-Decoder的cross-attention：

# 可视化Decoder的Cross-Attention
# 这是实际上计算en-it翻译任务的地方，cross attention使用encoder的key/value，以及decoder的query计算attention。
get_all_attention_maps("encoder-decoder", layers, heads, encoder_input_tokens, decoder_input_tokens, min(20, sentence_len))

理解Transformer模型1：编写Transformer

Sat, 06 Jan 2024 15:24:00 GMT

回头看来，Attention Is All You Need这篇文章是所有大模型的根基，从MLP、CNN、RNN发展而来的船新版本特征提取器。这次跟着油管UP Umar Jamil对照论文通过手写transformer来学习这个划时代的算法。Coding a Transformer from scratch on PyTorch, with full explanation, training and inference。本文以翻译任务为例，展示如何使用pytorch手写一个将英语翻译为意大利语的Transformer。

整个Transformer模型可以大致分为两个部分，Encoder和Decoder。新建文件model.py用于编写Transformer模型。

1 Encoder

Encoder由$N$个encoder模块首尾相接组合而成，每个encoder模块又包含了两个由Residual连接（也译为残差连接）的网络。

1.1 Input Embedding

<br>

第一步是embedding（也译为词嵌入），就是给将单词表里的每个词一个编号，然后将这个编号映射为一个词向量，在本文中词向量大小为512维度。需要注意的是在论文3.4节中提到embedding需要乘以$\sqrt{d_{model}}$。

import torch
import torch.nn as nn
import math


class InputEmbeddings(nn.Module):
    
    # `d_model`: 模型维度，本文中为512
    # `vocab_size`: 词表大小
    def __init__(self, d_model: int,  vocab_size: int) -> None:
        super().__init__()
        self.d_model = d_model
        self.vocab_size = vocab_size
        self.embedding = nn.Embedding(vocab_size, d_model) # 将一个数字映射为一个向量，这里的Embedding层包含vocab_size个大小为d_model的向量
    
    def forward(self, x):
        # (batch, seq_len) --> (batch, seq_len, d_model)
        # 论文3.4节Embeddings and Softmax中提到embedding要乘以d_model的平方根    
        return self.embedding(x) * math.sqrt(self.d_model)

1.2 Positional Encoding

<br>

第二步需要将每个单词在句子中的位置信息告诉模型，位置编码与embedding的维度相同（本文中为512），然后将这个位置编码与前面的embedding相加。位置编码矩阵大小为(seq_len, d_model)。

<br>

在位置向量的偶数元素使用公式$PE(pos, 2i)=\sin\frac{pos}{10000^\frac{2i}{d_{model}}}$，在奇数位置向量的奇数元素使用公式$PE(pos, 2i+1)=\cos\frac{pos}{10000^\frac{2i}{d_{model}}}$。为了计算的数值稳定性，我们对分母取对数和指数$\mathrm{e}^{\log_{\mathrm{e}}{10000\frac{2i}{d_{model}}}}$化简得到$\mathrm{e}^{2i\frac{\log_{\mathrm{e}}{10000}}{d_{model}}}$（这一项是分母所以代码中乘以这一项的负指数）。

class PositionalEncoding(nn.Module):

    # `d_model`: 模型维度，本文中为512
    # `seq_len`: 句子的最大长度，为每个位置分配一个向量
    # `dropout`: 添加dropout层抑制过拟合
    # 位置信息只计算一次，在之后的训练中用在每个句子上
    def __init__(self, d_model: int, seq_len: int, dropout: float) -> None:
        super().__init__()
        self.d_model = d_model
        self.seq_len = seq_len
        self.dropout = nn.Dropout(dropout)

        # 创建维度为(seq_len, d_model)的矩阵
        pe = torch.zeros(seq_len, d_model)
        # 创建维度为(seq_len)的向量，元素取值[0, seq_len-1]
        position = torch.arange(0, seq_len, dtype=torch.float).unsqueeze(1) # (seq_len, 1)
        # 创建维度为(d_model)的向量
        div_term = torch.exp(torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model)) # (d_model / 2)
        # 偶数项应用sin
        pe[:, 0::2] = torch.sin(position * div_term) # sin(position * (10000 ** (2i / d_model))
        # 奇数项应用cos
        pe[:, 1::2] = torch.cos(position * div_term) # cos(position * (10000 ** (2i / d_model))

        # 为位置编码添加batch维度，以方便一批一批的使用句子
        pe = pe.unsqueeze(0) # (1, seq_len, d_model)

        # 当你有一个不是习得的模型参数，而是表示模型状态的tensor，如果想要存放在模型中，则需要注册一个buffer，这个buffer就会跟模型文件一起保存在模型中
        self.register_buffer('pe', pe)

    def forward(self, x):
        # requires_grad_(False)告诉模型训练过程中不需要学习这一部分位置编码，因为他们是固定的
        x = x + (self.pe[:, :x.shape[1], :]).requires_grad_(False) # (batch, seq_len, d_model)
        return self.dropout(x)

1.3 Normaliation

<br>

Normaliation（也译为归一化），是取一个batch中的每个item，计算他们在本batch中相对于其他item的期望$\mu$和方差$\sigma^{2}$，再使用$\mu$和$\sigma^{2}$计算这一项的新值$\hat{x_j}=\frac{x_j-\mu_j}{\sqrt{\sigma_{j}^{2}+\epsilon}}$。此外，引入两个会被学习的参数，乘数gamma（或叫做alpha）和加数beta（或叫做bias），以增加数值的差异，因为如果将所有值都限定在[0, 1]之间，数值的起伏可能会过小，因此有必要让模型自己学习调整这两个能够引入更大数值起伏的参数。另外，之所以需要$\epsilon$这个参数，主要是为了数值稳定性，比如$\sigma$过小时将会导致整个$\hat{x_j}$过大。

class LayerNormalization(nn.Module):

    # `eps`: 批归一化的参数epsilon
    def __init__(self, eps: float = 10**-6) -> None:
        super().__init__()
        self.eps = eps
        self.alpha = nn.Parameter(torch.ones(1)) # 乘数
        self.bias = nn.Parameter(torch.zeros(1)) # 加数
    
    # `x`: 大小为(batch, seq_len, hidden_size)
    def forward(self, x):
        # `keepdim=True`让计算保持维度属性
        # `dim=-1`沿最后一个维度计算均值和方差
        mean = x.mean(dim=-1, keepdim=True) # (batch, seq_len, 1)
        std = x.std(dim=-1, keepdim=True) # (batch, seq_len, 1)

        # eps保持数值稳定性，防止除数过小
        return self.alpha * (x - mean) / (std + self.eps) + self.bias

1.4 Feed Forward

一个简单的全连接层，论文提了用到的参数和激活函数relu。文中提到可以将这一步计算看做两个核大小为1的卷积层，输入输出维度为d_model=512，内部隐藏层维度为d_ff=2048。

class FeedForwardBlock(nn.Module):

    # 一个简单的全连接层，论文3.3节提到d_model、d_ff的大小
    def __init__(self, d_model: int, d_ff: int, dropout: float) -> None:
        super().__init__()

        # Linear层默认就带有bias，因此我们无需新增参数
        self.linear_1 = nn.Linear(d_model, d_ff) # w1 and b1
        self.dropout = nn.Dropout(dropout)
        self.linear_2 = nn.Linear(d_ff, d_model) # w2 and b2

    def forward(self, x):
        # (batch, seq_len, d_model) -[linear_1]-relu-dropout-> (batch, seq_len, d_ff) -[linear_2]-> (batch, seq_len, d_model)
        return self.linear_2(self.dropout(torch.relu(self.linear_1(x))))

1.5 Multi-Head Attention

<br>

Encoder的重头戏，就是这个多头注意力层，需要注意的是，encoder和decoder的多头注意力层有些细微的区别。

先抛开batch维度，只关注算法，看看如何在一个句子上应用多头注意力模型。但需要记住，应用算法的时候，第一个维度是batch，程序会成批的输入句子。这里：

$seq$为句子最大长度
$d_{model}$为embedding向量的大小（本文中为512）；
$\mathrm{h}$为注意力头数
$d_k=d_v$为$d_{model}/h$

从流程上来说：

先将输入复制三份，即Q、K、V矩阵（分别代表query、key、value，维度均为$(seq, d_{model})$）；
分别乘以$W^Q$、$W^K$、$W^V$矩阵（维度均为$(d_{model}, d_{model})$），得到$Q'$、$K'$、$W'$（维度均为$(seq, d_{model})$）；
沿embedding方向将$Q'$、$K'$、$W'$拆分为$h$个小矩阵$Q_i$、$K_i$、$W_i$（维度均为$(seq, d_k)$），即每个小矩阵都能拿到完整的句子，但都只拿到了embedding向量的一小部分；
应用注意力模型公式$Attention(Q, K, V)=\mathrm{softmax}(\frac{QK^T}{\sqrt{d_k}})V$，计算出每个头$head_i=Attention(QW_i^Q, KW_i^K, VW_i^V)$，其中的每个头$head_i$维度均为$(d_v, seq)$；
将$head_i$合并成矩阵$H$，维度为$(seq, hd_v)$，即变回$(seq, d_{model})$，再乘以$W^O$矩阵（维度为$(hd_v, d_{model})$），最终得到$MH\text{-}A$矩阵（维度为$(seq, d_{model})$），这一步的整体运算为$MultiHead(Q, K, V)=\mathrm{Concat}(head_1 \dots head_h)W^O$；

class MultiHeadAttentionBlock(nn.Module):

    # `d_model`: 模型维度，本文中为512
    # `h`: 注意力头数
    # `dropout`: 添加dropout层抑制过拟合
    def __init__(self, d_model: int, h: int, dropout: float) -> None:
        super().__init__()
        self.d_model = d_model
        self.h = h
        # 多头需要均分d_model，应确保d_model可以被h整除
        assert d_model % h == 0, "d_model不可被h整除"

        self.d_k = d_model // h
        self.w_q = nn.Linear(d_model, d_model) # W^Q
        self.w_k = nn.Linear(d_model, d_model) # W^K
        self.w_v = nn.Linear(d_model, d_model) # W^V

        self.w_o = nn.Linear(d_model, d_model) # W^O
        self.dropout = nn.Dropout(dropout)

关于mask参数

<br>

在计算$Attention(Q, K, V)=\mathrm{softmax}(\frac{QK^T}{\sqrt{d_k}})V$时，我们会先使用$Q$和$K$计算$\mathrm{softmax}(\frac{QK^T}{\sqrt{d_k}})$（即在乘以$V$之前）。$\frac{QK^T}{\sqrt{d_k}}$得到的是一个$(seq, seq)$的矩阵，其内容为各词与其他词的关系表。如果我们不希望某词与其他某词产生联系，就需要将矩阵中两词对应的位置写成负无穷，即使其注意力分数变得极小，此时在进行$\mathrm{softmax}$运算时，矩阵该位置的值就几乎为零，也就意味着屏蔽了这两个词的注意力——这就是mask参数的作用。

    @staticmethod
    def attention(query, key, value, mask, dropout: nn.Dropout):
        d_k = query.shape[-1]

        # 计算论文中$\mathrm{softmax}\(\frac{QK^T}{\sqrt{d_k}}\)V$的部分
        # (batch, h, seq_len, d_k) -[transpose]-> (batch, h, d_k, seq_len)] -[matmul]-> (batch, h, seq_len, seq_len)
        attention_scores = (query @ key.transpose(-2, -1)) / math.sqrt(d_k)
        if mask is not None:
            # 在mask==0的位置写一个非常小的数来代表负无穷
            attention_scores.masked_fill_(mask == 0, -1e9)
        attention_scores = attention_scores.softmax(dim = -1) # (batch, h, seq_len, seq_len)再计算softmax
        if dropout is not None:
            attention_scores = dropout(attention_scores)
        # 乘以`value`后变为(batch, h, seq_len, seq_len) --> (batch, h, seq_len, d_k)
        # 这里额外返回`attention_scores`是为了可视化注意力分数
        return (attention_scores @ value), attention_scores

    def forward(self, q, k, v, mask):
        query = self.w_q(q) # (batch, seq_len, d_model) --> (batch, seq_len, d_model)
        key = self.w_k(k) # (batch, seq_len, d_model) --> (batch, seq_len, d_model)
        value = self.w_v(v) # (batch, seq_len, d_model) --> (batch, seq_len, d_model)

        # (batch, seq_len, d_model) -[view]-> (batch, seq_len, h, d_k) -[transpose]-> (batch, h, seq_len, d_k)
        query = query.view(query.shape[0], query.shape[1], self.h, self.d_k).transpose(1, 2)
        key = key.view(key.shape[0], key.shape[1], self.h, self.d_k).transpose(1, 2)
        value = value.view(value.shape[0], value.shape[1], self.h, self.d_k).transpose(1, 2)

        x, self.attention_scores = MultiHeadAttentionBlock.attention(query, key, value, mask, self.dropout)

        # (batch, h, seq_len, d_k) -[transpose]-> (batch, seq_len, h, d_k) -[contiguous+view]-> (batch, seq_len, d_model)
        # `contiguous`用于重新调整内存布局，因为诸如`transpose`、`view`等函数只会改变tensor的元数据以调整其表现形式，
        #     这些操作可能导致tensor显示的布局与其内存中的布局不一致，
        #     详情参见https://stackoverflow.com/questions/48915810/what-does-contiguous-do-in-pytorch
        x = x.transpose(1, 2).contiguous().view(x.shape[0], -1, self.h * self.d_k)

        # 乘以W^O，(batch, seq_len, d_model) --> (batch, seq_len, d_model)
        return self.w_o(x)

1.6 Residual Connection

在Transformer模型中可以看到不少Residual连接（也译为残差连接），比如左侧一开始的Input Embedding+Positional Encoding既输出到Multi-Head Attention又输出到Add & Norm，或是接下来Add & Norm输出既到Feed Forward又到下一个Add & Norm。可以看出，模型中的残差连接都是用来连接Add & Norm及其前一层网络的：

class ResidualConnection(nn.Module):

    def __init__(self, dropout: float) -> None:
        super().__init__()
        self.dropout = nn.Dropout(dropout)
        self.norm = LayerNormalization()

    def forward(self, x, sublayer):
        # 有些实现是先计算`norm`再计算`sublayer`，比如论文中的实现。
        # 这两种计算计算的先后顺序有些细微差别，本文按照先`norm`再`sublayer`的模式执行。
        return x + self.dropout(sublayer(self.norm(x)))

1.7 Encoder Block

现在可以实现左侧整个encoder模块了，可以看出这个模块在模型中又N个，前一个encoder的输出送入后一个encoder做输入，最后一个encoder的输出送入decoder。Encoder中包含了一层Multi-Head Attention、一层Feed Forward、两层Add & Norm：

class EncoderBlock(nn.Module):

    def __init__(self, self_attention_block: MultiHeadAttentionBlock, feed_forward_block: FeedForwardBlock, dropout: float) -> None:
        super().__init__()
        self.self_attention_block = self_attention_block
        self.feed_forward_block = feed_forward_block
        # 返回一个列表，包括两层`ResidualConnection`
        self.residual_connection = nn.ModuleList([ResidualConnection(dropout) for _ in range(2)])

    # `src_mask`应用在encoder的输入上，用于屏蔽padding词对正常词的影响，
    def forward(self, x, src_mask):
        # 从这里可以看到，`self_attention_block`之所以叫做"self attention"，
        # 是因为其中的query、key、value都是同一个输入句子`x`自身，
        # 即这一层输入的句子中的每个词，只会跟本句的词产生关系。
        # 在后文中可以看到decoder会有些许区别，将用到"cross attention"，
        # 即decoder中的query将会与encoder中的key和value产生关系。
        x = self.residual_connection[0](x, lambda x: self.self_attention_block(x, x, x, src_mask))
        x = self.residual_connection[1](x, self.feed_forward_block)
        return x

1.8 Encoder Module

然后将多个encoder模块首尾相接的组装在一起，最后添加一层Normalization形成模型的encoder：

class Encoder(nn.Module):

    def __init__(self, layers: nn.ModuleList) -> None:
        super().__init__()
        self.layers = layers
        self.norm = LayerNormalization()

    def forward(self, x, mask):
        for layer in self.layers:
            x = layer(x, mask)
        return self.norm(x)

2 Decoder

<br>

再来观察一下Decoder。对于输入，Decoder的Output Embedding与Encoder的Input Embedding一样，都是用到同一张词表，而且Positional Encoding也是一样的。不一样的是上面的Decoder Block，可以看到首先是Masked Multi-Head Attention和残差连接到Add & Norm，然后又是Multi-Head Attention残差连接到Add & Norm，最后是Feed Forward残差连接到Add & Norm。可以发现我们前文中定义的MultiHeadAttentionBlock已经考虑到mask参数，因此只需要使用已经定义好的模块，把他们首尾相接，即可快速组装出这个decoder。

2.1 Decoder Block

编写decoder模块时需要注意，最下层的Multi-Head Attention仍然是"self attention"，而中间的Multi-Head Attention则变为"cross attention"，我们将会用到两种输入并计算他们之间的关系。另外，之所以代码中有src_mask和tgt_mask，是因为本文展示的是一个翻译任务，源语言为英语，目标语言为意大利语，所以从算法角度来说，也可以叫做enc_mask和dec_mask，只需要记住encoder和decoder各自都有一个mask。

class DecoderBlock(nn.Module):

    def __init__(self, self_attention_block: MultiHeadAttentionBlock, cross_attention_block: MultiHeadAttentionBlock, feed_forward_block: FeedForwardBlock, dropout: float) -> None:
        super().__init__()
        self.self_attention_block = self_attention_block
        self.cross_attention_block = cross_attention_block
        self.feed_forward_block = feed_forward_block
        self.residual_connection = nn.ModuleList([ResidualConnection(dropout) for _ in range(3)])

    # `x`: decoder的输入；
    # `encoder_output`: encoder的输出；
    # `src_mask`: encoder的mask
    # `tgt_mask`: decoder的mask
    def forward(self, x, encoder_output, src_mask, tgt_mask):
        x = self.residual_connection[0](x, lambda x: self.self_attention_block(x, x, x, tgt_mask))
        x = self.residual_connection[1](x, lambda x: self.cross_attention_block(x, encoder_output, encoder_output, src_mask))
        x = self.residual_connection[2](x, self.feed_forward_block)
        return x

2.2 Decoder Module

同encoder类似，decoder也是多个decoder模块首尾相连，最后添加一层Normalization的结构：

class Decoder(nn.Module):

    def __init__(self, layers: nn.ModuleList) -> None:
        super().__init__()
        self.layers = layers
        self.norm = LayerNormalization()
    
    def forward(self, x, encoder_output, src_mask, tgt_mask):
        for layer in self.layers:
            x = layer(x, encoder_output, src_mask, tgt_mask)
        return self.norm(x)

3 Linear & Softmax

现在，Decoder的输出维度为$(seq, d_{model})$（仍然暂时忽略batch维度），我们想要将这些Embedding映射回词表，于是需要添加一层Linear将这些Embedding映射到词表中各词所在的位置上（因此也可以叫做Projection Layer投影层）。

class ProjectionLayer(nn.Module):

    def __init__(self, d_model: int, vocab_size: int) -> None:
        super().__init__()
        self.proj = nn.Linear(d_model, vocab_size)

    def forward(self, x):
        # (batch, seq_len, d_model) --> (batch, seq_len, vocab_size)
        # 这里为了数值稳定性，采用log softmax
        return torch.log_softmax(self.proj(x), dim=-1)

4 Transformer

现在我们已经完成了Transformer模型中所有模块的编写，是时候将他们组装成一个完整的Transformer了。本文的例子为翻译任务，因此Transformer初始化时需要源语言的Embedding和目标语言的Embedding。我们在用三个函数分别实现encoder、decoder、project，而不是使用一个forward函数实现，因为在推理过程中，我们可以重用encoder的输出，而且将这部分输出另存一份有利于可视化理解注意力模型的计算过程。

class Transformer(nn.Module):

    def __init__(self, encoder: Encoder, decoder: Decoder, 
                 src_embed: InputEmbeddings, tgt_embed: InputEmbeddings, 
                 src_pos: PositionalEncoding, tgt_pos: PositionalEncoding, 
                 projcetion_layer: ProjectionLayer) -> None:
        super().__init__()
        self.encoder = encoder
        self.decoder = decoder
        self.src_embed = src_embed
        self.tgt_embed = tgt_embed
        self.src_pos = src_pos
        self.tgt_pos = tgt_pos
        self.projcetion_layer = projcetion_layer
    
    def encode(self, src, src_mask):
        src = self.src_embed(src)
        src = self.src_pos(src)
        return self.encoder(src, src_mask)
    
    def decode(self, encoder_output, src_mask, tgt, tgt_mask):
        tgt = self.tgt_embed(tgt)
        tgt = self.tgt_pos(tgt)
        return self.decoder(tgt, encoder_output, src_mask, tgt_mask)
    
    def project(self, x):
        return self.projcetion_layer(x)

至此我们已经完成了所有模块的编写，还需要一个函数将这一大堆embedding、encoder、decoder模块赋超参数并完成初始化。

def build_transformer(src_vocab_size: int, tgt_vocab_size: int, 
                      src_seq_len: int, tgt_seq_len: int, 
                      d_model: int = 512, N: int = 6, h: int = 8, dropout: float = 0.1, d_ff = 2048) -> Transformer:
    """构造Transformer，创建超参数，初始化参数。

        参数: 
            `src_vocab_size`: 源语言的词表大小；
            `tgt_vocab_size`: 目标语言的词表大小；
            `src_seq_len`: 源语言语言句子最大长度；
            `tgt_seq_len`: 目标语言句子最大长度；
            （本文的范例为英语到意大利语的翻译，源和目标语言句子长度设置为相同大小。
            但对于其他语言，可能存在源和目标语言相差非常大的情况，届时将这两个值设置为不同大小）
            `d_model`: 模型大小，与论文一致预设为`512`；
            `N`: encoder/decoder的数量，与论文一致预设为`6`；
            `h`: 注意力头数，与论文一致预设为`8`；
            `dropout`: 与论文一致预设为`0.1`；
            `d_ff`: 前馈网络大小，与论文一致预设为`2048`。
        返回:
            一个完成了参数初始化的`Transformer`。
    """  
    
    # 初始化Embedding层
    src_embed = InputEmbeddings(d_model, src_vocab_size)
    tgt_embed = InputEmbeddings(d_model, tgt_vocab_size)

    # 初始化Positional Encoding层，实际上位置信息的编码只需要一组参数计算一次即可，本文使用相同的参数计算两层是为了更好的解释模型
    src_pos = PositionalEncoding(d_model, src_seq_len, dropout)
    tgt_pos = PositionalEncoding(d_model, tgt_seq_len, dropout)

    # 初始化N个Encoder
    encoder_blocks = []
    for _ in range(N):
        encoder_self_attention_block = MultiHeadAttentionBlock(d_model, h, dropout)
        feed_forward_block = FeedForwardBlock(d_model, d_ff, dropout)
        encoder_block = EncoderBlock(encoder_self_attention_block, feed_forward_block, dropout)
        encoder_blocks.append(encoder_block)
    
    # 初始化N个Decoder
    decoder_blocks = []
    for _ in range(N):
        decoder_self_attention_block = MultiHeadAttentionBlock(d_model, h, dropout)
        decoder_cross_attention_block = MultiHeadAttentionBlock(d_model, h, dropout)
        feed_forward_block = FeedForwardBlock(d_model, d_ff, dropout)
        decoder_block = DecoderBlock(decoder_self_attention_block, decoder_cross_attention_block, feed_forward_block, dropout)
        decoder_blocks.append(decoder_block)
    
    # 构造Encoder和Decoder
    encoder = Encoder(nn.ModuleList(encoder_blocks))
    decoder = Decoder(nn.ModuleList(decoder_blocks))

    # 初始化投影层
    projection_layer = ProjectionLayer(d_model, tgt_vocab_size)

    # 构造Transformer
    transformer = Transformer(encoder, decoder, src_embed, tgt_embed, src_pos, tgt_pos, projection_layer)
    
    # 初始化超参数
    for p in transformer.parameters():
        if p.dim() > 1:
            nn.init.xavier_uniform_(p)
    
    return transformer

最终，我们完成了一个Transformer的编写，这个过程详细展示了Transformer的内部结构，包括各模块的总体架构、每层的输入输出、各层计算过程及维度、模块间的关系等信息。接下来将要展示如何使用Transformer，包括搜集训练集数据，以及编写训练循环、推理过程、可视化等部分。

OpenAI API尝鲜

Fri, 31 Mar 2023 21:12:00 GMT

chat.openai.com这个网页是相当的难伺候，即使你是美帝IP也得看在哪个机房，比如注明的某瓦工就进了微软爸爸的ban list，所以想尝试一下通过API的方式稳定聊天。

0x00 WSL中搭环境

这两年微软爸爸干了很多人事，包括但不限于azure、vscode、wsl、OpenAI等，我虽然跟苹果十几年老夫老妻，但还是毅然决然的横跳回微软爸爸的怀抱。

Windows 10自带的WSL2，可以说是相当好用的虚拟机了，因为习惯了POSIX式的命令行环境，就像继续在WSL2里搭环境访问OpenAI。这当然就绕不开那些需要通过修改iptables进行透明代理的软件。

这一上来就是个下马威，这些软件在执行iptables ... -m string ...命令的时候直接会报" iptables Couldn't load match `string':No such file or directory"，搜了一下这个报错可能是iptables缺失string匹配模块，继续搜发现这个模块需要内核支持，而非常不巧的是微软爸爸的WSL2默认不支持这个功能。想用？自己加参数CONFIG_NETFILTER_XT_MATCH_STRING=y编译内核吧。

软爸倒是早就把WSL2内核准备好了，用WSL2就可以编译，编译前改一下Microsoft/config-wsl，把选项CONFIG_NETFILTER_XT_MATCH_STRING=y打开即可，桌面CPU编译很快的，指定-j选项100%负载几分钟就能搞定。

sudo apt install build-essential flex bison dwarves libssl-dev libelf-dev make bc
make -j 12 KCONFIG_CONFIG=Microsoft/config-wsl

完成后内核默认在arch/x86/boot/bzImage，参考软爸关于WSL2全局配置的官方文档，首先在虚拟机里建个/etc/wsl.conf，加两行配置把systemd打开，让它更像个Linux：

[boot]
systemd=true

然后在Windows用户文件夹根目录中建个.wslconfig文件，加几行配置加载自定义内核：

# Settings apply across all Linux distros running on WSL 2
[wsl2]

# Specify a custom Linux kernel to use with your installed distros. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernel
kernel=C:\\<path-to-kernel>\\bzImage

此时wsl --shutdown关闭WSL2，等一小会再打开，uname -a看内核时间编译时间就能发现已经用上咱新鲜出炉还冒着热气的内核了。再用iptables -m string --help试一下发现不报错了，这些软件正常工作之后，jupyter里面用OpenAI的API示例测试取一下模型列表就能正常返回了。

import os
import openai
openai.api_key = "your-api-key"
openai.Model.list()

0x01 策划

chatgpt用我手里现有的工具真的不好访问，经常就是access denied，即使用某瓦工在洛杉矶的VPS依然是黑名单，所以就想用API访问。大概的流程就是：

浏览器访问云服务器上的某个前端网页
云服务器上的前端网页穿透倒家里的rock5b，OpenAI的API服务端就放在rock5b上，十来瓦的功率24小时开机也不肉疼
rock5b服务端负责拿着API key去OpenAI的API上去聊天结果，再返回给前端

0x02 魔改

我直接在Github上搜OpenAI、ChatBot这些关键词，挑了一个长得顺眼的OpenAIChatBot，作者应该是在API发布早期写了这个项目就去玩别的了，三月初OpenAI更新了专门聊天的API，我就fork这个项目魔改了一下，现在可以用createChatCompletion了。

我直接用这个API替换了原项目里的createCompletion，因为官方建议用聊天模型gpt-3.5-turbo代替原项目里的问答模型text-davinci-003，理由是效果好还便宜。

需要注意的是，对于前端网页，问答模型只需要一问一答，也就是发一个prompt收一个replay并显示即可。而聊天模型需要记录聊天双方的历史对话，并将所有内容发给API，再拿到一个新的聊天回复。

0x03 部署

项目是用nodejs的express写的，前端写好了npm build放在云服务器上就好了，如果有需要可以调一下/assets的绝对/相对路径。
前端访问后端的地址为http://cloud-server/url/to/chat/api/，在NGINX配置里加一个location，url匹配到/url/to/chat/api/，在里面加上proxy_pass http://localhost:<lan-server-port>/;（代理设置参考NGINX入门教程，一个/都不能错-_-）。此时NGINX就能将API转发到云服务器本地的your-lan-server-port端口上了。记得防火墙要把这个端口要打开，但为了安全源可以只写云服务器的公网IP。
用内网穿透（我用的nps，frp之类的工具也完全可以）把云服务器上<lan-server-port>口收到的数据发给家里的rock5b服务端，rock5b的服务端监听0.0.0.0:<lan-server-port>，启动npc连接到云服务器的nps就大功告成。
因为中间的网络有点乱，可以在客户端和服务端加console.log打印看看请求和响应，测试没问题再去掉。

0x04 后记

其实这个fork项目极度简单，就是一收一发两端就完了。如果后期继续开发的话，还可以加上：

显示方面的优化，比如用markdown渲染OpenAI的回复，起码能把代码块弄好看一点
对chat completion回复，目前就是拿到内容贴在网页上，其实可以加上更多细节：
- 显示回复是否因字数限制而中断
- 对token计数，帮助我这种抠门人士精打细算的措辞
- 自定义系统角色，目前的聊天角色是我写死的{"role": "system", "content": "You are a helpful programming assistant"}

其他资料：

这两天稚晖君又发视频了，这次是双足机器人，还能变形成轮式，过于酷炫。立于皓月之边，不弱星光之势。

白嫖甲骨文云，但没有完全白嫖

Sat, 11 Feb 2023 23:33:00 GMT

听说甲骨文云有完全免费的VPS，气急败坏的去白嫖，看到首尔机房的延迟只有60ms果断下手，然后才知道整个棒子的甲骨文云的IP都被屏蔽了才后悔，应该听老人言用美国西海岸的机房。然鹅一切都太迟了，一个用户一张信用卡在免费账户中只能选一个机房，选定离手不能改……后来者看到这里一定要慎重选区呀！

:::caution 仅限技术交流！ :::

主机概况

甲骨文云的免费账户有两种VPS可以选，一种是普通x86的AMD处理器，1CPU/1G的普通机器；另一种是4CPU/24G的ARM机器。虽然提示说首尔和东京机房的ARM资源吃紧，不一定能嫖到，但是我不知道怎么回事蹲到了一个ARM机器，果断开了个机器。开实例的时候记得把私钥存下来，甲骨文云的主机默认ssh禁止用户名密码登录。

用的是Ubuntu 22.04的aarch64版本，甲骨文云的实例创建以后，虽然会给一个公网IP，但是此时还需要：

在下方快速操作中选择将公共子网连接到Internet，一路默认点创建，之后上方面板中的网络安全组就有了ig-quick-action-NSG，编辑这个网络安全组，添加ssh、ICMP等想要的入站规则；
点面板中的子网，然后在安全列表中添加想要的的入站规则。

由于首尔的甲骨文云全部被屏蔽了，只能走某瓦工了。外面的ping能通而且nc端口22也能通，用创建主机时拿到的私钥或在面板下方的控制台连接中拿到的私钥连接主机即可，用户名就在面板中，Ubuntu系统的默认用户名是ubuntu：

ssh -i ~/.ssh/<oracle-cloud.key> ubuntu@<vps-ip-address>

查看机器的硬件还是相当给力的，lscpu和lsmem表示确实有4CPU/24G。甲骨文云在ARM机器的免费策略是，每月给CPU了3000小时，给内存了18000G小时，也就是31*24*4=2976和31*24*24=17865，所以理论上这个配置就是永久免费。这硬件跑点大应用应该不难。

sudo apt update && sudo apt dist-upgrade -y
sudo apt install zsh 
sudo chsh -s $(which zsh)
sudo sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# /etc/ssh/sshd_config 中：
# 调整ssh会话一次存活60秒，自动重连60次
ClientAliveInterval 60
ClientAliveCountMax 60

开防火墙策略：

sudo ufw allow 22/tcp comment ssh
sudo ufw allow 443/tcp comment https
sudo ufw allow 80/tcp comment http
sudo ufw enable

安装docker

按照这篇文章一次安装完成：

更新，安装依赖：

# update software repositories
sudo apt update
# install necessary packages for https apt calls
sudo apt install apt-transport-https ca-certificates curl gnupg-agent software-properties-common

使用Ubuntu构建的Armbian添加如下gpg秘钥：

# add docker GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
# add docker software repository
sudo add-apt-repository "deb [arch=arm64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

**（跳过）**使用Debian构建的Armbian添加如下gpg秘钥：

# add docker GPG key
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
# add docker software repository
sudo add-apt-repository "deb [arch=arm64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"

安装docker：

# install docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io
# start docker service
sudo systemctl start docker
# enable docker service on startup
sudo systemctl enable docker
# create a docker group
sudo groupadd docker
# add the current user to the docker group
sudo usermod -aG docker $USER

使用hello-world镜像测试安装结果：

sudo docker run hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
7050e35b49f5: Pull complete
Digest: sha256:faa03e786c97f07ef34423fccceeec2398ec8a5759259f94d99078f264e9d7af
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/

For more examples and ideas, visit:
https://docs.docker.com/get-started/

对Rust生命周期的一些常见误解

Sat, 24 Dec 2022 16:45:00 GMT

:::note 本文内容大多翻译自原文：Common Rust Lifetime Misconceptions。 :::

概述

文中列出的这些误解都是我曾经以为正确的概念，我也看到现在仍有许多初学者都因为这些误解而苦苦挣扎。文中的一些术语可能不标准，我列了一张表，以解释我在文中使用某些短语时原本想表达的意思。

短语	解释
`T`	1) 包含所有可能类型的集合或<br>2) 该集合中的某种类型
自有类型	某些非引用类型，如`i32`、`String`、`Vec`等
1) 借用类型或<br>2) 引用类型	某些引用类型，可变或不可变均可，如`&i32`、`&mut i32`等
1) 可变借用或<br>2) 互斥借用	排他可变引用，如`&mut T`
1) immut ref or<br>2) shared ref	shared immutable reference, i.e. `&T`

概念误解

总的来说，一个变量的生命周期是指：该变量指向的数据在其当前的内存地址中，能被编译器静态验证为有效的时间。下面将用6500字的篇幅来详细说明大家通常会混淆的地方。

1) `T`只包含自有类型

这种误解更多的是关于泛型，而是不关于生命周期，但是泛型和生命周期在Rust中紧密的交织在一起，所以不可能在谈论一个的时候不提及另一个。总之：

当我刚开始学习Rust时，我明白i32、&i32和&mut i32是不同的类型。我也明白一些泛型变量T代表了一个包含所有可能类型的集合。然而，尽管我分别理解了这两个概念，但我并不能把它们放在一起理解。在我的新手Rust大脑中，我认为泛型是这样工作的：


类型变量	`T`	`&T`	`&mut T`
示例	`i32`	`&i32`	`&mut i32`

T包含所有自有类型。&T包含所有不可变借用类型。&mut T包含所有可变借用类型。T、&T和&mut T是互不相交的有限集合很好，简单，干净，容易，直观，但这是完全错误的理解。Rust中的泛型实际上是这样工作的：


类型变量	`T`	`&T`	`&mut T`
示例	`i32`， `&i32`, `&mut i32`, `&&i32`, `&mut &mut i32`, ...	`&i32`, `&&i32`, `&&mut i32`, ...	`&mut i32`, `&mut &mut i32`, `&mut &i32`, ...

T、&T和&mut T均为无限集合，因为我们可以无限地借用一个类型。T是&T和&mut T的超集。而&T和&mut T是互斥集合。下面用几个例子验证这些概念：

trait Trait {}

impl<T> Trait for T {}

impl<T> Trait for &T {} // ❌

impl<T> Trait for &mut T {} // ❌

上面的程序并不能通过编译：

error[E0119]: conflicting implementations of trait `Trait` for type `&_`:
 --> src/lib.rs:5:1
  |
3 | impl<T> Trait for T {}
  | ------------------- first implementation here
4 |
5 | impl<T> Trait for &T {}
  | ^^^^^^^^^^^^^^^^^^^^ conflicting implementation for `&_`

error[E0119]: conflicting implementations of trait `Trait` for type `&mut _`:
 --> src/lib.rs:7:1
  |
3 | impl<T> Trait for T {}
  | ------------------- first implementation here
...
7 | impl<T> Trait for &mut T {}
  | ^^^^^^^^^^^^^^^^^^^^^^^^ conflicting implementation for `&mut _`

编译器不允许我们为&T和&mut T实现Trait，因为这会与T的Trait实现冲突，后者已经包括了&T和&mut T的所有内容。下面的程序可以通过编译，因为&T和&mut T互斥：

trait Trait {}

impl<T> Trait for &T {}  // ✅

impl<T> Trait for &mut T {}  // ✅

主要结论

T是&T和&mut T的超集
&T和&mut T是互斥集合

2) 如果`T: 'static`，则`T`在程序整个生命周期都有效

误解的推论

T: 'static应该读作“T具有'static的生命周期”
&'static T与T: 'static是一回事
如果有T: 'static，则T一定是不可变的
如果有T: 'static，则T只能在编译期创建

大多数Rust初学者第一次接触到'static生命周期，是在一个类似这样的代码示例中：

fn main() {
    let str_literal: &'static str = "str literal";
}

他们被告知"str literal"是被硬编码到编译好的二进制文件中的，并且在运行时被加载到只读存储器中，所以它是不可变的，在整个程序的生命周期中都有效，这就是它'static的含义。这些观念通过使用static关键字定义static变量的规则得到了进一步加强。

// 注意：这个理智纯粹是为了说明问题。
// 永远不要使用`static mut`这种别扭的变量。
// 在Rust中，有一些安全的全局可变单例模式，
// 但这些不在本文的讨论范围之内。

static BYTES: [u8; 3] = [1, 2, 3];
static mut MUT_BYTES: [u8; 3] = [1, 2, 3];

fn main() {
    MUT_BYTES[0] = 99; // ❌ - 修改静态变量是非安全的

    unsafe {
        MUT_BYTES[0] = 99;
        assert_eq!(99, MUT_BYTES[0]);
    }
}

关于static变量

只能在编译期期创建
应该是不可变的，修改静态变量是非安全的
在整个程序的生命周期中都有效

'static生命周期可能是根据static变量的默认生命周期来命名的，对吧？所以'static生命周期遵循static变量相同的规则是很合理的，对吧？

也对，但是具有'static生命周期的类型与受到'static生命周期约束的类型是不同的。后者可以在运行时动态分配、可以安全的在任何地方修改、可以被析构，而且其生命周期可以持续任意的时间。

在这一点上，将&'static T与T: 'static区分开很重要。

&'static T是对某个T的不可变引用，可以安全的持有无限长时间，包括持有到程序结束。但这只有在T本身是不可变的且在引用被创建后没有移动时才可以。T并不一定要在编译期创建。以内存泄漏为代价，在运行时生成随机的动态分配的数据再返回其'static引用，也是可行的，例如：

use rand;

// 在运行时生成随机的'static str引用
fn rand_str_generator() -> &'static str {
    let rand_string = rand::random::<u64>().to_string();
    box::leak(rand_string.into_boxed_str())
}

T: 'static是一种可以安全的无限期持有的T，包括持有到程序结束。T: 'static包括所有的&'static T，此外还包括所有的自有类型，比如String、Vec等。一些数据的持有者被保证，只要所有者持有数据，数据就不会失效，因此所有者可以安全地无限期地持有数据，包括持有到程序结束。T: 'static应该读作“T受到'static生命周期约束”，而不是“T具有'static生命周期”。用一个程序来帮助解释这一概念：

use rand;

fn drop_static<T: 'static>(t: T) {
    std::mem::drop(t);
}

fn main() {
    let mut strings: Vec<String> = Vec::new();
    for _ in 0..10 {
        if rand::random() {
            // 所以字符串都是随机生成且在运行时动态分配的
            let string = rand::random::<u64>().to_string();
            strings.push(string);
        }
    }

    // 字符串为自有类型，因此受到'static约束
    for mut string in strings {
        // 所有字符串均可变
        string.push_str("a mutation");
        // 所有字符串均可析构
        drop_static(string);
    }

    // 所有字符串在程序结束前均已失效
    println!("I am the end of program");
}

主要结论

T: 'static应读作“T受到'static生命周期约束”
如果有T: 'static，则T可以是一个具有'static生命周期的借用类型或一个自有类型
因为T: 'static包括自有类型，这意味着T：
- 可以在运行时被动态的分配
- 不需要在程序的生命周期中始终有效
- 可以安全、自由的修改
- 可以在运行时动态的析构
- 可以有不同持续时间的生命周期

3) `&'a T`与`T: 'a`是一回事

这条误解是上一条误解的泛化版本。

&'a T要求并暗指T: 'a，因为如果T本身在生命周期'a上是无效的，那么以'a为生命周期的T的引用在生命周期'a上自然也是无效的。例如，Rust编译器不允许构造&'static Ref<'a, T>类型，因为如果Ref只在'a上有效，我们就不能对它使用'static引用。

T: 'a包括所有的&'a T，但反过来就不是这样了。

// 只接受受到'a约束的类型的引用
fn t_ref<'a, T: 'a>(t: &'a T) {}

// 接受任意受到'a约束的类型
fn t_bound<'a, T: 'a>(t: T) {}

// 包含一个引用的自有类型
struct Ref<'a, T: 'a>(&'a T);

fn main() {
    let string = String::from("string");

    t_bound(&string); // ✅
    t_bound(Ref(&string)); // ✅
    t_bound(&Ref(&string)); // ✅

    t_ref(&string); // ✅
    t_ref(Ref(&string)); // ❌ - 期待收到一个引用，但实际收到一个结构体
    t_ref(&Ref(&string)); // ✅

    // string var is bounded by 'static which is bounded by 'a
    // 字符串变量受到'static约束，即受到'a约束
    t_bound(string); // ✅
}

主要结论

T: 'a比&'a T更通用也更灵活
T: 'a接受自有类型、包含引用的自有类型以及引用
&'a T只接受引用
如果有T: 'static，那么T: 'a，因为'static >= 所有的'a

4) 我的代码没有泛型也没有生命周期

误解的推论

可以避免使用泛型和生命周期

这一令人欣慰的误解之所以能够继续存在，要感谢Rust的生命周期省略规则，它允许我们在函数中省略生命周期注释，因为Rust的借用检查器会按照这些规则来推断生命周期：

对于一个函数，每个输入的引用参数都具有不同的生命周期
如果有且只有一个输入的生命周期，则所有输出的引用都将应用该生命周期
如果有多个输入的生命周期，但其中一个是&self或&mut self，则所有输出的引用都将应用self的生命周期
否则就必须明确输出生命周期

这么多规则很难一下就弄明白，我们来看几个例子：

// 省略
fn print(s: &str);

// 展开为
fn print<'a>(s: &'a str);

// 省略
fn trim(s: &str) -> &str;

// 展开为
fn trim<'a>(s: &'a str) -> &'a str;

// 错误，因为没有输入，无法确定输出的生命周期
fn get_str() -> &str;

// 展开的选项包括
fn get_str<'a>() -> &'a str; // 泛型版本
fn get_str() -> &'static str; // 'static版本

// 错误，因为有多个输入，无法确定输出的生命周期
fn overlap(s: &str, t: &str) -> &str;

// 展开（依然有部分省略）的选项包括
fn overlap<'a>(s: &'a str, t: &str) -> &'a str; // 输出的有效期不能超过s
fn overlap<'a>(s: &str, t: &'a str) -> &'a str; // 输出的有效期不能超过t
fn overlap<'a>(s: &'a str, t: &'a str) -> &'a str; // 输出的有效期不能超过s和t
fn overlap(s: &str, t: &str) -> &'static str; // 输出的有效期可以超过s和t
fn overlap<'a>(s: &str, t: &str) -> &'a str; // 输出的生命周期与输入无关

// 展开为
fn overlap<'a, 'b>(s: &'a str, t: &'b str) -> &'a str;
fn overlap<'a, 'b>(s: &'a str, t: &'b str) -> &'b str;
fn overlap<'a>(s: &'a str, t: &'a str) -> &'a str;
fn overlap<'a, 'b>(s: &'a str, t: &'b str) -> &'static str;
fn overlap<'a, 'b, 'c>(s: &'a str, t: &'b str) -> &'c str;

// 省略
fn compare(&self, s: &str) -> &str;

// 展开为
fn compare<'a, 'b>(&'a self, &'b str) -> &'a str;

如果你曾写过

一个结构体方法
一个接受多个引用的函数
一个返回多个引用的函数
一个泛型函数
一个trait对象（后文会有更多介绍）
一个闭包（后文会有更多介绍）

那么你的代码中就充满了省略的生命周期注释。

主要结论

几乎所有的Rust代码都是泛型代码，到处都有被省略的生命周期注释。

5) 如果代码通过编译，就说明我们的生命周期注释是正确的

误解的推论

Rust函数的生命周期省略规则总是正确
Rust的借用检查器在技术上和语义上总是正确
Rust比我更了解我的程序的语义

Rust程序即使在技术上可以通过编译，但在语义上仍然有可能是错误的。例如：

struct ByteIter<'a> {
    remainder: &'a [u8]
}

impl<'a> ByteIter<'a> {
    fn next(&mut self) -> Option<&u8> {
        if self.remainder.is_empty() {
            None
        } else {
            let byte = &self.remainder[0];
            self.remainder = &self.remainder[1..];
            Some(byte)
        }
    }
}

fn main() {
    let mut bytes = ByteIter { remainder: b"1" };
    assert_eq!(Some(&b'1'), bytes.next());
    assert_eq!(None, bytes.next());
}

ByteIter是一个迭代字节片的迭代器。为了简洁起见，我们跳过了Iterator trait实现。它似乎能够正常工作，但如果我们想同时检查几个字节会怎样？

fn main() {
    let mut bytes = ByteIter { remainder: b"1123" };
    let byte_1 = bytes.next();
    let byte_2 = bytes.next();
    if byte_1 == byte_2 { // ❌
        // do something
    }
}

呕吼！编译错误：

error[E0499]: cannot borrow `bytes` as mutable more than once at a time
  --> src/main.rs:20:18
   |
19 |     let byte_1 = bytes.next();
   |                  ----- first mutable borrow occurs here
20 |     let byte_2 = bytes.next();
   |                  ^^^^^ second mutable borrow occurs here
21 |     if byte_1 == byte_2 {
   |        ------ first borrow later used here

我想我们可以复制每个字节。当我们处理字节时复制当然是可以的，但是如果我们将ByteIter变成一个通用的切片迭代器，它可以迭代任何&'a [T]，然后我们可能希望在未来使用它来处理那些复制/克隆成本很高，甚至是不可能复制的类型。好吧，我想我们对此无能为力。所以代码能通过编译，生命周期注释就一定正确吗？

不，当前的生命周期注释实际上是错误的来源！它特别难以发现，因为错误的生命周期注释被省略了。让我们声明省略的生命周期以更清楚地了解问题：

struct ByteIter<'a> {
    remainder: &'a [u8]
}

impl<'a> ByteIter<'a> {
    fn next<'b>(&'b mut self) -> Option<&'b u8> {
        if self.remainder.is_empty() {
            None
        } else {
            let byte = &self.remainder[0];
            self.remainder = &self.remainder[1..];
            Some(byte)
        }
    }
}

这并没有帮助，我们依然很困惑。这里有一个只有Rust专家知道的奇技淫巧：为你的生命周期注释提供描述性名称。让我们再试一次：

struct ByteIter<'remainder> {
    remainder: &'remainder [u8]
}

impl<'remainder> ByteIter<'remainder> {
    fn next<'mut_self>(&'mut_self mut self) -> Option<&'mut_self u8> {
        if self.remainder.is_empty() {
            None
        } else {
            let byte = &self.remainder[0];
            self.remainder = &self.remainder[1..];
            Some(byte)
        }
    }
}

每个返回的字节都注释为'mut_self，但这些字节显然来自'remainder！让我们修复这个问题。

struct ByteIter<'remainder> {
    remainder: &'remainder [u8]
}

impl<'remainder> ByteIter<'remainder> {
    fn next(&mut self) -> Option<&'remainder u8> {
        if self.remainder.is_empty() {
            None
        } else {
            let byte = &self.remainder[0];
            self.remainder = &self.remainder[1..];
            Some(byte)
        }
    }
}

fn main() {
    let mut bytes = ByteIter { remainder: b"1123" };
    let byte_1 = bytes.next();
    let byte_2 = bytes.next();
    std::mem::drop(bytes); // 我们甚至可以在此处析构迭代器！
    if byte_1 == byte_2 { // ✅
        // do something
    }
}

现在我们回过头来看前一个版本的程序，它错的错误非常明显，那为什么Rust会让它通过编译呢？答案很简单：它是内存安全的。

Rust借用检查器只关心程序中的生命周期注释，它仅使用这些注释来对程序的内存安全性进行静态验证。即使生命周期注释存在语义错误，Rust仍会愉快地编译程序，其结果是使程序受到不必要的限制。

下面是一个与上面相反的简单示例：Rust的生命周期省略规则在这个实例中恰好是语义正确的，但我们无意中编写了一个非常严格的方法，其中包含我们显式声明的不必要的生命周期注释。

#[derive(Debug)]
struct NumRef<'a>(&'a i32);

impl<'a> NumRef<'a> {
    // 我们的结构体以为'a泛型，这是否意味着我需要将self参数也注释为'a？
    // （答案：并不是）
    fn some_method(&'a mut self) {}
}

fn main() {
    let mut num_ref = NumRef(&5);
    num_ref.some_method(); // 可变借用num_ref直到其生命周期结束
    num_ref.some_method(); // ❌
    println!("{:?}", num_ref); // ❌
}

如果有结构体以'a为泛型，我们几乎不会想编写一个接受参数&'a mut self的方法。我们想告诉Rust的是“此方法将在结构体的整个生命周期内可变地借用该结构体”。实际上，这意味着Rust的借用检查器最多只允许调用一次some_method，然后该结构体将成为永久的可变借用，并因此无法再次使用。这种用例非常少见，但困惑的初学者很可能写出上面这种代码，而且还能通过编译。解决方法是不添加不必要的显式生命周期注释，交给Rust的生命周期省略规则处理：

#[derive(Debug)]
struct NumRef<'a>(&'a i32);

impl<'a> NumRef<'a> {
    // 不再给mut self添加'a注释
    fn some_method(&mut self) {}

    // 上面的方法实际上是：
    fn some_method_desugared<'b>(&'b mut self){}
}

fn main() {
    let mut num_ref = NumRef(&5);
    num_ref.some_method();
    num_ref.some_method(); // ✅
    println!("{:?}", num_ref); // ✅
}

主要结论

Rust函数的生命周期省略规则并不适用于所有情况
Rust并不比你更了解你程序的语义
给你的生命周期注解起描述性的名字
注意显式生命生命周期注释的位置以及原因

6) box指针中的trait对象没有生命周期概念

之前我们讨论了Rust的函数生命周期省略规则，当然，Rust也有针对特征对象的省略规则，它们是：

如果一个trait对象被用作泛型类型的类型参数，那么它的生命周期约束是从包含的类型中推断出来的
- 如果包含的类型有唯一的生命周期约束，那么就使用它
- 如果包含的类型有多个生命周期约束，那么必须指定一个显式生命周期约束
如果以上均不适用，则
- 如果该trait由唯一的一个生命周期约束定义，则使用该约束
- 如果'static用于任何生命周期约束，则使用'static
- 如果trait没有生命周期约束，那么它的生命周期是通过表达式推断出来的，并且在表达式之外是'static的

虽然上面这些规则听起来非常复杂，但是可以简单的概括为“trait对象的生命周期约束是从上下文中推断出来的”。在查看了一些示例之后，我们将意识到生命周期约束的推断是非常直观的，因此我们无需记住上面这些形式化的规则：

use std::cell::Ref;

trait Trait {}

// 省略
type T1 = Box<dyn Trait>;
//展开，Box<T>对T没有生命周期约束，因此推断为'static
type T2 = Box<dyn Trait + 'static>;

// 省略
impl dyn Trait {}
// 展开为
impl dyn Trait + 'static {}

// 省略
type T3<'a> = &'a dyn Trait;
// 展开，&'a T 要求 T: 'a，因此推断为'a
type T4<'a> = &'a (dyn Trait + 'a);

// 省略
type T5<'a> = Ref<'a, dyn Trait>;
// 展开，Ref<'a, T> 要求 T: 'a，因此推断为'a
type T6<'a> = Ref<'a, dyn Trait + 'a>;

trait GenericTrait<'a>: 'a {}

// 省略
type T7<'a> = Box<dyn GenericTrait<'a>>;
// 展开为
type T8<'a> = Box<dyn GenericTrait<'a> + 'a>;

// 省略
impl<'a> dyn GenericTrait<'a> {}
// 展开为
impl<'a> dyn GenericTrait<'a> + 'a {}

实现trait的具体类型可以有引用，因此它们也有生命周期约束，所以它们对应的trait对象也具有生命周期约束。你也可以直接为显然具有生命周期约束的引用实现trait：

trait Trait {}

struct Struct {}
struct Ref<'a, T>(&'a T);

impl Trait for Struct {}
impl Trait for &Struct {} // 直接为引用类型实现Trait
impl<'a, T> Trait for Ref<'a, T> {} // 为包含引用的类型实现

无论如何，这值得一读，因为当初学者将函数从使用trait对象重构为泛型，或从泛型到使用trait对象时，常常会感到困惑。以这个程序为例：

use std::fmt::Display;

fn dynamic_thread_print(t: Box<dyn Display + Send>) {
    std::thread::spawn(move || {
        println!("{}", t);
    }).join();
}

fn static_thread_print<T: Display + Send>(t: T) { // ❌
    std::thread::spawn(move || {
        println!("{}", t);
    }).join();
}

这段代码将抛出下面的编译错误：

error[E0310]: the parameter type `T` may not live long enough
  --> src/lib.rs:10:5
   |
9  | fn static_thread_print<T: Display + Send>(t: T) {
   |                        -- help: consider adding an explicit lifetime bound...: `T: 'static +`
10 |     std::thread::spawn(move || {
   |     ^^^^^^^^^^^^^^^^^^
   |
note: ...so that the type `[closure@src/lib.rs:10:24: 12:6 t:T]` will meet its required lifetime bounds
  --> src/lib.rs:10:5
   |
10 |     std::thread::spawn(move || {
   |     ^^^^^^^^^^^^^^^^^^

很好，编译期已经告诉我们如何修复问题了：

use std::fmt::Display;

fn dynamic_thread_print(t: Box<dyn Display + Send>) {
    std::thread::spawn(move || {
        println!("{}", t);
    }).join();
}

fn static_thread_print<T: Display + Send + 'static>(t: T) { // ✅
    std::thread::spawn(move || {
        println!("{}", t);
    }).join();
}

现在可以通过编译了，不过这两个函数放在一起看起来很奇怪，为什么第二个函数需要'static约束的T，而第一个函数就不需要？这是一个棘手的问题。应用生命周期省略规则，Rust会自动在第一个函数中推断出'static约束，因此两者实际上都有 'static约束。这是Rust编译器实际看到的：

use std::fmt::Display;

fn dynamic_thread_print(t: Box<dyn Display + Send + 'static>) {
    std::thread::spawn(move || {
        println!("{}", t);
    }).join();
}

fn static_thread_print<T: Display + Send + 'static>(t: T) {
    std::thread::spawn(move || {
        println!("{}", t);
    }).join();
}

主要结论

所有trait对象都具有某些推断的默认生命周期约束

7) 编译器的错误提示会告诉我如何修复程序

误解的推论

Rust对trait对象的生命周期省略规则总是正确的
Rust比我更了解我程序的语义

这种误解结合了前面两种误解，例如：

use std::fmt::Display;

fn box_displayable<T: Display>(t: T) -> Box<dyn Display> { // ❌
    Box::new(t)
}

抛出的错误为：

error[E0310]: the parameter type `T` may not live long enough
 --> src/lib.rs:4:5
  |
3 | fn box_displayable<T: Display>(t: T) -> Box<dyn Display> {
  |                    -- help: consider adding an explicit lifetime bound...: `T: 'static +`
4 |     Box::new(t)
  |     ^^^^^^^^^^^
  |
note: ...so that the type `T` will meet its required lifetime bounds
 --> src/lib.rs:4:5
  |
4 |     Box::new(t)
  |     ^^^^^^^^^^^

让我们按照编译器告诉我们方式来修复问题，它将我们boxed trait的约束自动推断为'static，而它推荐的修复方式就基于这个未声明的事实，虽然编译器没有告诉我们，但无需介意：

use std::fmt::Display;

fn box_displayable<T: Display + 'static>(t: T) -> Box<dyn Display> { // ✅
    Box::new(t)
}

所以程序现在可以通过编译了……但这真的是我们想要的吗？可能是也可能不是。编译器没有提到其他修复，但下面这种也是合适的：

use std::fmt::Display;

fn box_displayable<'a, T: Display + 'a>(t: T) -> Box<dyn Display + 'a> { // ✅
    Box::new(t)
}

此函数接受参数的范围比前面的版本更广！但这会让它变得更好用吗？不一定，要看我们程序的要求和约束。这个例子有点抽象，所以让我们看一个更简单且明显的例子：

fn return_first(a: &str, b: &str) -> &str { // ❌
    a
}

抛出的错误为：

error[E0106]: missing lifetime specifier
 --> src/lib.rs:1:38
  |
1 | fn return_first(a: &str, b: &str) -> &str {
  |                    ----     ----     ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `a` or `b`
help: consider introducing a named lifetime parameter
  |
1 | fn return_first<'a>(a: &'a str, b: &'a str) -> &'a str {
  |                ^^^^    ^^^^^^^     ^^^^^^^     ^^^

错误消息建议使用相同的生命周期注释输入和输出。如果我们这样做，程序的确会通过编译，但这个函数会过度限制返回类型。我们真正想要的是这样的：

fn return_first<'a>(a: &'a str, b: &str) -> &'a str { // ✅
    a
}

主要结论

Rust对trait对象的生命周期省略规则并不总是适用于所有情况
Rust并不比你更了解你程序的语义
Rust编译器的错误消息修复建议能够使你的程序通过编译，但这不一定是使你的程序通过编译的最合适的修复方式

8) 生命周期可以在运行时增长和收缩

误解的推论

容器类型可以在运行时切换引用，以改变它们的生命周期
Rust借用检查器会对程序进行高级控制流分析

这不能通过编译：

struct Has<'lifetime> {
    lifetime: &'lifetime str,
}

fn main() {
    let long = String::from("long");
    let mut has = Has { lifetime: &long };
    assert_eq!(has.lifetime, "long");

    {
        let short = String::from("short");
        // “切换”到short生命周期
        has.lifetime = &short;
        assert_eq!(has.lifetime, "short");

        // “切换回”long生命周期（但实际上并没有）
        has.lifetime = &long;
        assert_eq!(has.lifetime, "long");
        // `short`在此处析构
    }

    assert_eq!(has.lifetime, "long"); // ❌ - `short`在析构之后仍“被借用”
}

这段代码抛出：

error[E0597]: `short` does not live long enough
  --> src/main.rs:11:24
   |
11 |         has.lifetime = &short;
   |                        ^^^^^^ borrowed value does not live long enough
...
15 |     }
   |     - `short` dropped here while still borrowed
16 |     assert_eq!(has.lifetime, "long");
   |     --------------------------------- borrow later used here

下面这段代码也不能通过编译，且与上面的代码抛出的错误完全一致：

struct Has<'lifetime> {
    lifetime: &'lifetime str,
}

fn main() {
    let long = String::from("long");
    let mut has = Has { lifetime: &long };
    assert_eq!(has.lifetime, "long");

    // 虽然这个代码块从不执行
    if false {
        let short = String::from("short");
        // “切换”到short生命周期
        has.lifetime = &short;
        assert_eq!(has.lifetime, "short");

        // “切换回”long生命周期（但实际上并没有）
        has.lifetime = &long;
        assert_eq!(has.lifetime, "long");
        // `short`在此处析构
    }

    assert_eq!(has.lifetime, "long"); // ❌ - `short`在析构之后仍“被借用”
}

Rust中的生命周期必须在编译时静态验证，借用检查器只会进行最基本的控制流分析，所以它假设if-else语句中的每个块和match语句中的每个匹配分支都可以被执行，然后为变量选择可能的最短的生命周期。一旦一个变量被一个生命周期约束，就将永远受到该生命周期的约束。变量的生命周期只能收缩，而所有的收缩都是在编译时决定的。

主要结论

生命周期会在编译期静态验证
生命周期不能在运行时以任何方式增长、收缩或改变
Rust借用检查器将始终为变量选择尽可能短的生命周期，并会假设所有分支代码都能够被执行

9) 将可变引用降级为共享引用是安全的

误解的推论

重新借用一个引用将结束现有的生命周期并开始一个新的生命周期

您可以将可变引用传给期望共享引用的函数，因为Rust会隐式地重新借用这个可变引用并将其变为不可变的共享引用：

fn takes_shared_ref(n: &i32) {}

fn main() {
    let mut a = 10;
    takes_shared_ref(&mut a); // ✅
    takes_shared_ref(&*(&mut a)); // 上一行实际上执行的代码
}

直觉上这是有道理的，因为将一个可变引用重新借用为不可变的应该不会造成什么影响，对吧？令人惊讶的是，实际上并非没有影响，来看下面的程序就无法通过编译：

fn main() {
    let mut a = 10;
    let b: &i32 = &*(&mut a); // re-borrowed as immutable
    let c: &i32 = &a;
    dbg!(b, c); // ❌
}

这段代码抛出如下错误：

error[E0502]: cannot borrow `a` as immutable because it is also borrowed as mutable
 --> src/main.rs:4:19
  |
3 |     let b: &i32 = &*(&mut a);
  |                     -------- mutable borrow occurs here
4 |     let c: &i32 = &a;
  |                   ^^ immutable borrow occurs here
5 |     dbg!(b, c);
  |          - mutable borrow later used here

我们确实进行了可变借用，但它会立即无条件地重新进行不可变借用，然后被丢弃。为什么Rust将不可变的重新借用，仍然视为可变借用的独占生命周期？虽然在上面的特定示例中没有问题，但允许将可变引用降级为共享引用的功能，确实会引入潜在的内存安全问题：

use std::sync::Mutex;

struct Struct {
    mutex: Mutex<String>
}

impl Struct {
    // 将可变self降级为共享str
    fn get_string(&mut self) -> &str {
        self.mutex.get_mut().unwrap()
    }
    fn mutate_string(&self) {
        // 如果Rust允许将可变引用降级为共享引用
        // 则下面这行代码将使从get_string方法返回的任何共享引用无效
        *self.mutex.lock().unwrap() = "surprise!".to_owned();
    }
}

fn main() {
    let mut s = Struct {
        mutex: Mutex::new("string".to_owned())
    };
    let str_ref = s.get_string(); // 可变引用降级为共享引用
    s.mutate_string(); // str_ref将变得无效，产生悬空指针
    dbg!(str_ref); // ❌ - 如我们所料
}

这里的要点是，当你将可变引用重新借用为共享引用时，你不只得到了共享引用还掉进了一个大坑：重新借用还延长了可变引用的生命周期，即使可变引用自身已被析构。使用重新借用的共享引用非常难，因为它不仅不可变，还不能被其他任何共享引用共享。重新借用的共享引用集合了可变引用和共享引用的所有缺点，且并没有得到两者的任一的优点。我认为将可变引用重新借用为共享引用应该被视为Rust反面模式。意识到这种反面模式很重要，这样当您看到这样的代码时就可以很容易地发现它：

// 将可变T降级为共享T
fn some_function<T>(some_arg: &mut T) -> &T;

struct Struct;

impl Struct {
    // 将可变self降级为共享self
    fn some_method(&mut self) -> &Self;

    // 将可变self降级为共享T
    fn other_method(&mut self) -> &T;
}

即使你避免了在函数和方法签名中的重新借用，Rust仍然会自动进行隐式重新借用，所以我们很容易在没有意识到的情况下遇到这种问题：

use std::collections::HashMap;

type PlayerID = i32;

#[derive(Debug, Default)]
struct Player {
    score: i32,
}

fn start_game(player_a: PlayerID, player_b: PlayerID, server: &mut HashMap<PlayerID, Player>) {
    // 从服务器获取玩家，如果玩家不存在则创建或插入新玩家
    let player_a: &Player = server.entry(player_a).or_default();
    let player_b: &Player = server.entry(player_b).or_default();

    // do something with players
    dbg!(player_a, player_b); // ❌
}

上面的代码无法通过编译。or_default()将返回一个&mut Player，我们的显式类型注释将使Rust隐式地重新借用为&Player。所以，正确的写法应该是：

use std::collections::HashMap;

type PlayerID = i32;

#[derive(Debug, Default)]
struct Player {
    score: i32,
}

fn start_game(player_a: PlayerID, player_b: PlayerID, server: &mut HashMap<PlayerID, Player>) {
    // 丢弃返回的可变Player引用，反正我们也不能同时使用它们
    server.entry(player_a).or_default();
    server.entry(player_b).or_default();

    // 重新获取players，这次直接获取其不可变引用，且不带有啊任何隐式重新借用
    let player_a = server.get(&player_a);
    let player_b = server.get(&player_b);

    // do something with players
    dbg!(player_a, player_b); // ✅
}

这么写有点奇怪还很笨拙，但这是我们在内存安全问题上必要的牺牲。

主要结论

尽量不要将可变引用重新借用为共享引用，否则你可能会遇到大麻烦
对可变引用进行重新借用并不会结束它的生命周期，即使该引用已被删除

10) 闭包遵循与函数相同的生命周期省略规则

这与其说是一种误解，不如说是Rust的陷阱。

尽管闭包也是函数，但并不遵循与函数相同的生命周期省略规则。

fn function(x: &i32) -> &i32 {
    x
}

fn main() {
    let closure = |x: &i32| x; // ❌
}

报错：

error: lifetime may not live long enough
 --> src/main.rs:6:29
  |
6 |     let closure = |x: &i32| x;
  |                       -   - ^ returning this value requires that `'1` must outlive `'2`
  |                       |   |
  |                       |   return type of closure is &'2 i32
  |                       let's call the lifetime of this reference `'1`

补全上面代码省略的内容：

// 输入的生命周期应用于输出的生命周期
fn function<'a>(x: &'a i32) -> &'a i32 {
    x
}

fn main() {
    // 输入和输出分别得到了各自不同的生命周期
    let closure = for<'a, 'b> |x: &'a i32| -> &'b i32 { x };
    // 注意：上面一行代码的语法并不合法，我们只是使用它说明情况
}

这种差异没有什么合理的解释。闭包最初是使用与函数不同的类型推断语义实现的，不过我们可能要永远这么用下去了，因为如果现在统一两者的实现将是一个破坏性的更新。那么如何显式地注释闭包呢？我们的选择包括：

fn main() {
    // 若转换为trait对象，占用空间会变得固定，于是产生编译错误
    let identity: dyn Fn(&i32) -> &i32 = |x: &i32| x;

    // 可以分配在堆上，但感觉很笨重
    let identity: Box<dyn Fn(&i32) -> &i32> = Box::new(|x: &i32| x);

    // 可以跳过分配，只创建一个静态引用
    let identity: &dyn Fn(&i32) -> &i32 = &|x: &i32| x;

    // 上面这一行实际上是：
    let identity: &'static (dyn for<'a> Fn(&'a i32) -> &'a i32 + 'static) = &|x: &i32| -> &i32 { x };

    // 这么写是最理想的，但这样的语法是无效的
    let identity: impl Fn(&i32) -> &i32 = |x: &i32| x;

    // 这样写也很理想，但依然是无效语法
    let identity = for<'a> |x: &'a i32| -> &'a i32 { x };

    // `impl trait`只能用在在函数签名的返回值部分
    fn return_identity() -> impl Fn(&i32) -> &i32 {
        |x| x
    }
    let identity = return_identity();

    // 上面版本的泛型化写法
    fn annotate<T, F>(f: F) -> F where F: Fn(&T) -> &T {
        f
    }
    let identity = annotate(|x: &i32| x);
}

你应该已经从上面的示例中注意到了，当闭包类型用作trait约束时，它们确实应用了通常的函数生命周期省略规则。

此处并没有什么教训或启发，Rust现在就是这样。

主要结论

每个编程语言都有些陷阱🤷

结论

T是&T和&mut T的超集
&T和&mut T是互斥集合
T: 'static应读作“T受到'static生命周期约束”
如果有T: 'static，则T可以是一个具有'static生命周期的借用类型或一个自有类型
因为T: 'static包括自有类型，这意味着T：
- 可以在运行时被动态的分配
- 不需要在程序的生命周期中始终有效
- 可以安全、自由的修改
- 可以在运行时动态的析构
- 可以有不同持续时间的生命周期
T: 'a比&'a T更通用也更灵活
T: 'a接受自有类型、包含引用的自有类型以及引用
&'a T只接受引用
如果有T: 'static，那么T: 'a，因为'static >= 所有的'a
几乎所有的Rust代码都是泛型代码，到处都有被省略的生命周期注释。
Rust函数的生命周期省略规则并不适用于所有情况
Rust并不比你更了解你程序的语义
给你的生命周期注解起描述性的名字
注意显式生命生命周期注释的位置以及原因
所有trait对象都具有某些推断的默认生命周期约束
Rust编译器的错误消息修复建议能够使你的程序通过编译，但这不一定是使你的程序通过编译的最合适的修复方式
生命周期会在编译期静态验证
生命周期不能在运行时以任何方式增长、收缩或改变
Rust借用检查器将始终为变量选择尽可能短的生命周期，并会假设所有分支代码都能够被执行
尽量不要将可变引用重新借用为共享引用，否则你可能会遇到大麻烦
对可变引用进行重新借用并不会结束它的生命周期，即使该引用已被删除
每个编程语言都有些陷阱🤷

讨论

讨论这篇文章的地方：

深入阅读

析构2022 - 人可不能太害怕冬天

Sun, 11 Dec 2022 18:53:00 GMT

为啥现在写年终总结呢？因为这不是放开了嘛，昨天连滚带爬的采访了战地一线的防护经验丰富的老西医……

1 年终总结

先写个总结意思一下，今年干的人事：

跟着教程写了个KV数据库，基本了解了Rust的async是怎么运作的；
双十一从闲鱼上买了个优惠券，九百多拿下了16G版本的Rock-5B，四舍五入九百块买了个电脑你说值不值；
把域名和SSL证书彻底弄好了，老老实实把备案什么都做了，买了个最便宜的阿里云做流量中转，延迟非常低，感觉也很值。

非人事：

朝枪夕拾，重拾CSGO，虽然快四十了，端起那杆AWP，还是年轻时候的样子，欢迎kennyS来附体。

2 采访老西医

最近不是放开了么，得自己负责自己的健康了，刚好最近要出差，昨晚突击采访了某美帝排名前十的生物化学系的W教授，精华汇总成文如下。

2.1 tl;dr

<font color="red" size="5em"><b>管好自己带好口罩严防飞沫，把医疗资源让给需要的人。</b></font>

2.2 采访详情

教授首先就美帝三年个人防护经验做了简要介绍。教授有三针腺病毒疫苗护体，三年一共中招一次，是因为孩子在学校没防住，在家被传染。教授在感染的情况下紧急调整防护策略，单人单间三餐由夫人送到门口，不超过十天痊愈，无后遗症，夫人三年保持依然零中招。教授强调，飞沫是危害最大的传播途径，而口罩是最有效的防护手段，当然，独处一个房间关上门也可以隔断，但是只要出门必须戴口罩，尤其是公共场所，一定要带医用N95。

小结：如果不幸中招，立即单间隔离，按症状吃药，三餐送到门口（人离开再开门交接，介意的话吃完的餐具可以放门口等半个小时再收，虽然教授没这样做但建议这样做）；备一个血氧仪（淘宝百十块钱），若降至90就去医院，否则推荐在家别恐慌别折腾，把医疗资源留给更需要的人。

接下来，教授介绍了三年以来生活方式上的改变。首先就是，戴口罩，只要不是在家，只要不是独处，就带上口罩，把每个人都想象成传染源。因此，即使在办公室、食堂餐厅都应该佩戴口罩，有条件的话全程N95。

办公室除了喝水不摘口罩；
食堂餐厅打饭之后一个人找个地方单独就餐，找不到就呆车里；
不主动去人多的地方，实在没办法就全程N95不摘，回家洗澡；
勤洗手勤消毒。

教授认为国内这三年来已经相当幸福了，基本躲过了病毒最具破坏力的时段，之后在宏观层面最重要的就是防挤兑，微观层面最重要的是建立新的生活习惯，毕竟就算是美帝现在也没有完全躺平，坚决不能浪。

教授回忆道，在刚开始那一阵子，他们连厕所都不敢用，一日两餐车里解决少喝水，回家再方便。有别的教授感染了老版本的病毒，歇菜了半年，基本废了；有年轻人反复感染，有的完了有的没事，因人而异，不要赌自己天赋异禀。后来人类了解也多了病毒也弱了，起码上厕所什么的都敢去了。孩子在学校是真的没办法，这种时候就要将风险最小化，即使在同一个屋檐下也完全可以做到让家人全身而退。

小结：戴口罩，能N95就N95，只要不是封闭的单间独处，就一直带着别摘，核心就是防止飞沫传播。

之后，我就近期比较关心的出差问题，尤其是乘坐公共交通工具，如飞机，询问了教授。教授自己三年只做过一次公共交通工具，但是理论上，只要防住飞沫问题应该不大，推荐全程带口罩不摘（不吃喝不上厕所），可以穿雨披，到目的地先洗澡即可，眼罩或面罩有条件可选配。

最后，教授强调了，这玩意绝不是流感那么简单的东西，流感只会破坏上呼吸道的细胞，而这玩意会结合ACE2受体搞出很多花样。教授就自己生病的感受猜测，这玩意结合ACE2受体后会影响血流通量甚至能够间接影响心率，对肉体造成真实伤害，因此决不能掉以轻心。管不了别人就做好自己的防护，降低自己中招的概率，还能把医疗资源留给更需要的人。

我再提一点需要注意的地方，药不能只看名字，吃之前一定要看成分，比如対乙酰氨基酚这种东西可能在一些复方银翘片、抗病毒感冒药中出现，如果多种药混吃容易过量。不必太过恐慌，对症吃药，一次吃一种。

EOF

第一朵阿里云

Sat, 03 Dec 2022 17:32:00 GMT

最近希望有一个私人的流量中转站，即使在办公室也能访问家里的计算和存储，低延迟低流量低配置的乞丐VPS就可以。

抠门的我挑了半天，还是选择了大厂，阿里云成都分云，这次不用红帽系了，因为最近一直在Debian、Ubuntu和Armbian。

初始化

首次登录好习惯改密码（为了方便，应该把zsh、git、oh-my-zsh、vim、tmux、aria2c装上。）：

# VPS上改密码
passwd
# 修改主机名，阿里云默认的太丑了
sudo hostnamectl set-hostname aliyun.mydomain.tech
# 电脑上上传秘钥进行ssh免密登录，要指定秘钥则`ssh-copy-id -i ~/.ssh/id_rsa.pub root@4*.*.*.*`
ssh-copy-id root@4*.*.*.*

sudo apt update && sudo apt dist-upgrade -y
sudo apt install build-essential curl file git -y
sudo apt install zsh git vim tmux aria2
chsh -s $(which zsh)
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# 安装oh-my-tmux，github不通时，可以用gitclone先顶一下
cd ~
git clone https://gitclone.com/github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf
cp .tmux/.tmux.conf.local .

将ssh设置为无法用密码登录（只接受key pair认证），顺便调整ssh超时时间：

# /etc/ssh/sshd_config 中：
# 禁止密码认证
PasswordAuthentication no
# 调整ssh会话一次存活60秒，自动重连60次
ClientAliveInterval 60
ClientAliveCountMax 60

# 重启sshd服务：
sudo systemctl restart ssh.service

开防火墙策略：

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment ssh
sudo ufw allow 6800/tcp comment aria2c
sudo ufw allow 2017/tcp comment v2raya
sudo ufw enable

**注意：**若端口已经打开，使用nc检测端口发现公网IP（即4x.x.x.x）的端口不通，而内网IP（即172.x.x.x）端口正常。则需要在云服务器ESC->网络与安全->安全组里添加端口。

开启虚拟内存：

# 检查虚拟内存十分开启：
free -m
# 分配虚拟内存文件的空间，大小为 bs*count
sudo dd if=/dev/zero of=/swapfile bs=1024 count=1048576
# 设置文件权限
chmod 600 /swapfile
# 制作虚拟内存分区
mkswap /swapfile
# 激活虚拟内存
swapon /swapfile
# 此时检查就会有虚拟内存了
free -m
# 要一直使用的话，更改开机挂载虚拟内存
vim /etc/fstab
/swapfile swap swap defaults 0 0

# 检测swappiness值，即系统使用交换空间的优先级，默认为60即可，刚装好的阿里云为0
cat /proc/sys/vm/swappiness
# 临时修改
sysctl vm.swappiness=60
# 永久修改
vim /etc/sysctl.conf
vm.swappiness=60

安装科学冲浪

安装核心，如果install-release.sh不能下载，可以直接浏览器打开复制粘贴，然后chmod +x install-release.sh，运行即可：

# 安装或更新核心
sudo bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
# 仅更新核心
sudo bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install-geodata
# 卸载核心
sudo bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ remove

sudo systemctl status xray.service

安装UI，直接在release中挑了一个arm64的包。如果实在下不下来，就scp ./installer_debian_amd64_1.5.9.1698.1.deb root@47.109.18.231:./传一个上去吧，或者传到哪个没被ban的公网服务器上下载也行。

wget https://github.com/v2rayA/v2rayA/releases/download/v1.5.9.1698.1/installer_debian_amd64_1.5.9.1698.1.deb
sudo apt install ./installer_debian_arm64_1.5.9.1698.1.deb
# 可以添加为系统服务
sudo systemctl enable v2raya.service
sudo systemctl start v2raya.service
sudo systemctl status v2raya.service

配置aira2c

配置aria2c远程下载服务，本地使用AriaNg搭配风味更佳：

mkdir -p ~/.config/aria2
touch ~/.config/aria2/aria2.conf       #aria2的配置文件
touch ~/.config/aria2/aria2.session    #aria2保存会话的文件
vim ~/.config/aria2/aria2.conf         #修改配置文件

配置如下：

## '#'开头为注释内容, 选项都有相应的注释说明, 根据需要修改 ##
## 被注释的选项填写的是默认值, 建议在需要修改时再取消注释  ##

## 文件保存相关 ##

# 文件的保存路径(可使用绝对路径或相对路径), 默认: 当前启动位置
dir=/webroot/downloads
# 启用磁盘缓存, 0为禁用缓存, 需1.16以上版本, 默认:16M
#disk-cache=32M
# 文件预分配方式, 能有效降低磁盘碎片, 默认:prealloc
# 预分配所需时间: none < falloc ? trunc < prealloc
# falloc和trunc则需要文件系统和内核支持
# NTFS建议使用falloc, EXT3/4建议trunc, MAC 下需要注释此项
#file-allocation=none
# 断点续传
continue=true

## 下载连接相关 ##

# 最大同时下载任务数, 运行时可修改, 默认:5
#max-concurrent-downloads=5
# 同一服务器连接数, 添加时可指定, 默认:1
max-connection-per-server=16
# 最小文件分片大小, 添加时可指定, 取值范围1M -1024M, 默认:20M
# 假定size=10M, 文件为20MiB 则使用两个来源下载; 文件为15MiB 则使用一个来源下载
min-split-size=4M
# 单个任务最大线程数, 添加时可指定, 默认:5
split=16
# 整体下载速度限制, 运行时可修改, 默认:0
max-overall-download-limit=3000000
# 单个任务下载速度限制, 默认:0
#max-download-limit=0
# 整体上传速度限制, 运行时可修改, 默认:0
max-overall-upload-limit=50000
# 单个任务上传速度限制, 默认:0
#max-upload-limit=0
# 禁用IPv6, 默认:false
disable-ipv6=true
# 连接超时时间, 默认:60
#timeout=60
# 最大重试次数, 设置为0表示不限制重试次数, 默认:5
#max-tries=5
# 设置重试等待的秒数, 默认:0
#retry-wait=0

## 进度保存相关 ##

# 从会话文件中读取下载任务
input-file=/root/.config/aria2/aria2.session
# 在Aria2退出时保存`错误/未完成`的下载任务到会话文件
save-session=/root/.config/aria2/aria2.session
# 定时保存会话, 0为退出时才保存, 需1.16.1以上版本, 默认:0
save-session-interval=60

## RPC相关设置 ##

# 启用RPC, 默认:false
enable-rpc=true
# 允许所有来源, 默认:false
rpc-allow-origin-all=true
# 允许非外部访问, 默认:false
rpc-listen-all=true
# 事件轮询方式, 取值:[epoll, kqueue, port, poll, select], 不同系统默认值不同
#event-poll=select
# RPC监听端口, 端口被占用时可以修改, 默认:6800
rpc-listen-port=6800
# 设置的RPC授权令牌, v1.18.4新增功能, 取代 --rpc-user 和 --rpc-passwd 选项
rpc-secret=<your-rpc-secret>
# 设置的RPC访问用户名, 此选项新版已废弃, 建议改用 --rpc-secret 选项
#rpc-user=<USER>
# 设置的RPC访问密码, 此选项新版已废弃, 建议改用 --rpc-secret 选项
#rpc-passwd=<PASSWD>
# 是否启用 RPC 服务的 SSL/TLS 加密,
# 启用加密后 RPC 服务需要使用 https 或者 wss 协议连接
#rpc-secure=true
# 在 RPC 服务中启用 SSL/TLS 加密时的证书文件,
# 使用 PEM 格式时，您必须通过 --rpc-private-key 指定私钥
#rpc-certificate=/path/to/certificate.pem
# 在 RPC 服务中启用 SSL/TLS 加密时的私钥文件
#rpc-private-key=/path/to/certificate.key

## BT/PT下载相关 ##

# 当下载的是一个种子(以.torrent结尾)时, 自动开始BT任务, 默认:true
follow-torrent=true
# BT监听端口, 当端口被屏蔽时使用, 默认:6881-6999
listen-port=51414
# 单个种子最大连接数, 默认:55
#bt-max-peers=55
# 打开DHT功能, PT需要禁用, 默认:true
enable-dht=true
# 打开IPv6 DHT功能, PT需要禁用
#enable-dht6=false
# DHT网络监听端口, 默认:6881-6999
dht-listen-port=6881-6999
# 本地节点查找, PT需要禁用, 默认:false
bt-enable-lpd=true
# 种子交换, PT需要禁用, 默认:true
enable-peer-exchange=true
# 每个种子限速, 对少种的PT很有用, 默认:50K
bt-request-peer-speed-limit=3M
# 客户端伪装, PT需要
peer-id-prefix=-TR2770-
user-agent=Transmission/2.77
peer-agent=Transmission/2.77
# 当种子的分享率达到这个数时, 自动停止做种, 0为一直做种, 默认:1.0
seed-ratio=1.0
seed-time=0
# 强制保存会话, 即使任务已经完成, 默认:false
# 较新的版本开启后会在任务完成后依然保留.aria2文件
#force-save=false
# BT校验相关, 默认:true
#bt-hash-check-seed=true
# 继续之前的BT任务时, 无需再次校验, 默认:false
bt-seed-unverified=true
# 保存磁力链接元数据为种子文件(.torrent文件), 默认:false
bt-save-metadata=false
# dht-file
dht-file-path=/root/.config/aria2/dht.dat
# 删除未选择的文件
bt-remove-unselected-file=true
# 无速度时自动停止时间
#bt-stop-timeout=1800

启动aria2c：

aria2c --conf-path=$HOME/.config/aria2/aria2.conf -D

安装nps内网穿透服务端

小可怜服务器没多少空间舍不得安装golang，直接从release列表中下载相应的二进制运行：

wget https://github.com/ehang-io/nps/releases/download/v0.26.10/linux_amd64_server.tar.gz
tar -zxvf linux_amd64_server.tar.gz -C linux_amd64_server
sudo ./nps install
# 安装完成后支持的命令：`nps start|stop|restart|uninstall|update or nps-update update`
sudo nps start

修改配置文件/etc/nps/conf/nps.conf的用户名和密码，以及默认的http和https监听，这台VPS我用打算用来中转流量，所以80和443打算暂时留给nginx：

# ...
web_username=xxx
web_password=xxx
# ...
#http_proxy_port=80
#https_proxy_port=443
# ...

查看日志cat /var/log/nps.log：

2022/12/03 19:28:15.920 [I] [nps.go:202]  the version of server is 0.26.10 ,allow client core version to be 0.26.0
2022/12/03 19:28:16.496 [I] [server.go:200]  tunnel task  start mode：httpHostServer port 0
2022/12/03 19:28:16.496 [I] [connection.go:71]  web management start, access port is 8080
2022/12/03 19:28:16.508 [I] [connection.go:36]  server start, the bridge type is tcp, the bridge port is 8024

在内网Rock-5B上下载客户端：

wget https://github.com/ehang-io/nps/releases/download/v0.26.10/linux_arm64_client.tar.gz

或是在内网树莓派3B+上下载客户端：

wget https://github.com/ehang-io/nps/releases/download/v0.26.10/linux_arm_v7_client.tar.gz

按照说明添加一个客户端，并在树莓派上尝试连接nps服务器：

./npc -server=4x.x.x.x:8024 -vkey=xxxxxxx -type=tcp

此时刷新nps管理页面，客户端已显示线了。在管理页面的TCP隧道中加一条端口映射，就可以从电脑上连接ssh -p 10022 pi@4x.x.x.x了。

自动续期SSL证书

教程，我希望用4*服务器上的nps，将443映射给内网120服务器的443端口，并使得证书能够正常验证。

此时我使用apt update后，apt报错，很明显mirrors.cloud.aliyuncs.com这个地址指向我的Justhost服务器了，ping也是直接被解析成了ping mirrors.cloud.aliyuncs.com.mydomain.tech，此时dig、nslookup都不行，但resolvectl query mirrors.cloud.aliyuncs.com仍然正常。我查了ping命令，有文章说ping的解析靠/etc/nsswitch中host项目的配置，于是我改/etc/nsswitch、/etc/hosts都不行。然后搜索这个域名发现有的文章说，需要修改/etc/hosts：

# 这一组不行，v2rayA DNS hijack，这是v2rayA开启时注入的
#nameserver 127.2.0.17
#nameserver 119.29.29.29
# 这一组不行，这是v2rayA关闭后改回来的
#nameserver 223.6.6.6
#nameserver 119.29.29.29
# 这一组公共DNS也不行
#nameserver 8.8.8.8
#nameserver 114.114.114.114
# 这一组使得`mirrors.cloud.aliyuncs.com`恢复
# 即这个域名需要阿里云vpc下dns才能解析
nameserver 100.100.2.136
nameserver 100.100.2.138

申请SSL证书，

# 安装acme.sh，末尾的`-s email=xxx@xxx.com是用来接受let's encrypt等更新邮件的地址
curl https://get.acme.sh | sh -s email=xxx@xxx.com
# 如果使用standalone模式，acme.sh会需要socat在80或443上建立服务
sudo apt install socat

# 重载shell以生效
source ~/.zshrc
# 验证安装
acme.sh -v
https://github.com/acmesh-official/acme.sh
v3.0.5
# 另外，acme.sh已经将默认CA设置为ZeroSSL，如果要用let's encrypt需要指定服务，
# ZeroSSL只支持http-01 dns-01，不支持tls-alpn-01
acme.sh --set-default-ca --server letsencrypt
# 默认使用443端口，如果要修改需要指定`--httpport 8443`
# 使用前记得停掉443上的进程，比如nps
acme.sh --issue -d aliyun.mydomain.tech --alpn
[Sat Dec  3 09:13:38 PM CST 2022] Your cert is in: /root/.acme.sh/aliyun.mydomain.tech/aliyun.mydomain.tech.cer
[Sat Dec  3 09:13:38 PM CST 2022] Your cert key is in: /root/.acme.sh/aliyun.mydomain.tech/aliyun.mydomain.tech.key
[Sat Dec  3 09:13:38 PM CST 2022] The intermediate CA cert is in: /root/.acme.sh/aliyun.mydomain.tech/ca.cer
[Sat Dec  3 09:13:38 PM CST 2022] And the full chain certs is there: /root/.acme.sh/aliyun.mydomain.tech/fullchain.cer
#申请成功后，查看已申请的证书信息
acme.sh --info -d aliyun.mydomain.tech

安装证书到nginx：

acme.sh --install-cert -d aliyun.mydomain.tech \
--key-file       /etc/nginx/aliyun.mydomain.tech/key.pem  \
--fullchain-file /etc/nginx/aliyun.mydomain.tech/cert.pem \
--reloadcmd     "service nginx force-reload"

安装证书到syncthing

acme.sh --install-cert -d aliyun.mydomain.tech \
--key-file       /root/.config/syncthing/https-key.pem \
--fullchain-file /root/.config/syncthing/https-cert.pem \

obsidian使用初体验

Thu, 01 Dec 2022 14:37:00 GMT

obsidian有arm64版本的appimage，可以在rock 5b上直接使用，这下摸鱼的时候都可以记笔记了。

下载并执行AppImage

直接官网下载：

wget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.0.3/Obsidian-1.0.3-arm64.AppImage
chmod a+x ./Obsidian-1.0.3-arm64.AppImage
# 终端里执行
./Obsidian-1.0.3-arm64.AppImage

使用技巧

图片居中

在YOUR_VAULT/.obsidian/themes/YOUR_CUSTOM_THEME.css中：

exa -aT ./history_battle_100
history_battle_100
├── .stfolder
└── history_battle_100
   ├── .obsidian
   │  ├── app.json
   │  ├── appearance.json
   │  ├── core-plugins.json
   │  ├── hotkeys.json
   │  ├── themes
   │  │  └── my_custom.css          # 这个文件
   │  └── workspace.json
   ├── static
   │  └── test.png
   └── 第一季-秦并天下
      ├── 0. 汉末重写“开刊词”.md
      └── 1. 第一战：三家分晋（加量修订版）韩赵魏崛起，自春秋来到战国.md

添加自定义css：

img {
        display: block !important;
        margin-left: auto !important;
        margin-right: auto !important;
}
    
 .markdown-source-view.mod-cm6 .cm-content > * {
        margin: auto auto !important;
}

在Settings=>Appearance=>Themes中选择my_custom.css即可。

双向链接

链接到某一篇笔记：[[ ]]
链接到某一篇笔记中的某个标题：[[ # ]]
链接到某一篇笔记中的某个段落（块）：[[ # ^ ]]
为链接创建定义（关键词）：[[ | 关键词]]
链接到外部文件如印象笔记：[关键词](链接)

radxa Rock 5b使用体验

Sun, 13 Nov 2022 18:52:00 GMT

今年双十一最大战果，就是通过radxa的QQ群找了个热心大哥，60¥买了他-400¥的券，下单了ROCK 5b裸板，昨天到货后我就迫不及待地去单位对面的顺丰网点自提了。回家因为没有HDMI显示器（家里甚至没电视），就用SSH+VNC进行了初体验，后来为这个板子专门买了台4K显示器，谁是椟谁是珠我都快搞不清了……

烧录镜像

我选用了官方提供的debian 11，在release里选了rock-5b-debian-bullseye-xfce4-arm64-20221111-1506-gpt.img.xz镜像，按照教程像树莓派一样用balenaEtcher烧录进TF卡中（使用TF卡是因为买不起emmc）。

后来摸索发现Armbian也挺好用，但是23版本一线通有问题，暂时使用22版本。如果把系统装在emmc上，就可以使用显示器反向充电一线通，据说tf卡速度不够pd协商过不去会不停重启。按照官方教程将系统烧录到emmc中。

安装风扇自动控制

淘宝了个5v/5.5cm孔距/1.25接口的北桥风扇，一开始插上去运行风扇测试脚本sudo test_fan_run.sh不转（手拨一下才转），万用表测FAN输出4.87V，将脚本里的PWM占空参数调整为9000/10000后风扇起码跑起来了，再减下去依然能跑。网上有大佬写了自动控制风扇的程序：

sudo apt install lm-sensors

sudo ip route add 0.0.0.0/0 via 192.168.1.150 dev wlan0 proto static
wget https://github.com/pymumu/fan-control-rock5b/releases/download/1.1.0/fan-control-rock5b.1.1.0.arm64.deb
sudo ip route delete default via 192.168.1.150 dev wlan0 proto static
sudo apt install ./fan-control-rock5b.1.1.0.arm64.deb
sudo systemctl enable fan-control
sudo systemctl start fan-control
sudo systemctl status fan-control

正确设置WiFi和蓝牙

根据官方指南关于蓝牙的描述，如果使用RTL8852BE的蓝牙，需要修改黑名单设置才能让蓝牙正常工作：

sudo vim /etc/modprobe.d/blacklist.conf
blacklist pgdrv
blacklist btusb
blacklist btrtl
blacklist btbcm
blacklist btintel

在Armbian中，RTL8852BE网卡总会被认成两块MAC不同适配器，而且在启动时dmesg显示其中一块网卡会被重命名为wlP2p33s0，另一块可能叫做wlan0也可能叫做wlan1，这导致wlP2p33s0的MAC地址可能是14:xx:xx:xx:xx:xx也可能是16:xx:xx:xx:xx:xx，自动连接WiFi时不确定会先由哪个网卡连上，在IP-MAC绑定时就无法确定下一次连接上的IP是多少。临时的解决方法是禁止系统重命名设备：

sudo ln -s /dev/null /etc/udev/rules.d/80-net-setup-link.rules

重启后wlan0将会确定为14:xx:xx:xx:xx:xx，wlan1将会确定为16:xx:xx:xx:xx:xx。网上有一些猜测认为这种现象可能是双模WiFi网卡引起的。使用iw dev确实能看到是同一块物理设备下产生的两个适配器，iw phy phy0 info虽然能看到设备的详细信息，但是完全看不懂……

更新设备并获取GPU支持

按照Armbian官方说明添加大佬的源，以更新GPU驱动

如果在/lib/firmware/下没有mali_csffw.bin，就去下载一个sudo curl -o /lib/firmware/mali_csffw.bin https://github.com/JeffyCN/rockchip_mirrors/blob/libmali/firmware/g610/mali_csffw.bin。

镜像中如果有不需要的软件，如libreoffice，可以先卸掉在配置系统，以避免不必要的升级。

sudo ip route add 0.0.0.0/0 via 192.168.1.150 dev wlan0 proto static
sudo add-apt-repository ppa:liujianfeng1994/panfork-mesa
sudo add-apt-repository ppa:liujianfeng1994/rockchip-multimedia
sudo ip route delete default via 192.168.1.150 dev wlan0 proto static

sudo apt remove --purge libreoffice\* thunderbird\* codium pidgin
sudo apt remove --purge thunderbird\*
sudo apt remove --purge codium
sudo apt remove --purge pidgin
# # 卸载自带的chromium，装大神的GPU加速版，卸载其他不需要的软件
# sudo apt remove chromium-\*

sudo apt-get clean
sudo apt-get autoremove

sudo apt update
sudo apt list --upgradable
#sudo apt dist-upgrade # 是否升级要斟酌，armbian22->23后，pd有问题，无法一线通，还可能需要诱骗。

sudo apt install rockchip-multimedia-config

# sudo curl -o /lib/firmware/mali_csffw.bin https://github.com/JeffyCN/rockchip_mirrors/blob/libmali/firmware/g610/mali_csffw.bin

# sudo vim /etc/udev/rules.d/11-rockchip-multimedia.rules
# KERNEL=="mpp_service", MODE="0660", GROUP="video"
# KERNEL=="rga", MODE="0660", GROUP="video"
# KERNEL=="system-dma32", MODE="0666", GROUP="video"
# KERNEL=="system-uncached-dma32", MODE="0666", GROUP="video" RUN+="/usr/bin/chmod a+rw /dev/dma_heap"

sudo apt install kodi

sudo mv /usr/share/xsessions/kodi.desktop /usr/share/wayland-sessions/kodi-wayland.desktop

Armbian进系统选用户和桌面环境的界面叫lightdm-slick-greeter，桌面环境列表来自/usr/share/xsessions/*.desktop和/usr/share/wayland-session/*.desktop，如果列表里面有不需要的项目可以将*.desktop改为*.desktop.bak之类的名字。

sudo mv /usr/share/xsessions/gnome-xorg.desktop /usr/share/xsessions/gnome-xorg.desktop.bak
sudo mv /usr/share/xsessions/gnome.desktop /usr/share/xsessions/gnome.desktop.bak
sudo mv /usr/share/xsessions/ubuntu-xorg.desktop /usr/share/xsessions/ubuntu-xorg.desktop.bak
sudo mv /usr/share/xsessions/ubuntu.desktop /usr/share/xsessions/ubuntu.desktop.bak

sudo mv /usr/share/wayland-sessions/gnome.desktop /usr/share/wayland-sessions/gnome.desktop.bak
sudo mv /usr/share/wayland-sessions/ubuntu.desktop /usr/share/wayland-sessions/ubuntu.desktop.bak

可以使用lightdm --show-config查看lightdm各项配置来源，一些配置项可以参考LightDM - ArchWiki、LightDM - UbuntuWiki、Display manager - ArchWiki。其中，默认桌面环境可以在/etc/lightdm/lightdm.conf.d/11-armbian.conf中添加user-session=ubuntu-wayland。此外，可以用lightdm-settings以GUI的方式改登录时候的背景之类的东西。

注意，更新Armbian23.02后，PD一线通会无限重启，官方建议诱骗。之后重新下载了旧版Armbian_22.1.2，然后单独升级armbian-firmware，并安装大佬ppa中的所有包，在更新gnome相关的包，断电重启进wayland恢复正常。

sudo apt install armbian-firmware

sudo apt install libgl4es libdri2to3 libmali-g610-x11 malirun mali-g610-firmware libd3dadapter9-mesa libegl-mesa0 libegl1-mesa libgbm1 libgl1-mesa-dri libgl1-mesa-glx libglapi-mesa libgles2-mesa libglx-mesa0 libosmesa6 libwayland-egl1-mesa mesa-opencl-icd mesa-va-drivers mesa-vdpau-drivers mesa-vulkan-drivers

sudo apt install gnome-control-center-data gnome-control-center gnome-remote-desktop language-selector-gnome

其他的参考：

基础设置

手册上说SSH默认用户名密码是rock/rock，就直接进去了。进去以后执行命令是不是报语言环境的相关警告，就安装一下语言包，这个镜像默认没有装locales，得自己手动安装。

双十一买到手时，Armbian只有民间支持没有官方支持，Radxa官方只有debian和ubuntu，经过我一个多月的把玩，还是觉得Armbian好用。另外，十二月Armbian也官方也有了支持，因此建议直接用Armbian。

# 用`free -m`检测虚拟内存，若有则关闭，5b的16G版本内存绰绰有余
sudo swapoff -a
# 修改虚拟内存优先级到`0`
sudo sysctl vm.swappiness=0
sudo vim /etc/sysctl.conf
vm.swappiness=0

# 如果是电口，就是`enP4p65s0`
ip route list
default via 192.168.1.1 dev enP4p65s0 proto dhcp metric 100
192.168.1.0/24 dev enP4p65s0 proto kernel scope link src 192.168.1.120 metric 100
# 添加一条默认路由到OpenWRT，更新会快一些
sudo ip route add 0.0.0.0/0 via 192.168.1.150 dev enP4p65s0 proto static
# 删除该默认路由
sudo ip route delete default via 192.168.1.150 dev enP4p65s0 proto static

# 如果是RTL8852BE无线网卡，就是`wlP2p33s0`
ip route list
default via 192.168.1.1 dev wlP2p33s0 proto dhcp metric 100
192.168.1.0/24 dev wlP2p33s0 proto kernel scope link src 192.168.1.120 metric 100
# 添加一条默认路由到OpenWRT
sudo ip route add 0.0.0.0/0 via 192.168.1.150 dev wlP2p33s0 proto static
#sudo ip route add 0.0.0.0/0 via 192.168.1.150 dev wlan0 proto static
# 删除该默认路由
sudo ip route delete default via 192.168.1.150 dev wlP2p33s0 proto static
#sudo ip route delete default via 192.168.1.150 dev wlan0 proto static

# 更新包管理器
sudo apt update
# 安装常用软件
sudo apt install -y zsh git vim tmux ufw neofetch aria2 lm-sensors glances exa
# 配置防火墙，# 设置legacy若ufw status报错
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
sudo ufw status
sudo ufw allow 22/tcp   comment ssh
sudo ufw allow 5900/tcp comment vnc
sudo ufw allow 2017/tcp comment v2raya
sudo ufw allow 6800/tcp comment aria2
sudo ufw enable

# 安装oh-my-zsh
chsh -s $(which zsh)
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
# 如果安装路径有问题可以指定路径
ZSH="$HOME/.oh-my-zsh" sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# 安装oh-my-tmux
cd ~
git clone https://github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf
cp .tmux/.tmux.conf.local .

# 生成ssh秘钥
ssh-keygen
# 安装locales
sudo apt install locales
# 配置语言
sudo dpkg-reconfigure locales
# 调整时区
sudo timedatectl set-timezone Asia/Shanghai

没想到的是，切换oh-my-zsh的theme（可能是切换光标引起的，我切到jonathan就直接chromium segmentation fault），会导致chrome崩溃实属想不到，详见这篇文章……

装了neofetch看一下Debian的系统信息，起码硬件很强：

       _,met$$$$$gg.          rock@rock-5b
    ,g$$$$$$$$$$$$$$$P.       ------------
  ,g$$P"     """Y$$.".        OS: Debian GNU/Linux 11 (bullseye) aarch64
 ,$$P'              `$$$.     Host: Radxa ROCK 5B
',$$P       ,ggs.     `$$b:   Kernel: 5.10.66-27-rockchip-gea60d388902d
`d$$'     ,$P"'   .    $$$    Uptime: 27 mins
 $$P      d$'     ,    $$P    Packages: 1141 (dpkg)
 $$:      $$.   -    ,d$$'    Shell: zsh 5.8
 $$;      Y$b._   _,d$P'      Terminal: /dev/pts/0
 Y$$.    `.`"Y$$$$P"'         CPU: (8) @ 1.800GHz
 `$$b      "-.__              Memory: 365MiB / 15722MiB
  `Y$$
   `Y$$.
     `$$b.
       `Y$$b.
          `"Y$b._
              `"""

或是Armbian的：

                                 pi@rock-5b
                                 ----------
      █ █ █ █ █ █ █ █ █ █ █      OS: Armbian (22.11.2) aarch64
     ███████████████████████     Host: Radxa ROCK 5B
   ▄▄██                   ██▄▄   Kernel: 5.10.110-rockchip-rk3588
   ▄▄██    ███████████    ██▄▄   Uptime: 30 mins
   ▄▄██   ██         ██   ██▄▄   Packages: 1551 (dpkg)
   ▄▄██   ██         ██   ██▄▄   Shell: zsh 5.8.1
   ▄▄██   ██         ██   ██▄▄   Resolution: 3840x2160
   ▄▄██   █████████████   ██▄▄   Terminal: /dev/pts/1
   ▄▄██   ██         ██   ██▄▄   CPU: (8) @ 1.800GHz
   ▄▄██   ██         ██   ██▄▄   Memory: 830MiB / 15720MiB
   ▄▄██   ██         ██   ██▄▄
   ▄▄██                   ██▄▄
     ███████████████████████
      █ █ █ █ █ █ █ █ █ █ █

安装科学冲浪

安装核心：

# 安装或更新核心
sudo bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
# 仅更新核心
sudo bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install-geodata
# 卸载核心
sudo bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ remove

sudo systemctl status xray.service

安装UI，直接在release中挑了一个arm64的包

wget https://github.com/v2rayA/v2rayA/releases/download/v1.5.9.1698.1/installer_debian_arm64_1.5.9.1698.1.deb
sudo apt install ./installer_debian_arm64_1.5.9.1698.1.deb
# 可以添加为系统服务
sudo systemctl enable v2raya.service
sudo systemctl start v2raya.service
sudo systemctl status v2raya.service

# 更新防火墙
sudo ufw allow 2017/tcp

# 若防火墙报错可以切换nft或legacy试试
sudo update-alternatives --set iptables /usr/sbin/iptables-nft
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-nft
sudo update-alternatives --set arptables /usr/sbin/arptables-nft
sudo update-alternatives --set ebtables /usr/sbin/ebtables-nft

sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
sudo update-alternatives --set arptables /usr/sbin/arptables-legacy
sudo update-alternatives --set ebtables /usr/sbin/ebtables-legacy

这是个WebUI，访问192.168.1.120:2017，官方推荐配置如下：

配置	选项
透明代理/系统代理	启用: 大陆白名单模式
透明代理/系统代理实现方式	redirect
规则端口的分流模式	大陆白名单模式
防止DNS污染	仅防止DNS劫持(快速)
特殊模式	supervisor
TCPFastOpen	保持系统默认
多路复用	关闭
自动更新订阅	关闭
解析订阅链接/更新时优先使用	跟随透明代理/系统代理

配置aria2c服务

http下载vscode之类大文件之前，最好把aria2配好，然后使用如AriaNgAll-In-One版的WebUI控制。

如果想要将aria2c配置为系统服务随机启动，就不能再想以前部署服务器一样在$HOME目录下新建.conf和.session文件来保存配置和会话信息了，因为Linux禁止系统服务从用户目录运行或访问用户目录。因此，不论二进制文件还是配置文件，或是启动时需要访问的会话文件都得放在别的地方。比如可以将配置文件放在/etc/aria2c.conf中，将其他文件放在/var/aria2c目录下。

这里我使用的用户/组为pi/pi，若使用www-data/www-data下下来的文件用起来可能不方便。

wget https://github.com/mayswind/AriaNg/releases/download/1.3.2/AriaNg-1.3.2-AllInOne.zip
unzip ./AriaNg-1.3.2-AllInOne.zip

# 更新防火墙
sudo ufw allow 6800/tcp
# 创建下载目录
sudo mkdir -p /var/aria2c/Downloads
# 即使用于/var/tmp一样的访问权限
sudo chmod 777 /var/aria2c /var/aria2c/Downloads
# 修改配置文件
sudo vim /etc/aria2.conf

配置如下，注意修改<your-rpc-secret>的远程密码：

## '#'开头为注释内容, 选项都有相应的注释说明, 根据需要修改 ##
## 被注释的选项填写的是默认值, 建议在需要修改时再取消注释  ##

## 文件保存相关 ##

# 文件的保存路径(可使用绝对路径或相对路径), 默认: 当前启动位置
dir=/var/aria2c/Downloads
# 启用磁盘缓存, 0为禁用缓存, 需1.16以上版本, 默认:16M
#disk-cache=32M
# 文件预分配方式, 能有效降低磁盘碎片, 默认:prealloc
# 预分配所需时间: none < falloc ? trunc < prealloc
# falloc和trunc则需要文件系统和内核支持
# NTFS建议使用falloc, EXT3/4建议trunc, MAC 下需要注释此项
#file-allocation=none
# 断点续传
continue=true

## 下载连接相关 ##

# 最大同时下载任务数, 运行时可修改, 默认:5
#max-concurrent-downloads=5
# 同一服务器连接数, 添加时可指定, 默认:1
max-connection-per-server=16
# 最小文件分片大小, 添加时可指定, 取值范围1M -1024M, 默认:20M
# 假定size=10M, 文件为20MiB 则使用两个来源下载; 文件为15MiB 则使用一个来源下载
min-split-size=4M
# 单个任务最大线程数, 添加时可指定, 默认:5
split=16
# 整体下载速度限制, 运行时可修改, 默认:0
max-overall-download-limit=3000000
# 单个任务下载速度限制, 默认:0
#max-download-limit=0
# 整体上传速度限制, 运行时可修改, 默认:0
max-overall-upload-limit=50000
# 单个任务上传速度限制, 默认:0
#max-upload-limit=0
# 禁用IPv6, 默认:false
disable-ipv6=true
# 连接超时时间, 默认:60
#timeout=60
# 最大重试次数, 设置为0表示不限制重试次数, 默认:5
#max-tries=5
# 设置重试等待的秒数, 默认:0
#retry-wait=0

## 进度保存相关 ##

# 从会话文件中读取下载任务
input-file=/var/aria2c/aria2c.session
# 在Aria2退出时保存`错误/未完成`的下载任务到会话文件
save-session=/var/aria2c/aria2c.session
# 定时保存会话, 0为退出时才保存, 需1.16.1以上版本, 默认:0
save-session-interval=60

## RPC相关设置 ##

# 启用RPC, 默认:false
enable-rpc=true
# 允许所有来源, 默认:false
rpc-allow-origin-all=true
# 允许非外部访问, 默认:false
rpc-listen-all=true
# 事件轮询方式, 取值:[epoll, kqueue, port, poll, select], 不同系统默认值不同
#event-poll=select
# RPC监听端口, 端口被占用时可以修改, 默认:6800
rpc-listen-port=6800
# 设置的RPC授权令牌, v1.18.4新增功能, 取代 --rpc-user 和 --rpc-passwd 选项
rpc-secret=<your-rpc-secret>
# 设置的RPC访问用户名, 此选项新版已废弃, 建议改用 --rpc-secret 选项
#rpc-user=<USER>
# 设置的RPC访问密码, 此选项新版已废弃, 建议改用 --rpc-secret 选项
#rpc-passwd=<PASSWD>
# 是否启用 RPC 服务的 SSL/TLS 加密,
# 启用加密后 RPC 服务需要使用 https 或者 wss 协议连接
#rpc-secure=true
# 在 RPC 服务中启用 SSL/TLS 加密时的证书文件,
# 使用 PEM 格式时，您必须通过 --rpc-private-key 指定私钥
#rpc-certificate=/path/to/certificate.pem
# 在 RPC 服务中启用 SSL/TLS 加密时的私钥文件
#rpc-private-key=/path/to/certificate.key

## BT/PT下载相关 ##

# 当下载的是一个种子(以.torrent结尾)时, 自动开始BT任务, 默认:true
follow-torrent=true
# BT监听端口, 当端口被屏蔽时使用, 默认:6881-6999
listen-port=51414
# 单个种子最大连接数, 默认:55
#bt-max-peers=55
# 打开DHT功能, PT需要禁用, 默认:true
enable-dht=true
# 打开IPv6 DHT功能, PT需要禁用
#enable-dht6=false
# DHT网络监听端口, 默认:6881-6999
dht-listen-port=6881-6999
# 本地节点查找, PT需要禁用, 默认:false
bt-enable-lpd=true
# 种子交换, PT需要禁用, 默认:true
enable-peer-exchange=true
# 每个种子限速, 对少种的PT很有用, 默认:50K
bt-request-peer-speed-limit=3M
# 客户端伪装, PT需要
peer-id-prefix=-TR2770-
user-agent=Transmission/2.77
peer-agent=Transmission/2.77
# 当种子的分享率达到这个数时, 自动停止做种, 0为一直做种, 默认:1.0
seed-ratio=1.0
seed-time=0
# 强制保存会话, 即使任务已经完成, 默认:false
# 较新的版本开启后会在任务完成后依然保留.aria2文件
#force-save=false
# BT校验相关, 默认:true
#bt-hash-check-seed=true
# 继续之前的BT任务时, 无需再次校验, 默认:false
bt-seed-unverified=true
# 保存磁力链接元数据为种子文件(.torrent文件), 默认:false
bt-save-metadata=false
# dht-file
dht-file-path=/var/aria2c/dht.dat
# 删除未选择的文件
bt-remove-unselected-file=true
# 无速度时自动停止时间
#bt-stop-timeout=1800

添加启动项：

sudo vim /etc/systemd/system/aria2c.service

修改配置文件：

[Unit]
Description=Aria2c download manager
Requires=network.target
After=dhcpcd.service

[Service]
Type=forking
User=pi
Group=pi
ExecStartPre=/usr/bin/env touch /var/aria2c/aria2c.session
WorkingDirectory=/var/aria2c/
ExecStart=/usr/bin/aria2c --conf-path=/etc/aria2.conf -D
TimeoutStopSec=20
Restart=on-failure

[Install]
WantedBy=multi-user.target

测试启动：

sudo systemctl enable aria2c.service
sudo systemctl start aria2c.service
sudo systemctl status aria2c.service

安装vscode

添加微软源安装：

sudo apt-get install wget gpg
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -D -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/packages.microsoft.gpg
sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
rm -f packages.microsoft.gpg

sudo apt install apt-transport-https
sudo apt update
sudo apt install code # or code-insiders

或是下载deb安装：

下载微软官方的arm64 deb安装即可。

wget https://az764295.vo.msecnd.net/stable/6261075646f055b99068d3688932416f2346dd3b/code_1.73.1-1667966450_arm64.deb
sudo apt install ./code_1.73.1-1667966450_arm64.deb

安装wps-office

在wps主页下载即可。

wget https://wps-linux-personal.wpscdn.cn/wps/download/ep/Linux2019/11664/wps-office_11.1.0.11664_arm64.deb
sudo apt install ./wps-office_11.1.0.11664_arm64.deb

Armbian安装rime输入法

这篇文章中fcitx5+rime的方法我没安装成功，就转向这个答案，使用ibus+rime的组合。

sudo apt install ibus ibus-rime

在区域与语言->管理已安装的语言->键盘输入法系统->选择IBus。此时在keyboard->input source中能看到汉语->中文（Rime）（没有重启即可），选上即可。重启后，右上角出现ibus的选择框，选中文（Rime）后报错，查看日志：

cat /tmp/rime.fcitx-rime.ERROR
E0116 16:40:14.597605  4678 deployment_tasks.cc:212] missing input schema: luna_pinyin
E0116 16:40:14.598170  4678 deployment_tasks.cc:212] missing input schema: luna_pinyin_simp
E0116 16:40:14.598309  4678 deployment_tasks.cc:212] missing input schema: luna_pinyin_fluency
E0116 16:40:14.598423  4678 deployment_tasks.cc:212] missing input schema: bopomofo
E0116 16:40:14.598546  4678 deployment_tasks.cc:212] missing input schema: bopomofo_tw
E0116 16:40:14.598660  4678 deployment_tasks.cc:212] missing input schema: cangjie5
E0116 16:40:14.598773  4678 deployment_tasks.cc:212] missing input schema: stroke
E0116 16:40:14.598884  4678 deployment_tasks.cc:212] missing input schema: terra_pinyin

用apt搜索rime发现需要继续安装data包（不必装全，最关键的应该是luna-pinyin）：

sudo apt install rime-data-luna-pinyin rime-data-pinyin-simp rime-data-bopomofo rime-data-cangjie5 rime-data-stroke rime-data-terra-pinyin

随便找个能输入的地方，此时左上角已经可以切换到Rime输入法了，随意输入后按F4调出菜单界面选择朙月拼音简化字即可。

Armbian安装谷歌输入法

上安装中文输入法，我选了fcitx，不过中间需要很多玄学操作（UI上的操作就是“支持的语言”、“语言/区域”这种地方把中文选上，把默认输入法选成fcitx），关键是用fcitx-configtool查看报错，哪里飘红搜哪里。通常需要的操作是：

# 我也不知道到底是哪些包起作用
sudo apt install fcitx fcitx-pinyin fcitx-googlepinyin fcitx-config-gtk fcitx-frontend-all fcitx-frontend-gtk2 fcitx-frontend-gtk3 fcitx-frontend-qt5 fcitx-libs-dev  fcitx-ui-classic fcitx-ui-qimpanel fcitx-ui-light fcitx-table 
# 在shell配置文件里加几个环境变量
export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
XMODIFIERS=@im=fcitx
# 设置开机启动
cp /usr/share/applications/fcitx.desktop ~/.config/autostart/fcitx.desktop
# 用fcitx配置工具查看谷歌拼音之类的中文输入法有没有显式出来
fcitx-configtool
# 用输入法配置工具查看需要装什么东西
im-config
# 根据诊断工具debug
fcitx-diagnose
# 解决诊断工具中`gtk-query-immodules-3.0`和`gtk-query-immodules-2.0`的报错
sudo ln -s /usr/lib/aarch64-linux-gnu/libgtk-3-0/gtk-query-immodules-3.0 /usr/bin/gtk-query-immodules-3.0
sudo ln -s /usr/lib/aarch64-linux-gnu/libgtk2.0-0/gtk-query-immodules-2.0 /usr/bin/gtk-query-immodules-2.0

安装chromium（有些民间Armbian镜像没有浏览器）

注：chromium升级后不需要再进行下面的操作了，直接apt install chromium-browser即可。

sudo apt install chromium-browser

如果chromium慢，可能是登录的时候没用wayland（我习惯用ubuntu-wayland，速度上gnome-wayland也一样）。

可以换源：

sudo apt remove --purge chromium-browser chromium-codecs-ffmpeg-extra
sudo apt install chromium-browser=$(apt-cache show chromium-browser|grep Version|grep rkmpp|cut -d " " -f2) chromium-codecs-ffmpeg-extra=$(apt-cache show chromium-browser|grep Version|grep rkmpp|cut -d " " -f2) libv4l-rkmpp v4l-utils

sudo ln -s /lib /usr/lib64
cd /usr/lib64/ && sudo ln -s aarch64-linux-gnu/libv4l2.so.0.0.0 libv4l2.so

sudo vim /etc/rc.local:
# 添加以下内容
echo dec > /dev/video-dec0
chown root:video /dev/video-dec0
chmod 0660 /dev/video-dec0
echo enc > /dev/video-enc0
chown root:video /dev/video-enc0
chmod 0660 /dev/video-enc0

sudo vim /etc/chromium-browser/default
# 替换默认flag
CHROMIUM_FLAGS="--use-gl=egl"

sudo apt install gstreamer1.0-rockchip1 gstreamer1.0-alsa gstreamer1.0-pipewire gstreamer1.0-plugins-base-apps gstreamer1.0-plugins-base gstreamer1.0-x libgstreamer-gl1.0-0 libgstreamer-plugins-base1.0-0 clapper ffmpeg kodi moonlight-embedded obs-gstreamer obs-studio

安装syncthing

尝试部署一个syncthing服务器，在4x的服务器上安装：

curl -sS https://webinstall.dev/syncthing | bash
source ~/.config/envman/PATH.env

在公网IP上开GUI配置界面，并开启防火墙：

syncthing --gui-address=0.0.0.0:8384
sudo firewall-cmd --zone=public --permanent --add-port=8384/tcp  # WEB-UII界面
sudo firewall-cmd --zone=public --permanent --add-port=22000/tcp # 通信端口

在想用的机子上：

sudo apt install syncthing
sudo systemctl enable syncthing-resume.service
systemctl --user enable syncthing.service
systemctl --user start syncthing.service
systemctl --user status syncthing.service

民间旧版Armbian遗留操作

他们官网上说对debian做了优化，比如尽量使用内存，减少落盘读写什么的。Radax的群里有大佬做了action日更镜像，可以试一下。另外，Armbian官方也更新了适用于Rock5B的镜像。

如果刷了armbian接HDMI时ctrl+alt+F7只有光标，回ctrl+alt+F1看dmesg八成是显卡驱动问题：

# 命令行下搜WiFi
iwlist scanning
# 加入WiFi
nmcli d wifi connect "<your-ssid>" password <your-password>

# 下载显卡驱动固件
wget https://github.com/JeffyCN/rockchip_mirrors/raw/libmali/firmware/g610/mali_csffw.bin
sudo mv mali_csffw.bin /lib/firmware/
# 添加大佬源
sudo add-apt-repository ppa:liujianfeng1994/panfork-mesa
sudo apt update
sudo apt upgrade

Armbian安装docker

按照这篇文章一次安装完成：

更新，安装依赖：

# update software repositories
sudo apt update
# install necessary packages for https apt calls
sudo apt install apt-transport-https ca-certificates curl gnupg-agent software-properties-common

使用Ubuntu构建的Armbian添加如下gpg秘钥：

# add docker GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
# add docker software repository
sudo add-apt-repository "deb [arch=arm64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

使用Debian构建的Armbian添加如下gpg秘钥：

# add docker GPG key
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
# add docker software repository
sudo add-apt-repository "deb [arch=arm64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"

安装docker：

# install docker
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io
# start docker service
sudo systemctl start docker
# enable docker service on startup
sudo systemctl enable docker
# create a docker group
sudo groupadd docker
# add the current user to the docker group
sudo usermod -aG docker $USER

使用hello-world镜像测试安装结果：

sudo docker run hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
7050e35b49f5: Pull complete
Digest: sha256:faa03e786c97f07ef34423fccceeec2398ec8a5759259f94d99078f264e9d7af
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/

For more examples and ideas, visit:
https://docs.docker.com/get-started/

挂载smb共享

直接安装rock5b上的vlc和vlc-plugin-samba后，vlc仍然无法打开smb共享中的文件，若使用mpv时会报错说"ffmpeg protocol not found. make sure ffmpeg/libav is compiled with networking support ... smb"，可能是编译的时候没有带smb模块吧，懒得研究这个了，干脆将smb共享挂载为本地文件。

参考Mount password protected network folders：

sudo apt install cifs-utils
sudo mkdir /media/exos_1t
vim ~/.smbcredentials
#.smbcredentials
username=username
password=password

chmod 600 ~/.smbcredentials

//servername/EXOS_1T /media/exos_1t cifs credentials=/home/pi/.smbcredentials,iocharset=utf8 0 0

尝试玩游戏

B站上偶然间看到一个大佬的视频，大佬即是UP又是malior的作者，运行这个库需要先装docker再部署：

wget -O - https://github.com/ChisBread/malior/raw/main/install.sh > /tmp/malior-install.sh && bash /tmp/malior-install.sh  && rm /tmp/malior-install.sh 
malior-sudo 'echo $USER' # 拉rk3588-gaming的镜像时间比较长

# 安装wine，时间比较长
malior install wine
# 安装中文环境:
malior winetricks -q fakechinese wenquanyi
# 游戏貌似必须放在`~/.local/malior/`目录下，红警跑起来报Yuri.exe的错
malior wine "~/.local/malior/games/CandC_RA2/CandC_RA2YR/YURI.exe"
# 冰封王座，但是声音只会出来一秒，在设置的声音里选一下输出设备就好了
# `-windows`是窗口模式，不加就是全屏：
malior wine "~/.local/malior/games/Warcraft3_1.24E/War3.exe -opengl -windows"
# 混乱之治加上`-classic`
malior wine "~/.local/malior/games/Warcraft3_1.24E/War3.exe -opengl -classic"

参考：

魔兽命令行参数

安装node

node对arm64的支持貌似最高到14，更高的我没测试。

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
# 安装node 14
nvm install 14

安装Anaconda

anaconda也支持arm64，虽然Python不随最新的，但是包多省心啊。去anaconda或者miniconda下载一个arm64的.sh安装就好了。

备份tf卡

装了这么多东西，有必要备份一下系统，我这里备在samba的一个盘上了，5.7G备了一个小时（macOS上64k的k要小写，否则报错）：

sudo dd if=/dev/disk2 conv=sync,noerror bs=64k status=progress | gzip -c > /Volumes/EXOS_1T/backup_image20221129.img.gz

恢复：

gunzip -c /Volumes/EXOS_1T/backup_image20221129.img.gz | dd of=/dev/disk2 bs=64k status=progress

maskrom模式写入emmc

买个民间大神的emmc模块比官方便宜很多。

# 安装rkdeveloptool
sudo port install automake autoconf libusb # 或 brew install automake autoconf libusb
git clone https://github.com/radxa/rkdeveloptool.git
cd rkdeveloptool
autoreconf -i
./configure
make
sudo cp rkdeveloptool /opt/homebrew/bin/
# 测试rkdeveloptool
rkdeveloptool -v
rkdeveloptool ver 1.32

烧录镜像，按住maskrom后type-c口接电脑，使用lsusb验证USB设备显示Bus 020 Device 031: ID 2207:350b Fuzhou Rockchip Electronics Company。运行rkdeveloptool：

sudo rkdeveloptool ld
DevNo=1	Vid=0x2207,Pid=0x350b,LocationID=1402	Maskrom
# 下载spl loader
wget https://dl.radxa.com/rock5/sw/images/loader/rock-5b/rk3588_spl_loader_v1.08.111.bin
# 初始化ram并准备闪存环境
sudo rkdeveloptool db ./rk3588_spl_loader_v1.08.111.bin
Downloading bootloader succeeded.
# 写入镜像，如果是Armbian官网的.xz镜像则需要解压为.img
sudo rkdeveloptool wl 0 Armbian_22.11.2_Rock-5b_jammy_legacy_5.10.110_gnome_desktop.img

GPIO的PWM

参考这篇文章，用大佬的Blinka，先看香橙派的手册作参考：

sudo apt install -y python3 python3-pip
sudo apt install libgpiod2 python3-libgpiod
pip3 install gpiod
pip3 install --upgrade setuptools
pip3 freeze - local | grep -v '^\-e' | cut -d = -f 1 | xargs -n1 pip3 install -U

sudo apt install -y python3-smbus2 python3-dev i2c-tools
sudo pip3 install Adafruit-Blinka

安了一大堆东西，在5b的vscode上按手册写代码测试一下，GPIO的pin定义在rock5.py中：

import board
import pwmio
pwm = pwmio.PWMOut(board.PWM14)

在vscode的launch.json中要加上"sudo": true和"justMyCode": false两个选项，即“以管理员身份调试运行”和“调试库代码”，单步调试adafruit_blinka/microcontroller/rockchip/PWMOut.py中的PWMOut类时发现这段代码需要访问/sys/class/pwm/pwmchip0/pwm14这个文件，但是我只有/sys/class/pwm/pwmchip0/pwm0，而且感觉我的这个文件是风扇在用。

问了一下群里大神，可能跟设备树有关，有人说要改dts编译dtb后替换现有文件，有人说改overlay可能也行，搜了半天，找到这篇文章。改overlay即可：

# 查看有哪些overlay
exa -alT /boot/dtb/rockchip/overlay/
#...
.rwxr-xr-x  309 root  8 12月  2022 ├── rk3588-pwm2-m1.dtbo
.rwxr-xr-x  309 root  8 12月  2022 ├── rk3588-pwm3-m1.dtbo
.rwxr-xr-x  309 root  8 12月  2022 ├── rk3588-pwm5-m2.dtbo
.rwxr-xr-x  309 root  8 12月  2022 ├── rk3588-pwm6-m2.dtbo
.rwxr-xr-x  309 root  8 12月  2022 ├── rk3588-pwm7-m3.dtbo
.rwxr-xr-x  309 root  8 12月  2022 ├── rk3588-pwm8-m0.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm12-m0.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm13-m0.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm13-m2.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm14-m0.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm14-m1.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm15-m0.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm15-m1.dtbo
.rwxr-xr-x  311 root  8 12月  2022 ├── rk3588-pwm15-m3.dtbo

# 修改`armbianEnv`
sudo vim /boot/armbianEnv.txt
# 添加`overlays=pwm2-m1 pwm6-m2 pwm7-m3`（心比较沉，加了三个）
overlay_prefix=rk3588
overlays=pwm2-m1 pwm6-m2 pwm7-m3

重启后发现/sys/class/pwm/下出现了另外的pwmchip1、pwmchip2、pwmchip3，此时用exa查看这三个新项目比原来的pwmchip0少一些子目录，可能是没启用导致的，按照radax给的风扇的例子启用一下：

# 查看pwm项目
ls /sys/devices/platform/ | grep pwm
fd8b0010.pwm
fd8b0020.pwm
febd0020.pwm
febd0030.pwm
# 或用exa
exa -alt /sys/class/pwm/pwmchip0/
drwxr-xr-x    - root 14 2月  22:57 /sys/class/pwm/pwmchip0
lrwxrwxrwx    0 root 14 2月  22:59 ├── device -> ../../../fd8b0010.pwm

exa -alt /sys/class/pwm/pwmchip1/
drwxr-xr-x    - root 14 2月  22:57 /sys/class/pwm/pwmchip1
lrwxrwxrwx    0 root 14 2月  22:58 ├── device -> ../../../fd8b0020.pwm

exa -alt /sys/class/pwm/pwmchip2/
drwxr-xr-x    - root 14 2月  22:57 /sys/class/pwm/pwmchip2
lrwxrwxrwx    0 root 14 2月  22:58 ├── device -> ../../../febd0020.pwm

exa -alt /sys/class/pwm/pwmchip3/
drwxr-xr-x    - root 14 2月  23:08 /sys/class/pwm/pwmchip3
lrwxrwxrwx    0 root 14 2月  22:58 ├── device -> ../../../febd0030.pwm

# 启用pwm7-m3，引脚pin为27，https://wiki.radxa.com/Rock5/hardware/5b/gpio
echo 0 > /sys/devices/platform/febd0030.pwm/pwm/pwmchip3/export 
# 设置总周期
echo 10000 > /sys/devices/platform/febd0030.pwm/pwm/pwmchip3/pwm0/period 
# 调整占用时间
echo 3000 > /sys/devices/platform/febd0030.pwm/pwm/pwmchip3/pwm0/duty_cycle 
echo normal > /sys/devices/platform/febd0030.pwm/pwm/pwmchip3/pwm0/polarity 
# 打开引脚
echo 1 > /sys/devices/platform/febd0030.pwm/pwm/pwmchip3/pwm0/enable 
# 关闭引脚
echo 0 > /sys/devices/platform/febd0030.pwm/pwm/pwmchip*/pwm0/enable

Armbian上的这个pwmchip*应该是按顺序分配的，不是固定的，所以写成星号比较保险，用前面的fexxxxxx确定针脚就好了。

USB声卡

群里大佬都说5b这个把3.5mm模拟音频口放在DP电源旁边的操作很魔幻，刚好我有块MOTU M2的外置声卡，走USB让5b只输出数字信号就好了。而且如果是一线通的话声卡直接插显示器通过显示器的USB Hub送到type-c再到5b，也就是5b上始终只有一根type-c线，负责供电、显示以及声卡。

这时候问题就出现了，首先M2官方不支持Linux，然后在Armbian下5b的USB口直接驱动不起来声卡，必须接显示器USB Hub才能有足够的供电，一线通到5b时也能认出来这块声卡，但是播放音频的时候基本上每16秒钟有2-4秒的噪音，这种好了但没完全好的状态非常蛋疼，因为不懂dts也不懂内核，就懒得动手搞底层的东西，只是调了调pulseaudio和alsa的参数，毫无作用。

想到手里还有一块再吃灰的树莓派2b，就想着如果是Armbian的问题，树莓派作为SBC里被支持的最好的设备，声卡什么的应该没问题。一开始拿出RPi-2b送电俩指示灯常亮，插拔SD卡也没反应，很诡异。我换了几个电源都不行，万用表瞎戳也没搞清楚啥情况，都送上咸鱼准备告别了，搜了一下有老外说灯常亮的时候换根线试试，竟然被他说中了……

然后就是在RPi-2b上刷了个Raspberry Pi OS Lite (32-bit)，用当年RPi-2b配的USB 2.4G WiFi连上网，常规update和upgrade后，USB直接插声卡，亮了，说明起码供电没问题。装上pulseaudio，用aplay test.wav放歌试了一下，什么都没设它自动就送到USB声卡上了，没有噪音，很好。此时只需要把RPi-2b配置成PulseAudio Server，把5b配置成PulseAudio Client就好了。按照这个教程：

# client and server both
sudo apt install pulseaudio-zeroconf # rock5b上可能是 sudo apt install pulseaudio-module-zeroconf
sudo systemctl enable avahi-daemon.service
sudo systemctl start avahi-daemon.service

# server side: 
sudo vim /etc/pulse/default.pa
load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1;192.168.0.0/24 auth-anonymous=1
load-module module-zeroconf-publish
# restart pulseaudio, check loaded modules
pulseaudio -k
pulseaudio --start
pacmd list-modules | grep native-protocol-tcp
pacmd list-modules | grep zeroconf-publish

# client side: 
sudo vim /etc/pulse/default.pa
load-module module-native-protocol-tcp
load-module module-zeroconf-discover
# restart pulseaudio, check loaded modules
pulseaudio -k
pulseaudio --start
pacmd list-modules | grep native-protocol-tcp
pacmd list-modules | grep zeroconf-discover

此时在作为客户端的5b上，用pavucontrol查看输出设备，就已经出现多个RPi-2b上的虚拟输出设备了（多个可能是即有IPv4又有IPv6），选M2即可。测试播放音频，好了但没完全好，明显会有丢帧。RPi-2b（2.4G WiFi）与5b（5G Wifi）互联的延迟挺十几毫秒，有时候还跳上百，可能是因为小区的问题，我家的2.4G信号挺糟糕的。此时只能掏出网线，用RPi-2b跟5b直插，配上另一个段的IP（nmcli配上ipv4后记得改manual）再把RPi-2b的WiFi关了（nmcli里device disconnect或者connection down），重启PulseAudio即可，重新连上后基本解决了丢帧问题，现在听起跟本地设备一样，非常丝滑。

nmcli connection modify Wired\ connection\ 1 ipv4.addresses 192.168.100.100/24
nmcli connection modify Wired\ connection\ 1 ipv4.method manual

算是半完美解决声卡问题，小团圆结局也是happy ending。

安装硬盘休眠

hd-idle项目可以完成这个任务：

git clone https://github.com/adelolmo/hd-idle
cd hd-idle
make

直接运行hd-idle -i 300 -l /mnt/UD_64G/hd-idle.log，即为所有硬盘设置300秒空闲停转时间，并指定日志文件。

我的rock5b直接装不上release的deb，自己编译也不行。不折腾了

安装搜狗输入法（armbian安装可能会有问题）

apt中貌似没有，得从搜狗官网下载arm64的包

# 安装输入框架
sudo apt install fcitx5
# 安装输入法
sudo apt install ./sougoxxx.deb

然后再系统dock里找到“搜索”，搜“fcitx”启动，搜狗就出现了。

安装VNC（debian可能没有需要安装）

如此豪华的硬件，必须得体验一下图形界面！随便搜个教程安装VNC服务端：

# 大概看一下装了哪些包
apt list --installed
# 已更新且发行版自带了xfce4和xfce4-goodies就不用再装了
#sudo apt update && sudo apt install xfce4 xfce4-goodies

# 安装vnc服务端，这个发行版的apt里能搜到这一个vnc的server
sudo apt install tightvncserver
# 安装相关依赖
sudo apt install dbus-x11
# 启动
vncserver

使用vncserver执行首次启动，设置VNC访问密码（6-8位）并让VNC服务端生成配置文件。（我第一次不知道为什么密码没有设置成功，连接失败时日志指示~/.vnc/passwd文件没生成，运行vncpasswd再来一次就可以了）。

接下来自定义VNC服务端配置文件。VNC默认启动于5901端口，默认由:1session占用，先停止默认的实例，再修改配置。

# 开防火墙端口
sudo ufw allow 5901/tcp
# 停止实例`:1`
vncserver -kill :1
# 备份配置文件
mv ~/.vnc/xstartup ~/.vnc/xstartup.bak
# 新建配置文件
vim ~/.vnc/xstartup

#######写入配置#######
#!/bin/bash
xrdb $HOME/.Xresources # 让VNC的GUI去读取`.Xresources`文件，以指定图形化桌面终端的主题、颜色、字体等。
startxfce4 & # 让VNC启动xfce
#######写入结束#######

# 设置运行权限
sudo chmod +x ~/.vnc/xstartup
# 再次启动
vncserver

VNC本身不使用加密协议，可以使用SSH建立隧道转发VNC以实现加密：

ssh -L 5901:127.0.0.1:5901 -C -N -l rock 192.168.1.120

-L：将远端的5901绑定在127.0.0.1的5901上；
-C：开启压缩以节省流量；
-N：告诉ssh我们不在远端执行命令；
-l：指定登录用户名，应使用非root用户登录。

这条命令执行后将建立到192.168.1.120的隧道，命令不返回。在VNC客户端里，新建一个到本地127.0.0.1:5901的连接，用户名改成rock，就可以远程了。

将VNC加入系统服务，新建文件sudo vim /etc/systemd/system/vncserver@.service：

[Unit]
Description=Start TightVNC server at startup
After=syslog.target network.target

[Service]
Type=forking
User=rock
Group=rock
WorkingDirectory=/home/rock

PIDFile=/home/rock/.vnc/%H:%i.pid
ExecStartPre=-/usr/bin/vncserver -kill :%i > /dev/null 2>&1
ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280x800 :%i
ExecStop=/usr/bin/vncserver -kill :%i

[Install]
WantedBy=multi-user.target

加载配置（@后面的1指的是VNC的:1）：

# 重新加载系统配置工具
sudo systemctl daemon-reload
# 启动VNC服务端
sudo systemctl enable vncserver@1.service
sudo systemctl start vncserver@1
# 查看运行状态
sudo systemctl status vncserver@1

如果打开chrome上B站发现中文全是方框，则应安装字体（不过前面选过locale就没问题了）：

sudo apt install fonts-wqy-microhei fonts-wqy-zenhei xfonts-intl-chinese xfonts-intl-chinese-big emacs-intl-fonts

安装USB无线网卡（失败）

随便找了个USB网卡，插入后查看USB设备，找到设备ID为148f:7601 Ralink Technology, Corp. MT7601U Wireless Adapter。查看识别的网络设备，发现这个网卡未识别：

 lsusb
# ...
Bus 001 Device 004: ID 148f:7601 Ralink Technology, Corp. MT7601U Wireless Adapter
# ...

ip a # 或ip l
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
# ...
2: enP4p65s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
# ...

下载驱动并编译（没搞定没深究）：

sudo apt install linux-headers-generic build-essential
git clone https://github.com/art567/mt7601usta.git
cd mt7601usta/src 
make # 此时报错 `can't find file Kconfig` 就不懂了
sudo make install
sudo mkdir -p /etc/Wireless/RT2870STA/
sudo cp RT2870STA.dat /etc/Wireless/RT2870STA/
sudo modprobe mt7601Usta

把吃灰中raspberry pi 2的USB WiFi拔下来，0bda:8176 Realtek Semiconductor Corp. RTL8188CUS 802.11n WLAN Adapter，是个2.4G免驱，解决。

部署matrix

安装数据库：

sudo apt install postgresql
# 安装完毕后系统中会自动新增一个`postgres`用户，切换用户
sudo -i -u postgres  
# 登录postgreSQL
psql
psql (14.5 (Ubuntu 14.5-0ubuntu0.22.04.1))
Type "help" for help.

# 退出
\q
# 查看状态
systemctl status postgresql.service

初始化：

# 创建角色
sudo -u postgres createuser -P dendrite
# 创建数据库（单数据库模式）
sudo -u postgres createdb -O dendrite -E UTF-8 dendrite
# 测试connection string
pg_isready -d postgresql://dendrite:dendrite@localhost/dendrite
localhost:5432 - accepting connections

安装golang，nginx：

sudo apt install golang nginx
go version
go version go1.18.1 linux/arm64

安装并配置：

# 下载
wget https://github.com/matrix-org/dendrite/archive/refs/tags/v0.10.8.zip
unzip /v0.10.8.zip
cd ./dendrite-0.10.8
# 构建安装
./build.sh
go install ./cmd/dendrite-monolith-server
# 生成密钥
./bin/generate-keys --private-key matrix_key.pem
Created private key file: matrix_key.pem
# 按手册提示修改配置文件，若需要命令行添加用户，还需要将`client_api.registration_shared_secret`设置值。

启动dendrite，添加用户：

# 启动
./dendrite-monolith-server -config /path/to/dendrite.yaml
# 添加管理员用户
./bin/create-account -config ./dendrite.yaml -username admin -admin
# 添加普通用户
./bin/create-account -config ./dendrite.yaml -username qinzishi

下载并解压element客户端：

wget https://github.com/vector-im/element-web/releases/download/v1.11.15/element-v1.11.15.tar.gz
tar -zxvf element-v1.11.15.tar.gz

配置nginx为一个简单的静态文件服务器：

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 768;
    # multi_accept on;
}

http {
    server {
        listen 80;
        location / {
            root /var/aria2c/element-v1.11.15;
        }
    }
}

网络问题

2024/04/14更新：

领导又支援了一块5b。首先是随便买了个rtl8852be，结果lspci时发现verdor id是b85b，而不是原来的b852。整了一个礼拜，试了各种系统，编译了新驱动，lsmod什么的都能加载驱动，驱动起来也能搜索wifi，但是就是无法连接。我懒得编译旧驱动了，就重新买了块b852的卡。刷了Armbian上的默认系统，这次ok了。

发现了第二个问题，新系统5b的网卡是两块，用上面禁止重命名的方式无法连接，就将就着用了，但是俩个5b在某张卡连wifi时报destination host unreachable。两个5b到别的机子都通，但是互相之间不通。用arp -a或者ip neigh show看ARP表发现是incomplete状态，临时解决办法是在两个5b上都手写一条arp进去：

sudo ip neigh replace to xxx.xxx.xxx.xxx dev wlP2p33s0 lladdr xx:xx:xx:xx:xx:xx nud permanent

临时解决方法就这样了，也可以把命令加在启动脚本里省点事。

第二个VPS科学球 - 改

Sat, 24 Sep 2022 16:27:00 GMT

新VPS科学球是racknerd一年9.89$捡的，算是美帝良心？

后记：racknerd丢包率和延迟真的没法忍，趁人民币强势斥巨资（三百人民币）换了某瓦工的最贫穷CN2线路，果然一分价钱一分货……

看了几个帖子又咨询了chatgpt，简单的说CN2 GIA是CN2的升级版，贵了两三倍，如果只是上上网CN2就够用了。

:::caution 仅限技术交流！ :::

搭建新VPS科学球环境

Centos7实在太老了就重装了Ubuntu 22.04，首次登录改密码（为了方便，应该把zsh、git、oh-my-zsh、vim、tmux装上。）：

# VPS上改密码
passwd
# 电脑上上传秘钥进行ssh免密登录，也可以直接在云控制台里一次录入多个公钥
ssh-copy-id root@1*.*.*.*

sudo apt update && sudo apt dist-upgrade -y
sudo apt install zsh git vim tmux ufw
chsh -s $(which zsh)
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

将ssh设置为无法用密码登录（只接受key pair认证），顺便调整ssh超时时间：

# /etc/ssh/sshd_config 中：
# 禁止密码认证
PasswordAuthentication no
# 调整ssh会话一次存活60秒，自动重连60次
ClientAliveInterval 60
ClientAliveCountMax 60

# 重启sshd服务：
service sshd restart

开防火墙策略：

sudo ufw allow 22/tcp comment ssh
sudo ufw allow 443/tcp comment https
sudo ufw allow 80/tcp comment http
sudo ufw enable

搭建VPS科学球

继续向一键安装脚本（原来的一键安装脚本已失效）低头，真香……这个脚本推荐的是trojan+TCP+TLS，我客户端也按照这个配的，其他的配置貌似连不上，我也没仔细研究。

wget -P /root -N --no-check-certificate "https://raw.githubusercontent.com/mack-a/v2ray-agent/master/install.sh" && chmod 700 /root/install.sh && /root/install.sh

配置aria2c远程下载服务，本地使用AriaNg搭配风味更佳：

mkdir -p ~/.config/aria2
touch ~/.config/aria2/aria2.conf       #aria2的配置文件
touch ~/.config/aria2/aria2.session    #aria2保存会话的文件
vim ~/.config/aria2/aria2.conf         #修改配置文件

配置如下：

## '#'开头为注释内容, 选项都有相应的注释说明, 根据需要修改 ##
## 被注释的选项填写的是默认值, 建议在需要修改时再取消注释  ##

## 文件保存相关 ##

# 文件的保存路径(可使用绝对路径或相对路径), 默认: 当前启动位置
dir=/webroot/downloads
# 启用磁盘缓存, 0为禁用缓存, 需1.16以上版本, 默认:16M
#disk-cache=32M
# 文件预分配方式, 能有效降低磁盘碎片, 默认:prealloc
# 预分配所需时间: none < falloc ? trunc < prealloc
# falloc和trunc则需要文件系统和内核支持
# NTFS建议使用falloc, EXT3/4建议trunc, MAC 下需要注释此项
#file-allocation=none
# 断点续传
continue=true

## 下载连接相关 ##

# 最大同时下载任务数, 运行时可修改, 默认:5
#max-concurrent-downloads=5
# 同一服务器连接数, 添加时可指定, 默认:1
max-connection-per-server=16
# 最小文件分片大小, 添加时可指定, 取值范围1M -1024M, 默认:20M
# 假定size=10M, 文件为20MiB 则使用两个来源下载; 文件为15MiB 则使用一个来源下载
min-split-size=4M
# 单个任务最大线程数, 添加时可指定, 默认:5
split=16
# 整体下载速度限制, 运行时可修改, 默认:0
max-overall-download-limit=3000000
# 单个任务下载速度限制, 默认:0
#max-download-limit=0
# 整体上传速度限制, 运行时可修改, 默认:0
max-overall-upload-limit=50000
# 单个任务上传速度限制, 默认:0
#max-upload-limit=0
# 禁用IPv6, 默认:false
disable-ipv6=true
# 连接超时时间, 默认:60
#timeout=60
# 最大重试次数, 设置为0表示不限制重试次数, 默认:5
#max-tries=5
# 设置重试等待的秒数, 默认:0
#retry-wait=0

## 进度保存相关 ##

# 从会话文件中读取下载任务
input-file=/root/.config/aria2/aria2.session
# 在Aria2退出时保存`错误/未完成`的下载任务到会话文件
save-session=/root/.config/aria2/aria2.session
# 定时保存会话, 0为退出时才保存, 需1.16.1以上版本, 默认:0
save-session-interval=60

## RPC相关设置 ##

# 启用RPC, 默认:false
enable-rpc=true
# 允许所有来源, 默认:false
rpc-allow-origin-all=true
# 允许非外部访问, 默认:false
rpc-listen-all=true
# 事件轮询方式, 取值:[epoll, kqueue, port, poll, select], 不同系统默认值不同
#event-poll=select
# RPC监听端口, 端口被占用时可以修改, 默认:6800
rpc-listen-port=6800
# 设置的RPC授权令牌, v1.18.4新增功能, 取代 --rpc-user 和 --rpc-passwd 选项
rpc-secret=<your-rpc-secret>
# 设置的RPC访问用户名, 此选项新版已废弃, 建议改用 --rpc-secret 选项
#rpc-user=<USER>
# 设置的RPC访问密码, 此选项新版已废弃, 建议改用 --rpc-secret 选项
#rpc-passwd=<PASSWD>
# 是否启用 RPC 服务的 SSL/TLS 加密,
# 启用加密后 RPC 服务需要使用 https 或者 wss 协议连接
#rpc-secure=true
# 在 RPC 服务中启用 SSL/TLS 加密时的证书文件,
# 使用 PEM 格式时，您必须通过 --rpc-private-key 指定私钥
#rpc-certificate=/path/to/certificate.pem
# 在 RPC 服务中启用 SSL/TLS 加密时的私钥文件
#rpc-private-key=/path/to/certificate.key

## BT/PT下载相关 ##

# 当下载的是一个种子(以.torrent结尾)时, 自动开始BT任务, 默认:true
follow-torrent=true
# BT监听端口, 当端口被屏蔽时使用, 默认:6881-6999
listen-port=51414
# 单个种子最大连接数, 默认:55
#bt-max-peers=55
# 打开DHT功能, PT需要禁用, 默认:true
enable-dht=true
# 打开IPv6 DHT功能, PT需要禁用
#enable-dht6=false
# DHT网络监听端口, 默认:6881-6999
dht-listen-port=6881-6999
# 本地节点查找, PT需要禁用, 默认:false
bt-enable-lpd=true
# 种子交换, PT需要禁用, 默认:true
enable-peer-exchange=true
# 每个种子限速, 对少种的PT很有用, 默认:50K
bt-request-peer-speed-limit=3M
# 客户端伪装, PT需要
peer-id-prefix=-TR2770-
user-agent=Transmission/2.77
peer-agent=Transmission/2.77
# 当种子的分享率达到这个数时, 自动停止做种, 0为一直做种, 默认:1.0
seed-ratio=1.0
seed-time=0
# 强制保存会话, 即使任务已经完成, 默认:false
# 较新的版本开启后会在任务完成后依然保留.aria2文件
#force-save=false
# BT校验相关, 默认:true
#bt-hash-check-seed=true
# 继续之前的BT任务时, 无需再次校验, 默认:false
bt-seed-unverified=true
# 保存磁力链接元数据为种子文件(.torrent文件), 默认:false
bt-save-metadata=false
# dht-file
dht-file-path=/root/.config/aria2/dht.dat
# 删除未选择的文件
bt-remove-unselected-file=true
# 无速度时自动停止时间
#bt-stop-timeout=1800

启动aria2c：

aria2c --conf-path=$HOME/.config/aria2/aria2.conf -D

如果端口有监听，防火墙也设了策略，但是仍然不通，可能是selinux策略的问题，可以在selinux中选择添加新端口：

sudo semanage port -l | grep http_port_t
sudo semanage port -a -t http_port_t  -p tcp 8888

如果nginx报403错误，有可能是selinux的问题，看看ll文件夹权限最后有没有一个.或+，如果有可以尝试关闭selinux重新创建文件夹，去掉那个.。

如果觉得selinux麻烦，可以选择关闭selinux：

# 验证selinux状态：
getenforce
# 或
/usr/sbin/sestatus -v 

# 关闭selinux：
vim /etc/selinux/config
SELINUX=disabled

另外，我的tmux配置用的是Oh my tmux，安装也很简单，只要tmux >= 2.4即可（centos7默认是1.8）。

cd
git clone https://github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf
cp .tmux/.tmux.conf.local .

OpenWRT和客户端设置

我的macOS上用的是v2rayU，不过这个客户端貌似只有trojan配置可以用，其他不通，我也没仔细研究。

树莓派上依然是刷了最新版的OpenWrt-Rpi，这个版本跟一两年前的区别是，刷固件的时候会先覆盖内存卡做初始化，避免了上次那种配置了WiFi后即使重刷固件依然无法修改WiFi配置，必须低格才能删掉配置的尴尬。

在OpenWRT上要记得先设置静态IP（比如我用192.168.1.150），网关指向家里最前端的路由，再配置自定义DNS（如陕西移动的DNS是211.137.130.19），此时树莓派网络就正常了。

接下来记得设置OpenWRT的DHCP，以使连上来的终端的网关和DNS强制指向这个树莓派，在网络->LAN->高级设置 中勾选强制；设置IPv4子网掩码（比如我用255.255.255.0）；设置DHCP选项，比如我用3,192.168.1.150和6,192.168.1.150（3指设置DHCP客户端的网关，6指设置DHCP客户端的DNS，详见维基DHCP选项）。

最开始没设置DHCP选项，导致客户端接受的是前端路由器的DHCP设置，搜到这篇排错后，用service dnsmasq restart后查看日志logread -e dnsmasq，发现报错：

Mon Oct 31 22:27:24 2022 user.notice dnsmasq: found already running DHCP-server on interface 'br-lan' refusing to start, use 'option force 1' to override

这里要用强制选项DHCP才能设上，不过，如果网里同时有两个DHCP，通常相应快的那个会抢占设置客户端，所以最好还是关掉一个。

安装nps内网穿透服务端

小可怜服务器没多少空间舍不得安装golang，直接从release列表中下载相应的二进制运行：

wget https://github.com/ehang-io/nps/releases/download/v0.26.10/linux_amd64_server.tar.gz
tar -zxvf linux_amd64_server.tar.gz
sudo ./nps install
sudo nps start

查看日志cat /var/log/nps.log，此时应该会有报错，因为我的443早就被占了：

...
2022/11/06 12:21:24.577 [E] [http.go:82]  listen tcp 0.0.0.0:443: listen: address already in use

修改配置文件/etc/nps/conf/nps.conf的用户名和密码，以及默认的http和https监听：

# ...
web_username=xxx
web_password=xxx
# ...
http_proxy_port=8880
https_proxy_port=8443
# ...

重启nps restart再次查看日志，已正常启动：

...
2022/11/06 12:22:51.420 [I] [nps.go:202]  the version of server is 0.26.10 ,allow client core version to be 0.26.0
2022/11/06 12:22:52.927 [I] [connection.go:36]  server start, the bridge type is tcp, the bridge port is 8024
2022/11/06 12:22:52.931 [I] [server.go:200]  tunnel task  start mode：httpHostServer port 0
2022/11/06 12:22:52.931 [I] [connection.go:71]  web management start, access port is 8080
2022/11/06 12:22:52.946 [I] [connection.go:62]  start https listener, port is 8443
2022/11/06 12:22:52.946 [I] [connection.go:53]  start http listener, port is 8880

开启防火墙，其中：

8024是默认桥接口，用于将内网客户端注册上来；
8080是管理口，用于网页访问修改配置；
10022是我要用的ssh映射端口口，即访问4x.x.x.x:10022->内网192.168.x.x:22；
其他端口，如8443->443、8880->80，是用于作域名映射的，我不用就不开策略了。

sudo firewall-cmd --zone=public --permanent --add-port=8024/tcp # nps 桥接端口
sudo firewall-cmd --zone=public --permanent --add-port=8080/tcp # nps 管理端口
sudo firewall-cmd --zone=public --permanent --add-port=10022/tcp # nps 映射到内网22的端口
# 不使用域名代理，防火墙可以不开
#sudo firewall-cmd --zone=public --permanent --add-port=8443/tcp # nps http 代理端口
#sudo firewall-cmd --zone=public --permanent --add-port=8880/tcp # nps https 代理端口
firewall-cmd --list-all
firewall-cmd --reload

然后，在内网的树莓派3B+上下载客户端：

wget https://github.com/ehang-io/nps/releases/download/v0.26.10/linux_arm_v7_client.tar.gz

按照说明添加一个客户端，并在树莓派上尝试连接nps服务器：

./npc -server=4x.x.x.x:8024 -vkey=*******

此时刷新nps管理页面，客户端已显示线了。在管理页面的TCP隧道中加一条端口映射，就可以从电脑上连接ssh -p 10022 pi@4x.x.x.x了。

新树莓派环境里youtube-dl下载带有key的hls时，使用--hls-prefer-native标识如果不生效，总是回到用ffmpeg下载，有可能是因为树莓派的python环境里缺少解密包，安装即可：

pip install pycrypto
# 如果是python3.10，用pycryptodome，参考：https://stackoverflow.com/questions/70705404/systemerror-py-ssize-t-clean-macro-must-be-defined-for-formats

树莓派需要下载这些东西，如果要使用OpenWRT，可以临时改一下路由，将0.0.0.0/0的默认路由指向OpenWRT即可：

# 添加前
ip route list
default via 192.168.1.1 dev eth0 proto dhcp src 192.168.1.119 metric 202
192.168.1.0/24 dev eth0 proto dhcp scope link src 192.168.1.119 metric 202
# 添加默认路由
sudo ip route add 0.0.0.0/0 via 192.168.1.150 dev eth0 proto static
# 查看结果
ip route list
0.0.0.0/0 via 192.168.1.150 dev eth0 proto static # 此时会多一条默认路由
default via 192.168.1.1 dev eth0 proto dhcp src 192.168.1.119 metric 202
192.168.1.0/24 dev eth0 proto dhcp scope link src 192.168.1.119 metric 202
# 删除默认路由
sudo ip route del 0.0.0.0/0
# 查看结果
ip route list
default via 192.168.1.1 dev eth0 proto dhcp src 192.168.1.119 metric 202
192.168.1.0/24 dev eth0 proto dhcp scope link src 192.168.1.119 metric 202
# 如果不小心删了默认路由，加回去就行了
sudo ip route add default via 192.168.1.1 dev eth0 proto dhcp src 192.168.1.119 metric 202

另外，

最后注意，此时树莓派的22口相当于暴露在公网上了，所以最好把ssh的密码登录关掉，只允许密钥登陆。

PingCap的Rust训练课程5：异步编程

Tue, 30 Aug 2022 21:01:00 GMT

:::note 本文前半部分大多翻译自原文：PNA Rust Project 5: Asynchrony，但这篇文章年久失修且烂尾，推荐跳过。

本文 后半部分 将使用 tokio官方示例 mini-redis 作为替身，建议直接阅读。 :::

前言

任务：通过自定义协议，使用异步网络创建一个多线程、持久化键/值存储的服务端和客户端。

目标：

了解在Rust中编写future时使用基本模式
了解future的错误处理
学会调试类型系统
使用Tokio运行时执行异步网络
使用boxed future处理棘手的类型系统问题
使用impl Trait创建匿名Future类型 关键词：异步、future、tokio、impl Trait。

介绍

注意：本文仅仅是本项目的提纲，并没有写完。如果您已经读到这里了，请电子邮件至brian@pingcap.com以提醒我，我将尽快写写完本文。

在本项目中，您将创建一个使用自定义协议通信的简单键/值服务端和客户端。该服务端将基于Tokio运行时构建的异步网络。键/值引擎的日志文件读写部分依然使用同步模式，在基础线程池上进行调度工作，并提供一个异步接口。在此过程中，您将尝试使用多种方法多种定义和使用future类型。

因为学习使用Rust中的futures编程有较大的挑战性，而且相关文档目前仍然较少，因此该项目的范围相对有限，相关的解释也比之前的项目更加直接。

请务必阅读有关此项目的背景资料。而如果您在本项目中感觉力不从心，那就让自己放松，休息一下，然后再试试。对于每个人来说，在Rust使用异步编程都是比较困难的。

项目需求规格

cargo项目kvs建立了一个名为kvs-client的命令行键值存储客户端，和一个名为kvs-server的键值存储服务端，二者又都调用了一个名为kvs的库。客户端通过一个自定义协议与服务端通信。

CLI参数与上一个项目中的相同。引擎实现大致相同，即通过线程池分发同步的文件I/O作业。

本项目的不同之处在于，所有的网络操作都是异步执行的。

为了实现异步操作，KvsClient将提供基于future的API，而KvsEngine trait也将提供基于future的API，尽管它是通过线程池使用同步（阻塞）I/O实现的。

您的KvsServer将基于tokio运行时，tokio将负责把异步作业分发给自己的多个线程（tokio自带的线程池）。这意味着您的架构中实际包含了两层线程池，第一层用来异步的处理网络请求，每个线程占用一个核心；第二层用来同步的处理文件I/O，使用充足的线程以保持负责处理网络的线程持续忙碌。

这种架构带来的变化，就是作业将从多个线程中生成到您的线程池，您的ThreadPool trait及其实现将变为实现了Clone + Send + 'sync的共享类型，就像KvsEngine那样。

因为您将实验多种不同的future返回方式，这里不再一一列出定义，而是在需要时定义。

更具体地说，您将使用以下所有函数签名：

Client::get(&mut self, key: String) -> Box<Future<Item = Option<String>, Error = Error>
Client::get(&mut self, key: String) -> future::SomeExplicitCombinator<...>
Client::get(&mut self, key: String) -> impl Future<Item = Option<String>, Error = Error>
Client::get(&mut self, key: String) -> ClientGetFuture

项目设置

继续上一个项目，删除之前的测试目录，并复制本项目的测试目录。这个项目应该包含一个名为kvs的库，以及两个可执行文件，kvs-server和kvs-client。

Cargo.toml中需要以下dev-dependencies：

[dev-dependencies]
assert_cmd = "0.11"
criterion = "0.2.11"
crossbeam-utils = "0.6.5"
predicates = "1.0.0"
rand = "0.6.5"
tempfile = "3.0.7"
walkdir = "2.2.7"
panic-control = "0.1.4"

与之前的项目不同，不必费心编写足够的类型定义来编译测试套件。因为这样做将会一次向前跳过多个步骤。文本将明确指出何时使用测试套件。

知识背景：深入思考Rust中的future

为什么使用future？网络 vs 文件/io，阻塞 vs 非阻塞，同步 vs 异步
从用户角度看future（不是以poll为核心的实现）
关于执行器和运行时的技术细节，不需要思考过多
考虑函数调用链及其如何转换为future类型
如何调试Rust类型
Result vs Future vs FutureResult
future的错误处理
确定的future vs 智能指针future vs 匿名future
关于future 0.1和future 0.3 的注意事项（我们将使用future 0.1）
关于async/await的注意事项

第1部分：将tokio引入客户端

最终我们要将客户端和服务器都转换为future，由于客户端非常简单，我们就从这里入手。我们将首先在现有的同步KvsClient上，介绍tokio运行时。

这

对于客户端，我们将在保持同步KvsClient的同时引入异步运行时，然后再改造KvsClient。

KvsClient的connect方法。

请注意，作为一个库，KvsClient可以提供基于futures的最高效率，但是我们的kvs-client可执行文件并没有利用它，所以这个可执行文件运行单个future就立刻退出的行为看起来有点傻。

TODO @sticnarf - 看看您是否可以编写与具体未来类型无关的测试用例，以便它们与以下所有策略一起使用。

第2部分：将`KvsClient`转换为智能指针future

转为future类型时最省事的方式。

第3部分：具有显式future类型的`KvsClient`

只是为了体验一下它是多么不靠谱。

第4部分：具有匿名future类型的`KvsClient`

最终的解决方案

第5部分：使`ThreadPool`可共享

第6部分：将`KvsEngine`转换为future

对于服务器，我们将做在客户端中相反的事，为KvsEngine编写一个异步接口。这将表明future和底层运行时是相互独立的，并提供了一系列经验。

第7部分：使用tokio驱动`KvsEngine`

请注意，即使我们自己编写的异步代码很少，tokio本身也在num_cpus个线程间分发异步作业。权衡将CPU密集型作业直接放在网络线程或文件线程上的利弊，例如，将序列化操作放在哪里？

扩展1：使用tokio-fs替换同步文件I/O

干得漂亮，朋友。休息一下吧。

:::tip 以下内容大多翻译自原文：Tokio: Tutorial，推荐阅读。 :::

1 Tokio概述

Tokio是Rust的异步运行时，提供了编写网络应用程序所需的模块。Tokio可灵活部署在大多数系统中，从具有数十个内核的大型服务器到小型嵌入式设备。

概括的说，Tokio提供了几个主要组件：

用于执行异步代码的多线程运行时。
标准库的异步版本。
一个庞大的相关库生态系统。

Tokio 在您的项目中的角色

当您以异步方式编写应用程序时，您可以通过降低同时做许多事情的成本来提升性能。但是，异步Rust代码不会自行运行，因此您必须选择一个运行时来执行它们。Tokio库是应用最广泛的运行时，其使用量超过了所有其他运行时的总和。

此外，Tokio提供了许多有用的实用工具。编写异步代码时，不能使用Rust标准库提供的普通阻塞API，而必须使用它们的异步版本。这些替代版本由Tokio提供，在有意义时这些API将于Rust标准库API保持一致。

Tokio的优势

本章将概述Tokio的一些优点。

快速

Tokio很快，基于Rust，而Rust本身也很快。遵循Rust精神，即目标是用户不应该通过手动编写等效代码来提高性能。

Tokio可扩展，基于async/await语言特性，本身就是可扩展的。在处理网络时，由于延迟，处理连接的速度受到限制，因此扩展的唯一方法是一次处理多个连接。使用async/await语言特性，可以非常方便的增加并发操作的数量，允许您扩展到大规模并发任务。

可靠

Tokio基于Rust编写，而Rust是一种可以让开发者编写可靠且高效软件的语言。大量研究表明，大约70%的高危安全漏洞是由内存安全引起的。使用Rust可以消除应用程序中的这一类错误。

Tokio还非常注重提供一致的行为。Tokio的主要目标是允许用户部署行为可预测的软件，这些软件将日复一日地执行，具有可靠的响应时间，杜绝不可预测的延迟峰值。

简单

借助Rust的async/await特性，编写异步应用程序的复杂性已大大降低。结合Tokio的实用工具和充满活力的生态系统，编写应用程序变得轻而易举。

Tokio在有意义的情况下遵循标准库的命名约定，以使用户可以轻松地将使用标准库编写的代码转换为使用Tokio编写的代码。借助Rust的强大类型系统，轻松交付正确代码的能力是无与伦比的。

灵活

Tokio提供了多种运行时架构。从多线程的工作窃取运行时，到轻量级的单线程运行时，应有尽有。这些运行时中的每一个都带有许多可配置参数，以允许用户根据自己的需要调整它们。

不适用Tokio的场景

尽管Tokio对于许多需要同时做很多事情的项目很有用，但也有一些用例不适合Tokio。

通过在多个线程上并发执行以提速的CPU密集型计算。Tokio专为IO密集型应用程序而设计，其中每个单独的任务大部分时间都在等待IO。如果您的应用程序唯一要做的就是并发计算，那么您应该使用rayon。不过，如果您两种任务都做，仍然可以混合使用Tokio。
读取大量文件。尽管Tokio看上去对于只需要读取大量文件的项目很有用，但与普通线程池相比，Tokio在这里没有任何优势。因为操作系统通常不提供异步文件API。
发送单个Web请求。Tokio的优势是在需要同时做很多事情时。如果你需要使用一个用于异步Rust的库，例如reqwest，但你不需要一次做很多事情，你应该更喜欢那个库的阻塞版本，因为它会让你的项目更简单。当然，使用Tokio仍然有效，但与阻塞API相比并没有真正的优势。如果库不提供阻塞API，请参阅桥接同步代码章节。

获得帮助

在任何时候，如果您遇到困难，您总是可以在Discord或GitHub讨论中获得帮助。请不要担心问“初学者”问题。我们都是从某个地方开始，并乐于提供帮助。

2 环境设置

本教程将带您逐步完成构建Redis客户端和服务器的过程。我们将从使用Rust进行异步编程的基础知识开始，并从那里开始构建。我们将实现Redis命令的一个子集，以全面了解Tokio。

Mini-Redis

您将在本教程中构建的项目在GitHub上以Mini-Redis 的形式提供。Mini-Redis的主要目标是学习Tokio，也得到了很好的评价，但这也意味着Mini-Redis缺少一些您在真正的Redis库中需要的功能。您可以在crates.io上找到可部署于生产环境的Redis库。

我们将在教程中直接使用Mini-Redis，也就是在教程后面部分实现Mini-Redis之前就提前使用。

先修课

我们假设读者熟悉Rust。《Rust Book》就是很好的启蒙读物。

虽然不是必须的，但使用Rust标准库或其他语言编写网络代码的经验将会有所帮助。

我们不需要读者熟悉Redis。

Rust

在教程开始之前，您应该确保安装了Rust工具链。如果没有，最简单的安装方法是使用rustup。

教程需要不低于1.45.0的Rust版本，建议使用最新的Rust版本。

检查计算机上安装的Rust版本，执行：

rustc --version

您将会看到类似rustc 1.46.0 (04488afe3 2020-08-24)的输出。

Mini-Redis server

接下来，安装Mini-Redis server，以在我们完成客户端编写时进行测试。

cargo install mini-redis

启动服务器以确定安装成功：

mini-redis-server

然后，在另一个终端窗口中，尝试使用mini-redis-cli获取键foo的值。

mini-redis-cli get foo

你应该会看到输出为(nil)。

万事俱备

如此，一切就绪。阅读下一章以编写您的第一个异步Rust应用程序。

3 Hello Tokio

作为开胃菜，我们将编写一个非常基础的Rust应用。它将连接到Mini-Redis server，将键Hello的值设置为World，然后再读回键。这将使用Mini-Redis client库完成。

代码

初始化新crate

让我们从生成一个新的Rust App开始：

cargo new my-redis
cd my-redis

添加依赖

然后，向Cargo.toml的[dependencies]中添加以下依赖：

tokio = { version = "1", features = ["full"] }
mini-redis = "0.4"

编写代码

在main.rs编写如下代码：

use mini_redis::{client, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Open a connection to the mini-redis address.
    let mut client = client::connect("127.0.0.1:6379").await?;

    // Set the key "hello" with value "world"
    client.set("hello", "world".into()).await?;

    // Get key "hello"
    let result = client.get("hello").await?;

    println!("got value from the server; result={:?}", result);

    Ok(())
}

确保Mini-Redis server正在运行，在单独的终端中执行：

mini-redis-server

如果你还没有安装mini-redis，执行：

cargo install mini-redis

现在，运行my-redis：

cargo run
got value from the server; result=Some(b"world")

执行成功！

你可以在这里找到全部代码。

代码详解

让我们花一些时间来理解刚刚做的事情。虽然没有太多代码，但执行了很多动作。

let mut client = client::connect("127.0.0.1:6379").await?;

client::connect函数由mini-Redis Crate提供。它将异步的与指定的远端地址建立TCP连接，并在链接成功建立时返回client句柄。虽然这里执行了一个异步操作，但我们编写的代码看起来跟同步代码没什么区别。只有.await动作表明这个操作是异步的。

什么是异步编程？

大多数计算机程序会以与代码编写相同的顺序执行。先执行第一行，再执行下一行，依此类推。在同步编程中，当程序遇到无法立即完成的操作时，它将被阻塞直到操作完成。例如，建立TCP连接需要与网络上的其他节点交换数据，这可能需要大量时间，而在此期间，线程将被阻塞。

而在异步编程中，无法立即完成的操作在后台挂起。该线程没有被阻止，并且可以继续执行其他任务。一旦操作完成，挂起的任务就会恢复，并从挂起的位置继续执行。我们之前的示例中只有一个任务，因此在挂起时什么都没有发生，但是真正的异步程序通常具有大量此类任务。

尽管异步编程可以大幅提升应用程序的执行速度，但通常也会提升程序的复杂度。要求程序员在异步操作完成后跟踪所有可能的状态以恢复工作。以程序员的经验来说，这是一项繁琐且容易出错的任务。

编译时绿色线程

Rust使用称为async/await的特性来实现异步编程。执行异步操作的函数将用async关键字标记。在我们的示例中，connect函数是这样定义的：

use mini_redis::Result;
use mini_redis::client::Client;
use tokio::net::ToSocketAddrs;

pub async fn connect<T: ToSocketAddrs>(addr: T) -> Result<Client> {
    // ...
}

async fn定义看起来像是常规的同步函数，但其实执行的是异步操作。Rust在编译时将async fn转换为一个异步运行的例程。在async fn中的任何.await动作都会将控制权转回线程，以使线程再异步操作挂起在后台的时间里继续执行其他工作。

:::caution 虽然其他语言也实现了async/await，但Rust采用了更独特的方法。最基础的，Rust的异步是惰性操作，这将会导致与其他语言不同的运行时语义。 :::

如果这个解释不够明确，请不要担心。在整个指南中，我们将探索更多关于async/await的内容。

使用`async/await`

在Rust中调用异步函数与调用普通函数没什么区别。但是，仅调用这些函数并不会执行函数体，而是会返回一个值用来表示async fn的操作。这在概念上类似于一个无参闭包。要实际运行该操作，您应该在返回值上使用.await运算符。

以下面的代码为例：

async fn say_world() {
    println!("world");
}

#[tokio::main]
async fn main() {
    // Calling `say_world()` does not execute the body of `say_world()`.
    let op = say_world();

    // This println! comes first
    println!("hello");

    // Calling `.await` on `op` starts executing `say_world`.
    op.await;
}

输出为：

hello
world

async fn的返回值是一个实现了Future trait的匿名类型。

异步`main`函数

用于启动异步应用程序的main函数，与大多数Rust crate中的常用main函数不同。

这是一个async fn
带有#[tokio::main]标记

当我们想要进入异步上下文时，需要使用async fn。但是，异步函数必须由一个运行时执行。该运行时包含异步任务调度器，提供事件I/O、定时器等特性。运行时不会自动启动，所以需要main函数启动它。

#[tokio::main]函数是一个宏。它将async fn main()转换为同步fn main()，初始化一个运行时实例并执行异步main函数。

例如，下面的代码：

#[tokio::main]
async fn main() {
    println!("hello");
}

将转换为：

fn main() {
    let mut rt = tokio::runtime::Runtime::new().unwrap();
    rt.block_on(async {
        println!("hello");
    })
}

后面将会介绍关于Tokio运行时的详细信息。

Cargo特性

本教程依赖于Tokio，并启用了full特性：

tokio = { version = "1", features = ["full"] }

Tokio有很多功能（TCP、UDP、Unix sockets、计时器、同步实用程序、多种调度程序等）。并非所有应用程序都需要完整的Tokio功能。在尝试优化编译时间或最终程序的大小时，用户可以只选择需要使用的功能。

在本教程中，选择Tokio依赖时将使用full功能。

4 生成并发

我们将更换目标，开始研究Redis server端。

首先，将上一章客户端的SET/GET代码移至example文件。这样，就可以在我们的服务端上进行测试了。

mkdir -p examples
mv src/main.rs examples/hello-redis.rs

然后创建一个新的空src/main.rs文件。

接受sockets

我们的Redis服务端需要做的第一件事是接受入站TCP sockets，即使用tokio::net::TcpListener。

:::note Tokio的许多类型的名称，与这些类型在Rust标准库中的同步版本相同。如果定义合理，Tokio将暴露与std完全相同的API，只不过是使用async fn。 :::

TcpListener绑定到6379端口，并在循环中接受套sockets。每个socket都将被处理然后被关闭。现在，我们将读取命令，将其打印到标准输出并响应为一个错误。

use tokio::net::{TcpListener, TcpStream};
use mini_redis::{Connection, Frame};

#[tokio::main]
async fn main() {
    // Bind the listener to the address
    let listener = TcpListener::bind("127.0.0.1:6379").await.unwrap();

    loop {
        // The second item contains the IP and port of the new connection.
        let (socket, _) = listener.accept().await.unwrap();
        process(socket).await;
    }
}

async fn process(socket: TcpStream) {
    // The `Connection` lets us read/write redis **frames** instead of
    // byte streams. The `Connection` type is defined by mini-redis.
    let mut connection = Connection::new(socket);

    if let Some(frame) = connection.read_frame().await.unwrap() {
        println!("GOT: {:?}", frame);

        // Respond with an error
        let response = Frame::Error("unimplemented".to_string());
        connection.write_frame(&response).await.unwrap();
    }
}

现在运行这个循环：

cargo run

在另一个终端里运行hello-redis的示例（即上一章那个SET/GET命令的例子）：

cargo run --example hello-redis

输出应为：

Error: "unimplemented"

在服务端的终端窗口输出应为：

GOT: Array([Bulk(b"set"), Bulk(b"hello"), Bulk(b"world")])

并发

我们的服务端仍有个小问题（除了只响应错误）。它一次仅处理一个入站请求，当一个连接被接受时，服务器将停留在接受循环代码块内，直到响应完全写入socket。

我们希望Redis服务端能够并发处理大量请求，为此，我们需要添加一些并发性。

:::note 并发和并行不是一回事。如果您在两个任务之间交替进行，那么您是在并发处理这两个任务，而不是并行处理。如果是并行，您需要两个人，每个人专门负责一项任务。

使用Tokio的优点之一，是异步代码允许您同时处理许多任务，而不必新建线程并行处理它们。事实上，Tokio可以在一个线程上并发运行多个任务！ :::

为了并发处理连接，我们将为每个入站连接生成一个新任务，并在此任务上处理连接。

接受连接的循环变为：

use tokio::net::TcpListener;

#[tokio::main]
async fn main() {
    let listener = TcpListener::bind("127.0.0.1:6379").await.unwrap();

    loop {
        let (socket, _) = listener.accept().await.unwrap();
        // A new task is spawned for each inbound socket. The socket is
        // moved to the new task and processed there.
        tokio::spawn(async move {
            process(socket).await;
        });
    }
}

任务

Tokio任务是一个异步绿色线程，通过将async块传给tokio::spawn创建。tokio::spawn函数返回一个JoinHandle，调用者可以使用它与生成的任务进行交互。async块可能会有返回值。调用者可以在JoinHandle上使用.await获取返回值。

例如：

#[tokio::main]
async fn main() {
    let handle = tokio::spawn(async {
        // Do some async work
        "return value"
    });

    // Do some other work

    let out = handle.await.unwrap();
    println!("GOT {}", out);
}

等待JoinHandle返回一个Result。当任务在执行过程中遇到错误时，JoinHandle会返回一个Err，这将在任务panic、或任务因运行时关闭被强制取消时发生。

调度程序以任务为单位管理执行，生成任务将提交给Tokio调度程序，调度程序将确保在有工作要做时执行该任务。生成的任务可以在其生成的线程上执行，也可以在运行时其他线程上执行，该任务也可以在产生后在线程间移动。

Tokio中的任务非常轻量。实际上在底层，任务只需要一次64字节的内存分配。应用程序大可放心生成数千个乃至数百万个任务。

`'static`限制

当您在Tokio运行时生成任务时，其类型的生命周期必须是'static。这意味着生成的任务不得引用任务作用域外的任何数据。

:::note 'static总是意味着“永远存在”是一个常见的误解，事实并非如此。仅仅因为一个值是'static并不意味着你有内存泄漏。你可以在常见的Rust生命周期误解中了解到更多内容。 :::

比如下面的代码将无法通过编译：

use tokio::task;

#[tokio::main]
async fn main() {
    let v = vec![1, 2, 3];

    task::spawn(async {
        println!("Here's a vec: {:?}", v);
    });
}

尝试编译将会产生如下错误：

error[E0373]: async block may outlive the current function, but
              it borrows `v`, which is owned by the current function
 --> src/main.rs:7:23
  |
7 |       task::spawn(async {
  |  _______________________^
8 | |         println!("Here's a vec: {:?}", v);
  | |                                        - `v` is borrowed here
9 | |     });
  | |_____^ may outlive borrowed value `v`
  |
note: function requires argument type to outlive `'static`
 --> src/main.rs:7:17
  |
7 |       task::spawn(async {
  |  _________________^
8 | |         println!("Here's a vector: {:?}", v);
9 | |     });
  | |_____^
help: to force the async block to take ownership of `v` (and any other
      referenced variables), use the `move` keyword
  |
7 |     task::spawn(async move {
8 |         println!("Here's a vec: {:?}", v);
9 |     });
  |

发生这种情况是因为默认情况下，变量所有权不会移动到异步代码块中。v向量仍然归主函数所有，而println!一行却借用v。rust编译器向我们解释这一点，甚至建议将第7行更改为task::spawn(async move {，以告诉编译器将v移动到生成的任务中。如此，该任务拥有其需要的所有数据，使其成为'static。

如果必须从多个任务同时访问单个数据，则该数据需要通过诸如Arc之类的同步原语来共享。

注意到错误消息说，参数类型超过了'static生命周期。这个术语可能会相当迷惑，因为'static生命周期一直持续到程序结束，所以如果超过它，不就是有内存泄漏吗？实际上这个消息说的是参数的类型，而不是其值必须超过'static生命周期，并且值可能在其类型不再有效之前就被销毁。

当我们说一个值是'static时，意味着永远保持该值不会是错的。这很重要，因为编译器无法推断新生成的任务会保留多长时间。我们必须确保允许任务永远存在，以便Tokio可以在需要时让任务运行起来。

上面信息框中链接的文章使用术语“受'static限制”，而不是“它的类型比'static寿命长”或“值是'static”来指代T: 'static。这些都意味着同样的事情，但与&'static T中的“用'static'标识”不同。

`Send`限制

tokio::spawn生成的任务必须实现Send。这允许Tokio运行时在任务被.await挂起时，在线程之间移动它们。

当.await调用保存的所有数据都是Send时，任务也是Send的，这有点微妙。当调用.await时，任务将控制权转交给调度程序，在下次执行任务时，它会从上次转交的点恢复。为了确保这个策略生效，在.await之后使用的所有状态都必须由任务保存。如果这些状态为Send的，即可以跨线程移动，则任务本身就可以跨线程移动。相反，如果状态不是Send的，那么任务也不是。

这里的代码是有效的：

use tokio::task::yield_now;
use std::rc::Rc;

#[tokio::main]
async fn main() {
    tokio::spawn(async {
        // The scope forces `rc` to drop before `.await`.
        {
            let rc = Rc::new("hello");
            println!("{}", rc);
        }

        // `rc` is no longer used. It is **not** persisted when
        // the task yields to the scheduler
        yield_now().await;
    });
}

这里则是无效的：

use tokio::task::yield_now;
use std::rc::Rc;

#[tokio::main]
async fn main() {
    tokio::spawn(async {
        let rc = Rc::new("hello");

        // `rc` is used after `.await`. It must be persisted to
        // the task's state.
        yield_now().await;

        println!("{}", rc);
    });
}

尝试编译会得到如下错误：

error: future cannot be sent between threads safely
   --> src/main.rs:6:5
    |
6   |     tokio::spawn(async {
    |     ^^^^^^^^^^^^ future created by async block is not `Send`
    | 
   ::: [..]spawn.rs:127:21
    |
127 |         T: Future + Send + 'static,
    |                     ---- required by this bound in
    |                          `tokio::task::spawn::spawn`
    |
    = help: within `impl std::future::Future`, the trait
    |       `std::marker::Send` is not  implemented for
    |       `std::rc::Rc<&str>`
note: future is not `Send` as this value is used across an await
   --> src/main.rs:10:9
    |
7   |         let rc = Rc::new("hello");
    |             -- has type `std::rc::Rc<&str>` which is not `Send`
...
10  |         yield_now().await;
    |         ^^^^^^^^^^^^^^^^^ await occurs here, with `rc` maybe
    |                           used later
11  |         println!("{}", rc);
12  |     });
    |     - `rc` is later dropped here

我们将在下一章更深入地讨论这个错误的一个特例。

保存值

我们现在将实现process函数来处理传入的命令，使用HashMap来存储值。SET命令将值插入到HashMap中，而GET值将读取这些值。此外，我们将使用循环从而让每个连接能够接受多个命令。

use tokio::net::TcpStream;
use mini_redis::{Connection, Frame};

async fn process(socket: TcpStream) {
    use mini_redis::Command::{self, Get, Set};
    use std::collections::HashMap;

    // A hashmap is used to store data
    let mut db = HashMap::new();

    // Connection, provided by `mini-redis`, handles parsing frames from
    // the socket
    let mut connection = Connection::new(socket);

    // Use `read_frame` to receive a command from the connection.
    while let Some(frame) = connection.read_frame().await.unwrap() {
        let response = match Command::from_frame(frame).unwrap() {
            Set(cmd) => {
                // The value is stored as `Vec<u8>`
                db.insert(cmd.key().to_string(), cmd.value().to_vec());
                Frame::Simple("OK".to_string())
            }
            Get(cmd) => {
                if let Some(value) = db.get(cmd.key()) {
                    // `Frame::Bulk` expects data to be of type `Bytes`. This
                    // type will be covered later in the tutorial. For now,
                    // `&Vec<u8>` is converted to `Bytes` using `into()`.
                    Frame::Bulk(value.clone().into())
                } else {
                    Frame::Null
                }
            }
            cmd => panic!("unimplemented {:?}", cmd),
        };

        // Write the response to the client
        connection.write_frame(&response).await.unwrap();
    }
}

现在，启动服务：

cargo run

在另一个终端里运行hello-redis示例：

cargo run --example hello-redis

现在的输出应为：

got value from server; result=Some(b"world")

我们现在可以查询和设置键值了，但是有一个问题：这些键值并不能在连接之间共享。如果另一个套接字连接并尝试GET键hello，它将查询不到任何东西。

你可以在这里找到完整的代码。

在下一章中，我们将为所有套接字实现数据持久化。

5 共享状态

到目前为止，我们有了键值服务端，但却存在一个缺陷：状态并未在连接之间共享。本文将解决这个问题。

策略

在Tokio中共享状态通常有以下几种方式。

使用互斥锁封装共享状态。
再生成一个任务，专门用于管理状态，并使用消息传递操作状态。

第一种方法通常用于简单数据，而第二种方法用于需要异步工作（例如I/O原语）的场景。在本章中，共享状态是一个hashmap，并且操作是insert和get。这些操作都不是异步的，因此我们将使用互斥锁Mutex。

下一章将介绍后一种方法。

添加`bytes`依赖

Mini-Redis crate将使用bytes crate的Bytes代替Vec<u8>。Bytes专门用于为网络编程提供强大的字节阵列结构。相较于Vec<u8>，它添加了强大的浅拷贝功能。换句话说，在Bytes实例上调用clone()将不会复制底层数据，只会让实例的引用计数器加一，即Byte实例仅是某个底层数据的引用计数器句柄，类似于添加了新功能的Arc<Vec<u8>>。

要使用bytes，请在Cargo.toml的[dependencies]中添加以下内容：

bytes = "1"

初始化`HashMap`

为了让hashmap能够在许多任务和许多线程中共享，需要将其封装在Arc<Mutex<_>>中。

首先，为方便使用，在use之后给该类型起别名。

use bytes::Bytes;
use std::collections::HashMap;
use std::sync::{Arc, Mutex};

type Db = Arc<Mutex<HashMap<String, Bytes>>>;

然后，更新main函数以初始化Hashmap并将Arc的句柄传给process函数。使用Arc允许从许多任务中同时引用Hashmap，并可能在许多线程上运行。在整个Tokio中，术语句柄指的是那些可以访问某些共享状态的值。

use tokio::net::TcpListener;
use std::collections::HashMap;
use std::sync::{Arc, Mutex};

#[tokio::main]
async fn main() {
    let listener = TcpListener::bind("127.0.0.1:6379").await.unwrap();

    println!("Listening");

    let db = Arc::new(Mutex::new(HashMap::new()));

    loop {
        let (socket, _) = listener.accept().await.unwrap();
        // Clone the handle to the hash map.
        let db = db.clone();

        println!("Accepted");
        tokio::spawn(async move {
            process(socket, db).await;
        });
    }
}

关于使用`std::sync::Mutex`

注意这里使用了std::sync::mutex而不是tokio::sync::Mutex来封装Hashmap。一个常见的错误是在异步代码中无条件使用tokio::sync::mutex。异步互斥锁用于锁住所有.await操作。

同步互斥锁在等待获取锁定时会阻塞当前线程，于是，将阻止其他任务处理。而如果使用tokio::sync::Mutex通常没有作用，因为异步互斥锁的在内部也使用同步互斥锁。

根据经验，只要竞争不高，并且不会在调用.await时保持锁，则使用异步代码内的同步互斥锁也是可以的。此外，也可以考虑使用parking_lot::mutex作为std::sync::Mutex的更快替代方案。

修改`process()`

process()函数不再需要初始化Hashmap，现在，它将接受一个共享的句柄作为参数，并且需要在使用前锁定该Hashmap。要注意的是Hashmap的值现在是Bytes类型（可以高效的复制），因此也需要修改。

use tokio::net::TcpStream;
use mini_redis::{Connection, Frame};

async fn process(socket: TcpStream, db: Db) {
    use mini_redis::Command::{self, Get, Set};

    // Connection, provided by `mini-redis`, handles parsing frames from
    // the socket
    let mut connection = Connection::new(socket);

    while let Some(frame) = connection.read_frame().await.unwrap() {
        let response = match Command::from_frame(frame).unwrap() {
            Set(cmd) => {
                let mut db = db.lock().unwrap();
                db.insert(cmd.key().to_string(), cmd.value().clone());
                Frame::Simple("OK".to_string())
            }           
            Get(cmd) => {
                let db = db.lock().unwrap();
                if let Some(value) = db.get(cmd.key()) {
                    Frame::Bulk(value.clone())
                } else {
                    Frame::Null
                }
            }
            cmd => panic!("unimplemented {:?}", cmd),
        };

        // Write the response to the client
        connection.write_frame(&response).await.unwrap();
    }
}

任务、线程与竞争

当竞争较少时，使用互斥锁阻保护少量关键变量是可行的策略。当出现锁竞争时，执行任务的线程将会阻塞并等待互斥锁释放。这不仅会阻塞当前任务，而且还将阻止在当前线程上调度任何其他任务。

默认情况下，Tokio运行时使用多线程调度程序。任务被安排在由运行时管理的任意数量的线程上。如果需要调度执行大量任务，并且他们都需要访问互斥锁，则将产生竞争。不过，如果启用了current_thread运行时，则永远不会产生互斥锁竞争。

:::note current_thread运行时是一个轻量级的单线程运行时。当仅需生成少量任务并打开少量sockets时，这是一个不错的选择。例如，当在异步客户端库之上提供同步API时，就可以使用这个选项。 :::

即使同步互斥锁竞争成为问题，也很少使用Tokio的互斥锁，而是应当考虑：

使用一个专用任务，以管理状态并使用消息传递。
互斥锁分片。
重组代码以避免使用互斥锁。

在我们的例子中，由于各个键相互独立，因此可以选择将互斥锁分片。因此，我们将用N个不同的实例代替例子中的单个Mutex<HashMap<_, _>>。

type ShardedDb = Arc<Vec<Mutex<HashMap<String, Vec<u8>>>>>;

fn new_sharded_db(num_shards: usize) -> ShardedDb {
    let mut db = Vec::with_capacity(num_shards);
    for _ in 0..num_shards {
        db.push(Mutex::new(HashMap::new()));
    }
    Arc::new(db)
}

如此，找到任何给定键就需要两个步骤：先是要确定该键在哪个分片中，再在这个HashMap中查找该键。

let shard = db[hash(key) % db.len()].lock().unwrap();
shard.insert(key, value);

上面的这段简单实现要求确定的分片数量，而且一旦创建了分片映射分片数量就不能更改。dashmap crate提供了一个更复杂的分片哈希映射的实现。

在`.await`上持有`MutexGuard`

你可能会编写这样的代码：

use std::sync::{Mutex, MutexGuard};

async fn increment_and_do_stuff(mutex: &Mutex<i32>) {
    let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
    *lock += 1;

    do_something_async().await;
} // lock goes out of scope here

当你尝试并发调用那些调用此函数的代码时，将遇到以下错误消息：

error: future cannot be sent between threads safely
   --> src/lib.rs:13:5
    |
13  |     tokio::spawn(async move {
    |     ^^^^^^^^^^^^ future created by async block is not `Send`
    |
   ::: /playground/.cargo/registry/src/github.com-1ecc6299db9ec823/tokio-0.2.21/src/task/spawn.rs:127:21
    |
127 |         T: Future + Send + 'static,
    |                     ---- required by this bound in `tokio::task::spawn::spawn`
    |
    = help: within `impl std::future::Future`, the trait `std::marker::Send` is not implemented for `std::sync::MutexGuard<'_, i32>`
note: future is not `Send` as this value is used across an await
   --> src/lib.rs:7:5
    |
4   |     let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
    |         -------- has type `std::sync::MutexGuard<'_, i32>` which is not `Send`
...
7   |     do_something_async().await;
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^ await occurs here, with `mut lock` maybe used later
8   | }
    | - `mut lock` is later dropped here

这是因为std::sync::MutexGuard类型不可Send，即你不能将互斥锁发送到另一个线程，于是这将导致错误，因为Tokio运行时可以在每个.await时在线程间移动任务。为避免这种情况，你应该重组代码，使互斥锁在.await之前析构：

// This works!
async fn increment_and_do_stuff(mutex: &Mutex<i32>) {
    {
        let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
        *lock += 1;
    } // lock goes out of scope here

    do_something_async().await;
}

请注意这样也不行：

use std::sync::{Mutex, MutexGuard};

// This fails too.
async fn increment_and_do_stuff(mutex: &Mutex<i32>) {
    let mut lock: MutexGuard<i32> = mutex.lock().unwrap();
    *lock += 1;
    drop(lock);

    do_something_async().await;
}

目前，编译器仅根据作用域推断future是否为Send。将来，编译器可能会支持显式析构，但现在，您只能使用显式作用域。

请注意，这里讨论的错误也在并发一章的Send限制小节中讨论过。

如果您想尝试某种方式，通过生成不需要Send的并发任务来绕过此问题，是不可行的。因为如果Tokio在任务持有锁时将任务挂起在.await处，则可能会在同一线程上调度运行其他任务，而这里的其他任务也可能尝试获取该互斥锁，这将导致死锁，即等待获取互斥锁的任务会阻塞持有互斥锁的任务释放锁。

下面我们将讨论一些上述错误消息的方法：

重构你的代码，不跨`.await`持锁

我们已经在上面的代码片段中看到了一个例子，但是还有一些更健壮的代码实现。例如，你可以将互斥锁包装在一个结构体中，并只在非异步方法中锁定互斥锁：

use std::sync::Mutex;

struct CanIncrement {
    mutex: Mutex<i32>,
}
impl CanIncrement {
    // This function is not marked async.
    fn increment(&self) {
        let mut lock = self.mutex.lock().unwrap();
        *lock += 1;
    }
}

async fn increment_and_do_stuff(can_incr: &CanIncrement) {
    can_incr.increment();
    do_something_async().await;
}

这种模式保证你不会遇到Send错误，因为MutexGuard不会出现在异步函数中。

生成一个任务来管理状态并使用消息传递对其进行操作

这是本章开头提到的第二种方法，通常在共享的资源是I/O资源时使用。有关详细信息，请参阅下一章。

使用Tokio的异步互斥锁

也可以使用Tokio提供的tokio::sync::Mutex类型。Tokio互斥锁的主要特性是它可以跨.await 保存而不会出现任何问题。也就是说，异步互斥锁比普通互斥锁开销更大，因此一般建议从前面两种方法中选一种实现。

use tokio::sync::Mutex; // note! This uses the Tokio mutex

// This compiles!
// (but restructuring the code would be better in this case)
async fn increment_and_do_stuff(mutex: &Mutex<i32>) {
    let mut lock = mutex.lock().await;
    *lock += 1;

    do_something_async().await;
} // lock goes out of scope here

6 消息通道

现在我们已经了解了一些关于Tokio的并发性，现在让我们在客户端上应用它。把我们之前写的服务端代码放到一个显式的二进制文件中：

mkdir src/bin
mv src/main.rs src/bin/server.rs

创建一个包含客户端代码的新二进制文件：

touch src/bin/client.rs

在此文件中，您将编写本章的代码。要记住在运行客户端前，必须首先在单独的终端中启动服务端：

cargo run --bin server

再用单独的终端里运行客户端：

cargo run --bin client

让我们开始编码！

假设我们要并发执行两个Redis命令。我们可以为每个命令生成一个任务，然后这两个命令将同时发生。

起初，我们可能会进行如下尝试：

use mini_redis::client;

#[tokio::main]
async fn main() {
    // Establish a connection to the server
    let mut client = client::connect("127.0.0.1:6379").await.unwrap();

    // Spawn two tasks, one gets a key, the other sets a key
    let t1 = tokio::spawn(async {
        let res = client.get("hello").await;
    });

    let t2 = tokio::spawn(async {
        client.set("foo", "bar".into()).await;
    });

    t1.await.unwrap();
    t2.await.unwrap();
}

上面的代码无法通过编译，因为这两个任务都需要以某种方式访问client。由于Client没有实现Copy，所以如果没有一些代码来实现共享，就无法编译。此外，Client::set采用&mut self，这意味着需要互斥存取才能调用。我们可以为每个任务打开一个连接，但这并不理想。我们不能使用std::sync::Mutex因为.await需要在持有锁的情况下调用。我们可以使用tokio::sync::Mutex，但这只会允许一个运行中的请求。如果客户端实现了流水线，异步互斥锁还将导致连接不能被充分利用。

消息传递

解决方案是使用消息传递。该模式需要生成一个专门的任务来管理client资源。任何希望发出请求的任务，都会向client任务发送消息。client任务代理发送者发出请求，并将响应返回给发送者。

使用此策略，可以只建立一个连接。client管理任务能够获得互斥存取权限，以便调用get和set。此外，通道也起到了缓冲区的作用。即使client任务忙时，操作也可能会被发送到client任务。当client任务可用于处理新请求时，它就会从通道中获取下一个请求。这可以带来更好的吞吐量，并可扩展以支持连接池。

Tokio的通道原语

Tokio提供了许多通道，每个通道都有不同的用途。

mpsc：多生产者，单消费者通道。可以发送许多值。
oneshot：单生产者，单消费者渠道。可以发送单个值。
broadcast：多生产者，多消费者。可以发送许多值，每个消费者都能看到每个值。
watch：单生产者，多消费者。可以发送许多值，但不保留任何历史记录。消费者只能看到最新的值。

如果您需要一个多生产者多消费者通道，其中只有一个消费者可以看到每条消息，您可以使用async-channel crate。在异步Rust之外还有一些通道可以使用，例如std::sync::mpsc和crossbeam::channel。这些通道在等待消息时将阻塞线程，这在异步代码中是不允许的。

在本节中，我们将使用mpsc和oneshot，其他类型的消息传递通道将在后面的章节中探讨。你可在这里找到本节的完整代码。

定义消息类型

在大多数情况下，当使用消息传递时，接收消息的任务会响应多个命令。在我们的例子中，任务将响应GET和SET命令。为了对此建模，我们首先定义一个Command枚举并为每个命令指定一个成员变量。

use bytes::Bytes;

#[derive(Debug)]
enum Command {
    Get {
        key: String,
    },
    Set {
        key: String,
        val: Bytes,
    }
}

创建通道

在main函数中新建一个mpsc通道：

use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    // Create a new channel with a capacity of at most 32.
    let (tx, mut rx) = mpsc::channel(32);

    // ... Rest comes here
}

mpsc通道用于向管理redis连接的任务发送命令，多生产者特性允许从多个任务发送消息。创建通道返回两个值，一个发送端和一个接收端，两个句柄各有用处。他们可能会被转移到不同的任务中。

创建通道的容量为32，如果消息的发送速度快于接收速度，通道将存储它们。一旦有32条消息存储在通道中，调用send(...).await就将进入睡眠状态，直到接收方取走了一条消息为止。

从多个任务发送是通过克隆Sender来完成的。例如：

use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    let (tx, mut rx) = mpsc::channel(32);
    let tx2 = tx.clone();

    tokio::spawn(async move {
        tx.send("sending from first handle").await;
    });

    tokio::spawn(async move {
        tx2.send("sending from second handle").await;
    });

    while let Some(message) = rx.recv().await {
        println!("GOT = {}", message);
    }
}

两条消息都发送到同一个Receiver句柄。mpsc通道的接收端无法被克隆。

当所有Sender超出作用域或是被析构时，就无法再向通道发送更多消息。此时，在Receiver上调用recv会返回None，表示所有发送端都不在了，通道已关闭。

在我们管理Redis连接的任务中，当通道关闭时该任务就将关闭Redis连接，因为该连接将不再被使用。

生成管理任务

接下来，生成一个专门处理通道的消息的任务。首先，客户端建立到Redis服务端的连接；然后，通过Redis连接发送收到的命令。

use mini_redis::client;
// The `move` keyword is used to **move** ownership of `rx` into the task.
let manager = tokio::spawn(async move {
    // Establish a connection to the server
    let mut client = client::connect("127.0.0.1:6379").await.unwrap();

    // Start receiving messages
    while let Some(cmd) = rx.recv().await {
        use Command::*;

        match cmd {
            Get { key } => {
                client.get(&key).await;
            }
            Set { key, val } => {
                client.set(&key, val).await;
            }
        }
    }
});

现在可以修改任务，使用通道发送命令，以代替直接使用Redis连接发送命令。

// The `Sender` handles are moved into the tasks. As there are two
// tasks, we need a second `Sender`.
let tx2 = tx.clone();

// Spawn two tasks, one gets a key, the other sets a key
let t1 = tokio::spawn(async move {
    let cmd = Command::Get {
        key: "hello".to_string(),
    };

    tx.send(cmd).await.unwrap();
});

let t2 = tokio::spawn(async move {
    let cmd = Command::Set {
        key: "foo".to_string(),
        val: "bar".into(),
    };

    tx2.send(cmd).await.unwrap();
});

在main函数最后，在join句柄上使用.await，以确保命令在进程退出前能够执行完毕。

接收响应

最后一步是从管理任务接收响应。GET命令需要获取值，而SET命令需要知道操作是否成功完成。

我们使用oneshot通道，以传递响应。oneShot通道是一种单次生产、单次消费的通道，专门针对对发送单个值的场景进行了优化。在我们的例子中，这单个值就是响应。

和MPSC类似，oneShot::Channel()返回一对发送端、接收端句柄。

use tokio::sync::oneshot;

let (tx, rx) = oneshot::channel();

与mpsc不同的是，它无需指定通道数量，因为始终是一，此外，这两个句柄都不能克隆。

要从管理任务接收响应，在发送命令之前，就应创建oneshot通道。通道的发送端包含在命令中传给管理任务，接收端则用于接收响应结果。

首先，修改Command以包含Sender。为了方便起见，使用类型别名来指代Sender。

use tokio::sync::oneshot;
use bytes::Bytes;

/// Multiple different commands are multiplexed over a single channel.
#[derive(Debug)]
enum Command {
    Get {
        key: String,
        resp: Responder<Option<Bytes>>,
    },
    Set {
        key: String,
        val: Bytes,
        resp: Responder<()>,
    },
}

/// Provided by the requester and used by the manager task to send
/// the command response back to the requester.
type Responder<T> = oneshot::Sender<mini_redis::Result<T>>;

然后，修改管理任务以能够发送包含oneshot::Sender的命令。

let t1 = tokio::spawn(async move {
    let (resp_tx, resp_rx) = oneshot::channel();
    let cmd = Command::Get {
        key: "hello".to_string(),
        resp: resp_tx,
    };

    // Send the GET request
    tx.send(cmd).await.unwrap();

    // Await the response
    let res = resp_rx.await;
    println!("GOT = {:?}", res);
});

let t2 = tokio::spawn(async move {
    let (resp_tx, resp_rx) = oneshot::channel();
    let cmd = Command::Set {
        key: "foo".to_string(),
        val: "bar".into(),
        resp: resp_tx,
    };

    // Send the SET request
    tx2.send(cmd).await.unwrap();

    // Await the response
    let res = resp_rx.await;
    println!("GOT = {:?}", res);
});

最后，修改管理任务，以使用oneshot通道返回响应。

while let Some(cmd) = rx.recv().await {
    match cmd {
        Command::Get { key, resp } => {
            let res = client.get(&key).await;
            // Ignore errors
            let _ = resp.send(res);
        }
        Command::Set { key, val, resp } => {
            let res = client.set(&key, val).await;
            // Ignore errors
            let _ = resp.send(res);
        }
    }
}

调用oneshot::Sender的send会立即完成，不需要使用.await。这是因为在oneshot通道上send总是立刻失败或成功，不会有任何等待。

在oneshot通道上发送值时，如果接收端被析构则将返回Err，以表明接收端不再关注响应。在我们的例子中，接收端可以不接收响应，因此无需处理resp.send(...)返回的Err。

你可以在这里找到完整代码。

背压调节和通道限制

当引入并发或队列时，一定要确保队列是有限的，以使系统能优雅地处理负载。无限的队列最终将耗尽所有可用的内存，并导致系统以不可预测的方式宕机。

Tokio能够避免定义不明确的队列，主要也是因为Tokio中的异步操作是惰性求值。考虑以下代码：

loop {
    async_op();
}

如果异步操作立即求值，则此循环会不停的将新的async_op排入队列，且并不关心之前的操作是否完成，如此则会隐式的产生无限制队列。基于回调和立即求future的系统尤其容易受到上述影响。

但是，使用Tokio和异步Rust，上述代码片段的async_op根本不会运行，因为.await从未被调用。如果修改上述代码，加入.await，则循环会等待操作完成才进入下一次循环。

loop {
    // Will not repeat until `async_op` completes
    async_op().await;
}

使用并发和队列时必须明确引入。这样做的方法包括：

tokio::Spawn
select!
join!
mpsc::channel

这样做时，请注意确保并发的总数有上限。例如，在编写接受TCP连接的循环时，请确保打开的sockets的总数有上限。使用mpsc::channel时，选择合适的通道容量。针对特定的应用程序选择特定的约束限制。

编写可靠的Tokio应用程序的一个关键，就是留意并挑选良好的限制值。

7 I/O

Tokio中的I/O以与std中的运行方式几乎一样，只不过是异步的。有一个读trait（AsyncRead）和一个写trait（AsyncWrite）。一些类型已经良好的地实现了这些trait（TCPStream、File，Stdout）。许多数据结构也实现了AsyncRead和AsyncWrite（如Vec<u8>和&[u8]），这使得我们可以在需要用到reader和writer的地方使用字节数组。

本章将通过一些例子演示使用Tokio时的基本I/O读写操作。下一章江更加深入的介绍高级的I/O示例。

`AsyncRead`和`AsyncWrite`

这两个trait为异步读写字节流提供了基础工具。我们通常不直接调用这些trait上的方法，类似于你不会手动调用future trait的poll方法，而是使用AsyncReadExt和AsyncWriteExt提供的工具方法。

让我们简要看一下其中的一些方法，所有这些函数都是异步的，必须与配合.await使用。

`async fn read()`

AsyncReadExt::read提供了一种将数据读取到缓冲区的异步方法，返回值为读到的字节数。

注意：当read()返回Ok(0)时，意味着该流已关闭。任何调用read()的future江立即完成并返回Ok(0)。比如对TcpStream的实例，这表示socket的读端已关闭。

use tokio::fs::File;
use tokio::io::{self, AsyncReadExt};

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt").await?;
    let mut buffer = [0; 10];

    // read up to 10 bytes
    let n = f.read(&mut buffer[..]).await?;

    println!("The bytes: {:?}", &buffer[..n]);
    Ok(())
}

`async fn read_to_end()`

AsyncReadExt::read_to_end将读取流中的所有字节，直到遇到EOF。

use tokio::io::{self, AsyncReadExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut f = File::open("foo.txt").await?;
    let mut buffer = Vec::new();

    // read the whole file
    f.read_to_end(&mut buffer).await?;
    Ok(())
}

`async fn write()`

AsyncWriteExt::write将一个缓冲区写入writer，返回值为写入的字节数。

use tokio::io::{self, AsyncWriteExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut file = File::create("foo.txt").await?;

    // Writes some prefix of the byte string, but not necessarily all of it.
    let n = file.write(b"some bytes").await?;

    println!("Wrote the first {} bytes of 'some bytes'.", n);
    Ok(())
}

`async fn write_all()`

AsyncWriteExt::write_all将整个缓冲区写入writer。

use tokio::io::{self, AsyncWriteExt};
use tokio::fs::File;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut file = File::create("foo.txt").await?;

    file.write_all(b"some bytes").await?;
    Ok(())
}

这两个trait都包括许多其他有用的方法，详情请参阅API文档。

帮助函数

此外，就像std，tokio::io模块也包含许多实用的工具函数，以及用于标准输入、标准输出和标准错误的API。例如，使用tokio::io::copy异步将读端的所有内容复制到写端。

use tokio::fs::File;
use tokio::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let mut reader: &[u8] = b"hello";
    let mut file = File::create("foo.txt").await?;

    io::copy(&mut reader, &mut file).await?;
    Ok(())
}

留意到上例实际上利用了实现了AsyncRead的字节数组。

回音服务端

让我们上手试一下异步I/O，来编写一个简单的回音服务端。

回音服务端绑定一个TcpListener，使用一个循环接收入站连接。对于每个入站连接，从socket读取数据，然后立即将读到的数据写回socket。客户端将数据发送到服务器，然后接收完全相同的数据。

我们将使用两种稍微不同的策略分别实现回音服务端。

使用`io::copy()`

首先，我们将使用io:copy实现回音逻辑。

您可以在新的二进制文件中写入此代码：

touch src/bin/echo-server-copy.rs

您可以通过以下方式启动（或仅检查编译）：

cargo run --bin echo-server-copy

您将可以直接使用标准命令行工具（例如telnet）测试服务端，或使用tokio::net::TcpStream的文档中示例的简单客户测试服务端。

TCP服务端使用循环接受请求，每接受一个socket就生成一个新任务。

use tokio::io;
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:6142").await?;

    loop {
        let (mut socket, _) = listener.accept().await?;

        tokio::spawn(async move {
            // Copy data here
        });
    }
}

之前提到过，该工具函数将接受一个读端和一个写端，并将数据从一端拷贝到另一端，但此处我们只有一个Tcpstream，而这一个值同时实现了AsyncRead和AsyncWrite。由于io::copy要求读端和写端均为&mut，如果这两个参数都写成socket的话就不能通过编译。

// This fails to compile
io::copy(&mut socket, &mut socket).await

拆分读端和写端

要解决问题，我们需要将socket拆分为读句柄和写句柄，特定的类型有特定的最佳读/写端拆分方式。

任何读端+写端的类型，均可用io::split工具函数拆分，函数接受一个参数，返回一对读句柄/写句柄。这两个句柄可以独立使用，比如用在不同的任务中。

例如，回音客户端可以按如下的方式处理的并发读取：

use tokio::io::{self, AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;

#[tokio::main]
async fn main() -> io::Result<()> {
    let socket = TcpStream::connect("127.0.0.1:6142").await?;
    let (mut rd, mut wr) = io::split(socket);

    // Write data in the background
    tokio::spawn(async move {
        wr.write_all(b"hello\r\n").await?;
        wr.write_all(b"world\r\n").await?;

        // Sometimes, the rust type inferencer needs
        // a little help
        Ok::<_, io::Error>(())
    });

    let mut buf = vec![0; 128];

    loop {
        let n = rd.read(&mut buf).await?;

        if n == 0 {
            break;
        }

        println!("GOT {:?}", &buf[..n]);
    }

    Ok(())
}

io::split能够接受任何实现了AsyncRead + AsyncWrite的类型并返回独立的句柄，是因为io::split内部使用一个Arc和一个Mutex。我们可以使用TcpStream避免使用此开销。TcpStream提供了两个专用的拆分函数。

TcpStream::split接受一个流的引用，返回一对读/写句柄。由于使用了引用，因此两个句柄都必须呆在这个调用split()的任务中。这种专用拆分为零成本，不需要Arc或Mutex。TcpStream还提供了into_split函数，以仅使用一个Arc为代价，让句柄能够在任务间移动。

由于调用io::copy()的任务就拥有TcpStream的所有权，因此我们可以使用TcpStream::split。服务端中处理回音逻辑的任务变成：

tokio::spawn(async move {
    let (mut rd, mut wr) = socket.split();
    
    if io::copy(&mut rd, &mut wr).await.is_err() {
        eprintln!("failed to copy");
    }
});

你可以在这里找到完整的代码。

手动拷贝

现在，让我们来了解一下如何通过手动复制数据的方式编写回音服务端。这里，我们需要使用AsyncReadExt::read和AsyncWriteExt::write_all。

完整的回音服务端如下：

use tokio::io::{self, AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:6142").await?;

    loop {
        let (mut socket, _) = listener.accept().await?;

        tokio::spawn(async move {
            let mut buf = vec![0; 1024];

            loop {
                match socket.read(&mut buf).await {
                    // Return value of `Ok(0)` signifies that the remote has
                    // closed
                    Ok(0) => return,
                    Ok(n) => {
                        // Copy the data back to socket
                        if socket.write_all(&buf[..n]).await.is_err() {
                            // Unexpected socket error. There isn't much we can
                            // do here so just stop processing.
                            return;
                        }
                    }
                    Err(_) => {
                        // Unexpected socket error. There isn't much we can do
                        // here so just stop processing.
                        return;
                    }
                }
            }
        });
    }
}

（您可以将此代码放入src/bin/echo-server.rs中，并使用cargo run --bin echo-server运行）。

我们来逐行理解代码。首先，由于使用AsyncRead和AsyncWrite实用工具，因此必须引入这些扩展trait。

use tokio::io::{self, AsyncReadExt, AsyncWriteExt};

分配缓冲区

我们的策略是将一些从socket中读取的数据放入缓冲区，然后将缓冲区的内容写回到socket中。

let mut buf = vec![0; 1024];

这里显式禁止使用栈缓冲区。回想前面，我们注意到，跨.await调用存活的所有任务数据都必须保存在任务中。上面的代码中，buf跨.await调用使用。所有任务数据都存储在这单个分配中。您可以将其视为一个enum，其中每个成员变量都是需要保存在任务中以便特定的.await调用的数据。

如果缓冲区是一个栈数组，则为每个接受的socket生成的任务内部结构可能看起来像：

struct Task {
    // internal task fields here
    task: enum {
        AwaitingRead {
            socket: TcpStream,
            buf: [BufferType],
        },
        AwaitingWriteAll {
            socket: TcpStream,
            buf: [BufferType],
        }

    }
}

如果将栈数组当做缓冲区，则它将内联存储在任务结构体中。这将使任务结构体变得非常大。另外，缓冲的大小通常是页大小，于是，这将使任务大小变得很尴尬：$页大小 + 一些额外字节。

当然，编译器将异步代码块进行了优化，性能远超基本的enmu。实际上，变量并不会像enum可能需要的那样，在成员间移动。但是，任务结构体大小至少与最大的变量一样大。

因此，为缓冲区使用专用的分配通常能更加高效。

处理EOF

当关闭了TCP流的读端后，再调用read()将返回Ok(0)，此时必须让读循环终止。忘记在已经EOF的内容上继续循环读取，是一个常见的错误。

loop {
    match socket.read(&mut buf).await {
        // Return value of `Ok(0)` signifies that the remote has
        // closed
        Ok(0) => return,
        // ... other cases handled here
    }
}

忘记停止读循环，通常会导致CPU使用率100％的无限循环。当socket关闭时，socket.read()将立即返回，然后不停的重复循环。

你可以在这里找到完整的代码。

8 组帧

现在，我们将使用我们刚刚学到的I/O相关知识，实现Mini-Redis组帧层。组帧是获取字节流并将其转换为帧流的过程，帧是两节点间传输数据的单位。Redis协议帧定义如下：

use bytes::Bytes;

enum Frame {
    Simple(String),
    Error(String),
    Integer(u64),
    Bulk(Bytes),
    Null,
    Array(Vec<Frame>),
}

请留意该帧定义是如何使用没有语义的数据组成的，命令解析和实现位于更上层。

对于HTTP，帧可能看起来像：

enum HttpFrame {
    RequestHead {
        method: Method,
        uri: Uri,
        version: Version,
        headers: HeaderMap,
    },
    ResponseHead {
        status: StatusCode,
        version: Version,
        headers: HeaderMap,
    },
    BodyChunk {
        chunk: Bytes,
    },
}

为了实现Mini-Redis的帧，我们将实现Connection结构体，里面封装了一个TcpStream用以读/写mini_redis::Frame。

use tokio::net::TcpStream;
use mini_redis::{Frame, Result};

struct Connection {
    stream: TcpStream,
    // ... other fields here
}

impl Connection {
    /// Read a frame from the connection.
    /// 
    /// Returns `None` if EOF is reached
    pub async fn read_frame(&mut self)
        -> Result<Option<Frame>>
    {
        // implementation here
    }

    /// Write a frame to the connection.
    pub async fn write_frame(&mut self, frame: &Frame)
        -> Result<()>
    {
        // implementation here
    }
}

你可以在这里找到Redis Wire协议的详细信息，可以在这里找到完整的代码。

缓冲读

read_frame方法会等待收到整个帧才返回，而调用一次TcpStream::read()返回的数据长度不确定，可能包含整个帧，或是部分帧，也可能包含了多个帧。如果收到的是部分帧，则应缓冲数据并从socket中读取更多数据。如果收到的是多个帧，则应返回第一帧，缓冲其余数据，以等待下一次read_frame调用。

为了实现上述功能，需要给Connection添加一个读缓冲区字段，以数据将从socket读取到读缓冲区。解析帧时，再从缓冲区中返回并删除相应的数据即可。

我们选用BytesMut作为缓冲区类型，即Bytes的可变版本。

use bytes::BytesMut;
use tokio::net::TcpStream;

pub struct Connection {
    stream: TcpStream,
    buffer: BytesMut,
}

impl Connection {
    pub fn new(stream: TcpStream) -> Connection {
        Connection {
            stream,
            // Allocate the buffer with 4kb of capacity.
            buffer: BytesMut::with_capacity(4096),
        }
    }
}

接下来实现read_frame()方法：

use tokio::io::AsyncReadExt;
use bytes::Buf;
use mini_redis::Result;

pub async fn read_frame(&mut self)
    -> Result<Option<Frame>>
{
    loop {
        // Attempt to parse a frame from the buffered data. If
        // enough data has been buffered, the frame is
        // returned.
        if let Some(frame) = self.parse_frame()? {
            return Ok(Some(frame));
        }

        // There is not enough buffered data to read a frame.
        // Attempt to read more data from the socket.
        //
        // On success, the number of bytes is returned. `0`
        // indicates "end of stream".
        if 0 == self.stream.read_buf(&mut self.buffer).await? {
            // The remote closed the connection. For this to be
            // a clean shutdown, there should be no data in the
            // read buffer. If there is, this means that the
            // peer closed the socket while sending a frame.
            if self.buffer.is_empty() {
                return Ok(None);
            } else {
                return Err("connection reset by peer".into());
            }
        }
    }
}

让我们逐行分析这段代码。read_frame方法内是一个循环：首先调用self.parse_frame()，以将尝试从self.buffer中解析出一个完整的redis帧，如果有足够的数据来解析出一个完整帧，则将该帧返回给read_frame()的调用者；反之，则尝试将从socket读更多的数据取到缓冲区中。读取更多数据后将再次调用parse_frame()，此时，如果收到足够的数据，解析可能会成功。

从流中读取数据时，返回值为0表示将不能从对端收到更多数据，此时，如果读缓冲区仍有数据，则表明收到了部分帧，但该连接突然终止。这是一个错误，应返回Err。

`Buf` trait

从流中读取数据时调用了read_buf。此读函数接受的参数，需要实现bytes crate的BufMut trait。

这里先思考如果使用read()实现相同的读循环，该怎么写。（可以先用Vec<u8>代替上面的BytesMut）。

use tokio::net::TcpStream;

pub struct Connection {
    stream: TcpStream,
    buffer: Vec<u8>,
    cursor: usize,
}

impl Connection {
    pub fn new(stream: TcpStream) -> Connection {
        Connection {
            stream,
            // Allocate the buffer with 4kb of capacity.
            buffer: vec![0; 4096],
            cursor: 0,
        }
    }
}

再给Conneciont添加read_frame()函数：

use mini_redis::{Frame, Result};

pub async fn read_frame(&mut self)
    -> Result<Option<Frame>>
{
    loop {
        if let Some(frame) = self.parse_frame()? {
            return Ok(Some(frame));
        }

        // Ensure the buffer has capacity
        if self.buffer.len() == self.cursor {
            // Grow the buffer
            self.buffer.resize(self.cursor * 2, 0);
        }

        // Read into the buffer, tracking the number
        // of bytes read
        let n = self.stream.read(
            &mut self.buffer[self.cursor..]).await?;

        if 0 == n {
            if self.cursor == 0 {
                return Ok(None);
            } else {
                return Err("connection reset by peer".into());
            }
        } else {
            // Update our cursor
            self.cursor += n;
        }
    }
}

使用字节数组read时，需要手动维护一个游标用来跟踪缓冲了多少数据，还必须确保将缓冲区仍为空的部分传给read()；否则，将覆盖掉缓冲的数据。而当缓冲区用完时，还要手动扩大缓冲区以能够继续读到缓冲区。在parse_frame()（尚未提到）中，还需要指定解析位于self.buffer[..self.cursor]中的数据。

因为于将字节数组与游标搭配使用的场景很常见，bytes crate提供了表示字节数组和游标的抽象。Buf trait由那些可以从中读取数据的源头类型来实现。BufMut由那些可以进将数据写入的目的类型来实现。当把T: BufMut的参数传给read_buf()时，缓冲区内部的游标将被read_buf()自动更新。因此，在我们的read_frame，不再需要自己手动管理游标。

另外，使用vec<u8>时，必须初始化缓冲区。vec![0; 4096]将分配4096字节的数组，并将每个字节都置为零。调整缓冲区大小时，新增部分还必须使用零来初始化。而初始化操作是有代价的。使用BytesMut和BufMut时，缓冲区是未初始化的。BytesMut抽象会防止我们从未初始化的内存中读取数据，这就避免了初始化操作。

解析帧

现在，让我们看一下parse_frame()，解析分两个步骤进行。

确保全帧被缓冲，并索引到到帧的末尾。
解析帧。

mini-redis crate为我们提供了这两个步骤所需的函数：

这里又需要使用到Buf抽象。一个实现了Buf的对象会被传递给Frame::check，而在check函数检查传入的缓冲对象时，内部的游标会随着移动。当check返回时，缓冲区内部的游标就自动指向帧的末端了。

我们将使用std::io::Cursor<&[u8]>类型实现Buf。

use mini_redis::{Frame, Result};
use mini_redis::frame::Error::Incomplete;
use bytes::Buf;
use std::io::Cursor;

fn parse_frame(&mut self)
    -> Result<Option<Frame>>
{
    // Create the `T: Buf` type.
    let mut buf = Cursor::new(&self.buffer[..]);

    // Check whether a full frame is available
    match Frame::check(&mut buf) {
        Ok(_) => {
            // Get the byte length of the frame
            let len = buf.position() as usize;

            // Reset the internal cursor for the
            // call to `parse`.
            buf.set_position(0);

            // Parse the frame
            let frame = Frame::parse(&mut buf)?;

            // Discard the frame from the buffer
            self.buffer.advance(len);

            // Return the frame to the caller.
            Ok(Some(frame))
        }
        // Not enough data has been buffered
        Err(Incomplete) => Ok(None),
        // An error was encountered
        Err(e) => Err(e.into()),
    }
}

完整的Frame::check函数可以在这里找到，此处就不贴上它的完整代码了。

值得注意的是Buf使用了“字节迭代器”风格的API，以读取数据并移动内部游标。例如，解析帧时，检查第一个字节以确定帧的类型，使用的函数是Buf::get_u8，可以获取游标当前位置的字节，并将游标后移一位。

Buf trait还有更多有用的方，可以查看API文档获取更多信息。

缓冲写

帧相关API的另一半是write_frame(frame)函数，它会将一个完整的帧写入socket。为了最大程度地减少write系统调用，写将被缓冲。我们维护一个写缓冲区，并在写入socket之前将帧编码到该缓冲区。不过，与read_frame()不同，完整的帧并不总是在写入socket前缓冲到字节数组。

比如对一个大块流帧，要写入的值为Frame::Bulk(Bytes)。大块帧的的物理格式是一个帧头，即$符后接以字节计算的数据长度。帧的主体是内容的Bytes。如果数据量很大，则将其复制到中间缓冲区将非常耗资源。

为了实现缓冲写，我们将使用BufWriter结构体，它用T: AsyncWrite初始化并自己实现AsyncWrite。当在BufWriter上调用write时，并非直接调用内部的写操作，而是提交给缓冲区。当缓冲区满时，内容才一次性交给内部写操作，然后清理缓冲区。当然，在某些情况下，还有一些可以绕过缓冲区的优化操作。

这里的教程不会贴上完整的write_frame()实现了，你可以在这里找到完整代码。

首先，修改Connection结构体：

use tokio::io::BufWriter;
use tokio::net::TcpStream;
use bytes::BytesMut;

pub struct Connection {
    stream: BufWriter<TcpStream>,
    buffer: BytesMut,
}

impl Connection {
    pub fn new(stream: TcpStream) -> Connection {
        Connection {
            stream: BufWriter::new(stream),
            buffer: BytesMut::with_capacity(4096),
        }
    }
}

然后实现write_frame()：

use tokio::io::{self, AsyncWriteExt};
use mini_redis::Frame;

async fn write_frame(&mut self, frame: &Frame)
    -> io::Result<()>
{
    match frame {
        Frame::Simple(val) => {
            self.stream.write_u8(b'+').await?;
            self.stream.write_all(val.as_bytes()).await?;
            self.stream.write_all(b"\r\n").await?;
        }
        Frame::Error(val) => {
            self.stream.write_u8(b'-').await?;
            self.stream.write_all(val.as_bytes()).await?;
            self.stream.write_all(b"\r\n").await?;
        }
        Frame::Integer(val) => {
            self.stream.write_u8(b':').await?;
            self.write_decimal(*val).await?;
        }
        Frame::Null => {
            self.stream.write_all(b"$-1\r\n").await?;
        }
        Frame::Bulk(val) => {
            let len = val.len();

            self.stream.write_u8(b'$').await?;
            self.write_decimal(len as u64).await?;
            self.stream.write_all(val).await?;
            self.stream.write_all(b"\r\n").await?;
        }
        Frame::Array(_val) => unimplemented!(),
    }

    self.stream.flush().await;

    Ok(())
}

这里使用的诸多函数均由AsyncWriteExt trait提供，该trait也被TcpStream实现，但是不建议在没有中间缓冲区的情况下发送写单个字节的命令（译注：即直接在TcpStream上调用这些write_*函数会产生大量系统调用，建议的做法是在有缓冲包装的写对象上调用，如文中的stream是一个BufWriter<TcpStream>对象）。

write_u8将单个字节送入写端。
write_all将整个切片送入写端。
write_decimal由mini-redis实现。

该函数结束时将调用self.stream.flush().await。由于BufWriter在中间缓冲区保存写内容，因此调用write不能保证数据立即写入socket。在返回之前，我们希望将帧写入socket，手动调用flush()以将缓冲区中等待的所有数据写入socket。

另一种实现是在Connection上提供一个flush()方法，来代替在write_frame()中调用flush()。这将允许调用者将多个小帧排队写入写缓冲区，然后只用一个write系统调用将它们全部写入socket。不过这样会使Connection的API复杂化。简单也是Mini-Redis的目标，因此我们决定在fn write_frame()中调用flush().await。

9 深入异步

至此，我们已经较为全面的了解了关于异步Rust和Tokio的知识。现在，让我们更深入了研究Rust的异步运行时模型。在本教程的最开始，我们暗示异步Rust采用了一种独特的实现方法。本章，我们就解释一下这意味着什么。

Futures

我们用一个非常基本的异步函数，来快速回顾一下了解到的异步相关知识，在这个例子中并没有超出前几章的知识点。

use tokio::net::TcpStream;

async fn my_async_fn() {
    println!("hello from async");
    let _socket = TcpStream::connect("127.0.0.1:3000").await.unwrap();
    println!("async TCP operation complete");
}

我们调用该函数，它返回一些值。我们又在该值上调用.await。

#[tokio::main]
async fn main() {
    let what_is_this = my_async_fn();
    // Nothing has been printed yet.
    what_is_this.await;
    // Text has been printed and socket has been
    // established and closed.
}

my_async_fn()的返回值是一个future。实现了标准库std::future::Future trait的值就是future。这些值里包含了正在执行的异步计算。

std::future::Future trait的定义为：

use std::pin::Pin;
use std::task::{Context, Poll};

pub trait Future {
    type Output;

    fn poll(self: Pin<&mut Self>, cx: &mut Context)
        -> Poll<Self::Output>;
}

关联类型Output是future执行完毕后返回的类型。Pin类型使Rust能够支持异步函数内的借用。有关更多详细信息，请参阅标准库文档。

与用其他语言实现future的方式不同，Rust的future并不是正在后台执行的计算过程，而是计算本身。future的所有者负责通过轮询未来来推进计算。这是通过调用Future::poll来实现的。

（译注，本教程因主要关注tokio的应用，所以本章关于深入Rust异步机制的介绍篇幅并不大，更深入的讨论可以参考使用Rust编写操作系统 - 4.1 - Async/Await）

实现`Future`

让我们实现一个非常简单的future。这个future将：

等待，直到某个特定的时刻才执行。
将一些文本输出到标准输出。
生成一个字符串。

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};

struct Delay {
    when: Instant,
}

impl Future for Delay {
    type Output = &'static str;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>)
        -> Poll<&'static str>
    {
        if Instant::now() >= self.when {
            println!("Hello world");
            Poll::Ready("done")
        } else {
            // Ignore this line for now.
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

#[tokio::main]
async fn main() {
    let when = Instant::now() + Duration::from_millis(10);
    let future = Delay { when };

    let out = future.await;
    assert_eq!(out, "done");
}

将异步函数当做Future

在main函数中，我们实例化future并在其上调用.await。从异步函数中，我们可以在任何实现了Future的值上调用.await。反过来，调用async函数会返回一个实现了Future的匿名类型。在async fn main()的情况下，生成的future大致为：

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};

enum MainFuture {
    // Initialized, never polled
    State0,
    // Waiting on `Delay`, i.e. the `future.await` line.
    State1(Delay),
    // The future has completed.
    Terminated,
}

impl Future for MainFuture {
    type Output = ();

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>)
        -> Poll<()>
    {
        use MainFuture::*;

        loop {
            match *self {
                State0 => {
                    let when = Instant::now() +
                        Duration::from_millis(10);
                    let future = Delay { when };
                    *self = State1(future);
                }
                State1(ref mut my_future) => {
                    match Pin::new(my_future).poll(cx) {
                        Poll::Ready(out) => {
                            assert_eq!(out, "done");
                            *self = Terminated;
                            return Poll::Ready(());
                        }
                        Poll::Pending => {
                            return Poll::Pending;
                        }
                    }
                }
                Terminated => {
                    panic!("future polled after completion")
                }
            }
        }
    }
}

Rust future实际上是状态机。这里用一个包含了三种future可能状态的enum来表示MainFuture。future状态机始于State0状态。当调用poll时，future会尽可能地推进其内部状态。如果future能够完成，则返回包含了异步计算输出的Poll::Ready。

如果future无法完成，通常是由于它正在等待的资源尚未准备好，则返回Poll::Pending。若调用者收到Poll::Pending，则表明future将在稍后完成，调用者应该稍后再次调用poll。

我们还看到future也包含了其他future。调用外部future的poll会导致调用内部future的poll函数。

执行器

异步Rust函数返回future，而future必须依靠不断的poll调用来推进器状态。Future包含了其他future，那么问题来了，是谁在最外层的future调用poll呢？

回想一下，要运行异步函数，要么必须传递给tokio::spawn，要么使用带有#[tokio::main]标识的main函数。这实际上这是将生成的外层future提交给了Tokio执行器。执行器负责在外部future上调用Future::poll，以驱动异步计算完成执行。

迷你Tokio

为了更好地理解这一切是如何组合在一起的，让我们实现我们自己的最小版本的Tokio！你可以在这里找到完整的代码。

use std::collections::VecDeque;
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};
use futures::task;

fn main() {
    let mut mini_tokio = MiniTokio::new();

    mini_tokio.spawn(async {
        let when = Instant::now() + Duration::from_millis(10);
        let future = Delay { when };

        let out = future.await;
        assert_eq!(out, "done");
    });

    mini_tokio.run();
}

struct MiniTokio {
    tasks: VecDeque<Task>,
}

type Task = Pin<Box<dyn Future<Output = ()> + Send>>;

impl MiniTokio {
    fn new() -> MiniTokio {
        MiniTokio {
            tasks: VecDeque::new(),
        }
    }
    
    /// Spawn a future onto the mini-tokio instance.
    fn spawn<F>(&mut self, future: F)
    where
        F: Future<Output = ()> + Send + 'static,
    {
        self.tasks.push_back(Box::pin(future));
    }
    
    fn run(&mut self) {
        let waker = task::noop_waker();
        let mut cx = Context::from_waker(&waker);
        
        while let Some(mut task) = self.tasks.pop_front() {
            if task.as_mut().poll(&mut cx).is_pending() {
                self.tasks.push_back(task);
            }
        }
    }
}

这里执行了一个异步代码块。使用给定的延迟创建了一个Delay实例，并处于等待状态。但是现在的实现存在一个问题，即执行器不会休眠。这个执行器会在生成的所有future上不断调用轮询。大多数时间里，future都不会就绪，只会继续返回Poll::Pending。这一过程将吃满CPU周期，所以通常效率不高。

理想情况下，我们希望mini-tokio只在future就绪时才去调用轮询。这种情况发生在任务所需的被阻塞资源转为可用，从而能够执任务所求情的操作时，例如，若任务想从TCP socket读取数据，则我们只希望在TCP socket收到数据时才进行轮询。在mini-tokio中，任务在给定的Instant时间内被阻塞，所以理想情况下，mini-tokio应只在任务给定的Instance时间过去后，再执行一次轮询。

为了实现这一目标，当轮询了某资源，且尚未就绪时，该资源应在过度到就绪状态后立即发送通知。

唤醒器

现在我们还缺少唤醒器，即用于在资源就绪时，通知等待的任务资源已就绪，可以继续后面的操作。

再次观察Future:poll的函数签名：

fn poll(self: Pin<&mut Self>, cx: &mut Context)
    -> Poll<Self::Output>;

poll的Context参数有一个waker()方法，它返回一个绑定当前任务的Waker。Waker有一个wake()方法，调用此方法将通知执行器以安排执行相关任务。当资源过度到就绪状态时就会调用wake()，通知执行器轮询该任务以推进作业的执行。

修改`Delay`

给Delay代码加上唤醒器：

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::{Duration, Instant};
use std::thread;

struct Delay {
    when: Instant,
}

impl Future for Delay {
    type Output = &'static str;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>)
        -> Poll<&'static str>
    {
        if Instant::now() >= self.when {
            println!("Hello world");
            Poll::Ready("done")
        } else {
            // Get a handle to the waker for the current task
            let waker = cx.waker().clone();
            let when = self.when;

            // Spawn a timer thread.
            thread::spawn(move || {
                let now = Instant::now();

                if now < when {
                    thread::sleep(when - now);
                }

                waker.wake();
            });

            Poll::Pending
        }
    }
}

现在，一旦等待到了指定的延时，就会通知调用的任务，执行器就可以再次安排轮询任务了。接下来我们修改mini-tokio的代码，从而能够接受唤醒通知。

这里的Delay实现仍存在一些问题，我们会稍后修复。

:::caution 当future返回Poll:Pending时，必须确保在某个时刻通知唤醒器，若忘记执行此操作，会导致任务永久挂起。

在任务返回Poll:Pending后忘记唤醒是一个常见的bug。 :::

回忆我们的第一版Delay，是这样实现future的：

impl Future for Delay {
    type Output = &'static str;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>)
        -> Poll<&'static str>
    {
        if Instant::now() >= self.when {
            println!("Hello world");
            Poll::Ready("done")
        } else {
            // Ignore this line for now.
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

在返回Poll:Pending之前，我们调用了cx.waker().wake_by_ref()。这是为了符合future协议。由于返回了Poll::Pending，我们得负责通知唤醒器。由于此时我们还没实现计时器线程，所以我们在内部通知了唤醒器。这将导致该future被立刻安排轮询，从而再次执行，并且此刻的future依然没有就绪。

这里可以注意到，你确实可以比非必要不通知的理想状态，更频繁的通知唤醒器。比如上面的代码中，我们确实在未就绪的情况下通知了唤醒器。这也没什么大问题，只是浪费了点CPU周期，不过这种实现确实使得循环更加繁忙。

修改Mini Tokio

接下来是修改Mini Tokio的代码，以接收唤醒器通知。我们希望执行器仅在任务唤醒时运行它们，为此，需要给Mini Tokio实现唤醒器。调用唤醒器时，其关联的任务将被排入执行队列。Mini-Tokio在轮询future时会将该唤醒器传给该future。

新的Mini Tokio将使用通道存储排入计划的任务。通道能够让排入队列的任务在任意线程上执行。唤醒器必须是Send且Sync的，所以我们使用crossbeam提供的通道，因为标准库的通道不是Sync的。

:::note Send和Sync是Rust提供的并发相关的标记trait。能够被发送到其他线程的类型就是Send的，除了Rc之类的类型不是外，大多数类型都是Send的。能够通过不可变引用并发访问的类型就是Sync的。可以Send却不能Sync的类型，比如Cell，就可以通过不可变引用修改，却不能被安全的并发访问。

有关更多详情请参阅 Rust Book的相关章节。 :::

将以下依赖项添加到您的Cargo.toml，引入通道。

crossbeam = "0.8"

再更新MiniTikio结构体：

use crossbeam::channel;
use std::sync::Arc;

struct MiniTokio {
    scheduled: channel::Receiver<Arc<Task>>,
    sender: channel::Sender<Arc<Task>>,
}

struct Task {
    // 将在下文中实现此结构体。
}

Wakers既Sync又可被克隆。调用wake时，任务必须被安排执行。为了实现这一点，我们建立一个通道。当唤醒器调用wake()时，任务被推送到通道的发送端，我们的Task结构体将实现这个唤醒逻辑。为此，它需要同时包含生成的future和通道的发送端。

use std::sync::{Arc, Mutex};

struct Task {
    // `Mutux`用以让`Task`实现`Sync`。同时只允许一个线程访问`future`。
    // `Mutex`在此处并不是为了保证正确性。实际上Tokio在这里也并没使用什么互斥锁，
    // 而是使用了大量其他代码实现这一功能。
    future: Mutex<Pin<Box<dyn Future<Output = ()> + Send>>>,
    executor: channel::Sender<Arc<Task>>,
}

impl Task {
    fn schedule(self: &Arc<Self>) {
        self.executor.send(self.clone());
    }
}

为了安排任务，将Arc克隆并使用通道发送。现在，我们需要将schedule函数与std::task::Waker挂钩。标准库提供了一个低级API，让我们能够手动构造vtable以执行此操作。这种策略为实现者提供了最大的灵活性，但需要大量非安全的样板代码。这里，我们将使用futures crate提供的ArcWake实用程序，以替代直接用 RawWakerVTable。这允许我们通过实现一个简单的trait来将Task结构体呈现为一个唤醒器。

将以下依赖项添加到Cargo.toml中以引入futures。

futures = "0.3"

然后，实现futures::task::ArcWake。

use futures::task::{self, ArcWake};
use std::sync::Arc;
impl ArcWake for Task {
    fn wake_by_ref(arc_self: &Arc<Self>) {
        arc_self.schedule();
    }
}

当上面的定时器线程调用waker.wake()时，任务被推送到通道。接下来，我们在MiniTokio::run()函数中实现任务的接收和执行。

impl MiniTokio {
    fn run(&self) {
        while let Ok(task) = self.scheduled.recv() {
            task.poll();
        }
    }

    /// 初始化一个新的mini-tokio实例。
    fn new() -> MiniTokio {
        let (sender, scheduled) = channel::unbounded();

        MiniTokio { scheduled, sender }
    }

    /// 在mini-tokio中生成一个future
    /// 
    /// 给定的future将包装在`Task`中并被送入`scheduled`队列。调用`run`时将执行此future。
    fn spawn<F>(&self, future: F)
    where
        F: Future<Output = ()> + Send + 'static,
    {
        Task::spawn(future, &self.sender);
    }
}

impl Task {
    fn poll(self: Arc<Self>) {
        // 使用`Task`的实例创建一个唤醒器。这用到了上面的`ArcWake`实现。
        let waker = task::waker(self.clone());
        let mut cx = Context::from_waker(&waker);

        // 没有其他线程尝试获取future的锁。
        let mut future = self.future.try_lock().unwrap();

        // 轮询future
        let _ = future.as_mut().poll(&mut cx);
    }

    // 使用给定future生成一个新的task。
    // 
    // 初始化一个包裹着给定future的新Task，并将其推送至`sender`。通道的接收端将获取这个task并执行。
    fn spawn<F>(future: F, sender: &channel::Sender<Arc<Task>>)
    where
        F: Future<Output = ()> + Send + 'static,
    {
        let task = Arc::new(Task {
            future: Mutex::new(Box::pin(future)),
            executor: sender.clone(),
        });

        let _ = sender.send(task);
    }

}

以上代码做了很多事，首先，首先，实现MiniTokio::run()，该函数执行一个从通道接收计划任务的循环。由于任务在被唤醒后推送到通道，因此这些任务在执行时能够取得进展。

此外，MiniTokio::new()和MiniTokio::spawn()函数现在改为使用通道，而不是之前的VecDeque。当生成新任务时，它们会得到一份通道发送端的克隆，从而让任务在在运行时自行使用。

Task::poll()函数使用futures crate中的ArcWake实用程序创建唤醒器。唤醒器用于创建task::Context，task::Context将传递给poll。

小结

我们现在已经看到了异步Rust如何工作的端到端示例。Rust的async/await特性通过多个trait共同实现。这允许第三方crate使用自定义的执行细节，如Tokio。

异步Rust操作是惰性的，需要被调用者轮询。
唤醒器被传递给future，使得future能够找到到调用它的任务。
当资源尚未就绪时，返回Poll::Pending并记录任务的唤醒器。
当资源准备就绪时，通知任务的唤醒器。
执行器收到通知并安排任务执行。
再次轮询任务，这次资源就绪，任务取得进展。

一些未解决的问题

回忆实现Delay future时，我们提到还有一些事情需要解决。Rust的异步模型允许单个future跨任务执行。考虑以下情形：

use futures::future::poll_fn;
use std::future::Future;
use std::pin::Pin;

#[tokio::main]
async fn main() {
    let when = Instant::now() + Duration::from_millis(10);
    let mut delay = Some(Delay { when });

    poll_fn(move |cx| {
        let mut delay = delay.take().unwrap();
        let res = Pin::new(&mut delay).poll(cx);
        assert!(res.is_pending());
        tokio::spawn(async move {
            delay.await;
        });

        Poll::Ready(())
    }).await;
}

poll_fn函数使用闭包创建一个Future实例。上面的代码片段创建了一个Delay实例，轮询它一次，然后将Delay实例发送到新任务并执行.await。在这个例子中，Delay::poll被不同的Waker实例调用了不止一次。发生这种情况时，您必须确保在最近一次调用poll的Waker上调用wake。

在实现future时，应当假设每次调用poll都可能返回不同的Waker实例，轮询函数必须使用新的唤醒器代替旧的唤醒器。

我们早期的Delay实现在每次轮询时都会生成一个新线程。这没什么问题，但如果轮询过于频繁，效率可能会非常低（例如，如果您select!该future和其他future，只要其中之一有事件发生，则两者都会被轮询）。一种方法是记住你是否已经生成了一个线程，并只有在未生成线程时才执行生成。但是如果这样做，则必须确保在之后调用轮询时更新线程的唤醒器，否则你执行唤醒时将可能使用旧的唤醒器。

为了修复之前的实现，我们可以这样做：

use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll, Waker};
use std::thread;
use std::time::{Duration, Instant};

struct Delay {
    when: Instant,
    // 当我们生一个新线程时为`Some`，否则为`None`。
    waker: Option<Arc<Mutex<Waker>>>,
}

impl Future for Delay {
    type Output = ();

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        // 首先，如果这是第一次调用future，则生成一个计时器线程。
        // 如果计时器线程已经存在，则应确保我们保存的`Waker`就是当前任务的唤醒器。
        if let Some(waker) = &self.waker {
            let mut waker = waker.lock().unwrap();

            // 检测保存的唤醒器是否匹配当前线程的唤醒器。
            // 这一步是必要的，因为`Delay` future的实例可能在两次轮询间隔内移动到另一个任务中。
            // 如果发生移动，则给定的`Context`中包含的唤醒器将会不同，
            // 我们必须更新之前存储的唤醒器，以对此变化做出反应。
            if !waker.will_wake(cx.waker()) {
                *waker = cx.waker().clone();
            }
        } else {
            let when = self.when;
            let waker = Arc::new(Mutex::new(cx.waker().clone()));
            self.waker = Some(waker.clone());

            // 此处为第一次调用`poll`，生成计时器线程
            thread::spawn(move || {
                let now = Instant::now();

                if now < when {
                    thread::sleep(when - now);
                }

                // 当持续时间过去之后，调用唤醒器以通知调用者。
                let waker = waker.lock().unwrap();
                waker.wake_by_ref();
            });
        }

        // 在保存了唤醒器并启动了计时器线程后，就该检查给定的延时是否到达。
        // 这可以通过检测当前时刻来实现，如果持续时间已经过去，则future完成并返回`Poll::Ready``。
        if Instant::now() >= self.when {
            Poll::Ready(())
        } else {
            // 如果持续时间没到，则future未完成，应返回`Poll:Pending`。
            // `Future` trait协议规定，返回`Pending`时，future应通知一次给定唤醒器，
            // future应被再次轮询。在我们的例子中，此处返回`Pending`，
            // 我们承诺一旦持续时间过去，就将调用参数`Context`中给定的唤醒器。
            // 我们能够做出承诺，是依靠上面生成的计时器线程。
            //
            // 如果我们忘记调用唤醒器，任务将永久挂起
            Poll::Pending
        }
    }
}

这有点复杂，不过基本思路是，在每次调用poll时，future检查提供的唤醒器是否与先前保存的唤醒器一致，若不一致，则必须保存新的唤醒器。

`Notify`实用程序

我们演示了如何使用唤醒器手动实现Delay future。唤醒器是是异步Rust工作的基础。通常，没有必要深入到那个程度。例如，在Delay中，我们完全可以通过使用async/await配合tokio::sync::Notify实用程序来实现。该实用程序提供了一个基础的任务通知机制。它负责处理唤醒器的相关细节，包括确保保存的唤醒器与当前任务的唤醒器一致。

使用Notify，我们可以像这样使用async/await实现delay函数：

use tokio::sync::Notify;
use std::sync::Arc;
use std::time::{Duration, Instant};
use std::thread;

async fn delay(dur: Duration) {
    let when = Instant::now() + dur;
    let notify = Arc::new(Notify::new());
    let notify2 = notify.clone();

    thread::spawn(move || {
        let now = Instant::now();

        if now < when {
            thread::sleep(when - now);
        }

        notify2.notify_one();
    });


    notify.notified().await;
}

10 Select

现在，当想要向系统添加并发时，我们就生成一个新任务。下面，我们将介绍一些使用Tokio并发执行异步代码的其他方法。

`tokio::select!`

tokio::select!宏允许等待多个异步计算，并在某个计算完成时返回。

例如：

use tokio::sync::oneshot;

#[tokio::main]
async fn main() {
    let (tx1, rx1) = oneshot::channel();
    let (tx2, rx2) = oneshot::channel();

    tokio::spawn(async {
        let _ = tx1.send("one");
    });

    tokio::spawn(async {
        let _ = tx2.send("two");
    });

    tokio::select! {
        val = rx1 => {
            println!("rx1 completed first with {:?}", val);
        }
        val = rx2 => {
            println!("rx2 completed first with {:?}", val);
        }
    }
}

对于两个oneshot通道，任一通道都可能先完成。select!语句在两个通道上等待并将val绑定到任务返回的值。当tx1或tx2完成时，执行相关的代码块。

未完成的分支将被丢弃。在示例中，程序等待每个通道的oneshot::Receiver。未完成通道的oneshot::Receiver会被丢弃。

取消

异步Rust的取消操作，是通过放弃future来执行的。回顾“深入异步”章节，异步Rust使用future实现，而future是惰性的，操作只有被轮询时才会进行。如果如果future被丢弃，由于所有相关状态都已删除，因此无法进行操作。

也就是说，有时异步操作会生成后台任务，或启动在后台运行的其他操作。例如，在上面的示例中，生成了一个任务以发送消息。通常，任务将执行一些计算以生成值。

Future或其他类型可以实现Drop以清理后台资源。Tokio的oneshot::Receiver通过向Sender端发送一条关闭消息来实现Drop。发送端可以收到此消息并取消进行中的操作。

use tokio::sync::oneshot;

async fn some_operation() -> String {
    // Compute value here
}

#[tokio::main]
async fn main() {
    let (mut tx1, rx1) = oneshot::channel();
    let (tx2, rx2) = oneshot::channel();

    tokio::spawn(async {
        // Select on the operation and the oneshot's
        // `closed()` notification.
        tokio::select! {
            val = some_operation() => {
                let _ = tx1.send(val);
            }
            _ = tx1.closed() => {
                // `some_operation()` is canceled, the
                // task completes and `tx1` is dropped.
            }
        }
    });

    tokio::spawn(async {
        let _ = tx2.send("two");
    });

    tokio::select! {
        val = rx1 => {
            println!("rx1 completed first with {:?}", val);
        }
        val = rx2 => {
            println!("rx2 completed first with {:?}", val);
        }
    }
}

`future`的实现

为了更好的理解select!是如何工作的，让我们看看一个假想的Future实现会是什么样子。这是一个简化版本，现实中的select!还包含其他功能，例如随机选择首先轮询的分支。

use tokio::sync::oneshot;
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

struct MySelect {
    rx1: oneshot::Receiver<&'static str>,
    rx2: oneshot::Receiver<&'static str>,
}

impl Future for MySelect {
    type Output = ();

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        if let Poll::Ready(val) = Pin::new(&mut self.rx1).poll(cx) {
            println!("rx1 completed first with {:?}", val);
            return Poll::Ready(());
        }

        if let Poll::Ready(val) = Pin::new(&mut self.rx2).poll(cx) {
            println!("rx2 completed first with {:?}", val);
            return Poll::Ready(());
        }

        Poll::Pending
    }
}

#[tokio::main]
async fn main() {
    let (tx1, rx1) = oneshot::channel();
    let (tx2, rx2) = oneshot::channel();

    // use tx1 and tx2

    MySelect {
        rx1,
        rx2,
    }.await;
}

MySelect future包含两个分支的future。轮询MySelect时，将轮询第一个分支。若就绪，则使用该值，MySelect完成。在.await收到future的输出后，future将被丢弃，这导致两个分支的futures均被删除。由于一个分支没有完成，操作实际上被取消了。

回忆上一节的内容：

:::caution 当future返回Poll:Pending时，必须确保在某个时刻通知唤醒器，若忘记执行此操作，会导致任务永久挂起。

在任务返回Poll:Pending后忘记唤醒是一个常见的bug。 :::

MySelect实现中并没用显式使用Context参数，而是通过将cx传给内部的future来满足唤醒器的要求。通过仅在从内部future收到Poll::Pending时才返回Poll::Pending，来使内部future也满足唤醒器的要求，MySelect也满足唤醒器的要求。

语法

select!宏可以处理多个分支，目前的限制为64个分支。每个分支的结构如下：

<pattern> = <async expression> => <handler>,

当select宏求值时，所有<async expression>都会聚合并同时执行。当表达式完成时，结果与<pattern>匹配，若结果匹配，则取消所有剩余的异步表达式并执行<handler>。<handler>表达式可以访问<pattern>绑定的变量。

<pattern>的基本用法是给一个变量名赋值，即异步表达式的结果绑定到该变量名，使<handler>可以访问该变量。这就是为什么在上面的示例中，val用于<pattern>，<handler>能够访问val。

如果<pattern>与异步计算的结果不匹配，则剩余的异步表达式将继续并发执行，直到下一个完成。这时，上面的逻辑继续应用作用于该结果。

select!中可以使用任意异步表达式，因此可以定义更复杂的选择计算。

下面的例子中，我们在oneshot通道的输出和TCP连接上进行选择操作。

use tokio::net::TcpStream;
use tokio::sync::oneshot;

#[tokio::main]
async fn main() {
    let (tx, rx) = oneshot::channel();

    // 生成一个使用oneshot发送信息的任务
    tokio::spawn(async move {
        tx.send("done").unwrap();
    });

    tokio::select! {
        socket = TcpStream::connect("localhost:3465") => {
            println!("Socket connected {:?}", socket);
        }
        msg = rx => {
            println!("received message first {:?}", msg);
        }
    }
}

下面的例子中，我们在oneshot通道和TcpListenersocket间进行选择操作。

use tokio::net::TcpListener;
use tokio::sync::oneshot;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    let (tx, rx) = oneshot::channel();

    tokio::spawn(async move {
        tx.send(()).unwrap();
    });

    let mut listener = TcpListener::bind("localhost:3465").await?;

    tokio::select! {
        _ = async {
            loop {
                let (socket, _) = listener.accept().await?;
                tokio::spawn(async move { process(socket) });
            }

            // Help the rust type inferencer out
            Ok::<_, io::Error>(())
        } => {}
        _ = rx => {
            println!("terminating accept loop");
        }
    }

    Ok(())
}

循环将一直运行，直到遇到错误，或rx收到值。_模式表示我们对异步计算的返回值不感兴趣。

返回值

tokio::select!宏返回<handler>表达式求值的结果。

async fn computation1() -> String {
    // .. computation
}

async fn computation2() -> String {
    // .. computation
}

#[tokio::main]
async fn main() {
    let out = tokio::select! {
        res1 = computation1() => res1,
        res2 = computation2() => res2,
    };

    println!("Got = {}", out);
}

因此，每个分支的<handler>表达式的求值结果应为相同的类型。如果某个select!表达式不需要输出，最好将表达式的求值结果写为()。

错误

使用?运算符从表达式中传播错误，具体的行为取决于?是用在异步表达式（<async expression>）中，还是用在处理程序（<handelr>）中。在异步表达式中使用?会将错误传播到异步表达式之外，这使得异步表达式的输出为Result类型；在处理程序中使用?会立刻将错误传播到select!表达式之外。让我们再看一遍上面接受socket循环的例子：

use tokio::net::TcpListener;
use tokio::sync::oneshot;
use std::io;

#[tokio::main]
async fn main() -> io::Result<()> {
    // [setup `rx` oneshot channel]

    let listener = TcpListener::bind("localhost:3465").await?;

    tokio::select! {
        res = async {
            loop {
                let (socket, _) = listener.accept().await?;
                tokio::spawn(async move { process(socket) });
            }

            // Help the rust type inferencer out
            Ok::<_, io::Error>(())
        } => {
            res?;
        }
        _ = rx => {
            println!("terminating accept loop");
        }
    }

    Ok(())
}

注意listener.accept().await?，?运算符将错误从该表达式传播到res绑定变量。出现错误时，res将被设置为Err(_)。处理程序中再次使用了?运算符，res?语句将错误传播到main函数之外。

模式匹配

回忆select!宏的分支定义语法：

<pattern> = <async expression> => <handler>,

到目前为止，我们只在<pattern>处用了变量绑定。实际上，我们可以使用任何Rust模式匹配。例如，假设我们从多个MPSC通道接收数据，就可以这样写：

use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    let (mut tx1, mut rx1) = mpsc::channel(128);
    let (mut tx2, mut rx2) = mpsc::channel(128);

    tokio::spawn(async move {
        // Do something w/ `tx1` and `tx2`
    });

    tokio::select! {
        Some(v) = rx1.recv() => {
            println!("Got {:?} from rx1", v);
        }
        Some(v) = rx2.recv() => {
            println!("Got {:?} from rx2", v);
        }
        else => {
            println!("Both channels closed");
        }
    }
}

在这个例子中，select!表达式等待从rx1和rx2接收值。如果一个通道关闭，recv()返回None，则无法满足匹配，此分支将失效。于是select!表达式继续等待剩余的分支。

注意这个select!表达式包含一个else分支，即select!表达式必须返回一个值。使用模式匹配时，可能没有分支能够匹配其的关联模式，如果发生这种情况，则由else分支求值。

借用

当生成任务时，产生异步表达式必持有其所需数据的所有权，而select!宏并没有这种限制，每个分支的异步表达式可以借用数据且同时运行。遵循Rust的借用规则，多个异步表达式可以同时对某块数据进行不可变借用，或者，仅一个异步表达式可以对某块数据进行可变借用。

下面的例子中，我们同时将相同的数据发送到两个不同的TCP目的地址。

use tokio::io::AsyncWriteExt;
use tokio::net::TcpStream;
use std::io;
use std::net::SocketAddr;

async fn race(
    data: &[u8],
    addr1: SocketAddr,
    addr2: SocketAddr
) -> io::Result<()> {
    tokio::select! {
        Ok(_) = async {
            let mut socket = TcpStream::connect(addr1).await?;
            socket.write_all(data).await?;
            Ok::<_, io::Error>(())
        } => {}
        Ok(_) = async {
            let mut socket = TcpStream::connect(addr2).await?;
            socket.write_all(data).await?;
            Ok::<_, io::Error>(())
        } => {}
        else => {}
    };

    Ok(())
}

两个异步表达式都使用了data变量这一不可变借用。当其中一个操作成功完成时，另一个操作将被丢弃。因为我们需要匹配Ok(_)，如果一个表达式失败，另一个则将继续执行。

当执行到每个分支的<handler>时，select!保证只会有一个<handler>执行。因此，每个<handler>可以对同一块数据进行可变借用。

下面的例子中，两个处理程序都尝试对out进行修改：

use tokio::sync::oneshot;

#[tokio::main]
async fn main() {
    let (tx1, rx1) = oneshot::channel();
    let (tx2, rx2) = oneshot::channel();

    let mut out = String::new();

    tokio::spawn(async move {
        // Send values on `tx1` and `tx2`.
    });

    tokio::select! {
        _ = rx1 => {
            out.push_str("rx1 completed");
        }
        _ = rx2 => {
            out.push_str("rx2 completed");
        }
    }

    println!("{}", out);
}

循环

select!宏经常用在循环中，本节将介绍一些例子，以展示在循环中使用select!宏的常见方法。第一个例子是在多个通道上进行选择：

use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    let (tx1, mut rx1) = mpsc::channel(128);
    let (tx2, mut rx2) = mpsc::channel(128);
    let (tx3, mut rx3) = mpsc::channel(128);

    loop {
        let msg = tokio::select! {
            Some(msg) = rx1.recv() => msg,
            Some(msg) = rx2.recv() => msg,
            Some(msg) = rx3.recv() => msg,
            else => { break }
        };

        println!("Got {:?}", msg);
    }

    println!("All channels have been closed.");
}

上面的例子在三个通道的接收端上选择，当任一通道的接收端收到信息，就输出到STDOUT。当一个通道关闭时，recv()返回None，由于模式匹配，select!宏将继续等待其余通道。当所有通道关闭时，else分支将求值从而终止循环。

select!宏以随机的方式决定首先检查哪个分支是否就绪，当多个通道的值均未就绪时，将随机选择一个通道接受信息。这是为了处理接收循环的处理速度，慢于消息推入通道的速度的情况，这意味着通道可能被填满。如果select!首选检查的分支不是随机的，而是每次循环都首选检查rx1，若rx1始终都有一条新消息，则其他通道将永远不会被检查。

如果选择时！进行评估，多个通道有未决消息，只有一个通道弹出一个值。所有其他频道都没有受到影响，他们的消息一直在这些频道中，直到下一次循环迭代为止。没有消息丢失。

:::caution 当select!求值，只有一个通道有就绪值，其余通道都在等待时，其余通道的代码不会被执行，其余通道的信息将停留在通道内知道下一次迭代。因此不会有信息丢失。 :::

恢复一个异步操作

下面的例子将展示如何在多个select!调用间执行同一个异步操作。在此示例中，我们有一个类型为i32的MPSC通道和一个异步函数。我们希望一直运行异步函数，直到任务完成，或在通道上接收到一个偶数。

async fn action() {
    // Some asynchronous logic
}

#[tokio::main]
async fn main() {
    let (mut tx, mut rx) = tokio::sync::mpsc::channel(128);
    
    let operation = action();
    tokio::pin!(operation);
    
    loop {
        tokio::select! {
            _ = &mut operation => break,
            Some(v) = rx.recv() => {
                if v % 2 == 0 {
                    break;
                }
            }
        }
    }
}

注意这里是如何再循环外，而不是在select!宏内调用action()的。aciont()的返回值被赋给operation，且不执行.await。然后我们在operation上调用tokio:pin!。

在select!循环内，我们传入&mut operation，而不是operation。operation变量正在跟踪执行中的异步操作，循环的每次迭代都使用同一个变量，而不是调用一个新的action()。

另一个select!分支从通道接收数据，如果是一个偶数，则终止循环，否则再次select!。

此处是我们第一次使用tokio::pin!，这里我们并不介绍关于内存固定的细节，只需要注意，如果要.await一个引用，被引用的值必须是被固定的，或是实现了Unpin的。

如果我们删除tokio::pin!一行并尝试编译，就会收到以下错误：

error[E0599]: no method named `poll` found for struct
     `std::pin::Pin<&mut &mut impl std::future::Future>`
     in the current scope
  --> src/main.rs:16:9
   |
16 | /         tokio::select! {
17 | |             _ = &mut operation => break,
18 | |             Some(v) = rx.recv() => {
19 | |                 if v % 2 == 0 {
...  |
22 | |             }
23 | |         }
   | |_________^ method not found in
   |             `std::pin::Pin<&mut &mut impl std::future::Future>`
   |
   = note: the method `poll` exists but the following trait bounds
            were not satisfied:
           `impl std::future::Future: std::marker::Unpin`
           which is required by
           `&mut impl std::future::Future: std::future::Future`

虽然我们在上一章介绍了Future，但仍然不能明白这个错误。如果你尝试在一个引用上调用.await时，遇到了这种关于Future未被实现的错误，那么你可能需要固定该future。

在标准库上阅读更多有关Pin的信息。

修改一个分支

再看一个稍微复杂一点的循环，其中有：

一个i32类型的通道。
在i32值上执行的异步操作。

我们想要实现的逻辑是：

在通道上等待一个偶数。
使用该偶数作为输入以启动异步操作。
等待操作完成，但同时监听通道上的其他偶数。
如果在现有操作完成之前收到新的偶数，则终止现有操作并使用新偶数重新开始。

async fn action(input: Option<i32>) -> Option<String> {
    // 若输入为`None`则返回`None`。
    // 此处也可以简写为`let i = input?；`
    let i = match input {
        Some(input) => input,
        None => return None,
    };
    // async logic here
}

#[tokio::main]
async fn main() {
    let (mut tx, mut rx) = tokio::sync::mpsc::channel(128);
    
    let mut done = false;
    let operation = action(None);
    tokio::pin!(operation);
    
    tokio::spawn(async move {
        let _ = tx.send(1).await;
        let _ = tx.send(3).await;
        let _ = tx.send(2).await;
    });
    
    loop {
        tokio::select! {
            res = &mut operation, if !done => {
                done = true;

                if let Some(v) = res {
                    println!("GOT = {}", v);
                    return;
                }
            }
            Some(v) = rx.recv() => {
                if v % 2 == 0 {
                    // `.set` is a method on `Pin`.
                    operation.set(action(Some(v)));
                    done = false;
                }
            }
        }
    }
}

我们使用与上一个例子类似的策略，在循环外调用异步函数并将结果赋给operation，再将operation变量固定。循环中的选择操作同事在operation上与通道接收端上进行。

留意action是如何将Option<i32>作为参数的。在我们收到第一个偶数之前，我们需要将operation实例化，此处通过接收一个Option并返回一个Option来创建action，而如果传入为None则返回也为None。第一次循环迭代，operation返回None后立即完成。

例子中还使用了一些新的语法，第一个分支中的, if !done，即设置分支的前置条件。在解释它是如何工作之前，让我们看看如果删掉前置条件会发生什么。删除, if !done再运行例子会产生以下输出：

thread 'main' panicked at '`async fn` resumed after completion', src/main.rs:1:55
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

在operation完成后再次尝试调用就会发生此错误。通常，在使用.await时，被等待的值会被使用掉，而在这个例子中，我们等待的是一个引用。这意味着operation在完成后仍然存在。

为避免这种panic，我们必须要在操作完成后禁用第一个分支，此处done变量用于跟踪操作是否完成。一个select!分支可能包含一个前置条件，select!在等待分支之前会检查这个前提条件，如果前置条件求值为false，则分支被禁用。done变量初始化时为false，当操作完成时，done设置为true，在下一个循环迭代中将禁用operation分支。当从通道接收到的消息为偶数时，operation将被重置，done也将置为false。

单任务并发

tokio::spawn和select!都可以运行异步并发操作，但是，它们运行并发操作时使用的策略并不相同。tokio::spawn函数接受一个异步操作后生成一个新任务以运行该操作，即Tokio运行时调度的对象是任务。Tokio分别安排了两个不同的任务，它们可能运行在不同的系统线程上，因此，生成任务与生成线程具有相同的限制：禁止借用。

而select!宏在同一任务上同时运行所有分支。由于select!宏的所有分支在同一个任务上执行，它们永远不会同时运行。即slect!宏在单个任务上复用了异步操作。

流

流，就是一系列异步值，是Rust的std::iter::Iterator的异步版本，用Stream trait表示。在异步函数中可以迭代遍历流，也可以使用适配器转换流。Tokio在StreamExt trait上提供了许多通用适配器。

Tokio在一个独立的crate中提供流支持：tokio-stream。

tokio-stream = "0.1"

:::caution 目前，Tokio的Stream实用程序放在tokio-stream crate 中。一旦Steam triat在Rust标准库中稳定下来，Tokio的流实用程序将被移动到tokio中。 :::

迭代

目前，Rust语言还不支持异步for循环，代替方案是使用while let循环配合StreamExt::next()在流上进行迭代。

use tokio_stream::StreamExt;

#[tokio::main]
async fn main() {
    let mut stream = tokio_stream::iter(&[1, 2, 3]);

    while let Some(v) = stream.next().await {
        println!("GOT = {:?}", v);
    }
}

与迭代器类似，next()方法返回Option<T>，T为流内值的类型，若收到None则表示流迭代终止。

Mini-Redis广播

让我们来再看一个使用Mini-Redis客户端的稍微复杂的例子。

你可以在这里找到完整的代码。

use tokio_stream::StreamExt;
use mini_redis::client;

async fn publish() -> mini_redis::Result<()> {
    let mut client = client::connect("127.0.0.1:6379").await?;

    // Publish some data
    client.publish("numbers", "1".into()).await?;
    client.publish("numbers", "two".into()).await?;
    client.publish("numbers", "3".into()).await?;
    client.publish("numbers", "four".into()).await?;
    client.publish("numbers", "five".into()).await?;
    client.publish("numbers", "6".into()).await?;
    Ok(())
}

async fn subscribe() -> mini_redis::Result<()> {
    let client = client::connect("127.0.0.1:6379").await?;
    let subscriber = client.subscribe(vec!["numbers".to_string()]).await?;
    let messages = subscriber.into_stream();

    tokio::pin!(messages);

    while let Some(msg) = messages.next().await {
        println!("got = {:?}", msg);
    }

    Ok(())
}

#[tokio::main]
async fn main() -> mini_redis::Result<()> {
    tokio::spawn(async {
        publish().await
    });

    subscribe().await?;

    println!("DONE");

    Ok(())
}

生成一个任务以在Mini-Redis服务器的“number”频道上发布消息。然后，在主任务中订阅“numbers”频道并打印收到的消息。

订阅后，在返回的订阅者上调用into_stream()。如此将消耗掉该Subscriber，并返回一个能够在消息到达时产生消息的流。请注意，在开始迭代消息之前，我们用tokio::pin!将流固定在栈上，因为在流上调用next()需要固定该流。into_stream()函数返回一个未固定的流，我们必须显式固定后才能迭代它。

固定值的一个关键属性是可以将指针指向固定数据，并且调用者可以确信指针保持有效。 async/await 使用此功能来支持跨 .await 点借用数据。

:::caution 当一个Rust值不能再在内存中移动时，就称为被“固定”了。对于被固定的值，其中一个关键属性是可以将指针指向该数据，而调用者可以确信指针始终有效。async/await使用此特性来支持跨.await时对借用数据进行调用。 :::

如果我们忘记固定流，就会看到类似下面的错误：

error[E0277]: `from_generator::GenFuture<[static generator@Subscriber::into_stream::{closure#0} for<'r, 's, 't0, 't1, 't2, 't3, 't4, 't5, 't6> {ResumeTy, &'r mut Subscriber, Subscriber, impl Future, (), std::result::Result<Option<Message>, Box<(dyn std::error::Error + Send + Sync + 't0)>>, Box<(dyn std::error::Error + Send + Sync + 't1)>, &'t2 mut async_stream::yielder::Sender<std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 't3)>>>, async_stream::yielder::Sender<std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 't4)>>>, std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 't5)>>, impl Future, Option<Message>, Message}]>` cannot be unpinned
  --> streams/src/main.rs:29:36
   |
29 |     while let Some(msg) = messages.next().await {
   |                                    ^^^^ within `tokio_stream::filter::_::__Origin<'_, impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>`, the trait `Unpin` is not implemented for `from_generator::GenFuture<[static generator@Subscriber::into_stream::{closure#0} for<'r, 's, 't0, 't1, 't2, 't3, 't4, 't5, 't6> {ResumeTy, &'r mut Subscriber, Subscriber, impl Future, (), std::result::Result<Option<Message>, Box<(dyn std::error::Error + Send + Sync + 't0)>>, Box<(dyn std::error::Error + Send + Sync + 't1)>, &'t2 mut async_stream::yielder::Sender<std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 't3)>>>, async_stream::yielder::Sender<std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 't4)>>>, std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 't5)>>, impl Future, Option<Message>, Message}]>`
   |
   = note: required because it appears within the type `impl Future`
   = note: required because it appears within the type `async_stream::async_stream::AsyncStream<std::result::Result<Message, Box<(dyn std::error::Error + Send + Sync + 'static)>>, impl Future>`
   = note: required because it appears within the type `impl Stream`
   = note: required because it appears within the type `tokio_stream::filter::_::__Origin<'_, impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>`
   = note: required because of the requirements on the impl of `Unpin` for `tokio_stream::filter::Filter<impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>`
   = note: required because it appears within the type `tokio_stream::map::_::__Origin<'_, tokio_stream::filter::Filter<impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>, [closure@streams/src/main.rs:26:14: 26:40]>`
   = note: required because of the requirements on the impl of `Unpin` for `tokio_stream::map::Map<tokio_stream::filter::Filter<impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>, [closure@streams/src/main.rs:26:14: 26:40]>`
   = note: required because it appears within the type `tokio_stream::take::_::__Origin<'_, tokio_stream::map::Map<tokio_stream::filter::Filter<impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>, [closure@streams/src/main.rs:26:14: 26:40]>>`
   = note: required because of the requirements on the impl of `Unpin` for `tokio_stream::take::Take<tokio_stream::map::Map<tokio_stream::filter::Filter<impl Stream, [closure@streams/src/main.rs:22:17: 25:10]>, [closure@streams/src/main.rs:26:14: 26:40]>>`

如果你遇到类似上面这样的错误，请尝试固定该值。

在运行上面的代码之前，先启动Mini-Redis服务端：

mini-redis-server

再尝试运行代码，我们就会在STDOUT中看到如下输出：

got = Ok(Message { channel: "numbers", content: b"1" })
got = Ok(Message { channel: "numbers", content: b"two" })
got = Ok(Message { channel: "numbers", content: b"3" })
got = Ok(Message { channel: "numbers", content: b"four" })
got = Ok(Message { channel: "numbers", content: b"five" })
got = Ok(Message { channel: "numbers", content: b"6" })

由于订阅和发布之间存在竞争，一些早期消息可能会被丢弃。该程序永远不会退出，只要服务端保持活动状态，对Mini-Redis频道的订阅就会保持活动状态。

让我们看看如何使用流来扩展这个程序。

适配器

接受一个Stream并返回另一个Stream的函数通常称为“流适配器”，因为这属于“适配器模式”。常见的流适配器包括map、take和filter。

更新Mini-Redis以使其可以退出。我们希望收到三个消息后就停止遍历。这可以使用take完成，此适配器限制流最多只能产生n条消息。

let messages = subscriber
    .into_stream()
    .take(3);

再次运行程序，输出为：

got = Ok(Message { channel: "numbers", content: b"1" })
got = Ok(Message { channel: "numbers", content: b"two" })
got = Ok(Message { channel: "numbers", content: b"3" })

而这一次程序执行完毕后退出。

现在，让我们将流中的信息限制为一位数，我们将通过检查消息长度来实现这一点。这次使用filter适配器，以丢弃任何与此断言不匹配的消息。

let messages = subscriber
    .into_stream()
    .filter(|msg| match msg {
        Ok(msg) if msg.content.len() == 1 => true,
        _ => false,
    })
    .take(3);

再次运行程序，输出为：

got = Ok(Message { channel: "numbers", content: b"1" })
got = Ok(Message { channel: "numbers", content: b"3" })
got = Ok(Message { channel: "numbers", content: b"6" })

请注意，适配器的应用顺序很重要。先调用filter再调用take与先调用take再调用filter是不同的。

最后，我们将整理输出，即删除输出中的Ok(Message { ... })部分，这次使用map。因为这是在filter之后应用的，我们知道消息是Ok，因此可以使用unwrap()。

let messages = subscriber
    .into_stream()
    .filter(|msg| match msg {
        Ok(msg) if msg.content.len() == 1 => true,
        _ => false,
    })
    .map(|msg| msg.unwrap().content)
    .take(3);

此时的输出为：

got = b"1"
got = b"3"
got = b"6"

另一种选择是使用filter_map将filter和map合并在一个调用中。

还有更多可用的适配器，请查看此列表。

实现`Stream`

Stream trait与Future trait非常相似。

use std::pin::Pin;
use std::task::{Context, Poll};

pub trait Stream {
    type Item;

    fn poll_next(
        self: Pin<&mut Self>, 
        cx: &mut Context<'_>
    ) -> Poll<Option<Self::Item>>;

    fn size_hint(&self) -> (usize, Option<usize>) {
        (0, None)
    }
}

Stream::poll_next()函数很像Future::poll，不同在于你可以重复调用它，以从流中接收许多更多值。正如我们在深入异步中看到的那样，当流的返回值尚未就绪时，将返回Poll::Pending，此时任务的唤醒器已注册，一旦要再次轮询流，唤醒器就会收到通知。

size_hint()方法的使用方式与其在迭代器上的使用方式相同。

通常，在手动实现Stream时，是通过组合futures和其他流来完成的。作为一个例子，让我们再次以深入异步中实现的Delay future为基础构建。这次实现为以10毫秒为间隔产生三次()的流。

use tokio_stream::Stream;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::Duration;

struct Interval {
    rem: usize,
    delay: Delay,
}

impl Stream for Interval {
    type Item = ();

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>)
        -> Poll<Option<()>>
    {
        if self.rem == 0 {
            // No more delays
            return Poll::Ready(None);
        }

        match Pin::new(&mut self.delay).poll(cx) {
            Poll::Ready(_) => {
                let when = self.delay.when + Duration::from_millis(10);
                self.delay = Delay { when };
                self.rem -= 1;
                Poll::Ready(Some(()))
            }
            Poll::Pending => Poll::Pending,
        }
    }
}

`async-stream`

使用Stream特性手动实现流可能很乏味。然而，Rust尚不支持使用async/await语法定义流，该特性正在实现，只是尚未完成。

可将async-stream crate当作临时解决方案。该crate提供了一个stream!宏可以将输入转换为流。使用该crate，上面的interval可以这样实现：

use async_stream::stream;
use std::time::{Duration, Instant};

stream! {
    let mut when = Instant::now();
    for _ in 0..3 {
        let delay = Delay { when };
        delay.await;
        yield ();
        when += Duration::from_millis(10);
    }
}

PingCap的Rust训练课程4：并发与并行

Sat, 18 Jun 2022 18:40:00 GMT

:::warning 本文内容大多翻译自原文：PNA Rust Project 4: Concurrency and parallelism。 :::

前言

任务：使用自定义协议，创建一个具有同步网络的多线程、持久化键/值存储的服务端和客户端。

目标：

写一个简单的线程池
使用通道进行跨线程通信
利用锁共享数据结构
无锁执行读操作
对单线程与多线程版本进行基准测试 关键词：线程池、通道、锁、无锁数据结构、原子化、参数化基准测试。

介绍

在这个项目中，您将创建一个使用自定义协议进行通信的简单键/值服务端和客户端。服务端将使用同步网络，并将使用较为复杂的并发实现来响应多个请求。内存索引将改为并发数据结构，由所有线程共享，而压缩操作将在专用的线程上完成，以减少单个请求的延迟。

项目需求规格

命令行规格与前一个项目相同。本项目与前一个项目的的不同之处在于并发实现，在我们实现时会对其进行描述。

库的规格几乎相同，除了以下两点：一是这一次所有的KvsEngine、KvStore等类型的方法都使用&self而不是&mut self，我们将实现Clone trait，这在并发数据结构中很常见。但为什么呢？其实并不是说我们将不再编写不可变代码，尽管它们将会在线程之间共享。那为什么要在方法签名中避免使用&mut self？也许您现在还不清楚，但在本项目结束时，它会变得显而易见。

二是本项目中的库包含一个新的trait：ThreadPool。它包含以下方法：

ThreadPool::new(threads: u32) -> Result<ThreadPool> 创建一个新的线程池，立即生成指定数量的线程。如果未能生成线程，则返回错误。所有先前产生的线程都被结束。
ThreadPool::spawn<F>(&self, job: F) where F: FnOnce() + Send + 'static 在线程池中运行一个函数。运行操作总是成功的，但如果函数发生panic，线程池仍将继续以相同数量的线程运行 — 线程数不会减少，线程池也不会被析构、损坏或失效。

到这个项目结束时，该特性将有几个实现，您将再次执行基准测试来比较它们。

本项目完全不需要对客户端代码进行任何修改。

项目设置

继续上一个项目，删除之前的测试目录，并复制本项目的测试目录。这个项目应该包含一个名为kvs的库，以及两个可执行文件，kvs-server和kvs-client。

Cargo.toml中需要以下开发依赖项：

[dev-dependencies]
assert_cmd = "0.11"
criterion = "0.2.11"
crossbeam-utils = "0.6.5"
predicates = "1.0.0"
rand = "0.6.5"
tempfile = "3.0.7"
walkdir = "2.2.7"
panic-control = "0.1.4"

与以前的项目一样，添加足够的定义以使测试套件通过编译。

添加新模块thread_pool：

.
└── src
   └── thread_pool
      ├── mod.rs
      ├── naive.rs
      ├── rayon.rs
      └── shared_queue.rs

在lib.rs中添加thread_pool模块：

pub mod thread_pool;

在mod.rs中声明三种线程池：

//! This module provides various thread pools. All thread pools should implement
//! the `ThreadPool` trait.
use crate::Result;

mod naive;
mod rayon;
mod shared_queue;

pub use self::naive::NaiveThreadPool;
pub use self::rayon::RayonThreadPool;
pub use self::shared_queue::SharedQueueThreadPool;

/// The trait that all thread pools should implement.
pub trait ThreadPool {
    /// Creates a new thread pool, immediately spawning the specified number of
    /// threads.
    ///
    /// Returns an error if any thread fails to spawn. All previously-spawned threads
    /// are terminated.
    fn new(threads: u32) -> Result<Self>
    where
        Self: Sized;

    /// Spawns a function into the thread pool.
    ///
    /// Spawning always succeeds, but if the function panics the threadpool continues
    /// to operate with the same number of threads &mdash; the thread count is not
    /// reduced nor is the thread pool destroyed, corrupted or invalidated.
    fn spawn<F>(&self, job: F)
    where
        F: FnOnce() + Send + 'static;
}

三种线程池都用最简单的标准线程做实现，以通过编译。这里以naive.rs为例，其他两个也使用这样的实现即可：

use std::thread;
use super::ThreadPool;

use crate::Result;

/// It is actually not a thread pool. It spawns a new thread every time
/// the `spawn` method is called.
pub struct NaiveThreadPool;

impl ThreadPool for NaiveThreadPool {
    fn new(_threads: u32) -> Result<Self> {
        Ok(NaiveThreadPool)
    }

    fn spawn<F>(&self, job: F)
    where
        F: FnOnce() + Send + 'static,
    {
        thread::spawn(job);
    }
}

知识背景：阻塞和多线程

到目前为止，您已经在单线程上处理了所有请求，包括读取和写入（例如"get"和"set"）。换句话说，数据库中的所有请求都是串行的。使用我们将在这个项目中重复的图表，时间流向如下所示：

    thread
           +  +--------+--------+--------+--------+
      T1   |  |   R1   |   R2   |   W1   |   W2   |
           +  +--------+--------+--------+--------+

              --> read/write reqs over time -->

读取和写入操作都可能需要阻塞。阻塞是指线程在等待访问资源时停止执行（例如等待访问文件中的数据，或等待访问受锁保护的变量）。当一个线程在一个任务上被阻塞时，便可不能执行另一个任务。因此，在I/O密集型系统中，任何请求可能都在花费大量时间等待操作系统和内存从磁盘读取数据或将数据写入磁盘：

          +---------+----------------------------+---------+
      R1  | working | waiting for data ...       | working |
          +---------+----------------------------+---------+

          --> time -->

The simplest way to put the CPU back to work while one request is blocked is to service requests on multiple threads, so that ideally our requests are all processed concurrently, and — if we have enough CPUs — in parallel:

在一个请求被阻塞时，让CPU能够继续工作的最简单方法，是创建多个线程一起提供服务。因此理想情况下，我们的请求都是并发处理的 — 如果我们有足够的 CPU — 即并行处理：

    thread
           +  +--------+
      T1   |  |   R1   |
           |  +--------+
      T2   |  |   R2   |
           |  +--------+
      T3   |  |   W1   |
           |  +--------+
      T4   |  |   W2   |
           +  +--------+

              --> read/write reqs over time -->

所以这将是本项目的重点 — 并行处理请求。

第1部分：多线程

鉴于我们首次引入并发概念，就用最简单的方法：为每个传入的连接创建一个新线程，并响应该连接上的请求，然后让线程退出。如此，将工作分发到多个线程将提供怎样的性能收益？您预计延迟会受到怎样的影响？吞吐量呢？

第一步是为这种简单方法编写一个ThreadPool实现，其中ThreadPool::spawn将为每个生成的作业创建一个新线程。我们称之为NaiveThreadPool（实际上它甚至不能算是一个真正的线程池，因为这个实现不会在各作业间重用线程，但仍需要符合我们的trait规范以供之后的基准测试比较）。

我们现在不关注更复杂的实现，因为即使将这个简单方法集成到我们现有的设计中仍需要不少努力。请注意，ThreadPool::new构造函数接受一个threads参数，用于指定池中的线程数。在此实现中，该参数将处于未使用状态。

现在来实现这个版本的ThreadPool，然后我们将它集成到新的KvStore中。

需要通过的测试用例：

thread_pool::naive_thread_pool_*

经过“项目设置”一节的修改，现在的代码已经能够通过cargo test --test thread_pool的所有测试（实现时再修改）。

...
running 4 tests
test rayon_thread_pool_spawn_counter ... ok
test naive_thread_pool_spawn_counter ... ok
test shared_queue_thread_pool_spawn_counter ... ok
test shared_queue_thread_pool_panic_task ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s

第2部分：创建可共享`KvsEngine`

在我们将NaiveThreadPool集成到KvsServer之前，我们必须创建KvsEngine trait并实现KvStore（现在您可以忽略上一个项目中的 SledKvsEngine，当然，您可以重新实现它作为这个项目的附加作业）。

回想一下项目需求规格规范，在本项目中，KvsEngine会使用&self作为self，而不是上一个项目中的&mut self。此外，还需要为每个实现，显式编写Clone，并为它们隐式添加Send + 'static。具体定义如下：

pub trait KvsEngine: Clone + Send + 'static {
    fn set(&self, key: String, value: String) -> Result<()>;

    fn get(&self, key: String) -> Result<Option<String>>;

    fn remove(&self, key: String) -> Result<()>;
}

这个trait签名提供了很代码实现相关的信息。首先想想当我们要使用多线程实现时，为什么需要引擎实现Clone。参考Rust中其他并发数据类型的设计，例如Arc。再想想为什么需要使用&self，而不是&mut self。您对共享可变状态了解多少？在这个项目结束时，请确保你理解这里的含义 — 这就是我们使用Rust的意义。

在这个模型中，KvsEngine的行为类似于另一个对象的句柄，并且由于该对象需要在线程之间共享，它可能需要保持在堆上，并且因为该共享状态不能是可变的，它需要由一些同步原语保护。

因此，使用线程安全的共享指针类型将KvsEngine、KvStore中的数据移动到堆上，并将其保护在您选择的锁之后。

由于SledKvsEngine实现了KvsEngine，它可能也需要更改。

此时，您的单线程kvs-server应该可以再次工作，但现在有了一个可以在以后跨线程共享的KvsEngine。

需要通过的测试用例：

kv_store::concurrent_*

Arc会将内容物放在堆上，并可以使用clone创建指向同一个地址的引用；
之所以修改trait定义之后可以不使用mut引用，是因为实现时将以类似self.writer.lock().unwrap().set(key, value)的方式使用KvsEngine的写操作，而读操作封装在RefCell中即可共享；
将KvStore中的内存索引改为可并发的Arc<SkipMap<...>>方式，并将写对象封装在Arc<Mutex<...>>中，以便在多个线程中执行写操作；
创建一个单线程的KvStoreReader，将日志文件句柄封装在RefCell中以便共享读操作。继续负责从gen日志文件中读取CommandPos处的json数据并解析为Command返回；
创建一个跨线程的KvStoreWriter接管原KvStore中的写日志操作，包括set、remove、compact；

第3部分：向`KvsServer`添加多线程

让我们在这里快速回顾一下我们的架构：KvsServer设置一个TCP套接字并开始监听；当收到一个请求时，将反序列化并调用KvsEngine trait的一些实现来存储或检索数据；最后返回响应。KvsEngine如何工作的细节与KvsServer无关。

因此，在上一个项目中，您可能模糊地创建了一个循环，例如：

let listener = TcpListener::bind(addr)?;

for stream in listener.incoming() {
    let cmd = self.read_cmd(&stream);
    let resp = self.process_cmd(cmd);
    self.respond(&stream, resp);
}

现在您只需要做类似的事情，然后把循环内的工作都放在NaiveThreadPool中执行。这会将数据库查询和响应工作放在与TCP监听不同的线程中，从而将大部分繁重的工作转移到其他线程，以允许接收线程处理更多请求。如此便能够增加吞吐量，至少在多核机器上是这样。

于是，您现在仍然有一对有效的客户端/服务端键值存储，只不过现在是多线程的。

在循环中clone KvsEngine，然后将KvsEngine和ThreadPool一起传给线程执行函数serve；
此时serve由于有了KvsEngine的clone引用，也不需要通过self调用引擎了，因此可以不再当做类函数使用；
在bin/kvs-server.rs中创建服务时需要加上ThreadPool参数，可以在Cargo.toml中引入num_cpus库，以在创建线程池时自动获取主机cpu个数。

第4部分：创建真正的线程池

所以现在你已经有了你的多线程架构，是时候编写一个真正的线程池了。您可能不会在实践中编写自己的线程池，因为可以使用已经过充分测试的线程池crate，不过通过自己编写线程池可以更有效的学习并发相关经验。在本项目接下来的部分中，您将像我们在上一个项目中对引擎所做的那样，抽象线程池，并将您的实现与现有线程池进行性能比较。

那么，什么是线程池？

其实也没什么复杂的。为了不给每个要执行的多线程作业都创建一个新线程，我们选择来维护一“池”的线程，并不停重用这些线程以避免不停的创建新线程。

那么，为什么？

因为可以提高性能。重用线程可以节省出少量性能，而在编写高性能应用程序时，每一点性能都很重要。想象一下创建一个新线程需要什么：

您必须有一个调用栈才能运行该线程，从而必须为该调用栈分配空间。虽然分配空间已然相当简单，但仍不如不分配来的简单。调用栈的分配方式取决于操作系统和运行时的细节，但可能涉及锁和系统调用。同样的，虽然系统调用也很简单，但是当我们处理Rust级别的性能时它们也就算不上简单了 — 减少系统调用是简单且常见的优化方式。然后必须仔细初始化该栈，以便第一个栈帧包含适当的基指针值以及栈的初始化函数序言中所需的任何其他值。在Rust中，栈需要配置一个保护页来防止栈溢出，从而保护内存安全。这需要另外两个系统调用，mmap和mprotect（尽管Linux上避免了这两个系统调用）。

而这只是设置调用栈。创建新线程至少也需要一个系统调用，而内核必须在内部对新线程进行计算。

在Rust中，C库libpthread库负责处理大多数这种复杂工作。

然后在某个时刻，操作系统在新栈上执行上下文切换，线程运行。当线程终止时，所有工作都需要再次撤消。

当使用线程池时，仅有池里的线程需要初始化开销，后续作业只是简单的上下文切换到池中的线程。

那么如何构建线程池？

有许多策略和权衡，但对于练习项目，您只需将使用一个共享队列将工作分配给空闲线程即可。这意味着您的“生产者”，即接受网络连接的线程，将作业发送到这个队列（或通道）；而“消费者”，即池中的每个空闲线程，从该队列（通道）读取等待作业执行。这是最简单的工作调度策略，而且可能非常高效。那么，这种方法有什么缺点？

这里有三个重要因素需要考虑：

使用哪种数据结构来分配工作 — 应是一个队列，且应有一个发送者（“生产者”）负责监听TCP连接，同时应用许多接收者（“消费者”）即池中的线程。
如何处理panic的作业 — 线程池将运行任意作业。如果一个线程发生panic，线程池需要以某种方式恢复。
如何应对退出 — 即当ThreadPool对象超出作用域时，它需要关闭每个线程，一定不能不管这些线程。

这些问题都是相互交织的，因为每一个问题都可能涉及线程间的通信和同步。有些解决方案会很简单，每个问题的解决方案都可以优雅地协同工作；有些解决方案会很复杂，这些问题的解决方案可能相互独立独立且相互交织。仔细选择您的数据结构，聪明的运用这些数据结构的特点。

您将通过在某些并发队列类型上发送消息来分发工作（Rust中的并发队列通常是具有两种连接类型的数据结构：发送者类和接收者类；任何实现了Send + 'static的类型都可以在这两个类之间传递）。

Rust中的消息通常表示为枚举类型，每个可能发送的消息都有相应变量，例如：

enum ThreadPoolMessage {
    RunJob(Box<dyn FnOnce() + Send + 'static>),
    Shutdown,
}

这往往是一种更简单、更有效的解决方案，而不是为了不同目的而试图“兼顾”多个通道。当然，如果只有一种类型的消息，则不需要枚举。现在，上面的示例并不一定是管理线程池所需消息集的全集，这具体取决于设计。比如，如果您的队列返回值表明发送方已被销毁，则通常可以隐式shutdown。

现在有许多种的多线程队列。在Rust中最常见的是mpsc通道，就包含在Rust标准库中。这是一个多生产者、单消费者队列，因此将其用于单队列线程池将需要某种锁。在这里使用锁有什么缺点？Rust中还有许多其他并发队列类型，每种都有优缺点。如果您愿意同时锁定生产者和消费者，那么您甚至可以使用Mutex<VecDeque>，不过如果存在更好的解决方案，就没有理由在生产中这么做了。

历史趣事：Rust标准库中包含通道这件事有些奇怪，并且被一些人认为是一个错误，因为它背离了Rust的理念 — 保持最小化标准库、专注抽象操作系统，并让crate生态提供高级数据结构。它们的存在是Rust开发史中刻意为之的，可能来源于Go这样消息传递语言。其他库（例如crossbeam）提供了更复杂的替代方案，为不同场景提供更合适的选项😉。

您的线程池将需要处理作业函数产生panic的情况 — 放任panic销毁线程可能会使池中的线程快速耗尽。因此，如果池中的某个线程panic，您需要确保线程总数不会减少。那该怎么办？您至少有两个选择：当有线程销毁时立刻新建另一个线程，或者捕获panic并保持现有线程运行。这需要您做出权衡并选择其中一种方式，在您的代码中注释您的选择。

您可能会用到的工具有：thread::spawn、thread::panicking、catch_unwind、mpsc通道、Mutex、crossbeam的MPMC通道、thread的JoinHandle。按照您的需求选择合适的工具。

创建SharedQueueThreadPool类，实现ThreadPool。

需要完成的测试用例：

shared_queue_thread_pool_*

将KvsServer中用到的NaiveThreadPool替换为SharedQueueThreadPool。同样，您的kvs-server应该仍然像以前一样工作，只不过这次的多线程模型更高效一些。您应当使用恰当的数量构造线程池，这里推荐使用num_cpus crate，以为每个CPU创建一个线程。稍后我们将再次讨论线程个数。

利用crossbeam::channel创建一对tx/rx（发送者/接收者），tx用于在线程池的spawn中向channel发送作业，rx负责接收并执行这些作业；
我们目前的策略为放任线程panic，并立刻创建新线程。要实现这一策略需要将rx封装在新类TaskReceiver中，然后控制该类的Drop行为，当发生thread::panicking()时，克隆本TaskReceiver实例并放入新建的线程中以继续接收新的作业；
线程的执行函数，只需使用loop持续等待作业并执行作业中的函数即可。

use std::thread;
use crossbeam::channel::{self, Sender, Receiver};
use log::{debug, error};

use super::ThreadPool;

use crate::Result;

// Note for Rust training course: the thread pool is not implemented using
// `catch_unwind` because it would require the task to be `UnwindSafe`.

/// A thread pool using a shared queue inside.
///
/// If a spawned task panics, the old thread will be destroyed and a new one will be
/// created. It fails silently when any failure to create the thread at the OS level
/// is captured after the thread pool is created. So, the thread number in the pool
/// can decrease to zero, then spawning a task to the thread pool will panic.
pub struct SharedQueueThreadPool {
    tx: Sender<Box<dyn FnOnce() + Send + 'static>>, 
}

impl ThreadPool for SharedQueueThreadPool {
    fn new(threads: u32) -> Result<Self> {
        let (tx, rx) = channel::unbounded::<Box<dyn FnOnce() + Send + 'static>>();
        for _ in 0..threads {
            let rx = TaskReceiver(rx.clone());
            thread::Builder::new().spawn(|| run_task(rx))?;
        }
        Ok(SharedQueueThreadPool { tx })
    }

    /// Spawns a function into the thread pool.
    ///
    /// # Panics
    ///
    /// Panics if the thread pool has no thread.
    fn spawn<F>(&self, job: F)
    where
        F: FnOnce() + Send + 'static,
    {
        self.tx
            .send(Box::new(job))
            .expect("The thread pool has no thread.");
    }
}


#[derive(Clone)]
struct TaskReceiver(Receiver<Box<dyn FnOnce() + Send + 'static>>);

impl Drop for TaskReceiver {
    fn drop(&mut self) {
        if thread::panicking() {
            let rx = self.clone();
            if let Err(e) = thread::Builder::new().spawn(move || run_task(rx)) {
                error!("Failed to spawn a thread: {}", e);
            }
        }
    }
}

fn run_task(rx: TaskReceiver) {
    loop {
        match rx.0.recv() {
            Ok(task) => {
                task();
            },
            Err(_) => debug!("Thread exits because the thread pool destoryed. "),
        }
    }
}

第5部分：抽象线程池

与在之前的项目中抽象出KvsEngine来比较不同的实现一样，现在您应抽象出ThreadPool来做类似的事。

如果您还没有这么做，请向KvsServer添加第二个类型参数以表示ThreadPool实现，构造函数以线程池作为第二个参数，并使用该线程池来分发作业。

最后，使用rayon crate中的ThreadPool创建另一个ThreadPool，以实现RayonThreadPool。

Rayon的线程池使用一种称为“工作窃取”的更复杂的调度策略，预计它的性能会比我们的实现更好，不过在我们尝试之前谁知道呢！

use super::ThreadPool;

use crate::{Result, KvsError};

/// Wrapper of rayon::ThreadPool
pub struct RayonThreadPool{
    pool: rayon::ThreadPool,
}

impl ThreadPool for RayonThreadPool {
    fn new(threads: u32) -> Result<Self> {
        let pool = rayon::ThreadPoolBuilder::new()
            .num_threads(threads as usize)
            .build()
            .map_err(|e| KvsError::StringError(format!("{}", e)))?;
        Ok(RayonThreadPool{pool})
    }

    fn spawn<F>(&self, job: F)
    where
        F: FnOnce() + Send + 'static,
    {
        self.pool.spawn(job)
    }
}

第6部分：评估您的线程池

现在您将编写6个基准测试，一个写入繁重的工作负载比较SharedQueueThreadPool在不同线程数下的性能，一个读取繁重的工作负载比较SharedQueueThreadPool在不同线程数下的性能；再写两个测试，类似前面两个只不过用来测试RayonThreadPool；最后还有两个将RayonThreadPool与SledKvsEngine结合使用。

看上去要写6个其实并没有那么多 — 因为后四个基本上是复制前两个。

注意：接下来的两节描述了一组相当复杂的基准测试。它们确实可以实现出来（可能……还没有人写过），但有效理解和高效编写都比较难。两节确实介绍了一些有用的criterion特性，但如果对你来说内容过于庞杂，可以选择跳过（也可以告诉我们有哪些内容不适合你）。不过，这里的困难可能是一个很好的学习机会。最后，实现这些基准测试需要实现以编程方式关闭KvsServer的方法（即不发送SIGKILL并让操作系统执行退出），我们之前还没有讨论过。

其中一部分工作就是让将前一个项目中的SledKvsEngine在本项目的多线程环境中再次工作。这应该不难，因为sled可以被克隆并在线程间发送，就像您编写的引擎一样。

希望结果会很有趣。

您将再次使用criterion。

这些将是参数化基准测试，即使用不同参数多次运行的单个测试，而criterion支持使用参数作为基准测试的输入。这里的基准测试参数将是线程池中的线程数。

您将尝试测试服务器在各种条件下的吞吐量。您将同时发送许多请求，等待响应，然后结束。您可能会好奇，服务器CPU数量与线程总数的关系，是如何影响吞吐量的；您的线程池与rayon相比性能如何；以及在多线程环境下您的KvStore与SledKvsEngine的比较。

由于您的KvsClient（可能会）被阻塞，即请求后等待响应，这会使测试变的复杂。如果是非阻塞的，那么您可以发送许多请求而无需等待响应，然后再收集响应。而使用阻塞的KvsClient，您将需要在独立的线程中发送每个请求，以使服务饱和。

在进行基准测试时，一定要清楚您希望评估哪些代码，并尽可能只去测试那一部分代码。像criterion这样的基准测试库在一个循环中多次运行一段代码，测量它通过每个循环所花费的时间。因此，应当只将您想要评估的代码放入循环中，并将无关代码尽可能的留在循环外。

因此，以这个带有输入的简单criterion为例：

let c = Criterion::default();
let inputs = &[1, 2, 3, 4, 5];

c.bench_function_over_inputs("example", |b, &&num| {
    b.iter(|| {
        // important measured work goes here
    });
}, inputs);

iter多次调用您的闭包，测量每次迭代。但是如此就需要事先设置大量线程，您并不希望这么做。如果只需要设置一次，就能够在多次迭代中使用，则应该将设置过程放在闭包之外，例如：

let c = Criterion::default();
let inputs = &[1, 2, 3, 4, 5];

c.bench_function_over_inputs("example", |b, &&num| {
    // do setup here
    b.iter(|| {
        // important measured work goes here
    });
}, inputs);

只评估b.iter闭包中的代码，其余的环境设置代码都放在前面。

如果设置无法放在循环之前，那么另一种策略是使设置占用的工作量小于想要评估的代码的工作量，例如添加循环。也要考虑基准测试中的“析构”部分，通常指运行drop的成本。

如果您有一个阻塞客户端，则客户端将需要许多线程，而在执行循环之前，您只有一次机会创建这些线程。因此，在基准测试执行迭代前，您需要设置一堆可复用的线程。幸运的是，SharedQueueThreadPool就是一个很好的工具。为每个请求设置一个线程，并将其与某个通道配对，以报告收到响应，这就成了一个合适的基准测试工具。

现在开始编写前两个基准测试

前面提到这是一个参数化基准测试，参数就是服务器线程池中要使用的CPU核数。我们想看看只有1个、2个、4个等每个偶数一直到CPU核数的2倍时，吞吐量都是什么表现。至于为什么是2倍，也许拥有比内核更多的线程可能会有好处，您将通过实验来发现。

对于密集写入的作业，在环境设置期间（即调用b.iter(...)之前）先创建KvsServer<KvStore, SharedQueueThreadPool>，线程池使用参数化的线程数。然后编写一个作业，为1000个等长的键设置相同的值。请注意，尽管键不同，但为了测试结果的一致性，应在每个循环中使用同一套键。

然后在每次线程写入键和值后，也应该assert!调用成功（以确保作业执行中没有出错），从而表明作业成功完成。当所有线程都完成后，基准测试线程继续运行并结束迭代。实现这种信号式结束的最直观方法是让每个作业线程将消息发送回基准测试线程，但请记住，这些信号代码是与您希望评估的代码毫无关系的开销，因此它的工作量应尽可能少。您可以只使用一条消息，或者使用其他并发类型，仅向基准测试线程发出一次信号吗？

将此基准测试命名为write_queued_kvstore（或其他）。

对于密集读取作业，在环境设置期间先创建KvServer<KvStore, SharedQueueThreadPool>，线程池使用参数化的线程数。然后编写保护1000个线程的客户端线程池。仍然在环境设置阶段，创建另一个客户端并初始化1000个不同的等长键，并全部使用相同的值。

然后，在基准测试循环中，为客户端生成1000个检索相同键/值解析的作业，然后assert!结果是正确的。最后，像以前一样，向基准测试线程发送一条消息，表示读取已完成。

将此基准测试命名为read_queued_kvstore（或其他）。

的确有不少工作要做。

您可以像往常一样使用cargo bench运行这组criterion基准测试。

只不过这次您有更多工作要完成。由于您将要在多个参数上执行相同的基准测试，即以线程池中的线程数为参数，如果能将这些结果体现在一个漂亮的图表中，以看到不同线程数的影响，将会使测试结果更加直观。

恰好criterion就有这个功能！

请再次并阅读有关使用参数作为基准测试的输入的内容。文章解释了如何制作输入的基准测试图标。您注意到了什么？当您的线程数接近服务器CPU核数时会发生什么？当线程数超过服务器的线程数时会发生什么？您认为是什么导致了测试结果中的趋势？结果取决于许多因素，因此您的结果可能与其他任何人都不同。

这是始终进行基准测试而不非推测性能的一个很好的理由。我们可以做出有根据的猜测，但直到我们测试才会知道结果。

第7部分：评估其他线程池和引擎

到这里，您已经解决了基准测试练习中最困难的部分。现在您只需在之前的基础上做更多配置性工作即可。

拿您之前写的那两个基准，然后复制粘贴三遍。将这些副本中的SharedQueueThreadPool更改为RayonThreadPool。

将第三个和第四个命名为read/write_rayon_kvstore（或其他）。这两个将与前两个SharedQueueThreadPool实现进行比较，以了解您的实现与RayonThreadPool之间的区别。

第五个和第六个，命名为read/write_rayon_sledkvengine，将引擎改成SledKvsEngine。这些您将与前两个进行比较，以了解您的KvsEngine与多线程环境中的sled有什么区别。

和以前一样，运行并绘制所有这些基准测试。如上所述将它们相互比较，在各种线程数下，您的调度与rayon相比如何？在各种线程数下，您的存储引擎与sled相比如何？结果令人惊讶吗？你能想象为什么存在差异吗？

扩展1：比较函数

现在，您为三个不同的线程池执行了相同的基准测试，您运行了也比较了它们的性能。criterion内置支持比较多个实现。查看Criterion用户手册中的“比较函数”并修改您的基准测试，以便让criterion自己进行比较，看看那些华丽的图表。

背景：锁的极限

在本项目前期，我们建议通过将KvsEngine内部数据放在堆上并保护在锁之后来保证其线程安全。您可能立即意识到这不会提高吞吐量，因为它只是将一种阻塞换成了另一种阻塞 — 将原来的阻塞磁盘访问换成了现在的阻塞互斥访问。

所以到目前为止，我们所取得的成就是：

    thread
           +  +--------+
      T1   |  |   R1   |
           |  +-----------------+
      T2   |           |   R2   |
           |           +-----------------+
      T3   |                    |   W1   |
           |                    +-----------------+
      T4   |                             |   W2   |
           +                             +--------+
              --> read/write reqs over time -->

在上一节中，您对您的引擎与SledKvsEngine的多线程吞吐量进行了基准测试。希望您已经发现，您的多线程实现比sled的性能要差得多（如果不是，要么是您的实现非常棒，要么是sled出了什么问题）。到目前为止，添加多线程导致的性能比单线程实现更差 — 现在您的实现还需要执行线程间上下文切换的额外工作，以及为了保证互斥锁而强加的阻塞。

因此，对于项目的这一部分将变得更加复杂。用锁保护整个状态很容易 — 整个状态总是以原子方式读写，于是一次只有一个客户端可以访问整个状态。但这也意味着想要访问共享状态的两个线程必须互相等待。换句话说，当KvsEngine受互斥锁保护时，尽管是多线程的，但服务器中的实际并发量非常少。

高性能、可扩展、并行的软件倾向于尽可能避免锁和锁争用。与大多数语言相比，Rust使复杂且高性能的并发模式变的更容易（因为您无需担心数据竞争和程序崩溃），但它并不能阻止您写出可能导致错误程序行为的逻辑bug。

所以你仍然需要对并发进行一些认真的思考。幸运的是，Rust crate生态中有许多复杂的并行编程工具，因此您的任务通常只是了解它们是什么以及如何将它们组合在一起，而不是了解如何编写自己的复杂无锁数据结构。

让我们看一些更复杂的例子。我们将以单线程KvStore为例，并考虑如何将其改为线程安全的。

这是一个单线程KvStore示例，就像您在早期项目中创编写的那样（这是课程示例项目中的简化版本）：

pub struct KvStore {
    /// Directory for the log and other data
    path: PathBuf,
    /// The log reader
    reader: BufReaderWithPos<File>,
    /// The log writer
    writer: BufWriterWithPos<File>,
    /// The in-memory index from key to log pointer
    index: BTreeMap<String, CommandPos>,
    /// The number of bytes representing "stale" commands that could be
    /// deleted during a compaction
    uncompacted: u64,
}

而这是简单的多线程版本，用锁保护一切。希望您的实现看起来已经类似这样：

#[derive(Clone)]
pub struct KvStore(Arc<Mutex<SharedKvStore>>);

#[derive(Clone)]
pub struct SharedKvStore {
    /// Directory for the log and other data
    path: PathBuf,
    /// The log reader
    reader: BufReaderWithPos<File>,
    /// The log writer
    writer: BufWriterWithPos<File>,
    /// The in-memory index from key to log pointer
    index: BTreeMap<String, CommandPos>,
    /// The number of bytes representing "stale" commands that could be
    /// deleted during a compaction
    uncompacted: u64,
}

如此Arc<Mutex<T>>的解决方案，简单、正确且常见：

Arc将值放在堆上，以便它可以在线程之间共享，并提供一个clone方法来为每个线程创建一个“句柄”；
Mutex提供了一种在不使用&mut引用的情况下，获得该值的写访问权限的方法。

对于许多情况，这是一个完全合理的解决方案。但在本项目中，互斥锁将成为锁争用的源头：互斥锁不仅会串行化SharedKvStore的写访问，还会串行化读访问。任何想要使用KvStore的线程都需要等待Mutex被另一个线程解锁。所有请求都会阻塞任何其他并发请求。

我们真正想要的是不必使用锁，或者 — 如果确实需要锁的 — 它们尽量少的与其他线程竞争。

互斥锁的进阶是RwLock，即“读写锁”。这是每个并行软件开发者都必须知道的另一种常见锁。读写锁对互斥体的改进是它允许任意数量的读取，或单个写入。即用Rust术语，RwLock可以同时支持任意数量的&引用，或单个&mut引用。读会被写阻塞，写会阻塞其他所有读和写。

在我们的数据库中，这意味着可以同时满足所有读取请求，但是当单个写入请求进入时，系统中的所有其他活动都会停止并等待该写操作完成。实现这一点很简单，基本上就是将Mutex换成RwLock。

现在，再次考虑我们的多线程示意图，最终的处理流程如下所示：

    thread
           +  +--------+
      T1   |  |   R1   |
           |  +--------+
      T2   |  |   R2   |
           |  +-----------------+
      T3   |           |   W1   |
           |           +-----------------+
      T4   |                    |   W2   |
           +                    +--------+
              --> read/write reqs over time -->

第8部分：无锁读

对于本项目，我们想要尝试去创建永远不会锁定的读取器，即发生并发写入也依然不会阻塞读取。无论写入请求如何，都可以始终为读取请求提供服务。（写如现在仍然会阻塞其他写操作 — 除了成为一项具有挑战性的并行编程问题，并行写入本身是否有意义仍是一个难以回答的问题）。

我们最终的期望是：

    thread
           +  +--------+
      T1   |  |   R1   |
           |  +--------+
      T2   |  |   R2   |
           |  +--------+
      T3   |  |   W1   |
           |  +-----------------+
      T4   |           |   W2   |
           +           +--------+
              --> read/write reqs over time -->

如果能做到这一点，那么我们将实现无锁的读操作：即使有读操作在等待来自文件系统的数据（被阻塞），所有类型的其他操作（读和写）都可以继续进行。不过，这仍然不足以保证系统始终可以为读请求提供服务。想想如果在大小为N的线程池上存在N个阻塞的写请求会发生什么。稍后你需要考虑这个问题，但现在，您的重点是从读操作中移除锁。

与Mutex和RwLock不同，并没有一种封装类型可以应用于整个任意共享状态，以实现同时读取和写入的目标（至少不能同时还具有高性能）。

这意味着我们需要考虑如何使用SharedKvStore的每个字段，选择正确的同步方案以允许执行尽可能多的线程，并能够继续保持数据的逻辑一致性。

这就是多线程真正困难的地方。如果你移除那个大锁，Rust仍然会保护您免受数据竞争的影响，但它并不能帮助您保持数据的逻辑一致性。

所以在考虑解决方案之前，让我们考虑一下我们的需求。我们要：

同时在多个线程上读取内存索引和磁盘日志；
将命令写入磁盘，同时维护内存索引；
读与写并行，因此：
一般来说，为了保证读与写并发时总是能够读到一致的状态，这意味着：
- 维护一个不变量，使其实在指向日志中的一个有效命令；
- 维护一些适当的不变量以供其他的记录行为使用，比如为了下例uncompacted的记录；
定期压缩磁盘数据，同时为读操作维护不变量；

本节的其余部分是对有助于实现上述目标的各种背景知识的介绍，也这是项目的最终目标：修改KvStore以同时执行读取和写入。

示例数据结构的解释

为了更具体的讨论，我们将需要一个示例，以展示应受保护的数据和应被维护的不变量。下面是一个KvStore实现及其字段的示例：

pub struct KvStore {
    /// Directory for the log and other data
    path: PathBuf,
    /// The log reader
    reader: BufReaderWithPos<File>,
    /// The log writer
    writer: BufWriterWithPos<File>,
    /// The in-memory index from key to log pointer
    index: BTreeMap<String, CommandPos>,
    /// The number of bytes representing "stale" commands that could be
    /// deleted during a compaction
    uncompacted: u64,
}

这是本项目示例的简化版本。

各字段的作用非常明确：

path：PathBuf只是日志的目录路径，永远不会改变 — 它是不可变的，不可变的类型在Rust中是同步的，所以它甚至根本不需要任何保护。它可以被任何线程通过共享引用同时读取。

reader：HashMap<u64, BufReaderWithPos<File>>是当前日志文件的读句柄。它是可变的，即压缩后会指向新的日志文件。

writer：BufWriterWithPos<File>是当前日志文件的写句柄。任何写入都需要对writer的可变访问，并且压缩过程需要修改writer和current_gen。

index：BTreeMap<String, CommandPos>是数据库中每个键到其所在日志文件中具体位置的内存索引。它从可以从每个读线程读取，从每个写线程写入，即使在压缩期间也能正常访问。

uncompacted：u64仅用于计算日志中已被后续写入命令取代的“陈旧”命令的总长度，用以触发日志压缩操作。

在以前的项目中，我们不必担心写、读和压缩之间的交叉会产生不一致的结果，因为它们都发生在同一个线程上。现在，如果您对数据结构的选择和使用不够小心，很容易破坏数据库的状态。

消除锁的策略

高级并行编程的关键是了解可用的工具以及使用它们的时机。以下是我们在实施此项目时发现的一些有用的技术，其中一些您也将用到。这些技术将以上面的数据结构为例进行讲解。

理解并维护顺序一致性

（请注意，“顺序一致性”一词有其准确含义，但在这里我们只是概括性地讨论如何确保以特定顺序执行作业）。

理解并行编程的关键在于理解代码各部分的“执行顺序”间的关系。在这个线程中，要让本线程早于其他线程看到数据，共享数据结构需要怎样改动？要让本线程早于其他线程暴露内部数据，共享数据结构需要怎样改动？我如何保证执行结果？

在单线程代码中，推断出任意行代码之前发生了什么很简单 — 如果代码写在前面，则会在前面执行，反之则会在后面执行。但这实际上并不是这样，即使在单线程代码中：为了使代码更高效的运行，CPU和编译器都会重新组织代码执行的顺序，只不过CPU使用器机码，编译器使用用以生成机器码的内部编码。实际上的代码执行顺序跟您编写代码的顺序并不相同，代码只是看起来在按您编写的顺序运行，因为CPU和编译器都会跟踪数据依赖，它们并不会打乱依赖顺序重新排列操作。

在多线程代码中，CPU和编译器仍使用与单线程相同的条件重新排序代码，而且您的代码块会被打碎重排，除非您使用同步类型和操作告诉编译器不允许重新排序。

任何必须在特定操作之前或之后发生的操作，都必须显式使用同步类型或操作，如使用锁、原子类型等等。

在上面的例子中，文件写入和内存索引写入显然应以特定的顺序发生 — 如果索引在文件更新前更新会发生什么？另外，例子中包含另一个状态，即未压缩命令的总长度uncompacted。错误的计算未压缩命令的长度将产生什么影响？如果在将数据写入文件之前就可以看到uncompacted发生了变化可能还好，但是必须为每个这样的独立同步值制定策略。

确定不可变值

你可能已经了解了很多关于Rust中的不可变性，以及不可变值如何轻松的在线程间共享（它们具有Sync trait）。不可变值最适合并发 — 只需将它们放在Arc后面即可。

在本例中，PathBuf是不可变的。

复制值而不是复制共享

在Rust中我们可能不太喜欢克隆，特别是克隆大小不确定的类型，如String和Vec。但是克隆的存在是完全合理的：在某些情况下避免克隆可能非常困难，而且CPU也非常擅长复制内存缓冲区。此外，在本例中，服务端所需的状态副本的数量，实际上受线程池中线程数量的限制。

在本例中，PathBuf也很容易克隆。

考虑一个潜在问题，如何跨线程共享对文件的访问。File类型对读和写操作均需要可变访问。因此，其跨线程共享需要使用锁以授权可变访问。那么，什么是文件？它并不是一份实际上的文件 — 而只是磁盘上物理资源的句柄，一个文件同时存在多个打开句柄是可以的。注意File的API — 并没有实现Clone，虽然它确实有个诱人的try_clone方法，它的语义对多线程代码会产生复杂的影响，如seek原文件的位置会同步到try_clone创建的另一个文件。请考虑File::open和try_clone中文件之间的区别。使用try_clone还是File::open，将是您的选择。查看pread可能会有所帮助。

按角色分解数据结构

在例子中，我们有两个明确的角色：读和写（也许还有第三个用于压缩）。将读逻辑和写逻辑分离并各封装为一个并发类型在Rust中很常见。读逻辑有自己的数据集，写逻辑也一样，这就为封装提供了很好的条件，所有读操作划为一种类型，而所有写操作划为另一种类型。

这种划分将进一步使两者都访问哪些资源变得非常明显，因为读类型和写类型都将包含这些资源的共享句柄。

使用专门的并发数据结构

知道哪些工具可用以及该在哪些场景中使用可能是并行编程中最困难的部分。除了学校里教的基础锁类型，同步数据类型也变得越来越专业化。

在本项目中，由于内存索引是某种类型的关联数据结构（也称为“映射”），如树或哈希表，那么我们自然会想到是否存在并发关联数据结构。

确实存在，且正确的使用这些数据结构是完成本项目的关键。

但是怎么才能找到这些类型呢？第一步是确定是否存在并发映射。您可以阅读Rust Discord上的#beginners部分，但对于本项目，在网络上搜"concurrent map"即可。

这是容易的部分，在Rust中找到正确的并发映射类型则更困难。比较好的起手式是访问libs.rs。libs.rs与crates.io类似，但crates.io包含所有已发布的库，而libs.rs仅包含受到……好吧，某些人好评的库。因此，如果一个库在libs.rs上，就是库可用的一个指示，另一个是crates.io上的下载计数 — 通常，下载越多的crates被测试的越细。下载计数可以粗略的看作是“担保”库的人数。最后，在聊天中提问也是一个好主意。

将清理延后

像克隆一样，垃圾收集在Rust中经常遭到反对 — 避免GC几乎就是Rust存的意义。但实际上垃圾收集是不可避免的，“垃圾收集”和“内存回收”实际上是同义词，各种语言都复合使用了多种垃圾收集策略。GC策略轴的一端，在没有自动内存管理的语言（如C）中，垃圾收集完全由程序员决定，如使用malloc和free。另一端则是垃圾收集语言，如 Java，所有内存都由一个通用垃圾收集器管理。

但实际上，在C中并不是所有内存的管理和回收都使用malloc/free，在Java也并不是所有内存管理都通过GC完成。举个简单的例子，两者中的高性能应用程序通常都依赖于专门的内存区域，在这些区域既可以重用内存也可以大量解除分配，以优化其内存访问模式。

同样在Rust中，并非所有内存都被显式地释放。比如在Rc和Arc类型中实现了资源计数，也算算算一种简单的GC。

全局垃圾收集器的最大好处之一，就是使许多无锁数据结构成为可能。学术文献中描述的许多无锁数据结构都依赖于GC执行。crossbeam库及其epoch类型的出现，就是在不依赖GC的情况下实现无锁算法。

也就是说垃圾收集有多种形式，其“将资源清理延迟到未来某个时间”的基本策略在许多场景中都很强大。

当您现在不知道如何执行一些并发工作时，可以试着考虑：“可以稍后再做吗？”。

与原子类型共享标志和计数器

在底层，大多数并发数据结构都是使用原子操作或“原子类型”实现的。原子类型在单个内存单元上运行，一般在8到128个字节之间，通常是字长（与指针的字节数相同，并且与Rustusize类型大小相同）。如果两个线程正确使用原子类型，则一个线程中的写入结果将立即对另一个线程中的读取可见。除了使读取或写入立即可见之外，在Rust中，原子操作还通过Ordering标志限制编译器和CPU重新排序指令的方式。

当从粗粒度并行中的锁，转向更细粒度的并行时，通常需要使用原子类型来增强现成的并发数据结构。

实现无锁读

以上就是相关的背景知识。希望这些知识已经开始引导您考虑了很多东西，并朝着正确的方向前进了。现在轮到实现了：

修改KvStore以同时执行读取和写入。

use std::cell::RefCell;
use std::collections::BTreeMap;
use std::fs::{self, File, OpenOptions};
use std::io::{self, BufReader, BufWriter, Read, Seek, SeekFrom, Write};
use std::ops::Range;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};

use crossbeam_skiplist::SkipMap;
use log::error;
use serde::{Deserialize, Serialize};
use serde_json::Deserializer;
use crate::{KvsError, Result, KvsEngine};
use std::ffi::OsStr;

const COMPACTION_THRESHOLD: u64 = 1024 * 1024;

/// The `KvStore` stores string key/value pairs.
///
/// Key/value pairs are persisted to disk in log files. Log files are named after
/// monotonically increasing generation numbers with a `log` extension name.
/// A `BTreeMap` in memory stores the keys and the value locations for fast query.
///
/// ```rust
/// # use kvs::{KvStore, Result};
/// # fn try_main() -> Result<()> {
/// use std::env::current_dir;
/// use kvs::KvsEngine;
/// let mut store = KvStore::open(current_dir()?)?;
/// store.set("key".to_owned(), "value".to_owned())?;
/// let val = store.get("key".to_owned())?;
/// assert_eq!(val, Some("value".to_owned()));
/// # Ok(())
/// # }
/// ```
#[derive(Clone)]
pub struct KvStore {
    // map generation number to the file reader
    index: Arc<SkipMap<String, CommandPos>>,
    reader: KvStoreReader,
    // writer of the current log.
    writer: Arc<Mutex<KvStoreWriter>>,
    // the number of bytes representing "stale" commands that could be
    // deleted during a compaction.
}

impl KvStore {
    /// Opens a `KvStore` with the given path.
    ///
    /// This will create a new directory if the given one does not exist.
    ///
    /// # Errors
    ///
    /// It propagates I/O or deserialization errors during the log replay.
    pub fn open(path: impl Into<PathBuf>) -> Result<KvStore> {
        let path = Arc::new(path.into());
        fs::create_dir_all(&*path)?;

        let mut readers = BTreeMap::new();
        let index = Arc::new(SkipMap::new());

        let gen_list = sorted_gen_list(&path)?;
        let mut uncompacted = 0;

        for &gen in &gen_list {
            let mut reader = BufReaderWithPos::new(File::open(log_path(&path, gen))?)?;
            uncompacted += load(gen, &mut reader, &*index)?;
            readers.insert(gen, reader);
        }

        let current_gen = gen_list.last().unwrap_or(&0) + 1;
        let writer = new_log_file(&path, current_gen)?;
        let safe_point = Arc::new(AtomicU64::new(0));

        let reader = KvStoreReader { 
            path: Arc::clone(&path), 
            safe_point,
            readers: RefCell::new(readers),
        };

        let writer = KvStoreWriter {
            reader: reader.clone(),
            writer,
            current_gen, 
            uncompacted,
            path: Arc::clone(&path),
            index: Arc::clone(&index),
        };

        Ok(KvStore {
            reader,
            index,
            writer: Arc::new(Mutex::new(writer)),
        })
    }
}

impl KvsEngine for KvStore {
    /// Sets the value of a string key to a string.
    ///
    /// If the key already exists, the previous value will be overwritten.
    ///
    /// # Errors
    ///
    /// It propagates I/O or serialization errors during writing the log.
    fn set(&self, key: String, value: String) -> Result<()> {
        self.writer.lock().unwrap().set(key, value)
    }

    /// Gets the string value of a given string key.
    ///
    /// Returns `None` if the given key does not exist.
    ///
    /// # Errors
    ///
    /// It returns `KvsError::UnexpectedCommandType` if the given command type unexpected.
    fn get(&self, key: String) -> Result<Option<String>> {
        if let Some(cmd_pos) = self.index.get(&key) {
            if let Command::Set { value, .. } = self.reader.read_command(*cmd_pos.value())? {
                Ok(Some(value))
            } else {
                Err(KvsError::UnexpectedCommandType)
            }
        } else {
            Ok(None)
        }
    }

    /// Removes a given key.
    ///
    /// # Errors
    ///
    /// It returns `KvsError::KeyNotFound` if the given key is not found.
    ///
    /// It propagates I/O or serialization errors during writing the log.
    fn remove(&self, key: String) -> Result<()> {
        self.writer.lock().unwrap().remove(key)
    }

}

/// A single thread reader. 
/// 
/// Each `KvStore` instance has its own `KvStoreReader` and 
/// `KvStoreReader`s open the same file separately. So the user 
/// can read concurrently through multiple `KvStore`s in different 
/// threads.
struct KvStoreReader {
    path: Arc<PathBuf>,
    // generation of the latest compaction file
    safe_point: Arc<AtomicU64>,
    readers: RefCell<BTreeMap<u64, BufReaderWithPos<File>>>,
}

impl KvStoreReader {
    /// Close file handles with generation number less than safe_point.
    /// 
    /// `safe_point` is updated to the latest compaction gen after a compaction finished.
    /// The compaction generation contains the sum of all operations before it and the 
    /// in-memory index contains no entries with generation number less than safe_point.
    /// So we can safely close those file handles and the stales file can be deleted.
    fn close_stale_handles(&self) {
        let mut readers = self.readers.borrow_mut();
        while !readers.is_empty() {
            let first_gen = *readers.keys().next().unwrap();
            if self.safe_point.load(Ordering::SeqCst) <= first_gen {
                break;
            }
            readers.remove(&first_gen);
        }
    }

    /// Read the log file at the given `CommandPos`.
    fn read_and<F, R>(&self, cmd_pos: CommandPos, f: F) -> Result<R>
    where
        F: FnOnce(io::Take<&mut BufReaderWithPos<File>>) -> Result<R>,
    {
        self.close_stale_handles();

        let mut readers = self.readers.borrow_mut();
        // Open the file if we haven't open it in this `KvStoreReader`.
        // We don't use entry API here because we want the errors to be propogated.
        if !readers.contains_key(&cmd_pos.gen) {
            let reader = BufReaderWithPos::new(File::open(log_path(&self.path, cmd_pos.gen))?)?;
            readers.insert(cmd_pos.gen, reader);
        }
        let reader = readers.get_mut(&cmd_pos.gen).unwrap();
        reader.seek(SeekFrom::Start(cmd_pos.pos))?;
        let cmd_reader = reader.take(cmd_pos.len);
        f(cmd_reader)
    }

    // Read the log file at the given `CommandPos` and deserialize it to `Command`.
    fn read_command(&self, cmd_pos: CommandPos) -> Result<Command> {
        self.read_and(cmd_pos, |cmd_reader| {
            Ok(serde_json::from_reader(cmd_reader)?)
        })
    }
}

impl Clone for KvStoreReader {
    fn clone(&self) -> Self {
        KvStoreReader { 
            path: Arc::clone(&self.path), 
            safe_point: Arc::clone(&self.safe_point), 
            // don't use other KvStoreReader's readers
            readers: RefCell::new(BTreeMap::new()), 
        }
    }
}

struct KvStoreWriter {
    reader: KvStoreReader,
    writer: BufWriterWithPos<File>,
    current_gen: u64,
    // the number of bytes representing "stale" commands that could be
    // delete during a compaction
    uncompacted: u64,
    path: Arc<PathBuf>,
    index: Arc<SkipMap<String, CommandPos>>
}

impl KvStoreWriter {
    fn set(&mut self, key: String, value: String) -> Result<()>{
        let cmd = Command::set(key, value);
        let pos = self.writer.pos;
        serde_json::to_writer(&mut self.writer, &cmd)?;
        self.writer.flush()?;
        if let Command::Set { key, .. } = cmd {
            if let Some(old_cmd) = self.index.get(&key) {
                self.uncompacted += old_cmd.value().len;
            }
            self.index
                .insert(key, (self.current_gen, pos..self.writer.pos).into());
        }

        if self.uncompacted > COMPACTION_THRESHOLD {
            self.compact()?;
        }
        Ok(())
    }

    fn remove(&mut self, key: String) -> Result<()> {
        if self.index.contains_key(&key) {
            let cmd = Command::remove(key);
            let pos = self.writer.pos;
            serde_json::to_writer(&mut self.writer, &cmd)?;
            self.writer.flush()?;
            if let Command::Remove { key } = cmd {
                let old_cmd = self.index.remove(&key).expect("key not found");
                self.uncompacted += old_cmd.value().len;
                // the "remove" command itself can be deleted in the next compaction
                // so we add it's length to `uncompacted`
                self.uncompacted += self.writer.pos - pos;
            }

            if self.uncompacted > COMPACTION_THRESHOLD {
                self.compact()?;
            }
            Ok(())
        } else {
            Err(KvsError::KeyNotFound)
        }
    }

    /// Clear stale entries in log.
    fn compact(&mut self) -> Result<()> {
        // increase current gen by 2. current_gen + 1 is for compaction file
        let compaction_gen  = self.current_gen + 1;
        self.current_gen += 2;
        self.writer = new_log_file(&self.path, self.current_gen)?;

        let mut compaction_writer = new_log_file(&self.path, compaction_gen)?;

        let mut new_pos = 0;
        for entry in self.index.iter() {
            let len = self.reader.read_and(*entry.value(), |mut entry_reader| {
                Ok(io::copy(&mut entry_reader, &mut compaction_writer)?)
            })?;
            self.index.insert(
                entry.key().clone(),
                (compaction_gen, new_pos..new_pos+len).into(),
            );
            new_pos += len;
        }
        compaction_writer.flush()?;

        self.reader
            .safe_point
            .store(compaction_gen, Ordering::SeqCst);
        self.reader.close_stale_handles();

        // remove stale log files.
        // Note that actually these files are not deleted immediately because `KvStoreReader`s
        // still keep open file handles. When `KvStoreReader` is used next time, it will clear
        // its stale file handles. On Unix, the files will be deleted after all the handles
        // are closed. On Windows, the deletions below will fail and stale files are expected
        // to be deleted in the next compaction.
        let stale_gens = sorted_gen_list(&self.path)?
            .into_iter()
            .filter(|&gen| gen < compaction_gen);
        for stale_gen in stale_gens {
            let file_path = log_path(&self.path, stale_gen);
            if let Err(e) = fs::remove_file(&file_path) {
                error!("{:?} cannot be deleted: {}", file_path, e);
            }
        }
        self.uncompacted = 0;

        Ok(())
    }

}
/// Create a new log file with given generation number.
///
/// Returns the writer to the log.
fn new_log_file(path: &Path, gen: u64) -> Result<BufWriterWithPos<File>> {
    let path = log_path(&path, gen);
    let writer = BufWriterWithPos::new(
        OpenOptions::new()
            .create(true)
            .write(true)
            .append(true)
            .open(&path)?,
    )?;
    Ok(writer)
}

/// Returns sorted generation numbers in the given directory.
fn sorted_gen_list(path: &Path) -> Result<Vec<u64>> {
    let mut gen_list: Vec<u64> = fs::read_dir(&path)?
        .flat_map(|res| -> Result<_> { Ok(res?.path()) })
        .filter(|path| path.is_file() && path.extension() == Some("log".as_ref()))
        .flat_map(|path| {
            path.file_name()
                .and_then(OsStr::to_str)
                .map(|s| s.trim_end_matches(".log"))
                .map(str::parse::<u64>)
        })
        .flatten()
        .collect();
    gen_list.sort_unstable();
    Ok(gen_list)
}

/// Load the whole log file and store value locations in the index map.
///
/// Returns how many bytes can be saved after a compaction.
fn load(
    gen: u64,
    reader: &mut BufReaderWithPos<File>,
    index: &SkipMap<String, CommandPos>,
) -> Result<u64> {
    // To make sure we read from the beginning of the file.
    let mut pos = reader.seek(SeekFrom::Start(0))?;
    let mut stream = Deserializer::from_reader(reader).into_iter::<Command>();
    let mut uncompacted = 0; // number of bytes that can be saved after a compaction.
    while let Some(cmd) = stream.next() {
        let new_pos = stream.byte_offset() as u64;
        match cmd? {
            Command::Set { key, .. } => {
                if let Some(old_cmd) = index.get(&key) {
                    uncompacted += old_cmd.value().len;
                }
                index.insert(key, (gen, pos..new_pos).into());
            }
            Command::Remove { key } => {
                if let Some(old_cmd) = index.remove(&key) {
                    uncompacted += old_cmd.value().len;
                }
                // the "remove" command itself can be deleted in the next compaction
                // so we add its length to `uncompacted`
                uncompacted += new_pos - pos;
            }
        }
        pos = new_pos;
    }
    Ok(uncompacted)
}

fn log_path(dir: &Path, gen: u64) -> PathBuf {
    dir.join(format!("{}.log", gen))
}

/// Struct representing a command.
#[derive(Serialize, Deserialize, Debug)]
enum Command {
    Set { key: String, value: String },
    Remove { key: String },
}

impl Command {
    fn set(key: String, value: String) -> Command {
        Command::Set { key, value }
    }

    fn remove(key: String) -> Command {
        Command::Remove { key }
    }
}

#[derive(Debug, Clone, Copy)]
/// Represents the position and length of a json-serialized command in the log.
struct CommandPos {
    gen: u64,
    pos: u64,
    len: u64,
}

impl From<(u64, Range<u64>)> for CommandPos {
    fn from((gen, range): (u64, Range<u64>)) -> Self {
        CommandPos {
            gen,
            pos: range.start,
            len: range.end - range.start,
        }
    }
}

struct BufReaderWithPos<R: Read + Seek> {
    reader: BufReader<R>,
    pos: u64,
}

impl<R: Read + Seek> BufReaderWithPos<R> {
    fn new(mut inner: R) -> Result<Self> {
        let pos = inner.seek(SeekFrom::Current(0))?;
        Ok(BufReaderWithPos {
            reader: BufReader::new(inner),
            pos,
        })
    }
}

impl<R: Read + Seek> Read for BufReaderWithPos<R> {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        let len = self.reader.read(buf)?;
        self.pos += len as u64;
        Ok(len)
    }
}

impl<R: Read + Seek> Seek for BufReaderWithPos<R> {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.pos = self.reader.seek(pos)?;
        Ok(self.pos)
    }
}

struct BufWriterWithPos<W: Write + Seek> {
    writer: BufWriter<W>,
    pos: u64,
}

impl<W: Write + Seek> BufWriterWithPos<W> {
    fn new(mut inner: W) -> Result<Self> {
        let pos = inner.seek(SeekFrom::Current(0))?;
        Ok(BufWriterWithPos {
            writer: BufWriter::new(inner),
            pos,
        })
    }
}

impl<W: Write + Seek> Write for BufWriterWithPos<W> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        let len = self.writer.write(buf)?;
        self.pos += len as u64;
        Ok(len)
    }

    fn flush(&mut self) -> io::Result<()> {
        self.writer.flush()
    }
}

impl<W: Write + Seek> Seek for BufWriterWithPos<W> {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.pos = self.writer.seek(pos)?;
        Ok(self.pos)
    }
}

干得漂亮，朋友。休息一下吧。

PingCap的Rust训练课程3：同步的“客户端-服务端”网络模块

Tue, 10 May 2022 20:40:00 GMT

:::warning 本文内容大多翻译自原文：PNA Rust Project 3: Synchronous client-server networking。 :::

前言

任务：创建一个单线程、持久化的键/值存储的服务器和客户端，使用自定义协议进行同步联网。

目标：

创建一个客户端-服务器应用程序
用std库的网络API编写自定义协议
为服务端引入日志记录功能
用trait实现可插拔的后端
用sled对手写的后端进行基准测试 关键词：std::net、日志、trait、基准测试。

介绍

在这个项目中，你将创建一个简单的键/值存储服务端和客户端，它们将用你自定义的网络协议进行通信。你将使用标准的日志crate生成日志，并正确处理网络边界上的错误。一旦有了一个可运行的客户端-服务端架构，那么你就能够抽象出trait背后的存储引擎，并将你的实现与sled引擎进行性能比较。

项目需求规格

kvs-server可执行文件支持以下命令行参数：

kvs-server [--addr IP-PORT] [--engine ENGINE-NAME]

启动服务端并开始监听进入的连接。--addr接受一个IP地址（可以是v4或v6）以及一个端口号，格式为IP:PORT。如果没有指定--addr，则默认监听127.0.0.1:4000。

如果指定了--engine，那么ENGINE-NAME必须是"kvs"（即使用内置引擎），或者是"sled"（即使用sled引擎）。如果这是首次运行程序（没有以前保存的数据），那么默认值是"kvs"；如果以前有保存的数据，那么默认使用已经在用的引擎。如果以前保存的数据与当前选择的引擎不同，则打印一个错误并以非零的退出码退出。

如果套接字绑定失败，或ENGINE-NAME无效，或IP-PORT不能解析为一个地址，则打印一个错误并以非零的退出码退出。
kvs-server -V

打印版本信息。

kvs-client可执行文件支持以下命令行参数：

kvs-client set <KEY> <VALUE> [--addr IP-PORT]

将一个字符串键的值设置为一个字符串。

--addr接受一个IP地址（可以是v4或v6）以及一个端口号，格式为IP:PORT。如果没有指定--addr，则在默认127.0.0.1:4000上连接。

如果服务器出错，或者IP-PORT不能解析为一个地址，则打印错误并以非零的退出码退出。
kvs-client get <KEY> [--addr IP-PORT]

获取一个给定的字符串键的字符串值。

--addr接受一个IP地址（可以是v4或v6）以及一个端口号，格式为IP:PORT。如果没有指定--addr，则在默认127.0.0.1:4000上连接。

如果服务器出错，或者IP-PORT不能解析为一个地址，则打印错误并以非零的退出码退出。
kvs-client rm <KEY> [--addr IP-PORT]

删除一个给定的字符串键。

--addr接受一个IP地址（可以是v4或v6）以及一个端口号，格式为IP:PORT。如果没有指定--addr，则在默认127.0.0.1:4000上连接。

如果服务器出错，或者IP-PORT不能解析为一个地址，则打印错误并以非零的退出码退出。
kvs-client -V

打印版本信息。

所有错误信息都应打印到stderr。

kvs库包含四种类型。

KvsClient - 为kvs-client实现与kvs-server通信所需的功能。
KvsServer - 为kvs-server实现响应kvs-client请求的功能。
KvsEngine trait - 定义了KvsServer需要调用的存储接口。
KvStore - 手动实现KvsEngine trait
SledKvsEngine - 为sled存储引擎实现KvsEngine trait。

KvsClient和KvsServer的设计由你决定，并将使用你自定义的网络协议来通信。本项目的测试套件并不直接调用这两种类型，而仅是通过CLI测试它们。

KvsEngine trait支持以下方法：

KvsEngine::set(&mut self, key: String, value: String) -> Result<()>

将一个字符串键的值设置为一个字符串。

如果值没有成功写入，则返回错误。
KvsEngine::get(&mut self, key: String) -> Result<Option<String>>

获取一个字符串键的字符串值。如果键不存在，返回None。

如果没有成功读取该值，则返回错误。
KvsEngine::remove(&mut self, key: String) -> Result<()>

删除一个给定的字符串键。

如果键不存在或值未被成功读取，则返回错误。

当为一个键设置值时，KvStore会把set命令写入磁盘的顺序日志。当删除一个键时，KvStore将rm命令写入日志。在启动时，日志中的命令将被重新求值，各键的最新一条设置命令的日志指针（文件偏移量）将会被保存在内存索引中。

当用get命令检索一个键的值时，它会搜索索引，如果找到了，就从日志的相应位置中加载相应命令并求值。

当未压缩的日志条目的大小达到一个给定的阈值时，KvStore将其压缩成一个新的日志，删除多余的条目以释放磁盘空间。

项目设置

继续你以前的项目，删除你以前的tests目录，把这本项目的tests目录复制到它的位置。这个项目应该包含一个名为kvs的库，以及两个可执行文件，kvs-server和kvs-client。

你需要在Cargo.toml中加入以下dev-dependencies依赖：

[dev-dependencies]
assert_cmd = "0.11"
criterion = "0.3"
predicates = "1.0.0"
rand = "0.6.5"
tempfile = "3.0.7"
walkdir = "2.2.7"

与以前的项目一样，添加足够的定义，以构建测试套件。

使测试套件编译通过只需要：

按上文要求在lib.rs中添加一个新模块mod engines；
创建新模块engines\mod.rs；
在新模块mod.rs中按要求加入KvsEngine trait的定义即可。
在lib.rs中公开引用这个trait即可：pub use engines::KvsEngine;

目录结构为：

.
├── Cargo.toml
├── src
│  ├── bin
│  │  └── kvs.rs
│  ├── engines
│  │  └── mod.rs
│  ├── error.rs
│  ├── kv.rs
│  └── lib.rs
└── tests
   ├── cli.rs
   └── kv_store.rs

目前cli.rs中的11个测试均未通过：

cargo test --test cli
...
running 11 tests
test cli_log_configuration ... FAILED
test cli_access_server_kvs_engine ... FAILED
test cli_wrong_engine ... FAILED
test client_cli_invalid_get ... FAILED
test client_cli_invalid_rm ... FAILED
test client_cli_invalid_set ... FAILED
test cli_access_server_sled_engine ... FAILED
test client_cli_invalid_subcommand ... FAILED
test client_cli_version ... FAILED
test server_cli_version ... FAILED
test client_cli_no_args ... FAILED
...

kv_store.rs中的均通过测试：

cargo test --test kv_store
running 6 tests
test remove_non_existent_key ... ok
test remove_key ... ok
test get_stored_value ... ok
test get_non_existent_value ... ok
test overwrite_value ... ok
test compaction ... ok

第1部分：解析命令行

本项目中的命令行解析同之前的项目相比没有多少新功能。kvs-client二进制文件接受与之前项目相同的命令行参数。而kvs-server有一组自己的命令行参数需要处理，就像上文描述的那样。

处理kvs-server的命令行参数。

kvs-server的参数比较简单，依然使用clap的derive特性编写，由于Rust已经为&str实现了ToSocketAddrs特性，Args中直接使用SocketAddr类型会自动触发字符串到IP地址的转换：

use clap::{Parser};
use kvs::{Result};
use std::net::SocketAddr;

const DEFAULT_LISTENING_ADDRESS: &str = "127.0.0.1:4000";
const DEFAULT_ENGINE: Engine = Engine::kvs;

#[allow(non_camel_case_types)]
#[derive(clap::ArgEnum, Clone, Debug)]
enum Engine {
   kvs,
   sled,
}

impl FromStr for Engine {
    type Err = KvsError;

    fn from_str(s: &str) -> Result<Self> {
        match s {
            "kvs" => {
                Ok(Engine::kvs)
            },
            "sled" => {
                Ok(Engine::sled)
            }
            _ => {
                Err(KvsError::UnexpectedEngineType)
            }
        }
    }
}

#[derive(Parser, Debug)]
#[clap(name = "kvs-server")]
#[clap(author, version, about="server of key value storage", long_about=None)]
struct Args {
    /// [IPADDR:PORT] of server.
    #[clap(long, default_value=DEFAULT_LISTENING_ADDRESS)]
    addr: SocketAddr,

    /// backend engine of key value storage.
    #[clap(arg_enum, long, required(false))]
    engine: Option<Engine>,
}


fn main() -> Result<()> {
    let args = Args::parse();
    println!("{:?} {:?}", args.addr, args.engine);
    
    Ok(())
}

kvs-client需要在子命令后面再添加可选参数（IP地址），所以可以使用clap的builder编写模式增加可读性。当然，也可以继续使用derive特性编写更简略的代码：

// builder模式

use clap::{Command, arg, crate_version};
use kvs::{Result};
use std::net::SocketAddr;

const DEFAULT_LISTENING_ADDRESS: &str = "127.0.0.1:4000";

fn cli() -> Command<'static> {
    Command::new("kvs-client")
        .about("client of key value storage")
        .version(crate_version!())
        .subcommand_required(true)
        .disable_help_subcommand(true)
        .args_conflicts_with_subcommands(true)
        .subcommand(
            Command::new("get")
                .about("Get the string value of a given string key")
                .args(&[
                    arg!(<KEY> "A string key"),
                    arg!(--addr <"IP:PORT"> "Set the server address as IP:PORT").required(false).default_value(DEFAULT_LISTENING_ADDRESS)
                ])
        )
        .subcommand(
            Command::new("set")
                .about("Set the value of a string key to a string")
                .args(&[
                    arg!(<KEY> "A string key"),
                    arg!(<VALUE> "The string value of the key").required(true),
                    arg!(--addr <"IP:PORT"> "Set the server address as IP:PORT").required(false).default_value(DEFAULT_LISTENING_ADDRESS) 
                ])
        )
        .subcommand(
            Command::new("rm")
                .about("Remove a given string key")
                .args(&[
                    arg!(<KEY> "A string key"),
                    arg!(--addr <"IP:PORT"> "Set the server address as IP:PORT").required(false).default_value(DEFAULT_LISTENING_ADDRESS)                
                ])
        )
}

fn main() -> Result<()>{
    let matches = cli().get_matches();

    match matches.subcommand() {
        Some(("get", sub_matches)) => {
            println!("get {} {}", sub_matches.value_of("KEY").unwrap(), sub_matches.value_of("addr").unwrap());
            let key = sub_matches.value_of("KEY").unwrap();
            let addr: SocketAddr = sub_matches.value_of("addr").unwrap().parse()?;
        },
        Some(("set", sub_matches)) => {
            println!("set {} {} {}", sub_matches.value_of("KEY").unwrap(), sub_matches.value_of("VALUE").unwrap(), sub_matches.value_of("addr").unwrap());
            let key = sub_matches.value_of("KEY").unwrap();
            let value = sub_matches.value_of("VALUE").unwrap();
            let addr: SocketAddr = sub_matches.value_of("addr").unwrap().parse()?;
        }
        Some(("rm", sub_matches)) => {
            println!("rm {} {}", sub_matches.value_of("KEY").unwrap(), sub_matches.value_of("addr").unwrap());
            let key = sub_matches.value_of("KEY").unwrap();
            let addr: SocketAddr = sub_matches.value_of("addr").unwrap().parse()?;
        },

        _ => unreachable!(), // If all subcommands are defined above, anything else is unreachabe!()

    }

    Ok(())
}

// derive模式

use clap::{Parser, Subcommand};
use kvs::{KvStore, Result};
use std::process::exit;
use std::env::current_dir;
use std::net::SocketAddr;

const DEFAULT_LISTENING_ADDRESS: &str = "127.0.0.1:4000";

#[derive(Parser)]
#[clap(name = "kvs")]
#[clap(author, version, about="an in-memory key/value store", long_about=None, args_conflicts_with_subcommands(true))]
struct Cli {
    #[clap(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    // Set the value of a string key to a string
    #[clap(arg_required_else_help = true)]
    set {
        // A string key
        key: String,
        // The string value of the key
        value: String,
        #[clap(long, required(false), default_value(DEFAULT_LISTENING_ADDRESS), help="Set the server address as [IP:PORT]")]
        addr: SocketAddr
    }, 

    // Get the string value of a given string key
    #[clap(arg_required_else_help = true)]
    get {
        // A string key
        key: String,
        #[clap(long, required(false), default_value(DEFAULT_LISTENING_ADDRESS), help="Set the server address as [IP:PORT]")]
        addr: SocketAddr
    }, 

    // Remove a given key
    #[clap(arg_required_else_help = true)]
    rm {
        // A string key
        key: String,
        #[clap(long, required(false), default_value(DEFAULT_LISTENING_ADDRESS), help="Set the server address as [IP:PORT]")]
        addr: SocketAddr
    },
}

fn main() -> Result<()> {
    let cli= Cli::parse();
    match cli.command {
        Commands::get { key, addr } => {}, 
        Commands::set { key, value, addr } => {},
        Commands::rm { key, addr } => {},
    }

    Ok(())
}

第2部分：日志记录

生产环境下的服务器应用程序应具有功能强大且可配置的日志记录。因此，现在我们应为kvs-server添加日志功能，并在后续功能实现的过程中记录有用的信息。在开发过程中，通常使用debug!和trace!级日志来打印调试信息。

Rust中有两个好用的日志系统：log和slog。两者均为不同级别的日志输出类似的宏，如error!、info!等。两者都是可扩展的，支持不同的后端，以输出日志到控制台、日志文件或系统日志等。

最主要的区别是，log相当简单，只记录格式化的字符串；slog功能丰富，支持“结构化日志”，其日志条目是以容易解析的格式类型化和序列化的。

log可以追溯到Rust最早的时候，它是编译器的一部分，然后是标准库的一部分，最后作为独立的crate发布。它由Rust项目组维护。slog是较新的crate，独立维护。两者均已被广泛使用。

对于这两种系统，都需要选择一个“接收器”crate，用于将日志发送到该接收器以进行显示或存储。

阅读这两个系统，选择一个对你喜欢的，将它们作为依赖项添加，然后修改kvs-server以在传递命令行参数之前初始化日志。将日志设置为输出到stderr（将日志发送到其他地方也可以，但日志必须也发送到stderr以通过本项目的测试）。

在启动时日志记录服务器端的版本信息，还要记录配置信息。目前指的是IP地址和端口，以及存储引擎的名称。

因为第一次使用日志功能，还是先用简单的log入门，在Cargo.toml里引入log和env_logger（用于配置日志）。然后按要求输出日志即可：

// ...
fn main() -> Result<()> {
    env_logger::builder().filter_level(LevelFilter::Debug).init();
    let mut args = Args::parse();
//...
    run(args)
}

fn run(args: Args) -> Result<()> {
    let engine = args.engine.unwrap_or(DEFAULT_ENGINE);
    info!("kvs-server {}", env!("CARGO_PKG_VERSION"));
    info!("Storage engine: {:?}", engine);
    info!("Listening on {}", args.addr);
// ...
}
// ...

第3部分：客户端-服务端网络设置

接下来，我们将搭建网络模块。对于本项目，您将使用std::net中使用最基础的TCP/IP网络API：TcpListener和TcpStream。

对于本项目，服务器是同步、单线程的。这意味着您将监听一个socket，接受一个连接，然后一次执行/响应一条命令。在未来，我们将在实现异步、多线程和高性能数据库的过程中，多次重新回味这一设定。

考虑一下您的手动测试工作流程。现在有两个可执行文件要处理，您需要一种同时运行它们的方法。您可能和我们一样，同时使用两个终端，一个运行cargo run --bin kvs-server ，服务端将一直运行到你按下CTRL-D；另一个运行cargo run --bin kvs-client。

这是使用日志进行调试的好机会。继续记录有关每个已接受连接的信息。

在考虑协议之前，先修改kvs-server来监听和接受连接，在修改kvs-client来发起连接。

是时候把KvStore变成真正的KV引擎了，把为KvStore实现的get、set、remove拿出来，用于为KvStore实现KvsEngine特性：

//...
impl KvsEngine for KvStore {
//...
    fn set(&mut self, key: String, value: String) -> Result<()> {
        let cmd = Command::set(key, value);
        let pos = self.writer.pos;
        serde_json::to_writer(&mut self.writer, &cmd)?;
        self.writer.flush()?;
        if let Command::Set { key, .. } = cmd {
            if let Some(old_cmd) = self
                .index
                .insert(key, (self.current_gen, pos..self.writer.pos).into())
            {
                self.uncompacted += old_cmd.len;
            }
        }

        if self.uncompacted > COMPACTION_THRESHOLD {
            self.compact()?;
        }
        Ok(())
    }
//...
    fn get(&mut self, key: String) -> Result<Option<String>> {
        if let Some(cmd_pos) = self.index.get(&key) {
            let reader = self
                .readers
                .get_mut(&cmd_pos.gen)
                .expect("Cannot find log reader");
            reader.seek(SeekFrom::Start(cmd_pos.pos))?;
            let cmd_reader = reader.take(cmd_pos.len);
            if let Command::Set { value, .. } = serde_json::from_reader(cmd_reader)? {
                Ok(Some(value))
            } else {
                Err(KvsError::UnexpectedCommandType)
            }
        } else {
            Ok(None)
        }
    }
//...
    fn remove(&mut self, key: String) -> Result<()> {
        if self.index.contains_key(&key) {
            let cmd = Command::remove(key);
            serde_json::to_writer(&mut self.writer, &cmd)?;
            self.writer.flush()?;
            if let Command::Remove { key } = cmd {
                let old_cmd = self.index.remove(&key).expect("key not found");
                self.uncompacted += old_cmd.len;
            }
            Ok(())
        } else {
            Err(KvsError::KeyNotFound)
        }
    }

}

在实现客户端-服务端之前，可以先定义用于序列化的枚举类型，作为客户端与服务端之间的通信协议（在后面编写服务端和客户端时，可以方便的将这些支持序列化的类型放在TcpStream上进行读写）：

use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
pub enum Request {
    Get { key: String },
    Set { key: String, value: String },
    Remove { key: String },
}

#[derive(Debug, Serialize, Deserialize)]
pub enum GetResponse {
    Ok(Option<String>),
    Err(String),
}

#[derive(Debug, Serialize, Deserialize)]
pub enum SetResponse {
    Ok(()),
    Err(String),
}

#[derive(Debug, Serialize, Deserialize)]
pub enum RemoveResponse {
    Ok(()),
    Err(String),
}

然后在server.rs中实现KvsServer：

use std::{net::{ToSocketAddrs, TcpListener, TcpStream}, io::{BufReader, BufWriter, Write}};
use log::{error, debug};
use serde_json::Deserializer;
use crate::{KvsEngine, Result, common::{Request, GetResponse, SetResponse, RemoveResponse}};

/// The server of a key value store.
pub struct KvsServer<E: KvsEngine> {
    engine: E,
}

impl<E: KvsEngine> KvsServer<E>  {
    /// Create a `KvsServer` with a given storage engine.
    pub fn new(engine: E) -> Self {
        KvsServer { engine }
    }
    
    /// Run the server listening on the given address
    pub fn run(&mut self, addr: impl ToSocketAddrs) -> Result<()> {
        let listener = TcpListener::bind(addr)?;
        for stream in listener.incoming() {
            match stream {
                Ok(stream) => {
                    if let Err(e) = self.serve(stream) {
                        error!("Error on serving client: {}", e);
                    }
                }
                Err(e) => error!("Connection failed: {}", e),
            }
        }
        Ok(())
    }

    fn serve(&mut self, tcp: TcpStream) -> Result<()> {
        let peer_addr = tcp.peer_addr()?;
        let reader = BufReader::new(&tcp);
        let mut writer = BufWriter::new(&tcp);
        let req_reader = Deserializer::from_reader(reader).into_iter::<Request>();

        macro_rules! send_resp {
            ($resp:expr) => {{
                let resp = $resp;
                serde_json::to_writer(&mut writer, &resp)?;
                writer.flush()?;
                debug!("Response sent to {}: {:?}", peer_addr, resp);
            };};
        }

        for req in req_reader {
            let req = req?;
            debug!("Receive request from {} {:?}", peer_addr, req);
            match req {
                Request::Get { key } => send_resp!(
                    match self.engine.get(key) {
                        Ok(value) => { GetResponse::Ok(value) },
                        Err(e) => { GetResponse::Err(format!("{}", e)) },
                    }
                ),
                Request::Set { key, value } => send_resp!(
                    match self.engine.set(key, value) {
                        Ok(_) => SetResponse::Ok(()),
                        Err(e) => SetResponse::Err(format!("{}", e)),
                    }
                ),
                Request::Remove { key } => send_resp!(
                    match self.engine.remove(key) {
                        Ok(_) => RemoveResponse::Ok(()),
                        Err(e) => RemoveResponse::Err(format!("{}", e)),
                    }
                ),
            }
        }

        Ok(())
    }
}

其中send_resp!宏的作用与下面的代码相同，编写这个宏可以减少重复：

// 使用代码
Request::Get { key } => {
    let resp = match self.engine.get(key) {
        Ok(value) => { GetResponse::Ok(value) },
        Err(e) => { GetResponse::Err(format!("{}", e)) },
    };
    serde_json::to_writer(writer, &resp);
    writer.flush()?;
    debug!("Response sent to {}: {:?}", peer_addr, resp);
},
// 使用宏
macro_rules! send_resp {
    ($resp:expr) => {{
        let resp = $resp;
        serde_json::to_writer(&mut writer, &resp)?;
        writer.flush()?;
        debug!("Response sent to {}: {:?}", peer_addr, resp);
    };};
}

Request::Get { key } => send_resp!(
    match self.engine.get(key) {
        Ok(value) => { GetResponse::Ok(value) },
        Err(e) => { GetResponse::Err(format!("{}", e)) },
    }
),

在kvs-server.rs中使用KvsServer，此时可以将日志等级调整为Debug以方便调试：

use clap::Parser;
use kvs::{Result, KvsError, KvStore, KvsEngine, KvsServer};
use std::env::current_dir;
use std::fs;
use std::net::SocketAddr;
use std::process::exit;
use log::LevelFilter;
use log::{error, info, warn};
use std::str::FromStr;


const DEFAULT_LISTENING_ADDRESS: &str = "127.0.0.1:4000";
const DEFAULT_ENGINE: Engine = Engine::kvs;

#[allow(non_camel_case_types)]
#[derive(clap::ArgEnum, Copy, Clone, Debug, PartialEq, Eq)]
enum Engine {
   kvs,
   sled,
}

impl FromStr for Engine {
    type Err = KvsError;

    fn from_str(s: &str) -> Result<Self> {
        match s {
            "kvs" => {
                Ok(Engine::kvs)
            },
            "sled" => {
                Ok(Engine::sled)
            }
            _ => {
                Err(KvsError::UnexpectedEngineType)
            }
        }
    }
}

#[derive(Parser, Debug)]
#[clap(name = "kvs-server")]
#[clap(author, version, about="server of key value storage", long_about=None)]
struct Args {
    /// [IPADDR:PORT] of server.
    #[clap(long, default_value=DEFAULT_LISTENING_ADDRESS)]
    addr: SocketAddr,

    /// backend engine of key value storage.
    #[clap(arg_enum, long, required(false))]
    engine: Option<Engine>,
}


fn main() -> Result<()>{
    env_logger::builder().filter_level(LevelFilter::Debug).init();
    let mut args = Args::parse();

    let res = current_engine().and_then(move |curr_engine| {
        if args.engine.is_none() {
            args.engine = curr_engine;
        }
        if curr_engine.is_some() && args.engine != curr_engine {
            error!("Wrong engine!");
            exit(1);
        }
        run(args)
    });    
    if let Err(e) = res {
        error!("{}", e);
        exit(1);
    }
    Ok(())
}

fn run(args: Args) -> Result<()> {
    let engine = args.engine.unwrap_or(DEFAULT_ENGINE);
    info!("kvs-server {}", env!("CARGO_PKG_VERSION"));
    info!("Storage engine: {:?}", engine);
    info!("Listening on {}", args.addr);

    // write engine to engine file
    fs::write(current_dir()?.join("engine"), format!("{:?}", engine))?;

    match engine {
        Engine::kvs => run_with_engine(KvStore::open(current_dir()?)?, args.addr),
        Engine::sled => Ok(()), //TODO
    }
}

fn run_with_engine(engine: impl KvsEngine, addr: SocketAddr) -> Result<()> {
    let mut server = KvsServer::new(engine);
    server.run(addr)
}

fn current_engine() -> Result<Option<Engine>> {
    let engine = current_dir()?.join("engine");
    if !engine.exists() {
        return Ok(None);
    }

    match fs::read_to_string(engine)?.parse() {
        Ok(engine) => Ok(Some(engine)),
        Err(e) => {
            warn!("The content of engine file is invalid: {}", e);
            Ok(None)
        }
    }
}

接下来在client.rs中实现KvsClient：

use std::{io::{BufReader, BufWriter, Write}, net::{TcpStream, ToSocketAddrs}};
use crate::{Result, common::{Request, GetResponse, SetResponse, RemoveResponse}, KvsError};
use serde::Deserialize;
use serde_json::{Deserializer, de::IoRead};

/// Key value store client
pub struct KvsClient {
    reader: Deserializer<IoRead<BufReader<TcpStream>>>,
    writer: BufWriter<TcpStream>,
}

impl KvsClient {
    /// Connect to `addr` to access `KvsServer`.
    pub fn connect(addr: impl ToSocketAddrs) -> Result<Self> {
        let tcp_reader = TcpStream::connect(addr)?;
        let tcp_writer = tcp_reader.try_clone()?;
        Ok(KvsClient{
            reader: Deserializer::from_reader(BufReader::new(tcp_reader)),
            writer: BufWriter::new(tcp_writer),
        })
    }

    /// Get the value of a given key from the server.
    pub fn get(&mut self, key: String) -> Result<Option<String>> {
        serde_json::to_writer(&mut self.writer, &Request::Get { key })?;
        self.writer.flush()?;
        let resp = GetResponse::deserialize(&mut self.reader)?;
        match resp {
            GetResponse::Ok(value) => Ok(value),
            GetResponse::Err(msg) => Err(KvsError::StringError(msg)),
        }
    }

    /// Set the value of a string key in the server.
    pub fn set(&mut self, key: String, value: String) -> Result<()> {
        serde_json::to_writer(&mut self.writer, &Request::Set { key, value })?;
        self.writer.flush()?;
        let resp = SetResponse::deserialize(&mut self.reader)?;
        match resp {
            SetResponse::Ok(_) => Ok(()),
            SetResponse::Err(msg) => Err(KvsError::StringError(msg)),
        }
    }

    /// Remove a string key in the server.
    pub fn remove(&mut self, key: String) -> Result<()> {
        serde_json::to_writer(&mut self.writer, &Request::Remove { key })?;
        self.writer.flush()?;
        let resp = RemoveResponse::deserialize(&mut self.reader)?;
        match resp {
            RemoveResponse::Ok(_) => Ok(()),
            RemoveResponse::Err(msg) => Err(KvsError::StringError(msg)),
        }
    }
    
}

并在kvs-client.rs中使用：

use clap::{Parser, Subcommand};
use kvs::{Result, KvsClient};
use std::net::SocketAddr;

const DEFAULT_LISTENING_ADDRESS: &str = "127.0.0.1:4000";

#[derive(Parser)]
#[clap(name = "kvs")]
#[clap(author, version, about="an in-memory key/value store", long_about=None, args_conflicts_with_subcommands(true))]
struct Cli {
    #[clap(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
#[allow(non_camel_case_types)]
enum Commands {
    // Set the value of a string key to a string
    #[clap(arg_required_else_help=true)]
    set {
        // A string key
        key: String,
        // The string value of the key
        value: String,

        #[clap(long, required(false), default_value(DEFAULT_LISTENING_ADDRESS), help="Set the server address as [IP:PORT]")]
        addr: SocketAddr
    }, 

    // Get the string value of a given string key
    #[clap(arg_required_else_help=true)]
    get {
        // A string key
        key: String,
        
        #[clap(long, required(false), default_value(DEFAULT_LISTENING_ADDRESS), help="Set the server address as [IP:PORT]")]
        addr: SocketAddr
    }, 

    // Remove a given key
    #[clap(arg_required_else_help=true)]
    rm {
        // A string key
        key: String,
        
        #[clap(long, required(false), default_value(DEFAULT_LISTENING_ADDRESS), help="Set the server address as [IP:PORT]")]
        addr: SocketAddr
    },
}

fn main() -> Result<()> {
    let cli= Cli::parse();
    match cli.command {
        Commands::get { key, addr } => {
            let mut client = KvsClient::connect(addr)?;
            if let Some(value) = client.get(key.to_string())? {
                println!("{}", value);
            } else {
                println!("Key not found");
            }
        }, 
        Commands::set { key, value, addr } => {
            let mut client = KvsClient::connect(addr)?;
            client.set(key.to_string(), value.to_string())?;
        }
        Commands::rm { key, addr } => {
            let mut client = KvsClient::connect(addr)?;
            client.remove(key)?;
        }
    }

    Ok(())
}

此时一个终端打开cargo run --bin kvs-server，另一个终端运行cargo run --bin kvs-client -- get key，就可以从网络上将“训练课程2”中存入的键: 值取出来了：

# server
(base) ➜  kvs git:(master) ✗ cargo run --bin kvs-server
   Compiling kvs v0.1.0 (/Users/zealot/RustProjects/pingcap-projects/kvs)
    Finished dev [unoptimized + debuginfo] target(s) in 1.14s
     Running `target/debug/kvs-server`
[2022-06-03T10:38:45Z INFO  kvs_server] kvs-server 0.1.0
[2022-06-03T10:38:45Z INFO  kvs_server] Storage engine: kvs
[2022-06-03T10:38:45Z INFO  kvs_server] Listening on 127.0.0.1:4000
[2022-06-03T10:38:49Z DEBUG kvs::server] Receive request from 127.0.0.1:55017 Get { key: "键" }
[2022-06-03T10:38:49Z DEBUG kvs::server] Response sent to 127.0.0.1:55017: Ok(Some("值"))

# client
(base) ➜  kvs git:(master) ✗ cargo run --bin kvs-client -- get 键
    Finished dev [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/kvs-client get '键'`
值

第4部分：通过网络处理命令

在上一个项目中，您定义了数据库接受的命令，并学习了如何使用serde对日志进行序列化和反序列化。

现在是时候通过网络实现键/值存储，以通过前面实现的同步单进程模型远程执行命令。与您在上一个项目中创建日志的文件I/O一样，您将使用Read和Write特征序列化和流式传输命令。

现在您需要设计一个网络协议。有多种方法可以在TCP流上数读写数据，与上一个项目一样，也需要做出许多选择。该协议是基于文本还是二进制？数据如何从内存中的类型格式转换为字节流格式？每个连接传输一个还是多个请求？

请记住，该协议应支持执行成功并取回结果，也支持执行时遇到的错误，现在有两种错误：由您的存储引擎产生的错误，以及由网络通信产生的错误。

协议的所有细节都由您决定。测试套件不关心数据如何从一端到达另一端，只关心结果是否正确。

实现您的网络协议。

前面我们已经一并实现了该协议，需要注意的是，只要进行适当的定义，序列化的所有类型转换都是自动完成的。

第5部分：可插拔存储引擎

您的数据库目前有一个由您实现的存储引擎KvStore。现在将添加第二个存储引擎。

这样做有多种原因：

不同的业务负载需要不同的性能特征。对于特定的业务负载，某些存储引擎可能比其他存储引擎工作得更好；
搭建了一个熟悉的框架来比较不同的后端；
给了我们一个创建和使用trait的理由；
给了我们一个编写比较基准的环境。

所以你要从KvStore接口中抽象出一个新的特征：KvsEngine。这是一个典型的重构，将现有代码逐步修改为新的形式。一般在重构时，我们希望将工作最小化分解，以便进行持续构建和修改。

这是您最终需要的API：

KvsEnginetrait具有与KvStore具有相同签名的get、set和remove方法。
KvStore实现了KvsEngine，不再有自己的get、set和remove方法。
KvsEngine有一个新的实现——SledKvsEngine。稍后您需要使用sled库填充其get和set方法。

如果您的测试套件通过编译，则可能已经了编写了这些定义的签名，现在是时候实现定义的内容了。将重构分解为渐进式修改，并确保项目能够持续构建，并通过先前已经通过的测试，然后再继续下一步重构。

作为最后一步，您需要考虑当kvs-server使用一个引擎启动，然后进程被终结，接下来再使用不同的引擎重新启动时会发生什么。这种情况应当产生错误，你需要想清楚如何检测这种情况才能报告错误。测试cli_wrong_engine反映了这种情况。

本项目一开始，为了通过测试，我们已经实现了KvsEngine的签名，又在第3部分提前将KvStore的几个方法移动至KvsEngine的实现中。而在本项目需求说明部分，为了实现引擎切换报错，我们已经实现了启动时检测engine文件内容的功能：

若未检测到engine文件，则将本次使用的引擎写入engine文件（不指定时默认使用kvs）。
若检测到engine文件，当文件记录引擎与当前指定引擎不一致时，报错；一致时则继续执行。

在engine/sled.rs中为sled实现KvsEngine：

use sled::{Db, Tree};
use crate::{KvsEngine, Result, KvsError};

/// Wrapper of `sled::Db`
pub struct SledKvStore {
    db: Db,
}

impl SledKvStore {
    /// Creates a `SledKvsEngine` from `sled::Db`.
    pub fn new(db: Db) -> Self {
        Self { db }
    }
}

impl KvsEngine for SledKvStore {
    fn get(&mut self, key: String) -> Result<Option<String>> {
        let tree: &Tree = &self.db;
        Ok(
            tree.get(key)?
                .map(|iv| AsRef::<[u8]>::as_ref(&iv).to_vec())
                .map(String::from_utf8)
                .transpose()?
        )
    }

    fn set(&mut self, key: String, value: String) -> Result<()> {
        let tree: &Tree = &self.db;
        tree.insert(key, value.into_bytes()).map(|_| ())?;
        tree.flush()?;
        Ok(())
    }

    fn remove(&mut self, key: String) -> Result<()> {
        let tree: &Tree = &self.db;
        tree.remove(key)?.ok_or(KvsError::KeyNotFound)?;
        tree.flush()?;
        Ok(())
    }
}

然后在kvs-server.rs中调用SledKvStore，以补全最后一个//TODO：

// ...
match engine {
    Engine::kvs => run_with_engine(KvStore::open(current_dir()?)?, args.addr),
    Engine::sled => run_with_engine(SledKvStore::new(sled::open(current_dir()?)?), args.addr), 
}
//...

第6部分：基准测试

随着课程的进展，我们将越来越关注数据库的性能，探索不同架构对性能产生的影响。我们希望您不要局限于本文所展示的内容，多尝试自己的优化。

性能比对需要基准测试，目前有很多方法可以对数据库进行基准测试：例如使用ycsb和sysbench等标准测试套件。Rust内置了一些基准测试工具，我们将从此处入手。

Cargo支持使用cargo bench进行基准测试。基准测试可以使用Rust内置的基准测试工具编写，也可以使用外部工具编写。

为函数添加#[bench]属性即可启用内置基准测试套件。不过这一功能并不在Rust stable channel中提供，仅在the unstable book和test crate docs中有简略描述。尽管它在整个Rust生态中已被广泛使用—这些crates即使使用stable编译，也会用nightly进行基准测试。

尽管该系统实际上已被弃用—没有更新，且似乎永远不会被提升到stable channel。

不过，Rust也有更好的基准测试工具。本项目将使用criterion来对比kvs引擎与sled引擎的性能。

这这些基准测试工具的工作原理是定义一个基准测试函数，然后在该函数内循环迭代要执行的基准测试操作。基准测试工具将根据需要进行多次迭代，以获取具有统计意义的操作持续时间。

这是criterion指南中的这个基础示例：

fn criterion_benchmark(c: &mut Criterion) {
    c.bench_function("fib 20", |b| {
        b.iter(|| {
            fibonacci(20)
        });
    });
}

调用bench_function定义基准，调用iter定义为基准需要测试的代码。调用iter之前和之后的代码不计入基准测试时间。

通过创建一个名为benches/engine_benches.rs的文件来准备编写基准测试。同tests/tests.rs一样，cargo会自动找到这个文件并将其编译为基准测试。

首先编写以下基准测试：

kvs_write—使用kvs引擎，使用长度为1-100000字节的随机键和长度为1-100000字节的随机值写入100次；
sled_write—使用sled引擎，使用长度为1-100000字节的随机键和长度为1-100000字节的随机值写入100次；
kvs_read—使用kvs引擎，从先前写入的键中读取1000个值，键和值的长度是随机的；
sled_read—使用sled引擎，从先前写入的键中读取1000个值，键和值的长度是随机的；

（除了像上面描述的这样编写4个基准测试，您也可以用这2个引擎名作为参数编写参数化的基准测试，参见criterion手册）。

对于实现这些基准测试的技术细节，我们至少需要考虑三个因素：

哪些代码应该计时（写在基准测试循环内），哪些代码不应该计时（写在基准测试循环之外）？
尽管使用“随机”数字，如何使每次迭代执行相同操作。
在"read"的基准测试中，如何使用之前写入的同一组“随机”键读取值。

这些都是相互关联的：用作基准测试环境设置的代码应为非计时代码，此外还需要适当地重用随机数种子以复现测试环境。

在各种情况下，可能返回错误的操作都应该断言（使用assert!）它们没有返回错误；在"read"测试中，"get"操作应该断言找到了该键的值。

随机数可以使用randcrate生成。

编写完基准测试函数，就使用cargo bench运行它们。

完成上面的基准测试，对比kvs和sled的性能差距。

注意：请在没什么负载的主机上运行基准测试。基准测试对其运行环境非常敏感，虽然criterion库会尽力修正这些“噪音”，但最好在没有其他活动进程的干净机器上进行基准测试。如果您有一台仅用于开发的备用机器，请使用它。如果没有，AWS或其他云实例可能会产生比本地桌面更一致的结果。

在Cargo.toml中声明基准测试：

[[bench]]
name = "engine_benches"
harness = false

在engine_benches.rs中编写基准测试：

use criterion::{Criterion, BatchSize, criterion_group, criterion_main};
use kvs::{KvStore, KvsEngine, SledKvStore};
use rand::{rngs::SmallRng, SeedableRng, Rng};
use sled;
use tempfile::TempDir;

fn set_benches(c: &mut Criterion) {
    let mut group = c.benchmark_group("set_benches");
    group.bench_function("kvs", |b| {
        b.iter_batched(
            || {
            let temp_dir = TempDir::new().unwrap();
            (KvStore::open(temp_dir.path()).unwrap(), temp_dir)
            }, 
            |(mut store, _temp_dir)| {
                for i in 1..(1 << 12) {
                    store.set(format!("key-{}", i), format!("value-{}", i)).unwrap();
                }
            }, 
            BatchSize::SmallInput
        );
    });
    group.bench_function("sled", |b| {
        b.iter_batched(
            || {
            let temp_dir = TempDir::new().unwrap();
            (SledKvStore::new(sled::open(&temp_dir).unwrap()), temp_dir)
            }, 
            |(mut store, _temp_dir)| {
                for i in 1..(1 << 12) {
                    store.set(format!("key-{}", i), format!("value-{}", i)).unwrap();
                }
            }, 
            BatchSize::SmallInput
        );
    });
}

fn get_benches(c: &mut Criterion) {
    let mut group = c.benchmark_group("get_benches");
    for i in &vec![8, 12, 16, 20] {
        group.bench_with_input(format!("kvs_{}", i), i, |b, i| {
            let temp_dir = TempDir::new().unwrap();
            let mut store = KvStore::open(temp_dir.path()).unwrap();
            for key_i in 1..(1 << i) {
                store.set(format!("key-{}", key_i), format!("value-{}", key_i)).unwrap();
            }
            let mut rng = SmallRng::from_seed([0; 16]);
            b.iter(|| {
                store.get(format!("key-{}", rng.gen_range(1, 1 << i))).unwrap();
            });
        });
    }
    for i in &vec![8, 12, 16, 20] {
        group.bench_with_input(format!("sled_{}", i), i, |b, i| {
            let temp_dir = TempDir::new().unwrap();
            let mut store = SledKvStore::new(sled::open(&temp_dir).unwrap());
            for key_i in 1..(1 << i) {
                store.set(format!("key-{}", key_i), format!("value-{}", key_i)).unwrap();
            }
            let mut rng = SmallRng::from_seed([0; 16]);
            b.iter(|| {
                store.get(format!("key-{}", rng.gen_range(1, 1 << i))).unwrap();
            });
        });
    }
    
}

criterion_group!(benches, set_benches, get_benches);
criterion_main!(benches);

干得漂亮，朋友。休息一下吧。

PingCap的Rust训练课程2：日志结构文件I/O

Fri, 11 Mar 2022 18:50:00 GMT

:::warning 本文内容大多翻译自原文：PNA Rust Project 2: Log-structured file I/O。 :::

前言

任务：创建一个键/值存储程序，能够从命令行访问，支持持久化。

目标：

编写健壮的错误和异常处理
使用serde进行序列化
使用标准文件API将数据作为日志写入磁盘
从磁盘读取键/值数据的状态
将内存中的索引键映射在磁盘的对应值上
定期压缩日志以删除过期数据

关键词：日志结构文件I/O、bitcask、failurecrate、Read/Writetrait、serdecrate。

扩展练习：尝试使用structoptcrate。

介绍

在这个项目中，您将创建一个简单的基于磁盘的键/值存储程序，并可以通过命令行进行修改和查询。它将使用简化版的bitcask存储算法，该算法在简单和有效之间做了较好的平衡。您的第一个任务是在磁盘上维护先前写入命令的日志（有时称为“预写日志”或“WAL”），在程序启动时，通过对日志求值（译注：即按顺序执行日志）就能够在内存中重建数据库状态。您的第二个任务是继续拓展该程序，将键存储在内存中，将值存储到磁盘的日志中。您的最后一个任务是添加日志压缩功能，以确保日志不会无限增长。在这个项目结束时，您将使用Rust文件API构建一个简单且架构良好的数据库。

专业术语

下面列出本课程中使用的一些术语，部分参考了bitcask，不同的数据库会有略微不同的术语：

命令（command） - 一条对数据库的请求或一条请求的表示。命令来源于命令行或网络。命令有三种表示：内存表示、文本表示以及机器可读的序列化表示。
日志（log） - 由多条命令组成的序列，按照最初接收和执行的顺序放置在磁盘上。我们数据库在磁盘上的格式几乎完全由日志组成。这种实现很简单，而且非常高效。
日志指针（log pointer） - 日志中的文件偏移量，有时我们将其简称为“文件偏移量”（file offset）。
日志压缩（log compaction） - 当向数据库发出写入请求时，新的请求有时会使旧的日志条目无效。例如，写入键/值a = 0，之后再写入a = 1，这就会使"a"的第一条日志失效。压缩 — 至少在我们的数据库中 — 是一个从日志中删除过期的命令以减小数据库大小的过程。
内存索引/索引（in-memory index/index） - 指向日志指针的键映射。当发出读请求时，会在内存索引中查找相应的日志指针，找到后从磁盘日志中取回该值。我们的键/值存储程序与bitcask类似，整个数据库的索引都存储在内存中。
索引文件（index file） - 内存索引的磁盘表示。如果没有该文件，则每次启动数据库时都需要重放日志（重新执行整个日志）以恢复内存索引的状态。

项目需求规格

cargo项目kvs构建了一个名为kvs的命令行键值存储客户端，该客户端又调用了一个名为kvs的库。

kvs可执行文件支持以下命令行参数：

kvs set <KEY> <VALUE> 将字符串键的值设置为字符串值。打印错误并在失败时返回非零退出码。
kvs get <KEY> 获取给定字符串键的字符串值。打印错误并在失败时返回非零退出码。 -kvs rm <KEY> 删除给定的键。打印错误并在失败时返回非零退出码。
kvs -V 打印版本。

kvs库包含一个类型，KvStore，它支持以下方法：

KvStore::set(&mut self, key: String, value: String) -> Result<()> 将字符串键设置为字符串值。如果值未设置成功，则返回错误。
KvStore::get(&mut self, key: String) -> Result<Option<String>> 获取字符串键的字符串值。如果键不存在，则返回None。如果读取键值未成功，则返回错误。
KvStore::remove(&mut self, key: String) -> Result<()> 删除给定的key。如果key不存在或未成功删除，则返回错误。
KvStore::open(path: impl Into<PathBuf>) -> Result<KvStore> 从给定路径打开KvStore。返回KvStore。

在设置键值时，kvs将这条set命令写入位于磁盘的顺序日志中，然后将该命令的日志指针（文件偏移量）存储在内存索引中，即从键映射到日志指针。删除键时，类似地，kvs会在日志中写入rm命令，然后从内存索引中删除该键。当使用get命令检索键的值时，它会搜索内存索引，如果找到，则从日志中加载对应日志指针处的命令，对命令求值（译注：执行命令）并返回结果。

启动时，按时间顺序遍历日志中的命令，即可重建内存索引。

当未压缩日志记录大小达到给定阈值时，kvs会将其压缩到新日志中，删除冗余条目以回收磁盘空间。

请注意，我们的kvs项目既是一个无状态的命令行程序，也是一个包含有状态KvStore类型的库：作为命令行程序使用，KvStore类型将加载索引、执行命令、并退出；作为库使用，它将加载索引，然后执行多条命令，维护索引状态，直到它被删除。

项目设置

在上一个项目的基础上进行本项目，删除上一个项目的tests目录，将本项目的tests目录复制到该位置。和上一个项目一样，本项目应该包含一个库和一个可执行文件，两者都叫做kvs。

Cargo.toml中需要以下开发依赖项：

[dev-dependencies]
assert_cmd = "0.11.0"
predicates = "1.0.0"
tempfile = "3.0.7"
walkdir = "2.2.7"

与上一个项目一样，先编写空函数或panic来构建测试用例。

现在就试试吧。

我的作业：

/// 若仅让tests能够运行，则需要修改的地方很少

// 添加`PathBuf`导入
use std::{collections::HashMap, path::PathBuf};

// 添加Result<T>类型
pub type Result<T> = std::result::Result<T, ()>;

// 修改`KvStore`中函数的返回类型
impl KvStore {
    //...
    pub fn open(path: impl Into<PathBuf>) -> Result<KvStore> {
        Ok(Self::new())
    }
    //...
    pub fn get(&self, key: String) -> Result<Option<String>> {
        match self.db.get(&key) {
            Some(value) => Ok(Some(value.to_string())),
            None => Err(())
        }
    }
    //...
    pub fn set(&mut self, key: String, value: String) -> Result<()> {
        self.db.insert(key, value);
        Ok(())
    }
    //...
    pub fn remove(&mut self, key: String) -> Result<()>{
        self.db.remove(&key);
        Ok(())
    }

cargo test结果如下：

...
running 17 tests
test cli_invalid_subcommand ... ok
test cli_get_non_existent_key ... FAILED
test cli_rm_non_existent_key ... FAILED
test cli_get_stored ... FAILED
test cli_no_args ... ok
test get_non_existent_value ... FAILED
test get_stored_value ... FAILED
test compaction ... FAILED
test cli_invalid_get ... ok
test overwrite_value ... FAILED
test remove_non_existent_key ... FAILED
test cli_version ... ok
test remove_key ... FAILED
test cli_invalid_rm ... ok
test cli_set ... FAILED
test cli_rm_stored ... FAILED
test cli_invalid_set ... ok
...

第1部分：异常处理

在本项目中，代码运行时可能会因为I/O错误而失败。因此，在开始实现数据库之前，我们需要再做一件对Rust项目至关重要的事情：确定错误处理策略。

Rust的错误处理功能强大，但需要大量模板代码才能正确使用。本项目使用failurecrate以获得轻松处理各种错误的工具。

异常处理指南描述了几种常见的错误处理模式。

在您的实现中，选择其中一种策略，定义您自己的错误类型，或导入failures的Error。您将在所有Result中使用该错误类型，使用?运算符将其他crate中的错误类型转换为您自己定义的错误类型。

接下来，给包含您自定义错误类型的Result起一个类型别名，这样您就不需要在项目中键入Result<T, YourErrorType>了，只需Result<T>即可。这是Rust中常见的模式。

最后，使用use语句将这些类型导入您的可执行文件，并更改main函数签名以返回Result<()>。库中所有可能失败的函数都会将这些Result沿栈一路向下传递到main，然后传递到Rust运行时并打印出错误信息。

运行cargo check查找编译器错误并予以修复。目前可以用panic!()结束main函数以使项目通过编译。

在继续之前确定您的异常处理策略。

与之前的项目一样，您需要创建用于占位的数据结构和方法，以使测试能够编译。现在您已经定义了一个错误类型，通过编译应该很简单。可以在任何地方添加panic以使得测试套件能够通过编译（cargo test --no-run）。

注意：Rust中的错误处理实践仍在不断发展。本课程目前使用failurecrate来简化定义错误类型的过程。虽然failure设计良好，但使用它可能并不是最佳实践。 Rust专家可能不会继续看好这一实践。本课程也在迭代更新，未来可能不会使用failure。不过起码目前这一实践还不错，也提供了一个了解更多Rust错误处理发展细节的机会。

我的作业：

//...
mod error;
pub use error::{Result, KvsError};
//...
impl KvStore {
    //...
    pub fn get(&self, key: String) -> Result<Option<String>> {
        match self.db.get(&key) {
            Some(value) => Ok(Some(value.to_string())),
            None => Err(KvsError::KeyNotFound(key))
        }
    }
    //...
}

新增的自定义错误error模块（其实只定义一个错误就能通过编译）：

use failure::Fail;
use std::io;

/// custom error type of kvs
#[derive(Fail, Debug)]
pub enum KvsError {
    /// Key not found in kvs index
    #[fail(display="Key `{}` not found", _0)]
    KeyNotFound(String),
}

/// simplify `Result<T, KvsError>` to `Result<T>`
pub type Result<T> = std::result::Result<T, KvsError>;

第2部分日志行为

现在我们终于要开始实现一个数据库的基础功能并读写磁盘了。您将使用serde将"set"和"rm"命令序列化为字符串，再使用标准文件I/O API将其写入磁盘。

这是带日志kvs的基本行为：

"set"：
- 用户调用kvs set mykey myvalue
- kvs创建一个值来表示"set"命令，包含命令的键和值
- 将该命令序列化为String
- 将序列化后的命令追加到日志文件中
- 若执行成功，则返回错误码0，静默退出
- 若执行失败，则打印错误，返回非零错误码并退出
"get"
- 用户调用kvs get mykey
- kvs读取整个日志，一次一条命令，将被命令影响的键及文件偏移量录入到内存中的“键->日志指针”映射中
- 查找日志指针映射
- 若查找失败，则打印"Key not found"，并以退出码0退出
- 若查找成功：
  - 反序列化命令以获取该键的最新记录值
  - 将值打印到标准输出，并以退出码0退出
"rm"
- 用户调用kvs rm mykey
- 与"get"命令相同，kvs读取整个日志以重建内存索引
- 在映射中查找给定的键
- 若键不存在，则打印"Key not found"，并以非零错误码退出
- 若找到该键：
  - 创建一个值来表示"rm"命令，包含命令的键
  - 将序列化的命令追加到日志中
  - 若成功完成，则以错误码0静默退出

日志是一份提交到数据库的事务的记录。通过在启动时“重放”日志中的记录，即可重建数据库先前的状态。

在本次迭代中，您可以将键的值直接存储在内存中（因此在程序初始化和日志重放后就不再需要从读取日志了）。在后面的迭代中，您只需将“日志指针”（文件偏移量）存储在内存中。

第3部分：写日志

您将从实现"set"命令开始，有很多步骤，大多数步骤都很容易实现。您可以通过运行相应的的cli_*测试用例来验证。

serde是一个有有很多选项的大型库，支持多种序列化格式。只需要正确注释您的数据结构即可使用基础的序列化/反序列化功能，然后再调用函数将其写入String或任何实现了Writetrait的流。

您需要选择一种序列化格式。考虑您想要的序列化属性 — 需要优先考虑性能吗？需要以纯文本形式查看日志内容吗？这都是您选择时需要考虑的属性，您应该在代码注释中解释您的选择。

其他需要考虑的因素包括：系统的哪些部分需要使用缓冲、您需要在哪里设置缓冲？缓冲对后续的读操作有什么影响？什么时候打开/关闭文件句柄？每个命令都需要操作句柄吗？还是在KvStore的整个生命周期内都不释放句柄？（译注，可以使用BufWriter提高写效率）

您会用到的部分API可能会调用失败，并返回包含某种错误类型的Result。确保函数返回包含您自定义错误类型的Result，以决定是否使用?传播异常。

实现"rm"命令也类似，但您应该在将命令写入日志前，检查该键是否已经存在。由于我们必须区分两个不同的命令，因此您可以使用枚举类型变量来表示每个命令。而serde可以完美应用在枚举类型上。

您现在可以实现"set"和"rm"命令了，专注于通过set/rm的相关测试用例。此外您也可以继续阅读下一节的"get"命令相关内容。在实现过程中，同时考虑读、写两种操作可能使代码更容易编写。逐项实现或同时实现均可。

第4部分：读日志

现在该实现"get"命令了。您暂时还不用考虑在索引中存储日志指针的特性，我们将该特性的实现留到下一部分。目前，您只需在启动时读取日志中的每个命令，执行这些指令，以将所有键/值保存在内存中，再从内存中读取这些键值。

此时您需要考虑：应该把日志中的所有记录一次读入内存，再将一次性重放以初始化你的映射类型；还是应该一次读取一条的重放命令并初始化您的映射？应该在反序列化前先将日志读取到缓冲区；还是应该直接反序列化一个文件流？思考您的实现对应的内存使用情况，也要考虑从I/O流中读取数据时与内核交互的情况。（译注，可以使用BufReader提高读效率）

请记住，"get"也可能找不到指定键，这种情况需要特别处理。本项目的设定为，API返回None，且命令行客户端打印一条特定的消息并以零退出码退出。

读取日志有一个复杂之处，您可能在编写"set"代码时已经考虑过：如何区分日志文件中的每条记录？也就是说，程序怎么知道一条记录在哪里结束，而下一题记录从哪里开始？这会是一个问题吗？也许serde会直接从I/O流中反序列化一条记录，并在完成后停止读取，将文件光标留在正确的位置以便继续读取后面的记录？也许serde在看到两条记录粘在一起时会报错？也许你需要插入额外的信息来区分每条记录的长度？也许不用？

现在实现"get"命令。

(译注：此时使用BufReader和BufWriter实现即可，暂不需要记录命令在日志中的位置。虽然此时应新建Command枚举类型，并使用serde_json从日志文件中读取整条命令，但内存中的存储索引的形式暂时仍为BTreeMap<String, String>。同样，写操作也使用serde_json直接写入Command枚举类型。)

第5部分：在索引中存储日志指针

此时，测试条件中，除了压缩测试外的其他测试都应该能够通过。后续步骤中引入的是一些优化特性，这对于提高性能和减少存储空间是十分必要的。在实现这些特性时，请注意我们在优化什么。

正如我们所描述的，您正在构建的数据库将在内存中维护所有键的索引。该索引从键的字符串映射到日志的指针，而不是映射值本身。

此更改需要我们能够从日志的任意偏移量处读取数据，考虑如何按照此更改修改您的文件句柄管理方式。

如果在前面的步骤中，您选择将值的字符串直接存储在内存中，那么现在是时候更新代码，以存放日志指针了，然后实现按需从磁盘加载。

（译注：此时需要引入变量记录读写日志文件的位置，并将内存中的存储索引形式修改为BTreeMap<String, CommandPos{ pos: u64, len: u64 }>）

第6部分：无状态`KvStore` 与有状态`KvStore`

请记住，我们的项目既是库又是命令行程序。它们的要求略有不同：kvs命令行程序将单个更改提交到磁盘，然后退出（它是无状态的）；KvStore类将更改提交到磁盘，然后驻留在内存中以提供的查询服务（它是有状态的）。

您的KvStore是有状态的还是无状态的？

让您的KvStore将索引保留在内存中，这样它就不需要为每次接受get命令时都对日志求值。

第7部分：压缩日志

此时数据库工作正常，但日志无限增长。这适用于某些数据库，但不适用于我们正在构建的数据库 — 希望尽可能减少磁盘用量。

因此，创建数据库的最后一步是压缩日志。在使用中，随着日志的增长，对于某个键，可能会有多条命令进行设置值或删除键。不过对于该键，只有最新的修改命令才会修改它的值：

idx	command
0	~Command::Set("key-1", "value-1a")~
20	Command::Set("key-2", "value-2")
	...
100	Command::Set("key-1", "value-1b")

在上面的例子中，索引0的命令显然是多余的，因此不需要存储它。日志压缩就是重建日志，以删除冗余命令：

idx	command
0	Command::Set("key-2", "value-2")
	...
99	Command::Set("key-1", "value-1b")

基本算法如下：

您应当自行考虑如何重建日志。同时思考以下问题：朴素的解决方案是什么？需要多少内存？压缩日志所需的最小复制量是多少？压缩可以就地完成吗？如果压缩失败，您如何保持数据完整性？

到目前为止，我们一直再说“日志文件”，但实际上数据库通常会将大量日志存储在不同的文件中。在实现过程中您可能会发现，如果跨文件拆分日志将会更容易的压缩日志。

为您的数据库实现日志压缩功能。

恭喜！您已经成功实现了一个功能齐全的数据库。

如果您仍然好奇，那么现在可以对比您的键/值数据库与其他同类数据库（如sled、bitcask、badger或RocksDB）的性能。您可以继续研究他们的架构，思考他们的架构与您的架构的异同，以及架构如何影响性能。接下来的几个项目将为您提供优化的机会。

目录结构：

.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│  ├── bin
│  │  └── kvs.rs
│  ├── error.rs
│  ├── kv.rs
│  └── lib.rs
└── tests
   └── tests.rs

主要改动了lib.rs，将功能实现迁移至kv.rs，将错误处理迁移至error.rs。

#![deny(missing_docs)]
//! A simple key/value store.

pub use error::{KvsError, Result};
pub use kv::KvStore;

mod error;
mod kv;

use std::collections::{BTreeMap, HashMap};
use std::fs::{self, File, OpenOptions};
use std::io::{self, BufReader, BufWriter, Read, Seek, SeekFrom, Write};
use std::ops::Range;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};
use serde_json::Deserializer;

use crate::{KvsError, Result};
use std::ffi::OsStr;

const COMPACTION_THRESHOLD: u64 = 1024 * 1024;

/// The `KvStore` stores string key/value pairs.
///
/// Key/value pairs are persisted to disk in log files. Log files are named after
/// monotonically increasing generation numbers with a `log` extension name.
/// A `BTreeMap` in memory stores the keys and the value locations for fast query.
///
/// ```rust
/// # use kvs::{KvStore, Result};
/// # fn try_main() -> Result<()> {
/// use std::env::current_dir;
/// let mut store = KvStore::open(current_dir()?)?;
/// store.set("key".to_owned(), "value".to_owned())?;
/// let val = store.get("key".to_owned())?;
/// assert_eq!(val, Some("value".to_owned()));
/// # Ok(())
/// # }
/// ```
pub struct KvStore {
    // directory for the log and other data.
    path: PathBuf,
    // map generation number to the file reader.
    readers: HashMap<u64, BufReaderWithPos<File>>,
    // writer of the current log.
    writer: BufWriterWithPos<File>,
    current_gen: u64,
    index: BTreeMap<String, CommandPos>,
    // the number of bytes representing "stale" commands that could be
    // deleted during a compaction.
    uncompacted: u64,
}

impl KvStore {
    /// Opens a `KvStore` with the given path.
    ///
    /// This will create a new directory if the given one does not exist.
    ///
    /// # Errors
    ///
    /// It propagates I/O or deserialization errors during the log replay.
    pub fn open(path: impl Into<PathBuf>) -> Result<KvStore> {
        let path = path.into();
        fs::create_dir_all(&path)?;

        let mut readers = HashMap::new();
        let mut index = BTreeMap::new();

        let gen_list = sorted_gen_list(&path)?;
        let mut uncompacted = 0;

        for &gen in &gen_list {
            let mut reader = BufReaderWithPos::new(File::open(log_path(&path, gen))?)?;
            uncompacted += load(gen, &mut reader, &mut index)?;
            readers.insert(gen, reader);
        }

        let current_gen = gen_list.last().unwrap_or(&0) + 1;
        let writer = new_log_file(&path, current_gen, &mut readers)?;

        Ok(KvStore {
            path,
            readers,
            writer,
            current_gen,
            index,
            uncompacted,
        })
    }

    /// Sets the value of a string key to a string.
    ///
    /// If the key already exists, the previous value will be overwritten.
    ///
    /// # Errors
    ///
    /// It propagates I/O or serialization errors during writing the log.
    pub fn set(&mut self, key: String, value: String) -> Result<()> {
        let cmd = Command::set(key, value);
        let pos = self.writer.pos;
        serde_json::to_writer(&mut self.writer, &cmd)?;
        self.writer.flush()?;
        if let Command::Set { key, .. } = cmd {
            if let Some(old_cmd) = self
                .index
                .insert(key, (self.current_gen, pos..self.writer.pos).into())
            {
                self.uncompacted += old_cmd.len;
            }
        }

        if self.uncompacted > COMPACTION_THRESHOLD {
            self.compact()?;
        }
        Ok(())
    }

    /// Gets the string value of a given string key.
    ///
    /// Returns `None` if the given key does not exist.
    ///
    /// # Errors
    ///
    /// It returns `KvsError::UnexpectedCommandType` if the given command type unexpected.
    pub fn get(&mut self, key: String) -> Result<Option<String>> {
        if let Some(cmd_pos) = self.index.get(&key) {
            let reader = self
                .readers
                .get_mut(&cmd_pos.gen)
                .expect("Cannot find log reader");
            reader.seek(SeekFrom::Start(cmd_pos.pos))?;
            let cmd_reader = reader.take(cmd_pos.len);
            if let Command::Set { value, .. } = serde_json::from_reader(cmd_reader)? {
                Ok(Some(value))
            } else {
                Err(KvsError::UnexpectedCommandType)
            }
        } else {
            Ok(None)
        }
    }

    /// Removes a given key.
    ///
    /// # Errors
    ///
    /// It returns `KvsError::KeyNotFound` if the given key is not found.
    ///
    /// It propagates I/O or serialization errors during writing the log.
    pub fn remove(&mut self, key: String) -> Result<()> {
        if self.index.contains_key(&key) {
            let cmd = Command::remove(key);
            serde_json::to_writer(&mut self.writer, &cmd)?;
            self.writer.flush()?;
            if let Command::Remove { key } = cmd {
                let old_cmd = self.index.remove(&key).expect("key not found");
                self.uncompacted += old_cmd.len;
            }
            Ok(())
        } else {
            Err(KvsError::KeyNotFound)
        }
    }

    /// Clears stale entries in the log.
    pub fn compact(&mut self) -> Result<()> {
        // increase current gen by 2. current_gen + 1 is for the compaction file.
        let compaction_gen = self.current_gen + 1;
        self.current_gen += 2;
        self.writer = self.new_log_file(self.current_gen)?;

        let mut compaction_writer = self.new_log_file(compaction_gen)?;

        let mut new_pos = 0; // pos in the new log file.
        for cmd_pos in &mut self.index.values_mut() {
            let reader = self
                .readers
                .get_mut(&cmd_pos.gen)
                .expect("Cannot find log reader");
            if reader.pos != cmd_pos.pos {
                reader.seek(SeekFrom::Start(cmd_pos.pos))?;
            }

            let mut entry_reader = reader.take(cmd_pos.len);
            let len = io::copy(&mut entry_reader, &mut compaction_writer)?;
            *cmd_pos = (compaction_gen, new_pos..new_pos + len).into();
            new_pos += len;
        }
        compaction_writer.flush()?;

        // remove stale log files.
        let stale_gens: Vec<_> = self
            .readers
            .keys()
            .filter(|&&gen| gen < compaction_gen)
            .cloned()
            .collect();
        for stale_gen in stale_gens {
            self.readers.remove(&stale_gen);
            fs::remove_file(log_path(&self.path, stale_gen))?;
        }
        self.uncompacted = 0;

        Ok(())
    }

    /// Create a new log file with given generation number and add the reader to the readers map.
    ///
    /// Returns the writer to the log.
    fn new_log_file(&mut self, gen: u64) -> Result<BufWriterWithPos<File>> {
        new_log_file(&self.path, gen, &mut self.readers)
    }
}

/// Create a new log file with given generation number and add the reader to the readers map.
///
/// Returns the writer to the log.
fn new_log_file(
    path: &Path,
    gen: u64,
    readers: &mut HashMap<u64, BufReaderWithPos<File>>,
) -> Result<BufWriterWithPos<File>> {
    let path = log_path(&path, gen);
    let writer = BufWriterWithPos::new(
        OpenOptions::new()
            .create(true)
            .write(true)
            .append(true)
            .open(&path)?,
    )?;
    readers.insert(gen, BufReaderWithPos::new(File::open(&path)?)?);
    Ok(writer)
}

/// Returns sorted generation numbers in the given directory.
fn sorted_gen_list(path: &Path) -> Result<Vec<u64>> {
    let mut gen_list: Vec<u64> = fs::read_dir(&path)?
        .flat_map(|res| -> Result<_> { Ok(res?.path()) })
        .filter(|path| path.is_file() && path.extension() == Some("log".as_ref()))
        .flat_map(|path| {
            path.file_name()
                .and_then(OsStr::to_str)
                .map(|s| s.trim_end_matches(".log"))
                .map(str::parse::<u64>)
        })
        .flatten()
        .collect();
    gen_list.sort_unstable();
    Ok(gen_list)
}

/// Load the whole log file and store value locations in the index map.
///
/// Returns how many bytes can be saved after a compaction.
fn load(
    gen: u64,
    reader: &mut BufReaderWithPos<File>,
    index: &mut BTreeMap<String, CommandPos>,
) -> Result<u64> {
    // To make sure we read from the beginning of the file.
    let mut pos = reader.seek(SeekFrom::Start(0))?;
    let mut stream = Deserializer::from_reader(reader).into_iter::<Command>();
    let mut uncompacted = 0; // number of bytes that can be saved after a compaction.
    while let Some(cmd) = stream.next() {
        let new_pos = stream.byte_offset() as u64;
        match cmd? {
            Command::Set { key, .. } => {
                if let Some(old_cmd) = index.insert(key, (gen, pos..new_pos).into()) {
                    uncompacted += old_cmd.len;
                }
            }
            Command::Remove { key } => {
                if let Some(old_cmd) = index.remove(&key) {
                    uncompacted += old_cmd.len;
                }
                // the "remove" command itself can be deleted in the next compaction.
                // so we add its length to `uncompacted`.
                uncompacted += new_pos - pos;
            }
        }
        pos = new_pos;
    }
    Ok(uncompacted)
}

fn log_path(dir: &Path, gen: u64) -> PathBuf {
    dir.join(format!("{}.log", gen))
}

/// Struct representing a command.
#[derive(Serialize, Deserialize, Debug)]
enum Command {
    Set { key: String, value: String },
    Remove { key: String },
}

impl Command {
    fn set(key: String, value: String) -> Command {
        Command::Set { key, value }
    }

    fn remove(key: String) -> Command {
        Command::Remove { key }
    }
}

/// Represents the position and length of a json-serialized command in the log.
struct CommandPos {
    gen: u64,
    pos: u64,
    len: u64,
}

impl From<(u64, Range<u64>)> for CommandPos {
    fn from((gen, range): (u64, Range<u64>)) -> Self {
        CommandPos {
            gen,
            pos: range.start,
            len: range.end - range.start,
        }
    }
}

struct BufReaderWithPos<R: Read + Seek> {
    reader: BufReader<R>,
    pos: u64,
}

impl<R: Read + Seek> BufReaderWithPos<R> {
    fn new(mut inner: R) -> Result<Self> {
        let pos = inner.seek(SeekFrom::Current(0))?;
        Ok(BufReaderWithPos {
            reader: BufReader::new(inner),
            pos,
        })
    }
}

impl<R: Read + Seek> Read for BufReaderWithPos<R> {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        let len = self.reader.read(buf)?;
        self.pos += len as u64;
        Ok(len)
    }
}

impl<R: Read + Seek> Seek for BufReaderWithPos<R> {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.pos = self.reader.seek(pos)?;
        Ok(self.pos)
    }
}

struct BufWriterWithPos<W: Write + Seek> {
    writer: BufWriter<W>,
    pos: u64,
}

impl<W: Write + Seek> BufWriterWithPos<W> {
    fn new(mut inner: W) -> Result<Self> {
        let pos = inner.seek(SeekFrom::Current(0))?;
        Ok(BufWriterWithPos {
            writer: BufWriter::new(inner),
            pos,
        })
    }
}

impl<W: Write + Seek> Write for BufWriterWithPos<W> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        let len = self.writer.write(buf)?;
        self.pos += len as u64;
        Ok(len)
    }

    fn flush(&mut self) -> io::Result<()> {
        self.writer.flush()
    }
}

impl<W: Write + Seek> Seek for BufWriterWithPos<W> {
    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
        self.pos = self.writer.seek(pos)?;
        Ok(self.pos)
    }
}

use failure::Fail;
use std::io;

/// Error type for kvs.
#[derive(Fail, Debug)]
pub enum KvsError {
    /// IO error.
    #[fail(display = "{}", _0)]
    Io(#[cause] io::Error),
    /// Serialization or deserialization error.
    #[fail(display = "{}", _0)]
    Serde(#[cause] serde_json::Error),
    /// Removing non-existent key error.
    #[fail(display = "Key not found")]
    KeyNotFound,
    /// Unexpected command type error.
    /// It indicated a corrupted log or a program bug.
    #[fail(display = "Unexpected command type")]
    UnexpectedCommandType,
}

impl From<io::Error> for KvsError {
    fn from(err: io::Error) -> KvsError {
        KvsError::Io(err)
    }
}

impl From<serde_json::Error> for KvsError {
    fn from(err: serde_json::Error) -> KvsError {
        KvsError::Serde(err)
    }
}

/// Result type for kvs.
pub type Result<T> = std::result::Result<T, KvsError>;

干得漂亮，朋友，休息一下吧。

PingCap的Rust训练课程1：熟悉Rust工具链

Tue, 22 Feb 2022 22:22:22 GMT

:::warning 本文内容大多翻译自原文：PNA Rust Project 1: The Rust toolbox。 :::

前言

任务：在内存中创建一个能够接受命令行参数的键/值存储程序，且程序能够通过一些简单的测试。

目标：

安装Rust编译器和工具
了解本课程中使用的项目结构
使用cargo init/run/test/clippy/fmt
了解如何从crates.io查找、导入crates
为键值存储程序定义恰当的数据类型

关键词：测试、clapcrate、了解CARGO_VERSION等值、熟悉clippy和rustfmt工具。

扩展练习：尝试使用structoptcrate。

介绍

在这个项目中，您将在内存中创建一个简单的键/值存储，以将字符串映射到字符串，程序能够通过一些简单测试并能够响应命令行参数。项目的重点是熟悉典型Rust 项目的工具链和设置。

即使这些听起来很基础，也请亲手尝试这个项目，因为它将介绍一些会用在整个课程中的通用模式。

项目需求规格

cargo项目kvs构建了一个名为kvs的命令行键值存储客户端，该客户端又调用了一个名为kvs的库。

kvs可执行文件支持以下命令行参数：

kvs set <KEY> <VALUE> 将字符串键设置为字符串值
kvs get <KEY> 获取给定字符串键的字符串值 -kvs rm <KEY> 删除给定的键 -kvs -V 打印版本

kvs库包含一个类型，KvStore，它支持以下方法：

KvStore::set(&mut self, key: String, value: String) 将字符串键设置为字符串值
KvStore::get(&self, key: String) -> Option<String> 获取字符串键的字符串值。如果键不存在，返回None。
KvStore::remove(&mut self, key: String) 删除给定的键。

KvStore类型将值存储在内存中，因此命令行客户端除了打印版本外，能做的并不多。从命令行运行get/set/rm命令时返回"unimplemented"错误。未来项目会将值存储在磁盘上，并实现相应的的命令。

安装

以您此时的Rust基础应当知道如何使用rustup安装Rust。

如果不知道，运行下面的命令即可：

curl https://sh.rustup.rs -sSf | sh

（如果您使用的是Windows，请按照rustup.rs上的说明操作。请注意，您在本课程中将面临比其他人更多的挑战，因为它是在Unix上开发的。通常，在Windows上的Rust开发体验不如在Unix上那么顺滑）。

通过键入rustc -V来验证工具链是否正确安装。如果这不起作用，请注销当前shell的会话并重新登录，以使得安装时的shell profile配置变动可以生效。

项目设置

您将使用Cargo在git仓库完成本项目。您将从本课程的源仓库中导入项目的测试用例。

请注意，在源仓库中，与本课程相关的所有内容都在rust子目录中，您可以忽略其他目录。

本课程中的所有项目均包含库和可执行文件。使用可执行文件的形式，是因为我们正在开发一个可以运行的应用程序。使用库的形式，是因为提供的测试用例必须链接到这些库。

在本课程中，我们将为每个项目使用相同的设置。

我们将使用的目录结构为：

├── Cargo.toml
├── src
│   ├── bin
│   │   └── kvs.rs
│   └── lib.rs
└── tests
    └── tests.rs

其中Cargo.toml、lib.rs和kvs.rs文件内容如下：

Cargo.toml：

[package]
name = "kvs"
version = "0.1.0"
authors = ["Brian Anderson <andersrb@gmail.com>"]
description = "A key-value store"
edition = "2018"

lib.rs：

// just leave it empty for now

kvs.rs：

fn main() {
    println!("Hello, world!");
}

其中author应该是您的名字，而name必须是kvs，这是项目名称同时也是库的名称，以使测试用例起作用。同样，二进制文件（命令行应用程序）的名称必须是kvs。在上面的设置中，项目会因文件名隐式地叫做kvs，当然您也可以随意命名文件，只要将适当的信息写入配置文件（Cargo.toml）中即可。

您可以使用cargo new --lib直接新建项目；或使用cargo init --lib在一个空目录中初始化项目；或手动设置这个项目：您可能还需要在同一目录中初始化一个git仓库。

最后，从课程资料中复制tests目录：即将文件rust/projects/project-1/tests从课程仓库复制到您自己的仓库中，也叫做tests。

此时您应该可以使用cargo run运行程序。

现在就试试。

您已经为这个项目做好了准备，开始编写业务代码吧。

第1部分：编译测试代码

tests/tests.rs中为您提供了一套单元测试。打开它看看。

*尝试使用cargo test运行测试。*发生了什么？为什么？

本项目的第一个任务是让测试模块能够通过编译。

如果你的项目和我的一样，你应该会看到大量编译错误，我们来看看前几条。通常当你看到一堆错误时，第一条是最重要的 — rustc会在遇到错误后尝试继续编译，因此后面的可能是级联错误，其意义远低于第一条。您的前几条错误可能如下所示：

error[E0433]: failed to resolve: use of undeclared type or module `assert_cmd`
 --> tests/tests.rs:1:5
  |
1 | use assert_cmd::prelude::*;
  |     ^^^^^^^^^^ use of undeclared type or module `assert_cmd`

error[E0432]: unresolved import
 --> tests/tests.rs:3:5
  |
3 | use predicates::str::contains;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^

（如果您看到其他错误，请反馈issue）。

对于一个新的Rust程序员来说，这两个错误很难诊断出来，所以我只会告诉你这里发生了什么：项目配置文件中缺少开发依赖项的crates。

对于这个项目，你的Cargo.toml文件需要包含这些行：

[dev-dependencies]
assert_cmd = "0.11.0"
predicates = "1.0.0"

了解这些依赖项的详情，对您完成本项目并不重要，您可以自己去查找此类信息。我们之前没有告诉您需要开发依赖项，是为了让您自己会遇到这些错误。在未来的项目中，会在项目配置部分告诉您后面所需的开发依赖。

简要说明：您如何确定这些错误是由于项目配置中缺少依赖，项而不是由于源码中的错误造成的？以前面显示的错误为例，一个重要线索：

1 | use assert_cmd::prelude::*;
  |     ^^^^^^^^^^ use of undeclared type or module `assert_cmd`

在use语句中，路径中的第一个元素始终是crate的名称。不过，当第一个路径元素引用的，是之前由别的use语句引入上下文的名称时，会出现例外情况。换句话说，如果这个文件中有另一个use语句，例如use foo::assert_cmd，那么use assert_cmd::prelude::*中引用的就是之前那个assert_cmd。关于这一点还有很多内容，我们就不在这里探讨这些技术细节了。只需要记住，通常在use语句中，如果找不到路径中的第一个元素（即无法解析），问题可能是配置文件中没有声明那个crate。

这是我们在第一个项目中遇到的第一个问题。希望能有所启发。

继续，并将适当的开发依赖项添加到您的配置文件中。

再次尝试使用cargo test运行测试。发生什么了？为什么？

此时前面的那些错误应该已经消失了。现在的错误应该都是关于测试用例无法在您自己的代码中找到它期望的代码。

所以现在您的任务是：声明测试模块编译所需的类型、方法等。

在本课程中，您将大量阅读测试用例。测试用例将准确地告诉您对代码的期望。如果书本和实验不一致，则实验为真（纠正错误！）。在编程中也是如此。测试用例展示了软件应有的行为为。测试是现实，应习惯阅读测试用例。

此外，测试用例通常是任何项目中编写质量最差的代码，原始且没有文档注释。

再次尝试使用cargo test运行测试。发生什么了？为什么？

在src/lib.rs中编写能够让cargo test --no-run通过的类和方法签名。暂时不要编写任何函数体—使用panic!()宏。这是在不知道或不关心实现的情况下描述API的方法（此外还有宏unimplemented!，但由于这个单词有点长，因此通常简单地使用panic!即可。不过，如果您正在发布的软件包含未实现的方法的程序时，则应当使用unimplemented!宏）。

完成上述要求。

我的作业：

pub struct KvStore {

}

impl KvStore {
    pub fn new() -> Self {
        panic!()
    }

    pub fn get(&self, k: String) -> Option<String> {
        panic!()
    }

    pub fn set(&mut self, k: String, v: String) {
        panic!()
    }

    pub fn remove(&mut self, k: String) {
        panic!()
    }
}

之后，如果您运行cargo test（不带--no-run），您应该会看到一些测试失败输出，例如：

    Finished dev [unoptimized + debuginfo] target(s) in 2.32s
     Running target/debug/deps/kvs-b03a01e7008067f6

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/kvs-a3b5a004932c6715

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/tests-5e1c2e20bd1fa377

running 13 tests
test cli_get ... FAILED
test cli_invalid_get ... FAILED
test cli_invalid_rm ... FAILED
test cli_invalid_set ... FAILED
test cli_no_args ... FAILED
test cli_invalid_subcommand ... FAILED
... more lines of spew ...

...后还有很多行。太棒了！这结果正是我们现在所需要的。您会在本项目后面的内容中编写让这些测试通过的代码。

测试技巧

如果你再次查看cargo test的输出，就会看到一些有趣的东西：

     Running target/debug/deps/kvs-b03a01e7008067f6

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/kvs-a3b5a004932c6715

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

     Running target/debug/deps/tests-5e1c2e20bd1fa377


running 13 tests
test cli_get ... FAILED

cargo输出了三遍"Running ..."。实际上前两次并没有运行任何测试。那么如果这三批测试都没有失败，cargo将运行另一组测试。

为什么会这样？

这是因为在Rust中有很多可以用来编写测试的地方：

在库的源码中
在每个二进制的源码中
在每个测试的源码中
在库源码的注释文档中

其实cargo并不知道上面这四条里哪些确实包含了测试，cargo只是构建并运行这些测试。

所以这里有两组空测试：

     Running target/debug/deps/kvs-b03a01e7008067f6
running 0 tests
     Running target/debug/deps/kvs-a3b5a004932c6715
running 0 tests

不过，这里可能不容易理解：这其中一个是您的库，编译后测试，另一个是您的二进制，编译后测试，目前两者都不包含任何测试。名称中都有"kvs"的原因是因为您的库和二进制文件都称为"kvs"。

这些测试的输出可能有点烦人，有两种方法可以让cargo安静下来：使用命令行参数，或更改项目配置：

以下是相关的命令行标识：

cargo test --lib — 只测试库中的测试
cargo test --doc — 测试库中的文档测试
cargo test --bins — 测试项目中的所有二进制
cargo test --bin foo — 只测试foo的二进制
cargo test --test foo — 测试测试文件foo 中的测试

以上命令可以方便快速地隐藏测试输出，但如果项目不包含某种类型的测试，就最好不去处理测试。回想一下The Cargo Book中关于manifest description的描述，可知有两个配置选项可用：test = false和doctest = false。它们位于[lib]和[[bin]]部分，因此可以考虑更新您的项目配置。

如果以前没用过可以尝试下面这个命令：

cargo test -- --help

试试吧，输出很有趣。您在此处看到的是包含已编译测试的可执行文件的帮助信息（由空格包围的--将告诉cargo将之后的所有参数传递给测试二进制文件）。这与运行cargo test --help时显示的信息完全不同。它们是两个不同的命令：cargo在运行您的二进制测试时会将这些参数传递给测试程序。

您也可以通过命令执行同样的操作。让我们再回到的cargo test示例。我们看到了这一行：

     Running target/debug/deps/kvs-b03a01e7008067f6

这就是cargo告诉您测试二进制的文件名。您可以自己运行它，比如target/debug/deps/kvs-b03a01e7008067f6 --help。

target目录里有很多有趣的东西。深入研究可以教会您很多关于Rust工具链工作细节的知识。

在实践中，特别是对于大型项目，您不会在开发单个功能时运行整个测试套件。要将测试集缩小到我们关心的某个测试，请运行以下命令：

cargo test cli_no_args

这将运行名为cli_no_args的测试。事实上，它会运行名称中包含cli_no_args的任何测试，因此，例如，如果你想运行所有CLI测试，你可以运行cargo test cli。以上可能就是您在完成项目时手动运行测试的各种方式，否则您将被许多尚未修复的失败测试分心。不幸的是，该模式只是一个简单的字符串匹配，而不是像正则表达式那样功能强大的东西。

请注意，在撰写本文时，本课程中项目测试用例，并未按照能够明确指出某测试专为项目的某部分而编写的方式进行组织 - 只是到最后整个测试套件应该通过即可。您需要自己阅读测试的名称和实现，来确定您认为在哪些阶段应该通过哪些测试。

第2部分：接受命令行参数

本课程中的键/值存取都是通过命令行客户端执行的。在这个项目中，命令行客户端非常简单，因为键值存储的状态只存储在内存中，而不是持久化到磁盘。

通过这一部分，您应使名为cli_*的测试用例通过。

回忆上一部分中介绍的关于如何运行单个测试用例的内容。

重申一下CLI的接口是：

kvs set <KEY> <VALUE> 将字符串键设置为字符串值
kvs get <KEY> 获取给定字符串键的字符串值 -kvs rm <KEY> 删除给定的键 -kvs -V 打印版本

但在本次迭代中，get和set命令将从stderr输出字符串"unimplemented"，并以非零退出码退出，表示错误。

您可能需要使用clapcrate来处理命令行参数。

*找到最新版本的clapcrate 并将其添加到Cargo.toml的依赖项中。*有多种方法可以搜索或导入crate，我们推荐：查看内置的cargo search和插件cargo edit。

接下来使用crates.io、lib.rs或docs.rs查找clapcrate 的文档，并实现命令行界面以使名为cli_*的测试用例通过。

测试时，使用cargo run；不要直接从target/目录运行可执行文件。需要将参数传递给程序时，用两个破折号将它们与cargo run命令分开，--，如cargo run -- get key1。

我的作业

use clap::{Parser, Subcommand};
use std::process::exit;

#[derive(Parser)]
#[clap(name = "kvs")]
#[clap(author, version, about="an in-memory key/value store", long_about = None)]
struct Cli {
    #[clap(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
    // Set the value of a string key to a string
    #[clap(arg_required_else_help = true)]
    set {
        // the key of the value to be set
        key: String,
        // the value of the key to be set
        value: String,
    }, 

    // Get the string value of a given string key
    #[clap(arg_required_else_help = true)]
    get {
        // the key wish to query
        key: String,
    }, 

    // Remove a given key
    #[clap(arg_required_else_help = true)]
    rm {
        // the key wish to remove
        key: String,
    },
}

fn main() {
    let cli= Cli::parse();
    match &cli.command {
        Commands::get { key } => {
            eprintln!("unimplemented");
            exit(1);
        }, 
        Commands::set { key, value } => {
            eprintln!("unimplemented");
            exit(1);
        }
        Commands::rm { key } => {
            eprintln!("unimplemented");
            exit(1);
        }
    }
}

第3部分：cargo环境变量

当您设置clap来解析命令行参数时，您可能会设置名称、版本、作者和描述（如果没有，请这样做）。这些是Cargo.toml提供的冗余信息，而这些Cargo在构建时设置的环境变量可以被Rust源码访问。

修改您的clap设置以从cargo标准环境变量中设置这些值。

第4部分：将值存储在内存中

您的命令行程序已经有了雏形，现在让我们实现KvStore，以使得其余的测试用例通过。

通过阅读测试用例即可了解KvStore方法的行为 — 您不需要任何进一步的描述来完成这个项目的代码。

通过在KvStore上实现各方法使其余的测试用例通过。

我的作业：

use std::collections::HashMap;

pub struct KvStore {
    db: HashMap<String, String>,
}

impl KvStore {
    pub fn new() -> Self {
        KvStore { db: HashMap::new() }
    }

    pub fn get(&mut self, k: String) -> Option<String> {
        self.db.remove(&k)
    }

    pub fn set(&mut self, k: String, v: String) {
        self.db.insert(k, v);
    }

    pub fn remove(&mut self, k: String) {
        self.db.remove(&k);
    }
}

第5部分：文档

您已经实现了项目的功能，但是在它成为一个优秀的Rust软件之前我们还需要做一些事情，以准备好贡献或发布。

首先，公共项目通常应该有文档注释。

文档注释显示在crate的API文档中。使用命令cargo doc生成API文档，这可以将文档注释渲染为HTML并放在target/doc文件夹中。请注意，尽管target/doc文件夹不包含index.html。在本项目中，您的crate文档将位于target/doc/kvs/index.html。您可以使用cargo doc --open在该位置启动Web浏览器。cargo doc --open并不总是有效，比如，如果您通过ssh连接到云实例就无法打开。不过就算打不开浏览器，该命令仍将打印它无法打开的html的文件名 — 这会方便我们查找API文档的位置。

好的文档注释并不是是重复函数名，也不是重复从类型签名中收集到的信息。好的注释应该解释为什么以及如何使用函数，成功和失败时的返回值是什么，什么条件会触发error和panic。您编写的库非常简单，因此文档也会很简单。如果您真的想不出通过文档注释添加任何有用的内容，那么可以不添加文档注释（这是一个偏好问题）。在没有文档注释的情况下，仅从名称和类型签名就应该清楚如何使用类型或函数。

文档注释可以包含示例，而这些示例可以使用cargo test --doc进行测试。

将#![deny(missing_docs)]添加到src/lib.rs的顶部以强制所有公共项都具有文档注释。然后向您已经实现的类型和方法中添加文档注释，编写注释时请遵循文档指南。给每个函数一个例子，并确保他们通过cargo test --doc。

我的作业：

#![deny(missing_docs)]

//!
//! An in-memory key/value store.
//! Use hashmap to implement the get, set, remove behavior
//! 

use std::collections::HashMap;

/// `KvStore` structure contain a Hashmap as member `db` for manipulate key/values in memory.
pub struct KvStore {
    db: HashMap<String, String>,
}

impl KvStore {

    /// create a `KvStore`, initial an empty HashMap for member `db`.
    pub fn new() -> Self {
        KvStore { db: HashMap::new() }
    }

    /// Query HashMap in `KvStore` using key `key`.
    /// If the map did have this key present, get the corresponding `value` and return `Some(value)`. 
    /// If the map did not have this key present, return `None`.
    /// 
    /// # Example
    /// 
    /// ```rust
    /// use kvs::KvStore;
    /// 
    /// let mut store = KvStore::new();
    /// store.set("key1".to_owned(), "value1".to_owned());
    /// assert_eq!(store.get("key1".to_owned()), Some("value1".to_owned()));
    /// assert_eq!(store.get("key2".to_owned()), None);
    /// ```
    pub fn get(&self, key: String) -> Option<String> {
        match self.db.get(&key) {
            Some(value) => Some(value.to_string()),
            None => None
        }
    }
    /// Update HashMap in `KvStore` using key/value pair `key` and `value`.
    /// If the map did not have this key present, insert `key` with `value`.
    /// If the map did have this key present, the value is updated.
    /// 
    /// # Example
    /// 
    /// ```rust
    /// use kvs::KvStore;
    /// 
    /// let mut store = KvStore::new();
    /// 
    /// store.set("key1".to_owned(), "value1".to_owned());
    /// assert_eq!(store.get("key1".to_owned()), Some("value1".to_owned()));
    /// store.set("key1".to_owned(), "value2".to_owned());
    /// assert_eq!(store.get("key1".to_owned()), Some("value2".to_owned()));
    /// ```
    pub fn set(&mut self, key: String, value: String) {
        self.db.insert(key, value);
    }

    /// Removes the key `key` from HashMap in `KvStore`.
    /// 
    /// # Example
    /// 
    /// ```rust
    /// use kvs::KvStore;
    /// let mut store = KvStore::new();
    /// 
    /// store.set("key1".to_owned(), "value1".to_owned());
    /// store.remove("key1".to_owned());
    /// assert_eq!(store.get("key1".to_owned()), None);
    /// ```
    pub fn remove(&mut self, key: String) {
        self.db.remove(&key);
    }
}

第6部分：使用`clippy`和`rustfmt`规范代码

clippy和rustfmt是规范Rust代码的工具。clippy有助于确保代码风格符合规范，也能够检查出一些可能产生错误的编程模式。rustfmt会强制代码格式保持一致。在您有空的时候可以单击这些链接并阅读它们的文档。这些都是较为复杂的工具，功能远不止文中所述。

这两个工具都包含在Rust工具链中，但默认情况下不安装。可以使用以下rustup命令进行安装：

rustup component add clippy
rustup component add rustfmt

现在就试试吧。

这两个工具均以cargo子命令的形式调用，clippy使用cargo clippy、rustfmt使用cargo fmt调用。请注意，cargo fmt会修改您的源代码，因此请在运行之前提交您的工作，以避免产生意料之外的非必要修改，之后您可以再使用git commit --amend将更改作为先前提交的一部分包含在内。或者只是将它们作为自己的格式化提交 — 对于Rust来说，在一系列提交之后进行clippy和rustfmt是很常见的，比如在提交一个pull request前。

在您的项目上执行cargo clippy并按照建议修改代码。在您的项目上执行cargo fmt并提交所有更改。

建议阅读rustup、clippy和rustfmt文档，因为这些是您经常会用到的工具。

恭喜，您完成了你的第一个项目！如果您愿意，还可以试着完成下面的扩展作业，扩展作业是可选的。

此外，还可以使用下面的命令探索Rust工具链：

rustup component list
rustup component list | rg -v std # ripgrep，一个用rust编写的grep替代，`-v`即反向匹配

干得漂亮，同学，休息一下吧。

扩展1：`structopt`

在这个项目中，我们使用clap来解析命令行参数。通常将程序已解析的命令行参数表示为一个结构体，比如叫做Config或Options。这就需要调用clap的 ArgMatches类型上的相应方法。对于较大的程序，这两个步骤都需要大量模板化的代码。structoptcrate能够让您定义一个可以自动生成并注释clap命令行解释器的Config结构体，来大幅减少这些模板化代码。一些人发现使用这种方式，比显式编写clap代码更方便。

修改您的程序以使用structopt来解析命令行参数，而不是直接使用clap。

我的作业：

由于我在2022年3月初完成的作业，所以在我的Cargo.toml中声明的clap依赖已经具备了derive这一新特性。

clap = { version = "3.1.5", features = ["derive"] }

而derive特性就是装饰在某结构体上，通过宏给该结构体隐式实现各种功能。因此不再需要编写ArgMatches的相应方法，也不再需要使用structopt简化实现了：

use clap::{Parser, Subcommand};
use std::process::exit;

#[derive(Parser)]
//...
struct Cli {
    #[clap(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]
enum Commands {
//...
}

通过测试：

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests (target/debug/deps/kvs-8750b5b96d05456c)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running tests/tests.rs (target/debug/deps/tests-2241116061e67a21)

running 13 tests
test cli_get ... ok
test cli_invalid_subcommand ... ok
test cli_rm ... ok
test cli_set ... ok
test cli_no_args ... ok
test get_non_existent_value ... ok
test get_stored_value ... ok
test remove_key ... ok
test overwrite_value ... ok
test cli_version ... ok
test cli_invalid_get ... ok
test cli_invalid_rm ... ok
test cli_invalid_set ... ok

test result: ok. 13 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.35s

   Doc-tests kvs

running 3 tests
test src/lib.rs - KvStore::set (line 46) ... ok
test src/lib.rs - KvStore::get (line 28) ... ok
test src/lib.rs - KvStore::remove (line 64) ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.18s

使用rust编写高质量命令行程序

Thu, 10 Feb 2022 18:12:00 GMT

:::warning 本文内容大多翻译自原文：Write a Good CLI Program。 :::

前言

最近打算干点人事，继续入门rust。开始看pingcap提供的rust教程，Building Blocks 1引用了一篇文章写的挺好，翻译一下以备查阅。

使用rust编写高质量命令行程序

命令行界面（CLI）程序在终端上运行，这意味着没有图形界面（GUI）。

其实我们每天都在使用CLI，比如ls、ps、top 等。还有一个awesome-cli-apps收集了很多优秀的CLI程序，值得一看。我推荐exa，用rust编写的现代版ls。

命令行程序

通常，命令行程序看起来像这样：

$ ./program_name [arguments] [flags] [options]

一般我们会使用-h或--help命令以查看该命令的帮助信息。

以cargo为例：

$ cargo -h
Rust's package manager

USAGE:
    cargo [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -V, --version           Print version info and exit
        --list              List installed commands
        --explain <CODE>    Run `rustc --explain CODE`
    -v, --verbose           Use verbose output (-vv very verbose/build.rs output)
    -q, --quiet             No output printed to stdout
        --color <WHEN>      Coloring: auto, always, never
        --frozen            Require Cargo.lock and cache are up to date
        --locked            Require Cargo.lock is up to date
    -Z <FLAG>...            Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
    -h, --help              Prints help information

Some common cargo commands are (see all commands with --list):
    build       Compile the current project
    check       Analyze the current project and report errors, but don't build object files
    clean       Remove the target directory
    doc         Build this project's and its dependencies' documentation
    new         Create a new cargo project
    init        Create a new cargo project in an existing directory
    run         Build and execute src/main.rs
    test        Run the tests
    bench       Run the benchmarks
    update      Update dependencies listed in Cargo.lock
    search      Search registry for crates
    publish     Package and upload this project to the registry
    install     Install a Rust binary
    uninstall   Uninstall a Rust binary

See 'cargo help <command>' for more information on a specific command.

一目了然，如此我们就知道如何使用cargo了。

创建项目

让我们开始构建一个新的命令行程序吧！

我在这里将项目命名为meow。

$ cargo new meow
$ cd meow

参数

正如上面看到CLI的样子，CLI应有一些参数。

添加参数最简单的方法是：

// main.rs
use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();
    println!("{:?}", args);
}

$./meow a1 a2 a3
["meow", "a1", "a2", "a3"]

如此，程序即可打印参数。

不过，我摸实际使用到的CLI程序更会加复杂：

$ ./foo -g -e a1 a3 a4
$ ./foo a1 -e -l --path=~/test/123

可见这种简单的实现使用起来很不方便，因为：

参数可能有默认值
标识会交换位置
选项会交换位置
arg1可能会绑定arg2

因此，需要一个库来帮助我们轻松完成这项工作。

Clap

Clap是一个全面、高效的Rust命令行参数解析器，用法如下：

:::caution[YAML接口已废弃] 参见Deprecate Yaml API #3087，现行的clap版本已废弃YAML API，下面的例子需要使用2版本进行编译： :::

首先，创建一个cli.yml文件来设置参数。看起来像：

name: myapp
version: "1.0"
author: Kevin K. <kbknapp@gmail.com>
about: Does awesome things
args:
    - config:
        short: c
        long: config
        value_name: FILE
        help: Sets a custom config file
        takes_value: true
    - INPUT:
        help: Sets the input file to use
        required: true
        index: 1
    - verbose:
        short: v
        multiple: true
        help: Sets the level of verbosity
subcommands:
    - test:
        about: controls testing features
        version: "1.3"
        author: Someone E. <someone_else@other.com>
        args:
            - debug:
                short: d
                help: print debug information

然后我们在main.rs中添加如下代码：

#[macro_use]
extern crate clap;
use clap::App;

fn main() {
    // The YAML file is found relative to the current file, similar to how modules are found
    let yaml = load_yaml!("cli.yml");
    let m = App::from_yaml(yaml).get_matches();

     match m.value_of("argument1") {
         // ...
     }

     // ...
}

clap将加载和解析yml配置，以使得我们可以在程序中使用这些参数。

上面cli.yml加上-h的程序运行结果是：

$ meow -h
My Super Program 1.0
Kevin K. <kbknapp@gmail.com>
Does awesome things

USAGE:
    MyApp [FLAGS] [OPTIONS] <INPUT> [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -v               Sets the level of verbosity
    -V, --version    Prints version information

OPTIONS:
    -c, --config <FILE>    Sets a custom config file

ARGS:
    INPUT    The input file to use

SUBCOMMANDS:
    help    Prints this message or the help of the given subcommand(s)
    test    Controls testing features

:::tip[现行版本示例] clap现行版本（3.0.14）官方示例： :::

添加现行版依赖：

[dependencies]
clap = { version = "3.0.14", features = ["derive"] }

使用Derive API，以在编写struct时能够直接通过属性访问Builder API：

use clap::Parser;

/// Simple program to greet a person
#[derive(Parser, Debug)]
#[clap(author, version, about, long_about = None)]
struct Args {
    /// Name of the person to greet
    #[clap(short, long)]
    name: String,

    /// Number of times to greet
    #[clap(short, long, default_value_t = 1)]
    count: u8,
}

fn main() {
    let args = Args::parse();

    for _ in 0..args.count {
        println!("Hello {}!", args.name)
    }
}

观察输出：

$ demo --help
clap [..]
Simple program to greet a person

USAGE:
    demo[EXE] [OPTIONS] --name <NAME>

OPTIONS:
    -c, --count <COUNT>    Number of times to greet [default: 1]
    -h, --help             Print help information
    -n, --name <NAME>      Name of the person to greet
    -V, --version          Print version information

$ demo -n world
Hello world!

配置

CLI程序还需要配置。有些参数应当在运行前确定，并记录在配置文件中，如.env、.config、.setting。

一个.env文件的例子：

PORT = 8000
PATH = "home/foo/bar"
MODE = "happy mode"
ZONE = 8
AREA = "Beijing"

你可以选择手动处理，如：

读取文件.env
先按\n拆分每行
再按=拆分各项并将数据添加到HashMap中

或使用一个现成的crate。

dotenv_codegen

dotenv_codegen是一个带有宏的简单.env配置解析器。

使用这个crate可以轻松处理.env：

use dotenv_codegen::dotenv;

// ...

fn main() {
  println!("{}", dotenv!("PORT"));
}

注：.env是在meow根目录下的配置文件，它在编译时就被dotenv!读取，因此编译后再修改配置文件不会改变二进制文件meow的输出。

环境变量

您可能还想调用系统中的环境变量，例如JAVA_HOME：

use std::env;

let key = "HOME";
match env::var_os(key) {
    Some(val) => println!("{}: {:?}", key, val),
    None => println!("{} is not defined in the environment.", key)
}

// 打印环境变量`HOME`的值。

错误处理

最常见的：

panic!("this is panic");

这种方式过于简单：

它会直接终止程序
它在退出时没有错误代码
它通常使用在小型脚本中

使用`Result`

Result可以传递错误而不终止程序。如果函数中断，它将返回带有错误类型的Error。于是我们可以根据类型来决定下一步做什么，比如“重试”或者“放弃”。

enum MyErr {
    Reason1,
    Reason2,
}
fn foo() -> Result<(), MyErr> {
    match bar {
        Some(_)=>{}
        None => Err(MyErr::Reason1)
    }
}
fn hoo() {
    match foo() {
        Ok(_) => reply(),
        Err(e) => println!(e) 
        // 返回`e`其实还没有结束
        // 应该继续使用`fmt`明确该错误信息
    }
}

错误信息

如果我们希望为错误类型打印特定的错误信息，则需要为MyErr实现fmttrait，以使各类错误具有特定的错误信息。

enum MyErr {
    Reason1(String),
    Reason2(String, u32),
}
impl fmt::Display for MyErrError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match *self {
            MyErr::Reason1(ref s) => 
                write!(f, "`{}` is the error", s),
            MyErr::Reason2(ref s, ref num) => 
                write!(f, "`{}` and `{}` are error", s, num),
        }
    }
}

使用：

Err(e) => println!("{}", e)
// `XXX` is the error

标准错误

系统中有标准输出和标准错误。

println!()是标准输出，eprintln!()是标准错误。

例如：

$ cargo run > output.txt

如此仅将标准输出重定向到文件output.txt中。

因此，如果我们不想在output.txt文件中写入错误消息，就可以使用eprintln!()将错误打印为标准错误。

退出码

在程序有问题时使用非零退出码，以通知其他程序“我出错了”。

use std::process;

fn main() {
    process::exit(1);
}

总结

CLI程序可以胜任各种场景，而好的CLI程序需要良好的设计。CLI程序应该能解析参数和配置、读取环境变量、可以很好地处理错误、能够在标准输出和标准错误中输出相应的信息，并在执行失败时输出非零退出代码。

使用Rust在树莓派上编写操作系统 - 07 - 时间戳

Wed, 29 Dec 2021 12:00:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 07 - Timestamps；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

用SD卡上的镜像启动树莓派感觉很棒，但如果对每个新的二进制文件，都需要手动将其放在SD卡上就会非常麻烦。因此，本章我们将编写一个链式加载器。
这是我们最后一次手动拷贝镜像到SD卡上。后面的每章教程都会在Makefile中提供一个chainboot目标，以便通过UART加载内核。
我们为定时器硬件添加抽象，并在_arch/aarch64中为ARM架构实现了定时器。
新的计时器函数用于给UART打印的内容添加时间戳，并消除了GPIO设备驱动程序中由循环产生的延迟，从而提高精确性。
增加了一个warn!()宏。

测试

通过chainboot进行测试（在前一个教程中添加）：

$ make chainboot
[...]
Minipush 1.0

[MP] ⏳ Waiting for /dev/ttyUSB0
[MP] ✅ Serial connected
[MP] 🔌 Please power the target now
 __  __ _      _ _                 _
|  \/  (_)_ _ (_) |   ___  __ _ __| |
| |\/| | | ' \| | |__/ _ \/ _` / _` |
|_|  |_|_|_||_|_|____\___/\__,_\__,_|

           Raspberry Pi 3

[ML] Requesting binary
[MP] ⏩ Pushing 12 KiB =========================================🦀 100% 0 KiB/s Time: 00:00:00
[ML] Loaded! Executing the payload now

[    0.140431] mingo version 0.7.0
[    0.140630] Booting on: Raspberry Pi 3
[    0.141085] Architectural timer resolution: 52 ns
[    0.141660] Drivers loaded:
[    0.141995]       1. BCM GPIO
[    0.142353]       2. BCM PL011 UART
[W   0.142777] Spin duration smaller than architecturally supported, skipping
[    0.143621] Spinning for 1 second
[    1.144023] Spinning for 1 second
[    2.144245] Spinning for 1 second

与上一章代码的区别

diff -uNr 06_uart_chainloader/Cargo.toml 07_timestamps/Cargo.toml
--- 06_uart_chainloader/Cargo.toml
+++ 07_timestamps/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mingo"
-version = "0.6.0"
+version = "0.7.0"
 authors = ["Andre Richter <andre.o.richter@gmail.com>"]
 edition = "2021"

Binary files 06_uart_chainloader/demo_payload_rpi3.img and 07_timestamps/demo_payload_rpi3.img differ
Binary files 06_uart_chainloader/demo_payload_rpi4.img and 07_timestamps/demo_payload_rpi4.img differ

diff -uNr 06_uart_chainloader/Makefile 07_timestamps/Makefile
--- 06_uart_chainloader/Makefile
+++ 07_timestamps/Makefile
@@ -23,29 +23,27 @@

 # BSP-specific arguments.
 ifeq ($(BSP),rpi3)
-    TARGET                 = aarch64-unknown-none-softfloat
-    KERNEL_BIN             = kernel8.img
-    QEMU_BINARY            = qemu-system-aarch64
-    QEMU_MACHINE_TYPE      = raspi3
-    QEMU_RELEASE_ARGS      = -serial stdio -display none
-    OBJDUMP_BINARY         = aarch64-none-elf-objdump
-    NM_BINARY              = aarch64-none-elf-nm
-    READELF_BINARY         = aarch64-none-elf-readelf
-    LINKER_FILE            = src/bsp/raspberrypi/link.ld
-    RUSTC_MISC_ARGS        = -C target-cpu=cortex-a53
-    CHAINBOOT_DEMO_PAYLOAD = demo_payload_rpi3.img
+    TARGET            = aarch64-unknown-none-softfloat
+    KERNEL_BIN        = kernel8.img
+    QEMU_BINARY       = qemu-system-aarch64
+    QEMU_MACHINE_TYPE = raspi3
+    QEMU_RELEASE_ARGS = -serial stdio -display none
+    OBJDUMP_BINARY    = aarch64-none-elf-objdump
+    NM_BINARY         = aarch64-none-elf-nm
+    READELF_BINARY    = aarch64-none-elf-readelf
+    LINKER_FILE       = src/bsp/raspberrypi/link.ld
+    RUSTC_MISC_ARGS   = -C target-cpu=cortex-a53
 else ifeq ($(BSP),rpi4)
-    TARGET                 = aarch64-unknown-none-softfloat
-    KERNEL_BIN             = kernel8.img
-    QEMU_BINARY            = qemu-system-aarch64
-    QEMU_MACHINE_TYPE      =
-    QEMU_RELEASE_ARGS      = -serial stdio -display none
-    OBJDUMP_BINARY         = aarch64-none-elf-objdump
-    NM_BINARY              = aarch64-none-elf-nm
-    READELF_BINARY         = aarch64-none-elf-readelf
-    LINKER_FILE            = src/bsp/raspberrypi/link.ld
-    RUSTC_MISC_ARGS        = -C target-cpu=cortex-a72
-    CHAINBOOT_DEMO_PAYLOAD = demo_payload_rpi4.img
+    TARGET            = aarch64-unknown-none-softfloat
+    KERNEL_BIN        = kernel8.img
+    QEMU_BINARY       = qemu-system-aarch64
+    QEMU_MACHINE_TYPE =
+    QEMU_RELEASE_ARGS = -serial stdio -display none
+    OBJDUMP_BINARY    = aarch64-none-elf-objdump
+    NM_BINARY         = aarch64-none-elf-nm
+    READELF_BINARY    = aarch64-none-elf-readelf
+    LINKER_FILE       = src/bsp/raspberrypi/link.ld
+    RUSTC_MISC_ARGS   = -C target-cpu=cortex-a72
 endif

 QEMU_MISSING_STRING = "This board is not yet supported for QEMU."
@@ -77,7 +75,7 @@
     -O binary

 EXEC_QEMU          = $(QEMU_BINARY) -M $(QEMU_MACHINE_TYPE)
-EXEC_TEST_MINIPUSH = ruby tests/chainboot_test.rb
+EXEC_TEST_DISPATCH = ruby ../common/tests/dispatch.rb
 EXEC_MINIPUSH      = ruby ../common/serial/minipush.rb

 ##------------------------------------------------------------------------------
@@ -134,7 +132,7 @@
 ##------------------------------------------------------------------------------
 ifeq ($(QEMU_MACHINE_TYPE),) # QEMU is not supported for the board.

-qemu qemuasm:
+qemu:
 	$(call colorecho, "\n$(QEMU_MISSING_STRING)")

 else # QEMU is supported.
@@ -143,17 +141,13 @@
 	$(call colorecho, "\nLaunching QEMU")
 	@$(DOCKER_QEMU) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)

-qemuasm: $(KERNEL_BIN)
-	$(call colorecho, "\nLaunching QEMU with ASM output")
-	@$(DOCKER_QEMU) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN) -d in_asm
-
 endif

 ##------------------------------------------------------------------------------
 ## Push the kernel to the real HW target
 ##------------------------------------------------------------------------------
 chainboot: $(KERNEL_BIN)
-	@$(DOCKER_CHAINBOOT) $(EXEC_MINIPUSH) $(DEV_SERIAL) $(CHAINBOOT_DEMO_PAYLOAD)
+	@$(DOCKER_CHAINBOOT) $(EXEC_MINIPUSH) $(DEV_SERIAL) $(KERNEL_BIN)

 ##------------------------------------------------------------------------------
 ## Run clippy
@@ -217,8 +211,7 @@
 ##------------------------------------------------------------------------------
 test_boot: $(KERNEL_BIN)
 	$(call colorecho, "\nBoot test - $(BSP)")
-	@$(DOCKER_TEST) $(EXEC_TEST_MINIPUSH) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) \
-		-kernel $(KERNEL_BIN) $(CHAINBOOT_DEMO_PAYLOAD)
+	@$(DOCKER_TEST) $(EXEC_TEST_DISPATCH) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)

 test: test_boot


diff -uNr 06_uart_chainloader/src/_arch/aarch64/cpu/boot.s 07_timestamps/src/_arch/aarch64/cpu/boot.s
--- 06_uart_chainloader/src/_arch/aarch64/cpu/boot.s
+++ 07_timestamps/src/_arch/aarch64/cpu/boot.s
@@ -18,17 +18,6 @@
 	add	\register, \register, #:lo12:\symbol
 .endm

-// Load the address of a symbol into a register, absolute.
-//
-// # Resources
-//
-// - https://sourceware.org/binutils/docs-2.36/as/AArch64_002dRelocations.html
-.macro ADR_ABS register, symbol
-	movz	\register, #:abs_g2:\symbol
-	movk	\register, #:abs_g1_nc:\symbol
-	movk	\register, #:abs_g0_nc:\symbol
-.endm
-
 .equ _core_id_mask, 0b11

 //--------------------------------------------------------------------------------------------------
@@ -50,35 +39,23 @@
 	// If execution reaches here, it is the boot core.

 	// Initialize DRAM.
-	ADR_ABS	x0, __bss_start
-	ADR_ABS x1, __bss_end_exclusive
+	ADR_REL	x0, __bss_start
+	ADR_REL x1, __bss_end_exclusive

 .L_bss_init_loop:
 	cmp	x0, x1
-	b.eq	.L_relocate_binary
+	b.eq	.L_prepare_rust
 	stp	xzr, xzr, [x0], #16
 	b	.L_bss_init_loop

-	// Next, relocate the binary.
-.L_relocate_binary:
-	ADR_REL	x0, __binary_nonzero_start         // The address the binary got loaded to.
-	ADR_ABS	x1, __binary_nonzero_start         // The address the binary was linked to.
-	ADR_ABS	x2, __binary_nonzero_end_exclusive
-
-.L_copy_loop:
-	ldr	x3, [x0], #8
-	str	x3, [x1], #8
-	cmp	x1, x2
-	b.lo	.L_copy_loop
-
 	// Prepare the jump to Rust code.
+.L_prepare_rust:
 	// Set the stack pointer.
-	ADR_ABS	x0, __boot_core_stack_end_exclusive
+	ADR_REL	x0, __boot_core_stack_end_exclusive
 	mov	sp, x0

-	// Jump to the relocated Rust code.
-	ADR_ABS	x1, _start_rust
-	br	x1
+	// Jump to Rust code.
+	b	_start_rust

 	// Infinitely wait for events (aka "park the core").
 .L_parking_loop:

diff -uNr 06_uart_chainloader/src/_arch/aarch64/cpu.rs 07_timestamps/src/_arch/aarch64/cpu.rs
--- 06_uart_chainloader/src/_arch/aarch64/cpu.rs
+++ 07_timestamps/src/_arch/aarch64/cpu.rs
@@ -19,15 +19,6 @@

 pub use asm::nop;

-/// Spin for `n` cycles.
-#[cfg(feature = "bsp_rpi3")]
-#[inline(always)]
-pub fn spin_for_cycles(n: usize) {
-    for _ in 0..n {
-        asm::nop();
-    }
-}
-
 /// Pause execution on the core.
 #[inline(always)]
 pub fn wait_forever() -> ! {

diff -uNr 06_uart_chainloader/src/_arch/aarch64/time.rs 07_timestamps/src/_arch/aarch64/time.rs
--- 06_uart_chainloader/src/_arch/aarch64/time.rs
+++ 07_timestamps/src/_arch/aarch64/time.rs
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Architectural timer primitives.
+//!
+//! # Orientation
+//!
+//! Since arch modules are imported into generic modules using the path attribute, the path of this
+//! file is:
+//!
+//! crate::time::arch_time
+
+use crate::{time, warn};
+use core::time::Duration;
+use cortex_a::{asm::barrier, registers::*};
+use tock_registers::interfaces::{ReadWriteable, Readable, Writeable};
+
+//--------------------------------------------------------------------------------------------------
+// Private Definitions
+//--------------------------------------------------------------------------------------------------
+
+const NS_PER_S: u64 = 1_000_000_000;
+
+/// ARMv8 Generic Timer.
+struct GenericTimer;
+
+//--------------------------------------------------------------------------------------------------
+// Global instances
+//--------------------------------------------------------------------------------------------------
+
+static TIME_MANAGER: GenericTimer = GenericTimer;
+
+//--------------------------------------------------------------------------------------------------
+// Private Code
+//--------------------------------------------------------------------------------------------------
+
+impl GenericTimer {
+    #[inline(always)]
+    fn read_cntpct(&self) -> u64 {
+        // Prevent that the counter is read ahead of time due to out-of-order execution.
+        unsafe { barrier::isb(barrier::SY) };
+        CNTPCT_EL0.get()
+    }
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// Return a reference to the time manager.
+pub fn time_manager() -> &'static impl time::interface::TimeManager {
+    &TIME_MANAGER
+}
+
+//------------------------------------------------------------------------------
+// OS Interface Code
+//------------------------------------------------------------------------------
+
+impl time::interface::TimeManager for GenericTimer {
+    fn resolution(&self) -> Duration {
+        Duration::from_nanos(NS_PER_S / (CNTFRQ_EL0.get() as u64))
+    }
+
+    fn uptime(&self) -> Duration {
+        let current_count: u64 = self.read_cntpct() * NS_PER_S;
+        let frq: u64 = CNTFRQ_EL0.get() as u64;
+
+        Duration::from_nanos(current_count / frq)
+    }
+
+    fn spin_for(&self, duration: Duration) {
+        // Instantly return on zero.
+        if duration.as_nanos() == 0 {
+            return;
+        }
+
+        // Calculate the register compare value.
+        let frq = CNTFRQ_EL0.get();
+        let x = match frq.checked_mul(duration.as_nanos() as u64) {
+            None => {
+                warn!("Spin duration too long, skipping");
+                return;
+            }
+            Some(val) => val,
+        };
+        let tval = x / NS_PER_S;
+
+        // Check if it is within supported bounds.
+        let warn: Option<&str> = if tval == 0 {
+            Some("smaller")
+        // The upper 32 bits of CNTP_TVAL_EL0 are reserved.
+        } else if tval > u32::max_value().into() {
+            Some("bigger")
+        } else {
+            None
+        };
+
+        if let Some(w) = warn {
+            warn!(
+                "Spin duration {} than architecturally supported, skipping",
+                w
+            );
+            return;
+        }
+
+        // Set the compare value register.
+        CNTP_TVAL_EL0.set(tval);
+
+        // Kick off the counting.                       // Disable timer interrupt.
+        CNTP_CTL_EL0.modify(CNTP_CTL_EL0::ENABLE::SET + CNTP_CTL_EL0::IMASK::SET);
+
+        // ISTATUS will be '1' when cval ticks have passed. Busy-check it.
+        while !CNTP_CTL_EL0.matches_all(CNTP_CTL_EL0::ISTATUS::SET) {}
+
+        // Disable counting again.
+        CNTP_CTL_EL0.modify(CNTP_CTL_EL0::ENABLE::CLEAR);
+    }
+}

diff -uNr 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs 07_timestamps/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
--- 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
+++ 07_timestamps/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
@@ -143,25 +143,19 @@
     /// Disable pull-up/down on pins 14 and 15.
     #[cfg(feature = "bsp_rpi3")]
     fn disable_pud_14_15_bcm2837(&mut self) {
-        use crate::cpu;
+        use crate::{time, time::interface::TimeManager};
+        use core::time::Duration;

-        // Make an educated guess for a good delay value (Sequence described in the BCM2837
-        // peripherals PDF).
-        //
-        // - According to Wikipedia, the fastest RPi4 clocks around 1.5 GHz.
-        // - The Linux 2837 GPIO driver waits 1 µs between the steps.
-        //
-        // So lets try to be on the safe side and default to 2000 cycles, which would equal 1 µs
-        // would the CPU be clocked at 2 GHz.
-        const DELAY: usize = 2000;
+        // The Linux 2837 GPIO driver waits 1 µs between the steps.
+        const DELAY: Duration = Duration::from_micros(1);

         self.registers.GPPUD.write(GPPUD::PUD::Off);
-        cpu::spin_for_cycles(DELAY);
+        time::time_manager().spin_for(DELAY);

         self.registers
             .GPPUDCLK0
             .write(GPPUDCLK0::PUDCLK15::AssertClock + GPPUDCLK0::PUDCLK14::AssertClock);
-        cpu::spin_for_cycles(DELAY);
+        time::time_manager().spin_for(DELAY);

         self.registers.GPPUD.write(GPPUD::PUD::Off);
         self.registers.GPPUDCLK0.set(0);

diff -uNr 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs 07_timestamps/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
--- 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
+++ 07_timestamps/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
@@ -278,7 +278,7 @@
     }

     /// Retrieve a character.
-    fn read_char(&mut self, blocking_mode: BlockingMode) -> Option<char> {
+    fn read_char_converting(&mut self, blocking_mode: BlockingMode) -> Option<char> {
         // If RX FIFO is empty,
         if self.registers.FR.matches_all(FR::RXFE::SET) {
             // immediately return in non-blocking mode.
@@ -293,7 +293,12 @@
         }

         // Read one character.
-        let ret = self.registers.DR.get() as u8 as char;
+        let mut ret = self.registers.DR.get() as u8 as char;
+
+        // Convert carrige return to newline.
+        if ret == '\r' {
+            ret = '\n'
+        }

         // Update statistics.
         self.chars_read += 1;
@@ -373,14 +378,14 @@
 impl console::interface::Read for PL011Uart {
     fn read_char(&self) -> char {
         self.inner
-            .lock(|inner| inner.read_char(BlockingMode::Blocking).unwrap())
+            .lock(|inner| inner.read_char_converting(BlockingMode::Blocking).unwrap())
     }

     fn clear_rx(&self) {
         // Read from the RX FIFO until it is indicating empty.
         while self
             .inner
-            .lock(|inner| inner.read_char(BlockingMode::NonBlocking))
+            .lock(|inner| inner.read_char_converting(BlockingMode::NonBlocking))
             .is_some()
         {}
     }

diff -uNr 06_uart_chainloader/src/bsp/raspberrypi/link.ld 07_timestamps/src/bsp/raspberrypi/link.ld
--- 06_uart_chainloader/src/bsp/raspberrypi/link.ld
+++ 07_timestamps/src/bsp/raspberrypi/link.ld
@@ -3,6 +3,8 @@
  * Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
  */

+__rpi_phys_dram_start_addr = 0;
+
 /* The physical address at which the the kernel binary will be loaded by the Raspberry's firmware */
 __rpi_phys_binary_load_addr = 0x80000;

@@ -26,8 +28,7 @@

 SECTIONS
 {
-    /* Set the link address to 32 MiB */
-    . = 0x2000000;
+    . =  __rpi_phys_dram_start_addr;

     /***********************************************************************************************
     * Boot Core Stack
@@ -44,7 +45,6 @@
     /***********************************************************************************************
     * Code + RO Data + Global Offset Table
     ***********************************************************************************************/
-    __binary_nonzero_start = .;
     .text :
     {
         KEEP(*(.text._start))
@@ -61,10 +61,6 @@
     ***********************************************************************************************/
     .data : { *(.data*) } :segment_data

-    /* Fill up to 8 byte, b/c relocating the binary is done in u64 chunks */
-    . = ALIGN(8);
-    __binary_nonzero_end_exclusive = .;
-
     /* Section is zeroed in pairs of u64. Align start and end to 16 bytes */
     .bss (NOLOAD) : ALIGN(16)
     {

diff -uNr 06_uart_chainloader/src/bsp/raspberrypi/memory.rs 07_timestamps/src/bsp/raspberrypi/memory.rs
--- 06_uart_chainloader/src/bsp/raspberrypi/memory.rs
+++ 07_timestamps/src/bsp/raspberrypi/memory.rs
@@ -11,10 +11,9 @@
 /// The board's physical memory map.
 #[rustfmt::skip]
 pub(super) mod map {
-    pub const BOARD_DEFAULT_LOAD_ADDRESS: usize =        0x8_0000;

-    pub const GPIO_OFFSET:                usize =        0x0020_0000;
-    pub const UART_OFFSET:                usize =        0x0020_1000;
+    pub const GPIO_OFFSET:         usize = 0x0020_0000;
+    pub const UART_OFFSET:         usize = 0x0020_1000;

     /// Physical devices.
     #[cfg(feature = "bsp_rpi3")]
@@ -36,13 +35,3 @@
         pub const PL011_UART_START: usize = START + UART_OFFSET;
     }
 }
-
-//--------------------------------------------------------------------------------------------------
-// Public Code
-//--------------------------------------------------------------------------------------------------
-
-/// The address on which the Raspberry firmware loads every binary by default.
-#[inline(always)]
-pub fn board_default_load_addr() -> *const u64 {
-    map::BOARD_DEFAULT_LOAD_ADDRESS as _
-}

diff -uNr 06_uart_chainloader/src/cpu.rs 07_timestamps/src/cpu.rs
--- 06_uart_chainloader/src/cpu.rs
+++ 07_timestamps/src/cpu.rs
@@ -14,6 +14,3 @@
 // Architectural Public Reexports
 //--------------------------------------------------------------------------------------------------
 pub use arch_cpu::{nop, wait_forever};
-
-#[cfg(feature = "bsp_rpi3")]
-pub use arch_cpu::spin_for_cycles;

diff -uNr 06_uart_chainloader/src/main.rs 07_timestamps/src/main.rs
--- 06_uart_chainloader/src/main.rs
+++ 07_timestamps/src/main.rs
@@ -119,6 +119,7 @@
 mod panic_wait;
 mod print;
 mod synchronization;
+mod time;

 /// Early init code.
 ///
@@ -141,56 +142,38 @@
     kernel_main()
 }

-const MINILOAD_LOGO: &str = r#"
- __  __ _      _ _                 _
-|  \/  (_)_ _ (_) |   ___  __ _ __| |
-| |\/| | | ' \| | |__/ _ \/ _` / _` |
-|_|  |_|_|_||_|_|____\___/\__,_\__,_|
-"#;
-
 /// The main function running after the early init.
 fn kernel_main() -> ! {
-    use bsp::console::console;
-    use console::interface::All;
+    use core::time::Duration;
+    use driver::interface::DriverManager;
+    use time::interface::TimeManager;

-    println!("{}", MINILOAD_LOGO);
-    println!("{:^37}", bsp::board_name());
-    println!();
-    println!("[ML] Requesting binary");
-    console().flush();
-
-    // Discard any spurious received characters before starting with the loader protocol.
-    console().clear_rx();
-
-    // Notify `Minipush` to send the binary.
-    for _ in 0..3 {
-        console().write_char(3 as char);
+    info!(
+        "{} version {}",
+        env!("CARGO_PKG_NAME"),
+        env!("CARGO_PKG_VERSION")
+    );
+    info!("Booting on: {}", bsp::board_name());
+
+    info!(
+        "Architectural timer resolution: {} ns",
+        time::time_manager().resolution().as_nanos()
+    );
+
+    info!("Drivers loaded:");
+    for (i, driver) in bsp::driver::driver_manager()
+        .all_device_drivers()
+        .iter()
+        .enumerate()
+    {
+        info!("      {}. {}", i + 1, driver.compatible());
     }

-    // Read the binary's size.
-    let mut size: u32 = u32::from(console().read_char() as u8);
-    size |= u32::from(console().read_char() as u8) << 8;
-    size |= u32::from(console().read_char() as u8) << 16;
-    size |= u32::from(console().read_char() as u8) << 24;
-
-    // Trust it's not too big.
-    console().write_char('O');
-    console().write_char('K');
-
-    let kernel_addr: *mut u8 = bsp::memory::board_default_load_addr() as *mut u8;
-    unsafe {
-        // Read the kernel byte by byte.
-        for i in 0..size {
-            core::ptr::write_volatile(kernel_addr.offset(i as isize), console().read_char() as u8)
-        }
-    }
+    // Test a failing timer case.
+    time::time_manager().spin_for(Duration::from_nanos(1));

-    println!("[ML] Loaded! Executing the payload now\n");
-    console().flush();
-
-    // Use black magic to create a function pointer.
-    let kernel: fn() -> ! = unsafe { core::mem::transmute(kernel_addr) };
-
-    // Jump to loaded kernel!
-    kernel()
+    loop {
+        info!("Spinning for 1 second");
+        time::time_manager().spin_for(Duration::from_secs(1));
+    }
 }

diff -uNr 06_uart_chainloader/src/print.rs 07_timestamps/src/print.rs
--- 06_uart_chainloader/src/print.rs
+++ 07_timestamps/src/print.rs
@@ -36,3 +36,71 @@
         $crate::print::_print(format_args_nl!($($arg)*));
     })
 }
+
+/// Prints an info, with a newline.
+#[macro_export]
+macro_rules! info {
+    ($string:expr) => ({
+        #[allow(unused_imports)]
+        use crate::time::interface::TimeManager;
+
+        let timestamp = $crate::time::time_manager().uptime();
+        let timestamp_subsec_us = timestamp.subsec_micros();
+
+        $crate::print::_print(format_args_nl!(
+            concat!("[  {:>3}.{:03}{:03}] ", $string),
+            timestamp.as_secs(),
+            timestamp_subsec_us / 1_000,
+            timestamp_subsec_us modulo 1_000
+        ));
+    });
+    ($format_string:expr, $($arg:tt)*) => ({
+        #[allow(unused_imports)]
+        use crate::time::interface::TimeManager;
+
+        let timestamp = $crate::time::time_manager().uptime();
+        let timestamp_subsec_us = timestamp.subsec_micros();
+
+        $crate::print::_print(format_args_nl!(
+            concat!("[  {:>3}.{:03}{:03}] ", $format_string),
+            timestamp.as_secs(),
+            timestamp_subsec_us / 1_000,
+            timestamp_subsec_us modulo 1_000,
+            $($arg)*
+        ));
+    })
+}
+
+/// Prints a warning, with a newline.
+#[macro_export]
+macro_rules! warn {
+    ($string:expr) => ({
+        #[allow(unused_imports)]
+        use crate::time::interface::TimeManager;
+
+        let timestamp = $crate::time::time_manager().uptime();
+        let timestamp_subsec_us = timestamp.subsec_micros();
+
+        $crate::print::_print(format_args_nl!(
+            concat!("[W {:>3}.{:03}{:03}] ", $string),
+            timestamp.as_secs(),
+            timestamp_subsec_us / 1_000,
+            timestamp_subsec_us modulo 1_000
+        ));
+    });
+    ($format_string:expr, $($arg:tt)*) => ({
+        #[allow(unused_imports)]
+        use crate::time::interface::TimeManager;
+
+        let timestamp = $crate::time::time_manager().uptime();
+        let timestamp_subsec_us = timestamp.subsec_micros();
+
+        $crate::print::_print(format_args_nl!(
+            concat!("[W {:>3}.{:03}{:03}] ", $format_string),
+            timestamp.as_secs(),
+            timestamp_subsec_us / 1_000,
+            timestamp_subsec_us modulo 1_000,
+            $($arg)*
+        ));
+    })
+}

diff -uNr 06_uart_chainloader/src/time.rs 07_timestamps/src/time.rs
--- 06_uart_chainloader/src/time.rs
+++ 07_timestamps/src/time.rs
@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2020-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Timer primitives.
+
+#[cfg(target_arch = "aarch64")]
+#[path = "_arch/aarch64/time.rs"]
+mod arch_time;
+
+//--------------------------------------------------------------------------------------------------
+// Architectural Public Reexports
+//--------------------------------------------------------------------------------------------------
+pub use arch_time::time_manager;
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// Timekeeping interfaces.
+pub mod interface {
+    use core::time::Duration;
+
+    /// Time management functions.
+    pub trait TimeManager {
+        /// The timer's resolution.
+        fn resolution(&self) -> Duration;
+
+        /// The uptime since power-on of the device.
+        ///
+        /// This includes time consumed by firmware and bootloaders.
+        fn uptime(&self) -> Duration;
+
+        /// Spin for a given duration.
+        fn spin_for(&self, duration: Duration);
+    }
+}

diff -uNr 06_uart_chainloader/tests/boot_test_string.rb 07_timestamps/tests/boot_test_string.rb
--- 06_uart_chainloader/tests/boot_test_string.rb
+++ 07_timestamps/tests/boot_test_string.rb
@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+EXPECTED_PRINT = 'Spinning for 1 second'

diff -uNr 06_uart_chainloader/tests/chainboot_test.rb 07_timestamps/tests/chainboot_test.rb
--- 06_uart_chainloader/tests/chainboot_test.rb
+++ 07_timestamps/tests/chainboot_test.rb
@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-License-Identifier: MIT OR Apache-2.0
-#
-# Copyright (c) 2020-2021 Andre Richter <andre.o.richter@gmail.com>
-
-require_relative '../../common/serial/minipush'
-require_relative '../../common/tests/boot_test'
-require 'pty'
-
-# Match for the last print that 'demo_payload_rpiX.img' produces.
-EXPECTED_PRINT = 'Echoing input now'
-
-# Extend BootTest so that it listens on the output of a MiniPush instance, which is itself connected
-# to a QEMU instance instead of a real HW.
-class ChainbootTest < BootTest
-    MINIPUSH = '../common/serial/minipush.rb'
-    MINIPUSH_POWER_TARGET_REQUEST = 'Please power the target now'
-
-    def initialize(qemu_cmd, payload_path)
-        super(qemu_cmd, EXPECTED_PRINT)
-
-        @test_name = 'Boot test using Minipush'
-
-        @payload_path = payload_path
-    end
-
-    private
-
-    # override
-    def post_process_and_add_output(output)
-        temp = output.join.split("\r\n")
-
-        # Should a line have solo carriage returns, remove any overridden parts of the string.
-        temp.map! { |x| x.gsub(/.*\r/, '') }
-
-        @test_output += temp
-    end
-
-    def wait_for_minipush_power_request(mp_out)
-        output = []
-        Timeout.timeout(MAX_WAIT_SECS) do
-            loop do
-                output << mp_out.gets
-                break if output.last.include?(MINIPUSH_POWER_TARGET_REQUEST)
-            end
-        end
-    rescue Timeout::Error
-        @test_error = 'Timed out waiting for power request'
-    rescue StandardError => e
-        @test_error = e.message
-    ensure
-        post_process_and_add_output(output)
-    end
-
-    # override
-    def setup
-        pty_main, pty_secondary = PTY.open
-        mp_out, _mp_in = PTY.spawn("ruby #{MINIPUSH} #{pty_secondary.path} #{@payload_path}")
-
-        # Wait until MiniPush asks for powering the target.
-        wait_for_minipush_power_request(mp_out)
-
-        # Now is the time to start QEMU with the chainloader binary. QEMU's virtual tty is connected
-        # to the MiniPush instance spawned above, so that the two processes talk to each other.
-        Process.spawn(@qemu_cmd, in: pty_main, out: pty_main)
-
-        # The remainder of the test is done by the parent class' run_concrete_test, which listens on
-        # @qemu_serial. Hence, point it to MiniPush's output.
-        @qemu_serial = mp_out
-    end
-end
-
-##--------------------------------------------------------------------------------------------------
-## Execution starts here
-##--------------------------------------------------------------------------------------------------
-payload_path = ARGV.pop
-qemu_cmd = ARGV.join(' ')
-
-ChainbootTest.new(qemu_cmd, payload_path).run

diff -uNr 06_uart_chainloader/update.sh 07_timestamps/update.sh
--- 06_uart_chainloader/update.sh
+++ 07_timestamps/update.sh
@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-
-cd ../05_drivers_gpio_uart
-BSP=rpi4 make
-cp kernel8.img ../06_uart_chainloader/demo_payload_rpi4.img
-make
-cp kernel8.img ../06_uart_chainloader/demo_payload_rpi3.img
-rm kernel8.img

《腰，星际，健身房》

Sat, 27 Nov 2021 22:00:00 GMT

我那时候还太萌新，不知道所有母胎原装的部件，早已在暗中标好了使用期限。

——某猛男。

故事要从十几年前说起……本科一共四年，我就打了四年DOTA，没黑没白的那种，解锁了各种使用电脑的姿势，包括但不限于站、坐、躺、趴、卧，基本除了倒立都能来，不仅能来还能长时间保持同一个姿势进行鏖战。

我那时候还太萌新，不知道所有母胎原装的部件，早已在暗中标好了使用期限。

毕竟年轻，工作以后也偶尔会腰酸，但是我并不在意。第一次在意，应该是五年前在上海。上海夏天的室外，就两种结局：蒸死，或者被台风吹进黄浦江。于是，农闲时间我选择打游戏杀时间，其中的某一个月，我坚持每天晚上打几个小时DOTA。尽管公寓的凳子没有靠背，却也无法阻挡我推搭中单跪的热血。坚持了二十多天后，腰越来越酸。我一如既往的作死，搜了个点帖子和视频，学习并实践了几个姿势以缓解腰酸，从而辅助我继续保卫远古遗迹的伟大事业。

当然，我也是后来才知道，腰出问题的时候，要先恢复再锻炼。

第二天，腰椎就表示它崩了，以前的所有姿势都封杀了，只有绝对直立和绝对平躺可以用。我就在绝对躺平了几天后，回西安拍片子，大夫是个拥有有趣灵魂的中年大叔：“呦，小伙子没看出来啊，二十岁的年纪四十岁的腰~”……幸运的是，各方面都很平凡的我，椎间盘也并不突出，也可能是因为以前的各种姿势都解锁了，并没有长期保持同一种姿势……

为保狗命，我赶紧去办了健身卡，虽然五年来从一周六七次慢慢懒到了一周三四次，但好在一直没断。皮脂也上涨了，体重也上来了，肩也宽了背也厚了，核心更稳定了，总的来说就像个人了。于是我就飘了。

我一直喜欢暴雪，魔兽3星际2的正版我都买了，星际2更是首发就买，开无敌打剧情再赞叹暴雪爸爸做的RTS天下第一。今年我阴差阳错的追了萝卜和娜娜的星际2视频，看了大半年后，就有点饥渴难耐。

虽然今年32了，理论上已经是个体重62kg，又稳又重的中年人了。但有时候，我就是在意肚皮厚度和头发密度，我就是不服老啊。星际2是暴雪游戏里对年龄要求最低、对视力要求最低、对智力要求最低的，年轻人打得我打不得？

握了握手里的鼠标键盘，那就索性，让青春再燃烧一次吧。

9月下旬，诱人的国庆黄金周就被我用星际成就排满了，我的理由是，为了预祝中国队在TI 10上夺冠，打星际暖暖场。别管逻辑通不通，事后看来，我在DOTA背刺我之前，阴差阳错的背刺了DOTA。

星际2是个难度非常大的游戏，那几百个成就有些也非常阴间，但是我叱咤游戏几十年，心中早有觉悟。毕竟星际、红警、沙丘、帝国这批游戏，是我小学时在家属院俱乐部南边那片原初网吧里就认识的老面孔了。

今天看来，我还是轻敌了。成就很难做，APM飙到200是常有的事。休闲游戏可以靠在椅背上慢慢打，一口牛奶一口土豆片，顺便点一点鼠标键盘；DOTA这种普通游戏有打有歇，补刀的时候怠惰一点也没关系……但星际2这种高难度游戏不行，肌肉紧绷，全神贯注，脑速八千转——造农民、出建筑、攀科技、开分矿、守产能、打骚扰、抗正面——打不过去的时候研究地图和战术。这种极度充实的日子过了五十来天，除了吃饭睡觉工作以外，就是不停的操作。一个正在为自己精妙操作沾沾自喜的人，是不会在意自己已经几个小时身体前倾僵直满眼血丝死盯屏幕的，更不会在乎自己打完睡觉的时候已经手脚冰凉的像个姑娘。

萌新的能力是有极限的！我不要做萌新了！我如愿成为了一个猛男，一个成熟的指挥官，我信赖我的部队，他们给我带来了一次又一次的胜利。我了解历史，自然知道百战百胜的结果，就是力竭而亡，项王拿破仑我懂，我都懂，但是我不在乎。

嘿嘿~诶~脊椎说它在乎~

启初是11月开始的腰酸，我没在意，坚持在上旬抽空打完了所有战役成就。区区腰酸，呵，已经没有什么好怕的了。五年前我还是铁房萌新，但今天我已经成长为一个铁房猛男。作为一个成熟的撸铁男，我信赖我手中的各种杠铃和器械，它们给我带来了一块又一块的死肌肉，我解锁了撸铁的各种姿势，每次撸完还会抽出7分钟专门练核心。既然腰酸，那就撸铁的时候多加几组练背和核心！胸有惊雷而面如平湖者可拜上将军，古有周亚夫卧榻平夜惊，今有某猛男铁片治腰疼！

11月22日，我专门在单位铁房撸了一个多小时背带核心，洗完澡感觉这下稳了，可以继续我的猛男事业了，不论在星际2还是在健身房，猛男就要贯彻猛男的意志！

第二天，腰椎表示它又崩了。熟悉的感觉又回来了，所有姿势又被锁定，只有直立或平躺可用，不过这次好歹有猛男buff加持，没上次那么严重。但是精神上我是非常崩溃，一个萌新用了五年在铁房挥汗如雨的成为了猛男，不到五十天就让星际2正面突破。我可是一个猛男！猛男怎么会腰疼！

萌新的迷茫和无助也回来了，我又开始搜文献看帖和视频，进行了几天的病友情报收集：

脊椎就像底大杠，很不起眼，但也有使用寿命，也需要保养；
脊椎附近的组织类似韧带，供血较少，尤其9-11月供暖前天气寒冷会进一步减少组织供血；
供血少意味着恢复慢，一旦有损伤就应该立刻静养；
恢复之后再加强锻炼，并改掉损伤脊椎的姿势。

所有的雷我又趟了一遍，猛男不是无敌，猛男更应该爱惜自己的肉体。这几天状态恢复了些，打算静卧两周再去铁房老老实实做萌新。

我这个人啊，上了年纪就老想找机会证明自己还年轻。但是，人和人的天赋是有差距的，尤其是精力的差距，基本决定了功业的差距，特别是我这种死宅，精力槽基本为0，更应该看清自己假猛男真萌新的本质。正所谓自知者明，先为不可胜以待敌之可胜，不作死就不会死。

星际2是个好游戏，尤其是哲学这一块，神族粪坑流、虫族泉水沟、人族城市化，无一不是孙子兵法的最佳实践。我还是太萌新了，只玩到操作层和战术层，后面的战略层和哲学层完全没有入门。以后的日子更应该谨慎的开发腰、星际、健身房的更深层次内涵。

我一定要时刻提醒自己永远都只能是一个萌新这一事实，不论什么岁数，什么状态，什么境界，都要坚定的走在成为猛男的道路上，风霜雨雪，披荆斩棘，老兵不死，stay young, stay alive。

另外：大家秋冬季节一定要保护好自己的小腰！

完。

使用Rust在树莓派上编写操作系统 - 06 - UART的链式加载

Mon, 30 Aug 2021 22:00:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 06 - UART Chainloader；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

用SD卡上的镜像启动树莓派感觉很棒，但如果对每个新的二进制文件，都需要手动将其放在SD卡上就会非常麻烦。因此，本章我们将编写一个链式加载器。
这是我们最后一次手动拷贝镜像到SD卡上。后面的每章教程都会在Makefile中提供一个chainboot目标，以便通过UART加载内核。

注意

请注意，若仅查看源码差异，则很难掌握本章教程中出现的一些新功能。

关键就在boot.s中，我们正在编写一段位置无关代码，代码能够自动确定固件从什么位置(0x8_0000)加载二进制文件，以及应当链接到什么位置(0x200_0000，请参阅link.ld)。然后二进制文件将自身从加载地址复制到链接地址（即“重定位”自身），再跳转到重定位版本的_start_rust()中。

由于链式加载器自己已经“让出位置”，它现在就可以从UART接收另一个内核二进制文件，并将其复制到树莓派固件的标准加载地址0x8_0000。最后，它跳转到0x8_0000再透明的执行新加载的二进制文件，仿佛该文件是从SD卡中加载似的。

请耐心等待，等我一有时间，就会将这个过程写成详尽的文档。不过目前，请参阅本章教程看做一个方便的启动器，该驱动器允许我们快速启动后续教程章节中新的内核二进制文件。

安装并测试

我们的链式加载器叫做MiniLoad，其灵感来自raspbootin。

在本章教程中试用MiniLoad：

根据目标硬件，运行：make或者BSP=rpi4 make。
将kernel8.img复制到SD卡，并将SD卡插回到树莓派。
根据目标硬件，运行make chainboot或者BSP=rpi4 make chainboot。
连接USB串口线到宿主PC。
- 按照本项目的根README接线。
- 一定确保没有连接USB串口的电源引脚。只连接了RX/TX和GND。
为树莓派连接(USB)电源。
观察加载程序通过UART获取内核：

❗注意：make chainboot的默认串行设备名称为/dev/ttyUSB0。对于不同操作系统的宿主机，设备名称可能会有所不同。例如，在macOS上，名称可能类似于/dev/tty.usbserial-0001。这种情况下，需要明确给出名称：

$ DEV_SERIAL=/dev/tty.usbserial-0001 make chainboot

$ make chainboot
[...]
Minipush 1.0

[MP] ⏳ Waiting for /dev/ttyUSB0
[MP] ✅ Serial connected
[MP] 🔌 Please power the target now
 __  __ _      _ _                 _
|  \/  (_)_ _ (_) |   ___  __ _ __| |
| |\/| | | ' \| | |__/ _ \/ _` / _` |
|_|  |_|_|_||_|_|____\___/\__,_\__,_|

           Raspberry Pi 3

[ML] Requesting binary
[MP] ⏩ Pushing 6 KiB ==========================================🦀 100% 0 KiB/s Time: 00:00:00
[ML] Loaded! Executing the payload now

[0] mingo version 0.5.0
[1] Booting on: Raspberry Pi 3
[2] Drivers loaded:
      1. BCM GPIO
      2. BCM PL011 UART
[3] Chars written: 117
[4] Echoing input now

实验

本章教程中的Makefile有一个额外的目标——qemuasm——可以让您更好地观察内核内核在重定位后，是如何从加载地址0x80_XXX跳转到位于0x0200_0XXX的重定位代码处的：

$ make qemuasm
[...]
N:
0x00080030:  58000140  ldr      x0, #0x80058
0x00080034:  9100001f  mov      sp, x0
0x00080038:  58000141  ldr      x1, #0x80060
0x0008003c:  d61f0020  br       x1

----------------
IN:
0x02000070:  9400044c  bl       #0x20011a0

----------------
IN:
0x020011a0:  90000008  adrp     x8, #0x2001000
0x020011a4:  90000009  adrp     x9, #0x2001000
0x020011a8:  f9446508  ldr      x8, [x8, #0x8c8]
0x020011ac:  f9446929  ldr      x9, [x9, #0x8d0]
0x020011b0:  eb08013f  cmp      x9, x8
0x020011b4:  54000109  b.ls     #0x20011d4
[...]

与上一章代码的区别

diff -uNr 05_drivers_gpio_uart/Cargo.toml 06_uart_chainloader/Cargo.toml
--- 05_drivers_gpio_uart/Cargo.toml
+++ 06_uart_chainloader/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mingo"
-version = "0.5.0"
+version = "0.6.0"
 authors = ["Andre Richter <andre.o.richter@gmail.com>"]
 edition = "2021"

Binary files 05_drivers_gpio_uart/demo_payload_rpi3.img and 06_uart_chainloader/demo_payload_rpi3.img differ
Binary files 05_drivers_gpio_uart/demo_payload_rpi4.img and 06_uart_chainloader/demo_payload_rpi4.img differ

diff -uNr 05_drivers_gpio_uart/Makefile 06_uart_chainloader/Makefile
--- 05_drivers_gpio_uart/Makefile
+++ 06_uart_chainloader/Makefile
@@ -23,27 +23,29 @@

 # BSP-specific arguments.
 ifeq ($(BSP),rpi3)
-    TARGET            = aarch64-unknown-none-softfloat
-    KERNEL_BIN        = kernel8.img
-    QEMU_BINARY       = qemu-system-aarch64
-    QEMU_MACHINE_TYPE = raspi3
-    QEMU_RELEASE_ARGS = -serial stdio -display none
-    OBJDUMP_BINARY    = aarch64-none-elf-objdump
-    NM_BINARY         = aarch64-none-elf-nm
-    READELF_BINARY    = aarch64-none-elf-readelf
-    LINKER_FILE       = src/bsp/raspberrypi/link.ld
-    RUSTC_MISC_ARGS   = -C target-cpu=cortex-a53
+    TARGET                 = aarch64-unknown-none-softfloat
+    KERNEL_BIN             = kernel8.img
+    QEMU_BINARY            = qemu-system-aarch64
+    QEMU_MACHINE_TYPE      = raspi3
+    QEMU_RELEASE_ARGS      = -serial stdio -display none
+    OBJDUMP_BINARY         = aarch64-none-elf-objdump
+    NM_BINARY              = aarch64-none-elf-nm
+    READELF_BINARY         = aarch64-none-elf-readelf
+    LINKER_FILE            = src/bsp/raspberrypi/link.ld
+    RUSTC_MISC_ARGS        = -C target-cpu=cortex-a53
+    CHAINBOOT_DEMO_PAYLOAD = demo_payload_rpi3.img
 else ifeq ($(BSP),rpi4)
-    TARGET            = aarch64-unknown-none-softfloat
-    KERNEL_BIN        = kernel8.img
-    QEMU_BINARY       = qemu-system-aarch64
-    QEMU_MACHINE_TYPE =
-    QEMU_RELEASE_ARGS = -serial stdio -display none
-    OBJDUMP_BINARY    = aarch64-none-elf-objdump
-    NM_BINARY         = aarch64-none-elf-nm
-    READELF_BINARY    = aarch64-none-elf-readelf
-    LINKER_FILE       = src/bsp/raspberrypi/link.ld
-    RUSTC_MISC_ARGS   = -C target-cpu=cortex-a72
+    TARGET                 = aarch64-unknown-none-softfloat
+    KERNEL_BIN             = kernel8.img
+    QEMU_BINARY            = qemu-system-aarch64
+    QEMU_MACHINE_TYPE      =
+    QEMU_RELEASE_ARGS      = -serial stdio -display none
+    OBJDUMP_BINARY         = aarch64-none-elf-objdump
+    NM_BINARY              = aarch64-none-elf-nm
+    READELF_BINARY         = aarch64-none-elf-readelf
+    LINKER_FILE            = src/bsp/raspberrypi/link.ld
+    RUSTC_MISC_ARGS        = -C target-cpu=cortex-a72
+    CHAINBOOT_DEMO_PAYLOAD = demo_payload_rpi4.img
 endif

 QEMU_MISSING_STRING = "This board is not yet supported for QEMU."
@@ -75,8 +77,8 @@
     -O binary

 EXEC_QEMU          = $(QEMU_BINARY) -M $(QEMU_MACHINE_TYPE)
-EXEC_TEST_DISPATCH = ruby ../common/tests/dispatch.rb
-EXEC_MINITERM      = ruby ../common/serial/miniterm.rb
+EXEC_TEST_MINIPUSH = ruby tests/chainboot_test.rb
+EXEC_MINIPUSH      = ruby ../common/serial/minipush.rb

 ##------------------------------------------------------------------------------
 ## Dockerization
@@ -95,7 +97,7 @@
 ifeq ($(shell uname -s),Linux)
     DOCKER_CMD_DEV = $(DOCKER_CMD_INTERACT) $(DOCKER_ARG_DEV)

-    DOCKER_MINITERM = $(DOCKER_CMD_DEV) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)
+    DOCKER_CHAINBOOT = $(DOCKER_CMD_DEV) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)
 endif


@@ -103,7 +105,7 @@
 ##--------------------------------------------------------------------------------------------------
 ## Targets
 ##--------------------------------------------------------------------------------------------------
-.PHONY: all $(KERNEL_ELF) $(KERNEL_BIN) doc qemu miniterm clippy clean readelf objdump nm check
+.PHONY: all $(KERNEL_ELF) $(KERNEL_BIN) doc qemu chainboot clippy clean readelf objdump nm check

 all: $(KERNEL_BIN)

@@ -132,7 +134,7 @@
 ##------------------------------------------------------------------------------
 ifeq ($(QEMU_MACHINE_TYPE),) # QEMU is not supported for the board.

-qemu:
+qemu qemuasm:
 	$(call colorecho, "\n$(QEMU_MISSING_STRING)")

 else # QEMU is supported.
@@ -140,13 +142,18 @@
 qemu: $(KERNEL_BIN)
 	$(call colorecho, "\nLaunching QEMU")
 	@$(DOCKER_QEMU) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)
+
+qemuasm: $(KERNEL_BIN)
+	$(call colorecho, "\nLaunching QEMU with ASM output")
+	@$(DOCKER_QEMU) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN) -d in_asm
+
 endif

 ##------------------------------------------------------------------------------
-## Connect to the target's serial
+## Push the kernel to the real HW target
 ##------------------------------------------------------------------------------
-miniterm:
-	@$(DOCKER_MINITERM) $(EXEC_MINITERM) $(DEV_SERIAL)
+chainboot: $(KERNEL_BIN)
+	@$(DOCKER_CHAINBOOT) $(EXEC_MINIPUSH) $(DEV_SERIAL) $(CHAINBOOT_DEMO_PAYLOAD)

 ##------------------------------------------------------------------------------
 ## Run clippy
@@ -210,7 +217,8 @@
 ##------------------------------------------------------------------------------
 test_boot: $(KERNEL_BIN)
 	$(call colorecho, "\nBoot test - $(BSP)")
-	@$(DOCKER_TEST) $(EXEC_TEST_DISPATCH) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)
+	@$(DOCKER_TEST) $(EXEC_TEST_MINIPUSH) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) \
+		-kernel $(KERNEL_BIN) $(CHAINBOOT_DEMO_PAYLOAD)

 test: test_boot


diff -uNr 05_drivers_gpio_uart/src/_arch/aarch64/cpu/boot.s 06_uart_chainloader/src/_arch/aarch64/cpu/boot.s
--- 05_drivers_gpio_uart/src/_arch/aarch64/cpu/boot.s
+++ 06_uart_chainloader/src/_arch/aarch64/cpu/boot.s
@@ -18,6 +18,17 @@
 	add	\register, \register, #:lo12:\symbol
 .endm

+// Load the address of a symbol into a register, absolute.
+//
+// # Resources
+//
+// - https://sourceware.org/binutils/docs-2.36/as/AArch64_002dRelocations.html
+.macro ADR_ABS register, symbol
+	movz	\register, #:abs_g2:\symbol
+	movk	\register, #:abs_g1_nc:\symbol
+	movk	\register, #:abs_g0_nc:\symbol
+.endm
+
 .equ _core_id_mask, 0b11

 //--------------------------------------------------------------------------------------------------
@@ -39,23 +50,35 @@
 	// If execution reaches here, it is the boot core.

 	// Initialize DRAM.
-	ADR_REL	x0, __bss_start
-	ADR_REL x1, __bss_end_exclusive
+	ADR_ABS	x0, __bss_start
+	ADR_ABS x1, __bss_end_exclusive

 .L_bss_init_loop:
 	cmp	x0, x1
-	b.eq	.L_prepare_rust
+	b.eq	.L_relocate_binary
 	stp	xzr, xzr, [x0], #16
 	b	.L_bss_init_loop

+	// Next, relocate the binary.
+.L_relocate_binary:
+	ADR_REL	x0, __binary_nonzero_start         // The address the binary got loaded to.
+	ADR_ABS	x1, __binary_nonzero_start         // The address the binary was linked to.
+	ADR_ABS	x2, __binary_nonzero_end_exclusive
+
+.L_copy_loop:
+	ldr	x3, [x0], #8
+	str	x3, [x1], #8
+	cmp	x1, x2
+	b.lo	.L_copy_loop
+
 	// Prepare the jump to Rust code.
-.L_prepare_rust:
 	// Set the stack pointer.
-	ADR_REL	x0, __boot_core_stack_end_exclusive
+	ADR_ABS	x0, __boot_core_stack_end_exclusive
 	mov	sp, x0

-	// Jump to Rust code.
-	b	_start_rust
+	// Jump to the relocated Rust code.
+	ADR_ABS	x1, _start_rust
+	br	x1

 	// Infinitely wait for events (aka "park the core").
 .L_parking_loop:

diff -uNr 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
--- 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
+++ 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
@@ -148,7 +148,7 @@
         // Make an educated guess for a good delay value (Sequence described in the BCM2837
         // peripherals PDF).
         //
-        // - According to Wikipedia, the fastest Pi3 clocks around 1.4 GHz.
+        // - According to Wikipedia, the fastest RPi4 clocks around 1.5 GHz.
         // - The Linux 2837 GPIO driver waits 1 µs between the steps.
         //
         // So lets try to be on the safe side and default to 2000 cycles, which would equal 1 µs

diff -uNr 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
--- 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
+++ 06_uart_chainloader/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
@@ -278,7 +278,7 @@
     }

     /// Retrieve a character.
-    fn read_char_converting(&mut self, blocking_mode: BlockingMode) -> Option<char> {
+    fn read_char(&mut self, blocking_mode: BlockingMode) -> Option<char> {
         // If RX FIFO is empty,
         if self.registers.FR.matches_all(FR::RXFE::SET) {
             // immediately return in non-blocking mode.
@@ -293,12 +293,7 @@
         }

         // Read one character.
-        let mut ret = self.registers.DR.get() as u8 as char;
-
-        // Convert carrige return to newline.
-        if ret == '\r' {
-            ret = '\n'
-        }
+        let ret = self.registers.DR.get() as u8 as char;

         // Update statistics.
         self.chars_read += 1;
@@ -378,14 +373,14 @@
 impl console::interface::Read for PL011Uart {
     fn read_char(&self) -> char {
         self.inner
-            .lock(|inner| inner.read_char_converting(BlockingMode::Blocking).unwrap())
+            .lock(|inner| inner.read_char(BlockingMode::Blocking).unwrap())
     }

     fn clear_rx(&self) {
         // Read from the RX FIFO until it is indicating empty.
         while self
             .inner
-            .lock(|inner| inner.read_char_converting(BlockingMode::NonBlocking))
+            .lock(|inner| inner.read_char(BlockingMode::NonBlocking))
             .is_some()
         {}
     }

diff -uNr 05_drivers_gpio_uart/src/bsp/raspberrypi/link.ld 06_uart_chainloader/src/bsp/raspberrypi/link.ld
--- 05_drivers_gpio_uart/src/bsp/raspberrypi/link.ld
+++ 06_uart_chainloader/src/bsp/raspberrypi/link.ld
@@ -3,8 +3,6 @@
  * Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
  */

-__rpi_phys_dram_start_addr = 0;
-
 /* The physical address at which the the kernel binary will be loaded by the Raspberry's firmware */
 __rpi_phys_binary_load_addr = 0x80000;

@@ -28,7 +26,8 @@

 SECTIONS
 {
-    . =  __rpi_phys_dram_start_addr;
+    /* Set the link address to 32 MiB */
+    . = 0x2000000;

     /***********************************************************************************************
     * Boot Core Stack
@@ -45,6 +44,7 @@
     /***********************************************************************************************
     * Code + RO Data + Global Offset Table
     ***********************************************************************************************/
+    __binary_nonzero_start = .;
     .text :
     {
         KEEP(*(.text._start))
@@ -61,6 +61,10 @@
     ***********************************************************************************************/
     .data : { *(.data*) } :segment_data

+    /* Fill up to 8 byte, b/c relocating the binary is done in u64 chunks */
+    . = ALIGN(8);
+    __binary_nonzero_end_exclusive = .;
+
     /* Section is zeroed in pairs of u64. Align start and end to 16 bytes */
     .bss (NOLOAD) : ALIGN(16)
     {

diff -uNr 05_drivers_gpio_uart/src/bsp/raspberrypi/memory.rs 06_uart_chainloader/src/bsp/raspberrypi/memory.rs
--- 05_drivers_gpio_uart/src/bsp/raspberrypi/memory.rs
+++ 06_uart_chainloader/src/bsp/raspberrypi/memory.rs
@@ -11,9 +11,10 @@
 /// The board's physical memory map.
 #[rustfmt::skip]
 pub(super) mod map {
+    pub const BOARD_DEFAULT_LOAD_ADDRESS: usize =        0x8_0000;

-    pub const GPIO_OFFSET:         usize = 0x0020_0000;
-    pub const UART_OFFSET:         usize = 0x0020_1000;
+    pub const GPIO_OFFSET:                usize =        0x0020_0000;
+    pub const UART_OFFSET:                usize =        0x0020_1000;

     /// Physical devices.
     #[cfg(feature = "bsp_rpi3")]
@@ -35,3 +36,13 @@
         pub const PL011_UART_START: usize = START + UART_OFFSET;
     }
 }
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// The address on which the Raspberry firmware loads every binary by default.
+#[inline(always)]
+pub fn board_default_load_addr() -> *const u64 {
+    map::BOARD_DEFAULT_LOAD_ADDRESS as _
+}

diff -uNr 05_drivers_gpio_uart/src/main.rs 06_uart_chainloader/src/main.rs
--- 05_drivers_gpio_uart/src/main.rs
+++ 06_uart_chainloader/src/main.rs
@@ -141,38 +141,56 @@
     kernel_main()
 }

+const MINILOAD_LOGO: &str = r#"
+ __  __ _      _ _                 _
+|  \/  (_)_ _ (_) |   ___  __ _ __| |
+| |\/| | | ' \| | |__/ _ \/ _` / _` |
+|_|  |_|_|_||_|_|____\___/\__,_\__,_|
+"#;
+
 /// The main function running after the early init.
 fn kernel_main() -> ! {
     use bsp::console::console;
     use console::interface::All;
-    use driver::interface::DriverManager;

-    println!(
-        "[0] {} version {}",
-        env!("CARGO_PKG_NAME"),
-        env!("CARGO_PKG_VERSION")
-    );
-    println!("[1] Booting on: {}", bsp::board_name());
-
-    println!("[2] Drivers loaded:");
-    for (i, driver) in bsp::driver::driver_manager()
-        .all_device_drivers()
-        .iter()
-        .enumerate()
-    {
-        println!("      {}. {}", i + 1, driver.compatible());
+    println!("{}", MINILOAD_LOGO);
+    println!("{:^37}", bsp::board_name());
+    println!();
+    println!("[ML] Requesting binary");
+    console().flush();
+
+    // Discard any spurious received characters before starting with the loader protocol.
+    console().clear_rx();
+
+    // Notify `Minipush` to send the binary.
+    for _ in 0..3 {
+        console().write_char(3 as char);
     }

-    println!(
-        "[3] Chars written: {}",
-        bsp::console::console().chars_written()
-    );
-    println!("[4] Echoing input now");
+    // Read the binary's size.
+    let mut size: u32 = u32::from(console().read_char() as u8);
+    size |= u32::from(console().read_char() as u8) << 8;
+    size |= u32::from(console().read_char() as u8) << 16;
+    size |= u32::from(console().read_char() as u8) << 24;

-    // Discard any spurious received characters before going into echo mode.
-    console().clear_rx();
-    loop {
-        let c = bsp::console::console().read_char();
-        bsp::console::console().write_char(c);
+    // Trust it's not too big.
+    console().write_char('O');
+    console().write_char('K');
+
+    let kernel_addr: *mut u8 = bsp::memory::board_default_load_addr() as *mut u8;
+    unsafe {
+        // Read the kernel byte by byte.
+        for i in 0..size {
+            core::ptr::write_volatile(kernel_addr.offset(i as isize), console().read_char() as u8)
+        }
     }
+
+    println!("[ML] Loaded! Executing the payload now\n");
+    console().flush();
+
+    // Use black magic to create a function pointer.
+    let kernel: fn() -> ! = unsafe { core::mem::transmute(kernel_addr) };
+
+    // Jump to loaded kernel!
+    kernel()
 }

diff -uNr 05_drivers_gpio_uart/tests/boot_test_string.rb 06_uart_chainloader/tests/boot_test_string.rb
--- 05_drivers_gpio_uart/tests/boot_test_string.rb
+++ 06_uart_chainloader/tests/boot_test_string.rb
@@ -1,3 +0,0 @@
-# frozen_string_literal: true
-
-EXPECTED_PRINT = 'Echoing input now'

diff -uNr 05_drivers_gpio_uart/tests/chainboot_test.rb 06_uart_chainloader/tests/chainboot_test.rb
--- 05_drivers_gpio_uart/tests/chainboot_test.rb
+++ 06_uart_chainloader/tests/chainboot_test.rb
@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT OR Apache-2.0
+#
+# Copyright (c) 2020-2021 Andre Richter <andre.o.richter@gmail.com>
+
+require_relative '../../common/serial/minipush'
+require_relative '../../common/tests/boot_test'
+require 'pty'
+
+# Match for the last print that 'demo_payload_rpiX.img' produces.
+EXPECTED_PRINT = 'Echoing input now'
+
+# Extend BootTest so that it listens on the output of a MiniPush instance, which is itself connected
+# to a QEMU instance instead of a real HW.
+class ChainbootTest < BootTest
+    MINIPUSH = '../common/serial/minipush.rb'
+    MINIPUSH_POWER_TARGET_REQUEST = 'Please power the target now'
+
+    def initialize(qemu_cmd, payload_path)
+        super(qemu_cmd, EXPECTED_PRINT)
+
+        @test_name = 'Boot test using Minipush'
+
+        @payload_path = payload_path
+    end
+
+    private
+
+    # override
+    def post_process_and_add_output(output)
+        temp = output.join.split("\r\n")
+
+        # Should a line have solo carriage returns, remove any overridden parts of the string.
+        temp.map! { |x| x.gsub(/.*\r/, '') }
+
+        @test_output += temp
+    end
+
+    def wait_for_minipush_power_request(mp_out)
+        output = []
+        Timeout.timeout(MAX_WAIT_SECS) do
+            loop do
+                output << mp_out.gets
+                break if output.last.include?(MINIPUSH_POWER_TARGET_REQUEST)
+            end
+        end
+    rescue Timeout::Error
+        @test_error = 'Timed out waiting for power request'
+    rescue StandardError => e
+        @test_error = e.message
+    ensure
+        post_process_and_add_output(output)
+    end
+
+    # override
+    def setup
+        pty_main, pty_secondary = PTY.open
+        mp_out, _mp_in = PTY.spawn("ruby #{MINIPUSH} #{pty_secondary.path} #{@payload_path}")
+
+        # Wait until MiniPush asks for powering the target.
+        wait_for_minipush_power_request(mp_out)
+
+        # Now is the time to start QEMU with the chainloader binary. QEMU's virtual tty is connected
+        # to the MiniPush instance spawned above, so that the two processes talk to each other.
+        Process.spawn(@qemu_cmd, in: pty_main, out: pty_main)
+
+        # The remainder of the test is done by the parent class' run_concrete_test, which listens on
+        # @qemu_serial. Hence, point it to MiniPush's output.
+        @qemu_serial = mp_out
+    end
+end
+
+##--------------------------------------------------------------------------------------------------
+## Execution starts here
+##--------------------------------------------------------------------------------------------------
+payload_path = ARGV.pop
+qemu_cmd = ARGV.join(' ')
+
+ChainbootTest.new(qemu_cmd, payload_path).run

diff -uNr 05_drivers_gpio_uart/update.sh 06_uart_chainloader/update.sh
--- 05_drivers_gpio_uart/update.sh
+++ 06_uart_chainloader/update.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+cd ../05_drivers_gpio_uart
+BSP=rpi4 make
+cp kernel8.img ../06_uart_chainloader/demo_payload_rpi4.img
+make
+cp kernel8.img ../06_uart_chainloader/demo_payload_rpi3.img
+rm kernel8.img

使用Rust在树莓派上编写操作系统 - 05 - 驱动GPIO和UART

Sun, 08 Aug 2021 22:00:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 05 - Drivers: GPIO and UART；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

既然我们在上一章教程中已经准备好了基础设施——启用了安全全局变量——那么现在就可以为第一个真实设备添加驱动程序了。
现在我们可以离开神奇的QEMU控制台，来使用真正的UART设备了，就像正经的嵌入式开发者那样。

需要注意的新增代码

这是我们首次在真实的硬件上运行代码。
- 因此，现在的构建编译分为RPi3和RPi4两个版本。
- 默认情况下，所有Makefile项都以RPi3为目标进行构建。
- 如果需要以RPi4为构建目标，需要在每个构建项前面添加BSP=rpi4。例如： -BSP=rpi4 make -BSP=rpi4 make doc
- 不过QEMU目前还不支持RPi4，因此BSP=rpi4 make qemu将无法正常工作。
添加了driver::interface::DeviceDrivertrait，以从内核代码中抽象出BSP驱动程序实现。
驱动程序存储在src/bsp/device_driver中，并且可以在BSP之间重用。
- 我们引入了GPIO驱动，实现了对RPi的PL011 UART引脚的多路复用（pinmux即，将信号从SoC内部路由到实际的硬件引脚）。
  - 请注意此驱动程序如何区分RPi3和RPi4。由于二者使用了不同的硬件，所以我们也需要在软件中考虑这种不同。
- 其中的关键在于PL011Uart驱动：它实现了console::interface::*trait，而且从现在开始，它被用作主系统的控制台输出。
src/bsp/raspberrypi/memory.rs中的BSP现在具有一个内存映射。在特定情况下，映射包含了树莓派的MMIO地址，用于实例化相应设备的驱动程序。
我们也修改了panic!处理程序，以使其不再依赖println!，panic现在使用的全局共享实例UART，不过遇到异常时，该实例有可能正处于锁定状态（由于目前使用的是NullLock实现，并不会出现这种锁的问题，但是如果是使用一个真实锁的实现，将会出现这种问题）。
- 所以，为了避免变量被锁占用，现在的代码将会创建一个新的UART驱动实例，重新初始化设备，并使用这个新实例进行打印。这增加了系统在挂起之前能够打印出最后的重要消息的机会。

从SD卡启动

需要注意的是，在使用SD卡启动时，RPi3和RPi4的准备步骤有所不同。

通用步骤

创建一个名为boot的FAT32格式分区。
在SD卡上，新建一个名为config.txt的文件，内容如下：

arm_64bit=1
init_uart_clock=48000000

Pi 3

将Raspberry Pi固件仓库中的下列文件复制到SD卡上：

执行make。

Pi 4

将Raspberry Pi固件仓库中的下列文件复制到SD卡上：

执行BSP=rpi4 make。

Note: 如果上述步骤在你的RPi4上不起作用，请尝试将SD卡上的start4.elf重命名为start.elf（即去掉4）。

通用步骤（续）

将文件kernel8.img复制到SD卡上，插回RPi。
执行miniterm项，就会在主机上打开UART设备：

$ make miniterm

❗注意：Miniterm的默认串行设备名称为/dev/ttyUSB0。对于不同操作系统的宿主机，设备名称可能会有所不同。例如，在macOS上，名称可能类似于/dev/tty.usbserial-0001。这种情况下，需要明确给出名称：

$ DEV_SERIAL=/dev/tty.usbserial-0001 make miniterm

将USB串口线连接到宿主机PC。

按照本教程初始的README中的接线图连接引脚。
请确认没有连接USB串口线的电源引脚，仅连接了RX/TX和GND三个引脚。

将RPi接上电源电源线（miniUSB电源）并观察输出：

Miniterm 1.0

[MT] ⏳ Waiting for /dev/ttyUSB0
[MT] ✅ Serial connected
[0] mingo version 0.5.0
[1] Booting on: Raspberry Pi 3
[2] Drivers loaded:
      1. BCM GPIO
      2. BCM PL011 UART
[3] Chars written: 117
[4] Echoing input now

使用<kbd>ctrl-c</kbd>键退出。

与上一章代码的区别

diff -uNr 04_safe_globals/Cargo.toml 05_drivers_gpio_uart/Cargo.toml
--- 04_safe_globals/Cargo.toml
+++ 05_drivers_gpio_uart/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mingo"
-version = "0.4.0"
+version = "0.5.0"
 authors = ["Andre Richter <andre.o.richter@gmail.com>"]
 edition = "2018"

@@ -9,8 +9,8 @@

 [features]
 default = []
-bsp_rpi3 = []
-bsp_rpi4 = []
+bsp_rpi3 = ["tock-registers"]
+bsp_rpi4 = ["tock-registers"]

 [[bin]]
 name = "kernel"
@@ -22,6 +22,9 @@

 [dependencies]

+# Optional dependencies
+tock-registers = { version = "0.7.x", default-features = false, features = ["register_types"], optional = true }
+
 # Platform specific dependencies
 [target.'cfg(target_arch = "aarch64")'.dependencies]
 cortex-a = { version = "6.x.x" }

diff -uNr 04_safe_globals/Makefile 05_drivers_gpio_uart/Makefile
--- 04_safe_globals/Makefile
+++ 05_drivers_gpio_uart/Makefile
@@ -11,6 +11,9 @@
 # Default to the RPi3.
 BSP ?= rpi3

+# Default to a serial device name that is common in Linux.
+DEV_SERIAL ?= /dev/ttyUSB0
+


 ##--------------------------------------------------------------------------------------------------
@@ -72,6 +75,7 @@

 EXEC_QEMU          = $(QEMU_BINARY) -M $(QEMU_MACHINE_TYPE)
 EXEC_TEST_DISPATCH = ruby ../common/tests/dispatch.rb
+EXEC_MINITERM      = ruby ../common/serial/miniterm.rb

 ##------------------------------------------------------------------------------
 ## Dockerization
@@ -80,17 +84,25 @@
 DOCKER_CMD            = docker run -t --rm -v $(shell pwd):/work/tutorial -w /work/tutorial
 DOCKER_CMD_INTERACT   = $(DOCKER_CMD) -i
 DOCKER_ARG_DIR_COMMON = -v $(shell pwd)/../common:/work/common
+DOCKER_ARG_DEV        = --privileged -v /dev:/dev

 DOCKER_QEMU  = $(DOCKER_CMD_INTERACT) $(DOCKER_IMAGE)
 DOCKER_TOOLS = $(DOCKER_CMD) $(DOCKER_IMAGE)
 DOCKER_TEST  = $(DOCKER_CMD) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)

+# Dockerize commands, which require USB device passthrough, only on Linux.
+ifeq ($(shell uname -s),Linux)
+    DOCKER_CMD_DEV = $(DOCKER_CMD_INTERACT) $(DOCKER_ARG_DEV)
+
+    DOCKER_MINITERM = $(DOCKER_CMD_DEV) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)
+endif
+


 ##--------------------------------------------------------------------------------------------------
 ## Targets
 ##--------------------------------------------------------------------------------------------------
-.PHONY: all $(KERNEL_ELF) $(KERNEL_BIN) doc qemu clippy clean readelf objdump nm check
+.PHONY: all $(KERNEL_ELF) $(KERNEL_BIN) doc qemu miniterm clippy clean readelf objdump nm check

 all: $(KERNEL_BIN)

@@ -130,6 +142,12 @@
 endif

 ##------------------------------------------------------------------------------
+## Connect to the target's serial
+##------------------------------------------------------------------------------
+miniterm:
+	@$(DOCKER_MINITERM) $(EXEC_MINITERM) $(DEV_SERIAL)
+
+##------------------------------------------------------------------------------
 ## Run clippy
 ##------------------------------------------------------------------------------
 clippy:

diff -uNr 04_safe_globals/src/_arch/aarch64/cpu.rs 05_drivers_gpio_uart/src/_arch/aarch64/cpu.rs
--- 04_safe_globals/src/_arch/aarch64/cpu.rs
+++ 05_drivers_gpio_uart/src/_arch/aarch64/cpu.rs
@@ -17,6 +17,17 @@
 // Public Code
 //--------------------------------------------------------------------------------------------------

+pub use asm::nop;
+
+/// Spin for `n` cycles.
+#[cfg(feature = "bsp_rpi3")]
+#[inline(always)]
+pub fn spin_for_cycles(n: usize) {
+    for _ in 0..n {
+        asm::nop();
+    }
+}
+
 /// Pause execution on the core.
 #[inline(always)]
 pub fn wait_forever() -> ! {

diff -uNr 04_safe_globals/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
--- 04_safe_globals/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
+++ 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_gpio.rs
@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! GPIO Driver.
+
+use crate::{
+    bsp::device_driver::common::MMIODerefWrapper, driver, synchronization,
+    synchronization::NullLock,
+};
+use tock_registers::{
+    interfaces::{ReadWriteable, Writeable},
+    register_bitfields, register_structs,
+    registers::ReadWrite,
+};
+
+//--------------------------------------------------------------------------------------------------
+// Private Definitions
+//--------------------------------------------------------------------------------------------------
+
+// GPIO registers.
+//
+// Descriptions taken from
+// - https://github.com/raspberrypi/documentation/files/1888662/BCM2837-ARM-Peripherals.-.Revised.-.V2-1.pdf
+// - https://datasheets.raspberrypi.org/bcm2711/bcm2711-peripherals.pdf
+register_bitfields! {
+    u32,
+
+    /// GPIO Function Select 1
+    GPFSEL1 [
+        /// Pin 15
+        FSEL15 OFFSET(15) NUMBITS(3) [
+            Input = 0b000,
+            Output = 0b001,
+            AltFunc0 = 0b100  // PL011 UART RX
+
+        ],
+
+        /// Pin 14
+        FSEL14 OFFSET(12) NUMBITS(3) [
+            Input = 0b000,
+            Output = 0b001,
+            AltFunc0 = 0b100  // PL011 UART TX
+        ]
+    ],
+
+    /// GPIO Pull-up/down Register
+    ///
+    /// BCM2837 only.
+    GPPUD [
+        /// Controls the actuation of the internal pull-up/down control line to ALL the GPIO pins.
+        PUD OFFSET(0) NUMBITS(2) [
+            Off = 0b00,
+            PullDown = 0b01,
+            PullUp = 0b10
+        ]
+    ],
+
+    /// GPIO Pull-up/down Clock Register 0
+    ///
+    /// BCM2837 only.
+    GPPUDCLK0 [
+        /// Pin 15
+        PUDCLK15 OFFSET(15) NUMBITS(1) [
+            NoEffect = 0,
+            AssertClock = 1
+        ],
+
+        /// Pin 14
+        PUDCLK14 OFFSET(14) NUMBITS(1) [
+            NoEffect = 0,
+            AssertClock = 1
+        ]
+    ],
+
+    /// GPIO Pull-up / Pull-down Register 0
+    ///
+    /// BCM2711 only.
+    GPIO_PUP_PDN_CNTRL_REG0 [
+        /// Pin 15
+        GPIO_PUP_PDN_CNTRL15 OFFSET(30) NUMBITS(2) [
+            NoResistor = 0b00,
+            PullUp = 0b01
+        ],
+
+        /// Pin 14
+        GPIO_PUP_PDN_CNTRL14 OFFSET(28) NUMBITS(2) [
+            NoResistor = 0b00,
+            PullUp = 0b01
+        ]
+    ]
+}
+
+register_structs! {
+    #[allow(non_snake_case)]
+    RegisterBlock {
+        (0x00 => _reserved1),
+        (0x04 => GPFSEL1: ReadWrite<u32, GPFSEL1::Register>),
+        (0x08 => _reserved2),
+        (0x94 => GPPUD: ReadWrite<u32, GPPUD::Register>),
+        (0x98 => GPPUDCLK0: ReadWrite<u32, GPPUDCLK0::Register>),
+        (0x9C => _reserved3),
+        (0xE4 => GPIO_PUP_PDN_CNTRL_REG0: ReadWrite<u32, GPIO_PUP_PDN_CNTRL_REG0::Register>),
+        (0xE8 => @END),
+    }
+}
+
+/// Abstraction for the associated MMIO registers.
+type Registers = MMIODerefWrapper<RegisterBlock>;
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+pub struct GPIOInner {
+    registers: Registers,
+}
+
+// Export the inner struct so that BSPs can use it for the panic handler.
+pub use GPIOInner as PanicGPIO;
+
+/// Representation of the GPIO HW.
+pub struct GPIO {
+    inner: NullLock<GPIOInner>,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+impl GPIOInner {
+    /// Create an instance.
+    ///
+    /// # Safety
+    ///
+    /// - The user must ensure to provide a correct MMIO start address.
+    pub const unsafe fn new(mmio_start_addr: usize) -> Self {
+        Self {
+            registers: Registers::new(mmio_start_addr),
+        }
+    }
+
+    /// Disable pull-up/down on pins 14 and 15.
+    #[cfg(feature = "bsp_rpi3")]
+    fn disable_pud_14_15_bcm2837(&mut self) {
+        use crate::cpu;
+
+        // Make an educated guess for a good delay value (Sequence described in the BCM2837
+        // peripherals PDF).
+        //
+        // - According to Wikipedia, the fastest Pi3 clocks around 1.4 GHz.
+        // - The Linux 2837 GPIO driver waits 1 µs between the steps.
+        //
+        // So lets try to be on the safe side and default to 2000 cycles, which would equal 1 µs
+        // would the CPU be clocked at 2 GHz.
+        const DELAY: usize = 2000;
+
+        self.registers.GPPUD.write(GPPUD::PUD::Off);
+        cpu::spin_for_cycles(DELAY);
+
+        self.registers
+            .GPPUDCLK0
+            .write(GPPUDCLK0::PUDCLK15::AssertClock + GPPUDCLK0::PUDCLK14::AssertClock);
+        cpu::spin_for_cycles(DELAY);
+
+        self.registers.GPPUD.write(GPPUD::PUD::Off);
+        self.registers.GPPUDCLK0.set(0);
+    }
+
+    /// Disable pull-up/down on pins 14 and 15.
+    #[cfg(feature = "bsp_rpi4")]
+    fn disable_pud_14_15_bcm2711(&mut self) {
+        self.registers.GPIO_PUP_PDN_CNTRL_REG0.write(
+            GPIO_PUP_PDN_CNTRL_REG0::GPIO_PUP_PDN_CNTRL15::PullUp
+                + GPIO_PUP_PDN_CNTRL_REG0::GPIO_PUP_PDN_CNTRL14::PullUp,
+        );
+    }
+
+    /// Map PL011 UART as standard output.
+    ///
+    /// TX to pin 14
+    /// RX to pin 15
+    pub fn map_pl011_uart(&mut self) {
+        // Select the UART on pins 14 and 15.
+        self.registers
+            .GPFSEL1
+            .modify(GPFSEL1::FSEL15::AltFunc0 + GPFSEL1::FSEL14::AltFunc0);
+
+        // Disable pull-up/down on pins 14 and 15.
+        #[cfg(feature = "bsp_rpi3")]
+        self.disable_pud_14_15_bcm2837();
+
+        #[cfg(feature = "bsp_rpi4")]
+        self.disable_pud_14_15_bcm2711();
+    }
+}
+
+impl GPIO {
+    /// Create an instance.
+    ///
+    /// # Safety
+    ///
+    /// - The user must ensure to provide a correct MMIO start address.
+    pub const unsafe fn new(mmio_start_addr: usize) -> Self {
+        Self {
+            inner: NullLock::new(GPIOInner::new(mmio_start_addr)),
+        }
+    }
+
+    /// Concurrency safe version of `GPIOInner.map_pl011_uart()`
+    pub fn map_pl011_uart(&self) {
+        self.inner.lock(|inner| inner.map_pl011_uart())
+    }
+}
+
+//------------------------------------------------------------------------------
+// OS Interface Code
+//------------------------------------------------------------------------------
+use synchronization::interface::Mutex;
+
+impl driver::interface::DeviceDriver for GPIO {
+    fn compatible(&self) -> &'static str {
+        "BCM GPIO"
+    }
+}

diff -uNr 04_safe_globals/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
--- 04_safe_globals/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
+++ 05_drivers_gpio_uart/src/bsp/device_driver/bcm/bcm2xxx_pl011_uart.rs
@@ -0,0 +1,408 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! PL011 UART driver.
+//!
+//! # Resources
+//!
+//! - <https://github.com/raspberrypi/documentation/files/1888662/BCM2837-ARM-Peripherals.-.Revised.-.V2-1.pdf>
+//! - <https://developer.arm.com/documentation/ddi0183/latest>
+
+use crate::{
+    bsp::device_driver::common::MMIODerefWrapper, console, cpu, driver, synchronization,
+    synchronization::NullLock,
+};
+use core::fmt;
+use tock_registers::{
+    interfaces::{Readable, Writeable},
+    register_bitfields, register_structs,
+    registers::{ReadOnly, ReadWrite, WriteOnly},
+};
+
+//--------------------------------------------------------------------------------------------------
+// Private Definitions
+//--------------------------------------------------------------------------------------------------
+
+// PL011 UART registers.
+//
+// Descriptions taken from "PrimeCell UART (PL011) Technical Reference Manual" r1p5.
+register_bitfields! {
+    u32,
+
+    /// Flag Register.
+    FR [
+        /// Transmit FIFO empty. The meaning of this bit depends on the state of the FEN bit in the
+        /// Line Control Register, LCR_H.
+        ///
+        /// - If the FIFO is disabled, this bit is set when the transmit holding register is empty.
+        /// - If the FIFO is enabled, the TXFE bit is set when the transmit FIFO is empty.
+        /// - This bit does not indicate if there is data in the transmit shift register.
+        TXFE OFFSET(7) NUMBITS(1) [],
+
+        /// Transmit FIFO full. The meaning of this bit depends on the state of the FEN bit in the
+        /// LCR_H Register.
+        ///
+        /// - If the FIFO is disabled, this bit is set when the transmit holding register is full.
+        /// - If the FIFO is enabled, the TXFF bit is set when the transmit FIFO is full.
+        TXFF OFFSET(5) NUMBITS(1) [],
+
+        /// Receive FIFO empty. The meaning of this bit depends on the state of the FEN bit in the
+        /// LCR_H Register.
+        ///
+        /// If the FIFO is disabled, this bit is set when the receive holding register is empty. If
+        /// the FIFO is enabled, the RXFE bit is set when the receive FIFO is empty.
+
+        /// Receive FIFO empty. The meaning of this bit depends on the state of the FEN bit in the
+        /// LCR_H Register.
+        ///
+        /// - If the FIFO is disabled, this bit is set when the receive holding register is empty.
+        /// - If the FIFO is enabled, the RXFE bit is set when the receive FIFO is empty.
+        RXFE OFFSET(4) NUMBITS(1) [],
+
+        /// UART busy. If this bit is set to 1, the UART is busy transmitting data. This bit remains
+        /// set until the complete byte, including all the stop bits, has been sent from the shift
+        /// register.
+        ///
+        /// This bit is set as soon as the transmit FIFO becomes non-empty, regardless of whether
+        /// the UART is enabled or not.
+        BUSY OFFSET(3) NUMBITS(1) []
+    ],
+
+    /// Integer Baud Rate Divisor.
+    IBRD [
+        /// The integer baud rate divisor.
+        BAUD_DIVINT OFFSET(0) NUMBITS(16) []
+    ],
+
+    /// Fractional Baud Rate Divisor.
+    FBRD [
+        ///  The fractional baud rate divisor.
+        BAUD_DIVFRAC OFFSET(0) NUMBITS(6) []
+    ],
+
+    /// Line Control Register.
+    LCR_H [
+        /// Word length. These bits indicate the number of data bits transmitted or received in a
+        /// frame.
+        #[allow(clippy::enum_variant_names)]
+        WLEN OFFSET(5) NUMBITS(2) [
+            FiveBit = 0b00,
+            SixBit = 0b01,
+            SevenBit = 0b10,
+            EightBit = 0b11
+        ],
+
+        /// Enable FIFOs:
+        ///
+        /// 0 = FIFOs are disabled (character mode) that is, the FIFOs become 1-byte-deep holding
+        /// registers.
+        ///
+        /// 1 = Transmit and receive FIFO buffers are enabled (FIFO mode).
+        FEN  OFFSET(4) NUMBITS(1) [
+            FifosDisabled = 0,
+            FifosEnabled = 1
+        ]
+    ],
+
+    /// Control Register.
+    CR [
+        /// Receive enable. If this bit is set to 1, the receive section of the UART is enabled.
+        /// Data reception occurs for either UART signals or SIR signals depending on the setting of
+        /// the SIREN bit. When the UART is disabled in the middle of reception, it completes the
+        /// current character before stopping.
+        RXE OFFSET(9) NUMBITS(1) [
+            Disabled = 0,
+            Enabled = 1
+        ],
+
+        /// Transmit enable. If this bit is set to 1, the transmit section of the UART is enabled.
+        /// Data transmission occurs for either UART signals, or SIR signals depending on the
+        /// setting of the SIREN bit. When the UART is disabled in the middle of transmission, it
+        /// completes the current character before stopping.
+        TXE OFFSET(8) NUMBITS(1) [
+            Disabled = 0,
+            Enabled = 1
+        ],
+
+        /// UART enable:
+        ///
+        /// 0 = UART is disabled. If the UART is disabled in the middle of transmission or
+        /// reception, it completes the current character before stopping.
+        ///
+        /// 1 = The UART is enabled. Data transmission and reception occurs for either UART signals
+        /// or SIR signals depending on the setting of the SIREN bit
+        UARTEN OFFSET(0) NUMBITS(1) [
+            /// If the UART is disabled in the middle of transmission or reception, it completes the
+            /// current character before stopping.
+            Disabled = 0,
+            Enabled = 1
+        ]
+    ],
+
+    /// Interrupt Clear Register.
+    ICR [
+        /// Meta field for all pending interrupts.
+        ALL OFFSET(0) NUMBITS(11) []
+    ]
+}
+
+register_structs! {
+    #[allow(non_snake_case)]
+    pub RegisterBlock {
+        (0x00 => DR: ReadWrite<u32>),
+        (0x04 => _reserved1),
+        (0x18 => FR: ReadOnly<u32, FR::Register>),
+        (0x1c => _reserved2),
+        (0x24 => IBRD: WriteOnly<u32, IBRD::Register>),
+        (0x28 => FBRD: WriteOnly<u32, FBRD::Register>),
+        (0x2c => LCR_H: WriteOnly<u32, LCR_H::Register>),
+        (0x30 => CR: WriteOnly<u32, CR::Register>),
+        (0x34 => _reserved3),
+        (0x44 => ICR: WriteOnly<u32, ICR::Register>),
+        (0x48 => @END),
+    }
+}
+
+/// Abstraction for the associated MMIO registers.
+type Registers = MMIODerefWrapper<RegisterBlock>;
+
+#[derive(PartialEq)]
+enum BlockingMode {
+    Blocking,
+    NonBlocking,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+pub struct PL011UartInner {
+    registers: Registers,
+    chars_written: usize,
+    chars_read: usize,
+}
+
+// Export the inner struct so that BSPs can use it for the panic handler.
+pub use PL011UartInner as PanicUart;
+
+/// Representation of the UART.
+pub struct PL011Uart {
+    inner: NullLock<PL011UartInner>,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+impl PL011UartInner {
+    /// Create an instance.
+    ///
+    /// # Safety
+    ///
+    /// - The user must ensure to provide a correct MMIO start address.
+    pub const unsafe fn new(mmio_start_addr: usize) -> Self {
+        Self {
+            registers: Registers::new(mmio_start_addr),
+            chars_written: 0,
+            chars_read: 0,
+        }
+    }
+
+    /// Set up baud rate and characteristics.
+    ///
+    /// This results in 8N1 and 921_600 baud.
+    ///
+    /// The calculation for the BRD is (we set the clock to 48 MHz in config.txt):
+    /// `(48_000_000 / 16) / 921_600 = 3.2552083`.
+    ///
+    /// This means the integer part is `3` and goes into the `IBRD`.
+    /// The fractional part is `0.2552083`.
+    ///
+    /// `FBRD` calculation according to the PL011 Technical Reference Manual:
+    /// `INTEGER((0.2552083 * 64) + 0.5) = 16`.
+    ///
+    /// Therefore, the generated baud rate divider is: `3 + 16/64 = 3.25`. Which results in a
+    /// genrated baud rate of `48_000_000 / (16 * 3.25) = 923_077`.
+    ///
+    /// Error = `((923_077 - 921_600) / 921_600) * 100 = 0.16modulo`.
+    pub fn init(&mut self) {
+        // Execution can arrive here while there are still characters queued in the TX FIFO and
+        // actively being sent out by the UART hardware. If the UART is turned off in this case,
+        // those queued characters would be lost.
+        //
+        // For example, this can happen during runtime on a call to panic!(), because panic!()
+        // initializes its own UART instance and calls init().
+        //
+        // Hence, flush first to ensure all pending characters are transmitted.
+        self.flush();
+
+        // Turn the UART off temporarily.
+        self.registers.CR.set(0);
+
+        // Clear all pending interrupts.
+        self.registers.ICR.write(ICR::ALL::CLEAR);
+
+        // From the PL011 Technical Reference Manual:
+        //
+        // The LCR_H, IBRD, and FBRD registers form the single 30-bit wide LCR Register that is
+        // updated on a single write strobe generated by a LCR_H write. So, to internally update the
+        // contents of IBRD or FBRD, a LCR_H write must always be performed at the end.
+        //
+        // Set the baud rate, 8N1 and FIFO enabled.
+        self.registers.IBRD.write(IBRD::BAUD_DIVINT.val(3));
+        self.registers.FBRD.write(FBRD::BAUD_DIVFRAC.val(16));
+        self.registers
+            .LCR_H
+            .write(LCR_H::WLEN::EightBit + LCR_H::FEN::FifosEnabled);
+
+        // Turn the UART on.
+        self.registers
+            .CR
+            .write(CR::UARTEN::Enabled + CR::TXE::Enabled + CR::RXE::Enabled);
+    }
+
+    /// Send a character.
+    fn write_char(&mut self, c: char) {
+        // Spin while TX FIFO full is set, waiting for an empty slot.
+        while self.registers.FR.matches_all(FR::TXFF::SET) {
+            cpu::nop();
+        }
+
+        // Write the character to the buffer.
+        self.registers.DR.set(c as u32);
+
+        self.chars_written += 1;
+    }
+
+    /// Block execution until the last buffered character has been physically put on the TX wire.
+    fn flush(&self) {
+        // Spin until the busy bit is cleared.
+        while self.registers.FR.matches_all(FR::BUSY::SET) {
+            cpu::nop();
+        }
+    }
+
+    /// Retrieve a character.
+    fn read_char_converting(&mut self, blocking_mode: BlockingMode) -> Option<char> {
+        // If RX FIFO is empty,
+        if self.registers.FR.matches_all(FR::RXFE::SET) {
+            // immediately return in non-blocking mode.
+            if blocking_mode == BlockingMode::NonBlocking {
+                return None;
+            }
+
+            // Otherwise, wait until a char was received.
+            while self.registers.FR.matches_all(FR::RXFE::SET) {
+                cpu::nop();
+            }
+        }
+
+        // Read one character.
+        let mut ret = self.registers.DR.get() as u8 as char;
+
+        // Convert carrige return to newline.
+        if ret == '\r' {
+            ret = '\n'
+        }
+
+        // Update statistics.
+        self.chars_read += 1;
+
+        Some(ret)
+    }
+}
+
+/// Implementing `core::fmt::Write` enables usage of the `format_args!` macros, which in turn are
+/// used to implement the `kernel`'s `print!` and `println!` macros. By implementing `write_str()`,
+/// we get `write_fmt()` automatically.
+///
+/// The function takes an `&mut self`, so it must be implemented for the inner struct.
+///
+/// See [`src/print.rs`].
+///
+/// [`src/print.rs`]: ../../print/index.html
+impl fmt::Write for PL011UartInner {
+    fn write_str(&mut self, s: &str) -> fmt::Result {
+        for c in s.chars() {
+            self.write_char(c);
+        }
+
+        Ok(())
+    }
+}
+
+impl PL011Uart {
+    /// Create an instance.
+    ///
+    /// # Safety
+    ///
+    /// - The user must ensure to provide a correct MMIO start address.
+    pub const unsafe fn new(mmio_start_addr: usize) -> Self {
+        Self {
+            inner: NullLock::new(PL011UartInner::new(mmio_start_addr)),
+        }
+    }
+}
+
+//------------------------------------------------------------------------------
+// OS Interface Code
+//------------------------------------------------------------------------------
+use synchronization::interface::Mutex;
+
+impl driver::interface::DeviceDriver for PL011Uart {
+    fn compatible(&self) -> &'static str {
+        "BCM PL011 UART"
+    }
+
+    unsafe fn init(&self) -> Result<(), &'static str> {
+        self.inner.lock(|inner| inner.init());
+
+        Ok(())
+    }
+}
+
+impl console::interface::Write for PL011Uart {
+    /// Passthrough of `args` to the `core::fmt::Write` implementation, but guarded by a Mutex to
+    /// serialize access.
+    fn write_char(&self, c: char) {
+        self.inner.lock(|inner| inner.write_char(c));
+    }
+
+    fn write_fmt(&self, args: core::fmt::Arguments) -> fmt::Result {
+        // Fully qualified syntax for the call to `core::fmt::Write::write:fmt()` to increase
+        // readability.
+        self.inner.lock(|inner| fmt::Write::write_fmt(inner, args))
+    }
+
+    fn flush(&self) {
+        // Spin until TX FIFO empty is set.
+        self.inner.lock(|inner| inner.flush());
+    }
+}
+
+impl console::interface::Read for PL011Uart {
+    fn read_char(&self) -> char {
+        self.inner
+            .lock(|inner| inner.read_char_converting(BlockingMode::Blocking).unwrap())
+    }
+
+    fn clear_rx(&self) {
+        // Read from the RX FIFO until it is indicating empty.
+        while self
+            .inner
+            .lock(|inner| inner.read_char_converting(BlockingMode::NonBlocking))
+            .is_some()
+        {}
+    }
+}
+
+impl console::interface::Statistics for PL011Uart {
+    fn chars_written(&self) -> usize {
+        self.inner.lock(|inner| inner.chars_written)
+    }
+
+    fn chars_read(&self) -> usize {
+        self.inner.lock(|inner| inner.chars_read)
+    }
+}

diff -uNr 04_safe_globals/src/bsp/device_driver/bcm.rs 05_drivers_gpio_uart/src/bsp/device_driver/bcm.rs
--- 04_safe_globals/src/bsp/device_driver/bcm.rs
+++ 05_drivers_gpio_uart/src/bsp/device_driver/bcm.rs
@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! BCM driver top level.
+
+mod bcm2xxx_gpio;
+mod bcm2xxx_pl011_uart;
+
+pub use bcm2xxx_gpio::*;
+pub use bcm2xxx_pl011_uart::*;

diff -uNr 04_safe_globals/src/bsp/device_driver/common.rs 05_drivers_gpio_uart/src/bsp/device_driver/common.rs
--- 04_safe_globals/src/bsp/device_driver/common.rs
+++ 05_drivers_gpio_uart/src/bsp/device_driver/common.rs
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2020-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Common device driver code.
+
+use core::{marker::PhantomData, ops};
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+pub struct MMIODerefWrapper<T> {
+    start_addr: usize,
+    phantom: PhantomData<fn() -> T>,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+impl<T> MMIODerefWrapper<T> {
+    /// Create an instance.
+    pub const unsafe fn new(start_addr: usize) -> Self {
+        Self {
+            start_addr,
+            phantom: PhantomData,
+        }
+    }
+}
+
+impl<T> ops::Deref for MMIODerefWrapper<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        unsafe { &*(self.start_addr as *const _) }
+    }
+}

diff -uNr 04_safe_globals/src/bsp/device_driver.rs 05_drivers_gpio_uart/src/bsp/device_driver.rs
--- 04_safe_globals/src/bsp/device_driver.rs
+++ 05_drivers_gpio_uart/src/bsp/device_driver.rs
@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Device driver.
+
+#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
+mod bcm;
+mod common;
+
+#[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
+pub use bcm::*;

diff -uNr 04_safe_globals/src/bsp/raspberrypi/console.rs 05_drivers_gpio_uart/src/bsp/raspberrypi/console.rs
--- 04_safe_globals/src/bsp/raspberrypi/console.rs
+++ 05_drivers_gpio_uart/src/bsp/raspberrypi/console.rs
@@ -4,113 +4,34 @@

 //! BSP console facilities.

-use crate::{console, synchronization, synchronization::NullLock};
+use super::memory;
+use crate::{bsp::device_driver, console};
 use core::fmt;

 //--------------------------------------------------------------------------------------------------
-// Private Definitions
+// Public Code
 //--------------------------------------------------------------------------------------------------

-/// A mystical, magical device for generating QEMU output out of the void.
+/// In case of a panic, the panic handler uses this function to take a last shot at printing
+/// something before the system is halted.
 ///
-/// The mutex protected part.
-struct QEMUOutputInner {
-    chars_written: usize,
-}
-
-//--------------------------------------------------------------------------------------------------
-// Public Definitions
-//--------------------------------------------------------------------------------------------------
-
-/// The main struct.
-pub struct QEMUOutput {
-    inner: NullLock<QEMUOutputInner>,
-}
-
-//--------------------------------------------------------------------------------------------------
-// Global instances
-//--------------------------------------------------------------------------------------------------
-
-static QEMU_OUTPUT: QEMUOutput = QEMUOutput::new();
-
-//--------------------------------------------------------------------------------------------------
-// Private Code
-//--------------------------------------------------------------------------------------------------
-
-impl QEMUOutputInner {
-    const fn new() -> QEMUOutputInner {
-        QEMUOutputInner { chars_written: 0 }
-    }
-
-    /// Send a character.
-    fn write_char(&mut self, c: char) {
-        unsafe {
-            core::ptr::write_volatile(0x3F20_1000 as *mut u8, c as u8);
-        }
-
-        self.chars_written += 1;
-    }
-}
-
-/// Implementing `core::fmt::Write` enables usage of the `format_args!` macros, which in turn are
-/// used to implement the `kernel`'s `print!` and `println!` macros. By implementing `write_str()`,
-/// we get `write_fmt()` automatically.
+/// We try to init panic-versions of the GPIO and the UART. The panic versions are not protected
+/// with synchronization primitives, which increases chances that we get to print something, even
+/// when the kernel's default GPIO or UART instances happen to be locked at the time of the panic.
 ///
-/// The function takes an `&mut self`, so it must be implemented for the inner struct.
+/// # Safety
 ///
-/// See [`src/print.rs`].
-///
-/// [`src/print.rs`]: ../../print/index.html
-impl fmt::Write for QEMUOutputInner {
-    fn write_str(&mut self, s: &str) -> fmt::Result {
-        for c in s.chars() {
-            // Convert newline to carrige return + newline.
-            if c == '\n' {
-                self.write_char('\r')
-            }
-
-            self.write_char(c);
-        }
-
-        Ok(())
-    }
-}
-
-//--------------------------------------------------------------------------------------------------
-// Public Code
-//--------------------------------------------------------------------------------------------------
-
-impl QEMUOutput {
-    /// Create a new instance.
-    pub const fn new() -> QEMUOutput {
-        QEMUOutput {
-            inner: NullLock::new(QEMUOutputInner::new()),
-        }
-    }
+/// - Use only for printing during a panic.
+pub unsafe fn panic_console_out() -> impl fmt::Write {
+    let mut panic_gpio = device_driver::PanicGPIO::new(memory::map::mmio::GPIO_START);
+    let mut panic_uart = device_driver::PanicUart::new(memory::map::mmio::PL011_UART_START);
+
+    panic_gpio.map_pl011_uart();
+    panic_uart.init();
+    panic_uart
 }

 /// Return a reference to the console.
 pub fn console() -> &'static impl console::interface::All {
-    &QEMU_OUTPUT
-}
-
-//------------------------------------------------------------------------------
-// OS Interface Code
-//------------------------------------------------------------------------------
-use synchronization::interface::Mutex;
-
-/// Passthrough of `args` to the `core::fmt::Write` implementation, but guarded by a Mutex to
-/// serialize access.
-impl console::interface::Write for QEMUOutput {
-    fn write_fmt(&self, args: core::fmt::Arguments) -> fmt::Result {
-        // Fully qualified syntax for the call to `core::fmt::Write::write:fmt()` to increase
-        // readability.
-        self.inner.lock(|inner| fmt::Write::write_fmt(inner, args))
-    }
-}
-
-impl console::interface::Statistics for QEMUOutput {
-    fn chars_written(&self) -> usize {
-        self.inner.lock(|inner| inner.chars_written)
-    }
+    &super::PL011_UART
 }

diff -uNr 04_safe_globals/src/bsp/raspberrypi/driver.rs 05_drivers_gpio_uart/src/bsp/raspberrypi/driver.rs
--- 04_safe_globals/src/bsp/raspberrypi/driver.rs
+++ 05_drivers_gpio_uart/src/bsp/raspberrypi/driver.rs
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! BSP driver support.
+
+use crate::driver;
+
+//--------------------------------------------------------------------------------------------------
+// Private Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// Device Driver Manager type.
+struct BSPDriverManager {
+    device_drivers: [&'static (dyn DeviceDriver + Sync); 2],
+}
+
+//--------------------------------------------------------------------------------------------------
+// Global instances
+//--------------------------------------------------------------------------------------------------
+
+static BSP_DRIVER_MANAGER: BSPDriverManager = BSPDriverManager {
+    device_drivers: [&super::GPIO, &super::PL011_UART],
+};
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// Return a reference to the driver manager.
+pub fn driver_manager() -> &'static impl driver::interface::DriverManager {
+    &BSP_DRIVER_MANAGER
+}
+
+//------------------------------------------------------------------------------
+// OS Interface Code
+//------------------------------------------------------------------------------
+use driver::interface::DeviceDriver;
+
+impl driver::interface::DriverManager for BSPDriverManager {
+    fn all_device_drivers(&self) -> &[&'static (dyn DeviceDriver + Sync)] {
+        &self.device_drivers[..]
+    }
+
+    fn post_device_driver_init(&self) {
+        // Configure PL011Uart's output pins.
+        super::GPIO.map_pl011_uart();
+    }
+}

diff -uNr 04_safe_globals/src/bsp/raspberrypi/memory.rs 05_drivers_gpio_uart/src/bsp/raspberrypi/memory.rs
--- 04_safe_globals/src/bsp/raspberrypi/memory.rs
+++ 05_drivers_gpio_uart/src/bsp/raspberrypi/memory.rs
@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! BSP Memory Management.
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// The board's physical memory map.
+#[rustfmt::skip]
+pub(super) mod map {
+
+    pub const GPIO_OFFSET:         usize = 0x0020_0000;
+    pub const UART_OFFSET:         usize = 0x0020_1000;
+
+    /// Physical devices.
+    #[cfg(feature = "bsp_rpi3")]
+    pub mod mmio {
+        use super::*;
+
+        pub const START:            usize =         0x3F00_0000;
+        pub const GPIO_START:       usize = START + GPIO_OFFSET;
+        pub const PL011_UART_START: usize = START + UART_OFFSET;
+    }
+
+    /// Physical devices.
+    #[cfg(feature = "bsp_rpi4")]
+    pub mod mmio {
+        use super::*;
+
+        pub const START:            usize =         0xFE00_0000;
+        pub const GPIO_START:       usize = START + GPIO_OFFSET;
+        pub const PL011_UART_START: usize = START + UART_OFFSET;
+    }
+}

diff -uNr 04_safe_globals/src/bsp/raspberrypi.rs 05_drivers_gpio_uart/src/bsp/raspberrypi.rs
--- 04_safe_globals/src/bsp/raspberrypi.rs
+++ 05_drivers_gpio_uart/src/bsp/raspberrypi.rs
@@ -6,3 +6,33 @@

 pub mod console;
 pub mod cpu;
+pub mod driver;
+pub mod memory;
+
+//--------------------------------------------------------------------------------------------------
+// Global instances
+//--------------------------------------------------------------------------------------------------
+use super::device_driver;
+
+static GPIO: device_driver::GPIO =
+    unsafe { device_driver::GPIO::new(memory::map::mmio::GPIO_START) };
+
+static PL011_UART: device_driver::PL011Uart =
+    unsafe { device_driver::PL011Uart::new(memory::map::mmio::PL011_UART_START) };
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// Board identification.
+pub fn board_name() -> &'static str {
+    #[cfg(feature = "bsp_rpi3")]
+    {
+        "Raspberry Pi 3"
+    }
+
+    #[cfg(feature = "bsp_rpi4")]
+    {
+        "Raspberry Pi 4"
+    }
+}

diff -uNr 04_safe_globals/src/bsp.rs 05_drivers_gpio_uart/src/bsp.rs
--- 04_safe_globals/src/bsp.rs
+++ 05_drivers_gpio_uart/src/bsp.rs
@@ -4,6 +4,8 @@

 //! Conditional reexporting of Board Support Packages.

+mod device_driver;
+
 #[cfg(any(feature = "bsp_rpi3", feature = "bsp_rpi4"))]
 mod raspberrypi;


diff -uNr 04_safe_globals/src/console.rs 05_drivers_gpio_uart/src/console.rs
--- 04_safe_globals/src/console.rs
+++ 05_drivers_gpio_uart/src/console.rs
@@ -14,8 +14,25 @@

     /// Console write functions.
     pub trait Write {
+        /// Write a single character.
+        fn write_char(&self, c: char);
+
         /// Write a Rust format string.
         fn write_fmt(&self, args: fmt::Arguments) -> fmt::Result;
+
+        /// Block until the last buffered character has been physically put on the TX wire.
+        fn flush(&self);
+    }
+
+    /// Console read functions.
+    pub trait Read {
+        /// Read a single character.
+        fn read_char(&self) -> char {
+            ' '
+        }
+
+        /// Clear RX buffers, if any.
+        fn clear_rx(&self);
     }

     /// Console statistics.
@@ -24,8 +41,13 @@
         fn chars_written(&self) -> usize {
             0
         }
+
+        /// Return the number of characters read.
+        fn chars_read(&self) -> usize {
+            0
+        }
     }

     /// Trait alias for a full-fledged console.
-    pub trait All = Write + Statistics;
+    pub trait All = Write + Read + Statistics;
 }

diff -uNr 04_safe_globals/src/cpu.rs 05_drivers_gpio_uart/src/cpu.rs
--- 04_safe_globals/src/cpu.rs
+++ 05_drivers_gpio_uart/src/cpu.rs
@@ -13,4 +13,7 @@
 //--------------------------------------------------------------------------------------------------
 // Architectural Public Reexports
 //--------------------------------------------------------------------------------------------------
-pub use arch_cpu::wait_forever;
+pub use arch_cpu::{nop, wait_forever};
+
+#[cfg(feature = "bsp_rpi3")]
+pub use arch_cpu::spin_for_cycles;

diff -uNr 04_safe_globals/src/driver.rs 05_drivers_gpio_uart/src/driver.rs
--- 04_safe_globals/src/driver.rs
+++ 05_drivers_gpio_uart/src/driver.rs
@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Driver support.
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// Driver interfaces.
+pub mod interface {
+    /// Device Driver functions.
+    pub trait DeviceDriver {
+        /// Return a compatibility string for identifying the driver.
+        fn compatible(&self) -> &'static str;
+
+        /// Called by the kernel to bring up the device.
+        ///
+        /// # Safety
+        ///
+        /// - During init, drivers might do stuff with system-wide impact.
+        unsafe fn init(&self) -> Result<(), &'static str> {
+            Ok(())
+        }
+    }
+
+    /// Device driver management functions.
+    ///
+    /// The `BSP` is supposed to supply one global instance.
+    pub trait DriverManager {
+        /// Return a slice of references to all `BSP`-instantiated drivers.
+        ///
+        /// # Safety
+        ///
+        /// - The order of devices is the order in which `DeviceDriver::init()` is called.
+        fn all_device_drivers(&self) -> &[&'static (dyn DeviceDriver + Sync)];
+
+        /// Initialization code that runs after driver init.
+        ///
+        /// For example, device driver code that depends on other drivers already being online.
+        fn post_device_driver_init(&self);
+    }
+}

diff -uNr 04_safe_globals/src/main.rs 05_drivers_gpio_uart/src/main.rs
--- 04_safe_globals/src/main.rs
+++ 05_drivers_gpio_uart/src/main.rs
@@ -104,6 +104,8 @@
 //!     - It is implemented in `src/_arch/__arch_name__/cpu/boot.s`.
 //! 2. Once finished with architectural setup, the arch code calls `kernel_init()`.

+#![allow(clippy::upper_case_acronyms)]
+#![feature(const_fn_fn_ptr_basics)]
 #![feature(format_args_nl)]
 #![feature(global_asm)]
 #![feature(panic_info_message)]
@@ -114,6 +116,7 @@
 mod bsp;
 mod console;
 mod cpu;
+mod driver;
 mod panic_wait;
 mod print;
 mod synchronization;
@@ -123,16 +126,54 @@
 /// # Safety
 ///
 /// - Only a single core must be active and running this function.
+/// - The init calls in this function must appear in the correct order.
 unsafe fn kernel_init() -> ! {
-    use console::interface::Statistics;
+    use driver::interface::DriverManager;

-    println!("[0] Hello from Rust!");
+    for i in bsp::driver::driver_manager().all_device_drivers().iter() {
+        if let Err(x) = i.init() {
+            panic!("Error loading driver: {}: {}", i.compatible(), x);
+        }
+    }
+    bsp::driver::driver_manager().post_device_driver_init();
+    // println! is usable from here on.
+
+    // Transition from unsafe to safe.
+    kernel_main()
+}
+
+/// The main function running after the early init.
+fn kernel_main() -> ! {
+    use bsp::console::console;
+    use console::interface::All;
+    use driver::interface::DriverManager;
+
+    println!(
+        "[0] {} version {}",
+        env!("CARGO_PKG_NAME"),
+        env!("CARGO_PKG_VERSION")
+    );
+    println!("[1] Booting on: {}", bsp::board_name());
+
+    println!("[2] Drivers loaded:");
+    for (i, driver) in bsp::driver::driver_manager()
+        .all_device_drivers()
+        .iter()
+        .enumerate()
+    {
+        println!("      {}. {}", i + 1, driver.compatible());
+    }

     println!(
-        "[1] Chars written: {}",
+        "[3] Chars written: {}",
         bsp::console::console().chars_written()
     );
+    println!("[4] Echoing input now");

-    println!("[2] Stopping here.");
-    cpu::wait_forever()
+    // Discard any spurious received characters before going into echo mode.
+    console().clear_rx();
+    loop {
+        let c = bsp::console::console().read_char();
+        bsp::console::console().write_char(c);
+    }
 }

diff -uNr 04_safe_globals/src/panic_wait.rs 05_drivers_gpio_uart/src/panic_wait.rs
--- 04_safe_globals/src/panic_wait.rs
+++ 05_drivers_gpio_uart/src/panic_wait.rs
@@ -4,15 +4,35 @@

 //! A panic handler that infinitely waits.

-use crate::{cpu, println};
-use core::panic::PanicInfo;
+use crate::{bsp, cpu};
+use core::{fmt, panic::PanicInfo};
+
+//--------------------------------------------------------------------------------------------------
+// Private Code
+//--------------------------------------------------------------------------------------------------
+
+fn _panic_print(args: fmt::Arguments) {
+    use fmt::Write;
+
+    unsafe { bsp::console::panic_console_out().write_fmt(args).unwrap() };
+}
+
+/// Prints with a newline - only use from the panic handler.
+///
+/// Carbon copy from <https://doc.rust-lang.org/src/std/macros.rs.html>
+#[macro_export]
+macro_rules! panic_println {
+    ($($arg:tt)*) => ({
+        _panic_print(format_args_nl!($($arg)*));
+    })
+}

 #[panic_handler]
 fn panic(info: &PanicInfo) -> ! {
     if let Some(args) = info.message() {
-        println!("\nKernel panic: {}", args);
+        panic_println!("\nKernel panic: {}", args);
     } else {
-        println!("\nKernel panic!");
+        panic_println!("\nKernel panic!");
     }

     cpu::wait_forever()

diff -uNr 04_safe_globals/tests/boot_test_string.rb 05_drivers_gpio_uart/tests/boot_test_string.rb
--- 04_safe_globals/tests/boot_test_string.rb
+++ 05_drivers_gpio_uart/tests/boot_test_string.rb
@@ -1,3 +1,3 @@
 # frozen_string_literal: true

-EXPECTED_PRINT = 'Stopping here'
+EXPECTED_PRINT = 'Echoing input now'

使用Rust在树莓派上编写操作系统 - 04 - 安全的全局变量

Sat, 07 Aug 2021 17:29:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 04 - Safe Globals；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

引入了伪锁。
本章首次展示了操作系统的同步机制，并使全局数据结构可以被安全的访问。

Rust中可变的全局变量

当我们在第三章中引入全局可用的print!宏时，使了个小手段。在调用core::fmt的write_fmt()函数时，需要提供一个&mut self参数，而我们的调用之所以能成功，是因为每次调用时该函数时，我们都会创建一个新的QEMUOutput实例。

如果我们想保持某些状态——例如，对写入的字符进行统计——就需要创建一个QEMUOutput的全局实例（在Rust中，使用static关键字）。

然而，我们不能使用静态变量QEMU_OUTPUT调用参数为&mut self的函数。此时，我们需要一个static mut变量，但是，在static mut变量上调用函数修改状态并不安全。Rust编译器认为，此时，它无法阻止多个内核/线程同时改变该数据（该变量是全局的，因此任何代码都可能在任何地方引用它。借用检查器此时将无法继续保证借用安全）。

这个问题的解决方案是将全局封装在一个同步原语中（译注：synchronization primitive，实现同步操作的原子化执行）。在我们的例子中，将使用互斥锁（Mutex即MUTual EXclusion）的一个变体。 Mutex在synchronized.rs中作为一个trait引入，并由该文件中的NullLock实现。为了使代码更适合教学目的，现阶段省略了用于保护并发访问的罗辑结构，因为目前的内核仅在单核上执行且禁用中断，所以目前并不需要并发保护。

NullLock专注于展示Rust的一个核心概念——内部可变性，请务必仔细阅读。此外，我还建议阅读这篇关于Rust引用类型的准确认知模型。

如果你想将NullLock与某些实际应用中的互斥锁的实现进行比较，您可以查看spincrate或parking_lotcrate中的实现。

测试运行

$ make qemu
[...]

[0] Hello from Rust!
[1] Chars written: 22
[2] Stopping here.

与上一章代码的区别

diff -uNr 03_hacky_hello_world/Cargo.toml 04_safe_globals/Cargo.toml
--- 03_hacky_hello_world/Cargo.toml
+++ 04_safe_globals/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mingo"
-version = "0.3.0"
+version = "0.4.0"
 authors = ["Andre Richter <andre.o.richter@gmail.com>"]
 edition = "2018"


diff -uNr 03_hacky_hello_world/src/bsp/raspberrypi/console.rs 04_safe_globals/src/bsp/raspberrypi/console.rs
--- 03_hacky_hello_world/src/bsp/raspberrypi/console.rs
+++ 04_safe_globals/src/bsp/raspberrypi/console.rs
@@ -4,7 +4,7 @@

 //! BSP console facilities.

-use crate::console;
+use crate::{console, synchronization, synchronization::NullLock};
 use core::fmt;

 //--------------------------------------------------------------------------------------------------
@@ -12,25 +12,64 @@
 //--------------------------------------------------------------------------------------------------

 /// A mystical, magical device for generating QEMU output out of the void.
-struct QEMUOutput;
+///
+/// The mutex protected part.
+struct QEMUOutputInner {
+    chars_written: usize,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// The main struct.
+pub struct QEMUOutput {
+    inner: NullLock<QEMUOutputInner>,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Global instances
+//--------------------------------------------------------------------------------------------------
+
+static QEMU_OUTPUT: QEMUOutput = QEMUOutput::new();

 //--------------------------------------------------------------------------------------------------
 // Private Code
 //--------------------------------------------------------------------------------------------------

+impl QEMUOutputInner {
+    const fn new() -> QEMUOutputInner {
+        QEMUOutputInner { chars_written: 0 }
+    }
+
+    /// Send a character.
+    fn write_char(&mut self, c: char) {
+        unsafe {
+            core::ptr::write_volatile(0x3F20_1000 as *mut u8, c as u8);
+        }
+
+        self.chars_written += 1;
+    }
+}
+
 /// Implementing `core::fmt::Write` enables usage of the `format_args!` macros, which in turn are
 /// used to implement the `kernel`'s `print!` and `println!` macros. By implementing `write_str()`,
 /// we get `write_fmt()` automatically.
 ///
+/// The function takes an `&mut self`, so it must be implemented for the inner struct.
+///
 /// See [`src/print.rs`].
 ///
 /// [`src/print.rs`]: ../../print/index.html
-impl fmt::Write for QEMUOutput {
+impl fmt::Write for QEMUOutputInner {
     fn write_str(&mut self, s: &str) -> fmt::Result {
         for c in s.chars() {
-            unsafe {
-                core::ptr::write_volatile(0x3F20_1000 as *mut u8, c as u8);
+            // Convert newline to carrige return + newline.
+            if c == '\n' {
+                self.write_char('\r')
             }
+
+            self.write_char(c);
         }

         Ok(())
@@ -41,7 +80,37 @@
 // Public Code
 //--------------------------------------------------------------------------------------------------

+impl QEMUOutput {
+    /// Create a new instance.
+    pub const fn new() -> QEMUOutput {
+        QEMUOutput {
+            inner: NullLock::new(QEMUOutputInner::new()),
+        }
+    }
+}
+
 /// Return a reference to the console.
-pub fn console() -> impl console::interface::Write {
-    QEMUOutput {}
+pub fn console() -> &'static impl console::interface::All {
+    &QEMU_OUTPUT
+}
+
+//------------------------------------------------------------------------------
+// OS Interface Code
+//------------------------------------------------------------------------------
+use synchronization::interface::Mutex;
+
+/// Passthrough of `args` to the `core::fmt::Write` implementation, but guarded by a Mutex to
+/// serialize access.
+impl console::interface::Write for QEMUOutput {
+    fn write_fmt(&self, args: core::fmt::Arguments) -> fmt::Result {
+        // Fully qualified syntax for the call to `core::fmt::Write::write:fmt()` to increase
+        // readability.
+        self.inner.lock(|inner| fmt::Write::write_fmt(inner, args))
+    }
+}
+
+impl console::interface::Statistics for QEMUOutput {
+    fn chars_written(&self) -> usize {
+        self.inner.lock(|inner| inner.chars_written)
+    }
 }

diff -uNr 03_hacky_hello_world/src/console.rs 04_safe_globals/src/console.rs
--- 03_hacky_hello_world/src/console.rs
+++ 04_safe_globals/src/console.rs
@@ -10,10 +10,22 @@

 /// Console interfaces.
 pub mod interface {
+    use core::fmt;
+
     /// Console write functions.
-    ///
-    /// `core::fmt::Write` is exactly what we need for now. Re-export it here because
-    /// implementing `console::Write` gives a better hint to the reader about the
-    /// intention.
-    pub use core::fmt::Write;
+    pub trait Write {
+        /// Write a Rust format string.
+        fn write_fmt(&self, args: fmt::Arguments) -> fmt::Result;
+    }
+
+    /// Console statistics.
+    pub trait Statistics {
+        /// Return the number of characters written.
+        fn chars_written(&self) -> usize {
+            0
+        }
+    }
+
+    /// Trait alias for a full-fledged console.
+    pub trait All = Write + Statistics;
 }

diff -uNr 03_hacky_hello_world/src/main.rs 04_safe_globals/src/main.rs
--- 03_hacky_hello_world/src/main.rs
+++ 04_safe_globals/src/main.rs
@@ -107,6 +107,7 @@
 #![feature(format_args_nl)]
 #![feature(global_asm)]
 #![feature(panic_info_message)]
+#![feature(trait_alias)]
 #![no_main]
 #![no_std]

@@ -115,6 +116,7 @@
 mod cpu;
 mod panic_wait;
 mod print;
+mod synchronization;

 /// Early init code.
 ///
@@ -122,7 +124,15 @@
 ///
 /// - Only a single core must be active and running this function.
 unsafe fn kernel_init() -> ! {
+    use console::interface::Statistics;
+
     println!("[0] Hello from Rust!");

-    panic!("Stopping here.")
+    println!(
+        "[1] Chars written: {}",
+        bsp::console::console().chars_written()
+    );
+
+    println!("[2] Stopping here.");
+    cpu::wait_forever()
 }

diff -uNr 03_hacky_hello_world/src/synchronization.rs 04_safe_globals/src/synchronization.rs
--- 03_hacky_hello_world/src/synchronization.rs
+++ 04_safe_globals/src/synchronization.rs
@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2020-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Synchronization primitives.
+//!
+//! # Resources
+//!
+//!   - <https://doc.rust-lang.org/book/ch16-04-extensible-concurrency-sync-and-send.html>
+//!   - <https://stackoverflow.com/questions/59428096/understanding-the-send-trait>
+//!   - <https://doc.rust-lang.org/std/cell/index.html>
+
+use core::cell::UnsafeCell;
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// Synchronization interfaces.
+pub mod interface {
+
+    /// Any object implementing this trait guarantees exclusive access to the data wrapped within
+    /// the Mutex for the duration of the provided closure.
+    pub trait Mutex {
+        /// The type of the data that is wrapped by this mutex.
+        type Data;
+
+        /// Locks the mutex and grants the closure temporary mutable access to the wrapped data.
+        fn lock<R>(&self, f: impl FnOnce(&mut Self::Data) -> R) -> R;
+    }
+}
+
+/// A pseudo-lock for teaching purposes.
+///
+/// In contrast to a real Mutex implementation, does not protect against concurrent access from
+/// other cores to the contained data. This part is preserved for later lessons.
+///
+/// The lock will only be used as long as it is safe to do so, i.e. as long as the kernel is
+/// executing single-threaded, aka only running on a single core with interrupts disabled.
+pub struct NullLock<T>
+where
+    T: ?Sized,
+{
+    data: UnsafeCell<T>,
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+unsafe impl<T> Send for NullLock<T> where T: ?Sized + Send {}
+unsafe impl<T> Sync for NullLock<T> where T: ?Sized + Send {}
+
+impl<T> NullLock<T> {
+    /// Create an instance.
+    pub const fn new(data: T) -> Self {
+        Self {
+            data: UnsafeCell::new(data),
+        }
+    }
+}
+
+//------------------------------------------------------------------------------
+// OS Interface Code
+//------------------------------------------------------------------------------
+
+impl<T> interface::Mutex for NullLock<T> {
+    type Data = T;
+
+    fn lock<R>(&self, f: impl FnOnce(&mut Self::Data) -> R) -> R {
+        // In a real lock, there would be code encapsulating this line that ensures that this
+        // mutable reference will ever only be given out once at a time.
+        let data = unsafe { &mut *self.data.get() };
+
+        f(data)
+    }
+}

使用Rust在树莓派上编写操作系统 - 03 - 奇巧hello world

Thu, 05 Aug 2021 17:29:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 03 - Hacky Hello World；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

引入全局print!() 宏以尽早实现“printf调试”。
为了保证本章不至于过长，打印功能目前“滥用”了一个QEMU属性，以允许我们在未正确设置下使用树莓派的UART。
对如UART等真实硬件的使用，将在后续章节中逐步展开。

需要注意的新增代码

src/console.rs introduces interface Traits for console commands.
src/bsp/raspberrypi/console.rs implements the interface for QEMU's emulated UART.
The panic handler makes use of the new print!() to display user error messages.
There is a new Makefile target, make test, intended for automated testing. It boots the compiled kernel in QEMU, and checks for an expected output string produced by the kernel.
In this tutorial, it checks for the string Stopping here, which is emitted by the panic!() at the end of main.rs.
src/console.rs引入的interface中的trait将用于控制台命令行。
src/bsp/raspberrypi/console.rs为QEMU虚拟的UART设备实现了接口。
panic处理程序使用新的print!()宏显示用户错误消息。
新增了一个Makefile目标——make test——用于自动化测试。它能够在QEMU中引导编译后的内核，并检查内核能否输出预期的字符串。
- 在本章，它会检查由main.rs末尾的panic!()打印的字符串：Stopping here。

测试运行

至此，QEMU便不再以汇编模式运行了。从本章开始，它将显示console的输出。

$ make qemu
[...]
Hello from Rust!

Kernel panic: Stopping here.

与上一章代码的区别

diff -uNr 02_runtime_init/Cargo.toml 03_hacky_hello_world/Cargo.toml
--- 02_runtime_init/Cargo.toml
+++ 03_hacky_hello_world/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mingo"
-version = "0.2.0"
+version = "0.3.0"
 authors = ["Andre Richter <andre.o.richter@gmail.com>"]
 edition = "2018"


diff -uNr 02_runtime_init/Makefile 03_hacky_hello_world/Makefile
--- 02_runtime_init/Makefile
+++ 03_hacky_hello_world/Makefile
@@ -23,7 +23,7 @@
     KERNEL_BIN        = kernel8.img
     QEMU_BINARY       = qemu-system-aarch64
     QEMU_MACHINE_TYPE = raspi3
-    QEMU_RELEASE_ARGS = -d in_asm -display none
+    QEMU_RELEASE_ARGS = -serial stdio -display none
     OBJDUMP_BINARY    = aarch64-none-elf-objdump
     NM_BINARY         = aarch64-none-elf-nm
     READELF_BINARY    = aarch64-none-elf-readelf
@@ -34,7 +34,7 @@
     KERNEL_BIN        = kernel8.img
     QEMU_BINARY       = qemu-system-aarch64
     QEMU_MACHINE_TYPE =
-    QEMU_RELEASE_ARGS = -d in_asm -display none
+    QEMU_RELEASE_ARGS = -serial stdio -display none
     OBJDUMP_BINARY    = aarch64-none-elf-objdump
     NM_BINARY         = aarch64-none-elf-nm
     READELF_BINARY    = aarch64-none-elf-readelf
@@ -70,17 +70,20 @@
     --strip-all            \
     -O binary

-EXEC_QEMU = $(QEMU_BINARY) -M $(QEMU_MACHINE_TYPE)
+EXEC_QEMU          = $(QEMU_BINARY) -M $(QEMU_MACHINE_TYPE)
+EXEC_TEST_DISPATCH = ruby ../common/tests/dispatch.rb

 ##------------------------------------------------------------------------------
 ## Dockerization
 ##------------------------------------------------------------------------------
-DOCKER_IMAGE        = rustembedded/osdev-utils
-DOCKER_CMD          = docker run -t --rm -v $(shell pwd):/work/tutorial -w /work/tutorial
-DOCKER_CMD_INTERACT = $(DOCKER_CMD) -i
+DOCKER_IMAGE          = rustembedded/osdev-utils
+DOCKER_CMD            = docker run -t --rm -v $(shell pwd):/work/tutorial -w /work/tutorial
+DOCKER_CMD_INTERACT   = $(DOCKER_CMD) -i
+DOCKER_ARG_DIR_COMMON = -v $(shell pwd)/../common:/work/common

 DOCKER_QEMU  = $(DOCKER_CMD_INTERACT) $(DOCKER_IMAGE)
 DOCKER_TOOLS = $(DOCKER_CMD) $(DOCKER_IMAGE)
+DOCKER_TEST  = $(DOCKER_CMD) $(DOCKER_ARG_DIR_COMMON) $(DOCKER_IMAGE)



@@ -168,3 +171,28 @@
 ##------------------------------------------------------------------------------
 check:
 	@RUSTFLAGS="$(RUSTFLAGS)" $(CHECK_CMD) --message-format=json
+
+
+
+##--------------------------------------------------------------------------------------------------
+## Testing targets
+##--------------------------------------------------------------------------------------------------
+.PHONY: test test_boot
+
+ifeq ($(QEMU_MACHINE_TYPE),) # QEMU is not supported for the board.
+
+test_boot test :
+	$(call colorecho, "\n$(QEMU_MISSING_STRING)")
+
+else # QEMU is supported.
+
+##------------------------------------------------------------------------------
+## Run boot test
+##------------------------------------------------------------------------------
+test_boot: $(KERNEL_BIN)
+	$(call colorecho, "\nBoot test - $(BSP)")
+	@$(DOCKER_TEST) $(EXEC_TEST_DISPATCH) $(EXEC_QEMU) $(QEMU_RELEASE_ARGS) -kernel $(KERNEL_BIN)
+
+test: test_boot
+
+endif

diff -uNr 02_runtime_init/src/bsp/raspberrypi/console.rs 03_hacky_hello_world/src/bsp/raspberrypi/console.rs
--- 02_runtime_init/src/bsp/raspberrypi/console.rs
+++ 03_hacky_hello_world/src/bsp/raspberrypi/console.rs
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! BSP console facilities.
+
+use crate::console;
+use core::fmt;
+
+//--------------------------------------------------------------------------------------------------
+// Private Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// A mystical, magical device for generating QEMU output out of the void.
+struct QEMUOutput;
+
+//--------------------------------------------------------------------------------------------------
+// Private Code
+//--------------------------------------------------------------------------------------------------
+
+/// Implementing `core::fmt::Write` enables usage of the `format_args!` macros, which in turn are
+/// used to implement the `kernel`'s `print!` and `println!` macros. By implementing `write_str()`,
+/// we get `write_fmt()` automatically.
+///
+/// See [`src/print.rs`].
+///
+/// [`src/print.rs`]: ../../print/index.html
+impl fmt::Write for QEMUOutput {
+    fn write_str(&mut self, s: &str) -> fmt::Result {
+        for c in s.chars() {
+            unsafe {
+                core::ptr::write_volatile(0x3F20_1000 as *mut u8, c as u8);
+            }
+        }
+
+        Ok(())
+    }
+}
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// Return a reference to the console.
+pub fn console() -> impl console::interface::Write {
+    QEMUOutput {}
+}

diff -uNr 02_runtime_init/src/bsp/raspberrypi.rs 03_hacky_hello_world/src/bsp/raspberrypi.rs
--- 02_runtime_init/src/bsp/raspberrypi.rs
+++ 03_hacky_hello_world/src/bsp/raspberrypi.rs
@@ -4,4 +4,5 @@

 //! Top-level BSP file for the Raspberry Pi 3 and 4.

+pub mod console;
 pub mod cpu;

diff -uNr 02_runtime_init/src/console.rs 03_hacky_hello_world/src/console.rs
--- 02_runtime_init/src/console.rs
+++ 03_hacky_hello_world/src/console.rs
@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! System console.
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// Console interfaces.
+pub mod interface {
+    /// Console write functions.
+    ///
+    /// `core::fmt::Write` is exactly what we need for now. Re-export it here because
+    /// implementing `console::Write` gives a better hint to the reader about the
+    /// intention.
+    pub use core::fmt::Write;
+}

diff -uNr 02_runtime_init/src/main.rs 03_hacky_hello_world/src/main.rs
--- 02_runtime_init/src/main.rs
+++ 03_hacky_hello_world/src/main.rs
@@ -104,13 +104,17 @@
 //!     - It is implemented in `src/_arch/__arch_name__/cpu/boot.s`.
 //! 2. Once finished with architectural setup, the arch code calls `kernel_init()`.

+#![feature(format_args_nl)]
 #![feature(global_asm)]
+#![feature(panic_info_message)]
 #![no_main]
 #![no_std]

 mod bsp;
+mod console;
 mod cpu;
 mod panic_wait;
+mod print;

 /// Early init code.
 ///
@@ -118,5 +122,7 @@
 ///
 /// - Only a single core must be active and running this function.
 unsafe fn kernel_init() -> ! {
-    panic!()
+    println!("[0] Hello from Rust!");
+
+    panic!("Stopping here.")
 }

diff -uNr 02_runtime_init/src/panic_wait.rs 03_hacky_hello_world/src/panic_wait.rs
--- 02_runtime_init/src/panic_wait.rs
+++ 03_hacky_hello_world/src/panic_wait.rs
@@ -4,10 +4,16 @@

 //! A panic handler that infinitely waits.

-use crate::cpu;
+use crate::{cpu, println};
 use core::panic::PanicInfo;

 #[panic_handler]
-fn panic(_info: &PanicInfo) -> ! {
+fn panic(info: &PanicInfo) -> ! {
+    if let Some(args) = info.message() {
+        println!("\nKernel panic: {}", args);
+    } else {
+        println!("\nKernel panic!");
+    }
+
     cpu::wait_forever()
 }

diff -uNr 02_runtime_init/src/print.rs 03_hacky_hello_world/src/print.rs
--- 02_runtime_init/src/print.rs
+++ 03_hacky_hello_world/src/print.rs
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Printing.
+
+use crate::{bsp, console};
+use core::fmt;
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+#[doc(hidden)]
+pub fn _print(args: fmt::Arguments) {
+    use console::interface::Write;
+
+    bsp::console::console().write_fmt(args).unwrap();
+}
+
+/// Prints without a newline.
+///
+/// Carbon copy from <https://doc.rust-lang.org/src/std/macros.rs.html>
+#[macro_export]
+macro_rules! print {
+    ($($arg:tt)*) => ($crate::print::_print(format_args!($($arg)*)));
+}
+
+/// Prints with a newline.
+///
+/// Carbon copy from <https://doc.rust-lang.org/src/std/macros.rs.html>
+#[macro_export]
+macro_rules! println {
+    () => ($crate::print!("\n"));
+    ($($arg:tt)*) => ({
+        $crate::print::_print(format_args_nl!($($arg)*));
+    })
+}

diff -uNr 02_runtime_init/tests/boot_test_string.rb 03_hacky_hello_world/tests/boot_test_string.rb
--- 02_runtime_init/tests/boot_test_string.rb
+++ 03_hacky_hello_world/tests/boot_test_string.rb
@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+EXPECTED_PRINT = 'Stopping here'

使用Rust在树莓派上编写操作系统 - 02 - 运行时初始化

Tue, 03 Aug 2021 17:29:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 02 - Runtime Init；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

本章扩展了boot.s，以首次调用Rust代码。在跳转到Rust之前，一些运行时的初始化工作已经完成。
本章中被调用的Rust代码只能够通过调用panic!()宏来停止执行。
仍旧是查看make qemu的输出，以观察新增代码的运行情况。

需要注意的新增代码

新增了一些链接脚本（译注：仍位于link.ld中）：
- 新增的节包括：.rodata、.got、.data、.bss。（译注：详情参考ELF文件结构）
- 一个专用位置，用于存放_start()需要读取的引导时链接参数。（译注：新增src/bsp/raspberrypi/cpu.rs）
_arch/__arch_name__/cpu/boot.s中的_start()：
1. 如果当前核心不是core0，则挂起该核心。
2. 初始化内存，将bss节置为0。
3. 为Rust入口准备栈指针stack pointer。
4. 跳转至定义在arch/__arch_name__/cpu/boot.rs中的_start_rust()函数。
_start_rust()函数：
- 调用kernel_init()函数，从而调用panic!()宏，最终使得core0也被挂起。
该库目前使用cortex-acrate，该crate提供零开销抽象，并在处理CPU相关操作时封装unsafe代码。
- 具体使用参见_arch/__arch_name__/cpu.rs中的相关操作。

与上一章代码的区别

diff -uNr 01_wait_forever/Cargo.toml 02_runtime_init/Cargo.toml
--- 01_wait_forever/Cargo.toml
+++ 02_runtime_init/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mingo"
-version = "0.1.0"
+version = "0.2.0"
 authors = ["Andre Richter <andre.o.richter@gmail.com>"]
 edition = "2018"

@@ -21,3 +21,8 @@
 ##--------------------------------------------------------------------------------------------------

 [dependencies]
+
+# Platform specific dependencies
+[target.'cfg(target_arch = "aarch64")'.dependencies]
+cortex-a = { version = "6.x.x" }
+

diff -uNr 01_wait_forever/Makefile 02_runtime_init/Makefile
--- 01_wait_forever/Makefile
+++ 02_runtime_init/Makefile
@@ -152,6 +152,8 @@
 	$(call colorecho, "\nLaunching objdump")
 	@$(DOCKER_TOOLS) $(OBJDUMP_BINARY) --disassemble --demangle \
                 --section .text   \
+                --section .rodata \
+                --section .got    \
                 $(KERNEL_ELF) | rustfilt

 ##------------------------------------------------------------------------------

diff -uNr 01_wait_forever/src/_arch/aarch64/cpu/boot.rs 02_runtime_init/src/_arch/aarch64/cpu/boot.rs
--- 01_wait_forever/src/_arch/aarch64/cpu/boot.rs
+++ 02_runtime_init/src/_arch/aarch64/cpu/boot.rs
@@ -13,3 +13,15 @@

 // Assembly counterpart to this file.
 global_asm!(include_str!("boot.s"));
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// The Rust entry of the `kernel` binary.
+///
+/// The function is called from the assembly `_start` function.
+#[no_mangle]
+pub unsafe fn _start_rust() -> ! {
+    crate::kernel_init()
+}

diff -uNr 01_wait_forever/src/_arch/aarch64/cpu/boot.s 02_runtime_init/src/_arch/aarch64/cpu/boot.s
--- 01_wait_forever/src/_arch/aarch64/cpu/boot.s
+++ 02_runtime_init/src/_arch/aarch64/cpu/boot.s
@@ -3,6 +3,24 @@
 // Copyright (c) 2021 Andre Richter <andre.o.richter@gmail.com>

 //--------------------------------------------------------------------------------------------------
+// Definitions
+//--------------------------------------------------------------------------------------------------
+
+// Load the address of a symbol into a register, PC-relative.
+//
+// The symbol must lie within +/- 4 GiB of the Program Counter.
+//
+// # Resources
+//
+// - https://sourceware.org/binutils/docs-2.36/as/AArch64_002dRelocations.html
+.macro ADR_REL register, symbol
+	adrp	\register, \symbol
+	add	\register, \register, #:lo12:\symbol
+.endm
+
+.equ _core_id_mask, 0b11
+
+//--------------------------------------------------------------------------------------------------
 // Public Code
 //--------------------------------------------------------------------------------------------------
 .section .text._start
@@ -11,6 +29,34 @@
 // fn _start()
 //------------------------------------------------------------------------------
 _start:
+	// Only proceed on the boot core. Park it otherwise.
+	mrs	x1, MPIDR_EL1
+	and	x1, x1, _core_id_mask
+	ldr	x2, BOOT_CORE_ID      // provided by bsp/__board_name__/cpu.rs
+	cmp	x1, x2
+	b.ne	.L_parking_loop
+
+	// If execution reaches here, it is the boot core.
+
+	// Initialize DRAM.
+	ADR_REL	x0, __bss_start
+	ADR_REL x1, __bss_end_exclusive
+
+.L_bss_init_loop:
+	cmp	x0, x1
+	b.eq	.L_prepare_rust
+	stp	xzr, xzr, [x0], #16
+	b	.L_bss_init_loop
+
+	// Prepare the jump to Rust code.
+.L_prepare_rust:
+	// Set the stack pointer.
+	ADR_REL	x0, __boot_core_stack_end_exclusive
+	mov	sp, x0
+
+	// Jump to Rust code.
+	b	_start_rust
+
 	// Infinitely wait for events (aka "park the core").
 .L_parking_loop:
 	wfe

diff -uNr 01_wait_forever/src/_arch/aarch64/cpu.rs 02_runtime_init/src/_arch/aarch64/cpu.rs
--- 01_wait_forever/src/_arch/aarch64/cpu.rs
+++ 02_runtime_init/src/_arch/aarch64/cpu.rs
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! Architectural processor code.
+//!
+//! # Orientation
+//!
+//! Since arch modules are imported into generic modules using the path attribute, the path of this
+//! file is:
+//!
+//! crate::cpu::arch_cpu
+
+use cortex_a::asm;
+
+//--------------------------------------------------------------------------------------------------
+// Public Code
+//--------------------------------------------------------------------------------------------------
+
+/// Pause execution on the core.
+#[inline(always)]
+pub fn wait_forever() -> ! {
+    loop {
+        asm::wfe()
+    }
+}

diff -uNr 01_wait_forever/src/bsp/raspberrypi/cpu.rs 02_runtime_init/src/bsp/raspberrypi/cpu.rs
--- 01_wait_forever/src/bsp/raspberrypi/cpu.rs
+++ 02_runtime_init/src/bsp/raspberrypi/cpu.rs
@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+//
+// Copyright (c) 2018-2021 Andre Richter <andre.o.richter@gmail.com>
+
+//! BSP Processor code.
+
+//--------------------------------------------------------------------------------------------------
+// Public Definitions
+//--------------------------------------------------------------------------------------------------
+
+/// Used by `arch` code to find the early boot core.
+#[no_mangle]
+#[link_section = ".text._start_arguments"]
+pub static BOOT_CORE_ID: u64 = 0;

diff -uNr 01_wait_forever/src/bsp/raspberrypi/link.ld 02_runtime_init/src/bsp/raspberrypi/link.ld
--- 01_wait_forever/src/bsp/raspberrypi/link.ld
+++ 02_runtime_init/src/bsp/raspberrypi/link.ld
@@ -11,17 +11,43 @@
 PHDRS
 {
     segment_rx PT_LOAD FLAGS(5); /* 5 == RX */
+    segment_rw PT_LOAD FLAGS(6); /* 6 == RW */
 }

 SECTIONS
 {
     . =  __rpi_load_addr;
+                                        /*   ^             */
+                                        /*   | stack       */
+                                        /*   | growth      */
+                                        /*   | direction   */
+   __boot_core_stack_end_exclusive = .; /*   |             */

     /***********************************************************************************************
-    * Code
+    * Code + RO Data + Global Offset Table
     ***********************************************************************************************/
     .text :
     {
         KEEP(*(.text._start))
+        *(.text._start_arguments) /* Constants (or statics in Rust speak) read by _start(). */
+        *(.text._start_rust)      /* The Rust entry point */
+        *(.text*)                 /* Everything else */
     } :segment_rx
+
+    .rodata : ALIGN(8) { *(.rodata*) } :segment_rx
+    .got    : ALIGN(8) { *(.got)     } :segment_rx
+
+    /***********************************************************************************************
+    * Data + BSS
+    ***********************************************************************************************/
+    .data : { *(.data*) } :segment_rw
+
+    /* Section is zeroed in pairs of u64. Align start and end to 16 bytes */
+    .bss : ALIGN(16)
+    {
+        __bss_start = .;
+        *(.bss*);
+        . = ALIGN(16);
+        __bss_end_exclusive = .;
+    } :NONE
 }

diff -uNr 01_wait_forever/src/bsp/raspberrypi.rs 02_runtime_init/src/bsp/raspberrypi.rs
--- 01_wait_forever/src/bsp/raspberrypi.rs
+++ 02_runtime_init/src/bsp/raspberrypi.rs
@@ -4,4 +4,4 @@

 //! Top-level BSP file for the Raspberry Pi 3 and 4.

-// Coming soon.
+pub mod cpu;

diff -uNr 01_wait_forever/src/cpu.rs 02_runtime_init/src/cpu.rs
--- 01_wait_forever/src/cpu.rs
+++ 02_runtime_init/src/cpu.rs
@@ -4,4 +4,13 @@

 //! Processor code.

+#[cfg(target_arch = "aarch64")]
+#[path = "_arch/aarch64/cpu.rs"]
+mod arch_cpu;
+
 mod boot;
+
+//--------------------------------------------------------------------------------------------------
+// Architectural Public Reexports
+//--------------------------------------------------------------------------------------------------
+pub use arch_cpu::wait_forever;

diff -uNr 01_wait_forever/src/main.rs 02_runtime_init/src/main.rs
--- 01_wait_forever/src/main.rs
+++ 02_runtime_init/src/main.rs
@@ -102,8 +102,8 @@
 //!
 //! 1. The kernel's entry point is the function `cpu::boot::arch_boot::_start()`.
 //!     - It is implemented in `src/_arch/__arch_name__/cpu/boot.s`.
+//! 2. Once finished with architectural setup, the arch code calls `kernel_init()`.

-#![feature(asm)]
 #![feature(global_asm)]
 #![no_main]
 #![no_std]
@@ -112,4 +112,11 @@
 mod cpu;
 mod panic_wait;

-// Kernel code coming next tutorial.
+/// Early init code.
+///
+/// # Safety
+///
+/// - Only a single core must be active and running this function.
+unsafe fn kernel_init() -> ! {
+    panic!()
+}

diff -uNr 01_wait_forever/src/panic_wait.rs 02_runtime_init/src/panic_wait.rs
--- 01_wait_forever/src/panic_wait.rs
+++ 02_runtime_init/src/panic_wait.rs
@@ -4,9 +4,10 @@

 //! A panic handler that infinitely waits.

+use crate::cpu;
 use core::panic::PanicInfo;

 #[panic_handler]
 fn panic(_info: &PanicInfo) -> ! {
-    unimplemented!()
+    cpu::wait_forever()
 }

使用Rust在树莓派上编写操作系统 - 01 - 无限循环

Mon, 02 Aug 2021 17:29:00 GMT

:::warning 本文所有内容均为翻译，原文：Tutorial 01 - Wait Forever；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

概述

本章搭建了项目骨架。
一小段汇编代码让CPU的所有核心都执行内核代码。（译注：执行后CPU占用率100%）

构建

Makefile目标:
- doc：生成文档。
- qemu：在QEMU中运行内核。
- clippy
- clean
- readelf：检查ELF输出。
- objdump：检查汇编。
- nm：检查符号。

需要关注的代码

BSP中的link.ld为链接脚本。
- 加载地址为0x8_0000
- 目前只有一个节（section）：代码节.text。（译注：详情参考ELF文件结构）
main.rs中主要关注几个内部属性：
- #![no_std]（译注：编译禁用自动引用标准库）, #![no_main]（译注：不使用main函数，我们自己提供入口点函数）
boot.s中：汇编函数_start()将执行wfe（等待事件），挂起所有执行_start()CPU核心。
我们需要定义一个#[panic_handler]以使编译通过。
- 使用unimplemented!()宏作为占位符，否则可能会被编译器优化掉。

使用Rust在树莓派上编写操作系统 - 00 - 前言

Sun, 01 Aug 2021 11:56:00 GMT

:::warning 本文前半部分内容翻译自原文：Before we start；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

在我们开始之前

以下文本是文档的1:1副本，会出现在每章教程所对应的内核主要源文件的顶部。文档描述了相应源文件的结构，并尝试解释该实现背后的原理。请阅读该文档，以熟悉将会在教程中遇到的内容，文档将帮助你更好地浏览代码，并理解每一章教程之间的递进关系。

另请注意，以下文本将引用第一批教程中尚不存在的源文件（如**/memory.rs）或函数。随着教程的推进，它们将逐渐被添加。

玩得开心！

代码组织和架构

代码分为不同的模块，每个模块代表一个典型的内核子系统。子系统的顶层模块文件直接位于src文件夹中。例如，src/memory.rs将包含与所有内存管理相关的代码。

处理器架构代码的可见性

内核的某些子系统基于特定目标处理器架构的底层代码。对于每个支持的处理器架构，在src/_arch中都存在一个子文件夹，例如，src/_arch/aarch64。

这些架构文件夹反映了在src中布置的子系统模块。例如，属于内核MMU子系统（src/memory/mmu.rs）的架构相关代码将位于src/_arch/aarch64/memory/mmu.rs。里面的文件将以模块的方式，通过path属性加载到src/memory/mmu.rs中。通常使用以arch_为前缀，后接通用模块名称，作为导入的模块名称。

例如，这是src/memory/mmu.rs的前几行：

#[cfg(target_arch = "aarch64")]
#[path = "../_arch/aarch64/memory/mmu.rs"]
mod arch_mmu;

大多数情况下，arch_module中的项会被父模块以公开方式重导出。如此，针对各架构的模块就可以对外提供其各项实现，而调用者不必关心哪个架构已经被条件编译了。

BSP代码

BSP即Board Support Package。BSP代码位于src/bsp.rs下，包含目标板特定的变量和函数，例如目标板内存的映射、目标板特有设备的驱动程序实例之类的东西。

就像处理器架构代码那样，BSP代码的模块结构，类似内核子系统代码的模块结构，只不过这次没有重导出。这意味着必须从bsp命名空间开始调用其提供的任何内容，例如bsp::driver::driver_manager()。

内核接口

arch和bsp都包含条件编译的代码，具体取决于编译内核的目标环境和板卡。例如，树莓派3和树莓派4的中断控制器的硬件是不同的，但我们希望其余的内核能够很方便地与两者中的任何一个一起使用。

为了在arch、bsp和通用内核代码之间提供一个清晰的抽象，我们在只要有可能且有意义的地方封装了interfacetrait。这些trait定义在各子系统模块中，以强制我们实现面向接口编程，而是不面向实现编程。例如，将有一个通用IRQ处理接口，由两个版本树莓派各自的中断控制器驱动实现，并且只将该接口导出到内核的其余部分。

        +-------------------+
        | Interface (Trait) |
        |                   |
        +--+-------------+--+
           ^             ^
           |             |
           |             |
+----------+--+       +--+----------+
| kernel code |       |  bsp code   |
|             |       |  arch code  |
+-------------+       +-------------+

总结

对于逻辑内核子系统，相应的代码可以分发在不同的物理位置。以内存子系统为例：

src/memory.rs与src/memory/**/*：
- 通用代码并不知道目标处理器架构和BSP特征。
  - 示例：一个用于将内存块归零的函数。
- 由arch或BSP中的代码实现的内存子系统的接口。
  - 示例：定义MMU函数原型的MMU接口。
src/bsp/__board_name__/memory.rs与src/bsp/__board_name__/memory/**/*：
- 特定BSP的代码。
- 示例：特定板子的内存映射（DRAM和MMIO设备的物理地址）。
src/_arch/__arch_name__/memory.rs与src/_arch/__arch_name__/memory/**/*：
- 特定处理器架构的代码。
- 示例：实现__arch_name__处理器架构的MMU接口。

从名称空间的角度来看，内存子系统代码位于：

crate::memory::*
crate::bsp::memory::*

启动流程

内核的入口点是函数cpu::boot::arch_boot::_start()。

其实现位于src/_arch/__arch_name__/cpu/boot.rs。

下面不是翻译，是我写的使用方法。

下载

直接克隆本教程即可使用：

gh repo clone rust-embedded/rust-raspberrypi-OS-tutorials

rust-analyzer

我的macOS貌似通过macports装了另一个版本的Rust，要知道通过rustup安装的Rust位于~/.cargo/bin/中，而port安装的Rust位于/opt/local/bin/中。这导致vscode启动时，默认加载的环境变量可能会使用port的版本，而该版本并不是rustup安装的，可能缺少rust-src等组件，这会导致rust-analyzer工作异常。尝试解决：

😕 直接export环境变量后启动vscode，能解决问题，但是每次启动很麻烦，并不优雅。
😕 修改shell的各个profile环境变量，但是这会牵连出很多未知问题，因为可能影响到其他程序的环境变量搜索顺序。（附：shell各profile的加载顺序介绍1 2）
😕 尝试修改rust项目中配置文件的rustc设置，发现对rust-analyzer并不起作用。
😕 直接卸载port版本，简单有效，但是由于忘记了port版本是不是我有意识安装的，所以并不知道会不会对其他程序产生影响。
🎉 修改vscode的rust-analyzer插件的extraEnv配置，该配置位于：扩展: rust-analyzer -> 扩展设置 -> 搜索extraEnv -> 在 setting.json 中编辑，打开编辑器，向extraEnv字典新增两行路径：
```
    "rust-analyzer.server.extraEnv": {
        "RUSTC": "/Users/zealot/.cargo/bin/rustc",
        "RUSTDOC": "/Users/zealot/.cargo/bin/rustdoc"
    }
```
重新加载即可。

运行

自第一章起，每一章都是一个可执行的小系统，比如进入01_WAIT_FOREVER目录，即可执行make qemu来编译，并在虚拟环境中运行内核。

使用Rust在树莓派上编写操作系统 - 项目介绍

Sun, 01 Aug 2021 11:56:00 GMT

:::warning 本文所有内容均为翻译，原文：README.md；原项目：Operating System development tutorials in Rust on the Raspberry Pi :::

ℹ️ 介绍

这是一个教程系列，面向那些不熟悉ARM 64 bit ARMv8-A架构的操作系统开发爱好者。这些教程将逐步指导如何从头开始为嵌入式系统编写宏内核。教程涵盖了常见操作系统功能的实现，例如向串口写数据、设置虚拟内存和处理硬件异常。同时，利用Rust特有的语言特性来提供内存安全性和执行速度。

祝读者们看得开心！

Andre (@andre-richter)

P.S.：中文🇨🇳译版的教程由@colachg和@readlnh发起。您可以在相应的文件夹中以README.CN.md的形式找到这些翻译。当然，翻译会一定程度上落后原文的进度。

📑 组织

教程的每一章都包含一个独立可引导的二进制内核文件。
每一篇新的教程都建立在前一篇的基础上。
每一篇教程的README文件都会有一个简短的tl;dr小节，用于简要概述本章的新内容，并展示与前一篇教程源代码的diff，以方便读者检查修改和新增的代码。
- 除了tl;dr小节之外，一些教程还配有完整、详尽的文本说明。这个系列教程的长期计划是为教程的所有章节都编写详细说明，不过目前我仅为我认为tl;dr和diff不足以解释清楚的教程章节编写详细说明。
这些教程中的代码支持在树莓派3和树莓派4上运行。
- 教程的第1章到第5章是基础代码，仅用于在QEMU中运行。
- 从教程的第5章开始，您就可以在真正的树莓派上加载运行内核，并通过UART观察输出。
尽管教程将树莓派3和4作为为目标开发板，但文章中的代码均以模块化方式编写，可以轻松移植到其他CPU架构或开发板上。
- 如果真的有朋友尝试为RISC-V指令集编写实现我将非常高兴！
代码编辑器的选择，我推荐安装Rust Analyzer插件的Visual Studio Code。
除了阅读教程每一章的文本之外，还可以使用cargo的make doc命令，以方便的查看源码中丰富的文档和注释。

`make doc` 的输出

🛠 系统要求

本教程主要针对基于Linux的发行版。大部分代码同样适用于一些Unix版本，例如macOS，但这只是实验性的。

🚀 tl;dr 版本

安装Docker。
确保你的用户帐户在docker group中。
准备 Rust 工具链。第一次使用rust-toolchain就能够自动搞定大部分工具。而需要我们手动操作的是：
1. 如果你已经安装了Rust：
```
cargo install cargo-binutils rustfilt
```
1. 如果你需要从头安装Rust：
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

source $HOME/.cargo/env
cargo install cargo-binutils rustfilt
```
如果您使用Visual Studio Code，我们强烈建议你使用Rust Analyzer插件。

如果你不使用Linux，则还需要安装一些 Rubygems：

sudo gem install bundler
bundle config set path '.vendor/bundle'
bundle install

🧰 更多细节：消除工具链麻烦

本系列试图将重点放在用户友好性上。因此，已尽可能消除嵌入式开发中最大的痛点：工具链麻烦。

Rust本身已经在这方面提供了很大帮助，因为它内置了对交叉编译的支持。我们从x86主机交叉编译到树莓派的AArch64架构所需的一切都将由rustup自动安装。但是，除了Rust编译器之外，我们还将使用更多工具。其中：

QEMU：用于在编程机上模拟目标机的内核。
Minipush：我们自制的小工具，可通过UART按需将内核加载到树莓派上。
OpenOCD和GDB：用于在目标机上进行调试。

在编程主机上安装、编译每个工具的正确版本时，可能会出错很多。例如，编程机的发行版可能不提供所需的最新版本。或者在编译这些工具之一时缺少一些难以获得的依赖项。

这就是为什么我们会尽可能使用Docker。我们提供了一个附带的容器，其中预装了所有需要的工具或依赖项，一旦有需要docker就会自动pull下来。如果您想了解有关Docker的更多信息，并查看我们提供的容器，请查看docker文件夹。

📟 USB 串行输出

由于教程中开发的内核在真实硬件上运行，因此强烈建议您购买USB转串口线缆以获得完整体验。

你可以购买诸如[1] [2]的USB转串口线缆，当然还有许多其他类似的线缆。总的来说，你的线缆最好基于CP2102芯片。
将线缆连接到树莓派的GND和GPIO14/15引脚，如下所示。
第5章是第一个用到它的地方。查看有关如何准备SD卡以从中引导自制内核的说明。
从第6章开始，在树莓派上启动内核就会变得很很舒服。本教程开发了一个名为chainloader的程序，用于在最后手动将内核拷贝到树莓派上，并将使你能够在启动期间通过UART按需加载教程内核。

🙌 致谢

教程的原始版本最初是基于Zoltan Baldaszti用C编写的[RPi3上的裸机编程教程](https://github.com/bztsrc/ raspi3-tutorial。谢谢你给了我们一个良好的开始！

许可

以下两种许可均可：

Apache 许可证，版本 2.0，(LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

参与本项目

您的提交将如Apache-2.0许可定义的那样，会纳入上述两个许可，且不包含任何附加条款。

使用树莓派为音响添加AirPlay功能

Mon, 14 Jun 2021 09:08:00 GMT

今年618大出血买了音响功放，接口很多，但是就是没用接入WiFi当网络音响的功能，也就是苹果的AirPlay或安卓的DLNA/UPnP。虽然天逸已经提供了安卓APP，但是目前并没有苹果的APP，不过好在我有空闲的树莓派，可以将功放升级成AirPlay设备。

背景

一开始，我是把大硬盘直接挂在树莓派上，用Raspberry OS系统GUI播放音乐（比如用vlc player），这期间总是出现各种各样的不爽，比如压缩软件不顺手啊、中/日/法语字符集不全啊、2.4G的WiFi信号晚上不稳定啊什么的……所以就想利用树莓派给功放的DAC加上AirPlay功能，直接挂在家里的WiFi上或插网线做多媒体音箱。

1 `shairport-sync` - AirPlay

shairport-sync这个库是专门用来支持AirPlay的，主要参考树莓派的简要安装说明以及故障排查

例行调整命令行的用户体验：

sudo apt install -y ufw zsh vim tmux
chsh -s $(which zsh)
sh -c "$(wget -O- https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

1.1 关闭WiFi适配器的省电模式或者低功耗模式

对于树莓派3或者更高级的自带WiFi的板子，需要手动关闭省电模式，否则AirPlay可能会在家里的WiFi环境中消失一段时间，或者产生很大的延迟：

sudo iwconfig wlan0 power off

不过我打算用的是树莓派2B，iwconfig里能看到Power Management:off，因此不需要做上面的操作。

1.2 添加防火墙例外

sudo ufw allow proto tcp to 0.0.0.0/0 port 22 comment "sshd listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 80 comment "for http server"
sudo ufw allow proto tcp to 0.0.0.0/0 port 5900 comment "vnc server listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 8000 comment "for python -m http.server 8000"

sudo ufw allow from 192.168.1.1/24 to any port 5353 comment "shairport-sync"
sudo ufw allow proto tcp from 192.168.1.1/24 to any port 3689 comment "shairport-sync"
sudo ufw allow proto tcp from 192.168.1.1/24 to any port 5000:5005 comment "shairport-sync"
sudo ufw allow proto udp from 192.168.1.1/24 to any port 6000:6005 comment "shairport-sync"
sudo ufw allow proto udp from 192.168.1.1/24 to any port 35000:65535 comment "shairport-sync"

sudo ufw default deny 

sudo ufw enable

1.3 安装依赖

sudo apt install -y build-essential git xmltoman autoconf automake libtool \
    libpopt-dev libconfig-dev libasound2-dev avahi-daemon \
    libavahi-client-dev libssl-dev libsoxr-dev

1.4 下载并安装

git clone https://github.com/mikebrady/shairport-sync.git
cd shairport-sync
autoreconf -fi
./configure --sysconfdir=/etc --with-alsa --with-soxr --with-avahi --with-ssl=openssl --with-systemd
make
sudo make install

1.5 设置开机启动

sudo systemctl enable shairport-sync
sudo systemctl start shairport-sync

1.6 设置配置文件

我的板子是Raspberry Pi 2 Model B Rev 1.1，把天逸AD86-D功放miniUSB声卡插在树莓派的USB口上，在功放切换到PC模式时，aplay -l的输出为：

**** List of PLAYBACK Hardware Devices ****
card 0: b1 [bcm2835 HDMI 1], device 0: bcm2835 HDMI 1 [bcm2835 HDMI 1]
  Subdevices: 4/4
  Subdevice #0: subdevice #0
  Subdevice #1: subdevice #1
  Subdevice #2: subdevice #2
  Subdevice #3: subdevice #3
card 1: Headphones [bcm2835 Headphones], device 0: bcm2835 Headphones [bcm2835 Headphones]
  Subdevices: 4/4
  Subdevice #0: subdevice #0
  Subdevice #1: subdevice #1
  Subdevice #2: subdevice #2
  Subdevice #3: subdevice #3
card 2: AUDIO [USB AUDIO], device 0: USB Audio [USB Audio]
  Subdevices: 0/1
  Subdevice #0: subdevice #0

因此，我应该将shairport-sync配置文件（在make install输出中可以看到配置文件位于/etc/shairport-sync.conf）的alsa部分里output_device改为hw:2（这里写hw:2,0应该也可以），通过alsamixer选择USB AUDIO声卡时可以看到mixer是PCM，所以mixer_control_name也得修改为PCM：

alsa =
{
  output_device = "hw:2"; // the name of the alsa output device. Use "shairport-sync -h" to discover the names of ALSA hardware devices. "alsamixer" or "aplay" to find out the names of devices, mixers, etc.
  mixer_control_name = "PCM"; // the name of the mixer to use to adjust output volume. If not specified, volume in adjusted in software.
  ...
}

保存并重启服务：

sudo systemctl start shairport-sync

此时可以在macOS的声音控制面板中看到一个名为Raspberrypi的扬声器。切换到这个扬声器时，电脑只能控制是否静音，不能控制音量；而树莓派上的alsamixer不论选什么卡都无法控制音量，因此只能通过功放控制音量。

2 `samba` - 文件夹共享

为了解决把硬盘挂载树莓派上不爽的体验，可以选择用samba把盘共享在网络上。不过samba库有个几十兆，可以临时调整树莓派的路由表，把网关指向家里的OpenWrt上，这样下载软件包更快：

sudo route add default gw 192.168.1.150

2.1 安装`samba`

sudo apt install samba samba-common-bin

2.2 挂载硬盘

我的硬盘是希捷12年前的FreeAgent古董盘，在RaspberryOS上是自动挂载到/media/pi/FreeAgent Drive上的，大概是自动帮我执行了：

sudo mount /dev/sda1/ "/media/pi/FreeAgent Drive"

2.3 修改配置文件

修改samba的配置文件，将挂载点发布，并设置读写权限和认证。在/etc/samba/smb.conf的最后追加：

[FreeAgentShare]
path = /media/pi/FreeAgent Drive
writeable=Yes
create mask=0777
directory mask=0777
public=no

2.4 设置访问用户

将pi添加为samba的认证用户，并设置密码：

sudo smbpasswd -a pi

2.5 重启服务

sudo systemctl restart smbd

2.6 配置防火墙例外

sudo ufw allow proto udp from 192.168.1.1/24 to any port 137 comment "samba"
sudo ufw allow proto udp from 192.168.1.1/24 to any port 138 comment "samba"
sudo ufw allow proto tcp from 192.168.1.1/24 to any port 139 comment "samba"
sudo ufw allow proto tcp from 192.168.1.1/24 to any port 445 comment "samba"

2.7 连接

使用macOS连接，打开Finder，⌘+K打开“连接服务器”，地址填写smb://raspberrypi.local/FreeAgentShare，输入用户名密码就能连上了。（树莓派的默认主机名就是raspberrypi.local）

使用Rust编写操作系统 - 4.1 - Async/Await

Wed, 14 Apr 2021 15:18:00 GMT

:::warning 本文所有内容均为翻译，原文：Async/Await；原项目：Writing an OS in Rust :::

本文将探讨协作式多任务处理以及Rust的async/await特性。我们将详细研究async/await在Rust中的工作方式，包括Futuretrait的设计，状态机转换和pinning（译注：内存固定）。然后，我们通过创建异步键盘任务和基本执行器，使得内核具备对async/await的基本支持。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-12分支中找到。

多任务

多任务处理是大多数操作系统的基本特征之一，这是一种能够同时执行多个任务的功能。例如，在看这篇文章时，你可能会打开其他程序，例如文本编辑器或终端窗口。即使只打开一个浏览器窗口，也可能会有各种后台任务来管理桌面窗口，检查更新或为文件建立索引。

尽管所有任务看上去都是并行运行的，但实际在CPU内核上一次只能执行一个任务。为了产生任务可以并行运行的错觉，操作系统会在活动任务之间快速切换，以使得每个任务都可以有一些进展。由于计算机速度很快，因此大多数时候我们不会注意到这些切换。

单核CPU一次只能执行一个任务，而多核CPU可以真正并行地运行多个任务。例如，具有8个内核的CPU可以同时运行8个任务。我们将在以后的文章中解释如何设置多核CPU。在本文中，为简单起见，我们将重点介绍单核CPU。（值得注意的是，所有多核CPU都仅从单个活动核启动，因此我们目前仍然可以将它们视为单核CPU。）

多任务处理有两种形式：协作式多任务要求任务定期放弃对CPU的控制，以便其他任务可以继续执行。抢占式多任务使用操作系统功能通过强行暂停线程，以在任意时间点切换线程。在下文中，我们将更详细地探讨多任务的两种形式，并讨论它们各自的优缺点。

抢占式多任务

抢占式多任务处理的思路是使用操作系统控制何时切换任务，思路利用了操作系统在每个中断上可以重获CPU控制权这一机制。这样，只要系统有新输入可用，就可以切换任务。例如，当鼠标移动或网络数据包到达时，就可以执行任务切换。操作系统还可以通过配置硬件计时器在到达特定时间时发送中断，来确定允许任务运行的确切时间。

下图说明了硬件中断上的任务切换过程：

在第一行中，CPU正在执行程序A的任务A1，所有其他任务均被暂停。在第二行中，硬件中断到达CPU。就像硬件中断一文中介绍的那样，CPU立即停止执行任务A1，并跳转到中断描述符表(IDT)中定义的中断处理程序。通过中断处理程序，操作系统现在可以再次控制CPU，从而使它可以切换到任务B1，而不是继续执行任务A1。

状态保存

鉴于任务会在任意时间点中断，这些任务可能正处于某些计算中。为了能够在以后恢复这些任务，操作系统必须备份任务的整个状态，包括其调用栈和所有CPU寄存器的值。此过程称为上下文切换。

由于调用栈可能会非常大，操作系统通常会为每个任务设置单独的调用栈，而不是在每次任务切换时备份调用栈的内容。具有单独调用栈的此类任务称为执行线程或简称线程。通过为每个任务设置单独的栈，上下文切换时仅需要保存寄存器的内容即可（包括程序计数器和栈指针）。这种方法可以最大程度地减少上下文切换的性能开销，这非常重要，因为上下文切换通常能够到达每秒100次。

讨论

抢占式多任务处理的主要优点是操作系统可以完全控制任务的执行时间。这样即使不要求任务间的相互协作，也能够确保公平分配各任务的CPU时间。在运行第三方任务时或在多个用户共享系统时，这一点尤其重要。

抢占式的缺点是每个任务都需要自己的调用栈。与共享调用栈相比，这会导致每个任务的内存使用量增加，并且通常会限制系统中的任务的总量。抢占式的另一个缺点是，即使任务仅使用了一小部分寄存器，操作系统在每个任务切换时仍必须保存全部的CPU寄存器状态。

抢占式多任务处理和线程是操作系统的基本要素，因为它们能够使操作系统能够运行不受信任的用户空间程序，我们将在以后的文章中详细讨论这些概念。在本文中，我们将专注于协作式多任务处理，这种方式也能够为内核提供有用的多任务功能。

协作式多任务

协作多任务处理并不是在任意时间点强行暂停正在运行的任务，而是让每个任务运行到自愿放弃对CPU的控制为止。这使任务可以在方便的时间点暂停自己，比如当该任务需要等待I/O操作时。

合作多任务通常使用在语言层，例如以协程或async/await的形式。该思路是由程序员或编译器都将yield操作插入到程序中，从而使该任务放弃对CPU的控制以允许其他任务运行。在复杂循环的每次迭代之后都可以插入一个yield。

协作式多任务通常与异步操作一起使用。与抢占式的一直等待直到操作完成并在期间阻止其他任务的执行，在协作式中若操作尚未完成，则异步操作将返回一个“未就绪”状态。在这种情况下，等待的任务可以执行一个yield操作以允许其他任务运行。

状态保存

由于任务会为自己定义暂停点，因此它们不需要操作系统来保存其状态。与抢占式相比，协作式可以在暂停之前只保存用以在继续时恢复操作的必要的寄存器状态，这通常可以提高性能。例如，刚完成复杂计算的任务可能只需要备份计算的最终结果，因为此时中间结果已经不再需要了。

由语言支持实现的协作任务甚至可以在暂停之前只备份调用堆栈的所需部分。例如，Rust的async/await实现会将所有需要的局部变量存储在自动生成的结构体中（见下文）。通过在暂停之前备份调用堆栈的相关部分，所有任务可以共享一个调用堆栈，从而减少了每个任务的内存消耗。这样就可以创建几乎无限的协作任务，而不用担心内存耗尽。

讨论

协作式多任务处理的缺点是，一个非协作的任务可能会无限期地运行下去。那么，恶意程序或有bug的任务可能会阻止其他任务的运行，并拖慢甚至阻塞整个系统。因此，当且仅当所有任务都支持协作时才能使用协作式多任务处理。而让操作系统依赖于任意用户级程序的协作并不是一个好主意。

但是，协作多任务的强大性能和内存优势，使其成为在程序内部使用的好方法，特别是与异步操作结合使用时。由于操作系统内核需要与异步硬件交互，性能至关重要，因此协作多任务似乎是一个实现并发的好方法。

Rust的async/await

Rust语言以async/await的形式为协作式多任务提供了原生支持。在探讨什么是async/await及其工作原理之前，我们需要了解Rust中的futures和异步编程是如何工作的。

Futures

Future表示一个可能尚不可用的值。例如，这个值可能是由另一个任务计算的整数，也可能是从网络下载的文件。Future并不需要一直要等待到该值可用，它可以继续执行其他代码直到需要用到该值为止。

示例

最好用一个小例子说明futures的概念：

此序列图展示了一个main函数，它从文件系统读取文件，然后调用foo函数。图中以不同的方式执行两次此过程：一次是调用同步函数read_file，一次是调用异步函数async_read_file。

在同步调用中，main函数需要一直等待，直到该文件从文件系统中加载完毕。只有这样，它才能继续调用foo函数，并再次等待其执行结果。

通过异步async_read_file调用，文件系统直接返回一个future并在后台异步加载文件。这使main函数可以更早地调用foo函数，然后foo函数与文件加载并行运行。在此示例中，文件加载甚至在foo返回之前就完成了，因此main无需继续等待foo返回，可以直接处理文件。

Rust中的Futures

在Rust中，futures由Futuretrait表示，其定义如下：

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output>;
}

关联类型Output指定异步返回值的类型。例如，上图中的async_read_file函数将返回一个Output设置为File的Future实例。

调用poll方法可以检查该值是否已经可用。它将返回一个枚举Poll，如下所示：

pub enum Poll<T> {
    Ready(T),
    Pending,
}

如果该值已经可用（例如，已从磁盘中读取完整的文件），则将其封装在Ready变量中返回。否则，将返回Pending变量，以通知调用方该值尚不可用。

poll方法采用两个参数：self: Pin<&mut Self>和cx: &mut Context上下文。前者的行为类似于普通的&mut self引用，不同之处在于，Self值pinned在一个固定的内存位置上。如果不先了解async/await的工作原理，就很难理解Pin以及为什么需要Pin。因此，我们将在后文中进行详细解释。

cx: &mut Context参数用于将一个Waker实例传递给异步任务，例如加载文件系统。这个Waker允许异步任务发信号通知任务（或部分任务）已完成，例如该文件已从磁盘加载。由于主任务知道将在Future就绪时将会收到通知，因此就不需要一遍又一遍地调用poll了。我们会在后文中实现自己的waker类型，届时将更加详细地说明此过程。

使用Futures

现在，我们知道了如何定义future，了解了poll方法的基本思路。但是，我们仍然不知道如何有效地使用futures。由于futures代表异步任务的结果，可能尚不可用。但实际上，我们经常立即需要这些值以进行进一步的计算。所以问题是：在需要时如何有效地检索一个future的值？

等待Futures

一种可能的答案是一直等待到future就绪为止。该过程看起来像这样：

let future = async_read_file("foo.txt");
let file_content = loop {
    match future.poll(…) {
        Poll::Ready(value) => break value,
        Poll::Pending => {}, // 什么也不做
    }
}

在上面的代码中，我们通过循环中积极地调用poll来等待future完成。在这里poll的参数并不重要，因此已被省略。尽管此方法可行，但是效率很低，因为包含poll的循环会一直用占用CPU直到该值可用为止。

一种较为高效的方法是阻塞当前线程，直到future可用为止。当然，这只有在有线程支持的情况下才可行，因此并不适用于我们的内核，至少目前还不行。即使在支持阻塞的系统上，通常也不会这么做，因为阻塞会将异步任务再次变为同步任务，从而失去了并行任务的性能优势。

Future组合器

另一种等待方式是使用future组合器。Future组合器是类似于map的方法，它允许将futures链接并组合在一起，就像在Iterator上做的那样。这些组合器不等待future，而是自己返回future，即为poll应用了map操作。

下面举个简单的例子，一个用于将Future<Output = String>转换为Future<Output = usize>的string_len组合器可能看起来像这样：

struct StringLen<F> {
    inner_future: F,
}

impl<F> Future for StringLen<F> where F: Future<Output = String> {
    type Output = usize;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
        match self.inner_future.poll(cx) {
            Poll::Ready(s) => Poll::Ready(s.len()),
            Poll::Pending => Poll::Pending,
        }
    }
}

fn string_len(string: impl Future<Output = String>)
    -> impl Future<Output = usize>
{
    StringLen {
        inner_future: string,
    }
}

// Usage
fn file_len() -> impl Future<Output = usize> {
    let file_content_future = async_read_file("foo.txt");
    string_len(file_content_future)
}

该代码无法正常工作，因为尚未处理pinning，不过作为例子已经足够了。基本思路是string_len函数将给定的实现了Futuretrait的实例封装到新的StringLen结构体中，而该结构体也实现了Futuretrait。当poll封装的future时，即是poll其内部的future。如果该值尚未就绪，封装的future也将返回Poll::Pending。如果该值已就绪，则从Poll::Ready变量中获取字符串，并计算其长度。最后再将其封装在Poll::Ready中返回。

通过string_len函数，我们不需要等待一个异步字符串，就可以计算其长度。由于该函数也返回Future，因此调用者无法直接操作返回的值，而需要再次使用组合器函数。这样，整个调用过程就变为异步的了，我们可以高效地在某个时刻一次等待多个future，例如在main函数上。

手动编写组合器函数比较困难，所以它们通常由库直接提供。尽管Rust标准库本身还没有提供官方组合器方法，但半官方（兼容no_std）的futurecrate可以。其FutureExt特性提供了诸如map或then之类的高级组合器方法，可用于任意闭合操作结果。

优点

Future组合器最大的优点是能够使操作保持异步。这种方法和异步I/O接口结合使用时性能非常高。实际上future组合器将被实现为具有trait的普通结构体，以使编译器能够对其做出进一步优化。有关更多详细信息，请参阅Rust的零成本future一文，就是这篇文章宣布了在Rust生态系统中添加future。

缺点

尽管future组合器可以编写出非常高效的代码，但由于类型系统和基于闭包的接口的限制，组合器可能会在某些情况下变得难以使用。例如，考虑下面的代码：

fn example(min_len: usize) -> impl Future<Output = String> {
    async_read_file("foo.txt").then(move |content| {
        if content.len() < min_len {
            Either::Left(async_read_file("bar.txt").map(|s| content + &s))
        } else {
            Either::Right(future::ready(content))
        }
    })
}

（使用play rust在线运行上面的代码）

代码先读取文件foo.txt，然后使用then组合器根据文件内容链接第二个future。如果内容长度小于给定的min_len，我们将读取另一个bar.txt文件，然后使用map组合器将其附加到content中。否则，只返回foo.txt的content。

我们需要在传递给then的闭包上使用move关键字，否则min_len变量会产生生命周期错误。使用Either封装的原因是让if块和else块始终具有相同的类型。由于我们在块中返回了不同的future类型，因此必须使用封装类型将它们统一为一个类型。ready函数将立刻就绪的值封装到future中。这里需要使用该函数是因为Either封装要求值实现Futuretrait。

您可以想象，这种用法很快就会导致大型项目的代码变得非常复杂。尤其是再涉及借用和生命周期，就会变得更加复杂。因此，为了使异步代码从根本上更易于编写，我们投入了大量工作来为Rust添加对async/await的支持。

Async/Await模式

Async/Await的思路是让程序员以编写看起来像同步代码的方式编写异步代码，只不最后是由编译器将同步代码转换为异步代码。它基于两个关键字async和await。在函数签名中使用async关键字，就可以将同步函数转换为一个返回future的异步函数：

async fn foo() -> u32 {
    0
}

// 上面的函数大概会变编译器转换为：
fn foo() -> impl Future<Output = u32> {
    future::ready(0)
}

仅使用此关键字并没有那么有用。但是，在异步函数内部，可以使用await关键字来取回future的异步值：

async fn example(min_len: usize) -> String {
    let content = async_read_file("foo.txt").await;
    if content.len() < min_len {
        content + &async_read_file("bar.txt").await
    } else {
        content
    }
}

（使用play rust在线运行上面的代码）

将上面使用组合器实现的example函数直接转换为async/await模式：使用.await运算符就可以取回future的值，无需使用闭包或Either类型。如此，我们就可以像编写普通的同步代码一样编写异步代码。

状态机转换

在这种场景中，编译器的作用就是将async函数体转换为一个状态机，每个.await调用代表一个不同的状态。对于上面的example函数，编译器创建具有以下四个状态的状态机：

不同状态代表该函数的不同暂停点。"Start"和"End"状态代表函数在其执行的开始和结束时的状态。"Waiting on foo.txt"状态表示该函数目前正在等待第一个async_read_file的结果。同样的，"Waiting on bar.txt"状态表示函数在等待第二个async_read_file的结果的暂停点。

状态机通过将每个poll调用都变为一个可能的状态转换来实现Futuretrait：

图中使用箭头表示状态开关，并使用菱形表示条件路径。例如，如果foo.txt文件尚未准备好，则采用标记为"no"的路径，并达到"Waiting on foo.txt"的状态。否则，就采用标记为“yes”路径。没有字的红色小菱形代表example函数中if content.len() < 100的条件分支。

我们看到第一个poll调用启动了该函数并使它运行，直到遇到一个尚未就绪的future。如果路径上的所有future都已就绪，则该函数可以一直运行到"End"状态，并返回封装在Poll::Ready中的结果。否则，状态机将进入等待状态并返回Poll::Pending。然后在下一个poll调用中，状态机从上一个等待状态开始重试其最后一次操作。

状态保存

为了能够从上一个等待状态中恢复，状态机必须在内部跟踪当前状态。此外，它还必须保存在下一个poll调用中恢复执行所需的变量。这就是编译器真正发挥作用的地方：由于编译器知道在何时要使用哪些变量，因此它可以自动生成具有所需变量的结构体。

作为示例，编译器为上面的example函数生成类似于下面这样的结构体：

// 这是async版的`example`函数
async fn example(min_len: usize) -> String {
    let content = async_read_file("foo.txt").await;
    if content.len() < min_len {
        content + &async_read_file("bar.txt").await
    } else {
        content
    }
}

// 这是编译器生成的状态结构体

struct StartState {
    min_len: usize,
}

struct WaitingOnFooTxtState {
    min_len: usize,
    foo_txt_future: impl Future<Output = String>,
}

struct WaitingOnBarTxtState {
    content: String,
    bar_txt_future: impl Future<Output = String>,
}

struct EndState {}

在"Start"和"Waiting on foo.txt"状态下，需要存储min_len参数，因为稍后与content.len()做比较时需要使用该参数。"Waiting on foo.txt"状态还存储了一个foo_txt_future，用来表示async_read_file调用返回的future。状态机继续运行时会再次poll该future，因此需要将其保存。

"Waiting on bar.txt"状态包含content变量，是因为在bar.txt就绪后需要使用该变量进行字符串连接。该状态还存储了一个bar_txt_future，用来表示正在加载中的bar.txt。该结构体不包含min_len变量，因为在content.len()比较之后就不再需要该变量了。在"End"状态下，没有存储任何变量，因为此时函数已经运行完毕。

请记住，这只是编译器可能生成的代码的一个示例。结构体名称和字段布局是实现细节，可能会有所不同。

全状态机类型

尽管编译器生成的确切代码是实现细节，但这个示例还是有助于我们理解并想象example函数生成的状态机可能的样子。我们已经定义了代表不同状态的结构体，并给出了其中包含的所需变量。为了基于这些结构体创建一个状态机，我们可以将它们组合成一个枚举：

enum ExampleStateMachine {
    Start(StartState),
    WaitingOnFooTxt(WaitingOnFooTxtState),
    WaitingOnBarTxt(WaitingOnBarTxtState),
    End(EndState),
}

我们为每个状态定义一个单独的枚举变量，并将对应状态的结构体作为字段添加到每个变量。为了实现状态转换，编译器根据example函数实现Futuretrait：

impl Future for ExampleStateMachine {
    type Output = String; // `example`函数的返回类型

    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
        loop {
            match self { // TODO: 处理pinning
                ExampleStateMachine::Start(state) => {…}
                ExampleStateMachine::WaitingOnFooTxt(state) => {…}
                ExampleStateMachine::WaitingOnBarTxt(state) => {…}
                ExampleStateMachine::End(state) => {…}
            }
        }
    }
}

该Future的Output类型为String，即example函数的返回类型。为了实现poll函数，我们在loop内的当前状态上使用match语句。思路是我们尽可能长时间地切换到下一个状态，并在无法继续时显式的使用return Poll::Pending。

为简单起见，这里仅给出简化的代码，且暂不处理pinning、所有权、生命周期等内容。因此，这里的代码和下面的代码应被看做伪代码，不能直接使用。当然，真正的编译器生成的代码可以正确处理所有内容，尽管可能使用了与我们不同的方式。

为了使示意的代码更简洁，我们将分别显示每个匹配分支的代码。从"Start"状态开始：

ExampleStateMachine::Start(state) => {
    // from body of `example`
    let foo_txt_future = async_read_file("foo.txt");
    // `.await` operation
    let state = WaitingOnFooTxtState {
        min_len: state.min_len,
        foo_txt_future,
    };
    *self = ExampleStateMachine::WaitingOnFooTxt(state);
}

当状态机处于Start状态时，其对应位置正是函数体的最开始。在这种情况下，我们将执行example函数体中的所有代码，直到遇到第一个.await。为了处理.await操作，我们将self状态机的状态修改为WaitingOnFooTxt，并令状态中包含WaitingOnFooTxtState结构体。

由于match self {…}语句是在循环中执行的，因此该执行将跳至下一个分支WaitingOnFooTxt：

ExampleStateMachine::WaitingOnFooTxt(state) => {
    match state.foo_txt_future.poll(cx) {
        Poll::Pending => return Poll::Pending,
        Poll::Ready(content) => {
            // from body of `example`
            if content.len() < state.min_len {
                let bar_txt_future = async_read_file("bar.txt");
                // `.await` operation
                let state = WaitingOnBarTxtState {
                    content,
                    bar_txt_future,
                };
                *self = ExampleStateMachine::WaitingOnBarTxt(state);
            } else {
                *self = ExampleStateMachine::End(EndState));
                return Poll::Ready(content);
            }
        }
    }
}

在这一匹配分支中，我们首先调用foo_txt_future的poll函数。如果尚未就绪，则退出循环并返回Poll::Pending。由于在这种情况下self仍位于WaitingOnFooTxt状态，因此状态机的下一次poll调用也将进入相同的匹配分支并重试foo_txt_future。

当foo_txt_future就绪时，我们将结果赋给content变量，然后继续执行example函数的代码：如果content.len()小于状态结构体中保存的min_len，则异步读取bar.txt文件。我们再次将.await操作转换为状态更改，而这次应转换为WaitingOnBarTxt状态。由于我们是在循环内执行匹配，因此下一轮循环将直接跳转到新状态的匹配分支，然后在该状态下pollbar_txt_future。

如果我们进入else分支，则不会进行进一步的.await操作。此时已到达函数的结尾，并将content封装在Poll::Ready中返回。我们还需要将当前状态更改为End状态。

WaitingOnBarTxt状态的代码如下所示：

ExampleStateMachine::WaitingOnBarTxt(state) => {
    match state.bar_txt_future.poll(cx) {
        Poll::Pending => return Poll::Pending,
        Poll::Ready(bar_txt) => {
            *self = ExampleStateMachine::End(EndState));
            // from body of `example`
            return Poll::Ready(state.content + &bar_txt);
        }
    }
}

与WaitingOnFooTxt状态类似，我们从pollbar_txt_future开始。如果仍未就绪，则退出循环并返回Poll::Pending。否则，我们就执行example函数的最后一个操作：用content变量与future的结果做字符串连接。我们将状态机更新为End状态，然后将结果封装在Poll::Ready中返回。

最后，End状态的代码如下所示：

ExampleStateMachine::End(_) => {
    panic!("poll called after Poll::Ready was returned");
}

Future返回Poll::Ready后就不应再被poll了，因此，当我们已经处于End状态时，如果再次调用poll，就产生一个panic。

现在我们知道了编译器可能会生成怎样的状态机，以及怎样去给状态机实现Futuretrait。但实际上，编译器会以不同的方式生成代码。（如果您感兴趣的话，该实现目前基于生成器，不过这只是实现细节。）

最后一步是为example函数本身生成代码。记住，函数签名是这样定义的：

async fn example(min_len: usize) -> String

由于现在整个函数体是由状态机实现的，因此该函数唯一需要做的就是初始化状态机并将其返回。为此生成的代码如下所示：

fn example(min_len: usize) -> ExampleStateMachine {
    ExampleStateMachine::Start(StartState {
        min_len,
    })
}

该函数不再使用async修饰符，因为它现在显式返回一个实现了Futuretrait的ExampleStateMachine类型。如预期的那样，状态机被初始化为Start状态，并且使用min_len参数初始化了对应的状态结构体。

请注意，此函数并不会直接启动状态机。这是Rust中future的一个基本设计决策：在第一次被poll之前什么也不做。

Pinning

在这篇文章中，我们已经遇到pinning很多次了。现在终于是时候看看究竟什么是pinning以及为什么需要pinning了。

自引用结构体

如上所述，状态机转换将每个暂停点的局部变量存储在结构体中。对于像example函数这样的小例子就很简单，并不会导致任何问题。但是，当变量相互引用时，事情就会变得困难。例如，考虑以下函数：

async fn pin_example() -> i32 {
    let array = [1, 2, 3];
    let element = &array[2];
    async_write_file("foo.txt", element.to_string()).await;
    *element
}

该函数创建一个包含1、2、3的小数组。然后再创建对最后一个数组元素的引用，存储在element变量中。接下来，该函数将转换为字符串的数字异步写入到foo.txt文件中。最后返回由element引用的数字。

由于该函数使用了一个await操作，因此结果状态机具有三种状态："Start"、"End"、"Waiting on write"。该函数没有参数，因此开始状态对应的结构体为空。像以前一样，结束状态对应的结构体也为空，因为该函数此时已完成。而"Waiting on write"状态对应的结构体就很有趣：

struct WaitingOnWriteState {
    array: [1, 2, 3],
    element: 0x1001c, // 最后一个数组元素的地址
}

我们需要存储array和element变量，因为返回值需要element，而element又引用了array。由于element是一个引用，因此它存储指向所引用元素的指针（即内存地址）。我们在这里使用0x1001c作为示例存储地址。而实际上，element字段必须是array字段最后一个元素的地址，所以这与该结构体在内存中的位置有关。由于此类结构体对自身的某些字段做了引用，因此这种具有内部指针的结构体也叫做自引用结构体。

自引用结构体的问题

自引用结构的内部指针将导致一个很基本的问题，尤其是在查看其内存布局时会更加明显：

array字段从地址0x10014开始，element字段从地址0x10020开始。它指向地址0x1001c，即最后一个数组元素的地址。至此仍没什么问题。但是，当我们将此结构体移动到其他内存地址时，就会发生问题：

稍微移动该结构体，现在使其从地址0x10024开始。这是有可能的，例如当我们将该结构体作为函数参数传递时，或是将其分配给其他栈变量时。问题在于，尽管最后一个数组元素现已位于地址0x1002c，但element字段仍指向地址0x1001c。于是指针悬空，结果就是在下一个poll调用中发生未定义的行为。

可行的解决方案

有三种解决指针悬空问题的基本方法：

在移动时更新指针：思路是每当结构体在内存中移动时都更新其内部指针，以使该指针在移动后仍然有效。不幸的是，这种方法需要对Rust进行大量更改，并可能导致巨大的性能损失。因为如果实现这种方法，就需要某种运行时持续跟踪结构体中各种类型的字段，并在每次移动发生时检查是否需要更新指针。
存储偏移量而不是自引用：为了不去更新指针，编译器可以尝试将自引用存储为从结构体开始地址算起的偏移量。例如，上面的WaitingOnWriteState结构的element字段可以以element_offset字段的形式存储，其值为8，因为该引用指向的数组元素位于该结构体的起始地址后的第8个字节处。由于在移动结构时偏移量保持不变，因此不需要字段更新。问题是，如果实现这种方法，就必须让编译器检测所有自引用。这在编译时是不可能的，因为引用的值可能取决于用户输入，因此这又需要使用运行时系统来分析引用，从而正确地创建状态结构体。这不仅会导致运行时成本增加，而且还会阻止某些编译器优化，从而又会导致较大的性能损失。
禁止移动结构体：如上所示，仅当我们在内存中移动该结构体时，才会出现悬空指针。那么，通过完全禁止对自引用结构的移动操作，就可以避免该问题。这种方法的最大优点是可以实现在类型系统级别，并不会增加运行时成本。不过它的缺点是需要程序员自己处理在可能的自引用结构体上发生的移动操作。

为了遵守提供零成本抽象的原则（这意味着抽象不应产生额外的运行时成本），Rust选择了第三种解决方案。为此，在RFC 2349中提出了pinning API。在下文中，我们将简要概述此API，并说明它将如何与async/await和futures一起使用。

堆上的值

首先，很明显，堆分配的值在大多数情况下已经具有固定的内存地址。这些值是由allocate调用创建，并由如类似Box<T>的指针类型进行引用的。尽管这种指针类型可以移动，但指针所指向的堆值将始终位于相同的内存地址中，除非调用deallocate将其释放否则地址将一直不变。

使用堆分配，我们可以尝试创建一个自引用结构体：

fn main() {
    let mut heap_value = Box::new(SelfReferential {
        self_ptr: 0 as *const _,
    });
    let ptr = &*heap_value as *const SelfReferential;
    heap_value.self_ptr = ptr;
    println!("heap value at: {:p}", heap_value);
    println!("internal reference: {:p}", heap_value.self_ptr);
}

struct SelfReferential {
    self_ptr: *const Self,
}

（使用play rust在线运行上面的代码）

我们创建一个名为SelfReferential的简单结构体，其中包含一个指针字段。首先，我们使用空指针初始化结构体，然后使用Box::new将其分配到堆上。接下来，我们确定分配给堆的结构体的内存地址，并将其存储在ptr变量中。最后，通过将ptr变量分配给self_ptr字段，将结构体变为自引用结构体。

在play rust上执行此代码时，会看到堆值的地址及其内部指针地址相同，这意味着self_ptr字段是有效的自引用。由于heap_value变量仅是一个指针，因此移动它（例如，通过将其传递给函数）不会更改结构体本身的地址，因此，即使移动了指针，self_ptr也依然有效。

但是，还是有一种方法可以破坏这个例子：我们可以移出Box<T>或替换其内容：

let stack_value = mem::replace(&mut *heap_value, SelfReferential {
    self_ptr: 0 as *const _,
});
println!("value at: {:p}", &stack_value);
println!("internal reference: {:p}", stack_value.self_ptr);

（使用play rust在线运行上面的代码）

这里我们使用mem::replace函数，将堆分配内存中的原值替换为一个新结构体实例。这使我们可以将堆分配中的原值heap_value移动到栈中，而现在该结构体的self_ptr字段就是一个悬空指针了，它仍然指向旧的堆地址。当你尝试在play rust上运行该代码时，就会看到*“value at:”行和“internal reference:”*行确实打印了不同的指针地址。因此，堆分配的值并不能完全保证自引用的安全性。

导致上述现象的根本问题是Box<T>允许我们获取对堆分配值的&mut T引用。通过&mut引用，就可以使用诸如mem::replace或mem::swap一类的方法来使堆分配的自引用值无效。要解决此问题，我们必须禁止创建对自引用结构的&mut引用。

`Pin<Box<T>>`与`Unpin`

Pinning API用Pin封装类型和Unpin标记trait的方式为&mut T问题提供了解决方案。其思路是为Pin类型中所有可用于从Unpintrait上获取其封装值&mut可变引用方法（例如get_mut或deref_mut）设置关卡。Unpintrait是自动trait，即对于所有类型（显式声明退出的类型除外）都默认自动实现。而如果让自引用结构体显式声明退出Unpin，就再也没有（安全的）方法能够从Pin<Box<T>>类型中获取&mut T可变引用了。如此便能够保证它们的内部自引用始终有效。

让我们更新上面的SelfReferential类型以选择取消Unpin：

use core::marker::PhantomPinned;

struct SelfReferential {
    self_ptr: *const Self,
    _pin: PhantomPinned,
}

通过为结构体添加类型为PhantomPinned的第二个字段_pin来退出trait。这是一个零大小的标记类型，唯一目的就是退出Unpintrait。鉴于自动trait的工作方式，只需一个非Unpin的字段就可以使整个结构体退出Unpin。

第二步是将示例中的Box<SelfReferential>类型更改为Pin<Box<SelfReferential>>类型。最简单的方法是使用Box::pin函数代替Box::new来创建堆分配的值：

let mut heap_value = Box::pin(SelfReferential {
    self_ptr: 0 as *const _,
    _pin: PhantomPinned,
});

除了将Box::new改为Box::pin，还需要在结构体初始字段中添加新的_pin字段。由于PhantomPinned是零大小的类型，因此我们只需要使用其类型名称即可进行初始化。

现在，当我们尝试在play rust中运行修改后的示例代码，会发现代码有编译错误：

error[E0594]: cannot assign to data in a dereference of `std::pin::Pin<std::boxed::Box<SelfReferential>>`
  --> src/main.rs:10:5
   |
10 |     heap_value.self_ptr = ptr;
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^ cannot assign
   |
   = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `std::pin::Pin<std::boxed::Box<SelfReferential>>`

error[E0596]: cannot borrow data in a dereference of `std::pin::Pin<std::boxed::Box<SelfReferential>>` as mutable
  --> src/main.rs:16:36
   |
16 |     let stack_value = mem::replace(&mut *heap_value, SelfReferential {
   |                                    ^^^^^^^^^^^^^^^^ cannot borrow as mutable
   |
   = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `std::pin::Pin<std::boxed::Box<SelfReferential>>`

发生这两个错误都是由Pin<Box<SelfReferential>>类型不再实现DerefMuttrait引起的。这正是我们期望的，因为DerefMuttrait会返回一个&mut引用，而我们希望禁止该引用。这两个错误就是因为我们既退出了Unpin，又将Box::new更改为Box::pin。

现在的问题是，编译器不仅禁止在第16行中移动该类型，而且还禁止在第10行中初始化self_ptr字段。之所以发生这种情况，是因为编译器无法区分&mut引用的有效使用与无效使用。为了修复初始化一行的报错，我们必须使用非安全的get_unchecked_mut方法：

// 此处操作是安全的，因为仅修改了结构体字段，而未进行整个结构体的移动
unsafe {
    let mut_ref = Pin::as_mut(&mut heap_value);
    Pin::get_unchecked_mut(mut_ref).self_ptr = ptr;
}

（使用play rust在线运行上面的代码）

get_unchecked_mut函数的参数应为Pin<&mut T>而不是Pin<Box<T>>，因此我们必须先使用Pin::as_mut做转换。然后，我们就可以使用get_unchecked_mut返回的&mut引用来设置self_ptr字段了。

现在剩下的错误就是我们期望的mem::replace一行的错误。请记住，此操作尝试将堆分配的值移动到栈上，这会破坏存储在self_ptr字段中的自引用。通过退出Unpin并使用Pin<Box<T>>，就可以在编译时禁止执行此类操作，从而可以安全地使用自引用结构体。如我们所见，编译器（目前）还不能检测创建的自引用结构体是否安全，因此我们需要使用非安全块并自己确保其正确性。

栈上的pinning与`Pin<&mut T>`

在上一节中，我们学习了如何使用Pin<Box<T>>安全地创建堆分配上的自引用结构体。尽管这种方法可以很好地工作并且相对安全（除了非安全的初始化），但方法所要求的堆分配会带来一些性能损失。由于Rust始终希望尽可能的提供零成本抽象，因此pinning API还允许创建指向栈分配值的Pin<&mut T>实例。

与拥有封装值所有权的Pin<Box<T>>实例不同，Pin<&mut T>实例仅临时借用其封装的值。这使事情变得更加复杂，因为它需要程序员自己确保引用带来的附加的条件。最重要的是，在被引用T的整个生命周期中，Pin<&mut T>必须保持在pin的状态，这对于基于栈的变量来说会更加难以检查。为了处理这种问题，的确存在像pin-utils这样的crate，但是除非你真的知道自己在做什么，一般都不建议使用栈上的pinning。

要进一步阅读，请查看pin模块和Pin::new_unchecked方法的文档。

Pinning和Future

正如我们在本文中已经看到的那样，Future::poll方法使用的pinning参数为Pin<&mut Self>形式：

fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output>

该方法采用self: Pin<&mut Self>而不是常规&mut self作参数的原因如前文所述，从async/await创建的future实例通常是自引用的。通过将Self封装为Pin，并使编译器令async/await生成的自引用future退出Unpin，可以确保future在两次poll调用之间不会在内存中移动。如此便可以确保所有内部引用仍然有效。

值得注意的是，在第一个poll调用之前，移动future是可行的。这是因为future是惰性的，它在第一次poll之前什么也不做。所以生成状态机的"Start"状态仅包含函数参数，而没有内部引用。为了调用poll，调用者必须先将future封装到Pin中，以确保future不会在内存中移动。由于正确的使用栈pinning会更加困难，因此建议始终结合使用Box::pin与Pin::as_mut。

如果你有兴趣了解如何使用栈pinning来安全地实现future组合器函数，可以选择查看futurecrate中map组合器方法源码（该方法的源码相对简单），以及阅读有关pin文档中投影和结构的pinning部分。

执行器和唤醒器

使用async/await，可以最大限度的以完全异步的方式使用future。但是，正如我们从上面了解到的那样，future在被poll之前什么都不做。这意味着我们必须在某些时候发起对它们的poll，否则异步代码将永远不会执行。

对于单个future，我们总是可以使用上述循环手动等待每个future。但是，这种方式效率很低，而且对于那些创建大量future的程序实际上并不可行。针对此问题的最常见解决方案是定义一个全局执行器，以负责轮询系统中的所有future，直到它们全部完成。

执行器

执行器的作用是将future生成为任务，通常是使用一些spawn方法。然后，执行器负责轮询所有future，直到它们全部完成。集中管理所有future的最大好处是，只要future返回Poll::Pending，执行器就可以切换到另一个future。所以异步操作可以并行运行，CPU也因此持续作业。

许多执行器的实现也能够利用多核CPU系统的优点。这些实现会创建一个线程池，如果提供足够多的任务，线程池就能利用所有内核，并使用像work stealing之类的技术来平衡核心间的负载。嵌入式系统还会有一些特殊的执行器实现，专门为降低延迟和减少内存开销做了优化。

为了避免重复轮询future的开销，执行器通常还利用Rust的future支持的唤醒器API。

唤醒器

唤醒器API的思路是，将特殊的Waker类型封装在Context类型中，传递给每一次poll调用。这个Waker类型是由执行器创建的，异步任务可以用该类型表示任务已（部分）完成。于是，除非相应的唤醒器通知执行器，否则执行器都不需要在先前返回Poll::Pending的future上再进行poll调用了。

举个小例子可以很好地说明这一点：

async fn write_file() {
    async_write_file("foo.txt", "Hello").await;
}

此函数将字符串"Hello"异步写入foo.txt文件。由于硬盘写入需要一些时间，因此该future上的第一次poll调用可能会返回Poll::Pending。硬盘驱动将在内部存储传递给poll调用的Waker，并在完成文件写入时使用它通知执行器。如此，执行器在收到唤醒器的通知前，都不需要再在这个future上尝试poll了。

我们将在本文的实现一节创建具有唤醒器支持的执行器，届时将详细的看到Waker类型的工作原理。

协作式多任务？

在本文的开头，我们讨论了抢先式多任务和协作式多任务。抢占式多任务依靠操作系统在运行中的任务间做强制切换，而协作式多任务则要求任务定期通过yield操作主动放弃对CPU的控制。协作式的最大优点是任务可以自己保存状态，从而更高效地进行上下文切换，并可以在任务间共享相同的调用栈。

这可能不够直观，不过future和async/await就是协作式多任务模式的实现：

添加到执行器的每个future本质上都是一个协作任务。
Future不使用显式的yield操作，而是通过返回Poll::Pending（或完成时的Poll::Ready）来放弃对CPU核心的控制。
- 没有什么可以强制future放弃CPU。如果它们愿意，就能够永不从poll中返回，如在一个无限循环中打转。
- 由于每个future都可以阻止执行器中其他future的执行，因此我们需要信任它们不是恶意的。
Future在内部存储它在下一次poll调用时恢复执行所需的所有状态。使用async/await，编译器会自动检测所需的所有变量，并将其存储在生成的状态机中。
- 仅保存恢复执行所需的最少状态。
- 由于poll方法在返回时会放弃调用栈，因此该栈可用于poll其他的future。

我们看到future和async/await完美契合协作式多任务，区别就是使用了一些不同的术语。因此，在下文中，我们将交替使用术语“任务”和“future”。

实现

现在，我们了解了Rust中基于future和async/await的协作式多任务的工作原理，是时候向我们的内核中添加对多任务的支持了。由于Futuretrait是core库的一部分，而async/await是Rust语言本身的功能，因此在#![no_std]内核中使用无需其他操作就可以使用它们。唯一的要求是我们至少应使用Rust在2020-03-25之后的nightly版本，因为之前的async/await是不兼容no_std的。

只要使用较近的nightly版本，我们就可以在main.rs中使用async/await：

async fn async_number() -> u32 {
    42
}

async fn example_task() {
    let number = async_number().await;
    println!("async number: {}", number);
}

async_number函数是一个async fn，因此编译器将其转换为实现了Futuretrait的状态机。由于该函数仅返回42，因此生成的future将在首次poll调用时直接返回Poll::Ready(42)。像async_number一样，example_task函数也是一个async fn。它等待async_number返回的数字，然后使用println宏将其打印出来。

要运行example_task返回的future，我们需要一直对其调用poll，到它通过返回Poll::Ready告知其已完成为止。为此，我们需要创建一个简单的执行器类型。

任务

在实现执行器之前，我们要创建一个具有Task类型的新模块task：

pub mod task;

use core::{future::Future, pin::Pin};
use alloc::boxed::Box;

pub struct Task {
    future: Pin<Box<dyn Future<Output = ()>>>,
}

Task结构体是一个新的类型封装器，它封装了一个内存固定的、堆分配的、以空类型()作为输出的动态分发的future。让我们详细研究一下：

我们要求与任务关联的future返回()。这意味着任务不会返回任何结果，只是为了执行其中的副作用。例如，我们上面定义的example_task函数也没有返回值，但是作为副作用，函数将一些信息打印在了屏幕上。
dyn关键字告诉我们存放在Box中的是一个trait对象。这意味着future上的方法是动态分发的，因此我们才可以在Task类型中存储不同类型的future。这很重要，因为每个async fn都有自己的future类型，而我们希望能够创建多个不同的任务。
正如我们在pinning一节了解到的那样，Pin<Box>类型通过将值放在堆上并防止对值创建&mut引用来确保该值不会在内存中移动。这很重要，因为async/await生成的future可能是自引用的，即包含指向自身的指针，而该指针将在future移动时失效。

为了能够适应future创建Task结构体，我们编写一个new函数：

impl Task {
    pub fn new(future: impl Future<Output = ()> + 'static) -> Task {
        Task {
            future: Box::pin(future),
        }
    }
}

该函数接受输出类型为()的任意future，然后通过Box::pin函数将其固定在内存中。然后，函数将future封装在Task结构体中并返回。这里需要使用'static生命周期，因为返回的Task生存时间不确定，因此future也必须在该时间内保持有效。

我们还添加了一个poll方法，使执行器可以轮询存储的future：

use core::task::{Context, Poll};

impl Task {
    fn poll(&mut self, context: &mut Context) -> Poll<()> {
        self.future.as_mut().poll(context)
    }
}

由于Futuretrait的poll方法需要在Pin<&mut T>类型上调用，因此我们先要使用Pin::as_mut方法转换类型为Pin<Box<T>>的self.future字段。然后，在转换后的self.future字段上调用poll并返回结果。由于Task::poll方法仅应由我们稍后创建的执行器调用，因此保持其为task模块的私有函数。

简单执行器

由于执行器可能非常复杂，因此我们有意在开始仅创建一个非常基本的执行器，然后再渐进的实现更多功能。为此，我们先创建一个新的task::simple_executor子模块：

pub mod simple_executor;

use super::Task;
use alloc::collections::VecDeque;

pub struct SimpleExecutor {
    task_queue: VecDeque<Task>,
}

impl SimpleExecutor {
    pub fn new() -> SimpleExecutor {
        SimpleExecutor {
            task_queue: VecDeque::new(),
        }
    }

    pub fn spawn(&mut self, task: Task) {
        self.task_queue.push_back(task)
    }
}

该结构体包含一个VecDeque类型的字段task_queue，这是一个在两端都能执行push和pop操作的向量。使用这种类型的思路是，通过spawn在队尾方法插入新任务，并从队首弹出要执行的下一个任务。这样，我们就得到了一个简单的FIFO队列（“先进先出”）。

假唤醒器

为了调用poll方法，我们需要创建一个Context类型，用来封装Waker类型。简单起见，我们将首先创建一个不执行任何操作的假唤醒器。为此，我们创建了RawWaker实例，用以定义不同Waker方法的实现，然后使用Waker::from_raw函数将其转换为Waker：

use core::task::{Waker, RawWaker};

fn dummy_raw_waker() -> RawWaker {
    todo!();
}

fn dummy_waker() -> Waker {
    unsafe { Waker::from_raw(dummy_raw_waker()) }
}

from_raw函数是非安全的，因为如果程序员不按照RawWaker文档的要求使用，就可能导致未定义的行为。在查看dummy_raw_waker函数的实现之前，我们首先尝试了解RawWaker类型的工作方式。

`RawWaker`

RawWaker类型要求程序员显式定义一个虚拟方法表(vtable)，用以指定在克隆，唤醒、删除RawWaker时应调用的函数。vtable的布局由RawWakerVTable类型定义。每个函数都接收一个*const ()参数，该参数本质上是一个指向某结构体的擦除类型的&self指针，例如在堆上的分配。使用*const ()指针而不是某适当引用的原因是RawWaker类型应该是非泛型的，但仍需支持任意类型。作为参数传递给函数的指针值为给RawWaker::new的data指针。

通常，RawWaker结构体是为封装在Box或Arc类型中的某些堆分配而创建的。对于这些类型，可以使用Box::into_raw之类的方法将Box<T>转换为*const T指针。然后可以将该指针转换为匿名*const ()指针，再传递给RawWaker::new。由于每个vtable函数都使用相同的*const ()作为参数，因此这些函数可以安全地将指针转换回Box<T>或&T以执行操作。可以想象，此过程非常危险，很容易出错导致未定义行为。因此，若非必要，则并不建议手动创建RawWaker。

一个假的`RawWaker`

虽然不建议手动创建RawWaker，但目前还没有其他方法可以创建不执行任何操作的假Waker。幸运的是，不执行任何操作也会使得实现dummy_raw_waker函数变得相对安全：

use core::task::RawWakerVTable;

fn dummy_raw_waker() -> RawWaker {
    fn no_op(_: *const ()) {}
    fn clone(_: *const ()) -> RawWaker {
        dummy_raw_waker()
    }

    let vtable = &RawWakerVTable::new(clone, no_op, no_op, no_op);
    RawWaker::new(0 as *const (), vtable)
}

首先，我们定义两个名为no_op和clone的内部函数。no_op函数接受* const()指针，不执行任何操作。clone函数也接受* const()指针，并通过再次调用dummy_raw_waker返回一个新的RawWaker。我们使用这两个函数来创建最小化的RawWakerVTable：clone函数用于克隆操作，no_op函数用于其他所有操作。由于RawWaker不执行任何操作，因此从clone返回的是一个新RawWaker还是一个真正的克隆其实并不重要。

创建vtable之后，我们使用RawWaker::new函数创建RawWaker。传递的* const()无关紧要，因为并没有任何vtable的函数会使用它。于是我们只传递了一个空指针。

一个`run`方法

现在，我们有了创建Waker实例的方法，就可以使用它在执行器上实现run方法。最简单的run方法是在循环中不停的poll所有队列中的任务，直到所有任务均已完成。这并不高效，因为它没有利用Waker类型的通知功能，但是它是使示例能够运行起来的的最简单方法：

use core::task::{Context, Poll};

impl SimpleExecutor {
    pub fn run(&mut self) {
        while let Some(mut task) = self.task_queue.pop_front() {
            let waker = dummy_waker();
            let mut context = Context::from_waker(&waker);
            match task.poll(&mut context) {
                Poll::Ready(()) => {} // 任务已完成
                Poll::Pending => self.task_queue.push_back(task),
            }
        }
    }
}

该函数使用while let循环来处理task_queue中的所有任务。对于每个任务，我们首先把由dummy_waker函数返回的Waker实例封装为Context类型。然后调用Task::poll方法并使用该context做参数。如果poll方法返回Poll :: Ready，则说明任务已完成，就可以继续执行下一个任务。如果任务仍然处于Poll::Pending，则将其再次添加到队尾，以便在后续的循环中再次轮询它。

尝试运行

使用我们的SimpleExecutor类型，现在就可以尝试在main.rs中运行example_task函数返回的任务了：

use blog_os::task::{Task, simple_executor::SimpleExecutor};

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // […] initialization routines, including `init_heap`

    let mut executor = SimpleExecutor::new();
    executor.spawn(Task::new(example_task()));
    executor.run();

    // […] test_main, "it did not crash" message, hlt_loop
}


// Below is the example_task function again so that you don't have to scroll up

async fn async_number() -> u32 {
    42
}

async fn example_task() {
    let number = async_number().await;
    println!("async number: {}", number);
}

运行代码，将看到预期的消息"async number: 42"打印到屏幕上：

我们来总结一下示例中执行的各个步骤：

首先，我们创建一个带有空task_queue的SimpleExecutor类型实例。
接下来，我们调用异步example_task函数，该函数返回的是future。将这个future封装在Task类型中，以将其移动到堆中并固定在内存中，然后通过spawn方法将该任务添加到执行器的task_queue中。
然后，我们调用run方法以开始执行队列中的单个任务。这涉及：
- 从task_queue队首弹出任务。
- 为任务创建RawWaker，将其转换为Waker实例，然后用它创建Context实例。
- 在任务的future上调用poll方法，并传入我们刚才创建的Context实例。
- 由于example_task不会等待任何操作，因此可以直接运行到第一次poll调用为止。这就是打印"async number: 42"位置。
- 由于example_task将立刻返回Poll::Ready，因此并不会将其再添加回任务队列。

在task_queue为空后，run方法返回。之后，我们的kernel_main函数将继续执行，并打印"It did not crash!"信息。

异步键盘输入

这个简单执行器并不能利用Waker通知，只会循环遍历所有任务直到它们完成。对于我们的示例，这并不是问题，因为我们的example_task在首次执行poll时就可以直接完成。要能观察到一个正确的Waker实现所带来的性能优势，我们首先需要创建一个真正异步的任务，即可能会在首次poll调用中返回Poll::Pending的任务。

其实我们的系统中已经存在了一些异步特性：硬件中断。正如我们在硬件中断一文中了解到的那样，硬件中断可以在任意时刻发生，这是由某些外部设备所决定的。例如，在经过一段预定义的时间后，硬件计时器会将中断发送到CPU。当CPU接收到中断时，它会立即将控制权转移给在中断描述符表(IDT)中定义的相应处理函数。

下面，我们将基于键盘中断创建一个异步任务。键盘中断是一个很好的选择，因为它既具有不确定性又对延迟有很高的要求。不确定性意味着无法预测下一次按键的发生时间，因为这完全取决于用户。低延迟是指我们要及时处理键盘输入，否则用户会感到滞后。为了以一种更高效的方式支持此类任务，执行器就需要对Waker通知提供适当的支持。

键盘扫描码队列

我们当前仍是直接在中断处理程序中处理键盘输入。长远考虑这并不是一个好主意，因为中断处理程序应保持尽可能短，以免长时间中断重要工作。因此，中断处理程序应仅执行必要的最少量的工作（如键盘扫描码的读取），而将其余工作（如键盘扫描码的解释）留给后台任务。

将工作委派给后台任务的常见模式是创建某种队列。中断处理程序将工作单元推送到队列，而后台任务处理程序从队列中取出工作以进行处理。对于我们的键盘中断，就是中断处理程序仅从键盘读取扫描代码，并将其推送到队列，然后直接返回。键盘任务从队列的另一端取出扫描码，并对每个扫描码进行解释和处理：

可以用一个由互斥锁保护的VecDeque来简单的实现该队列。但是，在中断处理程序中使用互斥锁并不是一个好主意，因为很容易导致死锁。例如，当用户在键盘任务锁定队列时又按下了某个键，中断处理程序将再次尝试获取该锁，这会导致死锁。这种方法的另一个问题是，当VecDeque已满时，就会通过执行新的堆分配来自动增加队列容量。这可能又会导致死锁，因为我们的分配器还在内部使用了互斥锁。还有更深层次的问题，当堆碎片化时，堆分配可能会花费大量时间甚至会分配失败。

为避免这些问题，我们需要一个push操作不涉及互斥量或堆分配的队列实现。这种队列可以通过使用无锁原子操作来实现元素的push和pop。如此，就可以创建只需要&self引用即可使用的push和pop操作，因此也无需互斥锁。为了避免在push时执行堆分配，可以通过预先分配的固定大小的缓冲区来支持队列空间扩展。尽管这会让队列有界（即有最大长度限制），但在实际操作中通常能够为队列长度定义一个合理的上限，这并不是一个大问题。

`crossbeam`crate

以正确且高效的方式实现这样的队列是一件非常困难的事，因此建议使用经过良好测试的现有实现。crossbeam是一个流行的Rust项目，它实现了多种用于并发编程的无互斥类型。该crate提供的ArrayQueue正是我们需要的类型。更加幸运的是，该类型恰好与具有堆分配支持的no_stdcrate完全兼容。

要使用该类型，我们需要添加crossbeam-queuecrate依赖：

[dependencies.crossbeam-queue]
version = "0.2.1"
default-features = false
features = ["alloc"]

该crate默认依赖标准库。为了使其与no_std兼容，我们需要禁用其默认特性并启用alloc特性。（请注意，在这里选择主crossbeamcrate作为依赖将不能工作，因为它缺少用于no_std的queue模块导出。我们提交了一个pull请求来解决此问题，但该修改尚未在crates.io上发布。）

队列实现

有了ArrayQueue类型，我们就可以在新的task::keyboard模块中创建全局的扫描码队列了：

pub mod keyboard;

use conquer_once::spin::OnceCell;
use crossbeam_queue::ArrayQueue;

static SCANCODE_QUEUE: OnceCell<ArrayQueue<u8>> = OnceCell::uninit();

由于ArrayQueue::new需要执行堆分配，而这在编译时是不可行的（到目前为止），所以我们不能直接初始化该静态变量。为此，我们使用了conquer_oncecrate的OnceCell类型，以能够安全的执行一次性静态变量的初始化。为了使用该crate，我们需要将其作为依赖项添加到Cargo.toml中：

[dependencies.conquer-once]
version = "0.2.0"
default-features = false

我们确实也可以在这里使用lazy_static宏来代替OnceCell。不过OnceCell类型的优点是能够确保初始化不会在中断处理程序中发生，从而阻止中断处理程序执行堆分配。

填充队列

为了填充扫描代队列，我们创建了一个新的add_scancode函数，以从中断处理程序中调用：

use crate::println;

/// 由键盘中断调用程序调用
///
/// 该函数不应阻塞或执行堆分配
pub(crate) fn add_scancode(scancode: u8) {
    if let Ok(queue) = SCANCODE_QUEUE.try_get() {
        if let Err(_) = queue.push(scancode) {
            println!("WARNING: scancode queue full; dropping keyboard input");
        }
    } else {
        println!("WARNING: scancode queue uninitialized");
    }
}

使用OnceCell::try_get函数来获取对初始化队列的引用。如果队列尚未初始化，就忽略键盘扫描码并直接打印警告。要注意的是，不能在此函数中初始化队列，因为它将被中断处理程序调用，而我们不应该在中断处理的过程中执行堆分配。由于不应从main.rs中调用此函数，因此我们使用pub(crate)使该函数仅可在lib.rs中使用。

ArrayQueue::push方法只需&self引用即可执行，这使得我们能够非常简单的从静态队列上调用该方法。ArrayQueue类型本身执行所有必要的同步，因此这里不需要使用互斥类封装。如果队列已满，我们也会打印警告。

要在键盘中断上调用add_scancode函数，就需要在interrupts模块中更新keyboard_interrupt_handler函数：

extern "x86-interrupt" fn keyboard_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame
) {
    use x86_64::instructions::port::Port;

    let mut port = Port::new(0x60);
    let scancode: u8 = unsafe { port.read() };
    crate::task::keyboard::add_scancode(scancode); // new

    unsafe {
        PICS.lock()
            .notify_end_of_interrupt(InterruptIndex::Keyboard.as_u8());
    }
}

我们从该函数中删除了所有键盘事件处理的代码，并添加了对add_scancode函数的调用，其余代码保持不变。

正如预期，现在使用cargo run运行内核时，每次按键不再显示在屏幕上，取而代之的是，每次按键时都会看到队列未初始化的警告。

扫描码流

为了初始化SCANCODE_QUEUE并以异步方式从队列中读取扫描码，我们创建了一个新的ScancodeStream类型：

pub struct ScancodeStream {
    _private: (),
}

impl ScancodeStream {
    pub fn new() -> Self {
        SCANCODE_QUEUE.try_init_once(|| ArrayQueue::new(100))
            .expect("ScancodeStream::new should only be called once");
        ScancodeStream { _private: () }
    }
}

_private字段用于阻止从本模块外构造结构体的行为。这使得new函数成为构造该类的唯一方法。在函数中，我们首先尝试初始化SCANCODE_QUEUE静态变量。如果它已初始化，我们就产生一个panic，如此确保只会存在一个ScancodeStream实例。

为了使扫描码可用于异步任务，下一步是实现一个类似poll的方法，以尝试从队列中弹出下一个扫描码。虽然这听上去似乎是我们应该为该类型实现Futuretrait，但在这里实际上并不是。问题在于，Futuretrait仅对单个异步值进行抽象，并且期望在它返回Poll::Ready之后不会再次调用poll方法。但是，我们的扫描码队列包含多个异步值，因此可以持续对其进行轮询。

`Stream`trait

由于产生多个异步值的类型很常见，因此futurecrate为此类提供了有用的抽象：Streamtrait。其定义如下：

pub trait Stream {
    type Item;

    fn poll_next(self: Pin<&mut Self>, cx: &mut Context)
        -> Poll<Option<Self::Item>>;
}

此定义与Futuretrait非常相似，但有以下区别：

关联的类型叫做Item而不是Output。
与返回Poll<Self::Item>的poll方法不同，Streamtrait定义了一个返回Poll<Option<Self::Item>>的poll_next方法（请注意附加的Option）。

此外还有一个语义上的区别：poll_next可以被重复调用，直到返回Poll::Ready(None)来表示流已完成。从这方面来看，该方法类似于Iterator::next方法，即也会在返回最后一个值之后就只返回None。

实现`Stream`

让我们为ScancodeStream实现Streamtrait，以便使用异步方式提供SCANCODE_QUEUE中的值。为此，我们首先需要添加对futures-utilcrate的依赖，其中就包含Stream类型：

[dependencies.futures-util]
version = "0.3.4"
default-features = false
features = ["alloc"]

我们禁用默认特性以使crate兼容no_std，并启用alloc特性以使其基于堆分配的类型可用（稍后将需要它）。（请注意，我们确实可以添加对主futurescrate的依赖，从而重新导出futures-utilcrate，但这将产生更多的依赖和更长的编译时间。）

现在我们可以导入并实现Streamtrait：

use core::{pin::Pin, task::{Poll, Context}};
use futures_util::stream::Stream;

impl Stream for ScancodeStream {
    type Item = u8;

    fn poll_next(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Option<u8>> {
        let queue = SCANCODE_QUEUE.try_get().expect("not initialized");
        match queue.pop() {
            Ok(scancode) => Poll::Ready(Some(scancode)),
            Err(crossbeam_queue::PopError) => Poll::Pending,
        }
    }
}

我们首先使用OnceCell::try_get方法来获取初始化的扫描码队列的引用。此操作应该不会失败，因为我们已在new函数中执行了队列初始化，所以可以放心的使用expect，以在未初始化队列时直接panic。接下来，我们使用ArrayQueue::pop方法尝试从队列中获取下一个元素。如果成功，我们将返回封装在Poll::Ready(Some(…))中的扫描代码。如果失败，则意味着队列已空。在这种情况下，我们返回Poll::Pending。

唤醒器支持

与Futures::poll方法类似，Stream::poll_next方法要求异步任务在返回Poll::Pending之后才就绪时通知执行器。如此，执行器就不需要再次轮询相同的任务，任务完成会自动通知执行器，这大大降低了等待任务时的性能开销。

要发送此类通知，任务应从参数Context引用中获取Waker并将其储存在某处。当任务就绪时，它应该在储存的Waker上调用wake方法，以通知执行者应该再次轮询该任务了。

原子化的唤醒器

要为我们的ScancodeStream实现Waker通知功能，就需要一个可以在两次轮询调用之间储存Waker的地方。不能将其存储为ScancodeStream的字段中，因为我们需要从add_scancode函数进行访问。解决方案是使用由Futures-utilcrate提供的AtomicWaker类型创建静态变量。与ArrayQueue类型类似，此类型基于原子化的指令，可以被安全地存放在静态变量中，并支持并发修改。

定义一个AtomicWaker类型的静态变量WAKER：

use futures_util::task::AtomicWaker;

static WAKER: AtomicWaker = AtomicWaker::new();

思路是poll_next的实现将当前的唤醒器存储在此静态变量中，当将新的扫描码添加到队列时，add_scancode函数将在其上调用wake函数。

储存唤醒器

poll/poll_next的协议要求任务在返回Poll::Pending时为传递的Waker注册唤醒。让我们修改poll_next的实现以满足此要求：

impl Stream for ScancodeStream {
    type Item = u8;

    fn poll_next(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Option<u8>> {
        let queue = SCANCODE_QUEUE
            .try_get()
            .expect("scancode queue not initialized");

        // fast path
        if let Ok(scancode) = queue.pop() {
            return Poll::Ready(Some(scancode));
        }

        WAKER.register(&cx.waker());
        match queue.pop() {
            Ok(scancode) => {
                WAKER.take();
                Poll::Ready(Some(scancode))
            }
            Err(crossbeam_queue::PopError) => Poll::Pending,
        }
    }
}

像以前一样，我们首先使用OnceCell::try_get函数来获取对初始化的扫描码队列的引用。然后，我们乐观地尝试从队列中pop任务并在成功时返回Poll::Ready。如此，就可以避免在队列非空时注册唤醒其的性能开销。

如果对queue.pop()的第一次调用并未成功，则该队列有可能为空。仅仅有可能为空，是因为中断处理程序也许是在轮询检查后立即异步填充了队列。由于此竞争条件可能在下一次轮询检查时再次发生，因此我们需要在第二次检查之前在WAKER静态变量中注册Waker。这样，尽管在Poll::Pending返回之前也可能发起唤醒，但是可以保证我们能够收到所有在轮询检查后推送的扫描码。

使用AtomicWaker::register函数注册Context参数中包含的Waker之后，我们再次尝试从队列中弹出任务。如果这次能成功，则返回Poll::Ready。此时还需要使用AtomicWaker::take删除这个注册的唤醒器，因为任务已完成就不再需要唤醒器通知了。如果queue.pop()又失败了，我们仍将像以前一样返回Poll::Pending，区别是这次注册了唤醒器。

请注意，对于没有（或尚未）返回Poll::Pending的任务，可以通过两种方式进行唤醒。一种方法是在唤醒立刻发生于返回Poll::Pending之前，那么就使用上面提到的竞争条件。另一种方法是由于注册了唤醒器使得队列不再为空时，返回Poll::Ready。由于这些假唤醒是无法避免的，因此执行器必须能够正确处理它们。

唤醒储存的唤醒器

为了唤醒存储的Waker，我们在add_scancode函数中添加对WAKER.wake()的调用：

pub(crate) fn add_scancode(scancode: u8) {
    if let Ok(queue) = SCANCODE_QUEUE.try_get() {
        if let Err(_) = queue.push(scancode) {
            println!("WARNING: scancode queue full; dropping keyboard input");
        } else {
            WAKER.wake(); // new
        }
    } else {
        println!("WARNING: scancode queue uninitialized");
    }
}

此处的唯一修改就是，如果成功推送到扫描码队列，就调用WAKER.wake()。如果静态变量WAKER中已经注册了一个唤醒器，则此方法将在其上调用同名的wake方法，以通知执行器。否则，该操作将为空操作，即没有任何效果。

重要的是，我们必须在推送到队列后才能调用wake，否则在队列仍然为空时可能会过早唤醒任务。一个可能的例子，就是一个多线程执行器在CPU的其他核心中并发的唤醒任务时。虽然现在内核还不支持线程，但也会尽快添加，我们当然不希望那时再出问题。

键盘任务

我们为ScancodeStream实现了Streamtrait，现在就可以创建异步键盘任务了：

use futures_util::stream::StreamExt;
use pc_keyboard::{layouts, DecodedKey, HandleControl, Keyboard, ScancodeSet1};
use crate::print;

pub async fn print_keypresses() {
    let mut scancodes = ScancodeStream::new();
    let mut keyboard = Keyboard::new(layouts::Us104Key, ScancodeSet1,
        HandleControl::Ignore);

    while let Some(scancode) = scancodes.next().await {
        if let Ok(Some(key_event)) = keyboard.add_byte(scancode) {
            if let Some(key) = keyboard.process_keyevent(key_event) {
                match key {
                    DecodedKey::Unicode(character) => print!("{}", character),
                    DecodedKey::RawKey(key) => print!("{:?}", key),
                }
            }
        }
    }
}

上面的代码与本文修改之前在键盘中断处理程序中使用的代码非常相似。唯一的区别是，我们不是从I/O端口读取扫描码，而是从ScancodeStream中获取。为此，我们首先创建一个新的Scancode流，然后重复使用StreamExttrait所提供的next方法来获取Future，即为该流中的下一个元素。通过在其上使用await运算符，我们可以异步等待future的结果。

使用while let循环，直到流返回None表示结束为止。由于我们的poll_next方法从不返回None，因此这实际上是一个无休止的循环，即print_keypresses任务永远不会完成。

让我们在main.rs中的执行器中添加print_keypresses任务，以再次获得有效的键盘输入：

use blog_os::task::keyboard; // new

fn kernel_main(boot_info: &'static BootInfo) -> ! {

    // […] initialization routines, including init_heap, test_main

    let mut executor = SimpleExecutor::new();
    executor.spawn(Task::new(example_task()));
    executor.spawn(Task::new(keyboard::print_keypresses())); // new
    executor.run();

    // […] "it did not crash" message, hlt_loop
}

现在执行cargo run，将看到键盘输入再次起作用：

如果你密切注意计算机的CPU使用率，就会发现QEMU进程会令CPU持续繁忙。发生这种情况是因为我们的SimpleExecutor在一个循环中不停地轮询任务。因此，即使我们没有按键盘上的任何键，执行器也会在print_keypresses任务上不停的调用poll，即使该任务并未取得任何进展而每次都会返回Poll::Pending。

带有唤醒器支持的执行器

要解决性能问题，我们需要创建一个能够正确利用Waker通知的执行器。这样，当下一个键盘中断发生时，将通知执行器，因此就不需要再不停的轮询print_keypresses任务了。

任务ID

要创建能够正确支持唤醒器通知的执行器，第一步就是为每个任务分配唯一的ID。这是必需的，因为我们需要一种方法来指定希望唤醒的任务。首先，创建一个新的TaskId封装类型：

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
struct TaskId(u64);

TaskId结构体其实是对u64的简单封装。我们为它派生了许多trait，使其可打印、复制、比较、排序。其中可排序很重要，因为我们接下来将使用TaskId作为BTreeMap的键。

要生成一个新唯一ID，需要创建一个TaskID::new函数：

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

impl TaskId {
    fn new() -> Self {
        static NEXT_ID: AtomicU64 = AtomicU64::new(0);
        TaskId(NEXT_ID.fetch_add(1, Ordering::Relaxed))
    }
}

该函数使用AtomicU64类型的静态变量NEXT_ID来确保每个ID仅分配一次。fetch_add方法以原子化的方式自增，并在同一个原子操作中返回上一个值。这意味着即使并行调用TaskId::new方法，每个ID也会返回一次。Ordering参数定义是否允许编译器在指令流中对fetch_add操作重新排序。因为我们只要求ID是唯一的，所以在这种情况下，使用最弱的Relaxed排序就足够了。

现在，我们可以使用附加的id字段来扩展Task类型：

pub struct Task {
    id: TaskId, // new
    future: Pin<Box<dyn Future<Output = ()>>>,
}

impl Task {
    pub fn new(future: impl Future<Output = ()> + 'static) -> Task {
        Task {
            id: TaskId::new(), // new
            future: Box::pin(future),
        }
    }
}

新的id字段使唯一地命名任务成为可能，这是唤醒指定任务所必需的。

`Executor`类型

我们在task::executor模块中创建新的Executor类型：

pub mod executor;

use super::{Task, TaskId};
use alloc::{collections::BTreeMap, sync::Arc};
use core::task::Waker;
use crossbeam_queue::ArrayQueue;

pub struct Executor {
    tasks: BTreeMap<TaskId, Task>,
    task_queue: Arc<ArrayQueue<TaskId>>,
    waker_cache: BTreeMap<TaskId, Waker>,
}

impl Executor {
    pub fn new() -> Self {
        Executor {
            tasks: BTreeMap::new(),
            task_queue: Arc::new(ArrayQueue::new(100)),
            waker_cache: BTreeMap::new(),
        }
    }
}

我们没有像在SimpleExecutor中那样将任务存储在VecDeque中，而是存放在一个包含任务ID的task_queue字段和包含实际Task实例的BTreeMap类型的tasks字段中。该映射由TaskId索引，以允许有效地恢复执行特定任务。

task_queue字段是有任务ID组成的ArrayQueue，并封装为实现了引用计数的Arc类型。引用计数使得在多个所有者之间共享变量所有权成为可能。它在堆上分配变量，并计算对变量的活动引用数。当活动引用数达到零时，即不再需要该值，因此会将其释放。

我们将这种Arc<ArrayQueue>类型用于task_queue，以使其能够被执行者和唤醒者共享。这个思路是唤醒者将已唤醒任务的ID推送到队列中。而执行器位于队列的接收端，从task映射中按其ID取回已唤醒的任务，并运行任务。使用固定大小的队列而不是无限制队列（如SegQueue）的原因是，不应在中断处理程序中进行堆分配，将推送到此队列。

除了task_queue和tasks映射外，Executor类型还具有一个waker_cache字段，它也是一个映射。在创建任务后，此映射将缓存任务的Waker。首先，可以使用同一个唤醒器对同一个任务做多次唤醒操作，这相较于每次唤醒均创建一个唤醒器而言更高效。其次，它确保唤醒器的引用计数不会在中断处理程序内被释放，而这可能会导致死锁（有关此问题的更多信息，请参见下文）。

要创建Executor，我们可以编写一个简单的new函数。我们为task_queue选择100的容量，这对可预见的未来而言已经足够了。如果我们的系统在某个时刻真的保有超过100个并发任务，也可以轻松地修改这个值。

生成任务

与SimpleExecutor类似，我们也在Executor类型上编写一个spawn方法，该方法将给定任务添加到tasks映射，并通过将其ID推送到task_queue中来立刻执行唤醒：

impl Executor {
    pub fn spawn(&mut self, task: Task) {
        let task_id = task.id;
        if self.tasks.insert(task.id, task).is_some() {
            panic!("task with same ID already in tasks");
        }
        self.task_queue.push(task_id).expect("queue full");
    }
}

如果映射中已经存在具有相同ID的任务，则BTreeMap::insert方法将直接返回它。由于每个任务都有唯一的ID，理论上不应发生这种情况，因此若出现这种情况我们就产生panic，表明代码中存在错误。同样，当task_queue填满时也会产生panic，因为如果设置的队列大小合适，就不应该发生这种情况。

运行任务

要执行task_queue中的所有任务，我们创建一个私有的run_ready_tasks方法：

use core::task::{Context, Poll};

impl Executor {
    fn run_ready_tasks(&mut self) {
        // 解构`self`以避免借用检查出错
        let Self {
            tasks,
            task_queue,
            waker_cache,
        } = self;

        while let Ok(task_id) = task_queue.pop() {
            let task = match tasks.get_mut(&task_id) {
                Some(task) => task,
                None => continue, // 任务已不存在
            };
            let waker = waker_cache
                .entry(task_id)
                .or_insert_with(|| TaskWaker::new(task_id, task_queue.clone()));
            let mut context = Context::from_waker(waker);
            match task.poll(&mut context) {
                Poll::Ready(()) => {
                    // 任务完成 -> 删除任务及其缓存唤醒器
                    tasks.remove(&task_id);
                    waker_cache.remove(&task_id);
                }
                Poll::Pending => {}
            }
        }
    }
}

该函数的基本思路与SimpleExecutor类似：遍历task_queue中的任务，为每个任务创建唤醒器，并轮询该任务。但我们并不直接将待处理的任务添加到task_queue的队尾，而是让TaskWaker负责将唤醒的任务添加回队列。稍后将显示该唤醒器类型的实现。

让我们研究一下run_ready_tasks方法的一些实现细节：

我们将self解构为三个字段，以避免某些借用检查器错误。即我们的实现需要从闭包内部访问self.task_queue，而目前的闭包会尝试直接借用整个self。这本质上是借阅检查器自己的问题，且将在实现 RFC 2229时解决。
对于每个弹出的任务ID，我们从tasks映射中取出其对应任务的可变引用。由于我们的ScancodeStream会在检查任务是否需要休眠之前就注册唤醒器，因此可能会发生为已经不存在的任务执行唤醒的情况。在这种情况下，我们只需忽略唤醒并继续执行队列中的下一个ID即可。
为了避免在每个轮询中新建唤醒器所带来的性能开销，我们在每个任务创建后将其唤醒器缓存到waker_cache映射中。为此，我们结合使用BTreeMap::entry方法和Entry::or_insert_with，若唤醒器尚不存在则新建一个，再获得其的可变引用。为了创建新的唤醒器，我们克隆了task_queue并将其与任务ID一起传给TaskWaker::new函数（其实现见下文）。由于task_queue封装在Arc中，因此clone只会增加其引用计数，而仍指向同一堆分配的队列。请注意，并非所有唤醒器的实现都可以进行这种重用，但是我们的TaskWaker实现是允许重复的。

任务完成时将返回Poll::Ready。在这种情况下，我们使用BTreeMap::remove方法从tasks映射中删除该任务。如果该任务还有缓存的唤醒器，我们也会将其移除。

唤醒器设计

唤醒器用于将已唤醒的任务ID推送到执行器的task_queue。我们创建一个新的TaskWaker结构体，以存储任务ID和一个task_queue引用：

struct TaskWaker {
    task_id: TaskId,
    task_queue: Arc<ArrayQueue<TaskId>>,
}

由于task_queue的所有权由执行器和唤醒器共享，因此我们使用Arc封装类型来实现共享所有权的引用计数。

唤醒操作的实现非常简单：

impl TaskWaker {
    fn wake_task(&self) {
        self.task_queue.push(self.task_id).expect("task_queue full");
    }
}

我们将task_id推送到引用的task_queue中。由于对ArrayQueue类型的修改仅需要共享的引用，因此我们都不需要&mut self，仅用&self即可实现。

`Wake`trait

为了能够使用TaskWaker类型轮询future，我们首先要将其转为Waker实例。这是必需的，因为Future::poll方法使用Context的实例作参数，而该实例只能基于Waker类型构造。尽管确实可以通过提供一个RawWaker实现来做到这一点，但是使用基于Arc的Waketrait，然后再用标准库提供的Fromtrait的实现来构造Waker，将会更简单且安全。

WakeTrait实现如下所示：

use alloc::task::Wake;

impl Wake for TaskWaker {
    fn wake(self: Arc<Self>) {
        self.wake_task();
    }

    fn wake_by_ref(self: &Arc<Self>) {
        self.wake_task();
    }
}

由于唤醒器通常在执行器和异步任务之间共享，因此trait方法要求将Self的实例封装在Arc类型中，以实现所有权的引用计数。这意味着我们必须将TaskWaker放在Arc中才能进行调用。

wake和wake_by_ref方法之间的区别在于，后者仅需要Arc的引用，而前者需要Arc的所有权，因此通常需要增加引用计数。并非所有类型都支持通过引用调用唤醒，因此方法wake_by_ref的实现是可选的，不过由于该方法可以避免不必要的引用计数修改，所以性能较高。对我们来说，可以在两个trait方法中都简单地继续调用wake_task函数，该函数仅需要一个共享的&self引用。

创建唤醒器

由于所有Arc封装的实现了Wakertrait的类型都支持使用From转换，因此我们现在可以实现Executor::run_ready_tasks方法所需的TaskWaker::new函数了：

impl TaskWaker {
    fn new(task_id: TaskId, task_queue: Arc<ArrayQueue<TaskId>>) -> Waker {
        Waker::from(Arc::new(TaskWaker {
            task_id,
            task_queue,
        }))
    }
}

我们使用task_id和task_queue作为参数创建TaskWaker。然后，我们将TaskWaker封装在Arc中，并使用Waker::from将其转换为Waker。此from方法负责为TaskWaker类型构造RawWakerVTable和RawWaker实例。这个from方法用于TaskWaker类型构造一个RawWakerVTable和一个RawWaker实例。如果你对它的详细工作方式感兴趣，请查看alloccrate中的实现。

`run`方法

在实现了唤醒器之后，我们终于可以为执行器添加一个run方法了：

impl Executor {
    pub fn run(&mut self) -> ! {
        loop {
            self.run_ready_tasks();
        }
    }
}

此方法仅循环调用run_ready_tasks函数。理论上，当tasks映射为空时我们确实可以从令函数返回，不过这并不会发生因为keyboard_task永远不会完成，因此一个简单的loop就足够了。鉴于该函数永不返回，因此我们使用返回类型!以告诉编译器此为发散函数。

现在，我们可以更改kernel_main，以使用新的Executor来代替SimpleExecutor：

use blog_os::task::executor::Executor; // new

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // […] initialization routines, including init_heap, test_main

    let mut executor = Executor::new(); // new
    executor.spawn(Task::new(example_task()));
    executor.spawn(Task::new(keyboard::print_keypresses()));
    executor.run();
}

我们只需要更改导入类型和类型名称。由于run是发散函数，编译器知道它永不返回，因此我们不再需要在kernel_main函数末尾调用hlt_loop。

当我们现在使用cargo run运行内核时，将看到键盘输入依然有效：

不过，QEMU的CPU使用率并没有降低。这是因为我们仍然使CPU始终保持忙碌状态。现在虽然在任务唤通知醒前都不再执行轮询，但仍在循环中检查task_queue。要解决此问题，我们需要在CPU没有其他工作时进入睡眠状态。

空闲时睡眠

基本思路就是在task_queue为空时执行hlt指令。该指令使CPU进入睡眠状态，直到下一个中断到达。CPU在中断后立即会再次激活，这确保了当中断处理程序向task_queue推送任务时，CPU仍然可以直接做出反应。

为了实现这一点，我们在执行器中创建一个新的sleep_if_idle方法，并从run方法中调用它：

impl Executor {
    pub fn run(&mut self) -> ! {
        loop {
            self.run_ready_tasks();
            self.sleep_if_idle();   // new
        }
    }

    fn sleep_if_idle(&self) {
        if self.task_queue.is_empty() {
            x86_64::instructions::hlt();
        }
    }
}

由于我们在run_ready_tasks之后直接调用sleep_if_idle，这将一直循环直到task_queue为空，因此似乎无需再次检查队列。但是，硬件中断可能紧接着在run_ready_tasks返回之后发生，因此在调用sleep_if_idle函数时队列中可能还有一个新任务。仅当队列仍然为空时，我们才通过x86_64crate提供的instructions::hlt函数执行hlt指令，使CPU进入睡眠状态。

不幸的是，在此实现中仍然存在微妙的竞争条件。由于中断是异步的且可以随时发生，因此有可能在is_empty检查和hlt调用之间发生中断：

if self.task_queue.is_empty() {
    /// <--- 这里也可能发生中断
    x86_64::instructions::hlt();
}

万一此中断推送到task_queue，即使现在确实有一个就绪的任务，CPU也会进入睡眠状态。在最坏的情况下，这可能会将键盘中断的处理，延迟到下一次按键或下一个定时器中断。那么我们应该如何预防呢？

答案是在检查之前禁用CPU上的中断，并与hlt指令一起以原子化操作再启用中断。那么，此间发生的所有中断都将延迟到hlt指令之后，从而不会丢失任何唤醒。为了实现该方法，我们可以使用x86_64crate提供的interrupts::enable_and_hlt函数。

修改后的sleep_if_idle函数如下所示：

impl Executor {
    fn sleep_if_idle(&self) {
        use x86_64::instructions::interrupts::{self, enable_and_hlt};

        interrupts::disable();
        if self.task_queue.is_empty() {
            enable_and_hlt();
        } else {
            interrupts::enable();
        }
    }
}

为了避免竞争条件，我们在检查task_queue是否为空之前禁用中断。如果队列确实为空，我们将通过一个原子化操作，使用enable_and_hlt函数启用中断，同时让CPU进入睡眠。如果队列不再为空，则意味着在返回run_ready_tasks之后，中断会唤醒任务。在这种情况下，我们将再次启用中断，且不再hlt而直接继续让程序执行。

现在，执行器在没有任务的情况下能够正确地让CPU进入睡眠状态。我们可以看到，当再次使用cargo run运行内核时，QEMU进程的CPU利用率要低得多。

可能的扩展

我们的执行器现在可以高效地运行任务。它利用唤醒器通知来避免持续轮询等待的任务，并在无任何工作时使CPU进入睡眠状态。但是，我们的执行器仍然非常基础，而且可以通过许多方式来扩展功能：

调度：目前，我们使用VecDeque类型为task_queue实现先进先出（FIFO）策略，这通常也称为循环调度。此策略对于其上的所有任务负载可能并不是最高效的。例如，优先考虑延迟敏感的任务或执行大量I/O的任务可能更加高效。有关更多信息，请参见Operating Systems: Three Easy Pieces一书中的scheduling chapter章节，或Wikipedia上关于调度的文章。
任务生成：我们的Executor::spawn方法当前需要&mut self引用，因此在启动run方法之后将不再可用。为了解决这个问题，我们可以再创建一个额外的Spawner类型，该类型与执行器共享某种队列，并允许从任务自己创建新任务。例如，队列可以直接使用task_queue，也可以是一个在执行器中循环检查的单独的队列。
使用线程：我们尚不支持线程，但会在下一篇文章中添加。这将使我们能够在不同的线程中启动多个执行器实例。这种方法的优点是可以减少长时长任务带来的延迟，因为其他任务可以同时运行。这种方法还可以利用多个CPU内核。
负载均衡：添加线程支持时，如何在执行器间分配任务，以确保所有CPU核心都能够被用到将变得很重要。常见的技术是work stealing。

小结

在这篇文章的开始，我们介绍了多任务，并区分了抢占式多任务（强制性地定期中断正在运行的任务）和协作式多任务（使任务一直运行到自愿放弃对CPU的控制）之间的区别。

然后，我们探讨了Rust的async/await如何提供协作式多任务的语言级实现。Rust的实现基于基于轮询的Futuretrait，该特质抽象了异步任务。使用async/await，就可以像编写普通同步代码一样处理future。不同之处在于异步函数会再次返回Future，为了运行它，需要在某个时刻将其添加到执行器中。

在后台，编译器将async/await代码转换为状态机，每个.await操作对应一个可能的暂停点。通过利用程序对自身执行步骤的了解，编译器就能够为每个暂停点保存最小化的状态信息，从而使每个任务的内存消耗极小。而其中的一个挑战是，生成的状态机可能包含自引用结构体，例如，当异步函数的局部变量相互引用时。为了防止指针失效，Rust使用Pin类型来确保future在被第一次轮询后就不再能够在内存中移动了。

接下来介绍了如何实现，我们首先创建了一个非常简单的执行程序，它会在一个循环中持续轮询所有生成的任务，且完全不使用Waker类型。然后，我们通过实现异步键盘任务来展示了唤醒通知的优点。该任务使用crossbeamcrate提供的无互斥的ArrayQueue类型定义了一个静态变量SCANCODE_QUEUE。现在，键盘中断处理程序不会再直接处理按键，而会将所有接收到的扫描代码放入队列中，然后唤醒已注册的Waker，以发送信号表示有新的输入可用。在接收端，我们创建了一个ScancodeStream类型，以提供一个用于获取队列中下一个scancode的Future。这样就可以创建一个异步print_keypresses任务，以使用async/await来解释并打印队列中的扫描码。

为了利用键盘任务的唤醒通知，我们创建了一个新的Executor类型，该类型使用Arc封装task_queue，以使得就绪任务可共享。我们实现了一个TaskWaker类型，以将唤醒的任务的ID直接推送到task_queue，然后使用执行器进行轮询。为了在空闲时时节省CPU，我们利用hlt指令添加了对CPU在空闲时睡眠的支持。最后，我们讨论了执行器的一些潜在扩展，例如，提供多核支持。

下期预告

我们利用async/await使内核具备了对协作多任务的基本支持。尽管协作式多任务处理非常有效，但是当单个任务运行太长时间并导致其他任务无法运行时，系统就会出现延迟。因此，在我们的内核中添加对抢占式多任务的支持也是合理的。

在下一篇文章中，我们将介绍抢占式多任务处理的最常见形式，线程。除了解决长时长任务的问题，线程还能够利用多个CPU核心，并支持运行不受信任的用户程序。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

支持我的最好方式是在GitHub上赞助我，因为他们不收取任何中间费用。如果你喜欢其他平台，我也有Patreon和Donorbox账户。后者是最灵活的，因为它支持多种货币和一次性捐款。

感谢您的支持！

使用Rust编写操作系统 - 3.4 - 内存分配器设计

Tue, 06 Apr 2021 19:02:00 GMT

:::warning 本文所有内容均为翻译，原文：Allocator Designs；原项目：Writing an OS in Rust :::

本文将展示如何从零编写堆分配器，并讨论不同的分配器设计，包括线性分配，链表分配和固定大小块分配。我们将为这三种分配器分别创建一个可用于内核的基本实现。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-11分支中找到。

介绍

在上一篇文章中，我们向内核添加了对堆分配的基本支持。为此，我们在页表中创建了一个新的内存区域，并使用linked_list_allocatorcrate来管理该内存。现在我们有了一个工作堆，但大部分工作留给了该分配器crate，并没有去了解分配器是如何工作的。

在这篇文章中，我们将展示如何从头开始创建堆分配器，而不是依赖现有的分配器crate。我们还将讨论不同的分配器设计，包括简单的线性分配器和基本的固定大小块分配器，并使用此知识来实现性能提高的分配器（与linked_list_allocatorcrate相比）。

设计目标

分配器的主要任务是管理可用的堆内存，它需要在alloc调用中返回未使用的内存，并跟踪用dealloc释放的内存，以便实现内存重用。最重要的是，它绝不能分配已经在其他地方使用的内存，因为这将会导致未定义的行为。

除了确保正确性之外，还有许多次要任务。例如，分配器应有效地利用可用内存并减少内存碎片。此外，它应该能够很好的用于并发应用程序，并可以扩展到任意数量的处理器。为了获得最佳性能，它甚至可以针对CPU缓存优化内存布局，以提高缓存局部性并避免伪共享。

这些要求会使好的分配器非常复杂。比如jemalloc具有超过30.000行代码。不过，我们通常并不希望在内核中使用如此复杂的代码，因为在内核中一个bug就会导致严重的安全漏洞。幸运的是，与用户空间代码相比，内核代码的分配模式通常要简单得多，因此使用较为简单的分配器设计通常就足够了。

在下面的内容中，我们将介绍三种可能的内核分配器设计，并说明它们的优缺点。

线性分配器

最简单的分配器设计是线性分配器（也称为栈分配器）。它线性的分配内存，并且仅跟踪分配的字节数和分配数。线性分配器仅在非常特定的用例中使用，因为它有一个严格的限制：只能一次释放所有内存。

思路

线性分配器的思路是通过增加（“肿起来”）一个next变量来线性分配内存，该变量指向未使用内存的起点。一开始，next就是堆的起始地址。每次分配时，next都会增加，因此它始终指向已用内存和未用内存之间的边界：

next指针只会向前单方向移动，因此该方案永远不会将相同的存储区域分配出去两次。当指针到达堆尾时，已经没有更多的内存可供分配，因此下一次分配将引发一个内存不足错误。

线性分配器通常通过分配计数器实现，分配计数器在每次alloc调用时加1，在每次dealloc调用时减1。当分配计数器为零时，表示堆上的所有分配都已释放。在这种情况下，可以将next指针重置为堆的起始地址，以便再次分配完整的堆内存。

实现

我们通过声明一个新的allocator::bump子模块开始我们的实现：

pub mod bump;

子模块的代码位于新的src/allocator/bump.rs文件中，内容如下：

pub struct BumpAllocator {
    heap_start: usize,
    heap_end: usize,
    next: usize,
    allocations: usize,
}

impl BumpAllocator {
    /// 创建一个空的线性分配器
    pub const fn new() -> Self {
        BumpAllocator {
            heap_start: 0,
            heap_end: 0,
            next: 0,
            allocations: 0,
        }
    }
    
    /// 使用给定的堆边界初始化线性分配器
    /// 
    /// 该方法为非安全，因为调用者必须保证提供的内存范围未被使用。
    /// 同时，该方法只能被调用一次。
    pub unsafe fn init(&mut self, heap_start: usize, heap_size: usize) {
        self.heap_start = heap_start;
        self.heap_end = heap_start + heap_size;
        self.next = heap_start;
    }
}

heap_start和heap_end字段为堆内存区域的下限和上限。调用者需要确保这些地址有效，否则分配器将返回无效的内存。因此，init函数需要被标记为unsafe调用。

next字段将始终指向堆内存中的首个未使用字节，即下一次分配的起始地址。在初始化函数中将其设置为heap_start，因为在一开始整个堆都是未使用状态。在每次分配时，该字段都会增加分配出去的大小（“肿起来”），以确保我们不会两次返回相同的内存区域。

allocations字段是活动中已分配内存的简单计数器，目标是在释放最后一块已分配内存后重置分配器。初始化为0。

选择创建一个单独的init函数，而不是在new函数中直接执行初始化，是为了是我们的分配器接口与linked_list_allocatorcrate提供的分配器接口一致。这样，无需更改其他代码即可切换分配器。

为线性分配器实现`GlobalAlloc`

如上一篇文章所述，所有堆分配器都需要实现GlobalAlloctrait，其定义如下：

pub unsafe trait GlobalAlloc {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8;
    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout);

    unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { ... }
    unsafe fn realloc(
        &self,
        ptr: *mut u8,
        layout: Layout,
        new_size: usize
    ) -> *mut u8 { ... }
}

仅需要实现alloc和dealloc方法，其他两个方法均具有默认实现，我们在实现时可以忽略。

首次实现尝试

让我们试着为BumpAllocator实现alloc方法：

use alloc::alloc::{GlobalAlloc, Layout};

unsafe impl GlobalAlloc for BumpAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        // TODO 对齐及边界检查
        let alloc_start = self.next;
        self.next = alloc_start + layout.size();
        self.allocations += 1;
        alloc_start as *mut u8
    }

    unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {
        todo!();
    }
}

首先将next字段用作分配的起始地址。然后更新next字段，使其指向分配的结束地址，即堆上的下一个未使用的地址。最后，在将分配的起始地址作为* mut u8指针返回之前，我们将分配计数器加1。

请注意，我们不执行任何边界检查或对齐调整，因此此实现尚不安全。这无关紧要，因为无论如何它都无法通过编译：

error[E0594]: cannot assign to `self.next` which is behind a `&` reference
  --> src/allocator/bump.rs:29:9
   |
26 |     unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
   |                     ----- help: consider changing this to be a mutable reference: `&mut self`
...
29 |         self.next = alloc_start + layout.size();
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be written

（self.allocations += 1行也会报告相同的错误，在此省略。）

发生错误是因为GlobalAlloctrait的alloc和dealloc方法仅使用不可变的&self引用执行，因此无法修改next和allocations字段。这是不行的，因为在分配后更新next是线性分配器的基本原理。

注意，在方法声明中将&self更改为&mut self的编译器建议在这里并不会起作用。因为该方法签名是由GlobalAlloctrait定义的，不能在实现时进行更改。（我在Rust代码库中开了一个关于无效建议的issue。）

`GlobalAlloc`与可变性

在研究这个可变性问题可能的解决方案之前，让我们尝试理解GlobalAlloctrait中的方法为什么使用&self定义参数的原因：正如我们在上一篇文章中看到的那样，全局堆分配器是通过将#[global_allocator]属性添加到一个实现GlobalAlloctrait的static变量来定义的。静态变量在Rust中是不可变的，所以不能使用静态分配器的&mut self引用来调用方法。因此，GlobalAlloc的所有方法仅采用不可变的&self引用。

幸运的是，有一种方法可以从&self引用中获取&mut self引用：我们可以通过将分配器封装在spin::Mutex自旋锁中来使用同步的内部可变性。该类型提供互斥方法lock，从而安全地将&self引用转换为&mut self引用。我们已经在内核中多次使用了该封装类型，比如用在VGA文本缓冲区中。

`Locked`封装类型

借助spin::Mutex封装类型，我们可以为线性分配器实现GlobalAlloc特性。这里的技巧是不是直接为BumpAllocator实现trait，而是为封装的spin::Mutex <BumpAllocator>类型实现trait：

unsafe impl GlobalAlloc for spin::Mutex<BumpAllocator> {…}

很不幸这仍然不起作用，因为Rust编译器不允许为其他crate中定义的类型的实现trait：

error[E0117]: only traits defined in the current crate can be implemented for arbitrary types
  --> src/allocator/bump.rs:28:1
   |
28 | unsafe impl GlobalAlloc for spin::Mutex<BumpAllocator> {
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^--------------------------
   | |                           |
   | |                           `spin::mutex::Mutex` is not defined in the current crate
   | impl doesn't use only types from inside the current crate
   |
   = note: define and implement a trait or new type instead

要解决此问题，我们需要再次封装spin::Mutex以创建自己的封装类型：

/// 封装spin::Mutex，以允许为其实现trait
pub struct Locked<A> {
    inner: spin::Mutex<A>,
}

impl<A> Locked<A> {
    pub const fn new(inner: A) -> Self {
        Locked {
            inner: spin::Mutex::new(inner),
        }
    }

    pub fn lock(&self) -> spin::MutexGuard<A> {
        self.inner.lock()
    }
}

该类型是对spin::Mutex<A>的泛型封装。它对封装的类型A没有任何限制，因此可以用于封装所有类型，而不仅仅是分配器。它提供了一个简单的构造函数new，用于封装给定值。为了方便调用，它还提供了lock函数，该函数可调用被封装的Mutex上的lock函数。由于Locked类型非常通用，也可用在其他分配器实现中，因此我们将它放在父级模块allocator中。

实现`Locked<BumpAllocator>`

Locked类型是在我们自己的crate中定义的（与spin::Mutex不同），因此可以用来为线性分配器实现GlobalAlloc。完整实现如下：

use super::{align_up, Locked};
use alloc::alloc::{GlobalAlloc, Layout};
use core::ptr;

unsafe impl GlobalAlloc for Locked<BumpAllocator> {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        let mut bump = self.lock(); // 获取可变引用

        let alloc_start = align_up(bump.next, layout.align());
        let alloc_end = match alloc_start.checked_add(layout.size()) {
            Some(end) => end,
            None => return ptr::null_mut(),
        };

        if alloc_end > bump.heap_end {
            ptr::null_mut() // 内存不足
        } else {
            bump.next = alloc_end;
            bump.allocations += 1;
            alloc_start as *mut u8
        }
    }

    unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {
        let mut bump = self.lock(); // 获取可变引用

        bump.allocations -= 1;
        if bump.allocations == 0 {
            bump.next = bump.heap_start;
        }
    }
}

alloc和dealloc的第一步是通过inner字段调用Mutex::lock方法，以获取被封装分配器类型的可变引用。该实例将保持锁定状态，直到方法结束，即使在多线程环境中也不会发生数据竞争（我们将很快添加线程支持）。

与前面的原型实现相比，alloc现在的实现遵守对齐要求并执行边界检查，以确保分配器分配的内存块仍在堆内存区域范围内。第一步是将next地址向上界对齐到Layout参数上。我们稍后再展示align_up函数的代码。然后将请求的分配大小加上alloc_start以获得这次分配的结束地址。为了防止在执行大尺寸分配时整型溢出，我们使用checked_add方法进行检查。如果发生溢出或分配结果的结束地址大于堆的结束地址，我们将返回空指针以表示内存不足的情况。否则，我们将更新next地址，并像以前一样将allocations计数器加1。最后返回转换为*mut u8指针的alloc_start地址。

dealloc函数将忽略给定的指针和Layout参数。它仅用于为allocations计数器减1。如果计数器再次归0，则意味着所有分配都已被释放。在这种情况下，它将next地址重置为heap_start地址，以使完整的堆内存再次可用。

地址对齐

align_up函数非常通用，可以将其放入父级模块allocator中。其实现如下：

/// 将给定的`addr`向上对齐到`align`
fn align_up(addr: usize, align: usize) -> usize {
    let remainder = addr % align;
    if remainder == 0 {
        addr // `addr`已对齐
    } else {
        addr - remainder + align
    }
}

函数首先结算addr除以align的余数。如果余数为0，则地址已经与给定的参数对齐。否则，我们通过减去余数（这样新的余数为0）然后加上对齐参数（保证新地址不会变得小于原地址）来对齐地址。

请注意，这并不是实现此函数最高效的实现。更快的实现如下所示：

/// 将给定的`addr`向上对齐到`align`
///
/// 要求`align`是2的幂
fn align_up(addr: usize, align: usize) -> usize {
    (addr + align - 1) & !(align - 1)
}

该函数利用GlobalAlloctrait确保align始终是2的幂。这样就可以非常高效的通过创建位掩码的方式来执行地址对齐。让我们从右往左一步一步理解其工作原理：

由于align是2的幂，因此它的二进制表示只会有一位被置为1（例如0b000100000）。这意味着align-1操作会将所有低位置为1（例如0b00011111）。
通过!执行按位NOT运算，我们得到一个除低于align的位外（例如0b…111111111100000）其余位均置为1的数字。
通过对地址和!(align-1)进行按位AND，地址将向下对齐，即清除所有低于align的位。
由于需要的是要向上对齐而不是向下对齐，因此在执行按位与运算之前，需要给addr增加align-1。如此，已对齐的地址将保持不变，而未对齐的地址将在下一个对齐边界处取整。

你可以选择任意一种实现方式，它们的计算结果是相同的。

使用线性分配器

要使用线性分配器而不是linked_list_allocatorcrate，我们需要修改allocator.rs中的静态变量ALLOCATOR：

use bump::BumpAllocator;

#[global_allocator]
static ALLOCATOR: Locked<BumpAllocator> = Locked::new(BumpAllocator::new());

注意，这里的BumpAllocator::new和Locked::new均已声明为const函数。如果它们是普通函数，则会发生编译错误，因为static变量的初始化表达式必须在编译期求值。

我们不需要在init_heap函数中修改ALLOCATOR.lock().init(HEAP_START, HEAP_SIZE)调用，因为线性分配器提供的接口与linked_list_allocator相同。

现在内核使用了线性分配器！原来的代码应该仍然有效，包括我们在上一篇文章中创建的heap_allocation测试：

> cargo test --test heap_allocation
[…]
Running 3 tests
simple_allocation... [ok]
large_vec... [ok]
many_boxes... [ok]

关于线性分配器的讨论

线性分配的最大优点是效率极高。与需要主动寻找合适的内存块并在alloc和dealloc上执行各种跟踪记录任务的其他分配器设计（参见下文）相比，线性分配器甚至可以被优化为一组汇编指令。因此，在分配器性能优化任务中，线性分配器就十分有用，例如在创建虚拟DOM库时。

不过线性分配器很少被当做全局分配器使用，它通常出现在“分配竞技场”中，即将多个独立的分配器组合在一起以提高性能。Rust中的竞技场分配器的一个实现是toolshed。

线性分配器的缺点

线性分配器的主要局限性在于，它只有在释放了所有分配后才能重新使用释放的内存再次进行分配。这意味着一个长期独占的分配就足以拖延内存的重用。我们只需对many_boxes测试稍加修改就可以演示这个现象：

#[test_case]
fn many_boxes_long_lived() {
    let long_lived = Box::new(1); // new
    for i in 0..HEAP_SIZE {
        let x = Box::new(i);
        assert_eq!(*x, i);
    }
    assert_eq!(*long_lived, 1); // new
}

像many_boxes一样，此测试也会创建大量分配，如果分配器不重新使用释放的内存，将引发内存不足的错误。此外，测试会创建一个long_lived分配，该分配在整个循环执行期间均有效。

当我们尝试运行新测试时将发行测试确实失败了：

> cargo test --test heap_allocation
Running 4 tests
simple_allocation... [ok]
large_vec... [ok]
many_boxes... [ok]
many_boxes_long_lived... [failed]

Error: panicked at 'allocation error: Layout { size_: 8, align_: 8 }', src/lib.rs:86:5

详细讨论一下测试为什么会失败：首先，在堆的开头创建long_lived分配，从而将allocations计数器加1。在每次循环中，都会创建一个短暂的分配并在下一次迭代开始之前就被释放。这意味着allocations计数器在迭代开始时临时增加到2，在迭代结束时减少为1。现在的问题是，线性分配器仅在所有分配释放后才可以重用内存，即allocations计数器减至0。不过这在整个循环完全结束之前都不会发生，因此每次循环迭代都将会分配出去一个新的内存块，从而使得内存在多次迭代后耗尽。

修复这个测试？

有两个的技巧可以用来修复这个线性分配器的测试：

我们可以修改dealloc，通过比较被释放内存的结束地址与next指针是否一致，来判断本次内存释放是否为刚刚才分配出去的内存。如果二者相等，我们可以安全地将next重置为刚刚被释放的分配的起始地址。如此，每次循环都将会重复同一个内存块。
我们也可以添加一个alloc_back方法，该方法使用额外的next_back字段从堆尾开始分配内存。然后，我们就可以为所有长期分配手动调用方法，从而在堆上将短期分配和长期分配分隔开。请注意，只有事先清楚每个分配的有效期限，才能使用这种分隔。该方法的另一个缺点是需要手动执行分配，麻烦且存在安全风险。

虽然这两种方法都可以修复测试，但它们并不是通用的解决方案，因为它们都只能在非常特殊的情况下重用内存。问题是：是否有一个通用的解决方案可以重用所有已释放的内存？

重用所有被释放的内存

正如我们在上一篇文章中了解到的那样，分配可能具有任意的生命周期，并且可以按照任意顺序释放。这意味着我们需要跟踪数量未知且非连续的未使用内存区域，如以下示例所示：

上图显示了堆的分配状态随时间的变化。一开始，整个堆都是未使用的，此时next地址等于heap_start（第1行）。然后出现了第一次分配（第2行）。在第3行中，第二个存储块被分配出去，同时第一个分配被释放了。在第4行中新增了更多分配。其中一半有效期很短，它们在第5行中已被释放，而且在这一行中还新增了另一个分配。

第5行显示了一个基本问题：我们共有五个未使用的内存区域，它们的大小各不相同，但是next指针只能指向最后一个区域的开始。尽管对于本示例，我们可以将其他未使用的存储区域的起始地址和大小存储在大小为4的数组中，但这并不是一个通用的解决方案，因为我们同样可以轻松地创建一个包含8个、16个或1000个未使用的存储区域的例子。

通常，当我们需要处理数量未知的项目时，会倾向于使用在堆上进行分配的集合类型。但在现在并不可行，因为堆分配器不能依赖于自身（这将导致无限递归或死锁）。因此，我们需要找到其他解决方案。

链表分配器

在实现分配器时，跟踪任意数量的空闲内存区域的常见技巧，就是将这些区域本身用作后备存储。这利用了一个事实：这些已释放的内存区域仍被映射到虚拟地址上，其背后都有一个对应的物理帧，但是我们已经不再需要其上存储的信息了。通过使用区域本身存储该区域相关的内存释放信息，我们就可以跟踪任意数量的释放区域，而无需额外的内存。

最常见的实现方法是在释放的内存中构造一个链表，每个节点都是一个已释放的内存区域：

每个列表节点包含两个字段：此内存区域的大小和指向下一个未使用的内存区域的指针。使用这种方法，我们只需要那个指向第一个未使用区域的指针（称为head）即可跟踪所有未使用区域，而与它们的数量无关。产生的数据结构通常称为空闲列表。

你可能已经从名称中猜到，这正是linked_list_allocatorcrate使用的技术。使用此技术的分配器通常也被称为池分配器。

实现链表分配器

接下来，我们将使用上述跟踪已释放的内存区域的方法，自己实现一个简单的LinkedListAllocator类型。以后的文章并不需要这一部分的内容，因此你可以根据需要选择跳过实现细节。

分配器类型

我们首先在新的allocator::linked_list子模块中创建一个私有ListNode结构：

pub mod linked_list;

struct ListNode {
    size: usize,
    next: Option<&'static mut ListNode>,
}

就像在上图中描述的那样，列表节点具有一个size字段和一个指向下一个节点的可选指针，由Option<&'static mut ListNode>类型表示。静态mut类型在语义上描述了指针拥有其后指向的对象。这就基本上就是一个Box类型，只不过它没有能够在作用域末尾释放持有对象的析构函数。

我们为ListNode实现下列方法：

impl ListNode {
    const fn new(size: usize) -> Self {
        ListNode { size, next: None }
    }

    fn start_addr(&self) -> usize {
        self as *const Self as usize
    }

    fn end_addr(&self) -> usize {
        self.start_addr() + self.size
    }
}

该类型具有一个简单的构造函数new，以及用于计算所表示内存区域的开始地址和结束地址的方法。我们将新函数设为const函数，因为稍后会在构造静态链表分配器时使用到它。请注意，在const函数中使用可变引用（包括将next字段设置为None）仍然不稳定。为了能够编译，我们需要在lib.rs的开头添加#![feature(const_mut_refs)]。

我们现在可以使用ListNode结构作为积木，来创建LinkedListAllocator结构体：

pub struct LinkedListAllocator {
    head: ListNode,
}

impl LinkedListAllocator {
    /// 创建一个空的`LinkedListAllocator`.
    pub const fn new() -> Self {
        Self {
            head: ListNode::new(0),
        }
    }

    /// 使用给定的堆边界初始化分配器
    /// 
    /// 该方法为非安全，因为调用者必须保证提供的内存范围未被使用。
    /// 同时，该方法只能被调用一次。
    pub unsafe fn init(&mut self, heap_start: usize, heap_size: usize) {
        self.add_free_region(heap_start, heap_size);
    }

    /// 将给定的内存区域添加至链表前端
    unsafe fn add_free_region(&mut self, addr: usize, size: usize) {
        todo!();
    }
}

结构体包含一个head节点，指向第一个堆区域。我们只对next指针的值感兴趣，因此在ListNode::new函数中将大小设为0。将head设置为ListNode而不是仅使用&'static mut ListNode的优点是相应的alloc方法的实现将会更加简单。

就像线性分配器一样，new函数并不会直接使用堆边界来初始化分配器。除了希望保持API兼容性之外，原因还在于初始化过程需要将一个节点写入堆内存，这只能在运行时发生。然而，new函数必须是可以在编译时求值的const函数，因为它将用于初始化静态变量ALLOCATOR。出于这个原因，我们仍然使用一个独立的非-常函数init。

init方法使用add_free_region方法，稍后将展示其实现。现在，我们使用todo!宏提供一个总是panic的实现占位符。

`add_free_region`方法

add_free_region方法为链表提供了基本的push操作。目前，我们仅在init中调用此方法，但它也将成为我们dealloc实现中的核心方法。请记住，当释放分配的内存区域时，将调用dealloc方法。为了跟踪此次释放产生的的未使用内存区域，我们希望将其push到链表中。

add_free_region方法的实现如下：


use super::align_up;
use core::mem;

impl LinkedListAllocator {
    /// 将给定的内存区域添加至链表前端
    unsafe fn add_free_region(&mut self, addr: usize, size: usize) {
        // 确保此空闲区域足以容纳一个`ListNode`
        assert_eq!(align_up(addr, mem::align_of::<ListNode>()), addr);
        assert!(size >= mem::size_of::<ListNode>());

        // 创建一个新的`ListNode`并将其添加至链表前端
        let mut node = ListNode::new(size);
        node.next = self.head.next.take();
        let node_ptr = addr as *mut ListNode;
        node_ptr.write(node);
        self.head.next = Some(&mut *node_ptr)
    }
}

该方法获取一个内存区域的地址和大小作为参数，将该区域添加到列表前端。首先要保证给定的内存区域具有存储ListNode所需的大小和对齐方式。然后再按照下图中的步骤创建节点并将其插入到列表中：

步骤0显示了调用add_free_region前堆的状态。在步骤1中，使用图中标记为freed的内存区域作为参数调用该方法。初步检查后，该方法使用空闲区域大小作为参数，在其调用栈上创建了一个新node。然后，它使用Option::take方法将新node的next指针设置为当前的头指针，并将头指针重置为None。

在步骤2中，该方法使用write方法将新创建的node（译注：目前仍在调用栈中）写入空闲内存区域的开头。最后将head指针指向这个新节点。图中最后呈现出来的指针结构略显混乱，这是因为释放区域总是在列表的开头插入，不过如果我们跟随指针，就会从head指针开始依次到达每个空闲区域了。

`find_region`函数

链表的另一个基本操作是查找条目并将其从列表中移除。这是实现alloc方法所需的核心操作。我们通过以下方式将该操作实现为find_region方法：

impl LinkedListAllocator {
    /// 按照给定大小和对齐方式查找一个空闲内存区域
    /// 并将其从链表中删除
    ///
    /// 返回一个包含`ListNode`和其开始地址的分配
    fn find_region(&mut self, size: usize, align: usize)
        -> Option<(&'static mut ListNode, usize)>
    {
        // 当前链表节点的引用，会在每次迭代中更新
        let mut current = &mut self.head;
        // 在链表中查找一个足够大的内存区域
        while let Some(ref mut region) = current.next {
            if let Ok(alloc_start) = Self::alloc_from_region(&region, size, align) {
                // 该区域可以容纳所需的分配，则将该区域从链表中删除
                let next = region.next.take();
                let ret = Some((current.next.take().unwrap(), alloc_start));
                current.next = next;
                return ret;
            } else {
                // 该区域不可以容纳所需的分配，则继续下一轮迭代查找
                current = current.next.as_mut().unwrap();
            }
        }

        // 已经找不到合适的内存区域了
        None
    }
}

该方法使用一个current变量和一个while let循环来遍历列表元素。首先，将current设置到（假的）head节点。然后，在每次迭代中，它都会更新为当前节点的next字段（在else块中）。如果该区域适合于具有给定大小和对齐方式的分配，则将该区域从链表中删除，并与alloc_start地址一起返回。

当current.next指针变为None时，循环退出。这意味着我们遍历了整个链表，却没并有找到适合于给定分配的区域。在这种情况下，我们将返回None。检查区域是否合适由alloc_from_region函数完成，我们将在稍后展示其实现。

先让我们更加详细地研究如何从列表中删除合适的区域：

步骤0显示了链表指针调整之前的状态。region区域、current区域、region.next指针和current.next指针均已在图中标出。在步骤1中，使用Option::take方法将region.next和current.next指针都重置为None。原来的指针分别存储在局部变量next和ret中。

在步骤2中，将局部变量next指针赋给current.next指针，也就是原来的region.next指针。结果是current现在直接指向region之后的下一个区域，因此region就不再是链表中的元素了。最后将存储在局部变量ret中的指针返回。

`alloc_from_region`函数

alloc_from_region函数返回给定内存区域是否适合于具有给定大小和对齐方式的分配。其实现如下：

impl LinkedListAllocator {
    /// 尝试使用给定内存区域，为给定大小和对齐方式的分配做出分配
    ///
    /// 如果成功则返回分配的开始地址。
    fn alloc_from_region(region: &ListNode, size: usize, align: usize)
        -> Result<usize, ()>
    {
        let alloc_start = align_up(region.start_addr(), align);
        let alloc_end = alloc_start.checked_add(size).ok_or(())?;

        if alloc_end > region.end_addr() {
            // 内存区域太小
            return Err(());
        }

        let excess_size = region.end_addr() - alloc_end;
        if excess_size > 0 && excess_size < mem::size_of::<ListNode>() {
            // 该内存区域的剩余部分太小，无法容纳一个`ListNode`
            // （这是必须的，因为分配动作会将该区域分为已使用和未使用两个部分）
            return Err(());
        }

        // 该区域适合于给定的分配
        Ok(alloc_start)
    }
}

首先，该函数使用我们之前定义的align_up函数和checked_add方法来计算给定分配的起始地址和结束地址。若发生溢出，或结束地址在给定区域的结束地址之后，则给定区域过小，不适合给定分配，所以我们返回错误。

接下来，函数执行的检查可能不太直观。不过这个检查是必要的，因为在大多数情况下，给定区域不可能正好就适合给定分配，因此分配过后，该区域的一部分仍为未使用区域。而此次分配之后，该区域的这一空闲部分必须足够大，以存储其自己的ListNode。该检查将准确地验证：分配是否完全合适（excess_size == 0）或多余的大小是否足以存储一个ListNode。

为链表分配器实现`GlobalAlloc`

使用add_free_region和find_region方法提供的基本操作，就可以实现GlobalAlloctrait了。与线性分配器一样，我们不直接为LinkedListAllocator实现trait，而是为封装类型Locked<LinkedListAllocator>实现trait。Locked封装类型使用自旋锁增加了内部可变性，这使我们可以修改分配器实例，尽管alloc和dealloc方法只使用了不可变引用&self。

实现看起来像这样：

use super::Locked;
use alloc::alloc::{GlobalAlloc, Layout};
use core::ptr;

unsafe impl GlobalAlloc for Locked<LinkedListAllocator> {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        // 调整对齐布局
        let (size, align) = LinkedListAllocator::size_align(layout);
        let mut allocator = self.lock();

        if let Some((region, alloc_start)) = allocator.find_region(size, align) {
            let alloc_end = alloc_start.checked_add(size).expect("overflow");
            let excess_size = region.end_addr() - alloc_end;
            if excess_size > 0 {
                allocator.add_free_region(alloc_end, excess_size);
            }
            alloc_start as *mut u8
        } else {
            ptr::null_mut()
        }
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        // 调整对齐布局
        let (size, _) = LinkedListAllocator::size_align(layout);

        self.lock().add_free_region(ptr as usize, size)
    }
}

我们西安从更简单的dealloc方法看起：首先执行一些布局调整，我们将在稍后进行解释，并通过在Locked封装上调用Mutex::lock函数来获取分配器的可变引用&mut LinkedListAllocator。然后调用add_free_region函数将释放的区域添加到空闲链表中。

alloc方法有点复杂。类似的，先进行布局调整，再调用Mutex::lock函数以获取分配器的可变引用。然后使用find_region找到适合这次分配的内存区域，并将其从空闲链表中删除。如果没找到返回None时，方法会因为没有合适的内存区域而返回null_mut，以表示分配错误。

在分配成功的情况下，find_region方法将返回包含合适区域（已从空闲链表中移除）和分配起始地址的元组。使用alloc_start、给定的分配大小、区域的结束地址，方法将重新计算分配的结束地址以及该区域的剩余大小。如果确实有剩余大小，方法将调用add_free_region将区域的剩余部分重新添加回空闲列表。最后将alloc_start地址转换为*mut u8类型并返回。

布局调整

那么，我们在alloc和dealloc开头都进行了哪些布局调整？其实就是为了确保每个分配的块都能够存储ListNode。这一点很重要，因为在某个时刻，该内存块将要被释放时，我们需要向其写入一个ListNode记录。如果该内存块小于ListNode或并没有正确的对齐，就会引发未定义行为。

布局调整由size_align函数执行，该函数实现如下：

impl LinkedListAllocator {
    /// 调整给定布局，使生成的用以分配的内存区域也能够存储`ListNode`。
    ///
    /// 以元组`(size, align)`的形式返回调整后的大小和对齐方式。
    fn size_align(layout: Layout) -> (usize, usize) {
        let layout = layout
            .align_to(mem::align_of::<ListNode>())
            .expect("adjusting alignment failed")
            .pad_to_align();
        let size = layout.size().max(mem::size_of::<ListNode>());
        (size, layout.align())
    }
}

首先，函数在传入的Layout上调用align_to方法，以在必要时为ListNode增加空间以对齐。然后使用pad_to_align方法将布局大小向上对齐，以确保下一个内存块的起始地址也将具有正确的对齐方式，从而能再储一个ListNode。接下来，函数使用max方法强制所分配的大小至少要为mem::size_of::<ListNode>。如此，dealloc函数就可以安全地将ListNode写入已释放的内存块中了。

使用链表分配器

现在，我们只需要在allocator模块中更新静态变量ALLOCATOR，就可以使用新的LinkedListAllocator了：

use linked_list::LinkedListAllocator;

#[global_allocator]
static ALLOCATOR: Locked<LinkedListAllocator> =
    Locked::new(LinkedListAllocator::new());

由于线性分配器和链接列表分配器的init函数行为一致，因此我们无需修改init_heap中的init调用。

现在，当我们再次运行heap_allocation测试时，可以看到所有测试都通过了，其中包括在线性分配器中失败的many_boxes_long_lived测试：

> cargo test --test heap_allocation
simple_allocation... [ok]
large_vec... [ok]
many_boxes... [ok]
many_boxes_long_lived... [ok]

这说明了我们的链表分配器能够将释放的内存重新用于后续分配。

关于链表分配器的讨论

与线性分配器相比，链表分配器更适合作为通用分配器使用，主要是因为它能够立刻重用释放的内存。当然，链表分配器也有一些缺点。其中一部分是由于我们的实现过于简单引起的，另一些则是由于链表分配器的设计本身存在的固有缺陷。

合并空闲块

我们实现的主要问题是，它只会将堆拆分为越来越小的块，而不会再将小块合并成大块。考虑下面的例子：

在第一行中，堆上创建了三个分配。它们中的两个在第2行中被释放，而第三个在第3行中被释放。现在虽然整个堆处于空闲状态，但仍旧被分成四个单独的块。此时，可能会由于四个块中的任何一个都不足够大，导致内核不能再进行大型分配了。随着时间的流逝，该过程将持续进行，并将堆分成越来越小的块。最后可能出现的情况就是，堆中的块过于分散过于小，使得哪怕正常大小的分配都无法进行了。

要解决此问题，我们需要将相邻的释放块重新合并在一起。对于上面的示例，这意味着：

跟第一张图一样，第2行同样释放了三个分配中的两个。与第一张图不同的是，这次不在留着堆碎片不管，我们现在添加一个额外的2a行合并操作，将两个最右边的块重新合并在一起。在第3行中，第三个分配被释放（跟第一张图一样），从而产生由三个独立的块组成的一整个空闲的堆。同样的，我们再添加额外的3a行合并操作，将三个相邻的块重新合并成一整块未使用的堆。

linked_list_allocatorcrate使用以下方式实现此合并策略：与我们的实现不同，该实现并不向列表前端插入deallocate释放的内存块，而是始终将列表按开始地址排序。这样，可以通过检查列表中两个相邻块的地址和大小，直接在deallocate调用时执行合并。当然，这种方式的释放速度稍慢，但是可以防止在我们的实现中出现的堆碎片。

性能

正如我们在前文了解到的，线性分配器非常快，可以被优化为一组汇编操作。链表分配器作为分配器，性能则要差很多。问题在于，分配请求可能需要遍历完整的链表才能找到合适的块。

由于链表长度取决于未使用的存储块的数量，因此对于不同的程序，其性能可能会发生极大的变化。对于仅创建几个分配的程序，其分配性能较好。但是，对于一个用很多分配将堆碎片化的程序，其分配性能将非常差，因为链表将变得很长，且可能包含非常多非常小的块。

值得注意的是，这个性能问题并不是因为我们的实现过于简单而引起的，这是链表分配器设计的固有缺陷。由于分配器的性能对于内核级代码极其重要，因此，我们将在下文中探讨第三种分配器设计，该设计以降低内存利用率为代价来提高的性能。

固定大小的块分配器

接下来，我们将介绍一种使用固定大小的内存块来进行分配的分配器。这种分配器通常会返回大于分配所需的内存块，产生内部碎片从而导致一定的内存浪费。不过，它也大大降低了找到合适块所需的时间（与链表分配器相比），从而大幅提升分配性能。

简介

固定大小的块分配器的思路是：我们不再分配跟请求大小完全一致的块，而是定义少量种类的块，并为每一次分配选择一个大小向上取整的块。例如，我们可以定义16、64和512字节的块，分配需要4字节时就返回一个16字节的块，分配需要48字节时就返回一个64字节的块，而分配需要128字节时就返回一个512字节的块。

像链表分配器一样，我们通过在未使用的内存中创建链表来跟踪未使用的内存。不同的是，这次不是像链表分配器那样用一个链表来跟踪不同大小的块，而是为不同大小的块分别设置各自的跟踪链表。于是，每个链表仅存储同一种大小的块。例如，在定义了16、64和512字节块的情况下，内存中将存在三个单独的链表：

原先的链表分配器仅有一个head指针，现在有head_16、head_64和head_512三个了，它们分别指向各自对应大小的第一个未使用的块。而每个链表中的所有节点都具有相同的大小。例如，由head_16指针开始的链表仅包含16字节的块。这意味着我们不再需要在每个列表节点中存储块的大小，因为它已经由头指针的名称决定了。

由于链表中的每个节点都具有相同的大小，因此对一个分配请求来说，用链表中的哪个节点都是一样的。这意味着我们可以使用下列步骤非常有效地执行分配：

将请求的分配大小向上取整到最接近的块大小。比如在请求分配12个字节时，按照上例，我们将选择分配一个大小为16的块。
（例如从数组中）取出链表的头指针。对于大小为16的块，我们需要用到head_16。
从链表中移除并返回第一个块。

值得注意的是，此处仅需要返回链表的第一个元素，而不再需要遍历整个链表。因此，这种分配器会比链表分配器快得多。

块大小与内存浪费

我们在取整时将浪费的多少内存，取决于块大小的设置。例如，当返回一个分配请求128字节而我们返回一个512字节的块时，分配出去的内存中有四分之三被浪费了。通过定义合理的块大小，可以在一定程度上限制浪费的内存。例如，当使用2的幂（4、8、16、32、64、128等）作为块大小时，在最坏的情况下也只会浪费一半的内存，平均而言仅浪费四分之一的内存。

基于程序中的公共分配尺寸来优化块大小也是很常见的。例如，我们可以额外增加大小为24的块，以提高经常执行24字节分配的程序的内存使用率。这样通常可以减少浪费的内存量，而且不会造成性能损失。

释放

像分配一样，释放也非常高效。它涉及以下步骤：

将释放的分配大小向上取整到最接近的块大小。这是必需的，因为编译器传递给dealloc的并不是alloc返回的块的大小，而只是所请求的分配大小。通过在alloc和dealloc中使用相同的向上取整函数，就可以确保释放的内存量始终正确。
（例如从数组中）取出链表的头指针。
更新头指针，将释放的块添加到链表的前端。

值得注意的是，释放过程也不需要遍历链表。这意味着无论链表有多长，dealloc调用所需的时间都是一个常量。

后备分配器

鉴于大容量分配（大于2KB）通常是很少见的，尤其是在操作系统内核中，因此对于这些分配，使用不同的分配器可能也是合理的。例如，为了减少内存浪费，我们可以转而使用链表分配器，以进行大于2048字节的分配。因为这种尺寸的分配应该非常少，所以链表也将保持较小的状态，而分配/释放也仍将保持相当快的速度。

创建新块

前面我们始终假设特定大小的链表中始终有足够多的块来满足所有分配请求。但是，有时候某种大小的块的链表中没有多余的块了。此时，有两种方法可以创建特定大小的空闲新块来满足分配请求：

从后备分配器中分配一个新块（如果有后备分配器的话）。
从其他链表中拆分更大的块。如果块大小设置为2的幂，那么此方法将最有效。例如，一个32字节的块可以分为两个16字节的块。

在我们的实现中，将选择从后备分配器中分配新的块，因为这种实现要简单得多。

实现固定大小的块分配器

现在我们知道了固定大小的块分配器是如何工作的，就可以着手实现它了。我们将不会依赖上一节中创建的链表分配器的实现，因此即使你跳过了链表分配器的实现，也可以正常阅读这一部分。

链表节点

我们通过在新的allocator::fixed_size_block模块中创建ListNode类型来开始实现：

pub mod fixed_size_block;

struct ListNode {
    next: Option<&'static mut ListNode>,
}

该类型很像我们在链表分配器中实现的ListNode类型，不同之处在于这里没有了第二个字段size。不需要size字段，是因为在固定大小的块分配器的设计思路中，同一个链表中的每个块大小都相同。

块大小

接下来，我们定义一个常量切片BLOCK_SIZES，包含了实现中将会用到的块大小：

/// 将会用到的块大小
///
/// 块大小必须是2的幂，因为它们也将用于块对齐
///（对齐方式必须为2的幂）
const BLOCK_SIZES: &[usize] = &[8, 16, 32, 64, 128, 256, 512, 1024, 2048];

我们使用从8到2048的2的幂作为块大小。我们不定义任何小于8的块，因为每个块在被释放时必须能够存储指向下一个块的64位指针。对于大于2048字节的分配，我们将使用链表分配器。

为了简化实现，我们定义：一个块的大小也是其在内存中所需的对齐方式。因此，一个16字节的块始终在16字节的边界上对齐，而512字节的块始终在512字节的边界上对齐。由于对齐始终需要是2的幂，因此也排除了任何其他块大小。如果将来需要的块大小不是2的幂，我们仍然可以为此调整执行方式（例如，再定义一个BLOCK_ALIGNMENTS数组）。

分配器类型

使用ListNode类型和BLOCK_SIZES切片，我们现在可以定义分配器类型：

pub struct FixedSizeBlockAllocator {
    list_heads: [Option<&'static mut ListNode>; BLOCK_SIZES.len()],
    fallback_allocator: linked_list_allocator::Heap,
}

list_heads字段是head指针的数组，每个块大小对应一个头指针。使用BLOCK_SIZES切片的len()作为数组长度创建数组。对于那些大于最大块尺寸的分配，我们使用linked_list_allocator提供的分配器作为后备分配器。当然，也可以改用我们自己实现的LinkedListAllocator，但是它并不会自动合并空闲块。

为了构造一个FixedSizeBlockAllocator，我们依旧提供与其他类型分配器相同的new函数和init函数：

impl FixedSizeBlockAllocator {
    /// 创建一个空的`FixedSizeBlockAllocator`.
    pub const fn new() -> Self {
        const EMPTY: Option<&'static mut ListNode> = None;
        FixedSizeBlockAllocator {
            list_heads: [EMPTY; BLOCK_SIZES.len()],
            fallback_allocator: linked_list_allocator::Heap::empty(),
        }
    }

    /// 使用给定的堆边界初始化线性分配器
    /// 
    /// 该方法为非安全，因为调用者必须保证提供的内存范围未被使用。
    /// 同时，该方法只能被调用一次。
    pub unsafe fn init(&mut self, heap_start: usize, heap_size: usize) {
        self.fallback_allocator.init(heap_start, heap_size);
    }
}

新函数只是使用空节点初始化list_heads数组，并创建一个空链表分配器作为fallback_allocator。EMPTY必须为常量的原因是要告诉Rust编译器我们要使用常量值初始化数组。直接将数组初始化为[None; BLOCK_SIZES.len()]会有编译错误，因为之后编译器会要求Option<&'static mut ListNode>需要实现Copytrait，对于这点我们无能为力。这是目前的Rust编译器所具有的局限性，在未来的编译器中可能会解决这个问题。

如果你跳过了LinkedListAllocator的实现一节，则还需要在lib.rs的开头添加#![feature(const_mut_refs)]。原因是在const函数中使用可变引用类型仍然不稳定，包括list_heads字段的数组元素Option<&'static mut ListNode>类型（即使我们将其设置为None）也是如此。

非安全的init函数仅用于调用fallback_allocator的init函数，而无需对list_heads数组进行任何其他初始化。此后我们将在alloc和dealloc调用上延迟初始化该列表。

为了方便起见，我们还创建了一个私有的fallback_alloc方法，该方法使用fallback_allocator执行分配：

use alloc::alloc::Layout;
use core::ptr;

impl FixedSizeBlockAllocator {
    /// 使用后备分配器执行分配.
    fn fallback_alloc(&mut self, layout: Layout) -> *mut u8 {
        match self.fallback_allocator.allocate_first_fit(layout) {
            Ok(ptr) => ptr.as_ptr(),
            Err(_) => ptr::null_mut(),
        }
    }
}

由于linked_list_allocatorcrate的Heap类型无法实现GlobalAlloc（因为不使用锁就不可能实现）。而是提供了一个略有不同的接口的allocate_first_fit方法。它不返回*mut u8也不使用空指针来指示分配错误，而是返回Result<NonNull<u8>, ()>。 NonNull类型是是对那些能够保证自己是非空指针的裸指针的抽象。通过在匹配到Ok时返回NonNull::as_ptr方法，匹配到Err时返回null指针，我们可以方便地将其转换回*mut u8类型。

计算块大小列表索引

在实现GlobalAlloctrait之前，我们定义一个list_index帮助函数，用来返回适合给定Layout的最小块大小：

/// 为给定的`layout`选择一个合适的块大小
///
/// 返回该块大小在`BLOCK_SIZES`中的索引
fn list_index(layout: &Layout) -> Option<usize> {
    let required_block_size = layout.size().max(layout.align());
    BLOCK_SIZES.iter().position(|&s| s >= required_block_size)
}

块必须至少具有给定Layout所需的大小和对齐方式。由于我们定义了块的大小也是它的对齐方式，因此这意味着required_block_size应为布局的size()和align()属性中的较大值。为了在BLOCK_SIZES切片中查找最接近向上取整的块大小，我们首先使用iter()方法获取迭代器，然后使用position()方法在切片中查找第一个不小于required_block_size的块的索引并返回该索引。

请注意，这里并不返回块大小本身，而是返回BLOCK_SIZES切片的索引。原因是我们还要使用该索引作为list_heads数组的索引。

为固定大小的块分配器实现`GlobalAlloc`

最后一步是实现GlobalAlloctrait：

use super::Locked;
use alloc::alloc::GlobalAlloc;

unsafe impl GlobalAlloc for Locked<FixedSizeBlockAllocator> {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        todo!();
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        todo!();
    }
}

同其他分配器一样，我们仍不直接为分配器类型实现GlobalAlloctrait，而是使用Locked封装为其添加同步的内部可变性。由于alloc和dealloc的实现相对复杂，因此我们将在接下来的文章中逐一介绍它们。

`alloc`

alloc方法的实现如下所示：

unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
    let mut allocator = self.lock();
    match list_index(&layout) {
        Some(index) => {
            match allocator.list_heads[index].take() {
                Some(node) => {
                    allocator.list_heads[index] = node.next.take();
                    node as *mut ListNode as *mut u8
                }
                None => {
                    // 链表中没有多余的块了，于是创建并分配新块
                    let block_size = BLOCK_SIZES[index];
                    // 这只在所有块大小均为2的幂时有效
                    let block_align = block_size;
                    let layout = Layout::from_size_align(block_size, block_align)
                        .unwrap();
                    allocator.fallback_alloc(layout)
                }
            }
        }
        None => allocator.fallback_alloc(layout),
    }
}

我们来一步一步看：

首先调用Locked::lock方法获取对封装中的分配器实例的可变引用。然后调用刚刚定义的list_index函数来计算合适于给定布局的块大小，并尝试使用块大小索引从list_heads数组中取出对应链表的头指针。如果列表索引为None，则说明这次分配没有合适的块大小，于是使用fallback_alloc函数调用fallback_allocator进行分配。

如果列表索引为Some，就尝试使用Option::take方法取出（译注：获取并移除）list_heads[index]所在的链表的第一个节点node。如果该链表不为空，则进入match语句的Some(node)分支，将该链表的头指针指向node的后继节点（也是使用take）。最后，我们将取出的node以*mut u8指针的形式返回。

如果链表头指针为None，则表示该块大小对应的链表为空。这意味着我们需要按照上面描述的那样创建一个新块。为此，我们首先从BLOCK_SIZES切片中获取该块大小的具体值，并将其用作新块的大小和对齐方式，再从中创建一个新的Layout，并调用fallback_alloc方法执行分配。之所以需要调整布局和对齐方式，是因为该块将在释放时会被添加到相应的块链表中。

`dealloc`

dealloc方法的实现如下所示：

use core::{mem, ptr::NonNull};

// 在`unsafe impl GlobalAlloc`内

unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
    let mut allocator = self.lock();
    match list_index(&layout) {
        Some(index) => {
            let new_node = ListNode {
                next: allocator.list_heads[index].take(),
            };
            // 为存储的节点验证块大小和块对齐方式
            // verify that block has size and alignment required for storing node
            assert!(mem::size_of::<ListNode>() <= BLOCK_SIZES[index]);
            assert!(mem::align_of::<ListNode>() <= BLOCK_SIZES[index]);
            let new_node_ptr = ptr as *mut ListNode;
            new_node_ptr.write(new_node);
            allocator.list_heads[index] = Some(&mut *new_node_ptr);
        }
        None => {
            let ptr = NonNull::new(ptr).unwrap();
            allocator.fallback_allocator.deallocate(ptr, layout);
        }
    }
}

类似alloc中的操作，首先调用lock方法获取分配器的可变引用，然后使用list_index函数获取与给定Layout大小相适应的块链表。如果索引为None，则BLOCK_SIZES中并没有合适的块大小，这说明该分配是由后备分配器创建的。因此，这里也应调用后备分配器的deallocate来释放内存。该方法期望使用NonNull而不是*mut u8，因此我们需要做指针转换。（仅当指针为空时，调用unwrap才会失败，而在编译器调用dealloc时这不可能发生。）

如果list_index返回一个块大小的索引，则需要将已释放的内存块添加到相应块大小的链表中。为此，我们首先创建一个指向当前链表头的新ListNode（仍然使用Option::take）。在将新节点写入释放的内存块之前，我们首先断言由index指定的块大小具有存储ListNode所需的大小和对齐方式。然后，我们通过将参数给定的*mut u8指针转换为*mut ListNode指针，并在其上调用非安全的write方法来将new_node写入内存块。最后一步是将列表的头部指针指向新建的ListNode，该链表的目前的指针为None，因为我们在前面使用take取走了原指针而留下一个None。为此，我们将裸指针new_node_ptr转换为一个可变引用。

这里有几点值得注意：

我们不区分某个块究竟是从块链表分配的，还是从后备分配器中分配。这意味着将在alloc中创建的新块在dealloc时能够添加到相应的块链表中，从而增加该块大小链表中所包含的块数。
在我们的实现中，alloc方法是唯一能够创建新块的地方。这意味着我们初始化时仅有一系列空的块链表，且仅在执行针对特定块大小的分配时，才惰性填充相应的链表。
即使我们执行了一些unsafe操作，我们也不需要在alloc和dealloc中使用unsafe块。原因是Rust目前将整个非安全函数的函数体视为一个大的unsafe块。由于使用显式unsafe块的优点是很能够明显指出哪些操作是非安全的哪些操是安全的，因此已经有一个RFC提案讨论更改Rust当前的这种行为。

使用固定大小的块分配器

要使用新的FixedSizeBlockAllocator，我们需要在allocator模块中修改静态变量ALLOCATOR：

use fixed_size_block::FixedSizeBlockAllocator;

#[global_allocator]
static ALLOCATOR: Locked<FixedSizeBlockAllocator> = Locked::new(
    FixedSizeBlockAllocator::new());

由于init函数在我们实现的所有分配器中均具有相同的行为，因此无需修改init_heap中的init调用。

现在，当我们再次运行heap_allocation测试时，所有测试仍应通过：

> cargo test --test heap_allocation
simple_allocation... [ok]
large_vec... [ok]
many_boxes... [ok]
many_boxes_long_lived... [ok]

这个新分配器看起来也能够正常工作！

关于固定大小的块分配器的讨论

尽管固定大小的块分配器性能好于链表分配器，但是当使用2的幂作为块大小时，它可能会浪费了多达一半的内存。至于这种权衡是否值得，在很大程度上取决于应用程序类型。对于性能至关重要的操作系统内核而言，固定大小的块分配器似乎是更好的选择。

在实现方面，我们可以在当前实现的基础上继续进行多项改进：

与其使用后备分配器惰性分配块，不如在初始化时预先填充各链表，以提高初始的分配的性能。
为了简化实现，我们只允许块大小为2的幂，以便我们也可以将快大小也当做块对齐方式使用。通过以不同方式存储（或计算）对齐方式，我们还可以允许任意其他块大小。如此，我们就可以增加更多的块大小，例如为常见的分配建立块大小链表，以最大程度地减少内存浪费。
我们目前仅创建新的块，但不再释放它们，这将产生块碎片，最终可能会导致在进行大型分配时分配失败。为每个块大小强制设置最大链表长度可能也是合理的。当达到最大长度时，不应继续将其添加到链表中，而应当使用后备分配器直接将其彻底释放。
我们可以使用一个特殊的分配器来分配大于4KiB的内存，而不是使用后备的链表分配器。这个思路是利用大小恰好为4KiB的内存分页，将连续的虚拟内存块映射到非连续的物理帧。这样，未使用的内存碎片对于大型分配来说就不再是问题。
使用这样的页面分配器，可能有必要将块大小的上限提高到4KiB，并完全弃用链表分配器。这样的主要优点是减少了碎片并提高了性能可预测性，即在非理想情况下也能获取较好的性能。

要注意，上面提出的这些仅仅是改进建议。操作系统内核中使用的分配器通常会针对内核的特定工作负载进行高度优化，这只有通过广泛的性能分析才能实现。

其他分配器变体

固定大小的块分配器设计也有很多变体。slab分配器和伙伴分配器是两个流行的示例，它们也用在诸如Linux之类的流行内核中。下面，我们对这两种设计进行简短介绍。

Slab分配器

Slab分配器的思路是使用直接使用内核选定类型的大小作文的块大小。这样，对于这些类型的分配将恰好适合块大小，且不会浪费内存。有时，甚至有可能在未使用的块中预先初始化某些类型实例，以进一步提高性能。

Slab分配器通常与其他分配器结合使用。例如，它可以与固定大小的块分配器一起使用，以进一步拆分分配的块，从而减少内存浪费。此外，它还经常用于在单个大型分配时实现对象池模式。

伙伴分配器

伙伴分配器不是使用链表，而是使用二叉树来管理释放的块，同时配合使用2的幂作为块大小。当需要一定大小的新块时，它将一个较大的块分成两半，从而在树中创建两个子节点。每当释放一个块时，都会分析树中的邻居块。如果邻居也是空闲块，则将这两个块合并，重新成为双倍大小的块。

此合并过程的优点是减少了外部碎片，于是那些较小的释放块就可以重新用于较大的分配了。此外，它无需使用后备分配器，因此其性能更加可预测。它最大的缺点是只能使用2幂作为块大小，这可能会由于内部碎片而导致大量的内存浪费。因此，伙伴分配器通常与slab分配器一起使用，以将分配的块进一步拆分为多个较小的块。

小结

这篇文章概述了不同的分配器设计。我们学习了如何实现基本的线性分配器，它通过增加单个next指针来线性分配内存。虽然线性分配非常快，但是只有释放所有分配之后，它才能重新使用内存。因此，线性分配器很少用作全局分配器。

接下来，我们创建了一个链表分配器，该分配器使用释放的内存块本身来存放节点并组成链表，即所谓的空闲链表。该链表可以存储任意数量的大小不同的已释放块。尽管不会发生内存浪费，但是由于分配请求可能需要遍历整个列表，因此这种方法的性能很差。同时，我们的实现还遭受外部碎片的困扰，因为这个最小化的实现并不会将相邻的释放块重新合并在一起。

为了解决链表方法的性能问题，我们创建了一个固定大小的块分配器，该分配器预定义了一组固定的块大小。并为每个块大小设置一个单独的空闲链表，因此分配与释放只需要在相应列表的前端执行插入/取出，因此速度非常快。由于每个分配都向上取整到最接近的块大小，所以会因为内部碎片而浪费一些内存。

还有更多具有权衡不同取舍的分配器设计。Slab分配器可以为常见的固定大小的结构优化出更好地分配，但并非在所有情况下都适用。伙伴分配器使用二叉树将释放的块合并回去，但是可能会浪费大量内存，因为它仅支持的块大小只能为2的幂。重要的是要记住，每一个内核实现都有一个独特的工作量，因此并没有一个对所有情况都能保持“最佳”的分配器设计。

下期预告

目前，我就使用本文作为内存管理实现的尾声。接下来，我们将从线程开始探索对多任务的支持。在随后的文章中，我们将探讨多进程、进程、以及async/await形式的协作式多任务处理。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 3.3 - 内存堆分配

Thu, 01 Apr 2021 17:55:00 GMT

:::warning 本文所有内容均为翻译，原文：Heap Allocation；原项目：Writing an OS in Rust :::

本文将为内核添加对堆分配的支持。首先将介绍动态内存机制，并展示Rust借用检查器如何防止常见的分配错误。然后将实现Rust的基础分配器接口，创建一个堆内存区域，并编写一个分配器crate。在本文结束时，内核将能够支持Rust内置alloccrate中的所有分配和收集类型。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-10分支中找到。

局部变量和静态变量

当前，我们在内核中使用两种类型的变量：局部变量和static变量。局部变量存储在调用栈中，并且仅在其所在的函数返回之前有效。静态变量存储在固定的内存位置，并且在程序的整个生命周期中始终有效。

局部变量

局部变量存储在调用栈中，这是一个支持push和pop操作的栈数据结构。对于每个被调用的函数，编译器都将其参数、返回地址和局部变量压栈：

上图中的例子展示了outer函数调用了inner函数之后的调用栈。可以看到调用栈先是包含了outer函数的局部变量。在inner函数被调用时，参数1和返回地址被压栈。接下来控制权转给了inner函数，并继续将其局部变量压栈。

inner函数返回后，其位于调用栈中的相关部分弹栈，此时调用栈中仅剩下outer函数相关的局部变量：

我们看到inner的局部变量仅在函数返回之前有效。当我们持有变量时间过长时——比如尝试返回对局部变量的引用时——Rust编译器就会强行生命周期并引发编译错误：

fn inner(i: usize) -> &'static u32 {
    let z = [1, 2, 3];
    &z[i]
}

（使用play rust在线运行上面的代码）

虽然本例中返回引用并无意义，但在某些情况下，我们希望变量比其所在函数的生命周期更长。我们已经在编写内核的过程中遇到了这种情况，比如在尝试加载中断描述符表时就不得不使用static变量来延长其生命周期。

静态变量

静态变量存储在栈以外的固定内存位置中。此存储位置由链接器在编译时分配并编码在可执行文件中。静态变量在程序的完整运行时内始终有效，因此它们具有'static生命周期，并且始终可以被局部变量引用：

上图中的inner函数返回时，其在调用栈中的相关部分被析构。而静态变量位于一个独立的内存范围中，并不会被析构，因此&Z[1]的引用在函数返回后仍然有效。

除了'static生命周期以外，静态变量还有另一个有用的属性，即其内存位置在编译时就已确定，因此不需要引用就能够对其进行访问。我们利用该属性实现了println：通过在内部使用静态Writer，即便不使用&mut Writer引用也能够调用该宏。这在异常处理程序中非常有用，因为在其中我们无法访问任何其他变量。

但是，静态变量的这个属性也带来了一个致命缺点：它们默认是只读的。Rust强制此规则是为了避免数据竞争，比如当两个线程同时修改一个静态变量时。修改静态变量的唯一方法是将其封装在Mutex类型中，从而确保在任何时刻中仅存在一个&mut引用。我们已经将Mutex用于静态VGA缓冲区Writer。

动态内存

结合使用局部变量和静态变量已经能够实现非常强大的功能，足以应付大多数用例了。但是，它们仍然具有一定的局限性：

局部变量仅其所在的函数或块结束前有效。这是因为它们存在于调用栈中，并在上下文函数返回后被析构。
静态变量在程序的完整运行时内始终有效，因此无法在不再需要它们时回收和重用它们的内存。此外，它们的所有权语义不明确，且能够被任意函数访问，所以我们才会在需要修改时使用Mutex对其进行保护。

局部变量和静态变量的另一个局限性，就是它们的大小固定，因此，遇到需要添加更多元素的情况时，它们将无法存储这些动态增长的集合。（Rust中有一些关于unsized rvalues的提案，以允许局部变量具有动态大小，但它们仅在某些特定情况下有效。）

为了避开这些缺点，编程语言通常会提供第三块用于存放变量的内存区域，称为堆。堆使用两个叫做allocate和deallocate的函数在运行时动态内存分配。其工作方式为：allocate函数返回指定大小的可用内存块，用于存储变量。然后，该变量会一直有效，直到在其引用上调用deallocate函数将其释放为止。

让我们来看一个例子：

在这里，inner函数使用堆内存而不是静态变量来存储z。首先按照所需大小分配内存块，然后返回*mut u32裸指针。然后使用ptr::write方法写入数组[1,2,3]。最后使用offset函数计算指向第i个元素的指针，并将其返回。（请注意，为简洁起见，在此示例函数中，我们省略了一些必需的强制转换和unsafe块。）

分配的内存将会一直有效，直到通过调用dealloc显式释放为止。因此，即使在inner返回且其相关部分的调用栈被析构之后，返回的指针依然有效。与静态内存相比，使用堆内存的优势在于内存可以在释放后重用，这是通过outer的deallocate调用实现的。调用结束后的情形如下：

可以看到z[1]所在堆中的位置又空闲了，可以重新用于下一次allocate调用。但是，还可以看到z[0]和z[2]从未释放，因为我们从未释放过它们。这种错误称为内存泄漏，也通常是导致程序过度消耗内存的原因（试想一下，当我们在循环中重复调用inner时会发生什么）。这看起来很不好，然而动态分配可能会导致更多种危险的错误。

常见错误

内存泄漏虽然会导致过度消耗内存，但并不会使程序更容易受到攻击。除此之外，还有两种常见的错误类型，其后果更为严重：

当我们在调用deallocate后意外地继续使用变量时，便产生了一个称作释放后使用的漏洞。这种漏洞会导致未定义的行为，此外，攻击者也经常通过该漏洞来执行任意代码。
当我们不小心两次释放变量时，便产生了一个双重释放漏洞。这是有问题的，因为它这可能会释放第一次调用deallocate后在该位置重新分配的变量。因此，它可能再次导致释放后使用漏洞。

这些种类的漏洞是很常见的，看起来可以期望人们现在已经学会了如何规避它们。现实很遗憾，这些漏洞仍然经常出现，例如，近日Linux中出现的释放后使用漏洞允许执行任意代码。这也表明即使是最优秀的程序员也不一定总是能够正确处理复杂项目中的动态内存。

为了规避这些漏洞，许多语言——例如Java或Python——都使用称为垃圾回收的技术自动管理动态内存。其意图是使程序员不再需要手动调用deallocate，转而使程序定期暂停并扫描未使用的堆变量，然后将它们自动释放。于是，上述漏洞也就不会再出现了。不过，其缺点是常规扫描有一定的性能开销，以及暂停的时间可能会较长。

针对此问题Rust采用了不同的解决方案：它使用一种称为所有权的概念，能够在编译时检查动态内存操作的正确性。因此，Rust不需要垃圾收集也能避免上述漏洞，这意味着没有性能开销。该方案的另一个优点是，程序员仍然可以像使用C或C++一样对动态内存进行细粒度的控制。

Rust中的堆分配

Rust标准库提供了隐式调用allocate和deallocate抽象类型，省去程序员显示调用这些函数的麻烦。其中最重要的类型是Box，它是堆分配值的抽象。该类提供了构造函数Box::new，构造函数接受一个值并使用该值的大小调用allocate，再将该值移动到堆上新分配的空间中。为了能够释放堆内存，Box类型实现了Droptrait，以在变量离开作用域时调用deallocate：

{
    let z = Box::new([1,2,3]);
    […]
} // z离开作用域后，`deallocate`将被调用

此模式具有一个奇怪的名字——资源获取即初始化（或简称RAII）。它起源于C++，用于实现类似的抽象类型std::unique_ptr。

单靠这种类型不足以防止所有的释放后使用漏洞，因为在Box离开作用域并释放相应的堆内存空间之后，程序员仍然可以保留对其的引用：

let x = {
    let z = Box::new([1,2,3]);
    &z[1]
}; // z离开作用域后，`deallocate`将被调用
println!("{}", x);

而这便是Rust所有权机制大放异彩之处。所有权会为每个引用分配一个抽象的生命周期，就是该引用的有效的范围。在上例中，x引用来自于z数组，因此在z离开作用域后将变得无效。在线运行上例时，您将看到Rust编译器的确出现了编译错误：

error[E0597]: `z[_]` does not live long enough
 --> src/main.rs:4:9
  |
2 |     let x = {
  |         - borrow later stored here
3 |         let z = Box::new([1,2,3]);
4 |         &z[1]
  |         ^^^^^ borrowed value does not live long enough
5 |     }; // z goes out of scope and `deallocate` is called
  |     - `z[_]` dropped here while still borrowed

此时看这些术语可能会有些混乱。在Rust中，引用一个值称为借用值，因为它类似于现实生活中的借东西：你可以临时访问某个对象，但需要在某个时刻将其归还，而且一定不可以析构它。通过确保所有借用在其原对象被析构之前生命周期便已结束，Rust编译器可以保证不会发生释放后使用的情况。

Rust的所有权机制非常强大，不仅可以防止释放后使用的漏洞，而且能够像Java或Python这样的垃圾收集语言一样提供完整的内存安全。另外，它还能保证线程安全，因此其多线程代码比这些垃圾收集语言的更安全。最重要的是，所有这些检查都在编译时进行，因此与C语言中的手写内存管理相比一样没有运行时开销。

用例

现在我们知道了Rust中动态内存分配的基础知识，但是要在什么时候应该使用动态内存呢？我们的内核在没有动态内存分配情况下也已经走得很远了，那么为什么现在又需要动态内存呢？

不过，动态内存分配总是会带来一些性能开销，因为我们需要为每一个分配在堆上找到一个尚未使用的位置。因此，通常情况下尽可能使用局部变量，尤其是在对性能要求极高的内核代码中。但是，在某些情况下，动态内存分配才是最佳选择。

作为基本规则，具有动态生命周期或可变大小的变量需要动态内存。动态生命周期最重要的类型是Rc，它对其内部封装值的引用进行计数，并在所有引用均超出作用域后将内部封装值释放。具有可变大小的类型的示例包括Vec、String和其他集合类型，这些集合类型在添加更多元素时将会动态增长。这些类型的工作原理是，当集合装满时重新分配更大的内存，再将所有元素复制过来，最后取消旧的内存分配。

在内核中，我们非常需要集合类型，比如后文中在实现多任务处理时，用于存储活动任务的列表。

分配器接口

实现堆分配器的第一步是添加对内置alloc crate的依赖。像core crate一样，它也是标准库的子集，同时它还包含分配器和集合类型。要添加对alloc的依赖需要将以下内容添加到lib.rs中：

extern crate alloc;

与添加普通依赖不同，我们并不需要修改Cargo.toml。原因是alloccrate与Rust编译器一起作为标准库的一部分供我们使用，因此编译器已经知道了该crate。通过添加此extern crate语句，我们指定编译器去尝试包含该crate。（在以前的Rust中，所有依赖项都需要一个extern crate语句，不过现在该语句是可选的）。

由于我们正在为自定义目标系统进行编译，因此无法使用随Rust一起安装的alloc预编译版本。此处，我们必须告诉cargo用源码重新编译该crate。这可以通过将该crate添加到.cargo/config.toml文件中的unstable.build-std数组中来实现：

[unstable]
build-std = ["core", "compiler_builtins", "alloc"]

现在，编译器将重新编译alloc并其包括在内核中。

默认在#[no_std]的诸多crate中禁用alloccrate的原因是它还有其他要求。现在尝试编译项目时，我们可以看到这些要求引发的编译错误：

error: no global memory allocator found but one is required; link to std or add
       #[global_allocator] to a static item that implements the GlobalAlloc trait.

error: `#[alloc_error_handler]` function required, but not found

发生第一个错误是因为alloccrate需要堆分配器，以提供具有allocate和deallocate函数的对象。在Rust中，堆分配器GlobalAlloc trait，如错误消息所示。要为crate提供堆分配器，必须为实现GlobalAlloctrait的static变量添加#[global_allocator]属性。

发生第二个错误是因为调用allocate可能会失败，最常见的情况是在没有更多内存可用时。我们的程序必须能够对这种情况做出反应，这就是#[alloc_error_handler]函数的作用。

在下文的各小节中，我们将详细描述这些特征和属性。

`GlobalAlloc`trait

GlobalAlloctrait定义了堆分配器必须提供的函数。该特性非常特殊，通常程序员不会使用到。而当程序员使用alloc中的分配器和集合类型时，编译器将自动将调用适当的trait函数。

由于我们将需要为所有分配器类型实现该trait，因此有必要仔细研究其声明：

pub unsafe trait GlobalAlloc {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8;
    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout);

    unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { ... }
    unsafe fn realloc(
        &self,
        ptr: *mut u8,
        layout: Layout,
        new_size: usize
    ) -> *mut u8 { ... }
}

该trait定义了两个必须实现的方法alloc与dealloc，并与我们在示例中使用的allocate和deallocate函数相对应：

alloc方法将Layout实例作为参数，该实例描述了所分配的内存应具有的大小和对齐方式。该方法返回一个裸指针，并指向所分配内存块的第一个字节。当发生分配错误时，alloc方法返回一个空指针，而不是显式的错误值。虽然这有点不符合Rust的使用习惯，不过由于现有系统也使用相同的约定，所以其优点是可以很容易的封装现有的系统的分配器。
dealloc方法是分配的另一半，它负责释放内存块。该方法接收两个参数，即alloc返回的指针和分配时用的Layout。

该trait还使额外定义了两个带有默认实现的方法alloc_zeroed和realloc：

alloc_zeroed方法等效于先调用alloc再将分配的内存块全部置为零，正如其默认实现中所做的那样。如果自定义实现比默认实现更高效的话，也可以使用它来覆盖默认实现。
realloc方法允许增加或减少分配空间。默认实现会分配一个所需大小的新内存块，并会将先前分配中的所有内容复制进来。与上一个方法相同，自定义的分配器实现也可能会提供此一个更高效的实现，比如实现就地扩展/缩小原分配。

非安全特性

需要注意的是，trait本身的所有方法都被声明为unsafe：

将该trait声明为unsafe的原因是，程序员必须保证分配器类型的trait实现是正确的。例如，alloc方法绝不能返回已在其他地方使用的内存块，因为这将导致未定义的行为。
同样，其方法均为unsafe的原因是，调用者在调用方法时必须确保各种不变性，例如，传递给alloc的Layout实例指定的大小应是非零的。不过在实践中这并不重要，因为方法通常是由编译器直接调用的，可以确保满足要求。

编写一个`DummyAllocator`

既然已经知道了要为分配器类型提供什么，我们就可以实现一个简单的假分配器。首先创建一个新的分配器模块：

pub mod allocator;

我们的假分配器将实现特征的最低要求，即在调用alloc时始终返回错误。看起来像这样：

use alloc::alloc::{GlobalAlloc, Layout};
use core::ptr::null_mut;

pub struct Dummy;

unsafe impl GlobalAlloc for Dummy {
    unsafe fn alloc(&self, _layout: Layout) -> *mut u8 {
        null_mut()
    }

    unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {
        panic!("dealloc should be never called")
    }
}

该结构体不需要任何字段，于是我们将其创建为零大小类型。就像描述的那样，我们总是用alloc返回空指针，这正对应了分配错误。由于分配器从不返回任何内存，所以永远不应该调用dealloc。因此，我们仅在dealloc中panic即可。alloc_zeroed和realloc方法具有默认实现，因此无需为其提供实现。

这就实现了一个简单的分配器，但是我们仍然需要告诉Rust编译器它应该使用这个分配器。这就需要用到#[global_allocator]属性了。

`#[global_allocator]`属性

#[global_allocator]将属性告诉Rust编译器应该使用哪个分配器实例作为全局堆分配器。该属性仅适用于实现了GlobalAlloc特性的static对象。让我们将分配器Dummy的一个实例注册为全局分配器：

#[global_allocator]
static ALLOCATOR: Dummy = Dummy;

由于Dummy分配器是零大小类型，因此我们不需要在初始化表达式中指定任何字段。

现在尝试编译，第一个错误消失了。让我们继续修复第二个错误：

error: `#[alloc_error_handler]` function required, but not found

`#[alloc_error_handler]`属性

正如我们在讨论GlobalAlloctrait时所了解的那样，alloc函数可以通过返回空指针来表示分配错误。那么Rust在运行时应如何应对这种分配失败呢？这就是#[alloc_error_handler]属性起作用的地方了。该属性将指定发生分配错误时调用的处理函数，类似于在发生panic时调用panic处理程序。

我们来添加一个这样的函数以修复该编译错误：

#![feature(alloc_error_handler)] // 需要写在源文件开头

#[alloc_error_handler]
fn alloc_error_handler(layout: alloc::alloc::Layout) -> ! {
    panic!("allocation error: {:?}", layout)
}

alloc_error_handler函数仍然不稳定，因此我们需要一个特性门来启用它。该函数接收一个参数，即发生分配错误时传递给alloc的Layout实例。我们无法纠正该错误，因此仅在处理函数中进行panic并打印关于Layout实例的信息。

应用该函数就可以修复编译错误。现在我们可以使用alloc的分配器和集合类型了，例如，我们可以使用Box在堆上分配一个值：

extern crate alloc;

use alloc::boxed::Box;

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // […] print "Hello World!", call `init`, create `mapper` and `frame_allocator`

    let x = Box::new(41);

    // […] call `test_main` in test mode

    println!("It did not crash!");
    blog_os::hlt_loop();
}

注意，我们也需要在main.rs中指定extern crate alloc语句。这是必需的，因为lib.rs和main.rs部分被视为各自独立的crate。但是，我们不需要创建另一个#[global_allocator]静态变量，因为全局分配器适用于项目中的所有crate。实际上，在另一个crate中指定其他分配器将引发错误。

运行上面的代码，我们将看到alloc_error_handler函数被调用：

错误处理程序被调用是因为Box::new函数隐式调用了全局分配器的alloc函数。因为假分配器始终返回空指针，所以每次分配都将会失败。为了解决这个问题，我们需要创建一个真分配器，用以返回可以使用的内存。

创建内核堆

在创建适当的分配器之前，我们首先需要创建一个堆内存区域，使得分配器可以从该区域分配内存。为此，我们需要为堆区域定义一个虚拟内存范围，然后将该区域映射到物理帧上。有关虚拟内存和页表的介绍，请参见“内存分页简介”一文。

第一步是为堆定义虚拟内存区域。我们可以选择我们喜欢的任何虚拟地址范围，只要它尚未用于其他内存区域即可。让我们将其定义为从地址0x_4444_4444_0000开始的内存，以便未来可以轻松识别堆指针：

pub const HEAP_START: usize = 0x_4444_4444_0000;
pub const HEAP_SIZE: usize = 100 * 1024; // 100 KiB

目前将堆大小设置为100 KiB。如果将来我们需要更多空间，将该值改大即可。

如果我们现在尝试使用此堆区域，就会发生页面错误，因为虚拟内存区域尚未映射到物理内存。为了解决这个问题，我们创建init_heap函数并使用在“内存分页实现”一文中介绍的Mapper API映射堆页面：

use x86_64::{
    structures::paging::{
        mapper::MapToError, FrameAllocator, Mapper, Page, PageTableFlags, Size4KiB,
    },
    VirtAddr,
};

pub fn init_heap(
    mapper: &mut impl Mapper<Size4KiB>,
    frame_allocator: &mut impl FrameAllocator<Size4KiB>,
) -> Result<(), MapToError<Size4KiB>> {
    let page_range = {
        let heap_start = VirtAddr::new(HEAP_START as u64);
        let heap_end = heap_start + HEAP_SIZE - 1u64;
        let heap_start_page = Page::containing_address(heap_start);
        let heap_end_page = Page::containing_address(heap_end);
        Page::range_inclusive(heap_start_page, heap_end_page)
    };

    for page in page_range {
        let frame = frame_allocator
            .allocate_frame()
            .ok_or(MapToError::FrameAllocationFailed)?;
        let flags = PageTableFlags::PRESENT | PageTableFlags::WRITABLE;
        unsafe {
            mapper.map_to(page, frame, flags, frame_allocator)?.flush()
        };
    }

    Ok(())
}

该函数接受Mapper和FrameAllocator实例的可变引用作为参数，这两个实例均使用Size4KiB作为泛型参数指定页面大小为4KiB。该函数的返回值为Result，以单位类型()作为成功结果，以MapToError作为失败结果，该失败结果是由Mapper::map_to方法返回的错误类型。之所以在此处复用了该错误类型是因为map_to方法是此函数中错误的主要来源。

实现可以分为两部分：

创建页面范围：首先需要将HEAP_START指针转换为VirtAddr类型。然后用起始地址加上HEAP_SIZE计算出堆结束地址。我们想要一个闭区间（堆的最后一个字节的地址），故而减1。接下来使用containing_address函数将这些地址转换为Page类型。最后使用Page::range_inclusive函数创建从起始页面到结束页面的页面范围。
映射页面：第二步是映射刚刚创建的页面范围内的所有页面。为此，我们使用for循环遍历该范围内的页面。我们为每个页面执行以下操作：
- 使用FrameAllocator::allocate_frame方法将页面应映射到分配的物理帧上。当没有额外的帧时，该方法将返回None。遇到没有额外帧的情况时，我们使用Option::ok_or方法将错误映射到MapToError::FrameAllocationFailed，然后接问号运算符以在出错时提前返回。
- 为页面设置了必要的PRESENT和WRITABLE标志，以允许读取和写入访问，这对于堆内存是有实际意义的。
- 使用Mapper::map_to方法在活动页面表中创建映射。该方法可能会失败，因此我们再次使用问号运算符将错误传播给调用方。若成功，该方法将返回一个MapperFlush实例，然后使用该实例使用flush方法来更新转换后备缓冲区。

最后一步是从kernel_main中调用此函数：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    use blog_os::allocator; // new import
    use blog_os::memory::{self, BootInfoFrameAllocator};

    println!("Hello World{}", "!");
    blog_os::init();

    let phys_mem_offset = VirtAddr::new(boot_info.physical_memory_offset);
    let mut mapper = unsafe { memory::init(phys_mem_offset) };
    let mut frame_allocator = unsafe {
        BootInfoFrameAllocator::init(&boot_info.memory_map)
    };

    // new
    allocator::init_heap(&mut mapper, &mut frame_allocator)
        .expect("heap initialization failed");

    let x = Box::new(41);

    // […] call `test_main` in test mode

    println!("It did not crash!");
    blog_os::hlt_loop();
}

上面的代码显示了函数完整的上下文。这里仅有的新增行是blog_os::allocator的导入和allocator::init_heap函数的调用。如果init_heap函数返回错误，我们将使用Result::expect方法产生panic，因为目前还没有适当的处理此错误的方法。

现在，我们有一个准备使用的映射堆内存区域。但是Box::new调用仍然使用旧的Dummy分配器，因此如果此时运行仍会看到“内存不足”错误。让我们通过使用适当的分配器来解决此问题。

使用分配器crate

鉴于实现分配器较为复杂，我们先临时使用已有的分配器crate。在下一篇文章中，我们将学习如何实现自己的分配器。

对于no_std的应用程序，linked_list_allocator crate是一个简单的分配器实现。之所以叫这个名字，是因为该crate使用链表数据结构来跟踪释放的内存区域。有关该实现的详情参见下一篇文章。

要使用该crate，首先需要在Cargo.toml中添加其依赖：

[dependencies]
linked_list_allocator = "0.8.0"

然后便可以使用该crate提供的分配器代替我们的假分配器了：

use linked_list_allocator::LockedHeap;

#[global_allocator]
static ALLOCATOR: LockedHeap = LockedHeap::empty();

该结构体叫做LockedHeap，是因为它使用spining_top::Spinlock类型进行同步。这是必需的，因为多个线程可以同时访问ALLOCATOR静态对象。一如往常，在使用自旋锁或互斥锁时，我们需要注意不要意外引发死锁。这意味着我们不应该在中断处理程序中执行任何分配，因为它们可以在任意时间运行，并且可能会中断正在进行的分配。

仅将LockedHeap设置为全局分配器是不够的。原因是我们使用了构造函数empty，创建了一个没有任何后备内存的分配器。就像我们的假分配器一样，它总是在alloc时返回错误。为了解决这个问题，我们需要在创建堆之后初始化分配器：

pub fn init_heap(
    mapper: &mut impl Mapper<Size4KiB>,
    frame_allocator: &mut impl FrameAllocator<Size4KiB>,
) -> Result<(), MapToError<Size4KiB>> {
    // […] map all heap pages to physical frames

    // new
    unsafe {
        ALLOCATOR.lock().init(HEAP_START, HEAP_SIZE);
    }

    Ok(())
}

我们在LockedHeap类型的内部自旋锁上使用lock方法来获取对封装后的Heap实例的排他引用，然后在该实例上调用以堆边界为参数的init方法。重要的是，我们在映射堆页面之后才初始化堆，因为init函数已经在尝试写入堆内存了。

初始化堆之后就可以使用内置alloccrate的所有分配和收集类型，而且并不会出现错误：

use alloc::{boxed::Box, vec, vec::Vec, rc::Rc};

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // […] initialize interrupts, mapper, frame_allocator, heap

    // allocate a number on the heap
    let heap_value = Box::new(41);
    println!("heap_value at {:p}", heap_value);

    // create a dynamically sized vector
    let mut vec = Vec::new();
    for i in 0..500 {
        vec.push(i);
    }
    println!("vec at {:p}", vec.as_slice());

    // create a reference counted vector -> will be freed when count reaches 0
    let reference_counted = Rc::new(vec![1, 2, 3]);
    let cloned_reference = reference_counted.clone();
    println!("current reference count is {}", Rc::strong_count(&cloned_reference));
    core::mem::drop(reference_counted);
    println!("reference count is {} now", Rc::strong_count(&cloned_reference));

    // […] call `test_main` in test context
    println!("It did not crash!");
    blog_os::hlt_loop();
}

代码展示了Box、Vec和Rc类型的部分使用。对于Box和Vec类型，我们使用{:p}格式说明符来打印底层堆指针。为了展示Rc，我们创建一个引用计数的堆值，并在删除实例（使用core::mem::drop）前后分别使用Rc::strong_count函数两次打印引用计数。

运行将会看到以下内容：

不出所料，我们看到Box和Vec值存在于堆中，正如以0x_4444_4444_*为前缀的指针所指示。引用计数值也可以按预期方式运行，调用clone后，引用计数为2，在删除其中一个实例后，引用计数变为1。

向量从偏移量0x800开始的原因并不是Box类型的值大小为0x800字节，而是因为向量需要扩充容量时发生了再分配。例如，当向量的容量为32且我们尝试添加下一个元素时，向量将在后台分配一个容量为64的新后备数组，并将所有元素复制到到新数组，然后再释放掉旧分配。

当然，我们还有很多alloccrate中的其他分配器和集合类型可以在内核中使用，包括：

线程安全引用计数指针Arc
Rust的字符串类型String和format!格式化宏
链表LinkedList
可增长的环形缓冲区VecDeque
优先级队列BinaryHeap
BTreeMap和BTreeSet

当我们要实现线程列表、调度队列、或async/await支持时，这些类型将会非常有用。

添加测试

为了确保新的分配器代码不会被意外破坏，我们应该为其添加一个集成测试。首先创建一个新的tests/heap_allocation.rs文件，其内容如下：

#![no_std]
#![no_main]
#![feature(custom_test_frameworks)]
#![test_runner(blog_os::test_runner)]
#![reexport_test_harness_main = "test_main"]

extern crate alloc;

use bootloader::{entry_point, BootInfo};
use core::panic::PanicInfo;

entry_point!(main);

fn main(boot_info: &'static BootInfo) -> ! {
    unimplemented!();
}

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    blog_os::test_panic_handler(info)
}

我们重用了lib.rs中的test_runner和test_panic_handler函数。由于我们要测试分配器，所以需要使用extern crate alloc语句启用alloccrate。有关测试样板的更多信息，请查看前面的测试一文。

main函数的实现如下所示：

fn main(boot_info: &'static BootInfo) -> ! {
    use blog_os::allocator;
    use blog_os::memory::{self, BootInfoFrameAllocator};
    use x86_64::VirtAddr;

    blog_os::init();
    let phys_mem_offset = VirtAddr::new(boot_info.physical_memory_offset);
    let mut mapper = unsafe { memory::init(phys_mem_offset) };
    let mut frame_allocator = unsafe {
        BootInfoFrameAllocator::init(&boot_info.memory_map)
    };
    allocator::init_heap(&mut mapper, &mut frame_allocator)
        .expect("heap initialization failed");

    test_main();
    loop {}
}

它与main.rs中的kernel_main函数非常相似，不同之处在于我们不调用println，不包括任何分配示例，并且无条件调用test_main。

现在我们准备添加一些测试用例。首先，我们添加一个测试，以使用Box执行一些简单的分配并检查分配的值，以确保基本分配有效：

use alloc::boxed::Box;

#[test_case]
fn simple_allocation() {
    let heap_value_1 = Box::new(41);
    let heap_value_2 = Box::new(13);
    assert_eq!(*heap_value_1, 41);
    assert_eq!(*heap_value_2, 13);
}

最重要的是，此测试可验证是否发生分配错误。

接下来，我们循环新建一个大型向量，以测试大型分配和多重分配（以测试再分配）：

use alloc::vec::Vec;

#[test_case]
fn large_vec() {
    let n = 1000;
    let mut vec = Vec::new();
    for i in 0..n {
        vec.push(i);
    }
    assert_eq!(vec.iter().sum::<u64>(), (n - 1) * n / 2);
}

我们通过与求和公式进行比较来验证向量求和。这使我们确信分配的值都是正确的。

作为第三项测试，我们在执行一万次分配：

use blog_os::allocator::HEAP_SIZE;

#[test_case]
fn many_boxes() {
    for i in 0..HEAP_SIZE {
        let x = Box::new(i);
        assert_eq!(*x, i);
    }
}

此测试确保分配器将释放的内存重新用于后续分配，否则分配器将耗尽内存。这似乎是对分配器的基本要求，但是有些分配器设计并没有这样做。一个示例是线性分配器，我们将在下一篇文章中进行解释。

运行新的集成测试：

> cargo test --test heap_allocation
[…]
Running 3 tests
simple_allocation... [ok]
large_vec... [ok]
many_boxes... [ok]

三个测试全部通过！你还可以调用cargo test（不使用--test参数）来运行所有单元测试和集成测试。

小结

在这篇文章中，我们了解了动态内存的概念、为什么要使用动态内存以及需要在什么地方使用动态内存。我们了解了Rust的借用检查器如何防止常见漏洞，以及Rust分配器API的工作方式。

在使用假分配器创建了Rust分配器接口的最小化实现之后，我们为内核创建了一个适当的堆内存区域。为此，我们为堆定义了一个虚拟地址范围，然后使用上一篇文章中的Mapper和FrameAllocator将地址范围中的所有页面映射到物理帧。

最后，我们添加了对linked_list_allocatorcrate的依赖，以在内核中应用已有的分配器实现。利用此分配器，我们能够使用Box、Vec以及alloc crate中的其他分配器和集合类型。

下期预告

虽然我们已经在本文中添加了堆分配支持，但也将大部分工作留给了现成的linked_list_allocatorcrate。下一篇文章将详细展示如何从头开始实现分配器，并将介绍多种可能的分配器设计，展示如何实现它们的简单版本，并阐述它们的优缺点。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 3.2 - 内存分页实现

Fri, 26 Mar 2021 17:44:00 GMT

:::warning 本文所有内容均为翻译，原文：Paging Implementation；原项目：Writing an OS in Rust :::

本文将展示如何在内核中实现对内存分页的支持。我们首先将探讨使内核可以访问物理页表帧的各种技术，并讨论它们各自的优缺点。然后，实现地址转换函数和创建新映射函数。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-09分支中找到。

介绍

上一篇文章介绍了分页的概念，通过与分段进行比较来引入分页，解释了分页和页表的工作原理，然后介绍了x86_64的4级页表设计。我们发现bootloader已经为内核设置了页表层次结构，这意味着我们的内核已经在虚拟地址上运行。这有助于提高安全性，因为非法内存访问并不能修改任意物理内存，只会导致页面错误异常。

前文结尾我们留下一个问题——无法从内核访问页表——这是因为页表存储在物理内存中，而内核已经运行在虚拟地址上。本文将在这一点上深入，探讨使内核能够访问页表帧的不同方法。我们将讨论每种方法的优缺点，然后为内核确定一种适合的方法。

要实现该方法，首先，我们将需要bootloader的支持，因此需要对其进行配置。然后，我们将实现一个遍历页表层次结构的函数，以将虚拟地址转换为物理地址。最后，我们将学习如何在页表中创建新的映射，以及如何找到未使用的内存帧来创建新的页表。

访问页表的方法

从内核访问页表并不像看起来那样简单。为理解这个问题，让我们回顾前文的示例，4级页表层次结构：

这里的关键是每个页表条目都会存储下一张表的物理地址。这样做既避免了对这些地址再进行转换——会对性能造成不利影响——也避免了地址转换陷入无限递归。

对我们来说，问题在于无法直接通过内核访问物理地址，因为内核仍运行在虚拟地址上。例如，当我们访问地址4 KiB时，我们访问的是虚拟地址4 KiB，而不是存储第4级页表的物理地址4 KiB。当我们要访问物理地址4KiB时，我们只能通过映射到它的某个虚拟地址来进行访问。

因此，为了访问页表帧，我们需要将一些虚拟页映射到这些帧上。创建映射的方法有很多，而这些方法都允许我们访问任意页表帧。

恒等映射

一个简单的解决方案是对所有页表进行恒等映射：

在上图中，我们看到了很多恒等映射的页面表帧。如此，页表的物理地址也同时是有效的虚拟地址，我们因此可以轻松地从CR3寄存器开始访问到所有级别的页表。

但是，它会使虚拟地址空间变得混乱，并使得找到更大尺寸的连续存储区域变得更加困难。例如，假设我们要在上图中创建一个大小为1000KiB的虚拟内存区域，比如用于内存映射文件。我们无法从28KiB开始该区域，因为它会与已经映射的页面1004KiB发生冲突。因此，我们必须进一步寻找，直到找到足够大的连续未映射区域，例如1008KiB。这是与分段类似的碎片问题。

同样，这会使得创建新的页表变得更加困难，因为我们需要为新表找到大小相称且尚未使用的物理帧。例如，假设我们为内存映射文件保留了从1008KiB开始的1000KiB虚拟内存区域，于是便不能再使用物理地址在1000KiB和2008KiB之间的任何帧，因为无法对其进行恒等映射。

固定偏移量映射

为了避免使虚拟地址空间变的混乱，我们可以为页表映射划分单独的内存区域。因此，我们不再恒等映射页表帧，而将页表帧以固定偏移量映射到虚拟地址空间中。例如，偏移量可以是10 TiB：

通过将10TiB..(10TiB+物理内存大小)范围内的虚拟内存地址专门用于页表映射，我们避免了恒等映射的冲突问题。只有在虚拟地址空间寻址空间远大于物理内存大小时，才可以为虚拟地址空间保留如此巨大的区域。不过这个大小在x86_64上很容易达到，因为48位虚拟地址地址的寻址空间为256TiB。

该方法仍然有一个缺点，就是每当我们创建一个新的页表时，都需要创建一个新的映射。另外，该方法不允许访问其他地址空间的页表，这在创建新进程时很有用。

完整物理内存映射

要来解决这些问题，我们不再仅映射页表帧，而是映射完整物理内存：

这种方法允许内核访问任意物理内存，包括其他地址空间的页表帧。保留的虚拟内存范围与以上一节相同，不同之处在于虚拟内存不再包含未映射的页面（译注：即虚拟内存空间将全部映射到物理帧）。

这种方法的缺点是需要额外的页表来存储物理内存的映射。这些页表需要存储在某个地方，因此它们会用掉一部分物理内存，这在内存较小的设备上可能是个问题。

不过，在x86_64上我们可以使用2MiB的巨页进行映射，而不是默认的4KiB页面。这样，映射32GiB内存，仅需要1个3级表和32个2级表（译注：一个2级表包含512个2MiB的巨页条目，即一个2级表可映射1GiB）总共132KiB的空间用于存储页表（译注：每页表512条目，每条目占8B空间，即每页表占4KiB空间，一共占(1+32)*4KiB=132KiB）。而且巨页还可以提升缓存效率，因为巨页在转换后备缓冲区（TLB）中使用的条目更少。

临时映射

对于物理内存量很小的设备，我们只能在需要访问时才临时映射页表帧。为了能够创建临时映射，我们只需要一个恒等映射的1级页表：

图中的1级表控制虚拟地址空间的前2MiB（译注：512个大小为4KiB的虚拟页面）。这是因为它可以通过从CR3寄存器开始并跟随4级、3级和2级页表中的第0个条目来访问。索引为8的条目将地址32KiB上的虚拟页映射到地址32KiB上的物理帧，也就是恒等映射了1级表本身。图中使用32KiB处的水平箭头表明了此恒等映射。

通过写入恒等映射的1级表，我们的内核最多可以创建511个临时映射（512减去恒等映射所需的条目）。在上面的示例中，内核创建了两个临时映射：

将1级表的第0个条目映射到地址为24KiB的帧，便创建了一个虚拟的临时映射，将0KiB处的虚拟页映射到2级页表所在的物理帧，如虚线箭头所示。
将1级表的第9个条目映射到地址为4KiB的帧，便创建了一个虚拟的临时映射，将36KiB处的虚拟页映射到4级页表所在的物理帧，如虚线箭头所示。

现在，内核可以通过写入0KiB页面来访问第2级页表，以及通过写入36KiB页面来访问第4级页表。

使用临时映射访问任意页表帧的过程为：

在恒等映射的1级表中搜索未使用条目。
将该条目映射到我们想要访问的页表所在的物理帧。
通过映射到该条目的虚拟页面访问目标帧。
将该条目设置回未使用状态，从而删除本次临时映射。

这种方法重复使用相同的512个虚拟页面来创建映射，因此仅需要4KiB的物理内存。缺点是它有点麻烦，特别是因为新的映射可能需要修改多个级别的页表，这意味着我们需要将上述过程重复多次。

递归页表

另一个根本不需要附加页表的有趣方法是递归映射页表。这种方法的思路是将4级页表的某些条目映射到4级表本身。如此可以有效地保留一部分虚拟地址空间，并将所有当前和将来的页表帧映射到该空间。

让我们通过一个例子来理解该方法是如何工作的：

这与本文开头示例的唯一区别是，4级表中索引511处的附加条目映射到了4级表本身的4KiB物理帧。

通过让CPU在转换中跟踪此条目，它不会到达3级表，而又回到这一4级表。这类似于调用自身的递归函数，因此此表称为递归页表。重要的是，CPU假定4级表中的每个条目都指向3级表，因此现在将4级表视为3级表。这之所以可行，是因为所有级别的表在x86_64上的布局都完全相同。

通过在开始实际转换之前访问一次或多次递归项，我们可以有效地减少CPU遍历的级别数。例如，如果我们只访问一次递归条目，然后进入3级表，则CPU会认为3级表是2级表。更进一步，它将2级表视为1级表，将1级表视为映射的帧。这意味着我们现在可以读写1级页表，因为CPU认为它是映射的帧。下图说明了5个翻译步骤：

类似的，在开始转换之前，我们可以两次访问递归项，以将遍历的级别数减少为两个：

让我们逐步观察改操作：首先，CPU访问4级表上的递归条目，并认为自己已到达3级表。然后，它再次访问递归条目，并认为自己已到达2级表。但实际上，CPU仍然位于4级表中。当CPU现在访问另一个条目时，它将进入在3级表，但认为自己已经在1级表上了。因此，当下一个条目指向2级表时，CPU认为它指向映射的帧，这使我们可以读写2级表。

访问3级和4级表的工作方式相同。为了访问3级表，我们重复访问了3次递归项，使CPU认为它已经在1级表中了。然后，我们访问另一个条目并到达第3级表，CPU将其视为映射帧。要访问4级表本身，我们只需访问递归项四次，直到CPU将4级表本身视为映射帧（下图中的蓝色）。

你可能需要花一些时间来理解这个思路，但是在实践中却非常有效。

在下面的小节中，我们将解释如何构造虚拟地址以一次或多次访问递归项。我们不会在实现中使用递归分页，因此你可以跳过这一节继续阅读后文。

计算地址（选读）

可以看到在实际地址转换前通过一次或多次递归地访问条目来访问所有级别的页表。由于访问这四个级别的表的索引是直接从虚拟地址中派生的，因此我们需要为此方法构造特殊的虚拟地址。请记住，页表索引是通过以下方式从虚拟地址中派生的：

假设我们要访问映射特定页面的1级页表。如上所述，这意味着在继续执行4级，3级和2级索引之前，我们必须访问一次递归项。为此，我们将地址的每个块向右移动一个块，并将原始4级索引设置为递归索引：

为了访问2级表，我们将每个索引块向右移动两个块，并将原始4级索引和原始3级索引的块都设置为递归索引：

通过将每个块向右移动三个块并对原始4级，3级和2级地址块使用递归索引，便可以访问3级页表：

最后，我们可以通过将每个块向右移动四个块并使用除偏移量以外的所有地址块作为递归索引来访问4级表：

现在就可以计算全部四个级别的页表的虚拟地址了。我们甚至可以通过将其索引乘以8（页面表条目的大小）来计算精确指向特定页面表条目的地址。

下表总结了用于访问不同级别页表帧的地址结构：

用于访问	虚拟地址结构(八进制)
页	`0o_SSSSSS_AAA_BBB_CCC_DDD_EEEE`
1级页表项	`0o_SSSSSS_RRR_AAA_BBB_CCC_DDDD`
2级页表项	`0o_SSSSSS_RRR_RRR_AAA_BBB_CCCC`
3级页表项	`0o_SSSSSS_RRR_RRR_RRR_AAA_BBBB`
4级页表项	`0o_SSSSSS_RRR_RRR_RRR_RRR_AAAA`

其中AAA是4级索引，BBB是3级索引，CCC是2级索引，DDD是映射帧的1级索引，而EEEE是映射帧的偏移量。RRR是递归条目的索引。当索引（三位数，译注：9位二进制数转换为3位八进制数）转换为偏移量（四位数，译注：12位二进制偏移地址转换为4位八进制数）时，可以通过将其乘以8（页表项的大小，译注：八进制下乘八相当于左移一位）来完成。有了这样的偏移量，结果地址就直接指向相应的页表条目。

SSSSSS是符号扩展位，这意味着它们都是第47位的副本。这是对x86_64架构上有效地址的特殊要求。我们在上一篇文章中对此进行了解释。

之所以使用八进制表示地址，是因为每个八进制字符表示三个位，这使我们可以清楚地区分不同页表级别的9位索引。对于每个字符代表四个位的十六进制来说是不可能的。

用Rust代码实现

要在Rust代码中构造这样的地址，可以使用位运算：

// 希望访问的指定页表的虚拟地址
let addr: usize = […];

let r = 0o777; // 递归索引
let sign = 0o177777 << 48; // 符号扩展位

// 计算希望转换的页表索引
let l4_idx = (addr >> 39) & 0o777; // 4级索引
let l3_idx = (addr >> 30) & 0o777; // 3级索引
let l2_idx = (addr >> 21) & 0o777; // 2级索引
let l1_idx = (addr >> 12) & 0o777; // 1级索引
let page_offset = addr & 0o7777;

// 计算页表地址
let level_4_table_addr =
    sign | (r << 39) | (r << 30) | (r << 21) | (r << 12);
let level_3_table_addr =
    sign | (r << 39) | (r << 30) | (r << 21) | (l4_idx << 12);
let level_2_table_addr =
    sign | (r << 39) | (r << 30) | (l4_idx << 21) | (l3_idx << 12);
let level_1_table_addr =
    sign | (r << 39) | (l4_idx << 30) | (l3_idx << 21) | (l2_idx << 12);

上面的代码假定递归映射条目的索引为0o777，即最后一个4级条目511。不过目前情况并非如此，因此代码尚无法工作。请参阅下文，了解如何告诉bootloader设置递归映射。

除了手动执行按位运算之外，还可以使用x86_64crate的RecursivePageTable类型，该类型为各种页表操作提供安全的抽象。例如，以下代码展示了如何将虚拟地址转换为其映射的物理地址：

use x86_64::structures::paging::{Mapper, Page, PageTable, RecursivePageTable};
use x86_64::{VirtAddr, PhysAddr};

/// 为4级页表创建`RecursivePageTable`实例
let level_4_table_addr = […];
let level_4_table_ptr = level_4_table_addr as *mut PageTable;
let recursive_page_table = unsafe {
    let level_4_table = &mut *level_4_table_ptr;
    RecursivePageTable::new(level_4_table).unwrap();
}

/// 为给出的虚拟地址计算物理地址
let addr: u64 = […]
let addr = VirtAddr::new(addr);
let page: Page = Page::containing_address(addr);

// 实现转换
let frame = recursive_page_table.translate_page(page);
frame.map(|frame| frame.start_address() + u64::from(addr.page_offset()))

与上一段代码相同，运行此代码需要有效的递归映射。使用这种映射，可以像上一个代码示例中那样计算给定的level_4_table_addr。

递归分页是一种有趣的技术，也展示了页表中的单个映射功能有多强大。它相对容易实现，只需要极少的设置（即设置一个递归项），因此它作为我们的第一个分页实验确实是一个不错选择。

不过，它也有一些缺点：

该方法会占用大量虚拟内存空间（512GiB，译注：即占用4级页表一个条目）。不过48位虚拟地址空间较大，这也不算是一个大问题，但这可能会导致次优的缓存行为。
该方法仅允许轻松访问当前活动的地址空间。通过更改递归项，仍然可以访问其他地址空间，但是需要临时映射才能切换回去。我们在重新映射内核（已过时）一文中描述了如何执行此操作。
该方法在很大程度上依赖于x86的页表格式，可能无法在其他架构中使用。

Bootloader支持

所有这些方法在初始化时都需要对其页表进行修改。例如，需要创建物理内存的映射，或者需要递归映射4级表的条目。目前的问题是我们还没有能够访问页表的方法，因此也无法创建这些必要的的映射。

这意味着我们需要bootloader的帮助，该程序会创建内核运行的页表。bootloader可以访问页表，因此它可以创建我们需要的任何映射。在当前的实现中，bootloadercrate支持上面提到的两种方法，并可以通过cargo功能进行控制：

map_physical_memory特性可以将整个物理内存映射到虚拟地址空间中的某处。因此，内核可以访问所有物理内存，于是我们可以实现映射完整物理内存中的方法。
使用recursive_page_table特性，bootloader将递归映射4级页表的一个条目。这允许内核按照递归页表部分中的描述访问页面表。

我们为内核选择第一种方法，因为它简单，平台独立且功能更强大（还允许访问非页表帧）。为了启用所需的bootloader支持，我们将map_physical_memory特性添加到了bootloader的依赖项中：

[dependencies]
bootloader = { version = "0.9.8", features = ["map_physical_memory"]}

启用此特性后，bootloader会将完整的物理内存映射到一些未使用的虚拟地址范围。为了将希望使用的虚拟地址范围告诉内核，引导加载程序会传递一个引导信息结构体。

引导信息

bootloadercrate定义了一个BootInfo结构体，包含传递给内核的所有信息。该结构体仍处于早期阶段，因此在更新为将来与语义版本不兼容的bootloader版本时，可能会造成损坏。启用map_physical_memory特性后，它将包含memory_map和physical_memory_offset两个字段：

memory_map字段包含可用物理内存的概述。该字段告诉内核系统中有多少可用物理内存，以及哪些内存区域是为诸如VGA硬件之类的设备所保留的。可以从BIOS或UEFI固件查询内存映射，但查询只能在启动过程的早期。也正是由于这个原因，内存映射必须由bootloader提供，因为内核无法在之后检索该映射。在下文中，我们将需要内存映射。
physical_memory_offset字段包含物理内存映射到虚拟地址的起始地址。通过将此偏移量添加到物理地址，即可获得相应的虚拟地址。这使我们可以从内核访问任意物理内存。

bootloader将BootInfo结构体以_start函数的＆'static BootInfo参数的形式传递给内核。我们尚未在该函数中声明此参数，按照下面的方式修改：

use bootloader::BootInfo;

#[no_mangle]
pub extern "C" fn _start(boot_info: &'static BootInfo) -> ! { // new argument
    […]
}

在前面的文章中，我们一直都缺少该参数也并没有造成什么问题，因为x86_64调用约定在CPU寄存器中传递了第一个参数。因此，若不声明该参数，只会使得参数被忽略。但是，如果我们不小心使用了错误的参数类型，那将会造成问题，因为编译器并不知道我们入口点函数的正确类型签名。

`entry_point`宏

由于_start函数是从bootloader外部调用的，因此不会检查该函数的签名。这意味着我们可以让该函数接受任意参数也不产生任何编译错误，但是函数将无法运行或在运行时导致未定义的行为。

为了确保入口点函数始终具有bootloader期望的正确签名，bootloadercrate提供了entry_point宏，这个宏提供了类型检查的方式来将Rust函数定义为入口点。让我们使用此宏重写入口点函数：

use bootloader::{BootInfo, entry_point};

entry_point!(kernel_main);

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    […]
}

我们不再需要使用extern "C"或no_mangle修饰入口点，因为该宏为我们在底层定义了真正_start入口点。现在，kernel_main函数就是一个普通的的Rust函数，因此我们可以为其选择一个任意名称。重要的是对它进行类型检查，以便在我们使用错误的函数签名时（例如通过添加参数或更改参数类型）产生编译错误。

让我们在lib.rs中做出相同的更改：

#[cfg(test)]
use bootloader::{entry_point, BootInfo};

#[cfg(test)]
entry_point!(test_kernel_main);

/// Entry point for `cargo test`
#[cfg(test)]
fn test_kernel_main(_boot_info: &'static BootInfo) -> ! {
    // like before
    init();
    test_main();
    hlt_loop();
}

由于入口点仅在测试模式下使用，因此我们为本次修改的条目均添加#[cfg(test)]属性。此外，为了避免与main.rs的kernel_main混淆，我们也为测试入口点指定了不同的名称的函数test_kernel_main。目前暂时不使用BootInfo参数，于是我们在参数名称前添加_前缀以消除未使用某变量的编译警告。

实现

现在，我们可以访问物理内存了，也终于可以开始实现页表代码了。第一步，我们要看一下内核正在运行的当前活动页表。第二步，我们将创建一个转换函数，该函数返回给定虚拟地址所映射的物理地址。最后一步，我们将尝试修改页表以创建新的映射。

在开始之前，我们为代码创建一个新的memory模块：

pub mod memory;

再为该模块创建一个空的src/memory.rs文件。

访问页表

在上一篇文章的末尾，我们试图观察内核运行的页表，但是由于无法访问CR3寄存器指向的物理帧而失败。现在我们将接着上一篇文章，通过创建一个active_level_4_table函数来返回对活动4级页表的引用：

use x86_64::{
    structures::paging::PageTable,
    VirtAddr,
};

/// 返回4级页表的可变引用
/// 
/// 该函数为非安全，因为调用者必须保证已将完整的物理内存
/// 映射到偏移量为`physical_memory_offset`的虚拟内存中了。
/// 同时，该函数只能被调用一次，以避免产生其他`＆mut`引用（可能会造成未定义的行为）。
pub unsafe fn active_level_4_table(physical_memory_offset: VirtAddr)
    -> &'static mut PageTable
{
    use x86_64::registers::control::Cr3;

    let (level_4_table_frame, _) = Cr3::read();

    let phys = level_4_table_frame.start_address();
    let virt = physical_memory_offset + phys.as_u64();
    let page_table_ptr: *mut PageTable = virt.as_mut_ptr();

    &mut *page_table_ptr // unsafe
}

首先，我们从CR3寄存器中读取活动4级表的物理帧。然后，我们获取其物理起始地址，将其转换为u64，再为其添加physical_memory_offset，以获取映射页表帧的虚拟地址。最后，我们通过as_mut_ptr方法将虚拟地址转换为*mut PageTable裸指针，再为该指针非安全地创建＆mut PageTable引用。创建＆mut引用而非＆引用，是因为我们将在下文对页面表进行修改。

这里不需要使用非安全块，因为Rust会将unsafe fn函数体当做一个大型unsafe块来对待。这会使代码更加危险，可能稍不注意就会在前几行中意外引入非安全操作。这也使发现非安全操作变得更加困难。目前有一个RFC提出对此行为的修改。

现在，我们可以使用此函数来打印4级表的条目：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    use blog_os::memory::active_level_4_table;
    use x86_64::VirtAddr;

    println!("Hello World{}", "!");
    blog_os::init();

    let phys_mem_offset = VirtAddr::new(boot_info.physical_memory_offset);
    let l4_table = unsafe { active_level_4_table(phys_mem_offset) };

    for (i, entry) in l4_table.iter().enumerate() {
        if !entry.is_unused() {
            println!("L4 Entry {}: {:?}", i, entry);
        }
    }

    // as before
    #[cfg(test)]
    test_main();

    println!("It did not crash!");
    blog_os::hlt_loop();
}

首先，我们将BootInfo结构体重的physical_memory_offset字段转换为VirtAddr，再传给active_level_4_table函数。然后，使用iter函数迭代页表条目，并使用enumerate函数为每个元素添加遍历索引i。我们仅打印非空条目，因为全部512个条目无法一起显示在屏幕上。

运行可以看到以下输出：

我们看到了多个非空条目，它们都映射到不同的3级表。因为内核代码、内核堆栈、物理内存映射和引导信息都会使用单独的内存区域。

为了进一步遍历页表并查看第3级表，我们可以将条目的映射帧再次转换为虚拟地址：

use x86_64::structures::paging::PageTable;

if !entry.is_unused() {
    println!("L4 Entry {}: {:?}", i, entry);

    // 获取物理地址条目并再次转换
    let phys = entry.frame().unwrap().start_address();
    let virt = phys.as_u64() + boot_info.physical_memory_offset;
    let ptr = VirtAddr::new(virt).as_mut_ptr();
    let l3_table: &PageTable = unsafe { &*ptr };

    // 打印3级表的非空条目
    // print non-empty entries of the level 3 table
    for (i, entry) in l3_table.iter().enumerate() {
        if !entry.is_unused() {
            println!("  L3 Entry {}: {:?}", i, entry);
        }
    }
}

至于查看2级和1级表，只需对3级和2级条目重复该过程即可。你可以想象，这很快就会变得非常冗长，因此我们在这里不显示完整的代码。

手动遍历页表很有趣，因为它有助于了解CPU如何执行转换。但是，大多数时候我们只对给定虚拟地址的映射物理地址感兴趣，因此让我们为其创建一个函数。

转换地址

为了将虚拟地址转换为物理地址，我们必须遍历全部四级页表，直到到达映射的帧为止。让我们创建一个执行此转换的函数：

use x86_64::PhysAddr;

/// 将指定的虚拟地址转换为映射的物理地址，如果该地址未被映射则返回`None`。
///
/// 该函数为非安全，因为调用者必须保证已将完整的物理内存
/// 映射到偏移量为`physical_memory_offset`的虚拟内存中了。
pub unsafe fn translate_addr(addr: VirtAddr, physical_memory_offset: VirtAddr)
    -> Option<PhysAddr>
{
    translate_addr_inner(addr, physical_memory_offset)
}

再将该函数传递给安全函数translate_addr_inner，以限制非安全操作的范围。前面提到，Rust会将unsafe fn函数体当做一个大型unsafe块来对待。因此，通过调用私有安全函数，可以再次明确每个不安全操作。

其中的私有函数包含实际的实现细节：

/// `translate_addr`调用的私有函数
///
/// 该函数可以安全地限制`unsafe`操作的范围，因为Rust将非安全函数整体视为非安全块。
/// 该函数只能通过该模块外部的`unsafe fn`来访问。
fn translate_addr_inner(addr: VirtAddr, physical_memory_offset: VirtAddr)
    -> Option<PhysAddr>
{
    use x86_64::structures::paging::page_table::FrameError;
    use x86_64::registers::control::Cr3;

    // 从CR3寄存器中读取活动的4级帧
    let (level_4_table_frame, _) = Cr3::read();

    let table_indexes = [
        addr.p4_index(), addr.p3_index(), addr.p2_index(), addr.p1_index()
    ];
    let mut frame = level_4_table_frame;

    // 遍历多级页表
    for &index in &table_indexes {
        // 将帧转换为页表的引用
        let virt = physical_memory_offset + frame.start_address().as_u64();
        let table_ptr: *const PageTable = virt.as_ptr();
        let table = unsafe {&*table_ptr};

        // 读取页表条目并更新`frame`变量
        let entry = &table[index];
        frame = match entry.frame() {
            Ok(frame) => frame,
            Err(FrameError::FrameNotPresent) => return None,
            Err(FrameError::HugeFrame) => panic!("huge pages not supported"),
        };
    }

    // 加上页偏移量得到物理地址
    Some(frame.start_address() + u64::from(addr.page_offset()))
}

我们不选择复用active_level_4_table函数，而是再次从CR3寄存器中读取4级帧。这样做可以简化此原型实现。不用担心，我们将在稍后创建一个更好的解决方案。

VirtAddr结构体已经提供了用于计算进入四个级别页表的索引的方法。我们将这些索引存储在一个小的数组中，之后便可以使用for循环遍历页表。在循环之外，我们记录最后被访问的frame，以便稍后计算其物理地址。该帧在迭代时指向页表帧，并在最后一次迭代后（即在访问1级条目之后）指向映射的帧。

在循环内部，我们再次使用physical_memory_offset将帧转换为页表引用。然后，我们读取当前页表的条目，并使用PageTableEntry::frame函数检索映射的帧。如果条目未映射到帧，则返回None。如果条目映射到2MiB或1GiB的巨页，则产生panic。

让我们通过转换一些地址来测试转换函数：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // new import
    use blog_os::memory::translate_addr;

    […] // hello world and blog_os::init

    let phys_mem_offset = VirtAddr::new(boot_info.physical_memory_offset);

    let addresses = [
        // 恒等映射VGA缓冲区页
        0xb8000,
        // 某代码页
        0x201008,
        // 某栈页
        0x0100_0020_1a10,
        // 映射到物理地址0的虚拟地址
        boot_info.physical_memory_offset,
    ];

    for &address in &addresses {
        let virt = VirtAddr::new(address);
        let phys = unsafe { translate_addr(virt, phys_mem_offset) };
        println!("{:?} -> {:?}", virt, phys);
    }

    […] // test_main(), "it did not crash" printing, and hlt_loop()
}

运行可以看到以下输出：

如预期的那样，恒等映射的地址0xb8000转换为相同的物理地址。代码页和栈页转换为一些随机的物理地址，这取决于bootloader如何为内核创建初始映射。值得注意的是，转换后的最后12位（译注：在图中的十六进制体现为最后3位）始终保持不变，这是合理的，因为这些位是页面偏移量，而不是被转换地址的一部分。

由于可以通过加上physical_memory_offset来访问每个物理地址，因此physical_memory_offset地址本身的转换应指向物理地址0。但是，转换失败，因为该映射使用巨页来提高效率，但我们的实现尚不支持巨页。

使用`OffsetPageTable`

将虚拟地址转换为物理地址是OS内核中的常见任务，因此x86_64crate为其提供了一种抽象。该实现已经支持巨页和除translate_addr之外的其他几个页表函数，因此下文将使用该抽象进行操作，而不是在我们自己的实现中手动添加对巨页的支持。

该抽象基于两个trait，它们定义了各种页表映射函数：

Mapper trait的泛型约束为PageSize，它提供操作页面的函数。例如：translate_page用于将给定页面转换为其相应大小的帧，map_to函数在页表中创建新的映射。
Translate trait提供了适用于多种页面大小的函数，例如translate_addr或普通translate。

trait仅定义了接口，并未提供任何实现。x86_64crate当前提供三种类型，这些类型按照不同需求实现了这些trait。OffsetPageTable类型假定完整的物理内存以某个偏移量全部映射到虚拟地址空间。MappedPageTable更加灵活一些：它只假定每个页表帧均被映射到了一个位于虚拟地址空间中的可计算地址。最后，可以使用RecursivePageTable类型通过递归页表访问页表帧。

对我们来说，bootloader将完整的物理内存映射到附加physical_memory_offset偏移量的虚拟地址，因此我们可以使用OffsetPageTable类型。要初始化该类型，我们在内存模块中创建一个新的init函数：

use x86_64::structures::paging::OffsetPageTable;

// 初始化OffsetPageTable
///
/// 该函数为非安全，因为调用者必须保证已将完整的物理内存
/// 映射到偏移量为`physical_memory_offset`的虚拟内存中了。
/// 同时，该函数只能被调用一次，以避免产生其他`＆mut`引用（可能会造成未定义的行为）。
pub unsafe fn init(physical_memory_offset: VirtAddr) -> OffsetPageTable<'static> {
    let level_4_table = active_level_4_table(physical_memory_offset);
    OffsetPageTable::new(level_4_table, physical_memory_offset)
}

// make private
unsafe fn active_level_4_table(physical_memory_offset: VirtAddr)
    -> &'static mut PageTable
{…}

该函数将physical_memory_offset作为参数，新建并返回一个具有'static生命周期的OffsetPageTable实例。这意味着该实例在内核的完整运行时始终保持有效。在函数主体中，我们首先调用active_level_4_table函数获取4级页表的可变引用。然后，我们将此引用作为第一个参数传递给OffsetPageTable::new函数。我们使用physical_memory_offset变量作为第二个参数传递给new函数，该参数期望得到虚拟地址映射到物理地址的起点（译注：即虚拟地址映射到物理地址时附加的偏移量）。

从现在开始，仅应从init函数调用active_level_4_table函数，因为当多次调用它时，很容使可变的引用产生多个别名，而这可能会导致未定义的行为。因此，应通过删除pub关键字来使该函数变为私有。

现在，我们可以使用Translate::translate_addr方法来代替我们自己的memory::translate_addr函数。只需要在kernel_main中做几行更改：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // new: different imports
    use blog_os::memory;
    use x86_64::{structures::paging::Translate, VirtAddr};

    […] // hello world and blog_os::init

    let phys_mem_offset = VirtAddr::new(boot_info.physical_memory_offset);
    // new: initialize a mapper
    let mapper = unsafe { memory::init(phys_mem_offset) };

    let addresses = […]; // same as before

    for &address in &addresses {
        let virt = VirtAddr::new(address);
        // new: use the `mapper.translate_addr` method
        let phys = mapper.translate_addr(virt);
        println!("{:?} -> {:?}", virt, phys);
    }

    […] // test_main(), "it did not crash" printing, and hlt_loop()
}

这里需要导入Translatetrait以使用它提供的translate_addr方法。

此时运行，我们会看到与以前相同的转换结果，不同之处在于巨页也可以转换了：

不出所料，0xb8000、代码地址和栈地址的转换结果与我们自己实现的转换函数相同。此外，我们现在看到虚拟地址physical_memory_offset映射到物理地址0x0。

通过使用MappedPageTable类型的转换功能，我们就没必要自己实现对巨页的支持了。另外，还可以访问其他页面函数——如map_to——我们将在下一节中使用。

现在，我们不再需要前面手动实现的memory::translate_addr和memory::translate_addr_inner函数了，因此可以将它们删除。

创建新映射

到目前为止，我们仅查看了页表，还从未修改页表。让我们通过为先前未映射的页面创建一个新的映射来试着修改页表。

该操作将使用Mapper trait的map_to函数来实现，让我们首先看一下这个函数。文档说明该函数有四个参数，分别是：想要映射的页面，该页面应映射到的帧，要为该页表项设置的标志，以及frame_allocator。这里需要帧分配函数，是因为映射给定页面时，可能需要创建新的页表，而这个过程需要新给页表分配未使用的帧。

一个示例函数`create_example_mapping`

第一步是创建一个新的create_example_mapping函数，该函数将给定的虚拟页面映射到VGA文本缓冲区的物理帧0xb8000。我们选择该帧是因为它使我们能够轻松测试映射是否被正确创建：我们只需要对新映射的页面进行写入，就可以在屏幕上观察到写入是否成功。

create_example_mapping函数如下所示：

use x86_64::{
    PhysAddr,
    structures::paging::{Page, PhysFrame, Mapper, Size4KiB, FrameAllocator}
};

/// Creates an example mapping for the given page to frame `0xb8000`.
pub fn create_example_mapping(
    page: Page,
    mapper: &mut OffsetPageTable,
    frame_allocator: &mut impl FrameAllocator<Size4KiB>,
) {
    use x86_64::structures::paging::PageTableFlags as Flags;

    let frame = PhysFrame::containing_address(PhysAddr::new(0xb8000));
    let flags = Flags::PRESENT | Flags::WRITABLE;

    let map_to_result = unsafe {
        // FIXME: 不安全用法，仅演示用
        mapper.map_to(page, frame, flags, frame_allocator)
    };
    map_to_result.expect("map_to failed").flush();
}

除了需要被映射的page之外，该函数还需要OffsetPageTable实例的可变引用和一个frame_allocator。frame_allocator参数使用impl Trait语法约束该泛型参数必须实现FrameAllocator trait。而该trait又约束了其泛型参数必须实现PageSize trait，以便同时支持4KiB标准页和2MiB/1GiB巨页。我们只想创建一个4KiB映射，因此我们将泛型参数设置为Size4KiB。

map_to为非安全方法，而调用者必须确保该帧未被使用。两次映射同一帧会导致未定义行为，例如，当两个不同的＆mut引用指向同一物理内存位置时。在我们的例子中，确实也二次映射了已被映射的VGA文本缓冲区帧，因此打破了所需的安全条件。不过，create_example_mapping函数只是一个临时测试函数，在后文中将被删除，也无伤大雅。我们在该行上添加了FIXME注释，以提醒我们这种不安全用法。

除了page和unused_frame外，map_to方法还使用了一组用于映射的标志，和一个frame_allocator的引用，稍后将对此分配器进行说明。设置PRESENT是因为所有有效条目都需要该标志，而WRITABLE标志则使映射的页面可写入。关于所有可用的标志的列表，请参见上一篇文章的页表格式一节。

map_to函数可能会失败，因此它将返回一个Result。这只是示例用代码，不需要高鲁棒性，因此我们在发生panic时仅使用expect应付。调用成功时该函数将返回MapperFlush类型，该类型提供了一种调用其flush方法即可从转换后备缓冲区（TLB）中刷新新映射页面的简便方法。像Result一样，该类型也使用#[must_use]属性在我们意外忘记调用flush方法时发出警告。

一个假的`FrameAllocator`

为了能够调用create_example_mapping，首先需要创建一个实现了FrameAllocatortrait的类型。如上所述，如果map_to需要新的帧，则该trait就负责为新页表分配帧。

让我们先从简单的情况入手：假设我们不需要创建新的页表。在这种情况下，这个帧分配器始终返回None就足够了。下面的代码创建了一个EmptyFrameAllocator来测试我们的映射函数：

/// 一个始终返回`None`的帧分配器
pub struct EmptyFrameAllocator;

unsafe impl FrameAllocator<Size4KiB> for EmptyFrameAllocator {
    fn allocate_frame(&mut self) -> Option<PhysFrame> {
        None
    }
}

FrameAllocator的实现是非安全的，因为实现者必须保证分配器仅分配未使用的帧。否则，可能会发生不确定的行为，例如，当两个虚拟页面映射到同一物理帧上时。而我们的EmptyFrameAllocator只返回None，因此并不出现生这种问题。

选择一个虚拟页面

现在，我们有一个简单的帧分配器，可以将其传递给create_example_mapping函数了。不过这个分配器始终返回None，所以它也就只能用在创建映射时并不需要额外的页表帧的情况了。为了了解何时需要额外页表帧以及何时不需要额外页表帧，让我们看一个示例：

图的左侧为虚拟地址空间，右侧为物理地址空间，中间为页表。页表如虚线所示，存储在物理存储帧中。虚拟地址空间在地址0x803fe00000中包含一个映射的页面，以蓝色标记。为了将此页面转换为其所在的帧，CPU遍历全部4级页表，直到到达地址为36KiB的帧。

此外，图中以红色显示VGA文本缓冲区的物理帧。我们的目标是使用create_example_mapping函数将先前未映射的虚拟页面映射到此帧。不过由于EmptyFrameAllocator始终返回None，我们自然希望创建映射时不会用到该类型来分配额外的帧。而这取决于我们为映射选择的虚拟页面。

图中以黄色标记了虚拟地址空间中的两个候选页面，一个位于地址0x803fdfd000，就在被映射页（蓝色）之前3页。该地址的4级和3级页表索引与蓝页相同（译注：索引为别为1、0），但2级和1级索引却不同（参阅上一篇文章，译注：索引分别为126、125）。2级表中的索引不同意味着此页面使用了不同的1级表。如果我们选择该页作为我们示例中的映射，那么由于1级表尚不存在，就需要创建该表，也就需要一个额外的未使用的物理帧。而位于地址0x803fe02000的另一个候选页面则不存在此问题，因为它使用与蓝色页面相同的1级页表（译注：索引分别为1、0、127、2）。因此，所有必需的页表已经存在。

总之，创建新映射的难度取决于我们要映射的虚拟页面。在最简单的情况下，该页面的1级页表已经存在，我们只需要写入一个条目即可。在最困难的情况下，该页面所在的内存区域中尚不存在3级表，因此我们需要首先创建新的3级表、2级表、1级表。

为了让create_example_mapping函数能够使用EmptyFrameAllocator类型，我们需要选择一个所有页表均已存在的页面。要找到这样的页面，我们可以利用bootloader会将自身加载到虚拟地址空间的第一个兆字节中这一行为。这意味着该区域的所有页面都存在一个有效的1级表。因此，我们可以在此内存区域中选择任何未使用的页面作为示例映射，比如选择地址为0的页面。通常，该页面应保持未使用状态，以确保解引用空指针会导致页面错误，因此我们知道bootloader将该地址保留为未映射状态。

创建映射

至此，我们准备好了create_example_mapping函数所需的所有参赛，现在可以修改kernel_main函数，以将映射位于虚拟地址0的页面。由于我们会将页面映射到VGA文本缓冲区的帧上，那么也应该也能够通过该页面写在屏幕上。实现如下：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    use blog_os::memory;
    use x86_64::{structures::paging::Page, VirtAddr}; // new import

    […] // hello world and blog_os::init

    let phys_mem_offset = VirtAddr::new(boot_info.physical_memory_offset);
    let mut mapper = unsafe { memory::init(phys_mem_offset) };
    let mut frame_allocator = memory::EmptyFrameAllocator;

    // 映射未使用的页面
    let page = Page::containing_address(VirtAddr::new(0));
    memory::create_example_mapping(page, &mut mapper, &mut frame_allocator);

    // 通过新映射像屏幕写入字符串`New!`
    let page_ptr: *mut u64 = page.start_address().as_mut_ptr();
    unsafe { page_ptr.offset(400).write_volatile(0x_f021_f077_f065_f04e)};

    […] // test_main(), "it did not crash" printing, and hlt_loop()
}

我们首先使用mapper和frame_allocator的可变引用作为参数，调用create_exmaple_mapping函数，来为位于虚拟地址0处的页面创建映射。这会将该页面映射到VGA文本缓冲区的帧上，因此我们应该能够在屏幕上看到对其进行的任何写入。

然后，我们将页面转换为裸指针，并向偏移量400处写入一个值。我们不在页面开头进行写入，因为VGA缓冲区的首会直接被下一个println移出屏幕。写入值0x_f021_f077_f065_f04e代表字符串"New!"。在白色背景上。正如我们在*“VGA文本模式”*一文中所了解的那样，对VGA缓冲区的写操作应该是易失性的，因此我们使用write_volatile方法。

在QEMU中运行将看到以下输出：

屏幕上的"New!"是通过页面0写入的，这意味着我们成功在页表中创建了新的映射。

仅因为负责虚拟地址0处页面的1级页表已存在，所以创建该映射才起作用。当我们尝试为尚不存在1级表的页面进行映射时，map_to函数将失败，因为它试图从EmptyFrameAllocator分配帧以创建新的页面表。当我们尝试映射页面0xdeadbeaf000而不是页面0时，就会看到这种情况：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    […]
    let page = Page::containing_address(VirtAddr::new(0xdeadbeaf000));
    […]
}

运行会出现带有以下错误信息的panic：

panicked at 'map_to failed: FrameAllocationFailed', /…/result.rs:999:5

要映射没有1级页表的页面，我们需要创建一个适当的FrameAllocator。但是，我们如何知道哪些帧未被使用，以及到底有多少物理内存可用呢？

分配帧

为了创建新的页表，我们需要创建一个适当的帧分配器。为此，我们使用memory_map，它曾作为BootInfo结构体的一部分传给bootloader：

use bootloader::bootinfo::MemoryMap;

/// 一个从bootloader内存映射中返回可用帧的帧分配器
pub struct BootInfoFrameAllocator {
    memory_map: &'static MemoryMap,
    next: usize,
}

impl BootInfoFrameAllocator {
    /// 从传入的内存映射中创建帧分配器
    /// 
    /// 该函数为非安全，因为调用者必须确保传入的内存映射是有效的。
    /// 主要要求是其中所有标记为`USABLE`的帧实际上都未被使用。
    pub unsafe fn init(memory_map: &'static MemoryMap) -> Self {
        BootInfoFrameAllocator {
            memory_map,
            next: 0,
        }
    }
}

该结构体有两个字段：一个对bootloader传递的内存映射的'static引用，以及一个跟踪分配器应返回的下一帧的编号的字段next。

如我们在引导信息一节中所介绍的那样，内存映射由BIOS/UEFI固件提供。它只能在引导过程早期被查询，因此bootloader已经为我们调用了相应的函数。存储器映射由MemoryRegion结构体列表组成，结构体包含每个存储区域的起始地址、长度和类型（例如未使用，保留等）。

init函数使用给定的内存映射初始化BootInfoFrameAllocator。next字段初始化为0，且该值会随着每个帧的分配而增长，以避免两次返回相同的帧。由于我们不知道内存映射的可用帧是否已在其他地方使用，因此init函数必须标记为unsafe才能要求调用者提供额外的保证。

写一个`usable_frames`方法

在实现FrameAllocatortrait之前，我们先添加一个辅助方法，以将内存映射转换为能够返回可用帧的迭代器：

use bootloader::bootinfo::MemoryRegionType;

impl BootInfoFrameAllocator {
    /// 返回内存映射中可用帧的迭代器
    fn usable_frames(&self) -> impl Iterator<Item = PhysFrame> {
        // 获取内存映射中的可用区域
        let regions = self.memory_map.iter();
        let usable_regions = regions
            .filter(|r| r.region_type == MemoryRegionType::Usable);
        // 将各区域化为其地址范围
        let addr_ranges = usable_regions
            .map(|r| r.range.start_addr()..r.range.end_addr());
        // 将这些帧的起始地址化为迭代器
        let frame_addresses = addr_ranges.flat_map(|r| r.step_by(4096));
        // 使用这些起始地址创建`PhysFrame`类型
        frame_addresses.map(|addr| PhysFrame::containing_address(PhysAddr::new(addr)))
    }
}

该函数使用组合多个迭代器的方法，将初始MemoryMap转换为返回可用物理帧的迭代器：

首先，我们调用iter方法将内存映射转换为返回MemoryRegions的迭代器。
然后，我们使用filter方法跳过任何保留区域或别的不可用的区域。bootloader会为其创建的所有映射更新内存映射，因此内核使用的帧（代码，数据或栈）或用于存储引导信息的帧就已经被标记为InUse或类似的标志。因此，我们可以确定Usable帧不会在其他地方使用。
之后，我们使用map组合器和Rust的range语法将内存区域的迭代器转换为地址范围的迭代器。
接下来，我们使用flat_map将地址范围转换为帧起始地址的迭代器，在这个过程中同时使用step_by每隔4096字节选择一个地址。这是因为页面大小为4096字节（即4 KiB），每隔4096选择一个地址便得到了每个帧的起始地址。Bootloader页面会对齐所有可用的内存区域，因此我们在这里不需要任何用于对齐或舍入的代码。之所以使用flat_map而非map，是因为想要得到Iterator<Item = u64>而非Iterator<Item = Iterator<Item = u64>>。（译注：上一步得到的迭代器是Iterator<Item = Range<u64>>，因此只有使用flat_map将内外迭代器都打开才能操作其中的u64）。
最后，我们将起始地址转换为PhysFrame类型，以构造Iterator<Item = PhysFrame>。

该函数的返回类型使用impl Trait特性。这样，我们可以指定返回值某种实现了Iteratortrait特性且其中迭代元素类型为PhysFrame的类型，而无需指明具体的返回类型。注意，我们无法指明返回值的具体类型，因为它依赖于一个匿名的闭包。

实现`FrameAllocator`trait

现在我们可以实现FrameAllocatortrait了：

unsafe impl FrameAllocator<Size4KiB> for BootInfoFrameAllocator {
    fn allocate_frame(&mut self) -> Option<PhysFrame> {
        let frame = self.usable_frames().nth(self.next);
        self.next += 1;
        frame
    }
}

首先使用usable_frames方法从内存映射中获取可用帧的迭代器。然后，使用Iterator::nth函数获取索引为 self.next的帧（从而跳过第(self.next-1)帧）。在返回该帧之前，将self.next增加一，以便在下一次调用时返回下一个帧。

这种实现方式并不是十分理想，因为在每次分配帧时该函数都会重新创建usable_frame分配器。最好直接将迭代器存储为结构体的一个字段，然后，我们将不需要再调用nth方法，而是只需在每次分配时调用next。不过，这种方法的问题在于，目前还无法在结构体字段中存储impl Trait类型。不过在未来某一天，当Rust的named existential types完全实现时，这个方法也许会变得可行。

使用`BootInfoFrameAllocator`

现在，我们可以修改kernel_main函数，以传入BootInfoFrameAllocator实例代替原来的EmptyFrameAllocator实例了：

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    use blog_os::memory::BootInfoFrameAllocator;
    […]
    let mut frame_allocator = unsafe {
        BootInfoFrameAllocator::init(&boot_info.memory_map)
    };
    […]
}

使用引导信息帧分配器后映射成功，我们再次看到了白底黑字的"New!"出现在屏幕上。在后台，map_to方法通过以下方式创建了缺少的页表：

使用传入的frame_allocator分配未使用的帧。
将帧初始化为全零以创建一个新的空页表。
将更高级别的表的条目映射到该帧。
使用下一级表继续执行。

虽然我们的create_example_mapping函数只是一些示例代码，但至少现在已经能够为任意页面创建新的映射了。这对于在以后的文章中进行内存的分配或多线程的实现时至关重要。

不过目前，我们应该先删掉create_example_mapping函数，以避免上述的意外调用导致的未定义的行为。

小结

在这篇文章中，我们学习了访问页表物理帧的各种技术，包括恒等映射、完整物理内存映射、临时映射和递归页表等。接下来我们选择了映射完整的物理内存，因为它简单、可移植且功能强大。

如果没有页表的访问权限，我们就无法映射内核中的物理内存，因此我们需要bootloader的支持。bootloadercrate支持通过可选的cargo特性创建我们所期望的映射。而我们所需的引导信息将以&BootInfo参数的形式从入口点函数中传递给内核。

在代码实现的过程中，我们首先通过手动遍历页表的方式实现了地址转换函数，然后转而使用x86_64crate的MappedPageTable类型代替我们手写的代码。此外，我们还学习了如何在页表中创建新的映射，以及如何在bootloader传入的内存映射之上创建必要的FrameAllocator。

下期预告

下一篇文章将为我们的内核创建一个堆内存区域，这将使我们能够分配内存并使用各种集合类型。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 3.1 - 内存分页简介

Sun, 21 Mar 2021 21:30:00 GMT

:::warning 本文所有内容均为翻译，原文：Introduction to Paging；原项目：Writing an OS in Rust :::

在这篇文章中，我们将介绍分页机制，这是一种非常常见的内存管理方案，我们还将会在操作系统中实现它。本文还将解释为什么需要内存隔离、分段如何工作、什么是虚拟内存以及分页如何解决内存分段问题。此外，还探讨了x86_64架构上的多级页表的布局。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-08分支中找到。

内存保护

操作系统的一项主要任务是将程序彼此隔离。例如，你的网络浏览器不应该干扰你的文本编辑器。为了实现此目标，操作系统利用硬件功能来确保一个进程的内存区域不能被其他进程访问。内存保护有多种的方法，具体取决于硬件和操作系统实现。

例如，某些ARM Cortex-M处理器（用于嵌入式系统）具有内存保护单元(MPU)，可让用户定义少量（例如8个）具有不同访问权限（例如，无权访问、只读、读写等）的内存区域。在每次内存访问中，MPU会确保该地址位于具有正确访问权限的区域中，否则将抛出异常。通过在每次进程切换时更改区域和访问权限，操作系统可以确保每个进程仅访问它自己的内存，从而使进程彼此隔离。

在x86上，硬件支持两种不同的内存保护方法：分段和分页。

内存分段

分段早在1978年就已出现，最初是为了增加可寻址内存的数量。当时的情况是CPU仅使用16位地址，这将可寻址内存量限制在了64KiB。为了能够访问大于64KiB的内存，于是引入了附加的段寄存器，每个段寄存器都包含一个偏移地址。CPU会在每次访问内存时自动添加此偏移量，从而使可访问内存最多增加到1MiB。

CPU会根据内存访问的类型自动选择不同的段寄存器：对于获取指令，将使用代码段CS；对于栈操作（压栈/弹栈），将使用栈段SS。其他指令使用数据段DS或额外段ES。之后又添加了两个额外的段寄存器FS和GS，可供自由使用。

在内存分段的首个版本中，段寄存器直接包含偏移量，而且也不进行访问控制。这一点后来随着保护模式的引入而改变。当CPU在该模式下运行时，段描述符包含访问本地或全局描述符表的索引，该表除偏移地址外还包含段大小和访问权限。通过为每个进程加载单独的全局/本地描述符表，从而将对内存的访问限制在该进程自己的内存区域，操作系统也因此能够将进程彼此隔离。

通过在实际访问之前修改内存地址，内存分段也不知不觉的引入了一种在今天几乎到处使用的技术：虚拟内存。

虚拟内存

虚拟内存的思路是将内存地址从底层物理存储设备中抽象出来。不同于直接访问存储设备，这里会先执行一个转换步骤。对于内存分段，转换步骤是添加活动分段中的偏移地址。假设一个程序在偏移量为0x1111000的段中访问内存地址0x1234000：实际访问的地址为0x2345000。

为了区分这两种地址类型，转换前的地址称为虚拟地址，转换后的地址称为物理地址。这两种地址之间的一个重要区别是物理地址是唯一的，相同的物理地址始终指向相同且确定的内存空间。而虚拟地址则取决于转换。两个完全不同的虚拟地址可能指向相同的物理地址。同样，当相同的虚拟地址使用不同的转换时，它们可以指向不同的物理地址。

举个例子：并行执行同一个程序两次，就可以很好的解释这一行为：

例子中的同一程序运行两次，但具有不同的转换。第一个实例的段偏移量为100，因此其虚拟地址0–150转换为物理地址100–250。而第二个实例的偏移量为300，它将其虚拟地址0–150转换为物理地址300–450。这使两个程序都可以运行相同的代码并使用相同的虚拟地址，而不会互相干扰。

另一个优点是，即使程序使用完全不同的虚拟地址，现在也可以将它们放置在任意期望的物理内存中。因此，OS可以利用全部的可用内存，而无需重新编译程序。

内存碎片

内存分段强大的地方就在于虚拟地址和物理地址之间的区别。但是，它也具有碎片化的问题。例如，假设我们要运行上面看到的程序的第三份副本：

虽然仍有足够的可用内存空间，但我们也无法在不覆盖前两个实例的情况下，将程序的第三个实例映射到虚拟内存。问题在于，内存分段需要连续的内存，而不能有效利用小的空闲块。

解决这种碎片的一种方法是暂停执行，将内存中已使用的部分移到更近的位置，更新转换偏移量，然后恢复执行：

现在就有足够的连续空间来启动程序的第三个实例了。

这种碎片整理过程的缺点是需要复制大量内存，从而降低了性能。还需要定期进行整理，以免造成内存碎片过多。由于程序在随机时间暂停并且可能变得无响应，因此这使得系统行为不可预测。

这些问题是大多数系统不再使用内存分段的原因之一。实际上，x86上的64位模式甚至都不再支持分段，而是使用分页，这可以完全避免碎片问题。

内存分页

这个思路是将虚拟和物理内存空间都分成固定大小的小块。虚拟内存空间的块称为页，物理地址空间的块称为帧。每个页可以单独映射到一个帧，这使得我们可以在不连续的物理帧之间划出更大的内存区域。

如果我们回顾一下碎片化内存空间的例子，而这次使用分页而不是分段，就可以看到这样做的优点：

上图中的页面大小为50字节，这意味着我们的每个内存区域都分为三个页面。每个页面分别映射到一个帧，因此连续的虚拟内存区域可以映射到非连续的物理帧。这使我们可以在不执行任何碎片整理的情况下启动程序的第三个实例。

潜在碎片

与分段相比，分页使用许多固定大小的小块内存区域，而不是一些可变大小的大块区域。由于每个帧都具有相同的大小，因此不会存在太小而无法使用的帧，也就不会发生碎片了。

这样做看起来似乎没有碎片。不过确实仍存在着某些潜在碎片，即所谓的内部碎片。发生内部碎片是因为并非每个内存区域都正好是页面大小的整数倍。想象一下在上面的示例中，一个大小为101的程序：它仍将需要三个大小为50的页面，也就是比程序所需多占了49个字节。为了区分两种类型的碎片，使用分段时发生的碎片类型称为外部碎片。

内部碎片是不好，但通常要好于分段时发生的外部碎片。它仍然会浪费内存，不过好在不需要碎片整理，并使碎片量可预测（平均每个内存区域约半页）。

页表

可以看到这数以百万计的页面中的每一个都可以映射到一个单独的帧，而这套映射信息应当被记录在某处。内存分段为每个活动内存区域配置了一个单独的段选择器寄存器，这显然不能用于分页，因为页面数量远多于寄存器。相反，分页使用称为页表的表结构来记录映射信息。

对于我们上面的例子，页表如下所示：

我们看到每个程序实例都有自己的页表。指向当前活动页表的指针存储在特殊的CPU寄存器中。在x86上，此寄存器称为CR3。在运行每个程序实例之前，操作系统的工作是将指向正确页表的指针加载到该寄存器。

在每次访问存储器时，CPU将会从寄存器读取页表指针，并为被访问页面查找其对应的映射帧。这个过程完全由硬件完成，且对运行中的程序完全透明。为了加快转换过程，许多CPU架构都有一个特殊的缓存，用以记住上一次转换的结果。

对于一些硬件架构，页表条目还可以存储诸如访问权限一类的标志字段属性。在上面的示例中，具有“r/w”标志说明页面可读可写。

多级页表

我们刚刚看到的简单页表在较大的地址空间中存在一个问题：浪费内存。例如，假设有一个程序使用四个虚拟页面0、1_000_000、1_000_050和1_000_100（_为千位分隔符）：

它仅需要4个物理帧，但是页表有超过一百万个条目。我们不能省略空条目，因为如果省略空条目，翻译过程就无法继续保证CPU能够直接跳转到正确的条目了（例如，并不能保证第四页使用第四个条目。译注：翻译过程应保证低计算复杂度，如O(1)，因为几乎所欲操作都会涉及内存页表，所以保证CPU能够直接跳转非常重要。）。

为了减少浪费的内存，我们可以使用两级页表。思路是我们对不同的地址区域使用不同的页表。另一个称为2级页表的额外表包含了地址区域和（1级）页表之间的映射。

最好用一个例子来解释。让我们定义每个1级页面表负责一个大小为10_000的区域。对于上面的例子，则有下表：

第0页属于前10_000字节区域，因此它将使用2级页表的第一个条目。此条目指向1级页表T1，该页表指出第0页指向第0帧。

页1_000_000、1_000_050和1_000_100都属于第100个10_000字节区域，因此它们使用了2级页表的第100个条目。该条目指向另一个1级页表T2，该表将这三个页面分布映射到第100、150和200帧。注意，在1级表中的页面地址不包括区域偏移量，因此页面1_000_050在1级页表中的条目应为50。

虽然在2级表中仍有100个空条目，但比以前的百万个空条目要少得多。节约的空间就在于，我们并不需要为从10_000到1_000_000之间的未映射内存区域创建1级页表。

两级页表的原理可以扩展到三级、四级或更多级。然后，页表寄存器指向最高级的表，该表指向下一个较低级的表，再指向下一个较低级的表，依此类推。最后，1级页表指向映射的帧。通常，该原理称为多级页表或分层页表。

现在我们知道分页和多级页表是如何工作的，接下来可以看看x86_64架构中的分页是如何实现的（后文假设CPU在64位模式下运行）。

x86_64的分页

x86_64架构使用4级页面表，每个页面大小为4KiB。每个页表无论层级，均为具有512个条目的固定大小。每个条目的大小为8个字节，因此每个表的大小为512 * 8B = 4KiB，也正好为一页。

每级的页表索引能够直接用虚拟地址算出：

每个表索引有9位，因为每个表都有2^9=512个条目。最低的12位是4KiB页中的偏移量（2^12字节=4KiB）。第48到64位将被忽略，可以看出x86_64其实并不是真正的64位，因为它仅支持48位地址。

即使第48至64位将被忽略，也不能将这些位设为任意值。而是将这些位都赋上第位47的值，以保持地址唯一，并允许将来的扩展（如5级页表）。这被称为符号扩展，因为它与二进制补码中的符号扩展非常相似。如果地址未正确进行符号扩展，会引发CPU异常。

值得注意的是，最近Intel的“Ice Lake” CPU可选地支持5级页表，并将虚拟地址从48位扩展到57位。在当前阶段，为特定CPU优化我们的内核没有意义，因此本文仅使用标准的4级页表。

地址转换示例

让我们看一个例子，以详细了解转换过程的原理：

当前活动的4级页表的物理地址，也就是该4级页表的根，存放在CR3寄存器中。然后，每个页表条目都指向下一级表的物理帧。最后，1级页表的条目指向地址映射的帧。请注意，页表中的所有地址都是物理地址，而不是虚拟地址，否则CPU也需要转换这些地址（而这可能导致无限递归）。

上面的页面表层次结构映射了两个页面（蓝色）。从页表索引中，我们可以推断出这两个页的虚拟地址为0x803FE7F000和0x803FE00000。现在，让我们看看当程序尝试读取地址0x803FE7F5CE时会发生什么。首先，我们将地址转换为二进制，并确定该地址的页表索引和页偏移量：

有了这些索引，我们现在可以遍历页表层次，确定该地址映射的物流帧：

我们首先从CR3寄存器中读取第4级页表地址。
4级页表索引为1，于是我们查看表中索引为1的条目，该条目告诉我们3级页表存储在地址16KiB中。
我们从该地址加载3级表，然后查看索引为0的条目，该条目告诉我们2级页表存储在地址24KiB中。
2级页表的索引为511，于是我们查看该表的最后一个条目，以查找1级表的地址。
通过1级页表中索引为127的条目，最终找到页面映射到12KiB帧，即十六进制的0x3000。
最后一步，将页面偏移量添加到帧地址上，获取的物理地址为0x3000 + 0x5ce = 0x35ce。

1级页表中页面的权限为r，即只读。硬件会强制执行这些权限，如果我们尝试对该页面写入，将会引发异常。较高级别页面中的权限限制了较低级别中的可能权限，因此，如果我们将3级页面条目设置为只读，则即使较低级页面指定了读/写权限，使用该条目的页面也将无法执行写入。

需要注意，此示例使用了每级表仅有单个实例，但在实际中，通常地址空间中的每级表都有多个实例。最多有：

一个4级页表，
512个3级表（因为4级表有512个条目），
512 * 512个2级表（因为512个3级表中的每个表都有512个条目），并且还有
512 * 512 * 512个1级表（每个2级表都有512个条目）。

页表格式

x86_64架构上的页表基本上是具有512个条目的数组。使用Rust语法就是：

#[repr(align(4096))]
pub struct PageTable {
    entries: [PageTableEntry; 512],
}

如repr属性所示，页表需要进行页对齐，即在4KiB边界上对齐。此要求确保页表恰好能填满一页，同时允许优化以使条目更紧凑。

每个条目的大小为8个字节（64位），并具有以下格式：

位	名称	说明
0	present	本页是否存在于内存中
1	writable	本页是否可写
2	user accessible	如果未设置，则只有内核模式的代码可以访问本页
3	write through caching	对本页的写入是否能够直接进入内存，而无需经过缓存
4	disable cache	本页不使用缓存
5	accessed	当本页正在使用中，CPU将自动设置此位
6	dirty	当本页正被写入时，CPU将自动设置此位
7	huge page/null	此位在1级和4级页表中必须置为0，置为1时，在3级页表中会创建1GiB的页面，在2级页表中会创建2MiB的页面
8	global	地址空间切换时，本页不会被换出缓存 (必须将CR4寄存器的PGE位置为1)
9-11	available	此位供OS自由使用
12-51	physical address	页面对齐52位物理地址的帧地址或下一个页表的地址
52-62	available	此位供OS自由使用
63	no execute	禁止将本页数据当做代码执行（必须将EFER寄存器中的NXE位置为1）

我们看到只有第12-51位用于存储物理帧地址，其余位用作标志或由操作系统自由使用。这是可行的，因为我们总是指向一个4096字节对齐的地址，这可能指向一个页面对齐的页表，也可能指向映射帧的开头。这意味着位0-11始终为零，也没必要存储这些位，因为硬件会在使用地址之前将它们设置为零。第52-63位同样如此，因为x86_64架构仅支持52位物理地址（类似于它仅支持48位虚拟地址的方式）。

让我们仔细看看可用的标志：

present标志将被映射页面与未被映射页面区别开来。当主内存已满时，它可用于临时将页面换出到磁盘。当随后访问到该页面时，将会发生称为页面错误的特殊异常，操作系统将对此做出反应——从磁盘重新加载缺失的页面——然后继续执行程序。
writable和no execute标志分别控制页面的内容是可写，还是包含可执行指令。
当对页面被读取或写入时，CPU会自动设置accessed或dirty标志。该信息可以被操作系统利用，例如，在决定换出哪些页面时，或者确定自上次保存到磁盘以来内容是否已被修改。
write through caching和disable cache标志允许控制每个页面的缓存。
user accessible标志使页面可用于用户空间代码，否则仅当CPU处于内核模式时才可被访问。该特性使得CPU可以在运行用户空间程序时保持内核映射，该功能用于加快系统调用的速度。但是，Spectre漏洞仍然能够允许用户空间程序读取这些页面。
global标志向硬件发出信号，表明该页在所有地址空间中都可用，因此不需要在地址空间切换时将其从转换缓存中删除（请参阅下文中有关TLB的部分）。该标志通常与被置为0的user accessible标志一起使用，用以将内核代码映射到所有地址空间。
huge page标志允许通过使2级或3级页表的条目直接指向映射的帧，来创建更大尺寸的页面。设置此位后，对于第2级条目，页面大小将增加512倍，达到2MiB = 512 * 4KiB，对于第3级条目，甚至能够达到1GiB = 512 * 2MiB。使用较大页面的优点是需要更少的地址转换缓存行和更少的页表。

x86_64crate提供了页表及其条目的类型，因此我们不需要自己创建这些结构。

转换后备缓冲区

4级页表使虚拟地址的转换变得耗时，因为每次转换都需要4次内存访问。为了提高性能，x86_64架构将最后的几个转换缓存在所谓的转换后备缓冲区（TLB）中。当转换仍被缓存时，这允许跳过转换。

与其他CPU缓存不同，TLB不是完全透明的，而且在页表内容更改时也不会更新或删除转换。这意味着，每当内核修改页面表时，都必须手动更新TLB。为此，有一条特殊的CPU指令叫做invlpg（即“无效页面”），该指令从TLB中删除指定页面的转换，以便在下次访问时再次从页表中加载该转换。也可以通过重新加载CR3寄存器来模拟地址空间切换，从而完全清空TLB。x86_64crate为tlb模块为这两种更新方法都提供了Rust函数。

需要注意的是，在每次页表被修改时都需要刷新TLB，这一点很重要，否则CPU可能会继续使用旧的转换，这可能会导致难以调试的错误。

实现

有一个事实还没有提及：我们的内核已经在分页上运行了。在“最小化Rust内核”一文中添加的bootloader已经建立了一个4级分页层次结构，将内核的每个页面映射到一个物理帧。bootloader执行此操作是因为分页在x86_64的64位模式下是强制的。

这意味着我们在内核中使用的每个内存地址都是一个虚拟地址。我们之所以可以访问VGA缓冲区地址0xb8000，就是因为bootloader对该页面进行了恒等映射，即将虚拟页面0xb8000映射至物理帧0xb8000。

分页使我们的内核已经相对安全，因为每次超出范围的内存访问都会导致页面错误异常，而不是写入随机物理内存。bootloader甚至为每个页面设置了正确的访问权限，这意味着只有包含代码的页面才是可执行的，只有包含数据的页面才是可写的。

页面错误

让我们尝试通过访问内核外的某些内存来诱发页面错误。首先，创建一个页面错误处理程序并将其注册到IDT中，以便我们看到一个页面错误异常，而不是一个通用的双重故障：

lazy_static! {
    static ref IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();

        […]

        idt.page_fault.set_handler_fn(page_fault_handler); // new

        idt
    };
}

use x86_64::structures::idt::PageFaultErrorCode;
use crate::hlt_loop;

extern "x86-interrupt" fn page_fault_handler(
    stack_frame: &mut InterruptStackFrame,
    error_code: PageFaultErrorCode,
) {
    use x86_64::registers::control::Cr2;

    println!("EXCEPTION: PAGE FAULT");
    println!("Accessed Address: {:?}", Cr2::read());
    println!("Error Code: {:?}", error_code);
    println!("{:#?}", stack_frame);
    hlt_loop();
}

CPU会在发生页面错误时自动设置CR2寄存器，其中包含导致页面错误的访问的虚拟地址。我们使用x86_64crate的Cr2::read函数读取和打印该虚拟地址。PageFaultErrorCode类能够提供关于诱发页面错误的内存访问的类型的更多信息，例如，该错误是由读取还是写入操作引起的。因此，我们也应打印该信息。不过，不能在不解决页面错误的情况下继续执行程序，因此我们在最后添加一个hlt_loop。

现在我们可以尝试访问内核外的一些内存：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    blog_os::init();

    // new
    let ptr = 0xdeadbeaf as *mut u32;
    unsafe { *ptr = 42; }

    // as before
    #[cfg(test)]
    test_main();

    println!("It did not crash!");
    blog_os::hlt_loop();
}

运行内核，可以看到页面错误处理程序被调用：

CR2寄存器确实包含了0xdeadbeaf，也就是我们尝试访问的地址。错误代码通过CAUSED_BY_WRITE告诉我们，尝试执行写操作时发生了错误。通过未设置的位，我们还能了解更多信息。例如，PROTECTION_VIOLATION位未设置，意味着由于目标页面不存在而导致了页面错误。

我们看到当前指令指针是0x2031b2，因此我们知道该地址指向代码页。bootloader将代码页映射为只读，因此从该地址读取是允许的，但写入会导致页面错误。您可以通过将0xdeadbeaf指针更改为0x2031b2来尝试此操作：

// 注意：代码中的地址可能与你实际运行中得到的地址不同，
// 这里应使用你实际运行中产生的页面错误所打印的地址进行替换。
let ptr = 0x2031b2 as *mut u32;

// 从代码页读取
unsafe { let x = *ptr; }
println!("read worked");

// 向代码页写入
unsafe { *ptr = 42; }
println!("write worked");

可以看到读取访问有效，但是写入访问导致页面错误：

我们看到了“read worked”，这表明读操作没有引起任何错误。但是，并没有看到“write worked”，就发生页面错误。这次除了设置了CAUSED_BY_WRITE标志外，还设置了PROTECTION_VIOLATION标志，该标志说明被访问的页面存在，但对该页面进行的操作却并不被允许。在上面的例子中，由于代码页被映射为只读，因此对该页进行的写操作不会被允许。

访问页表

尝试观察一下定义我们内核如何进行映射的页表：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    blog_os::init();

    use x86_64::registers::control::Cr3;

    let (level_4_page_table, _) = Cr3::read();
    println!("Level 4 page table at: {:?}", level_4_page_table.start_address());

    […] // test_main(), println(…), and hlt_loop()
}

x86_64中的Cr3::read函数返回CR3寄存器中的当前活动的4级页表。函数返回一个由PhysFrame和Cr3Flags类型组成的元组。我们只对这个帧感兴趣，于是忽略了元组的第二个元素。

运行后可以看到以下输出：

Level 4 page table at: PhysAddr(0x1000)

所以当前活动的第4级页表存储在物理内存的0x1000中，如其封装类型PhysAddr所示。现在的问题是：如何从内核访问该表？

当分页处于活动状态时，无法直接访问物理内存，不然的话程序将很容易避开内存保护去访问其他程序的内存。因此，访问该表的唯一方法是通过某些虚拟页面，该虚拟页面映射到地址为0x1000的物理帧。为页表帧创建映射这个问题是个普遍的问题，因为内核需要定期访问页面表，例如在为新线程分配栈时。

在下一篇文章中将详细说明该问题的解决方案。

小结

本文介绍了两种内存保护技术：分段和分页。前者使用可变大小的内存区域但存在外部碎片的问题，而后者使用固定大小的页面同时允许对访问权限进行更细粒度的控制。

分页将页面的映射信息存储在具有一计或多级页表中。x86_64架构使用4级页表，页面大小为4KiB。硬件会自动遍历页表，并将生成的地址转换缓存在转换后备缓冲区（TLB）中。此缓冲区不是透明更新的，需要在页表更改时手动刷新。

我们了解到现在的内核已经在内存分页上运行了，而且非法的内存访问将会导致页面错误异常。我们试图访问当前活动的页表，但是由于CR3寄存器存储了我们无法直接从内核直接访问到的物理地址，所以我们并不能执行此操作。

下期预告

下一篇文章将解释如何在内核中实现对分页的支持，并提供从内核访问物理内存的不同方法，这使得访问内核运行中的页表成为可能。至此，我们能够实现将虚拟地址转换为物理地址并在页表中创建新映射的功能。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 2.3 - 硬件中断

Thu, 18 Mar 2021 22:51:00 GMT

:::warning 本文所有内容均为翻译，原文：Hardware Interrupts；原项目：Writing an OS in Rust :::

在这篇文章中，我们将设置可编程中断控制器，以便将硬件中断正确的转发到CPU。为了处理这些中断，我们将新条目添加到中断描述符表中，就像我们对异常处理程序所做的一样。我们将学习如何获取定期的定时器中断以及如何从键盘获取输入。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-07分支中找到。

概述

中断为连接在CPU上的硬件设备提供了一种通知CPU的方法。因此，键盘不必告诉内核要定期检查是否有新的字符输入（一种称为轮询的过程），而是将每次按键事件通知内核。如此，内核仅在发生某些事件时才做出反应，因此效率更高。这样做还可以缩短响应时间，因为内核不需要等待下一次轮询，它将会立即做出反应。

我们无法将所有硬件设备都直连到CPU，而是采用一个独立的中断控制器汇总所有外设的中断，再通知CPU：

                                    ____________             _____
               Timer ------------> |            |           |     |
               Keyboard ---------> | Interrupt  |---------> | CPU |
               Other Hardware ---> | Controller |           |_____|
               Etc. -------------> |____________|

大多数中断控制器是可编程的，这意味着它们支持不同的中断优先级。例如，这可以让计时器中断的优先级比键盘中断更高，以便确保计时的准确性。

与异常不同，硬件中断的发送是异步的。这意味着中断与正在执行的代码无关，中断是随时都会发生的。因此，内核中突然出现了一种并发，同时也包含了各种潜在的与并发相关的bug。Rust严格的所有权模型在这里帮上了大忙，因为它禁止了可变全局状态。但是，仍然可能出现死锁，正如我们将在本文后面看到的那样。

8259 PIC

英特尔 8259是1976年推出的可编程中断控制器(PIC)。虽然它早已被较新的APIC取代，但由于向后兼容的原因，如今的系统仍支持其接口。8259 PIC的配置比APIC要容易得多，因此在后续文章中切换到APIC之前，我们仍将使用8529 PIC来引入中断。

8259有8条中断线和几条用于与CPU通讯的线。当年的典型系统会配备两个8259 PIC实例，一个主控制器和一个通过中短线连接在主控上的从控制器：

                     ____________                          ____________
Real Time Clock --> |            |   Timer -------------> |            |
ACPI -------------> |            |   Keyboard-----------> |            |      _____
Available --------> | Secondary  |----------------------> | Primary    |     |     |
Available --------> | Interrupt  |   Serial Port 2 -----> | Interrupt  |---> | CPU |
Mouse ------------> | Controller |   Serial Port 1 -----> | Controller |     |_____|
Co-Processor -----> |            |   Parallel Port 2/3 -> |            |
Primary ATA ------> |            |   Floppy disk -------> |            |
Secondary ATA ----> |____________|   Parallel Port 1----> |____________|

上图显示了一个典型的中断线分配布局。可以看到15条线中的大多数都有固定的映射，例如次PIC的4号线分配给了鼠标。

每个控制器可以通过两个[I/O端口](https://os.phil-opp.com/testing/#i-o-ports)——一个“命令”端口和一个“数据”端口——进行配置。对于主控制器，这些端口是0x20（命令）和0x21（数据）。对于从控制器，它们是0xa0（命令）和0xa1（数据）。有关如何配置PIC的更多信息，请参见osdev.org上的文章。

实现

PIC的默认配置不可用，因为它会将范围为0到15的中断向量编号发送到CPU。而这些编号已被CPU异常占用，例如，编号8对应双重故障。为了解决这个占用问题，我们需要将PIC中断重新映射到不同的编号。实际范围并不重要，只要它不与例外重叠即可，但是我们通常会选择编号32到47，因为这些是32个异常占用后的第一个段空闲数字。

我们可以通过向PIC的命令和数据端口写入特殊值来使配置生效。幸运的是，已经有一个名为pic8259_simple的crate，因此我们不需要自己编写初始化过程。如果你对它的工作方式感兴趣，请查看它的源代码，该crate很小并且文档齐全。

要将crate添加为依赖，我们需要将以下内容添加到项目中：

[dependencies]
pic8259_simple = "0.2.0"

该crate提供的主要抽象为结构体ChainedPics。该结构体代表了我们在上面介绍的主/次PIC布局。它的用法如下：


use pic8259_simple::ChainedPics;
use spin;

pub const PIC_1_OFFSET: u8 = 32;
pub const PIC_2_OFFSET: u8 = PIC_1_OFFSET + 8;

pub static PICS: spin::Mutex<ChainedPics> =
    spin::Mutex::new(unsafe { ChainedPics::new(PIC_1_OFFSET, PIC_2_OFFSET) });

像上面这样将PIC的偏移量设置为32-47。通过将ChainedPics结构体放置于Mutex中，我们就能够（通过lock方法）获得安全的写访问权限，这是下一步所必需的。ChainedPics::new函数被标记为非安全的，因为提供错误的偏移量将可能导致未定义的行为。

现在，我们可以在init函数中初始化8259 PIC了：

pub fn init() {
    gdt::init();
    interrupts::init_idt();
    unsafe { interrupts::PICS.lock().initialize() }; // new
}

我们使用[initialize](https://docs.rs/pic8259_simple/0.2.0/pic8259_simple/struct.ChainedPics.html#method.initialize)函数来执行PIC初始化。与ChainedPics::new函数一样，该函数也是非安全的，因为如果PIC配置错误，使用它也将可能导致未定义的行为。

如果一切顺利，执行cargo run时，我们应该继续看到“It not not crash”消息。

启用中断

到目前为止，什么都没发生，因为在CPU配置中依然禁用着中断。这意味着CPU根本不侦听中断控制器，也就没有中断可以到达CPU。让我们更改一下配置：

pub fn init() {
    gdt::init();
    interrupts::init_idt();
    unsafe { interrupts::PICS.lock().initialize() };
    x86_64::instructions::interrupts::enable();     // new
}

x86_64crate的interrupts::enable将函数执行特殊的sti指令（即“设置中断”）以启用外部中断。当我们现在尝试cargo run时，将看到发生双重故障：

发生此双重故障是因为硬件计时器在默认情况下为启用状态（确切地说是Intel 8253），因此一旦启用中断，我们便开始接收计时器中断。由于尚未为计时器定义处理函数，因此双重故障处理程序将会被调用。

处理定时器中断

从上图可以看出，定时器使用主PIC的0号线。这意味着它将作为中断32（0+偏移量32）到达CPU。我们不对索引32进行硬编码，而是将其存放在InterruptIndex枚举中：

#[derive(Debug, Clone, Copy)]
#[repr(u8)]
pub enum InterruptIndex {
    Timer = PIC_1_OFFSET,
}

impl InterruptIndex {
    fn as_u8(self) -> u8 {
        self as u8
    }

    fn as_usize(self) -> usize {
        usize::from(self.as_u8())
    }
}

该枚举是一个C风格枚举，因此我们可以直接为每个变体指定索引。repr(u8)属性指定每个变体都表示为u8。将来我们还会添加更多中断变量。

现在我们可以为计时器中断添加一个处理函数：

use crate::print;

lazy_static! {
    static ref IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();
        idt.breakpoint.set_handler_fn(breakpoint_handler);
        […]
        idt[InterruptIndex::Timer.as_usize()]
            .set_handler_fn(timer_interrupt_handler); // new

        idt
    };
}

extern "x86-interrupt" fn timer_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame)
{
    print!(".");
}

timer_interrupt_handler的函数签名与之前的异常处理函数相同，因为CPU对异常和外部中断的反应相同（唯一的区别是某些异常会推送错误码）。InterruptDescriptorTable结构体实现了IndexMut trait，因此我们可以使用数组索引语法访问各个条目。

在计时器中断处理程序中，我们在屏幕上打印了一个点。由于定时器中断是周期性发生的，因此我们希望每个定时器定期出现一个点。但是，当我们运行它时，我们看到只打印了一个点：

当中断结束时

原因是PIC希望中断处理程序显示发出“中断结束”(EOI)信号。该信号告诉控制器该中断已被处理，同时系统已经准备好接收下一个中断。因此，PIC认为我们仍在忙于处理第一个计时器中断，并在耐心等待EOI信号，然后才发送下一个中断。

要发送EOI，我们需要再次使用静态PICS结构体：

extern "x86-interrupt" fn timer_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame)
{
    print!(".");

    unsafe {
        PICS.lock()
            .notify_end_of_interrupt(InterruptIndex::Timer.as_u8());
    }
}

notify_end_of_interrupt会推断出是主PIC还是从PIC发送了中断，然后使用command和data端口将EOI信号发送到各控制器。如果是从PIC发送了中断，则需要通知两个PIC，因为从PIC通过输入线连接在主PIC上。

我们需要小心的使用正确的中断向量编号，否则可能会意外删除重要的未发送中断或导致系统挂起。这也是为什么该函数别标记为了非安全。

现在，当我们执行cargo run时，我们会看到点定期出现在屏幕上：

配置计时器

我们使用的硬件计时器叫做可编程间隔计时器，也简称为PIT。顾名思义，我们可以配置两个中断之间的间隔。这里不做详细介绍，因为后文将很快切换到APIC计时器，但是OSDev Wiki上有大量有关配置PIT的文章。

死锁

现在，我们的内核中具有了一种并发形式：定时器中断会异步的发生，因此它们可以随时中断我们的_start函数。幸运的是，Rust的所有权系统可以在编译时就能够防止很多与并发相关的bug。不过，死锁是一个值得注意的例外。如果线程试图获取永远不会释放的锁，则会发生死锁。此时，线程会无限期地挂起。

我们现在就可以在内核中诱发死锁。记住，我们的println宏调用vga_buffer::__print函数，而该函数会用自旋锁锁定全局变量WRITER：

[…]

#[doc(hidden)]
pub fn _print(args: fmt::Arguments) {
    use core::fmt::Write;
    WRITER.lock().write_fmt(args).unwrap();
}

该函数先锁定WRITER再调用其write_fmt，并会在函数末尾隐式将WRITER解锁。现在想象一下，在WRITER锁定时发生了中断，并且中断处理程序也尝试打印一些内容：

时序	`_start`	`interrupt_handler`
0	调用`println!`
1	`print`锁定`WRITER`
2		中断发生，调用中断处理程序
3		调用 `println!`
4		`print`尝试锁定`WRITER`（已被锁定）
5		`print`尝试锁定`WRITER`（已被锁定）
…		...
永不	解锁 `WRITER`

WRITER被锁定，因此中断处理程序会等待锁释放。但这永远不会发生，因为_start函数仅在中断处理程序返回后才继续运行。因此，整个系统挂起。

诱发死锁

通过在_start函数末尾的loop循环中打印一些内容，我们就可以轻松地在内核中引发这种死锁：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    […]
    loop {
        use blog_os::print;
        print!("-");        // new
    }
}

我们看到只有有限的连字符被打印，当第一次定时器中断发生时便停止打印。之后系统挂起，因为计时器中断处理程序在尝试打印点时会死锁。这就是我们在上面的输出中看不到任何点的原因。

每次运行打印的连字符数量会有所不同，因为计时器中断是异步发生的。正是这种不确定性使得与并发相关的bug难以调试。

修复死锁

为了避免发生这种死锁，只要Mutex处于锁定状态，我们就禁用中断：

/// Prints the given formatted string to the VGA text buffer
/// through the global `WRITER` instance.
#[doc(hidden)]
pub fn _print(args: fmt::Arguments) {
    use core::fmt::Write;
    use x86_64::instructions::interrupts;   // new

    interrupts::without_interrupts(|| {     // new
        WRITER.lock().write_fmt(args).unwrap();
    });
}

without_interrupts函数将获取一个闭包并在无中断的环境中执行该闭包。我们使用它来确保只要互斥锁被锁定，就不会发生中断。现在，当我们运行内核时，我们看到它一直在运行而不会挂起。（我们仍然没有注意到任何点，这是因为打印滚动的速度太快。请尝试减慢打印速度，例如，将for _ in 0..10000 {}放置在loop中。）

我们可以对串行打印功能应用相同的更改，以确保不会发生死锁：

#[doc(hidden)]
pub fn _print(args: ::core::fmt::Arguments) {
    use core::fmt::Write;
    use x86_64::instructions::interrupts;       // new

    interrupts::without_interrupts(|| {         // new
        SERIAL1
            .lock()
            .write_fmt(args)
            .expect("Printing to serial failed");
    });
}

请注意，禁用中断并不应该作为通用的解决方案。因为这样做会增加最坏情况下的中断响应时间，即直到系统被允许对中断做出反应之前的时间。因此，只应该在很短的时间内禁用中断。

修复竞争条件

现在如果执行cargo test，可能会看到test_println_output测试失败：

> cargo test --lib
[…]
Running 4 tests
test_breakpoint_exception...[ok]
test_println... [ok]
test_println_many... [ok]
test_println_output... [failed]

Error: panicked at 'assertion failed: `(left == right)`
  left: `'.'`,
 right: `'S'`', src/vga_buffer.rs:205:9

原因是测试与我们的计时器处理程序之间存在竞争条件。回忆一下测试看起来像这样：

#[test_case]
fn test_println_output() {
    let s = "Some test string that fits on a single line";
    println!("{}", s);
    for (i, c) in s.chars().enumerate() {
        let screen_char = WRITER.lock().buffer.chars[BUFFER_HEIGHT - 2][i].read();
        assert_eq!(char::from(screen_char.ascii_character), c);
    }
}

该测试将一个字符串打印到VGA缓冲区，然后通过手动迭代buffer_chars数组来检查输出。由于计时器中断处理程序可能在println之后，读取屏幕字符之前运行（中断处理函数会输出一个.），因此发生竞争状态。请注意，这不是危险的数据竞争，Rust在编译时完全避免了这种竞争。有关详细信息，请参见Rustonomicon。

要解决此问题，我们需要在测试的整个过程中保持WRITER处于锁定状态，以使计时器处理程序无法将.打印到“打印行为”和“读取行为”之间的屏幕上。修复的测试如下所示：

#[test_case]
fn test_println_output() {
    use core::fmt::Write;
    use x86_64::instructions::interrupts;

    let s = "Some test string that fits on a single line";
    interrupts::without_interrupts(|| {
        let mut writer = WRITER.lock();
        writeln!(writer, "\n{}", s).expect("writeln failed");
        for (i, c) in s.chars().enumerate() {
            let screen_char = writer.buffer.chars[BUFFER_HEIGHT - 2][i].read();
            assert_eq!(char::from(screen_char.ascii_character), c);
        }
    });
}

我们进行了以下改进：

显式调用lock()方法，使WRITER在整个测试过程中保持锁定状态。代替println，我们使用writeln宏，该宏允许打印到已经锁定的写入器。
为了避免再次出现死锁，我们在测试期间禁用中断。否则，在WRITER仍处于锁定状态时，测试可能会中断。
由于计时器中断处理程序仍旧可能在测试之前运行，因此在打印字符串s之前，我们还要打印一个换行符\n。这样，即使计时器中断处理程序已经打印出.，我们仍然可以避免测试失败。

通过上述更改，现在可以确定地再次运行cargo test。

这是一个无害的竞争条件，仅可能会导致测试失败。你可以想象，其他竞争条件会由于其不确定性而更加难以调试。幸运的是，Rust帮我们阻止了最严重的竞争条件——数据竞争，该竞争条件会导致各种不确定的行为，包括系统崩溃和静默的内存数据损坏。

`hlt`指令

到目前为止，我们在_start和panic函数的末尾使用了一个简单的空循环语句。这将使得CPU一直在工作，虽然这是代码预期的效果，但这也是非常低效的，因为即使没有任何工作，CPU仍将继续满负荷运行。运行内核时，您可以在任务管理器中观察到此现象：QEMU进程始终需要近100％的CPU使用率。

我们真正想做的是停止CPU，直到下一个中断发生。这期间应允许CPU进入睡眠状态，在该状态下CPU消耗的能量要少得多。hlt指令正是这样做的。让我们使用该指令创建一个节能的无限循环：

pub fn hlt_loop() -> ! {
    loop {
        x86_64::instructions::hlt();
    }
}

instructions::hlt函数只是简单封装了汇编指令。不过这是安全的，因为这个操作并不会损害内存安全。

现在，我们可以使用此hlt_loop代替_start和panic函数中的无限循环：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    […]

    println!("It did not crash!");
    blog_os::hlt_loop();            // new
}


#[cfg(not(test))]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    println!("{}", info);
    blog_os::hlt_loop();            // new
}

把lib.rs也一更新一下：

/// Entry point for `cargo test`
#[cfg(test)]
#[no_mangle]
pub extern "C" fn _start() -> ! {
    init();
    test_main();
    hlt_loop();         // new
}

pub fn test_panic_handler(info: &PanicInfo) -> ! {
    serial_println!("[failed]\n");
    serial_println!("Error: {}\n", info);
    exit_qemu(QemuExitCode::Failed);
    hlt_loop();         // new
}

现在在QEMU中运行内核时，我们发现CPU使用率要低得多。

键盘输入

现在我们已经能够处理来自外部设备的中断了，也终于可以添加对键盘输入的支持了。这是将是我们与内核的首次交互。

请注意，此处我们仅描述如何处理PS/2键盘，而不是USB键盘。但是，主板会将USB键盘模拟为PS/2设备以支持较旧的软件，因此我们可以安心地忽略USB键盘，直到内核中能够提供对USB的支持。

与硬件计时器一样，键盘控制器在默认情况下就是启用状态。因此，当您按下一个键时，键盘控制器会向PIC发送一个中断，然后将其转发给CPU。CPU在IDT中查找处理程序功能，但相应的条目为空。于是会发生双重故障。

因此，让我们为键盘中断添加一个处理函数。这与我们为计时器中断定义处理程序的方式非常相似，只是使用了一个不同的中断编号而已：

#[derive(Debug, Clone, Copy)]
#[repr(u8)]
pub enum InterruptIndex {
    Timer = PIC_1_OFFSET,
    Keyboard, // new
}

lazy_static! {
    static ref IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();
        idt.breakpoint.set_handler_fn(breakpoint_handler);
        […]
        // new
        idt[InterruptIndex::Keyboard.as_usize()]
            .set_handler_fn(keyboard_interrupt_handler);

        idt
    };
}

extern "x86-interrupt" fn keyboard_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame)
{
    print!("k");

    unsafe {
        PICS.lock()
            .notify_end_of_interrupt(InterruptIndex::Keyboard.as_u8());
    }
}

从前面的图可以看出，键盘使用了主PIC的第1行。这意味着它作为中断33（1+偏移量32）到达CPU。将此索引作为InterruptIndex枚举的新变量Keyboard添加。我们并不需要显式指定该值，因为它默认为前一个值加一，也就是33。在中断处理程序中，我们打印一个k并将中断结束信号发送到中断控制器。

现在按下键盘时屏幕上会打印一个k。但是，这仅对我们按的第一个键起作用，此后即使我们继续按键盘也不会在屏幕上打印更多k了。这是因为键盘控制器在我们读取该键所对应的扫描码之前不会再发送下一个中断。

读取扫描码

为了找出按下了哪个键，我们需要查询键盘控制器。通过读取PS/2控制器的数据端口（即I/O端口0x60）来执行此操作：

extern "x86-interrupt" fn keyboard_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame)
{
    use x86_64::instructions::port::Port;

    let mut port = Port::new(0x60);
    let scancode: u8 = unsafe { port.read() };
    print!("{}", scancode);

    unsafe {
        PICS.lock()
            .notify_end_of_interrupt(InterruptIndex::Keyboard.as_u8());
    }
}

我们使用x86_64crate提供的Port类型从键盘的数据端口读取一个字节。该字节称为扫描码，是一个代表按下/释放的键所对应的数字。我们还没有用扫描码做任何事情，只是将其打印在屏幕上：

上图显示了我缓慢键入“123”时的情况。我们看到相邻的键具有相邻的扫描码，并且“按下键”和“释放键”所触发的扫描码并不相同。那么，我们如何将扫描码准确地转换为实际的按键动作呢？

翻译扫描码

扫描码和按键之间有三种不同的映射标准，即所谓的扫描码集。这三个码集都可以追溯到早期IBM计算机的键盘：IBM XT、IBM 3270 PC和IBM AT。值得庆幸的是后来的计算机没有延续这种定义新扫描码集的趋势，而是模拟了现有的扫描码集并进行扩展。如今，大多数键盘都可以配置为模拟这三组中的任意一组。

默认情况下，PS/2键盘模拟扫描代码集1("XT")。在此集中，扫描码字节的低7位定义键，而最高位定义是按下("0")还是释放("1")。那些IBM XT键盘上不存在的键，如Enter键，会连续生成两个扫描代码：一个0xe0转义字节，后接一个代表触发键的字节。有关集合1中所有扫描码及其对应键的表，参见OSDev Wiki。

要将扫描码转换为键，我们可以使用match语句：


extern "x86-interrupt" fn keyboard_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame)
{
    use x86_64::instructions::port::Port;

    let mut port = Port::new(0x60);
    let scancode: u8 = unsafe { port.read() };

    // new
    let key = match scancode {
        0x02 => Some('1'),
        0x03 => Some('2'),
        0x04 => Some('3'),
        0x05 => Some('4'),
        0x06 => Some('5'),
        0x07 => Some('6'),
        0x08 => Some('7'),
        0x09 => Some('8'),
        0x0a => Some('9'),
        0x0b => Some('0'),
        _ => None,
    };
    if let Some(key) = key {
        print!("{}", key);
    }

    unsafe {
        PICS.lock()
            .notify_end_of_interrupt(InterruptIndex::Keyboard.as_u8());
    }
}

上面的代码将翻译数字键0-9，并忽略其他键。它使用match语句为每个扫描码分配一个字符或一个None。然后使用if let语句解构变量key中的字符。通过在模式中使用相同变量名key，我们可以遮蔽先前的声明，这是Rust中解构Option类型的常见写法。

现在我们可以打印数字了：

翻译其他键的方法相同。幸运的是，有一个名为pc-keyboard的crate可用于翻译集1和集2的扫描码，因此我们不必自己实现此功能。要使用crate，请将其添加到Cargo.toml中，然后将其导入lib.rs中：

[dependencies]
pc-keyboard = "0.5.0"

现在，我们可以使用此crate重写我们的keyboard_interrupt_handler：

extern "x86-interrupt" fn keyboard_interrupt_handler(
    _stack_frame: &mut InterruptStackFrame)
{
    use pc_keyboard::{layouts, DecodedKey, HandleControl, Keyboard, ScancodeSet1};
    use spin::Mutex;
    use x86_64::instructions::port::Port;

    lazy_static! {
        static ref KEYBOARD: Mutex<Keyboard<layouts::Us104Key, ScancodeSet1>> =
            Mutex::new(Keyboard::new(layouts::Us104Key, ScancodeSet1,
                HandleControl::Ignore)
            );
    }

    let mut keyboard = KEYBOARD.lock();
    let mut port = Port::new(0x60);

    let scancode: u8 = unsafe { port.read() };
    if let Ok(Some(key_event)) = keyboard.add_byte(scancode) {
        if let Some(key) = keyboard.process_keyevent(key_event) {
            match key {
                DecodedKey::Unicode(character) => print!("{}", character),
                DecodedKey::RawKey(key) => print!("{:?}", key),
            }
        }
    }

    unsafe {
        PICS.lock()
            .notify_end_of_interrupt(InterruptIndex::Keyboard.as_u8());
    }
}

通过lazy_static宏创建一个由Mutex保护的静态Keyboard对象。使用美式键盘布局和扫描码集1初始化Keyboard。HandleControl参数允许将ctrl+[a-z]映射到U+0001至U+001A的Unicode字符上。我们并不想这样做，因此使用Ignore选项来像处理普通键一样处理ctrl。

对于每个中断，我们锁定Mutex，从键盘控制器读取扫描码，并将其传递给add_byte方法，该方法将扫描代码转换为Option<KeyEvent>。KeyEvent包含该键触发的事件，以及究竟是按下事件还是释放事件。

为了翻译此按键事件，我们将其传递给process_keyevent方法，如果可能的话，该方法会将按键事件转换为字符。例如，根据是否按下了Shift键，将A键的按下事件转换为小写字符a或大写A字符。

使用修改后的中断处理程序，我们已经能够输入文本了：

配置键盘

我们可以配置PS/2键盘的某些功能，例如应使用哪个扫描码集。我们不会在这里介绍它，因为这篇文章已经足够长了，但是OSDev Wiki概述了可能的配置命令。

小结

本文解释了如何启用和处理外部设备中断。我们了解了8259 PIC及其主/从布局、中断号的重新映射以及发送“中断结束”信号。我们为硬件计时器和键盘中断实现了处理程序，并了解了hlt指令，该指令能够将CPU暂停，直到下一个中断。

现在，我们可以与内核进行交互，并且初步编写出了一些基础模块，可用于创建小型shell或简单游戏。

下期预告

计时器中断对于操作系统来说至关重要，因为它们提供了一种定期中断运行中的进程并使得内核重新获得控制权的方法。之后，内核就可以切换到另一个进程，并让人们产生多个进程并行执行的错觉。

但是在创建进程或线程之前，我们需要一种为它们分配内存的方法。下一篇文章将探讨内存管理以提供此类基础模块。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 2.2 - 双重故障

Mon, 15 Mar 2021 18:18:00 GMT

:::warning 本文所有内容均为翻译，原文：Double Faults；原项目：Writing an OS in Rust :::

本文将详细探讨双重故障异常，这种异常是在CPU无法调用异常处理程序时发生的。通过处理此异常，我们能够避免导致系统重置的致命三重故障。为了能够在任何情况下防止三重故障，我们还将建立一个中断栈表，以便在单独的内核栈上捕获双重故障。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-06分支中找到。

何为双重故障？

总的来说，双重故障是一种特殊异常，当CPU无法调用异常处理程序时才会诱发这种异常，例如当发生页面错误却并未在中断描述符表（IDT）中注册页面错误处理程序时。这类似于编程语言中用于捕获所有异常的代码块，比如像C++中的catch(...)或是像Java及C#中的catch(Exception e)。

双重故障的行为与普通异常类似。它的向量索引为8，我们可以在IDT中为其定义一个普通的处理函数。提供双重故障处理程序非常重要，因为如果未处理双重故障，则会发生致命的三重故障。三重故障无法被捕获，而大多数硬件对三重故障做出的反应就是系统复位。

触发双重故障

让我们通过触发一个未注册处理函数的异常来引发双重故障：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    blog_os::init();

    // 触发页面错误
    unsafe {
        *(0xdeadbeef as *mut u64) = 42;
    };

    // as before
    #[cfg(test)]
    test_main();

    println!("It did not crash!");
    loop {}
}

我们使用unsafe块向无效地址0xdeadbeef写入数据。虚拟地址未映射到页表中的物理地址，于是发生页面错误。我们尚未在IDT中注册页面错误处理程序，因此发生了双重故障。

现在启动内核时，我们看到它陷入无限重启。重启原因如下：

CPU尝试向0xdeadbeef写入，这将导致页面错误。
CPU查找IDT中的相应条目，发现该条目未指定任何处理函数。因此，它不能调用页面错误处理程序，并诱发双重故障。
CPU查看双重故障处理程序的IDT条目，但该条目同样未指定处理函数。于是，诱发三重故障。
三重故障是致命的。QEMU像大多数真实硬件一样对此做出反应——命令系统重置。

为了防止出现三重故障，我们需要为页面错误提供处理函数，或者为双重故障提供处理函数。我们希望在任何情况下都能够避免三重故障，因此，我们从所有未注册异常都将调用的双重故障入手解决此类问题。

双重故障处理程序

双重故障是一个带有错误码的普通异常，因此我们指定的函数类似于断点处理函数：

lazy_static! {
    static ref IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();
        idt.breakpoint.set_handler_fn(breakpoint_handler);
        idt.double_fault.set_handler_fn(double_fault_handler); // new
        idt
    };
}

// new
extern "x86-interrupt" fn double_fault_handler(
    stack_frame: &mut InterruptStackFrame, _error_code: u64) -> !
{
    panic!("EXCEPTION: DOUBLE FAULT\n{:#?}", stack_frame);
}

处理程序将输出一条简短的错误消息，并转储异常栈帧。双重故障处理程序的错误码始终为零，因此没有必要打印它。与断点处理程序的不同之处在于，双重故障处理程序是发散函数，这是因为x86_64架构禁止从双重故障异常中返回。

现在启动内核时，应该看到调用了双重故障处理程序：

生效了！这次的执行过程如下：

CPU尝试写入0xdeadbeef，这将导致页面错误。
像以前一样，CPU查找IDT中的相应条目，发现未定义任何处理函数，于是诱发双重故障。
CPU跳至我们新注册的双重故障处理程序。

由于CPU现在可以调用双重故障处理程序，因此不再诱发三次故障（无限重启）。

如此简单！那么，为什么我们需要为这一主题撰写一整篇文章呢？好了，我们现在可以捕获大多数双重故障，但是在某些情况下，我们目前的方案仍不够用。

双重故障诱因

在查看特殊情况之前，我们需要知道双重故障的确切诱因。在上一节中我们使用了一个非常模糊的定义：

双重故障是一种特殊异常，当CPU无法调用异常处理程序时才会诱发这种异常。

“无法调用”的确切含义是什么？该处理程序不存在吗？处理程序被换出了吗？如果处理程序本身又导致异常时会发生什么呢？

例如，考虑以下情况发生时：

发生断点异常，但是相应的处理函数被换出时？
发生页面错误，但是页面错误处理程序被换出时？
除零处理程序会导致断点异常，但是该断点处理程序被换出时？
我们的内核栈溢出了，同时命中保护页时？

幸运的是，AMD64手册(PDF)中描述了准确定义（位于第8.2.9节）。根据该描述，“在执行先前（第一个）异常处理程序期间发生第二个异常时，可能会诱发双重故障异常”。这个*“可能”*很重要：只有非常特殊的异常组合才会导致双重故障。这些组合是：

第一个异常	第二个异常
除0错误，<br>无效任务状态段，<br>段不存在，<br>栈段错误，<br>一般性保护错误	无效任务状态段，<br>段不存在，<br>栈段错误，<br>一般性保护错误
页面错误	页面错误，<br>无效任务状态段，<br>段不存在，<br>栈段错误，<br>一般性保护错误

于是，诸如除零错误后接页面错误就相安无事（继续调用页面错误处理程序），但是除零错误后接一般性保护错误就会导致双重故障。

借助此表，我们可以回答上述四个问题中的前三个：

如果发生断点异常，同时相应的处理函数被换出，则会发生页面错误，并调用页面错误处理程序。
如果发生页面错误，同时页面错误处理程序被换出，则会发生双重故障，并调用双重故障处理程序。
如果除零错误处理程序导致断点异常，则CPU会尝试调用断点处理程序。如果断点处理程序被换出，则会发生页面错误并调用页面错误处理程序。

实际上，即使没有在IDT中注册处理函数的异常的情况也遵循此方案：当发生异常时，CPU会尝试读取相应的IDT条目。由于该条目为0，即无效的IDT条目，因此会诱发一般性保护错误。我们也没有为一般保护错误定义处理函数，因此会诱发另一个一般性保护故障。根据上表，这将导致双重故障。

内核栈溢出

让我们看第四个问题：

如果我们的内核栈溢出且命中保护页，会发生什么？

保护页是栈底的特殊内存页，可用来检测栈溢出。该页面未映射到任何物理内存，因此对其进行的访问动作将会导致页面错误，而不是静默的破坏内存其他数据。bootloader为我们的内核栈设置了一个保护页面，因此栈溢出会导致页面错误。

当发生页面错误时，CPU在IDT中查找页面错误处理程序，并尝试将中断栈帧压栈。但是，当前的栈指针仍指向不存在的保护页。于是，发生第二个页面错误，这将导致双重故障（根据上表）。

现在CPU将尝试调用双重故障处理程序。但是，在出现双重故障时，CPU也会尝试压入异常栈帧。此时栈指针仍指向保护页，于是发生第三个页错误，这将导致三重故障并使系统重启。可见，在这种情况下，目前的双重故障处理程序无法避免三重故障。

让我们自己尝试一下！通过调用无限递归函数就可以轻松诱发内核栈溢出：

#[no_mangle] // don't mangle the name of this function
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    blog_os::init();

    fn stack_overflow() {
        stack_overflow(); // 每次递归都会将返回地址压栈
    }

    // 触发栈溢出
    stack_overflow();

    […] // test_main(), println(…), and loop {}
}

当我们在QEMU中运行这段代码时，将看到系统再次陷入无限重启。

那么应该怎样避免这个问题呢？我们不能忽略异常栈帧压栈，因为这是CPU的硬件行为。因此，我们需要确保在发生双重故障时栈不会溢出。幸运的是，x86_64架构可以解决此问题。

切换栈

当发生异常时，x86_64架构能够切换到预定义的已知良好的栈上。此切换发生在硬件级别，因此可以在CPU推送异常栈帧之前执行。

切换机制通过中断栈表(IST)实现。IST是由7个指向已知良好栈的指针组成的表。以Rust伪代码描述类似：

struct InterruptStackTable {
    stack_pointers: [Option<StackPointer>; 7],
}

对于每个异常处理程序，我们可以通过相应IDT条目中的stack_pointers参数在IST中指定一个栈。例如，我们可以将IST中的第一个栈用于双重故障处理程序。此后，每当发生双重故障时，CPU都会自动切换到该栈。该切换将发生在一切压栈动作之前，因此能够防止三重故障。

IST和TSS

中断栈表(IST)是旧时代遗留的结构体任务状态段(TSS)中的一部分。在32位模式下TSS用于保存有关任务的各种信息（如处理器寄存器状态），例如用于硬件上下文切换。但是，在64位模式下不再支持硬件上下文切换，并且TSS的格式已完全更改。

在x86_64上，TSS不再用于保存任务相关信息。现在，它包含两个栈表（IST便是其中之一）。32位和64位TSS之间的唯一公共字段指向I/O port permissions bitmap。

64位TSS具有以下格式：

Field	Type
（保留位）	`u32`
特权栈表	`[u64; 3]`
（保留位）	`u64`
中断栈表	`[u64; 7]`
（保留位）	`u64`
（保留位）	`u16`
I/O映射基地址	`u16`

当特权级别变更时，CPU使用特权栈表。例如，如果在CPU处于用户模式（特权级别3）时发生异常，则在调用异常处理程序之前，CPU通常会切换到内核模式（特权级别0）。在这种情况下，CPU将切换到“特权栈表”中的第0个栈（因为0是目标特权级别）。我们目前还没有任何用户模式程序，因此我们暂时忽略此表。

新建TSS

让我们创建一个新的TSS，并在其中断栈表中包含一个单独的双重故障栈。为此，我们需要一个TSS结构体。幸运的是，x86_64crate已经包含了TaskStateSegment结构体。

我们在新的gdt（稍后会解释这个缩写的意义）模块中创建TSS：

pub mod gdt;

use x86_64::VirtAddr;
use x86_64::structures::tss::TaskStateSegment;
use lazy_static::lazy_static;

pub const DOUBLE_FAULT_IST_INDEX: u16 = 0;

lazy_static! {
    static ref TSS: TaskStateSegment = {
        let mut tss = TaskStateSegment::new();
        tss.interrupt_stack_table[DOUBLE_FAULT_IST_INDEX as usize] = {
            const STACK_SIZE: usize = 4096 * 5;
            static mut STACK: [u8; STACK_SIZE] = [0; STACK_SIZE];

            let stack_start = VirtAddr::from_ptr(unsafe { &STACK });
            let stack_end = stack_start + STACK_SIZE;
            stack_end
        };
        tss
    };
}

这里使用lazy_static是因为Rust的常量求值器还不够强大，无法在编译时进行上面的初始化操作。我们定义第0个IST条目为双重故障栈（换做其他任何IST条目均可）。再将双重故障栈的高位地址写入第0个条目。写入高位地址是因为x86上的栈向下增长，即从高位地址到低位地址（译注：即高位为栈底，低位为栈顶）。

我们尚未实现内存管理，因此目前并没有一个合适的方法能够用于新栈的分配。作为代替，我们使用static mut数组作为栈存储空间。这里需要使用unsafe块，因为在访问可变静态变量时，编译器无法保证数据竞争条件。重要的是它是一个static mut而不是一个普通static，否则bootloader会将其映射到只读页面。我们将在以后的文章中将其替换为适当的栈分配方法，使得这里不再需要unsafe块。

请注意，此双重故障栈并没用以防止栈溢出的保护页面。这意味着我们不应该在双重故障处理程序中执行密集的栈操作，从而导致栈溢出并破坏栈下方的内存。

加载TSS

我们创建了一个新的TSS，现在需要告诉CPU它应该使用这个新TSS。不幸的是，这有点麻烦，因为TSS使用分段系统（出于历史原因）。这里我们不应也不能直接加载表，而应向全局描述符表(GDT)添加新的段描述符。之后，就可以使用相应的GDT索引调用ltr指令来加载我们的TSS。（这就是为什么我们将模块命名为gdt。）

全局描述符表

全局描述符表（GDT）是旧时代遗留下来的，出现在内存分页成为事实上的标准之前，当时用来进行内存分段。不过它仍然在64位模式下的多种操作中起作用，例如内核模式/用户模式的配置或TSS的加载。

GDT是包含程序段的结构体，在内存分页成为标准之前的旧架构中，用于将程序彼此隔离。有关分段的更多信息，请查阅一本名为“Three Easy Pieces”的免费书籍中的同名章节。虽然在64位模式下不再支持分段，但是GDT仍然存在。现在它主要用于两件事：在内核空间和用户空间之间切换，以及加载TSS结构。

创建GDT

让我们创建一个静态GDT，其中包含我们的静态变量TSS：

use x86_64::structures::gdt::{GlobalDescriptorTable, Descriptor};

lazy_static! {
    static ref GDT: GlobalDescriptorTable = {
        let mut gdt = GlobalDescriptorTable::new();
        gdt.add_entry(Descriptor::kernel_code_segment());
        gdt.add_entry(Descriptor::tss_segment(&TSS));
        gdt
    };
}

继续通过lazy_static，用代码段和TSS段创建一个新的GDT。

加载GDT

创建一个新的gdt::init函数用于载GDT，我们再从（译注：lib.rs中的）总init函数中调用该初始化：

pub fn init() {
    GDT.load();
}

pub fn init() {
    gdt::init();
    interrupts::init_idt();
}

现在GDT已加载（因为_start函数调用了总init），但是我们仍然看到栈溢出时的无限重启。

最后一步

此时的问题在于新的GDT段尚未激活，因为段和TSS寄存器仍为旧GDT中的值。我们还需要修改双重故障IDT条目，使其能够使用新栈。

总之，我们需要执行以下操作：

重载代码段寄存器：我们更改了GDT，应该重载代码段寄存器cs。这是必需的，因为旧的段选择器现在可能指向其他GDT描述符（例如TSS描述符）。
加载TSS：我们加载了一个包含TSS选择器的GDT，但是我们仍然需要告诉CPU去使用这个新的TSS。
更新IDT条目：一旦加载了TSS，CPU就能够访问有效的中断栈表(IST)了。然后，通过修改双重故障的IDT条目，就可以告诉CPU它应该使用新的双重故障栈了。

对于前两个步骤，我们需要访问gdt::init函数中的code_selector和tss_selector变量。要使得这两个变量能够被访问，我们可以通过新建Selectors结构体使它们成为静态变量的一部分：

use x86_64::structures::gdt::SegmentSelector;

lazy_static! {
    static ref GDT: (GlobalDescriptorTable, Selectors) = {
        let mut gdt = GlobalDescriptorTable::new();
        let code_selector = gdt.add_entry(Descriptor::kernel_code_segment());
        let tss_selector = gdt.add_entry(Descriptor::tss_segment(&TSS));
        (gdt, Selectors { code_selector, tss_selector })
    };
}

struct Selectors {
    code_selector: SegmentSelector,
    tss_selector: SegmentSelector,
}

现在，可以使用选择器来重载cs段寄存器并加载我们的TSS：

pub fn init() {
    use x86_64::instructions::segmentation::set_cs;
    use x86_64::instructions::tables::load_tss;

    GDT.0.load();
    unsafe {
        set_cs(GDT.1.code_selector);
        load_tss(GDT.1.tss_selector);
    }
}

我们使用set_cs重载代码段寄存器，并使用load_tss加载TSS。这两个函数被标记为unsafe，因此需要在unsafe块中调用——它们可能会因为加载了无效选择器而破坏内存安全。

我们已经加载了有效的TSS和中断堆栈表，现在，可以在IDT中为双重故障处理程序设置栈索引了：

use crate::gdt;

lazy_static! {
    static ref IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();
        idt.breakpoint.set_handler_fn(breakpoint_handler);
        unsafe {
            idt.double_fault.set_handler_fn(double_fault_handler)
                .set_stack_index(gdt::DOUBLE_FAULT_IST_INDEX); // new
        }

        idt
    };
}

set_stack_index方法是非安全的，调用者必须确保使用的索引有效，并且未用于其他异常。

现在，每当发生双重故障时，CPU应该都能切换到双重故障栈。因此，我们能够捕获所有双重故障，包括内核栈溢出：

从现在开始，我们再也不会看到三重故障！为确保我们不会意外地破坏以上操作，我们应该为此添加一个测试。

栈溢出测试

为了测试新写的gdt模块，并确保在栈溢出时正确调用了双重故障处理程序，我们可以添加一个集成测试。大致思路是在测试函数中引发双重故障，以验证是否调用了双重故障处理程序。

让我们从一个最小化的测试程序：

#![no_std]
#![no_main]

use core::panic::PanicInfo;

#[no_mangle]
pub extern "C" fn _start() -> ! {
    unimplemented!();
}

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    blog_os::test_panic_handler(info)
}

就像我们的panic_handler测试一样，该测试将在没有测试环境的条件下运行。这是因为出现双重错误后程序无法继续执行，因此执行多于一个的测试是没有意义的。要禁用测试的测试环境，我们将以下内容添加到我们的Cargo.toml中：

[[test]]
name = "stack_overflow"
harness = false

现在，cargo test --test stack_overflow应该可以编译。当然，运行测试会失败，因为unimplemented宏会引起panic。

实现`_start`

_start函数的实现将会像这样：

use blog_os::serial_print;

#[no_mangle]
pub extern "C" fn _start() -> ! {
    serial_print!("stack_overflow::stack_overflow...\t");

    blog_os::gdt::init();
    init_test_idt();

    // 出发栈溢出
    stack_overflow();

    panic!("Execution continued after stack overflow");
}

#[allow(unconditional_recursion)]
fn stack_overflow() {
    stack_overflow(); // 每次递归都会将返回地址压栈
    volatile::Volatile::new(0).read(); // 防止尾递归优化
}

这里不调用interrupts::init_idt函数，而是调用gdt::init函数来初始化新的GDT，原因是我们要注册一个自定义双重故障处理程序，它将执行exit_qemu(QemuExitCode::Success)退出，而不是直接panic。我们还将调用init_test_idt函数，稍后将对其进行说明。

stack_overflow函数与main.rs中的函数几乎相同。唯一的不同是，我们在函数末尾使用Volatile类型进行了额外的易失性读取，以防止称为尾调用消除的编译器优化。此优化允许编译器将最后一条语句为递归调用的递归函数，从递归调用函数转换为带有循环的普通函数（译注：尾递归优化将递归化为循环）。若有此优化，则递归化为循环后函数将不再会新建额外的栈帧（用于返回地址压栈），于是该函数对于栈的使用将变为常量（译注：循环没有返回地址压栈环节，相较于递归会大幅提升执行效率与资源利用率）。

但是，在我们的情况下，我们的确希望栈溢出的发生，于是我们在函数的末尾添加了一个假的易失性读操作，以禁止编译器删除该语句。因此，该函数不再是尾递归，就可以防止递归转换为循环。我们还添加了allow(unconditional_recursion)属性，以使编译器保持不对这个无限递归的函数发出编译警告。

测试IDT

如上所述，测试需要使用自己的IDT，并自定义双重故障处理程序。实现看起来像这样：

use lazy_static::lazy_static;
use x86_64::structures::idt::InterruptDescriptorTable;

lazy_static! {
    static ref TEST_IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();
        unsafe {
            idt.double_fault
                .set_handler_fn(test_double_fault_handler)
                .set_stack_index(blog_os::gdt::DOUBLE_FAULT_IST_INDEX);
        }

        idt
    };
}

pub fn init_test_idt() {
    TEST_IDT.load();
}

该实现非常类似于我们在interrupts.rs中的IDT。就像在原来的IDT中，给用于双重故障处理程序的IST设置栈索引，以便触发异常时切换到这个已知良好的栈。最后init_test_idt函数通过load方法将IDT加载到CPU上。

双重故障处理程序

唯一缺少的部分是我们的双重故障处理程序。看起来像这样：

use blog_os::{exit_qemu, QemuExitCode, serial_println};
use x86_64::structures::idt::InterruptStackFrame;

extern "x86-interrupt" fn test_double_fault_handler(
    _stack_frame: &mut InterruptStackFrame,
    _error_code: u64,
) -> ! {
    serial_println!("[ok]");
    exit_qemu(QemuExitCode::Success);
    loop {}
}

调用双重故障处理程序时，我们以成功码退出QEMU，该代码将测试标记为已通过。由于集成测试是完全独立的可执行文件，因此我们仍需要在测试文件的顶部设置#![feature(abi_x86_interrupt)]属性。

现在，我们可以通过cargo test --test stack_overflow来运行该测试（或通过cargo test运行所有测试）。不出所料，我们在控制台中看到输出stack_overflow... [ok]。尝试注释掉set_stack_index一行：它应该导致测试失败。

小结

在这篇文章中，我们了解了什么是双重故障以及它将会在在什么情况下会发生。我们添加了一个基本的双重故障处理程序，该处理程序可以打印一条错误消息，并为此添加了集成测试。

我们还启用了硬件支持的双重故障异常上的切换栈功能，这保证了在栈溢出时程序依然能够正常运行。在实现它的过程中，我们了解了任务状态段（TSS）和其中包含的中断堆栈表（IST），以及用于在旧架构上进行内存分段的全局描述符表（GDT）。

下期预告

下一篇文章将介绍如何处理来自外部设备（如计时器，键盘或网络控制器）的中断。这些硬件中断与异常非常相似，比如它们同样也通过IDT调度。但是，与异常不同，它们不会直接出现在CPU上，而是会汇总在中断控制器上，然后根据优先级将它们转发给CPU。在接下来的内容中，我们将探索Intel 8259("PIC")中断控制器，并学习如何实现对键盘的支持。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 1.4 - 测试

Sat, 06 Mar 2021 21:15:00 GMT

:::warning 本文所有内容均为翻译，原文：Testing；原项目：Writing an OS in Rust :::

本篇文章将探讨在no_std环境中，可执行文件的单元和集成测试。我们将利用Rust对自定义测试框架的支持来在内核中执行测试函数。为了输出QEMU的结果，我们将使用QEMU和bootimage工具的其他功能。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-04分支中找到。

需要了解的内容

本文取代了（现已废弃的）单元测试和集成测试这两篇文章。本文将假设你在2019-04-27之后阅读量了A Minimal Rust Kernel一文。目的主要是为了添加.cargo/config.toml文件，设置了默认的编译目标，并设置了cargo run的runner参数。

Rust中的测试

Rust有一个内置的测试框架，它能够在不设置任何东西的情况下执行单元测试。只要创建一个通过断言检查一些结果的函数，并在函数前添加#[test]属性，cargo test就会自动发现并执行该crate中的所有测试函数。

不幸的是，对于像我们的内核这样no_std程序来说，就比较复杂了。问题在于Rust的测试框架隐式地使用了内置的test库，而测试库依赖于标准库。这意味着我们不能为#[no_std]的内核使用默认的测试框架。

当我们尝试在项目中运行cargo test时，可以看到以下报错：

> cargo test
   Compiling blog_os v0.1.0 (/…/blog_os)
error[E0463]: can't find crate for `test`

由于testcrate依赖于标准库，所以它不能用于我们的裸机目标。虽然将testcrate移植到#[no_std]环境中是可行的，但这是非常不稳定的，需要一些黑科技，比如重新定义panic宏。

自定义测试框架

幸运的是，Rust支持通过"unstable"的custom_test_frameworks特性替换默认的测试框架。这个特性下，测试不需要外部库，因此也可以在#[no_std]环境中工作。它的工作原理是收集所有带有#[test_case]属性的函数，然后以测试列表为参数调用用户指定的runner函数。因此，它给了实现者对测试过程尽可能大的控制权。

与默认的测试框架相比，缺少许多默认测试框架具有的高级功能，比如should_panic测试就是不可用的。因此，如果需要的话，要由实现者自己实现这样的功能。这对我们来说是很理想的，因为我们有一个非常特殊的执行环境，在这种环境下，这种高级特性的默认实现可能本来就无法正常工作。例如，#[should_panic]属性依赖于栈展开来捕获panic，但我们恰好禁用了栈展开。

要为我们的内核实现一个自定义测试框架，我们在main.rs中添加以下内容：

#![feature(custom_test_frameworks)]
#![test_runner(crate::test_runner)]

#[cfg(test)]
fn test_runner(tests: &[&dyn Fn()]) {
    println!("Running {} tests", tests.len());
    for test in tests {
        test();
    }
}

我们的runner只是打印一个简短的调试信息，然后调用列表中的每个测试函数。参数类型&[&dyn Fn()]，是由Fn()trait这一trait对象的引用组成的slice。它基本上是一个可以像函数一样调用的类型的引用，所组成的列表。由于这些函数对于非测试用途的cargo run是无用的，所以我们使用#[cfg(test)]属性只在测试中运行它。

现在运行cargo test时，我们看到运行成功了（如果没有成功，请看下面的注意）。然而，我们仍然看到的是"Hello World"，而不是test_runner的消息。原因是_start函数仍然被用作入口点。自定义测试框架功能会生成一个调用test_runner的main函数，但这个函数被忽略了，因为我们使用了#[no_main]属性，并提供了我们自己的入口点。

:::warning[注意] unstable.build-std配置项仅在2020-07-15之后的Rust nightly中提供 :::

目前在cargo中存在一个bug，在某些情况下会导致cargo test中出现"duplicate lang item"的错误。这是由于在Cargo.toml中将某个配置文件设置为了panic = "abort"。尝试删除它，然后cargo test应该就可以正常工作了。更多信息请参见这个cargo issue。

为了解决这个问题，我们首先需要通过reexport_test_harness_main属性将生成的函数名称改为与main不同的名称。然后我们就可以从我们的_start函数中调用重命名的函数了。

#![reexport_test_harness_main = "test_main"]

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    #[cfg(test)]
    test_main();

    loop {}
}

我们将测试框架入口函数的名称设置为test_main，并在_start入口点调用它。我们使用条件编译，只在测试环境中添加对test_main的调用，因为该函数不会在正常cargo run时生成。

当我们现在执行cargo test时，就能在屏幕上看到test_runner打印的"Running 0 tests"。现在就可以创建第一个测试函数了：

#[test_case]
fn trivial_assertion() {
    print!("trivial assertion... ");
    assert_eq!(1, 1);
    println!("[ok]");
}

现在运行cargo test时，便可以看到以下输出：

传递给test_runner函数的test slice现在包含了对trivial_assertion函数的引用。由trivial assertion... [ok]在屏幕上的输出，我们看到测试被调用，并且测试通过了。

执行完测试后，test_runner结束并回到到test_main函数，而这个函数又返回到_start入口点函数。在_start结束前，程序进入了一个死循环，因为入口点函数不允许返回。这是个问题，因为我们希望cargo test在运行完所有测试后能够自动退出。

退出QEMU

现在，_start函数最后是一个死循环，因此，需要在每次执行cargo test时手动关闭QEMU。这很麻烦，因为我们希望在没有用户交互的脚本中运行cargo test。最直观的解决方案是实现一种适当的方式来关闭操作系统。但是实现这个过程比较复杂，因为它需要实现对APM或ACPI电源管理标准的支持。

幸运的是，还有一条捷径。QEMU支持一个特殊的isa-debug-exit设备, 它提供了一个从访客系统中退出QEMU的简单方法。要启用该设备，则需要给QEMU传递一个-device参数。这可以通过在Cargo.toml中添加一个package.metadata.bootimage.test-args配置键来实现：

[package.metadata.bootimage]
test-args = ["-device", "isa-debug-exit,iobase=0xf4,iosize=0x04"]

bootimage runner将为所有可执行测试附加test-args参数到默认QEMU命令中。而对于正常的cargo run，这些参数会被忽略。

连同设备名(isa-debug-exit)，我们传递了iobase和iosize两个参数，这两个参数指定了设备可以从内核到达的I/O端口。

I/O端口

对于x86架构，CPU与外设硬件之间的通信有两种不同的方法，即内存映射I/O和端口映射I/O。我们已经使用内存映射I/O通过内存地址0xb8000来访问VGA文本缓冲区。这个地址不是映射到主存，而是映射到VGA设备上的一些内存。

与内存映射I/O不同，端口映射的I/O使用单独的I/O总线进行通信。每个连接的外设都有一个或多个端口号。为了与这样的I/O端口进行通信，有一种特殊的CPU指令，叫做in和out，这些指令需要指定一个端口号和一个字节数据作为参数（这些指令也有一些变体，允许发送一个u16或u32）。

isa-debug-exit设备使用端口映射的I/O。iobase参数指定设备的端口地址（0xf4是x86的IO总线上的一个一般不使用的端口），iosize指定端口大小（0x04表示4个字节）。

使用退出设备

isa-debug-exit设备的功能非常简单。当一个值被写入iobase所指定的I/O端口时，它会使QEMU以退出状态(value << 1) | 1退出。因此，当我们向该端口写入0时，QEMU将以退出状态(0 << 1) | 1 = 1退出，而当我们向该端口写入1时，将以退出状态(1 << 1) | 1 = 3退出。

我们不需要手动调用in和out汇编指令，直接使用x86_64 crate提供的抽象。在Cargo.toml的dependencies部分添加对该crate的依赖即可。

[dependencies]
x86_64 = "0.13.2"

现在我们可以使用crate提供的Port类型来创建exit_qemu函数了：

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum QemuExitCode {
    Success = 0x10,
    Failed = 0x11,
}

pub fn exit_qemu(exit_code: QemuExitCode) {
    use x86_64::instructions::port::Port;

    unsafe {
        let mut port = Port::new(0xf4);
        port.write(exit_code as u32);
    }
}

该函数在0xf4上创建了一个新Port对象，作为isa-debug-exit设备的iobase。然后将参数退出代码写入该端口。我们使用u32是因为我们指定了isa-debug-exit设备的iosize为4字节。这两种操作都是非安全的，因为向I/O端口写入数据可能会导致不可预知的结果。

为了指定退出状态，我们创建了一个QemuExitCode枚举类型。想要达到的效果是，如果所有的测试都成功了就用成功退出代码退出，否则就用失败退出代码退出。该枚举被标记为#[repr(u32)]，这会强制编译器用一个u32整型来表示该枚举变量。我们用退出码0x10表示成功，0x11表示失败。实际的退出代码并不太重要，只要不与QEMU的默认退出代码冲突即可。例如，使用退出码0表示成功并不是一个好主意，因为它在转换后变成了(0 << 1) | 1 = 1，这就是QEMU运行失败时的默认退出码，这将导致我们无法区分QEMU错误和测试运行成功。

现在就可以更新我们的test_runner了，在所有测试运行后会退出QEMU：

fn test_runner(tests: &[&dyn Fn()]) {
    println!("Running {} tests", tests.len());
    for test in tests {
        test();
    }
    /// new
    exit_qemu(QemuExitCode::Success);
}

我们现在运行cargo test时，看到QEMU在执行完测试后立即关闭。问题是，虽然我们传入了Success退出码，但cargo test却将测试解释为失败：

> cargo test
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
     Running target/x86_64-blog_os/debug/deps/blog_os-5804fc7d2dd4c9be
Building bootloader
   Compiling bootloader v0.5.3 (/home/philipp/Documents/bootloader)
    Finished release [optimized + debuginfo] target(s) in 1.07s
Running: `qemu-system-x86_64 -drive format=raw,file=/…/target/x86_64-blog_os/debug/
    deps/bootimage-blog_os-5804fc7d2dd4c9be.bin -device isa-debug-exit,iobase=0xf4,
    iosize=0x04`
error: test failed, to rerun pass '--bin blog_os'

问题在于，cargo test将除0以外的所有错误代码视为失败。

成功退出码

为了解决这个问题，bootimage提供了一个test-success-exit-code配置键，将指定的退出代码映射到退出代码0。


[package.metadata.bootimage]
test-args = […]
test-success-exit-code = 33         # (0x10 << 1) | 1

有了这个配置，bootimage就会把我们的成功退出码映射到退出码0上，如此，cargo test就会正确识别成功测试，也就不会再把成功测试算作失败了。

我们的测试函数现在会自动关闭QEMU，并能够将正确的测试结果上报。可以看到QEMU窗口瞬间闪过，以至于我们没有足够的时间阅读测试结果。如果能把测试结果打印到控制台就更好了，这样我们在QEMU退出后仍然能看到测试结果。

打印到控制台

为了在控制台上看到测试输出，我们需要以某种方式将数据从内核发送到主机系统。有很多方法可以实现，例如通过TCP网络接口发送数据。然而，设置网络协议栈是一项相当复杂的任务，所以我们将选择一个更简单的解决方案。

串口通信

一个简单的发送数据的方法是使用串口，这是一个古老的接口标准，在现代计算机中已经找不到了。串口协议很容易编程控制，QEMU可以将通过串口发送的字节重定向到主机的标准输出或文件中。

实现串行接口的芯片叫做UART。x86上的UART型号很多，但幸运的是它们之间的区别仅在于一些我们用不到的高级功能。目前常见的UART都能兼容到16550 UART，所以我们的测试框架就选用这个型号。

我们将使用uart_16550 crate来初始化UART并通过串口发送数据。为了将它作为一个依赖项添加，我们更新了Cargo.toml和main.rs：

[dependencies]
uart_16550 = "0.2.0"

uart_16550crate中包含了用以表示UART寄存器的SerialPort结构体，但我们仍然需要自己构造一个实例。为此，我们创建一个新的serial模块，其内容如下：

mod serial;

use uart_16550::SerialPort;
use spin::Mutex;
use lazy_static::lazy_static;

lazy_static! {
    pub static ref SERIAL1: Mutex<SerialPort> = {
        let mut serial_port = unsafe { SerialPort::new(0x3F8) };
        serial_port.init();
        Mutex::new(serial_port)
    };
}

类似VGA文本缓冲区中，使用lazy_static和spinlock来创建静态Writer实例的操作。我们这次通过使用lazy_static，确保init方法在第一次使用时有且仅有一次调用。

与isa-debug-exit设备一样，UART也是使用端口I/O进行编程的。由于UART比较复杂，它使用多个I/O端口来编程不同的设备寄存器。非安全函数SerialPort::new需要UART的第一个I/O端口的地址作为参数，从这个地址就可以计算出所有需要的端口地址。我们传递的是端口地址0x3F8，这是第一个串行接口的标准端口号。

为了使串口便于使用，我们添加了serial_print!和serial_println!宏：

#[doc(hidden)]
pub fn _print(args: ::core::fmt::Arguments) {
    use core::fmt::Write;
    SERIAL1.lock().write_fmt(args).expect("Printing to serial failed");
}

/// Prints to the host through the serial interface.
#[macro_export]
macro_rules! serial_print {
    ($($arg:tt)*) => {
        $crate::serial::_print(format_args!($($arg)*));
    };
}

/// Prints to the host through the serial interface, appending a newline.
#[macro_export]
macro_rules! serial_println {
    () => ($crate::serial_print!("\n"));
    ($fmt:expr) => ($crate::serial_print!(concat!($fmt, "\n")));
    ($fmt:expr, $($arg:tt)*) => ($crate::serial_print!(
        concat!($fmt, "\n"), $($arg)*));
}

这个实现与我们的print和println宏的实现非常相似。由于SerialPort类型已经实现了fmt::Writetrait，因此不需要提供自己的实现。

这次不用再将测试结果打印到VGA文本缓冲区了，现在直接将结果打印到串行接口：

#[cfg(test)]
fn test_runner(tests: &[&dyn Fn()]) {
    serial_println!("Running {} tests", tests.len());
    […]
}

#[test_case]
fn trivial_assertion() {
    serial_print!("trivial assertion... ");
    assert_eq!(1, 1);
    serial_println!("[ok]");
}

注意到serial_println宏直接存在于根命名空间下，这是因为我们使用了#[macro_export]属性。因此，如果通过使用crate::serial::serial_println将无法导入该宏。

QEMU参数

要查看QEMU的串行输出，我们需要使用-serial参数来重定向输出到stdout：

[package.metadata.bootimage]
test-args = [
    "-device", "isa-debug-exit,iobase=0xf4,iosize=0x04", "-serial", "stdio"
]

现在运行cargo test时，直接可以在控制台中看到测试输出：

> cargo test
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running target/x86_64-blog_os/debug/deps/blog_os-7b7c37b4ad62551a
Building bootloader
    Finished release [optimized + debuginfo] target(s) in 0.02s
Running: `qemu-system-x86_64 -drive format=raw,file=/…/target/x86_64-blog_os/debug/
    deps/bootimage-blog_os-7b7c37b4ad62551a.bin -device
    isa-debug-exit,iobase=0xf4,iosize=0x04 -serial stdio`
Running 1 tests
trivial assertion... [ok]

然而，当测试失败时，我们仍然会在QEMU中看到输出，因为我们的panic handler仍然使用println。为了模拟这种情况，我们可以将测试trivial_assertion中的断言改为assert_eq!(0, 1)：

可以看到，panic信息仍然被打印到VGA缓冲区，而其余的测试输出则被打印到串口。panic信息非常有用，所以我们希望也能在控制台中看到这些信息。

Panic时打印错误信息

为了在panic中带着错误信息退出QEMU，我们可以使用条件编译，在测试模式下使用另一个panic处理程序。

// 现有的panic_handler
#[cfg(not(test))] // 新增条件编译属性
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    println!("{}", info);
    loop {}
}

// 测试模式下的panic_handler
#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    serial_println!("[failed]\n");
    serial_println!("Error: {}\n", info);
    exit_qemu(QemuExitCode::Failed);
    loop {}
}

在测试panic处理函数中，我们使用serial_println代替println，然后用失败退出码退出QEMU。请注意，在exit_qemu调用之后，我们仍然需要写一个死循环，因为编译器并不知道在测试模式下isa-debug-exit设备会导致程序退出。

现在，QEMU也会因为测试失败而退出，并在控制台上打印一个有用的错误信息：

> cargo test
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running target/x86_64-blog_os/debug/deps/blog_os-7b7c37b4ad62551a
Building bootloader
    Finished release [optimized + debuginfo] target(s) in 0.02s
Running: `qemu-system-x86_64 -drive format=raw,file=/…/target/x86_64-blog_os/debug/
    deps/bootimage-blog_os-7b7c37b4ad62551a.bin -device
    isa-debug-exit,iobase=0xf4,iosize=0x04 -serial stdio`
Running 1 tests
trivial assertion... [failed]

Error: panicked at 'assertion failed: `(left == right)`
  left: `0`,
 right: `1`', src/main.rs:65:5

现在能够在控制台上看到了所有的测试输出了，我们也不再需要瞬间闪过的QEMU窗口。接下来，我们要完全隐藏它。

隐藏QEMU

通过使用isa-debug-exit设备和串口完成完整的测试结果的上报，现在我们不再需要QEMU窗口了。可以通过给QEMU传递-display none参数来隐藏它：

[package.metadata.bootimage]
test-args = [
    "-device", "isa-debug-exit,iobase=0xf4,iosize=0x04", "-serial", "stdio",
    "-display", "none"
]

现在的QEMU完全在后台运行，不再打开任何窗口。这不仅减少了弹出窗口的干扰，而且还允许我们的测试框架在没有图形用户界面的环境中运行，如CI服务或SSH连接。

超时

由于cargo test会等到测试运行结束才退出，所以一个永不返回的测试会永远的将测试阻塞。这很不幸，但在实践中并不是一个大问题，因为通常很容易避免在测试中写死循环。然而，在我们的案例中，死循环会在各种情况下发生：

bootloader无法加载我们的内核，这会导致系统无休止地重启。
BIOS/UEFI固件无法加载bootloader，同样也会导致无休止地重启。
CPU在我们一些函数的最后进入了loop {}语句，例如因为QEMU退出设备不能正常工作。
硬件导致系统复位，比如CPU异常没有被捕捉到（在以后的文章中会有详细解释）。

由于在很多情况下会出现死循环，bootimage工具默认为每个测试可执行文件设置了5分钟的超时。如果测试没有在这个时间内完成，它就会被标记为失败，并将 "Timed Out"错误打印到控制台。这个功能可以确保陷入死循环的测试不会永远的阻塞cargo test。

可以通过在trivial_assertion测试中加入一个loop {}语句自己尝试一下。当运行cargo test时，你会看到测试在5分钟后被标记为超时。超时时间可以通过Cargo.toml中的test-timeout键来进行配置：

[package.metadata.bootimage]
test-timeout = 300          # (in seconds)

如果你不想等待5分钟trivial_assertion测试超时，可以暂时地降低这个值。

自动插入打印

trivial_assertion测试目前需要使用serial_print!和serial_println!来打印自己的状态信息：

#[test_case]
fn trivial_assertion() {
    serial_print!("trivial assertion... ");
    assert_eq!(1, 1);
    serial_println!("[ok]");
}

为每一个测试手动添加这些打印语句是很麻烦的，升级一下test_runner函数就可以做到自动打印这些消息。要实现这一点，首先需要创建一个新的Testabletrait：

pub trait Testable {
    fn run(&self) -> ();
}

这个技巧是为所有具有Fn()trait的T类型实现这个测试用trait：

impl<T> Testable for T
where
    T: Fn(),
{
    fn run(&self) {
        serial_print!("{}...\t", core::any::type_name::<T>());
        self();
        serial_println!("[ok]");
    }
}

在实现run函数时，首先使用any::type_name函数打印函数名。这个函数在编译器中直接实现，它返回每个类型的字符串描述。对于函数来说，类型就是它们的名字，而这种情况这正是我们希望的。\t字符是制表符tab，为了与[ok]信息进行一定程度的对齐。

打印函数名后，我们使用self()调用测试函数本身。这只是因为我们要求self实现了Fn()trait。在测试函数返回后，我们打印[ok]来表示该函数没有panic。

最后一步是为test_runner升级新特性Testabletrait：

#[cfg(test)]
pub fn test_runner(tests: &[&dyn Testable]) {
    serial_println!("Running {} tests", tests.len());
    for test in tests {
        test.run(); // new
    }
    exit_qemu(QemuExitCode::Success);
}

仅有的两个变化是测试参数的类型从&[&dyn Fn()]变成了&[&dyn Testable]，以及我们现在调用的是test.run()而不是test()。

现在可以从trivial_assertion测试中删除打印语句，因为它们现在是自动打印的：

#[test_case]
fn trivial_assertion() {
    assert_eq!(1, 1);
}

现在cargo test的输出是这样的：

Running 1 tests
blog_os::trivial_assertion...	[ok]

现在函数名包含了函数的完整路径，这在不同模块中的测试函数有相同名称时很有用。其余的输出看起来和原来一样，只不过我们不再需要在测试中手动添加打印语句了。

VGA缓冲区测试

有了一个好用的测试框架，现在我们可以为VGA缓冲区的实现创建一些测试。首先，我们创建一个非常简单的测试来验证println是否能够正常工作：

#[test_case]
fn test_println_simple() {
    println!("test_println_simple output");
}

该测试只是打印一些字符到VGA缓冲区。如果测试没有panic，这意味着println调用也没有panic。

为了确保即使打印了很多行，并且行数多到从屏幕上方移除旧行，也不会发生panic，我们可以创建另一个测试：

#[test_case]
fn test_println_many() {
    for _ in 0..200 {
        println!("test_println_many output");
    }
}

我们还可以创建一个测试函数来验证打印的行是否真的出现在屏幕上：

#[test_case]
fn test_println_output() {
    let s = "Some test string that fits on a single line";
    println!("{}", s);
    for (i, c) in s.chars().enumerate() {
        let screen_char = WRITER.lock().buffer.chars[BUFFER_HEIGHT - 2][i].read();
        assert_eq!(char::from(screen_char.ascii_character), c);
    }
}

该函数指定了一个测试字符串，先使用println打印，然后遍历屏幕字符，也就是静态变量WRITER中代表VGA文本缓冲区的二维数组。由于println打印到最后一行屏幕后立即附加一个换行符，所以字符串应该出现在第BUFFER_HEIGHT - 2行。

利用enumerate函数，使用变量i记录迭代次数，然后用它来从VGA缓冲区二维数组中获取与c对应的字符，通过将屏幕字符的ascii_character与c进行比较，我们确保字符串的每个字符都真正出现在VGA文本缓冲区中。

我们还可以创建更多的测试函数，例如，测试打印很长的行时字符是否被正确封装的函数；或者测试是否能够正确处理换行符、非打印字符、非unicode字符的函数。

然而，在这篇文章的其余部分，我们将解释如何创建集成测试来测试不同组件之间的交互。

集成测试

Rust中集成测试的惯例是把它们放到项目根目录下的tests目录中（即与src目录平级）。默认测试框架和自定义测试框架都会自动识别并执行该目录下的所有测试。

所有的集成测试都是与与main.rs完全分开的单独的可执行文件。这意味着我们需要为每个测试定义一个入口点函数。让我们创建一个名为basic_boot的集成测试示例，仔细看看它是如何工作的：

#![no_std]
#![no_main]
#![feature(custom_test_frameworks)]
#![test_runner(crate::test_runner)]
#![reexport_test_harness_main = "test_main"]

use core::panic::PanicInfo;

#[no_mangle] // don't mangle the name of this function
pub extern "C" fn _start() -> ! {
    test_main();

    loop {}
}

fn test_runner(tests: &[&dyn Fn()]) {
    unimplemented!();
}

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    loop {}
}

由于集成测试是独立的可执行文件，我们需要再次提供所有的crate属性（如no_std、no_main、test_runner等）。我们还需要创建一个新的入口点函数_start，它调用测试入口点函数test_main。我们不需要任何cfg(test)属性，因为集成测试的可执行文件永远不会以非测试模式构建。

我们使用总是panic的unimplemented宏作为test_runner函数的占位符，而且暂时在panic_handler中只做loop。理想情况下，我们希望能像在main.rs中一样使用serial_println宏和exit_qemu函数实现这些函数。问题是，我们无法访问这些函数，因为测试是完全独立于main.rs可执行文件构建的。

如果你在这个阶段运行cargo test，你会得到一个无休止的循环，因为panic_handler会无休止地循环。你需要使用Ctrl+c快捷键来退出QEMU。

创建单独的库

为了使集成测试能够使用所需的功能，我们需要从main.rs中分离出一个库，以供其他crate和集成测试可执行文件使用。为此，我们创建一个新的src/lib.rs文件：

#![no_std]

与main.rs一样，lib.rs也是一个特殊的文件，会被cargo自动识别。这个库是一个独立的编译单元，所以我们需要再次指定#![no_std]属性。

为了使我们的库能与cargo test配合使用，我们还需要将main.rs中的测试函数和属性移到lib.rs中：


#![cfg_attr(test, no_main)]
#![feature(custom_test_frameworks)]
#![test_runner(crate::test_runner)]
#![reexport_test_harness_main = "test_main"]

use core::panic::PanicInfo;

pub trait Testable {
    fn run(&self) -> ();
}

impl<T> Testable for T
where
    T: Fn(),
{
    fn run(&self) {
        serial_print!("{}...\t", core::any::type_name::<T>());
        self();
        serial_println!("[ok]");
    }
}

pub fn test_runner(tests: &[&dyn Testable]) {
    serial_println!("Running {} tests", tests.len());
    for test in tests {
        test.run();
    }
    exit_qemu(QemuExitCode::Success);
}

pub fn test_panic_handler(info: &PanicInfo) -> ! {
    serial_println!("[failed]\n");
    serial_println!("Error: {}\n", info);
    exit_qemu(QemuExitCode::Failed);
    loop {}
}

/// Entry point for `cargo test`
#[cfg(test)]
#[no_mangle]
pub extern "C" fn _start() -> ! {
    test_main();
    loop {}
}

#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    test_panic_handler(info)
}

为了使可执行文件和集成测试能够调用test_runner，我们不对它应用cfg(test)属性，并将其公开。我们还将panic_handler的实现提取到一个公共的test_panic_handler函数中，这样它也可以用于可执行文件。

由于我们的lib.rs是独立于main.rs进行测试的，所以当库以测试模式编译时，我们需要添加一个_start入口点和一个panic_handler。通过使用cfg_attr crate属性，我们在这种情况下有条件地启用no_main属性。

继续将QemuExitCode枚举和exit_qemu函数移出，并将它们公开：

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum QemuExitCode {
    Success = 0x10,
    Failed = 0x11,
}

pub fn exit_qemu(exit_code: QemuExitCode) {
    use x86_64::instructions::port::Port;

    unsafe {
        let mut port = Port::new(0xf4);
        port.write(exit_code as u32);
    }
}

现在，可执行文件和集成测试可以从库中导入这些函数，而不需要定义自己的实现。为了让println和serial_println也能使用，我们把模块的声明也移到了这里：

pub mod serial;
pub mod vga_buffer;

我们将这些模块公开，以使它们可以在库外使用。这也是使println和serial_println宏可用的必要条件，因为它们使用了模块的_print函数。

现在我们可以使用新写好的库更新main.rs：

#![no_std]
#![no_main]
#![feature(custom_test_frameworks)]
#![test_runner(blog_os::test_runner)]
#![reexport_test_harness_main = "test_main"]

use core::panic::PanicInfo;
use blog_os::println;

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    #[cfg(test)]
    test_main();

    loop {}
}

/// This function is called on panic.
#[cfg(not(test))]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    println!("{}", info);
    loop {}
}

#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    blog_os::test_panic_handler(info)
}

这个库可以像普通的外部crate一样使用。调用它就像调用本项目的crate一样，在这里就是blog_os。上面的代码在test_runner属性中使用了blog_os::test_runner函数，在cfg(test)的panic_handler中使用了blog_os::test_panic_handler函数。同时，它还导入了println宏，使其可以用于_start和panic函数。

这时，cargo run和cargo test应该又可以工作了。当然，cargo test仍然会无休止地循环（你可以用Ctrl+c退出）。让我们通过在集成测试中使用所需的库函数来解决这个问题。

完成集成测试

如同src/main.rs一样，我们的tests/basic_boot.rs可执行文件也可以从新库中导入类型。这让我们可以导入缺少的组件来完成集成测试：

#![test_runner(blog_os::test_runner)]

#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    blog_os::test_panic_handler(info)
}

我们不需要重新实现一个测试runner，而是使用我们库中的test_runner函数。对于panic处理器，我们则调用blog_os::test_panic_handler函数，就像我们在main.rs中做的那样。

现在cargo test又正常退出了。当你运行它的时候，你会发现，它分别为lib.rs、main.rs和basic_boot.rs构建和运行测试。对于main.rs和basic_boot集成测试，它报告"Running 0 tests"，因为这些文件没有任何用#[test_case]注释的函数。

现在我们可以在basic_boot.rs中添加测试。例如，我们可以测试println是否能够正常工作，就像我们在VGA缓冲区测试中做的那样：

use blog_os::println;

#[test_case]
fn test_println() {
    println!("test_println output");
}

当我们现在运行cargo test时，我们看到它找到并执行了测试函数。

这个测试现在看起来可能有点无用，因为它几乎和VGA缓冲区的那个测试一模一样。但是，将来我们的main.rs和lib.rs的_start函数可能会扩充新内容，并在运行test_main函数之前调用各种初始化例程，这样两个测试就会在截然不同的环境中执行。

通过在basic_boot环境下测试println，而不调用_start中的任何初始化例程，我们可以确保println在启动后能正常工作。这一点很重要，因为我们需要依靠它来打印panic信息。

测试应该panic的行为

标准库的测试框架支持名为#[should_panic]的属性，以允许构建应该失败的测试。这很有用，例如当传递一个无效参数时，可以验证函数是否会出现错误。不幸的是，#[no_std]的crate并不支持这个属性，因为它需要标准库的支持。

虽然我们不能在内核中使用#[should_panic]属性，但是我们可以通过创建一个集成测试来获得类似的行为，这个测试可以从panic处理程序中获得成功的错误代码。让我们开始创建这样一个名为should_panic的测试：

#![no_std]
#![no_main]

use core::panic::PanicInfo;
use blog_os::{QemuExitCode, exit_qemu, serial_println};

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    serial_println!("[ok]");
    exit_qemu(QemuExitCode::Success);
    loop {}
}

这个测试仍然不完整，因为它还没有定义_start函数或任何自定义测试runner属性。让我们来补充缺失的部分：

#![feature(custom_test_frameworks)]
#![test_runner(test_runner)]
#![reexport_test_harness_main = "test_main"]

#[no_mangle]
pub extern "C" fn _start() -> ! {
    test_main();

    loop {}
}

pub fn test_runner(tests: &[&dyn Fn()]) {
    serial_println!("Running {} tests", tests.len());
    for test in tests {
        test();
        serial_println!("[test did not panic]");
        exit_qemu(QemuExitCode::Failed);
    }
    exit_qemu(QemuExitCode::Success);
}

测试没有复用lib.rs中的test_runner，而是定义了自己的test_runner函数，当测试没有panic并返回时（我们希望测试会产生panic），就以失败码退出。如果没有定义测试函数，runner就会以成功码退出。由于runner总是在运行一个测试后退出，所以定义多个#[test_case]函数是没有意义的。

现在我们可以创建一个应该会失败的测试：

use blog_os::serial_print;

#[test_case]
fn should_fail() {
    serial_print!("should_panic::should_fail...\t");
    assert_eq!(0, 1);
}

测试使用assert_eq来断言0和1相等，这当然会失败，于是测试就可以如愿以偿的panic了。注意，我们需要在这里使用serial_print!手动打印函数名，因为我们没有使用Testabletrait。

当我们通过cargo test --test should_panic运行测试时，我们看到测试是成功的，因为测试如期panic了。当我们注释掉断言一行并再次运行测试时，我们看到它确实失败了，出现了"test did not panic"的消息。

这种方法的一个重要缺点是，它只对单个测试函数有效。对于多个#[test_case]函数，只有第一个函数被执行，因为在调用了panic处理器之后便无法继续执行了。目前我还不知道有什么好的方法来解决这个问题，如果你有什么想法，请告诉我！

无环境测试

对于只有一个测试函数的集成测试（如should_panic测试），其实并不需要测试runner。在这样的情况下，我们可以完全禁用测试runner，并直接在_start函数中运行我们的测试。

其中的关键是在Cargo.toml中禁用测试的harness标志，它定义了集成测试是否使用测试runner。当它被设置为false时，默认的测试runner和自定义测试runner功能都会被禁用，这样测试就会被当作一个普通的可执行文件来处理。

让我们为should_panic测试禁用harness标识：

[[test]]
name = "should_panic"
harness = false

现在，我们通过删除测试runner相关代码，大幅简化了should_panic测试，看起来是这样的：

#![no_std]
#![no_main]

use core::panic::PanicInfo;
use blog_os::{exit_qemu, serial_print, serial_println, QemuExitCode};

#[no_mangle]
pub extern "C" fn _start() -> ! {
    should_fail();
    serial_println!("[test did not panic]");
    exit_qemu(QemuExitCode::Failed);
    loop{}
}

fn should_fail() {
    serial_print!("should_panic::should_fail...\t");
    assert_eq!(0, 1);
}

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    serial_println!("[ok]");
    exit_qemu(QemuExitCode::Success);
    loop {}
}

现在我们直接从_start函数中调用should_fail函数，如果函数能够返回，则以失败码退出。当我们现在运行cargo test --test should_panic时，我们看到测试的行为和之前完全一样。

除了创建should_panic测试外，禁用harness属性对于复杂的集成测试也很有用，例如当各测试函数均有副作用，需要按照指定的顺序运行时。

小结

测试是一种非常有用的技术，可以确保某些组件具有所期望的行为。即使测试不能表明没有bug，但也仍是找到bug的有用工具，尤其是避免回溯。

这篇文章解释了如何为Rust内核建立一个测试框架。我们使用Rust的自定义测试框架功能在裸机环境中实现对简单的＃[test_case]属性的支持。通过使用QEMU的isa-debug-exit设备，测试runner可以在运行测试后退出QEMU并报告测试结果。为了将错误消息打印到控制台而不是VGA缓冲区，我们为串行端口创建了一个基础驱动程序。

在为println宏创建了一些测试之后，我们在后半部分探讨了集成测试。我们了解到集成测试位于tests目录中，并被视为完全独立的可执行文件。为了使他们能够访问exit_qemu函数和serial_println宏，我们将大部分代码移入了一个库，该库可以被所有可执行文件和集成测试导入。由于集成测试在各自独立的环境中运行，因此可以测试与硬件的交互或创建应引起panic的测试。

现在，我们有了一个在QEMU内真实环境中运行的测试框架。通过在以后的文章中创建更多测试，我们可以使内核变得更复杂时依旧保持可维护性。

下期预告

在下一篇文章中，我们将探讨CPU异常。当发生非法事件时，CPU将抛出这些异常，例如除零或访问未映射的内存页面（即所谓的“页面错误”）。能够捕获和检查这些异常对于调试将来的错误非常重要。异常处理也非常类似于硬件中断的处理，这是提供键盘支持所必需的。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 2.1 - CPU异常

Sat, 06 Mar 2021 21:15:00 GMT

:::warning 本文所有内容均为翻译，原文：CPU Exceptions；原项目：Writing an OS in Rust :::

CPU异常发生在多种错误场景中，如在访问无效的内存地址时或是在除零运算时。为了对错误作出反应，我们需要建立一个提供处理函数的中断描述符表。在本文的结尾，我们的内核将能够捕获断点异常并在处理后恢复正常运行。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-05分支中找到。

概述

异常，意味着当前执行的指令有问题。例如，如果当前指令试图除以0，则CPU会发出异常。发生异常时，CPU会中断其当前工作，并根据具体异常的类型，立即调用相应的异常处理函数。

在x86平台上，大概有20种不同的CPU异常类型。其中最重要的是：

页面错误：在执行非法的内存访问时将发生页面错误。例如，若当前指令试图从未映射的页面读取或试图向只读页面写入时。
无效操作码：在当前指令无效时（例如，当我们尝试在不支持的旧CPU上使用较新的SSE指令时）将发生此异常。
常规保护故障：这是异常最常见的诱因。它发生在各种访问冲突中，例如试图在用户级代码中执行特权指令或是向配置寄存器中保留字段进行写入。
双重故障：发生异常时，CPU尝试调用相应的处理函数。如果在调用异常处理函数时又发生另一个异常，则CPU会引发双重故障异常。此外，当没有为某异常注册相应的处理函数时，也会引发这个异常。
三重故障：如果在CPU尝试调用双重故障异常处理函数时又发生异常，则将引发致命的三重故障。我们无法捕捉或处理三重故障。大多数处理器通过复位并重新引导操作系统来对此故障作出反应。

有关异常的完整列表，请查看OSDev Wiki。

中断描述符表

为了捕获和处理异常，我们必须建立一个所谓的中断描述符表(IDT)。在此表中，我们可以为每个CPU异常指定一个处理函数。硬件会直接使用此表，所以我们需要遵循预定义的格式。每个条目必须具有以下的16字节结构：

类型	名称	描述
u16	函数指针 [0:15]	处理函数指针的低(16)位。
u16	GDT 选择子	全局描述符表中的代码段的选择器
u16	选项字段	参见下表
u16	函数指针 [16:31]	处理函数（handler function)指针的中(16)位。
u32	函数指针 [32:63]	处理函数（handler function)指针的高(32)位。
u32	保留位

选项字段具有以下格式：

位	名称	描述
0-2	中断栈表索引	0：不换栈，1-7：当处理函数被调用时，切换到中断栈表的第n个栈。
3-7	保留位
8	0：中断门，1：陷阱门	若此位设置为0，则处理函数被调用的时，中断会被禁用。
9-11	必须为1
12	必须为0
13‑14	特权等级描述符(DPL)	允许调用该处理函数的最小特权等级。
15	条目是否存在

每个异常都有一个预定义的IDT索引。例如，无效操作码异常的表索引为6，而页面错误异常的表索引为14。因此，硬件可以为每个异常自动加载相应的IDT条目。 OSDev wiki中的异常表在"Vector nr."列展示了所有异常的IDT索引。

发生异常时，CPU大致将执行以下操作：

将某些寄存器压栈，包括指令指针和RFLAGS寄存器。（本文接下来将会用到这些值。）
从中断描述符表（IDT）中读取相应的条目。例如，发生页面错误时，CPU读取第14个条目。
检查是否存在该条目。若没有则引发双重故障。
如果该条目是中断门（第40位未置为1），则禁用硬件中断。
将指定的GDT选择器加载到CS段中。
跳转到指定的处理函数。

现在不必担心第4步和第5步，我们将在以后的文章中了解全局描述符表和硬件中断。

IDT类

我们无需自己创建IDT类，可以直接使用x86_64crate的InterruptDescriptorTable结构体，看起来像这样：

#[repr(C)]
pub struct InterruptDescriptorTable {
    pub divide_by_zero: Entry<HandlerFunc>,
    pub debug: Entry<HandlerFunc>,
    pub non_maskable_interrupt: Entry<HandlerFunc>,
    pub breakpoint: Entry<HandlerFunc>,
    pub overflow: Entry<HandlerFunc>,
    pub bound_range_exceeded: Entry<HandlerFunc>,
    pub invalid_opcode: Entry<HandlerFunc>,
    pub device_not_available: Entry<HandlerFunc>,
    pub double_fault: Entry<HandlerFuncWithErrCode>,
    pub invalid_tss: Entry<HandlerFuncWithErrCode>,
    pub segment_not_present: Entry<HandlerFuncWithErrCode>,
    pub stack_segment_fault: Entry<HandlerFuncWithErrCode>,
    pub general_protection_fault: Entry<HandlerFuncWithErrCode>,
    pub page_fault: Entry<PageFaultHandlerFunc>,
    pub x87_floating_point: Entry<HandlerFunc>,
    pub alignment_check: Entry<HandlerFuncWithErrCode>,
    pub machine_check: Entry<HandlerFunc>,
    pub simd_floating_point: Entry<HandlerFunc>,
    pub virtualization: Entry<HandlerFunc>,
    pub security_exception: Entry<HandlerFuncWithErrCode>,
    // some fields omitted
}

这些字段的类型为idt::Entry<F>，这是一个用于表示IDT条目字段的结构体（请参见上面的表格）。泛型参数F定义了预期的处理函数的类型。我们看到有的条目需要HandlerFunc，有的则需要HandlerFuncWithErrCode。而页面错误甚至有其自己的特殊类型：PageFaultHandlerFunc。

首先让我们看一下HandlerFunc类型：

type HandlerFunc = extern "x86-interrupt" fn(_: &mut InterruptStackFrame);

这是extern "x86-interrupt" fn类型的别名。extern关键字定义了一个具有外部调用约定的函数，最常见的是与C代码进行通信(extern "C" fn)的调用约定。不过，此处的x86-interrupt调用约定又是什么？

中断调用约定

异常与函数调用非常相似，都是CPU跳转到被调用函数的第一条指令并执行它。之后，CPU跳转到返回地址并继续执行父函数。

但是，异常和函数调用之间存在主要区别在于，函数调用是被编译器插入的call指令会主动调用的，而异常可能发生在任何指令中。为了了解这种差异的后果，我们需要更详细地研究函数调用。

调用约定明确了函数调用的细节。例如，调用约定指定了函数参数的放置位置（例如，在寄存器中还是在栈中）以及如何返回结果。在x86_64的Linux上，以下规则适用于C函数（在System V ABI中指定）：

前六个整型参数放在在寄存器rdi、rsi、rdx、rcx、r8、r9中传递
其他参数放在栈上传递
结果放在rax和rdx上返回

请注意，Rust不遵循C ABI（实际上甚至还没有Rust ABI），因此这些规则仅适用于extern "C" fn声明的函数。

Preserved寄存器与Scratch寄存器

调用约定将寄存器分为两种：preserved寄存器和scratch寄存器。

在函数调用过程中，preserved寄存器的值必须保持不变。因此，仅当被调用函数("callee")确定能够在返回前恢复寄存器原始值时，才可以写这些寄存器。因此，preserved寄存器称为*“被调用者保存寄存器”*("callee-saved")。一个常见用法是在函数开始时将这些寄存器保存在栈中，并在返回之前将其还原。

相比之下，被调用函数可以无限制地写scratch 寄存器。如果调用者想在函数调用期间保留scratch寄存器的值，则需要在函数调用之前进行备份和还原（如将其压入栈中）。因此，scratch寄存器是*“调用者保存寄存器”*("caller-saved")。

在x86_64上，C调用约定指定以下preserved和scratch寄存器：

preserved寄存器	scratch寄存器
`rbp`, `rbx`, `rsp`, `r12`, `r13`, `r14`, `r15`	`rax`, `rcx`, `rdx`, `rsi`, `rdi`, `r8`, `r9`, `r10`, `r11`
被调用者保存	调用者保存

编译器知道这些规则，因此会生成合适的代码。例如，大多数函数都以push rbp开始，即将rbp备份在栈上（因为它是被调用者保存的寄存器）。

保存所有寄存器

与函数调用不同，任何指令都可能发生异常。在大多数情况下，我们甚至在编译时都不知道生成的代码是否会导致异常。例如，编译器无法知道指令是否会导致栈溢出或页面错误。

由于我们不知道何时发生异常，我们也就无法提前备份任何寄存器。也就是说，调用约定不能以依赖于调用者保存的寄存器的行为作为异常处理程序，而是应该以保存所有寄存器的行为作为异常处理程序。x86-interrupt调用约定就是如此，因此它可以保证在函数返回时所有寄存器值都恢复到原始值。

注意，这并不意味着函数开始时会将所有寄存器都保存到栈中，实际上编译出的代码仅备份会被函数覆盖的寄存器。这样，可以为仅使用几个寄存器的短函数生成非常高效的代码。

中断栈帧

在正常的函数调用中（使用call指令），CPU在跳转到目标函数之前先将返回地址压栈。函数返回时（使用ret指令），CPU将返回地址弹栈并跳转到该地址。因此，普通函数调用的栈帧如下所示：

但是，对于异常和中断处理程序，仅将返回地址压栈是不够的，因为中断处理程序通常在不同的上下文中运行（如栈指针、CPU标志等）。在发生中断时，CPU执行以下步骤：

对齐栈指针：任何指令都可能发生中断，因此栈指针也可以是任何值。但是，某些CPU指令（例如某些SSE指令）要求栈指针在16字节边界上对齐，因此CPU在中断后立即执行此类对齐。
切换栈（在某些情况下）：当CPU特权级别改变时（例如，在用户模式程序中发生CPU异常时），将发生切换栈动作。还可以使用所谓的中断栈表（将在下一篇文章中介绍）为特定的中断配置切换栈。
压入旧栈指针：在发生中断时（对齐之前），CPU压入栈指针(rsp)和栈段(ss)寄存器的值。因此，从中断处理程序返回时，这可以恢复栈指针的原始值。
压入和更新RFLAGS寄存器：RFLAGS寄存器包含各种控制位和状态位。进入中断时，CPU修改一些位并将旧值压栈。
压入指令指针：在跳转到中断处理程序功能之前，CPU先压入指令指针(rip)和代码段(cs)。这相当于普通函数调用时的返回地址压栈。
压入错误码（对于某些异常）：对于某些特定的异常（例如页面错误），CPU压入一个错误码，用于描述异常原因。
调用中断处理函数：CPU从IDT的相应字段读取中断处理函数的地址和段描述符。之后，通过将这些值加载到rip和cs寄存器中来调用中断处理函数。

因此，中断栈帧如下所示：

在x86_64crate中，中断栈帧由InterruptStackFrame结构体表示。结构体被以＆mut的形式传递给中断处理函数，可用于获取异常原因相关信息。该结构体不包含错误码字段，因为只有少数异常会推送错误码。这些少数异常使用单独的HandlerFuncWithErrCode函数类型，该函数类型具有附加的error_code参数。

后台细节

x86-interrupt调用约定是一个强大的抽象，它几乎隐藏了异常处理过程的所有杂乱细节。但是，有时了解幕后的执行细节会很有用。这是x86-interrupt调用约定要处理的事情的简短概述：

取回参数：大多数调用约定都希望参数在寄存器中传递。这对于异常处理程序是不可能的，因为在将参数备份到栈上之前，我们绝不能覆盖任何寄存器。而x86-interrupt调用约定知道这些参数已经以特定的偏移量存放在栈上了。
使用iretq返回：中断栈帧与常规函数调用的栈帧完全不同，这使得我们无法通过常规的ret指令从中断处理函数中返回。相应的我们必须使用iretq指令。
处理错误码：为某些异常而将错误码压栈会使事情变得更加复杂。这会更改栈的对齐方式（请参阅下一点），并且在需要返回前弹栈。x86-interrupt中断调用约定封装了这些复杂过程。但是，它并不知道哪个处理程序函数该用于哪个异常，因此它需要从函数参数的数量中推断出该信息。这意味着程序员仍然有责任为每个异常选择正确的处理函数类型。幸运的是，由x86_64crate定义的InterruptDescriptorTable类型可确保使用正确的函数类型。
栈对齐：有些指令（尤其是SSE指令）需要16字节的栈对齐。CPU会在发生异常时确保这种对齐，但是某些异常会在将错误码压栈后再次破坏对齐。此情况发生时，x86-interrupt调用约定会通过重新对齐栈来解决此问题。

如果你对更多细节感兴趣：我们还有一系列文章，这些文章解释了如何使用文末的裸函数进行异常处理。

实现

现在，我们了解了中断的原理，是时候在内核中处理CPU异常了。我们将从在src/interrupts.rs中创建一个新的中断模块开始，该模块首先新建一个init_idt函数，用于创建一个新的InterruptDescriptorTable实例：

pub mod interrupts;

use x86_64::structures::idt::InterruptDescriptorTable;

pub fn init_idt() {
    let mut idt = InterruptDescriptorTable::new();
}

现在我们可以添加异常处理函数了，首先为断点异常添加处理程序。断点异常是测试异常处理函数的极佳案例。它的唯一用途是在执行断点指令int3时临时暂停程序。

断点异常通常在调试器（debugger）中使用：当用户设置断点时，调试器用int3指令覆盖断点行的原指令，以便在CPU执行到该行时抛出断点异常。当用户想要继续执行程序时，调试器将int3指令再次替换为原指令，然后继续执行程序。有关更多详细信息，请参见“调试器的工作方式”系列。

在我们的例子中，并不需要覆盖任何指令，只需要在执行断点指令时打印一条消息，然后继续执行该程序。因此，让我们创建一个简单的breakpoint_handler函数并将其添加到IDT中：

use x86_64::structures::idt::{InterruptDescriptorTable, InterruptStackFrame};
use crate::println;

pub fn init_idt() {
    let mut idt = InterruptDescriptorTable::new();
    idt.breakpoint.set_handler_fn(breakpoint_handler);
}

extern "x86-interrupt" fn breakpoint_handler(
    stack_frame: &mut InterruptStackFrame)
{
    println!("EXCEPTION: BREAKPOINT\n{:#?}", stack_frame);
}

我们的处理程序仅输出一条消息，并使用pretty-prints样式打印中断栈帧以提升可读性。

尝试对其进行编译会发生以下错误：

error[E0658]: x86-interrupt ABI is experimental and subject to change (see issue #40180)
  --> src/main.rs:53:1
   |
53 | / extern "x86-interrupt" fn breakpoint_handler(stack_frame: &mut InterruptStackFrame) {
54 | |     println!("EXCEPTION: BREAKPOINT\n{:#?}", stack_frame);
55 | | }
   | |_^
   |
   = help: add #![feature(abi_x86_interrupt)] to the crate attributes to enable

发生此错误的原因是x86-interrupt调用约定这一特性仍然处于开发状态，还不稳定。如果一定要使用该特性，则必须通过在lib.rs顶部显示的添加#![feature(abi_x86_interrupt)]。

加载IDT

我们需要使用lidt指令让CPU加载新建的中断描述符表。x86_64crate的InterruptDescriptorTable结构体将该指令封装为load方法。让我们尝试使用它：

pub fn init_idt() {
    let mut idt = InterruptDescriptorTable::new();
    idt.breakpoint.set_handler_fn(breakpoint_handler);
    idt.load();
}

此时编译将出现以下错误：

error: `idt` does not live long enough
  --> src/interrupts/mod.rs:43:5
   |
43 |     idt.load();
   |     ^^^ does not live long enough
44 | }
   | - borrowed value only lives until here
   |
   = note: borrowed value must be valid for the static lifetime...

查看load方法的文档可知，调用该方法的对象应为＆'static self，即该引用变量需要在程序运行时的整个生命周期中保持有效。这是因为CPU在每次中断时都会访问该表，直到我们加载了不同的IDT。因此，使用任何比'static短的生命周期都可能导致“析构后使用”的错误。

而这正是此编译错误的原因。我们的idt创建在栈上，仅在init函数内部有效。该函数结束后，栈空间将重新分配给其他函数，因此CPU可能会将栈空间中的随机内容当做IDT。幸运的是，InterruptDescriptorTable::load方法在其函数定义中声明了生命周期要求，于是Rust编译器能够在编译时防止这种可能的错误。

要解决这个编译错误，我们需要将idt存储在具有'static生命周期的地方。为此，我们通常可以使用Box为IDT在堆上分配空间，再将其转换为'static引用，但是由于我们正在编写OS内核，因此目前并没有堆可用。

作为替代方案，我们可以尝试将IDT存储为static：

static IDT: InterruptDescriptorTable = InterruptDescriptorTable::new();

pub fn init_idt() {
    IDT.breakpoint.set_handler_fn(breakpoint_handler);
    IDT.load();
}

但是这里有一个问题：静态变量是不可变的，因此我们并不能在init函数中修改断点条目。通常可以通过使用static mut解决此问题：

static mut IDT: InterruptDescriptorTable = InterruptDescriptorTable::new();

pub fn init_idt() {
    unsafe {
        IDT.breakpoint.set_handler_fn(breakpoint_handler);
        IDT.load();
    }
}

虽然该方法可以通过编译，但这一用法极为罕见。因为static mut变量非常容易发生数据竞争，导致我们只能在unsafe块中进行对该变量的访问。

使用惰性static救场

幸运的是我们有lazy_static宏。相较于普通静态变量在编译时求值，该宏可以让静态变量在第一次使用时才执行初始化。因此，我们几乎可以在该宏的初始化块中执行任何操作，甚至可以读取运行时的值。

在为VGA文本缓冲区创建抽象时，我们就导入lazy_staticcrate了，这里可以直接使用lazy_static!宏来创建惰性静态IDT：

use lazy_static::lazy_static;

lazy_static! {
    static ref IDT: InterruptDescriptorTable = {
        let mut idt = InterruptDescriptorTable::new();
        idt.breakpoint.set_handler_fn(breakpoint_handler);
        idt
    };
}

pub fn init_idt() {
    IDT.load();
}

留意此处是如何解决使用unsafe块问题的。lazy_static!宏实际上在后台也使用了unsafe块，只是将其封装抽象成了安全接口对外提供。

运行起来

让异常处理在内核中起作用的最后一步是在main.rs中调用init_idt函数。这里我们不选择直接调用该函数，而选择在lib.rs中引入了一个通用的总初始化函数init：

pub fn init() {
    interrupts::init_idt();
}

有了这个函数，我们便可以将初始化例程中各种操作放置于此，这样就能够在main.rs、lib.rs和集成测试中的不同_start函数之间共享这些例程。

现在，我们可以更新main.rs的_start函数以调用init，然后触发断点异常：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    println!("Hello World{}", "!");

    blog_os::init(); // new

    // invoke a breakpoint exception
    x86_64::instructions::interrupts::int3(); // new

    // as before
    #[cfg(test)]
    test_main();

    println!("It did not crash!");
    loop {}
}

当我们在QEMU中运行它（使用cargo run）时，将看到以下内容：

成功了！CPU成功调用了我们的断点处理程序，该断点处理程序将打印消息，然后返回到_start函数，继续打印出It did not crash!。

我们看到，发生异常时，中断栈帧会告诉我们指令指针和栈指针。在调试未预期的异常时，此信息将非常有用。

添加测试

让我们创建一个测试，以确保上述操作持续有效。首先，我们更新_start函数以也调用init：

/// Entry point for `cargo test`
#[cfg(test)]
#[no_mangle]
pub extern "C" fn _start() -> ! {
    init();      // new
    test_main();
    loop {}
}

请记住，运行cargo test --lib时才会使用此_start函数，因为Rust的lib.rs测试完全独立于main.rs。在运行测试之前，我们需要在此处调用init来设置IDT。

现在我们可以创建一个test_breakpoint_exception测试：

#[test_case]
fn test_breakpoint_exception() {
    // invoke a breakpoint exception
    x86_64::instructions::interrupts::int3();
}

该测试调用int3函数来触发断点异常。通过检查之后执行是否继续，我们可以验证断点处理程序是否正常运行。

你可以通过运行cargo test（执行所有测试）或cargo test --lib（仅执行lib.rs及其模块测试）来尝试此新测试。在输出中应该看到以下内容：

blog_os::interrupts::test_breakpoint_exception...	[ok]

使用太多奇妙魔法了吗？

x86-interrupt调用约定和InterruptDescriptorTable类型使异常处理过程相对简单明了。如果这对你来说太神奇了，而你又希望了解异常处理的所有细节，可以继续阅读我们的“使用裸函数处理异常”系列文章，这些文章展示了如何在不使用x86-interrupt调用约定的情况下处理异常，文章还创建了自己的IDT类型。从现在看来，这些旧文章介绍了x86-interrupt调用约定和x86_64crate出现之前的主要异常处理方法。请注意，这些帖子基于此博客的第一版，可能已过时。

下期预告

我们已经成功捕获了第一个异常并从中返回了！下一步是确保你能跟捕获所有异常，因为未捕获的异常会导致致命的三重故障，从而导致系统重置。下一篇文章将要解释如何通过正确捕获双重故障来避免这种情况的发生。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 1.3 - VGA文本模式

Sun, 28 Feb 2021 21:57:00 GMT

:::warning 本文所有内容均为翻译，原文：VGA Text Mode；原项目：Writing an OS in Rust :::

VGA文本模式是一种简单的将文本打印到屏幕上的方法。在这篇文章中，我们将创建一个接口，通过将所有的非安全代码封装在一个单独的模块中，使其使用变得安全和简单。我们还将实现对Rust中格式化宏的支持。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-03分支中找到。

VGA文本缓冲区

在VGA文本模式下，要想把一个字符打印到屏幕上，则需要把它写入VGA硬件的文本缓冲区。VGA文本缓冲区是一个二维数组，通常有25行80列，将直接渲染在屏幕上。每个数组元素通过以下格式描述一个屏幕字符：

位	值
0-7	ASCII 码点
8-11	前景色
12-14	背景色
15	闪烁

第一个字节代表应该用ASCII编码打印的字符。准确地说，它并不完全是ASCII码，而是一个名为代码页437的字符集，并添加了一些额外的字符和轻微的修改。为了简单起见，我们在这篇文章中继续称它为ASCII字符。

第二个字节定义了字符的显示方式。前四位定义前景色，后三位定义背景色，最后一位定义字符是否应该闪烁。以下是可用的颜色：

代码	颜色	代码 + 高亮位	高亮色
0x0	Black	0x8	Dark Gray
0x1	Blue	0x9	Light Blue
0x2	Green	0xa	Light Green
0x3	Cyan	0xb	Light Cyan
0x4	Red	0xc	Light Red
0x5	Magenta	0xd	Pink
0x6	Brown	0xe	Yellow
0x7	Light Gray	0xf	White

第4位是高亮位，例如它能将蓝色高亮变成了浅蓝色。对于背景色，该位被重新用作闪烁位。

VGA文本缓冲区可以通过内存映射I/O访问地址0xb8000。这意味着对该地址的读写不访问RAM，而是直接访问VGA硬件上的文本缓冲区。这意味着我们可以通过正常的内存操作对该地址进行读写。

需要注意的是，内存映射的硬件可能不支持所有正常的RAM操作。例如，一个设备可能只支持按字节读取，当读取一个u64时，就会返回垃圾。幸运的是，文本缓冲区支持正常读写，所以我们不必以特殊的方式对待它。

编写Rust模块

现在我们知道了VGA缓冲区的工作原理，我们可以创建一个Rust模块来处理打印。

mod vga_buffer;

我们创建一个新文件src/vga_buffer.rs来编写这个模块。下面所有的代码都会在我们的新模块中编写（除非另有说明）。

颜色

首先，我们用一个枚举来表示不同的颜色：

#[allow(dead_code)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum Color {
    Black = 0,
    Blue = 1,
    Green = 2,
    Cyan = 3,
    Red = 4,
    Magenta = 5,
    Brown = 6,
    LightGray = 7,
    DarkGray = 8,
    LightBlue = 9,
    LightGreen = 10,
    LightCyan = 11,
    LightRed = 12,
    Pink = 13,
    Yellow = 14,
    White = 15,
}

我们在这里使用一个C型枚举来显式地指定每种颜色的值。由于repr(u8)属性，每个枚举变量都存储为u8。其实4位就够了，但Rust没有u4类型。

通常编译器会对每个未使用的变量发出警告。通过使用#[allow(dead_code)]属性，我们可以禁用Color枚举的这些警告。

通过派生 Copy、Clone、Debug、PartialEq和Eq五个trait，我们实现了类型的复制语义，并使其可打印、可比较。

为了表示指定前景色和背景色的全部色码，我们在u8的基础上创建一个新类型：

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(transparent)]
struct ColorCode(u8);

impl ColorCode {
    fn new(foreground: Color, background: Color) -> ColorCode {
        ColorCode((background as u8) << 4 | (foreground as u8))
    }
}

ColorCode结构体包含完整的颜色字节——前景色和背景色。像之前一样，我们为它派生出Copy和Debug特征。为了确保ColorCode的数据类型布局与u8完全相同，我们使用repr(transparent)属性。

（译者注：关于repr(transparent)，可以参考repr_transparent的解释。）

文本缓冲区

现在我们可以添加结构体来表示屏幕字符和文本缓冲区了：

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
struct ScreenChar {
    ascii_character: u8,
    color_code: ColorCode,
}

const BUFFER_HEIGHT: usize = 25;
const BUFFER_WIDTH: usize = 80;

#[repr(transparent)]
struct Buffer {
    chars: [[ScreenChar; BUFFER_WIDTH]; BUFFER_HEIGHT],
}

由于Rust默认布局下结构体中的字段没有顺序，所以我们需要repr(C)属性。它可以保证Rust结构体的字段布局和C结构体中的字段完全一样，从而保证字段排序的正确性。对于Buffer结构，我们再次使用repr(transparent)来保证它的内存布局与其中的单字段相同。

为了实际写到屏幕上，我们现在创建一个写类型：

pub struct Writer {
    column_position: usize,
    color_code: ColorCode,
    buffer: &'static mut Buffer,
}

写的方式总是写到最后一行，当一行满了的时候（或者遇到\n），就会把行数往上移。column_position字段会跟踪最后一行的实时位置；color_code指定当前的前景色和背景色；buffer中存储一个VGA缓冲区的引用。需要注意的是，我们在这里需要指定一个显式生命周期来告诉编译器这个引用的有效期是多久。'static生命周期指定了引用在整个程序运行时间内都是有效的（这对VGA文本缓冲区来说是事实）。

打印

现在我们可以使用Writer来修改缓冲区的字符。首先我们创建一个方法来写入一个ASCII字节：

impl Writer {
    pub fn write_byte(&mut self, byte: u8) {
        match byte {
            b'\n' => self.new_line(),
            byte => {
                if self.column_position >= BUFFER_WIDTH {
                    self.new_line();
                }

                let row = BUFFER_HEIGHT - 1;
                let col = self.column_position;

                let color_code = self.color_code;
                self.buffer.chars[row][col] = ScreenChar {
                    ascii_character: byte,
                    color_code,
                };
                self.column_position += 1;
            }
        }
    }

    fn new_line(&mut self) {/* TODO */}
}

如果这个字节是换行字节\n，那么writer就不会打印任何内容，而是调用new_line方法，这个方法我们将在后面实现。在第二种匹配情况下，其他字节会被打印到屏幕上。

在打印字节时，writer会检查当前的行是否已满。若当前行已满，需要先调用new_line来结束这一行。然后，它将一个新的ScreenChar写入当前位置的缓冲区。最后，将当前列的位置前进一个字符。

要打印整个字符串，我们可以将它们转换成字节，然后逐一打印：

impl Writer {
    pub fn write_string(&mut self, s: &str) {
        for byte in s.bytes() {
            match byte {
                // 若属于可打印的ASCII字符或换行符，则打印
                0x20..=0x7e | b'\n' => self.write_byte(byte),
                // 若不属于可打印的ASCII字符，则打印0xfe
                _ => self.write_byte(0xfe),
            }

        }
    }
}

VGA文本缓冲区只支持ASCII字符和代码页437的附加字符。Rust字符串默认为UTF-8，所以它们可能包含VGA文本缓冲区不支持的字节。我们使用匹配来区分可打印的ASCII字节（换行或空格符和~字符之间的任何字符）和不可打印的字节。对于不可打印的字节，我们打印一个■字符，它在VGA硬件上的十六进制代码为0xfe。

试试吧

要在屏幕上写一些字符，可以创建一个临时函数：

pub fn print_something() {
    let mut writer = Writer {
        column_position: 0,
        color_code: ColorCode::new(Color::Yellow, Color::Black),
        buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
    };

    writer.write_byte(b'H');
    writer.write_string("ello ");
    writer.write_string("Wörld!");
}

函数首先创建一个新的Writer，指向位于0xb8000的VGA缓冲区，这里的语法看起来可能有点奇怪。首先，我们把整数0xb8000作为一个可变的裸指针。然后我们通过解引用（使用*运算符）将其转换为可变引用，并立即再次借用（通过&mut）。这种转换需要一个unsafe块，因为编译器不能保证裸指针是有效的。

然后它将字节b'H'写入其中。b前缀创建了一个文字字节，它代表一个ASCII字符。通过写入字符串"ello "和"Wörld!"，我们测试了我们的write_string方法和对不可打印字符的处理。为了看到输出，我们需要从_start函数中调用print_something函数：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    vga_buffer::print_something();

    loop {}
}

现在运行项目时，屏幕左下角应该会打印出一个黄色的Hello W■■rld！。

注意到ö被打印成两个■字符。这是因为ö在UTF-8中由两个字节表示，这两个字节都不属于可打印的ASCII范围。实际上这是UTF-8的一个基本属性：多字节值的单个字节永远不是有效的ASCII码。

易失性操作

我们刚刚看到信息被正确打印出来了。然而，它可能无法与未来更加积极优化的Rust编译器一起工作。

问题在于，是我们只对Buffer进行写入，而没有再从中读取。编译器不知道我们的确访问了VGA缓冲区内存（而不是正常内存），也不知道一些字符已经出现在屏幕上的额外效果。所以编译器可能决定这些写入是不必要的，可以省略。为了避免这种错误的优化，我们需要将这些写入指定为易失的。这就告诉编译器，这个写有副作用，不应该被优化掉。

为了对VGA缓冲区使用易失性写，我们使用volatile库。这个crate（在Rust世界中，包是这样称呼的）提供了一个带有read和write方法的Volatile包装类型。这些方法在内部使用了核心库的read_volatile和write_volatile函数，从而保证了读/写操作不会被优化掉。

我们可以通过在Cargo.toml的dependencies部分添加一个对volatilecrate的依赖：

[dependencies]
volatile = "0.2.6"

确保指定volatile版本为0.2.6。新版本的crate不兼容本文。0.2.6是语义版本号。更多信息，请参见cargo文档的指定依赖指南。

让我们用它来进行VGA缓冲区的易失性写入，更新的Buffer类型如下：

use volatile::Volatile;

struct Buffer {
    chars: [[Volatile<ScreenChar>; BUFFER_WIDTH]; BUFFER_HEIGHT],
}

我们现在使用Volatile<ScreenChar>来代替ScreenChar，（Volatile是泛型，几乎可以包装任何类型）。这确保了我们不能通过“普通”的写方法（译者注：如赋值）意外地写入到它。相反，我们现在必须调用write方法。

这意味着我们必须更新Writer::write_byte方法：

impl Writer {
    pub fn write_byte(&mut self, byte: u8) {
        match byte {
            b'\n' => self.new_line(),
            byte => {
                ...

                self.buffer.chars[row][col].write(ScreenChar {
                    ascii_character: byte,
                    color_code,
                });
                ...
            }
        }
    }
    ...
}

我们现在使用的是write方法，而不是使用=的普通赋值。这样可以保证编译器永远不会优化掉这个写操作。

格式化宏

如果能支持Rust的格式化宏就更好了。这样一来，我们就可以轻松地打印不同的类型，如整数或浮点数。接下来，我们需要实现core::fmt::Writetrait。这个trait唯一需要实现方法是write_str，它看起来和我们的write_string方法很相似，只不过返回类型为fmt::Result：

use core::fmt;

impl fmt::Write for Writer {
    fn write_str(&mut self, s: &str) -> fmt::Result {
        self.write_string(s);
        Ok(())
    }
}

Ok(())只是一个包含()类型的Ok Result。

现在我们可以使用Rust内置的write!/writeln!格式化宏了：

pub fn print_something() {
    use core::fmt::Write;
    let mut writer = Writer {
        column_position: 0,
        color_code: ColorCode::new(Color::Yellow, Color::Black),
        buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
    };

    writer.write_byte(b'H');
    writer.write_string("ello! ");
    write!(writer, "The numbers are {} and {}", 42, 1.0/3.0).unwrap();
}

现在你应该在屏幕底部看到Hello! The numbers are 42 and 0.3333333333333333。write!会返回一个Result，如果不使用会引起警告，所以我们在上面调用unwrap函数，如果发生错误，它会panic。现阶段并没有这种问题，因为对VGA缓冲区的写入不会失败。

换行

截至上一节，我们都忽略了换行或字符超出一行容量的情况。遇到这种情况时，我们希望将每个字符向上移动一行（最上面的一行被删除），然后从最后一行的行首重新开始。要做到这一点，我们为Writer的new_line方法添加一个实现：

impl Writer {
    fn new_line(&mut self) {
        for row in 1..BUFFER_HEIGHT {
            for col in 0..BUFFER_WIDTH {
                let character = self.buffer.chars[row][col].read();
                self.buffer.chars[row - 1][col].write(character);
            }
        }
        self.clear_row(BUFFER_HEIGHT - 1);
        self.column_position = 0;
    }

    fn clear_row(&mut self, row: usize) {/* TODO */}
}

我们对所有屏幕字符进行迭代，并将每个字符向上移动一行。请注意，区间范围(..)是前开后闭的。此外，我们也不迭代第0行（第一个循环从1开始），因为它是被移出屏幕的那一行。

为了完成换行代码，我们再添加clear_row方法：

impl Writer {
    fn clear_row(&mut self, row: usize) {
        let blank = ScreenChar {
            ascii_character: b' ',
            color_code: self.color_code,
        };
        for col in 0..BUFFER_WIDTH {
            self.buffer.chars[row][col].write(blank);
        }
    }
}

这个方法通过用空格字符覆盖所有字符来清除一行。

全局接口

提供一个全局Writer作为接口，可以使其他模块免去自己实例化Writer的麻烦，我们试着创建一个静态变量WRITER：

pub static WRITER: Writer = Writer {
    column_position: 0,
    color_code: ColorCode::new(Color::Yellow, Color::Black),
    buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
};

但是，如果我们现在尝试编译它，会出现以下错误：

error[E0015]: calls in statics are limited to constant functions, tuple structs and tuple variants
 --> src/vga_buffer.rs:7:17
  |
7 |     color_code: ColorCode::new(Color::Yellow, Color::Black),
  |                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error[E0396]: raw pointers cannot be dereferenced in statics
 --> src/vga_buffer.rs:8:22
  |
8 |     buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
  |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ dereference of raw pointer in constant

error[E0017]: references in statics may only refer to immutable values
 --> src/vga_buffer.rs:8:22
  |
8 |     buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
  |                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ statics require immutable values

error[E0017]: references in statics may only refer to immutable values
 --> src/vga_buffer.rs:8:13
  |
8 |     buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ statics require immutable values

为了理解这里发生的事情，我们需要知道，与普通变量在运行时初始化不同的是，静态变量是在编译时初始化的。Rust编译器中对此类初始化表达式进行求值的组件叫做 “常量求值器”。虽然它的功能现在还仍然有限，不过对其功能的扩展工作也在进行中，例如RFC“允许常量中的panic”。

关于ColorCode::new的问题可以利用const函数来解决，但这里的根本问题是Rust的常量求值器无法在编译时将原始指针转换为引用。也许未来的某一天将会支持该功能，但在那之前，我们必须找到另一个解决方案。

惰性静态变量

用非常函数一次性初始化静态变量是Rust中常见的问题。幸运的是，在一个名为lazy_static的crate中已经存在一个很好的解决方案。这个crate提供了一个lazy_static!宏，定义了一个惰性初始化的static。static在编译时不计算其的值，而是在第一次被访问时进行惰性初始化。因此，初始化发生在运行时，这使得各种复杂初始化代码成为可能。

让我们在项目中添加lazy_staticcrate。

[dependencies.lazy_static]
version = "1.0"
features = ["spin_no_std"]

我们需要spin_no_std特性，因为我们并没有链接标准库。

有了lazy_static，我们便可以定义静态WRITER：

use lazy_static::lazy_static;

lazy_static! {
    pub static ref WRITER: Writer = Writer {
        column_position: 0,
        color_code: ColorCode::new(Color::Yellow, Color::Black),
        buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
    };
}

然而，这个WRITER并没有什么用，因为它是不可变的，这意味着我们不能向它写任何东西（因为所有的写方法都需要获取&mut self）。一个可能的解决方案是使用一个可变静态变量。但是这样一来，对它的每一次读写都将是不安全的，因为这样很容易引入数据竞争和其他不好的东西。使用static mut是非常不推荐的，以至于有人提议移除这一特性。那么，有没有什么替代方案呢？我们可以尝试使用一个不可变的静态变量加上诸如RefCell甚至UnsafeCell，以提供内部可突变性。但是这些类型不具有Sync特性（有充分的理由），所以我们不能在静态变量中使用它们。

自旋锁

为了获得同步的（即具有Synctrait的）内部可变性，标准库的用户可以使用互斥锁Mutex。它在资源已经被锁定的情况下，通过阻塞线程来提供线程间互斥。但是我们的基本内核没有任何阻塞支持，甚至没有线程的概念，所以我们也无法使用它。然而在计算机科学中，有一种非常基础的互斥，它不需要操作系统的功能：自旋锁。线程不进行阻塞，而只是在一个循环中不停的尝试锁定它，从而消耗CPU时间，直到锁再次释放。

要使自旋锁，我们需要添加spin crate作为依赖：

[dependencies]
spin = "0.5.2"

于是，我们可以使用自旋锁来为我们的静态WRITER添加安全的内部可变性。

use spin::Mutex;
...
lazy_static! {
    pub static ref WRITER: Mutex<Writer> = Mutex::new(Writer {
        column_position: 0,
        color_code: ColorCode::new(Color::Yellow, Color::Black),
        buffer: unsafe { &mut *(0xb8000 as *mut Buffer) },
    });
}

现在我们可以删除临时函数print_something，直接从_start函数中打印：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    use core::fmt::Write;
    vga_buffer::WRITER.lock().write_str("Hello again").unwrap();
    write!(vga_buffer::WRITER.lock(), ", some numbers: {} {}", 42, 1.337).unwrap();

    loop {}
}

我们需要导入fmt::Writetrait来使用它的功能。

安全性

请注意，在我们的代码中，我们只有一个不安全的块，即需要创建一个指向0xb8000的裸指针作为Buffer并进行可变引用。之后，所有的操作都是安全的。Rust默认对数组访问使用边界检查，所以我们不能意外地写到缓冲区之外。因此，我们在类型系统中对所需的条件进行了编码，并且能够向外部提供一个安全的接口。

`println`打印宏

现在我们有了一个全局writer，可以再添加一个println宏，使其可以在代码库的任何地方使用。Rust的宏语法有点奇怪，所以我们不会尝试从头开始写一个宏。让我们先看看标准库中println!宏的源码：

#[macro_export]
macro_rules! println {
    () => (print!("\n"));
    ($($arg:tt)*) => (print!("{}\n", format_args!($($arg)*)));
}

宏是通过一个或多个规则来定义的，这些规则类似于match的匹配分支。println宏有两个规则：第一条规则是没有参数的调用（例如println!()）, 它被扩展为print!("\n"), 因此只是换行。第二条规则是有参数的调用，例如println!("Hello")或println!("Number: {}", 4)。它也是扩展为调用print!宏，传递所有参数，并在结尾处附加一个换行符\n。

#[macro_export]属性使宏可以被整个crate（而不仅仅是其定义所在的模块）和外部crate所使用。它还将宏置于crate根，这意味着我们必须通过使用std::println而不是std::macros::println来进行导入。

而print!宏的定义为：

#[macro_export]
macro_rules! print {
    ($($arg:tt)*) => ($crate::io::_print(format_args!($($arg)*)));
}

该宏扩展为调用io模块中的_print函数。$crate变量保证了这个宏在其他模块中使用时，通过扩展到std的方式，也能在std模块之外工作。

format_args宏使用其中传递的参数中新建一个fmt::Arguments类型，并传递给_print。libstd的_print函数调用print_to，这个函数相当复杂，因为它支持不同的Stdout设备。我们并不需要那么复杂，因为我们只是想打印到VGA缓冲区。

要打印到VGA缓冲区，我们只需复制println!和print!宏，并修改它们以使用我们自己的_print函数：

#[macro_export]
macro_rules! print {
    ($($arg:tt)*) => ($crate::vga_buffer::_print(format_args!($($arg)*)));
}

#[macro_export]
macro_rules! println {
    () => ($crate::print!("\n"));
    ($($arg:tt)*) => ($crate::print!("{}\n", format_args!($($arg)*)));
}

#[doc(hidden)]
pub fn _print(args: fmt::Arguments) {
    use core::fmt::Write;
    WRITER.lock().write_fmt(args).unwrap();
}

我们对原来的println定义做了一个改动，就是在调用print!宏的时候也添加$crate前缀。这确保了如果我们只想使用println时，不需要再导入print!宏。

像标准库中的实现一样，我们为这两个宏都添加了#[macro_export]属性，使它们在我们的crate中随处可用。请注意，此举将宏放在crate的根命名空间中，所以通过使用crate::vga_buffer::println导入它们是行不通的。相反，我们必须使用crate::println。

_print函数获得静态变量WRITER的锁，并对其调用write_fmt方法。这个方法来自Writetrait，我们需要导入那个trait。如果打印不成功，结尾的unwrap()就会panic。但是由于我们总是在write_str中返回Ok，所以这种情况应该不会发生。

由于宏需要能够从模块外部调用_print，所以该函数必须是公共的。但是，由于我们认为这是一个私有的实现细节，所以我们添加了doc(hidden)属性，以在生成的文档中因此该函数的说明。

使用`println`打印Hello World

现在我们可以在_start函数中使用println：

#[no_mangle]
pub extern "C" fn _start() {
    println!("Hello World{}", "!");

    loop {}
}

请注意，我们不必在main函数中导入宏，因为它已经存在于根命名空间中。

正如预期的那样，我们现在看到屏幕上出现了 "Hello World!"：

打印panic信息

现在我们已经有了一个println宏，我们可以在我们的panic函数中使用它来打印panic信息和panic的位置：

/// 函数在panic时被调用
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
    println!("{}", info);
    loop {}
}

当我们现在在_start函数中插入panic!("Some panic message");时，就会得到以下输出：

于是，我们不仅知道产生了panic，还知道panic信息以及它发生在代码的什么地方。

小结

在这篇文章中，我们了解了VGA文本缓冲区的结构，以及如何通过地址0xb8000的内存映射进行写入。我们创建了一个Rust模块，封装了向这个内存映射缓冲区写入数据的非安全操作，并向外部提供了一个安全便捷的接口。

我们也看到了添加第三方库依赖关系是多么的简单，这要感谢cargo工具。我们添加的两个依赖，lazy_static和spin，这两个库在操作系统开发中非常有用，我们会在以后的文章中将有更多的地方用到它们。

下期预告

下一篇文章将解释如何设置Rust的内置单元测试框架，然后我们将为这篇文章中的VGA缓冲模块创建一些基本的单元测试。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 1.2 - 最小化Rust内核

Sun, 21 Feb 2021 17:41:00 GMT

:::warning 本文所有内容均为翻译，原文：A Minimal Rust Kernel；原项目：Writing an OS in Rust :::

在这篇文章中，我们将为x86架构创建一个最小化的64位Rust内核。我们将在上一篇文章的独立Rust二进制程序基础上，创建一个可启动的磁盘映像，并在屏幕上打印一些东西。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-02分支中找到。

启动过程

当您打开计算机时，它开始执行存储在主板ROM中的固件代码。这段代码会执行开机自检，检测可用的RAM，并对CPU和硬件进行预初始化。之后，它寻找一个可启动的磁盘，并开始启动操作系统内核。

在x86上，有两种固件标准："基本输入/输出系统"（BIOS）和较新的 "统一可扩展固件接口"（UEFI）。BIOS标准虽然老旧过时，却较为简单，而且自20世纪80年代以来在任何x86机器上都得到了良好的支持。相比之下，UEFI更现代，功能更多，但设置起来更复杂（至少在我看来）。

目前，我们只提供BIOS支持，但对UEFI的支持也在计划之中。如果你愿意帮助我们，请查看Github issue。

BIOS启动

几乎所有的x86系统都支持BIOS启动，包括使用模拟BIOS的较新的基于UEFI的机器。这是很好的，因为你可以在上世纪的所有机器上使用相同的启动逻辑。但这种广泛的兼容性同时也是BIOS启动的最大缺点，因为这意味着CPU在启动前会被放入一个叫做实模式的16位兼容模式，这样上世纪80年代的老式引导程序仍然可以使用。

让我们从头说起。

当你打开电脑时，它会从位于主板上的一些特殊闪存中加载BIOS。BIOS会运行硬件的自我测试和初始化例程，然后寻找可启动磁盘。如果它找到了一个，控制权就会转移到它的bootloader，这是存储在磁盘开头的512字节的可执行代码部分。大多数的引导加载器都大于512字节，所以引导加载器通常被分成一个小的第一阶段引导程序——刚好512字节——和一个第二阶段引导程序——在第一阶段引导程序之后加载。

引导程序必须确定内核映像在磁盘上的位置，并将其加载到内存中。它还需要先将CPU从16位的实模式切换到32位的保护模式，然后再切换到64位的长模式，在长模式下可以使用64位寄存器和完整的主内存。它的j第三项工作是从BIOS中查询某些信息（如内存映射），并将其传递给操作系统内核。

编写一个bootloader是有点麻烦的，因为它需要汇编语言和很多非深入的步骤，比如 "把这个魔数值写入这个处理器寄存器"。因此，我们在这篇文章中不涉及bootloader的创建，而是提供了一个名为bootimage的工具，它可以自动将bootloader预置到你的内核中。

如果你对构建自己的bootloader感兴趣。请持续关注，一系列关于这个主题的文章已经在计划中了！

Multiboot标准

为了避免每个操作系统都实现自己的bootloader，而bootloader只能与单一操作系统兼容，自由软件基金会在1995年创建了一个名为Multiboot的开放bootloader标准。该标准定义了引导加载器和操作系统之间的接口，因此任何符合Multiboot标准的引导加载器都可以加载任何符合Multiboot标准的操作系统。参考实现是GNU GRUB，它是Linux系统中最流行的引导加载器。

要使内核符合Multiboot的要求，只需要在内核文件的开头插入一个所谓的Multiboot头。这使得在GRUB中启动一个操作系统变得非常容易。然而，GRUB和Multiboot标准也有一些问题：

只支持32位保护模式。这意味着你仍然必须进行CPU配置才能切换到64位长模式。
其设计是为了简化bootloader，而不是简化内核。例如，内核需要链接一个调整后的默认页长度，否则GRUB会找不到Multiboot头。另一个例子是，传递给内核的引导信息，包含了很多依赖于架构的结构，而不是提供清晰的抽象。
GRUB和Multiboot标准的文档支持较少。
GRUB需要安装在主机系统上才能从内核文件中创建一个可启动的磁盘镜像。这使得在Windows或Mac上的开发更加困难。

鉴于此，我们决定不使用GRUB或Multiboot标准。然而，我们计划在我们的bootimage工具中加入对Multiboot的支持，这样就可以在GRUB系统上加载你的内核。如果你对编写一个符合Multiboot标准的内核感兴趣，请查看本系列博客的第一版。

UEFI

(我们目前不提供UEFI支持，但我们很乐意! 如果你愿意帮忙，请在Github issue中告诉我们。)

最小化内核

现在我们已经大致知道了计算机是如何启动的，现在是时候创建我们自己的最小内核了。我们的目标是创建一个磁盘映像，在启动时向屏幕打印 "Hello World!"。为此，我们在上一篇文章中的独立Rust二进制程序基础上进行开发。

你可能还记得，我们通过cargo构建了独立的二进制文件，但根据不同的操作系统，我们需要不同的入口点名称和编译标识。这是因为cargo默认是为主机系统编译，也就是你正在运行的系统。这并不是我们想要的内核，因为一个运行在Windows之上的内核并没有什么意义。相反，我们希望为一个明确定义的目标系统编译。

安装Rust Nightly

Rust有三个发布频道：稳定版、测试版和nightly版。Rust Book很好地解释了这些频道之间的区别，所以花点时间看看吧。为了构建一个操作系统，我们需要一些实验性的功能，而这些功能只有在nightly频道上才有，所以我们需要安装一个nightly版本的Rust。

要管理Rust的安装，我强烈推荐rustup。它允许你并排安装nightly、测试版和稳定版编译器，并使其易于更新。使用rustup，你可以通过运行rustup override set nightly为当前目录使用夜间编译器。或者，你也可以在项目的根目录下添加一个名为rust-toolchain的文件，其内容为nightly。你可以通过运行rustc --version来检查你是否安装了nightly版本。版本号的末尾应该包含-nightly。

nightly编译器允许我们通过在文件顶部使用所谓的特征标识来选择加入各种实验性特征。例如，我们可以通过在main.rs的顶部添加#！[feature(asm)]来启用内联汇编的实验性asm!宏。请注意，这种实验性的特性是完全不稳定的，这意味着未来的Rust版本可能会在没有事先警告的情况下更改或删除它们。因此，我们只有在绝对必要的情况下才会使用它们。

目标配置清单

cargo通过--target参数支持不同的目标系统。目标由所谓的目标系统三元组描述，它描述了CPU架构、厂商、操作系统和ABI。例如，x86_64-unknown-linux-gnu目标三元组描述了一个具有x86_64 CPU、没有明确的供应商、且具有GNU ABI的Linux操作系统的目标系统。Rust支持许多不同的目标三元组，包括Android的arm-linux-androideabi或WebAssembly的wasm32-unknown-unknown。

然而，对于我们的目标系统，我们需要一些特殊的配置参数（比如没有底层操作系统），所以现有的目标三元组都不适合。幸运的是，Rust允许我们通过JSON文件来定义自己的目标三元组。例如，一个描述x86_64-unknown-linux-gnu目标的JSON文件是大概这样的：

{
    "llvm-target": "x86_64-unknown-linux-gnu",
    "data-layout": "e-m:e-i64:64-f80:128-n8:16:32:64-S128",
    "arch": "x86_64",
    "target-endian": "little",
    "target-pointer-width": "64",
    "target-c-int-width": "32",
    "os": "linux",
    "executables": true,
    "linker-flavor": "gcc",
    "pre-link-args": ["-m64"],
    "morestack": false
}

大多数字段是LLVM为该平台生成代码所需要的。例如，data-layout字段定义了各种整数、浮点和指针类型的大小。还有一些Rust用于条件编译的字段，比如target-pointer-width。第三种字段定义了应该如何构建crate。例如，pre-link-args字段指定了传递给链接器的参数。

我们的内核也是以x86_64系统为目标的，所以我们的目标描述文件看起来会和上面的很相似。让我们先创建一个x86_64-blog_os.json文件(选择任何你喜欢的名字)，里面有通用的内容有：

{
    "llvm-target": "x86_64-unknown-none",
    "data-layout": "e-m:e-i64:64-f80:128-n8:16:32:64-S128",
    "arch": "x86_64",
    "target-endian": "little",
    "target-pointer-width": "64",
    "target-c-int-width": "32",
    "os": "none",
    "executables": true
}

请注意，我们将llvm-target中的系统以及os字段中的系统均改为none，因为我们将在裸机上运行。

我们增加以下与build有关的配置项：

"linker-flavor": "ld.lld",
"linker": "rust-lld",

我们不使用平台的默认链接器（可能不支持Linux目标系统），而是使用Rust自带的跨平台LLD链接器来链接我们的内核。

"panic-strategy": "abort",

这个设置指定了目标不支持在panic时进行栈展开，因此程序遇到问题时将直接终止。这和我们Cargo.toml中的panic = "abort"选项一样，所以我们可以从那里删除它。(请注意，与Cargo.toml选项不同的是，这个目标选项在我们后面重新编译core库时通用需要。因此，即使你喜欢保留Cargo.toml里的选项，也一定要添加这个选项。)

"disable-redzone": true,

我们正在编写一个内核，所以我们需要在某些时候处理中断。为了安全起见，我们必须禁用一个叫做“红区”的堆栈指针优化，因为如果不这样做，可能会导致堆栈数据被破坏。更多的信息，请看我们单独的关于禁用红区的文章。

"features": "-mmx,-sse,+soft-float",

fatures字段启用/禁用目标的CPU指令特性。我们在mmx和sse特性前使用减号来禁用它们，在soft-float特性前加加号来启用它。注意不同标志之间不能有空格，否则LLVM无法解释特性字符串。

mmx和sse特性决定了对单指令多数据(SIMD)指令的支持，这通常可以大大提升程序的速度。然而，在操作系统内核中使用大型SIMD寄存器会导致性能问题。原因是内核需要在继续中断的程序之前将所有寄存器恢复到原来的状态。这意味着内核必须在每次系统调用或硬件中断时将完整的SIMD状态保存到主存中。由于SIMD状态非常大（512-1600字节），而且中断可能会非常频繁地发生，这些额外的保存/恢复操作会大大降低性能。为了避免这种情况，我们禁用了内核的SIMD（并不是禁用运行在其上的应用程序的SIMD特性！）。

禁用SIMD的一个问题是，x86_64上的浮点运算默认需要SIMD寄存器。为了解决这个问题，我们增加了soft-float特性，通过基于普通整数的软件函数来模拟所有的浮点运算。

我们撰写了一篇关于禁用SIMD的短文，以供读者深入了解相关信息。

放在一起

现在，我们的目标系统描述文件现在看起来是这样的：

{
  "llvm-target": "x86_64-unknown-none",
  "data-layout": "e-m:e-i64:64-f80:128-n8:16:32:64-S128",
  "arch": "x86_64",
  "target-endian": "little",
  "target-pointer-width": "64",
  "target-c-int-width": "32",
  "os": "none",
  "executables": true,
  "linker-flavor": "ld.lld",
  "linker": "rust-lld",
  "panic-strategy": "abort",
  "disable-redzone": true,
  "features": "-mmx,-sse,+soft-float"
}

编译内核

编译我们的新目标系统将使用Linux惯例（我不太确定为什么，我猜这只是LLVM默认如此）。这意味着我们需要一个名为_start的入口点，就像上一篇文章中描述的那样。

#![no_std] // 不链接Rust标准库
#![no_main] // 禁用所有Rust层级的入口点

use core::panic::PanicInfo;

/// 这个函数将在panic时被调用
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

#[no_mangle] // 不重整函数名
pub extern "C" fn _start() -> ! {
    // 因为编译器会寻找一个名为`_start`的函数，所以这个函数就是入口点
    // 默认命名为`_start`
    loop {}
}

注意，无论你的主机操作系统如何，这个入口点都需应命名为_start。

现在，我们可以给--target参数传入JSON描述文件来为我们的新目标系统构建内核。

> cargo build --target x86_64-blog_os.json

error[E0463]: can't find crate for `core`

编译失败了! 这个错误告诉我们，Rust编译器已经找不到core库了。这个库包含Rust基本类型，如Result、Option、迭代器等，并且隐式地链接到所有no_stdcrates。

这个问题在于，core库是作为预编译库与Rust编译器一起发布的。因此，它只支持预定义的几个目标系统三元组(如x86_64-unknown-linux-gnu)，而不支持我们自定义的目标三元组。如果我们想为其他目标编译代码，我们需要先为这些目标重新编译core库。

`build-std`选项

这就是cargo的build-std选项的作用：它允许按需重新编译core和其他标准库crate，而不是使用Rust安装时附带的预编译版本。这个功能是非常新的，还没有完成，所以它被标记为"unstable"，只在nightly的Rust编译器上可用。

为了使用该特性，我们需要在项目跟目录下新建cargo配置文件.cargo/config.toml，加入内容如下：

[unstable]
build-std = ["core", "compiler_builtins"]

该配置项告诉cargo需要重新编译core和compiler_builtins库，其中compiler_builtins库是编译core库的一个依赖。为了编译这些库，cargo需要读取rust源码，可以通过rustup component add rust-src安装源码组件。

:::tip[注意] unstable.build-std配置项仅在2020-07-15之后的Rust nightly中提供 :::

设置好unstable.build-std配置项并安装rust-src源码组件后，就可以重新运行我们的编译命令：

> cargo build --target x86_64-blog_os.json
   Compiling core v0.0.0 (/…/rust/src/libcore)
   Compiling rustc-std-workspace-core v1.99.0 (/…/rust/src/tools/rustc-std-workspace-core)
   Compiling compiler_builtins v0.1.32
   Compiling blog_os v0.1.0 (/…/blog_os)
    Finished dev [unoptimized + debuginfo] target(s) in 0.29 secs

我们看到cargo build现在为我们的自定义目标重新编译了core、rustc-std-workspace-core(此为compiler_builtins的依赖)和compiler_builtins库。

内存相关的内联函数

Rust编译器假设，在所有的操作系统中，均提供一组内置函数。其中的大多数函数由我们刚才编译的compiler_builtinscrate提供。不过，该crate中有一些内存相关的函数，通常由操作系统的C语言库提供，所以默认为不启用。这些函数包括用以将一个内存块中的所有字节设置为一个给定值的memset，用以将一个内存块复制到另一个内存块的memcpy，以及用来比较两个内存块的memcmp。虽然现在编译我们的内核的时候并不需要这些函数，但是当我们添加更多的代码时（例如在复制结构体的时候），就会用到这些函数。

由于我们无法链接到操作系统的C语言库，所以我们需要另一种方式来向编译器提供这些函数。一个可能的方法是实现我们自己的memset等一系列函数，并为它们添加#[no_mangle]标识（用以避免编译过程中的自动重命名）。不过这相当危险，因为在实现这些函数的过程中稍有差错就会导致程序不可预料的行为。例如，当你使用for循环实现memcpy时，你可能会得到一个无限递归，因为for循环隐式地调用IntoIterator::into_itertrait方法，这可能会再次调用memcpy。所以，重用现有的经过良好测试的实现是个好主意。

幸运的是，compiler_builtinscrate已经包含了所有需要的函数的实现，只是为了不与C语言库中的实现相冲突，它们被默认为禁用了。我们可以通过设置 cargo的build-std-features标识为["compiler-builtins-mem"]来启用它们。与build-std标识一样，这个标识可以在命令行中以-Z标志的形式传递，也可以在.cargo/config.toml文件中的"unstable"域中配置。由于我们总是希望用这个标识来构建，所以配置文件选项对我们来说会更方便：

[unstable]
build-std-features = ["compiler-builtins-mem"]

（compiler-builtins-mem特性是最近才添加的，因此需要2020-09-30后的Rust nightly版本。）

在幕后，这个标志启用了compiler_builtinscrate的mem功能。这样做的效果是，#[no_mangle]属性被应用到crate的memcpy等实现中，使得它们可以被链接器使用。

如此，对编译器要求的所有函数，我们的内核都有了有效的实现，之后即使我们的代码变得更复杂，它也能够通过编译。

设置默认目标

为了避免每次使用cargo xbuild时传递--target参数，我们可以覆写默认的编译目标。继续向cargo配置文件.cargo/config.toml添加以下内容：

[build]
target = "x86_64-blog_os.json"

这里的配置告诉cargo在没有显式声明目标的情况下，使用我们提供的x86_64-blog_os.json作为目标配置。这意味着我们可以直接使用cargo build进行构建。更多关于cargo配置选项的信息，请查看官方文档。

现在我们可以用一个简单的cargo build构建裸金属上的内核了。然而，我们的_start入口点仍然是空的，它将被bootloader调用。是时候输出一些东西到屏幕上了。

在屏幕上打印字符

现阶段将文字打印到屏幕上最简单的方法是使用VGA文字缓冲区。它是一个包含屏幕上显示的内容的特殊的内存区域，直接映射到VGA硬件。它通常由25行组成，每行包含80个字符单元。每个字符单元显示一个ASCII字符，并带有一些前景和背景颜色。屏幕输出的内容是这样的。

我们将在下一篇文章中讨论VGA缓冲区的详情，届时将为它编写第一个小型驱动程序。我们目前仅仅是打印"Hello World!"，只需要知道缓冲区位于地址0xb8000，每个字符单元由一个ASCII字节和一个颜色字节组成。

我们的实现就像这样：

static HELLO: &[u8] = b"Hello World!";

#[no_mangle]
pub extern "C" fn _start() -> ! {
    let vga_buffer = 0xb8000 as *mut u8;

    for (i, &byte) in HELLO.iter().enumerate() {
        unsafe {
            *vga_buffer.offset(i as isize * 2) = byte;
            *vga_buffer.offset(i as isize * 2 + 1) = 0xb;
        }
    }

    loop {}
}

首先，我们将整数0xb8000转成一个裸指针。然后，我们对静态HELLO字节字符串的字节进行迭代。我们使用enumerate方法额外获得迭代索引i，在for循环中，我们使用offset方法写入字符串字节和相应的颜色字节（0xb为淡青色）。

请注意，所有的内存写入操作均放置于unsafe块中。原因是Rust编译器无法推断出我们创建的裸指针是有效的。它们可能指向任何地方并导致数据损坏。通过将它们放入unsafe块，我们基本上是在告诉编译器，我们绝对确信这些操作是有效的。请注意，unsafe块并不会关闭Rust的安全检查。它只允许您做五件额外的事情。

我想强调的是，这不是我们想在Rust中做的事情！在不安全的块内处理裸指针时，很容易出乱子，例如，如果我们不小心，很容易写到缓冲区的末端。

所以我们要尽可能的减少unsafe块的使用。Rust通过创建安全抽象给我们提供了这样的能力。例如，我们可以创建一个VGA缓冲类型，封装所有的不安全操作，并确保不可能从外部进行任何错误调用。这样一来，我们就只需要最少的unsafe块，并且可以确保不违反内存安全。我们将在下一篇文章中创建这样一个安全的VGA缓冲区抽象。

启动内核

现在我们已经有了一个可执行文件，并且可以进行一些可见的操作，是时候运行它了。首先，我们需要将我们编译好的内核通过与bootloader连接，变成一个可引导的磁盘镜像。然后，我们可以在QEMU虚拟机中运行磁盘镜像，或者用U盘在真实的硬件上引导它。

创建引导镜像

为了把编译后的内核变成一个可启动的磁盘镜像，我们需要把它和引导程序连接起来。正如我们在启动过程一节中所学到的，引导程序负责初始化CPU和加载内核。

我们不需要编写自己的bootloader，这是一个独立的项目，我们使用bootloader crate。这个crate实现了一个基本的BIOS引导加载器，没有任何C语言的依赖，只有Rust和内联汇编。为了使用它来启动我们的内核，我们需要添加一个依赖。

[dependencies]
bootloader = "0.9.8"

添加bootloader作为依赖，并不足以真正创建一个可启动的磁盘镜像。其中的问题是，我们需要在编译后将内核与bootloader链接起来，但cargo不支持post-build脚本。

为了解决这个问题，我们创建了一个名为bootimage的工具，它首先编译内核和bootloader，然后将它们连接在一起，创建一个可启动的磁盘镜像。要安装这个工具，请在你的终端上执行以下命令：

cargo install bootimage

为了运行bootimage和构建bootloader，你需要安装llvm-tools-preview rustup组件。你可以通过执行rustup component add llvm-tools-preview来安装。

安装bootimage并添加llvm-tools-preview组件后，我们可以创建可启动磁盘镜像：

> cargo bootimage

我们看到该工具使用cargo build重新编译我们的内核，所以它会自动获取你所做的任何更改。之后，它会编译bootloader，这可能需要一段时间。像所有的crate依赖一样，它只编译一次，然后进行缓存，所以后续的编译速度会快很多。最后，bootimage将bootloader和你的内核结合成一个可启动的磁盘镜像。

执行该命令后，你应该会在target/x86_64-blog_os/debug目录下看到一个名为bootimage-blog_os.bin的可启动磁盘镜像。你可以在虚拟机中启动它，或者将它复制到USB驱动器中，在真正的硬件上启动它。(注意，这不是CD镜像，因为CD镜像有不同的格式，所以刻录到CD上是不行的)。

它是如何工作的？

bootimage工具在后台执行以下步骤：

它将我们的内核编译成ELF文件。
它将bootloader的依赖性编译成一个独立的可执行文件。
它将内核ELF文件按字节链接到bootloader末尾。

当启动时，bootloader读取并解析附加的ELF文件。然后，它将程序段映射到页表中的虚拟地址，将.bss部分归零，并建立一个堆栈。最后，它读取入口点地址（我们的_start函数）并跳转到它。

在QEMU中启动内核

现在我们可以在虚拟机中启动内核了。为了在QEMU中启动内核，我们使用下面的命令：

> qemu-system-x86_64 -drive format=raw,file=target/x86_64-blog_os/debug/bootimage-blog_os.bin
warning: TCG doesn't support requested feature: CPUID.01H:ECX.vmx [bit 5]

这将打开一个单独的窗口与，看起来像这样：

我们看到屏幕上可以看到的"Hello World!"。

在物理机器上运行内核

也可以将其写入U盘，在物理机器上启动：

> dd if=target/x86_64-blog_os/debug/bootimage-blog_os.bin of=/dev/sdX && sync

其中sdX是你的U盘的设备名。请注意选择正确的设备名称，因为该设备上的所有内容都会被覆盖。

将镜像写入U盘后，就可以通过从U盘启动，并在物理硬件上运行它。你可能需要指定启动项或改变BIOS配置中的启动顺序来从U盘启动。需要注意的是，目前它还不能用于UEFI机器，因为bootloader crate还不支持UEFI。

使用`cargo run`

为了方便在QEMU中运行我们的内核，可以设置cargo的runner配置键。

要让在QEMU中运行内核更轻松，我们可以设置在cargo配置文件中设置runner配置项：

[target.'cfg(target_os = "none")']
runner = "bootimage runner"

target.'cfg(target_os = "none")'域适用于所有将目标系统配置文件的"os"字段设置为"none"的目标系统。这将包括我们的x86_64-blog_os.json目标。runner键指定了cargo run应该调用的命令。该命令是在成功编译后运行的，可执行文件的路径将作为第一个参数传递。更多细节请参见cargo文档。

bootimage runner命令是专门设计用作runner配置项的可执行程序使用的，它将链接给定的可执行程序和项目的bootloader依赖关系，然后启动QEMU。更多细节和可能的配置选项请参见bootimage的Readme。

现在我们可以使用cargo run来编译我们的内核，并在QEMU中启动它。

下期预告

在下一篇文章中，我们将更详细地探讨VGA文本缓冲区，并为它编写一个安全的接口。我们还将添加对println宏的支持。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

使用Rust编写操作系统 - 1.1 - Rust独立二进制程序

Sun, 21 Feb 2021 16:56:00 GMT

:::warning 本文所有内容均为翻译，原文：A Freestanding Rust Binary；原项目：Writing an OS in Rust :::

创建我们自己的操作系统内核的第一步，是创建一个不链接标准库的Rust可执行程序。这样就可以在没有底层操作系统的情况下在裸机上运行Rust代码。

这个博客是在GitHub上公开开发的。如果你有任何问题或疑问，请在那里开一个issue。你也可以在底部留言。这篇文章的完整源代码可以在post-01分支中找到。

介绍

要编写操作系统内核，我们需要写出的代码不能依赖任何操作系统提供的功能。这意味着我们不能使用线程、文件、堆内存、网络、随机数、标准输出或任何其他需要操作系统抽象或需要特定硬件的功能。这是有道理的，毕竟我们正在尝试编写自己的操作系统和自己的驱动程序。

这意味着我们不能使用大多数Rust标准库，但是可以使用很多Rust功能。例如，我们可以使用迭代器、闭包、模式匹配、Option、Result、格式化字符串，当然还有所有权系统。这些功能使我们能够以一种非常有表现力的高级方式编写内核，而不必担心未定义行为或内存安全。

为了使用Rust创建OS内核，我们需要创建一个无需底层操作系统即可运行的可执行文件。这种可执行文件通常称为“独立式”或“裸机”可执行文件。

这篇文章描述了创建一个Rust独立二进制文件的必要步骤，并解释了为什么需要这些步骤。如果您仅对一个最小的示例感兴趣，则可以直接跳转至小结部分。

禁用标准库

默认情况下，所有Rust crate都链接标准库，该库建立在操作系统的线程、文件或网络等功能之上。它还依赖于C标准库libc，该库与OS服务紧密交互。我们的计划是编写一个操作系统，因此不能使用任何依赖于OS的库。我们必须通过no_std属性禁用自动引用标准库。

首先创建一个新的cargo项目。最简单的方法是通过命令行：

cargo new blog_os --bin --edition 2018

我将项目命名为blog_os，你当然可以选择自己喜欢的名称。--bin标志意为创建可执行二进制文件（与创建库的--lib不同），而--edition 2018参数指定crate需要使用2018版的Rust。当我们运行命令时，cargo为我们创建以下目录结构：

blog_os
├── Cargo.toml
└── src
    └── main.rs

Cargo.toml包含crate配置，例如crate名称、作者、语义版本号和相关依赖。 src/main.rs文件包含crate的根模块和main函数。您可以通过cargo build来编译crate，然后在target/debug子文件夹中运行已编译的blog_os二进制文件。

`no_std`属性

现在，我们的crate隐式链接了标准库。让我们尝试通过添加no_std属性来禁用此功能：

#![no_std]

fn main() {
    println!("Hello, world!");
}

当我们尝试立即构建（通过运行cargo build）时，会发生以下错误：

error: cannot find macro `println!` in this scope
 --> src/main.rs:4:5
  |
4 |     println!("Hello, world!");
  |     ^^^^^^^

发生此错误是因为println宏是标准库的一部分，我们不能再使用它，也就是说我们无法再打印东西。这是合理的，因为println写入标准输出，这也是由操作系统提供的特殊文件描述符。

那么让我们删除打印语句，然后使用空的main函数再试一次：

#![no_std]

fn main() {}

> cargo build
error: `#[panic_handler]` function required, but not found
error: language item required, but not found: `eh_personality`

现在，编译器指出缺少#[panic_handler]函数和一个语言项。

实现Rust的panic

panic_handler属性定义的函数在发生panic时会被编译器调用。标准库提供了自己的panic处理函数，但那是在no_std环境中，我们需要自己定义它：

use core::panic::PanicInfo;

/// This function is called on panic.
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

PanicInfo类型的参数包含产生panic时的文件和行以及可选的panic消息。该函数永不返回，因此使用!定义函数返回“never”类型，以将其标记为发散函数。目前我们还不能在此函数中执行太多操作，因此在其中写一个无限循环。

`eh_personality`语言项

语言项是编译器内部所需的特殊功能和类型。例如，Copy trait是一种语言项，它告诉编译器哪些类型具有可复制语义。在查看其实现时，会看到特殊的#[lang = "copy"]属性，该属性将其定义为语言项。

虽然我们自己提供语言项的自定义实现是可能的，但仅应将其作为最后的手段。原因是语言项是非常不稳定的实现细节，甚至不会进行类型检查（编译器甚至不检查函数是否具有正确的参数类型）。幸运的是，有一种更稳定的方法可以解决上述的语言项错误。

被eh_personality语言项标记的函数用于实现栈展开功能。默认情况下，在出现panic时，Rust使用栈展开为所有活动的栈变量执行析构函数。这样可以确保释放所有使用的内存，并允许父线程捕获panic并继续执行。但是，栈展开是一个复杂的过程，需要一些特定的OS库支持（例如，Linux上的libunwind或Windows上的结构化异常处理），因此我们不希望将其用于我们的操作系统。

禁用栈展开

在一些其他场景中同样不希望使用栈展开，因此Rust提供了一个选择，可以在发生panic时中止操作。这禁用了栈展开标志信息的生成，也会大大减小二进制程序的大小。禁用栈展开功能有多种方式，最简单的方法是将以下行添加到Cargo.toml中：

[profile.dev]
panic = "abort"

[profile.release]
panic = "abort"

这将为dev profile（用于cargo build）和release profile（用于cargo build --release）设置中止panic策略。现在，编译器应该不提醒缺少eh_personality语言项了。

我们修复了以上两个错误。但是，如果现在尝试编译，则会发生另一个错误：

> cargo build
error: requires `start` lang_item

我们的程序缺少定义入口点的start语言项。

`start`语言项

你可能会认为main函数是程序运行时调用的第一个函数。但是，大多数语言都有一个运行时系统，负责诸如垃圾回收（如Java）或软件线程（如Go中的goroutines）之类的事情。该运行时需要在main函数之前调用，因为它需要初始化自己。

在链接标准库的典型Rust二进制文件中，执行过程从名为crt0("C runtime zero")的C运行时库开始，该库为C应用程序设置了环境。其中包括创建堆栈并将参数放置在正确的寄存器中。然后，C运行时调用Rust运行时的入口点，该入口点被start语言项标记。Rust的运行时非常短，它可以处理一些小事情，例如设置栈溢出防护，或是在panic时打印回溯信息。之后，运行时才会调用main函数。

我们的独立可执行文件无法访问Rust运行时和crt0，因此我们需要定义自己的入口点。自己实现start语言项并没有什么帮助，因为它仍然需要crt0。而我们要做的是直接覆盖crt0入口点。

重写入口点

为了告诉Rust编译器我们不想使用普通的入口点链，需要添加了#![no_main]属性。

#![no_std]
#![no_main]

use core::panic::PanicInfo;

/// This function is called on panic.
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

你可能会注意到，我们删除了main函数，这是因为没有了底层的运行时调用，main就失去意义。而我们现在使用自己的_start函数覆盖操作系统入口点：

#[no_mangle]
pub extern "C" fn _start() -> ! {
    loop {}
}

通过使用#[no_mangle]属性，我们禁用了名称重整，以确保Rust编译器确实输出名称为_start的函数。如果没有该属性，则编译器会生成一些神秘的诸如_ZN3blog_os4_start7hb173fedf945531caE的名称，用以为每个函数赋予唯一的名称。该属性是必需的，因为我们需要在下一步中将入口点函数的名称告知链接器。

我们还必须将函数标记为extern "C"，以告知编译器该函数应使用C调用约定（而不是默认的Rust调用约定）。将函数命名为_start的原因也是因为这是大多数系统的默认入口点名称。

这里的!返回类型表示这是一个发散函数，即永不返回。这是必需的，因为该入口点不会被任何函数调用，而是由操作系统或bootloader直接调用。因此该函数不会返回，而会调用操作系统的退出系统调用。在我们的项目中，关闭计算机可能是一个合理的操作，因为如果独立二进制程序返回后无需执行任何操作。目前，我们也通过无限循环来实现。

现在，当我们运行cargo build时，我们会看到一个难看的链接器错误。

我们使用no_mangle标记这个函数，来对它禁用名称重整（name mangling）——这确保Rust编译器输出一个名为_start的函数；否则，编译器可能最终生成名为_ZN3blog_os4_start7hb173fedf945531caE的函数，无法让链接器正确辨别。

我们还将函数标记为extern "C"，告诉编译器这个函数应当使用C语言的调用约定，而不是Rust语言的调用约定。函数名为_start，是因为大多数系统默认使用这个名字作为入口点名称。

与前文的panic函数类似，这个函数的返回值类型为!——它定义了一个发散函数，或者说一个不允许返回的函数。这一点是必要的，因为这个入口点不将被任何函数调用，但将直接被操作系统或引导程序（bootloader）调用。所以作为函数返回的替换，这个入口点应该调用，比如操作系统提供的exit系统调用（"exit" system call）函数。在我们编写操作系统的情况下，关机应该是一个合适的选择，因为当一个独立式可执行程序返回时，不会留下任何需要做的事情（there is nothing to do if a freestanding binary returns）。暂时来看，我们可以添加一个无限循环，这样可以符合返回值的类型。

如果我们现在编译这段程序，会出来一大段不太好看的链接器错误（linker error）。

链接器错误

链接器是一个将生成的代码组合成可执行文件的程序。由于Linux、Windows和macOS的可执行文件格式不同，因此每个系统都有自己的链接器，引发不同的错误。而错误的本因是相同的：链接器的默认配置假定我们的程序依赖于C运行时，而实际上并非如此。

为了解决这个错误，我们需要告诉链接器它不应该引用C运行时。我们可以通过将一组特定的参数传递给链接器或通过构建裸机目标程序来实现。

构建逻辑目标程序

默认情况下，Rust将尝试构建一个能够在你当前的系统环境中运行的可执行文件。例如，如果你在x86_64硬件上使用Windows，Rust会尝试构建一个使用x86_64指令的.exe Windows可执行程序。该环境也称为您的“宿主机”系统。

Rust使用被称为目标三元组的字符串来描述不同的编译环境。你可以通过运行rustc --version --verbose来查看宿主机的目标三元组：

rustc 1.35.0-nightly (474e7a648 2019-04-07)
binary: rustc
commit-hash: 474e7a6486758ea6fc761893b1a49cd9076fb0ab
commit-date: 2019-04-07
host: x86_64-unknown-linux-gnu
release: 1.35.0-nightly
LLVM version: 8.0

这些输出来自一个x86_64上的Linux系统。我们看到host三元组是x86_64-unknown-linux-gnu，这包括了CPU架构(x86_64)，供应商(unknown)，操作系统linux和ABI(gnu)。

为了以我们的宿主机三元组为目标编译程序，Rust编译器和链接器会假定存在默认情况下使用C运行时的底层操作系统（例如Linux或Windows），而这会导致链接器错误。因此，为避免链接器错误，我们可以针对没有基础操作系统的其他环境进行编译。

这种裸机环境的一个例子是thumbv7em-none-eabihf目标三元组，它描述了嵌入式 ARM系统。细节并不重要，重要的是这个目标中的none表明该目标三元组也没有底层操作系统。为了能够为此目标进行编译，我们需要使用rustup添加这个目标所需文件：

rustup target add thumbv7em-none-eabihf

这将下载系统的标准（和核心）库的。如此，我们可以为该目标构建独立可执行程序了：

cargo build --target thumbv7em-none-eabihf

通过指定--target参数，我们交叉编译了裸机目标系统的可执行程序。由于目标系统并没有操作系统，因此链接程序不会尝试链接C运行时，也因此构建将没有任何链接程序错误，提示构建成功。

这便是我们即将用于OS内核构建的方法。这一次，我们将使用描述x86_64裸机环境的自定义目标三元组来代替thumbv7em-none-eabihf。我们将在下一篇文章中做出详细介绍。

链接器参数

除了以裸机为目标进行编译之外，我们还可以通过将一组特定的参数传递给链接器来解决链接器错误。这不并是我们将用于内核编译的方法，因此本节是可选的，仅出于完整性考虑而提供。

在本小节中，我们讨论在Linux，Windows和macOS上发生的链接器错误，并说明如何通过将其他参数传递给链接器来解决这些错误。请注意，操作系统之间的可执行程序格式和链接器有所不同，因此每个系统都需要不同的参数集。

Linux

在Linux上，发生以下链接程序错误（部分）：

error: linking with `cc` failed: exit code: 1
  |
  = note: "cc" […]
  = note: /usr/lib/gcc/../x86_64-linux-gnu/Scrt1.o: In function `_start':
          (.text+0x12): undefined reference to `__libc_csu_fini'
          /usr/lib/gcc/../x86_64-linux-gnu/Scrt1.o: In function `_start':
          (.text+0x19): undefined reference to `__libc_csu_init'
          /usr/lib/gcc/../x86_64-linux-gnu/Scrt1.o: In function `_start':
          (.text+0x25): undefined reference to `__libc_start_main'
          collect2: error: ld returned 1 exit status

其问题在于，链接器默认情况下引用C运行时的启动例程，也称为_start。这需要已经被no_std属性禁用的C标准库libc中的一些符号，因此链接器无法解析这些引用。为了解决这个问题，我们可以通过传递-nostartfiles参数来告诉链接器它不应链接C启动例程。

其中一种使用cargo向传递链接器参数的方法是cargo rustc命令。该命令的行为与cargo build相同，同时允许将选项传递给底层的Rust编译器rustc。rustc具有-C link-arg标志，该标志将参数传递给链接程序。综上，我们的新构建命令应为：

cargo rustc -- -C link-arg=-nostartfiles

如此，我们的crate便构建为Linux上的独立可执行程序了！

我们并不需要显式指定入口点函数的名称，因为链接器默认情况下就会查找名称为_start的函数。

Windows

在Windows上，发生了另一个链接器错误（部分）：

error: linking with `link.exe` failed: exit code: 1561
  |
  = note: "C:\\Program Files (x86)\\…\\link.exe" […]
  = note: LINK : fatal error LNK1561: entry point must be defined

"entry point must be defined"的错误意味着链接器找不到入口点。在Windows上，默认入口点名称取决于所使用的子系统。对于CONSOLE子系统，链接器将寻找一个名为mainCRTStartup的函数，对于WINDOWS子系统，它将寻找一个名为WinMainCRTStartup的函数。要覆盖默认值以告诉链接器应查找名为_start的函数，可以将/ENTRY参数传递给链接器：

cargo rustc -- -C link-arg=/ENTRY:_start

从不同的参数格式中，我们可以清楚地看到Windows链接器是与Linux链接器完全不同的程序。

现在出现另一个链接器错误：

error: linking with `link.exe` failed: exit code: 1221
  |
  = note: "C:\\Program Files (x86)\\…\\link.exe" […]
  = note: LINK : fatal error LNK1221: a subsystem can't be inferred and must be
          defined

发生该错误的原因是Windows可执行程序可以使用不同的子系统。对于普通程序，根据入口点名称进行推断：如果入口点名为main，则使用CONSOLE子系统；如果入口点名为WinMain，则使用WINDOWS子系统。由于_start函数是另一个名称，因此我们需要显式指定子系统：

cargo rustc -- -C link-args="/ENTRY:_start /SUBSYSTEM:console"

我们在这里使用CONSOLE子系统，指定WINDOWS子系统也可以工作。与其多次传递-C link-arg，不如使用-C link-args，它使用空格分隔的参数列表。

使用这个命令，我们成功的在Windows上构建了可执行程序。

macOS

在macOS上，发生以下链接器错误（部分）：

error: linking with `cc` failed: exit code: 1
  |
  = note: "cc" […]
  = note: ld: entry point (_main) undefined. for architecture x86_64
          clang: error: linker command failed with exit code 1 […]

该错误消息告诉我们，链接器无法找到默认名称为main的入口点函数（由于某些原因，在macOS上所有函数均带有_前缀）。要将入口点设置为·函数，我们需要传递链接器参数-e：

cargo rustc -- -C link-args="-e __start"

-e标志指定入口点函数的名称。由于所有函数在macOS上都有一个附加的_前缀，因此我们需要将入口点设置为__start而不是_start。

这次又出现以下链接器错误：

error: linking with `cc` failed: exit code: 1
  |
  = note: "cc" […]
  = note: ld: dynamic main executables must link with libSystem.dylib
          for architecture x86_64
          clang: error: linker command failed with exit code 1 […]

macOS并不正式支持静态链接的二进制文件，并且默认情况下要求程序链接libSystem库。要覆盖它并链接静态二进制文件，我们将-static标志传递给链接器：

cargo rustc -- -C link-args="-e __start -static"

这仍然不够，出现了第三个链接器错误：

error: linking with `cc` failed: exit code: 1
  |
  = note: "cc" […]
  = note: ld: library not found for -lcrt0.o
          clang: error: linker command failed with exit code 1 […]

该错误出现的原因是在默认情况下macOS上的程序链接到crt0("C runtime zero")。这类似于我们在Linux上遇到的错误，也可以通过添加-nostartfiles链接器参数来解决：

cargo rustc -- -C link-args="-e __start -static -nostartfiles"

现在我们的程序应该可以在macOS上成功构建了。

统一构建命令

现在，根据主机平台，我们有不同的构建命令，这并不方便。我们可以创建一个名为.cargo/config.toml的文件，用以包含针对不同平台的特定编译参数：

in .cargo/config.toml

[target.'cfg(target_os = "linux")']
rustflags = ["-C", "link-arg=-nostartfiles"]

[target.'cfg(target_os = "windows")']
rustflags = ["-C", "link-args=/ENTRY:_start /SUBSYSTEM:console"]

[target.'cfg(target_os = "macos")']
rustflags = ["-C", "link-args=-e __start -static -nostartfiles"]

rustflags键包含的参数会自动添加到rustc的每次调用中。有关.cargo/config.toml文件的更多信息，请查看官方文档。

现在，我们的程序应该可以在这三个平台上以简单的cargo build方式构建了。

应该这要做吗

虽然可以为Linux、Windows和macOS构建独立的可执行程序，但这可能不是一个好主意。原因是我们的可执行程序仍然需要各种各样的东西，例如，在调用_start函数时初始化堆栈。没有C运行时，可能无法满足其中一些要求，这可能导致我们的程序出错，例如通过分段故障。

如果要创建在现有操作系统（包括libc）之上运行的最小二进制文件，并按此处所述设置#[start]属性，可能是一个更好的主意。

小结

一个最小的独立Rust二进制程序如下所示：

#![no_std] // 不链接Rust标准库
#![no_main] // 禁用Rust层入口点

use core::panic::PanicInfo;

#[no_mangle] // 该函数不进行名称重整
pub extern "C" fn _start() -> ! {
    // 此函数为入口点，因为连接器将会查找默认叫做`_start`的函数
    loop {}
}

/// This function is called on panic.
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

[package]
name = "crate_name"
version = "0.1.0"
authors = ["Author Name <author@example.com>"]

# the profile used for `cargo build`
[profile.dev]
panic = "abort" # disable stack unwinding on panic

# the profile used for `cargo build --release`
[profile.release]
panic = "abort" # disable stack unwinding on panic

要构建此二进制程序，我们需要针对裸机目标进行编译，例如thumbv7em-none-eabihf：

cargo build --target thumbv7em-none-eabihf

此外，我们也可以通过向链接器传递其他参数来为宿主机系统编译它：

# Linux
cargo rustc -- -C link-arg=-nostartfiles
# Windows
cargo rustc -- -C link-args="/ENTRY:_start /SUBSYSTEM:console"
# macOS
cargo rustc -- -C link-args="-e __start -static -nostartfiles"

请注意，这只是Rust独立二进制程序的最小示例。该二进制程序还需要更多操作，例如，在调用_start函数时初始化堆栈。因此，对于此类二进制程序的任何在实际场景中的使用，都需要继续添加更多的内容。

下期预告

下一篇文章将介绍将我们的独立二进制程序转换为最小操作系统内核所需的步骤。其中包括创建自定义编译目标，将我们的可执行文件与bootloader结合以及学习如何在屏幕上打印内容。

支持本项目

创建和维护这个博客和相关库是一项繁重的工作，但我真的很喜欢。通过支持我，您可以让我在新内容、新功能和持续维护上投入更多时间。

感谢您的支持！

Rust尝鲜

Wed, 02 Dec 2020 22:17:00 GMT

最近有一些水文章的需求，而且意外的在github上看到一些巨有趣的项目，结合了树莓派、Rust、操作系统等诸多元素，多厨狂喜，就准备搞一把Rust尝个鲜。

其中一个项目叫做Writing an OS in Rust，有中文版本，但是翻译的不多。英文的我大概看了，深入浅出的在x86设备上编写操作系统，有很多操作系统相关基础的文字介绍。

另一个项目叫做Operating System development tutorials in Rust on the Raspberry Pi。从readme来看，是一个给ARM64位ARMv8-A架构的操作系统业余爱好者进行入门的一个类教程项目。项目用docker来抹平可能存在的工具链问题，推荐在Linux（据说macOS这种unix也可以）里练手。里面还提到了在宿主机上用QEMU模拟内核进行编码并编译，后面还会通过串口和UART在树莓派实操。

还有个更神的太素 TisuOS，这是在RISC-V上的教程型操作系统，国人创作，后期可以试试。

可能因为我最近极度崇拜稚晖君，因此，想以一个CS的身份向EE方向龟速考虑，日拱一卒吧……

1 Rust环境

安装官方推荐方法curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh，安装rust全家桶（包括包管理器及工具链管理器rustup和一些环境变量配置）。

宿主机macOS，IDE选用不要钱的vscode，插件装上Rust或rust-analyzer、codelldb（调试）后，基本环境组装完毕（再夸一句不要钱的vscode）。（如果lldb安装时下载不给力，可以手动下然后使用cmd+shift+p，搜索入Extensions: Install from VSIX离线安装*.vsix文件。）

配置debug参数，vscode里cmd+shift+P调出菜单，输入debug选择调试打开launch.json配置调试参数，vscode自动新建该.vscode/lanuch.json文件并初始化配置（这时候就用到codelldb了）。

在vscode中启动调试时，vscode会自动安装调试组件：

rustup component add rust-analysis --toolchain stable-x86_64-apple-darwin <
info: component 'rust-analysis' for target 'x86_64-apple-darwin' is up to date

rustup component add rust-src --toolchain stable-x86_64-apple-darwin <
info: component 'rust-src' is up to date

rustup component add rls --toolchain stable-x86_64-apple-darwin <
info: installing component 'rls'

一个典型的配置类似：

{
    // 使用 IntelliSense 了解相关属性。
    // 悬停以查看现有属性的描述。
    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Launch",
            "args": [],
            "program": "${workspaceFolder}/target/debug/${workspaceFolderBasename}",
            "cwd": "${workspaceFolder}",
            "stopOnEntry": false,
            "sourceLanguages": ["rust"],
            "sourceMap": {
                "/rustc/*": "${env:HOME}/.rustup/toolchains/stable-x86_64-apple-darwin/lib/rustlib/src/rust"
            }
        }
    ]
}

使用cmd+shift+b进行cargo build，然后F5启动调试。（解释性语言用多了会忘记build……）

注：后面在使用中发现，rust-analyzer每次更新的时候重新安装插件会很慢，建议科学上网，比如直接挂在有openwrt的wifi上，因为系统全局代理貌似在vscode升级的时候不起作用。

2 实录

花了一周的空闲时间大概看了一下runoob和简单教程的rust基础知识。把里面的代码基本打了一遍，了解了一下写rust的感觉。也大概摸清了在vscode下写rust的一般步骤：

cargo new xxx创建项目；
cmd + shift + B打开build快捷菜单，点后面的齿轮按钮；
此时vscode会创建.vscode/task.json文件，用于显式定义build任务，该文件定义的初始任务只有cargo build；

我们一般还需要使用cargo check和cargo run，只需要复制初始task并替换command字段就可以实现：

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "cargo",
            "command": "build",
            "problemMatcher": [
                "$rustc"
            ],
            "group": "build",
            "label": "rust: cargo build"
        },
        {
            "type": "cargo",
            "command": "run",
            "problemMatcher": [
                "$rustc"
            ],
            "group": "build",
            "label": "rust: cargo run"
        }
    ]
}

接下来啃官方教程中文 | 英文。

必须看官方教程，决不能只看速通tutorial，这个语言的细节感觉并不比C/C++系少多少。如果看中文版有不懂的地方，建议移步原文……

ch02-00：介绍安装和更新（cargo update）dependency，以及通过Result处理无效输入：
```
let guess: u32 = match guess.trim().parse() {
    Ok(num) => num,
    Err(_) => continue,
};
```
ch03-01：shadowing常用于重复利用变量名：
```
let spaces = "   ";
let spaces = spaces.len();
```
ch03-02：关于元组的一个细节，如果元组数据均为基础类型，则该元组的内容均存放在栈上，进行赋值时，如let tup2 = tup1，元组内容会在栈上复制一份新的给tup2。而如果元组数据类型包含非基础类型，则该院组的内容将存放在堆上，此时赋值就相当于移动（move），即tup2仅包含tup1内容的指针，移动后tup1失效，因为内容的所有权转移给了tup2。
ch03-03：Rust是一门基于表达式（expression-based）的语言，表达式有返回值，语句则没有返回值，因此可以使用代码块和包裹表达式：
```
let y = {
    let x = 3;
    x + 1
};
```

ch03-05：三元运算符的写法：

let number = if condition { 5 } else { 6 };

ch04-01：Rust的基础类型和复杂类型的指针是存放于栈上的，复杂类型本身存在于堆上。栈内的内容赋值时（如let int1 = int2）会拷贝，因为栈编译时大小确定所以快；而堆内的内容赋值时（如let string1 = string2）默认不拷贝（Rust的设计就是不会主动进行深拷贝，因此Rust提供的自动复制对运行时效率影响都很小），只拷贝其栈内指针，并且使原来的变量失效（即string1失效），以避免二次释放等bug。很明确，基础类型的赋值操作会自动赋值，基础类型的各种组合元组也延续这一特性。
ch04-02：Rust的引用作用域是首次声明到最后一次使用，因此在只读引用的最后一次使用后，再进行可变引用，是可以通过编译的。也就是说，只要只读引用和可变引用的作用域不重叠，就没有问题。
ch04-03：&str就是slice，这是不可变引用。（Rust的这种把问题消灭在编译中的特性，是不是也顺便消灭了一批有问题的程序员……）
ch05-01：通常在结构体中不使用引用，如果使用引用，则需要用生命周期标识，以确保结构体引用的数据有效性跟结构体本身保持一致。没有任何字段的类单元结构体被称为类单元结构体（unit-like structs）因为它们类似于()，即unit类型。类单元结构体常常在你想要在某个类型上实现trait但不需要在类型中存储数据的时候发挥作用。
ch05-02：想要通过println!("{}", xxx)打印结构体，需要实现std::fmt::Display；

想要通过println!("{:?}", xxx)打印结构体，需要实现std::fmt::Debug，或手动为结构体加上#[derive(Debug)]注解，此时打印出：
```
rect1 is Rectangle { width: 30, height: 50 }
```
或者使用pretty-print风格println!("{:#?}", xxx)，此时打印出：
```
rect1 is Rectangle {
    width: 30,
    height: 50
}
```
Rust提供了很多可以使用derive注解来使用的trait。
ch05-03：C++中的静态函数（使用::调用），即附着在类而不是类实例上的函数，在Rust中称为关联函数，impl中不以&self作为第一个参数的函数均为关联函数。

ch06-01：枚举类型的定义：

enum Message {
    Quit,                       // 没有包含任何数据
    Move { x: i32, y: i32 },    // 包含匿名结构体
    Write(String),              // 包含单独一个`String`
    ChangeColor(i32, i32, i32), // 包含三个 i32
}

ch06-03：if let...else...常用于代替match..._...的情况：

let mut count = 0;
match coin {
    Coin::Quarter(state) => println!("State quarter from {:?}!", state),
    _ => count += 1,
}
// ↓↓↓↓↓↓↓↓↓↓ 使用`if let`代替 ↓↓↓↓↓↓↓↓↓↓
let mut count = 0;
if let Coin::Quarter(state) = coin {
    println!("State quarter from {:?}!", state);
} else {
    count += 1;
}

ch07-02：新建二进制项目用cargo new xxx，生成src/main.rs文件为bin执行入口；新建库项目用cargo new --lib xxx，生成src/lib.rs为lib编译入口；
ch07-03：公有结构体若包含私有字段，则应当提供公有关系函数（::）来构造实例，因为无法在外部初始化私有变量；而枚举一旦公有，则所有成员均为公有。
ch07-04：pub use可以将导入的模块变为公有，供外部调用的模块使用，单纯use是私有的。

ch08-01：虽说vector<T>只能包含类型T，但是也可以用枚举类型向vector里塞多种类型：

enum SpreadsheetCell {
    Int(i32),
    Float(f64),
    Text(String),
}

let row = vec![
    SpreadsheetCell::Int(3),
    SpreadsheetCell::Text(String::from("blue")),
    SpreadsheetCell::Float(10.12),
];

ch09-02：unwrap返回正常的Ok中的值或触发panic!，expect类似，只不过可以通过expect自定义错误信息（unwrap只有默认信息，有多个unwrap时容易混淆）。使用unwrap_or_else简化match：

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let f = File::open("hello.txt");

    let f = match f {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {:?}", e),
            },
            other_error => panic!("Problem opening the file: {:?}", other_error),
        },
    };
}
// ↓↓↓↓↓↓↓↓↓↓ 更老练的Rustacean会这么写 ↓↓↓↓↓↓↓↓↓↓
fn main() {
    let f = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {:?}", error);
            })
        } else {
            panic!("Problem opening the file: {:?}", error);
        }
    });
}

用?简化match（注意：?运算符只能用在返回值是Result类型的函数中，用来传播异常）：

use std::io::{self, Read};
use std::fs::File;

fn read_username_from_file() -> Result<String, io::Error> {
    let f = File::open("hello.txt");

    let mut f = match f {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut s = String::new();

    match f.read_to_string(&mut s) {
        Ok(_) => Ok(s),
        Err(e) => Err(e),
    }
}
// ↓↓↓↓↓↓↓↓↓↓ 使用`?`简化 ↓↓↓↓↓↓↓↓↓↓
fn read_username_from_file() -> Result<String, io::Error> {
    let mut f = File::open("hello.txt")?;
    let mut s = String::new();
    f.read_to_string(&mut s)?;
    Ok(s)
}
// ↓↓↓↓↓↓↓↓↓↓ 链式`?`再简化 ↓↓↓↓↓↓↓↓↓↓
fn read_username_from_file() -> Result<String, io::Error> {
    let mut s = String::new();

    File::open("hello.txt")?.read_to_string(&mut s)?;

    Ok(s)
}

ch10-02：几种trait声明写法：

// 普通公有trait
pub trait Summary {
    fn summarize(&self) -> String;
}
// 带默认实现
pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}
// trait中默认实现调用其他函数
pub trait Summary {
    fn summarize_author(&self) -> String;
    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}
// impl trait语法，trait作为参数
pub fn notify(item: impl Summary) {
    println!("Breaking news! {}", item.summarize());
}
// ↓↓↓↓↓↓↓↓↓↓ trait bound语法
pub fn notify<T: Summary>(item: T) {
    println!("Breaking news! {}", item.summarize());
}

// 多个impl trait
pub fn notify(item1: impl Summary, item2: impl Summary) {}
// ↓↓↓↓↓↓↓↓↓↓ 使用trait bound语法强行指定同类型参数
pub fn notify<T: Summary>(item1: T, item2: T) {}

// + 同时指定多个trait
pub fn notify(item: impl Summary + Display) {}
// ↓↓↓↓↓↓↓↓↓↓ + 同时指定多个trait的trait bound
pub fn notify<T: Summary + Display>(item: T) {}

// 复杂trait bound
fn some_function<T: Display + Clone, U: Clone + Debug>(t: T, u: U) -> i32 {}
// ↓↓↓↓↓↓↓↓↓↓ where简化复杂trait bound函数签名
fn some_function<T, U>(t: T, u: U) -> i32
    where T: Display + Clone,
        U: Clone + Debug
{}
// 函数返回值为trait
// 不能直接通过如if/else等方法在同一个函数中返回不同的均实现Summary trait的类
// 如if => Tweet else => NewsArticle
fn returns_summarizable() -> impl Summary {
    Tweet {
        username: String::from("horse_ebooks"),
        // --snip--
    }
}
// 为符合特定条件的泛型实现方法
struct Pair<T> {
    x: T,
    y: T,
}
// 为所有泛型实现new方法
impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self {
            x,
            y,
        }
    }
}
// 为满足Display和PartialOrd trait的类实现cmp_display方法
impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}
// 为实现了特定trait的类有条件的实现trait
impl<T: Display> ToString for T {}

ch10-03：生命周期标注确实抽象……
- 首先，生命周期一般出现在变量借用环节；
- 其次，函数的生命周期标注只是为了告诉借用检查器，各借用变量的生命周期长短关系，并不会改变函数行为；
- 再次，类似“协变”概念，为方便可以理解为长生命周期是短生命周期的子类。类似面向对象中里氏代换的概念——“接受父类型的位置，子类型也可以占位”，对类型而言，范围大类型是范围小类型的父类，比如i32是i16的父类；那么对生命周期而言长生命周期的变量是短生命周期变量的子类，也就是活得长的变量可以代替活的短的变量的位置，这样就能避免引用参数过早释放；
- 最后，生命周期一般标注在输入（参数）和输出（返回值）有关系的变量（参数或返回值）上，无关变量即使是借用也可以不标注。
- 函数或方法的参数的生命周期被称为输入生命周期（input lifetimes），而返回值的生命周期被称为输出生命周期（output lifetimes）。
- 编译器采用三条规则来判断引用何时不需要明确的注解。第一条规则适用于输入生命周期，后两条规则适用于输出生命周期。如果编译器检查完这三条规则后仍然存在没有计算出生命周期的引用，编译器将会停止并生成错误。这些规则适用于fn定义，以及impl块。
  1. 第一条规则是每一个是引用的参数都有它自己的生命周期参数。换句话说就是，有一个引用参数的函数有一个生命周期参数：fn foo<'a>(x: &'a i32)，有两个引用参数的函数有两个不同的生命周期参数，fn foo<'a, 'b>(x: &'a i32, y: &'b i32)，依此类推。
  2. 第二条规则是如果只有一个输入生命周期参数，那么它被赋予所有输出生命周期参数：fn foo<'a>(x: &'a i32) -> &'a i32。
  3. 第三条规则是如果方法有多个输入生命周期参数并且其中一个参数是&self或&mut self，说明是个对象的方法，那么所有输出生命周期参数被赋予 self的生命周期。第三条规则使得方法更容易读写，因为只需更少的符号。
ch11-01：测试某函数应该在特定条件下panic时， expected的内容就是panic输出时应该包含的内容：
```
#[test]
#[should_panic(expected = "Guess value must be less than or equal to 100")]
fn greater_than_100() {
    Guess::new(200);
}
```
利用返回值为Result<T, E>的函数进行测试，可以在函数中使用?运算符，也可以方便的编写任何运算符会返回Err成员的测试。不能对使用 Result<T, E>的测试使用#[should_panic]注解。相反应该在测试失败时直接返回Err值：
```
#[test]
fn it_works() -> Result<(), String> {
    if 2 + 2 == 4 {
        Ok(())
    } else {
        Err(String::from("two plus two does not equal four"))
    }
}
```

ch11-02：cargo test选项：

# 单线程运行，若各测试间存资源抢占可以使用线程指定选项test-threads
cargo test -- --test-threads=1
# 测试默认会截获程序所有输出，使得测试输出更具备可读性，希望打印程序输出使用nocapture选项
cargo test -- --nocapture
# 测试可以指定测试名称
cargo test it_works
# 测试可以匹配名称，如匹配各种it开头的测试
cargo test it
# 可以在代码中使用#[ignore]注解来禁止诸如耗时测试的进行，使用ignored选项运行这些被禁止的测试注解
cargo test -- --ignored

ch11-03：测试规范：
- 单元测试：单元测试与他们要测试的代码共同存放在位于src目录下相同的文件中。规范是在每个文件中创建包含测试函数的tests模块，并使用#cfg(test)标注模块（即在test时才编译运行，build事不做以节省时间）。
- 集成测试：应在项目根目录创建一个tests目录，与src同级，cargo会去找到这个文件夹中的所有文件并编译成一个个单独的crate（无需#[cfg(test)]注解，tests是cargo认为的特殊文件夹，只有测试是才编译）。
- 输出依次为单元测试、集成测试、文档测试，使用cargo test --test integration_test可以指定集成测试。
- tests目录中的子目录不会被作为单独的crate编译或作为一个测试结果部分出现在测试输出中，因此，需要诸如多个测试均涉及的工具函数可以放在tests/common/mod.rs中。
ch12-01：collect方法的返回值需要显示注明类型，因为rust无法推断出collect返回的类型，比如：
```
let args: Vec<String> = env::args().collect();
```
ch12-03：当函数返回一个Result，失败时希望返回失败原因字符串，则泛型应有static生命周期注释，如pub fn new(mut args: std::env::Args) -> Result<Config, &'static str>。
ch13-01：闭包可以通过三种方式捕获其环境，他们直接对应函数的三种获取参数的方式：获取所有权，可变借用和不可变借用。这三种捕获值的方式被编码为如下三个Fntrait：
- FnOnce消费从周围作用域捕获的变量，闭包周围的作用域被称为其环境。为了消费捕获到的变量，闭包必须获取其所有权并在定义闭包时将其移动进闭包。其名称的Once部分代表了闭包不能多次获取相同变量的所有权的事实，所以它只能被调用一次。
- FnMut获取可变的借用值所以可以改变其环境。
- Fn从其环境获取不可变的借用值大部分需要指定一个Fn系列trait bound的时候，可以从Fn开始，而编译器会根据闭包体中的情况告诉你是否需要FnMut或FnOnce。

ch13-03：函数式编程风格倾向于最小化可变状态的数量来使代码更简洁：

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}
// ↓↓↓↓↓↓↓↓↓↓ 通过filter省略result中间变量
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    contents.lines().filter(|line: &&str| line.contains(query)).collect()
}

ch14-02：使用重导出功能可以重新组织希望暴露在外的API，编写者和使用者可以面对不同的API结构，如此，使用者无需了解crate内部结构即可方便的调用公开的API：
```
pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;
```
ch14-03：按照教程做，添加rand依赖时，保存后vscode自动运行cargo check，然后显示"fetch metadata"很长时间不动，手动运行cargo metadata，发现卡在Updating crates.io index下载很慢，只好祭出替换镜像源大法……在/Users/xxx/.cargo/目录下新建config文件，添加内容替换中科大镜像源：
```
[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"
replace-with = 'ustc'
[source.ustc]
registry = "git://mirrors.ustc.edu.cn/crates.io-index"
```
ch15-01：除了数据被储存在堆上而不是栈上之外，box 没有性能损失。不过也没有很多额外的功能。它们多用于如下场景：
- 当有一个在编译时未知大小的类型，而又想要在需要确切大小的上下文中使用这个类型值的时候。
- 当有大量数据并希望在确保数据不被拷贝的情况下转移所有权的时候。
- 当希望拥有一个值并只关心它的类型是否实现了特定 trait 而不是其具体类型的时候。
ch15-02：Rust 在发现类型和 trait 实现满足三种情况时会进行解引用强制多态：
- 当T: Deref<Target=U>时（即当T实现了Deref返回U时），从&T到&U。
- 当T: DerefMut<Target=U>时从&mut T到&mut U。
- 当T: Deref<Target=U>时从&mut T到&U。（只允许将可变借用转为不可变借用，反之则禁止）
ch15-06：Rc::clone使Rc::strong_count加一，Rc::downgrade使Rc::weak_count加一。强引用共享不可变所有权，弱引用不涉及所有权。
ch16-01：rust标准库仅提供1:1线程，即语言线程映射系统线程，不存在运行时的线程管理损耗。

ch16-02：mpsc(multiple producer, single consumer)的channel通过mpsc::Sender::clone(&tx)来实现多生产者：

let (tx, rx) = mpsc::channel();

let tx1 = mpsc::Sender::clone(&tx);
thread::spawn(move || {
    let vals = vec![
        String::from("hi"),
        String::from("from"),
        String::from("the"),
        String::from("thread"),
    ];

    for val in vals {
        tx1.send(val).unwrap();
        thread::sleep(Duration::from_secs(1));
    }
});

thread::spawn(move || {
    let vals = vec![
        String::from("more"),
        String::from("messages"),
        String::from("for"),
        String::from("you"),
    ];

    for val in vals {
        tx.send(val).unwrap();
        thread::sleep(Duration::from_secs(1));
    }
});

for received in rx {
    println!("Got: {}", received);
}

ch16-03：十五章中使用Rc::new(RefCell::new(x))提供Rc内部值的可变引用，类似的，多线程中使用Arc::new(Mutex::new(x))提供Arc内部值的可变引用。
ch16-04：Send（允许在线程间转移所有权）和Sync（允许多线程访问）是标记trait，基本类型均具有该标记，有该标记的类型的复合类型也具有该标记，而Rc、RefCell等智能指针并不具有该标记，Arc、Mutex具有该标记。

ch17-03：Option.take将获取Some中资源的所有权，然后为Option留下一个None：

pub struct Post {
    state: Option<Box<dyn State>>,
    content: String,
}

if let Some(s) = self.state.take() {
    self.state = Some(s.request_review())
}
// 区别于下面unwrap实现，unwrap()会获取state的所有权并消费掉state，而这里的state是在可变引用self后的，
// 所以unwrap无法获取state的所有权，自然无法消费这个state，也就无法通过编译了
// 而take无需state的所有权，只需要从state引用中拿到Some中的内容，即Box指针的所有权并赋给s，同时给state这个Option类型留下一个None
self.state = Some(self.state.unwrap().request_review());

ch18-03：match匹配的其他类型：

// 逻辑或
match x {
    1 | 2 => println!("one or two"),
    3 => println!("three"),
    _ => println!("anything"),
}
// 匹配范围：仅能匹配数字和char类型
match x {
    1..=5 => println!("one through five"),
    _ => println!("something else"),
}
match x {
    'a'..='j' => println!("early ASCII letter"),
    'k'..='z' => println!("late ASCII letter"),
    _ => println!("something else"),
}

解构结构体：

let p = Point { x: 0, y: 7 };
let Point { x: a, y: b } = p;
// 或
let p = Point { x: 0, y: 7 };
let Point { a, b } = p;

解构并匹配：

let p = Point { x: 0, y: 7 };
match p {
    Point { x, y: 0 } => println!("On the x axis at {}", x),
    Point { x: 0, y } => println!("On the y axis at {}", y),
    Point { x, y } => println!("On neither axis: ({}, {})", x, y),
}

解构枚举：

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {
    let msg = Message::ChangeColor(0, 160, 255);

    match msg {
        Message::Quit => {
            println!("The Quit variant has no data to destructure.")
        }
        Message::Move { x, y } => {
            println!(
                "Move in the x direction {} and in the y direction {}",
                x,
                y
            );
        }
        Message::Write(text) => println!("Text message: {}", text),
        Message::ChangeColor(r, g, b) => {
            println!(
                "Change the color to red {}, green {}, and blue {}",
                r,
                g,
                b
            )
        }
    }
}

解构嵌套的枚举和结构体：

enum Color {
Rgb(i32, i32, i32),
Hsv(i32, i32, i32),
}

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(Color),
}

fn main() {
    let msg = Message::ChangeColor(Color::Hsv(0, 160, 255));

    match msg {
        Message::ChangeColor(Color::Rgb(r, g, b)) => {
            println!(
                "Change the color to red {}, green {}, and blue {}",
                r,
                g,
                b
            )
        }
        Message::ChangeColor(Color::Hsv(h, s, v)) => {
            println!(
                "Change the color to hue {}, saturation {}, and value {}",
                h,
                s,
                v
            )
        }
        _ => ()
    }
}

解构嵌套的结构体和元组：

let ((feet, inches), Point {x, y}) = ((3, 10), Point { x: 3, y: -10 });

变量命名使用下划线开头时，即使不使用该变量编译器也不会警告“变量未使用”。

使用..忽略剩余值：

let origin = Point { x: 0, y: 0, z: 0 };
match origin {
    Point { x, .. } => println!("x is {}", x),
}
// 或
let numbers = (2, 4, 8, 16, 32);
match numbers {
    (first, .., last) => {
        println!("Some numbers: {}, {}", first, last);
    },
}

匹配守卫（match guard）：

// 输出 less than five: 4
let num = Some(4);
match num {
    Some(x) if x < 5 => println!("less than five: {}", x),
    Some(x) => println!("{}", x),
    None => (),
}
// 使用匹配守卫解决match会引入新作用域的问题，match中的y覆盖了外部的y
fn main() {
    let x = Some(5);
    let y = 10;

    match x {
        Some(50) => println!("Got 50"),
        Some(y) => println!("Matched, y = {:?}", y),
        _ => println!("Default case, x = {:?}", x),
    }

    println!("at the end: x = {:?}, y = {:?}", x, y);
}
// ↓↓↓↓↓↓↓↓↓↓ 利用匹配守卫就可以用到外部的y ↓↓↓↓↓↓↓↓↓↓
fn main() {
    let x = Some(5);
    let y = 10;

    match x {
        Some(50) => println!("Got 50"),
        Some(n) if n == y => println!("Matched, n = {}", n),
        _ => println!("Default case, x = {:?}", x),
    }

    println!("at the end: x = {:?}, y = {}", x, y);
}
// 匹配守卫结合或条件，意为此分支值匹配x值为4、5或6同时y为true的情况，本例中y为false所以不会匹配首个条件：
let x = 4;
let y = false;

match x {
    4 | 5 | 6 if y => println!("yes"),
    _ => println!("no"),
}
``
`
`@`运算符，本例希望测试`Message::Hello`的`id`字段是否位于`3..=7`范围内，同时也希望能将其值绑定到`id_variable`变量中以便此分支相关联的代码可以使用它（可以将`id_variable`命名为`id`，与字段同名，不过出于示例的目的这里选择了不同的名称）：

```rust
enum Message {
    Hello { id: i32 },
}

let msg = Message::Hello { id: 5 };

match msg {
    Message::Hello { id: id_variable @ 3..=7 } => {
        println!("Found an id in range: {}", id_variable)
    },
    Message::Hello { id: 10..=12 } => {
        println!("Found an id in another range")
    },
    Message::Hello { id } => {
        println!("Found some other id: {}", id)
    },
}

ch19-01：unsafe的用法：
```
// 不会崩溃的用法，因为裸指针范围恰好不重叠
use std::slice;

fn split_at_mut(slice: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) {
    let len = slice.len();
    let ptr = slice.as_mut_ptr();

    assert!(mid <= len);

    unsafe {
        (slice::from_raw_parts_mut(ptr, mid),
        slice::from_raw_parts_mut(ptr.add(mid), len - mid))
    }
}
// 可能会崩溃的用法，因为i32型的裸指针向后取一万个生成的序列，所用的内存并不在这段程序的掌控之中
use std::slice;

let address = 0x01234usize;
let r = address as *mut i32;

let slice: &[i32] = unsafe {
    slice::from_raw_parts_mut(r, 10000)
};
```
使用extern调用外部代码，调用外部代码总被认为是unsafe的，比如调用C语言：
```
extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    unsafe {
        println!("Absolute value of -3 according to C: {}", abs(-3));
    }
}
```
使用extern编译成被外部代码调用的ABI：
```
#[no_mangle]
pub extern "C" fn call_from_c() {
    println!("Just called a Rust function from C!");
}
```
声明静态变量（全局变量），静态变量只能储存拥有'static生命周期的引用，这意味着 Rust 编译器可以自己计算出其生命周期而无需显式标注。访问不可变静态变量是安全的。（常量与不可变静态变量可能看起来很类似，不过一个微妙的区别是静态变量中的值有一个固定的内存地址。使用这个值总是会访问相同的地址。另一方面，常量则允许在任何被用到的时候复制其数据。常量与静态变量的另一个区别在于静态变量可以是可变的。访问和修改可变静态变量都是不安全的）。声明并读取不可变静态变量：
```
static HELLO_WORLD: &str = "Hello, world!";

fn main() {
    println!("name is: {}", HELLO_WORLD);
}
```
声明、修改并读取可变静态变量：
```
static mut COUNTER: u32 = 0;

fn add_to_count(inc: u32) {
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_count(3);

    unsafe {
        println!("COUNTER: {}", COUNTER);
    }
}
```
不安全的trait，典型场景为ch16-04中线程共享数据，如果实现了一个包含一些不是Send或Sync的类型（如裸指针），并希望将此实现类型标记为Send或Sync，则必须使用unsafe。Rust不能验证我们的类型保证可以安全的跨线程发送或在多线程间访问，所以需要我们自己进行检查并通过unsafe表明。：
```
unsafe trait Foo {
    // methods go here
}

unsafe impl Foo for i32 {
    // method implementations go here
}
```
union和struct类似，但是在一个实例中同时只能使用一个声明的字段。联合体主要用于和C代码中的联合体交互。访问联合体的字段是不安全的，因为 Rust 无法保证当前存储在联合体实例中数据的类型。

不安全的使用场景：
- 解引用裸指针
- 调用不安全的函数或方法
- 访问或修改可变静态变量
- 实现不安全trait
- 访问union的字段

ch19-03：高级trait中的关联类型的默认类型，其典型场景为：运算符重载时，符号两侧数据类型不同的情况（如“米+毫米”）：

// 观察Add运算符trait的定义：
trait Add<RHS=Self> {
    type Output;

    fn add(self, rhs: RHS) -> Self::Output;
}
// 运算符两端的数据类型相同时，不需要显示声明`Add`右侧数据类型，默认与左侧相同：
use std::ops::Add;

#[derive(Debug, PartialEq)]
struct Point {
    x: i32,
    y: i32,
}

impl Add for Point {
    type Output = Point;

    fn add(self, other: Point) -> Point {
        Point {
            x: self.x + other.x,
            y: self.y + other.y,
        }
    }
}

fn main() {
    assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 },
            Point { x: 3, y: 3 });
}
// 左侧类型与右侧类型不同时，才需要显示声明类型：
use std::ops::Add;

struct Millimeters(u32);
struct Meters(u32);

impl Add<Meters> for Millimeters {
    type Output = Millimeters;

    fn add(self, other: Meters) -> Millimeters {
        Millimeters(self.0 + (other.0 * 1000))
    }
}

在trait中要求实现该trait的类型具有某些其他trait，类似于为trait添加"trait bound"，例如要求实现OutlinePrint这一trait的类型具有Displaytrait，以便我们在outline_print()中调用to_string()：

use std::fmt;

trait OutlinePrint: fmt::Display {
    fn outline_print(&self) {
        let output = self.to_string();
        let len = output.len();
        println!("{}", "*".repeat(len + 4));
        println!("*{}*", " ".repeat(len + 2));
        println!("* {} *", output);
        println!("*{}*", " ".repeat(len + 2));
        println!("{}", "*".repeat(len + 4));
    }
}

ch19-05：将函数以参数的方式传递给另一个函数，除了传递闭包外，也可以传递fn定义的函数，函数的类型是fn（使用小写的“f”）以免与Fn闭包trait相混淆。fn被称为函数指针（function pointer）：
```
fn add_one(x: i32) -> i32 {
    x + 1
}

fn do_twice(f: fn(i32) -> i32, arg: i32) -> i32 {
    f(arg) + f(arg)
}

fn main() {
    let answer = do_twice(add_one, 5);

    println!("The answer is: {}", answer);
}
```
返回一个闭包函数时，与往常一样，由于rust并不知道闭包需要多少空间来储存，因此需要返回指针包裹的闭包，如Fntrait对象：
```
fn returns_closure() -> Box<dyn Fn(i32) -> i32> {
    Box::new(|x| x + 1)
}
```
ch19-06：类似于vec![1, 2, 3]的声明宏（declarative macros）：
```
// 简化版的vec!宏
#[macro_export]
macro_rules! vec {
    ( $( $x:expr ),* ) => {
        {
            let mut temp_vec = Vec::new();
            $(
                temp_vec.push($x);
            )*
            temp_vec
        }
    };
}
// 调用这个宏vec![1, 2, 3]生成的代码类似于：
let mut temp_vec = Vec::new();
temp_vec.push(1);
temp_vec.push(2);
temp_vec.push(3);
temp_vec
```
过程宏（procedural macros）实现较复杂，我大概率只用不写。

类属性宏，示例有两个TokenStream类型的参数；第一个用于属性内容本身，也就是GET, "/"部分。第二个是属性所标记的项：在本例中，是fn index() {}和剩下的函数体。除此之外，类属性宏与自定义派生宏工作方式一致：创建 proc-macro crate类型的crate并实现希望生成代码的函数：
```
#[route(GET, "/")]
fn index() {...}
// ↓↓↓↓↓↓↓↓↓↓ 实现 ↓↓↓↓↓↓↓↓↓↓
#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {...}
```
类函数宏，定义看起来像函数调用的宏。类似于macro_rules!，它们比函数更灵活（例如，可以接受未知数量的参数，macro_rules!宏只能使用前面vec!例子中匹配语法定义）。类函数宏获取TokenStream参数，其定义使用Rust代码操纵TokenStream，就像另两种过程宏一样。一个类函数宏例子是可以像这样被调用的sql!宏：
```
let sql = sql!(SELECT * FROM posts WHERE id=1);
// ↓↓↓↓↓↓↓↓↓↓ 实现 ↓↓↓↓↓↓↓↓↓↓
#[proc_macro]
pub fn sql(input: TokenStream) -> TokenStream {...}
```

ch20-03：多线程webserver范例：目录结构大致为：

hello
├── 404.html
├── Cargo.lock
├── Cargo.toml
├── hello.html
├── src
│   ├── bin
│   │   └── main.rs
│   └── lib.rs
...

这个范例通过实现线程模型间消息的传递、线程的结束等目标，利用了很多前面十几章提到的知识点：

利用type缩写类型；
通过Option交换所有权；
智能指针Arc与Mutux在线程模型中的用法；
如何在线程模型中将mpsc通道变为“spmc”；
通过观察标准库中的thread::spawn()，模仿着编写一个类似的接受闭包指针且能够在线程模型中使用的函数；

...

use std::{fs, net::{TcpListener, TcpStream}, thread, time::Duration};
use hello::ThreadPool;
use std::io::prelude::*;

fn main() {
    let listener = TcpListener::bind("127.0.0.1:7878").unwrap();
    let pool = ThreadPool::new(4);

    for stream in listener.incoming() {
        let stream = stream.unwrap();

        pool.execute(|| {
            handle_connection(stream);
        });
    }
}

fn handle_connection(mut stream: TcpStream) {
    let mut buffer = [0; 1024];

    stream.read(&mut buffer).unwrap();

    let get = b"GET / HTTP/1.1\r\n";
    let sleep = b"GET /sleep HTTP/1.1\r\n";


    let (status_line, filename) = if buffer.starts_with(get) {
        ("HTTP/1.1 200 OK\r\n\r\n", "hello.html")
    } else if buffer.starts_with(sleep) {
        thread::sleep(Duration::from_secs(5));
        ("HTTP/1.1 200 OK\r\n\r\n", "hello.html")
    } else {
        ("HTTP/1.1 404 NOT FOUND\r\n\r\n", "404.html")
    };

    let contents = fs::read_to_string(filename).unwrap();

    let response = format!("{}{}", status_line, contents);

    stream.write(response.as_bytes()).unwrap();
    stream.flush().unwrap();    
}

use std::{sync::{Arc, Mutex, mpsc}, thread};

pub struct ThreadPool {
    workers: Vec<Worker>,
    sender: mpsc::Sender<Message>,
}

type Job = Box<dyn FnOnce() + Send + 'static>;

enum Message {
    NewJob(Job),
    Terminate,
}

impl ThreadPool {

    /// 创建线程池
    /// 
    /// `size`为线程池中线程的数量
    ///
    /// # Panics
    /// 
    /// `new`函数在`size`为`0`时会panic。
    pub fn new(size: usize) -> ThreadPool {
        assert!(size > 0);
        let mut workers = Vec::with_capacity(size);

        let (sender, receiver) = mpsc::channel();

        // Arc指针负责提供线程间复制功能，Mutex指针负责提供线程间共享数据功能。
        let receiver = Arc::new(Mutex::new(receiver));

        for id in 0..size {
            workers.push(Worker::new(id, Arc::clone(&receiver)));
        }

        ThreadPool {
            workers,
            sender,
        }
    }

    pub fn execute<F>(&self, f: F) 
        where F: FnOnce() + Send + 'static
    {
        let job = Box::new(f);

        self.sender.send(Message::NewJob(job)).unwrap();
    }
}

impl Drop for ThreadPool {
    fn drop(&mut self) {
        println!("Sending terminate message to all workers.");

        // 这里必须使用两个迭代发送终止消息，因为消息的发送无法针对特定worker
        // 使用同一个循环先发送终止消息再join，并不能保证收取消息的worker与join的worker是同一个worker
        for _ in &self.workers {
            self.sender.send(Message::Terminate).unwrap();
        }

        println!("Shutting down all workers.");

        for worker in &mut self.workers {
            println!("Shutting down worker {}", worker.id);

            if let Some(thread) = worker.thread.take() {
                thread.join().unwrap();
            }
        }
    }
}

pub struct Worker {
    id: usize,
    // 使用Option的原因在于join线程时需要拿到句柄所有权后消费掉这个句柄，Option的take方法可以拿到Some中内容的所有权同时交还一个None。
    // 若不通过Option封装，则结构体的thread字段无法交出其中的句柄所有权，因为结构体不允许thread字段悬空。
    thread: Option<thread::JoinHandle<()>>,
}

impl Worker {
    fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Message>>>) -> Worker {
        let thread = thread::spawn(move || loop {
            let message = receiver.lock().unwrap().recv().unwrap();

            match message {
                Message::NewJob(job) => {
                    println!("Worker {} got a job; executing.", id);

                    job();
                },
                Message::Terminate => {
                    println!("Worker {} was told to terminate.", id);

                    break;
                }
            }
        });

        Worker  {
            id,
            thread: Some(thread),
        }
    }
}

更换VPS科学球

Sat, 28 Nov 2020 19:27:00 GMT

影子VPS科学球中的飞机在一个月内多次被击落后（估计主要因为反复使用9000、9001、8000、8001端口，流量也不小），VPS科学球也被炸了……这是我第一次体验炸机+炸VPS科学球事故……

:::caution 仅限技术交流！ :::

1 背景环境

大概从九月中旬开始，飞机就隔三差五的被炸，我依然在作大死的不停换飞机升空。于是，到了十月底，VPS科学球被炸掉了。这是VPS科学球的废墟：

(base) ➜  ~ traceroute 45.135.xxx.xxx
traceroute to 45.135.xxx.xxx (45.135.xxx.xxx), 64 hops max, 52 byte packets
 1  10.0.6.1 (10.0.6.1)  33.186 ms  5.674 ms  7.163 ms
 2  * * *
 3  114.86.28.1 (114.86.28.1)  6.460 ms  11.830 ms  9.385 ms
 4  61.152.10.85 (61.152.10.85)  7.064 ms
    61.152.10.253 (61.152.10.253)  11.341 ms
    61.152.10.85 (61.152.10.85)  5.387 ms
 5  101.95.120.218 (101.95.120.218)  9.113 ms
    61.152.24.50 (61.152.24.50)  11.964 ms
    101.95.120.218 (101.95.120.218)  7.964 ms
 6  202.97.61.86 (202.97.61.86)  24.081 ms
    202.97.57.25 (202.97.57.25)  19.092 ms
    202.97.57.157 (202.97.57.157)  6.437 ms
 7  202.97.90.33 (202.97.90.33)  28.298 ms
    202.97.74.37 (202.97.74.37)  23.032 ms
    202.97.90.33 (202.97.90.33)  21.522 ms
 8  59.43.244.113 (59.43.244.113)  23.334 ms  22.408 ms *
 9  59.43.247.125 (59.43.247.125)  34.363 ms  52.363 ms  38.770 ms
10  59.43.246.18 (59.43.246.18)  126.581 ms *  132.564 ms
11  145.14.89.2 (145.14.89.2)  126.328 ms  129.369 ms  125.261 ms
12  * * *
...
64  * * *

2 更换科学球服务

依然是熟悉的CentOS 7。

2.1 重建VPS科学球环境

首次登录好习惯改密码（为了方便，应该把zsh、git、oh-my-zsh、vim和tmux装上。）：

# VPS上改密码
passwd
# 电脑上上传秘钥进行ssh免密登录
ssh-copy-id root@46.*.*.*

sudo yum -y update && sudo yum -y install zsh git vim tmux
chsh -s $(which zsh)
sh -c "$(wget -O- https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

将ssh设置为无法用密码登录（只接受key pair认证）：

# /etc/ssh/sshd_config 中：
PasswordAuthentication no
# 重启sshd服务：
service sshd restart

2.2 申请VPS科学球名

V家的服务需要域名服务（以下简称VPS科学球名），按照教程申请免费VPS科学球名。

转念一想，还是整个大厂的吧，就买了个阿里云的.tech域名，反正双十一感觉199十年也算不贵，又在阿里云上申请了个免费证书。

2.2 搭建VPS科学球

年纪大了懒得从头学了，向一键安装脚本（一键安装脚本已失效）低头，真香……

这个脚本的nginx的80端口被设置了跳向一个小说网站，据说是为了伪装，有需求可以换掉（即修改/etc/nginx/conf.d/域名.conf里location块的proxy_pass代理重定向改掉即可）。比如我把重定向直接改到了自己的https://zlotus.github.io上了，还挺不错的。

需要注意的是，那个一键脚本中使用的证书是Let’s Encrypt颁发的庶民免费证书，作为阿里云付费会员，我自然需要使用会员免费证书申明自己的高贵身份[狂笑]。这里需要在v2ray配置文件中/etc/v2ray/config.json把路径改到我从阿里云获得的证书：

"certificateFile": "/etc/letsencrypt/live/yourname.com/fullchain.pem",
"keyFile": "/etc/letsencrypt/live/yourname.com/privkey.pem"

阿里云的域名解析一开始正常了一个来小时，后面就异常了，在whois上说是域名等待实名认证的问题，再等等吧，提交了工单据说一两天就自动好了。我是上谷歌的学术派，实名什么的对我来说更好，虽然自带正值属性，依旧希望今生不喝茶。

3 客户端

据说现在客户端对vless的支持还不全面，macOS上我用了v2rayU，安卓上用了v2rayNG。（mac上我一开始选了qt的那个客户端，一个是运行有qt特有的不顺滑感，另外就是outbound_direct的流量总不正常，倒是机舱里的数据很正常，挺奇怪的，我就换了U的这个客户端）。

4 OpenWrt

老的OpenWrt-rpi貌似不支持vless，我就更新了个版本，参考老文章。

我的新版本应该是2020-11-06的nightly build，部署的时候在修改无线加密方式时遇到点小麻烦，选择WPA2-PSK/WPA3-SAE Mixed Model时，设置密码重启进不去，我就重新刷了固件准备清设置，谁知道快速格式化是不行的，我低格了整个SD卡才把设置清掉，还是有点神奇的[捂脸]（估计拷个大文件覆盖也行）……后来选了WPA-PSK/WPA2-PSK Mixed Model就好了。

依然是配置LAN口网关（192.168.1.1）、DNS（61.134.1.4和218.30.19.40），先让能上网

新版影子的服务类型里明确有vless，填上东西就能正常科学化了。或者使用PassWall服务，里面也有vless。

5 大插曲

用了没两天，DNS解析断了，在阿里的whois上查，说是被注册局封了，也挺迷的，持续了一个月吧。详情如下：

也许是我的V型VPS科学球的自动部署脚本里有广告程序，也许是倒霉被入侵（反正我在VPS里没看到什么可疑进程ps、奇怪链接netstat、不对劲的文件访问lsof）。

在阿里云上提交工单，客服反映我的域名是被被radix注册局封了，让我直接给注册局发邮件询问，还好心的说，最好多发几封邮件，耐心等待。于是，我跟肖申克的安迪一样，开始了每天发邮件的日常任务，主要是给abuse@radixregistry.com和china@radix.email发邮件，不限语言。我就每天中英双语给每个邮箱各发两封邮件。

二十多天后，有回复了，注册局那边解释说，我是被一个叫surbl的网站列为域名滥用对象了，让我在surbl上提交“移除域名滥用对象”的申请。

在提交申请后两三天，surbl上查确实从红变绿了，又过了一两天域名就能够正常解析了，阿里云DNS控制台也显示正常。不过又过了一天，我在surbl上看域名又变红了，目前还不知道什么情况，但是DNS解析依然正常，希望域名别再出事了……

6 总结

我一直觉得自己是个没什么耐心的人，通过这个事件才发现，原来我很有耐心，只是分对谁，目前看来只是对傻逼容忍度为零，其他都还好。祝自己肉体和心灵都能够继续保持健康，下周体检有点紧张[捂脸]~

在VPS上配置内网穿透

Sat, 05 Sep 2020 09:45:00 GMT

最近老经常出差到上海，笔记本和树莓派就放上海这边办公室懒得拿回公寓，但是上面都有些想随时调出来看的文件，希望能用手机直接访问这俩设备，搜了一下准备用frps-frpc做个内网穿透试试。

1 需求

用手机访问VPS特定端口后，VPS转发请求到笔记本和树莓派，就这么简单。搜到的第一篇文章就是内网穿透：在公网访问你家的 NAS。

2 部署frp

2.1 部署frps

在VPS上部署服务端frps：

下载页面在Release · fatedier/frp：

wget https://github.com/fatedier/frp/releases/download/v0.33.0/frp_0.33.0_linux_amd64.tar.gz
tar xvzf frp_0.33.0_linux_amd64.tar.gz
mv frp_0.33.0_linux_amd64 frp
cd frp

开启防火墙，我打算用默认的7000端口：

sudo firewall-cmd --zone=public --permanent --add-port=7000/tcp # frps监听端口
sudo firewall-cmd --zone=public --permanent --add-port=10022/tcp # 树莓派ssh服务
sudo firewall-cmd --zone=public --permanent --add-port=10080/tcp # 笔记本http服务
firewall-cmd --reload
#firewall-cmd --list-ports
#7000/tcp 10022/tcp 10080/tcp

在VPS上配置frps.ini：

[common]
bind_port = 7000    # frps监听端口
token = ***token***

配置启动项：

ln frps /usr/bin/frps
mkdir /etc/frp/
ln frps.ini /etc/frp/frps.ini

ln -s /root/frp/systemd/frps.service /usr/lib/systemd/system/
systemctl enable frps.service
systemctl start frps.service

2.2 部署frpc - ssh

在树莓派上部署客户端，下载并解压：

wget https://github.com/fatedier/frp/releases/download/v0.33.0/frp_0.33.0_linux_arm.tar.gz
tar xvzf frp_0.33.0_linux_arm.tar.gz
mv frp_0.33.0_linux_arm frp
cd frp

在树莓派上配置frpc.ini

[common]
server_addr = 45.135.xxx.xxx # VPS地址
server_port = 7000           # VPS frps监听端口
token = ***token***

[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22              # 树莓派需要暴露给VPS frps的服务端口，如这里的ssh默认22端口
remote_port = 10022          # VPS frps监听10022端口，并将访问这个端口的流量转发给树莓派的22端口

配置启动项：

sudo ln frpc /usr/bin/frpc
sudo mkdir /etc/frp/
sudo ln frpc.ini /etc/frp/frpc.ini

sudo ln -s /home/pi/frp/systemd/frpc.service /usr/lib/systemd/system/
sudo systemctl enable frpc.service
sudo systemctl start frpc.service

2.3 部署frpc - http

在笔记本上部署客户端，下载并解压：

wget https://github.com/fatedier/frp/releases/download/v0.33.0/frp_0.33.0_darwin_amd64.tar.gz
tar xvzf frp_0.33.0_darwin_amd64.tar.gz
mv frp_0.33.0_darwin_amd64 frp
cd frp

在笔记本上配置frpc.ini

[common]
server_addr = 45.135.xxx.xxx # VPS地址
server_port = 7000           # VPS frps监听端口
token = ***token***

[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 80              # 树莓派需要暴露给VPS frps的服务端口，如这里的ssh默认22端口
remote_port = 10080          # VPS frps监听10022端口，并将访问这个端口的流量转发给树莓派的22端口

笔记本就不配置启动项了，临时服务web，用完就关。另外，macOS的防火墙过于傻瓜，只能配置程序，不能配置端口，用nginx的时候得把这傻瓜墙关了。

3 测试

谷歌上搜个Termux的apk安在手机上，再Termux安装ssh（pkg install dropbear），用手机登录ssh -p10022 pi@45.135.135.76：

小结

frp作为内网穿透工具还有好多高级功能我都没试，有需要再尝试。另外，提交上面的手机图片时遇到一个不太常见的git使用场景：

     B
    /
---X---A

一开始我提交了一张图片（即在本地库及远端github上均从X->A，本地库及远端库最新为A）
发现忘了给IP打码，就用git reset --hard HEAD^在本地回退了（即本地从A->X，而远端仍然为A）
打码提交（即本地X->B，本地库最新为B，而远端仍然为A）。此时远端库最新的A节点和本地库最新的B节点冲突了，直接提交会出现错误：

 ➜  imagebed git:(master) git push -u origin master
To github.com:zlotus/imagebed.git
 ! [rejected]        master -> master (non-fast-forward)
error: 推送一些引用到 'github.com:zlotus/imagebed.git' 失败
提示：更新被拒绝，因为您当前分支的最新提交落后于其对应的远程分支。
提示：再次推送前，先与远程变更合并（如 'git pull ...'）。详见
提示：'git push --help' 中的 'Note about fast-forwards' 小节。

按照git给出的提示查看Note about fast-forwards一节，发现我遇到的情况叫做non-fast-forward提交，即希望提交B以将分支A抹掉。此时需要使用git push --force -u origin master命令。这种场景不常见，一般只有在没有别人参与的分支提交上能用到，因为强制提交会抹掉X->A分支的所有提交，如果是协作模式下会造成提交丢失。

修改版梅尔系数普

Fri, 21 Aug 2020 21:00:00 GMT

前两周搞定了数据实时传输，这两周多整了点特征，当时就看上古典派语音识别里常用的梅尔系数普了，实现了一下发现简单好用，就打算改一改拿来用。

不废话了直接贴代码

另外，为了把这个主题的两列扩宽，我参考了这里：

修改了themes/icarus/include/style/base.styl24-27行；
修改了themes/icarus/layout/layout.jsx第29行以及themes/icarus/layout/common/widgets.jsx的36行，把8-8-8和4-4-4，该为9-9-9和3-3-3。

年纪大了，得记一下别忘了改不回去了……

将树莓派用作声源

Mon, 10 Aug 2020 09:18:00 GMT

前一阵子跟刘老师聊天发现，不能总是灌10分低端水了，得进军20分中端水……就着树莓派上的麦阵列作为传感器信号源，送到mbp上做分析试试水先。

1 硬件现状

1.1 源端

硬件：树莓派3B+一枚，还是老文章里麦阵列用的那枚；麦阵列还是ReSpeaker-6mic阵列。

系统：用buster-2020-05的版本，装麦阵列驱动有问题，报错：

E: Unable to locate package dkms
E: Package 'libasound2-plugins' has no installation candidate

先换成旧的stretch……

刷了stretch，更新软件包update & upgrade后貌似也会出问题……干脆：

直接用旧版image(2019-04-09)不升级；
手动安装旧版kernel-headers(2019-04-01)：dpkg -i raspberrypi-kernel-headers_1.20190401-1_armhf.deb
将麦阵列驱动git reset --hard回溯到2019年四月份的版本，然后把install.sh里76-77行的升级和内核安装注释掉，再安装就好了。

毕竟我记得去年四月的时候还能用……估计是新系统和驱动不匹配的锅……其中有用的操作：

升级单个软件包sudo apt-get --only-upgrade install apt，全升级的话kernel和kernel-headers也会跟着升级；
用pyenv安装和管理Python版本：Install Python 3.8.1 on Raspberry Pi (Raspbian)
树莓派时间同步：How to sync time with a server on Raspberry Pi?（后来发现是mbp的时间总不同步：sudo sntp -sS time.apple.com）
重启shell的命令是exec "$SHELL"，装完zsh等重启shell会方便很多；

1.2 接收端

我那尚能饭否的mbp……

2 使用PulseAudio进行流媒体传输

2.1 TCP（是不对的）

按照ReSpeaker 6-Mic Circular Array kit for Raspberry Pi的介绍，打算安装最常见的PulseAudio Server，据说可以方便的做流媒体数据源。

修改PulseAudio远程配置，匿名网络访问：

# /etc/pulse/default.pa
load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1;10.0.6.0/24 auth-anonymous=1

开防火墙端口：sudo ufw allow proto tcp to 0.0.0.0/0 port 4713 comment "pulseaudio tcp port"

后来发现tcp访问pulseaudio的目的貌似是控制而不是传输流媒体数据……进一步才发现原来rtp是传输流媒体数据用的……

2.2 RTP（也没搞定）

一开始想得简单，以为直接默认配置就能搞定：

load-module module-null-sink sink_name=rtp
load-module module-rtp-send source=rtp.monitor
set-default-sink rtp

此时并没有指定广播目的IP和端口，pulseaudio就默认用了224.0.0.56和一个随机五位端口号。出现的现象是：

在树莓派上可以通过tcpdump -n net 224.0.0.0/8 -c10看到发包，类似：
```
IP 192.168.1.101.44556 > 224.0.0.56.44668: UDP, length 1292
```
我的连在同一个局域网中的mbp里tcpdump一直是空的。
不论rpi还是mbp的ping到224.0.0.56都是不通的。

看了Multicast UDP not working后使用netstat -gn发现rpi和mbp的组播地址里都没有224.0.0.56，猜测可能是内核把包扔掉了，按照该文章的方法处理：

# macbookpro
netstat -gn
IPv4 Multicast Group Memberships
Group                   Link-layer Address      Netif
224.0.0.1               1:0:5e:0:0:1            en0
224.0.0.251             1:0:5e:0:0:fb           en0

# raspberrypi
 netstat -gn
IPv6/IPv4 Group Memberships
Interface       RefCnt Group
--------------- ------ ---------------------
wlan0           1      224.0.0.251
wlan0           1      224.0.0.1

ping了一下组播组里出现的224.0.0.1和224.0.0.251发现是通的。本来想按照Linux built-in or open source program to join multicast group?写的把224.0.0.56加入两个机器的组播组里，结果rpi试了不行（命令执行成功，但是用netstat或ip maddr show检查都没法写新加的组播地址），而mbp根本没有ip这个命令，我又不太懂iptable这种高端货，天色已晚我也懒得查解决方案了……干脆就着现有组播组里的224.0.0.251用吧：

load-module module-null-sink sink_name=rtp
load-module module-rtp-send source=rtp.monitor destination_ip="224.0.0.251" port=45678
set-default-sink rtp

此时出现新问题，在mbp上tcpdump已经能看到rpi不停的发包，但是用tcpdump -n net 224.0.0.0/8 -c1 -X查看包内容时，发现内容全零，pulseaudio的配置文件怎么改都不行（就rtp相关的几个模块配置参数怎么调都没用），用pulseaudio -v调试模式启动，也看不太懂，遂早早放弃有（后）空（会）在（无）搞（期）……

2.3 小结：战略失败

当需求很简单时，用别人的软件，有学习如何配置的功夫，还不如自己写个小程序实现功能呢……

3 使用python-sounddevice采集/播放音频流

整理一下思路，目的其实很明确，就是将麦阵列采集的数据通过网络传出去。搜了下，用python的sounddevice（以下简称sd）貌似就可以采集/写入音频流，至于如何发送，想了想就用以前用过的pyzmq吧（高速低延时高可拓展）。

sd的流有两种封装，Stream需要numpy，而RawStream更底层，使用的是buffer。虽然看源码Stream版本是在Raw版本之上做的封装，但是并没感觉慢多少，试用zmq发包的时候，rpi的那颗弱鸡CPU一直在7-9%浮动，完全hold住，那就用numpy输出吧，操作起来会方便很多。

（这次树莓派上的python版本控制选用了pyenv，装的python3.8.5）

3.1 采集音频数据

使用sd.query_devices()在rpi上查询音频设备：

  0 bcm2835 ALSA: - (hw:0,0), ALSA (0 in, 2 out)
  1 bcm2835 ALSA: IEC958/HDMI (hw:0,1), ALSA (0 in, 2 out)
  2 seeed-8mic-voicecard: - (hw:1,0), ALSA (8 in, 8 out)
  3 sysdefault, ALSA (0 in, 128 out)
  4 ac108, ALSA (128 in, 128 out)
  5 dmixer, ALSA (0 in, 128 out)
  6 ac101, ALSA (128 in, 128 out)
  7 dmix, ALSA (0 in, 2 out)
* 8 default, ALSA (32 in, 32 out)

0 {'name': 'bcm2835 ALSA: - (hw:0,0)', 'hostapi': 0, 'max_input_channels': 0, 'max_output_channels': 2, 'default_low_input_latency': -1.0, 'default_low_output_latency': 0.005804988662131519, 'default_high_input_latency': -1.0, 'default_high_output_latency': 0.034829931972789115, 'default_samplerate': 44100.0}
1 {'name': 'bcm2835 ALSA: IEC958/HDMI (hw:0,1)', 'hostapi': 0, 'max_input_channels': 0, 'max_output_channels': 2, 'default_low_input_latency': -1.0, 'default_low_output_latency': 0.005804988662131519, 'default_high_input_latency': -1.0, 'default_high_output_latency': 0.034829931972789115, 'default_samplerate': 44100.0}
2 {'name': 'seeed-8mic-voicecard: - (hw:1,0)', 'hostapi': 0, 'max_input_channels': 8, 'max_output_channels': 8, 'default_low_input_latency': 0.005804988662131519, 'default_low_output_latency': 0.008707482993197279, 'default_high_input_latency': 0.034829931972789115, 'default_high_output_latency': 0.034829931972789115, 'default_samplerate': 44100.0}
3 {'name': 'sysdefault', 'hostapi': 0, 'max_input_channels': 0, 'max_output_channels': 128, 'default_low_input_latency': -1.0, 'default_low_output_latency': 0.005804988662131519, 'default_high_input_latency': -1.0, 'default_high_output_latency': 0.034829931972789115, 'default_samplerate': 44100.0}
4 {'name': 'ac108', 'hostapi': 0, 'max_input_channels': 128, 'max_output_channels': 128, 'default_low_input_latency': 0.005333333333333333, 'default_low_output_latency': 0.008, 'default_high_input_latency': 0.032, 'default_high_output_latency': 0.032, 'default_samplerate': 48000.0}
5 {'name': 'dmixer', 'hostapi': 0, 'max_input_channels': 0, 'max_output_channels': 128, 'default_low_input_latency': -1.0, 'default_low_output_latency': 0.125, 'default_high_input_latency': -1.0, 'default_high_output_latency': 0.125, 'default_samplerate': 48000.0}
6 {'name': 'ac101', 'hostapi': 0, 'max_input_channels': 128, 'max_output_channels': 128, 'default_low_input_latency': 0.005333333333333333, 'default_low_output_latency': 0.008, 'default_high_input_latency': 0.032, 'default_high_output_latency': 0.032, 'default_samplerate': 48000.0}
7 {'name': 'dmix', 'hostapi': 0, 'max_input_channels': 0, 'max_output_channels': 2, 'default_low_input_latency': -1.0, 'default_low_output_latency': 0.021333333333333333, 'default_high_input_latency': -1.0, 'default_high_output_latency': 0.021333333333333333, 'default_samplerate': 48000.0}
8 {'name': 'default', 'hostapi': 0, 'max_input_channels': 32, 'max_output_channels': 32, 'default_low_input_latency': 0.008707482993197279, 'default_low_output_latency': 0.008707482993197279, 'default_high_input_latency': 0.034829931972789115, 'default_high_output_latency': 0.034829931972789115, 'default_samplerate': 44100.0}

其中的seeed-8mic-voicecard是我们需要的输入设备，8路输入（2×AC108 ADC，每芯片4路输出，而每芯片都有一路是playback，因此实际是2*3=6mic信号）。为了方便rpi本地测试，AC101（1×DAC，2输入2输出，我觉得就是左右声道？）要用作输出设备。sd的流要用id指定输入输出设备（也就是上面的[2, 6]）：

iodevs = [0, 0]
for idx, d in enumerate(sd.query_devices()):
    if 'seeed-8mic-voicecard' in d['name']:
        iodevs[0] = idx
    elif 'ac101' in d['name']:
        iodevs[1] = idx
rs = sd.Stream(samplerate=48000, device=iodevs, channels=[8, 2], callback=cb, finished_callback=fcb)

流有两种发送方式：阻塞和非阻塞回调，为了方便调试，我用了非阻塞回调的方式（即Stream.start()后立即返回不耽误监控或执行其他命令）。

sd.Stream一旦指定了callback参数就会使用非阻塞模式运行，其函数签名：

callback(indata: ndarray, outdata: ndarray, frames: int, time: CData, status: CallbackFlags) -> None

indata是输入设备传来的数据，我用的48kHz采样率，每次回调传来的都是(512, 8)的numpy数组，基本上10毫秒一组数据；
outdata是传给输出设备的数据，我的输入输出配置是[8, 2]，因此不能直接把indata复制给输出，图省事我就前后四个数分别求mean，把8个数强行压成两个数；
frames是帧数，我这里每次都是512；
time是一个CFFI的C结构体，能用的属性有time.inputBufferAdcTime（输入开始时间）、time.outputBufferDacTime（输出开始的时间）、time.currentTime（本次callback被调用的时间）。
status没用过不知道，看起来可以用来在回调里发送指令终止回调或终止流。

一旦完成输入数据到输出数据的复制，插在AC101上的音响就有声音了，能感觉到很微小的延迟，完全够用了。

最后就剩在回调里写上pyzmq的发送，如此发送端就完成了。这里有个小问题，就是pyzmq直接发送numpy是不行滴，直接发送的话代码虽然可以运行，但zmq会使用Python的memoryview直接将numpy数组转换为字节发出去。如此一来，在接收端是无法重建数组的，因为丢失了shape和dtype等元数据。按照官方解决方案，使用多段发送标识SNDMORE先发送数组属性，在发送数组内容即可在接收端重建数组了：

def send_array(socket, A, flags=0, copy=True, track=False):
    """send a numpy array with metadata"""
    md = dict(
        dtype = str(A.dtype),
        shape = A.shape,
    )
    socket.send_json(md, flags|zmq.SNDMORE)
    return socket.send(A, flags, copy=copy, track=track)

def recv_array(socket, flags=0, copy=True, track=False):
    """recv a numpy array"""
    md = socket.recv_json(flags=flags)
    msg = socket.recv(flags=flags, copy=copy, track=track)
    buf = memoryview(msg)
    A = numpy.frombuffer(buf, dtype=md['dtype'])
    return A.reshape(md['shape'])

发送端代码如下：

import sounddevice
import numpy as np
import zmq
import sys


class SdSender(object):
    def __init__(self, host='*', port=9000):
        self.__frame_idx = 0
        self.__frame_time = 0
        self.__device = self.__init_device()

        context = zmq.Context()
        self.__zmq_socket = context.socket(zmq.PUB)
        self.__zmq_socket.bind(f"tcp://{host}:{port}")

        self.__verbose = False

    def __init_device(self):
        iodevs = [0, 0]
        for idx, d in enumerate(sounddevice.query_devices()):
            if 'seeed-8mic-voicecard' in d['name']:
                iodevs[0] = idx
            elif 'ac101' in d['name']:
                iodevs[1] = idx
        return iodevs

    def send_array(self, A, ct, flags=0, copy=True, track=False):
        """send a numpy array with metadata"""
        self.__frame_idx += 1
        md = dict(
            frame_idx = self.__frame_idx,
            tf = ct,
            dtype = str(A.dtype),
            shape = A.shape,
        )
        if self.__verbose:
            print(f'\r{md["self.__frame_idx"]}', end="", flush=True)
        self.__zmq_socket.send_json(md, flags|zmq.SNDMORE)
        return self.__zmq_socket.send(A, flags, copy=copy, track=track)

    def cb(self, indata, outdata, frames, time, status):
        # 六声道强行用平均数合成双声道(512, 8) -> (512, 2)，让rpi本机也输出声音方便调试
        outdata[:] = np.hstack( (np.mean(indata[:, 0:4], axis=1, keepdims=True),
                                np.mean(indata[:, 4:8], axis=1, keepdims=True)) )
        # 发送音频原始8路数据
        self.send_array(indata, time.currentTime)

    def fcb(self):
        print('finished!')

    def run(self, verbose=False):
        self.__verbose = verbose
        try:
            with sounddevice.Stream(samplerate=48000, device=self.__device, channels=[8, 2],
                                    callback=self.cb, finished_callback=self.fcb) as rs:
                input()
        except KeyboardInterrupt as ki:
            self.__zmq_socket.close()
            print('exit!')
            sys.exit(0)
        except Exception as e:
            raise Exception

if __name__ == "__main__":
    sd = SdSender()
    sd.run(verbose=True)

3.2 接收音频数据

使用sd.query_devices()在mbp上查询音频设备，可以看到mbp就1-in-1-out，都是双通道，很朴实（我修改了mbp的midi音频设置，将采样率从默认的44100该为48000，输出44100的话，播放48000的数据明显会…慢…）：

> 0 Built-in Microphone, Core Audio (2 in, 0 out)
< 1 Built-in Output, Core Audio (0 in, 2 out)

0 {'name': 'Built-in Microphone', 'hostapi': 0, 'max_input_channels': 2, 'max_output_channels': 0, 'default_low_input_latency': 0.0027708333333333335, 'default_low_output_latency': 0.01, 'default_high_input_latency': 0.012104166666666666, 'default_high_output_latency': 0.1, 'default_samplerate': 48000.0}
1 {'name': 'Built-in Output', 'hostapi': 0, 'max_input_channels': 0, 'max_output_channels': 2, 'default_low_input_latency': 0.01, 'default_low_output_latency': 0.012291666666666666, 'default_high_input_latency': 0.1, 'default_high_output_latency': 0.021625, 'default_samplerate': 48000.0}

接收端代码如下：

import sounddevice
import numpy as np
import zmq
import sys


class SdReceiver(object):
    def __init__(self, host='10.0.6.223', port=9000):
        self.__device = self.__init_device()

        context = zmq.Context()
        self.__zmq_socket = context.socket(zmq.SUB)
        self.__zmq_socket.connect(f"tcp://{host}:{port}")
        self.__zmq_socket.setsockopt_string(zmq.SUBSCRIBE, '')

        self.__verbose = False

    def __init_device(self):
        iodevs = [0, 0]
        for idx, d in enumerate(sounddevice.query_devices()):
            if 'Built-in Microphone' in d['name']:
                iodevs[0] = idx
            elif 'Built-in Output' in d['name']:
                iodevs[1] = idx
        return iodevs

    def recv_array(self, flags=0, copy=True, track=False):
        """recv a numpy array"""
        md = self.__zmq_socket.recv_json(flags=flags)
        msg = self.__zmq_socket.recv(flags=flags, copy=copy, track=track)
        if self.__verbose:
            print(f'\r{md["frame_idx"]}: {md["tf"]}', end="", flush=True)
        buf = memoryview(msg)
        A = np.frombuffer(buf, dtype=md['dtype'])
        return A.reshape(md['shape'])

    def cb(self, indata, outdata, frames, time, status):
        rpi_8mic_data = self.recv_array()
        outdata[:] = np.hstack( (np.mean(rpi_8mic_data[:, 0:4], axis=1, keepdims=True),
                                np.mean(rpi_8mic_data[:, 4:8], axis=1, keepdims=True)) )

    def fcb(self):
        print('finished!')

    def run(self, verbose=False):
        self.__verbose = verbose
        try:
            with sounddevice.Stream(samplerate=48000, device=self.__device, channels=[2, 2],
                                    callback=self.cb, finished_callback=self.fcb) as ss:
                input()
        except KeyboardInterrupt as ki:
            self.__zmq_socket.close()
            print('exit!')
            sys.exit(0)
        except Exception as e:
            raise Exception

if __name__ == "__main__":
    sd = SdReceiver()
    sd.run(verbose=True)

3.3 小结

吐槽：明确目标直接写代码，比无头苍蝇似的瞎配PulseAudio简单太多了。

4 总结

python-sounddevice每次调用callback传出来的是一个512帧的数组，即采样率48000Hz时约0.01067秒的数据，数据类型为float32，每个数字4字节，一个回调输出512*8*4=16384字节，如果按秒算的话就是48000*8*4=1,536,000字节，大概1.465MB/s。以前在单位都是千万十万的交换机，没仔细抠门过带宽问题，在上海基地用的这个民用wifi很明显受不了这种流量……延迟极大……（这时候想想人家mp3，192kHz几分钟的歌才4/5M，真NB）

这种极端环境下，ØMQ这种“假消息队列”的劣势就显现出来了，作为仅实现了“消息”和“队列”功能的超轻量级库，zmq没有持久化，默认缓存就几十兆，我试了下大概能存不到半分钟数据……订阅者消化能力太差就会导致缓存不够旧数据丢失，然而我就是喜欢zmq的这种朴素感🤦‍。反正树莓派上sd卡也不敢做缓存，搞不好写一写就坏了……后面在研究研究zmq的其他连接模式，毕竟宝藏库。

接下来就是利用音频数据进行分析了，明天试试把mfcc调个参魔改一下，看能不能水一篇20分的中端……

我租了个巨便宜的VPS

Fri, 31 Jul 2020 21:00:00 GMT

前几天不能面向搜索编程了，码农一旦没法使用Stack Overflow就萎了。于是调研了一晚上VPS……打算能跑点没啥算力的程序，顺便也将科学技术掌握在自己手中。

:::caution 仅限技术交流！ :::

1 背景环境

最终在某论坛老帖某乎某浪里发现，有个来自毛熊的VPS，按汇率一年115¥，速度、延迟都能接受，就冲动消费了。经过实测延迟发现，其TTK机房（新西伯利亚，据说针对5%-10%的中国线路友好）和DataLine机房（号称CN2对大多中国线路友好）对我的陕西电信来说，延迟/丢包最优，因此，目前把主机建在TTK机房了。

家里有个刷了Openwrt的树莓派，以前用老科学工具，配置的影子R，搜了搜，准备docker个影子R镜像在VPS上。影子R作为一种生产力工具，不值得在部署环节浪费太多精力，毕竟编译部署也挺麻烦的，docker沙箱又方便又相对安全，很适合我这种懒汉。

这个justhost.ru据说是个老服务商了，主攻低端市场（比如我），虽然延迟和丢包有点多，但是不太影响使用，美中不足的是，网站是纯俄语的 🤦‍♀️ 不翻译完全不知道在说什么……（像我这种语言小天才，看日语拉丁系都能连蒙带猜，但俄语真特么是异星语言……）此外，他们家的售后也挺给力的。

2 部署影子R

VPS选用的最常见的CentOS 7。

2.1 部署docker镜像

首次登录好习惯改密码（为了方便，应该把zsh、git、oh-my-zsh、vim和tmux装上。）：

# VPS上改密码
passwd
# 电脑上上传秘钥进行ssh免密登录
ssh-copy-id root@193.38.xxx.xxx

sudo yum update && sudo yum -y install zsh git vim tmux
chsh -s $(which zsh)
sh -c "$(wget -O- https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

安装docker：

# 安装docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker
sudo systemctl start docker

拉影子R镜像，写默认配置启动：

docker pull teddysun/shadowsocks-r
mkdir -p /etc/shadowsocks-r
cat > /etc/shadowsocks-r/config.json <<EOF
{
    "server":"0.0.0.0",
    "server_ipv6":"::",
    "server_port":9000,
    "local_address":"127.0.0.1",
    "local_port":1080,
    "password":"xxxxxxxxxxx",
    "timeout":120,
    "method":"aes-256-cfb",
    "protocol":"origin",
    "protocol_param":"",
    "obfs":"plain",
    "obfs_param":"",
    "redirect":"",
    "dns_ipv6":false,
    "fast_open":true,
    "workers":1
}
EOF

docker run -d -p 9000:9000 -p 9000:9000/udp --name ssr9000 --restart=always -v /etc/shadowsocks-r:/etc/shadowsocks-r teddysun/shadowsocks-r

2.2 安装BBR加速

BBR是谷歌开源的一个TCP拥堵问题解决方案。

2.2.1 一键部署

wget --no-check-certificate https://github.com/teddysun/across/raw/master/bbr.sh && chmod +x bbr.sh && ./bbr.sh

2.2.2 手动部署（参考） - 升级内核

一键部署真相不明，也可以自己部署，并不麻烦。首先检查自己的系统内核版本：

➜  ~ uname -r
3.10.0-514.2.2.el7.x86_64

低于4.10的得升内核，可使用 ELRepo 源更新：

sudo rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
sudo rpm -Uvh http://www.elrepo.org/elrepo-release-7.0-2.el7.elrepo.noarch.rpm
sudo yum --enablerepo=elrepo-kernel install kernel-ml -y

确认升级结果：

➜  ~ rpm -qa | grep kernel
kernel-ml-5.7.9-1.el7.elrepo.x86_64
kernel-tools-libs-3.10.0-1127.13.1.el7.x86_64
kernel-debug-devel-3.10.0-1127.13.1.el7.x86_64
kernel-3.10.0-1062.el7.x86_64
kernel-tools-3.10.0-1127.13.1.el7.x86_64
kernel-headers-3.10.0-1127.13.1.el7.x86_64
kernel-3.10.0-1127.el7.x86_64
kernel-3.10.0-1127.13.1.el7.x86_64

通过设置默认引导为 grub2 ，来启用5.7.9内核，显示 grub2 菜单中的所有条目，结果类似下面的输出：

➜  ~ sudo egrep ^menuentry /etc/grub2.cfg | cut -f 2 -d \'
CentOS Linux (3.10.0-1127.13.1.el7.x86_64) 7 (Core)
CentOS Linux (5.7.9-1.el7.elrepo.x86_64) 7 (Core)
CentOS Linux (3.10.0-1127.el7.x86_64) 7 (Core)
CentOS Linux (3.10.0-1062.el7.x86_64) 7 (Core)
CentOS Linux (0-rescue-1cfc3bd119f34aa79df425015ceaaeee) 7 (Core)

我想用的5.7.9在输出菜单的第二行，而菜单条目索引是从0开始的，因此我需要选择菜单索引为1的条目5.7.9作为grub2启动项：

sudo grub2-set-default 1
reboot

完成重启后检查内核：

➜  ~ uname -r
5.7.9-1.el7.elrepo.x86_64

2.2.3 手动部署 - 启动BBR

要启用 BBR，要修改sysctl配置：

echo 'net.core.default_qdisc=fq' | sudo tee -a /etc/sysctl.conf
echo 'net.ipv4.tcp_congestion_control=bbr' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

检查结果，出现类似的输出即为成功：

➜  ~ sudo sysctl net.ipv4.tcp_available_congestion_control
net.ipv4.tcp_available_congestion_control = reno cubic bbr
➜  ~ sudo sysctl -n net.ipv4.tcp_congestion_control
bbr

检查模块加载状态：

➜  ~ lsmod | grep bbr
tcp_bbr                20480  15

清理无用老旧内核（可选）：

yum remove $(rpm -qa | grep kernel | grep -v $(uname -r))

3 编译Python 3.8（参考）

最近3.8用习惯了，想整个不然不舒服。在VPS上编译很快的，可不是树莓派这种便宜货上的速度 😏。

更新并安装依赖：

sudo yum -y update
sudo yum -y groupinstall "Development Tools"
sudo yum -y install openssl-devel bzip2-devel libffi-devel

确认gcc已安装（上面清理老旧内核的可能把gcc顺道清理了，得装回来……）：

➜  ~ gcc --version
gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-39)
Copyright © 2015 Free Software Foundation, Inc.
本程序是自由软件；请参看源代码的版权声明。本软件没有任何担保；
包括没有适销性和某一专用目的下的适用性担保。

下载Python3.8.5：

sudo yum -y install wget
wget https://www.python.org/ftp/python/3.8.5/Python-3.8.5.tgz
tar xvf Python-3.8.5.tgz
cd Python-3.8.5/

运行configure文件准备安装环境、make并安装：

./configure --enable-optimizations
sudo make altinstall

确认安装结果：

➜  ~ python3.8 --version
Python 3.8.5
➜  ~ pip3.8 --version
pip 20.1.1 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)

4 安装Nginx

我装Python3，其中一个原因就是想试一下python -m http.server 8000这个单进程单线程的简易http服务器。用aria2c去拖大文件，不论split配多少都是单块下载。因此，要进行segmented文件下载，得要整个简约而不简单的发布。

辣么，Linux下大家自然而然会想到，大红大紫到快过气的Nginx啦~

安装并查看EPLE源：

sudo yum install epel-release
sudo yum repolist

安装nginx：

sudo yum install nginx

设置服务：

sudo systemctl enable nginx

启动/重启服务：

sudo systemctl start nginx
sudo systemctl restart nginx

开防火墙服务并刷新防火墙配置使生效：

sudo firewall-cmd --zone=public --permanent --add-service=http
sudo firewall-cmd --reload

查看防火墙服务/端口策略：

sudo firewall-cmd --list-service
sudo firewall-cmd --list-ports

安装netcat进行连接测试：

yum install nmap-ncat
nc -zv 193.x.x.x 80

5 配置Nginx

配置文件在：

vim /etc/nginx/nginx.conf

一开始八成都会有403错误，因为配置第一行user nginx指的是使用nginx用户运行nginx服务。那么，我们使用root用户新建的文件夹和文件都不能访问，为了懒省事，干脆改成user root。

在http域中，添加连接数限制，每秒并发16个连接：

    limit_conn_zone $binary_remote_addr zone=connaddr:10m;
    limit_req_zone $binary_remote_addr zone=reqaddr:10m rate=16r/s;

在server域中详细定义connaddr和reqaddr，每个地址允许16个连接，每个请求允许并发16个连接，这玩意调大调小得自己试：

            limit_conn connaddr 16;
            limit_req zone=reqaddr burst=16;

在server域指定该虚拟主机的根目录：

        root         /root/webroot;
        index        index.html;

添加一个location块作为静态文件服务，开启auto_index自动文件索引，需要注意的是，其中的alias如果换成root，则访问的路径会变成/root/webroot/downloads/downloads/，即root会使url自动加上location后面的路径。因此，我选用alias加强可读性：

        location /downloads {
            alias /root/webroot/downloads;
            charset utf-8;
            limit_conn connaddr 16;
            limit_req zone=reqaddr burst=16;
            autoindex on;
            autoindex_exact_size off;
            autoindex_format html;
            autoindex_localtime on;
        }

如此，一个简约而不简单的文件下载服务就搭好了，访问http://193.x.x.x/downloads就可以看到简陋的"index of downloads"了。当然，这个文件服务器还是可以继续升级改造的，网上似乎有美化教程，我懒得弄了，值得一提的就是，可以简单的在上面location域最后再加两行：

        location /downloads {
            ...
            auth_basic "Authorized users only";
            auth_basic_user_file /etc/nginx/htpasswd;
        }

然后新建一个/etc/nginx/htpasswd文件，里面写一行用在线htpasswd生成工具生成的加密用户名密码，重启nginx再次访问http://193.x.x.x/downloads就会发现弹出输入用户名密码的窗口了。至此，文件服务端的基本功能已经完备。

接下来，就是用aria2c多线程拖文件了，其最主要的配置（参考）有：

# 单个任务最大分片数，默认为5，我们可以改成16
split=16
# 断点续传
continue=true
# 最小文件分片大小，添加任务时可指定，取值范围1M - 1024M，默认为20M
# 假定size=10M，文件为20MB，则使用两个来源下载；文件为15MiB 则使用一个来源下载；
# 这个属性的大小应该按照任务的实际情况即网速进行调整。
min-split-size=10M

使用Nginx作为文件服务器的思路为：找到大文件，先下载到vps上（因为vps在外面的速度很快，我这个贱民vps都号称200M带宽），然后使用vps的Nginx作为文件服务器，从里面利用文件分片，并发多连接拖。自己搭文件服务的好处是没有并发连接数、下载超时、重传次数之类的限制，想连多少，想下多久，想断点续传多少次，都随自己。

总结

国家强大了，我们的汇率买美帝的vps，至少三五百一年，而我们的汇率买毛熊的vps，只要一百出头，也许美帝主机确实性能和网络状态要好一些，但比起价钱，毛熊的主机就跟白嫖差不多。

再次祝愿祖国母亲繁荣昌盛！生生不息！Live Long and Prosper！

关于OAuth2的密码式令牌

Sat, 04 Jul 2020 23:00:00 GMT

想写个不需要登录，无需维护Session或Cookie等状态的纯RESTful API，但是又需要有身份认证和权限鉴别功能。比如我有一套爬来的金融数据API，想让指定的用户使用，其他人访问就报401。最近用FastAPI，里面提供了OAuth2以及scopes的密码式令牌鉴权机制，十分方便，但是部分场景也容易造成信息泄露。

:::important OAuth2的密码式令牌应在可信任网络中使用。 :::

OAuth2密码式令牌应用场景

众所周知OAuth2有四种应用场景各不相同的鉴权方式，其中，密码式可以说是在互联网环境中最不安全的一种了，因为你需要将你在诸如微信的用户名密码一类的信息告诉一个第三方应用，而后第三方应用拿着你的用户名密码去向微信申请数据。如果是在互联网上使用这种验证方式，你必须极度信任这个第三方应用，不然就是社会性自杀。

那么，这样一个危险的鉴权方式有什么实际作用呢？那当然是可控网络环境中，对各业务系统API进行集中访问控制了——毕竟现在微服务这么火，就算是内网应用也应该试试开放几个API吐出点数据——这样PPT上就可以写打破数据孤岛了✌️。

比如，我有很多业务系统，以系统A为例。a.com开放了两个API：

查看当前用户的信息http://a.com/me；
查看当前用户拥有的数据条目http://a.com/me/items。

这时候有人想调用这俩API，而A系统管理员只希望指定的人用，此外，还有XYZ的各种业务系统，都有这种需求，如何在不使用session、cookie这种有状态身份认证的情况下（调用API还要先认证个session太麻烦了）直接在请求中附带一个通行证就调用API，还要保证安全和权限分级呢？

OAuth2密码式令牌应用环境

密码式令牌提供了一个简单的解决方案：

在A系统上开一个发通行证access_token的窗口：http://a.com/token。

系统中有个加解密的秘钥SECRET_KEY；
通行证窗口是一个可以被A系统全信任的窗口，不私存用户名密码，就是个工具窗口。
通行证窗口接受用户认证信息，返回一个jwt库使用秘钥SECRET_KEY加密的通行证。
通行证窗口接受方式规定为HTTP POST方式。接受如下的表单，其中scope为表示权限的字符串，以空格为分隔符：
```
grant_type: password
scope: me items
username: johndoe
password: secret
```
通行证窗口拿到用户名密码后确认身份，并取出库中的权限列表与请求中的权限列表进行核对，如果请求的权限多于在册的权限，则http-401，反之则放行。

通行证窗口返回的通行证为json格式，通行证的内容包含认证用户ID、权限列表、通行证有效期，例如

{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIiwic2NvcGVzIjpbIm1lIiwiaXRlbXMiXSwiZXhwIjoxNTk0MTI2MjkxfQ.AimqzTZg1t7XHstWi-048prkRAPv6-m-IM9OfGYio8A","token_type":"bearer"}
// 其中access_token解密后的明文形为
{'sub': 'johndoe', 'scopes': ['me', 'items'], 'exp': 1593831859}

A系统提供了很多API：

查看当前用户的信息http://a.com/me；
查看当前用户拥有的数据条目http://a.com/me/items。
...
系统中有个加解密的秘钥SECRET_KEY，与发通行证的窗口用的一样；
这些API都有身份验证机制，具有独立的权限列表要求，需要提供OAuth2通行证令牌，jwt库使用秘钥SECRET_KEY对令牌解密，以验明正身。

A系统管理员维护着一个用户及权限表，包括用户名username（如johndoe）、密码hashed_password、权限列表scope（如['b/me', 'b/items']）。

OAuth2密码式令牌调用流程

此时，第三方系统B想要调用业务系统A的API，比如有人想要调用http://a.com/me，那么A系统如何认证用户和权限呢？

B需要获取A库表中的某个用户名密码：

这个动作可以是A管理员给B的，比如我A系统就开一个API专用账户，你B拿着这个账号就随便临幸我A吧。（这种通常权限开的尺度比较大）
也可以是A的一个用户给B的，用户aaa表示你B系统可以去A系统拿我的某些数据。

B拿着用户名密码去A的通行证窗口申请通行证：

通行证窗口就是负责接收用户名密码，确认在A的库表中后，发通行证。
查无此人直接http-401。

B拿到通行证，在每一次对A系统的API请求Header中附带这个通行证：

例如，在访问a.com/me时加上Authorization头部字段，其值形为Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIiwic2NvcGVzIjpbIm1lIiwiaXRlbXMiXSwiZXhwIjoxNTk0MTI2MjkxfQ.AimqzTZg1t7XHstWi-048prkRAPv6-m-IM9OfGYio8A。

A的API会拿到Authorization头部字段，取出其中的通行证，解密，获取其中的用户名、权限、有效期：

若令牌可解密，且在有效期内，比对API所需的权限与请求通行证提供的权限，若提供满足所需，则API响应并返回，反之则http-401。

OAuth2密码式令牌代码示例

from datetime import datetime, timedelta

import jwt
from jwt import PyJWTError
from passlib.context import CryptContext

from fastapi import Depends, FastAPI, HTTPException, Security, status
from fastapi.security import (
    OAuth2PasswordBearer,
    OAuth2PasswordRequestForm,
    SecurityScopes,
)

from typing import Optional, List
from pydantic import BaseModel, ValidationError

# to get a string like this run:
# openssl rand -hex 32
SECRET_KEY = "4ff135e7c8c7375a00738b8f02cc016a7983ea345fe35735900495bea0cf9ce9"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30


app = FastAPI()
VERSION = '1.0'

fake_users_db = {
    "johndoe": {
        "username": "johndoe",
        "full_name": "John Doe",
        "email": "johndoe@example.com",
        "hashed_password": "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW",
        "disabled": False,
    },
    "alice": {
        "username": "alice",
        "full_name": "Alice Chains",
        "email": "alicechains@example.com",
        "hashed_password": "$2b$12$gSvqqUPvlXP2tfVFaWK1Be7DlH.PKZbv5H8KnzzVgXXbVxpva.pFm",
        "disabled": True,
    },
}

class Token(BaseModel):
    access_token: str
    token_type: str


class TokenData(BaseModel):
    username: str = None
    scopes: List[str] = []


class User(BaseModel):
    username: str
    email: Optional[str] = None
    full_name: Optional[str] = None
    disabled: Optional[bool] = None


class UserInDB(User):
    hashed_password: str


pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(
    tokenUrl="/token",
    scopes={
        "me": "Read information about the current user.", 
        "items": "Read items."
    },
)


def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)


def get_user(db, username: str):
    if username in db:
        user_dict = db[username]
        return UserInDB(**user_dict)


def authenticate_user(fake_db, username: str, password: str):
    user = get_user(fake_db, username)
    if not user:
        return False
    if not verify_password(password, user.hashed_password):
        return False
    return user


def create_access_token(data: dict, expires_delta: timedelta = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt


async def get_current_user(security_scopes: SecurityScopes, token: str = Depends(oauth2_scheme)):
    # Request Headers里添加了: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIiwic2NvcGVzIjpbIm1lIiwiaXRlbXMiXSwiZXhwIjoxNTkzODMyMTM2fQ.Ulq6S2zg0kETKdS_3NhcFho9M4-JhzHXcXWPZQJm0Cc
    # curl -X GET "http://localhost:8910/users/me/" -H "accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIiwic2NvcGVzIjpbIm1lIiwiaXRlbXMiXSwiZXhwIjoxNTkzODMyMTM2fQ.Ulq6S2zg0kETKdS_3NhcFho9M4-JhzHXcXWPZQJm0Cc"
    if security_scopes.scopes:
        authenticate_value = f'Bearer scope="{security_scopes.scope_str}"'
    else:
        authenticate_value = f"Bearer"
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": authenticate_value},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM]) # payload解密为 {'sub': 'johndoe', 'scopes': ['me', 'items'], 'exp': 1593831859}
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_scopes = payload.get("scopes", [])
        token_data = TokenData(scopes=token_scopes, username=username)
    except (PyJWTError, ValidationError):
        raise credentials_exception
    user = get_user(fake_users_db, username=token_data.username)
    if user is None:
        raise credentials_exception
    for scope in security_scopes.scopes: # security_scopes.scopes为当前请求所要求的scopes权限，如/me为['me']，/me/items为['items', 'me']
        if scope not in token_data.scopes: # token_data.scopes为当前请求的token中持有的scopes权限，如果所需的scopes中有任何一条不在请求持有的的scopes时（即少持有任一条），均禁止访问
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Not enough permissions",
                headers={"WWW-Authenticate": authenticate_value},
            )
    return user


async def get_current_active_user(current_user: User = Security(get_current_user, scopes=["me"])):
    if current_user.disabled:
        raise HTTPException(status_code=400, detail="Inactive user")
    return current_user


@app.post("/token", response_model=Token)
async def login_for_access_token(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(fake_users_db, form_data.username, form_data.password)
    if not user:
        raise HTTPException(status_code=400, detail="Incorrect username or password")
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user.username, "scopes": form_data.scopes},
        expires_delta=access_token_expires,
    )
    return {"access_token": access_token, "token_type": "bearer"}


@app.get("/users/me/", response_model=User)
async def read_users_me(current_user: User = Depends(get_current_active_user)):
    return current_user


@app.get("/users/me/items/")
async def read_own_items(current_user: User = Security(get_current_active_user, scopes=["items"])):
    return [{"item_id": "Foo", "owner": current_user.username}]


@app.get("/status/")
async def read_system_status(current_user: User = Depends(get_current_user)):
    return {"status": "ok"}

:::caution[警告] 在152行中，示例为了方便直接给令牌赋予了请求者索要的权限，在真实情况下，此处应该将请求索要的权限与数据库中记录的权限进行比对，若索要权限大于记录权限，则应产生“未授权”的异常。 :::

总结

在网络环境较为透明可控的场景下，使用OAuth2的密码方式对开放的API进行身份及权限验证，是一种安全、可控、简便的管理方法。除上文描述的方法外，还可以将各应用系统的权限收口统一管理，维护一个用户权限库表，将通行证的发放维护在一个入口中，再于各应用系统中约定同一个加解密秘钥，可进一步方便管理。当然，这些方法的前提必须是网络环境较为透明可控。

不要健康过度

Fri, 15 May 2020 19:49:00 GMT

近一个多月消化有点不那么良，吃多了总感觉反酸，嗓子里总有东西顶着，比较怂就去医学院看了个消化科。虽劳神伤财折腾好几天，情节曲折百转千回，但结果依旧是屁事没有。特此记录，警钟长鸣，停止沙雕行为，不要没事找事。

:::important 本文很无聊，不涉及计算机方面的知识。 :::

现象

快一个月食欲不振（后来想想大概率是心理作用），吃的复杂一点，食道就感觉有胃酸反流，感觉吃多了食道也会顶，有时候打嗝会带有食物或者胃酸，总之就是吃饭没以前那么爽了，果然不爽的时候才知道爽的可贵。

具体测试如下：

牛奶+黄油面包，反酸；
牛奶+麦片，微酸；
水+麦片，没啥问题；
臊子面、油泼面，反酸；
白面条+鸡蛋羹，没啥问题，最多吃多了会有点顶；
酸汤水饺，反酸；
羊血饸饹、麻辣米线等比较刺激的食物，吃完半天或一天后下面也辣，证明消化通畅；
上下通气，暂时没有证据表明消化通路有阻塞。

听说不少人有反酸现象，说不是啥大事。但是我自认为是个敏感而又脆弱的男人，稍微有哪里不对劲我就想让医生帮忙瞅瞅顺手再修修，所以还是打算去医院，不行就让医生拿胃镜搋一搋。（几年前也是同样的症状在省人民医院做过，当时也是屁事没有[捂脸]）

就诊流程

周一（2020-05-11）按钊钊的指导，在微信公众号（西安交大一附院）上挂了交大医学院消化科王医生的号（这个医生特别特别好，墙裂推荐），准备第二天先看看啥情况。

2020-05-12 周二

周一在微信上约的是下午四点多，我怕初来乍到的摸不清流程，就在两点早早到了。首先是挂号，需要十元现金在自助机上办就诊卡。我没有立刻就给就诊卡里充值，是挂号的时候在护士站旁边才临时跑过去充值的。

:::tip[优化 1] 办完就诊卡，应该接着就用自助机充值30元，用以挂号扣费。支付宝、微信、银行卡等都可以。 :::

接下来，不需要在意预约时间，只要是网上预约的，就可以直接去护士站先排预约的号。这里要注意，并不是非要等到预约的时间才去护士站。我是等到快四点才去排号的，结果快五点才轮到我。

:::tip[优化 2] 一上班就应该立刻去护士站抽号，门诊是预约优先，现场排号。也就是预约的一视同仁，谁先排号谁先看。另外，现场拿号的（非预约）要等到所有预约病人看完，才能开始看。 :::

见到医生后，陈述了状况和自己的测试经验，医生觉得不是大问题，推荐先吃药观察，询问我要不要做胃镜，并不推荐做。我觉得看一下心理踏实，就下决心做个胃镜。医生开了好几个申请单，包括验血、查心电图、胃镜药等。此时已经下午五点，我就去一楼缴费，结果医保卡出现问题，收费的医生说刷卡时医保卡报“12至5月不能办理业务”之类的错误信息，让我询问单位医保情况，这时候已经到了下班时间，问哪都不方便，今天先就这么找吧，明天的事交给明天的我。

2020-05-13 周三

上班，九十点钟抽空问了一下医保卡的问题，首先单位人力确定单位社保OK，省医保确定卡状态正常，接着省医保的另一个电话给出建议，有可能是我们这种在学校办过社保的拿的卡号比较特殊，以SNA开头，会让部分医生认为是市医保（医生可能会认为省医保应该以SNS，SNA开头的他们往往认为是市医保），电话建议刷卡时明确告知使用省医保。

:::caution[失误 1] 以后刷医保卡，应该声明刷省医保，以免造成误会。 :::

晚上去药店用医保卡刷了冯姐建议的四磨汤，确定医保卡正常。

2020-05-14 周四

早上去医院缴费，明确刷省医保，一切正常。除了胃镜本身外的项目都可以在医保窗口一次用医保卡刷完，而胃镜在窗口刷了30%后，需要在2号窗口办一个什么结算表，然后拿着表在隔壁3号窗口继续刷医保就行了。总之，全程刷医保卡，完全不需要现金、银行卡、支付宝或微信。

接下来就是胃镜前的检查了。我先去验血了，验血是在2楼西的自助机上刷就诊卡抽号，验血还是很快的，十来个窗口并行，虽然前面排了快一百个人，也没等多久，但是排号单上写的出结果需要两小时。

:::tip[优化 3] 如果是多人协同作战的话，应该在缴费的同时，派一个人去抽号。因为缴费慢在缴胃镜项目的医保表格办理了，其他项目（如化验和药）在缴费的第一个窗口就已经办完了，此时就可以抽号了。 :::

这里不需要等两小时出结果，在手机APP“智慧好医院”上注册（我觉得绑银行卡快一些，我不喜欢用微信授权登录，腾讯知道已经的太多了）登录。在“做检验”->“更多”里就能看到这个线下检验的状态，也可以直接在“查报告”里看到状态和结果，等了不到一个小时就出结果了，在3、4楼的自助机上刷就诊卡取结果，得到化验单一张。

心电图在2楼东，直接排队检查就行，查完现场取结果，基本没等几分钟，得到心电图一张。然后我傻傻的去取药了。

:::caution[失误 2] 胃镜药是在预约后取，拿到化验单和心电图后应立刻去预约胃镜。 :::

等我反应过来都到上午下班时间了，等到下午2:20才开始继续预约，但是这时候预约的就是第二天早上8:30的了，一天没吃饭等做胃镜快饿死了也没做上[捂脸]。

:::tip[优化 4] 窗口预约胃镜需要用就诊卡刷材料费，应该提前充上100备用。 :::

预约完成后去取药，时间还早就先回单位了。

2020-05-15 周五

早上8:30，带上胃镜药，填交疫情调查表和申请单，排队叫号，被叫后等待时喝药，然后做胃镜。感觉医生真的把我当马桶了，搋了几分钟，漫长的我都快走马灯了，唯一的收获就是，可能有点咽炎，算是挂错号了吧[捂脸]。

后记

以后有经验了：

就近逮住一家医院，别老换医院和医生，如此，以往的经验好用，以往的档案也好调，要低熵。
没事别找搋，虽然搋完立马通畅……但是照这个手法，我觉得没问题都有可能搋出问题……
春天换季，敏感的可能有概率出现轻微的消化问题，不能因为不常见就认为是大事。
嗯，没事少去医院，听说最近又严了。

另外，不想在被搋了：

换季注意保暖，别浪，掉体重可都是白花花的蛋白粉；
严格执行中老年作息，采用中老年食谱，进一步降低粉汤羊血加羊肚、羊血饸饹、麻辣米线的频率；
以后吃多了可以试试冯姐的四磨汤+益生菌助消化；
可以把消化系统方面找搋的阈值调高一些……

可能是疫情的debuff，进一步增强了我贪财怕死爱睡觉的属性，再加上突如其来的假期中作息/饮食不规律，以及铁房关门使得运动量大幅减少，导致对身体状态过于敏感，把平时的噪音也当做异常值重视。以后应该大幅加强肉体上的顿感，毕竟单位每年的体检其实已经能排查很多问题了。对于健康不应该过于谨慎，因为入侵式的检查对身体的伤害也是很大的，而且饿了好几天，肉掉了好几斤，这都是汗水和蛋白粉堆出来的肉啊！心疼！

记录一下，本文开头的注意效果是icarus官方文档里用的，看着好看就抄来了。要改的地方在themes/icarus/include/style/article.styl：

article
    /* ... */
    &.article
        /* ... */
        .content
            /* ... 以下为新增样式 */
            .message
                &.message-immersive
                    border-radius: 0
                    margin: 0 -1.5rem 1.5rem -1.5rem
                
                    .message-body
                        border: none

注意修改样式后，部署时使用hexo g -f -d，加上-f强制重新生成样式。

在文章中使用<article>标签即可，比如开头的标签为：

<article class="message message-immersive is-primary">
    <div class="message-body">
    <i class="fas fa-info-circle mr-2"></i>本文很无聊，不涉及计算机方面的知识。
</div>
</article>

原主题中图片是左对齐的，可以通过样式调整为居中，新增a标签的四行即可：

...
article
    ...
    &.article
        ...
        a
            img
                margin: auto
                display: block
...

另外，这个主题中的inline型code块，默认没有padding（我觉得跟文字挤在一起不好看）、没有background-color（我觉得有个背景色块更容易区分）。而且如果这个inline代码块恰好还需要加上超链接<a>标签，像这样GlobalAlloc，那么使用默认主题时就无法区分不带超链接的块和带超链接的块了，只有把鼠标放上去才能看到一个小手。因此，我打算自己加上padding、background-color以及a.code继承超链接的默认颜色：

...
article
    ...
    &.article
        ...
        .content
            ...
            code
                ...
                padding: 1
                background-color: #f9f9f9
                ...
        a
            ...
            code
                color: inherit
                background-color: #f9f9f9
...

后面又添加了了各级标题的加粗、五级标题的斜体：

article
    &.article
        .content
            ...
            h1
                font-size: 1.75em
                font-weight: bold

            h2
                font-size: 1.5em
                font-weight: bold

            h3
                font-size: 1.25em
                font-weight: bold

            h4
                font-size: 1.125em
                font-weight: bold

            h5
                font-size: 1em
                font-weight: bold
                font-style: italic
            ...

在树莓派上部署openwrt

Sun, 03 May 2020 19:49:00 GMT

五一放假，不想写代码不想看书也懒得追番，准备搞事情，把旧iPhone和一块旧树莓派（3B）废物重组一下，让iPhone体验一下Tiktok的沙雕。

打算按照mlapp帖子里的固件和方法整，当然，有关树（Li）莓（nu）派（x）的任何东西都不会那么一帆风顺的……

概况

:::note[理论目标] 无线猫的LAN口接树莓派电口，然后把树莓派的WiFi当做热点用，树莓派写openwrt镜像，配置SSR，用单独的SSID，以实现在不影响现有WiFi和连接设备的情况下，接出一个带有科学功能的上网热点。 :::

现有环境

因为我最近才发现，家里用的TP-LINK的无线猫上已经连了很多设备了，智能音响、扫地机器人、空气净化器、树莓派、手机、电脑、电视等等十几个设备，直接改造TP-LINK影响太大了，而且一时半会上不了网，这个我是不能接受的。那么，只好从主猫上再接出一路WiFi。

目前手里有好几块树莓派（但是我没买4，因为听说type-c有些无伤大雅的设计问题，完美主义者怎么能买这种东西呢？！），3B+、3B、2B我都有，于是选了个3B，因为性能还凑合，而且我只有一个2B舍不得用，要知道2B是不板载无线里性能最NB的了，万一哪天会在比较严格的环境试验这种东西，肯定首选这个没无线功能的了[捂脸]另外，3B+上面有DOA的麦阵列那一套环境，懒得删了，所以选用这个闲置的3B。

iPhone吧是个6S，卡早换新手机上了，你要用Tiktok得骗它。因此，通过某瑞士安全邮箱服务、谷歌地图、一次性手机号服务等AppleID相关操作，再连上有科学功能的树莓派WiFi，它就真以为自己是个硅谷手机了。这个时候，装上Tiktok，就可以绕过字节跳动的分区管理了。

写镜像

使用macOS向SD卡写镜像

失败：用balenaEtcher写镜像直接报错，不管是lean官方的，还是mlapp提供的都说“镜像损坏”。

失败：用macOS的dd强行写，虽然能写进去，但返回值是错误的（unix非0返回值，zsh红箭头），插入树莓派启动失败：

(base) ➜  ~ sudo dd bs=1m if=/Users/zealot/Downloads/openwrt-bcm27xx-bcm2710-rpi-3-squashfs-factory.img of=/dev/rdisk2
Password:
dd: /dev/rdisk2: Invalid argument
247+1 records in
247+0 records out
258998272 bytes transferred in 19.296779 secs (13421839 bytes/sec)

网上搜了一下，推荐用Windows下的分区工具或者Linux下的dd。

使用虚拟机向SD卡写镜像

实在是因为手头拿不出Windows电脑或者USB读卡器[捂脸]。

用以前在virtualbox建好的里的win7，不论怎么设置苹果内置的sdcard reader（虚拟机里显示为一个USB设备，不论mount状态、如何重启虚拟机都不行），都报设备busy的错误：

查看sdcard：

(base) ➜  ~ df -lh
Filesystem     Size   Used  Avail Capacity iused      ifree %iused  Mounted on
/dev/disk1s5  465Gi   11Gi   30Gi    26%  487852 4876640268    0%   /
/dev/disk1s1  465Gi  420Gi   30Gi    94% 2976908 4874151212    0%   /System/Volumes/Data
/dev/disk1s4  465Gi  4.0Gi   30Gi    12%       5 4877128115    0%   /private/var/vm
/dev/disk1s3  465Gi  504Mi   30Gi     2%      41 4877128079    0%   /Volumes/Recovery
/dev/disk2s1   64Mi   17Mi   47Mi    26%     512          0  100%   /Volumes/NO NAME

或是卸载sdcard：

diskutil umount /dev/disk2s1

查帖子说是因为后来的MBP不把读卡器暴露为USB设备了，按这个帖子做：

插入SDcard，在终端里用mount查看分区，确定设备名称。在我的电脑上，显示为“NO NAME”的卷就是SD卡，其对应的设备叫做/dev/disk2s1，而这个s1表示/dev/disk2上的第一个分区，因此设备名其实应该叫做/dev/disk2：

(base) ➜  ~ mount
/dev/disk1s5 on / (apfs, local, read-only, journaled)
devfs on /dev (devfs, local, nobrowse)
/dev/disk1s1 on /System/Volumes/Data (apfs, local, journaled, nobrowse)
/dev/disk1s4 on /private/var/vm (apfs, local, journaled, nobrowse)
map auto_home on /System/Volumes/Data/home (autofs, automounted, nobrowse)
/dev/disk1s3 on /Volumes/Recovery (apfs, local, journaled, nobrowse)
/dev/disk2s1 on /Volumes/NO NAME (msdos, local, nodev, nosuid, noowners)

打开电脑上“Disk Utility.app”，也就是“磁盘工具.app”，找到SD卡然后卸载它，要注意是卸载，而不是推出。另外，可能在做完下一步后还需要在卸载一次，因为macOS有可能自动把SD卡装载回来。
使用下面的命令，要注意的是，-rawdisk后面跟的参数是/dev/disk2，不是/dev/disk2s1。另外，/Users/zealot/VirtualBox\ VMs/WIN7/sdcard.vmdk这个路径写哪都行，图方便我直接放在我的WIN7虚拟机文件夹下了。：

(base) ➜  ~ sudo VBoxManage internalcommands createrawvmdk -filename /Users/zealot/VirtualBox\ VMs/WIN7/sdcard.vmdk -rawdisk /dev/disk2
RAW host disk access VMDK file /Users/zealot/VirtualBox VMs/WIN7/sdcard.vmdk created successfully.

注：若出现类似"...vmdk uuid...does not match /var/root/Library/VirtualBox/VirtualBox.xml"这种报错，可以考虑修改虚拟机配置文件如WIN7.vbox或VirtualBox.xml文件中的相应uuid。

重新配置虚拟机：
确定虚拟机已关闭；
打开“设置”->“存储”，点控制器旁边的“添加虚拟磁盘”，并选择“使用现有的虚拟磁盘”；
点击“注册”，选择上一步中生成的/Users/zealot/VirtualBox\ VMs/WIN7/sdcard.vmdk；此处如果报权限错误，我试了chmod和chown改.vmdk和disk2s1的权限是没用的，我也试了关掉macOS的SIP同样是没用的，必须命令行管理员权限运行sudo VirtualBox才可以。真的不太懂系统权限问题[捂脸]。
双击列表中的sdcard.vmdk，然后就会返回“存储”界面并看到这个设备。
启动虚拟机，看到该设备显示为一个本地磁盘。
这一套做下来，我们的SD卡在win7里就挂载为了一个ATA设备，也就是硬盘，很不幸的是“Win32 Disk Imager”是不认硬盘的。
因此，把4.2修改一下：打开“设置”->“存储”，点控下方的“添加存储控制器”，选择菜单项“添加USB控制器”，这时候列表里多出来一个“USB控制器”，然后再按照上一步中2、3操作添加虚拟磁盘，然后选上“热插拔”和“固态驱动器”，这样就真的把SD卡伪装成USB设备了。此时Win7里出现两块硬盘，一个是ATA设备，一个是USB设备。再打开“Win32 Disk Imager”时，就可以选择这个盘了：

开机搜索名为“openwrt”的无线SSID，连接，进入http://192.168.1.1，用“root/password”登录配置界面。

配置openwrt

先让自己能上网

我家用的TP-LINK的猫，LAN口接树莓派，而这个TP-LINK默认是在192.168.1.1上的，所以先在openwrt配置界面中“网络”->“接口”里改个IP，默认网关写在192.168.1.1上，然后写上俩TP-LINK里用的DNS（我的西安电信通常是61.134.1.4和218.30.19.40，西安移动通常是211.137.130.19）就可以访问互联网了。

配置SS

先把本机的公钥先传到openwrt上，方便ssh登录，然后直接root登录吧，懒得弄用户了。

如果vim时报错遇到"E437: terminal capability "cm" required"，需要执行一下export TERM=xterm。

继续，在openwrt管理页面中配置“ShadowSocksR Plus+”->“服务器节点”，添加一个类型为“ShadowSocksR”的服务器就可以了，我的情况，主机名、端口、密码、加密方式填上，其他默认就可以直接联通了。

github免密push

临时想到的，最近时不时要更新博客，push的时候总是让我输入用户名密码，很烦。因为我的github号是双因子的，push时总要输用户名，然后复制粘贴那个巨长的push key。

github repo的免密push设置也很简单，最关键的是注意仓库的git协议。

本机git仓库配置

在仓库中使用git config -e命令修改配置文件，只有使用git时才可以免密，https不行：

  [remote "origin"]
-         url = https://github.com/your-gh/your-repo.git
+         url = git@github.com:your-gh/your-repo.git
          fetch = +refs/heads/*:refs/remotes/origin/*

如果是hexo之类的博客，cli工具自动集成push功能，那么修改其配置文件的repo目标即可，比如我用的hexo，那么修改_config.yml即可：

  deploy:
    type: git 
-   repo: https://github.com/your-gh/your-repo.git 
+   repo: git@github.com:your-gh/your-repo.git 
    branch: master

远端github配置

可以在你的某个特定github-repo下的“settings”->“deploy key”里写一个公钥，选上允许写权限。这个方法有个缺点，一个库会占一个key，下一个库就不能再用这个key了。

也可以直接在github账号配置的“settings”->“SSH and GPG keys”里写一个SSH公钥，这个号里所有的repo就都可以push了。其实这个方法更简单，推荐。

后记

工作这么多年，除了自学机器学习，最有用的就是去成都培训了一个月的Linux基础知识，打那时候起，就再也不虚Linux环境了，甚至编译报错都敢直接改源码了。所以说，对程序员来说，什么最重要？是以技术为基础产生的信念，遇到问题时，始终相信只要是计算机上的罗辑问题，都是可解的，就算当下搞不定，时间长了总能搞定。

在Ant Design中写动态路由

Thu, 09 Apr 2020 18:54:00 GMT

普通的路由像一个映射，通常就是一个类似/path/sth的字符串，对应一个Project中存在的源码组件/page/sth.js，你只要访问/path/sth，代码就自动去调用/page/sth.js文件展现给用户。但是，有的时候，我们希望访问/path/sth/id，而页面也自动使用/page/sth.js来响应，只不过会将路由中的id以参数的形式告诉sth.js组件，以展现具有相应参数的页面。

比如，我最近在给自己写盯盘程序的UI，我的期望是，当我访问/index/000300这个页面时，调用/page/index/中的某sth.js程序，并且让程序知道path中有个000300的参数。类似的，当我访问/index/000905、/index/000015等页面时，同样调用sth.js，并将000905和000015告诉sth.js。此外，在配置路由的时候，只需要写/index/indexCode就能让程序自动映射到/page/index/中的某sth.js程序就好了。

在Ant Design中，要实现这个功能非常简单，参考动态路由。

约定式路由的动态配置

在我的例子中，我需要明确的配置出路由树，因为程序的侧边栏菜单是直接通过路由树生成的，因此，需要做的就是在配置中如此编写：

{
    // ...其他配置
    routes: [
        {
            path: '/index/:code',
            component: 'index/[code]',
            // ...其他配置
        },
        {
            path: '/fund/:code',
            component: 'fund/[code]',
            // ...其他配置
        }
    ]
    // ...其他配置
}

这样就明确的指出凡是访问/index/:code的（即/index/000905、/index/000015）都使用/page/index/[code].js来渲染；凡是访问/fund/:code的都使用/page/fund/[code].js来渲染。

对于真正的约定式路由就更简单了，只需要将project的文件系统组织成下面的形式：

.
  └── pages
    └── [post]
      ├── index.tsx
      └── comments.tsx
    └── users
      └── [id].tsx
    └── index.tsx

约定式路由会自动翻译成配置的路由（这些路由是不需要我们自己配置的，直接通过文件系统生成，这里只是展示理解方便）：

[
  { exact: true, path: '/', component: '@/pages/index' },
  { exact: true, path: '/users/:id', component: '@/pages/users/[id]' },
  { exact: true, path: '/:post/', component: '@/pages/[post]/index' },
  {
    exact: true,
    path: '/:post/comments',
    component: '@/pages/[post]/comments',
  },
];

获取路由参数

以index/:code到/page/index/[code].js为例，当用户访问/index/000905时，[code].js可以直接通过组件的props.match.params.code拿到URL中的:code参数，也就是例子中的字符串'000905'：

// /page/index/[code].js
import React, { Component } from 'react'
//...
@connect(mapStateToProps, mapDispatchToProps)
export default class IndexPage extends Component {
    constructor(props) {
        super(props);
        this.state = {
            code: this.props.match.params.code,
        };
    }
    //...
}

总结

其实这个功能有点类似layout模板系统，只不过现在的模板是/page/index/[code].js，并通过props获取参数来进行相应的渲染。

Ant Design 4.0中的新版connect函数

Tue, 07 Apr 2020 11:39:00 GMT

Ant Design最近推出了4.0版本，其中我最喜欢的改动是connect函数/装饰器的语法糖，极大的降低了我这种智商欠费者的认知成本……

1 老版本中的`connect`

我们先看看旧版connect函数的官方示例：

import React from 'react';
import { connect } from 'dva';
import ProductList from '../components/ProductList';

const Products = ({ dispatch, products }) => {
    function handleDelete(id) {
        dispatch({
            type: 'products/delete',
            payload: id,
        });
    }

    return (
        <div>
            <h2>List of Products</h2>
            <ProductList onDelete={handleDelete} products={products} />
        </div>
    );
};

// export default Products;
export default connect(({ products }) => ({
  products,
}))(Products);

最后三行的connect函数，第一个参数是mapStateToProps函数，用于将需要的部分state传递进组件Products。示例中虽然没写，但是connect还可以再传递一个参数mapDispatchToProps，用于将封装好的dispatch传递给组件Products。

我原来经常被那一堆括号，和最后的(Products)搞晕，导致忘记最后的那一对括号……

2 新版的`connect`装饰器

上面的代码就变成了这样：

import React from 'react';
import { connect } from 'dva';
import ProductList from '../components/ProductList';

const mapStateToProps = (state) => {
    return { products: state.products }
};
const mapDispatchToProps = (dispatch) => {
    return {
        handleDelete: (id) => {
            dispatch({ type: 'products/delete', payload: id });
        },
    };
};

@connect(mapStateToProps, mapDispatchToProps)
export default class Products extends Component {
    render() {
        return (
            <div>
                <h2>List of Products</h2>
                <ProductList onDelete={this.props.handleDelete} products={this.props.products} />
            </div>
        );
    }
}

mapStateToProps和mapDispatchToProps也都通过装饰器传入了组件的props属性，但是这样的写法确实极大的降低了认知负担。

写在庚子年初的春天

Sun, 15 Mar 2020 11:39:00 GMT

我已经很久没在这个博客下面写非技术类文章了，2020年的初的这几个月，真是开眼界了，不记录一下实在是对不起时间……

世界人民大团结

我是个没有地标打卡习惯的人，说白了是个对大部分事物提不起什么兴趣死宅。好几年前，去北京出过几次差，也并没有一次想要去天安门广场看看。说起来天安门城楼，我记得最清楚的是左右两句标语——“中华人民共和国万岁”和“世界人民大团结万岁”——第一句不必多说，咱自己的地标当然要强调咱自己人了，可这第二句啊，我小时候是一直不知道为啥要留在咱自己人的地标建筑上……

今年，已经是我奔三后的第二年了，高中毕业这十年来，除了对代码感兴趣，也就是科幻、动漫和游戏了。当然，科幻是核心，动漫和游戏最好都带点科幻，大概是因为当下永远没有未来出彩吧。说起科幻，有个问题在我脑子里转了好多年，科幻作品里，只要涉及星际间的描写，作者们都不约而同的把星球写成“同一个星球，同一个政府”，可能在地球这种母星上会有一点点例外，但是也无外乎“东亚联邦”、“北美联邦”这种整合过的科幻政体。

“世界人民大团结万岁”，好像是这么回事，当然，也可能是作者懒得描写星球内部政体细节了吧。不过，更有可能的是，在科幻小时作者的眼中，宇宙里一个弹丸泥球，自己都没完成内部整合，都没有一个组织能够调动起泥球上绝大多数的生产力，就别谈什么星际级别的故事了，火星都别想，甚至月球都别想。人类命运共同体、世界人民大团结，这是科幻概念吗？也许，在成熟的政治家眼中，这是不远的未来——就像在我们码农眼中，未来可能会出现one-for-all的代码互译程序，或是万能容器/虚拟机一样——就是个时间的事，走着走着自然就到了。

最近这三四年里，我除了撸了点铁，也看了点历史故事。历史这东西，配着科幻看，其实很有意思。比如说，一百年前，人类对摩天大楼的幻想，就是高耸入云的建筑里，有各种生活所需的商铺——因为那时候的人对高速电梯没概念，觉得住那么高下来不方便，所以摩天大楼里应该有理发店之类的“民生类店铺”。科学对生活的影响是整体的，方方面面的，估计很难出现这种“有了造摩天大楼的技术却没有造电梯的技术”之类的场景。那么，这个“人类命运共同体”大概也是一样的道理吧。

回到今天，2020年3月15日，一个把消费者憋在家里的日子，消费者们也渐渐觉得，这个庚子年，注定不太平。我们在一月见到了从否认到承认，在二月见到了从遮遮掩掩到众志成城。就在离自己不远的地方，看到的恐惧和愤怒，妥协和牺牲，有发国难财的不法商贩，也有虽千万人吾往矣的医护人员。进入三月，我们自己家算是暂时控制住了，别人家却又上演了我们一二月份的历史，就像在别的国家进行了版本回退——“历史给人类的唯一教训，就是人类从来不吸取教训”。这不，三月过了一半，全球的账面金融都在玩过山车，有不少人开始讨论普选民主、民主集中、专治、自由这种他们自己都不明白，甚至是人类自己都搞不清楚的词语，就像我们也不知道病毒到底算不算生命，或是究竟什么才算生命一样——嗯，约学NLP越觉得自然语言是个极度神奇的事物。

病毒面前主义平等

我是个不喜欢政治课的人，大概率是因为我中考祭出了年级倒数的好成绩，在幼小的心灵里留下了不可磨灭的伤痕。是这几年是因为没办法，喜欢上了看历史故事，就不得不了解政治，话说这个政治跟我差点没及格那个不太一样……这几年的个人感觉，这历史攒多了，一积分就变成了政治；政治攒多了，一积分就形成了文化。中国这片土地，说幸运是真的幸运，核心地带的地形地貌极其丰富，中原土地承载力极高，可割据可一统，北边太冷养不了太多人，东边是大海，南边是海+横断山脉，西边是青藏高原+河西走廊，这唯一的走廊还接着两个国中国作为缓冲——关中平原和四川盆地。中国的地理，就像个大肚子烧瓶，就河西走廊一个小口，咱也不好出去，别人也很难进来，可劲作么，于是，说不幸也真的不幸，咱这儿一夫作难而七庙隳的事也见的太多太多了。

既然可以任性的作，咱就确实作出成果了，比如最近联储又被建国同志绑架印钞——咱武帝和桑弘羊试验过，自此之后，铸币权再不下放，货币政策慎之又慎；（所以啊，我真的不太看好比特币系列）。再比如最近讨论普选民主到底好不好，准四世三公家族的风暴降生、儒生团体的普选领导人、奥斯卡影帝一世、西汉终结者、东汉远爹、大善人、一世而亡者——王莽同志觉得太好了。这估计是蓝星上极度少有的几次，无战乱仅因为错误政策就让天下人口减半、经济崩溃的社会试验了。作为老百姓，有个观点我是十分赞同的，世界上的政府，只应该分为好政府和坏政府，其他分成民主啊、专制啊什么的，都是肉食者的遮羞布而已。汉初我们也试验过，上面都杀破天了，老刘家都快被老吕家连锅端了，老百姓照样黄老之治人口翻番。你看，肉食者厮杀，管我们素食者什么事，只要给我们黄老几十年，你们打到太阳上都没关系。

这两天，咱终于能挤出来一些医疗专家去援助别的地方了，估计老外也开始考虑这种问题了。与其说我们有多好，倒不如说我们试了很多次不好的，其中几十次亡了国，一两次差点灭种，终于发现现在这个好像还能成，先将就着用，边用边修补吧。春秋战国封土建国、秦汉郡县带单分封、北方民族的融入、魏晋南北朝从豪族到士族、唐的朝贡体系、五代十国民族大融（血）合（洗）、宋辽金夏的岁币政策、元明清继续融（血）合（洗）、近现代的各种救亡图存尝试，到如今中国特色社会主义，这一路过来试的太多了。鲁迅先生说历史歪歪扭扭的写着仁义道德，瞧仔细了才发现是吃人二字，可不是么，咱码农一条命令过去成千上万的地址也清空了，那肉食者大笔一挥也会是类似的效果，所以啊，不管是编程还是制定政策，先要多想。

随着生产力的发展，人口越来越多，码农都知道你FAT32管着的那点地址和NTFS的规模是不一样的，教小孩子都说量变引起质变，等到自己这县长郡守州牧就成一样的了吗？人家古希腊城邦普选，是在万把人的时候，人家确实好使着呢。问题是现在动辄亿把人的情形，你还往上直接套普选就显得有点不思进取了，这明摆着稀释选民的股权啊。你建国同志说普选民主好普选民主妙，我丘吉尔也说普选民主是最不差的制度，但是今天病毒来了，完全遵循传播规律，甚至有点好预测，于是，效率被第一次强行搬上了桌面，并且被民众按在了桌面上不能拿下去。这时候确实得讨论一下，各种主义的区别，啥是好的啥是不那么好的，或者说啥是坏的啥是不那么坏的。

科幻作品中的低熵体

怎么在一段特定时间内，简单的判断一个“主义”的优劣，我个人认为啊，降低社会的总熵，是一个比较好的标准。这个熵字，就是科幻作品里经常出现的低熵体那个意思。比如郡县代替了封建，政策一杆子插到底，在西汉看来熵降低了；士族兴起坞堡自治在后几百年融合混战看来，熵降低了，隋唐抵御外族入侵，节度使也看起来熵降低了……这种例子很多，而且并不全是正面例子，但是都是尽量让老百姓继续活下去的例子，留得百姓在就不怕没国建，看昭烈帝带着百姓出荆入蜀的，那都是革命的火种啊。

这片土地上的政权，但凡没跑偏的，都相信“民为邦本，本固邦宁”。只要能有效的组织群众，和谐生产不打架，肉食者有肉吃，素食的有菜吃偶尔还能喝个汤，那就是好的“主义”。说起来最简单做起来最难的方法，比如“实事求是”，出自汉书，两千来年了；比如“放弃幻想”，近现代的发明。政治，从来都不是也不应该是选演员、演说家、道德楷模，而是应该选有能力让老百姓心无旁骛的从事安全生产的人。大家都是三百六十行里出来的，大家都要凭着数学物理化学生物语文英语历史地理政治混饭吃，凭什么你普选民主任命领导人就可以不需要考核专业科目，长得好看的、能说会道的、表情丰富的、能够调动情绪的、甚至擅于造假注水的就可以参与制定政策了？长得好看和制定政策有关系吗？昂，那我们这些丑的怎么办？！！估计啊，棺材里的薪王们要是活过来看到这种人，会叫他们弄臣。

作为死宅，愿意的话甚至可以说说我奴性很重，因为你给我一根网线再临时拼个健身房，只要把粮草供上，我估计就能宅一辈子，我并不需要那种“Do you hear the people sing”式自由，毕竟我不太容易变成angry man，能让我安安稳稳的码代码上B站就成。天下太平的时候你怎么吹自己好都行，不太平的时候老百姓需抱大腿而不得，就容易导致遮羞布的大幅缩水。都说金融的核心是信心，你看政治也是啊。金融危机来了，老百姓相信央妈会稳住大多数人的钱袋子；病毒来了，老百姓相信国家会稳住大多数人的命根子，这就够了。要是有一天老百姓不再相信，那就真的会遇到“Do you hear the people sing”了。现在已经吃了肉的弄臣们，最好要明白过来，有问题的政策是会出人命的，而且那些人命对现役的肉食者来说可不只是数字，太平年景王莽都能十几年死几千万，最后脑袋被人当球踢，更别说最近并不太平了。

人类命运共同体

这次的医疗援助和数据共享只是在病毒突发事件中有了突出体现，全球化的大趋势早已形成且难以扭转，毕竟熵降低了，效率上去了，能享受到的更多了还更便宜了，各国老百姓都是喜闻乐见的。这次是医疗卫生系统的合作，谁知道下一次是不是航空航天船舶核能电子系统的深入合作呢？

人类命运共同体，世界人民大团结，这种事如果真的能成，那我觉得儒家学说再改一改磨合磨合还是可以用的，简称儒家改。从董仲舒天人三策以来，儒家基本就是权力的外衣。衣服嘛，好看很重要，毕竟需要被大众认同，而法家通常是贴身小棉袄，没怎么大改过——正所谓霸王道杂之——外儒内法的组合应该还是能继续用很久的。这种体系建立之初，就“幸运”的遇到武帝这种作大死的，几乎把一个帝王能脑洞出来的点子都试了然后被逼无奈轮台罪己，之后“幸运”的遇到霍光宣帝拼老命软着陆，更“幸运”王莽就更极端的玩起了“普选民主”，基本上把整套体系玩崩了，最后最“幸运”的光武集齐云台二十八将拯救世界，于是除了君权神授这种权力加成以外，君王们又多了个避免苍天警示的重要责任。如此一来，这种原本纯粹为服务权力诞生的体系，居然开始自洽并真的走上了“民为贵，社稷次之，君为轻”的道路，这一路上君比较沉的基本也都沉了。此外，我们的史官制度也是非常NB的古代日志服务器作为辅助。这套体系确实很适合各族人民大团结，因为它不讲自由民主这些概念，它的目的就是让老百姓能在白天安安心心的耕田，在晚上快快乐乐的造人，老百姓即是生产力，也是生产资料，毕竟食色性也，活着并且继续活下去很重要。当然，我们不是复辟者，老百姓的浑浑噩噩直接或间接的导致科技停滞不前，没能形成科学体系，古人的科技树点的太偏了，最后在形成了大清这个人类历史上的集权巅峰，最后被坚船利炮轰的粉碎。虽然这个体系缺点很多，但是优点还是有的，比如千百年来的民族融合。

说起民族融合，不得不提到政治正确，这也是一种民族融合的方式，立竿见影，药效特猛，核心就是我尊重你，我认同你。而我们的民族融合是另一种思路，既然你来了，你要尊重我，你要认同我。听着不好听，药效也慢，但是效果好，毕竟我的东西玩了上千年，稳定啊，你认同我了，大家就都稳定了。政治正确是因为别的民族不是自愿来的，所以我得尊重你啊，毕竟你的先辈们是我强行运来的奴隶；而我们这种恰恰相反，我是灯塔，你们自愿来了，那就要守我的规矩。如果有的地方政治正确这条路走的不顺利，也是可以试试我们过去民族融合的老路，就像股市一样，试了不好可以关掉嘛。

作为科幻伪粉，我还是真的挺希望在有生之年能看到小说里描写的那样，一个星球一个政体，毕竟没见过，挺好奇的。到那时候，生产力应该已经发展到可以让我这种贫下中农从东航买到四折以下去火星的船票了吧。

星辰大海后的柴米油盐

淡扯完了，说回这个病毒。湖北人民真是倒了八辈子血霉，遇到这么个破事，然而就像鲁迅先生说的，悲喜并不相通，估计武汉老百姓早都被“加油”加的麻木了。我是那种吃不了苦的人，现在想到医护人员要带着尿不湿穿着隔离服，勒着护目镜和口罩一干一整天，我就特别虚；想到湖北那边总会有人出现物资短缺，那些得了病毒以外的特殊病情需要照顾而不得，也挺害怕的。但是，悲喜确实不相通，大家也只能慢慢熬了，可能我们离得远的能熬的轻松点，处在漩涡中央的熬的痛苦一些罢了。老百姓嘛，只能希望这些破事不要发生在自己身上，强身健体多读书多思考、尊重概率远离危墙，剩下的看老天的心情。

该说的不该说的说完舒服了很多~以后继续专注更新码农贴。

Python中的协程使用举例

Sat, 22 Feb 2020 18:54:00 GMT

新冠肺炎放假快一个月，新年一开盘暴跌，就又想写跟踪大盘指数的代码了……

由于GIL名声在外，所以Python的线程编程我是从来没实际操作过……不过随着Python3中各大版本对协程支持的力度加大，在同一个进程内，可以考虑通过协程增加代码的执行效率了，尤其是在I/O部分。

在Python3.6/7/8中（尤其是7/8），对协程的支持使得编写一个协程变得异常简单，这里就介绍两种最常见的情况。（本文使用Python3.8版本）

1 异步执行传统函数

举个例子，比如我希望requests.get多个页面http://www.baidu.com，可以这样写：

async def make_requests():
    loop = asyncio.get_event_loop()
    future_list = []
    url = 'http://www.baidu.com'
    for i in range(5): 

        future = loop.run_in_executor(None, requests.get, url)
        future_list.append(future)
    
    response_list = await asyncio.gather(*future_list)
    return response_list

rps_list = asyncio.run(make_requests())
print(rps_list)

主要就是将普通函数放入loop.run_in_executor中生成一个future对象，然后把这些future交给asyncio.gather去统一执行，并返回结果。

注意，requests的复杂请求，如post请求或通过requests.Session设置header后再通过session.send发送的请求，使用asyncio.gather执行会报requests.exceptions.InvalidSchema异常，我猜测可能因为复杂请求调用了线程相关的适配器。

代码异步请求了5次百度页面，结果如下，用timeit测试比同步请求快了4倍左右，还是符合期望的：

[<Response [200 OK]>, <Response [200 OK]>, <Response [200 OK]>, <Response [200 OK]>, <Response [200 OK]>]

2 异步执行协程

这个就更简单了，依然用上面的例子，requests这个库通常是用在同步场景中的。如果希望既要使用异步还要享受requests的友好API，可以试试httpx，这个库包含了异步调用的请求支持，API与同步版的几乎没有差别，十分方便：

async def make_requests():
    async with httpx.AsyncClient() as client:
        url = 'http://www.baidu.com'
        req_task_list, rsp_list = [], []
        for i in range(5): 
            method, data, headers = 'GET', {}, {}
            req_task_list.append(asyncio.create_task(client.request(method, url, data=data, headers=headers)))

        for task in req_task_list:
            rsp = await task
            rsp_list.append(rsp)
    return rsp_list

rps_list = asyncio.run(make_requests())
print(rps_list)

可以看到httpx直接提供了用于异步请求的AsyncCLient，即使是复杂请求也可以进行异步请求了。我们的主要工作就是通过asyncio.create_task批量创建Task，再统一await task即可。

注意，始终要记得await其实就是yield的语法糖，如果创建一个task直接await，然后再创建下一个，就变成同步请求了。

结果以及获得结果的速度与第一节的例子相差无几：

[<Response [200 OK]>, <Response [200 OK]>, <Response [200 OK]>, <Response [200 OK]>, <Response [200 OK]>]

3 总结

通过协程在同一个进程内进行诸如I/O请求的耗时操作，可以极大的提升代码执行效率，而且随着Python大版本的更新，将引入越来越多的异步支持。

自然场景中的中文识别尝试

Sat, 24 Aug 2019 21:09:11 GMT

想做个考试作弊系统[捂脸]……

又想作弊了

最近想整个通过图像识别自然场景中的中文“试卷” -> 自然语言处理 -> 查找题库 -> 返回结果的小程序。目前考虑的是，图像通过树莓派的摄像头产生，将结果输出到柔性墨水屏上。

1 Connectionist Text Proposal Network

据说ctpn算法在长文本上也能够保持一个不错的效果，先试试吧

1.1 虚拟环境

一开始想用pipenv，不过在安装Cython的lock package的时候就挂起不动了，搜了一下估计是跟跟网络和依赖有关系，因此就直接用Python自带的venv做虚拟环境管理了。

虚拟环境主要需要安装tensorflow，所以新建一个tf虚拟空间并激活：

python3 -m venv tf
cd tf
source bin/activate

包依赖有Cython、numpy、opencv。安装numpy之前记得安装sudo apt -y install libatlas-base-dev，不然会报libf77blas.so.3找不到的错误。

pip install numpy
# 直接pip（在2019-09-18）会安装到1.13.1版本的
pip install tensorflow
# 搜了一个新的1.14.0版本的
#wget https://github.com/lhelontra/tensorflow-on-arm/releases/download/v1.14.0-buster/tensorflow-1.14.0-cp37-none-linux_armv7l.whl
# pip install tensorflow-1.14.0-cp37-none-linux_armv7l.whl
proxychains4 git clone https://github.com/eragonruan/text-detection-ctpn.git

测试import tensorflow的时候会报一堆Future Warning。

1.2 安装OpenCV

安装OpenCV很麻烦，单独拉出来写。

1.2.1 准备工作

打开摄像头：sudo raspi-config -> Enable camera。
扩展存储卡空间，以防不测：sudo raspi-config -> Advanced Options -> Expand filesystem。
重启：sudo reboot -h now，检查空间df -h。

可选，清理不常用的程序：

sudo apt-get purge wolfram-engine
sudo apt-get purge libreoffice*
sudo apt-get clean
sudo apt autoremove

1.2.2 安装OpenCV依赖

注意，我在使用lite系统的时候，会遇到关于NEON的cmake错误，在桌面版下一切正常。

更新系统：

time sudo apt update && time sudo apt upgrade && time sudo apt dist-upgrade

安装cmake等开发工具：

sudo apt install -y build-essential cmake unzip pkg-config

安装图片和视频相关库：

sudo apt install -y libjpeg-dev libpng-dev libtiff-dev
sudo apt install -y libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
sudo apt install -y libxvidcore-dev libx264-dev

可选，安装GUI库GTK以及能减少GTK警告的库[捂脸]（名字中的*号可以匹配到ARM版的库）

sudo apt install -y libgtk-3-dev
sudo apt install -y libcanberra-gtk*

为OpenCV安装数值优化库：

sudo apt install -y libatlas-base-dev gfortran

最后安装Python的头文件库：

sudo apt-get install python3-dev

1.2.3 下载OpenCV

下载opencv和附加的模块opencv_contrib，这些附加模块和函数可能会被经常用到：

#proxychains4 wget -O opencv_4.1.1.zip https://github.com/opencv/opencv/archive/4.1.1.zip
#proxychains4 wget -O opencv_contrib_4.1.1.zip https://github.com/opencv/opencv_contrib/archive/4.1.1.zip
proxychains4 wget -O opencv_4.1.0.zip https://github.com/opencv/opencv/archive/4.1.0.zip
proxychains4 wget -O opencv_contrib_4.1.0.zip https://github.com/opencv/opencv_contrib/archive/4.1.0.zip
#proxychains4 wget -O opencv_4.0.1.zip https://github.com/opencv/opencv/archive/4.0.1.zip
#proxychains4 wget -O opencv_contrib_4.0.1.zip https://github.com/opencv/opencv_contrib/archive/4.0.1.zip
#proxychains4 wget -O opencv_4.0.0.zip https://github.com/opencv/opencv/archive/4.0.0.zip
#proxychains4 wget -O opencv_contrib_4.0.0.zip https://github.com/opencv/opencv_contrib/archive/4.0.0.zip

解压：

unzip opencv_4.1.0.zip
unzip opencv_contrib_4.1.0.zip

注意：我尝试编译4.1.1版，在编译到49%的时候总会出现：

[ 49%] Linking CXX shared library ../../lib/libopencv_imgproc.so
[ 49%] Built target opencv_imgproc
make: *** [Makefile:163: all] Error 2

换4.1.0版就好了，耗时数小时。

1.2.4 CMake及编译

使用cmake构建编译，再用make进行编译，这一步非常耗时。先新建一个build文件夹：

cd opencv-4.1.0
mkdir build
cd build

运行cmake，其中：

OPENCV_ENABLE_NONFREE=ON标识可以让我们在OpenCV 4中使用SIFT/SURF等专利算法。
OPENCV_GENERATE_PKGCONFIG=ON生成opencv4.pc用于后面darknet的编译。
注意：保证OPENCV_EXTRA_MODULES_PATH的路径正确，不然会出现类似 sys/videoio.h: No such file or directory 的错误。

cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D OPENCV_EXTRA_MODULES_PATH=~/ocr/opcv/opencv_contrib-4.1.0/modules \
    -D ENABLE_NEON=ON \
    -D ENABLE_VFPV3=ON \
    -D BUILD_TESTS=OFF \
    -D OPENCV_ENABLE_NONFREE=ON \
    -D OPENCV_GENERATE_PKGCONFIG=ON \
    -D INSTALL_PYTHON_EXAMPLES=OFF \
    -D BUILD_EXAMPLES=OFF ..

接下来要为树莓派增加交换区空间，以便能够利用全部的四颗核心，否则可能会因为内存耗尽而挂起编译，打开/etc/dphys-swapfile文件：

sudo vim /etc/dphys-swapfile

修改CONF_SWAPSIZE标识，我们将交换区从100M增加到2048M：

# set size to absolute value, leaving empty (default) then uses computed value
#   you most likely don't want this, unless you have an special disk situation
# CONF_SWAPSIZE=100
CONF_SWAPSIZE=2048

重启交换服务：

sudo /etc/init.d/dphys-swapfile stop
sudo /etc/init.d/dphys-swapfile start

注意：增加交换区空间有可能导致存储卡卡损坏，因为基于闪存的存储器的读写次数是有限的。我们这里仅在编译时增加交换区空间。

编译，用-j4告诉make使用四颗核心，这是最耗时的一步，大约用了4-5小时：

make -j4

安装：

sudo make install
sudo ldconfig

恢复交换区空间，打开/etc/dphys-swapfile文件：

sudo vim /etc/dphys-swapfile

恢复CONF_SWAPSIZE=100，并重启交换服务：

sudo /etc/init.d/dphys-swapfile stop
sudo /etc/init.d/dphys-swapfile start

1.2.5 为Python虚拟环境建立OpenCV 4连接

在我们的tf虚拟环境中建立OpenCV的软链接：

ln -s /usr/local/lib/python3.7/site-packages/cv2/python-3.7/cv2.cpython-37m-arm-linux-gnueabihf.so /home/pi/cn_dect/tf/lib/python3.7/site-packages/cv2.so

软链接的源和目的路径一定要写正确，其中源路径可以在安装时sudo make install命令的输出中看到：

-- Installing: /usr/local/lib/python3.7/site-packages/cv2/__init__.py
-- Installing: /usr/local/lib/python3.7/site-packages/cv2/load_config_py2.py
-- Installing: /usr/local/lib/python3.7/site-packages/cv2/load_config_py3.py
-- Installing: /usr/local/lib/python3.7/site-packages/cv2/config.py
-- Installing: /usr/local/lib/python3.7/site-packages/cv2/python-3.7/cv2.cpython-37m-arm-linux-gnueabihf.so
-- Set runtime path of "/usr/local/lib/python3.7/site-packages/cv2/python-3.7/cv2.cpython-37m-arm-linux-gnueabihf.so" to "/usr/local/lib"
-- Installing: /usr/local/lib/python3.7/site-packages/cv2/config-3.7.py

1.2.6 测试OpenCV

测试虚拟环境中的OpenCV：

Python 3.7.3 (default, Apr  3 2019, 05:39:12)
[GCC 8.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import cv2
>>> cv2.__version__
'4.1.0'
>>>

成功。

1.3 测试text-detection-ctpn

无奈的是ctpn训练好的模型很大，一加载TensorFlow就报错，只好再把swap区改成2048[捂脸]。不知道这么玩下去存储卡能撑多久……

python ./main/demo.py

测试ctpn检测，还是比较慢的，第一张图在树莓派上就用了35秒。我准备再试试chineseocr这种端到端杂烩项目。

2 OCR

大概扫了一眼chineseocr这个项目，估计是用yolo3/darknet做的文本检测，再用基于pytorch的crnn做检测到的文本的ocr。

2.1 虚拟环境

还是用原来的虚拟环境

cd ~/cn_dect/tf
source ./bin/activate

在虚拟环境中安装依赖（由于前面我们在本机上编译了OpenCV，所以不用再装opencv-contrib-python了）：

pip install scipy numpy easydict Cython h5py lmdb mahotas pandas requests bs4 matplotlib lxml pillow web.py keras

2.2 编译 & 配置darknet

下载项目和darknet：

proxychains4 git clone https://github.com/chineseocr/chineseocr.git
proxychains4 git clone https://github.com/pjreddie/darknet.git 
mv darknet chineseocr/

修改darknet/Makefile：

GPU=0
CUDNN=0
OPENCV=1
OPENMP=1

直接make时提示PKG_CONFIG_PAT中找不到opencv.pc，手动帮它找到：

sudo cp /usr/local/lib/pkgconfig/opencv4.pc /usr/local/lib/pkgconfig/opencv.pc
export PKG_CONFIG_PAT=/usr/local/lib/pkgconfig

编译过程出现./src/image_opencv.cpp:12:1: error: ‘IplImage’ does not name a type的错误，这是由于我们用的新版OpenCV导致的兼容性问题，此时需要pull一个补丁：

git fetch origin pull/1348/head:opencv4
git checkout opencv4
make -j4

把darknet/python/darknet.py第48行改成刚编译好的libdarknet.so的路径：

lib = CDLL("/home/pi/cn_dect/chineseocr/darknet/libdarknet.so", RTLD_GLOBAL)

2.3 下载OCR模型

因为是百度网盘上的东西，我用bnd2加了个速。

将下载的所有文件放在models文件夹下。（如果是用python -m http.server 8000做临时中转，wget -r http://192.168.1.100:8000可以递归下载下所有目录和文件）

2.4 安装PyTorch

安装系统依赖：

sudo apt install -y libopenblas-dev libblas-dev m4 cmake cython python3-dev python3-yaml python3-setuptools libatomic-ops-dev

下载并安装：

mkdir pytorch_install && cd pytorch_install
proxychains4 git clone --recursive https://github.com/pytorch/pytorch
cd pytorch
git submodule sync
git submodule update --init --recursive

貌似protobuf这个库有个bug，会导致在编译近半时出现：

[ 43%] Linking CXX executable ../../../bin/protoc
/usr/bin/ld: ../../../lib/libprotobuf.a(arena.cc.o): in function `google::protobuf::internal::ArenaImpl::Init()':
arena.cc:(.text+0x24): undefined reference to `__atomic_fetch_add_8'

需要更新一下protobuf修复bug：

proxychains4 git submodule update --remote third_party/protobuf

因为我试了好几次了，因此用export BUILD_TEST=0跳过测试以缩短编译时间，设置环境并编译：

export NO_CUDA=1
export NO_DISTRIBUTED=1
export NO_MKLDNN=1 
export NO_NNPACK=1
export NO_QNNPACK=1
export BUILD_TEST=0

python3 setup.py build

接下来正式安装，安装前需要注意的是，一定要记得带着上面的export的环境变量安装（因为编译时间太长，有时候编译完了重启就忘了设置环境变量）：

python3 setup.py install

小注意一下：如果安装完成后不切换工作目录直接试就会出现No module named 'torch._C'的异常，因为编译目录下就有一个torch目录，切换工作目录再启动Python即可。

2.5 安装CTC模型

pip install wget
git clone --recursive https://github.com/parlance/ctcdecode.git   
cd ctcdecode   
pip install .

其中--recursive指将引用的第三方git repo一并克隆。安装会持续个把小时，可以追几集番了。

2.6 下载语言模型

不到3个G，挂梯子下载了：

cd chineseocr/models/
proxychains4 wget https://deepspeech.bj.bcebos.com/zh_lm/zh_giga.no_cna_cmn.prune01244.klm

2.7 运行

按自己的情况修改config.py文件，运行python app.py 8080即可。在树莓派3B+上的结果是，内存耗尽[捂脸]总共不到1G的内存，连一个CTC模型都读不进去[捂脸]

更新到最新的app分支

git pull origin app

这下炸出了一个貌似是bug的问题……这个分支（git版本daabebc93a8b4436a3653f83668429ab99eefaea）跟以前最大的不同就是一开始就在用keras和tensorflow创建yolo3的darknet，结果在text/keras_yolo3.py的第285行boxes = concatenate(boxes, axis=0)报错：

>>> boxes  = concatenate(boxes, axis=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/layers/merge.py", line 687, in concatenate
    return Concatenate(axis=axis, **kwargs)(inputs)
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/engine/base_layer.py", line 630, in __call__
    base_layer_utils.create_keras_history(inputs)
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/engine/base_layer_utils.py", line 199, in create_keras_history
    _, created_layers = _create_keras_history_helper(tensors, set(), [])
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/engine/base_layer_utils.py", line 245, in _create_keras_history_helper
    layer_inputs, processed_ops, created_layers)
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/engine/base_layer_utils.py", line 245, in _create_keras_history_helper
    layer_inputs, processed_ops, created_layers)
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/engine/base_layer_utils.py", line 245, in _create_keras_history_helper
    layer_inputs, processed_ops, created_layers)
  [Previous line repeated 2 more times]
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/engine/base_layer_utils.py", line 243, in _create_keras_history_helper
    constants[i] = backend.function([], op_input)([])
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/keras/backend.py", line 3349, in __call__
    run_metadata=self.run_metadata)
  File "/home/pi/cn_dect/tf/lib/python3.7/site-packages/tensorflow_core/python/client/session.py", line 1450, in __call__
    run_metadata_ptr)
tensorflow.python.framework.errors_impl.InvalidArgumentError: You must feed a value for placeholder tensor 'Placeholder_367' with dtype float and shape [2]
         [[{{node Placeholder_367}}]]

我目前的环境是：

Python 3.7.3 (default, Apr  3 2019, 05:39:12)
[GCC 8.2.0] on linux
# TensorFlow版本
>>> tf.__version__
'1.13.1'
# keras版本
>>> K.__version__
'2.2.5'

一步一步的在REPL中调试，只要一concatenate，Placeholder_367就报错，这个Placeholder就是text/keras_detect.py中第23行就初始化了的那个input_shape。不知道为什么，我在我自己的电脑上试了，同样的代码，完全没有问题，咱也不懂不知道，咱也懒得在github上问[捂脸]

其中，环境上的不同在于，电脑用的Python 3.6，TensorFlow 1.14.0，Keras 2.2.4。打算重新写张存储卡用Python 3.6的整套环境在树莓派上试一下，毕竟这张卡上还有波达方向定位的程序呢（用了Python 3.7的协程新特性）。之所以没有用chineseocr项目要求的版本是因为树莓派上安装软件真的不容易[捂脸]

调试代码：

import sys
sys.path.append(r'~/cn_dect/chineseocr')
#sys.path.append(r'~/PycharmProjects/chineseocr')
from config import *
os.environ["CUDA_VISIBLE_DEVICES"] = ''
scale,maxScale = IMGSIZE[0],2048
from text.keras_yolo3 import yolo_text,box_layer,K
import tensorflow as tf
import numpy as np

graph = tf.get_default_graph()##解决web.py 相关报错问题

anchors = [float(x) for x in keras_anchors.split(',')]
anchors = np.array(anchors).reshape(-1, 2)
num_anchors = len(anchors)
num_classes = len(class_names)
K.clear_session()
tf.reset_default_graph()
textModel = yolo_text(num_classes,anchors)
textModel.load_weights(kerasTextModel)
#textModel.load_weights(r'~/PycharmProjects/text.h5')
sess = K.get_session()
image_shape = K.placeholder(shape=(2, ))##图像原尺寸:h,w
input_shape = K.placeholder(shape=(2, ))##图像resize尺寸:h,w


y1,y2,y3 = [*textModel.output]
out = [y1,y2,y3]

num_layers = len(out)
anchor_mask = [[6,7,8], [3,4,5], [0,1,2]]
boxes = []
scores =[]
input_shape = K.cast(input_shape, tf.float32)
image_shape = K.cast(image_shape, tf.float32)
#from keras.utils import plot_model
#plot_model(textModel, to_file='model.png')

def yolo_head(feats, anchors, num_classes, input_shape, calc_loss=False):
    """Convert final layer features to bounding box parameters."""
    num_anchors = len(anchors)
    # Reshape to batch, height, width, num_anchors, box_params.
    anchors_tensor = K.reshape(K.constant(anchors), [1, 1, 1, num_anchors, 2])
    
    grid_shape = K.shape(feats)[1:3] # height, width
    grid_y =tf.tile(K.reshape(K.arange(0, stop=grid_shape[0]), [-1, 1, 1, 1]),
        [1, grid_shape[1], 1, 1])
    grid_x =tf.tile(K.reshape(K.arange(0, stop=grid_shape[1]), [1, -1, 1, 1]),
        [grid_shape[0], 1, 1, 1])
    grid = K.concatenate([grid_x, grid_y])
    grid = K.cast(grid, K.dtype(feats))
    
    feats = K.reshape(
        feats, [-1, grid_shape[0], grid_shape[1], num_anchors, num_classes + 5])
    
    # Adjust preditions to each spatial grid point and anchor size.
    box_xy = (K.sigmoid(feats[..., :2]) + grid) / K.cast(grid_shape[::-1], K.dtype(feats))
    box_wh = K.exp(feats[..., 2:4]) * anchors_tensor / K.cast(input_shape[::-1], K.dtype(feats))
    box_confidence = K.sigmoid(feats[..., 4:5])
    box_class_probs = K.sigmoid(feats[..., 5:])
    
    if calc_loss == True:
        return grid, feats, box_xy, box_wh
    return box_xy, box_wh, box_confidence, box_class_probs


for lay in range(num_layers):
    box_xy, box_wh, box_confidence, box_class_probs = yolo_head(out[lay],anchors[anchor_mask[lay]], num_classes, input_shape)
    #box_xy = (box_xy - offset) * scale
    #box_wh = box_wh*scale
    
    box_score = box_confidence * box_class_probs
    box_score = K.reshape(box_score, [-1, num_classes])
    
    box_mins  = box_xy - (box_wh / 2.)
    box_maxes = box_xy + (box_wh / 2.)
    box =  K.concatenate([
                    box_mins[..., 0:1],  # xmin
                    box_mins[..., 1:2],  # ymin
                    box_maxes[..., 0:1], # xmax
                    box_maxes[..., 1:2]  # ymax
                ],axis=-1)
    
    box = K.reshape(box, [-1, 4])
    
    boxes.append(box)
    
    scores.append(box_score)

concatenate        = tf.keras.layers.concatenate
boxes  = concatenate(boxes, axis=0)

2.8 更换环境再试一遍

由于新的buster系统都是自带Python3.7，于是打算用pipenv创建Python3.6版本的环境：

首先，pipenv在系统只有3.7版本的时候并不能直接创建3.6，所以我手动sudo apt install python3.6；
结果发现并不是那么回事，这时候再次pipenv --python 3.6会报错，大概是说python3.6的distutils找不到模块；
网上说可能是Linux自带的Python损坏，sudo apt install python3-distutils就好了，我试了一下，3.7确实是好了，3.6依然不行；
我打算用系统级Python多版本切换：
```
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.6 1
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.7 2
配置版本
sudo update-alternatives --config python3
或切换设置
sudo update-alternatives --set python3 /usr/bin/python3.6
```
重新设3.6为系统默认Python，再执行apt或者dpkg安装说不定就安装到3.6下面去了，结果发现还是太天真了。试完了想把系统Python切换到Python3.6上，再运行apt install python3-distutils，结果并不可以。dist这个库安装完成后使用dpkg -L python3-distutils查看发现它已经在/usr/lib/python3.7/distutils文件夹下了，没法再装给Python3.6。被逼无奈只好强行把dpkg列出来的文件拷过去了，反正都是纯Python代码且发布无所谓小版本：
```
sudo cp -r /usr/lib/python3.7/distutils/* /usr/lib/python3.6/distutils/
```
这下终于好了，运行pipenv --python 3.6报环境变量的错，按提示重新配置即可：
```
export LC_ALL=C.UTF-8
export LANG=C.UTF-8
```
在运行pipenv终于成功安装了Python 3.6的环境。

装TensorFlow和Pytorch这两个大家伙，发现piwheel上没有现成的numpy[捂脸] wget https://github.com/lhelontra/tensorflow-on-arm/releases/download/v1.14.0-buster/tensorflow-1.14.0-cp37-none-linux_armv7l.whl

2.9 在macOS上再试一遍

安装Xcode自不必说，然后同意许可，安装Apple Command Line Tools：

sudo xcodebuild -license
sudo xcode-select --install

接下来我用macports安装系统依赖：

sudo port install cmake pkgconfig 
sudo port install jpeg libpng tiff openexr
sudo port install eigen3 tbb

下载OpenCV源码：

proxychains4 wget -O opencv.zip https://github.com/opencv/opencv/archive/4.1.1.zip
proxychains4 wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/4.1.1.zip
unzip opencv.zip
unzip opencv_contrib.zip
mv opencv-4.1.1 opencv
mv opencv_contrib-4.1.1 opencv_contrib

下面关于Python虚拟环境的路径，我都是用conda做的管理，所以跟venv、virtualenv、pipenv有所不同。准备执行cmake：

cd opencv
mkdir build && cd build

cmake -D CMAKE_BUILD_TYPE=RELEASE \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D OPENCV_EXTRA_MODULES_PATH=~/PycharmProjects/opcv/opencv_contrib/modules \
      -D PYTHON3_LIBRARY=`python -c 'import subprocess; import sys; s = subprocess.check_output("python3-config --prefix", shell=True).decode("utf-8").strip(); m = subprocess.check_output("python3-config --abiflags", shell=True).decode("utf-8").strip(); (V, v) = sys.version_info[:2]; print("{}/lib/libpython{}.{}{}.dylib".format(s, V, v, m))'` \
      -D PYTHON3_INCLUDE_DIR=`python -c 'import distutils.sysconfig as s; print(s.get_python_inc())'` \
      -D PYTHON3_EXECUTABLE=`python -c 'import subprocess; print(subprocess.check_output("which python", shell=True).decode("utf-8").strip())'` \
      -D BUILD_opencv_python2=OFF \
      -D BUILD_opencv_python3=ON \
      -D INSTALL_PYTHON_EXAMPLES=ON \
      -D INSTALL_C_EXAMPLES=OFF \
      -D OPENCV_GENERATE_PKGCONFIG=ON \
      -D OPENCV_ENABLE_NONFREE=ON \
      -D BUILD_EXAMPLES=ON \
      -D EIGEN_INCLUDE_PATH=/opt/local/include/eigen3 ..

编译并安装：

make -j4
sudo make install

完成安装后注意看安装日志，我们需要的文件位于/usr/local/lib/python3.6/site-packages/cv2/python-3.6/cv2.cpython-36m-darwin.so，为当前环境创造连接即可：

ln -s /usr/local/lib/python3.6/site-packages/cv2/python-3.6/cv2.cpython-36m-darwin.so /Users/<user-name>/anaconda3/envs/py36/lib/python3.6/site-packages/cv2.so

轻量级的用于开放或闭合麦阵列中的声源定位与追踪方法

Thu, 01 Aug 2019 23:40:11 GMT

翻译论文 Lightweight and Optimized Sound Source Localization and Tracking Methods for Open and Closed Microphone Array Configurations ，先坑着……

要死记硬背的拎出来没事就看看。

优化的轻量级的用于开放或闭合麦阵列中的声源定位与追踪方法

摘要

自然环境中的人机交互需要对环境中的不同的声源进行过滤。这种功能通常需要使用麦阵列，实时的对声源进行定位、追踪，并对不同声源进行分解。同时收集多个麦克风信号并处理分析可以提高对噪音的健壮性，但是麦克风数目的增加也会增加更多的计算量，这限制了响应时间，也限制了机器人的应用场景。声源定位算法会扫描广阔的三维空间以确定声源方位，这需要较多的算力，因此，减少声源定位算法的计算量将能够有效帮助声源定位机器人的场景推广及实施应用。不过，机器人的外形也会限制麦阵列的几何形状。此外，声源定位方法通常会返回一些环境噪音，而这些噪音应该通过声源追踪进行平滑和过滤。本文提出了一种名为SRP-PHAT-HSDA的新的声源定位方法，该方法将结合使用低分辨率和高分辨率的网格以节省扫描空间时对内存的访问。文章将使用一种麦克风指向性模型以减少方位扫描的数目，并忽略掉不重要的麦克风。本文还将引入一种新的麦阵列配置方法，用以自动调整那些平常需要参考麦阵列形状通过经验调试的参数。本文提出了一种对三维卡尔曼方法的改进（简写为M3K），用于生源追踪，该方法可以在三维空间中同时追踪多个声源。本文通过使用包含16个麦克风的阵列和低功耗硬件进行测试，结果显示SRP-PHAT-HSDA和M3K方法仅使用传统算法的1/30到1/4的算力，却能够达到不低于传统声源定位、追踪方法的效果。

关键词：声源定位，声源追踪，麦阵列，实时计算，嵌入式系统，移动机器人，机器人听觉。

1 引言

当发言者离（一个或多个）麦克风较远时进行的语音识别称为远距离语音识别（简称DSR），而远距离会使得背景噪音和反射回响与语音叠加[1, 2]，给识别带来困难。不过，DSR可以让发言者在不佩戴手持或头带式麦克风的场景中进行语音识别。尽管，远距离语音识别的健壮性依然是个挑战[3]。麦阵列这种硬件可以在人机交互（简称HRI）中实现DSR。这需要在机器人平台上安装多个麦克风，以处理远距离感知音频，通过过滤机器人平台的风扇、驱动机构，以及环境中不稳定的背景反射声源，在处理速度应当足够快时，实现实时的人机交互交互。这一过程首先需要对感知到的声源进行定位和追踪，然后才能对不同的声源进行分离[4]，以进行下一阶段的操作，比如对分离出来的特定语音进行识别[5, 6]。在实现声源定位及追踪方法时，对环境噪音的健壮性以及对计算量的控制十分关键[7]，因为这仅仅是实现基于语音的人机交互（HRI）的第一步。在自然环境下实现基于语音的人机交互需要让机器人避免环境中的各种噪音干扰，从嘈杂的背景音中分辨出并识别语音指令。

<center> <img style="border-radius: 0.3125em; box-shadow: 0 2px 4px 0 rgba(34,36,38,.12),0 2px 10px 0 rgba(34,36,38,.08);" src="https://raw.githubusercontent.com/zlotus/imagebed/master/2019/odas-paper-figure-1.png"> <br> <div style="color:orange; border-bottom: 1px solid #d9d9d9; display: inline-block; color: #999; padding: 2px;">图1 声源追踪及定位模块示意图</div> </center>

如图1所示，声源定位（简称SSL）以及声源追踪（简称SST）是按顺序依次进行计算的。对于每一帧$l$，SSL使用来自包括$M$个麦克风的麦阵列的音频数据$\mathbf{X}^l=\left{\mathbf{X}^l_1, \mathbf{X}^l_2, \ldots, \mathbf{X}^l_M\right}$生成$V$个潜在声源$\mathbf{\Psi}^l=\left{\psi^l_1, \psi^l_2, \ldots, \psi^l_V\right}$，其中的每个潜在声源$\psi^l_V$由一组表示波达方向（DoA）的笛卡尔坐标$\lambda^l_v$和一个表示可控波束能级组成的$\Lambda^l_v$组成。SSL方法给出由零星的声源（比如稀疏的语音）引起的带噪声源的波达方向，并且同一时间可能存在多个竞争声源。接着，SST利用潜在声源给出$I$个过滤掉噪音的被追踪声源$\mathbf{\Phi}^l=\left{\phi^l_1, \phi^l_2, \ldots, \phi^l_I\right}$，以提供声源的平滑轨迹。改进的SSL和SST方法的功能与所使用的麦克风数量直接相关，而麦克风数量会影响到计算量。

在这一过程中，SSL是最消耗算力的操作，现有不少算法可用于声源定位。Rascon等人[9]提供了一种轻量级的对内存和CPU消耗较低的SSL方法，但是仅支持3个麦克风，而且只能在一个2维平面内进行波达方向计算。Nesta与Omologo[10]提供了一种使用通用状态相干变换实现的声源定位，这一定位方法在多声源场景中尤为有效，但是这一方法中涉及独立成分分析运算（ICA），需要较长时间才能收敛。Drude等人[11]使用基于相位和电平差异的核函数方法，但是这一方法会增加计算量。Loesch和Yang[12]提供了一直基于时域-频域稀疏的定位方法，但这一方法对高混响水平较为敏感。基于标准特征值分解的多信号分类（SEVD-MUSIC）使SSL对加性噪声具有较好的鲁棒性[13]。SEVD-MUSIC最初用于窄带信号[14]，不过目前已经可以适用于宽带声源，例如语音[15]，并且只要噪音没有被定位信号（如语言）强，这一方法就可以对噪声具有较强的健壮性。基于广义特征值分解（GEVD-MUSIC）方法[16]的多信号分类也用于处理该问题，但这一种方法增加了计算量。基于广义奇异值分解（GSVD-MUSIC）的多信号分类降低了GEVD-MUSIC的计算量，同时提高了定位精度[17]，但这一方法仍涉及矩阵特征分解运算。其他方法利用麦阵列的几何特性（线性，圆形或球形）来提高鲁棒性并降低计算量[18,19,20]。尽管这些几何形状产生了有趣的特性，但由于其特定的几何形状也带来了一些物理约束，这些麦阵列配置对于移动机器人的体积限制来说并不太实用。还可以使用具有相位变换的转向响应功率（SRP-PHAT）来实现声源定位。SRP-PHAT通常使用来自成对麦克风的带有相位变换的加权广义互相关（GCC-PHAT）来计算[4,8]。SRP-PHAT比基于MUSIC的方法的计算量更少，但在通过大量麦克风数据扫描3D空间时仍需要大量的计算。随机区域收缩[21]、层次搜索[22,23,24]和矢量化[25]也被研究用SRP-PHAT加速扫描，但通常局限于2维平面和单个资源搜索。Marti[26]等人还提出一种同时在粗网格和细网格上进行递归搜索的方法。这一方法将空间划分为矩形小块，然后将细网格中的多点映射在粗网格的一个点中。不过，这一方法也忽略了麦克风的方向性，并在GCC值上使用了平均窗口，这可能在临近值为负时削减一个峰值的效果。

我们可以把声源追踪方法分为以下四类：

维特比搜索：Anguera等人[27]提出了一种后处理Viterbi方法来追踪时序中的声源。在实时处理数据时，这一方法将引入显著的延迟，因此仅适用于非实时分析。这一方法实现的追踪仅限于离散状态空间，因此该方法仅适用于固定网格中的声源追踪。
顺序蒙特卡罗（SMC）滤波：SMC方法，也称为粒子滤波，能够对单个声源执行低延迟追踪[28,29,30]。 Valin等人[4,8]采用SMC方法来跟踪多个声源。这一方法通过用有限粒子对空间进行采样，以模拟出非高斯的状态分布。SMC可以用来追踪连续空间轨迹，不过这一方法需要大量计算，而且因为使用了随机生成的粒子而不够确定。
卡尔曼滤波：Rascon等人[9]提出了一种基于卡尔曼滤波器的轻量级方法，该方法能够追踪连续轨迹，同时显著减少计算量。然而，该方法仅限于球面坐标中的波达方向，输出高度和方位角，不过，当方位角分辨率随高度变化时，会产生畸变，即引入了方位角隐藏现象。Marković等人[31]提出了一个在李群上的扩展卡尔曼滤波器（LG-EKF），用8麦克风阵列进行方向追踪。LG-EKF解决了方位角隐藏现象，但仅限在2维圆环上进行追踪，因此并不适合追踪3维球面上的声源。
联合概率数据关联过滤（JPDA）：Marković等[32]提出了一种可用于3维球面声源追踪的，基于von Mises-Fisher分布上的贝叶斯估计。然而，该方法需要事先知道声源数量，并且忽略各跟踪源的运动模型，这导致当两个声源交叉时会被当做轨迹的切换或融合。

为了改进声源定位和声源追踪，本文提出了一种称为SRP-PHAT-HSDA的SRP-PHAT方法，即按层级搜索指向性模型并自动校准，以及一种使用笛卡尔坐标的改进的3D卡尔曼滤波（M3K）的追踪方法。SRP-PHAT-HSDA首先在粗分辨率网格上扫描3D空间，然后优化特定区域的搜索。该方法利用到达时间差（TDOA）的不确定性模型，通过开放和闭合麦阵列配置，使用多种分辨率水平的网格来优化扫描精度。此方法还使用了麦克风指向性模型，以减少扫描方向的数量，并忽略不重要的麦克风对。M3K用卡尔曼滤波器取代了Valin等人[8]使用的SMC滤波器，并引入了三个新概念：1) 归一化状态以将空间限制为单位球体；2) 推导出计算相干声源的解析解表达式，以加速计算；3) 用于同时跟踪多个声源的卡尔曼均值向量和协方差矩阵的加权更新。这些改进形成了高效的对多个声源的跟踪方法，使之能够嵌入低算力硬件。改进的方法不仅比SMC更节省算力，还解决了卡尔曼滤波在球面座标中的畸变和隐藏。

文章的结构如下：首先，第2节描述了SRP-PHAT与SEVD-MUSIC的计算要求对比，以证明和确定SRP-PHAT-HSDA带来的改进。然后，第3节和第4节分别对SRP-PHAT-HSDA方法和M3K方法进行描述。第5节介绍了在移动机器人上实现8和16圆形麦阵列以及闭合立方麦阵列的实验设置，在3代树莓派上实现了SSL和SST方法。第6节给出了将SRP-PHAT与SRP-PHAT-HSDA方法，以及M3K与SMC方法的对比的实验结果。最后，第7节对文章进行总结，并说明未来工作。

2 SRP-PHAT与SEVD-MUSIC的算力需求

声源定位通常被分为两个子任务：1) 达到时间差估计；2) 在麦阵列周围的3维空间中搜索波达方向。而SRP-PHAT与SEVD-MUSIC方法的主要区别就在于子任务1：SRP-PHAT基于带有相位变换的加权广义互相关（GCC-PHAT）方法，而SEVD-MUSIC基于奇异特征值分解。

分布式波达方向定位尝试

Tue, 09 Jul 2019 21:09:11 GMT

想把odas这个项目弄成分布式的，用一个主机同时监控多个树莓派进行波达方向定位。源码备份在doa-project，防丢用。

树莓派

新的 raspbian buster 自带了python 3.7，安装pipenv即可：

proxychains4 pip install pipenv

环境准备

初始化虚拟环境

为odas项目新建文件夹odas，初始化pipenv环境：

mkdir odas
cd odas
proxychains4 pipenv --python 3.7
# 或 pipenv --python /usr/bin/python3

安装声卡驱动

mkdir 3rd-lib
cd 3rd-lib

# 安装声卡驱动
git clone https://github.com/respeaker/seeed-voicecard.git
cd seeed-voicecard
sudo proxychains4 ./install.sh
sudo reboot -h now

# 测试声卡
arecord -L
aplay -L

编译`odas`项目

# 编译odas
cd 3rd-lib/
proxychains4 git clone https://github.com/introlab/odas.git
mkdir odas/build
cd odas/build
cmake ..
make

# 做软链接方便使用
ln -s ~/odas/3rd-lib/odas/bin/odaslive ~/.local/bin/odaslive

# 测试odas
odaslive -c ~/respeaker-6mic-odas.cfg

安装`pyzmq`

新的buster自带了libzmq 4.3.1，安装pyzmq即可：

proxychains4 pip install pyzmq

测试：

>>> import zmq
>>> zmq.zmq_version()
'4.3.1'

配置防火墙

检查端口是否开启可以使用nc -zvw3 192.168.1.108 5557（z用于扫描端口的零I/O模式，v显示详情，w3三秒后超时）。

为zmq打开防火墙端口：

sudo ufw allow proto tcp to 0.0.0.0/0 port 5556 comment "zmq publish port of odas for sound source tracking"
sudo ufw allow proto tcp to 0.0.0.0/0 port 5557 comment "zmq publish port of odas for sound source localization"

注：我一开始为了用上Python 3.7，早早更新了buster的测试版，现在buster正式发布了，更新时报错：

E: Repository 'http://mirrors.aliyun.com/raspbian/raspbian buster InRelease' changed its 'Suite' value from 'testing' to 'stable'
N: This must be accepted explicitly before updates for this repository can be applied. See apt-secure(8) manpage for details.

按照Explicitly accept change for PPA 'Label'方法中说的，把apt-get改成apt即可。

使用`pyzmq`发布定位数据

from multiprocessing import Process
import os
import socket
import zmq


def sst_write(rpi_host='0.0.0.0', rpi_port=9000, zmq_host='*', zmq_port=5556):
    """
    A process, listened on socket://rpi_host:port,
        receive odas Sound Source Tracking(SST) json format data in bytes.
    Reassemble json byte frames and publish using zmq on tcp://zmq_host:zmq_port.
    :return: None
    """
    write_pid = os.getpid()
    print('#Write Process# %s start' % write_pid)
    bind_ip, bind_port = rpi_host, rpi_port
    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    server.bind((bind_ip, bind_port))
    server.listen(5)  # max backlog of connections
    print('#Write Process# listening on {}:{}'.format(bind_ip, bind_port))
    client_socket, address = server.accept()
    print('#Write Process# accepted connection from {}:{}'.format(address[0], address[1]))

    context = zmq.Context()
    zmq_socket = context.socket(zmq.PUB)
    zmq_socket.bind(f"tcp://{zmq_host}:{zmq_port}")

    temp = b''
    while True:
        t = 0
        temp = client_socket.recv(1024)
        for i in range(5):
            t = temp.find(b'}', t) + 1
        zmq_socket.send(temp[:t])
        temp = temp[t:]


def ssl_write(rpi_host='0.0.0.0', rpi_port=9001, zmq_host='*', zmq_port=5557):
    """
    A process, listened on socket://rpi_host:port,
        receive odas Sound Source Localization(SSL) json format data in bytes.
    Reassemble json byte frames and publish using zmq on tcp://zmq_host:zmq_port.
    :return: None
    """
    write_pid = os.getpid()
    print('#Write Process# %s start' % write_pid)
    bind_ip, bind_port = rpi_host, rpi_port
    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    server.bind((bind_ip, bind_port))
    server.listen(5)  # max backlog of connections
    print('#Write Process# listening on {}:{}'.format(bind_ip, bind_port))
    client_socket, address = server.accept()
    print('#Write Process# accepted connection from {}:{}'.format(address[0], address[1]))

    context = zmq.Context()
    zmq_socket = context.socket(zmq.PUB)
    zmq_socket.bind(f"tcp://{zmq_host}:{zmq_port}")

    temp = b''
    while True:
        t = 0
        temp = client_socket.recv(1024)
        for i in range(5):
            t = temp.find(b'}', t) + 1
        zmq_socket.send(temp[:t])
        temp = temp[t:]


if __name__ == '__main__':
    try:
        p_ssl_w = Process(target=ssl_write)
        p_sst_w = Process(target=sst_write)
        # p_ssl_r = Process(target=ssl_read, kwargs={"verbose": True})
        # 启动子进程pw，写入:
        p_ssl_w.start()
        p_sst_w.start()
        # 等待pw结束:
        p_ssl_w.join()
        p_sst_w.join()
    except KeyboardInterrupt:
        p_ssl_w.terminate()
        p_sst_w.terminate()
        print('KeyboardInterrupt pw pr Terminated')

远端主机

使用`pyzmq`订阅定位数据

from multiprocessing import Process
import os
import json
import asyncio
from aiohttp import web, WSMsgType
import zmq


def sst_read(zmq_host='192.168.1.108', zmq_port=5556, aio_host='0.0.0.0', aio_port=8080, verbose=False):
    """
    A process, used for subscribing zmq socket on tcp://zmq_host:zmq_port,
        receiving Sound Source Tracking(SST) data frames.
    In the meantime the process runs an aiohttp server on ws://aio_host:aio_port,
        sending SST data frames to user browser via websocket connection.
    User browser websocket-client should send a 'received' message after every data frame received,
        to tell the server 'last message received, please send next.'
    :output: Sound Source Tracking output like this:
    {
        "timeStamp": 45602,
        "src": [
            { "id": 43, "tag": "dynamic", "x": 0.025, "y": 0.128, "z": 0.991, "activity": 1.000 },
            { "id": 0, "tag": "", "x": 0.000, "y": 0.000, "z": 0.000, "activity": 0.000 },
            { "id": 0, "tag": "", "x": 0.000, "y": 0.000, "z": 0.000, "activity": 0.000 },
            { "id": 0, "tag": "", "x": 0.000, "y": 0.000, "z": 0.000, "activity": 0.000 }
        ]
    }
    :return: None
    """
    read_pid = os.getpid()
    print('#Read  Process# %s start' % read_pid)
    routes = web.RouteTableDef()

    context = zmq.Context()
    zmq_socket = context.socket(zmq.SUB)

    print("Collecting updates from odas publisher...")
    zmq_socket.connect(f"tcp://{zmq_host}:{zmq_port}")
    zmq_socket.setsockopt_string(zmq.SUBSCRIBE, '{')

    @routes.get('/ws')
    async def websocket_handler(request):
        print('websocket connection open')

        ws = web.WebSocketResponse()
        await ws.prepare(request)
        c = 0
        await ws.send_str(zmq_socket.recv_string())
        async for msg in ws:
            if msg.type == WSMsgType.TEXT:
                if msg.data == 'close':
                    print('websocket connection close')
                    await ws.close()
                else:
                    c += 1
                    tmp = zmq_socket.recv_string()
                    await ws.send_str(tmp)
                    if verbose:
                        c += 1
                        print(f'\r{c}', end='', flush=True)
                    # TODO: debug jump, delete later
                    # for i in range(100):
                    #     zmq_socket.recv_string()
            elif msg.type == WSMsgType.ERROR:
                print('ws connection closed with exception %s' %
                      ws.exception())
        return ws

    app = web.Application()
    app.add_routes(routes)
    web.run_app(app, host=aio_host, port=aio_port)


def ssl_read(zmq_host='192.168.1.108', zmq_port=5557, aio_host='0.0.0.0', aio_port=8081, verbose=False):
    """
    A process, used for subscribing zmq socket on tcp://zmq_host:zmq_port,
        receiving Sound Source Localization(SSL) data frames.
    In the meantime the process runs an aiohttp server on ws://aio_host:aio_port/ws,
        sending SSL data frames to user browser via websocket connection.
    User browser websocket-client should send a 'received' message after every data frame received,
        to tell the server 'last message received, please send next.'
    :output: Sound Source Localization output like this:
    {
        "timeStamp": 45608,
        "src": [
            { "x": 0.132, "y": 0.181, "z": 0.975, "E": 0.557 },
            { "x": 0.198, "y": 0.342, "z": 0.918, "E": 0.130 },
            { "x": 0.000, "y": 0.273, "z": 0.962, "E": 0.018 },
            { "x": 0.000, "y": 0.339, "z": 0.941, "E": 0.006 }
        ]
    }
    :return: None
    """
    read_pid = os.getpid()
    print('#Read  Process# %s start' % read_pid)
    routes = web.RouteTableDef()

    context = zmq.Context()
    zmq_socket = context.socket(zmq.SUB)

    print("Collecting updates from odas publisher...")
    zmq_socket.connect(f"tcp://{zmq_host}:{zmq_port}")
    zmq_socket.setsockopt_string(zmq.SUBSCRIBE, '{')

    @routes.get('/ws')
    async def websocket_handler(request):
        print('websocket connection open')

        ws = web.WebSocketResponse()
        await ws.prepare(request)
        c = 0
        await ws.send_str(zmq_socket.recv_string())
        async for msg in ws:
            if msg.type == WSMsgType.TEXT:
                if msg.data == 'close':
                    print('websocket connection close')
                    await ws.close()
                else:
                    tmp = zmq_socket.recv_string()
                    await ws.send_str(tmp)
                    if verbose:
                        c += 1
                        print(f'\r{c}', end='', flush=True)
                    # TODO: debug jump, delete later
                    # for i in range(100):
                    #     zmq_socket.recv_string()
            elif msg.type == WSMsgType.ERROR:
                print('ws connection closed with exception %s' %
                      ws.exception())
        return ws

    app = web.Application()
    app.add_routes(routes)
    web.run_app(app, host=aio_host, port=aio_port)


if __name__ == '__main__':
    try:
        p_ssl_r = Process(target=ssl_read, kwargs={"verbose": True})
        # p_ssl_r = Process(target=ssl_read)
        p_sst_r = Process(target=sst_read)
        # 启动子进程pr，读取:
        p_ssl_r.start()
        p_sst_r.start()
    except KeyboardInterrupt:
        p_ssl_r.terminate()
        p_sst_r.terminate()
        print('KeyboardInterrupt pw pr Terminated')

注意： 这里我使用了aiohttp将数据发布为websocket，在浏览器上进行可视化。

使用`three.js`可视化数据

封装ant-design组件

为了以后用着方便，我特意将可视化代码封装为ant-design的组件：

# 新建文件夹
mkdir odas-front
# 安装antd测试
npm install antd --save

注意： 在电脑上用nvm控制node版本，最新的已经是版本12.x了。但是port安装的yarn使用的是node --version 10.16.0，因此还是要配合安装nvm install 10.16.0，使默认node变成10.16.0（12版本会报错）。

安装`create-umi`
npm create umi
选择`app`，并同意使用`typescript`，再选择`dva`和`antd`

代码基本照抄odas的Element版本。

使用Python代码进行树莓派上的麦阵列声源定位

Sat, 15 Jun 2019 20:13:11 GMT

偶然发现seeedstudio更新了他们的英文版说明书，然而中文版还没更新[捂脸]。关于DOA的部分，除了原来的使用ODAS Studio的方法以外，又多加了一些使用Python代码直接进行DOA的章节。

0 安装驱动

别忘了用source activate doa切到专门的环境里，或者conda create -n doa python=3.6现造一个环境。

安装驱动：

proxychains4 git clone https://github.com/respeaker/seeed-voicecard.git
cd seeed-voicecard
sudo proxychains4 ./install.sh
sudo reboot -h now

检查驱动：

arecord -L # 输入驱动，即录制
null
    Discard all samples (playback) or generate zero samples (capture)
default
ac108
dmixer
ac101
sysdefault:CARD=seeed8micvoicec
    seeed-8mic-voicecard,
    Default Audio Device
dmix:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample mixing device
dsnoop:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample snooping device
hw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct hardware device without any conversions
plughw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Hardware device with all software conversions

aplay -L # 输出驱动，即播放
null
    Discard all samples (playback) or generate zero samples (capture)
default
ac108
dmixer
ac101
sysdefault:CARD=ALSA
    bcm2835 ALSA, bcm2835 ALSA
    Default Audio Device
dmix:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Direct sample mixing device
dmix:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Direct sample mixing device
dsnoop:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Direct sample snooping device
dsnoop:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Direct sample snooping device
hw:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Direct hardware device without any conversions
hw:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Direct hardware device without any conversions
plughw:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Hardware device with all software conversions
plughw:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Hardware device with all software conversions
sysdefault:CARD=seeed8micvoicec
    seeed-8mic-voicecard,
    Default Audio Device
dmix:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample mixing device
dsnoop:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample snooping device
hw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct hardware device without any conversions
plughw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Hardware device with all software conversions

1 测试LED

说实话，自打买了这个麦阵列，我还从来没试过这12个LED灯[捂脸]，试试吧要不感觉对不起这个板子，另外，运行demo需要gpiozero、spidev、pyusb。

proxychains4 git clone --depth 1 https://github.com/respeaker/pixel_ring.git
cd pixel_ring
proxychains4 pip install -U -e .
proxychains4 pip install gpiozero RPi.GPIO
python examples/respeaker_4mic_array.py

控制LED的主要代码其实就在函数show()，直接在Python交互环境中输入下面的代码，就可以打开12点方向的灯，并渲染为白色，也就是ARGB(0, 64, 64, 64)。

from pixel_ring import pixel_ring
from gpiozero import LED

power = LED(5)
power.on()

pixel_ring.set_brightness(10) # 0-100，其实会被转换为`APA102.dev.global_brightness`的0-31
pixel_ring.pattern.show([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 64, 64, 64])

用于控制的数组是一个48位的list，从1点钟方向开始，到12点钟方向结束，每四位控制一个LED灯，非常好操作。

2 装DOA相关库

添加seeed提供的apt源。（靠谱的公司啊）

echo "deb https://seeed-studio.github.io/pi_repo/ stretch main" | sudo tee /etc/apt/sources.list.d/seeed.list
proxychains4 curl https://seeed-studio.github.io/pi_repo/public.key | sudo apt-key add -
proxychains4 sudo apt update

安装numpy和pyaudio：

proxychains4 conda install -y numpy
proxychains4 sudo apt-get install -y portaudio19-dev 
proxychains4 pip install pyaudio

安装编译工具：

sudo proxychains4 apt-get install -y swig python-dev libatlas-base-dev build-essential make

安装snowboy（热词检测DOA）：

proxychains4 git clone --depth 1 https://github.com/Kitt-AI/snowboy.git
cd snowboy
python setup.py build
python setup.py bdist_wheel
pip install dist/snowboy*.whl

安装seeed的voice-engin：

proxychains4 git clone https://github.com/voice-engine/voice-engine.git
cd voice-engine
python setup.py bdist_wheel
pip install dist/*.whl

测试ok~：

python ~/doa/voice-engine/examples/respeaker_6mic_array_for_pi/kws_doa.py

如果只是想用DOA功能，可以试试seeed的老项目mic_array：

proxychains4 git clone https://github.com/respeaker/mic_array.git
python ./mic_array/mic_array.py

对比了一下，跟人家introlab/odas项目差的还是比较远的。直观上看就是我们简单的靠fft实现的DOA仅仅能做到平面范围内的方位判断，仅输出一个角度（平面offset），速度慢且不支持声源跟踪等功能。而odas的声源定位项目输出两个值，一个平面offset一个法向offset，还能进行声源分辨，多声源跟踪跟踪。odas项目的理论收录在Lightweight and Optimized Sound Source Localization and Tracking Methods for Opened and Closed Microphone Array Configurations中，值得一读。

我是不是得写个2018年终总结啊

Sat, 19 Jan 2019 09:36:25 GMT

嗯，嘛，理论上讲，2019年，所有80后都将踏入中年人的行列……听说这个世界是中年人撑起来的？完全没感觉到啊……

2018基本虚度，好在算是正式入宅……看了不少好番，比如硬核的《Megalo Box》、超燃的《我的英雄学院》、过于真实的《白箱》、炫富嫌疑的《进击的巨人》等等。当然，也按年度例行复习了宫崎骏、押井守、井上雄彦、荒川弘等神仙的经典。看了gakki的某新剧，同时通过Unnatural也粉了十元……

今年依旧在砖总、李哥、白总、陈哥的血虐下，体重突破62kg。前几天又找到了拉背的快感，下午再去蹲个腿，感觉离施瓦辛格就差65536个郭达斯坦森了[认真脸]。

通过不懈努力，我应该算正式步入肥宅的行列了吧[捂脸]。

今年倒是在各种番剧的夹击中，忙里偷闲的糊了篇毕业论文，给自己及导师一个胶带。看上单位一姑娘还贼怂不敢追，打算在2019死皮赖脸的给自己及办公室的阿姨领导一个胶带……

然后说点严肃又装逼的事吧——生老病死。小时候跟表哥堂妹参见姑妈的追悼会，后来是老爸的，再接着是爷爷的，上个礼拜是姥姥的，感觉跟西安殡仪馆都熟起来了……

我对殡仪馆是没什么感觉的，比起殡仪馆我更讨厌医院。虽然今年已经要三十而立了，但是我依然中二的坚信着不论信不信春哥，永生都会随着技术的发展而降临，因此在生老病死中我非常非常的抗拒老和病。今年越来越觉得宅是硬道理，除了贫穷这一主要因素外，宅还能降低各种不可预知事件发生的概率，我估计是方圆几十里内最怕死的了，愉悦[捂脸]。

同样，这两年撸铁把体脂提上来了几个百分点，感觉对感冒的抵抗力明显强了很多，当然也可能是空气净化器的功劳……在我眼里，世界上最可怕的莫过于死亡，比死亡更恐怖的莫过于病逝……当年姑妈去世的时候，我虽然年纪小但是也有些触动，后来在中二动画、游戏、小说的熏陶下，渐渐萌生了“人生得意须尽欢”的人生战略方针，工作后中二病发作誓要踏遍祖国的壮美山河，毕竟引无数英雄竞折腰嘛，我不也算是个小英雄嘛。我知这中二如露水般短暂，然而，然而，最后一次空对月大概就是去喀纳斯了——逼自己交定金、早早订机票、给自己打气脱宅——美酒美食拉肚子的飞回西安，发着烧第二天继续飞上海出差，我突然明白了，我并不是小英雄，我连小垃圾都算不上，我们现在能在说上号的人物，不论历史还是当今、不论正义还是邪恶、不论伟大还是卑微、不论现实还是虚构，哪一个有名号的人物不拥有着开外挂的人生？！

也许是王立群老师的大型情感类历史剧看多了，更可能是科幻或者加缪读傻了，我的人生啊，真的是毫无意义，连时间长河中的水分子都算不上，充其量是水面的一瞬波光，幻灭嘛。嘴上说着脚踏碧蓝大海头顶金色太阳，实际上怂的跟什么似的，前进？大概是把，连被逼无奈都算不上，仅仅是无所事事罢了。什么追求啊逃避啊，说的好像一副志存高远成竹在胸似的，其实统统滴莫有啊，说好听点随心所欲，说难听点随波逐流。不过，这样不也挺好吗，我啊，也不是年轻人说的什么阶级固化看不到希望，更不是多么厌恶鼓吹奋斗的人，希望嘛努力努力也能看到，对奋斗者也报以带有嫉妒的祝福，这应该不是丧吧，大概是隐约感到自己的幸运吧。虽然不算顺风顺水，却也没遭到什么大灾大难，在不到三十岁明白了身体是等待技术革命的本钱，明白了活得久总会碰到更多幸运的事，开始相信概率论与数理统计，开始相信时间，这本身就算是幸运吧。王诺诺大神也说过，成长嘛，无非就是用点与生俱来的，换点朝思暮想的，那用时间换更多的时间也不算犯规吧~哈哈哈~

时间嘛，时间诶，确实，这几年硬笔字明显是好看多了，胸背臀肩也盖上了五花肉，等体重涨到65kg就开始冻结身体版本，缩短撸铁时间。早就想买个电钢琴，趁着还有闲就实现了吧。

另外，今年大概是旺桃花？这个月没过一半已经接了三个介绍，大概是同学同事都看不下去我三点一线的的单身生活吧……作为一个极度功利的人，咱一看照片二聊兴趣，每个对象都是几小时结束战斗。咱可是知道女生特别看重身高，看完照片如实强调自己身高170就能够很轻易的结束会话。我，真是凭本事单身的。聊了这几个我也发现自己越发鄙视“仪式感”这个词了，在法庭或者殡仪馆看重仪式感无可厚非，但是生活中仪式XXX啊，日子过的太闲了吧，有考虑仪式和优雅的空，多给自己充充电保保鲜不好吗！另一个同样属性的词大概是“有趣”了。撸了一年半载的铁我算是明白了，有趣的灵魂满街都是，完美的肉体万中无一。有几个人称得上无趣？稍微受点教育会用谷歌看过点美女路过点美景，最后嘴皮子在利索点，个个不都是字字珠玑的少年英雄小哪吒嘛。但是完美的肉体呢？首先你得生的足够幸运吧，其次得长的足够幸运吧，然后你得足够幸运的有闲有钱而刚好又足够幸运的有毅力去撸铁吧，这些小概率是按乘算的。发现了吧，为什么有趣的灵魂多啊？因为“有趣的灵魂”不是一个well defined的词语啊，但是“完美的肉体”可就完全不一样了，骨相皮相站姿身段、三庭五眼头身比例、有闲有钱时刻保鲜，更别提什么体质啊肌纤维啊分离度啊这些精细特征了，哪一个不能量化衡量？就像写跑代码一样，前后层级环环相扣，编译链接缺一不可……扯远了跑语言学范畴了……其实就是想表达一下，现在越来越欣赏那种刚毅不屈心沉似铁的人了。

要说谁不慌，那是不存在的，慌啊，都慌，个个心里没底，毕竟都第一次做人没经验嘛，当然，有人故作镇定的不慌，有人嘻皮笑脸的慌。慌或者不慌，还不一样是顶着太阳踏浪扬帆嘛~反正也没有别的事做……

最后，感谢中国人民的好朋友莱蒙托夫先生的原创，以及德艺双馨的民间艺术家柴静女士的翻译：

一只船孤独地航行在海上，它既不寻求幸福，也不逃避幸福，它只是向前航行，底下是沉静碧蓝的大海，而头顶是金色的太阳。

许个愿吧，下一个十年希望能够达成：键盘乐器独奏成就……以及……兼职声优成就，万一咱这几十年也侥幸汇成河了呢。

完。

树莓派开发环境准备汇总

Sat, 01 Dec 2018 12:09:10 GMT

由于经常要折腾Raspbian，所以打算在这里汇总一下树莓派环境初始化要做的工作。

1 系统安装及配置

1.1 Headless下的WiFi及ssh配置

按树莓派官方说明在SD卡上写入镜像，然后进行Headless配置：

配置WIFI，需要在SD卡根目录下新建一个名为wpa_supplicant.conf的文件：

touch /Volumes/boot/wpa_supplicant.conf

写入WIFI配置：

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="<YOUR-NETWORK-NAME>"
    psk="<YOUR-NETWORK-PASSWORD>"
}

开启SSH，只需在SD卡根目录下新建一个名为ssh的空文件即可：

touch /Volumes/boot/ssh

或者直接将本地编辑好的wpa_supplicant.conf、ssh文件拷贝到SD卡上：

# 本地存储卡初始化
cp ~/Raspberrypi/wpa_supplicant.conf /Volumes/boot
touch /Volumes/boot/ssh

配置完成后正常启动树莓派即可自动连接WIFI，SSH可以正常登录。注：如果不知道设备IP，可以使用ping raspberry.local查找。

如果这个IP上曾经还有过其他树莓派前辈，那么要先删除本机上的ssh信任主机，比如我的树莓派一直用固定IP配在108上：

ssh-keygen -R 192.168.1.108

# 树莓派插卡启动，上传本地秘钥方便ssh登录
ssh-copy-id pi@192.168.1.108

第一次用pi登录后默认密码为raspberry，应该直接使用passwd修改密码。或是使用sudo raspi-config，通过树莓派管理工具修改密码、主机名、地区、时区等信息。

1.2 换国内镜像源

解决升级慢或Cannot initiate the connection to mirrors.opencas.cn问题：

sudo vi /etc/apt/sources.list

修改sources.list，注释第一行，在最后添加国内镜像站：

deb http://mirrors.aliyun.com/raspbian/raspbian/ stretch main non-free contrib
deb-src http://mirrors.aliyun.com/raspbian/raspbian/ stretch main non-free contrib

也可以使用其他镜像站，比如：

# 中科大
deb http://mirrors.ustc.edu.cn/raspbian/raspbian/ stretch main contrib non-free rpi 
# 清华
deb https://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/ stretch main contrib non-free rpi
# 大连东软
deb http://mirrors.neusoft.edu.cn/raspbian/raspbian/ stretch main contrib non-free rpi
# 重庆大学
deb http://mirrors.cqu.edu.cn/raspbian/raspbian/ stretch main contrib non-free rpi
# 浙江大学
deb http://mirrors.zju.edu.cn/raspbian/raspbian/ stretch main contrib non-free rpi
# 阿里云
deb http://mirrors.aliyun.com/raspbian/raspbian/ stretch main contrib non-free rpi 
# 搜狐
deb http://mirrors.sohu.com/raspbian/raspbian/ stretch main contrib non-free rpi 
# 元智大学（中国台湾）
deb http://ftp.cse.yzu.edu.tw/Linux/raspbian/raspbian/ stretch main contrib non-free rpi 
# 新加坡国立大学
deb http://mirror.nus.edu.sg/raspbian/raspbian/ stretch main contrib non-free rpi
# 北陆先端科学技术大学院大学（日本知名镜像站，日常出口带宽2g）
deb http://ftp.jaist.ac.jp/raspbian/ stretch main contrib non-free rpi
# 牛津大学
deb http://mirror.ox.ac.uk/sites/archive.raspbian.org/archive/raspbian/  stretch main contrib non-free rpi
# 美国Berkely大学
deb http://mirrors.ocf.berkeley.edu/raspbian/raspbian/ stretch main contrib non-free rpi
# 美国俄克拉荷马大学
deb http://reflection.oss.ou.edu/raspbian/raspbian/ stretch main contrib non-free rpi
# 南非知名软件源
deb http://mirror.liquidtelecom.com/raspbian/raspbian/ stretch main contrib non-free rpi 
# 默认源（带重定向by mirrorbrain）
deb http://mirrordirector.raspbian.org/raspbian/ stretch main contrib non-free rpi
# 官方源
deb https://archive.raspbian.org/raspbian/ stretch main contrib non-free rpi

同样的，修改raspi.list，树莓派的软件包源仅有清华和中科大镜像：

sudo vi /etc/apt/sources.list.d/raspi.list

注释第一行，在最后添加：

deb https://mirrors.tuna.tsinghua.edu.cn/raspberrypi/ stretch main ui

或者直接在树莓派上执行：

sudo sed -i 's#://raspbian.raspberrypi.org#s://mirrors.tuna.tsinghua.edu.cn/raspbian#g' /etc/apt/sources.list
sudo sed -i 's#://archive.raspberrypi.org/debian#s://mirrors.tuna.tsinghua.edu.cn/raspberrypi#g' /etc/apt/sources.list.d/raspi.list

如果嫌麻烦的话，上面这些需要配置的东西可以写成文件，再用脚本执行：

# 将本地编写好的配置文件拷贝到树莓派上
scp ~/Raspberrypi/raspi.list ~/Raspberrypi/sources.list pi@192.168.1.108:./

# 树莓派上拷贝配置文件到相应目录
sudo mv ~/sources.list /etc/apt/sources.list
sudo mv ~/raspi.list /etc/apt/sources.list.d/raspi.list

固件升级（谨慎操作，可能会踩到奇怪的编译坑）：

sudo rpi-update && sudo reboot -h now

软件包升级：

time sudo apt -y update && time sudo apt -y upgrade && time sudo apt -y dist-upgrade

软件包清理，顺便装个vim和tmux：

sudo apt clean
sudo apt install -y vim tmux

我的tmux的配置只有一行set -g mouse on，可以将本地编写好的tmux配置文件上传到树莓派家目录，不需要再移动位置：

scp ~/Raspberrypi/.tmux.conf pi@192.168.1.108:./

可以直接拷贝到树莓派上

2 搭建科学上网环境

2.1 安装SS

安装shadowsocks命令行客户端（推荐用pip和apt，快一些）：

pip install shadowsocks
sudo apt install -y shadowsocks-libev
# 或cpan安装
# 更新CPAN
sudo cpan install CPAN
# 重载CPAN
sudo cpan reload CPAN
sudo cpan Net::Shadowsocks

2.2 配置防火墙

安装ufw以方便调整防火墙策略，其实是我不会用iptables：

sudo apt-get install -y ufw

更新防火墙策略：

sudo ufw allow proto tcp to 0.0.0.0/0 port 22 comment "sshd listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 1080 comment "Shadowsocks server listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 5900 comment "vnc server listen port"
# 有时候需要用python -m http.server 8000传文件，开个口比较方便
sudo ufw allow proto tcp to 0.0.0.0/0 port 8000 comment "for python -m http.server 8000"
sudo ufw default deny 
sudo ufw enable

2.3 socks5代理

在/etc/shadowsocks-libev/xxx.json下配置科学上网服务器：

{
    "server": "<your-remote-server>",
    "server_port": <your-remote-server-port>,
    "timeout": 60,
    "password": "<your-password>",
    "method": "aes-256-cfb",
    "local_address": "0.0.0.0",
    "local_port": 1080
}

当然，也可以把配置文件在本地写好，再上传树莓派：

# 本地上传
scp ~/Raspberrypi/jiasd.json pi@192.168.1.108:./
# 在树莓派上将配置文件移动到相应目录
sudo mv ~/jiasd.json /etc/shadowsocks-libev/jiasd.json

检查默认端口占用，通常SS安装完成后会自动使用默认配置（/etc/shadowsocks-libev/config.json）启动ss-server进程，因此8388端口通常会被占用。而我们在树莓派上使用SS仅仅是为了加速，因此不需要启动ss-server：

# 测试端口连通性
nc -zv 127.0.0.1 8388
# 或检查进程占用端口
netstat -nap | grep 8388

停止默认ss服务端：

# 检查ss默认系统服务
systemctl list-unit-files # 或 systemctl -a
# 检查ss服务状态
systemctl status shadowsocks-libev.service 
# 停止服务
sudo systemctl stop shadowsocks-libev.service 
sudo systemctl disable shadowsocks-libev.service 
systemctl status shadowsocks-libev.service

启动ss客户端：

# 后台
nohup ss-local -v -c /etc/shadowsocks-libev/jiasd.json &
# 或前台
ss-local -v -s <your-remote-server> -p <your-remote-server-port> -l 1080 -k <your-password> -m aes-256-cfb

测试ss客户端的socks5是否正常：

curl -I --socks5 localhost:1080 google.com

停止ss客户端：

sudo kill -TERM 5914 && rm nohup.out

编写快捷脚本

启动脚本ss-s：

sudo touch /usr/local/bin/ss-s
sudo chmod +x /usr/local/bin/ss-s

#!/bin/bash

nohup ss-local -v -c /etc/shadowsocks-libev/jiasd.json > ~/nohup.log 2>&1 &
echo $! > ~/ss-pid.txt

停止ss-t：

sudo touch /usr/local/bin/ss-t
sudo chmod +x /usr/local/bin/ss-t

#!/bin/bash

kill -s TERM `cat ~/ss-pid.txt`
rm ~/ss-pid.txt

当然，也可以把配置文件在本地写好，再上传树莓派：

# 本地上传
scp ~/Raspberrypi/ss-s ~/Raspberrypi/ss-t pi@192.168.1.108:./
# 然后再修改文件属性并放置在相应目录下
chmod +x ss-s
chmod +x ss-t
sudo mv ss-s /usr/local/bin/ss-s
sudo mv ss-t /usr/local/bin/ss-t

2.4 proxychains-ng

ProxyChains是一个使用方便的代理工具，它只会代理指定的程序，下载：

mkdir misc && cd misc
git clone https://github.com/rofl0r/proxychains-ng

安装：

cd proxychains-ng/
./configure --prefix=/usr --sysconfdir=/etc
# 若是macOS下安装可能会遇到/usr/lib因SIP保护禁止写入的问题，需要更改配置为：
#./configure --prefix=/usr/local --sysconfdir=/etc
# ref: https://apple.stackexchange.com/questions/208764/cant-write-to-usr-lib
make 
sudo make install
sudo make install-config

配置/etc/proxychains.conf，将最后一行修改为shadowsocks的端口：

socks5 127.0.0.1 1080

测试wget，返回网页源码：

proxychains4 wget -qO- https://www.google.com

3 安装科学计算环境

使用pipenv作为环境管理器：

sudo apt install -y pipenv

关于这个pipenv不得不说一下，要想在默认Python版本是3.7的buster上安装3.6的环境，你必须先sudo apt install python3.6，问题是不论3.6还是3.7的Python，其distutils包都不全，我也不知道这是bug还是buster特供版Python，反正pipenv没法正常的用buster中apt安装的版本运行。

要解决这个问题，对3.7来说还好办，sudo apt install python3-distutils就行了，通过dpkg -L python3-distutils查看就知道它在/usr/lib/python3.7/distutils里装了一些东西。要想让3.6也能正常用pipenv，只能手动sudo cp -r /usr/lib/python3.7/distutils/* /usr/lib/python3.6/distutils/了。

3 安装Python科学计算环境

注意：berryconda也只更新到python3.6，而新的raspbian buster已经自带python3.7了，所以下面的安装可以酌情考虑。

我习惯使用conda环境，因此下载了berryconda：

proxychains4 wget https://github.com/jjhelmus/berryconda/releases/download/v2.0.0/Berryconda3-2.0.0-Linux-armv7l.sh

安装berryconda：

chmod +x Berryconda3-2.0.0-Linux-armv7l.sh
./Berryconda3-2.0.0-Linux-armv7l.sh

更新conda：

proxychains4 conda update -y --all

新建名叫doa的环境：

conda create -n doa python=3.6

激活环境：

source activate doa

退出环境：

source deactivate

安装Numpy，需要比较长的时间：

conda install numpy

关于不使用pip而，使用conda进行安装的原因可以参考这里（简单的说，是由于编译选项问题导致conda安装的Python与pip安装的Numpy不兼容）。

最后，需要知道的一个坑，不知道为什么我的jupyter notebook不能正确的识别conda中已安装的环境，也就是新建的环境在笔记本中无法新建或者切换，我做了如下操作：

把笔记本的运行时配置/Users/<your-user>/Library/Jupyter/中的所有内容清空。
在新建的环境py36中手动添加，参考Conda environments not showing up in Jupyter Notebook Ask：

(py36) ➜  ~ python -m ipykernel install --user --name py36 --display-name "Python (py36)"

总结

把安装conda前的操作汇总一下：

需要在本地执行的操作：

# 插SD卡，准备wifi和ssh
cp ~/Raspberrypi/wpa_supplicant.conf /Volumes/boot
touch /Volumes/boot/ssh

# 删除前一次的known-hosts指纹
ssh-keygen -R 192.168.1.108

# 上传本地秘钥
ssh-copy-id pi@192.168.1.108

# 上传更新源
scp ~/Raspberrypi/raspi.list ~/Raspberrypi/sources.list pi@192.168.1.108:./

# 上传SS配置
scp ~/Raspberrypi/jiasd.json pi@192.168.1.108:./

# 上传SS启停脚本
scp ~/Raspberrypi/ss-s ~/Raspberrypi/ss-t pi@192.168.1.108:./

# 上传proxychains配置
scp ~/Raspberrypi/proxychains.conf pi@192.168.1.108:./

# 上传tmux配置
scp ~/Raspberrypi/.tmux.conf pi@192.168.1.108:./

需要在树莓派上执行的操作：

# 移动更新源
sudo mv ~/sources.list /etc/apt/sources.list
sudo mv ~/raspi.list /etc/apt/sources.list.d/raspi.list

# 更新树莓派
time sudo apt -y update && time sudo apt -y upgrade && time sudo apt -y dist-upgrade
# 清理
sudo apt -y autoremove
sudo apt -y clean

# 安装shadowsocks、vim、tmux
pip install shadowsocks
sudo apt install -y shadowsocks-libev vim tmux

# 安装防火墙
sudo apt-get install -y ufw
# buster默认有两个iptables，选择老版才能和ufw兼容
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
# 更新防火墙策略
sudo ufw allow proto tcp to 0.0.0.0/0 port 22 comment "sshd listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 5900 comment "vnc server listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 1080 comment "Shadowsocks server listen port"
# 有时候需要用python -m http.server 8000传文件，开个口比较方便
sudo ufw allow proto tcp to 0.0.0.0/0 port 8000 comment "for python -m http.server 8000"
sudo ufw default deny 
sudo ufw enable

# 关闭ss-server
sudo systemctl stop shadowsocks-libev.service 
sudo systemctl disable shadowsocks-libev.service 
systemctl status shadowsocks-libev.service 

# 移动SS配置
sudo mv ~/jiasd.json /etc/shadowsocks-libev/jiasd.json
# 添加可执行权限
chmod +x ss-s
chmod +x ss-t
sudo mv ~/ss-s /usr/local/bin/ss-s
sudo mv ~/ss-t /usr/local/bin/ss-t

# 安装proxychains
mkdir misc && cd misc
git clone https://github.com/rofl0r/proxychains-ng
cd proxychains-ng/
./configure --prefix=/usr --sysconfdir=/etc
make 
sudo make install
sudo make install-config
cd ~

# 移动proxychains配置
sudo mv ~/proxychains.conf /etc/proxychains.conf

树莓派上的麦阵列定位

Thu, 25 Oct 2018 21:09:11 GMT

最近又弄了个麦阵列玩定位……

1 安装ReSpeaker驱动

参考：ReSpeaker 6-Mic Circular Array kit for Raspberry Pi

手册上说换个源会快，那就换吧：

sudo vim /etc/apt/sources.list

手册上让用清华的镜像站：

deb http://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/ buster main non-free contrib
deb-src http://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/ buster main non-free contrib

安装麦阵列驱动：

mkdir seeed
proxychains4 git clone https://github.com/respeaker/seeed-voicecard.git
cd seeed-voicecard
sudo proxychains4 ./install.sh
sudo reboot -h now

需要注意的是，在安装前不要运行sudo rpi-update升级固件，否则会因为固件版本问题导致无法安装。

2 录音及播放测试

查看声卡输入设备arecord -L，返回：

null
    Discard all samples (playback) or generate zero samples (capture)
default
ac108
dmixer
ac101
sysdefault:CARD=seeed8micvoicec
    seeed-8mic-voicecard,
    Default Audio Device
dmix:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample mixing device
dsnoop:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample snooping device
hw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct hardware device without any conversions
plughw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Hardware device with all software conversions

检查声卡输出设备aplay -L，返回：

null
    Discard all samples (playback) or generate zero samples (capture)
default
ac108
dmixer
ac101
sysdefault:CARD=ALSA
    bcm2835 ALSA, bcm2835 ALSA
    Default Audio Device
dmix:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Direct sample mixing device
dmix:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Direct sample mixing device
dsnoop:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Direct sample snooping device
dsnoop:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Direct sample snooping device
hw:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Direct hardware device without any conversions
hw:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Direct hardware device without any conversions
plughw:CARD=ALSA,DEV=0
    bcm2835 ALSA, bcm2835 ALSA
    Hardware device with all software conversions
plughw:CARD=ALSA,DEV=1
    bcm2835 ALSA, bcm2835 IEC958/HDMI
    Hardware device with all software conversions
sysdefault:CARD=seeed8micvoicec
    seeed-8mic-voicecard,
    Default Audio Device
dmix:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample mixing device
dsnoop:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct sample snooping device
hw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Direct hardware device without any conversions
plughw:CARD=seeed8micvoicec,DEV=0
    seeed-8mic-voicecard,
    Hardware device with all software conversions

按照手册录制、播放音频文件，一切OK，还能边录边播~

#It will capture sound on AC108 and save as a.wav
arecord -Dac108 -f S32_LE -r 16000 -c 8 a.wav
#Take care of that the captured mic audio is on the first 6 channels

#It will play sound file a.wav on AC101
aplay -D ac101 a.wav
#Do not use -D plughw:1,0 directly except your wave file is single channel only.

#Doing capture && playback the same time
arecord -D hw:1,0 -f S32_LE -r 16000 -c 8 to_be_record.wav &
#mono_to_play.wav is a mono channel wave file to play
aplay -D plughw:1,0 -r 16000 to_be_record.wav

按照手册安装audacity，图形界面音频编辑软件，可以说是非常舒适了~

sudo apt-get install -y audacity

3 DOA定位测试

参考：ReSpeaker 6 Mic Array for Raspberry Pi

下载ODAS源码并编译：

sudo proxychains4 apt install -y libfftw3-dev libconfig-dev libasound2-dev cmake
proxychains4 git clone https://github.com/introlab/odas.git
mkdir odas/build
cd odas/build
cmake ..
make

安装完成后，编写麦阵列配置文件respeaker-6mic-odas.cfg：

# Configuration file for ReSpeaker 6 Mic Array
# Circular shape, R = 0.0463m

version = "2.1";

# Raw
raw: 
{
    fS = 16000;
    hopSize = 128;
    nBits = 32;
    nChannels = 8; 

    # Input with raw signal from microphones
    interface: {
        type = "soundcard";
        card = 1;
        device = 0;
    }
}

# Mapping
mapping:
{
    map: (1, 2, 3, 4, 5, 6);
}

# General
general:
{
    epsilon = 1E-20;
    size: 
    {
        hopSize = 128;
        frameSize = 256;
    };
    samplerate:
    {
        mu = 16000;
        sigma2 = 0.01;
    };
    speedofsound:
    {
        mu = 343.0;
        sigma2 = 25.0;
    };
    mics = (
        # Microphone 1
        { 
            mu = ( -0.0232, +0.0401, +0.0000 ); 
            sigma2 = ( +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000 );
            direction = ( +0.000, +0.000, +1.000 );
            angle = ( 80.0, 90.0 );
        },
        # Microphone 6
        { 
            mu = ( +0.0232, +0.0401, +0.0000 ); 
            sigma2 = ( +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000 );
            direction = ( +0.000, +0.000, +1.000 );
            angle = ( 80.0, 90.0 );
        },
        # Microphone 5
        { 
            mu = ( +0.0463, +0.0000, +0.0000 ); 
            sigma2 = ( +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000 );
            direction = ( +0.000, +0.000, +1.000 );
            angle = ( 80.0, 90.0 );        
        },
        # Microphone 4
        { 
            mu = ( +0.0232, -0.0401, +0.0000 ); 
            sigma2 = ( +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000 );
            direction = ( +0.000, +0.000, +1.000 );
            angle = ( 80.0, 90.0 );        
        },
        # Microphone 3
        { 
            mu = ( -0.0232, -0.0401, +0.0000 ); 
            sigma2 = ( +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000 );
            direction = ( +0.000, +0.000, +1.000 );
            angle = ( 80.0, 90.0 );
        },
        # Microphone 2
        { 
            mu = ( -0.0463, +0.0000, +0.0000 ); 
            sigma2 = ( +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000, +0.000 );
            direction = ( +0.000, +0.000, +1.000 );
            angle = ( 80.0, 90.0 );
        }
    );

    # Spatial filters to include only a range of direction if required
    # (may be useful to remove false detections from the floor, or
    # limit the space search to a restricted region)
    spatialfilters = (
        {
            direction = ( +0.000, +0.000, +1.000 );
            angle = (80.0, 90.0);
        }
    );  
    nThetas = 181;
    gainMin = 0.25;
}

# Stationnary noise estimation
sne:
{
    b = 3;
    alphaS = 0.1;
    L = 150;
    delta = 3.0;
    alphaD = 0.1;
}

# Sound Source Localization
ssl:
{
    nPots = 4;
    nMatches = 10;
    probMin = 0.5;
    nRefinedLevels = 1;
    interpRate = 4;

    # Number of scans: level is the resolution of the sphere
    # and delta is the size of the maximum sliding window
    # (delta = -1 means the size is automatically computed)
    scans = (
        { level = 2; delta = -1; },
        { level = 4; delta = -1; }
    );

    # Output to export potential sources
    potential: {
        format = "json";
        interface: {
            type = "socket"; ip = "192.168.1.100"; port = 9001;
        };
        #format = "undefined";
        #interface: {
        #    type = "blackhole";
        #}
    };
}

# Sound Source Tracking
sst:
{
    # Mode is either "kalman" or "particle"
    mode = "kalman";

    # Add is either "static" or "dynamic"
    add = "dynamic";

    # Parameters used by both the Kalman and particle filter
    active = (
        { weight = 1.0; mu = 0.3; sigma2 = 0.0025 }
    );

    inactive = (
        { weight = 1.0; mu = 0.15; sigma2 = 0.0025 }
    );

    sigmaR2_prob = 0.0025;
    sigmaR2_active = 0.0225;
    sigmaR2_target = 0.0025;
    Pfalse = 0.1;
    Pnew = 0.1;
    Ptrack = 0.8;

    theta_new = 0.9;
    N_prob = 5;
    theta_prob = 0.8;
    N_inactive = ( 150, 200, 250, 250 );
    theta_inactive = 0.9;

    # Parameters used by the Kalman filter only
    kalman: {
        sigmaQ = 0.001;
    };
   
    # Parameters used by the particle filter only
    particle: {
        nParticles = 1000;
        st_alpha = 2.0;
        st_beta = 0.04;
        st_ratio = 0.5;
        ve_alpha = 0.05;
        ve_beta = 0.2;
        ve_ratio = 0.3;
        ac_alpha = 0.5;
        ac_beta = 0.2;
        ac_ratio = 0.2;
        Nmin = 0.7;
    };

    target: ();

    # Output to export tracked sources
    tracked: {
        format = "json";
        interface: {
            type = "socket"; ip = "192.168.1.100"; port = 9000;
        };
        #format = "undefined";
        #interface: {
        #    type = "blackhole";
        #}
    };
}

sss:
{
    # Mode is either "dds", "dgss" or "dmvdr"
    mode_sep = "dds";
    mode_pf = "ms";

    gain_sep = 1.0;
    gain_pf = 10.0;

    dds: {

    };

    dgss: {
        mu = 0.01;
        lambda = 0.5;
    };

    dmvdr: {

    };

    ms: {
        alphaPmin = 0.07;
        eta = 0.5;
        alphaZ = 0.8;        
        thetaWin = 0.3;
        alphaWin = 0.3;
        maxAbsenceProb = 0.9;
        Gmin = 0.01;
        winSizeLocal = 3;
        winSizeGlobal = 23;
        winSizeFrame = 256;
    };

    ss: {
        Gmin = 0.01;
        Gmid = 0.9;
        Gslope = 10.0;
    };

    separated: {
        fS = 44100;
        hopSize = 512;
        nBits = 16;        

        interface: {
            type = "file";
            path = "separated.raw";
        };       
    };

    postfiltered: {
        fS = 44100;
        hopSize = 512;
        nBits = 16;        

        interface: {
            type = "file";
            path = "postfiltered.raw";
        };      
    };
}

classify:
{
    frameSize = 1024;
    winSize = 3;
    tauMin = 32;
    tauMax = 200;
    deltaTauMax = 7;
    alpha = 0.3;
    gamma = 0.05;
    phiMin = 0.15;
    r0 = 0.2;    

    category: {
        format = "undefined";

        interface: {
            type = "blackhole";
        }
    }
}

波达方向定位服务odaslives位于odas/bin/目录下，使用配置文件启动定位服务：

ln -s ~/odas/3rd-lib/odas/bin/odaslive ~/.local/bin/odaslive
odaslive -c ~/respeaker-6mic-odas.cfg

在电脑上下载ODAS Studio源码并编译：

sudo npm install npm@latest -g
wget https://github.com/introlab/odas_web/archive/v0.2-alpha.zip
unzip -a v0.2-alpha.zip 
git clone https://github.com/introlab/odas_web.git
cd odas_web-0.2-alpha 
npm install

在电脑上安装npm，并从源码编译odas web v0.2-alpha：

sudo npm install npm@latest -g
cd odas_web
npm install

或者使用已编译好的程序：

proxychains4 wget https://github.com/introlab/odas_web/releases/download/v0.1-alpha/MacOS_x64.tar.gz

Aria2上的BT下载加速

Mon, 15 Oct 2018 21:09:11 GMT

最近迅雷反盗版确实很厉害……

参考：解决Aria2 BT下载速度慢没速度的问题

训练用不了了，用Aria2下载几乎没有速度，怎么办呢？只能靠添加BT源来加速了，新建配置文件：

mkdir ~/.aria2
vim ~/.aria2/aria2.conf

新建Aira2的会话文件，用于保存任务状态：

touch ~/.aria2/aria2.session

Github上有个维护BT源的项目An updated list of public BitTorrent trackers，用Best 20就行，在配置文件里写入：

# https://github.com/ngosang/trackerslist
bt-tracker=udp://62.138.0.158:6969/announce,udp://185.225.17.100:1337/announce,udp://51.15.4.13:1337/announce,udp://151.80.120.114:2710/announce,udp://208.83.20.20:6969/announce,udp://184.105.151.164:6969/announce,udp://191.96.249.23:6969/announce,udp://51.15.76.199:6969/announce,udp://5.79.83.194:6969/announce,udp://51.15.40.114:80/announce,http://128.1.203.23:8080/announce,udp://91.216.110.52:451/announce,udp://5.206.28.90:6969/announce,http://123.249.16.65:6961/announce,udp://51.38.184.185:6969/announce,udp://188.246.227.212:80/announce,udp://51.15.103.67:1337/announce,udp://95.211.168.204:2710/announce,http://104.28.22.4:80/announce,udp://176.31.106.35:80/announce
dir=/Users/zealot/Downloads
max-connection-per-server=16
save-session=/Users/zealot/.aria2/aria2.session
input-file=/Users/zealot/.aria2/aria2.session
save-session-interval=60
enable-dht=true
bt-enable-lpd=true
enable-peer-exchange=true

于是有了速度。

树莓派上的摄像头与OpenCV

Fri, 05 Oct 2018 21:09:11 GMT

树莓派上都有OpenCV了，是不是再装个摄像头玩[奸笑]

参考：Accessing the Raspberry Pi Camera with OpenCV and Python

1 摄像头连接及配置

摄像头安装及配置我就不写了，懒的翻译原文……

1.1 安装依赖

安装带array子模块的picamera，用以将图像Numpy的array传给OpenCV处理：

source activate cv
pip install "picamera[array]"

1.2 摄像头图像预览

需要注意的是，树莓派上的vnc-server默认配置是不能将传输摄像头预览图像传送到vnc-client上的，需要修改配置：在树莓派上打开vnc-server的菜单 -> Options...-> TroubleShooting -> 选择Enable experimental direct capture mode。（参考Sending Raspberry Pi Camera preview to a laptop running VNC Viewer）

2 使用Python+OpenCV访问摄像头输出的图片

通过Python将摄像头输出的图片送入OpenCV进行显示，显示时用到了OpenCV的highGUI：

from picamera.array import PiRGBArray
from picamera import PiCamera
import time
import cv2

# 初始化摄像头
camera = PiCamera()
# 新建原始摄像头数据的引用
rawCapture = PiRGBArray(camera)

# 等一小段时间让摄像头启动
time.sleep(0.1)

# 从摄像头获取一张图片
camera.capture(rawCapture, format="bgr")
image = rawCapture.array

# 在屏幕上显示，按下任意键退出
cv2.imshow("Image", image)
cv2.waitKey(0)
cv2.destroyAllWindows()

需要注意的是获取图片时使用的矩阵格式为format="bgr"，参见4.2. Capturing to an OpenCV object。

使用PiRGBArray对象的好处就是省去了将原始的RGB矩阵封装成各种格式（如JPEG）的步骤，这样读入OpenCV时也就省去了OpenCV将各种格式解码为RGP矩阵的步骤，尤其是在树莓派这种资源受限的设备上能够节省很多算力。

from picamera.array import PiRGBArray
from picamera import PiCamera
import time
import cv2

# 初始化摄像头并设置分辨率和帧率
camera = PiCamera()
camera.resolution = (640, 480)
camera.framerate = 32
# 新建原始摄像头数据的引用，指定分辨率
rawCapture = PiRGBArray(camera, size=(640, 480))

# 等一小段时间让摄像头启动
time.sleep(0.1)

# 从摄像头中获取视频帧
for frame in camera.capture_continuous(rawCapture, format="bgr", use_video_port=True):
    # 直接从摄像头获取使用Numpy矩阵表达的原始图片数据，
    # 其中`camera.capture_continuous`返回一个`frame`对象，
    # `frame`对象的`array`属性中存储的就是该帧Numpy矩阵
    image = frame.array

    # 在highGUI中显示该帧
    cv2.imshow("Frame", image)
    key = cv2.waitKey(1) & 0xFF

    # 注意，在读取下一帧前需要清空当前帧，否则代码报错
    rawCapture.truncate(0)

    # 在highGUI中按q键退出循环
    if key == ord("q"):
        cv2.destroyAllWindows()
        break

3 试一试图像的透视变换

搞事情之前：我想在Python模块搜索路径中加入我的工作环境~/pyworkspace，以后的事情都在这里搞。因此，在~/berryconda3/envs/cv/lib/python3.5/site-packages下新建workspace.pth文件，写入内容：

/home/pi/pyworkspace

搞一个小事情先，试一下OpenCV的性能，比如4 Point OpenCV getPerspective Transform Example，矩形的四点透视变换。

mkdir cvpi && cd cvpi
touch __init__.py
mkdir transform && cd transform
touch perspective_transform.py

透视变换的代码思路：

通过Python代码测量图片中目标矩形区域的长宽；
计算输出直角坐标系中的矩形顶点坐标
利用cv2.getPerspectiveTransform()函数计算变换矩阵并应用，输出图片

import numpy as np
import cv2

# /home/pi/cvpi/transform/perspective_transform.py
# 使用透视变换还原矩形

def order_points(pts):
    """
    调整矩形四个点的排列顺序，用以维护有序的坐标列表。

    接受一个包含四个坐标的列表，按照左上、右上、右下、左下的顺序重新排列坐标。

    Args:
        pts: 一个shape为(4, 2)的nparray。
    Returns:
        顺序调整后的nparray，shape依然是(4, 2)。
    """
    # 初始化包含四个坐标的坐标列表（cv用坐标系，x轴向右，y轴向下），分别对应矩形的左上、右上、右下、左下坐标
    rect = np.zeros((4, 2), dtype = "float32")

    # 计算每个坐标的x+y，左上应当具有最小的和，而右下则应当具有最大的和
    s = pts.sum(axis = 1)
    rect[0] = pts[np.argmin(s)]
    rect[2] = pts[np.argmax(s)]

    # 计算每个坐标的y-x，右上应具有最小差，左下应具有最大差
    diff = np.diff(pts, axis = 1)
    rect[1] = pts[np.argmin(diff)]
    rect[3] = pts[np.argmax(diff)]
    
    return rect

def four_point_transform(image, pts):
    """
    用透视变换，将图片中使用`pts`标注的透视图矩形区域，变换为鸟瞰图中的矩形区域。

    接受一个图片，以及图片中一个矩形的顶点坐标列表，通过透视变换输出该区域的鸟瞰图。

    Args: 
        image: 图片RGB矩阵。
        pts: 目标矩形区域的顶点坐标列表。
    Returns: 
        透视变换后的矩形区域鸟瞰图片。
    """
    # 重新排列矩形顶点坐标，初始化左上、右上、右下、左下坐标
    rect = order_points(pts)
    (tl, tr, br, bl) = rect

    # 计算矩形宽度：取 右上与左上顶点间的距离 与 右下与左下顶点间的距离 之中的最大值
    widthA = np.sqrt(((br[0] - bl[0]) ** 2) + ((br[1] - bl[1]) ** 2))
    widthB = np.sqrt(((tr[0] - tl[0]) ** 2) + ((tr[1] - tl[1]) ** 2))
    maxWidth = max(int(widthA), int(widthB))

    # 计算矩形高度：取 右上与右下顶点间的距离 与 左上与左下顶点间的距离 之中的最大值
    heightA = np.sqrt(((tr[0] - br[0]) ** 2) + ((tr[1] - br[1]) ** 2))
    heightB = np.sqrt(((tl[0] - bl[0]) ** 2) + ((tl[1] - bl[1]) ** 2))
    maxHeight = max(int(heightA), int(heightB))

    # 按照左上(0, 0)、右上(0, H)、右下(W, H)、左下(W, 0)的顺序构造变换后的鸟瞰图坐标列表
    dst = np.array([
        [0, 0],
        [maxWidth - 1, 0],
        [maxWidth - 1, maxHeight - 1],
        [0, maxHeight - 1]
    ], dtype = "float32")

    # 使用源坐标和目标坐标计算透视变换矩阵
    M = cv2.getPerspectiveTransform(rect, dst)
    # 在源图片上应用透视变换
    warped = cv2.warpPerspective(image, M, (maxWidth, maxHeight))

    return warped

测试变换效果：

cd ../..
mkdir test && cd test
touch pptf_test.py

from cvpi.transform.perspective_transform import four_point_transform
import numpy as np
import argparse
import cv2

# /home/pi/cvpi/test/pptf_test.py
# 测试透视变换：
# python pptf_test.py --image images/example_01.png --coords "[(73, 239), (356, 117), (475, 265), (187, 443)]"
# python pptf_test.py --image images/example_02.png --coords "[(101, 185), (393, 151), (479, 323), (187, 441)]"
# python pptf_test.py --image images/example_03.png --coords "[(63, 242), (291, 110), (361, 252), (78, 386)]"

# 构造命令行工具
ap = argparse.ArgumentParser()
ap.add_argument("-i", "--image", help = "path to the image file")
ap.add_argument("-c", "--coords",
	help = "comma seperated list of source points")
args = vars(ap.parse_args())
 
# load the image and grab the source coordinates (i.e. the list of
# of (x, y) points)
# 从文件读取图片RGB矩阵，从命令行中读取目标矩形区域的顶点坐标。
# NOTE: 出于安全考虑，不鼓励使用`eval`函数，但在此仅为测试代码功能。
image = cv2.imread(args["image"])
pts = np.array(eval(args["coords"]), dtype = "float32")
 
# 测试`four_point_transform`的功能。
warped = four_point_transform(image, pts)
 
# 显示图片
cv2.imshow("Original", image)
cv2.imshow("Warped", warped)
cv2.waitKey(0)
cv2.destroyAllWindows()

4 试一试OpenCV文档扫描器

在搞事情之前：

# pwd: ~./pyworkspace/cvpi
mkdir tool && cd tool
touch __init__.py scan.py
conda install -y scikit-image

作者还开源了自己封装的OpenCV常用函数，比如上面的透视变换就包含在内，安装imutils工具包：

pip install --upgrade imutils

另外，我发现16G的卡已经用了很多空间了，所以推荐删点空间出来：

sudo apt-get purge wolfram-engine
sudo apt-get purge libreoffice*
sudo apt-get clean
sudo apt-get autoremove

from cvpi.transform.perspective_transform import four_point_transform
from skimage.filters import threshold_local
import numpy as np
import argparse
import cv2
import imutils

# /home/pi/cvpi/tool/scan.py
 
# 构造命令行工具
ap = argparse.ArgumentParser()
ap.add_argument("-i", "--image", required = True,
	help = "Path to the image to be scanned")
args = vars(ap.parse_args())

################################################################################
# 1 边缘检测
################################################################################
# 读取图片，计算图片原始高度与目标高度的缩放比例
# 备份图片，然后以500为高度成比例缩放图片
image = cv2.imread(args["image"])
ratio = image.shape[0] / 500.0
orig = image.copy()
image = imutils.resize(image, height = 500)
 
# 将图片处理为灰阶图
gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
# 使用高斯模糊去掉较为繁杂的边界，目的是仅保留明显的轮廓，有助于轮廓检查
gray = cv2.GaussianBlur(gray, (5, 5), 0)
edged = cv2.Canny(gray, 75, 200)
 
# show the original image and the edge detected image
# 显示原图与边缘检测的结果对比
print("STEP 1: Edge Detection")
cv2.imshow("Image", image)
cv2.imshow("Edged", edged)
cv2.waitKey(0)
cv2.destroyAllWindows()

################################################################################
# 2 轮廓查找
#   文档扫描的对象通常是一页矩形的文档，按照经验矩形有四个顶点。
#   因此我们假设，边界检查结果中最大的且具有四个顶点的轮廓即为文档轮廓。
################################################################################
# 获得轮廓列表：
# 第一个参数：传入要进行轮廓查找的图片，由于函数会直接操作该图片，这里使用边缘检测后的图片备份。
# 第二个参数：表示使用仅普通列表组织返回的轮廓，
#   若指定为RETR_TREE则还会返回为有层级结构的列表（即表示出轮廓之间的包含关系）。
# 第三参数表示简单压缩轮廓点集，如将共线段的点简化为线段两端点，节省内存。
cnts = cv2.findContours(edged.copy(), cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
# 由于OpenCV2与3返回轮廓检查返回值结构不一样，因此为了代码通用性需要判断OpenCV版本。
cnts = cnts[0] if imutils.is_cv2() else cnts[1]
# 按面积将轮廓从大到小排序，保留面积最大的5个轮廓。
cnts = sorted(cnts, key = cv2.contourArea, reverse = True)[:5]
 
for c in cnts:
	# 测量轮廓周长。
	peri = cv2.arcLength(c, True)
    # 使用Douglas-Peucker曲线近似算法，允许2%的周长误差，返回近似后的顶点列表。
	approx = cv2.approxPolyDP(c, 0.02 * peri, True)
 
    # 如果近似结果仅包含4个顶点，则假设找到原图片中目标文件的轮廓
	if len(approx) == 4:
		screenCnt = approx
		break
 
# 显示目标文件的轮廓
print("STEP 2: Find contours of paper")
# 参数分别为：要绘制的原图，轮廓点集列表，需要绘制的轮廓（-1表示画出所有），轮廓颜色，轮廓粗细
cv2.drawContours(image, [screenCnt], -1, (0, 255, 0), 2)
cv2.imshow("Outline", image)
cv2.waitKey(0)
cv2.destroyAllWindows()

################################################################################
# 3 透视变换
# 将获得的文档轮廓进行透视变换，输出文档的鸟瞰图。
################################################################################
# 将轮廓按比例缩放，并应用透视变换。
warped = four_point_transform(orig, screenCnt.reshape(4, 2) * ratio)
 
# 将变换结果灰阶处理，设置阈值以制造出类似扫描仪的黑白效果。
warped = cv2.cvtColor(warped, cv2.COLOR_BGR2GRAY)
T = threshold_local(warped, 11, offset = 10, method = "gaussian")
warped = (warped > T).astype("uint8") * 255
 
# 显示原图与处理后效果对比
print("STEP 3: Apply perspective transform")
cv2.imshow("Original", imutils.resize(orig, height = 650))
cv2.imshow("Scanned", imutils.resize(warped, height = 650))
cv2.waitKey(0)
cv2.destroyAllWindows()

边缘检测

轮廓查找

透视变换

在树莓派上安装Python3+OpenCV3

Mon, 01 Oct 2018 12:06:10 GMT

最近给树莓派买了一些传感器，感觉能做的事更多了，那就先抄一个机器视觉的玩具练练手吧~当然，怎么能少了OpenCV呢[奸笑]

参考：Raspbian Stretch: Install OpenCV 3 + Python on your Raspberry Pi

1 扩展存储卡空间

运行树莓派配置sudo raspi-config，选择"Advanced Options"，选择"Expand filesystem"，按提示重启。

使用df -h检查存储空间。

当然，如果空间仍然不够用，可以删点东西：

sudo apt-get purge wolfram-engine
sudo apt-get purge libreoffice*
sudo apt-get clean
sudo apt-get autoremove

2 安装依赖

2.1 更新系统

当然，安装依赖前先将系统更新至最新：

sudo apt-get update && time sudo apt-get upgrade && time sudo apt-get dist-upgrade

2.2 安装编译/开发工具

安装包括cmake在内的开发工具，帮助我们配置并编译opencv：

sudo apt-get install build-essential cmake pkg-config

2.3 图片相关依赖

安装图片I/O相关包，包括常见的JPEG、PNG、TIFF等：

sudo apt-get install libjpeg-dev libtiff5-dev libjasper-dev libpng12-dev

2.4 视频相关依赖

安装读取视频、处理视频流的相关依赖：

sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
sudo apt-get install libxvidcore-dev libx264-dev

2.5 `highgui`相关依赖

安装OpenCV时会附带一个叫做highgui的子模块，该模块使用GUI界面显示图片，要使得该模块能够正常编译，需要安装：

sudo apt-get install libgtk2.0-dev libgtk-3-dev

2.6 优化相关依赖

通过安装一些依赖可以优化OpenCV内部的矩阵运算过程，这些优化依赖对像树莓派这样计算资源受限的设备来说尤为重要：

sudo apt-get install libatlas-base-dev gfortran

2.7 Python头文件

为了通过Python使用OpenCV库，在编译时需要Python头文件等资源：

sudo apt-get install python2.7-dev python3-dev

3 下载OpenCV源码

3.1 OpenCV

我们从OpenCV官网下载最新版源码（版本3.4.3），该版本带有深度神经网络模块，推荐从本机下载并上传树莓派，因为本机迅雷下器比较快🤦‍：

scp ./Downloads/cv_3.4.3.zip pi@192.168.1.108:./
unzip cv_3.4.3.zip

3.2 OpenCV高级功能

我们希望能够使用OpenCV的所有功能（包括如SIFT、SURF在内的高级功能），需要下载相应版本的opencv_contrib：

scp ./Downloads/cv_c_3.4.3.zip pi@192.168.1.108:./
unzip cv_c_3.4.3.zip

4 Python版本控制

我习惯使用conda，因此下了个berryconda，上传树莓派（还是因为迅雷更快🤦‍）：

scp ./Downloads/Berryconda3-2.0.0-Linux-armv7l.sh pi@192.168.1.108:./

并安装：

chmod +x Berryconda3-2.0.0-Linux-armv7l.sh
./Berryconda3-2.0.0-Linux-armv7l.sh

安装完成之后更新conda：

conda update --all

新建名叫cv的环境：

conda create -n cv python=3.5.3

激活环境：

source activate cv
# 退出环境
#source deactivate

安装Numpy，需要比较长的时间：

conda install numpy

关于原文使用pip而这里使用conda的参考原因（编译选项问题导致conda安装的Python与pip安装的Numpy不兼容）。

5 其他软件包

因为个人爱好和习惯，我又安装了TensorFlow以及tesseract：

sudo apt install libatlas-base-dev
pip install tensorflow
sudo apt-get install tesseract-ocr
pip install pytesseract

6 构建

6.1 解压并构建

cd ~/opencv-3.4.3/
mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D INSTALL_PYTHON_EXAMPLES=ON \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib-3.4.3/modules \
    -D BUILD_EXAMPLES=ON ..

6.2 检查构建输出

务必检查CMake构建输出中Python解释器/库等信息，正常构建完成的信息应包含类似：

--   Python 3:
--     Interpreter:                 /home/pi/berryconda3/envs/cv/bin/python3 (ver 3.5.3)
--     Libraries:                   /usr/lib/arm-linux-gnueabihf/libpython3.5m.so (ver 3.5.3)
--     numpy:                       /home/pi/berryconda3/envs/cv/lib/python3.5/site-packages/numpy/core/include (ver 1.15.1)
--     packages path:               lib/python3.5/site-packages
--

6.3 修改SWAP配置

在开始编译前，先调整一下虚拟内存大小，使得编译过程能够利用树莓派的全部四颗核心，避免编译过程因为内存不足而挂起：

sudo vim /etc/dphys-swapfile
# dphys-swapfile:
# CONF_SWAPSIZE=100
CONF_SWAPSIZE=1024

再重启虚拟内存服务：

sudo /etc/init.d/dphys-swapfile stop
sudo /etc/init.d/dphys-swapfile start

注意：在完成所有编译、安装，且试验成功后，记得吧虚拟内存改回去，否则据说容易烧卡。

7 编译

终于可以开始编译了，大约需要一个半小时：

make -j4

编译时树莓派会启用全部四颗核心，因此强烈建议开启散热风扇，编译时的top CPU利用率：

8 安装

将编译完成的OpenCV安装在系统中：

sudo make install
sudo ldconfig

此时OpenCV及Python支持已经安装再/usr/local/lib/python3.5/site-packages目录下了：

ls -l /usr/local/lib/python3.5/site-packages/
总用量 4628
-rw-r--r-- 1 root staff 4738076 9月  28 23:16 cv2.cpython-35m-arm-linux-gnueabihf.so

出于某种原因，编译完成的的.so文件叫做cv2.cpython-35m-arm-linux-gnueabihf.so，我们需要将其重命名：

cd /usr/local/lib/python3.5/site-packages/
sudo mv cv2.cpython-35m-arm-linux-gnueabihf.so cv2.so

之后再将其链接在conda的cv环境中：

cd ~/berryconda3/envs/cv/lib/python3.5/site-packages/
ln -s /usr/local/lib/python3.5/site-packages/cv2.so cv2.so

9 测试

在cv环境中测试：

source activate cv
python
>>> import cv2
>>> cv2.__version__
'3.4.3'
>>>

10 一些问题

一开始我使用python 3.6.6：

conda create -n cv python=3.6

然后编译：

cd ~/opencv-3.4.3/
mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D INSTALL_PYTHON_EXAMPLES=ON \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib-3.4.3/modules \
    -D BUILD_EXAMPLES=ON ..

报错：

-- Found PythonInterp: /usr/bin/python2.7 (found suitable version "2.7.13", minimum required is "2.7")
-- Found PythonLibs: /usr/lib/arm-linux-gnueabihf/libpython2.7.so (found suitable exact version "2.7.13")
-- Found PythonInterp: /home/pi/berryconda3/envs/cv/bin/python3 (found suitable version "3.6.6", minimum required is "3.4")
-- Could NOT find PythonLibs (missing:  PYTHON_LIBRARIES PYTHON_INCLUDE_DIRS) (Required is exact version "3.6.6")

即树莓派上还没有python3.6-dev，仅有python3.5-dev（即python 3.5.3-0版本），于是我打算用cmake -D指定，或是export环境变量，发现报错依然存在：

cd ~/opencv-3.4.3/
mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D INSTALL_PYTHON_EXAMPLES=ON \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib-3.4.3/modules \
    -D PYTHON_INCLUDE_DIR=$(python -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())")  \
    -D PYTHON_LIBRARY=$(python -c "import distutils.sysconfig as sysconfig; print(sysconfig.get_config_var('LIBDIR'))") \
    -D BUILD_EXAMPLES=ON ..

参考CMake cannot find PythonLibs #8174的说明想修改cmake文件也不成功。

通过Debian软件包搜索可知这个包在新版的buster中才有，scratch中是没有的……

肝的太晚了实在懒得解决了……有知道的仁人志士麻烦邮箱我一下解决方案Orz。

树莓派上的科学上网

Tue, 25 Sep 2018 12:06:10 GMT

树莓派上不论是raspbian的安装/更新，还是conda/pip的安装/更新，都因为科学原因不太稳定，因此可以先准备科学安装/更新环境。

1 系统安装及配置

1.1 Headless下的WiFi及ssh配置

因为要将树莓派当做网关用，所以用命令行就可以了，下载lite镜像。按树莓派官方说明在SD卡上写入镜像，然后进行Headless配置：

配置WIFI，需要在SD卡根目录下新建一个名为wpa_supplicant.conf的文件：

touch /Volumes/boot/wpa_supplicant.conf

写入WIFI配置：

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="<YOUR-NETWORK-NAME>"
    psk="<YOUR-NETWORK-PASSWORD>"
}

开启SSH，只需在SD卡根目录下新建一个名为ssh的空文件即可：

touch /Volumes/boot/ssh

配置完成后正常启动树莓派即可自动连接WIFI，SSH可以正常登录。注：如果不知道设备IP，可以使用ping raspberry.local查找。

如果这个IP上曾经还有过其他树莓派前辈，那么要先删除本机上的ssh信任主机，比如我的树莓派一直用固定IP配在108上：

ssh-keygen -R 192.168.1.108

第一次用pi登录后默认密码为raspberry，应使用sudo raspi-config通过树莓派管理工具修改密码、主机名等信息，或是直接使用passwd修改密码。

1.2 换国内镜像源

解决升级慢或Cannot initiate the connection to mirrors.opencas.cn问题：

sudo vi /etc/apt/sources.list

修改sources.list，注释第一行，在最后添加国内镜像站：

deb http://mirrors.aliyun.com/raspbian/raspbian/ stretch main non-free contrib
deb-src http://mirrors.aliyun.com/raspbian/raspbian/ stretch main non-free contrib

同样的：

sudo vi /etc/apt/sources.list.d/raspi.list

修改raspi.list，注释第一行，在最后添加：

deb http://mirrors.aliyun.com/raspbian/raspbian/ stretch main ui

也可以使用其他镜像站，比如：

# 中国科学技术大学
Raspbian http://mirrors.ustc.edu.cn/raspbian/raspbian/
# 阿里云
Raspbian http://mirrors.aliyun.com/raspbian/raspbian/
# 清华大学
Raspbian http://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/
# 华中科技大学
Raspbian http://mirrors.hustunique.com/raspbian/raspbian/
Arch Linux ARM http://mirrors.hustunique.com/archlinuxarm/
# 华南农业大学（华南用户）
Raspbian http://mirrors.scau.edu.cn/raspbian/
# 大连东软信息学院源（北方用户）
Raspbian http://mirrors.neusoft.edu.cn/raspbian/raspbian/
# 重庆大学源（中西部用户）
Raspbian http://mirrors.cqu.edu.cn/Raspbian/raspbian/
# 中山大学 已跳转至中国科学技术大学源
Raspbian http://mirror.sysu.edu.cn/raspbian/raspbian/
# 新加坡国立大学
Raspbian http://mirror.nus.edu.sg/raspbian/raspbian

固件升级，谨慎操作，可能会踩到奇怪的编译坑：

sudo rpi-update && sudo reboot -h now

软件包升级：

sudo apt-get update && time sudo apt-get upgrade && time sudo apt-get dist-upgrade

软件包清理，顺便装个vim：

sudo apt-get clean
sudo apt-get install -y vim

解决树莓派的locale警告：

sudo dpkg-reconfigure locales

选择生成en_GB.UTF-8、en_US.UTF-8、zh_CN.UTF-8。

为空项设置值：

sudo update-locale LANGUAGE="en_GB.UTF-8"
sudo update-locale LC_ALL="en_GB.UTF-8"

2 搭建科学工具

2.1 安装SS

安装shadowsocks命令行客户端：

pip install shadowsocks
sudo apt-get install -y shadowsocks-libev
# 更新CPAN
sudo cpan install CPAN
# 重载CPAN
sudo cpan reload CPAN
sudo cpan Net::Shadowsocks

2.2 配置防火墙

安装UFW以方便调整防火墙策略，其实是我不会用iptables：

sudo apt-get install ufw

更新防火墙策略：

sudo ufw allow proto tcp to 0.0.0.0/0 port 22 comment "sshd listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 5900 comment "vnc server listen port"
sudo ufw allow proto tcp to 0.0.0.0/0 port 1080 comment "Shadowsocks server listen port"
sudo ufw default deny 
sudo ufw enable

2.3 socks5代理

在/etc/shadowsocks-libev/xxx.json下配置科学上网服务器：

{
    "server": "<your-remote-server>",
    "server_port": <your-remote-server-port>,
    "timeout": 60,
    "password": "<your-password>",
    "method": "aes-256-cfb",
    "local_address": "0.0.0.0",
    "local_port": 1080
}

sudo netstat -nap | grep 8388

停止默认ss服务端：

# 检查ss默认系统服务
systemctl list-unit-files # 或 systemctl -a
systemctl status shadowsocks-libev.service 
sudo systemctl stop shadowsocks-libev.service 
sudo systemctl disable shadowsocks-libev.service 
systemctl status shadowsocks-libev.service

启动ss客户端：

# 后台
nohup ss-local -v -c /etc/shadowsocks-libev/xxx.json &
# 或前台
ss-local -v -s <your-remote-server> -p <your-remote-server-port> -l 1080 -k <your-password> -m aes-256-cfb

测试ss客户端的socks5是否正常：

curl -I --socks5 localhost:1080 google.com

停止ss客户端：

sudo kill -TERM 5914 && rm nohup.out

编写快捷脚本：

启动脚本ss-s：

sudo touch /usr/local/bin/ss-s
sudo chmod +x /usr/local/bin/ss-s

#!/bin/bash

nohup ss-local -v -c /etc/shadowsocks-libev/xxx.json > ~/nohup.log 2>&1 &
echo $! > ~/ss-pid.txt

停止ss-t：

sudo touch /usr/local/bin/ss-t
sudo chmod +x /usr/local/bin/ss-t

#!/bin/bash

kill -s TERM `cat ~/ss-pid.txt`
rm ~/ss-pid.txt

2.4 proxychains-ng

ProxyChains是一个使用方便的代理工具，它只会代理指定的程序，下载：

git clone https://github.com/rofl0r/proxychains-ng

安装：

cd proxychains-ng/
./configure --prefix=/usr --sysconfdir=/etc
make 
sudo make install
sudo make install-config

配置/etc/proxychains.conf，将最后一行修改为shadowsocks的端口：

socks5 127.0.0.1 1080

测试wget，返回网页源码：

proxychains4 wget -qO- https://www.google.com

2.5 http代理

有些程序并不像curl那样能够直接支持socks5代理，有时，按照情况需要配置http代理。安装privoxy，开启全局http代理，其默认代理地址为http://127.0.0.1:8118：

sudo apt-get install privoxy
sudo -s
echo 'forward-socks5 / 127.0.0.1:1080 .' >>/etc/privoxy/config
^D
systemctl status privoxy.service
#systemctl enable privoxy.service
#systemctl start privoxy.service
#systemctl restart privoxy.service
systemctl status privoxy.service

测试http代理：

wget -qO- -e use_proxy=yes -e http_proxy=127.0.0.1:8118 http://google.com

conda可能存在科学安装问题，因此可以临时设置代理环境变量：

export HTTP_PROXY="http://127.0.0.1:8118" && conda install -y scikit-image
unset HTTP_PROXY

或是配置.condarc的代理：

proxy_servers:
  http: http://127.0.0.1:8118

3 云科学（要钱）

3.1 在AWS上部署Streisand

在aws中新建用户administrator，放入新建组Administrators，附加超级管理员权限AdministratorAccess。新建访问秘钥并下载，记住key id与key后删除秘钥。

aws启动Ubuntu 16.04实例，在安装pip时出现E: Unable to locate package python-pip：

sudo apt-get install software-properties-common
sudo apt-add-repository universe
sudo apt-get update
sudo apt-get install python-pip
pip install --upgrade pip

软件包升级：sudo apt-get update && time sudo apt-get upgrade && time sudo apt-get dist-upgrade

查看系统地区设置locale，添加中文支持sudo locale-gen zh_CN.UTF-8 设置空项的值：

sudo update-locale LANGUAGE="en_US.UTF-8"
sudo update-locale LC_ALL="en_US.UTF-8"

在树莓派上安装Streisand的准备工作：生成秘钥对：

ssh-keygen

安装git和vim：

sudo apt-get install git
sudo apt-get install vim

安装python编译依赖：

sudo apt install python-paramiko python-pip python-pycurl python-dev build-essential

安装ansible相关依赖：

sudo pip install ansible markupsafe

安装aws相关依赖：

sudo pip install boto boto3

下载Streisand源码并安装：

git clone https://github.com/StreisandEffect/streisand.git && cd streisand
./streisand

按要求填写aws的相关信息，等很久…部署完成…

拷贝generated-docs到一个能看HTML网页的机器上（我的树莓派是raspbian lite版本）：

scp -r pi@<raspberrypi-ip>:streisand ~/Downloads

按照网页提示、按需求（iOS、Linux、Android等）一步一步操作。

在树莓派上，按streisand生成的generated-docs中的提示信息，填写shadowsocks的配置文件/etc/shadowsocks-libev/aws.json：

{
    "server":"<your-server-ip>",
    "server_port":<your-server-port>,
    "timeout":60,
    "password":"<your-password>",
    "method":"chacha20-ietf-poly1305",
    "local_address":"0.0.0.0",
    "local_port":1080
}

3.2 本机编译科学工具

由于树莓派上直接安装的shadowsocks不支持chacha20-ietf-poly1305加密算法，因此，需要从源码编译shadowsocks：

# Installation of basic build dependencies
sudo apt-get install --no-install-recommends gettext build-essential autoconf libtool libpcre3-dev asciidoc xmlto libev-dev libc-ares-dev automake libmbedtls-dev libsodium-dev

# Installation of Libsodium
export LIBSODIUM_VER=1.0.16
wget https://download.libsodium.org/libsodium/releases/libsodium-$LIBSODIUM_VER.tar.gz
tar xvf libsodium-$LIBSODIUM_VER.tar.gz
pushd libsodium-$LIBSODIUM_VER
./configure --prefix=/usr && make
sudo make install
popd
sudo ldconfig

# Installation of MbedTLS
export MBEDTLS_VER=2.12.0
wget https://tls.mbed.org/download/mbedtls-$MBEDTLS_VER-gpl.tgz
tar xvf mbedtls-$MBEDTLS_VER-gpl.tgz
pushd mbedtls-$MBEDTLS_VER
make SHARED=1 CFLAGS=-fPIC
sudo make DESTDIR=/usr install
popd
sudo ldconfig

# Start building
git submodule update --init --recursive
# ref: https://github.com/shadowsocks/shadowsocks-libev/issues/1177#issuecomment-319032195
./autogen.sh && ./configure --with-sodium-include=/usr/include --with-sodium-lib=/usr/local/lib --with-mbedtls-include=/usr/include --with-mbedtls-lib=/usr/lib && make
sudo make install

现在使用ss-local --help会发现加密算法支持chacha20-ietf-poly1305。使用

# 启动aws
nohup ss-local -v -c /etc/shadowsocks-libev/aws.json&
# 测试连接
curl -I --socks5 localhost:1080 google.com
# 返回301，成功

关于要钱：最便宜的EC2即可，一个月不到8刀吧……

Redhat Linux初体验（3）

Fri, 03 Aug 2018 11:22:47 GMT

这三周都被拐卖到成都培训RHCE，讲真，还是当学生好啊~哈哈哈~把学习笔记搬上来，关键时刻能做个速查~

献上第三周的笔记。

2018-07-30

防火墙

通常使用Firewall Configuration图形界面进行配置更方便；
Ports、Sources等普通规则（单规则）添加时应注意，这些规则的生效是取并集；Rich Rules（富语言规则）用来配置复杂规则，常用语配置交集过滤；
iptables等旧命令使用直接语言规则，在Redhat 7中已经不提倡使用，具体参考man 1 firewall-cmd和man 5 firewalld.direct；
Redhat 7推荐使用富语言规则，参考man 5 firewalld.richlanguage
- 查看服务firewall-cmd --get-services
- 查看区域已经添加或生效的策略firewall-cmd --list-all
- 查看富语言规则firewall-cmd --list-rich-rules
实验：仅允许desktop4访问server4的web服务，要求日志具有前缀NEW HTTP ，日志限速每秒3条：
- 安装httpd服务：yum -y install httpd；
- 添加内容：echo '<h1>hello world</h1>' > index.html；
- 启动服务：systemctl start httpd.service && systemctl enable httpd.service；查看服务netstat -tnlp
- 图形化界面添加：Family: ipv4、Element: service: http、Action、Source: 172.25.4.10/32、Log: Prifix: NEW HTTP; With limit: 3/second
- 查看日志在系统挑日志：tail /var/log/message；
- 查看已生效策略：firewall-cmd --list-all
- 使用命令行重新实验，重载配置：firewall-cmd --reload；
- 参考man 5 firewalld.direct：
```
# 运行时生效
firewall-cmd --add-rich-rule 'rule family="ipv4" source address="172.25.4.10/32" service name="http" log prefix="NEW HTTP" limit value="3/s" accept'
# 永久生效
firewall-cmd --add-rich-rule 'rule family="ipv4" source address="172.25.4.10/32" service name="http" log prefix="NEW HTTP" limit value="3/s" accept' --permanent
```
伪装功能Masquerading用来改“发件人”信息（通常用于保护内部网络结构），端口转发Port Forwarding用来改“收件人”信息；
- 伪装，发送包时，内网使用10.0.0.1-3...，伪装为1.2.3.4:10001-3转发去外网；接受包时将1.2.3.4:10001-3转换为内网IP10.0.0.1-3；（NAT转换）
- 富语言规则可以指定网段进行伪装，但规则伪装只能对所有包进行伪装，无法指定网段；
- 端口转发，服务器使用私有IP，外部请求为1.2.3.4:80，防火墙转发为10.0.0.1:8080，通常用于保护内网服务安全；
- 伪装不需要配置伪装前后的规则，防火墙自动转换；而端口转发需要配置转发前后的规则；
实验：服务器server4（172.25.4.11）是一个在防火墙desktop4（172.25.4.10）后面的运行web服务（8080/TCP）的服务器，配置过程如下：
- 重置虚拟机：rht-vmctl reset all
- server4安装httpd：yum install -y httpd；配置vim /etc/httpd/conf/httpd.conf监听8080；
- 启动服务：systemctl start httpd.service && systemctl enable httpd.service；查看服务netstat -tnlp，8080启动；
- 为server4添加允许来自desktop4的流量：
```
firewall-cmd --add-rich-rule 'rule family="ipv4" source address="172.25.4.10/32" port port="8080" portocol="tcp" accept'
```
- 为desktop4添加端口转发并开启伪装：
```
# 开启伪装
firewall-cmd --add-masquerade
# 开启端口转发
firewall-cmd --add-rich-rule 'rule family="ipv4" forward-port port="80" protocol="tcp" to-port="8080" to-addr="172.25.0.11"'
```
- 从物理机访问防火墙desktop4的80端口，会转发至server4的8080端口；
- 注意：从desktop4直接访问desktop4的80端口是不可以的，牵扯到用户态到内核态的数据转换，只能通过外部（如物理机）访问desktop4进行测试，详情Google “iptables四表五链”；

SELinux端口控制

SELinux检查进程和端口的标签间的权限：
- 查看进程标签：ps Z 1757，即SELinux标签的源；
- 查看80端口的标签：semanage port -l | egrep"\b80\b"，即SELinux标签的目的；
- 查看规则：sesearch -A -s httpd_t -t http_port_t
配置SELinux端口权限：
- 修改端口为8800：vim /etc/httpd/conf/httpd.conf
- 重启systemctl restart httpd报错，具体情况查看systemctl status -l httpd；
- 为8800新增http访问的标签：semanage port -a -t http_port_t -p tcp 8800；
- 删除原来的标签：semanage port -d -p tcp 8080
- 修改原来的标签：semanage port -m -t ftp_port_t -p tcp 8800
- 注意：SELinux的默认标签是无法删除的，而对默认标签的修改也仅是新增一条相应的标签策略；

DNS管理

静态授权DNS位于/etc/hosts；
DNS缓存
DNS服务器位于/etc/resolv.conf
解析过程为：先找DNS静态授权数据，再找本地缓存，最后远程DNS缓存服务器（查找条件转发器forward，最后查找rootDNS服务器)；
查找DNS：
- 显示简要信息：nslookup www.example.com；
- 显示详细的查询过程过程（IPv4）：host -vt A desktop4.example.com
- 显示详细的查询过程过程（IPv6）：host -vt AAAA desktop4.example.com
- 主DNS服务器可以修改数据；辅助DNS服务器不能直接修改，只能同步主DNS服务器，主/辅DNS是授权DNS，有负责的区域，即与跟域呈树形结构；缓存服务器缓存的是任意值，即二维表型结构；
- 别名是由主机名指向主机名的记录，A、AAAA与别名都是存在正向DNS记录中；
搭建缓存名称服务：
- 安装unbound：yum install -y unbound；
- 修改配置文件：vim /etc/unbound/；
```
interface: 172.25.4.11
access-control: 172.25.4.0/24 allow
domian-insecure: "example.com"
forward-zone:
        name: "example.com"
        forward-addr: 172.25.254.254
```
- 启动服务：systemctl start unbound；查看服务启动情况：netstat -tnlp；
- 允许防火墙通过：firewall-cmd --add-service=dns；
- 检查配置文件语法错误：unbound-checkconf；
- 从desktop4上测试dig @server4.example.com A server6.example.com；
- 导出配置：unbound-control dump_cache > dump.out；
- 导入配置：unbound-control load_cache < dump.out；
- 清除缓存：unbound-control flush server4.example.com；
- 清楚域信息：unbound-control flush_zone example.com；

邮件服务

邮件是所有Linux自带的服务，因为crond等服务都是依赖邮件服务的；
发送邮件：mail -s 'hello student'
空客户端：禁用本地邮件投递能力，将邮箱投递全部转发到指定服务器中；
配置postfix邮件服务器：/etc/postfix/mail.cf，可以使用postconf工具，也可以直接编辑；
- 在desktop4上：重置服务器，lab smtp-nullclient setup
- 修改邮件服务器配置：vim /etc/postfix/main.cf
```
myorigin        = desktop4.example.com
inet_interfaces = loopback-only
# [空]
mydestination   = 
mynetworks      = 127.0.0.0/8 [::1]/128
relayhost       = smtp4.example.com
local_transport = error:"local delivery disabled"
```
- 日志排错在/var/log/maillog，如果遇到服务报错或邮件未收到，可以使用日志排错；
- 在server4上发送邮件测试：
```
mail -s 'remote student' student@desktop4.example.com
# 正文
hello remote
# ^D提交
EOT
```

2018-7-31

存储

DAS(direct attach storage)
NAS(network attach storage):
- unix-like nfs;
- Windows smb(cifs)
SAN(storage area network): SCSI
概念：
- node: iSCSI initiator或iSCSI target都是node；
- IQN(iSCSI Qualified Name)：全球唯一，类似链路层的MAC地址，以及网络层的IP地址；
- target：一个带有IQN地址的提供存储资源的设备；
- initiator：一个带有IQN地址的获取存储资源的设备；
- portal：入口，由IP地址和端口组成，用于建立连接；
- TPG(Target Portal Group)：一组入口，用于指定iSCSI目标监听；
- ACL(Access Control List)：用于限制initiator访问的IQN资源；
- discovery：基于入口或入口组的资源发现；
- login：initiator验证登录；
实验：
- desktop4上安装initiatoryum install -y iscsi-initiator-utils.i686；
- server4上安装targetyum install -y targetcli.noarch；

在server4上：

查看硬盘：lsblk，划分分区：fdisk /dev/vdb；
创建pv：pvcreate /dev/vdb1；
创建vg：vgcreate ISCSI_vg /dev/vdb1；
创建lv：lvcreate -l 511 -n disk1_lv ISCSI_vg，把disk1_lv当做存储做实验；
进入targetcli交互模式：

# 创建block1：
/backstores/block create block1 /dev/ISCSI_vg/disk1_lv
# 创建IQN：
/iscsi create iqn.2018-07.com.example:server4
# 创建ACL指定desktop4：
/iscsi/iqn.2018-07.com.example:server4/tpg1/acls create iqn.2018-07.com.example:desktop4
# 切换到/iscsi/iqn.2018-07.com.example:server4/tpg1>方便一些，创建LUN
luns/ create /backstores/block/block1
# 创建监听端口，使用默认端口3260：
portals/ create 172.25.4.11
# 查看所有配置
ls
# 退出自动保存（格式为json，在/etc/target/saveconfig.json）
exit

添加防火墙策略：firewall-cmd --add-port=3260/tcp；

在desktop4上：
- 修改IQN：vim /etc/iscsi/initiatorname.iscsi中的IQN为server4 ACL允许的名称iqn.2018-07.com.example:desktop4；
- 发现target：iscsiadm --mode discoverydb --type sendtargets --portal 172.25.4.11:3260 --discover，发现后系统自动将目标记录在/var/lib/iscsi/nodes/中；
- 登录：iscsiadm --mode node -targetname iqn.2018-07.com.example:server4 --portal 172.25.4.11:3260 --login
- 查看设备：lsblk
- 登出：iscsiadm --mode node -targetname iqn.2018-07.com.example:server4 --portal 172.25.4.11:3260 --logout
- 详情参考man 8 iscsiadm

nfs共享

在server4上：
- 查看包是否按照rpm -q nfs-util；创建/nfsshare目录；
- 配置共享vim /etc/exports：/nfsshare desktop4.example.com(rw)；
- 启用服务systemctl status nfs-server && systemctl enable nfs-server && systemctl start nfs-server；
- 修改共享配置后重载exportfs -r；
- 添加nfs防火墙策略firewall-cmd --add-service=nfs --permanent && firewall-cmd --add-service=nfs；
- 添加rpc-bind防火墙策略（远端查看showmount需要）firewall-cmd --add-service=rpc-bind --permanent && firewall-cmd --add-service=rpc-bind；
- 添加mountd防火墙策略（远端查看showmount需要）firewall-cmd --add-service=mountd --permanent && firewall-cmd --add-service=mountd；
- 端口信息可以从grep 2049 /etc/services中看到；
- 查看共享目录showmount -e server4
在desktop4上：
- 新建挂载点mkdir /mnt/nfsshare；
- 挂载mount server4:/nfsshare /mnt/nfsshare；
- 永久挂载echo 'server4:/nfsshare /mnt/nfsshare nfs defaults,_netdev 0 0' >> /etc/fstab && mount -a；
共享权限问题：
- 若共享不可写，则检查model模型及SELinux；共享时虽然由root发起nfs-server进程，但是实际服务用户是一个名为id nfsnobody的内置账号，因此需要在server4上授权chmod o+w /nfsshare；
- 在desktop4上强制修改SELinux标签：mount -o context="system_u:object_r:public_content_rw_t:s0" server4:/nfs /media；
- 服务端的配置在/etc/sysconfig/nfs配置RPCNFSDARGS="-V 4.2"，desktop4挂载时使用mount -o v4.2 server4:/nfs /media，可以使客户端与服务端文件的SELinux一致；
- 关于各软件的SELinux目录权限标签可以参考“软件名_selinux(8)”，如man 8 nfsd\_selinux；公共目录读写通常使用public_content_rw_t；
实验：
- 安装环境：lab nfskrb5 setup
- 在server4上，下载krb凭证wget -O /etc/krb5.keytab http://classroom.example.com/pub/keytabs/server4.keytab
- 新建文件夹/securenfs；
- 设置共享/etc/exports写入/securenfs desktop4.exmaple.com(rw,sec=krb5p)；
- 修改nfs版本配置/etc/sysconfig/nfs该为RPCNFSDARGS="-V 4.2"；
- 防火墙添加服务：
```
firewall-cmd --add-service=nfs
firewall-cmd --add-service=nfs --permanent
```
- 启动nfs服务：
```
systemctl enable nfs-server
systemctl enable nfs-secure-server
systemctl start nfs-server
systemctl start nfs-secure-server
systemctl status nfs-server
systemctl status nfs-secure-server
```
- 在desktop4上，下载krb凭证wget -O /etc/krb5.keytab http://classroom.example.com/pub/keytabs/desktop4.keytab
- 新建挂载点mkdir /mnt/sercureshare
- 启动服务
```
systemctl enable nfs-secure
systemctl start nfs-secure
systemctl status nfs-secure
```
- 挂载mount -o sec=krb5p,v4.2 server4:/securenfs /mnt/secureshare
- 配置永久挂载：server4:/securenfs /mnt/secureshare nfs4 defaults,_netdev,sec=krb5p,v4.2 0 0
- 另外，如果挂载时遇到访问被拒绝的问题，可以使用klist /etc/krb5.keytab查看证书问题；
- 挂载选项中的_netdev选项参见man 8 mount，即网络设备启动过后再执行挂载；

2018-08-01

nfs共享权限

使用krb认证后，若切换到认证用户身份（如ldapuser1），则权限已经从nfsnobody用户变为认证用户了（即ldapuser1）；共享的权限检查顺序为：
- 共享权限vim /etc/exports；
- model权限ll -d /securenfs，包括ACL权限；
- SELinux权限ll -dZ /securenfs；
权限试验：
- 在server4上创建文件：echo 'hello world' > /securenfs/testfile.txt
- 修改SELinux标签：chron -t public_content_t /securenfs/testfile.txt
- 修改文件属主为ldap用户：chown ldapuser0:ldapuser0 /securenfs/testfile.txt
- 修改model权限：chmod 644 /securenfs/testfile.txt
- 在desktop4上查看共享权限：ls -Z /mnt/shcureshare/
- 通过认证切换用户为ldapuser4：ssh ldapuser4@localhost
- 尝试写入失败：echo 'i can't wirte' >> /mnt/seucreshare/testfile.txt，文件对ldapuser4只读；
- 通过认证切换用户为ldapuser0：ssh ldapuser4@localhost；注意：不可以通过su - ldapuser0，因为这样不会通过krb进行认证；
- 此时可以写入：echo 'i can't wirte' >> /mnt/seucreshare/testfile.txt；
nfs与smb的路径对比：
- nfs：hostname:/pathname
- cifs(smb)：//hostname/sharename，其中的sharename在/etc/samba/smb.conf中配置；

smb共享

smb(server message block)是一个标准的文件共享协议，用户Windows系统；smb文件服务器可以配置为工作组模式或域模式；
- 工作组绝对平等，每台电脑管理自己的本地用户及密码，不适于大规模管理；
- 域成员服从域控制器，用户通过域控制器认证；

创建smb共享：

在server4上安装及查看yum install -y samba，rpm -ql samba；
smb安装完成后提供两个服务：nmb提供netbios服务，解析共享时的域名解析；smb即共享服务；
配置vim /etc/samba/smb.conf，参考man 4 samba：

workgroup = WORKGROUP
hosts allow = 
[yinhe]
path = /smbshare/
# 用户,@组
write list = smbuser4,@smb
valid users = smbuser4

使用testparm检查配置文件语法错误；
启动服务

systemctl enable smb nmb
systemctl start smb nmb
# 检查服务：139、445端口已经启动
netstat -tnlp

配置防火墙：

firewall-cmd --add-service=samba
firewall-cmd --add-service=samba --permanent

在desktop4上新建非交互用户，为smbuser4指定非交互shell：useradd -s /sbin/nologin smbuser4
设置smb格式密码：

# 搜索提供该命令的包
yum provides smbpasswd
# 安装该包
yum install -y samba-client
# 为用户设置密码
smbpasswd -a smbuser4
# 查看该用户
pdbedit -L

尝试挂载：mount //server4/yinhe /media报错，查看日志tail /var/log/message，发现需要cifs文件系统；
安装cifs文件系统支持yum install -y cifs-utils
指定用户挂载：mount -o username=smbuser4,password=redhat //server4/yinhe /media/

尝试访问被拒绝，在server4中添加SELinux读权限：

# 查看SELinux标签
ll -dZ /smbshare
# 添加读标签，测试后可以访问，注意，chcon只用于临时调试，要永久修改策略应使用semanage
chcon -t public_content_t /smbshare/
# 该为写标签
chcon -t public_content_rw_t /smbshare/

为共享用户smbuser4添加ACL：

# 查看ACL
getfacl /smbshare
# 为smbuser4设置读写ACL
setfacl -m smbuser4:rwx /smbshare/

尝试写发现写被拒绝，修改SELinux策略：

# 检查smb权限
getsebool -a | grep smb
# 设置写权限
setsebool smbd_anon_write on
# 永久生效
setsebool -P smbd_anon_write on

多用户挂载
- 切换student写被拒绝，添加model权限：chmod o+w /smbshare/，我们发现student创建的属主文件也是smbuser4（即文件属于挂载用户）；
- 在server4上初始化实验环境lab smbmultiuser setup；
- 可以看到实验创建了/smbshare协作目录drwxrwsr-x.，并新增了两个账号brain:1001:1001(marketing)和rob:1002:1002
- 在desktop4上初始化实验环境lab smbmultiuser setup；
- 安装cifs：yum install -y cifs-utils；
- 创建认证文件vim /root/multiuser：
```
username=brain
password=redhat
```
- 配置永久挂载vim /etc/fstab：
```
//server4/smbshare /mnt/multiuser cifs defaults,_netdev,multiuser,credentials=/root/multiuser 0 0
```
- 测试切换briansu - brian：
```
# 创建文件被拒绝
touch /mnt/multiuser/testfile
# 用户名密码认证
cifscreds add server4
# 具有读写权限
touch test
```
- 测试切换robsu - rob：
```
# 创建文件被拒绝
touch /mnt/multiuser/testfile
# 用户名密码认证
cifscreds add server4
# 具有只读权限
touch test
```

2018-08-02

数据库

安装MariaDB：
- 在server4上安装服务端，以组安装比较方便：yum groups install MariaDB\ Database\ Server
- 使用yum history list查看安装历史，使用yum history info 2查看组中安装的包详情
- 使用rpm -ql mariadb-server | grep .service查看安装的服务；
- 启动服务：
```
systemctl enable mariadb.service
systemctl start mariadb.service
# 确认默认端口3306
netstat -tnlp
```
- 添加防火墙：
```
firewall-cmd --add-service=mysql
firewall-cmd --add-service=mysql --permanent
```
- 在desktop4上安装服务端，以组安装比较方便：yum groups install MariaDB\ Database\ Client
- 运行yum history list查看安装历史，运行yum history info 2查看组中安装的包详情
登录数据库
- 本地匿名登录，使用mysql客户端：mysql：
```
SHOW DATABASES;
USE mysql;
SHOW TABLES;
DESC user;
SELECT user, host, password FROM user;
```
- 运行安全脚本禁用匿名用户、远程登录等功能：mysql_secure_installation
- 使用密码本地登录：mysql -u root -predhat -h localhost，注意-p选项后接密码无空格；
```
USE mysql;
SELECT user, host, password FROM user;
```

配置：

vim /etc/my.cnf

# 默认配置指向套接字文件，供同一个电脑的进程间通信使用：
socket=/var/lib/mysql/mysql.sock
# bind-address，在所以配置文件中只允许一次，监听本地IP 172.25.0.11：
bind-address=172.25.0.11
# 禁用网络，仅使用本地套接字文件(以localhost连接会被自动转为本地套接字，而以server4连接则会被禁用)：
skip-network=1
# 修改配置使能够远程访问，需要指向

子配置位于ll /etc/my.cnf.d；
日志、数据文件、套接字等位于ll /var/lib/mysql；

SQL：

DDL数据定义语言：create, show, drop, alter等，对象为容器（如表、视图）；
DML数据管理语言：insert, delete, select, update等，对象为数据记录；

-- DDL与DML：
SHOW HELP;
-- %通配多位
SHOW TABLES FROM mysql LIKE '%zone%';
-- _通配一位
SHOW TABLES FROM mysql LIKE '_i%';
-- 创建库
CREATE DATABASE inventory;
USE inventory;
-- 创建表
CREATE TABLE regions (
    region_id int(8),
    region_name varchar(20),
    country_name varchar(20)
);
-- 查看表结构
DESC regions;
-- 插入记录
INSERT INTO regions values (1, 'Asia', 'China');
INSERT INTO regions(region_id, country_name) value ('Asia', 'Japan');
UPDATE regions SET country_name='CN' WHERE region_id=1;

DCL数据控制语言：grant, revoke等；

-- 新建用户
CREATE USER 'yinhe'@'desktop4.example.com' identified by 'redhat';
-- 若使用主机名登录有问题，可以尝试使用IP地址登录
CREATE USER 'yinhe'@'172.25.4.10' identified by 'redhat';
-- 授予权限
GRANT SELECT, UPDATE, DELETE, INSERT ON inventory.regions TO 'yinhe'@'desktop4.example.com';
-- 刷新内存，赋权后建议刷新
flush privileges;
-- 回收权限
REVOKE UPDATE, INSERT, DELETE ON inventory.regions FROM 'yinhe'@'desktop4.example.com';
-- 查看用户权限
SHOW GRANTS FOR 'yinhe'@desktop4.example.com'
-- 用户授权支持SQL用通配符
mobius@'localhost'
mobius@'192.168.1.5'
mobius@'192.168.1.%'

数据备份
- 按业务分为冷备（所有业务下线）、温备（业务只读）、热备（所有业务在线）；
- 备份方式分为逻辑备份（通过SQL导出记录，可以不下线，低效、高可移植）、物理备份（复制数据目录，如/var/lib/mysql，需要下线，高效、低可移植）；
- 逻辑备份：
```
# 备份
mysqldump -uroot -predhat inventory > ~/dump.out
# 还原
mysql -uroot -predhat abc < /root/dump.out
```
- 物理备份：mysqlhotcopy是mysql提供的冷/温备工具，或直接给逻辑卷做快照（lvm snapshots，cow写前复制，所以建议数据文件规划在逻辑卷上）；

网页服务

安装yum install -y httpd：
- 查看配置文件rpm -qc httpd；
- 日志默认存放在/var/log/httpd（同时也会写入系统日志/var/log/message）；
- 内容默认存放在/var/www/html；
- httpd的详细帮助文档，安装yum install -y httpd-manual；

实验，使用/srv/www4.example.com/www/为www4.example.com提供内容，使用/srv/default/www/为其他域名提供内容：

SELinux策略已经为/srv/*/www目录授予权限，若遇到403，使用restorecon -vvvR /srv/（v越多显示的过程越详细），使用ll -RZ /srv/查看，发现SELinux已重置为httpd_sys_content_t；
虚拟主机配置可以参考/usr/share/doc/httpd-2.4.6/httpd-vhosts.conf，复制到/etc/httpd/conf.d/下，分屏编辑vim -o {default,www4}.conf；
default配置：

<VirtualHost *:80>
    DocumentRoot "/srv/default/www/"
</VirtualHost>
<Directory "/srv/default/www/">
    AllowOverride None
    Require all granted
</Directory>

www4配置：

<VirtualHost *:80>
    DocumentRoot "/srv/www4.example.com/www/"
    ServerName www4.example.com
    ServerAlias www4
</VirtualHost>
<Directory "/srv/www4.example.com/www/">
    AllowOverride None
    Require all granted
    # Allow,Deny是老版本的访问控制命令，Require是新版本的命令
    # Order allow,deny
    # Allow from all
    # Deny from 172.25.4.10
    # 多条Require放入Require容器：<RequireAny>、<RequireAl>
    # <RequireAny>
    #     Require all granted
    #     Require not ip 172.25.0.10
    # </RequireAny>
</Directory>

若有欢迎页面，重命名掉/etc/httpd/conf.d/welcome.conf，注释掉主配置Options Indexes FollowSymLinks；

实验，https（TLS）配置：

生成秘钥对：openssl genrsa 1024 > /root/pair.key；
生成新签名请求：openssl req -new -key /root/pair.key -out /root/server.csr；
安装SSL支持：yum install mod_ssl.x86_64，查看安装文件rpm -ql mod_ssl，主配置文件为/etc/httpd/conf.d/ssl.conf；
添加防火墙：

firewall-cmd --add-service=https
firewall-cmd --add-service=https --permanent

备份配置mv /etc/httpd/conf.d/ssl.conf{,.bak}

Listen 443 https
<VirtualHost *:443>
    SSLEngine on
    SSLProtocol all -SSLv2 -SSLv3
    SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5
    SSLHonorCipherOrder on
    ServerName www4.example.com
    DocumentRoot /srv/ssl/www/
    SSLCertificateFile
    SSLCertificateKeyFile
    SSLCACertificateFile /etc/pki/tls/certs/ca.crt
    <Directory "/srv/ssl/www/">
        Require all granted
    </Directory>
</VirtualHost>

重启服务：systemctl restart httpd.server；

实验，部署python网络应用：

安装wsgi插件：yum install -y mod_wsgi.x86_64；
修改webapp.wsgi的SELinux标签：

# 永久改标签
semanage fcontext -a -t "httpd_sys_content_t" "/srv/wsgi/www(/.*)?"
# 刷新标签
restorecon -vvvR /srv/wsgi/www/

修改端口的SELinux标签：

# 查看9981端口标签
semanage port -l | grep 9981
# 查看一般网页端口的标签
semanage port -l | grep 80
# 永久改标签
semanage port -a -t http_port_t -p tcp 9981

修改vim wsgi.conf：

Listen 9981
<VirtualHost *:9981>
    DocumentRoot "/srv/wsgi/www/"
    ServerName webapp4.example.com
    WSGIScriptAlias / /srv/wsgi/www/webapp.wsgi
</VirtualHost>
<Directory "/srv/wsgi/www/">
    AllowOverride None
    Require all granted
</Directory>

添加防火墙：

firewall-cmd --add-port=9981/tcp
firewall-cmd --add-port=9981/tcp --permanent

2018-08-03

Shell脚本

脚本文件首行可以写入魔术字：#!/usr/bin/bash，用于指定脚本执行的程序；

使用常量创建用户：

创建用户：

echo "adding user1"
useradd user1 & > /dev/null
echo "setting password for user1"
echo "redhat" | passwd --stdin user1

执行脚本：

# 将脚本读入bash子进程执行，ps j能够看到多一个bash子进程
bash createusers
# 将脚本读入当前进程运行执行
source createusers
# .等效于source
. createusers
# 直接运行
chmod a+x createusers
/root/createusers
./createusers

which路径查找的顺序：alias、hash、$PATH中具有x权限的文件，设置别名：alias cdnet='cd /etc/sysconfig/network-scripts/'；
- which默认查找PATH，找到立刻返回，which -a表示查找PATH中的所有路径；
- whereis也是路径查找，包man手册；whatis专用于查找man手册，匹配名称，man -k还匹配摘要内容；
$用于变量调用，其他如*, @, #等特殊符号参见man 1 bash中“Special Parameters”；
- 设置环境变量：export user=user2；
- 变量默认以字符存储，使用[]转换数字：
```
a=1
b=2
echo $[$a+$b]
```
- 使用let数字赋值：
```
let c=$a+$b
echo $c
```
- 算数表达式：
```
echo $[1+1*2]
echo $[(1+1)*2]
```
退出码0表示正常，非0值各程序定义不同，使用exit 255表示退出码；
条件判断：
- 数字比较：[ "$a" -eq "$b" ] && echo true || echo false，注意：中括号前后有空格；
- 字符串比较：[ "$a" == "$b" ] && echo true || echo false，注意：中括号前后有空格；
- 文件相关信息的条件判断参见man 1 bash的“Conditional Expressions”；
- 判断语句if，参见help if：
```
if xxx ; 
    then ... ;
elif ... ;
    then ... ;
else ... ;
fi
```
- 判断语句case，参见help case，实验：
```
#!/bin/bash
case $* in
    redhat)
        echo fedora ;;
    fedora)
        echo redhat ;;
    *)
        echo "/root/foo.sh redhat|fedora"
esac
```
- 添加运行权限chmod a+x foo.sh

循环语句：

for语句：

for in {1..100};
    do echo $i; 
done

判断PC是否在线：

#!/bin/bash
for i in {1..20}
    do ping -c1 172.25.254.$i > /dev/null
    if [ $? -eq 0 ] 
        then echo pc${i}:online
        let sumon++
    else
        echo pc${i}:online
        let sumoff++
    if
done

while语句：

while: xxx
    do ...;
done

表格处理：grep w /etc/passwd | cut -d: -f 1,7；
实验，用到的文件newusers每行形为Cassy:Rundle:60:1：

#!/bin/bash
if [ $# -ne 1 ]
then
    echo 'Usage: /root/batchusers filename'
    exit 256
elif [ -f $1 ]
then
    for username in `cut -d: -f1 $1`
    do
        echo $username
        useradd -s /bin/false $username
    done
else
    echo 'input file not found'
    exit 128
fi

Redhat Linux初体验（1） Redhat Linux初体验（2）

结语

特别感谢李老师在授课之余，带我刷猪肘饭和骨汤面；
感谢成都天气控制部门一直将盛夏的气温保持在25℃左右，湿度也刚刚好，我现在知道成都妹纸为啥皮肤好了[捂脸]；
感谢金开服务公寓的免费撸铁房；
感谢东哥拐我来成都培训[捂脸]。
特此批评西安的天气控制部门，连续的40℃还说自己是啥线城市？

Redhat Linux初体验（2）

Sat, 28 Jul 2018 11:22:47 GMT

这三周都被拐卖到成都培训RHCE，讲真，还是当学生好啊~哈哈哈~把学习笔记搬上来，关键时刻能做个速查~

献上第二周的笔记。

2018-07-23

日志

syslog是老日志系统（文件型）、journal是新日志系统（内存型，可以配置保持硬盘，持久化）；日志默认保存在/var/log下；
- 除了认证、邮件、周期性作业、纯调试相关日志等类型，大多数日志都保存在/var/log/messages；
- 启动日志保存在/var/log/boot.log，成功登录日志保存在/var/log/utmp和/var/log/wtmp，对应last；失败登录保存在/var/log/btmp，对应lastb；
syslog日志系统包含很多设备，如：
- 认证设备：LOG_AUTH，放在/var/log/secure中；
- 邮件设备：LOG_MAIL，放在/var/log/maillog中；
- 周期性作业：LOG_CRON，放在/var/log/cron中；
- 详见man 3 syslog；
syslog日志系统分优先级，详见man 3 syslog；
syslog日志配置详见man 5 rsyslog.conf；日志系统采用异步I/O，以提高硬盘性能；
/etc/rsyslog.conf为syslog的主配置文件，通常，我们通过在/etc/rsyslog.d中新建.conf结尾的文件来配置日志，如：
- 新建/etc/rsyslog.d/debug.conf，新增一行*.debug /var/log/messages-debug；
- 重启服务：systemctl restart rsyslog.service；
- 跟踪日志文件：tail -f /var/log/messages-debug；
- 产生日志信息：logger -p user.debug "Debug Message Test"；
rsyslog中r代表remote，所以可以将日子保存在远程主机上，在man 5 rsyslog.conf中有详细信息，支持包括SNMP、MYSQL等模块在内的远程传输；
使用journalctl查看journal的日志，详见man 5 journalctl，常用的功能有：
- -n显示最近的日志；
- -p显示小于等于指定级别的日志；
- _PID=显示指定进程的日志；（双击TAB自动补全现实）
- _UID=显示指定用户的日志；
- --since 09:30:00显示指定时间后的日志；
- --until 10:00:00显示指定时间前的日志；
- _SYSTEMD_UNIT=sshd.service显示指定服务的日志；
配置journal，详见man 5 journald.conf，配置文件为/etc/systemd/journald.conf：
- journal持久化日志默认保存在/var/log/journal，新建该目录mkdir /var/log/journal；
- journal的各组件的内置用户均属于systemd-journal用户组（grep journal /etc/group），因此，/var/log/journal应配置为协作目录：先更改目录属组chown root:systemd-journal /var/log/journal，再添加协作权限chmod 2755 /var/log/journal，
- 重启进程killall -USR1 systemd-journald；

系统时间

硬件时间hwclock，对应cmos(bios|uefi)中的一个硬件，因为主板工艺在关机后存在计时差异；
软件时间在开机时复制硬件时间，软件时间可以手动调整，可以自动同步（网络的时钟服务器），软件时间可以将时间再写入硬件时间；
timedatectl红帽新提供的新工具，时间同步服务在systemctl status chronyd.service中，配置文件在/etc/chronyd.conf中；
修改/etc/chronyd.conf的服务器为教学环境的授时服务器后，重启服务systemctl restart chronyd.service，再timedatectl查看发现NTP synchronized为yes；
很多分布式软件均需要保持精确的系统时间；

网络

旧命令netstat，网络状态统计：
- -t查看tcp链接，-u查看udp链接；
- -n用数字表示（不解析域名）；
- -l监听状态的端口（开放端口，/etc/service中可以看到端口对应信息）；
- -p查看哪个个程序调用信息
新命令ss，套接字统计，与netstat基本用法一样；
旧命令ifconfig，不推荐使用；旧命令ip：查看三层：ip addr；查看二层ip link；添加地址ip addr add 172.25.0.22/24 dev eth0（重启后无效，需要改配置文件）；
新命令nmcli（命令行）或nmtui（字符图形化），旧命令仅能当前生效，并不能永久生效（需要改配置文件），新命令直接永久生效；
- 新命令systemctl status network是提供后台网络功能的服务，systemctl status NetworkManager是后台维护网络配置的服务，配置文件在/etc/sysconfig/network-scripts/ifcfg-接口，前台提供配置的工具有：
- nmcli device status查看设备概要信息，nmcli device shwo查看设备详细信息；
- nmcli connection show "System eth0"，查看链接详细信息；
- 新建链接：nmcli connection add con-name home ifname eth0 type ethernet（此时多一个/etc/sysconfig/network-scripts/ifcfg-home文件）；
- 配置自动连接的静态IPnmcli connection add con-name work autoconnect yes ifname eth0 type ethernet ip4 172.24.4.11/24 gw4 172.24.4.254(此时多一个/etc/sysconfig/network-scripts/ifcfg-work文件；
- nmcli delect work删除链接
- nmcli connection modify work ipv4.addresses 172.25.0.23/24添加IP地址；
- 修改地址获取方式nmcli connection modify home ipv4.method manual ipv4.address 172.25.0.23/24；
- nmcli connection show --active查看生效链接;
- nmcli connection up "work"使配置work生效；
- show命令时，大写是生效的配置，小小是配置文件中未生效的配置；
旧命令hostname，仅查看，配置需要改/etc/hosts；
新命令hostnamectl，新工具直接永久生效；
- dns查找顺序：/etc/hosts->buffer->/etc/resolv.conf
- hostnamectl set-hostname server.example.com设置主机映射；
- 配置存放在/etc/hostname；

2018-07-24

软件安装

rpm复制后端安装编译等工作，yum负责用户交互及解决依赖关系，是rpm的前段工具；
rpm常用命令：
- man 8 rpm查看rpm数据库等帮助信息；
- rpm -qa | wc -l统计已安装个数；
- rpm -q xxx查询已安装包名；
- rpm -qi xxx查询已安装包详细信息；
- rpm -ql xxx查看包在安装时具体安装了哪些文件；rpm -qc xxx查看配置文件；rpm -qd xxx查看文档文件；rpm -qf filename查看指定文件属于哪个程序；
- 已安装的包在rpm数据库/var/lib/rpm中；rpm -qpi xxx命令也可以看到未安装包，同样的rpm -qpl/qpc/qpd命令可以看到该包的所有文件、配置文件、文档文件；
- rpm -qR xxx查询依赖；
建立本地yum仓库（redhat和centOS有mini/everything等版本，而epel的包比everything还多，通常用于自建仓库）：
- /etc/yum.conf是yum的配置文件，/etc/yum.repos.d是yum仓库的配置目录；
- 下载rhel.xxx.iso，在linux下.iso是个文件系统，需要挂载：mount xxx.iso /mnt；（通过file xxx.iso可以显示文件系统详情）
- 在/etc/yum.repos.d下新建dvd.repo，写入：
```
# 必须且应保证主机上唯一
[dvd]                 
# 非必须
name = dvd            
# 必须
baseurl = file:///mnt 
# 开启本仓库
enable = 1            
# 是否需要校验，通常官方光盘不需要
gpgcheck = 0          
```
- yum repolist查看仓库信息，多了一个我们新建的dvd；
- repolist读取的仓库信息缓存在/var/cache/yum下；
- yum自动添加仓库：
```
yum -config-manager --add-repo=http://classroom.example.com/content/rhel7.0/x86_64/dvd
```
- 新建的仓库名称很长，还需要手动添加gpgcheck=0，推荐使用前一种方法；
- yum -config-manager --enable/disable可以用来禁用/启用仓库，仓库全名使用yum repolist列出；
yum常用命令：
- yum list列出所有软件，按名字查找使用yum list xxx（软件名完全匹配）可以使用通配符，如yum list http*；
- yum search搜索软件，匹配包括简介信息；
- yum info tcpdump查看软件详细信息；
- yum group install以组为单位进行安装；
- yum history显示yum历史操作汇总信息，加list命令查看详细信息，再使用list中的ID可以附加undo和redo等命令进行撤销或重做操作；
- yum erase删除；
- yum provide查询提供指定命令、文件的软件包；

文件系统

Linux仅允许一个主文进系统，一个根目录/（入口），其他文件系统需要挂载在主文进系统之下，统一从根目录/进入；（Windows允许多个跟目录，通过盘符区分），参见man 8 mount；
上一节中的挂载：mount xxx.iso /mnt，卸载：umount /mnt；
df -h查看文件系统详细信息，du filename查看文件占硬盘大小，du -s dirname查看目录占用硬盘大小；
blkid查看块设备的属性；
临时挂载、卸载使用mount、umount；
- 对于无法直接卸载的目录，使用lsof /xxx或fuser /xxx查看哪个用户哪个进程在使用，结束该进程后就可以卸载；
永久挂载，配置/etc/fstab：
- 使用/xxx/xxx.iso /mnt iso9660 defaults 0 0挂载一个永久文件系统；
- 意为挂载xxx.iso文件；
- 挂载点为/mnt；
- 文件系统类型为iso9660（这个信息可以使用mount xxx.iso /mnt临时挂载文件后使用mount命令查看到）；
- defaults为默认选项（rw, suid, dev, exec, auto, nouser, async）；
- 0为dump选项，不允许转存；
- 0为非启动文件系统且不需要检查；
硬链接ln：
- Linux硬盘管理一个扇区的最小单位为4k，使用mkfs格式化分区时，系统会将扇区分为存储inode或存储block；
- inode，即文件索引，存储文件元数据，通过ll -i xxx查看到除文件名以外的信息全部是存储在inode中的，权限后的数字即block被连接的次数，使用stat xxx查看元信息，其中Modify是block修改时间，Change是元数据修改时间；
- block，存储文件内容；
- 使用ln xxx yyy后，通过ll -i xxx yyy发现两个文件的inode值相同，即硬链接只复制了元数据；
- 硬链接不依赖原文件，修改一处另一处也修改，一个block中的文件仅有一个inode值；
- 硬链接删除操作删除的是inode连接，只有当连接数为0时，才删除文件回收block；
- 硬链接不能跨文件系统，因为inode有可能冲突；
- 硬链接不能对目录使用；
- 另外，空目录连接次数为2，除了自己以外，还有.连接了它；如果有子目录，则连接数继续+1，即被子目录的..连接；
软链接ln -s，相当于Windows的快捷方式：
- 软链接是指向源文件的路径名（硬链接指向原文件的block，即复制inode，软链接的大小刚好是目标文件的路径长度），因此，软链接的源一定要使用绝对路径；
- 软链接可以跨文件系统，因为是路径；
- 软链接可以对目录使用；
- 软链接的原文件必须存在，如果原文件被删除，则软链接失效；
文件查找locate：
- 基于文件名进行模糊查找；
- 维护一个inode与文件名的映射，存在数据库/var/lib/mlocate/mlocate.db中，该数据库默认一天更新一次，即新建的文件不会存在于数据库中，也就找不到；
- 使用updatedb更新数据库；
- 不会查找/tmp中的任何文件；
- 不能定义在那个目录中去找；
文件查找find：
- 实时查找，可以基于文件的任何元属性进行查找，如文件名、修改日期、访问时间等；
- -amin n最近n分钟被访问的文件，其中-n为n分钟以内、+n为n分钟以外；
- -anewer file找出所有访问时间比file大的文件；
- 命令包含time的单位为天；
- -empty查找空文件；
- -links n查找硬链接次数超过n的文件；
- find后可以接动作，如删除动作find . -empty -delete；
- find / -perm -2000查找的是特殊权限2，仅查找四位权限码第一位；
- find / -perm /7000查找的是所有特殊权限；
- find / -nouser查找失去用户的文件（不安全，因为下其他用户有可能占用该inode，造成权限漏洞）；
- find /var -user root -a -group wheel，其中-a可以省略，默认and，也可以用-o；
- find /var -size -5k -exec ls -dlh '{}' \;，表示小于等于4k的文件；
- find /root -size -6M -a -type f -exec tar cvzfP /tmp/5m.tar.gz '{}' \;，将/root下所以小于6M的文件查找并打包放在/tmp下；

2018-07-25

系统批量部署

安装kvm虚拟机时，对于Intel的CPU，支持vmx的CPU可以进行硬件虚拟化，需要在BIOS中保证开启vmx及nx；
Kickstart批量部署：
- %pre安装软件包前的脚本；
- %package安装软件包；
- %post安装软件包后的脚本；
- %end脚本结束标记；
使用virt-manager管理虚拟机：
- 将server重启，使用F12后^B中断正常启动，选择iPXE
- 输入gPXE> autoboot执行PXE启动；
- 将ks=http://172.25.4.10/ks-config/ks.cfg输入到行尾（行尾为... quit）；
- 实验完成后，使用rht-vmctl fullreset server将虚拟机完全重置；

正则表达式

grep为全局（对文件）正则表达式搜索，egrep为使用扩展正则表达式搜索，扩展的更强大，fgrep为固定格式搜索（即不使用正则表达式，更快）；
注意：
- \<词首、\>词尾，等同于\b；
- 正则表达式也可以使用[[:digit:]]代替[0-9]，[^]取反，参考man 7 glob和man 7 regex；
- 正则表达式的测试可以使用/usr/share/dict/words；
- wc -l可以统计行数；
- ()表示当做整体，通常在扩展正则表达式中使用，非扩展的需要转移括号；
- -v表示取反，即显示不匹配的行；-i不区分大小写；-A n匹配行后显示n行，-B n匹配行前显示n行，-C m, -n匹配行前显示m行后显示n行，

计划任务

at适合定时执行仅一次的任务：
- 使用at计划任务前，使用systemctl start atd启动at后台服务；
- at是atd的前端工具，使用^d提交；
- atq是监控任务的工具；
- atrm删除任务；
- 对于某些用户，不希望他执行at任务，可以将其用户名写入/etc/at.deny；
- 对于某些用户，希望他执行at任务，可以将其用户名写入/etc/at.allow；at命令先查找allow，若没找到则继续在deny中查找，若仍未找到，则允许执行（默认允许）；
cron适合周期性执行的任务：
- cron是crond的前端工具；
- cron分为用户cron（如数据备份）和系统cron（如locate命令使用的数据库更新）；
- crontab是用户cron的前端工具，系统cron在/etc/crontab中，
- cron的deny/allow和at的行为一样；
- 通过crontab -e编辑当前用户的计划任务，写入9-11/2 * * * * mktemp /tmp/XXXX表示每个小时的第9到11分钟步长为2的执行作业，即9、11分钟各执行一次；
- crontab -l列出当前用户的计划任务；
- crontab -r删除当前用户的计划任务；
- 系统cron在/etc/cron.d中，0hourly存储立即执行的任务，raid-check存储阵列检查相关任务，sysstat存储系统状态相关任务；
- 其他文件夹如.daily、.hourly等文件夹存放按日、按小时执行的作业；

进程优先级

优先级高的进程能够获得更多CPU资源：
- TOP的PR和NI字段，即系统优先级和用户配置优先级；
- 优先级取值为-100~39，系统优先级为-100~-1，用户优先级为0~39；
- NI取值为-20~19；
- PR值为rt的表示用户无法调整的（PR没有小于0的，小于0即显示rt）；
- PR-NI=20
nice后接命令调整该命令的优先级，如nice --20 dd if=/dev/zero of=/dev/null（-代表省略的选项-n）
renice后接进程PID可以重新调整该进程优先级；，如renice -5 12336；
top命令也可以调整优先级，使用r命令再输入PID，确认后输入优先级值即可；

权限访问控制列表（权限ACL）

ACL控制粒度比POSIX的文件权限控制model更细；
在ll显示的文件权限中如-rwx-r-x-r-x.，其中的.即表示未添加访问控制；
使用getfacl xxx查看权限细节
使用setfacl给文件设置ACL权限：
- setfacl -m group::r xxx（修改权限为r--），setfacl -x group::- xxx（删除权限为---），即也可以用于给文件设置model权限；
- 比如对于-rw-------. root root的文件，user是不能读取的，因为user在model权限中匹配的是最后三位---（既不是root用户也不是用户组的其他权限），此时无法通过用户和组的model来设置文件权限；
- 具体设置方法参见man 1 setfacl；
- 如setfacl -m user:r xxx给user用户添加ACL读权限、setfacl -m user:rw xxx给user用户ACL添加读写权限、setfacl -m m::r修改ACL掩码将user权限改为读、set -x user xxx删除用户ACL权限
- setfacl -m g:user:rw xxx给组添加权限，setfacl -x g:user xxx给组删除权限；
- setfacl -b xxx删除所有ACL权限；
- setfacl -m user:rwx xdir给目录添加rwx权限，若想要该目录下的所以新建文件均具有ACL权限，则应写为setfacl -m d:user:rwx xdir；需要注意的是d参数对目标目录无效，仅对目标目录下的子文件及子目录生效，要修改目标目录的ACL，仍应使用没有d的命令，即setfacl -m user:rwx xdir；

2018-07-26

SELinux

model模型的权限控制针对用户和文件，而SELinux针对程序和文件，SELinux是为了**避免人为错误（配置错误）**而设计的；
SELinux对程序的标签可以用ps uZ 7842显示出来，对文件的标签可以用ll -dZ /tmp显示出来；
举例：
- httpd的标签为system_u:system_r:httpd_t:s0；
- /tmp的标签为system_u:object_r:tmp_t:s0；
- /var/www/html的标签为system_u:object_r:httpd_sys_content_t:s0；
安装setools-console可以查看SELinux规定的进程对目录做的操作：sesearch -A -s httpd_t -t tmp_t，可以看到allow httpd_t tmp_t : dir开头的两条记录，其中权限大的一条为Permissive模式（临时关闭SELinux）下的权限，权限小的一条为Enforce模式下的权限（即正常的SELinux开启时，可以通过getenforce目录查看）；
SELinux的开机启动配置在/etc/selinux/config中，要关闭SELinux应配置为SELinux=disabled，使配置生效需要重启；
在关闭SELinux后，用-Z选项查看新建的文件是没有SELinux标签的，在关闭SELinux后新建（或修改并保存）文件，会在该目录下生成一个名为.autorelabel的文件，意味着当再次开启SELinux并启动系统时，系统会再次打标签，系统会自动在打标签后再次重启；
setenforce可以临时修改模式，通常供调试时使用；
semanage管理SELinux策略：
- 其中fcontext子命令管理文件上下文标签；
- semanage fcontext -l | grep admin_home_t列出标签为admin_home_t的条目，其中默认条目/root(/.*)?只能改不能删；
- semanage fcontext -a -t admin_home_t /var/www/html/(/.*)，将/var/www/html下所有文件改为admin_home_t标签；
- restorecon -vR /var/www/html/，递归的重置标签，包括目录本身及子目录
- semanage fcontext -a -t admin_home_t '/var/www/html/(/.*)?'，修改包括/var/www/html本身及子目录；
- semanage boolean -l | grep ftpd查看ftp相关功能设置（getsebool查看的是内存中的运行时配置）；
- 开启FTP匿名上产需要修改semanage bool --modify --on ftpd_anon_write，semanage boolean --modify --on ftp_home_dir，chomd o+w .，chcon -t public_content_rw_t .等很多策略，因为SELinux默认认为FTP匿名上传行为不安全；其中setsebool不加-P用于临时修改标签，-P用于永久修改标签；若要排查问题可参考系统日志tail -n 50 /var/log/message；
SELinux的默认配置已经能够很好的运行，通常不需要重新配置，除非确定需要的功能确实是因为SELinux安全策略引起的，再进行修改，推荐始终打开SELinux功能以提高系统安全性；

网络用户

安装yum install authconfig-gtk.x86_64，使用authconfig-gtk设置用户类型，
- 选择LDAP，LDAP搜索基DN为dc=example,dc=com（范围小的写前面）LDAP sever为classroom.example.com；
- 选择TLS加密连接，在CA证书中写证书地址即可；
- 认证模式为Kerberos密码认证，Realm为EXAMPLE.COM，KDCs和管理服务器均为classroom.example.com，下面两个DNS解析主机及DNC定位KDCs不选；应用配置
- 使用getent passwd发现新加了ldapuser*账号，使用ssh ldapuser4@localhost测试登录，默认密码为kerberos；
- 使用getent passwd ldapuser0查看网络用户条目（也可以查看本地用户，如getent passwd root）
autofs按需挂载（mount必须是root用户，且为永久挂载）：
- 安装yum install -y autofs.x86_64，查看rpm -ql autofs | grep .service发现有autofs有service；帮助参见man auto.master；
- 开机运行并启动：systemctl enable autofs.service && systemctl start autofs.service；
- 编辑/etc/auto.master，添加一行/home/guests /etc/auto.ldap
- 新建并编辑/etc/auto.ldap（参考auto.misc，使用:sp /etc/auto.master或vim -o /etc/auto.{ldap,misc}分屏对照编辑更方便）：
```
# *与&是一对内容对应的占位符
* -fstype=nfs,rw,sync classroom.example.com:/home/huests/&
# 若要指定用户及目录应写为
ldapuser4 -fstype=nfs,rw,sync classroom.example.com:/home/huests/ldapuser4
```
- 此时在使用ssh ldapuser4@localhost登录即可按需挂载ldapuser4的home目录

分区及格式化

MBR分区（即微软的DOS），硬盘的的第一分区（盘面最外面）为MBR分区，存储主引导记录（如Linux的grub2.0 448字节）和分区表（64字节，其中，一条分区记录要占用16字节，即最多只能分四个主分区），通常最后一个分区作为扩展分区，用来做逻辑分区，而逻辑分区表不再MBR中，因此没有限制（MBR最大支持2T的硬盘）：
```
mbr
├── P1
├── P2
├── P3
└── extend(4)
      ├── L5
      ├── L6
      ├── L7
      ├── L8
      ├── L9
      ├── L10
      └── L11
```
lsblk查看硬盘分区，-p显示完全路径，fdisk -l列出分区信息，分区完成后，使用partprobe通知系统重新读取分区表：
- fdisk /dev/vdb开始分区；
- fdisk对MBR支持更好；
GPT分区（GUID Partition Table），LBA0为保护MBR区，LBA1为主GPT头，LBA2-34的每个LBA存四个条目，共128个条目；
- gdisk对GPT支持更好
上面仅是分区，现在的分区系统还不能使用，需要格式化，给每个分区分配UUID，使用blkid查看；
- mkfs格式化为文件系统用，mkfs /dev/vdb1；
- 临时挂载mount /dev/vdb1 /mnt；
- 重挂mount -o remount,ro,nosuid /mnt，即设备不断线仅改变参数；
- 永久挂载配置/etc/fstab（man 5 fstab查看挂载及文件系统信息），使用blkid查看UUID，写入配置：
```
# 硬盘
UUID=xxx /mnt xfs  default 0 0
# 虚拟内存
UUID=xxx swap swap default 0 0
```
- 使用df -h或fdisk -l查看硬盘挂载结果；
- mkswap格式化为虚拟内存用，挂载/写在虚拟内存swapon /dev/vdb5、swapoff /dev/vdb5；
- 使用top或free查看Swap内存挂载结果；
分区必须是连续的存储空间，而卷没有这种要求：
- 分区不能跨硬盘，而卷可以；
- 分区不能动态扩展，而卷可以；
- 逻辑卷可以做快照；
- 物理分区->pv（物理卷）->vg（卷组）->lv（逻辑卷，当做逻辑卷或虚拟硬盘）->mkfs->mount
创建物理卷pvcreate /dev/vdb7 /dev/vdc5：
- pvs或pvscan查看概要，
- pvdisplay /dev/vdb7查看详情；
- -s指定PE（PhysicalExtent）大小（默认4M）；
创建卷组vgcreate vg0 /dev/vdb7 /dev/vdc5
- vgs查看卷组；
- vgremove vg0删除卷组
- vgcreate -s 8m vg0 /dev/vdb7 /dev/vdc5按8M指定PE大小
创建逻辑卷lvcreate -l 512 -n lv0 vg0
- lvs查看逻辑卷概要；
- -n 指定卷名
- -l 指定分配到PE个数；
- -L 指定分配的空间；
此时lsblk可以看到逻辑卷了，mkfs.xfs格式化mkfs.xfs /dev/vg0/lv0或mkfs.xfs /dev/mapper/vg0-lv0；
创建挂载点mkdir -p /lv/{lv0,lv1}，在vim /etc/fstab中的配置使挂载永久生效；
扩展逻辑卷：
- 扩展前vgs查看卷组的空闲，扩展使用lvextend -L +2G /dev/vg0/lv0，df -hT查看文件系统信息，而xfs支持自动识别增重的空间，使用xfs_growfs /dev/vg0/lv0；
- 若卷组空间不够，硬向卷组添加空间（插硬盘，分区并格式化）；
- 创建pvpvcreate /dev/vdc6 /dev/vdd5；
- 扩展vgvgextent vg0 /dev/vdc6 /dev/vdd5；
- 扩展lvlvextent -L +10G /dev/vg0/lv1，若为ext文件系统使用resize2fs /dev/vg0/lv1重新识别；

2018-07-27

启动排错

启动相关项位于/boot，vm开头的文件为内核文件，相关配置文件位于/etc/grub.d；
查看运行级别runlevel，共0~6七个运行级别，类似于Windows“安全模式、带网络的安全模式等”，不同的启动模式启动的功能不一样，正常启动模式为3和5：
- runlevel的返回值第一位为上次运行级别，第二位为本次运行级别；
- 0为关机，即什么都不启动；
- 1为单用户模式（root用户），即救援模式（类似Windows的安全模式）；
- 2/4，未定义，都认为是3模式；
- 3为正常命令行启动，不提供图形化界面；
- 5为正常图形化启动，提供图形化界面及命令行界面（ctl+alt+F2~6）
- 6位重启（先结束所有进程再启动）；
- 使用init n即可执行相应的运行级别，如init 6即重启；
- 以上是为了兼容Redhat 6，在7版本通常使用systemctl [target]
systemctl目标：
- systemctl poweroff或直接执行poweroff，查看poweroff可知/usr/sbin/poweroff -> ../bin/systemctl，即systemctl poweroff.target；
- reboot与上一条一样；
- 目标存放在/usr/lib/systemd/system，使用ll *.target查看，发现Redhat 7的目标更加细致；
- systemctl -t补全可以看到目标容器，将目标分为10类，类似分类服务，如查看vim NetworkManager.service中，有配置Wants=network.target表示NetworkManager服务应加入network目标容器；
- 临时切换目标systemctl isolate multi-user.target（3级别）、systemctl isolate graphical.target（5级别）；
- 查看默认目标systemctl get-default；
- 设置默认目标systemctl set-default multi-user.target；
- 刚启动时也可以设置目标，选择Linux版本时按e键，在linux16行行尾（物理机，虚拟机删到ro），输入systemd.unit=multi-user.target，按^x提交，系统启动就进入正常命令行模式了；

修复密码

openssl rand -hex 16产生16位随机数，以十六进制输出；
openssl rand -base64 16 | passwd --stdin root，此时不知道root密码了：
- 选择Linux版本时按e键，在虚拟机环境linux16删到ro，输入rd.break（打断正常启动），按^x提交，进入交换根（内存根目录）；
- 查看挂载情况mount | grep ^/，发现只读ro，重新挂载为读写mount -o remount,rw /sysroot
- 临时切换根目录chroot /sysroot，为了恢复环境（如补全等功能）；
- 查看ls -lZ /etc/shadow，在此模式下发现没有标签（即SELinux）
- echo 'redhat'| passwd --stdin root
- 通知SELinux重建标签touch /.autorelabel
- 退出临时根exit，退出中断exit，继续启动过程，SELinux启动会重新打标签，自动重启后正常；

修复文件系统

fstab的永久挂载信息有误：
- 选择Linux版本时按e键，在虚拟机环境linux16删到ro，输入systemd.unit=emergency.target（rescue也可以，打断正常启动），按^x提交，进入维护模式；
- 查看关注情况mount | grep ^/，发现只读ro，重新挂载为读写mount -o remount,rw /；
- 修改/etc/fstab，删除错误信息后reboot，系统正常；

启动引导程序故障

grub错误，启动Linux立刻报错：
- 个人电脑：设备断电，将硬盘换到正常设备，挂载并chroot；服务器：使用救援光盘（虚拟机用virt-manager挂载光驱并加载下载好的镜像）；
- 启动按esc进入启动项，选择光驱启动；
- 选择rescue xxx，选择continue；
- 临时切换根目录chroot /mnt/sysimage；
- vim /etc/grub2.cfg查看配置找出错误，或生成默认配置覆盖grub2-mkconfig > /etc/grub2.cfg；

控制服务及守护进程

守护进程可以在/usr/lib/systemd/system中通过ll -d *d.*大概查看；
使用systemctl控制守护进程及服务，也可以控制系统运行级别；
系统相关功能的启动及服务的启动都是通过systemd的system和service manager管理；
Redhat认为，守护进程是一直在后台执行的作业，服务是守护进程的集合；
进程ID为1的为systemd的进程，systemctl是systemd的前端命令行；
- systemctl查询所有单元；
- systemctl --type=service查看服务类单元；
- systemctl start|stop xxx.service临时启停服务；
- systemctl enable|disable xxx.service永久起停服务；
对于目标（target）：
- 其中的emergency初始化内核（/boot中vm开头）、初始化内存（/boot中initramfs开头）、初始化系统根目录（挂载到/并为只读挂载）；
- 其中的rescue模式为单用户，初始化基本的系统环境；
- multi-user模式提供字符接口；
- graphical模式提供字符及图形化接口；
- 目标可以包含其他目标，使用systemctl list-dependencies graphical.target查看目标间的依赖关系；

配置IPv6

回顾NetworkManager：
- 一个device就是一个网络接口；
- 一个连接就对应一个配置文件（连接是为设备做的）；
- 一个设备可以对应多个连接；同一个时刻一个设备只允许一个连接生效；
- 连接的永久配置在/etc/sysconfig/network-scripts/ifcfg-name；
- nmcli用来创建或编辑连接配置；
IPv6有128位，缩写为8组十六进制数字，每组的引导0可以省略，连续的0组可以省略一次，XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX；
- ::1/128 localhost，回环地址；
- :: 0.0.0.0，未分配；
- ::/0 0.0.0.0/0，匹配IPv4的所有IP地址；
- 2000::/3，全局单播地址；
- ffe0::/8，多播地址；
- fe80::/64，链路多播；
- fe80::/64，链路本地单播；
- fddb:fe2a:ab1e::c0a8:1/64
IPv6故障排查：
- ping6 fddb:fe2a:ab1e::c0a8:fe，IPv6的ping命令；
- tracepath6 fddb:fe2a:ab1e::c0a8:fe，追踪路由；
- traceroute -6 fddb:fe2a:ab1e::c0a8:fe，追踪路由的另一种写法；
- ip -6 route，IPv6的路由；
试验lab ipv6 setup：
- 先查看所有网卡配置ip a；
- 创建连接nmcli connection add con-name eno1 autoconnect yes ifname eno1 type ethernet；
- 配置连接，使下次重启生效nmcli connection modify eno1 ipv4.method manual ipv4.addresses "192.168.0.100/24 192.168.0.254" ipv6.method manual ipv6.addresses "fddb:fe2a:ab1e::c0a8:64/64 fddb:fe2a:ab1e::c0a8:fe"
- 是配置立即生效nmcli conncetion up eno1；
- 检查路由ip route和ip -6 route；
- ping测试ping -I eno1 192.168.0.254和ping6 -I eno1 fddb:fe2a:ab1e::c0a8:fe；
- 跟踪IPv6路由tracepath6 fddb:fe2a:ab1e::c0a8:fe或traceroute -6 fddb:fe2a:ab1e::c0a8:fe；

链路聚合与软件网桥

将多个物理网卡合并为一个逻辑网卡，做负载均衡、故障转移、增加吞吐量；
链路聚合lab teambridge setup；
- 先查看所有网卡配置ip a；
- 新建team0连接nmcli connection add con-name team0 autoconnect yes ifname team0 type team；
- 修改team0连接的运行法则nmcli connection modify team0 team.config '{"runner": {"name": "activebackup"}}'（运行法则参考man teamd.conf）；
- 查看的team0连接的运行法则是否配置正确nmcli connection show team0；
- 给team0连接添加物理接口：
```
nmcli connection add con-name team0-port1 autoconnect yes ifname eno1 type team-slave master team0
nmcli connection add con-name team0-port2 autoconnect yes ifname eno2 type team-slave master team0
```
- 查看添加的物理接口：nmcli connection show；
- 为team0连接配置IPv4：nmcli connection modify team0 ipv4.method manual ipv4.address "192.168.0.100/24 192.168.0.254"；
- 启动team0连接：nmcli connection up team0；
- 测试连接ping -I team0 192.168.0.254；
- 检查运行聚合连接team0的运行状态：teamdctl team0 state，可以看到只有一个接口处于活动状态，则另一个接口处于预备状态；
- 测试关闭物理接口：nmcli device disconnect eno1（旧命令ifdown eno1），备用接口立刻上线；
- 配置在/etc/sysconfig/network-scripts/ifcfg-team0、/etc/sysconfig/network-scripts/ifcfg-team0-port1、/etc/sysconfig/network-scripts/ifcfg-team0-port2中；
软件网桥常用于虚拟化平台，在物理机上brctl show查看：
- 先查看所有网卡配置ip a；
- 删除上一节的配置：
```
nmcli connection delete team0
nmcli connection delete team0-port1
nmcli connection delete team0-port2
```
- 新建br0网桥：；
- 给br0网桥添加物理接口：
```
nmcli connection add con-name br0-port1 autoconnect yes ifname eno1 type bridge=slave master br0
nmcli connection add con-name br0-port2 autoconnect yes ifname eno2 type bridge-slave master br0
```
- 给br0网桥配置IPv4：nmcli connection modify br0 ipv4.method manual ipv4.addresses "192.168.0.100/24 192.168.0.254"；
- 查看链接nmcli connection show；
- 启动端口：
```
nmcli connection up br0-port1
nmcli connection up br0-port2
```
- 测试连接：ping -I br0 192.168.0.254；
- 若连接不通，重启网络服务：systemctl restart network.service，若仍然不通，重启虚拟机；
nmcli的配置建议参考man 5 nmcli-example，范例丰富；

Redhat Linux初体验（1） Redhat Linux初体验（3）

Redhat Linux初体验（1）

Sat, 21 Jul 2018 11:22:47 GMT

这三周都被拐卖到成都培训RHCE，讲真，还是当学生好啊~哈哈哈~把学习笔记搬上来，关键时刻能做个速查~

献上第一周的笔记。

2018-07-16

Linux历史

Multics的产生
Unix的产生
BSD与GUN等开源软件的发展
Linux的发展与发行现状

教学环境简介

安装vnc以及使用vnc远程教师机器
红帽虚拟机使用管理：rht-vmctl [start|view|reset|stop]
红帽虚拟机配置管理：virt-manager
通过伪终端连接虚拟机：ssh student@desktop4

2018-07-17

常用基础命令

修改密码passwd的策略；
使用date修改、显示时间命令，以及命令行转义；
文件查看相关命令：file、wc、head、tail，文本编辑器nano；
使用history操作命令历史记录，使用!或^r快速逆向查找历史命令，使用esc+.或!$复制上条命令的参数，使用!!复现上一条命令；
命令行光标操作：光标移至行首^a、光标移至行尾^e、删除光标之前^u、删除光标之后^k、删除前一个参数^w、^l清屏、^Y恢复^u或^w擦除的命令、^\撤销操作；

文件操作

文件系统树形结构：/, /bin, /boot, /dev, /etc, /etc/opt, /etc/sgml, /etc/X11, /home, /lib, /media, /mnt, /opt, /proc, /root, /sbin, /srv, /tmp, /usr, /var的功能介绍；
文件系统路径，区分相对路径、绝对路径，使用cd -切换到上一次使用的路径下
新建文件：touch的本意是用来更新文件的时间戳，也用来新建文件；使用mkdir -p创建一系列路径；ls -R递归现实目录内容，类似tree；
删除文件：rmdir不常用，只能删除非空目录；rm常用，可删除文件或目录，-r选项可递归删除
修改文件：使用cp复制文件，-r递归复制，*通配复制（不可用于子目录）；使用mv移动文件，mv可用于重命名；
文件通配符：
- *匹配任意字符任意长度；
- ?匹配任意字符1长度；
- []匹配指定字符1长度；
- 使用touch file{start..stop..step}生成多个文件，类似python的range；
- ll -d ?????匹配5位长度的文件名，ll -d [abc]?????匹配abc开头后接5位的文件名，ll -d *[0-9]*匹配包含数字的文件名；
- ll [[::upper:]]*匹配大写字母开头的所有文件，具体匹配参见man 7 glob（不建议使用[A-Z]，在不同的字符集中A-Z之间的编码字符不一样）；字符集中^或!（如[!0-9]）表示取反；

2018-07-18

获取帮助

Unix帮助：使用man man查看man帮助格式（包括8个必选1个可选章节），使用man 章节数命令查看相应命令的详细帮助信息，使用man -k fd搜索所有fd相关帮助
使用ls --help、ls --info或help ls、info ls获取简要操作指南，
在man中使用-N CR命令显示行号
GNU帮助：使用info info查看info帮助各式，pinfo查看易读的info格式，若命令未提供info帮助，则info会将man帮助显示出来
man手册位于/usr/share/man，info手册位于/usr/share/info，第三方软件的帮助位于/usr/share/doc，使用rpm -ql httpd | grep /usr/share查看第三方软件httpd的帮助文件安装情况

文本文件

cat可以连接输出多个文件，head或tail则会将文件分开输出，cat -A输出换行/制表等控制字符；
使用more、less分屏显示文件，less功能更强大，man的输出默认调用less；
重定向，man stdin查看；/dev中的stdin/out/err均指向fd（文件描述符），ll -i std*发现输出最前多了一列index node，即文件索引节点，使用tty查看当前终端的文件描述符，echo hello1 1> /dev/pts/2可以在另一个终端上看到输出；
输入重定向：tr '[:lower:]' '[:upper:]' 0<.bashrc，将.bashrc的内容重定向到stdin传给tr进行大小写转换
输出重定向：>覆盖，>>追加
管道|，连接前一个命令的stdout到后一个命令的stdin；

vim

^u向上^d向下，ZZ保存退出，ZQ不保存退出；
插入模式、命令模式、可视模式（仅用于选择）；
v按字符选择、V按行选择、^v按块选择；
字符级移动hjkl，10j向后移动10行；0绝对行首，^非空行首，$（行尾）；
句级移动：(前一句，)后一句；
段级移动：{前一段，}后一段；
单词级移动：w下一个词首），e下一个词尾，b前一个词首；
使用#查找相同单词，可以使用n N在该单词的搜索结果中跳转；
d删除，d10w删除后十个单词，d10l删除后十个字符；c删除并插入；
dd删除行；S删除行并插入；
x删除字符；s删除字符并插入；
y复制；
p粘贴光标后，P粘贴光标前；
插入模式：i（插入光标前）a（插入光标后）I（行首插入）A（行尾插入）o（下行插入）O（上行插入）R（改写）；
.重复上一条命令；
命令行模式，set all查看所有命令，直接输数字回车移动到相应行（10CR），命令10G也可以；
命令行模式：10,15d（删除10-15行），.,+3d删除1+3行（.光标所在行，\$最后一行，%所有行）；
命令行模式：10,20s#nologin#login#（10到20行第一个nologin换login）；10,20s#n#N#gc（10到20行n换N，询问模式）；10,20s#n#A#gic（10到20行n换A忽略大小写，询问模式）；
命令行模式：r abc.txt（将abc.txt追加到光布行后面）o abc.txt（打开abc.txt）；
命令行模式：!（执行外部命令），r !hostname（将hostname的输出读入到光标下一行）；
命令行模式：first prev next last在多个打开的文件中切换；
u撤销，^r重复；
多文件打开vim -o a b c d多文件水平分屏，-O竖直分屏，使用^w在多屏间切换，命令行下split为水平分屏，hsplit为竖直分屏；

在root用户下，vi与vim是两个程序，vim更强大，语法高亮只有在特定位置自动渲染

2018-07-19

本地用户

uid 0 分配给root用户；uid 1-999 分配给应用程序，通常不用来登录计算机，为内置账号；uid > 1000 分配给普通用户
/etc/passwd存储用户配置；
- 使用useradd user1添加用户；
- 使用id user1现实uid（用户id）/gid（私有组）/group（附加组）信息；
- 使用useradd -u 8888 user2指定UID；使用useradd -d指定home目录，使用useradd -s指定shell；
- 使用passwd user1设置密码；
- 使用su - user1切换用户；
- 可以分配的shell在/etc/shells中；
普通用户均有home目录和登录程序（shell），
查看tail -n 2 /etc/{passwd,shadow,group,gshadow}：
- passwd保存用户信息；
- shadow保存用户密码信息；
- group保存组信息，新建用户时，若不指定，系统将用户分配至同名组，该组为私有组，gid分配方式与uid相同；微软使用公有组机制，比如Windows中新建用户统一加入users组；红帽使用私有组，部分Linux也使用公有组；用户除了自己的私有组，可以使用groupadd group1新建组，使用usermod -aG group1 user1给user1添加附加组group1（a写在前面，表示追加，若不写则会覆盖原来的附加组，G是要加参数的选项，放在后面）
- gshadow保存组密码信息；
管理用户（必须使用root权限）：
- 图形管理界面sudo system-config-users
- 命令行添加用户useradd，使用passwd设置密码；
- 命令行修改用户usermod，修改home目录时需使用-md（m移动home目录，放在d之前），home目录下默认文件均从/etc/skel复制而来；-L锁定用户，-U解锁用户；
- 命令行删除用户userdel，-r表示删除home目录
- sudo的权限写在/etc/sudoer，visudo是专门用于修改/etc/sudoer的程序，使用man 5 sudoers查看具体格式；
- chage -l user1查看用户密码相关易读的时间信息（上次密码更改日期、密码过期日期、账户过期时间等）；使用chage修改这些信息；
- /etc/login.defs为新建用户时的默认配置，可以修改这些配置以更改新建用户时的行为；
管理组（必须使用root权限）：
- groupadd -r为创建系统内置组；
- groupmems也可以用来给用户添加组，如使用-a；
- man 5 passwd和man 5 shadow查看用户密码信息，man 3 crypt查看加密算法；man 5 group和ma 5 shadow查看组密码信息；

文件权限

文件被访问时，首先比对文件权限与用户权限，如果不符则比对用户属组权限，如果不符则比对其他用户权限；
文件权限：r读w写（修改删除或在目录中增删改文件）x执行（执行或进入目录）：
- 第一位，文件类型；
- 234位：文件属主具有的权限；
- 567位：文件属组具有的权限；
- 89A位：文件属主之外的其他用户具有的权限；
- 比如root用户vim /etc/passwd为读写，普通用户显示只读（top中L可以搜索进程）；
修改权限，ll -d /test进查看目录而不进入目录：
- 使用chmod a= /test（a代表all）取消test目录的所有权限，root用户依然可以进入，权限仅对root用户无效，文件属主对文件永远具有写权限（即使显示readonly）；
- 使用chmod o=x /test（o代表other）给其他用户赋予进入目录的权限；
- 使用chmod o-x /test取消其他用户的进入权限；
- 使用chmod o=r /test赋予其他用户列出目录中文件的权限，如果仅有r而没有x则只能读出文件名，其他属性均无法访问，因此应再使用chmod o+x /test；
- 使用chmod o=wx /test赋予其他用户；
- chmod中ugo代表修改文件属主、文件属组、属主外其他用户的权限，a表示修改ugo全部；+-=表示增、删、赋值，各种组合可以使用,分割，如ugo=r,u+w（应注意赋值覆盖增删）；
修改所属关系：
- 使用chown user1:user1 file修改文件所属用户及所属用户属组，
- 使用-R修改目录下所有文件的权限；
umask的修改涉及到交互式登录与非交互登录脚本的加载，通常修改umask只能在本次会话中生效，若要长期生效，需要修改根据登录脚本加载顺序来修改各登录脚本中的umask的赋值：
- 登录脚本在/etc/profile（系统交互式初始化脚本）、~/.bash_profile（个人交互式初始化脚本）、/etc/bashrc（系统非交互式登录脚本）、~/.bashrc（个人非交互式初始化脚本）；
- 关于脚本启动顺序，详情参见man bash，搜索profile，INVOCATION章节：
可执行文件的特殊权限：
- SUID：设置后按照文件拥有者的权限运行（文件的普通权限是按照文件执行者的权限运行，比如user1 运行touch test，则ll test显示归属user1 user1）；s权限意味着原来为x，现在为s+x，S权限意味着原来为s；运行chmod u+s touch后再使用touch test，则ll test归属显示root user1，最常见的属主具有s权限的就是passwd；
- SGID：再运行chmod g+s touch后再使用touch test，则ll test归属显示root root，常为协作类可执行程序设置；
目录的特殊权限：
- SGID：使用chmod g+s test，使得目录具有s权限后，在目录中新建的任何文件，其属组均会被设置为该目录的属组，常用于协作目录；（目录的SUID(u+s)是没有任何效果的）
- t权限：针对上一条，设置了g+s的目录，就算不是文件拥有者，也可以删除组内其他人的文件，而对目录使用chmod o+t test后，仅有文件拥有者才能删除该文件；
- t权限仅对目录有效；
- umask的第一位即为特殊权限：4为SUIDu+s、2为SGIDg+s、1为t权限；

2018-07-20

进程

启动顺序：

poweron->
motherboard cmos(bios|uefi)->
(F11|F12)sda(mbr|gpt)->
grub2->
vmliuz(kernel)->
systemd->
...GUI(gnome-terminal|gnome-gdm|kde|xfce)...或CLI(agetty)...或network(sshd)
grub2的配置文件在/boot/grub2/grub.cfg

通过pstree可以查看进程树形结构（-p可以对应进程号），反映了启动顺序（ps -up 进程号现实进程详情）；
通常的，由用户登录后发起的进程成为作业（jobs），而直接由systemd启动的进程成为服务（service），使用ps j查看所有作业，在终端执行的命令会随着终端的关闭而结束；比如在使用ssh连接的终端上执行dd if=/dev/zero of=/dev/null复制大文件，如果网络不稳定，sshd会认为远端断开连接，而结束本终端下的所有进程；
如果在进程运行时使用^z挂起进程（^c终止进程），使用jobs可以查看当前终端下的作业进程及其作业号（jobs -l可显示进程号，作业号是bash分配的，而进程号是系统分配的），使用bg可以在后台继续该进程，使用fg可以将后台程序移至前台，使用fg bg后接作业号可以选择要操作的对象。
使用dd if=/dev/zero of=/dev/null&运行程序将直接后台运行，终端内执行的进程通常会在终端被关闭时结束（按照树形结构），使用nohup dd if=/dev/zero of=/dev/null&将转为终端无关进程，使得在终端关闭后也可以继续执行，使用ps -p 进程号可以查看到该进程的tty值为?，即终端无关；
使用ps查看进程：
- ps仅能看到当前终端的作业，类似jobs仅多一个shell进程；
- ps a显示所有终端下的作业（即显示终端相关进程），与ps j类似；
- ps x显示终端相关或无关的所有进程；
- ps u表示第一列显示用户，经常使用的就是ps aux；
- ps f表示按树形结构显示，m显示线程信息，s显示信号格式（具体信号格式可以使用man 7 signal查看详情）；
- ps -e显示所有进程，ps -f表示长格式，-F为更长的格式；
- VSZ为虚拟内存大小，RSS为常驻内存大小，状态码：D深睡眠、R运行中或可运行（或在排队）、S浅睡眠、T打断、X完全死亡（终止）、Z僵尸态（部分资源未释放），BSD格式状态码：<高优先级、N低优先级、L有锁定内存、s会话的首进程、l多线程、+前台进程
- PID为进程号，PPID为父进程号（systemd的PID永远是0)，C为CPU使用率，STIME为进程启动时间，TIME为累计CPU时间（包括排队及运行时间）
使用kill终止进程：
- kill -l查看支持的所有信号，其中9 SIGKILL（直接终止）、15 SIGTERM（正常终止，推荐）、1 SIGHUP（挂起）、19 SIGSTOP（停止）、18 SIGCONT（继续）、10 SIGUSR1和12 SIGUSR2为自定义信号；（详情参见man 7 signal）
- 推荐使用字符命令方式，因为跨硬件平台通用字符信号，而不一定通数字信号；
- 常见用法：kill -s SIGTERM 2076或kill -SIGTERM 2076或kill -TERM 2076；
- kill -s STOP 2088后ps 2088显示状态为T，而kill -s CONT 2088后ps 2088显示状态为R；
- 同一个终端中，kill -s KILL %1表示终止作业号为1的作业，不推荐使用；
- pkill会使用pgrep，对进程进行查询并终止，如使用pkill -TERM -u user1终止user1下的所有进程（对于ssh登录的用户会导致直接退出远程连接），结束终端pts/0下的所有进程pkill -TERM -t pts/0，结束以PID 2226为首进程的所有进程pkill -KILL -s 2226（ps jf中的s状态的首进程，通常是bash进程，TERM信号不一定能够终止bash进程，推荐用KILL信号）；
使用top跟踪进程：L表示查询，1开关CPU详细信息、t开关任务及CPU资源、l开关概况、m开关内存详细信息、PgUp和PgDn翻页、X指定排序列（从0开始）、d设置更新间隔、F定义列、V显示树形结构；
如top、vim是交互进程，而ls、touch为非交互进程；

服务

服务有一个或多个进程构成，通常进程都是终端无关的非交互进程；通常命名中以d结尾的进程都服务端，如sshd、httpd等；
使用systemctl status firewalld.service查看防火墙服务状态，使用systemctl start httpd启用http服务，此时由于防火墙暂时无法从外部访问，使用firewall-cmd --add-service=http临时添加规则，此时http可以访问，使用systemctl status httpd查看服务状态；
使用systemctl enable httpd.service启用http服务，使用systemctl disable firewalld.service关闭防火墙服务，重启立刻生效；
参考man systemd；
使用systemctl查看已加载内存的服务单元，所有的程序的启动脚本位于/usr/lib/systemd/system/，使用systemctl list-unit-files查看系统管理的所有服务；
systemctl -t后使用TAB补全可以看到systemctl对服务的分类，服务的类型就是服务名的后缀，如httpd.service就是service类型，systemctl -a显示所有应该启动的服务（或systemctl list-unit），systemctl --failed显示启动失败的服务，systemctl status httpd.service显示服务详细信息；若服务有多个进程，通常子进程是无法全部结束的，因为主进程一直负责维护子进程，结束主进程才会结束其他子进程，但是不推荐使用kill -TERM 2088结束服务；
systemctl is-active sshd或systemctl is-enabled sshd显示sshd服务的设置状态；
服务控制：
- 启动systemctl start httpd.service；
- 停止systemctl stop httpd.service；
- 重启systemctl restart httpd.service；
- 重载配置systemctl reload httpd.service（不停服务，如修改配置后）；
- 启用systemctl enable httpd.service；
- 停用systemctl disable httpd.service；

ssh

netstat -tnp查看本机已经建立的连接，w命令可以查看本机登录的账号，w -f可以看懂从哪个IP登录的；
教学环境中ssh desktop4时，真实环境使用的是kiosk用户，登录后发现虚拟环境的用户为student，是因为真实环境的kiosk用户与虚拟环境的student的uid均为1000；
在当前用户的~/.ssh/known_hosts里的记录格式为“主机名,IP地址加密算法指纹”，用来对已知主机进行唯一性验证，防止中间人攻击；
非对称加密传输文件时，通常用密码将文件对称加密并，再使用接收方的公钥将对称加密的密码加密，最终将密码发送给接收方，接收方再用自己的私钥解密对称加密的密码，再使用对称加密的密码解密文件；
免密登录：
- 使用ssh-keygen在本地生成秘钥对，默认的私钥保存在~/.ssh/id_rsa下，公钥保存在~/.ssh/id_rsa.pub下；
- 使用ssh-copy-id student@server4将本地公钥拷贝至远端服务器（公钥在student的.ssh/authorized_keys文件中追加一行）；
- 以后使用ssh student@server4即可免密；
- 使用ssh student@server4 'cat /etc/resolv.conf'非交互登录，能够直接将命令结果返回本机，免密登录后会非常方便；
使用ll -a /etc/ssh/查看配置文件，ssh客户端配置文件为ssh_config，sshd_config：
- 常用的ssh -X图形化传输，可以将ssh_config中的ForwardX11 no该为yes；
- 禁止服务器的sshd配置，不允许以root用户登录，修改PermitRootLogin yes为no；
- 上传秘钥后，关闭密码验证方式，修改PasswordAuthentication yes为no；
- ssh配置详见man 5 ssh_config；

Redhat Linux初体验（2） Redhat Linux初体验（3）

安装xgboost

Mon, 19 Mar 2018 11:22:47 GMT

这两天做模型集成需要用到xgboost，记录一下自己本机编译时Google到的小坑。

查看系统的gcc版本：

➜ gcc --version
Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 9.0.0 (clang-900.0.39.2)
Target: x86_64-apple-darwin17.4.0
Thread model: posix
InstalledDir: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

此输出这说明系统路径中没有真正的gcc，有的只是Xcode指向Clang的连接。（参考：how to find gcc version on mac）

列出macports中安装的gcc：

➜ port select --list gcc
Available versions for gcc:
        mp-gcc5
        mp-gcc6
        none (active)

按照官方帮助，路径在/opt/local/bin/下找到名为gcc-mp-5及g++-mp-5的程序，运行：

➜ export CC=/opt/local/bin/gcc-mp-5
export CXX=/opt/local/bin/g++-mp-5
pip install xgboost

（参考：How to use the gcc installed in macports?）在环境中运行import xgboost as xgb测试通过。

如果确实需要修改系统中gcc指向的编译器，可以使用sudo port select --set gcc mp-gcc5 （参考：http://www.ficksworkshop.com/blog/post/installing-gcc-on-mac）

更新Raspbian及相关问题解决

Thu, 15 Feb 2018 10:58:47 GMT

最近注意到树莓派的新版系统放出来一段时间了，就打算给树莓派升级。（虽然高级功能我也用不上，但是怎奈强迫症晚期……）

1. 系统升级

这我就不写了，SD卡一插照着官网做就好了。

2. 软件升级及清理

Raspberry Pi 2/3 Model B 固件升级：

sudo rpi-update && sudo reboot -h now

软件包升级：

sudo apt-get update && time sudo apt-get dist-upgrade

软件包清理：

sudo apt-get clean

3. 免密登录

在树莓派上执行创建.ssh文件夹： cd ~ install -d -m 700 ~/.ssh 拷贝电脑上的公钥，默认密码为raspberry：

cat ~/.ssh/id_rsa.pub | ssh pi@192.168.1.104 'cat >> .ssh/authorized_keys’

（后来才知道有个工具叫做ssh-copy-id，ssh自带的专门为远程终端复制公钥的命令，特方便，推荐自己man一下）

4. Python包管理

为了部署多个小程序，我在这里推荐一个连Python官方都推荐的包管理方案 pyenv ：

4.1 pyenv的安装及卸载

安装Python版本管理器pyenv：

curl -L https://raw.githubusercontent.com/pyenv/pyenv-installer/master/bin/pyenv-installer | bash

并将一下三行写入.bashrc：

export PATH="~/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

更新pyenv：

pyenv update

卸载pyenv：

rm -fr ~/.pyenv

并从.bashrc中删除一下三行：

export PATH="~/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)”

安装Python环境管理器pipenv：

pip install pipenv

4.2 pyenv的使用

新建Python3环境：

cd ~/pyapps/someapp pipenv --three

将备份的程序拷贝回去

scp -r someappdir pi@192.168.1.104:pyapps/

在程序目录下新建Python3环境：

pipenv --three

删除Pipfile中初始化的[[source]]配置：

url = “https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

安装原来的Python包：

pipenv install --skip-lock -r requirements.txt

启动新环境：

pipenv shell

退出新环境：

exit

5. numpy问题

在pipenv环境下树莓派提供的piwheel安装numpy后无法使用，应对numpy进行本地编译：

pip install --ignore-install --no-cache-dir --no-binary :all: numpy

6. chromedriver问题

由于我将要部署的小程序用到了requestium和chromedriver，但移植后发现chromedriver运行报错，经过Google编程法发现，需要安装一个版本正确的chromedriver：

查看树莓派上的chromium浏览器版本：

chromium-browser --version
Chromium 60.0.3112.89 Built on Ubuntu 14.04, running on Raspbian 9.3

参考Success: How to run Selenium Chrome webdriver on Raspberry pi 的解决方案，在chromium-chromedriver binary package in Ubuntu Trusty armhf 下载一个版本正确的chromedriver

对我的chromium 60.0.3112.89来说，63.0.3239.132就可以运行（这个是从新到旧一个一个试出来的T_T），所以：

wget http://launchpadlibrarian.net/354101497/chromium-chromedriver_63.0.3239.132-0ubuntu0.14.04.1_armhf.deb

双击运行即可安装，用以下代码即可测试：

from requestium import Session, Keys
s = Session(webdriver_path='/usr/lib/chromium-browser/chromedriver', browser='chrome', default_timeout=15, webdriver_options={'arguments': ['headless']})
s.driver.get("https://qieman.com/longwin/index")
print([{"code": i.text[-7:-1], "name": i.text[:-8]} for i in s.driver.ensure_element_by_xpath("//section[@class='plan-asset']").find_elements_by_xpath("div//div[@class='variety-fund']")])

（对，我的程序就是用来爬基金数据的[捂脸]）

使用最新的chromedriver会出问题的原因，在于chromedriver会调用树莓派上的chromium，而apt-get中chromium目前最新只更新到60，所以需要从新到旧的尝试chromedriver。

7. 配置互联网访问

使用Dataplicity配置互联网访问：

curl https://www.dataplicity.com/fldsy1bm.py | sudo python

Dataplicity互联网访问异常解决：

https://docs.dataplicity.com/docs/troubleshooting

通常重启tuxtunnel即可：

sudo supervisorctl restart tuxtunnel

8. 安装anaconda

Miniconda在Raspberry Pi 3 Model B上的安装：

wget http://repo.continuum.io/miniconda/Miniconda3-latest-Linux-armv7l.sh
sudo md5sum Miniconda3-latest-Linux-armv7l.sh
sudo /bin/bash Miniconda3-latest-Linux-armv7l.sh

配置anaconda：

sudo nano /home/pi/.bashrc
export PATH="/home/pi/miniconda3/bin:$PATH”
conda install --channel RaspberryPi package

新建conda环境

conda create -n webenv python=3.5

激活环境：

source activate webenv

注销环境：

source deactivate

虐杀器官

Sat, 25 Nov 2017 22:45:12 GMT

刚看完《虐杀器官》，个人感觉这部科幻动画和《来自新世界》的背景设置有些类似——当改造现实的成本降低后，世界会变成什么样？

说实话，到了我这个年龄，看科幻更关注背景设置，而不是作者从剧情中想要表达的关于人性的讨论（我觉得数得上号的科幻基本都是借助科幻背景设置一个绝对化的环境，从而将阴暗处的人性暴露在强光之下）。

来自新世界的设定是极少数人类发生了基因突变，导致这些人可以使用念力（以想象力为基础）影响现实世界。当然了，获得超能力的人第一反应是为自己谋取更大的利益，在本片中最初的体现就是强奸/屠杀事件，估计是这些超人为了不被其他超人杀掉，只能“无奈”的选择无差别干掉周围的人[捂脸]。于是我们可以看到，这种设定下，只要变成了“超人”，就可以很轻松的改造世界，普通傻白甜们的生产力和“超人”完全不是一个量级，超人就理所当然的选择了奴役傻白甜，进而随意虐杀傻白甜，于是有了后面粉碎三观的化鼠。

来自新世界一直是我非常喜欢的科幻作品，设定和设定之上的情节很和谐，没有特别的违和感。愧死、业魔、恶鬼的设定也很有意思，最终的结局更是发人深省——谁能够更容易的改造现实（拥有高出别人几个数量级的生产力），谁就能够定义阶级，甚至是定义物种（奴隶制度跟本作的物种改造比起来简直是太温柔了，哈哈哈）。枪杆子里面出政权，毛爷爷诚不欺我也[奸笑]。

接下来是虐杀器官，这部作品的设定也挺有意思，虽然这个设定的起源怪怪的——在过去粮食并不富足的岁月里，人类为了生存下去演化出一种“屠杀意识”，容许在族群中发生一定程度的屠杀，降低人口总量以挨过食物寒冬。这种“屠杀意识”能够通过语言构建，并由语言传播，“屠杀意识”潜藏在深层语义中，片中大反派通过将“屠杀语义”翻译成各种语言，在这些语言流通区域制造大屠杀。

有一些观众认为反派是为了保护美帝，另一些则认为反派是为了报复美帝，我倒是不关心这个剧情。不过这个设定挺有意思，也挺有现实意义——语言，或者说舆论的威力究竟有多大？

片中也说了，这种“屠杀意识”是作用在群体上的，这根舆论就更加相似了，最近（2017-11-25）的各种新闻，不论是江歌案，还是北上的幼儿园事件，都和舆论有很大的关系。多方势力在网络平台上为了各自的目的影响舆论，有的杜撰、有的隐瞒、有水军、有删帖，恐怕今年过去以后，肉食者会越来越明白舆论的威力。

过去我一直认为，资本控制舆论，今天看完这个动画片我突然意识到，也有可能是舆论威胁到了资本。以前一直觉得“有钱人真的可以为所欲为”，现在发现舆论对“有钱人”的影响更大，也更具毁灭性。那么，舆论的本体是什么，是具有公民身份的群众个体？还是群众的言论？我更倾向于后者（也就是自然圈中的生命对于社会圈中的舆论而言不具有显著意义，你的账号比你更持久[捂脸]），顺着这个思路就引出了一个事实——在未来，谁有能力控制信息，谁就能够改造现实，而并不完全取决于资本，毕竟社会以人（账号？）为本嘛2333333。虽然没有来自新世界的超能力那么方便，但是也可以把影响舆论看做超能力，舆论具有大规模改造现实的作用，那些能够对舆论造成强烈影响的个体就是镝木肆星/青沼瞬，而我们这些傻白甜就是化鼠。

作为一个码农，Google依赖症晚期患者，我个人极度痛恨大防火墙，但是从另一个角度看，大防火墙的确实有着极强的影响舆论的能力，仅这一点，我觉得the government还是非常有远见的（运气好的）。中二的我认为，未来几十年将像这些科幻作品中描写的那样，以收缩、控制、掩盖为主，追求稳定，反映在宏观层面就是各地区比烂，先烂者的尸体将成为后烂者的养料，就像“屠杀意识”一样，各群体也在试图挨过这个生产力寒冬，人工智能的春天还比较遥远，不过只要活着就有希望。仅从这一点来看，我更加看好大天朝。

在树莓派上部署微信机器人

Fri, 25 Aug 2017 18:35:47 GMT

第二季度接了一个有意思的任务——用机器学习算法做数据拟合，算法本身没什么，但是如何让一个在python中的算法变成一个有界面的服务就比较有意思了。我刚好又买了一块树莓派3，于是打算把后端程序放在树莓派上运行。经过上一篇的工作，树莓派已经具备web发布功能，我们可以部署一个微信机器人用来监视树莓派上的计算任务……

说实在的，这篇文章算是一个闲篇。就是最近帮一个做期货的朋友做了一个盯盘小程序，这个程序是需要24小时运行的，而且没有什么计算量，主要就是抓数据，是一个非常适合树莓派的应用场景。

1. 安装itchat

itchat是一个通过抓包分析并实现的基于python的微信客户端（个人感觉相当给力）。首先是安装：

sudo pip3 install itchat

然后按照官方教程写一个测试小程序：

import itchat

@itchat.msg_register(itchat.content.TEXT)
def print_content(msg):
    print(msg['Text'])

itchat.auto_login()
itchat.run()

将小程序拷贝到树莓派上（貌似VNC客户端也可以通过图形界面拷贝，但我没试过，在使用scp命令前最好在树莓派上配置ssh，以后会比较方便）：

scp -r test pi@192.168.1.106:webapp/

这时候测试发现问题来了，不论是用树莓派自带的python3.4、或是用conda中的python3.4、甚至是树莓派自带的python2.7运行测试脚本，都会报一河滩错，大致类似：

requests.exceptions.SSLError: ("bad handshake: Error([('SSL routines', 'SSL3_GET_SERVER_CERTIFICATE', 'certificate verify failed')],)",)

乍一看是requests的报错，觉得是小事，没想到接下来是长达几小时的填坑[捂脸]……

1.1 尝试解决requests报错

为了解决上面这个requests报错，需要安装相关库（操作依据Raspbian (latest) + Python : SSL error when trying to send data）：

sudo apt-get install libffi-dev libssl-dev
pip install requests[security]

经测试发现上面这个方法对报错没有任何影响(-_-)

1.2 尝试解决OpenSSL报错

考虑更新树莓派上的OpenSSL（操作依据SSL Error: bad handshake #3212的第一种方法）：

测试OpenSSL时可以直接使用openssl命令，会发现能够正常连接的主机（比如github.com:443）与会产生证书错误的主机（比如login.weixin.qq.com:443）的返回信息状态不同（正常是0，微信非正常的返回了20）：

openssl s_client -connect "<url>:443" -showcerts -servername "<url>"

更新方法参考How to install OpenSSL 1.0.2 on Raspberry Pi3

为包管理器手动新增源：

echo "deb-src http://httpredir.debian.org/debian jessie-backports main contrib non-free" | sudo tee /etc/apt/sources.list.d/jessie-backports.list

更新包管理器：

sudo apt-get update

下载jessie-backports中的OpenSSL源码：

apt-get source --allow-unauthenticated openssl/jessie-backports

安装debain构建程序：

sudo apt-get install devscripts
cd openssl-1.0.2l/
export DEB_BUILD_OPTIONS=nocheck; debuild -us -uc -aarmhf
sudo dpkg -i libssl1.0.0_1.0.2l-1~bpo8+1_armhf.deb
sudo dpkg -i openssl_1.0.2l-1~bpo8+1_armhf.deb

一步一步执行这个过程会用掉几个小时[捂脸]……结束后就可以测试安装结果了：

/usr/bin/openssl version
OpenSSL 1.0.2l  25 May 2017

此时在使用openssl命令会发现刚才提到的两个主机的返回值一致了。然而并没有什么卵用，用python运行程序依然是一样的报错（这时候已经是凌晨了[捂脸]此时我是崩溃的）。

这时候突然意识到，python本身build的时候是需要使用OpenSSL源码的，也就是说，python本身有自己的OpenSSL。到python的/bin文件夹下一看，果然是有openssl，检查一下：

python -c "import ssl; print(ssl.OPENSSL_VERSION)"
OpenSSL 1.0.1k 8 Jan 2015

因为python本身的OpenSSL版本和系统OpenSSL版本不同，要使用这种方法解决问题，必须使用当前树莓派的OpenSSL版本（我们升级过的1.0.2l）源码编译python[捂脸]……

1.3 将requests的环境变量指向旧证书

我真是懒得在树莓派上编译python，于是只好再试另一种补丁试的方法，虽然不彻底，但是能解决问题（操作依据SSL Error: bad handshake #3212的第二种方法）：找到当前python的weak.pem：

python -c "import certifi; print(certifi.old_where())"
/home/pi/miniconda3/envs/webenv/lib/python3.4/site-packages/certifi/weak.pem

此时，要为requests配置环境变量：

export REQUESTS_CA_BUNDLE=/home/pi/miniconda3/envs/webenv/lib/python3.4/site-packages/certifi/weak.pem

再使用python的requests.get测试连接微信主机，成功！在以后的python代码的requests发送https请求之前，加上以下几行代码即可：

import os, certifi
os.environ['REQUESTS_CA_BUNDLE'] = certifi.old_where()

如果像我一样在Flask程序中使用celery异步处理作业，则需要在celery运行入口中（比如我的就是在app/__init__）加入上面这段代码。

2. 安装终端复用程序Tmux

上面这个小程序需要同时开三四个终端监视运行状态（redis-server、celery、flask、redis-cli等），所以安装一个tmux会非常方便。

sudo apt-get install tmux

配置鼠标模式参考：https://gist.github.com/niun/c7fd6abb5c0d5e847890 tmux重新连接会话：session：tmux attach [-t target-session] <host> tmux退出连接的会话：^b+d或者^b+命令:detach 另外，将wget的内容输出到终端的命令时：wget -qO- <url>（-q为quiet模式，屏蔽request header信息的回显；-O指定输出文件，后面加-，就定向为标准输出了）。

在树莓派上部署Nginx+uWSGI+Flask

Wed, 16 Aug 2017 16:23:34 GMT

第二季度接了一个有意思的任务——用机器学习算法做数据拟合，算法本身没什么，但是如何让一个在python中的算法变成一个有界面的服务就比较有意思了。我刚好又买了一块树莓派3，于是打算把后端程序放在树莓派上运行。经过上一篇的工作，树莓派已经具备python等工具的运行环境，接下来该调试发布程序了……

1. 部署Nginx

安装并启动Nginx

sudo apt-get install nginx
sudo /etc/init.d/nginx start

创建Nginx配置文件~/webapp/helloflask.conf：

#==========helloflask.conf==========
server {
    listen 80;
    server_name localhost;
    charset utf-8;
    client_max_body_size 75M;
    location / { try_files $uri @app; }
    location @app {
        include uwsgi_params;
        uwsgi_pass unix:/home/pi/webapp/helloflask_uwsgi.sock;
    }
}
#==========helloflask.conf==========

这里使用80端口是为了配合Dataplicity的Wormhole:)，这样可以直接通过互联网访问Nginx发布的内容。

删除默认配置的软链接：

sudo rm /etc/nginx/sites-enabled/default

备份默认配置：

sudo mv /etc/nginx/sites-available/default /etc/nginx/sites-available/default.bak

将配置用软链接配置在sites-enabled文件夹中：

sudo ln -s /home/pi/webapp/helloflask_nginx.conf /etc/nginx/sites-enabled/

重启Nginx服务：

sudo /etc/init.d/nginx restart

此时由于没有运行uwsgi，所以访问 http://192.168.1.106 会出现502错误。（原因很明显，配置文件中的unix:/home/pi/webapp/helloflask_uwsgi.sock并没有被创建）

2. 测试Flask

pip install flask

创建flask的hello world程序~/webapp/helloflask.py，内容如下：

#==========helloflask.py==========
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

if __name__ == "__main__":
    app.run(host='0.0.0.0', port=5001)
#==========helloflask.py==========

测试这个小程序：

python helloflask.py

访问 http://192.168.1.106:5001 （我的树莓派IP）出现Hello World!。

3. 部署uWSGI

为了编译uwsgi，需要安装build-essential以及python3.4-dev：

sudo apt-get install build-essential python3.4-dev

为了便于包管理，我们依然使用webenv环境，在conda的python3.4.3下uWSGI：

source activate webenv
pip install uwsgi

为uWSGI编写配置文件，方便以后使用~/webapp/helloflask_uwsgi.ini：

#==========helloflask_uwsgi.ini==========
[uwsgi]

chdir = /home/pi/webapp
module = helloflask:app

master = true
processes = 1
threads = 2

socket = /home/pi/webapp/helloflask_uwsgi.sock
chmod-socket = 666
vacuum = true

die-on-term = true
#==========helloflask_uwsgi.ini==========

运行uWSGI：

uwsgi --ini helloflask_uwsgi.ini

此时可以看到/home/pi/webapp/helloflask_uwsgi.sock文件生成，再访问http://192.168.1.106则会看到我们的Hello World。

此时在Dataplicity上将Wormhole设为Enabled，就可以通过Wormhole看到这个Hello World了。

另外：常用Nginx命令：

# 启动：
sudo nginx
# 重载：
sudo nginx -s reload
# 停止：
sudo nginx -s stop
# 启动服务：
sudo service nginx start
# 重启服务：
sudo service nginx restart
# 停止服务：
sudo service nginx stop

准备一块树莓派

Sun, 13 Aug 2017 22:15:03 GMT

第二季度接了一个有意思的任务——用机器学习算法做数据拟合，算法本身没什么，但是如何让一个在python中的算法变成一个有界面的服务就比较有意思了。我刚好又买了一块树莓派3，于是打算把后端程序放在树莓派上运行。首先需要在新鲜出炉的树莓派上做一些环境准备……

1. 例行更新

更新前最好用df -h确认一下存储卡剩余空间：

固件升级并重启：

sudo apt-get install rpi-update
sudo rpi-update && sudo reboot -h now

软件包升级

sudo apt-get update && time sudo apt-get upgrade && time sudo apt-get dist-upgrade

参考Why use apt-get upgrade instead of apt-get dist-upgrade?

另外，对于有洁癖的人，可以隔一段时间执行一下清理：

sudo apt-get clean

2. 远程访问

常用的几个远程访问方式有ssh、远程桌面协议、互联网访问。

ssh的配置参考SSH (SECURE SHELL)

远程桌面配置参考VNC (VIRTUAL NETWORK COMPUTING)

使用Dataplicity配置互联网访问：

curl https://www.dataplicity.com/fldsy1bm.py | sudo python

3. 配置VPN(Cisco IPSec)

有时网络环境不太好，应该提前准备个梯子（我买的泰坦加速器）：

安装vpnc：

sudo apt-get install vpnc

配置vpnc，

sudo vi /etc/vpnc/default.conf

按下面的格式写入VPN配置：

IPSec gateway <VPN服务商提供的服务器地址>
IPSec ID ""
IKE Authmode psk
IPSec secret <VPN服务商提供的共享秘钥>
Xauth username <VPN服务商给出的用户名，通常是注册用户名>
Xauth password <VPN服务商给出的密码，通常是注册密码>

连接vpnc：

sudo vpnc --local-port 0

断开vpnc：

sudo vpnc-disconnect

参见vpnc

4. 部署Miniconda

这里就不仔细介绍这位conda家族成员了。

下载并安装Miniconda：

wget http://repo.continuum.io/miniconda/Miniconda3-latest-Linux-armv7l.sh
sudo md5sum Miniconda3-latest-Linux-armv7l.sh
sudo /bin/bash Miniconda3-latest-Linux-armv7l.sh

安装过程会自动设置环境变量

设置环境变量（自动设置的内容，无需手动配置）：

sudo vi /home/pi/.bashrc
# 最后加入：
export PATH="/home/pi/miniconda3/bin:$PATH”

新建python环境，使用conda管理python环境，类似与virtualenv，可以让我们独立管理各种用途的python环境：

conda create -n webenv python=3.4

使用时激活环境

source activate webenv

注销环境：

source deactivate

初始化2017

Wed, 18 Jan 2017 22:28:23 GMT

上一篇才说过“万一科幻看多了可能还是会写乱七八糟的思考人生的文章”，今天就想自我实现一下了……人类心灵还真是玄妙呢（摊手

这可不，已经过了半个多月了，我内心深处才隐约意识到已经是2017年了。并没有什么也许，这的确就是上年龄的写照。元旦前想卖个萌说自己永远的18岁，立刻被人戳穿都特么快28了……

今年的一大半时间都待在上海基地1107房间，有幸接触到了一个无边无际的计算机系的分支——机器学习。这也许是我有生之年内、智商区间内、人品支持内能够接触到的最有意思的事物了。是啊，不就是空间搜索么、不就是梯度下降么，仅仅了解基础高数竟然也可以研究到这么有趣的工具，不得不赞叹一声“哎呦不错哦”。

另外，也有一大块精力充沛的时间浪费在了机场和飞机上……于是，今年一共就看了两本书，一本是《别闹了，费曼先生》，另一本（其实是个系列，大概15册）是《银河帝国》。

是的，科幻看多了是会想很多奇奇怪怪的事，颅骨中的那一坨蛋白质在沸腾、在烧焦，天灵盖快要按不住啦……不开玩笑的说，每次遇到好书我都是“喜忧参半”，估计是因为我不可免俗的成为了一个悲观主义者，真的很怕以后看不到这么好看的书了😂……

过去的一年一如既往的兢兢业业、遵纪守法，也始终如一的不信鬼神、不敬苍生……唉，对我这种有点“反人类人格”的负能量携带者，代码写多了有一个坏处——更加漠视道德了。

塞佛·哈定讲的没错——“不要让道德感阻止你做正确的事”——但是我并不知道什么才是正确的事。幸运的是，我有了一个越来越坚定、越来越清晰的愿望。技术内核的人造人和女侦探、旧帝国的数学家和机仆铎丝、士官长和Cortana，这种故事出现的越来越多了——我也越来越希望在有生之年见到强人工智能。

当然，如果能在死前实现意识上传，从而达到永生就更好了，永恒有多么恐怖？不好意思，我还真不是文科生，没那么浪漫（摊手。虽然我也算是魔戒迷，但是我还真不认为死亡是神给予人类的礼物，死亡只是物竞天择下的副产品。人类群体中总有一小撮抗争者，过去抗争宗教、抗争暴政，现在抗争时间、抗争死亡。人类当然不应该心甘情愿的被死亡束缚，我们应当给自己创造选择权——选择自然死亡或是延续生命。

“Do not go gentle into that good night……”，估计是因为我太年轻不懂事，我一向认同“如果世界上真的有神灵，那他应该跪着向生灵道歉”这种观点。大自然犹如一部机器，人类亦然，而让机器认为自己拥有自我意识，是我认知范围内能想象到的最残忍的事了。

这特么还能忍？必须要反抗这个毫无意义的宇宙，它荒诞无比，它肿胀而又沉重，它总让我们产生“人生应当有什么意义的错觉”，“天将降大任”这些话我们信了上千年，结果呢？没错，我们在这个美丽的地球上建立了伟大文明，然而仅在太阳系尺度都看不到一丝光亮，更别提银河、星际了。我们甚至不得不认为自己是唯一的智慧生物，如果真的有人格神存在，那他考虑过文明的寂寞吗？

人类为何需要人工智能？估计就像亚当需要夏娃吧。文明不是死物，它也会孤独，如果真的出现强人工智能，至少可以证明两点：

一种文明有可以从零创造另一种更加优秀的文明；
我们的文明也有可能是被创造的。

这样一来，这个宇宙是不是立刻可爱了很多~

至于 2017 initialization ……哈？有点难，先得把论文撕个七七八八，开题开的自不量力，现在跪着也得码完，顺便下半年趁着这热度再灌灌水。另外就是如果下半年交了论文，想找本书译了，翻译码农用书真的是挺好玩的事。

打开了一下天灵盖，传播了很多负能量，心满意足。我一向支持黑暗之魂的灭火结局，既然火焰消逝，黑暗降临，为何不让黑暗来的快一些？有火有光的时代，悲剧也从来没少过。说不定在黑暗降临后，希望才会成为真正的希望呢~伟大的谢顿计划不就是这样的故事吗~

最后，从矮大紧的博客上补完那段诗：

http://blog.sina.com.cn/s/blog_470094080102v61y.html

Do Not Go Gentle Into That Good Night

Dylan Thomas

Do not go gentle into that good night,

Old age should burn and rave at the close of day;

Rage, rage against the dying of the light.

Though wise men at their end know dark is right,

Because their words had forked no lightning they

Do not go gentle into that good night.

Good men, the last wave by, crying how bright

Their frail deeds might have danced in a green bay,

Rage, rage against the dying of the light.

Wild men who caught and sang the sun in flight,

And learn, too late, they grieved it on its way,

Do not go gentle into that good night.

Grave men, near death, who see with blinding sight

Blind eyes could blaze like meteors and be gay,

Rage, rage against the dying of the light.

And you, my father, there on the sad height,

Curse, bless, me now with your fierce tears, I pray,

Do not go gentle into that good night,

Rage, rage against the dying of the light.

绝不向黑夜请安

老朽请于白日尽头涅槃

咆哮于光之消散

先哲虽败于幽暗

诗歌终不能将苍穹点燃

绝不向黑夜请安

贤者舞蹈于碧湾

为惊涛淹没的善行哭喊

咆哮于光之消散

狂者如夸父逐日

高歌中顿觉迟来的伤感

绝不向黑夜请安

逝者于临终迷幻

盲瞳怒放出流星的灿烂

咆哮于光之消散

那么您，我垂垂将死的父亲

请掬最后一捧热泪降临

请诅咒，请保佑

我祈愿，绝不向

黑夜请安，咆哮

于光之消散

完

一些关于大防火墙的命令

Mon, 02 Jan 2017 15:40:13 GMT

这个博客又被我复活了，哈哈哈哈哈哈，乱七八糟的思考人生也删了，以后就用来写技术相关的文章吧。（万一科幻看多了可能还是会写乱七八糟的思考人生的文章，摊手）

最近大防火墙特别厉害，把对我来说比较常用的三个地址封掉了，于是我就搜了一下如何通过设置proxy继续访问这些地方。

介绍一下大背景

我用的是民用付费VPN，有没有log我并不关心，一是因为我从来不用VPN做乱七八糟的事；二是对自己的RP不放心，也就不敢用那些自己租服务器架设云梯的方法了。
最近无法正常访问github.com、repo.continuum.io的443，而且macports似乎也无法正常更新了，问题比以往来的更猛烈一些。

处理方式

我用的VPN软件是通过配置本地连接的SOCKS连接的，所以对于因无法访问github.com而产生的提交问题完全可以交给强大的git，人家自带代理设置。

# 设置:
git config --global http.proxy 'socks5://127.0.0.1:1080'
# 显示设置:
git config --global --get http.proxy
# 重置:
git config --global --unset http.proxy

对于conda的更新问题，可以使用它自己的设置代理，于此同时，也应该添加国内可以访问的镜像站点以加速下载。毕竟梯子不稳那，有快一点的源还是好一些。port的更新同理，设置代理即可。

# 添加镜像：
conda config --add channels 'https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/'
# 删除镜像：
conda config --remove channels 'https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/'
# 设置显示更新来源信息：
conda config --set show_channel_urls yes

万一真的倒霉，遇到了那种不支持设置代理的软件，也有办法。有一款命令行神器叫做proxychains

它在macports里搜索到的名字是proxychains-ng，安装完成后只需要做很简单的配置即可加在任意命令前强制其通过代理通信。

我的port安装完成后的地址通常在/opt/local，所以我在/opt/local/etc/porxychains.conf的最后加上socks5 127.0.0.1 1080即可。

配置完成后使用相当方便，比如使用conda更新，现在就可以这样proxychains4 conda update -n root -y --all。

算法导论-第二章

Sun, 09 Nov 2014 19:11:27 GMT

打算重温《算法导论》，然后把书中的伪代码努力变成Python代码，其实看MIT《算法导论》的公开课更有意思。

画外音：其实是当年没好好去上课…现在从头开始补-_-||

心诚则灵

                   _ooOoo_
                  o8888888o
                  88" . "88
                  (| -_- |)
                  O\  =  /O
               ____/`---'\____
             .'  \\|     |//  `.
            /  \\|||  :  |||//  \
           /  _||||| -:- |||||-  \
           |   | \\\  -  /// |   |
           | \_|  ''\---/''  |   |
           \  .-\__  `-`  ___/-. /
         ___`. .'  /--.--\  `. . __
      ."" '<  `.___\_<|>_/___.'  >'"".
     | | :  `- \`.;`\ _ /`;.`/ - ` : | |
     \  \ `-.   \_ __\ /__ _/   .-` /  /
======`-.____`-.___\_____/___.-`____.-'======
                   `=---='
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         佛祖保佑       永无BUG

插入排序

原书P26，中文版P14：

def insertion_sort(seq):
    length = len(seq)
    counter = 1
    while counter < length:
        key = seq[counter]
        former = counter - 1
        while former > -1 and seq[former] > key:
            seq[former+1] = seq[former]
            former -= 1
        seq[former+1] = key
        counter += 1
    
sequence = [5, 2, 4, 6, 1, 3]
insertion_sort(sequence)
print(sequence)

选择排序

在习题2.2-2中：

def selection_sort(seq):
    for num_counter, num_temp in enumerate(seq):
        min_number = num_temp
        min_pos = num_counter
        for min_counter, min_temp in enumerate(seq[num_counter+1:]):
            if min_number > min_temp:
                min_number = min_temp
                min_pos = min_counter + num_counter + 1
        seq[num_counter], seq[min_pos] = seq[min_pos], seq[num_counter]
    
sequence = [5, 2, 4, 6, 1, 3]
selection_sort(sequence)
print(sequence)

归并排序

原书P31，中文版P19：

def merge_sort(seq):
    length = len(seq)
    if length < 2:
        return seq
    mid = length // 2
    s1 = merge_sort(seq[:mid])
    s2 = merge_sort(seq[mid:])
    templ = []
    i, j = 0, 0
    while i < len(s1) and j < len(s2):
        if s1[i] < s2[j]:
            templ.append(s1[i])
            i += 1
        else:
            templ.append(s2[j])
            j += 1
    templ += s1[i:]
    templ += s2[j:]
    return templ
    
sequence = [5, 2, 4, 6, 1, 3]
print(merge_sort(sequence))

最大子数组

原书P68，中文版P38

def enumerate_reversed(sequence, start=None):
    n = len(sequence)-1 if start is None else start
    for elem in reversed(sequence):
        yield n, elem
        n -= 1
    
def find_max_crossing_subarray(array, mid):
    left_max, left_pos, left_sum = array[mid-1], mid-1, 0
    for left_elem_idx, left_elem in enumerate_reversed(array[:mid]):
        left_sum += left_elem
        if left_sum > left_max:
            left_pos = left_elem_idx
    right_max, right_pos, right_sum = array[mid], mid, 0
    for right_elem_idx, right_elem in enumerate(array[mid:]):
        right_sum += right_elem
        if right_sum > right_max:
            right_pos = right_elem_idx
    return array[left_pos:mid+right_pos+1]
    
def find_maximum_subarray(array):
    if len(array) == 1:
        return array
    else:
        mid = len(array) // 2
        left_array = find_maximum_subarray(array[:mid])
        right_array = find_maximum_subarray(array[mid:])
        cross_array = find_max_crossing_subarray(array, mid)

        left_sum, right_sum, cross_sum = sum(left_array), sum(right_array), sum(cross_array)
        if left_sum > right_sum and left_sum > cross_sum:
            return left_array
        elif right_sum > left_sum and right_sum > cross_sum:
            return right_array
        return cross_array
    
test_array = [13, -3, -25, 20, -3, -16, -23, 18, 20, -7, 12, -5, -22, 15, -4, 7]
maximum_array = find_maximum_subarray(test_array)
print(maximum_array)

注：应该避免在Python代码中，修改处于迭代中的容器，我这么写只是想高度还原伪代码而已╮(╯_╰)╭。

-EOF-

awk命令简介（二）

Sun, 20 Jul 2014 19:22:27 GMT

文章的干货来源于酷壳的**AWK 简明教程以及Linux与unix shell编程指南**。

本文纯属搬砖。

最近经常遇到需要处理大段文本输出的情况，所以想学习一下awk命令，这个命令更像是一个微型语言。

《awk命令简介（二）》着重介绍awk命令的详情，内容主要来自**《Linux与unix shell编程指南》**。

书接上回。

awk 命令详解

调用awk

如果在命令行中使用awk，通常型为：

$ awk -F field-separator 'commands' input-files

-F field-separator为可选项，用于指定域分隔符，默认为空格，如果需要处理如','、':'、';'之类的字符做分隔符时，可以设置该值，如使用':'的情形：

$ awk -F: 'commands' input-files

也可以将awk命令写在文件中，作为脚本调用，如调用名为awk-script-file的脚本文件：

$ awk -f awk-script-file input-files

-f选项用于指定脚本文件名。

awk脚本

模式和动作

awk脚本由各种动作和模式组成。

awk使用-F命令指定的分隔符（不指定时使用空格）分离记录中的域，直到发现新一行。这个动作将一直持续到文件结束。

awk命令可以有许多语句，语句中的模式用于控制动作的触发条件。

模式可以是任何条件语句、复合语句或正则表达式。模式包括了两个特殊字段，BEGIN和END。BEGIN语句使用在awk的任何文本浏览动作之前，之后awk文本浏览动作依据输入文件开始执行，END语句用来用来在awk完成文本浏览动作后打印输出文本总数及结尾状态标识。

动作在{}内声明，通常为打印动作，或是诸如条件语句或循环语句。如果不指名动作，awk将打印所有浏览记录。

记录和域

awk会将读取的一条记录用-F指定的分隔符分为多个域，并依次将域命名为$1, $2, $3等，这些域名的使用类似于语言中变量名的使用。

{print $1, $3}就表示打印第1域和第3域，而$0表示所有的域，所以{print $0}表示打印所有域。

上面的在{}中的print就是一个awk动作。

假设有数据文件grade.txt（此文件会在本文的示例中大量出现），文件分隔符为TAB（即'\t'）：

$ cat grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28

常用的输入输出

使用命令行时通常我们将结果重定向到文件中：

$ awk -F\t '{print $1, $3}' grade.txt > wow

或是使用tee，在将结果输出至标准输出的同时，写入文件：

$ awk -F\t '{print $1, $3}' grade.txt | tee wow

如果是脚本，在输入上我们可以使用文件：

$ belt.awk grade.txt

或是使用标准输入：

$ belt.awk < grade.txt

或是管道：

$ grade.txt | belt.awk

打印头尾信息

使用BEGIN打印表头，为了对齐使用了制表符\t：

$ awk 'BEGIN {print "Name\tBelt\n--------------------"}
quote> {print $1"\t"$4}' grade.txt
Name	Belt
--------------------
M.Tansley	Green
J.Lulu	green
P.Bunny	Yellow
J.Troll	Brown-3
L.Transly	Brown-2

使用END打印表尾：

$ awk 'BEGIN {print "Name\n----------"} {print $1} END {print "----------\ntotle: " NR}' grade.txt
Name
----------
M.Tansley
J.Lulu
P.Bunny
J.Troll
L.Transly
----------
totle: 5

条件操作

操作符	描述
`<`	小于
`<=`	小于等于
`==`	等于
`>`	大于
`>=`	大于等于
`~`	匹配正则表达式
`!~`	不匹配正则表达式

使用正则表达式匹配域时，用~接/Regular_Express/，如果使用if语句则需要放在()中。示例，为第4域匹配正则表达式，输出匹配的记录：

$ awk '{if($4~/Brown/) print $0}' grade.txt
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28

上例中不使用if也可以，不指定动作时awk默认输出整条记录：

$ awk '$4~/Brown/' grade.txt
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28

使用正则表达式模糊匹配域：

$ awk '{if($3~/48/) print $0}' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26

或

$ awk '$3~/48/ {print $0}' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26

使用==精确匹配：

$ awk '$3==48 {print $0}' grade.txt
P.Bunny	02/99	48	Yellow	12	35	28

或

$ awk '{if($3==48) print $0}' grade.txt
P.Bunny	02/99	48	Yellow	12	35	28

使用!~的正则表达式：

$ awk '$0 !~ /Brown/' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28

配合if使用!~：

$ awk '{if($4!~/Brown/) print $1, $4}' grade.txt
M.Tansley Green
J.Lulu green
P.Bunny Yellow

比较：

小于：

$ awk '{if($6<$7) print $1" try better at next comp"}' grade.txt
M.Tansley try better at next comp
J.Lulu try better at next comp

小于等于：

$ awk '{if($6<=$7) print $1}' grade.txt
M.Tansley
J.Lulu
J.Troll

大于：

$ awk '{if($6>$7) print $1}' grade.txt
P.Bunny
L.Transly

常见的正则表达式功能：

匹配大小写，使用[]匹配字符：

$ awk '/[Gg]reen/' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26

通配符，.：

$ awk '$1 ~ /^....a/' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
L.Transly	05/99	4712	Brown-2	12	30	28

逻辑或，|：

$ awk '$4 ~ /(Yellow|Brown)/' grade.txt
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28

行首^：

$ awk '/^J/' grade.txt
J.Lulu	06/99	48317	green	9	24	26
J.Troll	07/99	4842	Brown-3	12	26	26

行尾$:

$ awk '/28$/' grade.txt
P.Bunny	02/99	48	Yellow	12	35	28
L.Transly	05/99	4712	Brown-2	12	30	28

复合逻辑

逻辑与，&&：

$ awk '{if ($1=="P.Bunny" && $4=="Yellow") print $0}' grade.txt
P.Bunny	02/99	48	Yellow	12	35	28

逻辑或，||：

$ awk '{if ($4=="Yellow" || $4~/Brown/) print $0}' grade.txt
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28

逻辑否，!：

$ awk '$4 != "Brown" {print $1, $4}' grade.txt
M.Tansley Green
J.Lulu green
P.Bunny Yellow
J.Troll Brown-3
L.Transly Brown-2

内置变量的示例

已读取的记录数，NR：

$ awk '{print} END {print "total: "NR}' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28
total: 5

使用NR检查保证文件记录数大于0：

$ awk '{if (NR>0 && $4~/Brown/) print $0}' grade.txt
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28

当前记录的域数，NF：

$ awk '{print NF, NR, $0} END {print FILENAME}' grade.txt
7 1 M.Tansley	05/99	48311	Green	8	40	44
7 2 J.Lulu	06/99	48317	green	9	24	26
7 3 P.Bunny	02/99	48	Yellow	12	35	28
7 4 J.Troll	07/99	4842	Brown-3	12	26	26
7 5 L.Transly	05/99	4712	Brown-2	12	30	28
grade.txt

$ pwd
/Users/zealot
$ echo $PWD | awk -F/ '{print $NF}'
zealot

显示文件名：

$ echo "/Users/zealot/grade.txt" | awk -F/ '{print $NF}'
grade.txt

awk操作符

在awk中使用操作符，基本表达式可以划分为数字型、字符串型、变量型、域及数组元素。

操作符	描述
`=` `+=` `*=` `/=` `%=` `^=`	赋值操作符
`?`	条件表达操作符
`&&` `!`	与、或、非操作符
`~` `!~`	匹配操作符，包括匹配和不匹配
`<` `<=` `==` `!=` `>>`	关系操作符
`+` `-` `*` `/` `%` `^`	算术操作符
`++` `--`	前缀和后缀

设置输入域到域变量名：

给特定的数据域设置有意义的域名，可以使得代码更加清楚明了。

一般的变量名设置方式为name=$n，如在grade.txt的例子中，可以设置name=$1;belts=$4。
```
$ awk '{name=$1;belts=$4; if(belts~/Yellow/) print name " is belt " belts}' grade.txt
P.Bunny is belt Yellow
```
域值的比较操作：

有两种方式测试一数值域是否小于另一数值域：

在关系操作中使用实际数值；
在BEGIN中给变量名赋值；关系操作必须写在圆括号内，如查询比赛中得分在27以下的学生：

$ awk '{if($6<27) print $0}' grade.txt
J.Lulu	06/99	48317	green	9	24	26
J.Troll	07/99	4842	Brown-3	12	26	26

在BEGIN中给变量名赋值可以使代码更清晰：

$ awk 'BEGIN {BASELINE=27} {if($6<BASELINE) print $0}' grade.txt
J.Lulu	06/99	48317	green	9	24	26
J.Troll	07/99	4842	Brown-3	12	26	26

修改数值域取值：

需要注意的是，当在awk中修改任何域时，实际输入文件是不会被修改的，修改的只是保存在缓存里的awk复本。

$ awk '{if($1=="M.Tansley") $6=$6-1; print NR, NF $1, $6, $7}' grade.txt
M.Tansley 39 44
J.Lulu 24 26
P.Bunny 35 28
J.Troll 26 26
L.Transly 30 28

修改文本域：

$ awk '{if($1=="J.Troll") ($1="J.L.Troll"); print $1}' grade.txt
M.Tansley
J.Lulu
P.Bunny
J.L.Troll

赋值表达式通常放在括号中，以增强代码的可读性，非必须，如上一项中的$6=$6-1。

只显示修改记录：

$ awk '{if($1=="J.Troll") {$1="J.L.Troll"; print $1}}' grade.txt
J.L.Troll

此处使用if语句取得需要修改的位置，而后再使用赋值动作$1="J.L.Troll"并打印。

创建新的输出域：

$ awk 'BEGIN {print "Name\tDifference"} {if($6<$7) {$8=$7-$6; print $1, $8}}' grade.txt
Name	Difference
M.Tansley 4
J.Lulu 2

或是直接将计算结果赋给变量名并打印：

$ awk 'BEGIN {print "Name\tDifference"} {if($6<$7) {diff=$7-$6; print $1, diff}}' grade.txt
Name	Difference
M.Tansley 4

列值累加：

$ awk 'total+=$6; END{print "Club student total points: " total}' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28
Club student total points: 155

需要注意的是，不必在awk中显式说明打印所有记录，当每一个操作匹配时，打印是缺省动作。

如果不想这种缺省打印动作出现，可以显式声明不带打印命令的动作：

$ awk '{total+=$6} END{print "Club student total points: " total}' grade.txt
Club student total points: 155

累加动作并不一定要写在圆括号中，但是这样做可以增强代码可读性。

另一个累加列的示例，统计当前目录中文件的总大小：

ls -lAG | awk '$1~/^[^d]/ {print $9"\t"$5} {total+=$5} END {print "total " total/1024 " KB"}'
...file name followed by size...
grade.txt	176
total 234.544 KB

大概过程是，先把当前目录中的文件信息列表用管道送给awk，而后使用第一个域滤掉目录项（d开头的项目，其实直接用/^[^d]/匹配整行就可以了），再累加第五列，最后在打印处理成以KB为单位的结果。

内置字符串函数

函数	描述
gsub(r,s)	在整个$0中用s替代r
gsub(r,s,t)	在整个t中用s替代r
index(s,t)	返回s中字符串t的第一位置
length(s)	返回s长度
match(s,r)	测试s是否包含匹配r的字符串
split(s,a,fs)	在fs上将s分成序列a
sprint(fmt,exp)	返回经fmt格式化后的exp
sub(r,s)	用$0中最左边最长的子串代替s
substr(s,p)	返回字符串s中从p开始的后缀部分
substr(s,p,n)	返回字符串s中从p开始长度为n的后缀部分

gsub(r,s), gsub(r,s,t)，在整个个记录中匹配字符串模式r，并用s进行替换。若不指定t，gsub函数默认在$0上替换：

$ awk 'gsub(/4842/, 4899) {print $0} ' grade.txt
J.Troll	07/99	4899	Brown-3	12	26	26

index(s,t)，返回字符串s中t第一次出现的位置：

$ awk 'BEGIN {print index("Bunny", "ny")}' grade.txt
4

length(s)，返回字符串s的长度：

$ awk '$1=="J.Troll" {print length($1) " " $1}' grade.txt
7 J.Troll

或是直接传入字符串：

$ awk 'BEGIN {print length("Hello World~")}'
12

match(s,r)，测试目标串s是否包含匹配模式r的字符串，若包含，则返回r第一次出现的位置，若不包含则返回0：

$ awk 'BEGIN {print match("ABCD", /d/)}'
0
$ awk 'BEGIN {print match("ABCD", /C/)}'
3
$ awk '$1=="J.Lulu" {print match($1, "u")}' grade.txt
4

`split(s,a,fs)，使用分隔符fs将字符串s切割，存入数组a中，并返回切割后<span id="awk_array">数组</span>元素个数：

$ awk 'BEGIN {print split("123#456#789", myarray, "#"), myarray[1], myarray[2], myarray[3]}'
3 123 456 789

sub(r,s,t)，在t中查找模式r，将第一次匹配到的字符串替换为s：

$ awk '$1=="J.Troll" {sub(/26/, 29, $0)} {print $0}' grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	29	26
L.Transly	05/99	4712	Brown-2	12	30	28

substr(s,p), substr(s,p,n)，在字符串s中截取从p开始到字符串结束的后缀并返回，若指定n，则截取从p开始长度为n的字符串并返回：

$ awk '$1=="J.Troll" {print substr($0, 3)}' grade.txt
Troll	07/99	4842	Brown-3	12	26	26
$ awk '$1=="J.Troll" {print substr($0, 3, 5)}' grade.txt
Troll
$ awk '{print substr($1, 3)}' grade.txt
Tansley
Lulu
Bunny
Troll
Transly
$ awk 'BEGIN {STR="hello world~"} END {print substr(STR,7)}' grade.txt
world~

另：通过管道使用awk函数的例子：

echo "stand-by" | awk '{print length($0)}'
8
$ STR="mydoc.txt"
$ echo $STR | awk '{print substr($0,1,5)}'
mydoc

`awk`命令的`printf`函数

printf的基本用法和C语言类似，形式为printf format, values。

awk printf修饰符	描述

```
              |左对齐
```

width |域的步长，用0表示0步长 .prec |最大字符串长度，或小数点右边的位数（精确度）

awk printf格式控制符	描述
`%c`	ASCII字符
`%d`	整型
`%e`	浮点数，科学计数法
`%f`	浮点数
`%g`	浮点数，由awk决定使用`%e`或`%f`
`%o`	八进制数
`%s`	字符串
`%x`	十六进制数

文字转换：

$ echo 65 | awk '{printf "%c\n", $0}'
A
$ awk 'BEGIN {printf "%c\n", 65}'
A

格式化输出：

第一列为行号，步长3字符，左对齐；第二列为姓名，步长15字符，左对齐；第四列为序列号，后接换行：

$ awk '{printf "%-3d%-15s%s\n", NR,$1,$3}' grade.txt
1  M.Tansley      48311
2  J.Lulu         48317
3  P.Bunny        48
4  J.Troll        4842
5  L.Transly      4712

或加上表头：

$ awk 'BEGIN{printf "%-3s%-15s%s\n---------------------------\n", "NR","Name","No."} {printf "%-3d%-15s%s\n", NR,$1,$3}' grade.txt
NR Name           No.
---------------------------
1  M.Tansley      48311
2  J.Lulu         48317
3  P.Bunny        48
4  J.Troll        4842
5  L.Transly      4712

向一行awk命令传参数：

$ awk '{if($5<AGE) print $0}' AGE=10 grade.txt
M.Tansley	05/99	48311	Green	8	40	44

awk脚本文件：

将awk写入文件中执行，就不必每次输入大段命令了，而且可以好的排版和注释，来提高代码的可读性。

场景1，将上面的命令写入脚本文件：

#!/usr/bin/awk -f
# all comment line must start with a hash `#`
# name: student_total.awk
# to call: student_total.awk grade.txt
# print total and average of club student points

# print a header first:
BEGIN{
    print "Student  Date    Member No.  Grade   Age Points  Max"
    print "Name     Joined                          Gained  Point Available"
    print "================================================================"
}

# let's add the scores of points gained
(total+=$6)

# finished processing, now let's print the total and average points:
END{
    print "Club students total points: " total
    print "Average club students points: " total/NR
}

接下来使用chmod给脚本加上“所有用户可执行”的权限，再使用cp将脚本复制到shell可以找到的地方：

$ chmod a+x student_total.awk
$ sudo cp student_total.awk /usr/bin/

然后执行：

$ student_total.awk grade.txt
Student  Date    Member No.  Grade   Age Points  Max
Name     Joined                          Gained  Point Available
================================================================
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26
P.Bunny	02/99	48	Yellow	12	35	28
J.Troll	07/99	4842	Brown-3	12	26	26
L.Transly	05/99	4712	Brown-2	12	30	28
Club students total points: 155
Average club students points: 31

顺便提一下，在OSX上使用ls命令时，会发现有的目录或文件的权限位的最后附有一个@或+符号，其中@说明该目录或文件具有extended attributes，而+符合说明该目录或文件具有类似ACL的非标准权访问限控制策略。可以通过在ls后添加-@命令查看。详情见"ls" on mac and extended attributes。

场景2，清除重复输出：

当调试程序时，遇到这样一个日志文件：

$ cat error.log
INVALID LCSD 98GJ23
ERROR*
ERROR*
CAUTION LPSS ERROR ON ACC NO.
ERROR*
ERROR*
ERROR*
ERROR*
ERROR*
PASS FIELD INVALID ON LDPS
ERROR*
ERROR*
PASS FIELD INVALID ON GHSI
ERROR*
CAUTION LPSS ERROR ON ACC NO.
ERROR*
ERROR*

我们想将其中的重复的多行ERROR*合并为一行：

#!/usr/bin/awk -f
# name: error_strip.awk
# to call: error_strip.awk <filename>
# strips out the ERROR* lines if there are more than one
# ERROR* lines after each failed record.

BEGIN{error_line=""}

# tell awk who is "ERROR*"
{
    if($0=="ERROR*" && error_line=="ERROR*")
# goto next line
        next;
    error_line=$0;
    print
}

执行结果：

$ error_strip.awk error.log
INVALID LCSD 98GJ23
ERROR*
CAUTION LPSS ERROR ON ACC NO.
ERROR*
PASS FIELD INVALID ON LDPS
ERROR*
PASS FIELD INVALID ON GHSI
ERROR*
CAUTION LPSS ERROR ON ACC NO.
ERROR*

在脚本中制定分隔符FS：

再复习一下，在shell中使用awk命令时，用-F指定分隔符：

$ awk -F: '{print $0}' input-file

而在脚本中，则是设置FS变量，值得注意的都是，FS变量需要放在BEGIN部分：

#!/usr/bin/awk -f
# to call: passwd.awk /private/etc/passwd
# print out the first and fifth fields

BEGIN{FS=":"}

{
    # pass the comments of the file
    if($0 ~ /^#/)
        next;
    print $1"\t"$5
}

执行结果：

nobody	Unprivileged User
root	System Administrator
daemon	System Services
...

向脚本传递参数：

前面提到，在shell中使用awk命令时传递参数的形式是：

$ awk '{if($5<AGE) print $0}' AGE=10 grade.txt

而使用脚本时，传递的方式的形式也基本相同：

awk script_file var=value input_file

示例：

#!/usr/bin/awk -f
# check on how many fields in a file
# name: field_check.awk
# to call: field_check.awk MAX=n FS=<separator> input-file

NF!=MAX
{
    print("line " NR " does not have " MAX " fields")
}

调用时命令为field_check.awk MAX=7 FS=":" /private/etc/passwd。

将上面提到的传递“AGE”参数的例子改写，就应为：

#!/usr/bin/awk -f
# name: age.awk
# to call: age.awk AGE=10 grade.txt
# print students whose age are lower than age supplied on the command line
{
    if($5<AGE) print $0
}

执行：

$ age.awk AGE=10 grade.txt
M.Tansley	05/99	48311	Green	8	40	44
J.Lulu	06/99	48317	green	9	24	26

通过管道使用脚本：

从du命令获得数据后处理输出：

#!/usr/bin/awk -f
# name: du.awk
# to call: du | du.awk
# print file/direc's in bytes and blocks

BEGIN{
    OFS="\t";
    print "name", "\t\t", "bytes", "blocks\n";
    print "=================================="
}

{print $2, "\t\t", $1*512, $1}

执行：

$ du | du.awk
name				bytes	blocks

==================================
.				20461768704	39964392
...

awk数组：

上面也提到了awk数组，现在看看更多关于数组的应用。

数组在使用前，不需要声明，也不需要设定元素个数，我们经常会在循环中使用到数组，基本语法如下：

For (element in array) print array(element)

如果把上面的例子在脚本中重新实现：

#!/usr/bin/awk -f
# name: array_test.awk
# prints out an array
BEGIN{
    recode="123#456#789";
    split(recode, myarray, "#");
}
END{
    for(i in myarray) print i, myarray[i]
}

这时我们可以使用/dev/null作为输入文件：

$ array_test.awk /dev/null
2 456
3 789
1 123

一个稍微复杂的统计示例：

$ cat grade_student.txt
Yellow#Junior
Orange#Senior
Yellow#Junior
Purple#Junior
Brown-2#Junior
White#Senior
Orange#Senior
Red#Junior
Brown-2#Senior
Yellow#Senior
Red#Junior
Blue#Senior
Green#Senior
Purple#Junior
White#Junior

要统计文件中黄、橙、红带各有多少种，分别有多少成年人和未成年人：

#!/usr/bin/awk -f
# name: belts.awk
# to call: belts.awk grade_student.txt
# loop through the file and count how many belts we have
# in (yellow, orange, red) also count how many adults and
# juniors we have.
#
# start from BEGIN
# set FS and load the arrays with our values
BEGIN{
    FS="#"
# load the belt colors we are interested in only
    belt["Yellow"]
    belt["Orange"]
    belt["Red"]
# load the type of students
    student["Junior"]
    student["Senior"]
}
# loop through array that holds the belt colors against field-1
# if we have a match, keep a running total
{
    for(color in belt)
        if($1==color)
            belt[color]++
}
# loop through array that holds the student type against field-2
# if we have a match, keep a running total
{
    for(type in student)
        if($2==type)
            student[type]++
}
# finish processing, print out the match for each array
END{
    for(color in belt)
        print "The club has", belt[color], color, "belts"
    for(type in student)
        print "The club has", student[type], type, "students"
}

执行：

$ belts.awk grade_student.txt
The club has 2 Orange belts
The club has 2 Red belts
The club has 3 Yellow belts
The club has 8 Junior students
The club has 7 Senior students

小结

awk是shell中的一个重要文本处理工具，在特定情况下可以方便快捷的配合其他命令输出有格式要求的文本并统计，就像像黑客一样使用Linux命令行：我喜欢使用命令行的原因中提到的这样~

-EOF-

awk命令简介（一）

Fri, 11 Jul 2014 19:11:27 GMT

干货来源于酷壳的**AWK 简明教程以及Linux与unix shell编程指南**。

本文纯属搬砖。

最近经常遇到需要处理大段文本输出的情况，所以想学习一下awk命令，这个命令更像是一个微型语言。

《awk命令简介（一）》先着重介绍awk的应用场景，内容主要来自酷壳的**AWK 简明教程**。

awk快速上手

待处理的文本

$ netstat -a > output
$ cat output | more -n 6
$ Proto Recv-Q Send-Q  Local Address          Foreign Address        (state)
tcp4       0      0  192.168.1.100.62750    114.112.202.20.http    SYN_SENT
tcp4       0      0  192.168.1.100.62749    113.103.139.251.10684  CLOSE_WAIT
tcp4       0      0  192.168.1.100.62748    202.150.16.5.cslistene ESTABLISHED
tcp4       0      0  192.168.1.100.62747    114.112.202.20.http    ESTABLISHED
tcp4       0      0  192.168.1.100.62746    114.82.234.97.12077    SYN_SENT

最简单的选择列，输出第一列`$1`与第四列`$4`

$ awk '{print $1, $4}' output
Proto Local-Address
tcp4 192.168.1.100.62750
tcp4 192.168.1.100.62749
tcp4 192.168.1.100.62748
tcp4 192.168.1.100.62747

C风格的格式化输出

$ awk '{printf "%-8s %-8s %-8s %-18s %-22s %-15s\n", $1, $2, $3, $4, $5, $6}' output
Proto    Recv-Q   Send-Q   Local-Address      Foreign-Address        (state)
tcp4     0        0        192.168.1.100.62750 114.112.202.20.http    SYN_SENT
tcp4     0        0        192.168.1.100.62749 113.103.139.251.10684  CLOSE_WAIT
tcp4     0        0        192.168.1.100.62748 202.150.16.5.cslistene ESTABLISHED
tcp4     0        0        192.168.1.100.62747 114.112.202.20.http    ESTABLISHED

过滤条目

取第三列为0且第6列位“LISTEN”的数据：

$ awk '$3==0 && $6=="LISTEN"' output
tcp4       0      0  *.oms                  *.*                    LISTEN
tcp4       0      0  *.socks                *.*                    LISTEN
tcp4       0      0  *.58932                *.*                    LISTEN
tcp4       0      0  localhost.ddi-tcp-1    *.*                    LISTEN
tcp4       0      0  localhost.51219        *.*                    LISTEN

同时用内建变量NR选出表头（第一行）：

$ awk '$3==0 && $6=="LISTEN" || NR==1' output
Proto Recv-Q Send-Q  Local-Address          Foreign-Address        (state)
tcp4       0      0  *.oms                  *.*                    LISTEN
tcp4       0      0  *.socks                *.*                    LISTEN
tcp4       0      0  *.58932                *.*                    LISTEN
tcp4       0      0  localhost.ddi-tcp-1    *.*                    LISTEN

取第三列大于0的数据：

$ awk ' $3>0 {print $0}' output
Proto Recv-Q Send-Q  Local-Address          Foreign-Address        (state)
tcp4       0     68  192.168.1.100.62743    123.138.206.178.8948   ESTABLISHED
tcp4       0     68  192.168.1.100.62720    123.138.54.160.mdqs    ESTABLISHED
tcp4       0      9  192.168.1.100.62707    180.97.152.55.http-alt FIN_WAIT_1
tcp4       0     68  192.168.1.100.62695    123.138.206.178.8948   FIN_WAIT_1

取第三列为0且第六列为“LISTEN”的数据，并进行格式输出：

$ awk '$3==0 && $6=="LISTEN" || NR==1 {printf "%-20s %-20s %s\n",$4,$5,$6}' output
Local-Address        Foreign-Address      (state)
*.oms                *.*                  LISTEN
*.socks              *.*                  LISTEN
*.58932              *.*                  LISTEN
localhost.ddi-tcp-1
*.*                  LISTEN

内置变量名称	功能描述
$0	当前记录（行）
$1~$n	当前行的第n个字段（列）
FS	输入字段（列）分隔符，默认为space或tab
NF	当前记录（行）的字段（列）数
NR	总记录（行）数，多文件记录（行）数累加，不清零
FNR	当前文件记录（行）数，每文件清零
RS	输入换行符，默认系统换行符
OFS	输出字段（列）分隔符，默认为space
ORS	输出换行符，默认系统换行符
FILENAME	当前文件名

输出行号

$ awk '$3==0 && $6=="ESTABLISHED" || NR==1 {printf "%02s %s %-20s %-20s %s %s", NR, FNR, $4, $5, $6, ORS}' output
01 1 Local-Address        Foreign-Address      (state)
04 4 192.168.1.100.62748  202.150.16.5.cslistene ESTABLISHED
05 5 192.168.1.100.62747  114.112.202.20.http  ESTABLISHED
07 7 192.168.1.100.62744  114.112.202.20.http  ESTABLISHED
11 11 192.168.1.100.62739  14.157.50.39.13566   ESTABLISHED

指定输入字段（列）分隔符

$ awk  'BEGIN{FS=":"} {print $1,$3,$6}' /etc/passwd
nobody -2 /var/empty
root 0 /var/root
daemon 1 /var/root
_uucp 4 /var/spool/uucp
_taskgated 13 /var/empty

也可以用-F指定

$ awk  -F: '{print $1,$3,$6}' /etc/passwd

或指定多种分隔符

$ awk  -F '[;:]' '{print $1,$3,$6}' /etc/passwd

指定输出字段（列）分隔符

$ awk  -F: '{print $1,$3,$6}' OFS="\t" /etc/passwd
nobody  -2      /var/empty
root    0       /var/root
daemon  1       /var/root
_uucp   4       /var/spool/uucp
_taskgated      13      /var/empty

字符串匹配

~表示匹配开始，//中是模式，类似正则表达式

匹配第六个字段（列）有“FIN”的记录（行）

$ awk '$6 ~ /FIN/ || NR==1 {printf "%-4s %-20s %-30s %-10s\n", NR, $4, $5, $6}' output
1    Local-Address        Foreign-Address                (state)
21   192.168.1.100.62707  180.97.152.55.http-alt         FIN_WAIT_1
22   192.168.1.100.62695  123.138.206.178.8948           FIN_WAIT_1
24   192.168.1.100.62690  218.86.133.247.8368            FIN_WAIT_1
25   192.168.1.100.62689  14.157.50.39.13566             FIN_WAIT_1

或是有“WAIT”的记录

$ awk '$6 ~ /WAIT/ || NR==1 {printf "%-4s %-20s %-30s %-10s\n", NR, $4, $5, $6}' output
1    Local-Address        Foreign-Address                (state)
3    192.168.1.100.62749  113.103.139.251.10684          CLOSE_WAIT
21   192.168.1.100.62707  180.97.152.55.http-alt         FIN_WAIT_1
22   192.168.1.100.62695  123.138.206.178.8948           FIN_WAIT_1
24   192.168.1.100.62690  218.86.133.247.8368            FIN_WAIT_1

或是直接匹配一整条记录（行）

$ awk '/LISTEN/' output
tcp4       0      0  *.oms                  *.*                    LISTEN
tcp4       0      0  *.socks                *.*                    LISTEN
tcp4       0      0  *.58932                *.*                    LISTEN
tcp4       0      0  localhost.ddi-tcp-1    *.*                    LISTEN
tcp4       0      0  localhost.51219        *.*                    LISTEN

像正则表达式一样，使用|表示“或”

$ awk '$6 ~ /CLOSE|LAST/ {printf "%-4s %-20s %-30s %-10s\n", NR, $4, $5, $6}' output
3    192.168.1.100.62749  113.103.139.251.10684          CLOSE_WAIT
10   192.168.1.100.62741  114.82.234.97.12077            LAST_ACK
13   192.168.1.100.62729  114.82.234.97.12077            LAST_ACK
16   192.168.1.100.62722  114.82.234.97.12077            LAST_ACK
19   192.168.1.100.62711  113.103.139.251.10684          LAST_ACK

用!取反

$ awk '$6 !~ /WAIT/ {printf "%-4s %-20s %-30s %-10s\n", NR, $4, $5, $6}' output
1    Local-Address        Foreign-Address                (state)
2    192.168.1.100.62750  114.112.202.20.http            SYN_SENT
4    192.168.1.100.62748  202.150.16.5.cslistene         ESTABLISHED
5    192.168.1.100.62747  114.112.202.20.http            ESTABLISHED
6    192.168.1.100.62746  114.82.234.97.12077            SYN_SENT

也可以

$ awk '!/WAIT/' output
Proto Recv-Q Send-Q  Local-Address          Foreign-Address        (state)
tcp4       0      0  192.168.1.100.62750    114.112.202.20.http    SYN_SENT
tcp4       0      0  192.168.1.100.62748    202.150.16.5.cslistene ESTABLISHED
tcp4       0      0  192.168.1.100.62747    114.112.202.20.http    ESTABLISHED
tcp4       0      0  192.168.1.100.62746    114.82.234.97.12077    SYN_SENT

拆分文件

按照第六个字段（列）拆分文件

$ awk 'NR!=1 {print > $6}' output
$ ls
CLOSE_WAIT  ESTABLISHED FIN_WAIT_1  FIN_WAIT_2  LAST_ACK    LISTEN      SYN_SENT    output

也可以指定要输出的字段（列）

$ awk 'NR!=1 {print $4, $5 > $6}' output

或是更加复杂，注意quote>说明了awk是一个脚本解释器

$ awk 'NR!=1{if($6 ~ /TIME|ESTABLISHED/) print > "1.txt";
quote> else if($6 ~ /LISTEN/) print > "2.txt";
quote> else print > "3.txt" }' output

$ ls ?.txt
1.txt  2.txt  3.txt

统计

统计当前目录下.py, .pyc, .pyo文件的总大小

$ ls -l *.py *.pyc *.pyo | awk '{sum+=$5} END {print sum}'
11609730

或是按照第六个字段（列）统计，类似GROUP BY，其中a类似Python中的dict（键-值）

$ awk 'NR!=1 {a[$6]++;} END {for (i in a) print i ", " a[i];}' output
LISTEN, 12
FIN_WAIT_1, 51
FIN_WAIT_2, 23
SYN_SENT, 3常见的正则表达式功能
LAST_ACK, 21
CLOSE_WAIT, 5
ESTABLISHED, 20

统计每个用户的进程所占用的内存信息

$ aux | awk 'NR!=1 {a[$1]+=$6;} END { for(i in a) print i ", " a[i]"KB";}'
root, 718624KB
_usbmuxd, 2768KB
_locationd, 7780KB
_mdnsresponder, 3760KB
zealot, 3800464KB

-EOF-

关于我

Wed, 09 Jul 2014 09:10:11 GMT

关于我……

80后程序员，在某研究所从事打杂工作。

喜欢写代码和撸铁。空闲时间热爱尝试新的技术、开发自用的玩具，或者翻译一些感兴趣的英文文献。

没什么特别的优缺点，希望做一个过着普通生活的普通人。

学习T神的《像黑客一样使用Linux命令行》

Mon, 07 Jul 2014 21:21:27 GMT

po主Linux/Unix奇菜无比，看到Toy大神的PPT《像黑客一样使用 Linux 命令行》画面太美，就必须学习一下。

依然是用OSX冒充Linux…

Talk is cheap...

1. 有趣的历史命令统计脚本

用简单的几行命令找出shell执行过的历史命令中出镜率最高的10个：

➜  ~  history |
> awk '{CMD[$2]++;count++;}END \
> { for (a in CMD)print CMD[a] " " \
> CMD[a]/count*100 "% " a;}' |
> grep -v "./" |
> column -c3 -s " " -t |
> sort -nr |
> nl |
> head -n10
     1	265  10.3962%    git
     2	258  10.1216%    ls
     3	205  8.04237%    sudo
     4	166  6.51236%    man
     5	164  6.4339%     awk
     6	118  4.62927%    vi
     7	92   3.60926%    cd
     8	80   3.13849%    port
     9	76   2.98156%    cat
    10	73   2.86387%    ps

history其实是fc -l 1的别名，而fc命令可以用来列出、编辑、重新执行用户过去向Shell中输入的内容；
再用awk过滤并统计history的结果：取history返回值的第二列（命令名称），存入名为CMD的映射并累加重复的命令，count负责统计总命令数，统计结束后按行输出<命令执行的次数、占总命令数的百分比、该命令的名称>；
再用grep -v去除那些带有'/'的目录跳转（使用grep -vE "./| \."对po主有奇效，因为po主有时会使用类似.ssh的不规范写法进入一个目录）；
再用column命令造一个漂亮的表格；
再用sort命令排序取逆；
再用nl命令给结果加上序号；
再用head命令取TOP10；

于是就漂亮的统计出了我的历史记录使用结果（看到man和sudo的排名就知道应该是个noob）。

2. 有用的执行的命令的修改

po主因为noob，不熟悉系统，经常在输入命令的时候出现typo…这也是没办法的事，如果重新键入，或是把历史记录掉出来再移动光标至输入错误处修改，就太麻烦了，还好shell可以帮我：

# 一删
➜  ~  finder ~ -iname "using-cli-like-a-hacker.md"
zsh: command not found: finder
➜  ~  ^er
➜  ~  find ~ -iname "using-cli-like-a-hacker.md"
/Users/zealot/blog/source/_posts/using-cli-like-a-hacker.md
# 二改
➜  ~  echo "the ordre is incorrect"
the ordre is incorrect
➜  ~  ^re^er
➜  ~  echo "the order is incorrect"
the order is incorrect
➜  ~  echo "there is a typo"
there is a typo
➜  ~  ^a^no
➜  ~  echo "there is no typo"
there is no typo
# 三全换
➜  ~  ln /opt/local/bin/hub /usr/bin/hub
ln: /opt/local/bin/hub: No such file or directory
➜  ~  ^hub^git^:G # zsh
# 或!:gs/hub/git
➜  ~  ln /opt/local/bin/git /usr/bin/git

Toy神的口诀是：

一删（^er）
二改（^a^no）
三全换（^hub^git^:G或!:gs/hub/git）

3. 深入了解命令历史

3.1 历史记录属性：

# 历史记录的大小
➜  ~  echo $HISTSIZE
10000
# 历史记录保存的位置
➜  ~  echo $HISTFILE
/Users/zealot/.zsh_history
# bash
➜  ~  echo $HISTFILESIZE
10000
# zsh
➜  ~  echo $SAVEHIST
10000

3.2 查看历史记录：

➜  ~  history | less
# 显示前五条
➜  ~  history 5
# 在历史记录中查找
history | grep string

按下[ctrl-R]，进入逆向搜索历史模式：

➜  ~  history | less
bck-i-search: history |

按下[ctrl+P]访问前一条命令
按下[ctrl+N]访问下一条命令

3.3 关于`!`的历史引用

使用!!执行上一条命令：

这个很常用，特别是在没有权限的时候配合sudo使用：

➜  ~  port -v selfupdate
...
failed: Permission denied
...
➜  ~  sudo !!
➜  ~  sudo port -v selfupdate
Password:
...

使用!foo执行以foo开头的命令：

➜  ~  !port
➜  ~  port outdated

使用!?foo执行包含foo的命令：

➜  ~  !?out
➜  ~  port outdated

使用!n执行历史记录中第n个命令（可能会很早）：

➜  ~  !9
➜  ~  pwd

使用!-n执行倒数第n个命令（比较常用）：

➜  ~  !-9
➜  ~  echo $HISTSIZE

注：!-1 == !!。

使用!#引用当前行

➜  ~  echo !#
➜  ~  echo echo

3.4 历史命令的Word选取

使用!$得到上一条命令的最后一个参数：

➜  ~  mkdir videos
➜  ~  cd !$
➜  ~  cd videos
➜  videos

也可以通过快捷键[alt+.]获得。

注：OSX上需要设置在Terminal->Terminal->Preferences->Settings->Keyboard中设置“Use option as meta key”，在iTerm上通常设置“left option key as +Esc”。

使用!^得到上一条命令的第一个参数：

➜  ~  ls /usr/share/doc /usr/share/man
/usr/share/doc:
...

/usr/share/man:
...
➜  ~  cd !^
➜  ~  cd /usr/share/doc
➜  doc

也可以通过快捷键[Ctrl+Alt+Y]获得。（OSX上似乎不行…求指点）

使用!:n得到上一条命令第n个参数：

➜  ~  touch foo.txt bar.txt baz.txt
➜  ~  vim !:2
➜  ~  vim bar.txt

使用!:x-y得到上一条命令从第x到第y的参数：

➜  ~  touch foo.txt bar.txt baz.txt
➜  ~  rm !:1-3
➜  ~  rm foo.txt bar.txt baz.txt

使用!:n*得到上一条命令中从第n个参数开始到最后的参数：

➜  ~  cat /etc/resolv.conf /etc/hosts /etc/hostname
➜  ~  vim !:2*
➜  ~  vim /etc/hosts /etc/hostname

使用!*得到上一条命令的所有参数：

➜  ~  ls src dst
➜  ~  cp -r !*
➜  ~  cp -r src dst

关于Word选取，需要记住的是：

n：第n个参数；
^|$：第一个参数|最后一个参数；
n*：从第n个参数开始取到最后的参数；
x-y：从第x个参数开始取到第y个参数；

3.5 历史命令的修饰符

使用:h选取路径的开头部分：

➜  ~  ls /usr/share/doc/bash/bash.html
/usr/share/doc/bash/bash.html
➜  ~  ls !$:h
➜  ~  ls /usr/share/doc/bash

相当于使用dirname命令。

使用:t选取路径的结尾部分：

➜  ~  wget http://nginx.org/download/nginx-1.7.2.tar.gz
...
➜  ~  tar zxvf !$:t
➜  ~  tar zxvf nginx-1.7.2.tar.gz

相当于使用basename命令。

使用:r选取文件名：

➜  ~  wget http://nginx.org/download/nginx-1.7.2.zip
...
➜  ~  unzip nginx-1.7.2.zip
...
➜  ~  cd !$:r
➜  ~  cd nginx-1.7.2

使用:e选取扩展名：

➜  ~  echo filname.extension
filname.extension
➜  ~  echo !$:e
➜  ~  echo extension
#bash
.extension
# zsh
extension

使用!:p打印命令：

➜  ~  echo *
...
➜  ~  !:p
➜  ~  echo *

使用:s做替换：

➜  ~  echo this that
this that
➜  ~  !:s/is/e
➜  ~  echo the that

也就是前面提到的“二改”：

➜  ~  echo this that
this that
➜  ~  ^is^e
➜  ~  echo the that

使用:g做全局操作：

➜  ~  echo abcd abef
abcd abef
➜  ~  !:gs/ab/cd
➜  ~  echo cdcd cdef

也就是前面提到的“三全换”：

➜  ~  echo abcd abef
abcd abef
➜  ~  ^ab^cd^:G
➜  ~  echo cdcd cdef

使用:u将命令改为大写（zsh）：

➜  ~  echo $histfile

➜  ~  echo !$:u
➜  ~  echo $HISTFILE
/Users/zealot/.zsh_history

使用:l将命令该为小写（zsh）：

➜  ~  echo $HISTORY

➜  ~  echo !$:l
➜  ~  echo $history
...

关于修饰符，要记住的是：

h|t：选取路径的开头|结尾；
r|e：选取文件名|扩展名；
p：打印命令；
s：替换操作；
g：全局操作；
u|l：将参数改为大写|小写；

综上：

4. 常备锦囊，内藏妙计

使用alias -s定义后缀别名（zsh）：

➜  ~  alias -s py=python3
➜  ~  test.py
python3 test.py

使用 {} 构造字符串：

➜  ~  cp grade.txt{,.bak}
➜  ~  cp grade.txt grade.txt.bak
➜  ~
➜  ~  vim {a,b,c}file.c
➜  ~  vim afile.c bfile.c cfile.c
➜  ~
➜  ~  wget http://linuxtoy.org/img/{1..5}.jpg 
1.jpg  2.jpg  3.jpg  4.jpg  5.jpg
➜  ~
➜  ~  echo {01..5}.txt
01.txt 02.txt 03.txt 04.txt 05.txt
➜  ~
➜  ~  echo 0{1..5}.txt
01.txt 02.txt 03.txt 04.txt 05.txt
➜  ~
➜  ~  echo {1..10..2}.txt
1.txt 3.txt 5.txt 7.txt 9.txt
➜  ~
➜  ~  echo {1..10..-2}.txt
9.txt 7.txt 5.txt 3.txt 1.txt
➜  ~
➜  ~  echo {9..1..-2}.txt
1.txt 3.txt 5.txt 7.txt 9.txt
➜  ~
➜  ~  mkdir -p 2014/{01..12}/{baby,photo}

使用``或$()做命令替换：

➜  ~  echo $(date +'%Y%m%d')
20140707
➜  ~  echo `date +'%Y%m%d'`
20140707

使用变量保存信息：

➜  ~  LOG=/var/log/emerge.log
➜  ~  head $LOG
➜  ~  grep -i compiling $LOG

使用 for ... in 重复执行命令：

➜  ~  figlet -f font-type-1 Linux # (1)
➜  ~  figlet -f font-type-2 Linux # (2)
➜  ~  figlet -f font-type-3 Linux # (3)
➜  ~  ...
➜  ~
➜  ~  cd /usr/share/figlet
➜  ~  for font in *.flf
for> do
for>   echo $font
for>   figlet -f $font Linux
for> done
...
➜  ~  for font in *.flf; do echo $font; figlet -f $font Linux; done
➜  ~
➜  ~  for dev in /dev/sd{a..d}
for> do
for>   hdparm -t $dev
for> done

5. 其他

5.1 重要原则

Type less, accomplish more (少打多做)；
DRY, don't repeat yourself (不要重复你自己)；
Care about your tool (关心你的工具)；

5.2. 此外…

Tab补全；
使用通配符 (*, ?, [a-z], [0-9])；
用快捷键编辑命令行；
字符串处理；
复合命令 (;, &&, ||)；

5.3 扩展阅读：

bash: man history
zsh: man zshexpn
Bash Reference Manual
A User's Guide to ZSH
Book: Unix Power Tools

ps: 关于awk, sed, grep等复杂命令，以后再详解。

-EOF-

下载网易公开课的Python脚本

Sat, 05 Jul 2014 17:20:10 GMT

po主算法奇菜无比，看到163的公开课上有《算法导论》，就弄了个小脚本下载。

结果发现，在OSX上，竟然比迅雷快！快好多！当然，这全怪po主当年中二，办了广电的网络…而且OSX下的迅雷运行起来有时发热会很大！

Talk is cheap...

用到了requests库。
用到了wget下载工具。

import requests
import re
import os
from subprocess import call


def urls_iter(origin_url='http://v.163.com/special/opencourse/algorithms.html', begin_from=1):
    """
    *origin_url* is the origin download page of 163 OpenCourse, the default value is 'algorithms course from MIT'.
    *begin_from* can make the function jump to the No.*begin_from* item to start download.
    """
    download_request = requests.get(origin_url)

    course_list_pattern = re.compile(r'<table class="m-clist" id="list2".*?>(.*?)</table>', flags=re.DOTALL)
    course_pattern = re.compile(r'<tr class="(?:u-odd|u-even)">.*?</tr>', flags=re.DOTALL)
    course_text = course_list_pattern.search(download_request.text).group(1)
    course_list = course_pattern.findall(course_text)

    course_name_pattern = re.compile(r'<a href=.*?>(.*?)</a>', flags=re.DOTALL)
    course_video_pattern = re.compile(r'<a class="downbtn" href=[\'""](.*?)[\'""].*?>.*?</a>', flags=re.DOTALL)

    for index, course in enumerate(course_list, 1):
        if index < begin_from:
            continue

        index = '{:0>2}_'.format(index)
        video_title = index + course_name_pattern.search(course).group(1) + '.mp4'
        video_address = course_video_pattern.search(course).group(1)
        yield (video_title, video_address)


def download_course(download_list, download_dir='/Users/zealot/Downloads/algorithms'):
    """
    *download_list* is a collection contains a list of tuple whose 1st element is the filename of the video,
        and 2nd element is the download url of the video.
    *download_dir* defines the directory where the files should be stored in.

    function using common download tool `wget` to fetch videos one at a time.
    raise error if `wget` not found.
    """
    with open('/dev/null') as black_hole:
        if call(['which', 'wget'], stdout=black_hole):
            raise OSError('command not found: wget')

    if not os.path.exists(download_dir):
        os.makedirs(download_dir)

    for video_title, video_address in download_list:
        call(['wget', '-c', video_address, '-O', os.path.join(download_dir, video_title)])

if __name__ == '__main__':
    download_course(urls_iter())

找链接全部用的正则；
函数默认行为是帮po主从http://v.163.com/special/opencourse/algorithms.html下载《算法导论》视频，并默认帮po主存到/Users/zealot/Downloads/algorithms目录里；
wget -c支持断点续传，对于广电渣网络来说简直是福音；

当然，如果你想要下载《傅里叶变换及其应用》可以把最后的调用改为：

if __name__ == '__main__':
    download_course(urls_iter('http://v.163.com/special/opencourse/fouriertransforms.html'),
                    '/Users/zealot/downloads/fouriertransforms')

效果不错~

-EOF-

Z的日志

Orin AGX 64G 中模型常驻指南

0 网络准备

1 NVIDIA工具

2 Docker

3 llama.cpp测试

4 llama.cpp部署中模型

5 LiteLLM模型汇聚网关

6 部署 Hermes

Pre-Requisites

安装 Hermes

附：Orin AGX 64G的PVE刷机指南：

新年要用新系统

0 备份

1 装系统

2 清理微软的垃圾

3 清理其他垃圾，装Windows下的常用工具

4 安装wsl2

5 初始化wsl2

5.1 关于yt-dlp

5.2 关于恢复备份的.ssh文件夹

5.3 关于nomachine

5.4 关于中文环境，上面装了字体和中文编码，需要配置语言环境：

5.5 关于starship

6 tailscale 与 ipv6

PVE装tailscale

全家搬到tailscale

6.1 tailscale可能存在的坑1 - 外带设备o6n回家后只能单向ping

6.1.1 现象

6.1.2 排查

6.1.3 原因

6.1.4 解决

6.1.5 进阶固化：使用 systemd 实现路由规则开机自启

Step 1: 编写路由修复脚本

Step 2: 编写 systemd 服务文件

Step 3: 激活服务并验证

6.2 tailscale可能存在的坑2 - 子网发布网关rock5b开启TUN导致tailscale无法链接

6.2.1 现象：

6.2.2 原因

6.2.3 解决

添加 Merge (合并) 路由规则

注：关于如何查找配置文件位置

Step1: 进程追踪

Step2: 分析追踪日志

7 self host atuin

8 启用 rock 5b 的 pwm

学习Widevine服务

了解Google Widevine

获取CDM Device验证文件

创建CDM设备

获取秘钥

解密多媒体文件

理解Transformer模型2：训练Transformer

1 Tokenizer

2 Dataset

3 Trainning Loop

4 Validation Loop

5 Attention Visualization

理解Transformer模型1：编写Transformer

1 Encoder

1.1 Input Embedding

1.2 Positional Encoding

1.3 Normaliation

1.4 Feed Forward

1.5 Multi-Head Attention

1.6 Residual Connection

1.7 Encoder Block

1.8 Encoder Module

2 Decoder

2.1 Decoder Block

2.2 Decoder Module

3 Linear & Softmax

4 Transformer

OpenAI API尝鲜

0x00 WSL中搭环境

0x01 策划

0x02 魔改

0x03 部署

0x04 后记

白嫖甲骨文云，但没有完全白嫖

5.1 关于`yt-dlp`

1) `T`只包含自有类型

2) 如果`T: 'static`，则`T`在程序整个生命周期都有效

3) `&'a T`与`T: 'a`是一回事