Add some more guidance on how to rebuild the plutosdr-fw

[mbna76]

Dear Daniel, thank you for your great project, I really like it, also I wonder if we can add a bit more guidance for rebuilding because it was confusing for me at times since I needed to put it together from several sources and this was my order in the preparation and the build instructions:

(1) Setup Containers and Install Vivado 2023.2
ON HOST sudo docker pull ghcr.io/maia-sdr/maia-sdr-devel:20241130
ON HOST sudo docker volume create vivado2023_2
ON HOST sudo docker cp ./Downloads/FPGAs_AdaptiveSoCs_Unified_2023.2_1013_2256_Lin64.bin maia-sdr-devel:/home/ubuntu
ON HOST docker run --rm --net host -e DISPLAY=$DISPLAY -e TERM
--name=maia-sdr-devel --hostname=maia-sdr-devel
-v vivado2023_2:/opt/Xilinx -v maia_sdr_devel_home:/home
-v $HOME:/hdl
-it ghcr.io/maia-sdr/maia-sdr-devel -> opens docker container user command line
ON HOST (extra command line) xhost +local: -> need this otherwise Vivado Installer fails to open graphics window on host
ON HOST (extra command line) sudo docker exec -u 0 -it maia-sdr-devel /bin/bash -> opens docker container root command line -> Run .FPGAs_AdaptiveSoCs_Unified_2023.2_1013_2256_Lin64.bin and select do not upgrade, select VITIS - not VIVADO -> check Vitis, Vivado, Vitis HLS and Devices for Custom Platforms (SoCs only) - this already downloads 25.27 GB

(2) ON container root command line -> apt update, apt upgrade, apt install nano

(3) Clone Repo and change to most recent version
ON HOST (in your home f.e.) git clone --recursive https://github.com/maia-sdr/plutosdr-fw.git
ON HOST (in your home f.e.) git checkout maia-sdr-v0.8.0

(3) On Container - ubuntu@maia-sdr-devel -> nano .bashrc -> append and save to the end of file
source /opt/Xilinx/Vivado/2023.2/settings64.sh
source /opt/rust/env
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin/:/usr/bin:/sbin:/bin:/opt/gcc-arm-linux-gnueabi/bin:$PATH:/opt/oss-cad-suite/bin -> manually execute once, at next reboot it will be included by default

(4) On Container - ubuntu@maia-sdr-devel -> change to /hdl/plutosdr-fw -> here you can run "make" and all will be build correctly and output to build director

[daniestevez]

Hi @mbna76, thanks for these notes. I think that it would be great to have more detailed build instructions, since it simplifies on-boarding people on the project. Where do you think that it would be a good place for these instructions? There are multiple Github repositories involved, so I don't know if one of them is the more obvious place where people would look first. Another possibility is in the Maia SDR webpage. The firmware installation instructions are already there, and this web page is intended to be the landing place for people first learning about Maia SDR. The webpage is on this Github repository, and I can take PRs in that repo.

This said, some comments:

ON HOST sudo docker pull ghcr.io/maia-sdr/maia-sdr-devel:20241130

It's better to pull ghcr.io/maia-sdr/maia-sdr-devel:latest, since in that case the instructions will stay good when the version is updated.

-v $HOME:/hdl

Here some people might prefer to only mount a subdirectory of their $HOME. This is what I do normally. An advantage is that it limits the damage caused by a mistake in the container (like deleting all the files). I realize that this comes directly from the maia-sdr-docker README, but in more detailed documentation perhaps it's good to explain the alternatives here (since some people will not be familiar with Docker).

(3) On Container - ubuntu@maia-sdr-devel -> nano .bashrc -> append and save to the end of file

An alternative that I normally use, and which will save you from installing nano (which will be wiped the next time you run the container) is to do

cat >> ~/.bashrc

then paste the lines and hit Ctrl+D.

It's also possible to go (as root) into /var/lib/docker/volumes/maia_sdr_devel_home/_data/ubuntu in the host and edit .bashrc with whatever editor you have on the host.

ON HOST docker run --rm --net host -e DISPLAY=$DISPLAY -e TERM
[...]
-it ghcr.io/maia-sdr/maia-sdr-devel

I see that now I'm also adding --ulimit "nofile=1024:1048576" to this docker run because of moby/moby#45436 (comment) (the problem this solves is that fakeroot, which is used by buildroot to generate the rootfs, is very slow without this option). But I forgot to add this to the maia-sdr-docker README (I will do this now).

Besides this approach, there is another way of building that I introduced more recently. This is to use Docker compose as indicated in the plutosdr-fw REAME. This still needs Vivado 2023.2 installed to a Docker volume, so starting from scratch the process would begin in the same way as in your instructions to install Vivado on a volume (The need to install Vivado manually is something that will always make the process more tricky, but alas the volume containing the Vivado installation cannot be legally redistributed, so the user always needs to download the installer and run it). After Vivado is installed in the volume, the compose.yml and build-docker.sh files take care of setting up the rest. Running xhost + is not needed in this approach. It can even run on a headless machine. The advantage of this approach is that it needs less set up, and it basically runs the same as Github CI. The disadvantage is that this is limited to building the plutosdr-fw repository. Your approach gives a development environment where it is possible to open the Vivado GUI to look at synthesis results, build parts of the project partially by hand, etc., so it might be more suitable for more complex development use case (I use both approaches depending on what I need).

Would you be willing to format these notes and contribute them as a PR to one of the READMEs or the webpage?

[mbna76]

Hi @daniestevez - awesome, happy to help with this, however still learning, since I am originally more a hardware and rf engineer. Yes, certainly add the guidance to your website. Are you by chance at FOSDEM? Do you have an example of how to format it?

[daniestevez]

I agree that the web site is the best place to put this information. The site is rendered with Zola, and the contents are written in Markdown. You can get an idea about how to format it by reading https://github.com/maia-sdr/maia-sdr-web/blob/main/content/installation.md?plain=1

If you want to test your changes locally, you can install Zola, clone the https://github.com/maia-sdr/maia-sdr-web repository, and run zola serve inside the repository.

I suggest you make a PR that creates an new Markdown file in https://github.com/maia-sdr/maia-sdr-web/tree/main/content with this documentation. Even if formatting is not perfect, that takes us 90% of the way and then I can make the final adjustments.

Are you by chance at FOSDEM?

I will be at FOSDEM, indeed. On Saturday I'll spend all day in the Radio devroom. On Sunday I don't have any concrete plans at the moment.