Module fxfs::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.
• INTERBLOCK_SEEK_VERSION
• JOURNAL_BLOCK_SIZE_CHANGE_VERSION
  The version where the journal block size changed.
• LATEST_VERSION
  The latest version of on-disk filesystem format.
• PER_BLOCK_SEEK_VERSION

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.