1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
| # Bumping the kernel pin
Foundry OS never builds "whatever the kernel repo has checked out". It
builds **one exact commit**, `KERNEL_REV` in `config.mk`. Moving to a newer
Rustbelt is a deliberate step with its own commit, so that if something
breaks you know exactly which kernel change did it (`git bisect` works
across our history too).
The kernel repo is only ever *read*: `git archive` copies the pinned
commit out of its git store into `out/kernel-src`, and the build happens
there, with its own target dir (`out/kernel-target`).
## The steps
1. **See what changed in the kernel** (read-only commands):
```sh
cd /workspace/rust-kernel
git log --oneline OLD..NEW
git diff --stat OLD..NEW
git diff OLD..NEW -- build.rs scripts/run-headless.sh disk/ user/
```
The files that matter to us:
| Kernel file | What to update here |
|---|---|
| `Cargo.toml` (`version`), `src/` banner | `KERNEL_VERSION`, `KERNEL_BANNER` in `config.mk` |
| `build.rs`: `PROGRAMS`, `C_PROGRAMS`, `MUSL_PROGRAMS` | `FIXTURE_RUST`, `FIXTURE_C`, `FIXTURE_MUSL`, `BIN_ORDER` in `config.mk` |
| `build.rs`: the compile commands | `scripts/build-fixtures.sh` (use the *same* flags) |
| `scripts/run-headless.sh`: the `expect` list | `scripts/run-headless.sh` here (version strings come from `config.mk`) |
| `disk/` (readme, notes, `scripts/selftest.sh`) | `rootfs/` (our copy; keep Foundry's own section at the end) |
| `scripts/http-reply.sh`, `scripts/hvc0-session.txt` | our copies in `scripts/` |
| `user/link.ld` | `rust/link.ld` (where our Rust programs are linked) |
2. **Edit `config.mk`**: `KERNEL_REV`, `KERNEL_VERSION`, `KERNEL_BANNER`,
and the fixture lists if the kernel added or renamed test programs.
The banner is the kernel's first line without the trailing ` x86_64`;
`ver` in the shell prints it too.
3. **Run all three checks**:
```sh
make test # our image on the new kernel
make test-reference # the kernel's own disk.img, same checks: the baseline
make compare # our image vs the kernel's disk.img, file by file
```
If `make test` fails but `make test-reference` passes, the problem is on
our side. If both fail the same way, it is the kernel (or a flaky test:
run it again before you blame anyone; see "Known flaky checks" below).
4. **Update the docs** that name the version (`grep -rn 0.19 README.md docs/`),
then commit everything as **one** commit: `Bump kernel pin to Rustbelt X.Y.Z`.
## Where the version-dependent bits live
- `config.mk`: `KERNEL_REV`, `KERNEL_VERSION`, `KERNEL_BANNER`, the fixture lists.
- `scripts/run-headless.sh` gets `KERNEL_BANNER`, `KERNEL_VERSION` and
`BIN_COUNT` (the `dir bin | wc -l` result) from the Makefile, so the
expected lines don't need hand edits for a plain version bump.
## History of bumps
| 2026-10-31 | `a55b41d` 0.19.0 | `5291332` 0.20.0 | User space now starts at 0x40_0000, so plain `gcc -static` / `musl-gcc -static` ET_EXEC programs run: the fixture build lost its `-Ttext-segment`/crt1/`_DYNAMIC` tricks. New fixtures `exechello`, `execthreads` (piethreads.c as ET_EXEC), `timerfdtest`: /bin has 47 programs. timerfd (283/286/287) works. |
## Known flaky checks
- `[fputest] 40 async signals with clobbering handlers` (kernel fixture):
seen once at 0.20.0 as "39 async signals". Ordinary signals are not
queued, so two arriving before the first is delivered count as one. It
is the kernel's test, not ours; re-run and report it to the kernel side
if it repeats.
|