Skip to main content

modrt/
lib.rs

1// modrt -- the runtime of a loadable module (jxl-module): what `rt` is for an app, for a no_std
2// cdylib without imports that runs inside a host process (PaintCraft loads modules/jxlenc)
3//                                                                       [jxl-module: no asm]
4//
5// The module build (build_rs.py section jxl-module) passes this crate as `rt` (and
6// modules/modplat as `plat`) to every library crate the module contains (simd, gfx,
7// img_core, img_jpeg, img_jxl, img_jxl_enc), so their unchanged sources compile against it:
8//
9//   cpu, crash, fx, sync, x87   copies of the files of lib/rt in shared/ (the same SSE /
10//                               x87 float semantics, the same CPU feature bits, spin lock)
11//   os                          what rt::os is, through the host: yield_now, exit (a panic),
12//                               write_stdout / write_stderr (the host's log)
13//   modabi                      a copy of lib/plat/modabi.rs: the host / module records
14//   host()                      the host's table (set by the entry)
15//   module_entry!(name, TABLE)  the module's one export: name(&HostTable) -> &TABLE
16//   jxl_table::<W>()            a ModTable whose jxl_encode runs W::encode (JxlWriter) on a
17//                               safe JxlRequest (the raw JxlReq unpacked here)
18//   (global allocator)          the host's allocator (HostTable::alloc / free): blocks move
19//                               between host and module as Vec raw parts
20//   (panic handler)             the message to HostTable::panic: the host's crash report
21//   (memcpy, memset, ...)       a copy of lib/plugin/mem.rs (assembly: never an export)
22//
23// shared/ holds byte-equal copies, because a package may not reach outside its folder
24// (docs/CRATES.md); build_rs.py's lint refuses a copy that differs from its source.
25//
26// One of the crates that may contain `unsafe` (it is the module's rt); a module's own code is
27// `#![deny(unsafe_code)]` with module_entry!() as its one exception (as plugin::entry!).
28#![no_std]
29
30extern crate alloc;
31
32#[path = "shared/rt/cpu.rs"]
33pub mod cpu;
34#[path = "shared/rt/crash.rs"]
35pub mod crash;
36#[path = "shared/rt/fx.rs"]
37pub mod fx;
38#[path = "shared/rt/portable/fx.rs"]
39pub mod scalar_fx;
40/// Portable float contract used by the common scalar SIMD backend in module builds.
41pub mod portable {
42    /// Explicit scalar rounding/conversion operations shared with the application runtime.
43    pub use crate::scalar_fx as fx;
44}
45#[path = "shared/rt/sync.rs"]
46pub mod sync;
47#[path = "shared/rt/x87.rs"]
48pub mod x87;
49#[path = "shared/plat/modabi.rs"]
50pub mod modabi;
51#[path = "shared/plugin/mem.rs"]
52mod mem;
53
54use alloc::vec::Vec;
55use core::alloc::{GlobalAlloc, Layout};
56use core::mem::ManuallyDrop;
57use core::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
58
59use modabi::*;
60
61static HOST: AtomicPtr<HostTable> = AtomicPtr::new(core::ptr::null_mut());
62
63/// the host's table (a module runs only after its entry stored it; before: a fault)
64#[inline]
65pub fn host() -> &'static HostTable {
66    let p = HOST.load(Ordering::Acquire);
67    if p.is_null() {
68        trap();
69    }
70    // SAFETY: the entry stored a pointer to the host's table, which lives as long as the
71    // process (the host leaks it on purpose).
72    unsafe { &*p }
73}
74
75/// ud2: a fault the host's crash handler reports
76pub fn trap() -> ! {
77    // SAFETY: an illegal instruction, nothing else.
78    unsafe { core::arch::asm!("ud2", options(noreturn, nomem, nostack)) }
79}
80
81/// the OS calls rt makes, through the host
82pub mod os {
83    /// give the time slice away (the host's yield)
84    pub fn yield_now() {
85        (crate::host().yield_now)()
86    }
87
88    /// end the process: as a panic of the module (rt calls it only on its crash path)
89    pub fn exit(code: i32) -> ! {
90        let mut s = crate::crash::StackText::<64>::new();
91        let _ = core::fmt::Write::write_fmt(&mut s, format_args!("exit({code}) inside the module"));
92        (crate::host().panic)(s.bytes().as_ptr(), s.bytes().len())
93    }
94
95    /// a line for the host's log
96    pub fn write_stdout(b: &[u8]) {
97        let b = b.strip_suffix(b"\n").unwrap_or(b);
98        (crate::host().log)(b.as_ptr(), b.len())
99    }
100
101    /// a line for the host's log
102    pub fn write_stderr(b: &[u8]) {
103        write_stdout(b)
104    }
105}
106
107/// the host's allocator
108struct HostAlloc;
109
110unsafe impl GlobalAlloc for HostAlloc {
111    unsafe fn alloc(&self, l: Layout) -> *mut u8 {
112        (host().alloc)(l.size(), l.align(), 0)
113    }
114    unsafe fn alloc_zeroed(&self, l: Layout) -> *mut u8 {
115        (host().alloc)(l.size(), l.align(), 1)
116    }
117    unsafe fn dealloc(&self, p: *mut u8, l: Layout) {
118        (host().free)(p, l.size(), l.align())
119    }
120}
121
122#[global_allocator]
123static ALLOC: HostAlloc = HostAlloc;
124
125#[panic_handler]
126fn panic(info: &core::panic::PanicInfo) -> ! {
127    use core::fmt::Write;
128    let mut s = crash::StackText::<1024>::new(); // no allocation on the crash path
129    let _ = write!(s, "{info}");
130    let p = HOST.load(Ordering::Acquire);
131    if p.is_null() {
132        trap();
133    }
134    // SAFETY: as host().
135    let h = unsafe { &*p };
136    (h.panic)(s.bytes().as_ptr(), s.bytes().len())
137}
138
139/// the entry of module_entry!: keep the host's table (version 1 only), take its CPU features
140/// (--simd sse2 in the host: SSE2 kernels here too) -> the module's table, or null
141pub fn entry(h: *const HostTable, tab: &'static ModTable) -> *const ModTable {
142    if h.is_null() {
143        return core::ptr::null();
144    }
145    // SAFETY: the host passes its table (read once here, then kept).
146    let t = unsafe { &*h };
147    if t.version != MOD_VERSION || (t.size as usize) < core::mem::size_of::<HostTable>() {
148        return core::ptr::null();
149    }
150    HOST.store(h as *mut HostTable, Ordering::Release);
151    if t.cpu & cpu::CPU_AVX2 == 0 && cpu::features() & cpu::CPU_AVX2 != 0 {
152        cpu::force_baseline();
153    }
154    tab
155}
156
157/// the module's one export: `name(&HostTable) -> &TABLE` (extern "win64", #[no_mangle])
158#[macro_export]
159macro_rules! module_entry {
160    ($name:ident, $table:path) => {
161        /// the module's entry (lib/plat/modabi.rs)
162        #[allow(unsafe_code)]
163        #[unsafe(no_mangle)]
164        pub extern "win64" fn $name(host: *const $crate::modabi::HostTable) -> *const $crate::modabi::ModTable {
165            $crate::entry(host, &$table)
166        }
167    };
168}
169
170/// a JPEG XL encode as the module's writer gets it (JxlReq unpacked)
171pub struct JxlRequest<'a> {
172    pub w: u32,
173    pub h: u32,
174    pub gray: bool,
175    pub alpha: bool,
176    pub rgba: Vec<u8>, // owned (the host's allocation)
177    pub effort: u32,
178    pub quality: u32,
179    pub flags: u32,
180    pub icc: Option<&'a [u8]>,
181    pub exif: Option<&'a [u8]>,
182    pub xmp: Option<&'a [u8]>,
183    pub cancel: Option<&'a AtomicU32>,
184}
185
186/// the writer of a jxlenc module
187pub trait JxlWriter {
188    /// the file, or ERR_*
189    fn encode(req: JxlRequest<'_>) -> Result<Vec<u8>, i32>;
190}
191
192/// the ModTable of a jxlenc module with the writer W
193pub const fn jxl_table<W: JxlWriter>() -> ModTable {
194    ModTable {
195        size: core::mem::size_of::<ModTable>() as u32,
196        version: MOD_VERSION,
197        magic: MOD_MAGIC,
198        kind: MOD_JXLENC,
199        jxl_encode: jxl_encode::<W>,
200    }
201}
202
203/// a blob of the request (None when its JXB_* bit is clear)
204///
205/// # Safety
206/// p, n describe a buffer that lives as long as the request (or n == 0).
207unsafe fn blob<'a>(on: bool, p: *const u8, n: usize) -> Option<&'a [u8]> {
208    if !on {
209        return None;
210    }
211    if p.is_null() || n == 0 {
212        return Some(&[]);
213    }
214    // SAFETY: the caller's contract.
215    Some(unsafe { core::slice::from_raw_parts(p, n) })
216}
217
218const ERR_HDR: i32 = -2;
219
220extern "win64" fn jxl_encode<W: JxlWriter>(req: *const JxlReq, res: *mut JxlRes) -> i32 {
221    if req.is_null() || res.is_null() {
222        return ERR_HDR;
223    }
224    // SAFETY: the host passes its request record for the time of the call.
225    let r = unsafe { &*req };
226    if r.size as usize != core::mem::size_of::<JxlReq>() || r.rgba.is_null() || r.rgba_len > r.rgba_cap {
227        return ERR_HDR;
228    }
229    // SAFETY: the host hands over its Vec<u8> of the samples (raw parts); its blocks come from
230    // the host's allocator, which is this module's global allocator (same layout rules).
231    let rgba = unsafe { Vec::from_raw_parts(r.rgba, r.rgba_len, r.rgba_cap) };
232    match r.test {
233        JXT_PANIC => panic!("test panic inside the module (jfgui_JXLENC_TEST=panic)"),
234        // SAFETY: a deliberate 4-byte write to address 0x10 (the crash tests of the host).
235        JXT_FAULT => unsafe { core::arch::asm!("mov dword ptr [{0}], {1:e}", in(reg) 0x10usize, in(reg) 16u32, options(nostack)) },
236        _ => {}
237    }
238    // SAFETY: the blobs and the cancel flag live in the host during the call.
239    let q = unsafe {
240        JxlRequest {
241            w: r.w,
242            h: r.h,
243            gray: r.gray != 0,
244            alpha: r.alpha != 0,
245            rgba,
246            effort: r.effort,
247            quality: r.quality,
248            flags: r.flags,
249            icc: blob(r.blobs & JXB_ICC != 0, r.icc, r.icc_len),
250            exif: blob(r.blobs & JXB_EXIF != 0, r.exif, r.exif_len),
251            xmp: blob(r.blobs & JXB_XMP != 0, r.xmp, r.xmp_len),
252            cancel: (r.cancel as *const AtomicU32).as_ref(),
253        }
254    };
255    match W::encode(q) {
256        Ok(v) => {
257            let mut v = ManuallyDrop::new(v); // the host owns it now
258            // SAFETY: the host's result record, written once.
259            unsafe { *res = JxlRes { data: v.as_mut_ptr(), len: v.len(), cap: v.capacity() } };
260            0
261        }
262        Err(e) => e,
263    }
264}