lib/std/lang/il/binary.rad 14.7 KiB raw
1
//! Wire definitions for `.ril.bin` package images.
2
//! Integers use little-endian byte order. Sequences have a u32 element count.
3
//! Symbols, layouts and signatures use u32 table indices. Optional fields use
4
//! a byte: zero for absent, one for present.
5
6
export mod writer;
7
export mod reader;
8
export mod program;
9
export mod collect;
10
export mod cfg;
11
export mod linkage;
12
@test export mod tests;
13
14
use std::char;
15
use std::hash::blake3;
16
use std::lang::il;
17
use std::mem;
18
19
/// Minimum wire bytes in a register and value-type parameter.
20
export constant MIN_PARAM_BYTES: u32 = 5;
21
/// Minimum wire bytes in a layout slot.
22
export constant MIN_SLOT_BYTES: u32 = 13;
23
/// Minimum wire bytes in a variant of a union slot.
24
export constant MIN_VARIANT_BYTES: u32 = 9;
25
/// Wire bytes in a region index.
26
export constant REGION_BYTES: u32 = 4;
27
/// Minimum wire bytes in a global data record.
28
export constant MIN_DATA_BYTES: u32 = 15;
29
/// Minimum wire bytes in a repeated data value.
30
export constant MIN_DATA_VALUE_BYTES: u32 = 5;
31
/// Minimum wire bytes in a function record.
32
export constant MIN_FUNCTION_BYTES: u32 = 21;
33
/// Minimum wire bytes in a block record.
34
export constant MIN_BLOCK_BYTES: u32 = 8;
35
/// Minimum wire bytes in an imported symbol.
36
export constant MIN_IMPORT_BYTES: u32 = 13;
37
/// Minimum wire bytes in an exported symbol.
38
export constant MIN_EXPORT_BYTES: u32 = 9;
39
/// Minimum wire bytes in a layout record.
40
export constant MIN_LAYOUT_BYTES: u32 = 16;
41
/// Minimum wire bytes in a function signature.
42
export constant MIN_SIGNATURE_BYTES: u32 = 9;
43
/// Minimum wire bytes in a borrowed result source.
44
export constant MIN_BORROW_BYTES: u32 = 10;
45
/// Minimum wire bytes in a trait record.
46
export constant MIN_TRAIT_BYTES: u32 = 4;
47
/// Minimum wire bytes in a trait method.
48
export constant MIN_METHOD_BYTES: u32 = 9;
49
/// Minimum wire bytes in a switch case.
50
export constant MIN_SWITCH_CASE_BYTES: u32 = 16;
51
52
/// Wire tag for a function import or export.
53
export constant SYMBOL_FUNCTION: u64 = 0;
54
/// Wire tag for a data import or export.
55
export constant SYMBOL_DATA: u64 = 1;
56
57
/// Binary RIL signature, encoded as the bytes RIL followed by zero.
58
export constant MAGIC: u32 = 0x004c4952;
59
60
/// A binary RIL encoding or decoding failure.
61
export union Error: Copy {
62
    /// The output buffer has insufficient space.
63
    Capacity,
64
    /// A referenced name is absent from the symbol table.
65
    Symbol,
66
    /// An integer width, tag, or field is invalid.
67
    Invalid,
68
    /// The input ends inside a field.
69
    Truncated,
70
    /// The decode arena has insufficient space.
71
    Storage,
72
}
73
74
/// Wire tag for value Reg.
75
export constant VALUE_REG: u8 = 0;
76
/// Wire tag for value Imm.
77
export constant VALUE_IMM: u8 = 1;
78
/// Wire tag for value DataSym.
79
export constant VALUE_DATASYM: u8 = 2;
80
/// Wire tag for value FnAddr.
81
export constant VALUE_FNADDR: u8 = 3;
82
/// Wire tag for value Undef.
83
export constant VALUE_UNDEF: u8 = 4;
84
85
/// Wire tag for instruction Reserve.
86
export constant INSTR_RESERVE: u8 = 0;
87
/// Wire tag for instruction Load.
88
export constant INSTR_LOAD: u8 = 1;
89
/// Wire tag for instruction Sload.
90
export constant INSTR_SLOAD: u8 = 2;
91
/// Wire tag for instruction Store.
92
export constant INSTR_STORE: u8 = 3;
93
/// Wire tag for instruction Blit.
94
export constant INSTR_BLIT: u8 = 4;
95
/// Wire tag for instruction Copy.
96
export constant INSTR_COPY: u8 = 5;
97
/// Wire tag for instruction BinOp.
98
export constant INSTR_BINOP: u8 = 6;
99
/// Wire tag for instruction UnOp.
100
export constant INSTR_UNOP: u8 = 7;
101
/// Wire tag for instruction Zext.
102
export constant INSTR_ZEXT: u8 = 8;
103
/// Wire tag for instruction Sext.
104
export constant INSTR_SEXT: u8 = 9;
105
/// Wire tag for instruction Call.
106
export constant INSTR_CALL: u8 = 10;
107
/// Wire tag for instruction Ret.
108
export constant INSTR_RET: u8 = 11;
109
/// Wire tag for instruction Jmp.
110
export constant INSTR_JMP: u8 = 12;
111
/// Wire tag for instruction Br.
112
export constant INSTR_BR: u8 = 13;
113
/// Wire tag for instruction Switch.
114
export constant INSTR_SWITCH: u8 = 14;
115
/// Wire tag for instruction Unreachable.
116
export constant INSTR_UNREACHABLE: u8 = 15;
117
/// Wire tag for instruction Ecall.
118
export constant INSTR_ECALL: u8 = 16;
119
/// Wire tag for instruction Ebreak.
120
export constant INSTR_EBREAK: u8 = 17;
121
/// Wire tag for instruction MemoryFence.
122
export constant INSTR_MEMORYFENCE: u8 = 18;
123
/// Wire tag for a checked device read.
124
export constant INSTR_DEVICE_READ: u8 = 19;
125
/// Wire tag for a checked device write.
126
export constant INSTR_DEVICE_WRITE: u8 = 20;
127
128
/// Wire tag for value type Void.
129
export constant VALTYPE_VOID: u8 = 0;
130
/// Wire tag for value type Data.
131
export constant VALTYPE_DATA: u8 = 1;
132
/// Wire tag for value type Ptr.
133
export constant VALTYPE_PTR: u8 = 2;
134
/// Wire tag for value type Fn.
135
export constant VALTYPE_FN: u8 = 3;
136
/// Wire tag for value type Heap.
137
export constant VALTYPE_HEAP: u8 = 4;
138
139
/// Wire tag for slot kind Ptr.
140
export constant SLOT_PTR: u8 = 0;
141
/// Wire tag for slot kind Slice.
142
export constant SLOT_SLICE: u8 = 1;
143
/// Wire tag for slot kind Fn.
144
export constant SLOT_FN: u8 = 2;
145
/// Wire tag for slot kind Sub.
146
export constant SLOT_SUB: u8 = 3;
147
/// Wire tag for slot kind Array.
148
export constant SLOT_ARRAY: u8 = 4;
149
/// Wire tag for slot kind Trait.
150
export constant SLOT_TRAIT: u8 = 5;
151
/// Wire tag for slot kind Heap.
152
export constant SLOT_HEAP: u8 = 6;
153
/// Wire tag for slot kind Union.
154
export constant SLOT_UNION: u8 = 7;
155
156
/// Heap type flag: the heap can provide elements that have slots.
157
export constant HEAP_TYPED: u8 = 1;
158
/// Heap type flag: the heap can be reset. A heap never has both flags.
159
export constant HEAP_RESET: u8 = 2;
160
161
/// Pointer type flag: the pointee lives as long as the domain.
162
export constant PTR_OWN: u8 = 1;
163
/// Pointer type flag: the pointee can be written.
164
export constant PTR_MUTABLE: u8 = 2;
165
/// Pointer type flag: the pointer can be zero.
166
export constant PTR_NULLABLE: u8 = 4;
167
168
/// Wire tag for instruction Field.
169
export constant INSTR_FIELD: u8 = 21;
170
/// Wire tag for instruction Elem.
171
export constant INSTR_ELEM: u8 = 22;
172
/// Wire tag for instruction SliceElem.
173
export constant INSTR_SLICE_ELEM: u8 = 23;
174
/// Wire tag for instruction SliceNew.
175
export constant INSTR_SLICE_NEW: u8 = 24;
176
/// Wire tag for instruction SliceSub.
177
export constant INSTR_SLICE_SUB: u8 = 25;
178
/// Wire tag for instruction LoadPtr.
179
export constant INSTR_LOAD_PTR: u8 = 26;
180
/// Wire tag for instruction StorePtr.
181
export constant INSTR_STORE_PTR: u8 = 27;
182
/// Wire tag for instruction PageSlice.
183
export constant INSTR_PAGE_SLICE: u8 = 28;
184
/// Wire tag for instruction TraitNew.
185
export constant INSTR_TRAIT_NEW: u8 = 29;
186
/// Wire tag for instruction TraitCall.
187
export constant INSTR_TRAIT_CALL: u8 = 30;
188
/// Wire tag for instruction TraitCopy.
189
export constant INSTR_TRAIT_COPY: u8 = 31;
190
/// Wire tag for instruction SliceLen.
191
export constant INSTR_SLICE_LEN: u8 = 33;
192
/// Wire tag for instruction SliceCopy.
193
export constant INSTR_SLICE_COPY: u8 = 34;
194
/// Wire tag for slice growth from a heap.
195
export constant INSTR_SLICE_GROW: u8 = 35;
196
/// Wire tag for instruction PageHeap.
197
export constant INSTR_PAGE_HEAP: u8 = 36;
198
/// Wire tag for instruction HeapReset.
199
export constant INSTR_HEAP_RESET: u8 = 37;
200
/// Wire tag for instruction UnionGet.
201
export constant INSTR_UNION_GET: u8 = 38;
202
/// Wire tag for instruction UnionSet.
203
export constant INSTR_UNION_SET: u8 = 39;
204
205
/// Wire tag for checked byte loads.
206
export constant INSTR_BYTES_LOAD: u8 = 40;
207
/// Wire tag for checked byte stores.
208
export constant INSTR_BYTES_STORE: u8 = 41;
209
210
/// Wire tag for data Val.
211
export constant DATA_VAL: u8 = 0;
212
/// Wire tag for data Sym.
213
export constant DATA_SYM: u8 = 1;
214
/// Wire tag for data Fn.
215
export constant DATA_FN: u8 = 2;
216
/// Wire tag for data Str.
217
export constant DATA_STR: u8 = 3;
218
/// Wire tag for data Undef.
219
export constant DATA_UNDEF: u8 = 4;
220
221
/// Wire tag for binary operation Add.
222
export constant BIN_ADD: u8 = 0;
223
/// Wire tag for binary operation Sub.
224
export constant BIN_SUB: u8 = 1;
225
/// Wire tag for binary operation Mul.
226
export constant BIN_MUL: u8 = 2;
227
/// Wire tag for binary operation Sdiv.
228
export constant BIN_SDIV: u8 = 3;
229
/// Wire tag for binary operation Udiv.
230
export constant BIN_UDIV: u8 = 4;
231
/// Wire tag for binary operation Srem.
232
export constant BIN_SREM: u8 = 5;
233
/// Wire tag for binary operation Urem.
234
export constant BIN_UREM: u8 = 6;
235
/// Wire tag for binary operation Eq.
236
export constant BIN_EQ: u8 = 7;
237
/// Wire tag for binary operation Ne.
238
export constant BIN_NE: u8 = 8;
239
/// Wire tag for binary operation Slt.
240
export constant BIN_SLT: u8 = 9;
241
/// Wire tag for binary operation Sge.
242
export constant BIN_SGE: u8 = 10;
243
/// Wire tag for binary operation Ult.
244
export constant BIN_ULT: u8 = 11;
245
/// Wire tag for binary operation Uge.
246
export constant BIN_UGE: u8 = 12;
247
/// Wire tag for binary operation And.
248
export constant BIN_AND: u8 = 13;
249
/// Wire tag for binary operation Or.
250
export constant BIN_OR: u8 = 14;
251
/// Wire tag for binary operation Xor.
252
export constant BIN_XOR: u8 = 15;
253
/// Wire tag for binary operation Shl.
254
export constant BIN_SHL: u8 = 16;
255
/// Wire tag for binary operation Sshr.
256
export constant BIN_SSHR: u8 = 17;
257
/// Wire tag for binary operation Ushr.
258
export constant BIN_USHR: u8 = 18;
259
260
/// Wire tag for RotL.
261
export constant BIN_ROTL: u8 = 19;
262
/// Wire tag for RotR.
263
export constant BIN_ROTR: u8 = 20;
264
265
/// Wire tag for unary operation Neg.
266
export constant UN_NEG: u8 = 0;
267
/// Wire tag for unary operation Not.
268
export constant UN_NOT: u8 = 1;
269
270
/// Wire tag for LeadingZeros.
271
export constant UN_LEADING_ZEROS: u8 = 2;
272
/// Wire tag for TrailingZeros.
273
export constant UN_TRAILING_ZEROS: u8 = 3;
274
/// Wire tag for PopCount.
275
export constant UN_POP_COUNT: u8 = 4;
276
/// Wire tag for ByteSwap.
277
export constant UN_BYTE_SWAP: u8 = 5;
278
279
/// Wire tag for comparison Eq.
280
export constant CMP_EQ: u8 = 0;
281
/// Wire tag for comparison Ne.
282
export constant CMP_NE: u8 = 1;
283
/// Wire tag for comparison Slt.
284
export constant CMP_SLT: u8 = 2;
285
/// Wire tag for comparison Ult.
286
export constant CMP_ULT: u8 = 3;
287
288
/// The kind and definition of an exported package symbol.
289
export union ExportKind: Copy {
290
    /// A callable function entry, by index in the package's function table.
291
    Function(u32),
292
    /// A global data definition, by index in the package's data table.
293
    Data(u32),
294
}
295
296
/// A public symbol supplied by a package. A package lists its exports in
297
/// strictly increasing byte order of their names, so names are unique.
298
export record Export: Copy {
299
    /// Qualified symbol name, equal to the name of its definition.
300
    name: *[u8],
301
    /// Definition kind and table index.
302
    kind: ExportKind,
303
    /// Context-entry eligibility, derived by package verification.
304
    startable: bool,
305
}
306
307
/// A 256-bit content identity.
308
export record Id: Copy {
309
    /// Digest bytes in network order.
310
    bytes: [u8; blake3::DIGEST_BYTES],
311
}
312
313
/// Type expected at an imported symbol.
314
export union ImportKind: Copy {
315
    /// Index of the expected signature in the importing program.
316
    Function(u32),
317
    /// Expected data layout and access rights.
318
    Data {
319
        /// Index in the importing program's layout table.
320
        layout: u32,
321
        /// Whether the data can only be read.
322
        readOnly: bool,
323
        /// Heap handle rights, when this names a heap.
324
        heap: ?il::HeapType,
325
    },
326
}
327
328
/// An explicit symbol binding in one importing package. The package's
329
/// instructions use the exported name, which is qualified by its package.
330
export record Import: Copy {
331
    /// Index in the dependency and pin tables.
332
    dependency: u32,
333
    /// Public export key in the selected dependency.
334
    exported: *[u8],
335
    /// Expected call or data contract.
336
    kind: ImportKind,
337
}
338
339
/// Link declarations and a derived verification classification.
340
export record Links: Copy {
341
    /// Compiler metadata hash for exported contracts and RID declarations.
342
    metadata: Id,
343
    /// Metadata hashes in dependency order, one for each dependency.
344
    pins: *[Id],
345
    /// Explicit bindings of imported definitions.
346
    imports: *[Import],
347
    /// Exact payload identity, computed after complete binary decoding.
348
    /// Constructed IL has no identity until it has an encoded payload.
349
    image: ?Id,
350
    /// Whether package verification checked all local bodies and structural import bindings.
351
    /// This field is derived and is never decoded from the wire.
352
    verified: bool,
353
}
354
355
/// Link metadata of a package with no dependencies.
356
export constant EMPTY_LINKS: Links = Links {
357
    metadata: Id { bytes: [0; blake3::DIGEST_BYTES] }, pins: &[], imports: &[], image: nil, verified: false
358
};
359
360
/// Supported RIL package encoding, semantics, and RV64 call, layout, and
361
/// domain-state ABI. A change to any of them changes the version.
362
export constant VERSION: u32 = 1;
363
364
/// Return the decimal major, minor, and patch components of a package version.
365
/// Each component has no leading zeros unless its value is zero.
366
export fn versionParts(text: *[u8]) -> ?[*[u8]; 3] {
367
    let mut parts: [*[u8]; 3] = [""; 3];
368
    let mut start: u32 = 0;
369
    for i in 0 .. 3 {
370
        let mut end = start;
371
        while end < text.len and char::isDigit(text[end]) {
372
            set end += 1;
373
        }
374
        if start == end {
375
            return nil;
376
        }
377
        while start + 1 < end and text[start] == '0' {
378
            set start += 1;
379
        }
380
        set parts[i] = &text[start .. end];
381
        if i < 2 {
382
            if end == text.len or text[end] <> '.' {
383
                return nil;
384
            }
385
            set start = end + 1;
386
        } else if end <> text.len {
387
            return nil;
388
        }
389
    }
390
    return parts;
391
}
392
393
/// A binary package and its IL definitions.
394
/// Referenced storage must remain valid and immutable while the package is read.
395
export record Package: Copy {
396
    /// Release version declared by the package, when present.
397
    version: ?*[u8],
398
    /// Unique symbol names in wire-index order.
399
    symbols: *[*[u8]],
400
    /// Immutable package name.
401
    name: *[u8],
402
    /// Names of required packages.
403
    dependencies: *[*[u8]],
404
    /// Public definitions, sorted by name.
405
    exports: *[Export],
406
    /// Default exported entry, if the package has one.
407
    entry: ?*[u8],
408
    /// Package-local functions and global data.
409
    program: il::Program,
410
    /// Exact dependency identities and typed import bindings.
411
    links: Links,
412
}
413
414
/// Structural limits supplied by the consumer of decoded IL.
415
export record Limits: Copy {
416
    /// Exclusive upper bound for SSA register numbers.
417
    registers: u32,
418
    /// Maximum number of blocks in one function.
419
    blocks: u32,
420
}
421
422
/// Find an export by name in a sorted export table.
423
export fn find(exports: &[Export], name: &[u8]) -> ?Export {
424
    let mut low: u32 = 0;
425
    let mut high = exports.len;
426
    while low < high {
427
        let middle = low + (high - low) / 2;
428
        let order = mem::cmp(exports[middle].name, name);
429
        if order == 0 {
430
            return exports[middle];
431
        }
432
        if order < 0 {
433
            set low = middle + 1;
434
        } else {
435
            set high = middle;
436
        }
437
    }
438
    return nil;
439
}