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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
/*
* Copyright (c) Meta Platforms, Inc. and affiliates.
* All rights reserved.
*
* This source code is licensed under the BSD-style license found in the
* LICENSE file in the root directory of this source tree.
*/
//! The machine a guest runs on, as Hermit describes it: one description that
//! every guest-visible source of machine facts reads, so that they tell the
//! same story on every backend and every host
//! (<https://github.com/rrnewton/hermit/issues/4266>).
//!
//! Today `uname`, `sysinfo` and the fixed procfs files (`procfs::fixed`)
//! read it. The virtual CPU (CPUID, `/proc/cpuinfo`, the CPU files under
//! `/sys`, `sched_getaffinity`) still has its own sources, which this
//! description is to absorb; the design lists every source that must agree.
//!
//! The values are fixed. They may come only from Hermit's configuration
//! (today: the epoch and the memory size), never from the host.
use chrono::DateTime;
use chrono::Utc;
/// The machine a guest sees.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct MachineDescription {
/// The running kernel.
pub kernel: Kernel,
/// The kernel's fixed limits and settings.
pub limits: KernelLimits,
/// The number of CPUs: 1. Detcore runs a guest's threads one at a time,
/// as on one CPU, and `/proc/stat`, the CPU files under `/sys` and
/// `sched_getaffinity` already report one; the tables that have a column
/// or block per CPU (`/proc/interrupts`, `/proc/softirqs`,
/// `/proc/schedstat`, `/proc/zoneinfo`) render this many.
pub cpus: u32,
/// The memory size in bytes, which `/proc/meminfo` (in kB, rounded
/// down) and `sysinfo` report: the configured `--memory` (1 GB by
/// default). Linux counts memory in whole pages, so its two reports
/// agree exactly; here they differ by the size modulo 1024 (512 bytes
/// for the default), as they did before this description.
pub memory: u64,
}
/// `--memory`'s default, 1 GB (`bytesize` reads "1GB" as 10^9 bytes).
const DEFAULT_MEMORY: u64 = 1_000_000_000;
impl Default for MachineDescription {
fn default() -> Self {
Self {
kernel: Kernel::default(),
limits: KernelLimits::default(),
cpus: 1,
memory: DEFAULT_MEMORY,
}
}
}
impl MachineDescription {
/// The machine of a run whose configured epoch is `epoch`.
pub fn new(epoch: DateTime<Utc>) -> Self {
Self {
kernel: Kernel {
built: epoch,
..Kernel::default()
},
..Self::default()
}
}
/// The contents of the fixed procfs file at `path` on this machine, if
/// `path` names one (`procfs::fixed`).
pub fn procfs_file(&self, path: &str) -> Option<Vec<u8>> {
crate::procfs::FixedProcfsFile::from_path(path).map(|file| file.contents(self))
}
/// The machine of a run with configuration `config`.
pub fn of(config: &crate::config::Config) -> Self {
Self {
memory: config.memory,
..Self::new(config.epoch)
}
}
}
/// The running kernel.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Kernel {
/// `uname().sysname` and `kernel/ostype`.
pub sysname: String,
/// `uname().release` and `kernel/osrelease`: 5.2.0. It must pass glibc's
/// ABI-tag check for the libraries a guest loads; whether to advertise a
/// newer release is an open question in the design.
pub release: String,
/// When the kernel was built, which dates its version: the epoch.
pub built: DateTime<Utc>,
/// The options after the boot image on `/proc/cmdline`: `quiet`.
pub boot_options: String,
/// `kernel/random/boot_id`: one UUID for every run, version 4 in form;
/// its first bytes spell `hermit` in hex.
pub boot_id: String,
}
impl Default for Kernel {
fn default() -> Self {
Self {
sysname: "Linux".to_owned(),
release: "5.2.0".to_owned(),
built: DateTime::<Utc>::default(),
boot_options: "quiet".to_owned(),
boot_id: "6865726d-6974-4000-8000-000000000000".to_owned(),
}
}
}
impl Kernel {
/// `uname().version` and `kernel/version`: a build dated when it was
/// built. Formatted in UTC: `Local` initializes libc TLS, which is
/// unavailable while a DynamoRIO application thread is executing a
/// client callback.
pub fn version(&self) -> String {
format!("#1 SMP {}", self.built.format("%a %b %d %T %Z %Y"))
}
/// `/proc/version`: sysname, release and version, in the form
/// `Linux version <release> <version>` that gVisor also uses. Linux adds
/// the builder and compiler, which describe no kernel a guest can see.
pub fn banner(&self) -> String {
format!(
"{} version {} {}",
self.sysname,
self.release,
self.version()
)
}
/// `/proc/cmdline`: a boot image named after the release.
pub fn command_line(&self) -> String {
format!("BOOT_IMAGE=/vmlinuz-{} {}", self.release, self.boot_options)
}
}
/// The kernel's fixed limits and settings.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct KernelLimits {
/// `kernel/random/entropy_avail`: 256, which Linux 5.18 and later always
/// report.
pub entropy_avail: u32,
/// `kernel/overflowuid`: 65534, Linux's default, the ID an unmapped user
/// shows as.
pub overflow_uid: u32,
/// `kernel/overflowgid`: 65534, as `overflow_uid`, for groups.
pub overflow_gid: u32,
/// `kernel/pid_max`: 4194304 (2^22, `PID_MAX_LIMIT`), the value systemd
/// sets on 64-bit machines. Detcore's virtual PIDs stay far below it.
pub pid_max: u32,
/// `kernel/cap_last_cap`: 40, `CAP_CHECKPOINT_RESTORE`, the last
/// capability of the kernels Hermit runs on. `capget` and
/// `PR_CAPBSET_READ` reach the host kernel, so this agrees with the
/// capability sets the guest is shown.
pub cap_last_cap: u32,
/// `vm/overcommit_memory`: 0, Linux's heuristic default.
pub overcommit_memory: u32,
/// `vm/max_map_count`: 65530, Linux's default (`DEFAULT_MAX_MAP_COUNT`).
pub max_map_count: u32,
/// `vm/mmap_min_addr`: 65536, the default of the common distributions.
pub mmap_min_addr: u64,
/// `fs/file-max`: `LONG_MAX`, what Linux 5.0 and later default to.
pub file_max: u64,
/// `fs/aio-max-nr`: 65536, Linux's default. (Before, the guest read 0,
/// which says that no asynchronous I/O context can be set up.)
pub aio_max_nr: u64,
/// `fs/pipe-max-size`: the capacity Detcore pins every pipe at
/// (`DETERMINISTIC_PIPE_CAPACITY_BYTES`), which is also the most that
/// `F_SETPIPE_SZ` allows.
pub pipe_max_size: u32,
}
impl Default for KernelLimits {
fn default() -> Self {
Self {
entropy_avail: 256,
overflow_uid: 65534,
overflow_gid: 65534,
pid_max: 1 << 22,
cap_last_cap: 40,
overcommit_memory: 0,
max_map_count: 65530,
mmap_min_addr: 65536,
file_max: i64::MAX as u64,
aio_max_nr: 65536,
pipe_max_size: crate::syscalls::DETERMINISTIC_PIPE_CAPACITY_BYTES as u32,
}
}
}
#[cfg(test)]
mod tests {
use chrono::TimeZone;
use super::*;
/// The kernel's strings agree with each other as Linux's do.
#[test]
fn the_kernel_describes_itself_consistently() {
let machine = MachineDescription::new(Utc.with_ymd_and_hms(2026, 1, 1, 0, 0, 0).unwrap());
let kernel = &machine.kernel;
assert_eq!(kernel.version(), "#1 SMP Thu Jan 01 00:00:00 UTC 2026");
assert_eq!(
kernel.banner(),
format!("Linux version 5.2.0 {}", kernel.version())
);
assert_eq!(kernel.command_line(), "BOOT_IMAGE=/vmlinuz-5.2.0 quiet");
}
}