HDL containers

Ready-to-use images are provided for each tool, which contain the tool and the dependencies for it to run successfully. These are typically named <REGISTRY_PREFIX>/<TOOL_NAME>.

Multiple tools from fine-grained images are included in larger images for common use cases. These are named <REGISTRY_PREFIX>/<MAIN_USAGE>. This is the recommended approach for users who are less familiar with containers and want a quick replacement for full-featured virtual machines. Coherently, some common Unix tools (such as make or cmake) are also included in these all-in-one imags.

By default, tools with Graphical User Interface (GUI) cannot be used in containers, because there is no graphical server. However, there are multiple alternatives for making an X11 or Wayland server visible to the container. mviereck/x11docker and mviereck/runx are full-featured helper scripts for setting up the environment and running GUI applications and desktop environments in OCI containers. GNU/Linux and Windows hosts are supported, and security related options are provided (such as cookie authentication). Users of GTKWave, KLayout, nextpnr and other tools will likely want to try x11docker (and runx).

Virtual Machines used on Windows for running either Windows Subsystem for Linux (WSL) or Docker Desktop by default do not support sharing USB devices with the containers. Only those that are identified as storage or COM devices can be bind directly. See microsoft/WSL#5158. That prevents using arbitrary drivers inside the containers. As a result, most container users on Windows do install board programming tools through MSYS2 (see hdl/MINGW-packages).

Nevertheless, USB/IP protocol allows passing USB device(s) from server(s) to client(s) over the network. As explained at kernel.org/doc/readme/tools-usb-usbip-README, on GNU/Linux, USB/IP is implemented as a few kernel modules with companion userspace tools. However, the default underlying Hyper-V VM machine (based on Alpine Linux) shipped with Docker Desktop (aka docker-for-win/docker-for-mac) does not include the required kernel modules. Fortunately, privileged docker containers allow installing missing kernel modules. The shell script in usbip/ supports customising the native VM in Docker Desktop for adding USB over IP support.

Understanding how all the pieces in this project fit together might be daunting for newcomers. Fortunately, there is a map for helping maintainers and contributors traveling through the ecosystem. Subdir graph/ contains the sources of directed graphs, where the relations between workflows, dockerfiles, images and tests are shown.

(Graphviz)'s digraph format is used, hence, graphs can be rendered to multiple image formats. The SVG output is shown in Figure 2 describes which images are created in each map. See the details in the figure corresponding to the name of the subgraph: Base (Figure 3), Sim (Figure 4), Synth (Figure 5), Impl (Figure 6), Formal (Figure 7) and , ASIC (Figure 8). Multiple colours and arrow types are used for describing different dependency types. All of those are explained in the legend: Figure 9.

Each EDA tool/project is built once only for each collection in this image/container ecosystem. However, some (many) of the tools need to be included in multiple images for different purposes. Moreover, it is desirable to keep build recipes separated, in order to better understand the dependencies of each tool/project. Therefore, <REGISTRY_PREFIX>/pkg/ images are created/used (coloured BLUE in the Graphs). These are all based on scratch and are not runnable. Instead, they contain pre-built artifacts, to be then added into other images through COPY --from=.

Since <REGISTRY_PREFIX>/pkg/ images are not runnable per se, but an intermediate utility, the usage of environment variables PREFIX and DESTDIR in the dockerfiles might be misleading. All the tools in the ecosystem are expected to be installed into /usr/local, the standard location for user built tools on most GNU/Linux distributions. Hence:

Despite the usage of these variables being documented in GNU Coding Standards, DESTDIR seems not to be very used, except by packagers. As a result, contributors might need to patch the build scripts upstream. Sometimes DESTDIR is not supported at all, or it is supported but some lines in the makefiles are missing it. Do not hesitate to reach for help through the issues or the chat!

The strategical priorities are the following:

Currently, the Graphs are updated manually. That is error prone, because the information shown in them is also defined in the dockerfiles and CI workflows. Ideally, graphs would be auto-generated by parsing/analysing those. However, the complexity of the graphs is non trivial. There are many tools for automatically generating diagrams from large datasets, but not so many with features for visualizing complex hierarchical nets. The requirements we are willing to satisfy are the following:

So far, the following options were analysed:

Graphviz and Gephi are probably the most known tools for generating all kinds of diagrams. Unfortunately, none of them supports hierarchical clusters as required in this use case. The same issue applies to aafigure and graphdracula.

yEd is a very interesting product, and fits most (if not all) the technical constraints. However, it’s not open source. The editor is freeware and the SDK is paid. For programmatic generation, the SDK is required. The draw.io/mxgraph toolkit seems to be the most similar open source solution. However, using SDKs for building custom interactive diagraming tools feels overkill in this use case. We don’t need graphs to be editable through a GUI!

Similarly, Tikz and SVG generation libraries (such as svgo) can be used for having the work done, but they require writing a non-negligible plumbing which would increase the maintenance burden, instead of reducing it. This would be a last resort.

Although d3-hwschematic and netlistsvg are very different use cases, the JSON format used in elkjs might be suitable.

dagre-d3 is meant for DAGs and it supports nested clusters (experimentally, Dagre D3 Demo: Clusters). Although clusters seem not to have ports, it might be an easy update from the current solution. Since it’s a client-side JS library, it does not write an SVG file to disk by default, but achieving it should be trivial.

As a result, it seems that the most suitable solution might be using the JSON format from elkjs, either with elkjs or with dagre-d3. Yet, generating an SVG programmatically seems not to be as straightforward as using other solutions such as Graphviz’s dot. The following references illustrate advanced features for building custom views/GUIs/editors:

However, it seems that writing a JSON is cumbersome. On the one hand, some nodes need to have a size for them to be shown. On the other hand, it seems not possible to draw edges across hierarchies. Port need to be explicitly defined for that purpose. Therefore, the complexity of generating the JSON given a set of nodes, edges and clusters is non-trivial.