Document process of updating test images & update test images

[n0toose]

The game plan with this PR is split into two parts:

• Define a simple process for updating (and documenting) the unikernel images under data/ (with a focus on reproducibility given our scientific context).
• Update the unikernels using that said procedure.

Fixes #886

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.38%. Comparing base (c48c74f) to head (c07c00a).
⚠️ Report is 87 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1168   +/-   ##
=======================================
  Coverage   76.38%   76.38%           
=======================================
  Files          29       29           
  Lines        3616     3616           
=======================================
  Hits         2762     2762           
  Misses        854      854           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[n0toose]

Maybe the "mention the toolchain" might be a bit redundant, because in theory, you can just obtain that using strings...

However, two different toolchain versions might show up, and that also doesn't necessarily fix the problem of that being too hard:

[jounathaen]

👍

[jounathaen]

Maybe the "mention the toolchain" might be a bit redundant, because in theory, you can just obtain that using strings...

However, two different toolchain versions might show up, and that also doesn't necessarily fix the problem of that being too hard:

Doesn't sound like a reliable thing to me and the "cost" of inserting the Note into the elf are basically zero.

[jounathaen]

Adding this as a comment to track the addition of the steps

[jounathaen]

I think adding the permalink here is a little overkill. Mentioning the toolchain in the commit of the update is more than sufficient.

[n0toose]

I will be moving on with this a bit iteratively due to current time constraints. I'll keep a few notes for the document.

Note to self:

---

Step 1: Adjust existing benchmarks and test cases as seen here: #1307 (TODO: include the paths)

[n0toose]

Step 2: Adjust uhyve-interface and push to a remote tree, modify local kernel tree's Cargo.toml to use updated uhyve-interface version, adjust the kernel and implement all the necessary changes (to uhyve-interface and Uhyve itself). Some further modifications might be required to:

• Hypercall-handling functions called by r#continue/creating a new function
• Serial port
• src/stats.rs (so that we can maintain statistics of how many hypercalls were called for a given run)
• Pay attention to memory range-related changes and ASLR.

It is standard practice to maintain backwards compatibility with older versions, primarily by "translating" 'old structs' into 'new structs'. Such an example can be found here:

uhyve/src/hypercall.rs

Lines 425 to 448 in c5d5737

	/// Handles a v1 read hypercall (for which a guest-provided guest virtual address must be
	/// converted to a guest physical address by the host).
	fn read_v1(
	mem: &MmapMemory,
	sysread: &mut v1::parameters::ReadParams,
	root_pt: GuestPhysAddr,
	file_map: &mut UhyveFileMap,
	) {
	sysread.ret = if let Ok(guest_phys_addr) = virt_to_phys(sysread.buf, mem, root_pt) {
	let mut tmp = v2::parameters::ReadParams {
	fd: sysread.fd,
	buf: guest_phys_addr,
	len: sysread.len as u64,
	ret: 0i64,
	};
	read(mem, &mut tmp, file_map);
	tmp.ret
	.try_into()
	.unwrap_or_else(|ret| panic!("Unable to fit return value {} in read_v1.", ret))
	} else {
	warn!("Unable to convert guest virtual address into guest physical address");
	-EFAULT as isize
	}
	}

If the integration tests pass, assuming that a kernel version that does not contain your uhyve-interface-related modifications is used, you're most likely good to go. Normally, Uhyve's CI pipelines should be a sufficient indicator that everything's working as it's supposed to.

Step 3: cd test/test-kernels, HERMIT_MANIFEST_DIR=/path/to/modified/kernel cargo build -Zbuild-std=std,panic_abort --target=x86_64-unknown-hermit (if this fails, e.g. due to a backwards incompatible change, modify test/test-kernels/Cargo.toml to use a local tree of hermit-rs). Draft pull requests can use the draft uhyve-interface changes by overriding dependencies (e.g. [patch.crates-io]), see: https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html

Step 4: Go back to Step 2 until all of Uhyve's test cases pass.

Step 5: Build new test cases that accommodate potentially new hypercalls, confirm that they work.

Step 6: Merge uhyve-interface changes to Uhyve tree, publish a new version of the crate on crates.io.

Step 7: If you have submitted any draft pull requests to the kernel tree, remove the overrides from Cargo.toml and update Cargo.lock. Your kernel PR should be nearly ready.

Step 8: Confirm, again, that Uhyve's tests pass locally; such tests are not run when submitting PRs to the kernel. For good measure, confirm that this is the case on other targets as well. Share results on the pull request to the kernel.

Step 9: Your kernel pull request should be ready to merge (as long as all tests pass). If feasible, wait for a new release after it is merged.

Step 10: Adjust test-kernels to use a version of Hermit that bundles a kernel with the newly merged uhyve-interface modifications.

Step 11: <concrete build instructions for new Hermit unikernel images for data/>

See: https://github.com/hermit-os/hermit-rs/blob/0e68850e7b848656f8704b6c1fdc3a09685cb4de/hermit/build.rs#L43-L57