博客¶

切换 ConnectX-4 为以太网模式

背景

最近在给机房配置网络，遇到一个需求，就是想要把 ConnectX-4 当成以太网卡用，它既支持 Infiniband，又支持 Ethernet，只不过默认是 Infiniband 模式，所以需要用 mlxconfig 工具来做这个切换。

切换方法

在 Using mlxconfig 文档中，写了如何切换网卡为 Infiniband 模式：

$ mlxconfig -d /dev/mst/mt4103_pci_cr0 set LINK_TYPE_P1=1 LINK_TYPE_P2=1

Device #1:
----------
Device type:   ConnectX3Pro
PCI device:    /dev/mst/mt4103_pci_cr0
Configurations:        Next Boot        New
  LINK_TYPE_P1         ETH(2)           IB(1)
  LINK_TYPE_P2         ETH(2)           IB(1)

Apply new Configuration? ? (y/n) [n] : y
Applying... Done!
-I- Please reboot machine to load new configurations.

那么，我们只需要反其道而行之，设置模式为 ETH(2) 即可。

MST 安装

要使用 mlxconfig，就需要安装 MFT(Mellanox Firmware Tools)。我们用的是 Debian bookworm，于是要下载 DEB：

wget https://www.mellanox.com/downloads/MFT/mft-4.20.1-14-x86_64-deb.tgz
unar mft-4.20.1-14-x86_64-deb.tgz
cd mft-4.20.1-14-x86_64-deb

UPDATE 2022-10-28: 现在最新版本 mft-4.21.0-99 已经修复了下面出现的编译问题。

wget https://www.mellanox.com/downloads/MFT/mft-4.21.0-99-x86_64-deb.tgz
unar mft-4.21.0-99-x86_64-deb.tgz
cd mft-4.21.0-99-x86_64-deb

尝试用 sudo ./install.sh 安装，发现 dkms 报错。查看日志，发现是因为内核过高（5.18），有函数修改了用法，即要把 pci_unmap_single 的调用改为 dma_unmap_single，并且修改第一个参数，如 linux commit a2e759612e5ff3858856fe97be5245eecb84e29b 指出的那样：

-           pci_unmap_single(dev->pci_dev, dev->dma_props[i].dma_map, DMA_MBOX_SIZE, DMA_BIDIRECTIONAL);
+           dma_unmap_single(&dev->pci_dev->dev, dev->dma_props[i].dma_map, DMA_MBOX_SIZE, DMA_BIDIRECTIONAL);

修改完以后，手动 sudo dkms install kernel-mft-dkms/4.20.1，发现就编译成功了。再手动安装一下 mft 并启动服务：

$ sudo dpkg -i DEBS/mft_4.20.1-14_amd64.deb
$ sudo mst start
Starting MST (Mellanox Software Tools) driver set
Loading MST PCI module - Success
[warn] mst_pciconf is already loaded, skipping
Create devices
Unloading MST PCI module (unused) - Success
$ sudo mst status
MST modules:
------------
    MST PCI module is not loaded
    MST PCI configuration module loaded

MST devices:
------------
/dev/mst/mtxxxx_pciconf0         - PCI configuration cycles access.
                                   domain:bus:dev.fn=0000:xx:xx.0 addr.reg=yy data.reg=zz cr_bar.gw_offset=-1
                                   Chip revision is: 00

既然已经安装好了，最后执行 mlxconfig 即可切换为以太网：

$ sudo mlxconfig -d /dev/mst/mtxxxx_pciconf0 set LINK_TYPE_P1=2 LINK_TYPE_P2=2

Device #1:
----------

Device type:    ConnectX4
Name:           REDACTED
Description:    ConnectX-4 VPI adapter card; FDR IB (56Gb/s) and 40GbE; dual-port QSFP28; PCIe3.0 x8; ROHS R6
Device:         /dev/mst/mtxxxx_pciconf0

Configurations:                              Next Boot       New
         LINK_TYPE_P1                        IB(1)           ETH(2)
         LINK_TYPE_P2                        IB(1)           ETH(2)

 Apply new Configuration? (y/n) [n] : y
Applying... Done!
-I- Please reboot machine to load new configurations.

显示各个配置可能的选项和内容：sudo mlxconfig -d /dev/mst/mtxxxx_pciconf0 show_confs

整个安装流程在仓库 https://github.com/jiegec/mft-debian-bookworm 中用脚本实现。

UPDATE: 太新的 MFT 版本不支持比较旧的网卡，例如 4.22.1-LTS 支持 ConnectX-3，但 4.26.1-LTS 就不支持了。

VMware ESXi

如果要在 ESXi 上把网卡改成以太网模式，可以参考下面的文档：

• https://docs.nvidia.com/networking/pages/releaseview.action?pageId=15049813
• https://docs.nvidia.com/networking/plugins/servlet/mobile?contentId=15051769#content/view/15051769

命令（ESXi 7.0U3）：

scp *.vib root@esxi:/some/path
esxcli software vib install -v /some/path/MEL_bootbank_mft_4.21.0.703-0.vib
esxcli software vib install -v /some/path/MEL_bootbank_nmst_4.21.0.703-1OEM.703.0.0.18434556.vib
reboot
/opt/mellanox/bin/mst start
/opt/mellanox/bin/mst status -vv
/opt/mellanox/bin/mlxfwmanager --query
/opt/mellanox/bin/mlxconfig -d mt4115_pciconf0 set LINK_TYPE_P1=2 LINK_TYPE_P2=2
reboot

然后就可以看到网卡了。

rsyslog 收集远程日志

背景

最近在运维的时候发现网络设备（如交换机）有一个远程发送日志的功能，即可以通过 syslog udp 协议发送日志到指定的服务器。为此，可以在服务器上运行 rsyslog 并收集日志。

rsyslog 配置

默认的 rsyslog 配置是收集系统本地的配置，因此我们需要编写一个 rsyslog 配置，用于收集远程的日志。

首先复制 /etc/rsyslog.conf 到 /etc/rsyslog-remote.conf，然后修改：

1. 注释掉 imuxsock 和 imklog 相关的 module 加载
2. 去掉 imudp 和 imtcp 相关的注释，这样就会监听在相应的端口上
3. 修改 $WorkDirectory，例如 $WorkDirectory /var/spool/rsyslog-remote，防止与已有的 rsyslog 冲突
4. 注释 $IncludeConfig，防止引入了不必要的配置
5. 注释所有已有的 RULES 下面的配置
6. 添加如下配置：

$template FromIp,"/var/log/rsyslog-remote/%FROMHOST-IP%.log"
*.* ?FromIp

这样，就会按照来源的 IP 地址进行分类，然后都写入到 /var/log/rsyslog-remote/x.x.x.x.log 文件里。最后的 /etc/rsyslog-remote.conf 内容如下：

module(load="imudp")
input(type="imudp" port="514" address="1.2.3.4")

module(load="imtcp")
input(type="imtcp" port="514" address="1.2.3.4")

$FileOwner root
$FileGroup adm
$FileCreateMode 0640
$DirCreateMode 0755
$Umask 0022

$WorkDirectory /var/spool/rsyslog-remote

$template FromIp,"/var/log/rsyslog-remote/%FROMHOST-IP%.log"
*.* ?FromIp

此外，还需要手动创建 /var/spool/rsyslog-remote 和 /var/log/rsyslog-remote 目录。

systemd service

最后，写一个 systemd service /etc/systemd/system/rsyslog-remote.service 让它自动启动：

[Unit]
ConditionPathExists=/etc/rsyslog-remote.conf
Description=Remote Syslog Service

[Service]
Type=simple
PIDFile=/var/run/rsyslogd-remote.pid
ExecStart=/usr/sbin/rsyslogd -n -f /etc/rsyslog-remote.conf -i /var/run/rsyslogd-remote.pid
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target

立即启动并设置开机启动：

systemctl daemon-reload
systemctl enable --now rsyslog-remote

这样就实现了远程日志的收集。

logrotate 设置

为了防止日志太多，还需要配置 logrotate。

复制 /etc/logrotate.d/rsyslog 到 /etc/logrotate.d/rsyslog-remote，然后修改开头为 /var/log/rsyslog-remote/*.log 即可，路径和上面对应：

/var/log/rsyslog-remote/*.log
{
        rotate 4
        weekly
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
        postrotate
                /usr/lib/rsyslog/rsyslog-remote-rotate
        endscript
}

注意脚本 /usr/lib/rsyslog/rsyslog-remote 也需要复制一份到 /usr/lib/rsyslog/rsyslog-remote-rotate，然后修改一下 systemd service 名字：

#!/bin/sh

if [ -d /run/systemd/system ]; then
    systemctl kill -s HUP rsyslog-remote.service
fi

一键脚本

完成以上所有事情的一键脚本：

# assuming bash
# please change ip address below
cat > /etc/rsyslog-remote.conf << 'EOL'
module(load="imudp")
input(type="imudp" port="514" address="1.2.3.4")

module(load="imtcp")
input(type="imtcp" port="514" address="1.2.3.4")

$FileOwner root
$FileGroup adm
$FileCreateMode 0640
$DirCreateMode 0755
$Umask 0022

$WorkDirectory /var/spool/rsyslog-remote

$template FromIp,"/var/log/rsyslog-remote/%FROMHOST-IP%.log"
*.* ?FromIp
EOL
mkdir -p /var/spool/rsyslog-remote
mkdir -p /var/log/rsyslog-remote
cat > /etc/systemd/system/rsyslog-remote.service << 'EOL'
[Unit]
ConditionPathExists=/etc/rsyslog-remote.conf
Description=Remote Syslog Service

[Service]
Type=simple
PIDFile=/var/run/rsyslogd-remote.pid
ExecStart=/usr/sbin/rsyslogd -n -f /etc/rsyslog-remote.conf -i /var/run/rsyslogd-remote.pid
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target
EOL
systemctl daemon-reload
systemctl enable --now rsyslog-remote
cat > /etc/logrotate.d/rsyslog-remote << 'EOL'
/var/log/rsyslog-remote/*.log
{
        rotate 4
        weekly
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
        postrotate
                /usr/lib/rsyslog/rsyslog-remote-rotate
        endscript
}
EOL
cat > /usr/lib/rsyslog/rsyslog-remote-rotate << 'EOL'
#!/bin/sh

if [ -d /run/systemd/system ]; then
    systemctl kill -s HUP rsyslog-remote.service
fi
EOL
chmod +x /usr/lib/rsyslog/rsyslog-remote-rotate

syslog 客户端配置

配好服务端以后，很多服务都支持远程 syslog 功能：

• iBMC: 维护诊断->告警上报->Syslog 报文通知
• Supermicro BMC: Configuration->Syslog
• 交换机：见 常用交换机命令

• ESXi: 见 Configuring syslog on ESXi：

  esxcli system syslog config set --loghost=udp://1.2.3.4
  esxcli system syslog reload
  esxcli network firewall ruleset set --ruleset-id=syslog --enabled=true
  esxcli network firewall refresh
  

参考文档

• How to Set Up Remote Logging on Linux Using rsyslog
• Configuring Remote Logging using rsyslog in CentOS/RHEL
• How to Setup Central Logging Server with Rsyslog in Linux
• How to Setup Rsyslog Client to Send Logs to Rsyslog Server in CentOS 7

「教学」Wishbone 总线协议

本文的内容已经整合到知识库中。

背景

最近在研究如何把 Wishbone 总线协议引入计算机组成原理课程，因此趁此机会学习了一下 Wishbone 的协议。

总线

总线是什么？总线通常用于连接 CPU 和外设，为了更好的兼容性和可复用性，会想到能否设计一个统一的协议，其中 CPU 实现的是发起请求的一方（又称为 master），外设实现的是接收请求的一方（又称为 slave），那么如果要添加外设、或者替换 CPU 实现，都会变得比较简单，减少了许多适配的工作量。

那么，我们来思考一下，一个总线协议需要包括哪些内容？对于 CPU 来说，程序会读写内存，读写内存就需要以下几个信号传输到内存：

1. 地址（addr）：例如 32 位处理器就是 32 位地址，或者按照内存的大小计算地址线的宽度
2. 数据（w_data 和 r_data）：分别是写数据和读数据，宽度通常为 32 位 或 64 位，也就是一个时钟周期可以传输的数据量
3. 读还是写（we）：高表示写，低表示读
4. 字节有效（be）：例如为了实现单字节写，虽然 w_data 可能是 32 位宽，但是实际写入的是其中的一个字节

除了请求的内容以外，为了表示 CPU 想要发送请求，还需要添加 valid 信号：高表示发送请求，低表示不发送请求。很多时候，外设的速度比较慢，可能无法保证每个周期都可以处理请求，因此外设可以提供一个 ready 信号：当 valid=1 && ready=1 的时候，发送并处理请求；当 valid=1 && ready=0 的时候，表示外设还没有准备好，此时 CPU 需要一直保持 valid=1 不变，等到外设准备好后，valid=1 && ready=1 请求生效。

简单总结一下上面的需求，可以得到 master 和 slave 端分别的信号列表。这次，我们在命名的时候用 _o 表示输出、_i 表示输入，可以得到 master 端（CPU 端）的信号：

1. clock_i：时钟输入
2. valid_o：高表示 master 想要发送请求
3. ready_i：高表示 slave 准备好处理请求
4. addr_o：master 想要读写的地址
5. we_o：master 想要读还是写
6. data_o：master 想要写入的数据
7. be_o：master 读写的字节使能，用于实现单字节写等
8. data_i：slave 提供给 master 的读取的数据

除了时钟都是输入以外，把上面其余的信号输入、输出对称一下，就可以得到 slave 端（外设端）的信号：

1. clock_i：时钟输入
2. valid_i：高表示 master 想要发送请求
3. ready_o：高表示 slave 准备好处理请求
4. addr_i：master 想要读写的地址
5. we_i：master 想要读还是写
6. data_i：master 想要写入的数据
7. be_i：master 读写的字节使能，用于实现单字节写等
8. data_o：slave 提供给 master 的读取的数据

根据我们上面设计的自研总线，可以绘制出下面的波形图（以 master 的信号为例）：

• a 周期：此时 valid_o=1 && ready_i=1 说明有请求发生，此时 we_o=1 说明是一个写操作，并且写入地址是 addr_o=0x01，写入的数据是 data_o=0x12
• b 周期：此时 valid_o=0 && ready_i=0 说明无事发生
• c 周期：此时 valid_o=1 && ready_i=0 说明 master 想要从地址 0x02（addr_o=0x02）读取数据（we_o=0），但是 slave 没有接受（ready_i=0）
• d 周期：此时 valid_o=1 && ready_i=1 说明有请求发生，master 从地址 0x02（addr_o=0x02）读取数据（we_o=0），读取的数据为 0x34（data_i=0x34）
• e 周期：此时 valid_o=0 && ready_i=0 说明无事发生
• f 周期：此时 valid_o=1 && ready_i=1 说明有请求发生，master 向地址 0x03（addr_o=0x03）写入数据（we_o=1），写入的数据为 0x56（data_i=0x56）
• g 周期：此时 valid_o=1 && ready_i=1 说明有请求发生，master 从地址 0x01（addr_o=0x01）读取数据（we_o=0），读取的数据为 0x12（data_i=0x12）
• h 周期：此时 valid_o=1 && ready_i=1 说明有请求发生，master 向地址 0x02（addr_o=0x02）写入数据（we_o=1），写入的数据为 0x9a（data_i=0x9a）

从上面的波形中，可以有几点观察：

1. master 想要发起请求的时候，就设置 valid_o=1；当 slave 可以接受请求的时候，就设置 ready_i=1；在 valid_o=1 && ready_i=1 时视为一次请求
2. 如果 master 发起请求，同时 slave 不能接收请求，即 valid_o=1 && ready_i=0，此时 master 要保持 addr_o we_o data_o 和 be_o 不变，直到请求结束
3. 当 master 不发起请求的时候，即 valid_o=0，此时总线上的信号都视为无效数据，不应该进行处理；对于读操作，只有在 valid_o=1 && ready_i=1 时 data_i 上的数据是有效的
4. 可以连续多个周期发生请求，即 valid_o=1 && ready_i=1 连续多个周期等于一，此时是理想情况，可以达到总线最高的传输速度

Wishbone Classic Standard

首先我们来看最简单的 Wishbone 版本 Wishbone Classic Standard。其设计思路和上面的自研总线非常相似，让我们来看看它的信号，例如 master 端（CPU 端）的信号：

1. CLK_I: 时钟输入，即自研总线中的 clock_i
2. STB_O：高表示 master 要发送请求，即自研总线中的 valid_o
3. ACK_I：高表示 slave 处理请求，即自研总线中的 ready_i
4. ADR_O：master 想要读写的地址，即自研总线中的 addr_o
5. WE_O：master 想要读还是写，即自研总线中的 we_o
6. DAT_O：master 想要写入的数据，即自研总线中的 data_o
7. SEL_O：master 读写的字节使能，即自研总线中的 be_o
8. DAT_I：master 从 slave 读取的数据，即自研总线中的 data_i
9. CYC_O：总线的使能信号，无对应的自研总线信号

还有一些可选信号，这里就不赘述了。可以看到，除了最后一个 CYC_O，其他的信号其实就是我们刚刚设计的自研总线。CYC_O 的可以认为是 master 想要占用 slave 的总线接口，在常见的使用场景下，直接认为 CYC_O=STB_O。它的用途是：

1. 占用 slave 的总线接口，不允许其他 master 访问
2. 简化 interconnect 的实现

把上面自研总线的波形图改成 Wishbone Classic Standard，就可以得到：

Wishbone Classic Pipelined

上面的 Wishbone Classic Standard 协议非常简单，但是会遇到一个问题：假设实现的是一个 SRAM 控制器，它的读操作有一个周期的延迟，也就是说，在这个周期给出地址，需要在下一个周期才可以得到结果。在 Wishbone Classic Standard 中，就会出现下面的波形：

• a 周期：master 给出读地址 0x01，此时 SRAM 控制器开始读取，但是此时数据还没有读取回来，所以 ACK_I=0
• b 周期：此时 SRAM 完成了读取，把读取的数据 0x12 放在 DAT_I 并设置 ACK_I=1
• c 周期：master 给出下一个读地址 0x02，SRAM 要重新开始读取
• d 周期：此时 SRAM 完成了第二次读取，把读取的数据 0x34 放在 DAT_I 并设置 ACK_I=1

从波形来看，功能没有问题，但是每两个周期才能进行一次读操作，发挥不了最高的性能。那么怎么解决这个问题呢？我们在 a 周期给出第一个地址，在 b 周期得到第一个数据，那么如果能在 b 周期的时候给出第二个地址，就可以在 c 周期得到第二个数据。这样，就可以实现流水线式的每个周期进行一次读操作。但是，Wishbone Classic Standard 要求 b 周期时第一次请求还没有结束，因此我们需要修改协议，来实现流水线式的请求。

实现思路也很简单：既然 Wishbone Classic Standard 认为 b 周期时，第一次请求还没有结束，那就让第一次请求提前在 a 周期完成，只不过它的数据要等到 b 周期才能给出。实际上，这个时候的一次读操作，可以认为分成了两部分：首先是 master 向 slave 发送读请求，这个请求在 a 周期完成；然后是 slave 向 master 发送读的结果，这个结果在 b 周期完成。为了实现这个功能，我们进行如下修改：

• 添加 STALL_I 信号：CYC_O=1 && STB_O=1 && STALL_I=0 表示进行一次读请求
• 修改 ACK_I 信号含义：CYC_O=1 && STB_O=1 && ACK_I=1 表示一次读响应

进行如上修改以后，我们就得到了 Wishbone Classic Pipelined 总线协议。上面的两次连续读操作波形如下：

• a 周期：master 请求读地址 0x01，slave 接收读请求（STALL_O=0）
• b 周期：slave 返回读请求结果 0x12，并设置 ACK_I=1；同时 master 请求读地址 0x02，slave 接收读请求（STALL_O=0）
• c 周期：slave 返回读请求结果 0x34，并设置 ACK_I=1；master 不再发起请求，设置 STB_O=0
• d 周期：所有请求完成，master 设置 CYC_O=0

这样我们就实现了一个每周期进行一次读操作的 slave。

参考文档

• Wishbone Spec B4

Nix Cookbook

背景

最近在尝试 NixOS 和在 macOS 上跑 Nix，下面记录一些我在使用过程中遇到的一些小问题和解决思路。

NixOS

全局配置

NixOS 的全局配置路径：/etc/nixos/configuration.nix 和 /etc/nixos/hardware-configuration.nix

应用更新后的全局配置：

nixos-rebuild switch
# or
nixos-rebuild switch --upgrade

应用 Flakes 配置文件并显示变化：

#!/usr/bin/env python3
import os

user = os.getenv("USER")
home = f"/nix/var/nix/profiles/"
old = home + os.readlink(f"{home}system")
os.system("sudo nixos-rebuild switch --flake .")
new = home + os.readlink(f"{home}system")
os.system(f"nix store diff-closures {old} {new}")

更新大版本

如果要更新 NixOS 21.11 到 22.05:

nix-channel --list
nix-channel --add https://nixos.org/channels/nixos-22.05 nixos
nixos-rebuild switch --upgrade

可以考虑改或者不改 /etc/nixos/configuration.nix 中的 system.stateVersion。

常用配置

常用的 NixOS 配置：

# Enable XFCE
services.xserver.enable = true;
services.xserver.desktopManager.xfce.enable = true;

# System wide packages
environment.systemPackages = with pkgs; [
  xxx
];

# Fish shell
programs.fish.enable = true;
users.users.xxx = {
  shell = pkgs.fish;
}

# Command not found
programs.command-not-found.enable = true;

# Steam gaming
nixpkgs.config.allowUnfree = true;
programs.steam.enable = true;

# NOPASSWD for sudo
security.sudo.wheelNeedsPassword = false;

# QEMU guest
services.qemuGuest.enable = true;
services.spice-vdagentd.enable = true;

# XRDP
services.xrdp.enable = true;
services.xrdp.defaultWindowManager = "xfce4-session";
services.xrdp.openFirewall = true;

# OpenSSH server
services.openssh.enable = true;

# Udev rules for Altera USB Blaster
services.udev.packages = with pkgs; [
  usb-blaster-udev-rules
];

VSCode Remote

VSCode Remote 会在远程的机器上运行一个预编译的 nodejs，运行的时候会因为路径问题无法执行。

解决方法在 NixOS Wiki 上有，具体来说，首先，需要安装 nodejs：

environment.systemPackages = with pkgs; [
  nodejs-16_x # vscode remote
];

然后，用软链接来覆盖 nodejs：

cd ~/.vscode-server/bin/HASH
ln -sf /run/current-system/sw/bin/node

这样就可以正常使用 VSCode Remote 了。

Home Manager

Home Manager 描述用户默认看到的程序，而 NixOS 的配置是所有用户的。

配置文件

配置文件：~/.config/nixpkgs/home.nix

应用配置文件：

home-manager switch

应用 Flakes 配置文件并显示变化：

#!/usr/bin/env python3
import os

user = os.getenv("USER")
home = f"/nix/var/nix/profiles/per-user/{user}/"
old = home + os.readlink(f"{home}profile")
os.system("home-manager switch --flake .")
new = home + os.readlink(f"{home}profile")
os.system(f"nix store diff-closures {old} {new}")

常用配置

常用的 Home Manager 配置：

# Allow unfree
nixpkgs.config.allowUnfree = true;
nixpkgs.config.allowUnfreePredicate = (pkg: true);

# User wide packages
home.packages = with pkgs; [
  xxx
];

生成 Nix 配置 ~/.config/nix/nix.conf：

# Enable flakes & setup TUNA mirror
nix.package = pkgs.nix;
nix.settings = {
  experimental-features = [ "nix-command" "flakes" ];
  substituters = [ "https://mirrors.tuna.tsinghua.edu.cn/nix-channels/store" "https://cache.nixos.org/"];
};

Shell 环境变量和 PATH：

home.sessionVariables = {
  A = "B";
};
home.sessionPath = [
  "$HOME/.local/bin"
];

离线 Home Manager 文档（用 home-manager-help 命令打开）：

manual.html.enable = true;

覆盖依赖版本

设置 JVM 程序依赖的 JDK 版本：

# Maven with java 11
home.packages = with pkgs; [
  (maven.override { jdk = jdk11; })
];

# Many packages with the same JDK
home.packages = 
  let java = pkgs.jdk11; in
  with pkgs; [
    (maven.override { jdk = java; })
    (sbt.override { jre = java; })
  ];

具体的参数命名要看 nixpkgs 上对应的包的开头。

配置 direnv

direnv 是一个 shell 插件，它的用途是进入目录的时候，会根据 .envrc 来执行命令，比如自动进入 nix-shell 等。配置：

programs.direnv.enable = true;

然后在工程路径下，编写 .envrc：

use_nix

那么，在 shell 进入目录的时候，就会自动获得 nix-shell 的环境变量。

配置 fish

可以在 home manager 配置中编写 fish 配置，这样它会自动生成 ~/.config/fish/config.fish 文件：

programs.fish.enable = true;
programs.fish.shellAliases = {
  a = "b";
};
programs.fish.shellInit = ''
  # Rust
  set -x PATH ~/.cargo/bin $PATH
'';

配置 git

同理，也可以在 home manager 中配置 git：

programs.git.enable = true;
programs.git.lfs.enable = true;
programs.git.userName = "Someone";
programs.git.userEmail = "mail@example.com";
programs.git.extraConfig = {
  core = {
    quotepath = false;
  };
  pull = {
    rebase = false;
  };
};
programs.git.ignores = [
  ".DS_Store"
];

生成的 git 配置在 ~/.config/git/config 和 ~/.config/git/ignore。

Flakes

Flakes 可以用来把多个系统的 nix 配置写在一个项目中。例如：

{
  description = "Nix configuration";

  inputs = {
    home-manager.url = "github:nix-community/home-manager/release-22.05";
    nixpkgs.url = "github:nixos/nixpkgs/nixos-22.05";
  };

  outputs = { self, nixpkgs, home-manager }:
    {
      nixosConfigurations.xxxx = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./nixos/xxxx/configuration.nix
          home-manager.nixosModules.home-manager
          ./nixos/xxxx/home.nix
        ];
      };
      homeConfigurations.yyyy = home-manager.lib.homeManagerConfiguration {
        configuration = import ./home-manager/yyyy/home.nix;
        system = "aarch64-darwin";
        homeDirectory = "/Users/yyyy";
        username = "yyyy";
        stateVersion = "22.05";
      };
    };
}

然后，要应用上面的配置，运行：

# NixOS
nixos-rebuild switch --flake .
# Home manager
home-manager switch --flake .

这样就可以把若干个系统上的 nix 配置管理在一个仓库中了。

实用工具

nixpkgs-fmt

nixpkgs-fmt 用来格式化 Nix 代码。

search.nixos.org

search.nixos.org 可以搜索 nixpkgs 上的各种包，也可以看到不同平台支持情况。缺点是看不出是否 unfree 和 broken，并且一些 darwin os-specific 的包不会显示。

nix-tree

显示各个 nix derivation 的硬盘占用和依赖关系。

打包

可以很容易地编写 default.nix 来给自己的项目打包。

CMake

对于一个简单的 cmake 程序，可以按照如下的格式编写 default.nix：

with import <nixpkgs> {};

stdenv.mkDerivation {
  name = "xyz";
  version = "1.0";

  src = ./.;

  nativeBuildInputs = [
    cmake
  ];

  buildInputs = [
    xxx
    yyy
  ];
}

可以用 nix-build 命令来构建，生成结果会在当前目录下创建一个 result 的软链接，里面就是安装目录。

由于 nix-build 的时候也会创建 build 目录，为了防止冲突，建议开发的时候用其他的名字。

Qt

对于 Qt 项目来说，由于有不同的 Qt 大版本，所以实现的时候稍微复杂一些，要拆成两个文件，首先是 default.nix：

with import <nixpkgs> {};

libsForQt5.callPackage ./xxx.nix { }

这里就表示用 qt5 来编译，那么编写 xxx.nix 的时候，传入的 qtbase 等库就是 qt5 的版本：

{ stdenv, qtbase, wrapQtAppsHook, cmake }:

stdenv.mkDerivation {
  name = "xxx";
  version = "1.0";

  src = ./.;

  nativeBuildInputs = [
    cmake
    wrapQtAppsHook # must-have for qt apps
  ];

  buildInputs = [
    qtbase
  ];
}

实际测试中发现，运行的程序可能会报告 Could not initialize GLX 的错误，这个方法可以通过 wrapProgram 添加环境变量解决：

  # https://github.com/NixOS/nixpkgs/issues/66755#issuecomment-657305962
  # Fix "Could not initialize GLX" error
  postInstall = ''
    wrapProgram "$out/bin/xxx" --set QT_XCB_GL_INTEGRATION none
  '';

开发环境

除了打包以外，通常还会在 shell.nix 中定义开发环境需要的包：

{ pkgs ? import <nixpkgs> {}
}:

pkgs.mkShell {
  buildInputs = with pkgs; [
    cmake
  ];
}

然后可以用 nix-shell 来进入开发环境。如果不希望外面的环境变量传递进去，可以用 nix-shell --pure。

搜索

按名字搜索一个包：

nix search nixpkgs xxx
nix-env -qaP yyy

Nixpkgs

可以从 TUNA 镜像上先 clone 一份到本地，然后再添加 github 上游作为 remote。

从本地 nixpkgs 安装：

nix-env -f $PWD -iA xxx

从本地 nixpkgs 编译：

nix-build $PWD -A xxx

从本地 nixpkgs 开一个 shell：

nix-shell -I nixpkgs=$PWD -p xxx

Nixpkgs 的分支

Nixpkgs 开发分支主要有三个：

1. master
2. staging-next
3. staging

发 PR 的时候，如果需要重新编译的包比较多，就要往 staging 提交；比较少，就往 staging-next 提交。

CI 会自动把 master 合并到 staging-next，也会把 staging-next 合并到 staging。这样 master 上的改动也会同步到 staging 上。

维护者会定义把 staging 手动合并到 staging-next，然后手动合并 staging-next 到 staging。这个的周期一般是一周多，可以在 pr 里搜索 staging-next。

Hydra 会编译 master 分支和 staging-next 分支上的包，不会编译 staging 分支上的包。同理，binary cache 上前两个分支上有的，而 staging 上没有的。

参考：https://nixos.org/manual/nixpkgs/stable/#submitting-changes-commit-policy

提交贡献

注意事项：

1. 升级一些比较老的写法，例如 mkDerivation -> stdenv.mkDerivation，Qt 的 hook
2. 引入 patch 的时候，建议先向上游提 PR，如果合并了，就直接用上游的 commit；如果没有合并，退而求其次可以用 pr 的 patch；如果没有提 PR 的渠道，或者上游的 commit 无法应用到当前的版本，或者这个 patch 没有普适性，再写本地的 patch；注释里要写打 patch 的原因和相关的 issue 链接，什么时候不再需要这个 patch，并且起个名字
3. 不知道 SHA256 的时候，可以注释掉或者随便写一个，这样 nix build 的时候会重新下载，然后把正确的显示出来
4. 对于有命令的包，可以添加 testVersion 测试
5. 长时间没有 review 的 pr，可以在 discourse 上回复帖子。
6. 更新之前，可以搜索一下，有没有相关的 issue 或者 pr；如果有 issue，新建 pr 的时候要提一下

一些常见的问题：

1. 编译器打开 -fno-common 后，可能会导致一些链接问题
2. Darwin 上的 clang 没有打开 LTO，也没有打开 Universal 支持
3. AArch64 Darwin 上的 gfortran 的 stack protector 不工作，需要把 hardening 关掉
4. 当编译报错是 -Werror 导致的时候，按照 warning 类型在 NIX_CFLAGS_COMPILE 中添加 -Wno-error=warning-type
5. configure 版本较老，需要引入 autoreconfHook

阅读文档：https://github.com/NixOS/nixpkgs/blob/master/doc/contributing/quick-start.chapter.md 和 https://github.com/NixOS/nixpkgs/blob/master/doc/contributing/coding-conventions.chapter.md

VSCode

可以安装 https://github.com/nix-community/vscode-nix-ide/ 插件，配合 rnix-lsp 来使用。

杂项

可以用 nix copy 命令在不同机器的 store 之间复制文件，见 nix copy - copy paths between Nix stores。

在 libvirt 中运行 RISC-V 虚拟机

背景

我在 libvirt 中跑了几个 KVM 加速的虚拟机，然后突发奇想，既然 libvirt 背后是 qemu，然后 qemu 是支持跨指令集的，那是否可以让 libvirt 来运行 RISC-V 架构的虚拟机？经过一番搜索，发现可以跑 ARM：How To: Running Fedora-ARM under QEMU，既然如此，我们也可以试试用 libvirt 来运行 RV64 虚拟机。

准备 rootfs

第一步是根据 Debian 的文档 Creating a riscv64 chroot 来创建 rootfs，然后再用 virt-make-fs 来打包。

首先是用 mmdebstrap 来生成一个 chroot：

$ sudo mkdir -p /tmp/riscv64-chroot
$ sudo apt install mmdebstrap qemu-user-static binfmt-support debian-ports-archive-keyring
$ sudo mmdebstrap --architectures=riscv64 --include="debian-ports-archive-keyring" sid /tmp/riscv64-chroot "deb http://deb.debian.org/debian-ports sid main" "deb http://deb.debian.org/debian-ports unreleased main"

进入 chroot 以后，进行一些配置：

$ sudo chroot /tmp/riscv64-chroot
$ apt update
$ apt install linux-image-riscv64 u-boot-menu vim
# set root password
$ passwd

然后修改 /etc/default/u-boot 文件，添加如下的配置：

# change ro to rw, set root device
U_BOOT_PARAMETERS="rw noquiet root=/dev/vda1"
# fdt is provided by qemu
U_BOOT_FDT_DIR="noexist"

然后运行 u-boot-update 生成配置文件 /boot/extlinux/extlinux.conf。

到这里，rootfs 已经准备完毕。

尝试在 QEMU 中启动

接下来，可以参考 Setting up a riscv64 virtual machine 先启动一个 qemu 来测试一下是否可以正常工作：

首先制作一个 qcow2 格式的镜像：

$ sudo virt-make-fs --partition=gpt --type=ext4 --size=+10G --format=qcow2 /tmp/riscv64-chroot rootfs.qcow2
$ qemu-img info rootfs.qcow2
image: rootfs.qcow2
file format: qcow2
virtual size: 11.4 GiB (12231971328 bytes)
disk size: 1.33 GiB
cluster_size: 65536
Format specific information:
    compat: 1.1
    compression type: zlib
    lazy refcounts: false
    refcount bits: 16
    corrupt: false
    extended l2: false

然后启动 qemu，配置好 OpenSBI 和 U-Boot 的路径：

$ sudo apt install qemu-system-misc opensbi u-boot-qemu
$ sudo qemu-system-riscv64 -nographic -machine virt -m 8G \
    -bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_jump.elf \
    -kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
    -object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-device,rng=rng0 \
    -append "console=ttyS0 rw root=/dev/vda1" \
    -device virtio-blk-device,drive=hd0 -drive file=rootfs.qcow2,format=qcow2,id=hd0 \
    -device virtio-net-device,netdev=usernet -netdev user,id=usernet,hostfwd=tcp::22222-:22

如果系统可以正常工作，看到下面的输出，下一步就可以配置 libvirt 了。

[    6.285024] Run /init as init process
Loading, please wait...
Starting version 251.1-1
[    7.743714] virtio_ring: module verification failed: signature and/or required key missing - tainting kernel
[    8.071762] virtio_blk virtio1: [vda] 23838189 512-byte logical blocks (12.2 GB/11.4 GiB)
[    8.181210]  vda: vda1
Begin: Loading essential drivers ... done.
Begin: Running /scripts/init-premount ... done.
Begin: Mounting root file system ... Begin: Running /scripts/local-top ... done.
Begin: Running /scripts/local-premount ... done.
Warning: fsck not present, so skipping root file system
[    9.003143] EXT4-fs (vda1): mounted filesystem with ordered data mode. Quota mode: none.
done.
Begin: Running /scripts/local-bottom ... done.
Begin: Running /scripts/init-bottom ... done.
[    9.754151] Not activating Mandatory Access Control as /sbin/tomoyo-init does not exist.
[    9.808860] random: fast init done
[   10.651361] systemd[1]: Inserted module 'autofs4'
[   10.735574] systemd[1]: systemd 251.1-1 running in system mode (+PAM +AUDIT +SELINUX +APPARMOR +IMA +SMACK +SECCOMP +GCRYPT -GNUTLS +OPENSSL +ACL +BLKID +CURL +ELFUTILS +FIDO2 +IDN2 -IDN +IPTC +KMOD +LIBCRYPTSETUP +LIBFDISK +PCRE2 -PWQUALITY -P11KIT -QRENCODE +TPM2 +BZIP2 +LZ4 +XZ +ZLIB +ZSTD -BPF_FRAMEWORK -XKBCOMMON +UTMP +SYSVINIT default-hierarchy=unified)
[   10.736902] systemd[1]: Detected architecture riscv64.

Welcome to Debian GNU/Linux bookworm/sid!

配置 libvirt

首先，打开 virt-manager，在向导中，可以在下拉菜单选择自定义的架构，选择 riscv64 和 virt，然后选择 Import existing disk image，找到刚刚创建的 qcow2 文件。

创建好以后，我们还不能直接启动，因为此时还没有配置 OpenSBI 和 U-Boot。由于 virt-aa-helper 会检查 OpenSBI 和 U-Boot 的路径，要求它们不能在 /usr/lib 路径下：

/*
 * Don't allow access to special files or restricted paths such as /bin, /sbin,
 * /usr/bin, /usr/sbin and /etc. This is in an effort to prevent read/write
 * access to system files which could be used to elevate privileges. This is a
 * safety measure in case libvirtd is under a restrictive profile and is
 * subverted and trying to escape confinement.
 *
 * Note that we cannot exclude block devices because they are valid devices.
 * The TEMPLATE file can be adjusted to explicitly disallow these if needed.
 *
 * RETURN: -1 on error, 0 if ok, 1 if blocked
 */
    const char * const restricted[] = {
        "/bin/",
        "/etc/",
        "/lib",
        "/lost+found/",
        "/proc/",
        "/sbin/",
        "/selinux/",
        "/sys/",
        "/usr/bin/",
        "/usr/lib",
        "/usr/sbin/",
        "/usr/share/",
        "/usr/local/bin/",
        "/usr/local/etc/",
        "/usr/local/lib",
        "/usr/local/sbin/"
    };

所以，我手动把 U-Boot 和 OpenSBI 复制一份到 /var/lib 下：

$ sudo mkdir -p /var/lib/custom
$ cd /var/lib/custom
$ sudo cp -r /usr/lib/u-boot/qemu-riscv64_smode .
$ sudo cp -r /usr/lib/riscv64-linux-gnu .