使用PyPI来发布FPGA Overlays

使用PyPI来发布FPGA Overlays

现存的问题

现在有很多FPGA应用同时包含了硬件设计和软件驱动，比如PL bitstreams和Python包，用户必须要同时部署这两部分内容才能顺利运行起来。软件包的发布比较容易，但是硬件设计的bitstream往往比较大（>10M在GitHub上属于大文件），发布比较困难，这就导致了FPGA应用的整体部署往往需要先配置硬件环境然后再装软件，显得有些繁琐。

本文贡献

本文将介绍如何用PyPI来打包硬件bitstreams和软件程序，然后一并推送给用户。我们使用的范例是PYNQ，用户可以简单地在不同硬件平台上用pip install pynq来完成整体环境的部署，包含了FPGA overlays、Python软件驱动以及Jupyter notebook。

方案，以PYNQ-HelloWorld为例

Repository结构

• boards
  包含所有硬件projects。用户可以在里面找到自己对应的硬件平台，然后build
• pynq_helloworld
  这是主要的python package，里面还包含了jupyter notebook
• MANIFEST.in
  里面就是需要包含在分发包中的文件,也就是需要把要查找的分发的包的路径写上
• pyproject.toml
  这里指定了该项目build的最小系统需求
• setup.py
  主要写需要安装的包的一些配置信息，比如包的版本号、作者、需要处理的包目录等等

如何做到打包对应的overlay

答案是不打包，而是在用户安装的时候再通过项目里的notebook（例子中是PYNQ-HelloWorld/pynq_helloworld/notebooks/*/）中对应的*.link文件来下载，这是PYNQ Utils Module提供的一个工具（build_py，在setup.py中的cmd_class字段指定）自动完成的。当用户安装时会自动读取当前平台并找到对应的*.link来下载。

如何提取合适的notebook

很简单的一个小技巧，在setup.py中定义一个entry_points，该entry_points实际上就是在安装时检测一下当前的硬件平台（是edge还是pcie），然后当用户使用pynq get-notebooks pynq-helloworld -p .命令来提取对应notebook时就会拿取对应平台的文件（命令中的pynq-helloworld实际上已经被替换成了pynq_helloworld.notebook.edge/pcie即项目中的notebook路径）。

打包上传流程

1. python3 setup.py sdist会将项目打包成*.tar.gz并放在dist目录下，开发者可以用python3 -m pip install dist/*.tar.gz命令来尝试安装一下
2. 打包安装没问题后只需要上传到PyPI就行了，具体可以参考官方流程，实际上关键步骤只要两步：python3 -m pip install --upgrade twine(更新) & python3 -m twine upload dist/*（上传）。
3. 上传成功后应该能看到和PyPI上的页面

安装

1. 现在可以愉快地安装了，只需要一条命令python3 -m pip install pynq-helloworld
2. 如果需要用jupyter notebook，进入系统的jupyter notebook home目录并运行pynq get-notebooks pynq-helloworld -p .