#binary #layout #data #structured #format

binary-layout

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.

8 releases (4 stable)

2.0.1 Jul 19, 2021
1.0.1 May 2, 2021
0.4.0 May 2, 2021
0.3.0 May 1, 2021
0.1.0 May 1, 2021

#180 in Data structures

Download history 94/week @ 2021-04-28 3/week @ 2021-05-05 15/week @ 2021-05-12 6/week @ 2021-06-02 21/week @ 2021-06-09 9/week @ 2021-06-16 39/week @ 2021-06-23 91/week @ 2021-06-30 47/week @ 2021-07-07 91/week @ 2021-07-14 34/week @ 2021-07-21

117 downloads per month

MIT/Apache

130KB
2K SLoC

Build Status Latest Version docs.rs License License codecov unsafe forbidden

binary-layout

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 package data directly.

Example

use binary_layout::prelude::*;

// See https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol for ICMP package layout
define_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().data();
  // equivalent: let data_section: &[u8] = &packet_data[8..];

  // and modify it
  view.data_section_mut().data_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 define_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 make sure that all offset calculations happen at compile time and will not have a runtime overhead.
  • 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. 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 packages 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 define_layout! macro. Based on such a layout, this library offers two alternative APIs for data access:

  1. 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.
  2. 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

Primitive integer types

For these fields, the Field API offers FieldCopyAccess::read, FieldCopyAccess::write and the FieldView API offers FieldView::read and FieldView::write.

Fixed size byte arrays: [u8; N].

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

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 package data is. For these fields, the Field API offers FieldSliceAccess::data, FieldSliceAccess::data_mut and the FieldView API offers FieldView::data, FieldView::data_mut and FieldView::extract.

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.

  • bool stored as 1 byte
  • 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 package 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 package 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.

License: MIT OR Apache-2.0

Dependencies

~45KB