Module serialized_types

On-disk versioning

This module manages serialization and deserialization of FxFS structures to disk.

In FxFS, on-disk layout is deferred to serialization libraries (i.e. bincode, serde). Stability of these layouts depends on both struct/enum stability and serialization libraries.

This module provides struct/enum stability by maintaining a generation of types and a means to upgrade from older versions to newer ones.

The trait mechanism used is flexible enough to allow specific versions to use differing serialization code if we ever require it.

Traits

All serialization is done with serde so Serialize and Deserialize traits must be derived for all types and sub-types.

All versioned, serializable struct/enum type should have the Versioned trait. The most recent version of a type should also have the VersionedLatest trait. These traits are largely implemented for you via the versioned_type! macro as follows:

versioned_type! {
  3.. => SuperBlockHeaderV3,
  2.. => SuperBlockHeaderV2,
  1.. => SuperBlockHeaderV1,
}

// Note the reuse of SuperBlockRecordV1 for two versions.
versioned_type! {
  3.. => SuperBlockRecordV2,
  1.. => SuperBlockRecordV1,
}

The user is required to implement From to migrate from one version to the next. The above macros will implement further From traits allowing direct upgrade from any version to the latest. VersionedLatest provides a deserialize_from_version method that can be used to deserialize any supported version and then upgrade it to the latest format.

Conventions

There are limits to how automated this process can be, so we rely heavily on conventions.

• Every versioned type should have a monotonically increasing Vn suffix for each generation.
• Every versioned sub-type (e.g. child of a struct) should also have Vn suffix.
• In type definitions, all versioned child types should be referred to explicitly with their Vn suffix. This prevents us from accidentally changing a version by changing a sub-type.

Macros

versioned_type

Implements traits for versioned structures. Namely:

Structs

BlobMetadata

Version

Version are themselves serializable both alone and as part of other Versioned structures. (For obvious recursive reasons, this structure can never be Versioned itself.)

Constants

DEFAULT_MAX_SERIALIZED_RECORD_SIZE

EARLIEST_SUPPORTED_VERSION

The earliest supported version of the on-disk filesystem format.

FIRST_EXTENT_IN_SUPERBLOCK_VERSION

From this version of the filesystem, the superblock explicitly includes a record for it’s first extent. Prior to this, the first extent was assumed based on hard-coded location.

LATEST_VERSION

The latest version of on-disk filesystem format.

SMALL_SUPERBLOCK_VERSION

From this version of the filesystem, we shrink the size of the extents that are reserved for the superblock and root-parent store to a single block.

Traits

Versioned

This trait is assigned to all versions of a versioned type and is the only means of serialization/deserialization we use.

VersionedLatest

This trait is only assigned to the latest version of a type and allows the type to deserialize any older versions and upgrade them to the latest format.

Attribute Macros

migrate_nodefault

This does nothing by itself, but with the Migrate derive macro, it signals that the struct being migrated to, does not require a Default implementation, since all the fields are available in both.

migrate_to_version

This does nothing by itself, but with the Migrate derive macro, it defines the target to migrate to. Without this, Migrate will make a From impl for IdentVX to Ident.

Derive Macros

Migrate

Adds a From implementation to help migrate structs or enums. This will support the following migrations:

Versioned

This is just a shorthand for impl Versioned for Foo {} which is required for all top-level versioned struct/enum in Fxfs.