Skip to main content

onelf_format/
drivers.rs

1//! What the host is expected to supply, and how to find it.
2//!
3//! A bundled loader has its compiled-in search paths scrubbed, so anything
4//! the host must still provide (libcuda, libvulkan, libGL, libva) has to be
5//! found by onelf itself. The driver families name what that is, and the
6//! host's loader cache says where it lives. The launch resolver uses both.
7
8use std::path::Path;
9
10/// Directories holding a library named by the host's `/etc/ld.so.cache`,
11/// in the order the cache lists them, filtered to those that exist.
12///
13/// The bundled loader cannot consult the cache itself: `bundle-libs` blanks
14/// the `/etc/` string inside it and the runtime passes `--inhibit-cache`,
15/// both so a host library cannot shadow a bundled one. That leaves the fixed
16/// list above as the only route to a host library, and it is a guess about
17/// where a distribution puts things.
18///
19/// Where the guess fails, a host GPU driver loads and its own dependencies do
20/// not. Gentoo slots LLVM under `/usr/lib/llvm/<n>/lib64`, so Mesa's RADV
21/// driver resolves but the `libLLVM.so.<n>` behind it does not, and Vulkan
22/// goes silently missing. Reading the cache here keeps the decision about
23/// what the host may supply on onelf's side, while letting the answer come
24/// from the host's own index instead of a hardcoded list.
25pub fn cache_dirs() -> Vec<String> {
26    cache_dirs_in(&cache_file())
27}
28
29/// [`cache_dirs`] for the cache image at `cache`.
30pub fn cache_dirs_in(cache: &Path) -> Vec<String> {
31    let Ok(data) = std::fs::read(cache) else {
32        return Vec::new();
33    };
34
35    let mut dirs: Vec<String> = Vec::new();
36    for entry in cache_paths(&data) {
37        let Some((dir, _)) = entry.rsplit_once('/') else {
38            continue;
39        };
40        if !dir.is_empty() && !dirs.iter().any(|d| d == dir) {
41            dirs.push(dir.to_string());
42        }
43    }
44    // One stat per distinct directory rather than one per cache entry: a
45    // cache routinely lists a couple of thousand libraries across a handful
46    // of directories.
47    dirs.retain(|d| Path::new(d).is_dir());
48    dirs
49}
50
51/// Sonames the host is expected to provide because they have to match its
52/// GPU and compute drivers: the glvnd and Vulkan front ends, and the
53/// vendor userspace behind them. Matched as prefixes against sonames.
54///
55/// Deliberately generous. Naming something here that the host does not
56/// have costs nothing, while leaving out a driver family means the
57/// package cannot reach it at all.
58pub const DRIVER_FAMILIES: &[&str] = &[
59    "libGL.so",
60    "libGLX.so",
61    "libEGL.so",
62    "libGLdispatch.so",
63    "libOpenGL.so",
64    "libGLESv2.so",
65    "libvulkan.so",
66    "libcuda.so",
67    "libnvidia",
68    // The compute backends Blender probes alongside CUDA. Measured:
69    // withholding these costs OptiX while leaving CUDA working, so a miss
70    // here is a silent loss of capability rather than a failure anyone
71    // would notice.
72    "libnvoptix",
73    "libamdhip64",
74    "libze_loader",
75    "libva.so",
76    // The VA-API display wrappers ship with libva and track its version.
77    "libva-drm.so",
78    "libva-x11.so",
79    "libva-wayland.so",
80    "libva-glx.so",
81    "libOpenCL.so",
82    "libdrm",
83    "libgbm.so",
84];
85
86/// The loader cache image this process reads: `ONELF_LD_CACHE` when set,
87/// so a test or a debugging session can supply its own, otherwise the
88/// host's.
89pub fn cache_file() -> std::path::PathBuf {
90    std::env::var_os("ONELF_LD_CACHE")
91        .map(std::path::PathBuf::from)
92        .unwrap_or_else(|| std::path::PathBuf::from("/etc/ld.so.cache"))
93}
94
95/// Every library the cache image at `cache` names, as `(soname, path)`
96/// pairs in cache order. The cache lists a soname once per directory that
97/// holds it, highest priority first, so a reader that wants one path per
98/// soname keeps the first.
99pub fn cache_paths_in(cache: &Path) -> Vec<(String, String)> {
100    let Ok(data) = std::fs::read(cache) else {
101        return Vec::new();
102    };
103    cache_paths(&data)
104        .into_iter()
105        .filter_map(|path| {
106            let (_, name) = path.rsplit_once('/')?;
107            (!name.is_empty()).then(|| (name.to_string(), path.to_string()))
108        })
109        .collect()
110}
111
112const CACHE_MAGIC_OLD: &[u8] = b"ld.so-1.7.0";
113const CACHE_MAGIC_NEW: &[u8] = b"glibc-ld.so.cache1.1";
114
115/// The ABI bits of a cache entry's flags word, `FLAG_REQUIRED_MASK` in
116/// glibc's `dl-cache.h`. A multilib host lists `libGL.so.1` once per ABI,
117/// and the loader picks by these bits; a reader that ignores them hands a
118/// 32-bit process the 64-bit copy.
119const FLAG_ABI_MASK: u32 = 0xff00;
120
121/// The ABI bits glibc tags this runtime's own libraries with, or `None`
122/// where the value is not known, in which case nothing is filtered.
123const fn native_abi() -> Option<u32> {
124    if cfg!(target_arch = "x86_64") {
125        Some(0x0300) // FLAG_X8664_LIB64
126    } else if cfg!(target_arch = "x86") {
127        Some(0x0000) // FLAG_ELF_LIBC6 alone
128    } else if cfg!(target_arch = "aarch64") {
129        Some(0x0a00) // FLAG_AARCH64_LIB64
130    } else if cfg!(target_arch = "powerpc64") {
131        Some(0x0500) // FLAG_POWERPC_LIB64
132    } else {
133        None
134    }
135}
136
137/// `FLAG_ELF_LIBC6`, the type bits every entry a current `ldconfig`
138/// writes carries.
139const FLAG_ELF_LIBC6: u32 = 0x0003;
140
141/// The flags word `ldconfig` writes for a library of this runtime's ABI.
142/// For a test that describes a host of its own making.
143pub const fn native_entry_flags() -> u32 {
144    match native_abi() {
145        Some(abi) => abi | FLAG_ELF_LIBC6,
146        None => FLAG_ELF_LIBC6,
147    }
148}
149
150fn for_this_abi(flags: u32) -> bool {
151    match native_abi() {
152        Some(abi) => flags & FLAG_ABI_MASK == abi,
153        None => true,
154    }
155}
156
157/// The paths a cache image lists for this runtime's ABI, in cache order.
158///
159/// `ldconfig` sorts a library's hwcaps copies (such as
160/// `glibc-hwcaps/x86-64-v3/libzstd.so.1`) ahead of its base copy, and the
161/// loader takes one only after checking that the CPU supports it. A reader
162/// that keeps the first path would hand an older CPU code it cannot run,
163/// so a hwcaps copy is dropped whenever the cache also lists a base copy.
164fn cache_paths(data: &[u8]) -> Vec<&str> {
165    fn file_name(path: &str) -> &str {
166        path.rsplit_once('/').map_or(path, |(_, name)| name)
167    }
168    let entries: Vec<(u64, &str)> = cache_entries(data)
169        .into_iter()
170        .filter_map(|(flags, hwcap, path)| for_this_abi(flags).then_some((hwcap, path)))
171        .collect();
172    let is_hwcaps = |hwcap: u64, path: &str| hwcap != 0 || path.contains("/glibc-hwcaps/");
173    let base: std::collections::HashSet<&str> = entries
174        .iter()
175        .filter(|(hwcap, path)| !is_hwcaps(*hwcap, path))
176        .map(|(_, path)| file_name(path))
177        .collect();
178    entries
179        .into_iter()
180        .filter(|(hwcap, path)| !is_hwcaps(*hwcap, path) || !base.contains(file_name(path)))
181        .map(|(_, path)| path)
182        .collect()
183}
184
185/// Library paths recorded in a glibc loader cache image, each with the
186/// entry's flags and hwcap words. An old-format entry has no hwcap word
187/// and reads as zero.
188///
189/// Two layouts exist. `ldconfig` in its compatibility mode writes the old
190/// header, its entries, and then a complete new-format cache after them;
191/// otherwise it writes the new format alone, which is what current
192/// distributions ship. The new format is preferred wherever it appears, since
193/// the old one cannot express hwcap and is only kept for compatibility.
194fn cache_entries(data: &[u8]) -> Vec<(u32, u64, &str)> {
195    if data.starts_with(CACHE_MAGIC_NEW) {
196        return new_entries(data, 0);
197    }
198    if data.starts_with(CACHE_MAGIC_OLD) {
199        // struct cache_file: char magic[11], then `unsigned int nlibs` at the
200        // next 4-byte boundary, then 12-byte entries.
201        let Some(nlibs) = read_u32(data, 12) else {
202            return Vec::new();
203        };
204        let Some(entries_len) = (nlibs as usize).checked_mul(12) else {
205            return Vec::new();
206        };
207        let Some(end) = entries_len.checked_add(16) else {
208            return Vec::new();
209        };
210        // The new-format header follows, aligned to its 8-byte alignment.
211        let aligned = end.next_multiple_of(8);
212        if data.len() > aligned && data[aligned..].starts_with(CACHE_MAGIC_NEW) {
213            return new_entries(data, aligned);
214        }
215        return old_entries(data, nlibs as usize, end);
216    }
217    Vec::new()
218}
219
220/// Entries of a new-format cache whose header starts at `base`.
221fn new_entries(data: &[u8], base: usize) -> Vec<(u32, u64, &str)> {
222    // Header: magic+version (20), nlibs (4), len_strings (4), flags (1),
223    // padding (3), extension_offset (4), unused (12). Entries follow at 48
224    // and are 24 bytes each: flags, key, value, osversion, then a 64-bit
225    // hwcap. String offsets are relative to `base`.
226    let Some(nlibs) = read_u32(data, base + 20) else {
227        return Vec::new();
228    };
229    let mut out = Vec::new();
230    for i in 0..nlibs as usize {
231        let Some(entry) = base.checked_add(48).and_then(|s| s.checked_add(i * 24)) else {
232            break;
233        };
234        let (Some(flags), Some(value), Some(hwcap_lo), Some(hwcap_hi)) = (
235            read_u32(data, entry),
236            read_u32(data, entry + 8),
237            read_u32(data, entry + 16),
238            read_u32(data, entry + 20),
239        ) else {
240            break;
241        };
242        let hwcap = u64::from(hwcap_hi) << 32 | u64::from(hwcap_lo);
243        if let Some(s) = read_str(data, base + value as usize) {
244            out.push((flags, hwcap, s));
245        }
246    }
247    out
248}
249
250/// Entries of an old-format cache with `nlibs` entries and a string table
251/// beginning at `strings`.
252fn old_entries(data: &[u8], nlibs: usize, strings: usize) -> Vec<(u32, u64, &str)> {
253    let mut out = Vec::new();
254    for i in 0..nlibs {
255        let entry = 16 + i * 12;
256        let (Some(flags), Some(value)) = (read_u32(data, entry), read_u32(data, entry + 8)) else {
257            break;
258        };
259        if let Some(s) = read_str(data, strings + value as usize) {
260            out.push((flags, 0, s));
261        }
262    }
263    out
264}
265
266fn read_u32(data: &[u8], at: usize) -> Option<u32> {
267    let bytes = data.get(at..at.checked_add(4)?)?;
268    Some(u32::from_le_bytes(bytes.try_into().ok()?))
269}
270
271/// The NUL-terminated string at `at`, if it is in bounds, terminated, and
272/// an absolute path. Anything else is a cache we do not understand, and a
273/// relative path would resolve against the app's working directory.
274fn read_str(data: &[u8], at: usize) -> Option<&str> {
275    let rest = data.get(at..)?;
276    let end = rest.iter().position(|&b| b == 0)?;
277    let s = std::str::from_utf8(&rest[..end]).ok()?;
278    s.starts_with('/').then_some(s)
279}
280
281#[cfg(test)]
282mod tests {
283    use super::*;
284
285    fn paths(img: &[u8]) -> Vec<&str> {
286        cache_entries(img).into_iter().map(|(_, _, p)| p).collect()
287    }
288
289    /// A new-format cache image naming `paths`.
290    fn new_cache(paths: &[&str]) -> Vec<u8> {
291        let flagged: Vec<(u32, &str)> = paths.iter().map(|p| (0, *p)).collect();
292        new_cache_flagged(&flagged)
293    }
294
295    /// A new-format cache image naming `entries` as `(flags, path)`.
296    fn new_cache_flagged(entries: &[(u32, &str)]) -> Vec<u8> {
297        let full: Vec<(u32, u64, &str)> = entries.iter().map(|(f, p)| (*f, 0, *p)).collect();
298        new_cache_hwcap(&full)
299    }
300
301    /// A new-format cache image naming `entries` as `(flags, hwcap, path)`.
302    fn new_cache_hwcap(entries: &[(u32, u64, &str)]) -> Vec<u8> {
303        let paths: Vec<&str> = entries.iter().map(|(_, _, p)| *p).collect();
304        let mut out = Vec::from(CACHE_MAGIC_NEW);
305        out.extend_from_slice(&(paths.len() as u32).to_le_bytes());
306        out.extend_from_slice(&0u32.to_le_bytes()); // len_strings
307        out.push(0); // flags
308        out.extend_from_slice(&[0; 3]); // padding
309        out.extend_from_slice(&0u32.to_le_bytes()); // extension_offset
310        out.extend_from_slice(&[0; 12]); // unused
311        assert_eq!(out.len(), 48, "entries must start at 48");
312
313        let base = out.len();
314        let strings_at = base + paths.len() * 24;
315        let (offsets, strings) = string_table(&paths, strings_at);
316        for (off, (flags, hwcap, _)) in offsets.into_iter().zip(entries) {
317            out.extend_from_slice(&flags.to_le_bytes());
318            out.extend_from_slice(&0u32.to_le_bytes()); // key
319            out.extend_from_slice(&(off as u32).to_le_bytes()); // value
320            out.extend_from_slice(&0u32.to_le_bytes()); // osversion
321            out.extend_from_slice(&hwcap.to_le_bytes());
322        }
323        out.extend_from_slice(&strings);
324        out
325    }
326
327    /// An old-format cache image naming `paths`, optionally followed by a
328    /// new-format cache naming `also`, the way glibc before 2.32 wrote it.
329    ///
330    /// The two formats share one string table. glibc bases old-format offsets
331    /// at `&libs[nlibs]`, which is exactly where the new header is aligned to,
332    /// so when both are present both formats count from the same place.
333    fn old_cache(paths: &[&str], also: Option<&[&str]>) -> Vec<u8> {
334        let mut out = Vec::from(CACHE_MAGIC_OLD);
335        out.push(0); // pad to the 4-byte boundary nlibs sits on
336        out.extend_from_slice(&(paths.len() as u32).to_le_bytes());
337        assert_eq!(out.len(), 16, "entries must start at 16");
338
339        let entries_end = 16 + paths.len() * 12;
340        let Some(also) = also else {
341            let (offsets, strings) = string_table(paths, 0);
342            for off in offsets {
343                out.extend_from_slice(&0i32.to_le_bytes()); // flags
344                out.extend_from_slice(&0u32.to_le_bytes()); // key
345                out.extend_from_slice(&(off as u32).to_le_bytes()); // value
346            }
347            assert_eq!(out.len(), entries_end);
348            out.extend_from_slice(&strings);
349            return out;
350        };
351
352        let new_base = entries_end.next_multiple_of(8);
353        let strings_at = new_base + 48 + also.len() * 24;
354        // Both tables count from new_base, so lay the strings out once and
355        // hand each format the slice of offsets that belongs to it.
356        let all: Vec<&str> = paths.iter().chain(also.iter()).copied().collect();
357        let (offsets, strings) = string_table(&all, strings_at - new_base);
358
359        for off in &offsets[..paths.len()] {
360            out.extend_from_slice(&0i32.to_le_bytes());
361            out.extend_from_slice(&0u32.to_le_bytes());
362            out.extend_from_slice(&(*off as u32).to_le_bytes());
363        }
364        out.resize(new_base, 0);
365
366        out.extend_from_slice(CACHE_MAGIC_NEW);
367        out.extend_from_slice(&(also.len() as u32).to_le_bytes());
368        out.extend_from_slice(&0u32.to_le_bytes()); // len_strings
369        out.push(0); // flags
370        out.extend_from_slice(&[0; 3]); // padding
371        out.extend_from_slice(&0u32.to_le_bytes()); // extension_offset
372        out.extend_from_slice(&[0; 12]); // unused
373        for off in &offsets[paths.len()..] {
374            out.extend_from_slice(&0i32.to_le_bytes()); // flags
375            out.extend_from_slice(&0u32.to_le_bytes()); // key
376            out.extend_from_slice(&(*off as u32).to_le_bytes()); // value
377            out.extend_from_slice(&0u32.to_le_bytes()); // osversion
378            out.extend_from_slice(&0u64.to_le_bytes()); // hwcap
379        }
380        assert_eq!(out.len(), strings_at);
381        out.extend_from_slice(&strings);
382        out
383    }
384
385    fn string_table(paths: &[&str], base: usize) -> (Vec<usize>, Vec<u8>) {
386        let mut offsets = Vec::new();
387        let mut strings: Vec<u8> = Vec::new();
388        for p in paths {
389            offsets.push(base + strings.len());
390            strings.extend_from_slice(p.as_bytes());
391            strings.push(0);
392        }
393        (offsets, strings)
394    }
395
396    #[test]
397    fn reads_a_new_format_cache() {
398        let img = new_cache(&[
399            "/usr/lib64/libc.so.6",
400            "/usr/lib/llvm/22/lib64/libLLVM.so.22.1",
401        ]);
402        assert_eq!(
403            paths(&img),
404            [
405                "/usr/lib64/libc.so.6",
406                "/usr/lib/llvm/22/lib64/libLLVM.so.22.1"
407            ]
408        );
409    }
410
411    #[test]
412    fn prefers_the_new_cache_appended_after_an_old_one() {
413        // glibc before 2.32 writes both. The old section is compatibility
414        // padding; reading it instead would miss anything hwcap-tagged.
415        let img = old_cache(&["/lib/old.so.1"], Some(&["/usr/lib64/new.so.2"]));
416        assert_eq!(paths(&img), ["/usr/lib64/new.so.2"]);
417    }
418
419    #[test]
420    fn reads_an_old_format_cache_with_nothing_appended() {
421        let img = old_cache(&["/lib/libz.so.1", "/usr/lib/libm.so.6"], None);
422        assert_eq!(paths(&img), ["/lib/libz.so.1", "/usr/lib/libm.so.6"]);
423    }
424
425    #[test]
426    fn a_damaged_cache_yields_nothing_rather_than_panicking() {
427        assert!(paths(b"").is_empty());
428        assert!(paths(b"not a cache at all").is_empty());
429        // Truncated part-way through the entry table, and a count that would
430        // run far past the end of the image.
431        let img = new_cache(&["/usr/lib64/libc.so.6"]);
432        for cut in 0..img.len() {
433            let _ = paths(&img[..cut]);
434        }
435        let mut lying = new_cache(&["/usr/lib64/libc.so.6"]);
436        lying[20..24].copy_from_slice(&u32::MAX.to_le_bytes());
437        assert!(paths(&lying).len() < 2);
438    }
439
440    #[test]
441    fn relative_and_unterminated_entries_are_skipped() {
442        // A path resolved against the app's working directory would be a way
443        // in for anything that can chdir the process.
444        let img = new_cache(&["not/absolute", "/usr/lib64/fine.so"]);
445        assert_eq!(paths(&img), ["/usr/lib64/fine.so"]);
446
447        let mut unterminated = new_cache(&["/usr/lib64/fine.so"]);
448        let last = unterminated.len() - 1;
449        unterminated[last] = b'x'; // clobber the NUL
450        assert!(paths(&unterminated).is_empty());
451    }
452
453    #[test]
454    fn only_this_abi_is_kept_on_a_multilib_host() {
455        let Some(native) = native_abi() else {
456            return;
457        };
458        // ldconfig lists the other ABI's copy first on a multilib host.
459        let other = if native == 0 { 0x0300 } else { 0 };
460        let img = new_cache_flagged(&[
461            (other | 0x0003, "/usr/lib32/libGL.so.1"),
462            (native | 0x0003, "/usr/lib64/libGL.so.1"),
463            (native | 0x0003, "/usr/lib64/libc.so.6"),
464        ]);
465        assert_eq!(paths(&img).len(), 3, "the reader sees every entry");
466        assert_eq!(
467            cache_paths(&img),
468            ["/usr/lib64/libGL.so.1", "/usr/lib64/libc.so.6"]
469        );
470    }
471
472    /// ldconfig lists hwcaps copies before the base copy. Keeping the first
473    /// path per soname would give a CPU without AVX2 the x86-64-v3 build.
474    #[test]
475    fn hwcaps_copies_yield_to_a_base_copy() {
476        let flags = native_entry_flags();
477        // glibc 2.33+ marks glibc-hwcaps entries with bit 62 and an index.
478        let ext = 1u64 << 62;
479        let img = new_cache_hwcap(&[
480            (flags, ext, "/usr/lib64/glibc-hwcaps/x86-64-v3/libzstd.so.1"),
481            (flags, 0, "/usr/lib64/glibc-hwcaps/x86-64-v2/libzstd.so.1"),
482            (flags, 0, "/usr/lib64/libzstd.so.1"),
483            (flags, 1 << 3, "/usr/lib64/haswell/libfoo.so.1"),
484            (flags, 0, "/usr/lib64/libfoo.so.1"),
485            (flags, ext, "/usr/lib64/glibc-hwcaps/x86-64-v3/libonly.so.1"),
486        ]);
487        assert_eq!(
488            cache_paths(&img),
489            [
490                "/usr/lib64/libzstd.so.1",
491                "/usr/lib64/libfoo.so.1",
492                "/usr/lib64/glibc-hwcaps/x86-64-v3/libonly.so.1",
493            ]
494        );
495    }
496}