PyNVMe3使用指导书

介绍

Pynvme3是Pynvme2工具的升级版本，同样是用于进行nvme设备的测试工具，该版本比pynvme2做了升级和优化，需要收费。

准备

首先，安装Ubuntu20.04，建议在SATA SSD上安装操作系统。

用户使用sudo命令获取root权限时，通常需要输入密码，这让人感到麻烦。建议做如下设置，可不用输入密码：

1. 在Ubuntu 20.04的命令行中，执行以下命令，系统会自动打开nano编辑器。

> sudo visudo

1. 在最后一行输入

your_username  ALL=(ALL)  NOPASSWD: ALL

1. Ctrl-o进入配置文件的编辑。Ctrl-x退出编辑器。这样后续再使用sudo时就不需要输入密码了。

安装和配置

安装PyNVMe3需要通过终端的命令进行，软件本身已经自动完成了大部分流程，安装并不复杂。安装流程如下：

1. PyNVMe3会使用大量的python库，所以需要先安装pip3。

> sudo apt install -y python3-pip

1. （可省）用户可以修改pip3的源代码。创建或修改文件~/.pip/pip.conf，添加下列内容并保存。

[global]

index-url=https://pypi.tuna.tsinghua.edu.cn/simple/

[install]

trusted-host=pypi.tuna.tsinghua.edu.cn

1. 如果已经安装过PyNVMe3，请先卸载。

> sudo pip3 uninstall PyNVMe3 
> sudo rm -rf /usr/local/PyNVMe3

1. 通过pip安装PyNVMe3，安装目录为/usr/local/PyNVMe3。如果没有PyNVMe3安装包，请联系sales@pynv.me。

> sudo pip install PyNVMe3-22.11.tar.gz

1. 以root权限打开/etc/default/grub文件，并将GRUB_CMDLINE_LINUX_DEFAULT行按如下内容修改：

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash default_hugepagesz=2M hugepagesz=1G hugepages=1 amd_iommu=off"

1. 执行命令

> sudo update-grub

1. 在文件/etc/fstab末尾插入：

none /mnt/huge hugetlbfs pagesize=1G,size=1G 0 0

1. 安装和配置PyNVMe3完成。重启平台。

> sudo reboot

 

测试执行

PyNVMe3有几种不同的执行方式：

• 在VSCode上执行，主要用于调试脚本。
• 通过命令行执行。
• 在CI环境上执行，如Jenkins。

首先介绍命令行的执行方式。

1. 进入PyNVMe3目录

> cd /usr/local/PyNVMe3

1. 切换到root模式

> sudo su

1. 配置运行环境。该步骤会用PyNVMe3的用户模式驱动替换NVMe设备的kernal驱动，以便保留更大的内存用于测试。

> make setup

如果运行测试脚本需要占用大量内存，我们可以通过memsize参数预留更多的内存空间：

> make setup memsize=100000

PyNVMe3默认尽量预留10G的内存空间，以保证4T容量硬盘（LBA 512byte）的测试要求。建议测试机内存16G或以上。

1. 通过以下命令执行测试：

> make test

该命令默认执行scripts\conformance目录下所有的测试项目。Conformance测试套中的测试脚本用于测试NVMe协议，大约需要1-2小时的执行时间。

在scripts/benchmark中有更多测试脚本。执行benchmark测试脚本需要较长时间，有几小时、几天甚至几周的执行周期。在执行命令行中，可以直接指定不同的测试脚本。

> make test TESTS=scripts/benchmark/performance.py

如果测试平台上有多个NVMe设备，我们要在命令行中指定被测设备的BDF地址。

> make test pciaddr=0000:03:00.0

如果平台上只有1个NVMe盘，就不用指定该参数了，PyNVMe会自行寻到该盘的BDF地址。所以我们推荐使用SATA盘安装操作系统。

NVMe盘可以配置多个namespace，可以通过nsid参数指定测试的namespace，该参数默认为1。

> make test nsid=2

在命令行中，TEST、pciaddr、nsid参数可以组合使用。

1. 获取执行结果。测试执行开始后，终端会打印出测试log，同时log文件会在results目录下生成，以此作更进一步的调试。每次测试通常会包含下列测试结果：

• SKIPPED：测试跳过。通常由于一些条件不满足导致测试没有必要执行。
• FAILED：测试失败。Log会打印出相应的失败原因，通常是由于某个assert语句不满足。如果assert语句失败，测试会立即退出，后续的测试内容也不会再执行。
• PASSED：测试通过。
• ERROR：测试无法执行。可能是PyNVMe3无法找到被测设备。如果看到ERROR，建议先查看log中ERROR之前导致FAILED的测试用例，有可能是该用例导致被测设备故障。

无论哪种测试结果，测试过程中都有可能产生warning消息。测试log中会答应所有的warning信息。大多数warning消息与CQE中的错误码有关，也可能是触发了AER命令。Warning消息不回中断测试执行，但建议查明warning消息的原因。

Results目录下不仅保存了测试log文件，也保存了测试脚本生成的文件（excel、csv或png）。

1. 在测试正常结束后，make test命令会自动切回kernal的NVMe驱动。用户也可以通过以下命令手动切到kernal的NVMe驱动，以便执行其他基于kernal的工具（如fio、nvme-cli等）。

> make reset

命令make setup和make reset是作用相对的两个命令。但是make reset不会释放make setup已经保留的内存。一旦这些内存被释放，很有可能就无法再满足make setup所需的内存了。因此，建议在操作系统启动时，就执行make setup以预留足够的内存空间。