Hansen's ink

基于 Docker 的 MailServer 部署指南 (Gentoo Linux)

Thu, 16 Apr 2026 00:00:00 GMT

核心配置要点与规避事项

标准输出重定向 (Syslog 限制)： 容器环境通常缺失 syslog 进程。Postfix 与 Dovecot 的日志必须显式重定向至 /dev/stdout 或 /dev/stderr，以确保日志可通过 docker logs 捕获。
SSL 强制依赖检查： Dovecot 2.3+ 版本即使在 ssl = no 模式下，若配置文件中存在未注释的 ssl_cert 路径，仍会因检查证书文件失败而产生 Fatal 错误。
LMTP 端口非特权化： 为避免 Linux 容器对 1024 以下端口（特权端口）的权限限制或网络策略拦截，建议将内部 LMTP 投递端口由默认的 24 迁移至高位端口（如 2424）。
静态虚拟用户数据库 (Userdb Static)： 在使用 passwd-file 作为认证源时，userdb 应配置为 static 驱动。需显式指定 uid、gid 及 mail 路径格式，防止 Dovecot 自动探测机制在非标准环境下失效。

部署流程

环境说明：

宿主机： Gentoo Linux
基础镜像： Rocky Linux 9
数据根目录： /opt/mail_stack
示例域名： localhost.com

1. 宿主机环境初始化

配置数据持久化目录并统一 UID/GID 映射，确保容器内外文件系统访问权限一致。

# 停止宿主机冲突服务
/etc/init.d/postfix stop && rc-update del postfix default

# 初始化目录结构
mkdir -p /opt/mail_stack/{vmail,postfix_conf,dovecot_conf,users}

# 创建映射账号 (UID/GID 5000)
groupadd -g 5000 vmail
useradd -u 5000 -g vmail -s /sbin/nologin -d /opt/mail_stack/vmail vmail

# 配置权限
chown -R vmail:vmail /opt/mail_stack/vmail
chmod -R 770 /opt/mail_stack/vmail

# 配置初始用户凭据
cat << 'EOF' > /opt/mail_stack/users/passwd
guoy@localhost.com:{PLAIN}111111
wanghh@localhost.com:{PLAIN}111111
EOF
chmod 644 /opt/mail_stack/users/passwd

2. 提取基础配置文件

通过临时容器获取各组件的默认配置文件。

docker run --rm -v /opt/mail_stack/postfix_conf:/export rockylinux:9 \
  bash -c "dnf install -y postfix && cp -r /etc/postfix/* /export/"
docker run --rm -v /opt/mail_stack/dovecot_conf:/export rockylinux:9 \
  bash -c "dnf install -y dovecot && cp -r /etc/dovecot/* /export/"

3. Dovecot 配置优化

编辑 /opt/mail_stack/dovecot_conf/ 目录下的配置文件。

协议声明： dovecot.conf 头部添加 protocols = imap lmtp。
日志输出： conf.d/10-logging.conf 设置为标准流输出。
禁用 SSL： 在 conf.d/10-ssl.conf 中设置 ssl = no 并注释所有 ssl_cert 与 ssl_key 行。

LMTP 监听配置： 修改 conf.d/10-master.conf：

service lmtp {
  inet_listener lmtp {
    address = 0.0.0.0
    port = 2424
  }
}

认证策略： 重写 conf.d/10-auth.conf：

disable_plaintext_auth = no
auth_mechanisms = plain login
passdb {
  driver = passwd-file
  args = scheme=PLAIN username_format=%u /etc/dovecot/users/passwd
}
userdb {
  driver = static
  args = uid=5000 gid=5000 home=/var/vmail/%d/%n mail=maildir:/var/vmail/%d/%n
}

4. Postfix 路由配置

在 /opt/mail_stack/postfix_conf/main.cf 中追加或修改以下参数：

myhostname = mail.localhost.com
mydomain = localhost.com
myorigin = $mydomain
inet_interfaces = all
inet_protocols = ipv4
mynetworks = 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
virtual_mailbox_domains = localhost.com
virtual_transport = lmtp:inet:dovecot:2424
local_recipient_maps =

5. 容器构建与编排

Dockerfile.postfix:

FROM rockylinux:9
RUN dnf install -y postfix && dnf clean all
RUN postconf -e "maillog_file = /dev/stdout"
CMD ["postfix", "start-fg"]

Dockerfile.dovecot:

FROM rockylinux:9
RUN dnf install -y dovecot && dnf clean all
CMD ["dovecot", "-F"]

docker-compose.yml:

services:
  dovecot:
    build:
      context: .
      dockerfile: Dockerfile.dovecot
    container_name: mail_dovecot
    ports:
      - "143:143"
    volumes:
      - ./dovecot_conf:/etc/dovecot
      - ./vmail:/var/vmail
      - ./users:/etc/dovecot/users
    restart: always

  postfix:
    build:
      context: .
      dockerfile: Dockerfile.postfix
    container_name: mail_postfix
    ports:
      - "25:25"
    volumes:
      - ./postfix_conf:/etc/postfix
    depends_on:
      - dovecot
    restart: always

6. 服务验证

执行 docker-compose up -d --build 启动服务。

SMTP 投递测试： 使用 telnet 或 nc 连接宿主机 25 端口，通过 DATA 指令提交邮件。

文件系统验证： 检查 /opt/mail_stack/vmail/localhost.com/guoy/new/ 目录。若生成对应的邮件文件，则说明 Postfix (SMTP) 经由 LMTP 成功向 Dovecot 交付邮件。

企业内部RTL设计与验证的大规模语言模型本地化部署研究报告

Wed, 18 Mar 2026 00:00:00 GMT

传统的硬件描述语言（HDL）编写与验证流程正面临严峻挑战，开发周期的压缩与设计质量的提升成为企业生存的核心诉求。近年来，大语言模型（LLM）在软件工程领域的卓越表现，尤其是Cursor和Gemini等工具展示出的语义理解与代码生成能力，为 RTL 设计提供了新的技术路径。然而，芯片设计的核心在于知识产权（IP）的绝对安全，因此，构建一套性能比肩Cursor且能实现物理隔离、本地化部署的RTL辅助设计与验证体系，已成为半导体企业数字化转型的核心课题。

1. RTL大模型内核的选型与性能评估

构建本地化系统的首要任务是选择合适的基础模型。不同于通用编程模型，RTL设计要求模型对时序并发、时钟域交叉（CDC）、复位逻辑及硬件特有的语法约束有深层理解。

1.1 开源编程模型的竞争格局

目前的开源模型中，Qwen2.5-Coder、DeepSeek-Coder-V2和Llama 3.1系列处于第一梯队。Qwen2.5-Coder系列在5.5万亿token的多语言语料上进行了预训练，其32B版本在编程能力上被认为已达到GPT-4o的同等水平，支持高达128K的上下文窗口，能够覆盖中型SoC子系统的代码关联需求。DeepSeek-Coder-V2则采用了混合专家（MoE）架构，总参数量虽大，但单次推理激活的参数量（21B）较低，使其在保持高性能的同时显著降低了对计算资源的消耗。

| 模型名称 | 架构类型 | 训练Token量 | 支持语言数 | 上下文长度 | 核心优势 | | ----------------- | ------------ | --------------- | -------------- | -------------- | --------------------------------- | | Qwen2.5-Coder-32B | Dense | 5.5T | 40+ 主要语言 | 128k | 极强的代码修复与逻辑推理性能 | | DeepSeek-Coder-V2 | MoE | 10.2T | 338 | 128k | 极高的推理效率与广泛的语言支持 | | Llama 3.1-70B | Dense | 15T | 通用/代码 | 128k | 生态兼容性最强，推理稳定性高 | | StarCoder2-15B | Dense | 1T | 600+ | 16k | 针对库文件与Git提交信息有深度优化 |

1.2 硬件专用微调模型的崛起

通用模型虽然在语法上表现尚可，但在遵循硬件设计规范（如同步复位优先、避免锁存器推断）方面往往不及经过领域微调的模型。RTLCoder、CodeV和VeriCoder等模型通过在过滤后的高质量Verilog数据集（如VerilogDB）上进行监督微调（SFT），显著提升了功能正确性。以CodeV为例，该模型采用了“多级总结”策略，利用GPT-3.5对真实世界的RTL代码进行逆向描述生成，从而构建了高质量的“指令-代码”对。实验表明，CodeV在RTLLM基准测试中的表现优于GPT-4，展示了专用微调在解决硬件设计“幻觉”方面的巨大潜力。最新的研究如CodeV-R1，则进一步结合了DeepSeek-R1的推理链能力，通过强化学习（RL）引导模型在生成代码前进行逻辑思考，使其在复杂的协议实现任务中取得了突破。

1.3 基准测试与性能比对

评估本地模型在RTL任务中的实际效能，主要参考VerilogEval（侧重补全）和RTLLM（侧重合成与验证）。

| 模型/方法 | VerilogEval-Machine (Pass@1) | RTLLM v1.1 (Pass@1) | 资源需求 (4-bit) | | ------------------ | -------------------------------- | ----------------------- | -------------------- | | GPT-4o (云端基准) | 67.7% | 33.8% | N/A | | CodeV-R1-7B (本地) | 68.6% | 72.9% | ~6GB VRAM | | Qwen2.5-Coder-32B | 66.6% | 47.9% | ~20GB VRAM | | RTL-Coder-6.7B | 61.2% | 36.8% | ~6GB VRAM | | StarCoder2-15B | 37.8% | 15.5% | ~12GB VRAM |

数据表明，经过针对性RL训练的小参数模型（如7B量级）在特定硬件指标上已能超越通用巨量模型。这一发现为企业在有限资源下部署高性能AI助理提供了坚实的理论依据。

2. 企业级推理引擎后端建设

本地部署Cursor类体验的关键不仅在于模型，更在于能够支撑多用户并发请求、低延迟响应的推理后端。

2.1 主流推理后端的技术路线比对

企业在构建私有服务时，通常在vLLM、TensorRT-LLM和Ollama之间进行选择。

vLLM：是目前高吞吐量生产环境的事实标准。其核心贡献是PagedAttention（分页注意力）技术，该技术模仿操作系统的虚拟内存管理，将KV缓存（Key-Value Cache）切分为固定大小的页面，从而彻底解决了内存碎片化问题。在并发用户数超过10人时，vLLM的吞吐量可达Ollama的10倍以上。
TensorRT-LLM：作为NVIDIA官方推出的深度优化框架，其通过内核融合（Kernel Fusion）和FP8精度的原生支持，在NVIDIA硬件上能够榨取极致的推理速度。对于延迟极其敏感的实时代码补全任务，TensorRT-LLM相较于通用框架有20%-40%的性能领先。
Ollama：虽然其并发调度能力较弱，但其“Docker化”的部署体验极大地降低了原型开发难度。对于仅在个人工作站进行尝试的小型团队，Ollama通过集成llama.cpp，在单卡或CPU环境下展现了良好的兼容性。

2.2 显存需求与硬件拓扑设计

RTL任务的模型规模通常分布在7B到32B之间。为了在本地支撑Cursor的流畅感，推理显存的计算必须考虑模型权重、KV缓存和批处理余量。

| 模型规模 | 浮点精度 (FP16) 显存 | 量化精度 (INT4) 显存 | | ------------ | ------------------------ | ------------------------ | | 7B / 8B | ~14GB | ~4-6GB | | 14B / 20B | ~40GB | ~12-16GB | | 32B / 35B | ~64GB | ~20-24GB | | 70B+ | ~140GB | ~40-48GB |

对于需要服务多个并发会话的中央服务器，推荐采用多卡张量并行（Tensor Parallelism）架构。研究显示，使用H100 GPU配合vLLM或TensorRT-LLM，在FP8量化下可实现每秒数千个token的产出速率，确保在大型项目搜索或代码重构时，工程师无需长时间等待。

3. IDE层级的本地化集成方案

Cursor的成功在于其对编辑器上下文的深度集成。要实现这一体验，企业可以采用插件+私有后端的松耦合架构。

3.1 Continue.dev：万能本地连接器

Continue是一个开源的IDE插件（支持VS Code和JetBrains），被广泛视为 Cursor 的最佳本地化替代品。其允许开发者自定义模型路由，将不同的任务分发给不同的本地模型。

多模型协同架构：可以在config.json中配置：将轻量级模型（如Qwen2.5-Coder 1.5B/7B）分配给“tabAutocomplete”通道，以实现毫秒级的代码补全体验；而将推理能力更强的大模型（如Qwen2.5-Coder 32B或DeepSeek-R1 32B）分配给“chat”通道，处理复杂的逻辑问答和代码重构。
上下文增强：Continue支持通过@codebase或@docs指令引入项目上下文。在本地环境下，插件会自动通过嵌入模型（Embedding Model）为当前工作区建立索引，从而实现跨文件的语义跳转和IP复用分析。

3.2 Tabby与代码补全

Tabby是一个专为自托管设计的AI编程助手服务器。它集成了模型推理和向量数据库，能够对企业的整个代码仓进行全量索引。

Repository-Level RAG：不同于常规的文本切片，Tabby能理解Git仓库的层级结构。当工程师开始编写一个新的模块时，Tabby能检索出内部库中现有的例化（Instantiation）模板和时序逻辑参考，有效减少了重复劳动。
团队管控优势：作为中心化的服务端，Tabby便于合规团队进行单一入口审计，确保没有非授权的外部调用，同时可以根据不同部门的权限分发不同的代码索引库。

4. 针对硬件设计的检索增强生成（RAG）深度优化

通用的RAG技术在处理RTL代码和硬件规格书（Spec）时常因无法理解层级关系而失效。构建一套“EDA语义感知”的检索系统是本地部署成功的关键。

4.1 结构化硬件文档的解析策略

硬件文档包含大量表格（如寄存器表、引脚定义）和图表。传统的固定长度切片（Chunking）会撕裂语义。

层级感知解析：建议引入LlamaParse或Unstructured等工具，专门针对PDF中的章节层级（Section 3.1.2）进行树状存储。解析 Liberty（.lib）文件时，应将其转化为结构化的JSON，提取出每个标准单元（Standard Cell）的关键时序与功耗参数（如propagation delay, setup/hold time），以便LLM在进行PPA优化建议时能精准调用数据。
SDC约束的处理：时序约束文件（SDC）具有极强的逻辑关联性。应采用基于正则表达式与语义标签结合的方法，将create_clock与相关的set_false_path划归为同一知识单元。实验显示，结构化解析能将复杂查询的召回准确度从31%提升至79%。

4.2 知识图谱（KG）增强检索

硬件设计的本质是信号间的连通与反馈，这与图结构高度吻合。

VeriGRAG架构：该方案通过提取Verilog代码中的数据路径图（DPG），利用图神经网络（GNN）生成结构化嵌入。当工程师询问“信号A如何影响输出端B”时，系统不再仅仅寻找包含这两个名字的代码片段，而是通过图遍历（Traversal）找回真实的逻辑传播路径，极大地降低了LLM在解释复杂逻辑时的幻觉率。
混合检索机制：生产环境下可采用“向量搜索 + BM25关键字匹配”的混合模式。向量搜索负责捕捉语义意图（如“握手协议实现”），而BM25则确保诸如inst_reg_0_addr等具体的工程命名能够被精确命中。

5. 设计与验证的闭环自动化（Agentic Workflow）

Cursor的“效果好”不仅来自补全，还来自其尝试运行和纠错的能力。在本地环境中，这需要将LLM与既有的EDA工具链深度联动。

5.1 基于编译器反馈的自修复流

LLM生成的Verilog代码常含有微小的语法错误或非合成逻辑。

Verilator/VCS反馈环：建立一个多代理（Multi-agent）工作流。第一个Agent根据需求生成初始RTL代码；第二个Agent负责调用本地的Verilator进行静态语法检查；第三个Agent将编译器的错误日志（Log）重新喂回LLM进行修复。
Log2BetterRTL技术：研究表明，这种基于日志的闭环反馈能将语法正确率提升约18%，并显著减少Lint违规项（如阻塞/非阻塞赋值混用）。这种迭代修复的过程能在分钟级完成，替代了原本数小时的人工纠错。

5.2 验证套件的高效合成

验证工作量通常占整个芯片设计周期的60%-70%。

SVA断言生成：利用LLM从自然语言规格书中提取时序逻辑，并自动转换为SystemVerilog Assertions。例如，将“请求必须在2个时钟周期内得到确认”转换为property req_ack_p; @(posedge clk) req |-> ##[1:2] ack; endproperty。这种方式能将手工编写断言的工作量降低70%以上。
激励生成与覆盖率闭环：AI Agent可以根据功能描述自动生成UVM测试序列（Sequence），并根据上一次仿真运行的覆盖率报告（Coverage Report），自动生成能够触发冷门分支（Corner Cases）的随机测试向量。

5.3 synopsys eda 能力

6. 算力架构计算与显存模型建议

在多卡并行环境中，通信带宽往往比单核算力更关键。

6.1 并行计算策略

当模型参数超过单卡限制时（如部署70B规模的底座模型），必须采用并行技术。

张量并行（TP）：将模型的各层横向切割并分布在多个显卡上。这种方式最适合单节点内的多显卡环境，因为它对GPU间的互联带宽要求极高。建议利用NVLink提供的600GB/s或900GB/s双向带宽。
流水线并行（PP）：将模型的不同层纵向分布在不同节点。其带宽要求较低，但会产生计算空泡。在跨服务器集群部署时，这是扩展显存总容量的主要方式。

6.2 显存资源计算公式

为了确保模型在高负载下不发生OOM（内存溢出），需要精准计算显存消耗： $M_{total} = (P \times Q_{bytes} \times 1.2) + (Batch \times Context \times H_{dim} \times L_{layers} \times 2 / G)$ 其中：

P：模型参数量（如32B）。
Q_{bytes}：每参数字节数（4-bit量化约为0.5字节）。
1.2：框架与激活层冗余系数。
Batch：并发用户数。
Context：上下文窗口（如128k）。
G：GPU卡数。部分实际测试显示，利用4张A6000（每张显存48G）组成的192G显存池，可以非常从容地运行DeepSeek-Coder-V2（236B量级）的4-bit量化版，并同时支撑20名左右的工程师进行设计任务。综上所述，通过“强大的开源底座（Qwen/DeepSeek）+ 高并发推理引擎（vLLM）+ 深度IDE集成（Continue）+ 硬件感知RAG”的组合架构，企业完全可以在不牺牲安全性的前提下，获得比肩云端工具的生产力增益。这不仅是开发方式的升级，更是半导体企业在AI时代保护核心竞争力、加速芯片迭代周期的必然选择。

Mailman3 批量初始化用户与邮件列表

Fri, 20 Feb 2026 00:00:00 GMT

WEB 端批量注册用户

Mailman Web 默认用 django-allauth 做注册/邮箱验证。避免每个用户自己注册并点验证链接，最直接的是在 /opt/mailman/web/settings.py 里关掉验证。在 settings.py 里加入/修改：

# 关闭邮箱验证（最关键）
ACCOUNT_EMAIL_VERIFICATION = "none"

# 允许不验证也能登录（一般默认就是 True，但明确写上）
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_AUTHENTICATION_METHOD = "username_email"  # 你的版本若提示 deprecated 可忽略或按新项改

# 可选：如果你不希望开放自助注册，直接关掉注册入口（强烈建议内网这样做）
ACCOUNT_ALLOW_REGISTRATION = False   # 若版本不支持就用 URL/模板层面禁用 /accounts/signup/

在 /opt/mailman/web/scripts 下创建 create_web_users.py：

#!/opt/mailman/venv/bin/python
import os
import sys

# === Django bootstrap (must be BEFORE importing Django models) ===
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings")
sys.path.insert(0, "/opt/mailman/web")

import django
django.setup()

# === then import Django/allauth models ===
from django.contrib.auth import get_user_model
from django.db import transaction
from allauth.account.models import EmailAddress

PASSWORD = "111111"

emails = [
    "wanghh@example.com",
]

User = get_user_model()

created = 0
updated = 0

with transaction.atomic():
    for email in emails:
        email = email.lower().strip()
        username = email.split("@")[0]

        user, is_new = User.objects.get_or_create(
            username=username,
            defaults={"email": email, "is_active": True},
        )

        user.email = email
        user.is_active = True
        user.set_password(PASSWORD)
        user.save()

        ea, _ = EmailAddress.objects.get_or_create(
            user=user,
            email=email,
            defaults={"primary": True, "verified": True},
        )
        ea.primary = True
        ea.verified = True
        ea.save()

        if is_new:
            created += 1
        else:
            updated += 1

print(f"Web users done: created={created}, updated={updated}, total={len(emails)}")

随后使用虚拟环境的 python 运行：

/opt/mailman/venv/bin/python create_web_users.py

Mailman 3 创建 list 并添加订阅者

在 /opt/mailman/scripts 中创建 create_list.py：

#!/opt/mailman/venv/bin/python
# -*- coding: utf-8 -*-

"""
Create-or-update a Mailman3 list and batch-add members from member.txt.
Also ensures default owners are assigned.

Usage:
  /opt/mailman/venv/bin/python create_list.py dev
  /opt/mailman/venv/bin/python create_list.py dev --domain lists.example.com --members-file member.txt

Env (optional):
  MAILMAN_REST_URL   default: http://127.0.0.1:8001/3.1
  MAILMAN_REST_USER  default: restadmin
  MAILMAN_REST_PASS  default: restpass
"""

import argparse
import os
import sys
import time
from urllib.error import HTTPError

from mailmanclient import Client

DEFAULT_OWNERS = [
    "pengyq@example.com",
    "wangwy@example.com",
    "xiaorzh@example.com",
]


def read_emails(path: str) -> list[str]:
    emails: list[str] = []
    with open(path, "r", encoding="utf-8") as f:
        for line in f:
            s = line.strip()
            if not s or s.startswith("#"):
                continue
            emails.append(s)
    # 去重但保持顺序
    seen = set()
    out = []
    for e in emails:
        if e not in seen:
            seen.add(e)
            out.append(e)
    return out


def http_status(e: Exception) -> int | None:
    # urllib.error.HTTPError 有 code 字段
    return getattr(e, "code", None)


def get_or_create_domain(client: Client, domain: str):
    """
    Return domain proxy; create if not exists.
    """
    try:
        return client.get_domain(domain)
    except HTTPError as e:
        if http_status(e) == 404:
            try:
                client.create_domain(domain)
            except HTTPError as e2:
                # 可能域已存在：400 Duplicate email host / 409 Conflict
                if http_status(e2) not in (400, 409):
                    raise
            return client.get_domain(domain)
        raise


def robust_get_list(client: Client, list_id: str, retries: int = 3, sleep_s: float = 0.5):
    """
    After a create_list 500, the list may still have been created.
    Retry-get to confirm.
    """
    last = None
    for _ in range(retries):
        try:
            return client.get_list(list_id)
        except HTTPError as e:
            last = e
            if http_status(e) == 404:
                time.sleep(sleep_s)
                continue
            raise
    # retries exhausted
    if last:
        raise last
    raise RuntimeError("unexpected")


def get_or_create_list(client: Client, domain: str, local_part: str):
    """
    Return (mlist, created_bool)
    list_id in Mailman REST is typically "<local_part>.<domain>".
    """
    list_id = f"{local_part}.{domain}"

    # 先查是否存在
    try:
        mlist = client.get_list(list_id)
        return mlist, False
    except HTTPError as e:
        if http_status(e) != 404:
            raise

    # 不存在 -> 创建
    dom = get_or_create_domain(client, domain)

    try:
        mlist = dom.create_list(local_part)
        return mlist, True

    except HTTPError as e:
        # 关键：有时服务端返回 500，但 list 已写入 DB
        if http_status(e) == 500:
            # 再查一次确认是否已创建
            mlist = robust_get_list(client, list_id, retries=5, sleep_s=0.5)
            return mlist, True

        # 已存在/冲突等：再查一次兜底
        if http_status(e) in (400, 409):
            mlist = robust_get_list(client, list_id, retries=3, sleep_s=0.2)
            return mlist, False

        raise


def ensure_owners(mlist, owners: list[str]) -> tuple[int, int]:
    """
    Ensure owners are assigned. Returns (added, skipped).
    Uses role API mlist.add_owner(address).
    """
    added = 0
    skipped = 0
    for addr in owners:
        try:
            mlist.add_owner(addr)
            added += 1
        except HTTPError as e:
            if http_status(e) in (400, 409):
                skipped += 1
                continue
            raise
    return added, skipped


def add_members(mlist, members: list[str]) -> tuple[int, int]:
    """
    Subscribe members in batch. Returns (added, skipped).
    pre_verified/pre_confirmed/pre_approved 可以绕过每人单独确认/验证。
    """
    added = 0
    skipped = 0
    for addr in members:
        try:
            mlist.subscribe(
                addr,
                pre_verified=True,
                pre_confirmed=True,
                pre_approved=True,
            )
            added += 1
        except HTTPError as e:
            if http_status(e) in (400, 409):
                skipped += 1
                continue
            raise
    return added, skipped


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("listname", help="mailing list local-part (e.g. dev)")
    ap.add_argument("--domain", default="lists.example.com", help="mail host/domain (default: lists.example.com)")
    ap.add_argument("--members-file", default="member.txt", help="members file path (default: member.txt)")
    args = ap.parse_args()

    rest_url = os.getenv("MAILMAN_REST_URL", "http://127.0.0.1:8001/3.1")
    rest_user = os.getenv("MAILMAN_REST_USER", "restadmin")
    rest_pass = os.getenv("MAILMAN_REST_PASS", "restpass")

    client = Client(rest_url, rest_user, rest_pass)

    if not os.path.exists(args.members_file):
        print(f"[FATAL] members file not found: {args.members_file}", file=sys.stderr)
        sys.exit(2)

    members = read_emails(args.members_file)

    mlist, created = get_or_create_list(client, args.domain, args.listname)
    print(f"[OK] list: {mlist.fqdn_listname} (created={created})")

    a, s = ensure_owners(mlist, DEFAULT_OWNERS)
    print(f"[OK] owners ensured: added={a}, skipped(existing/dup)={s}")

    a, s = add_members(mlist, members)
    print(f"[OK] members subscribed: added={a}, skipped(existing/dup)={s}")

    print("[DONE]")


if __name__ == "__main__":
    main()

通过运行虚拟环境中的 python 来执行脚本：

/opt/mailman/venv/bin/python create_list.py "dev"

Mailman3 安装与部署

Thu, 19 Feb 2026 00:00:00 GMT

一、整体架构说明

Postfix  -->  Mailman Core  -->  HyperKitty (Archiver)
                  |
                  +--> REST API (8001)
                  |
                  +--> Postorius (Web 管理)

Mailman Core：负责邮件列表逻辑、投递、归档调度
Postorius：列表管理 Web UI
HyperKitty：邮件归档与 Web 展示
Mailman-Web：Django 项目，包含 Postorius + HyperKitty
Nginx：对外 Web 入口（8090）

关键端口规划

| 服务 | 端口 | 说明 | | :----------: | :--: | :---------: | | Mailman REST | 8001 | 仅本机访问 | | Mailman Web | 8000 | Gunicorn 内部 | | Nginx Web | 8090 | 对外访问 |

二、Mailman Core 安装

2.1 安装系统依赖（Rocky Linux 10）

sudo dnf update -y
sudo dnf install -y \
  git gcc make \
  python3 python3-devel python3-pip \
  libffi-devel openssl-devel \
  postfix \
  mariadb-connector-c-devel \
  nginx

说明：Mailman Core/ Web 都是 Python 项目；生产环境强烈建议用独立虚拟环境和专用系统用户。

2.2 创建专用用户与目录

sudo useradd -r -m -d /opt/mailman -s /sbin/nologin mailman
sudo mkdir -p /opt/mailman/{venv,core,web,var,logs,etc}
sudo chown -R mailman: mailman /opt/mailman

2.3 建虚拟环境

sudo -u mailman python3 -m venv /opt/mailman/venv
sudo -u mailman /opt/mailman/venv/bin/pip install -U pip wheel setuptools

clone 仓库再安装

sudo -u mailman git clone https://gitlab.com/mailman/mailman.git /opt/mailman/core
sudo -u mailman /opt/mailman/venv/bin/pip install -e /opt/mailman/core

Mailman Core 的安装与运行结构、命令行（mailman start|stop|shell）以官方安装文档为基准。

2.4 配置 Mailman Core（mailman. Cfg）

把主配置放到 /opt/mailman/etc/mailman.cfg（自建目录更清晰）。最终配置为：

[paths.custom]
var_dir: /opt/mailman/var

[mailman]
layout: custom
site_owner: wanghh@example.com
# Mailman 的 var_dir：队列、数据、生成的 postfix map 等

[mta]
incoming: mailman.mta.postfix.LMTP
outgoing: mailman.mta.deliver.deliver
# Postfix 投递给 Mailman 用 LMTP（推荐 8024 之类高端口）
lmtp_host: 127.0.0.1
lmtp_port: 8024

# Mailman 发信走 Postfix（本机 25）
smtp_host: 127.0.0.1
smtp_port: 25


[database]
# 生产强烈建议用 PostgreSQL
# 这里给 PostgreSQL 的写法示意：
class: mailman.database.postgresql.PostgreSQLDatabase
url: postgresql://mailman:123456@127.0.0.1:5432/mailman

[logging]
config: /opt/mailman/etc/logging.cfg

[rest]
username: restadmin
password: restpass

[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: /opt/mailman/etc/hyperkitty.cfg

此处应注意 var_dir: /opt/mailman/var ，设置为本地默认路径，避免路径错误。另外，直接运行 mailman 3 不要在 root 目录下，可能会是程序将当前路径加载进程序，导致权限问题或其他问题。

三、Mailman 3 与原有邮件服务器协同工作

Postfix / Dovecot 基于虚拟用户使用

3.1 整体架构

在 虚拟用户环境 下，正确的职责划分是：

外部邮件
   ↓
Postfix
   ├─ 普通邮箱（user@example.com） → virtual_mailbox_maps → Dovecot
   └─ 列表邮箱（list@lists.example.com）
         → transport_maps → lmtp:127.0.0.1:8024 → Mailman Core

用 transport_maps 把“列表域 / 列表地址”优先交给 Mailman
Mailman 自动生成 Postfix maps
Postfix 只“引用”这些 map，不自己维护列表

3.2 Mailman 3 生成 Postfix map

Mailman Core 在运行后，会在它的 var_dir 下生成 Postfix 可用的映射文件

在Mailman 侧：启用 Postfix MTA 接口

[mta]
incoming: mailman.mta.postfix.LMTP
outgoing: mailman.mta.deliver.deliver
# Postfix 投递给 Mailman 用 LMTP（推荐 8024 之类高端口）
lmtp_host: 127.0.0.1
lmtp_port: 8024

# Mailman 发信走 Postfix（本机 25）
smtp_host: 127.0.0.1
smtp_port: 25

然后确认 Mailman 正常运行后，生成了 map：

ls -l /opt/mailman/var/data/

total 72
-rw-rw----. 1 mailman mailman   349 Feb  3 10:42 postfix_domains
-rw-r-----. 1 mailman mailman 32768 Feb  3 10:42 postfix_domains.lmdb
-rw-rw----. 1 mailman mailman   988 Feb  3 10:42 postfix_lmtp
-rw-r-----. 1 mailman mailman 32768 Feb  3 10:42 postfix_lmtp.lmdb

如果这个目录不存在，说明 Mailman 还没真正启动成功。也可以指定生成 map 文件：

sudo -u mailman -H /opt/mailman/venv/bin/mailman -C /opt/mailman/etc/mailman.cfg aliases

Postfix 侧：正确引用 Mailman 生成的 map

在虚拟用户场景下：

virtual_mailbox_maps：只管真实邮箱
transport_maps：优先级更高，用来“劫持”列表地址
local_recipient_maps：要么关闭，要么确保不拒绝列表地址修改 Postfix /etc/postfix/main.cf 推荐配置

# for mailman
local_recipient_maps =                                                                 lmdb:/opt/mailman/var/data/postfix_lmtp,
	$alias_maps,
    lmdb:/etc/postfix/virtual-mailbox

relay_domains =                                                                        lmdb:/opt/mailman/var/data/postfix_domains
transport_maps =                                                                       lmdb:/opt/mailman/var/data/postfix_lmtp

在 Rocky/RHEL 系现在更推荐 lmdb:，而不是 hash:（db3/bdb 经常被拆包或默认不带）

生成 map

Mailman 生成的是 文本文件，Postfix 用时必须 postmap：

sudo postmap lmdb:/opt/mailman/var/data/postfix_domains
sudo postmap lmdb:/opt/mailman/var/data/postfix_lmtp

验证 Postfix transport 是否命中：

postmap -q lists.example.com /opt/mailman/var/data/postfix_domains

也可查看日志：

tail -f /var/log/maillog

systemd 管理 Mailman Core

创建 systemd unit：/etc/systemd/system/mailman.service

[Unit]
Description=GNU Mailman Core
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=mailman
Group=mailman
WorkingDirectory=/opt/mailman
Environment=HOME=/opt/mailman

# 关键：systemd 直接跟踪 master 进程
ExecStart=/opt/mailman/venv/bin/master -C /opt/mailman/etc/mailman.cfg

# 让 systemd 用 SIGTERM 停止（默认也是 SIGTERM）
ExecStop=/bin/kill -TERM $MAINPID

Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target

重载并重启：

sudo systemctl daemon-reload
sudo systemctl reset-failed mailman
sudo systemctl restart mailman
sudo systemctl status mailman --no-pager

四、部署 Mailman Web

Mailman Web 实际是一个 Django 项目，由三部分组成：

┌──────────────┐
│  Postorius   │  ← 列表管理 UI
├──────────────┤
│  HyperKitty  │  ← 邮件归档 UI
├──────────────┤
│ mailman-web  │  ← Django 项目本体
└──────┬───────┘
       │ REST
       ▼
┌──────────────────┐
│   Mailman Core   │  ← 你已经跑起来了
└──────────────────┘

4.1 安装 web

直接复用 /opt/mailman/venv，这样版本和依赖最干净。

sudo -u mailman -H /opt/mailman/venv/bin/pip install -U \
  mailman-web \
  postorius \
  hyperkitty
# 验证
sudo -u mailman -H /opt/mailman/venv/bin/pip show mailman-web postorius hyperkitty

创建 mailman-web Django 项目配置 1、创建配置目录

sudo mkdir -p /opt/mailman/web
sudo chown -R mailman:mailman /opt/mailman/web

sudo mkdir -p /opt/mailman/web/logs
sudo chown -R mailman:mailman /opt/mailman/web/logs
sudo chmod 750 /opt/mailman/web/logs

sudo mkdir -p /opt/mailman/var/logs
sudo chown -R mailman:mailman /opt/mailman/var/logs
sudo chmod 750 /opt/mailman/var/logs

2、生成默认 Django 配置 /opt/mailman/web/settings.py

# Mailman Web configuration (custom location)
from mailman_web.settings.base import *
from mailman_web.settings.mailman import *

# ---- Basic ----
DEBUG = False
ALLOWED_HOSTS = ["192.168.52.46", "127.0.0.1", "localhost"]
SECRET_KEY = "f1a3696c-961e-4133-ad1a-2c7fcb5e5722"

# --- static files ---
STATIC_URL = "/static/"
STATIC_ROOT = "/opt/mailman/web/static"

# 如果用 compressor offline，建议保留：
COMPRESS_OFFLINE = True

# ---- Database (建议单独建一个库) ----
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "mailmanweb",
        "USER": "mailman",
        "PASSWORD": "123456",
        "HOST": "127.0.0.1",
        "PORT": "5432",
    }
}

# ---- Connect to Mailman Core REST (与你 mailman.cfg 一致) ----
MAILMAN_REST_API_URL = "http://127.0.0.1:8001/"
MAILMAN_REST_API_VERSION = "3.1"
MAILMAN_REST_API_USER = "restadmin"
MAILMAN_REST_API_PASS = "restpass"


# 归档页面 URL
HYPERKITTY_URL = "http://127.0.0.1/hyperkitty/"
#HYPERKITTY_API_KEY = "59ebff6c-3f00-4991-8125-e3a3b28907c7"

MAILMAN_ARCHIVER_KEY = "59ebff6c-3f00-4991-8125-e3a3b28907c7"

CSRF_TRUSTED_ORIGINS = [
    "http://192.168.52.46:8090",
]

USE_X_FORWARDED_HOST = True
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'http')

ACCOUNT_DEFAULT_HTTP_PROTOCOL = "http"
CSRF_COOKIE_SECURE = False
SESSION_COOKIE_SECURE = False
CSRF_COOKIE_HTTPONLY = False

3、PostgreSQL 创建 mailmanweb 数据库（如果还没建）

sudo -u postgres psql -c "CREATE DATABASE mailmanweb OWNER mailman;"

4、初始化 Django（迁移 + 管理员 + 静态文件）后面所有命令都用同一个环境变量：

export MAILMAN_WEB_CONFIG=/opt/mailman/web/settings.py

迁移数据库

sudo -u mailman -H env MAILMAN_WEB_CONFIG=/opt/mailman/web/settings.py \
  /opt/mailman/venv/bin/mailman-web migrate

创建 Web 超级管理员

sudo -u mailman -H env MAILMAN_WEB_CONFIG=/opt/mailman/web/settings.py \
  /opt/mailman/venv/bin/mailman-web createsuperuser

收集静态文件：

sudo -u mailman -H \
  PYTHONPATH=/opt/mailman/web \
  DJANGO_SETTINGS_MODULE=settings \
  /opt/mailman/venv/bin/django-admin collectstatic

尝试运行：

sudo -u mailman -H \
  PYTHONPATH=/opt/mailman/web \
  DJANGO_SETTINGS_MODULE=settings \
  /opt/mailman/venv/bin/django-admin runserver 127.0.0.1:8000

5、用 gunicorn 跑 mailman-web（systemd）创建 systemd 服务文件 /etc/systemd/system/mailman-web.service

[Unit]
Description=Mailman3 Web (Postorius + HyperKitty) via Gunicorn
After=network.target

[Service]
Type=simple
User=mailman
Group=mailman
WorkingDirectory=/opt/mailman/web

Environment="PYTHONPATH=/opt/mailman/web"
Environment="DJANGO_SETTINGS_MODULE=settings"

# 如果 settings.py 里还保留了 MAILMAN_WEB_CONFIG 机制，不用也行；
# 但避免混乱，生产建议只用 DJANGO_SETTINGS_MODULE 即可。

ExecStart=/opt/mailman/venv/bin/gunicorn \
  --bind 127.0.0.1:8000 \
  --workers 3 \
  --timeout 120 \
  --access-logfile /opt/mailman/web/logs/gunicorn_access.log \
  --error-logfile /opt/mailman/web/logs/gunicorn_error.log \
  wsgi:application

Restart=on-failure
RestartSec=3

# 让 gunicorn 读到必要路径
UMask=0027

[Install]
WantedBy=multi-user.target

启动：

sudo systemctl daemon-reload
sudo systemctl enable --now mailman-web
systemctl status mailman-web --no-pager

4.2 Nginx 反向代理

创建 /etc/nginx/conf.d/mailman-web.conf：

server {
    listen 8090;
    server_name 192.168.52.46;

    # 静态文件（关键：解决样式简陋）
    location /static/ {
        alias /opt/mailman/web/static/;
        expires 7d;
        add_header Cache-Control "public";
    }

    # Web 反代（Postorius/HyperKitty）
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

重启 nginx ：

sudo nginx -t
sudo systemctl reload nginx

4 .3 HyperKitty 与 mailman 互通

Mailman 的配置文件需要配置 HyperKitty 信息，/opt/mailman/etc/mailman.cfg：

[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: /opt/mailman/etc/hyperkitty.cfg

其中，/opt/mailman/etc/hyperkitty.cfg 中内容为：

[general]
base_url: http://127.0.0.1:8090/hyperkitty/
api_key: 59ebff6c-3f00-4991-8125-e3a3b28907c7

Django 也需配置 /opt/mailman/web/settings.py：

# 归档页面 URL
HYPERKITTY_URL = "http://127.0.0.1/hyperkitty/"
#HYPERKITTY_API_KEY = "59ebff6c-3f00-4991-8125-e3a3b28907c7"

MAILMAN_ARCHIVER_KEY = "59ebff6c-3f00-4991-8125-e3a3b28907c7"

MySQL 自动备份脚本

Sun, 26 Oct 2025 00:00:00 GMT

1、数据库备份脚本

#!/usr/bin/env python3
"""
MySQL数据库自动备份脚本
支持定时备份、压缩、保留策略、日志记录
"""

import os
import sys
import subprocess
import datetime
import time
import gzip
import shutil
import logging
from logging.handlers import RotatingFileHandler
import json
import argparse
from pathlib import Path

class MySQLBackup:
    def __init__(self, config_file=None):
        # 默认配置
        self.config = {
            'mysql': {
                'host': 'localhost',
                'port': 3306,
                'user': 'root',
                'password': '123456',  # 建议使用配置文件或环境变量
                'database': 'fdmtek-aps'
            },
            'backup': {
                'backup_dir': '/data1/backups/mysql',
                'retention_days': 30,  # 保留30天
                'compress': False,
                'compress_level': 6,  # 压缩级别 1-9
                'timeout': 300  # mysqldump超时时间（秒）
            },
            'logging': {
                'log_file': '/var/log/mysql_backup.log',
                'log_level': 'INFO',
                'max_size_mb': 10,
                'backup_count': 5
            }
        }

		# 初始化日志
		self.setup_logging()

        # 加载配置文件
        if config_file and os.path.exists(config_file):
            self.load_config(config_file)

        # 检查必要工具
        self.check_prerequisites()

    def load_config(self, config_file):
        """加载配置文件"""
        try:
            with open(config_file, 'r', encoding='utf-8') as f:
                user_config = json.load(f)

            # 深度更新配置
            def deep_update(target, source):
                for key, value in source.items():
                    if key in target and isinstance(target[key], dict) and isinstance(value, dict):
                        deep_update(target[key], value)
                    else:
                        target[key] = value

            deep_update(self.config, user_config)
            self.logger.info(f"已加载配置文件: {config_file}")
        except Exception as e:
            self.logger.error(f"加载配置文件失败: {e}")
            raise

    def setup_logging(self):
        """设置日志系统"""
        log_config = self.config['logging']

        # 创建日志目录
        log_dir = os.path.dirname(log_config['log_file'])
        os.makedirs(log_dir, exist_ok=True)

        # 创建logger
        self.logger = logging.getLogger('MySQLBackup')
        self.logger.setLevel(getattr(logging, log_config['log_level']))

        # 清除已有的handler
        self.logger.handlers.clear()

        # 文件handler（滚动日志）
        file_handler = RotatingFileHandler(
            log_config['log_file'],
            maxBytes=log_config['max_size_mb'] * 1024 * 1024,
            backupCount=log_config['backup_count'],
            encoding='utf-8'
        )

        # 控制台handler
        console_handler = logging.StreamHandler()

        # 设置格式
        formatter = logging.Formatter(
            '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
            datefmt='%Y-%m-%d %H:%M:%S'
        )

        file_handler.setFormatter(formatter)
        console_handler.setFormatter(formatter)

        self.logger.addHandler(file_handler)
        self.logger.addHandler(console_handler)

    def check_prerequisites(self):
        """检查必要的工具是否安装"""
        required_tools = ['mysqldump', 'mysql']

        for tool in required_tools:
            try:
                subprocess.run(['which', tool], check=True, capture_output=True)
            except subprocess.CalledProcessError:
                self.logger.error(f"未找到必要工具: {tool}")
                raise RuntimeError(f"请先安装 {tool}")

        self.logger.info("所有必要工具已就绪")

    def create_backup_dir(self):
        """创建备份目录"""
        backup_dir = self.config['backup']['backup_dir']
        try:
            os.makedirs(backup_dir, exist_ok=True)
            self.logger.debug(f"备份目录: {backup_dir}")
            return backup_dir
        except Exception as e:
            self.logger.error(f"创建备份目录失败: {e}")
            raise

    def backup_database(self):
        """执行数据库备份"""
        mysql_config = self.config['mysql']
        backup_config = self.config['backup']

        # 创建备份目录
        backup_dir = self.create_backup_dir()

        # 生成备份文件名
        timestamp = datetime.datetime.now().strftime('%Y%m%d_%H%M%S')
        backup_file = os.path.join(
            backup_dir,
            f"{mysql_config['database']}_{timestamp}.sql"
        )

        # 构建mysqldump命令
        cmd = [
            'mysqldump',
            '--single-transaction',
            '--routines',
            '--triggers',
            '--events',
            '--add-drop-database',
            '--databases', mysql_config['database'],
            '--host', mysql_config['host'],
            '--port', str(mysql_config['port']),
            '--user', mysql_config['user'],
            '--result-file', backup_file
        ]

        # 添加密码（安全方式）
        env = os.environ.copy()
        if mysql_config['password']:
            env['MYSQL_PWD'] = mysql_config['password']

        try:
            self.logger.info(f"开始备份数据库: {mysql_config['database']}")
            self.logger.debug(f"备份命令: {' '.join(cmd)}")

            # 执行备份
            start_time = time.time()
            result = subprocess.run(
                cmd,
                env=env,
                capture_output=True,
                text=True,
                timeout=backup_config['timeout']
            )

            elapsed_time = time.time() - start_time

            if result.returncode != 0:
                self.logger.error(f"备份失败: {result.stderr}")
                return False

            # 检查备份文件
            if not os.path.exists(backup_file):
                self.logger.error("备份文件未生成")
                return False

            file_size = os.path.getsize(backup_file)
            self.logger.info(f"备份成功: {backup_file} ({file_size / 1024:.2f} KB)")
            self.logger.info(f"备份耗时: {elapsed_time:.2f}秒")

            # 压缩备份文件
            if backup_config['compress']:
                backup_file = self.compress_backup(backup_file, backup_config['compress_level'])

            # 清理旧备份
            self.clean_old_backups(backup_dir)

            return backup_file

        except subprocess.TimeoutExpired:
            self.logger.error("备份操作超时")
            return False
        except Exception as e:
            self.logger.error(f"备份过程中发生错误: {e}")
            return False

    def compress_backup(self, backup_file, compress_level=6):
        """压缩备份文件"""
        try:
            compressed_file = f"{backup_file}.gz"

            self.logger.info(f"开始压缩备份文件: {backup_file}")

            with open(backup_file, 'rb') as f_in:
                with gzip.open(compressed_file, 'wb', compresslevel=compress_level) as f_out:
                    shutil.copyfileobj(f_in, f_out)

            # 删除原始文件
            os.remove(backup_file)

            # 计算压缩比
            original_size = os.path.getsize(compressed_file)
            self.logger.info(f"压缩完成: {compressed_file}")

            return compressed_file

        except Exception as e:
            self.logger.error(f"压缩备份文件失败: {e}")
            return backup_file

    def clean_old_backups(self, backup_dir):
        """清理旧的备份文件"""
        retention_days = self.config['backup']['retention_days']
        cutoff_time = time.time() - (retention_days * 24 * 3600)

        try:
            deleted_files = []
            for item in os.listdir(backup_dir):
                item_path = os.path.join(backup_dir, item)

                # 只处理备份文件
                if not (item.startswith(self.config['mysql']['database']) and
                       (item.endswith('.sql') or item.endswith('.sql.gz'))):
                    continue

                # 检查文件时间
                if os.path.getmtime(item_path) < cutoff_time:
                    os.remove(item_path)
                    deleted_files.append(item)

            if deleted_files:
                self.logger.info(f"已清理过期备份文件: {len(deleted_files)}个")
                self.logger.debug(f"清理的文件: {', '.join(deleted_files)}")

        except Exception as e:
            self.logger.error(f"清理旧备份失败: {e}")

    def test_mysql_connection(self):
        """测试MySQL连接"""
        mysql_config = self.config['mysql']

        cmd = [
            'mysql',
            '--host', mysql_config['host'],
            '--port', str(mysql_config['port']),
            '--user', mysql_config['user'],
            '--execute', 'SELECT 1'
        ]

        env = os.environ.copy()
        if mysql_config['password']:
            env['MYSQL_PWD'] = mysql_config['password']

        try:
            result = subprocess.run(
                cmd,
                env=env,
                capture_output=True,
                text=True
            )

            if result.returncode == 0:
                self.logger.info("MySQL连接测试成功")
                return True
            else:
                self.logger.error(f"MySQL连接测试失败: {result.stderr}")
                return False

        except Exception as e:
            self.logger.error(f"MySQL连接测试异常: {e}")
            return False

    def list_backups(self):
        """列出所有备份文件"""
        backup_dir = self.config['backup']['backup_dir']

        if not os.path.exists(backup_dir):
            self.logger.warning("备份目录不存在")
            return []

        backups = []
        for item in sorted(os.listdir(backup_dir)):
            item_path = os.path.join(backup_dir, item)
            if os.path.isfile(item_path) and item.startswith(self.config['mysql']['database']):
                stat = os.stat(item_path)
                backups.append({
                    'name': item,
                    'size': stat.st_size,
                    'mtime': datetime.datetime.fromtimestamp(stat.st_mtime),
                    'path': item_path
                })

        return backups

def main():
    parser = argparse.ArgumentParser(description='MySQL数据库备份工具')
    parser.add_argument('--config', '-c', default='config.json',
                       help='配置文件路径 (默认: config.json)')
    parser.add_argument('--test', action='store_true',
                       help='测试MySQL连接')
    parser.add_argument('--list', action='store_true',
                       help='列出所有备份文件')
    parser.add_argument('--run', action='store_true',
                       help='立即执行备份')
    parser.add_argument('--daemon', action='store_true',
                       help='以守护进程方式运行，按配置定时备份')

    args = parser.parse_args()

    try:
        backup = MySQLBackup(args.config)

        if args.test:
            backup.test_mysql_connection()
        elif args.list:
            backups = backup.list_backups()
            if backups:
                print(f"\n找到 {len(backups)} 个备份文件:")
                print("-" * 80)
                for b in backups:
                    print(f"{b['mtime']:%Y-%m-%d %H:%M:%S} | "
                          f"{b['size']/1024:8.1f} KB | {b['name']}")
            else:
                print("未找到备份文件")
        elif args.run:
            result = backup.backup_database()
            if result:
                print(f"备份成功: {result}")
            else:
                print("备份失败，请查看日志")
                sys.exit(1)
        elif args.daemon:
            print("守护进程模式，请使用systemd或cron进行定时执行")
            # 这里可以添加循环等待逻辑，但建议使用系统定时任务
        else:
            parser.print_help()

    except Exception as e:
        print(f"程序执行失败: {e}")
        sys.exit(1)

if __name__ == "__main__":
    main()

2、配置文件 `config.json`

{
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "123456",
    "database": "fdmtek-aps"
  },
  "backup": {
    "backup_dir": "/data1/backups/mysql",
    "retention_days": 30,
    "compress": true,
    "compress_level": 6,
    "timeout": 600
  },
  "logging": {
    "log_file": "/var/log/mysql_backup.log",
    "log_level": "INFO",
    "max_size_mb": 10,
    "backup_count": 5
  }
}

3、验证脚本 `verify_backup.py`

#!/usr/bin/env python3
import subprocess
import sys
import os

def verify_backup(backup_file):
    """验证备份文件"""
    if backup_file.endswith('.gz'):
        cmd = f"gzip -t {backup_file}"
    else:
        # 检查SQL文件格式
        cmd = f"head -n 10 {backup_file} | grep 'MariaDB dump'"

    result = subprocess.run(cmd, shell=True, capture_output=True)
    return result.returncode == 0

if __name__ == "__main__":
    if len(sys.argv) > 1:
        backup_file = sys.argv[1]
        if verify_backup(backup_file):
            print(f"✓ 备份文件有效: {backup_file}")
        else:
            print(f"✗ 备份文件损坏: {backup_file}")
            sys.exit(1)
    else:
        print("使用方法: python verify_backup.py <backup_file>")

4、使用说明

# 1. 修改config.json中的数据库配置
# 2. 创建备份目录
sudo mkdir -p /data/backups/mysql
sudo chmod 755 /data/backups/mysql

# 3. 测试连接
python3 mysql_backup.py --config config.json --test

# 4. 手动执行一次备份
python3 mysql_backup.py --config config.json --run

服务器定时执行脚本：

# 编辑crontab
crontab -e

# 添加以下内容，每天凌晨2点执行备份
0 2 * * * /usr/bin/python3 /data1/backups/mysql_backup/mysql_backup.py --config /data1/backups/mysql_backup/config.json --run >> /var/log/mysql_backup_cron.log 2>&1

# 查看crontab
crontab -l

Gerrit 使用

Tue, 12 Aug 2025 00:00:00 GMT

介绍

关于Gerrit

Gerrit，一种开放源代码的代码审查软件，使用网页界面。利用网页浏览器，同一个团队的程序员，可以相互审阅彼此修改后的代码，决定是否能够提交，退回或是继续修改。它使用版本控制系统Git作为底层。

定位

理论上Git虽然是一个分布式版本管理系统，不需要中心代码库就能相互同步数据。而在实际的操作过程中，为了方便一个团队的多名开发人员通常需要指定一个确定的代码库用于提交和相互同步代码。所以我们的代码管理一般使用如下结构：

在引入Gerrit代码审核机制后，我们的代码提交和同步的方式发生了变化：

工作流程

首先贡献者的代码通过 git 命令推送到 Gerrit 管理下的 Git 版本库，推送的提交转化为一个一个的代码审核任务，审核任务可以通过 refs/changes/下的引用访问到。代码审核者可以通过 Web 界面查看审核任务、代码变更，通过 Web 界面做出通过代码审核或者打回等决定。测试者也可以通过 refs/changes/引用获取（fetch）修订对其进行测试，如果测试通过就可以将该评审任务设置为校验通过（verified）。最后经过了审核和校验的修订可以通过 Gerrit 界面中提交动作合并到版本库对应的分支中。在 Android 项目的网站的代码贡献流程图更为详细的介绍了 Gerrit 代码审核服务器的工作流程。

用户登录

首先打开主页 http://192.168.51.201:81

主页会提示登录：

其中用户名与密码皆与邮箱账号名相同，如：

username ：wanghh
password : 111111

登录后的界面如下：

简单入手

克隆代码仓库

进行代码修改、提交审查，显然第一步是要从远程代码库中克隆一份代码。Gerrit服务提供了HTTP和SSH两种服务（使用SSH协议需要配置本机密钥）供大家从远程服务器获取代码，获取方式可在项目基本信息页面查看。

其中 clone 命令有两种类型：

1. 命令含 `commit-msg hook`

git clone "http://wanghh%40fdmtek.com@192.168.52.46:8088/a/gerrit-base" \
&& (cd "gerrit-base" && mkdir -p `git rev-parse --git-dir`/hooks/ \
&& curl -Lo `git rev-parse --git-dir`/hooks/commit-msg http://192.168.52.46:8088/tools/hooks/commit-msg \
&& chmod +x `git rev-parse --git-dir`/hooks/commit-msg)

功能：

克隆仓库：首先，通过 git clone 命令从 Gerrit 服务器克隆 gerrit-base 仓库。
设置 commit-msg hook：
- 进入克隆的 Git 仓库目录 gerrit-base。
- 创建一个 Git Hooks 的目录：GIT_DIR/hooks/。（GIT_DIR 是 Git 的 .git 文件夹路径，由 git rev-parse --git-dir 获取）。
- 下载 commit-msg hook：使用 curl 从服务器地址 http://192.168.52.46:8088/tools/hooks/commit-msg 获取文件。
- 添加执行权限：对下载的 commit-msg 文件运行 chmod +x。

作用：

commit-msg hook 是 Gerrit 为 Git 提供的一种工具：

检查提交的消息是否符合 Gerrit 的要求。
在提交消息中自动添加 Change-Id，这是 Gerrit 用于跟踪代码变更的标识符。
没有该 hook 时，手动提交可能会报错或不符合 Gerrit 的提交规范。

这个命令适用于需要 Gerrit Change-Id 参与代码审查的用户，例如提交代码到 Gerrit 时必须满足其 Change-Id 要求。

2. 命令不含 `commit-msg hook`

git clone "http://wanghh%40fdmtek.com@192.168.52.46:8088/a/gerrit-base"

功能：

此命令只是简单地克隆了指定的仓库 gerrit-base。
克隆后的仓库没有额外设置 commit-msg hook，意味着使用默认的 Git 操作。

作用：

适合仅用于拉取代码或进行简单的本地修改，而不提交代码到 Gerrit。
如果用户计划把修改提交到 Gerrit，则可能会缺少 Change-Id，因此 Gerrit 后续可能拒绝提交。

HTTP 使用需要申请 Token 用于验证

同时可以顺便验证一下邮箱（重要！）

➜  git_test git clone "http://wanghh%40fdmtek.com@192.168.52.46:8088/a/gerrit-base" && (cd "gerrit-base" && mkdir -p `git rev-parse --git-dir`/hooks/ && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg http://192.168.52.46:8088/tools/hooks/commit-msg && chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
Cloning into 'gerrit-base'...
Password for 'http://wanghh%40fdmtek.com@192.168.52.46:8088':
remote: Counting objects: 2, done
remote: Finding sources: 100% (2/2)
Receiving objects: 100% (2/2), 197 bytes | 197.00 KiB/s, done.
remote: Total 2 (delta 0), reused 0 (delta 0)
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  3127  100  3127    0     0  1737k      0 --:--:-- --:--:-- --:--:-- 3053k
➜  git_test cd gerrit-base
➜  gerrit-base git:(master) git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

仓库 clone 完成之后就可以进行后续的操作：

➜  gerrit-base git:(master) ✗ git add .
➜  gerrit-base git:(master) ✗ git commit -m "v0.0.1"
[master 8d921fc] v0.0.1
 1 file changed, 1 insertion(+)
 create mode 100644 test.txt
➜  gerrit-base git:(master) git push
Password for 'http://wanghh%40fdmtek.com@192.168.52.46:8088':
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Writing objects: 100% (3/3), 274 bytes | 274.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
remote: error: branch refs/heads/master:
remote: Push to refs/for/master to create a review, or get 'Push' rights to update the branch.
remote: User: wanghh@fdmtek.com
remote: Contact an administrator to fix the permissions
remote: Processing changes: refs: 1, done
To http://192.168.52.46:8088/a/gerrit-base
 ! [remote rejected] master -> master (prohibited by Gerrit: not permitted: update)
error: failed to push some refs to 'http://192.168.52.46:8088/a/gerrit-base'

此时需要的密码依然是之前生成的 Token，但是可以发现 Push 操作被拒绝了。这是因为仓库中的权限没有开放，并且通常无法直接 push 到 master，需要首先 push 到 gerrit 的分支上，如 refs/for/master

此时，我们就可以进行提交了

➜  gerrit-base git:(master) git push origin HEAD:refs/for/master
Password for 'http://wanghh%40fdmtek.com@192.168.52.46:8088':
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Writing objects: 100% (3/3), 274 bytes | 274.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Processing changes: refs: 1, new: 1, done
remote:
remote: SUCCESS
remote:
remote:   http://192.168.52.46:8088/c/gerrit-base/+/1 v0.0.1 [NEW]
remote:
To http://192.168.52.46:8088/a/gerrit-base
 * [new reference]   HEAD -> refs/for/master

提交成功之后就可以在gerrit中看到变化：

可以看到当前是不满足 submit 条件的。需要进行 Review 与 Verify。

审查代码

默认情况下项目的所有者、管理员能够指定代码的审核人。指定审核人后，Gerrit会给审核人发送邮件提醒有审核任务。

审核代码的流程：

浏览代码增量，并给出注释;
浏览完成所有代码，并给出综合评价和评分(-2, -1, 0, 1, 2)。只有打分>2，才能允许merge到目标分支。

这个时候，我们想起允哥说有空的时候就可以想起他：

此时，电脑另一端的允哥也就收到了干活的消息：

允哥打开 gerrit 后，也看到新的 commit

随后允哥觉得小伙子写的很不错！

但是这时高老爷也过来看了一下，说小伙子菜还得多练啊

返工修改

根据上面Gerrit流程图，当代码审核、确认未通过或合并的过程中出现冲突，这个时候就需要返工修改后再提交。

返工流程有三步：

获取未通过的代码到本地工作目录；
修改代码；
再提交审核。

修改好代码之后我们再次提交

➜  gerrit-base git:(master) ✗ git add .
➜  gerrit-base git:(master) ✗ git commit --amend
[master 2a84938] v0.0.1
 Date: Fri Jan 9 14:14:47 2026 +0800
 1 file changed, 3 insertions(+)
 create mode 100644 test.txt

// push patch set
➜  gerrit-base git:(master) git push origin HEAD:refs/for/master
Password for 'http://wanghh%40fdmtek.com@192.168.52.46:8088':
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Writing objects: 100% (3/3), 301 bytes | 301.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Processing changes: refs: 1, updated: 1, done
remote:
remote: SUCCESS
remote:
remote:   http://192.168.52.46:8088/c/gerrit-base/+/1 v0.0.1
remote:
remote: The following approvals got outdated and were removed:
remote: * Code-Review+1 by guoy@fdmtek.com
remote: * Code-Review+1 by wanghh@fdmtek.com
remote:
remote:
To http://192.168.52.46:8088/a/gerrit-base
 * [new reference]   HEAD -> refs/for/master

修改后的提交，change-id不会发生变化，而仅仅是patch-id加1。

这一次，高老爷也满意了。至此，我们完成了代码的 Review。

验证修改

新提交的修改，如果已经通过代码审核，下一步流程则是代码验证。验证之前需要代码测试人员先将修改获取到本地，然后对代码进行测试。代码测试后，则投票对本次修改做出评价。

提交修改

当代码成功通过Review和Verified后，此时这段修改后的代码片段就可以合并到主分支里面去了。

这时候，高老爷动了动小手：

代码这时真正被同步到了 master 分支中。

查看官方文档了解更多

另：

Gerrit 的 HTTP 验证通常依赖外部的反向代理来处理用户的认证，客户端通过浏览器发送 HTTP basic authentication 的头部信息来完成验证。因此：

用户的登录状态由浏览器缓存的 Basic Authentication 凭据维持，不存储在 Gerrit 中。
用户点击 Sign out 后，Gerrit 本身无法清除浏览器上缓存的凭据。
此外，现代浏览器的 HTTP Basic Auth 无法通过 JS 或页面行为主动触发清理，退出登录变得较为困难。

**即：*浏览器缓存了 Basic Authentication 凭证，*即使点击了 Sign out，浏览器依然用之前缓存的凭据重新发送认证请求，导致用户无法登出。

基于较新的火狐内核支持特定形式的 URL 处理，因此通过反代的配置修改能够清除缓存的 HTTP Basic Authentication 会话，解决此问题。但是基于 chromium 内核的浏览器可能会依然存在这个问题，如果你拒绝使用火狐且坚持需要退出用户登录的话，请自行清理浏览器缓存记录。

Gerrit 安装

Mon, 11 Aug 2025 00:00:00 GMT

安装

安装 JDK

Gerrit 基于 Java 开发，因此依赖 JAVA 的运行环境，当前最新 3.13 版本要求至少 Java 21。因此需要先安装 JRE。

# 创建jdk存放目录
mkdir /usr/local/java

# 将压缩包解压到上述目录当中
tar -zxvf jdk-21_linux-64_bin.tar.gz -C /usr/local/java

# 创建软连接
# 需要先删除系统可能自带的软连接
# 然后重新创建 java 软链接到 /usr/bin/ 目录下
ln -s /usr/local/java/jdk-21.0.5/ /usr/bin/java

# 编辑系统配置文件
em /etc/profile

# 输入以下内容
export JAVA_HOME=/usr/bin/java
export PATH=$JAVA_HOME/bin:$PATH

# 激活配置文件
source /etc/profile

java --version

安装 Gerrit

Gerrit 账号创建并使用：

sudo adduser gerrit

sudo su gerrit
cd /home/gerrit

Gerrit 安装

java -jar gerrit-3.10.1.war init -d /home/gerrit

安装时初始参数：

Auth 方式输入 HTTP，并使用反向代理；

Plugin 插件都选 y

配置用户：

htpasswd -c /home/gerrit/gerrit/etc/gerrit.password admin     # 创建第一个用户admin，同时会生成一个gerrit.password文件
htpasswd -m /home/gerrit/gerrit/etc/gerrit.password user1     # 在gerrit.password增加用户用 -m

此时 gerrit/etc/gerrit.conf 配置如下：

[gerrit]
        basePath = git
        canonicalWebUrl = <http://192.168.52.46:8088>
        serverId = 3d9af676-03aa-4cc6-a75c-98d76682443e
[container]
        javaOptions = "-Dflogger.backend_factory=com.google.common.flogger.backend.log4j.Log4jBackendFactory#getInstance"
        javaOptions = "-Dflogger.logging_context=com.google.gerrit.server.logging.LoggingContext#getInstance"
        user = gerrit
        javaHome = /usr/local/java/jdk-25.0.1
[index]
        type = lucene
[auth]
        type = HTTP
        userNameCaseInsensitive = true
[receive]
        enableSignedPush = false
[sendemail]
        smtpServer = 192.168.52.46
        smtpServerPort = 25
        smtpUser = gerrit
[sshd]
        listenAddress = *:29418
[httpd]
        listenUrl = proxy-http://*:8088/
[cache]
        directory = cache

配置反向代理

设置 nginx

em /etc/nginx/conf.d/gerrit.conf

server {
    listen 81;            # 代理监听81端口
    server_name 192.168.52.46;

    auth_basic "Welcome to Gerrit Code Review Site!";
    auth_basic_user_file /home/gerrit/gerrit/etc/gerrit.password;       # 代理使用 gerrit.password
    location / {
        proxy_pass  <http://192.168.52.46:8088>;        # 代理指向gerrit本地服务url,这个url要和gerrit.config中的canonicalWebUrl相同
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header Cache-Control "no-store";
        proxy_set_header Pragma "no-cache";
        proxy_set_header Expires "-1";
    }

    location = /logout {
        return 302 <http://logout:logout@192.168.52.46:81/>;
    }

}

其中

location = /logout {
        return 302 <http://logout:logout@192.168.52.46:81/>;
}

这一部分是因为：

Gerrit 的 HTTP 验证通常依赖外部的反向代理（如 Nginx、Apache）来处理用户的认证，客户端通过浏览器发送 HTTP basic authentication 的头部信息（Authorization: Basic <credentials>）来完成验证。

HTTP 验证的特点是：

用户的登录状态由浏览器缓存的 Basic Authentication 凭据维持，不存储在 Gerrit 中。
用户点击 Sign out 后，Gerrit 本身无法清除浏览器上缓存的凭据。
此外，现代浏览器的 HTTP Basic Auth 无法通过 JS 或页面行为主动触发清理，退出登录变得较为困难。

**浏览器缓存了 Basic Authentication 凭证，**即使点击了 Sign out，浏览器依然用之前缓存的凭据重新发送认证请求，导致用户无法登出。

基于火狐内核的解决方案：

浏览器会对包含 logout:logout@ 这样形式的 URL 自动处理，直接向目标服务器发送带有 Authorization 头的请求。
因为提供的用户名和密码（logout:logout）在服务器端被拒绝，导致浏览器认为当前凭据已经失效，从而清除缓存的 HTTP Basic Authentication 会话。

KLEE 使用

Wed, 11 Jun 2025 00:00:00 GMT

使用

klee因为其复杂性，依赖比较多。除了llvm,cmake之类的通用依赖之外，还需要为其编译SAT求解器minisat和SMT求解器stp。因此为了简洁使用，可以通过官方提供的docker来使用，通过以下命令即可使用。

docker run -ti --name=my_first_klee_container --ulimit='stack=-1:-1' klee/klee:3.0

docker start -aiklee_container

KLEE 在 LLVM 位码上运行。要使用 KLEE 运行程序，首先使用将其编译为 LLVM 位码clang -emit-llvm。

clang -I ../klee_build/include -emit-llvm -g -O0 -Xclang -disable-O0-optnone -c test.c -o test.bc

运行 KLEE

要在位码文件上运行 KLEE，只需执行：

$ klee get_sign.bc

应该看到类似以下输出：

KLEE: output directory = "klee-out-0"

KLEE: done: total instructions = 33
KLEE: done: completed paths = 3
KLEE: done: partially completed paths = 0
KLEE: done: generated tests = 3

$ ls klee-last/
assembly.ll      run.istats       test000002.ktest
info             run.stats        test000003.ktest
messages.txt     test000001.ktest warnings.txt

KLEE 生成的测试用例

KLEE 生成的测试用例被写入名为.ktest扩展的文件中。这些是二进制文件，可以使用_ktest-tool_实用程序读取。ktest -tool_输出同一对象的不同表示形式，例如 Python 字节字符串（数据）、整数（int）或 ascii 文本（text）。

$ ktest-tool klee-last/test000001.ktest
ktest file : 'klee-last/test000001.ktest'
args       : ['get_sign.bc']
num objects: 1
object 0: name: 'a'
object 0: size: 4
object 0: data: b'\x00\x00\x00\x00'
object 0: hex : 0x00000000
object 0: int : 0
object 0: uint: 0
object 0: text: ....

执行测试用例

虽然我们可以手动（或借助现有测试基础架构）在程序上运行 KLEE 生成的测试用例，但 KLEE 提供了一个方便的重放库，它只是将对的调用替换klee_make_symbolic为对函数的调用，该函数将存储在文件中的值分配给我们的输入.ktest。要使用它，只需将程序与libkleeRuntest库链接起来，并将环境变量设置KTEST_FILE为指向所需测试用例的名称。

$ export LD_LIBRARY_PATH=path-to-klee-build-dir/lib/:$LD_LIBRARY_PATH
$ gcc -I ../../include -L path-to-klee-build-dir/lib/ get_sign.c -lkleeRuntest
$ KTEST_FILE=klee-last/test000001.ktest ./a.out
$ echo $?
0
$ KTEST_FILE=klee-last/test000002.ktest ./a.out
$ echo $?
1
$ KTEST_FILE=klee-last/test000003.ktest ./a.out
$ echo $?
255

KLEE 的符号执行引擎确实支持浮点数（如 float 和 double 类型），但是其处理能力是有限的。KLEE 原生并不完全支持浮点数的符号执行，尤其是在精确度和操作的复杂度上，可能会遇到一些困难。这是因为符号执行主要设计时主要针对整数类型的符号执行进行了优化，而浮点数涉及的数值范围、舍入误差等问题，使得其符号执行变得更加复杂。

KLEE 对浮点数的处理

符号执行支持： KLEE 确实能够进行浮点数的符号执行，但在浮点数计算时，其对某些操作（如浮点比较、算术运算等）可能没有与整数运算一样的精确支持。这意味着 KLEE 在遇到浮点数时可能无法像处理整数那样精确地模拟计算过程，特别是在符号约束（symbolic constraints）和符号路径（symbolic path）上。
浮点数具体化（Concretization）：如果 KLEE 遇到无法精确符号执行的浮点数表达式，它通常会将浮点数的值“具体化”为一个常数（如 0）。例如，如果代码中涉及到浮点数的算术运算或比较，KLEE 可能会将浮点数的值设置为一个默认的数值（通常是 0），以避免符号执行失败。
浮点数操作的精度问题：浮点数计算涉及舍入误差和精度问题，这对于符号执行来说是一个挑战。KLEE 在浮点数计算时可能无法精确模拟这些操作，尤其是对于复杂的浮点数函数（如三角函数、对数等）来说，符号执行的表现可能不如整数。
浮点数的优化和支持： KLEE 团队已经进行了一些优化，尤其是在浮点数符号执行方面。具体来说，KLEE 使用了一个叫 SymFPU 的浮点数支持库，来改进对浮点数操作的处理。SymFPU 是一个专门用于浮点数符号执行的模块，它能够处理浮点数的符号执行，尤其是在有限的操作和函数支持上有所改进。

软件测试

Wed, 04 Jun 2025 00:00:00 GMT

单元测试

Gcov是一个测试覆盖程序，是集成在GCC中的，随GCC一起发布。

基本概念

基本块BB

基本块指一段程序的第一条语句被执行过一次后，这段程序中的每一跳语句都需要执行一次，称为基本块，因此基本块中的所有语句的执行次数是相同的，一般由多个顺序执行语句后边跟一个跳转语句组成

跳转ARC

从一个BB到另外一个BB的跳转叫做一个ARC,要想知道程序中的每个语句和分支的执行次数，就必须知道每个BB和ARC的执行次数

程序流图

如果把BB作为一个节点，这样一个函数中的所有BB就构成了一个有向图，要想知道程序中的每个语句和分支的执行次数，就必须知道每个BB和ARC的执行次数，根据图论可以知道有向图中BB的入度和出度是相同的，所以只要知道了部分的BB或者ARC大小，就可以推断所有的大小，这里选择由ARC的执行次数来推断BB的执行次数，所以对部分ARC插桩，只要满足可以统计出来所有的BB和ARC的执行次数即可

原理

测试程序首先进行编译预处理，生成汇编文件，并完成插桩，插桩的过程中会向源文件的末尾插入一个静态数组，数组的大小就是这个源文件中桩点的个数，数组的值就是桩点的执行次数，每个桩点插入3~4条汇编语句，直接插入生成的*.s文件中，最后汇编文件经过汇编生成目标文件，在程序运行过程中桩点负责收集程序的执行信息

使用

编译

测试代码如下： say.c:

#include <stdio.h>

int say(char *what) {
    printf("------ %s\n", what);
    return 0;
}

main.c:

#include <stdio.h>

extern int say(const char *);

int main(int argc, const char *argv[]) {

 if (argv[1]) {
	 say("hello");
 } else {
	 say("bye");
 }
 return 0;
}

添加-fprofile-arcs -ftest-coverage -fPIC编译参数编译程序，生成可执行程序和*.gcno文件，里面记录了行信息和程序流图信息：

$ gcc -fprofile-arcs -ftest-coverage -fPIC -O0 say.c main.c

$ ls
a.out  main.c  main.gcno  say.c  say.gcno

数据收集

运行可执行文件，生成*.gcda在默认生成在相应*.o文件目录，里面记录了*.c文件中程序的执行情况，包括跳变次数等:

 $ ./a.out
 ------ bye
 
 $ ls
 a.out  main.c  main.gcda  main.gcno  say.c  say.gcda  say.gcno

报告生成

针对某一个文件的执行情况，可以通过如下命令生成报告，并创建*.gcov文件：

$ gcov -a main.c
File 'main.c'
Lines executed:80.00% of 5
Creating 'main.c.gcov'

常用选项，更多可参考Invoking gcov：

 -b：分支覆盖
 -a：所有基本块覆盖
 -f：函数覆盖

注意事项

在编译时不要加优化选项，否则代码会发生变化，无法准确定位
代码中复杂的宏，比如宏展开后是循环或者其他控制结构，可以用内联函数来代替，因为gcov只统计宏调用出现的那一行
代码每一行最好只有一条语句
*.gcno与*.gcda需要匹配，两个文件是有时间戳来记录是不是匹配的
若是编译动态库，需要在链接时-lgcov

图形化展示

gcov生成的报告分散在各个源码文件所对应的*.gcov文件中，难以汇总分析，并且可视化效果较差，所以需要转化成可视图形化报告，有lcov或gcovr两个工具可以完成，两者功能基本相同，gcovr，是一个用Python编写的开源软件，大小只有几十KB.

列表形式

代码覆盖率

$ gcovr -r .
------------------------------------------------------------------------------
                           GCC Code Coverage Report
Directory: .
------------------------------------------------------------------------------
File                                       Lines    Exec  Cover   Missing
------------------------------------------------------------------------------
main.c                                         5       4    80%   15
say.c                                          3       3   100%
------------------------------------------------------------------------------
TOTAL                                          8       7    87%
------------------------------------------------------------------------------

报告展示程序运行后覆盖了80%的代码

分支覆盖率

$ gcovr -b -r .
------------------------------------------------------------------------------
                           GCC Code Coverage Report
Directory: .
------------------------------------------------------------------------------
File                                    Branches   Taken  Cover   Missing
------------------------------------------------------------------------------
main.c                                         2       1    50%   14
say.c                                          0       0    --%
------------------------------------------------------------------------------
TOTAL                                          2       1    50%
------------------------------------------------------------------------------

报告展示了在main.c中有一个分支没有执行到

HTML文件形式

$ gcovr -r . --html -o xxx.html
$ ls
a.out  main.c  main.gcda  main.gcno  say.c  say.gcda  say.gcno  xxx.html

可以发现添加--html参数后，可以生成html文件，用浏览器打开，如下图：

还可以添加--html-details选项，为每个代码文件单独生成html

$ gcovr -r . --html --html-details -o xxx.html
$ ls
a.out  main.c  main.gcda  main.gcno  say.c  say.gcda  say.gcno  xxx.html  xxx.main.c.html  xxx.say.c.html

可以发现多了xxx.main.c.html和xxx.say.c.html，用浏览器打开xxx.html，如下图：文件名较之前带上了下划线，单击文件名，可以看到具体的代码覆盖情况，如下图：

测试样例生成

当前的大型商用代码测试软件包括了测试样例自动生成，调研了老牌的测试软件Parasoft C/C++ test与国产新推出的测试工具wings。

| 对比方面 | wings | C/C++ test | | --------- | ------------------------------ | ------------------------- | | 测试样例生成灵活性 | 可以根据需求，修改赋值次数 | 基于Google Test框架，一次性生成固定组值 | | 测试类型 | 见下方表格 | 见下方表格 | | 生成方式 | 基于xml的值填充 | 基于Google Test框架的测试样例代码 | | 应用范围 | 国产替代，使用较少 | 市场占比极大 | | 获取难易 | 使用依赖于厂家的数据库格式，需要厂家提供转换插件，获取难度大 | 有破解版，可用 |

VSCode 配置 TeX/LaTeX 开发环境

Thu, 27 Mar 2025 00:00:00 GMT

一、检查TEX

通过命令： tex -version 来检查当前用户目录下TexLive是否可用

(base) [wanghh@platform_fat01 tex_test]$ tex -version
TeX 3.141592653 (TeX Live 2025)
kpathsea version 6.4.1
Copyright 2025 D.E. Knuth.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the TeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the TeX source.
Primary author of TeX: D.E. Knuth.

or 检查软件路径是否有效

(base) [wanghh@platform_fat01 tex_test]$ which tex
/usr/local/texlive/2025/bin/x86_64-linux/tex

二、VSCode安装 Latex Workshop插件

插件存放地址为 /home/wanghh/Public/vsx 插件安装后重启VSCode，随后新建并打开一个.tex文件，latex插件即可在左侧栏出现。插件使用比较简单，可自行尝试。

使用插件编辑latex前，需要配置一下VSCode的环境，打开setting.json后，添加下列配置即可：

	"latex-workshop.latex.autoBuild.run": "never",
    "latex-workshop.showContextMenu": true,
    "latex-workshop.intellisense.package.enabled": true,
    "latex-workshop.message.error.show": false,
    "latex-workshop.message.warning.show": false,
    "latex-workshop.latex.tools": [
        {
            "name": "xelatex",
            "command": "xelatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "pdflatex",
            "command": "pdflatex",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "%DOCFILE%"
            ]
        },
        {
            "name": "latexmk",
            "command": "latexmk",
            "args": [
                "-synctex=1",
                "-interaction=nonstopmode",
                "-file-line-error",
                "-pdf",
                "-outdir=%OUTDIR%",
                "%DOCFILE%"
            ]
        },
        {
            "name": "bibtex",
            "command": "bibtex",
            "args": [
                "%DOCFILE%"
            ]
        }
    ],
    "latex-workshop.latex.recipes": [
        {
            "name": "XeLaTeX",
            "tools": [
                "xelatex"
            ]
        },
        {
            "name": "PDFLaTeX",
            "tools": [
                "pdflatex"
            ]
        },
        {
            "name": "BibTeX",
            "tools": [
                "bibtex"
            ]
        },
        {
            "name": "LaTeXmk",
            "tools": [
                "latexmk"
            ]
        },
        {
            "name": "xelatex -> bibtex -> xelatex*2",
            "tools": [
                "xelatex",
                "bibtex",
                "xelatex",
                "xelatex"
            ]
        },
        {
            "name": "pdflatex -> bibtex -> pdflatex*2",
            "tools": [
                "pdflatex",
                "bibtex",
                "pdflatex",
                "pdflatex"
            ]
        },
    ],
    "latex-workshop.latex.clean.fileTypes": [
        "*.aux",
        "*.bbl",
        "*.blg",
        "*.idx",
        "*.ind",
        "*.lof",
        "*.lot",
        "*.out",
        "*.toc",
        "*.acn",
        "*.acr",
        "*.alg",
        "*.glg",
        "*.glo",
        "*.gls",
        "*.ist",
        "*.fls",
        "*.log",
        "*.fdb_latexmk"
    ],
    "latex-workshop.latex.autoClean.run": "onFailed",
    "latex-workshop.latex.recipe.default": "lastUsed",
    "latex-workshop.view.pdf.internal.synctex.keybinding": "double-click",
    "latex-workshop.view.pdf.viewer": "tab"

以上个人配置也可自行更改。

编译选项以XeLaTeX为主（其针对中文支持较好）

三、中文字体使用说明

XeLaTeX本身对于中文的支持较为友好，其次TEX自带了一些中文字体。通过 fc-list :lang=zh命令可以查看当前已安装的中文字体

其中/usr/local/texlive/2025/texmf-dist/fonts/路径下为TEX自带的字体， /usr/share/fonts/custom/路径下为我们安装的字体主要包括以下几类：

% Noto Serif CJK SC
% Source Han Serif SC
% AR PL KaitiM GB
% Source Han Sans SC

具体字体细分（黑体、粗体、细体等）可根据需求修改。

Docker 使用

Mon, 24 Mar 2025 00:00:00 GMT

离线安装Docker, docker-compose

一、安装docker

1、下载docker 安装包

https://download.docker.com/linux/static/stable/x86_64/

选择23.0.0，与其他服务器保持一致。

2、上传至服务器并解压

tar -zxvf docker-23.0.0.tgz

3、复制刚解压的docker/目录下所有文件到/usr/bin 目录下

cp -rf docker/* /usr/bin/

4、创建docker.service文件

进入到 /usr/lib/systemd/system/ 目录下，编辑创建docker.service文件，用于管理docker服务，复制黏贴如下内容即可。

vi /usr/lib/systemd/system/docker.service

[Unit]
Description=Docker Application Container Engine
Documentation=http://docs.docker.com
After=network.target docker.socket
[Service]
Type=notify
EnvironmentFile=-/run/flannel/docker
WorkingDirectory=/usr/local/bin
ExecStart=/usr/bin/dockerd \
                -H tcp://0.0.0.0:4243 \
                -H unix:///var/run/docker.sock \
                --selinux-enabled=false \
                --log-opt max-size=100m
ExecReload=/bin/kill -s HUP $MAINPID
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
TimeoutStartSec=0
Delegate=yes
KillMode=process
Restart=on-failure
[Install]
WantedBy=multi-user.target

5、重新加载daemon-reload

systemctl daemon-reload

6、设置开机启动

systemctl enable docker.service

7、启动docker并查看版本

systemctl start docker
docker version

二、安装 docker-compose

1、下载docker-compose 文件

https://github.com/docker/compose/releases/tag/v2.18.1

此处选择linux_x86_64版本

2、上传至服务器并复制到指定目录

# 复制到 /usr/local/bin
mv docker-compose-linux-x86_64 /usr/local/bin/docker-compose
# 设置可执行
chmod +x /usr/local/bin/docker-compose
# 创建软链
ln -sf /usr/local/bin/docker-compose /usr/bin/docker-compose

3、确定是否成功

docker-compose version

docker 使用

# 进入容器
docker exec -it redis bash

# 打包镜像
docker build -t vue-app .

# 基于compose构建容器
docker-compose up -d
# 删除compose构建的容器
docker-compose down

# 重启相关容器
docker-compose restart redis

使用 docker ps -a 来检查 Redis 容器是否正在运行或已经停止，并查看其退出状态代码

docker ps -a

查看容器的日志 比如查看 Redis 容器的日志以了解启动失败的具体原因

docker logs redis

单独命令创建容器

docker run -d -p 8080:8080 flowable

MySQL 的用户权限

确保 root 用户或其他用户允许从外部访问。通过以下步骤检查：

进入 MySQL 容器：
```
docker exec -it mysql bash
```
登录 MySQL：
```
mysql -u root -p
```
确保 MySQL 用户可以从任意主机（即 %）进行访问：
```
GRANT ALL PRIVILEGES ON *.* TO 'root'@'%';
FLUSH PRIVILEGES;
```

QEMU 外设建模模板

Tue, 28 Jan 2025 00:00:00 GMT

QEMU 自定义外设模板

此模板为开发 QEMU 中的外设提供了指南。它包含了详细的解释和代码注释。

1. 引入必要的头文件

这些头文件是大多数 QEMU 设备模型所必需的。

#include "qemu/osdep.h"             // OS 兼容层
#include "hw/irq.h"                 // 中断请求 (IRQ) 处理
#include "hw/qdev-properties.h"     // QEMU 设备属性管理
#include "migration/vmstate.h"      // 虚拟机迁移支持
#include "qemu/log.h"               // QEMU 日志功能
#include "qemu/module.h"            // QEMU 模块初始化

2. 定义设备状态结构体

定义一个结构体来保存自定义设备的内部状态。这包括设备所需的寄存器和状态标志。

typedef struct CustomDeviceState {
    SysBusDevice parent_obj;   // 系统总线设备的基础结构
    uint32_t reg1;             // 示例寄存器 1
    uint32_t reg2;             // 示例寄存器 2
    uint64_t tick_offset;      // 时间或时钟偏移
    bool enable;               // 设备启用标志
    QEMUTimer *timer;          // 定时器，用于计划事件
    qemu_irq irq;              // 中断请求
    MemoryRegion iomem;        // 内存映射 I/O 区域
} CustomDeviceState;

3. 设备初始化与重置

reset(): 重置设备的内部状态和寄存器。
init(): 初始化设备，包括内存和中断连接。

static void custom_device_reset(DeviceState *dev)
{
    CustomDeviceState *s = CUSTOM_DEVICE(dev);
    s->reg1 = 0;               // 将寄存器 1 重置为 0
    s->reg2 = 0;               // 将寄存器 2 重置为 0
    s->enable = true;          // 默认启用设备
}

static void custom_device_init(Object *obj)
{
    CustomDeviceState *s = CUSTOM_DEVICE(obj);

    // 初始化中断处理（GPIO 输出用于中断信号）
    qdev_init_gpio_out(DEVICE(s), &s->irq, 1);

    // 初始化内存映射 I/O（MMIO）区域
    memory_region_init_io(&s->iomem, obj, &custom_device_ops, s, "CustomDevice", 0x100);

    // 将 MMIO 区域和中断连接到系统总线
    sysbus_init_mmio(SYS_BUS_DEVICE(obj), &s->iomem);
    sysbus_init_irq(SYS_BUS_DEVICE(obj), &s->irq);
}

4. 实现读写函数

这些函数定义了设备如何处理对寄存器的读写请求。

// 读取 MMIO 区域的函数
static uint64_t custom_device_read(void *opaque, hwaddr offset, unsigned size)
{
    CustomDeviceState *s = opaque;  // 访问设备状态
    switch (offset) {
        case 0x00:
            return s->reg1;         // 返回 reg1 的值
        case 0x04:
            return s->reg2;         // 返回 reg2 的值
        default:
            return 0;               // 无效的偏移，返回 0
    }
}

// 写入 MMIO 区域的函数
static void custom_device_write(void *opaque, hwaddr offset, uint64_t val, unsigned size)
{
    CustomDeviceState *s = opaque;  // 访问设备状态
    switch (offset) {
        case 0x00:
            s->reg1 = val;          // 将值写入 reg1
            break;
        case 0x04:
            s->reg2 = val;          // 将值写入 reg2
            break;
        default:
            break;                  // 无效的偏移，不执行操作
    }
}

5. 定义 MemoryRegion 操作

此部分将读写函数绑定到设备的内存区域。

static const MemoryRegionOps custom_device_ops = {
    .read = custom_device_read,    // 绑定读取函数
    .write = custom_device_write,  // 绑定写入函数
    .endianness = DEVICE_NATIVE_ENDIAN,  // 使用本地字节序
};

6. 支持虚拟机迁移（可选）

如果设备需要支持虚拟机迁移，开发者需要定义哪些字段应被保存和恢复。

static const VMStateDescription vmstate_custom_device = {
    .name = "custom_device",       // VM 状态名称
    .version_id = 1,               // 状态版本 ID
    .minimum_version_id = 1,       // 最小兼容版本 ID
    .fields = (VMStateField[]) {
        VMSTATE_UINT32(reg1, CustomDeviceState),  // 保存/恢复 reg1
        VMSTATE_UINT32(reg2, CustomDeviceState),  // 保存/恢复 reg2
        VMSTATE_END_OF_LIST()                     // 状态字段列表结束
    }
};

7. 实现并注册设备

此函数实现设备的逻辑。在这里，我们初始化定时器并连接中断。

static void custom_device_realize(DeviceState *dev, Error **errp)
{
    CustomDeviceState *s = CUSTOM_DEVICE(dev);

    // 创建一个新的定时器，该定时器将在 custom_device_interrupt 函数中触发
    s->timer = timer_new_ns(QEMU_CLOCK_VIRTUAL, custom_device_interrupt, s);

    // 获取并连接中断线路
    qemu_irq plic_irq = qdev_get_gpio_in(DEVICE(plic), 7);
    qdev_connect_gpio_out(DEVICE(s), 0, plic_irq);
}

// 初始化设备类
static void custom_device_class_init(ObjectClass *klass, void *data)
{
    DeviceClass *dc = DEVICE_CLASS(klass);
    dc->reset = custom_device_reset;   // 绑定重置函数
    dc->vmsd = &vmstate_custom_device; // 绑定 VM 状态描述
    dc->realize = custom_device_realize; // 绑定实现函数
}

// 注册设备类型
static const TypeInfo custom_device_info = {
    .name = TYPE_CUSTOM_DEVICE,            // 设备名称
    .parent = TYPE_SYS_BUS_DEVICE,         // 父类
    .instance_size = sizeof(CustomDeviceState),  // 实例大小
    .instance_init = custom_device_init,   // 实例初始化函数
    .class_init = custom_device_class_init // 类初始化函数
};

// 将设备类型注册到 QEMU
static void custom_device_register_types(void)
{
    type_register_static(&custom_device_info);  // 注册设备类型
}

// 在 QEMU 初始化时调用注册函数
type_init(custom_device_register_types);

通过遵循此模板，开发者可以在 QEMU 中实现支持 MMIO、中断和可选迁移功能的自定义外设。你可以根据具体的设备需求修改此模板。

Nextcloud + OnlyOffice 安装与使用

Sat, 18 Jan 2025 00:00:00 GMT

安装nextcloud

docker run -d --name nextcloud --restart=always -v /home/docker/workspace/nextcloud:/var/www/html -e TZ="Asia/Shanghai" -p 8080:80 nextcloud

安装onlyoffice服务

#安装 onlyoffice
docker run -d --restart=always --name onlyoffice -p 9002:80 -p 9001:443 onlyoffice/documentserver

使用docker-compose.yml

version: '3'

services:
  nextcloud:
    image: nextcloud
    container_name: nextcloud
    restart: always
    ports:
      - "8080:80"
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /docker/nextcloud:/var/www/html

  onlyoffice:
    image: onlyoffice/documentserver
    container_name: onlyoffice
    restart: always
    ports:
      - "9002:80"
      - "9001:443"
    volumes:
      - /docker/onlyoffice/data:/var/www/onlyoffice/Data
			# - /home/docker/workspace/onlyoffice/logs:/var/log/onlyoffice  # 日志文件
		  # - /home/docker/workspace/onlyoffice/lib:/var/lib/onlyoffice   # 数据库和应用配置
		  # - /home/docker/workspace/onlyoffice/cache:/var/cache/onlyoffice  # 缓存文件

获取onlyoffice秘钥（用于后面nextcloud的onlyoffice插件配置）

进入onlyoffice容器内

## 进入onlyoffice容器
docker exec -it onlyoffice bash

## 查看秘钥
cat /etc/onlyoffice/documentserver/local.json

随后将离线下载的nextcloud app的压缩包传入容器中/var/www/html/apps目录里面（即挂载数据卷的apps目录）后解压即可

tar -zxvf onlyoffice.tar.gz

onlyoffice添加字体

# 将字体文件传入容器中
cp ~/方正书宋简体.ttf onlyoffice:/usr/share/fonts/truetype/custom/
# 进入容器
docker exec -it onlyoffice bash
# 执行脚本，随后刷新浏览器缓存即可
bash /usr/bin/documentserver-generate-allfonts.sh

nextcloud优化

配置缓存 APCu + redis

APCu : 配置config.php文件

'memcache.local'  =>  '\\OC\\Memcache\\APCu' ,

检查

docker exec -it nextcloud bash

cat /usr/local/etc/php/conf.d/docker-php-ext-apcu.ini

redis ：配置config.php文件

  'memcache.locking' => '\\OC\\Memcache\\Redis',
  'memcache.distributed' => '\\OC\\Memcache\\Redis',
  'redis' => array(
     'host' => '49.233.160.34',
     'port' => 16379,
  ),

使用http2

进入 Nextcloud 容器：
```
docker exec -it nextcloud bash
```
启用 http2 模块：
```
a2enmod http2
```

后台任务

选择第三种corn

在宿主机上确保 Cron 服务正在运行，使用以下命令：

systemctl status cron

可以手动测试这条命令，看看是否正常运行：

docker exec -u www-data nextcloud php -f /var/www/html/cron.php

检查是否已经安装：

rpm -qa | grep cronie

启动并启用 cron 服务：

sudo systemctl start crond
sudo systemctl enable crond

在宿主机的 Crontab 中添加任务：

使用 crontab -e 编辑宿主机的 cron 配置文件。

添加如下行，定期在容器内执行 cron.php：

*/5 * * * * docker exec -u www-data nextcloud php -f /var/www/html/cron.php

这条命令每 5 分钟在容器内以 www-data 用户身份执行 Nextcloud 的 cron.php。

修改php运行内存

docker exec -it nextcloud bash

sed -i 's/memory_limit=.*/memory_limit=1024M/' /usr/local/etc/php/conf.d/nextcloud.ini

Spike 模拟器基础

Sun, 15 Sep 2024 00:00:00 GMT

Spike机制

Spike 仿真器模拟 RISC-V 处理器的指令执行，而宿主机是运行仿真器的物理计算机。tohost 和 fromhost 寄存器的通信机制允许目标系统（仿真中的 RISC-V 处理器）与宿主机之间进行数据交换，主要作用包括：

输入/输出（I/O）处理：例如，当仿真程序需要与外部设备（如控制台、磁盘等）交互时，这些通信机制允许目标系统通过宿主机的资源来执行这些操作。
系统调用（Syscalls）：当仿真程序执行系统调用（如文件操作、内存分配等）时，tohost 和 fromhost 机制将系统调用的请求从目标系统传递到宿主机，由宿主机模拟相应的系统调用，并返回结果。
异常与中断处理：仿真过程中，宿主机负责处理一些来自目标系统的异常情况或中断信号，通过 tohost 发送中断请求，宿主机可以模拟响应这些事件。

`tohost` 和 `fromhost` 寄存器的工作机制：

tohost 寄存器：目标系统将数据写入 tohost 寄存器，通常用于发送命令或请求给宿主机。例如，仿真程序可能请求宿主机进行某种I/O操作或触发系统调用。
fromhost 寄存器：宿主机通过 fromhost 寄存器将响应数据传递回目标系统，例如返回系统调用的结果或提供输入数据。

通信机制未启用时

如果 tohost_addr 为零，通信未启用。在这种情况下，仿真器会简单地执行目标系统的指令而不与宿主机进行任何交互。这意味着仿真器处于一个纯粹的“裸机模式”（bare-metal mode），运行的是不需要宿主机协助的程序。
在这个模式下，仿真器通过不断调用 idle() 函数执行指令，直到接收到退出信号。在这种情况下，仿真程序无法与外部系统（宿主机）进行交互，所以适合用于一些不依赖 I/O 的测试程序或无操作系统的裸机程序。

Spike的运行

Spike的程序启动逻辑位于spike.cc文件的主函数（main()）中。包括以下关键部分：

参数解析：解析输入参数并根据这些参数设置仿真器的配置。
初始化内存和处理器：根据配置初始化仿真的内存和处理器核心。
加载程序：将内核和初始RAM盘加载到仿真内存中。
启动仿真：通过sim_t::run()进入主仿真循环，开始指令的执行。

通过sim_t::run()调用htif_t::run()的主运行循环（它是仿真器和宿主机之间的接口主循环。htif_t::run() 会不断调用 sim_t::idle() 函数来推进仿真的进程。）

 int htif_t::run()
 {
   start();
 
   auto enq_func = [](std::queue<reg_t>* q, uint64_t x) { q->push(x); };
   std::queue<reg_t> fromhost_queue;
   std::function<void(reg_t)> fromhost_callback =
     std::bind(enq_func, &fromhost_queue, std::placeholders::_1);
 
   if (tohost_addr == 0) { // 裸机模式运行
     while (!signal_exit)
       idle();  // 从这里进入，在 sim_t::idle() 函数中，仿真器会执行指令并让时间前进。
   }
   ......
 }

sim_t::idle() 负责推进仿真器的时间状态，通常通过让仿真中的处理器核心执行指令。它可以处理中断、定时器事件等，模拟系统的实际行为。

 void sim_t::idle()
 {
   if (done())
     return;
 
   if (debug || ctrlc_pressed)
     interactive();
   else
     step(INTERLEAVE); // 默认  static const size_t INTERLEAVE = 5000;
 
   if (remote_bitbang)
     remote_bitbang->tick();
 }

step(INTERLEAVE)：idle() 函数调用 sim_t::step() 函数来推进仿真器的执行。INTERLEAVE 是仿真器每次执行的指令数量，它是一个预定义的值或根据仿真配置设定。

sim_t::step() 函数是仿真器的主执行循环，它遍历每个处理器核心，并调用每个核心的 processor_t::step() 函数来执行指令：

 void sim_t::step(size_t n)
 {
   for (size_t i = 0, steps = 0; i < n; i += steps) // 这个循环会持续执行，直到仿真器核心已经执行了 n 条指令。
   {
     steps = std::min(n - i, INTERLEAVE - current_step); // steps 变量决定每次当前处理器核心将执行的指令数
     procs[current_proc]->step(steps); // procs[current_proc]->step(steps)：这一行代码调用当前处理器核心的 step() 函数，执行steps条指令。
 
     current_step += steps;
     if (current_step == INTERLEAVE) // 当 current_step 达到 INTERLEAVE 时，仿真器将 current_step 重置为 0，并切换到下一个处理器核心
     {
       current_step = 0;
       procs[current_proc]->get_mmu()->yield_load_reservation();
       if (++current_proc == procs.size()) { // 如果所有核心都轮流执行了一次（即 current_proc == procs.size()），仿真器会调用设备的 tick() 函数更新其状态。rtc_ticks 是计算出来的虚拟时钟周期，表示在执行的指令数之间设备所经历的虚拟时间
         current_proc = 0;
         reg_t rtc_ticks = INTERLEAVE / INSNS_PER_RTC_TICK;
         for (auto &dev : devices) dev->tick(rtc_ticks);
       }
     }
   }
 }

processor_t::step(size_t n) 是 Spike 中用于实现指令取指（fetch）、解码（decode）、执行（execute）循环的核心函数。它负责让每个处理器核心（hart）执行 n 条指令，同时处理调试模式、陷阱、触发器和中断等情况。

调试模式检查

 if (!state.debug_mode) {
   if (halt_request == HR_REGULAR) {
     enter_debug_mode(DCSR_CAUSE_DEBUGINT);
   } else if (halt_request == HR_GROUP) {
     enter_debug_mode(DCSR_CAUSE_GROUP);
   } else if (state.dcsr->halt) {
     enter_debug_mode(DCSR_CAUSE_HALT);
   }
 }

在执行指令之前，Spike 会检查是否存在调试模式请求。如果有调试中断或调试模式标志被设置，处理器会进入调试模式。

主执行循环

基本状态初始化

 while (n > 0) {
     size_t instret = 0;
     reg_t pc = state.pc;
     mmu_t* _mmu = mmu;
     state.prv_changed = false;
     state.v_changed = false;
     ......
 }

instret 记录已经执行的指令数量。
pc 是当前的程序计数器，指向当前要执行的指令的地址。
_mmu 指向内存管理单元（MMU），用于加载和存储指令。
state.prv_changed 和 state.v_changed 用于跟踪特权级（privilege level）和矢量化（vectorization）的变化。

取指、解码和执行

慢速路径（slow path）

 if (unlikely(slow_path())) {
   while (instret < n) {
     // 执行单条指令
     insn_fetch_t fetch = mmu->load_insn(pc);
     pc = execute_insn_logged(this, pc, fetch);
     advance_pc();
   }
 }

慢速路径：如果进入了“慢速路径”（即需要特殊处理的情况，如单步调试、触发器检测等），每条指令都会通过 mmu->load_insn(pc) 从内存中加载，并通过 execute_insn_logged() 执行。
单步执行：在慢速路径下，指令会逐条取出、解码并执行，同时处理调试触发器和中断。

快速路径（fast path）

 else while (instret < n) {
   for (auto ic_entry = _mmu->access_icache(pc); ; ) {
     auto fetch = ic_entry->data;
     pc = execute_insn_fast(this, pc, fetch);
     ic_entry = ic_entry->next;
     if (unlikely(ic_entry->tag != pc))
       break;
     if (unlikely(instret + 1 == n))
       break;
     instret++;
     state.pc = pc;
   }
   advance_pc();
 }

快速路径：在不需要特殊处理的情况下，Spike 使用指令缓存（icache）加速执行流程。处理器从缓存中读取指令，并通过 execute_insn_fast() 执行指令。如果缓存匹配，则直接执行下一个指令块，减少频繁的内存访问。
跳转指令：如果遇到分支跳转或者缓存不匹配的情况，指令缓存中的执行流会中断，并重新从新地址获取指令。

中断和陷阱处理

在指令执行过程中，可能会发生各种异常、中断或者调试陷阱：

中断处理

 take_pending_interrupt();

take_pending_interrupt()：检查并处理待处理的中断。如果检测到中断，将触发中断处理流程。

陷阱处理

catch (trap_t& t) {
  take_trap(t, pc);
  n = instret;
}

如果在指令执行过程中发生陷阱（如非法指令、内存访问异常等），Spike 会捕获陷阱，并调用 take_trap() 处理陷阱。

触发器匹配

catch (triggers::matched_t& t) {
  take_trigger_action(t.action, t.address, pc, t.gva);
}

如果检测到触发器匹配事件，Spike 会执行相应的触发器操作（如中断、陷阱等）。

等待中断

catch (wait_for_interrupt_t& t) {
  n = ++instret;
  in_wfi = true;
}

当执行 WFI（等待中断）指令时，处理器会进入等待状态，并等待中断发生。此时会退出循环，并标记为 in_wfi 状态。

指令计数和周期计数

state.minstret->bump(instret);
state.mcycle->bump(instret);

Spike 模拟了处理器的性能计数器。在每次指令执行后，minstret（已完成指令计数器）和 mcycle（周期计数器）会根据执行的指令数量进行递增。

QEMU tcg中间码优化与后端机制

Mon, 02 Sep 2024 00:00:00 GMT

TCG 基本逻辑

qemu tcg 的基本翻译思路是把 guest 指令先翻译成中间码(IR)，然后再把 IR 翻译成 host 指令。guest->IR->host 这种三段式实现的好处是把前端翻译，优化和后端翻译拆开了，降低了开发的难度。

IR 指令的理解是比较直白的，qemu 定义了一套 IR 的指令，具体的定义在 tcg/README 里说明,在一个 tb 里，qemu 前端翻译得到的 IR 被串联到一个链表里，中间码优化和后端翻译都靠这个链表得到 IR，中间码优化时，需要改动 IR 时(比如，删掉不可达的 IR)，对这个链表做操作就好。

中间码不只是定义了对应的指令，也有寄存器的定义，它形成了一个独立的逻辑空间，在 IR 这一层，可以认为都在中间码相关的寄存器上做计算的。IR 这一层定义了几个寄存器类型，它们分别是：global, local temp, normal temp, fixed, const, ebb

一般 guest 的 gpr 也被定义为 IR 这一层的 global 寄存器，中间码做计算的时候，会用到一些临时变量，这些临时变量就保存在 local temp 或者是 normal temp 这样的寄存器里，计算的时候要用到一些常量时，需要定义一个 TCG 寄存器，创建一个常量并把它赋给 TCG 寄存器。

riscv 下 global 寄存器一般如下定义：

/* target/riscv/translate.c */
riscv_translate_init
  [...]
  +-> cpu_gpr[i] = tcg_global_mem_new(cpu_env,
  		    offsetof(CPURISCVState, gpr[i]), riscv_int_regnames[i]);
        /* 在TCGContext里分配对应的空间，并且设定这个寄存器是TEMP_GLOBAL */
    +-> tcg_global_mem_new_internal(..., reg, offset, name);
  [...]
  +-> cpu_pc = tcg_global_mem_new(cpu_env, offsetof(CPURISCVState, pc), "pc");
  [...]

这里分配了对应的 TCG 寄存器，返回值是这些寄存器存储地址相对 tcg_ctx 的偏移。注意这里得到的是 global 寄存器的描述结构，类型是 TCGTemp，而 global 寄存器实际存储在 CPURISCVState 内具体定义的地方，TCGTemp 内通过 mem_base 和 mem_offset 指向具体存储地址。

实际上，所有 TCG 寄存器的分配都是在 TCGContext 里分配了对应的存储空间，并且配置上相关参数，这些参数和 IR 一起交给后端做 IR 优化和后端翻译，后端使用 TCGContext 的地址和具体寄存器的偏移可以找见具体的 TCG 寄存器。

normal temp 只在一个 BB 中有效，local temp 在一个 TB 中有效。fixed 要结合 host 寄存器分配来看，首先 IR 中分配的这些寄存器都是虚拟的寄存器，IR 翻译到 host 指令都要给虚拟寄存器分配对应的 host 物理寄存器，当一个 TCG 寄存器有 TEMP_FIXED 标记表示在后端翻译时把这个虚拟寄存器固定映射到一个 host 物理寄存器上，一般 fixed 寄存器都是翻译执行时经常要用到的参数。

中间码优化

前端翻译得到的 IR 可能会有优化的空间存在，所以 qemu 在进行后端翻译之前会先做中间码优化，优化以一个 TB 为单位，优化的输入就是一个 TB 对应的 IR 和用到的 TCG 寄存器。

/* tcg/tcg.c */
tcg_gen_code
  +-> tcg_optimize(s)
    +-> done = fold_add(&ctx, op);

  +-> reachable_code_pass(s);

tcg_optimize 是做着一些常量的检查，进而做指令优化(折叠常量表达式), 我们取其中的一个 case，比如 fold_add 具体看下，大概知道下这里是在干什么。可以看到这个 case 检测 add_32/64 这个 IR 的两个操作数是不是常量，如果是常量，那么在这里直接把常量相加后的结果放到一个常量类型 TCG 寄存器，然后把之前的 add_32/64 改成一条 mov 指令。

从名字就可以看出 reachable_code_pass 应该做的是一些死代码的删除，这里检测到运行不到的 IR 就直接从 IR 链表里把他们删掉。

中间码优化的输出还是 IR 链表和相关的 TCG 寄存器，可见我们也可以把这两个函数注释掉，从而把中间码优化关掉。可以看出，中间码优化和编译器 IR 优化的逻辑是类似的。

tcg 后端功能

qemu 用 tcg 模拟 guest 指令执行，qemu 把 guest 指令先翻译成中间码，然后再把中间码翻译成 host 指令，host 指令可以最终在 host cpu 上执行，这样就完成了翻译。

此部分关注的是后端翻译模型，也就是中间码翻译成 host 指令的过程。中间码是一套完整的指令集定义，使用中间码可以完整的表述 guest 指令的行为，看一个小例子对这种描述会有更直观的感受。

addi            sp,sp,-32                  <-- guest汇编
sd              s0,24(sp)

add_i64 x2/sp,x2/sp,$0xffffffffffffffe0    <-- 中间码
add_i64 tmp4,x2/sp,$0x18
qemu_st_i64 x8/s0,tmp4,leq,0

如上 guest 那条 store 指令，它被翻译成了两条中间码，第一条 add_i64 是用来计算 sd 要 store 的地址，计算出的地址保存在 tmp4 这个虚拟寄存器里，第二条中间码把 s0 的值 store 到 tmp4 描述的内存上，qemu 用中间码和虚拟寄存器完整的表述 guest 的逻辑。这里 qemu_st_i64 这个中间码表示一个 store 操作，store 的数据和地址都用虚拟寄存器描述，所以在 qemu_st_i64 之前要用 add_i64 先计算出 store 的地址，并保存在虚拟寄存器里。

qemu 中，其它的 guest 指令也是这样先翻译成中间码和虚拟寄存器的表示，后端翻译基于中间码和虚拟寄存器进行。上面的中间码表述中，x2/sp 和 x8/s0 还是 guest 上寄存器的名字，但是逻辑上 guest 上的寄存器都已经映射到 qemu 虚拟寄存器，所以中间码指令中的所有寄存器都是 qemu 的虚拟寄存器。

qemu 模拟的 guest cpu 系统说到底就是 host 内存里表示的 guest cpu 的软件结构体的状态以及 guest 内存的状态，qemu 中间码已经完整的描述了 guest 状态改变的激励，拿上面 addi 和 sd guest 指令的模拟为例，模拟 addi 的中间码是 addi_64 x2/sp,x2/sp,$0xffffffffffffffe0 ，表示要把 guest 的 sp 加上-32，sd 的中间码表示要把 guest sp + 24 指向的地址上的值改成 s0 的值。我们拿到如上中间码或者 guest 指令，甚至可以直接写 c 代码去完成模拟。qemu 为了追求效率把中间码翻译成 host 指令来完成模拟。

add_i64 x2/sp,x2/sp,$0xffffffffffffffe0
add_i64 tmp4,x2/sp,$0x18
qemu_st_i64 x8/s0,tmp4,leq,0

这几条中间码只是表意，实际真正更新 guest cpu 的数据结构和 guest 地址还需要 host 指令完成，所以实际翻译后的 host 指令可能是这样的：

ldr      x20, [x19, #0x10]    把guest cpu中的sp load到host的x20寄存器
sub      x20, x20, #0x20      使用host sub指令完成guest sp的计算
str      x20, [x19, #0x10]    更新guest cpu中sp的值
add      x21, x20, #0x18      使用host add指令计算store的地址，并保存到host的x21寄存器
ldr      x22, [x19, #0x40]    把guest cpu中的s0 load到host的x22寄存器
str      x22, [x21, xzr]      使用host str指令更新guest地址上的值

qemu 的后端翻译就是完成如上功能，总结起来就是：

分配 host 物理寄存器；
生成 host 指令；
host 和 guest 之间的状态同步。

分配 host 物理寄存器

虚拟寄存器和 host 物理寄存器是两个独立的概念，虚拟寄存器可能会很多，而物理寄存器的个数是有限的，虚拟寄存器有自己的生命周期，虚拟寄存器生命周期结束后，它所使用的物理寄存器就可以给其它虚拟寄存器使用。因为 host 物理寄存器数目有限，就有可能出现 host 物理寄存器不够分的情况，这时候就需要把已经分配但是目前还没有用到的 host 物理寄存器的值保存到内存，这样就可以腾出 host 物理寄存器来使用。

qemu 在处理 host 物理寄存器分配的时候，分了两步处理，第一步先确定虚拟寄存器的生命周期，一般叫做寄存器活性分析，第二步根据虚拟寄存器活性分析的结果具体分配物理寄存器。

针对一段中间码，qemu 对其做逆序遍历，依此确定虚拟寄存器的生命周期。如果一个虚拟寄存器后续还中间码使用，那它还是 live 的，如果后面没有中间码用了，它就 dead 了。

所以，一个虚拟寄存器 dead 与否是和具体中间码一起看的，一个虚拟寄存器可能在前几个中间码中是 live 的(虽然这几个中间码并没有使用这个虚拟寄存器)，最后一个使用它的中间码后这个虚拟寄存器就 dead 了。qemu 里只要记录虚拟寄存器被引用时的状态就好。

生成 host 指令以及状态同步

我们把状态同步和 host 指令生成放到一起看，因为所谓状态同步也要生成 host 指令进行。

对于中间码的输入虚拟寄存器，需要先判断这个输入寄存器的值是保存在内存上，还是已经保存在 host 物理寄存器上了，如果还在内存上，qemu 就要分配 host 物理寄存器，然后插入 host 上的 load 指令把内存上的值 load 到 host 物理寄存器上，如果虚拟寄存器的值已经在 host 物理寄存器上，那么它直接就可以参与计算。对于中间码的输出虚拟寄存器，qemu 需要为它分配 host 物理寄存器。

中间码的输入和输出寄存器都有着落了，qemu 就可以尝试把中间码翻译成 host 指令。这个翻译可能直接就可以翻译成一条 host 指令，也可能需要再插入几条 host 指令调整下。

guest 指令对应的中间码执行完后，需要把 guest 指令的输出同步回 guest CPU 数据结构，所以 qemu 在这里还需要插入 host store 指令把数据刷回 guest CPU。qemu 在寄存器活性分析的时候会把需要做同步的虚拟寄存器打上 sync 的标记，生成 host 指令的时候遇见 sync 标记就可以直接插入 host 指令做同步。

并不需要每个 guest 指令执行完都要把信息刷回 guest CPU 数据结构，虽然 guest CPU 的信息是定义在 guest CPU 数据结构中的，但是我们是模拟 guest CPU，只要不破坏模拟的逻辑，host 物理寄存器上的值就可以先不刷回 guest CPU 数据结构。那什么时候需要刷回 guest CPU，整个 TB 执行完时，虚拟寄存器需要被同步回 guest CPU，当中间码可能导致 guest CPU 异常时，需要做同步，因为触发异常后，guest CPU 跳转到异常处理地址，并且向软件报告异常处理的上下文，其中 guest CPU 的通用寄存器就都是从 guest CPU 数据结构获取。

加入 BB 的概念

上面讲的寄存器分配和状态同步其实还不完整，qemu 的一个翻译块(TB)里是可以存在跳转中间码的，在有跳转中间码的情况下，上面逆序遍历确定虚拟寄存器活性的办法就会有问题。为此 qemu 中在 TB 的基础上又引入了 Basic Block(BB)的概念，简单讲在一个 BB 内中间码都是顺序执行的，这样如上的逻辑在 BB 内还是成立的。所以，在 BB 的结尾就要 dead 全部虚拟寄存器，并且把 guest CPU 对应的虚拟寄存器向 guest CPU 数据结构做同步。

Spike 运行机制详解

Sun, 18 Aug 2024 00:00:00 GMT

指令获取

Spike 使用 MMU（内存管理单元）来加载指令。具体来说，指令获取的过程通过 mmu->load_insn(pc) 函数完成，该函数负责根据程序计数器的地址从内存中读取一条指令。

 struct insn_fetch_t
 {
   insn_func_t func;
   insn_t insn;
 };
 
 struct icache_entry_t {
   reg_t tag;
   struct icache_entry_t* next;
   insn_fetch_t data;
 };
 
 insn_fetch_t fetch = mmu->load_insn(pc);
     -> inline insn_fetch_t load_insn(reg_t addr)
        {
            icache_entry_t entry;
            return refill_icache(addr, &entry)->data;
        }

mmu->load_insn(pc)：根据当前程序计数器（pc）的值，MMU 从内存中读取指令。这是一个指令获取函数，它返回一个 insn_fetch_t 结构，其中包含了要执行的指令及其相关的元数据。

Spike 提供了一个指令缓存（ICache）来加速指令获取的过程。缓存中的指令可以避免频繁从内存中读取相同的指令，这提高了仿真的性能。

在快速路径中，Spike 会从指令缓存中直接获取指令：

 auto ic_entry = _mmu->access_icache(pc);
     -> inline icache_entry_t* access_icache(reg_t addr)
       {
         icache_entry_t* entry = &icache[icache_index(addr)];
         if (likely(entry->tag == addr))
           return entry;
         return refill_icache(addr, entry);
       }
 auto fetch = ic_entry->data;

如果指令缓存未命中或者在慢速路径中，Spike 会直接从内存中加载指令。通过 mmu->load_insn() 函数完成，它负责从内存地址中读取原始的指令二进制数据。

读取指令

refill_icache 是 Spike 仿真器中用于填充指令缓存（ICache）的函数。它从内存中读取指令，并将指令及其解码结果缓存起来，以便后续访问时可以从缓存中快速获取指令，而不必再次进行内存访问。

 inline icache_entry_t* refill_icache(reg_t addr, icache_entry_t* entry)
   {
     if (matched_trigger)
       throw *matched_trigger;
 
     auto tlb_entry = translate_insn_addr(addr); // 将虚拟地址（addr）转换为物理地址
     // 从内存中读取指令的前两个字节（16位），并将其存入 insn 变量。
     insn_bits_t insn = from_le(*(uint16_t*)(tlb_entry.host_offset + addr));
     int length = insn_length(insn); // 确定该指令的长度
     // 根据 length 的值，Spike 从内存中获取剩余的指令字节，并组装成完整的指令
     if (likely(length == 4)) {
       insn |= (insn_bits_t)from_le(*(const uint16_t*)translate_insn_addr_to_host(addr + 2)) << 16;
     } else if (length == 2) {
       // entire instruction already fetched
     } else if (length == 6) {
       insn |= (insn_bits_t)from_le(*(const uint16_t*)translate_insn_addr_to_host(addr + 2)) << 16;
       insn |= (insn_bits_t)from_le(*(const uint16_t*)translate_insn_addr_to_host(addr + 4)) << 32;
     } else {
       static_assert(sizeof(insn_bits_t) == 8, "insn_bits_t must be uint64_t");
       insn |= (insn_bits_t)from_le(*(const uint16_t*)translate_insn_addr_to_host(addr + 2)) << 16;
       insn |= (insn_bits_t)from_le(*(const uint16_t*)translate_insn_addr_to_host(addr + 4)) << 32;
       insn |= (insn_bits_t)from_le(*(const uint16_t*)translate_insn_addr_to_host(addr + 6)) << 48;
     }
 
     insn_fetch_t fetch = {proc->decode_insn(insn), insn}; // 指令解码
     entry->tag = addr; // 将缓存条目中的 tag 更新为当前指令的地址（addr），以便后续可以根据地址快速找到这条缓存条目。
     entry->next = &icache[icache_index(addr + length)]; // 将 next 指针设置为下一个缓存条目地址
     entry->data = fetch; // 将 fetch（包含解码后的指令和原始指令）存入 entry->data 中。
     // 跟踪与异常处理
     reg_t paddr = tlb_entry.target_offset + addr;;
     if (tracer.interested_in_range(paddr, paddr + 1, FETCH)) {
       entry->tag = -1;
       tracer.trace(paddr, length, FETCH);
     }
     return entry;
   }

refill_icache 的主要功能是：

地址转换（TLB）。
读取不同长度的指令。
解码指令。
将指令存入缓存。
监控触发器或调试器的状态。

指令解码

processor_t::decode_insn(insn_t insn) 是 Spike 中用于将二进制指令解码为对应的操作函数的核心函数。它会通过查找一个哈希表来快速获取指令对应的处理函数（insn_func_t），如果哈希表未命中，则会通过线性搜索找到相应的指令描述符，并将其缓存起来以供后续查找。

decode_insn 的主要功能是：

从二进制指令中提取出操作码。
查找指令对应的操作函数。
通过哈希表缓存机制加速指令解码。
处理自定义指令集和扩展。

通过哈希表查找指令

 size_t idx = insn.bits() % OPCODE_CACHE_SIZE;
 auto [hit, desc] = opcode_cache[idx].lookup(insn.bits());

insn.bits()：从指令对象中提取出指令的二进制表示。bits() 返回指令的位表示。
idx = insn.bits() % OPCODE_CACHE_SIZE：使用指令的位表示对 OPCODE_CACHE_SIZE 取模，计算哈希表中的索引 idx。这个索引指向缓存中的某个槽位。
opcode_cache[idx].lookup(insn.bits())：在哈希表（opcode_cache）中查找是否存在该指令。如果存在（hit 为 true），则直接返回指令描述符 desc。

处理自定义指令和标准指令

如果哈希表中没有找到对应的指令（hit 为 false），Spike 将使用线性搜索方法在自定义指令和标准指令列表中寻找匹配的指令

 if (unlikely(!hit)) {
   // fall back to linear search
   auto matching = [insn_bits = insn.bits()](const insn_desc_t &d) {
     return (insn_bits & d.mask) == d.match;
   };
   auto p = std::find_if(custom_instructions.begin(),
                         custom_instructions.end(), matching);
   if (p == custom_instructions.end()) {
     p = std::find_if(instructions.begin(), instructions.end(), matching);
     assert(p != instructions.end());
   }
   desc = &*p;
   opcode_cache[idx].replace(insn.bits(), desc);
 }

线性搜索：如果缓存未命中，Spike 会在 custom_instructions（自定义指令集）中线性搜索。matching 是一个匿名函数，它通过指令的掩码（mask）和匹配值（match）来匹配指令。
std::find_if：标准库函数 find_if 在列表中寻找第一个满足条件的指令描述符。如果没有在自定义指令集中找到，Spike 将搜索标准的 instructions 集合。
缓存更新：一旦找到匹配的指令编码，Spike 将该描述符插入哈希表的缓存中，以加速后续的解码过程。

指令什么时候被添加到队列中？

processor_t::processor_t初始化函数中processor_t::register_base_instructions() 函数就是 Spike 仿真器中将指令添加到 instructions 容器中的地方。这也是标准 RISC-V 指令集被注册的关键函数。

   #define DEFINE_INSN(name) \
     if (!name##_overlapping) \
       register_base_insn((insn_desc_t) { \
         name##_match, \
         name##_mask, \
         fast_rv32i_##name, \
         fast_rv64i_##name, \
         fast_rv32e_##name, \
         fast_rv64e_##name, \
         logged_rv32i_##name, \
         logged_rv64i_##name, \
         logged_rv32e_##name, \
         logged_rv64e_##name});
   #include "insn_list.h"
   #undef DEFINE_INSN

DEFINE_INSN 宏：声明与每条指令相关的各种处理函数。每条指令可以有多个变种（例如针对 RV32I、RV64I、RV32E、RV64E 等不同的指令集变体），每个变种都有对应的快速路径（fast）和日志记录（logged）版本。

 DEFINE_INSN(add)
 DEFINE_INSN(addi)
 DEFINE_INSN(addiw)
 DEFINE_INSN(addw)
 DEFINE_INSN(and)
 DEFINE_INSN(andi)
 DEFINE_INSN(auipc)
 DEFINE_INSN(beq)
 DEFINE_INSN(bge)
 DEFINE_INSN(bgeu)
 DEFINE_INSN(blt)

insn_list.h：该文件包含所有标准 RISC-V 指令的列表。通过包含这个文件，Spike 为每条指令声明了其相关的处理函数。

 static uint32_t addi(unsigned int dest, unsigned int src, uint16_t imm) __attribute__ ((unused));
 static uint32_t addi(unsigned int dest, unsigned int src, uint16_t imm)
 {
   return (bits(imm, 11, 0) << 20) |
     (src << 15) |
     (dest << 7) |
     MATCH_ADDI;
 }

随后会调用processor_t::register_insn函数，将指令添加入指令队列中。

void processor_t::register_insn(insn_desc_t desc, bool is_custom) {
  assert(desc.fast_rv32i && desc.fast_rv64i && desc.fast_rv32e && desc.fast_rv64e &&
         desc.logged_rv32i && desc.logged_rv64i && desc.logged_rv32e && desc.logged_rv64e);

  if (is_custom)
    custom_instructions.push_back(desc);
  else
    instructions.push_back(desc);
}

获得指令执行函数

desc->func(xlen, rve, log_commits_enabled);

desc->func：指令描述符包含了对应指令的处理函数（func），这是一个指令处理函数（insn_func_t 类型）。根据指令描述符，Spike 返回这个指令处理函数。

insn_func_t func(int xlen, bool rve, bool logged) const
  {
    if (logged)
      if (rve)
        return xlen == 64 ? logged_rv64e : logged_rv32e;
      else
        return xlen == 64 ? logged_rv64i : logged_rv32i;
    else
      if (rve)
        return xlen == 64 ? fast_rv64e : fast_rv32e;
      else
        return xlen == 64 ? fast_rv64i : fast_rv32i;
  }

此时获得的指令执行函数形式类似于fast_rv32i_add,实际上是没有这个函数，而是会通过宏定义的方式来实现指令执行的逻辑。

指令执行

获得指令的执行函数后Spike就会直接调用。

static inline reg_t execute_insn_fast(processor_t* p, reg_t pc, insn_fetch_t fetch) {
  return fetch.func(p, fetch.insn, pc);
}

Spike的指令逻辑是在ISA（指令集架构）模块中定义的，具体是在riscv/insns/目录下。

每条指令都有一个对应的C++文件。例如，add指令的编码格式在riscv/insns/add.h文件中定义。Spike使用宏和位运算来解析和生成指令的二进制编码。
指令的解析和执行逻辑是由仿真器内部的解码器来实现的。指令的二进制编码由RISC-V ISA的标准规定，在Spike中，这些编码由解码器解析并映射到相应的指令处理函数。

Spike 使用宏定义的方式来实现指令执行的逻辑。这种方式可以让多条指令共享相似的结构逻辑，并简化重复性代码的编写。例如，add.h 文件中的宏实现可能被多个变种（例如 RV32I 和 RV64I）使用，而不需要为每个变种编写单独的函数。

在构建时，Spike 的编译器会将这些宏展开到实际的指令处理逻辑中。具体的执行流程如下：

当仿真器解码到 add 指令时，会使用指令表中的描述符（如fast_rv32i_add）找到 add.h 文件中的处理逻辑。
add.h 中的宏会被展开为相应的操作，仿真器将使用这些操作执行加法指令。

// add.h
WRITE_RD(RS1 & RS2);
|
||-> // riscv/decode_macros.h
    #define RS1 READ_REG(insn.rs1())
    #define RS2 READ_REG(insn.rs2())
||-> // riscv/decode_macros.h
    #define WRITE_RD(value) WRITE_REG(insn.rd(), value)
    #define WRITE_REG(reg, value) ({ \
        reg_t wdata = (value); /* value may have side effects */ \
        if (DECODE_MACRO_USAGE_LOGGED) STATE.log_reg_write[(reg) << 4] = {wdata, 0}; \
        CHECK_REG(reg); \
        STATE.XPR.write(reg, wdata); \
      })

以上就是Spike在运行时指令获取和指令执行的大体流程。

Qemu机制与自定义指令添加指南

Tue, 13 Aug 2024 00:00:00 GMT

qemu 基础逻辑

qemu 虚拟机提供两种 CPU 实现的方式，一种是基于中间码的实现，一种是基于 KVM 的实现。第一种方式一般被叫做叫 tcg(tiny code generator)，这种方式的基本思路是用纯软件的方式把 target CPU 的指令先翻译成中间码，然后再把中间码翻译成 host CPU 的指令，通常把 target CPU 指令翻译成中间码的过程叫整个过程的前端，中间码翻译成 host CPU 的过程对应的叫做后端。给 qemu 增加一个新 CPU 的模型需要既增加前端也增加后端，如果要模拟整个系统，还要增加基础设备以及 user mode 的支持。如果目的是在一个成熟的平台上验证另一个新的 CPU，比如在 x86 机器上跑 riscv 的虚拟机，验证 riscv 的逻辑，只需要加上 riscv 指令到中间码这个前端支持就可以了，因为中间码到 x86 的后端已经存在；如果目的是在一台 riscv 的机器上模拟 x86 架构，就需要添加中间码到 riscv 的后端支持。

KVM（Kernel Virtual Machine）是 Linux 的一个内核驱动模块，它能够让 Linux 主机成为一个 Hypervisor（虚拟机监控器）。QEMU 虚拟机是一个纯软件的实现，可以在没有 KVM 模块的情况下独立运行，但是性能会较低一些。QEMU 有整套的虚拟机实现，包括处理器虚拟化、内存虚拟化以及 I/O 设备的虚拟化。QEMU 默认使用纯软件模拟来模拟 CPU 的执行。当启用 KVM 时，QEMU 将 CPU 的执行转交给 KVM 来处理。在硬件支持的情况下，KVM 将直接使用主机 CPU 的硬件虚拟化扩展来执行虚拟机中的指令，从而极大地提升性能。简单来说，KVM 和 QEMU 相辅相成，QEMU 通过 KVM 达到了硬件虚拟化的速度，而 KVM 则通过 QEMU 来模拟设备。我们暂时只关注第一种方式。riscv 体系相关的前端的代码在：target/riscv/，后端的代码在：tcg/riscv/，基础外设和 machine 的代码在 hw/riscv/。

qemu tcg 前端解码逻辑

把 target cpu 指令翻译成 host cpu 指令有两种方式，一种是使用 helper 函数，一种是使用 TCG 函数的方式。通常是使用 TCG 函数来操作数据、翻译指令，只有在某些 TCG 操作不方便或者无法模拟 CPU 操作时才会使用 helper 函数。

如果把逻辑拉高一层来看，所谓 target CPU 的运行，实际上是根据 target CPU 指令流去不断的改变 target CPU 数据结构里的数据状态。因为实际的代码要运行到 host CPU 上，所以 target 代码要被翻译成 host 代码，才可以执行，通过执行模拟改变 target CPU 的数据状态。qemu 为了解耦把 target CPU 代码先翻译成中间码，翻译成的中间码的语义也就是改变 target CPU 数据状态的一组==描述语句==，所以 target CPU 状态参数会被当做入参传入中间码描述语句。这组中间码是改变 CPU 状态的抽象的描述，有些 CPU 上的状态不好抽象成一般的描述就用 helper 函数的方式补充，所以 helper 函数也是改变 target CPU 状态的描述。

如果要用 tcg 的方式，就需要使用 tcg_gen_xxx 的函数组织逻辑描述 target CPU 指令对 target CPU 状态的改变。一些公共的代码会自动生成的，qemu 里使用 decode tree 的方式自动生成这一部分代码。

riscv 的指令描述在 target/riscv/insn16.decode、insn32.decode 里（包括指令编码、参数位置、入参结构体等），qemu 编译的时候会解析.decode 文件，使用脚本(scripts/decodetree.py)生成对应的定义和函数，生成的文件放在 qemu/build/libqemu-riscv64-softmmu.fa.p/decode-insn32.c.inc，decode-insn16.c.inc 里。这些文件生成的 trans_xxx 函数只是声明，具体功能需要自己实现，riscv 的这部分实现是放在了在 target/riscv/insn_trans/*里。生成的文件里有两个很大的解码函数 decode-insn32.c.inc 和 decode-insn16.c.inc，qemu 把 target CPU 指令翻译成中间码的时候就需要调用上面两个解码函数，通过查找解码树来调用对应的翻译函数。

现在用 riscv 架构下 user mode 的代码来看看上层具体调用关系。qemu 提供 system mode 和 user mode 的模拟方式，其中 system mode 会完整模拟整个系统，一个完整的 OS 可以运行在这个模拟的系统上，user mode 只是支持加载一个 target CPU 构架的用户态程序来跑，对于一般指令使用 tcg 的方式翻译执行，对于用户态程序里的系统调用，user mode 代码里模拟实现了==系统调用==的过程。linux user mode 的代码在 qemu/linux-user/*，具体的调用过程如下：

/* qemu/linux-user/main.c */
main
  +-> cpu_loop
    +-> cpu_exec
      +-> tb_gen_code
      |     /* qemu/target/riscv/trannslate.c */
      | +-> gen_intermediate_code
      | | +-> translator_loop(&riscv_tr_ops, xxx)
      | |       /* riscv_tr_translate_insn */
      | |   +-> ops->translator_insn
      | |     +-> decode_ops
      | |       +-> decode_insn16
      | |       +-> decode_insn32
      | +-> tcg_gen_code
      |   +-> tcg_out_xxx
      +-> cpu_loop_exec_tb

gen_intermediate_code 是前端的解码函数，把 target CPU 的指令翻译成 tcg 中间码。tcg_gen_code 是后端，把中间码翻译成 host CPU 上的指令，其中 tcg_out_xxx 的一组函数做具体的翻译工作。下面展开其中的各个细节：

tcg 整个翻译流程构架分析
decode tree 的语法
tcg trans_xxx 函数的语法

tcg 翻译流程

整个 tcg 前后端的翻译流程按指令块的粒度来搞，收集一个指令块翻译成中间码，然后把中间码翻译成 host CPU 指令，整个过程动态执行。为了加速翻译，qemu 把翻译成的 host CPU 指令块做了缓存，tcg 前端解码的时候，先在缓存里找，如果找见就直接执行。

decode tree 语法

CPU 指令编码通常是按组划分的，因此可以用 decode 去描述这些固定的结构，然后 qemu 根据这些指令定义，使用一个脚本(scripts/decodetree.py)在编译的时候生成解码函数的框架。 decode tree 里定义了几个描述：field，argument，format，pattern，group。CPU 在解码的时候总要把指令中的特性 field 中的数据取出作为入参(寄存器编号，立即数，操作码等)，field 描述一个指令编码中特定的域段，根据描述可以生成取对应域段的函数。

+---------------------------+---------------------------------------------+
| Input                     | Generated code                              |
+===========================+=============================================+
| %disp   0:s16             | sextract(i, 0, 16)                          |
+---------------------------+---------------------------------------------+
| %imm9   16:6 10:3         | extract(i, 16, 6) << 3 | extract(i, 10, 3)  |
+---------------------------+---------------------------------------------+
| %disp12 0:s1 1:1 2:10     | sextract(i, 0, 1) << 11 |                   |
|                           |    extract(i, 1, 1) << 10 |                 |
|                           |    extract(i, 2, 10)                        |
+---------------------------+---------------------------------------------+
| %shimm8 5:s8 13:1         | expand_shimm8(sextract(i, 5, 8) << 1 |      |
|   !function=expand_shimm8 |               extract(i, 13, 1))            |
+---------------------------+---------------------------------------------+

一个数据，比如一个立即数，可能是多个域段拼成的，所以就有相应的移位操作，再比如有些立即数是编码域段的数值取出来后再进过简单运算得到的，field 定义中带的函数就可以完成这样的计算。 argument 用来定义数据结构，比如，riscv insn32.decode 里定义的: &b imm rs2 rs1，编译后的 decode-insn32.c.inc 里生成的数据结构如下，这个结构会作为 trans_xxx 函数的入参。

typedef struct {
    int imm;
    int rs2;
    int rs1;
} arg_b;

format 定义指令的格式。

@r       .......   ..... ..... ... ..... ....... &r                %rs2 %rs1 %rd
@i       ............    ..... ... ..... ....... &i      imm=%imm_i     %rs1 %rd

比如上面就是对一个 32bit 指令编码的描述，. 表示一个 0 或者 1 的 bit 位，描述里可以用 field、之前定义的 filed 的引用、argument 的引用，field 的引用还可以赋值。field 可以用来匹配，argument 用来生成 trans_xxx 函数的入参。 pattern 用来定义具体指令。比如 riscv32 里的 lui 指令：

lui      ....................       ..... 0110111 @u
@u       ....................      ..... ....... &u      imm=%imm_u          %rd
&u    imm rd
%imm_u    12:s20                 !function=ex_shift_12
%rd        7:5

上面把相关的 format、argument、field 的定义也列了出来。可以看到 lui 的操作码是 0110111，这个指令的格式定义是@u，这个格式定义使用的参数定义是&u，&u 就是 trans_lui 函数入参结构体里的变量的定义，其中定义的变量名字是 imm、rd，这个 imm 实际的格式是%imm_i, 它是一个在指令编码 31-12bit 定义立即数，要把 31-12bit 的数值左移 12bit 得到最终结果，rd 实际的格式是%rd，是一个在指令编码 11-7bit 定义的 rd 寄存器的标号。可以看到 riscv 里对应的 trans 函数的实现如下，在编译时，脚本只生成一个空函数，函数内容需要前端实现者编写。

static bool trans_lui(DisasContext *ctx, arg_lui *a)
{
    if (a->rd != 0) {
        tcg_gen_movi_tl(cpu_gpr[a->rd], a->imm);
    }
    return true;
}

trans_xxx 函数的逻辑

trans_xxxx 函数的作用是生成中间码指令。以 riscv 的 add 指令为例，如下是 trans_rvi.c.inc 里 add 指令的模拟。

static bool trans_add(DisasContext *ctx, arg_add *a)
{
    return gen_arith(ctx, a, EXT_NONE, tcg_gen_add_tl, tcg_gen_add2_tl);
}
static bool gen_arith(DisasContext *ctx, arg_r *a, DisasExtend ext,
                      void (*func)(TCGv, TCGv, TCGv),
                      void (*f128)(TCGv, TCGv, TCGv, TCGv, TCGv, TCGv))
{
    TCGv dest = dest_gpr(ctx, a->rd);
    TCGv src1 = get_gpr(ctx, a->rs1, ext);
    TCGv src2 = get_gpr(ctx, a->rs2, ext);
    if (get_ol(ctx) < MXL_RV128) {
        func(dest, src1, src2);
        gen_set_gpr(ctx, a->rd, dest);
    } else {
        if (f128 == NULL) {
            return false;
        }
        TCGv src1h = get_gprh(ctx, a->rs1);
        TCGv src2h = get_gprh(ctx, a->rs2);
        TCGv desth = dest_gprh(ctx, a->rd);
        f128(dest, desth, src1, src1h, src2, src2h);
        gen_set_gpr128(ctx, a->rd, dest, desth);
    }
    return true;
}

tcg_gen_add_i32 可以看作为 tcg_gen_add_tl 的函数入参，riscv 的 add 指令从 target CPU 的 rs1，rs2 两个寄存器里取两个加数，相加后放到 rd 寄存器里。这里在 TCG 体系中的操作从直观上看应该是已经操作完成了，但是实际上这里的操作只是保存了这一条指令的操作语义。tcg_gen_add_i32 的实现为：

void tcg_gen_add_i32(TCGv_i32 ret, TCGv_i32 arg1, TCGv_i32 arg2)
{
    tcg_gen_op3_i32(INDEX_op_add_i32, ret, arg1, arg2);
}
tcg_gen_add_i32(TCGv_i32 ret, TCGv_i32 arg1, TCGv_i32 arg2)|tcg_gen_add_tl
  -> tcg_gen_op3_i32(TCGOpcode opc, TCGv_i32 a1, TCGv_i32 a2, TCGv_i32 a3)
    -> tcg_gen_op3(TCGOpcode opc, TCGArg a1, TCGArg a2, TCGArg a3)
        -> TCGOp *op = tcg_emit_op(opc, 3);
    	-> op->args[0] = a1;
    	-> op->args[1] = a2;
    	-> op->args[2] = a3;

可以看到最后生成的指令把数据挂到了一个链表里，后面的后端解码会把这些指令翻译成 host 指令。

TCG 体系的数据结构

这里需要简单介绍一下 TCG 体系的数据结构的定义。

// tcg/tcg.h
// TCG 的核心数据结构之一，它包含了 TCG 状态的所有全局信息
struct TCGContext {
    /* ... other fields ... */
    TCGOp *ops;               // 当前正在生成的 TCG 操作
    TCGTemp *temps;           // 临时变量数组
    int nb_temps;             // 临时变量数量
    TCGLabel *labels;         // 标签数组
    int nb_labels;            // 标签数量
    int code_gen_buffer_size; // 代码生成缓冲区大小
    uint8_t *code_gen_buffer; // 代码生成缓冲区
    /* ... other fields ... */
};

// tcg/tcg.h
// 表示一个 TCG 操作，通常是翻译后的目标指令
typedef struct TCGOp {
    TCGOpcode opc;           // 操作码
    TCGArg args[TCG_MAX_OP_ARGS]; // 操作的参数
} TCGOp;

// tcg/tcg.h
// 表示一个 TCG 临时变量
struct TCGTemp {
    TCGType type;            // 临时变量类型
    int val_type;            // 值类型
    int reg;                 // 寄存器编号
    int mem_reg;             // 内存寄存器编号
    tcg_target_long val;     // 临时变量的值
    /* ... other fields ... */
};

// tcg/tcg.h
// 表示一个标签，用于标记代码生成中的位置
typedef struct TCGLabel {
    tcg_insn_unit *label_ptr; // 标签指针，指向生成代码的位置
} TCGLabel;

// tcg/tcg-opc.h
// 一个枚举类型，表示 TCG 支持的所有操作码
typedef enum TCGOpcode {
    INDEX_op_add_i32,
    INDEX_op_sub_i32,
    /* ... other opcodes ... */
} TCGOpcode;

那么 TCG 创建的变量存在哪里？TCGv cpu_gpr[reg_num]是一个全局变量，它如何索引到 target CPU 的寄存器？

get_gpr(ctx, a->rs2, ext) <==> return cpu_gpr[reg_num]
// cpu_gpr[i] 会在每个TB块CPUStatus初始化时创建
riscv_translate_init
	->cpu_gpr[i] = tcg_global_mem_new(tcg_env, offsetof(CPURISCVState, gpr[i]), riscv_int_regnames[i]);

首先 tcg_temp_new 分配的空间是在 TCGContext tcg_ctx 里的，所谓创建一个这样的 TCGv 就是在 tcg_ctx 里用去一个 TCGTemp。cpu_gpr[reg_num]可以索引到 target CPU 寄存器的基本逻辑就是只要在前端和后端约定好描述 target CPU 的软件结构，cpu_gpr[reg_num]描述的就是相关寄存器在这个软件结构里的位置。然后 tcg_env 在 tcg_context_init(unsigned max_cpus)里初始化，得到的是 tcg_ctx 里 TCGTemp temps 的地址。 tcg_global_mem_new 在 tcg_ctx 里从 TCGTemp temps 上分配空间，返回空间在 tcg_ctx 上的相对地址。这样 cpu_gpr[reg_name]就可以作为标记在前端和后端之间建立连接。后端的代码直接把中间码翻译成 host 指令，中间码中的 TCGv 直接映射到 host CPU 的寄存器上，从逻辑上讲，应该是翻译得到的 host 代码修改中间码对应 TCGv 对应的内存才对。这里的逻辑是 qemu 在生成的中间码中以及 TB 执行后做了 host 寄存器到 target CPU 描述内存之间的同步。

指令添加流程

通过以上针对 TCG 前端的分析，这里会通过一个例子来展示如何添加 RISC-V 自定义指令，以 SADD 饱和加法指令为例。首先需要在 insn32.decode 文件中定义指令编码，因为操作数格式与 r 类指令相同，因此不需要添加新的 Argument。

sadd     0000000 .....    ..... 000 ..... 0001011 @r

通过 decodetree.py 脚本生成后会得到 sadd 指令的翻译函数与入参结构体(qemu/build/libqemu-riscv32-softmmu.fa.p/decode-insn32.c.inc)：

typedef struct {
    int rd;
    int rs1;
    int rs2;
} arg_r;
typedef arg_r arg_sadd;
static bool trans_sadd(DisasContext *ctx, arg_sadd *a);

同时，sadd 指令的解析也被添加到 decode tree 中：

case 0x0000000b:
        /* ........ ........ ........ .0001011 */
        switch (insn & 0xf8007000u) {
        case 0x00000000:
            /* 00000... ........ .000.... .0001011 */
            decode_insn32_extract_r(ctx, &u.f_r, insn);
            switch ((insn >> 25) & 0x3) {
            case 0x0:
                /* 0000000. ........ .000.... .0001011 */
                /* ../target/riscv/insn32.decode:187 */
                if (trans_sadd(ctx, &u.f_r)) return true;
                break;
            }
            break;

具体的 trans_sadd()函数功能需要我们在翻译文件中自己添加实现：

target/riscv/insn_trans/trans_rvi.c.inc
static bool trans_sadd(DisasContext *ctx, arg_sadd *a)
{
    return gen_sadd(ctx, a, EXT_NONE);
}
static bool gen_sadd(DisasContext *ctx, arg_r *a, DisasExtend ext)
{
    TCGv rd = dest_gpr(ctx, a->rd);
    TCGv rs1 = get_gpr(ctx, a->rs1, ext);
    TCGv rs2 = get_gpr(ctx, a->rs2, ext);
    TCGv temp = tcg_temp_new_i32();
    TCGv max_val = tcg_constant_i32(0x7fffffff);
    TCGv min_val = tcg_constant_i32(0x80000000);
    TCGv zero = tcg_constant_i32(0);
    // temp = rs1 + rs2
    tcg_gen_add_i32(temp, rs1, rs2);
    // checkout overflow = (rs1 > 0 && rs2 > 0 && temp < 0)
    TCGv_i32 overflow = tcg_temp_new_i32();
    TCGv_i32 temp_cond = tcg_temp_new_i32();
    tcg_gen_setcond_i32(TCG_COND_GT, overflow, rs1, zero);
    tcg_gen_setcond_i32(TCG_COND_GT, temp_cond, rs2, zero);
    tcg_gen_and_i32(overflow, overflow, temp_cond);
    tcg_gen_setcond_i32(TCG_COND_LT, temp_cond, temp, zero);
    tcg_gen_and_i32(overflow, overflow, temp_cond);
    // checkout underflow = (rs1 < 0 && rs2 < 0 && temp >= 0)
    TCGv_i32 underflow = tcg_temp_new_i32();
    tcg_gen_setcond_i32(TCG_COND_LT, underflow, rs1, zero);
    tcg_gen_setcond_i32(TCG_COND_LT, temp_cond, rs2, zero);
    tcg_gen_and_i32(underflow, underflow, temp_cond);
    tcg_gen_setcond_i32(TCG_COND_GE, temp_cond, temp, zero);
    tcg_gen_and_i32(underflow, underflow, temp_cond);
    /// if overflow, result = INT32_MAX
    tcg_gen_movcond_i32(TCG_COND_NE, rd, overflow, zero, max_val, temp);
    // if underflow, result = INT32_MIN
    tcg_gen_movcond_i32(TCG_COND_NE, rd, underflow, zero, min_val, temp);
    return true;
}

总体的添加流程简述如上。

Conda 使用

Sat, 27 Apr 2024 00:00:00 GMT

背景：在云服务器通过 conda 的虚拟环境安装 qemu 的依赖环境，将环境打包迁移部署到内网

Miniconda 介绍

Conda 是用于管理依赖包和虚拟环境的工具（常常被用来作为 Python 环境管理和包管理的工具，但实际也是非常好用的 C++/C 包管理工具）。Anaconda 是一个完整的带有 Conda 工具的软件包，包含了 conda、python 等 180 多个科学包及其依赖项。它主要用于科学计算和数据分析，并提供了包管理与环境管理的功能。Anaconda 的安装包比较大，因为它预装了大量的科学计算工具和包。Miniconda 是 Anaconda 的轻量版，只包含 conda 和 Python，但没有包含 Anaconda 中捆绑的科学计算和数据分析用的包。 Miniconda 的安装与换源暂且不表。

Miniconda 使用

创建并激活 Conda 虚拟环境

 conda create -n qemu_env python=3.12
 conda activate qemu_env

添加 Conda-Forge 频道

 conda config --add channels conda-forge

conda-forge 是一个广泛使用的社区驱动的 Conda 包管理器通道（channel）。它由开源社区维护，包含了大量高质量的开源软件包和库。与官方的 Conda 通道相比，conda-forge 通道通常会包含更多的包，更新速度也更快。

安装所需要的包

 conda search xxx
 conda install xxx
 # or
 conda install -c conda-forge xxx # -c 参数用于指定要安装软件包的通道（channel）
 # or
 pip install xxx

查看已安装的包（库）版本

 ninja --version
 > 1.10.2
 pkg-config --modversion glib-2.0
 > 2.78.0
 #or
 ls $CONDA_PREFIX/lib

要确保安装的目录在虚拟环境下

 which pkg-config
 > /root/miniconda3/envs/qemu_env/bin/pkg-config
 which pip
 > /root/miniconda3/envs/qemu_env/bin/pip
 export PATH=$CONDA_PREFIX/bin:$PATH

按照以上步骤安装的软件包或者库文件会安装在当前虚拟环境下。（确认是否进入创建的虚拟环境，而不是 base 环境）

虚拟环境打包及迁移

以下介绍仅适用于同系统下虚拟环境迁移，不同系统之间迁移情况会略有不同。

打包虚拟环境

定位虚拟环境路径

 conda info --envs

打包虚拟环境目录

 tar -czvf qemu_env.tar.gz -C /path/to/conda/envs/qemu_env ./

生成一个包含虚拟环境的压缩文件 qemu_env.tar.gz

迁移虚拟环境

内网服务器上解压并导入打包好的 Conda 环境

 tar -xzvf qemu_env.tar.gz -C /path/to/conda/envs/qemu_env

💡 需要提前在内网服务器安装好 Miniconda，但是不需要提前创建新的虚拟环境

激活环境

conda activate qemu_env

验证环境完整性

在服务器上激活环境后，确保所有包和依赖都存在

conda list

文件权限: 确保迁移后的文件拥有正确的权限，特别是在不同用户之间迁移时，可能需要修改文件权限以确保虚拟环境能够正常使用。

外部依赖: 如果虚拟环境中依赖系统库，需要确认这些库在当前服务器上也已安装。

解决版本冲突

可能迁移成功后虚拟环境中有的包的版本与外部包的版本不一致，而当前所使用的包指向的是外部的包。这个问题通常与环境变量的优先级、路径设置以及多个版本的库共存有关。 e.g. 在 Conda 环境中安装了 glib-2.78.0，但是 pkg-config 仍然指向系统的 glib-2.56.4，则可能是因为环境变量或路径配置导致了这个冲突。

确认 `pkg-config` 使用的是 Conda 环境的版本

**激活虚拟环境：**确保 Conda 虚拟环境 qemu_env 已激活
检查 pkg-config 的路径： 确保当前的 pkg-config 来自 Conda 环境
验证 pkg-config 中的包版本

确保 Conda 环境中的 `pkg-config` 优先级

export PATH=$CONDA_PREFIX/bin:$PATH

设置链接库优先级

在某些应用程序编译过程中，可能仍然会链接到系统的 glib，此时可以检查链接器的配置。确保编译过程中使用的 LD_LIBRARY_PATH 和链接器标志指向 Conda 环境中的库文件。

export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH

以上为 Conda 虚拟环境的简单使用

Docker 学习

Thu, 02 Mar 2023 00:00:00 GMT

1. 初识 Docker

1.1. 什么是 Docker

分布式系统中，依赖的组件非常多，不同组件之间部署时往往会产生一些冲突。
在数百上千台服务中重复部署，环境不一定一致，会遇到各种问题。

1.1.1. 应用部署的环境问题

大型项目组件较多，运行环境也较为复杂，部署时会碰到一些问题：

依赖关系复杂，容易出现兼容性问题
开发、测试、生产环境有差异

例如一个项目中，部署时需要依赖于 node.js、Redis、RabbitMQ、MySQL 等，这些服务部署时所需要的函数库、依赖项各不相同，甚至会有冲突。给部署带来了极大的困难。

1.1.2. Docker 解决依赖兼容问题

Docker 为了解决依赖的兼容问题的，采用了两个手段：

将应用的 Libs（函数库）、Deps（依赖）、配置与应用一起打包
将每个应用放到一个隔离容器去运行，避免互相干扰

这样打包好的应用包中，既包含应用本身，也保护应用所需要的 Libs、Deps，无需再操作系统上安装这些，自然就不存在不同应用之间的兼容问题了。

1.1.3. Docker 解决操作系统环境差异

要解决不同操作系统环境差异问题，必须先了解操作系统结构。以一个 Ubuntu 操作系统为例，结构如下：

结构包括：

计算机硬件：例如 CPU、内存、磁盘等
系统内核：所有 Linux 发行版的内核都是 Linux，例如 CentOS、Ubuntu、Fedora 等。内核可以与计算机硬件交互，对外提供内核指令，用于操作计算机硬件。
系统应用：操作系统本身提供的应用、函数库。这些函数库是对内核指令的封装，使用更加方便。

应用与计算机交互的流程如下：

1）应用调用操作系统应用（函数库），实现各种功能

2）系统函数库是对内核指令集的封装，会调用内核指令

3）内核指令操作计算机硬件

Ubuntu 和 CentOS 都是基于 Linux 内核，无非是系统应用不同，提供的函数库有差异：

此时，如果将一个 Ubuntu 版本的 MySQL 应用安装到 CentOS 系统，MySQL 在调用 Ubuntu 函数库时，会发现找不到或者不匹配，就会报错了：

Docker 如何解决不同系统环境的问题？

Docker 将用户程序与所需要调用的系统 (比如 Ubuntu) 函数库一起打包
Docker 运行到不同操作系统时，直接基于打包的函数库，借助于操作系统的 Linux 内核来运行

如图：

1.1.4. 小结

Docker 如何解决大型项目依赖关系复杂，不同组件依赖的兼容性问题？

Docker 允许开发中将应用、依赖、函数库、配置一起打包，形成可移植镜像
Docker 应用运行在容器中，使用沙箱机制，相互隔离

Docker 如何解决开发、测试、生产环境有差异的问题？

Docker 镜像中包含完整运行环境，包括系统函数库，仅依赖系统的 Linux 内核，因此可以在任意 Linux 操作系统上运行

Docker 是一个快速交付应用、运行应用的技术，具备下列优势：

可以将程序及其依赖、运行环境一起打包为一个镜像，可以迁移到任意 Linux 操作系统
运行时利用沙箱机制形成隔离容器，各个应用互不干扰
启动、移除都可以通过一行命令完成，方便快捷

1.2. Docker 和虚拟机的区别

Docker 可以让一个应用在任何操作系统中非常方便的运行。而以前我们接触的虚拟机，也能在一个操作系统中，运行另外一个操作系统，保护系统中的任何应用。

两者有什么差异呢？

虚拟机（virtual machine）是在操作系统中模拟硬件设备，然后运行另一个操作系统，比如在 Windows 系统里面运行 Ubuntu 系统，这样就可以运行任意的 Ubuntu 应用了。

Docker 仅仅是封装函数库，并没有模拟完整的操作系统，如图：

对比来看：

小结：

Docker 和虚拟机的差异：

Docker 是一个系统进程；虚拟机是在操作系统中的操作系统
Docker 体积小、启动速度快、性能好；虚拟机体积大、启动速度慢、性能一般

1.3. Docker 架构

1.3.1. 镜像和容器

Docker 中有几个重要的概念：

镜像（Image）：Docker 将应用程序及其所需的依赖、函数库、环境、配置等文件打包在一起，称为镜像。

容器（Container）：镜像中的应用程序运行后形成的进程就是容器，只是 Docker 会给容器进程做隔离，对外不可见。

一切应用最终都是代码组成，都是硬盘中的一个个的字节形成的文件。只有运行时，才会加载到内存，形成进程。

而镜像，就是把一个应用在硬盘上的文件、及其运行环境、部分系统函数库文件一起打包形成的文件包。这个文件包是只读的。

容器呢，就是将这些文件中编写的程序、函数加载到内存中允许，形成进程，只不过要隔离起来。因此一个镜像可以启动多次，形成多个容器进程。

1.3.2. DockerHub

开源应用程序非常多，打包这些应用往往是重复的劳动。为了避免这些重复劳动，人们就会将自己打包的应用镜像，例如 Redis、MySQL 镜像放到网络上，共享使用，就像 GitHub 的代码共享一样。

DockerHub：DockerHub 是一个官方的 Docker 镜像的托管平台。这样的平台称为 Docker Registry。
国内也有类似于 DockerHub 的公开服务，比如网易云镜像服务、阿里云镜像库等。

我们一方面可以将自己的镜像共享到 DockerHub，另一方面也可以从 DockerHub 拉取镜像：

1.3.3. Docker 架构

我们要使用 Docker 来操作镜像、容器，就必须要安装 Docker。

Docker 是一个 CS 架构 of 程序，由两部分组成：

服务端 (server)：Docker 守护进程，负责处理 Docker 指令，管理镜像、容器等
客户端 (client)：通过命令或 RestAPI 向 Docker 服务端发送指令。可以在本地或远程向服务端发送指令。

如图：

1.3.4. 小结

镜像：

将应用程序及其依赖、环境、配置打包在一起

容器：

镜像运行起来就是容器，一个镜像可以运行多个容器

Docker 结构：

服务端：接收命令或远程请求，操作镜像或容器
客户端：发送命令或者请求到 Docker 服务端

DockerHub：

一个镜像托管的服务器，类似的还有阿里云镜像服务，统称为 DockerRegistry

1.4. 安装 Docker

企业部署一般都是采用 Linux 操作系统，而其中又数 CentOS 发行版占比最多，因此常在 CentOS 下安装 Docker。

Docker 分为 CE 和 EE 两大版本。CE 即社区版（免费，支持周期 7 个月），EE 即企业版，强调安全，付费使用，支持周期 24 个月。

Docker CE 分为 stable test 和 nightly 三个更新频道。

官方网站上有各种环境下的安装指南，这里主要介绍 Docker CE 在 CentOS 上的安装。

1.4.1. 卸载（可选）

如果之前安装过旧版本的 Docker，可以使用下面命令卸载：

yum remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-selinux \
                  docker-engine-selinux \
                  docker-engine \
                  docker-ce

1.4.2. 安装 Docker

首先需要大家虚拟机联网，安装 yum 工具

yum install -y yum-utils \
           device-mapper-persistent-data \
           lvm2 --skip-broken

然后更新本地镜像源：

# 设置 docker 镜像源
yum-config-manager \
    --add-repo \
    https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

sed -i 's/download.docker.com/mirrors.aliyun.com\/docker-ce/g' /etc/yum.repos.d/docker-ce.repo

yum makecache fast

然后输入命令：

yum install -y docker-ce

1.4.3. 启动 Docker

Docker 应用需要用到各种端口，逐一去修改防火墙设置。

# 关闭
systemctl stop firewalld
# 禁止开机启动防火墙
systemctl disable firewalld

通过命令启动 Docker：

systemctl start docker  # 启动 docker 服务
systemctl stop docker  # 停止 docker 服务
systemctl restart docker  # 重启 docker 服务

然后输入命令，可以查看 Docker 版本：

docker -v

如图：

2. Docker 的基本操作

2.1. 镜像操作

2.1.1. 镜像名称

首先来看下镜像的名称组成：

镜名称一般分两部分组成：[repository]:[tag]。
在没有指定 tag 时，默认是 latest，代表最新版本的镜像

如图：

2.1.2. 镜像命令

常见的镜像操作命令如图：

2.2. 容器操作

2.2.1. 容器相关命令

容器操作的命令如图：

2.3. 数据卷（容器数据管理）

2.3.1. 什么是数据卷

数据卷（volume） 是一个虚拟目录，指向宿主机文件系统中的某个目录。

一旦完成数据卷挂载，对容器的一切操作都会作用在数据卷对应的宿主机目录了。

3. Dockerfile 自定义镜像

3.1. 镜像结构

3.2. Dockerfile 语法

4. Docker-Compose

Docker Compose 可以基于 Compose 文件帮我们快速的部署分布式应用，而无需手动一个个创建和运行容器！