Skip to main content

Crate binlayout

Crate binlayout 

Source
Expand description

§binlayout

Calculate the size, alignment, field offsets, and padding of binary structures without reading or writing their data. Intended for binary format and protocol implementations, compiler tooling, and guest data models in emulators and VMs.

Host layout and target layout are independent. All byte sizes, offsets, alignments, and array counts use u64, including on a 32-bit host. There are no dependencies and no unsafe code. Rust 1.85 or newer is required.

§Installation

[dependencies]
binlayout = "0.1"

The API reference is available with cargo doc --open.

§Basic layouts

Layout describes byte geometry. Construction validates alignment, which must be a nonzero power of two. Size can be zero or an unpadded intermediate size.

use binlayout::Layout;

let a = Layout::new(1, 1)?;
let b = Layout::new(4, 4)?;
let (combined, offset) = a.extend(b)?;
assert_eq!(offset, 4);
assert_eq!(combined.size(), 8);
assert_eq!(combined.align(), 4);

extend inserts padding before the next field. pad_to_align adds trailing padding when a record is finished. repeat(count) returns an array layout and element stride, including trailing padding for every element.

Calculations that exceed u64 return LayoutError::Overflow.

§Named structures

use binlayout::{Layout, StructLayout};

let header = StructLayout::builder()
    .field("tag", Layout::new(1, 1)?)
    .field("length", Layout::new(4, 4)?)
    .field("flags", Layout::new(2, 2)?)
    .build()?;

assert_eq!((header.size(), header.align()), (12, 4));
assert_eq!(header.offset("tag"), Some(0));
assert_eq!(header.offset("length"), Some(4));
assert_eq!(header.offset("flags"), Some(8));
assert_eq!(header.fields()[1].padding_before(), 3);
assert_eq!(header.tail_padding(), 2);
Byte rangeContents
0tag
1–3padding
4–7length
8–9flags
10–11tail padding

Fields retain declaration order. Duplicate names are errors; unknown names return None. header.layout() can be nested in another structure or repeated as an array.

For byte-packed wire formats, use .packed(1) on the builder: this header then has offsets 0, 1, 5, size 7, and alignment 1. A larger power-of-two packing value caps field alignment at that value. .align(n) imposes a minimum aggregate alignment. Packing does not alter padding already inside a nested layout. FieldLayout::layout() preserves the original layout while FieldLayout::align() reports the effective placement alignment.

§Types and targets

Type describes fixed-width unsigned/signed integers, floats, pointers, arrays, ordered structures, and unions. A target supplies scalar and pointer alignment rules.

use binlayout::{TargetLayout, Type};

let foo = Type::Struct(vec![Type::U8, Type::Pointer]);
let wasm32 = TargetLayout::wasm32();
let x86_64 = TargetLayout::x86_64();

let a = wasm32.layout_of(&foo)?;
let b = x86_64.layout_of(&foo)?;
assert_eq!((a.size(), a.align()), (8, 4));
assert_eq!((b.size(), b.align()), (16, 8));

// Use named types when you also need field offsets.
let named = x86_64.struct_layout([
    ("tag", Type::U8),
    ("data", Type::Pointer),
])?;
assert_eq!(named.offset("data"), Some(8));

let records = Type::array(foo, 3);
assert_eq!(wasm32.layout_of(&records)?.size(), 24);
assert_eq!(x86_64.layout_of(&records)?.size(), 48);

Custom targets require explicit pointer size and alignment. Scalar alignments default to their byte sizes, and can be overridden individually:

use binlayout::{Scalar, TargetLayout, Type};

let target = TargetLayout::builder()
    .pointer_size(4)
    .pointer_align(4)
    .scalar_alignment(Scalar::U64, 4)
    .scalar_alignment(Scalar::I64, 4)
    .scalar_alignment(Scalar::F64, 4)
    .build()?;

let record = Type::Struct(vec![Type::U8, Type::U64]);
assert_eq!(target.layout_of(&record)?.size(), 12);

Scalar and pointer sizes must be nonzero multiples of alignment. Signed and unsigned scalar overrides are independent. For a packed target-specific record, pass target.layout_of(&ty)? into StructLayout::builder().field(...).

The wasm32 and x86-64 presets cover scalar, pointer, and aggregate layouts; they do not implement complete calling conventions or bit-field rules.

§Unions

Unions place every member at offset zero and round the largest member size up to the union alignment. They do not add a tag or discriminant.

use binlayout::{Layout, UnionLayout};

let payload = UnionLayout::builder()
    .field("bytes", Layout::new(9, 1)?)
    .field("number", Layout::new(8, 8)?)
    .build()?;
assert_eq!((payload.size(), payload.align()), (16, 8));
assert_eq!(payload.offset("bytes"), Some(0));
assert_eq!(payload.offset("number"), Some(0));
assert_eq!(payload.tail_padding(), 7);

UnionLayout supports the same .packed(n) and .align(n) builder options as structures. Type::Union(vec![...]) and target.union_layout([("name", ty), ...]) provide target-dependent union calculations. tail_padding() counts bytes past the largest member, not unused bytes after a smaller alternative.

§Format examples

  • cargo run --example header: padding and 32/64-bit pointer layouts.
  • cargo run --example elf: ELF32 and ELF64 headers, with every field offset.
  • cargo run --example protocol: a byte-packed tagged union.

§no_std

Disable the default std feature:

[dependencies]
binlayout = { version = "0.1", default-features = false }

alloc is still required for names and type/field collections. Basic Layout arithmetic does not allocate.

§License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. See LICENSE or https://mozilla.org/MPL/2.0/.

Structs§

FieldLayout
One named field’s placement within a structure or union.
Layout
Size and alignment in bytes, independent of the host’s address space.
StructLayout
A declaration-order structure with field offsets and trailing padding.
StructLayoutBuilder
Builds a structure. Validation and arithmetic errors are returned by build.
TargetLayout
Explicit scalar and pointer rules for an external data model.
TargetLayoutBuilder
Configures a target without inspecting the host.
UnionLayout
Overlapping named fields, all starting at offset zero.
UnionLayoutBuilder
Builds a union, reporting validation and arithmetic errors at build.

Enums§

LayoutError
A layout could not be constructed or represented in u64 bytes.
Scalar
A fixed-width scalar whose alignment can be customized for a target.
Type
A target-independent type description; no binary data is stored or decoded.