|
| 1 | +# Alpha Submission |
| 2 | + |
| 3 | +In order to ensure that the contest environment is able to support all router |
| 4 | +entries ahead of the final submission deadline, a mandatory step for continued |
| 5 | +participation in the contest is the submission of an early "alpha" release. |
| 6 | +The performance of this alpha submission will have **zero** effect on the |
| 7 | +final submission score; instead, the organizers will endeavour to work with |
| 8 | +contestants to ensure that the runtime environment is as desired. |
| 9 | +Contestants will receive private feedback from the organizers assessing the |
| 10 | +performance of just their router on the released benchmark suite (plus a hidden |
| 11 | +benchmark) when run on contest hardware. |
| 12 | + |
| 13 | +## Key Details |
| 14 | + |
| 15 | +* Alpha submission is mandatory for continued participation in the contest |
| 16 | +* Performance of alpha submissions will be shared privately with contestants and will not impact the final score |
| 17 | +* Alpha submissions will be evaluated on [AMD Heterogeneous Compute Cluster (HACC)](https://www.amd-haccs.io/) hardware |
| 18 | +* Contestants are required to use [Apptainer](https://apptainer.org/docs/user/latest/) to containerize their submission (details below) |
| 19 | + |
| 20 | +## Runtime Environment |
| 21 | + |
| 22 | +Aside from running under Linux without network access, no restrictions are |
| 23 | +placed on the languages, software dependencies, or runtime environment that |
| 24 | +contestants may use to implement their router. In order to enable this platform |
| 25 | +independence, contestants must containerize their router and runtime environment |
| 26 | +with the [Apptainer](https://apptainer.org/docs/user/latest/) framework. |
| 27 | + |
| 28 | +### Apptainer |
| 29 | + |
| 30 | +From the [Apptainer documentation](https://apptainer.org/docs/user/latest/introduction.html): |
| 31 | +> Apptainer is a container platform. It allows you to create and run containers that package up pieces of software in a way that is portable and reproducible. You can build a container using Apptainer on your laptop, and then run it on many of the largest HPC clusters in the world, local university or company clusters, a single server, in the cloud, or on a workstation down the hall. Your container is a single file, and you don’t have to worry about how to install all the software you need on each different operating system. |
| 32 | +
|
| 33 | +Apptainer containers may be described with a `*.def` |
| 34 | +[definition file](https://apptainer.org/docs/user/latest/definition_files.html) |
| 35 | +that specifies the base operating system image, and any further customisations |
| 36 | +(such as library installations) required to support an application. A |
| 37 | +definition file can then be compiled into an executable `*.sif` image which |
| 38 | +allows the application to be run in an isolated environment. |
| 39 | + |
| 40 | +The [contest repository](https://github.com/Xilinx/fpga24_routing_contest/) |
| 41 | +has been updated with example `*.def` files in the `alpha_submission` directory |
| 42 | +for both `rwroute` and `nxroute-poc`. To build and run the default container |
| 43 | +(which on a fresh clone would be `rwroute`) one would just run: |
| 44 | + |
| 45 | +``` |
| 46 | +make run-container |
| 47 | +``` |
| 48 | + |
| 49 | +This is roughly equivalent to: |
| 50 | +``` |
| 51 | +apptainer build rwroute_container.sif alpha_submission/rwroute_container.def |
| 52 | +apptainer run --pid --home `pwd` --rocm --bind /etc/OpenCL --mount src=/tools/,dst=/tools/,ro rwroute_container.sif make |
| 53 | +``` |
| 54 | + |
| 55 | +The `apptainer build` command creates an image from the `rwroute_container.def` |
| 56 | +definition, and the `apptainer run` command runs this image. The Apptainer |
| 57 | +command line options do the following: |
| 58 | + |
| 59 | +* `--pid` runs the container in a new process ID namespace to ensure processes |
| 60 | +spawned by the container are not orphaned if the container is killed. |
| 61 | +* ``--home `pwd` `` sets the container home directory to be the current directory |
| 62 | +* `--rocm --bind /etc/OpenCL` configures [GPU Access](alpha_submission.md#gpu-access) |
| 63 | +* `--mount ...` creates a read-only mount of the host system's `/tools` |
| 64 | +directory to the container's `/tools` directory, which allows the container to |
| 65 | +access the host Vivado installation. |
| 66 | + |
| 67 | +The remainder of the Apptainer command line simply runs the default make target from inside the |
| 68 | +container. |
| 69 | + |
| 70 | +Finally, in order to aid in development the Makefile target: |
| 71 | + |
| 72 | +``` |
| 73 | +make test-container |
| 74 | +``` |
| 75 | + |
| 76 | +has also been provided. This target is identical to the `run-container` target, |
| 77 | +except that results are only collected for the `boom_med_pb` benchmark, instead |
| 78 | +of collecting results for every benchmark. This allows contestants to quickly |
| 79 | +test their Apptainer flow and avoid overloading shared resources should they |
| 80 | +be working on a shared cluster. |
| 81 | + |
| 82 | +For further information about working with Apptainer containers please refer to |
| 83 | +[the user documentation](https://apptainer.org/docs/user/latest/introduction.html). |
| 84 | + |
| 85 | +### GPU Access |
| 86 | + |
| 87 | +It is possible to access AMD GPU resources on the host from an Apptainer |
| 88 | +container. The directory `alpha_submission/opencl_example` contains a sample |
| 89 | +`*.def` file that builds a [C++/OpenCL "Hello World" example](https://github.com/cqcallaw/ocl-samples). |
| 90 | +To run this example: |
| 91 | + |
| 92 | +``` |
| 93 | +make run-opencl-example |
| 94 | +``` |
| 95 | + |
| 96 | +This `make` target builds a `*.sif` image from the |
| 97 | +`opencl_example_container.def` definition file and runs it with the command: |
| 98 | + |
| 99 | +``` |
| 100 | +apptainer run --pid --home `pwd` --rocm --bind /etc/OpenCL opencl_example_container.sif |
| 101 | +``` |
| 102 | + |
| 103 | +The `--rocm` switch enables AMD ROCm support in the container. The |
| 104 | +`--bind /etc/OpenCL` switch mounts the host OpenCL directory in the container, |
| 105 | +which is required to allow the containerized OpenCL stack to discover the host |
| 106 | +resources. |
| 107 | + |
| 108 | +Please note that contestants are free to use GPU interfaces other than OpenCL, |
| 109 | +such as [AMD HIP](https://github.com/ROCm-Developer-Tools/HIP). |
| 110 | + |
| 111 | +## Submission Format |
| 112 | + |
| 113 | +Contestants are required to submit a clone of the contest |
| 114 | +repository which has been modified to run their router in Apptainer. |
| 115 | +Specifically, organizers must be able to run the submitted router by calling only |
| 116 | +the `make run-container` target. By default, in a fresh checkout of the contest |
| 117 | +repository, this target will run `rwroute` in an Apptainer container. |
| 118 | +Thus in addition to their router contestants must supply a custom `*.def` file |
| 119 | +in the `alpha_submission` directory, as well as a Makefile that has been |
| 120 | +modified to run their router by default. To set the default router in the |
| 121 | +Makefile contestants must change the value of the `ROUTER` variable from |
| 122 | +`rwroute` to the name of their router. |
| 123 | + |
| 124 | +Starting from a clone of the contest repository that has already had its |
| 125 | +Makefile `ROUTER` variable modified such that `make` invokes the contestant |
| 126 | +router, one would just execute: |
| 127 | + |
| 128 | +``` |
| 129 | +make distclean-and-package-submission |
| 130 | +``` |
| 131 | + |
| 132 | +Which generates a submission artifact named |
| 133 | +`<router_name>_submission_<timestamp>.tar.gz` in the current directory. |
| 134 | +Internally, this executes the following commands: |
| 135 | + |
| 136 | +``` |
| 137 | +make distclean |
| 138 | +tar -czf ../<router_name>_submission_<timestamp>.tar.gz.tar.gz . |
| 139 | +mv ../<router_name>_submission_<timestamp>.tar.gz.tar.gz . |
| 140 | +``` |
| 141 | + |
| 142 | +Note that `make distclean` will delete all unrouted design files, routed |
| 143 | +results and logs, as well as the device description. The organizers will then |
| 144 | +evaluate the artifact with a process similar to the following: |
| 145 | + |
| 146 | +``` |
| 147 | +mkdir <router_name>_alpha_submission |
| 148 | +cd <router_name>_alpha_submission |
| 149 | +tar -xvf <router_name>_submission_<timestamp>.tar.gz |
| 150 | +make run-container |
| 151 | +``` |
| 152 | + |
| 153 | +### Closed-Source Submissions |
| 154 | + |
| 155 | +While contestants are strongly encouraged to open-source their solutions at the |
| 156 | +conclusion of the contest, there is no requirement to do so. In such cases, |
| 157 | +it is still necessary to use the flow described above to produce a binary only |
| 158 | +submission. That is, any precompiled router must still work inside Apptainer |
| 159 | +and be invoke-able using `make run-container` on the contest hardware. |
0 commit comments