From c2a33803d521672a30191ac0b452a32d23ed0108 Mon Sep 17 00:00:00 2001
From: Nick Spinale <nick@nickspinale.com>
Date: Wed, 1 Nov 2023 10:10:36 +0000
Subject: [PATCH] docs: Add note about versions of seL4 and Microkit

Signed-off-by: Nick Spinale <nick@nickspinale.com>
---
 README.md                     | 23 +++++++++++++++++++++--
 hacking/nix/scope/sources.nix |  2 ++
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index dff27528d..e6cb371fe 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,8 @@
 
 # Rust support for seL4 userspace
 
-This repository contains crates for supporting the use of Rust in seL4 userspace. So far, this
-includes:
+This repository contains crates for supporting the use of Rust in
+[seL4](https://github.com/seL4/seL4) userspace. So far, this includes:
 
 - Rust bindings for the seL4 API ([source](./crates/sel4))
 - A runtime for root tasks ([source](./crates/sel4-root-task))
@@ -28,6 +28,25 @@ This work is funded by the [seL4 Foundation](https://sel4.systems/Foundation/hom
 
 [https://sel4.github.io/rust-sel4/](https://sel4.github.io/rust-sel4/)
 
+### Compatible versions of related seL4 Foundation projects
+
+This project builds upon [seL4](https://github.com/seL4/seL4) and the [seL4 Microkit](https://github.com/seL4/microkit).
+In particular, this project works with the following versions of those related projects:
+
+- seL4, when used without Microkit: `1c7a0cb549021bc0781b49aa69359ee8d035981c`
+  ([github.com/coliasgroup/seL4:rust](https://github.com/coliasgroup/seL4/tree/rust), an ancestor of
+  [github.com/seL4/seL4:master](https://github.com/seL4/seL4/tree/master)).
+- seL4, when used with Microkit: `7b8c552b36fe13b8a846b06a659c23697b7df926`
+  ([github.com/coliasgroup/seL4:rust-microkit](https://github.com/coliasgroup/seL4/tree/rust-microkit),
+  not an ancestor of [github.com/seL4/seL4:master](https://github.com/seL4/seL4/tree/master)). For
+  now, Microkit (both upstream trunk and the branch used by this project) requires [a
+  patch](https://github.com/coliasgroup/seL4/commit/7b8c552b36fe13b8a846b06a659c23697b7df926) on top
+  of upstream seL4 trunk.
+- seL4 Microkit: `004e340a38d1ed7bf9d1a0223aff8475bba6e6e8`
+  ([github.com/coliasgroup/microkit:rust](https://github.com/coliasgroup/microkit/tree/rust), not an
+  ancestor of [github.com/seL4/microkit:main](https://github.com/seL4/microkit/tree/main)). For now,
+  this project requires a few patches to upstream Microkit trunk which have not yet be upstreamed.
+
 ### Demos
 
 - Simple root task: https://github.com/seL4/rust-root-task-demo
diff --git a/hacking/nix/scope/sources.nix b/hacking/nix/scope/sources.nix
index b839b69d0..200be5c72 100644
--- a/hacking/nix/scope/sources.nix
+++ b/hacking/nix/scope/sources.nix
@@ -43,6 +43,8 @@ in rec {
   inherit srcRoot localRoot;
   inherit fetchGit mkKeepRef;
 
+  # NOTE: Be sure to keep the commit hashes in the top-level README up-to-date.
+
   seL4 = {
     rust = fetchGit {
       url = "https://github.com/coliasgroup/seL4.git";