Skip to main content

modrt/shared/plat/
modabi.rs

1// modabi -- the ABI of loadable modules (jxl-module): the records the host (modhost.rs) and a
2// module (the module runtime modules/modrt, which has a copy of this file) exchange
3//                                                                       [jxl-module: no asm]
4//
5// A module is a no_std cdylib linked against nothing (no imports; built and checked like a
6// Rust PaintCraft plugin, build_rs.py section jxl-module) that exports exactly one function
7//
8//     <name>_module(host: *const HostTable) -> *const ModTable          extern "win64"
9//
10// (`jxlenc_module` for the JPEG XL writer).  The host keeps the module loaded for the rest of
11// the process; the module keeps the HostTable pointer.  Null = the module refuses the host
12// (another MOD_VERSION).  Every function pointer is extern "win64" on both systems (as the
13// plugin ABI), so the records are the same on Windows and Linux.
14//
15// Memory: the module's global allocator is the host's (HostTable::alloc / free = the host's
16// GlobalAlloc with the same Layout), so blocks move between both sides as Vec<u8> raw parts
17// (JxlReq::rgba to the module, JxlRes to the host) without a copy.
18// Threads: parallel_for runs item(ctx, index, job) on the host's worker pool (and the calling
19// thread); thr_count / thr_self are the pool's, so per-thread arrays of the module work as in
20// the host.  A panic of the module ends in HostTable::panic: the host's normal crash report
21// (stderr "panic: jxlenc: ...", the crash hook, exit code 3); a fault inside the module code
22// goes to the host's crash handlers like any other.
23//
24// Version 1.  Layouts are asserted below.
25
26use core::ffi::c_void;
27
28/// ModTable::magic ("MODM" little endian)
29pub const MOD_MAGIC: u32 = 0x4D44_4F4D;
30/// the ABI version of this file
31pub const MOD_VERSION: u32 = 1;
32/// ModTable::kind of the JPEG XL writer
33pub const MOD_JXLENC: u32 = 1;
34
35/// JxlReq::blobs: which of the blobs are present (None vs Some)
36pub const JXB_ICC: u32 = 1;
37pub const JXB_EXIF: u32 = 2;
38pub const JXB_XMP: u32 = 4;
39
40/// JxlReq::test: crash tests of the module (plat::jxlenc_*: jfgui_JXLENC_TEST=panic / fault)
41pub const JXT_PANIC: u32 = 1;
42pub const JXT_FAULT: u32 = 2;
43
44/// one item of a parallel loop: item(ctx, index, job)
45pub type ItemFn = extern "win64" fn(ctx: *const c_void, index: usize, job: *const c_void);
46
47/// the host's functions (the module keeps the pointer)
48#[repr(C)]
49pub struct HostTable {
50    pub size: u32,    // size_of::<HostTable>()
51    pub version: u32, // MOD_VERSION
52    pub cpu: u32,     // the host's rt::cpu::features() (--simd sse2: 0, the module then uses SSE2 too)
53    pub threads: u32, // workers of the host's pool
54    /// a block of `size` bytes aligned to `align` from the host's allocator (zeroed != 0:
55    /// cleared), null when out of memory
56    pub alloc: extern "win64" fn(size: usize, align: usize, zeroed: u32) -> *mut u8,
57    /// free a block of alloc with its size and alignment
58    pub free: extern "win64" fn(p: *mut u8, size: usize, align: usize),
59    /// item(ctx, i, job) for i in 0..count on the pool; 0 = done, 1 = cancelled
60    pub parallel_for: extern "win64" fn(count: usize, ctx: *const c_void, item: ItemFn) -> u32,
61    /// job.cancel() of the job an item got
62    pub job_cancel: extern "win64" fn(job: *const c_void),
63    /// job.cancelled()
64    pub job_cancelled: extern "win64" fn(job: *const c_void) -> u32,
65    /// the pool's thr_count() / thr_self()
66    pub thr_count: extern "win64" fn() -> u32,
67    pub thr_self: extern "win64" fn() -> usize,
68    /// give the time slice away (spin locks)
69    pub yield_now: extern "win64" fn(),
70    /// one line on stderr ("<module>: msg")
71    pub log: extern "win64" fn(msg: *const u8, len: usize),
72    /// a panic of the module (UTF-8 message): the host's crash report, exit code 3
73    pub panic: extern "win64" fn(msg: *const u8, len: usize) -> !,
74}
75
76/// what a module offers
77#[repr(C)]
78pub struct ModTable {
79    pub size: u32,    // size_of::<ModTable>()
80    pub version: u32, // MOD_VERSION
81    pub magic: u32,   // MOD_MAGIC
82    pub kind: u32,    // MOD_JXLENC
83    /// the JPEG XL writer: 0 and res filled, or ERR_* (res empty)
84    pub jxl_encode: extern "win64" fn(req: *const JxlReq, res: *mut JxlRes) -> i32,
85}
86
87/// a JPEG XL encode: the samples of img_jxl::writer::image_of and the writer's options
88#[repr(C)]
89pub struct JxlReq {
90    pub size: u32, // size_of::<JxlReq>()
91    pub w: u32,
92    pub h: u32,
93    pub gray: u32,  // Px::gray
94    pub alpha: u32, // Px::alpha
95    pub effort: u32,
96    pub quality: u32,
97    pub flags: u32, // IO_FLAGS
98    pub blobs: u32, // JXB_*: which blobs are present
99    pub test: u32,  // JXT_* (0)
100    /// Px::rgba (R, G, B, A per pixel) as Vec raw parts: the module owns it from now on
101    pub rgba: *mut u8,
102    pub rgba_len: usize,
103    pub rgba_cap: usize,
104    pub icc: *const u8,
105    pub icc_len: usize,
106    pub exif: *const u8,
107    pub exif_len: usize,
108    pub xmp: *const u8,
109    pub xmp_len: usize,
110    /// the cancel flag (an AtomicU32), null = none
111    pub cancel: *const u32,
112}
113
114/// the file the writer made, as Vec raw parts (the host owns it from now on)
115#[repr(C)]
116pub struct JxlRes {
117    pub data: *mut u8,
118    pub len: usize,
119    pub cap: usize,
120}
121
122const _: () = assert!(core::mem::size_of::<HostTable>() == 16 + 10 * 8);
123const _: () = assert!(core::mem::size_of::<ModTable>() == 24);
124const _: () = assert!(core::mem::offset_of!(ModTable, jxl_encode) == 16);
125const _: () = assert!(core::mem::size_of::<JxlReq>() == 40 + 10 * 8);
126const _: () = assert!(core::mem::offset_of!(JxlReq, rgba) == 40);
127const _: () = assert!(core::mem::size_of::<JxlRes>() == 24);