From d43afb9c29a02371a2de4191dc3442fbd4422d1f Mon Sep 17 00:00:00 2001
From: Dave Tucker <dave@dtucker.co.uk>
Date: Thu, 10 Aug 2023 15:13:03 +0100
Subject: [PATCH] integration-test, xtask: Move xtask run docs into README

This moves the docs for downloading kernels into the integration-test
README since it allows us to be more verbose.

Instructions have been added for the use of Fedora kernels.

The instructions for Debian kernels were amended to not download all the
kernels, and to encourage targetted download of the one you care about.

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
---
 test/README.md   | 57 +++++++++++++++++++++++++++++++++++++++++++-----
 xtask/src/run.rs | 11 ----------
 2 files changed, 51 insertions(+), 17 deletions(-)

diff --git a/test/README.md b/test/README.md
index 82e41da0..83e7ade2 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,7 +1,6 @@
-Aya Integration Tests
-=====================
+# Aya Integration Tests
 
-The aya integration test suite is a set of tests to ensure that
+The Aya integration test suite is a set of tests to ensure that
 common usage behaviours work on real Linux distros
 
 ## Prerequisites
@@ -19,21 +18,67 @@ From the root of this repository:
 
 ### Native
 
-```
+```console
 cargo xtask integration-test local
 ```
 
 ### Virtualized
 
+VM tests require a kernel image to test with.
+
+#### Obtaining a kernel image
+
+##### Debian
+
+To download an image from the Debian project:
+
+- Browse to the [Debian FTP site](ftp://ftp.us.debian.org/debian/pool/main/l/linux/) for the kernel version you require
+- Download the kernel into `tests/.tmp/debian-kernels/${architecture}/`
+
+```bash
+wget -nd -q -P test/.tmp/debian-kernels/x86_64 \
+  ftp://ftp.us.debian.org/debian/pool/main/l/linux/linux-image-5.10.0-23-cloud-amd64-unsigned_5.10.179-3_amd64.deb
+```
+
+- Extract the kernel image:
+
+```bash
+dpkg --fsys-tarfile test/.tmp/debian-kernels/arm64/linux-image-5.10.0-23-cloud-amd64-unsigned_5.10.179-3_amd64.deb | tar -C test/.tmp --wildcards --extract '*vmlinuz*' --file -
+```
+
+#### Fedora
+
+To download an image from the Fedora project:
+
+- Search for the kernel version you require on [Koji](https://koji.fedoraproject.org/koji/search?match=glob&type=build&terms=kernel-4*)
+- Copy the download link for the `kernel-core-${version}.rpm` and download it into `tests/.tmp/fedora-kernels/${architecture}/`
+
+```bash
+wget -nd -P test/.tmp/fedora-kernels/x86_64 \
+  https://kojipkgs.fedoraproject.org//packages/kernel/5.10.23/200.fc33/x86_64/kernel-core-5.10.23-200.fc33.x86_64.rpm
+```
+
+- Extract the kernel image:
+
+```bash
+rpm2cpio ./test/.tmp/fedora-kernels/x86_64/kernel-core-5.10.23-200.fc33.x86_64.rpm \
+  | cpio -iv --to-stdout ./lib/modules/5.10.23-200.fc33.x86_64/vmlinuz > ./test/.tmp/boot/vmlinuz-5.10.23-200.fc33.x86_64
 ```
-cargo xtask integration-test vm
+
+#### Running the tests
+
+To run the tests run the following command, replacing `/path/to/vmlinuz` with
+the path to the kernel image you extracted above:
+
+```console
+cargo xtask integration-test vm /path/to/vmlinuz
 ```
 
 ### Writing an integration test
 
 Tests should follow these guidelines:
 
-- Rust eBPF code should live in `integration-ebpf/${NAME}.rs` and included in
+- Rust eBPF code should live in `integration-ebpf/${NAME}.rs` and be included in
   `integration-ebpf/Cargo.toml` and `integration-test/src/lib.rs` using
   `include_bytes_aligned!`.
 - C eBPF code should live in `integration-test/bpf/${NAME}.bpf.c`. It should be
diff --git a/xtask/src/run.rs b/xtask/src/run.rs
index 63d33dad..4ed3ab30 100644
--- a/xtask/src/run.rs
+++ b/xtask/src/run.rs
@@ -25,17 +25,6 @@ enum Environment {
     /// Runs the integration tests in a VM.
     VM {
         /// The kernel images to use.
-        ///
-        /// You can download some images with:
-        ///
-        /// wget --accept-regex '.*/linux-image-[0-9\.-]+-cloud-.*-unsigned*' \
-        ///   --recursive ftp://ftp.us.debian.org/debian/pool/main/l/linux/
-        ///
-        /// You can then extract them with:
-        ///
-        /// find . -name '*.deb' -print0 \
-        /// | xargs -0 -I {} sh -c "dpkg --fsys-tarfile {} \
-        ///   | tar --wildcards --extract '*vmlinuz*' --file -"
         #[clap(required = true)]
         kernel_image: Vec<PathBuf>,
     },