Crate binary_layout

Expand description

The binary-layout library allows type-safe, inplace, zero-copy access to structured binary data. You define a custom data layout and give it a slice of binary data, and it will allow you to read and write the fields defined in the layout from the binary data without having to copy any of the data. It’s similar to transmuting to/from a #[repr(packed)] struct, but much safer.

Note that the data does not go through serialization/deserialization or a parsing step. All accessors access the underlying packet data directly.

This crate is #[no_std] compatible.

§Example

use binary_layout::prelude::*;

// See https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol for ICMP packet layout
binary_layout!(icmp_packet, BigEndian, {
  packet_type: u8,
  code: u8,
  checksum: u16,
  rest_of_header: [u8; 4],
  data_section: [u8], // open ended byte array, matches until the end of the packet
});

fn func(packet_data: &mut [u8]) {
  let mut view = icmp_packet::View::new(packet_data);

  // read some data
  let code: u8 = view.code().read();
  // equivalent: let code: u8 = packet_data[1];

  // write some data
  view.checksum_mut().write(10);
  // equivalent: packet_data[2..4].copy_from_slice(&10u16.to_be_bytes());

  // access an open ended byte array
  let data_section: &[u8] = view.data_section();
  // equivalent: let data_section: &[u8] = &packet_data[8..];

  // and modify it
  view.data_section_mut()[..5].copy_from_slice(&[1, 2, 3, 4, 5]);
  // equivalent: packet_data[8..13].copy_from_slice(&[1, 2, 3, 4, 5]);
}

See the icmp_packet module for what this binary_layout! macro generates for you.

§What to use this library for?

Anything that needs inplace zero-copy access to structured binary data.

Network packets are an obvious example
File system inodes
Structured binary data in files if you want to avoid explicit (de)serialization, possibly in combination with memmap.

§Why use this library?

Inplace, zero-copy, type-safe access to your data.
Data layout is defined in one central place, call sites can’t accidentally use wrong field offsets.
Convenient and simple macro DSL to define layouts.
Define a fixed endianness in the layout, ensuring cross platform compatibility.
Fully written in safe Rust, no std::mem::transmute or similar shenanigans.
Const generics ensure that all offset calculations happen at compile time. This, together with inlining annotations, makes this library zero-overhead. Using it is just as performant as writing manual slice accesses into your code.
Comprehensive test coverage.

§Why not `#[repr(packed)]`?

Annotating structs with #[repr(packed)] gives some of the features of this crate, namely it lays out the data fields exactly in the order they’re specified without padding. But it has serious shortcomings that this library solves.

#[repr(packed)] uses the system byte order, which will be different depending on if you’re running on a little endian or big endian system. #[repr(packed)] is not cross-platform compatible. This library is.
#[repr(packed)] can cause undefined behavior on some CPUs when taking references to unaligned data. This library avoids that by not offering any API that takes references to unaligned data. Primitive integer types are allowed to be unaligned but they’re copied and you can’t get references to them. The only data type you can get a reference to is byte arrays, and they only require an alignment of 1 which is trivially always fulfilled.

§When not to use this library?

You need dynamic data structures, e.g. a list that can change size. This library only supports static data layouts (with the exception of open ended byte arrays at the end of a layout).
Not all of your layout fits into the memory and you need to process streams of data. Note that this crate can still be helpful if you have smaller layouted packets as part of a larger stream, as long as any one layouted packet fits into memory.

§Alternatives

To the best of my knowledge, there is no other library offering inplace, zero-copy and type-safe access to structured binary data. But if you don’t need direct access to your data and are ok with a serialization/deserialization step, then there is a number of amazing libraries out there.

Nom is a great crate for all your parsing needs. It can for example parse binary data and put them in your custom structs.
Binread, Binwrite, Binrw are great libraries for (de)serializing binary data.

§APIs

Layouts are defined using the binary_layout! macro. Based on such a layout, this library offers two alternative APIs for data access:

The Field API that offers free functions to read/write the data based on an underlying slice of storage (packet_data in the example above) holding the packet data. This API does not wrap the underlying slice of storage data, which means you have to pass it in to each accessor. This is not the API used in the example above, see Field for an API example.
The FieldView API that wraps a slice of storage data and remembers it in a View object, allowing access to the fields without having to pass in the packed data slice each time. This is the API used in the example above. See FieldView for another example.

§Supported field types

Reading a zero values will throw an error. Because of this, FieldReadExt::read and FieldView::read are not available for those types and you need to use FieldCopyAccess::try_read and FieldView::try_read.

§bool, char

bool and char are supported using the bool as u8 and char as u32 data type notation.

Note that not only 0u8 and 1u8 are valid boolean values and not all u32 values are valid unicode code points. Reading invalid values will throw an error. Because of this, FieldReadExt::read and FieldView::read are not available for those types and you need to use FieldCopyAccess::try_read and FieldView::try_read.

§Primitive Zero-Sized Types (ZSTs)

ZSTs neither read nor write to the underlying storage, but the appropriate traits are implemented for them to support derive macros which may require all members of a struct to implement or enum to also support the various traits.

(), also known as the unit type.

§Fixed size byte arrays: `[u8; N]`.

For these fields, the Field API offers FieldSliceAccess::data, FieldSliceAccess::data_mut, and the FieldView API returns a slice.

§Open ended byte arrays: `[u8]`.

This field type can only occur as the last field of a layout and will mach the remaining data until the end of the storage. This field has a dynamic size, depending on how large the packet data is. For these fields, the Field API offers FieldSliceAccess::data, FieldSliceAccess::data_mut and the FieldView API returns a slice.

§Custom field types

You can define your own custom types as long as they implement the LayoutAs trait to define how to convert them from/to a primitive type.

§Data types maybe supported in the future

These data types aren’t supported yet, but they could be added in theory and might be added in future versions.

bit fields / bool stored as 1 bit

§Data types with dynamic length

This crate relies on a static layout, it cannot support data types with dynamic length. In theory, types with dynamic length could be supported if they either

are the last field of a layout, an already implemented example of this are open ended byte arrays.
or they may be in the middle of the packet but have a maximal size defined and will always reserve storage for their maximal size, even if smaller. This way, the fields after it would still have a constant offset.

Both of these, however, would be some effort to implement and it is unclear if that will ever happen (unless somebody opens a PR for it).

§Strings

For strings, note that even fixed-size UTF-8 strings take a variable number of bytes because of the UTF-8 encoding and that brings all the issues of data types with dynamic length with it. This is why strings aren’t supported yet.

§Fixed-size arrays other than `[u8; N]`

Say we wanted to have a [u32; N] field. The API couldn’t just return a zero-copy &[u32; N] to the caller because that would use the system byte order (i.e. endianness) which might be different from the byte order defined in the packet layout. To make this cross-platform compatible, we’d have to wrap these slices into our own slice type that enforces the correct byte order and return that from the API. This complexity is why it wasn’t implemented yet, but feel free to open a PR if you need this.

§Nesting

Layouts can be nested within each other by using the NestedView type created by the binary_layout! macro for one layout as a field type in another layout.

Example:

use binary_layout::prelude::*;

binary_layout!(icmp_header, BigEndian, {
  packet_type: u8,
  code: u8,
  checksum: u16,
  rest_of_header: [u8; 4],
});
binary_layout!(icmp_packet, BigEndian, {
  header: icmp_header::NestedView,
  data_section: [u8], // open ended byte array, matches until the end of the packet
});

Nested layouts do not need to have the same endianess. The following, which is copied from the complete example at tests/nested.rs in this repository, shows how you can mix different endian layouts together:

use binary_layout::prelude::*;
use core::convert::TryInto;

binary_layout!(deep_nesting, LittleEndian, {
    field1: u16,
});
binary_layout!(header, BigEndian, {
    field1: i16,
});
binary_layout!(middle, NativeEndian, {
    deep: deep_nesting::NestedView,
    field1: u16,
});
binary_layout!(footer, BigEndian, {
    field1: u32,
    deep: deep_nesting::NestedView,
    tail: [u8],
});
binary_layout!(whole, LittleEndian, {
    head: header::NestedView,
    field1: u64,
    mid: middle::NestedView,
    field2: u128,
    foot: footer::NestedView,
});

Modules§

example
This module contains an example use case for defining a layout: ICMP packets.
prelude
Import this to get everything into scope that you need for defining and using layouts.

Macros§

binary_layout
This macro defines a data layout. Given such a layout, the Field or FieldView APIs can be used to access data based on it.
define_layoutDeprecated
Deprecated name for crate::binary_layout!. Please switch to crate::binary_layout!.

Structs§

BigEndian
This is a marker type to mark layouts using big endian encoding. The alternative is LittleEndian and NativeEndian encoding.
Data
An instance of data owns a block of data. It implements AsRef<[u8]> and AsMut<[u8]> to allow borrowing that data, and it has a Data::into_subregion function that cuts away bytes at either end of the block and returns a Data instance that (semantically) owns a subrange of the original Data instance. This works without copying. Implementation wise, the new instance still owns and holds all of the data, just the accessors got limited to a smaller subrange.
FieldView
A field view represents the field metadata stored in a Field plus it stores the underlying storage data it operates on, either as a reference to a slice &[u8], &mut [u8], or as an owning Vec<u8>.
LittleEndian
This is a marker type to mark layouts using little endian encoding. The alternative is BigEndian and NativeEndian encoding.
NativeEndian
This is a marker type to mark layouts using native endian encoding. The alternative is BigEndian and LittleEndian encoding.
NonZeroIsZeroError
This error is thrown when trying to read a non-zero integer type, e.g. NonZeroU32, but the data being read was actually zero.
PrimitiveField
A PrimitiveField is a Field that directly represents a primitive type like u8, i16, … See Field for more info on this API.
WrappedField
A WrappedField is a Field that, unlike PrimitiveField, does not directly represent a primitive type. Instead, it represents a wrapper type that can be converted to/from a primitive type using the LayoutAs trait. See Field for more info on this API.

Enums§

WrappedFieldError
The error being thrown when reading or writing fields that use custom data types implemented via LayoutAs.

Traits§

Endianness
This marker trait represents the endianness used in a layout for accessing primitive integer fields.
Field
A field represents one of the fields in the data layout and offers accessors for it. It remembers the offset of the field in its const generic parameter and the accessors use that to access the field.
FieldCopyAccess
This trait is implemented for fields with “try copy access”, i.e. fields that read/write data by copying it from/to the binary blob, but where reading or writing can fail. Examples of this are primitive types like NonZeroU8, NonZeroI32, …
FieldReadExt
This extension trait adds a FieldReadExt::read method to any type supporting FieldCopyAccess::try_read that has an implementation that cannot throw errors. This is a convenience function so that callers can just call FieldReadExt::read instead of having to call FieldCopyAccess::try_read and then calling Result::unwrap on the returned value.
FieldSliceAccess
This trait is implemented for fields with “slice access”, i.e. fields that are read/write directly without a copy by returning a borrowed slice to the underlying data.
FieldWriteExt
This extension trait adds a FieldWriteExt::write method to any type supporting FieldCopyAccess::try_write that has an implementation that cannot throw errors. This is a convenience function so that callers can just call FieldWriteExt::write instead of having to call FieldCopyAccess::try_write and then calling Result::unwrap on the returned value.
InfallibleResultExt
This extension trait adds InfallibleResultExt::infallible_unwrap to Result types that use core::convert::Infallible as error type.
LayoutAs
Implementing the LayoutAs trait for a custom type allows that custom type to be used as the type of a layout field. Note that the value of this type is copied each time it is accessed, so this is only recommended for primitive wrappers of primitive types, not for types that are expensive to copy.

Crate binary_layoutCopy item path