FFX Plugin for Product and Image Assembly

TODO: Document Product Assembly

Image Assembly RFC-0072.

Image Assembly is responsible for taking prebuilt artifacts and generating images that can be used to update or flash a Fuchsia device. The FFX plugin has three subcommands: create-system, create-update, and

create-system

Create a Fuchsia system that minimally includes a ZBI, and optionally a VBMeta and FVM images.

ffx assembly create-system                           \
  --image-assembly-config image_assembly_config.json \
  --images images_config.json                        \
  --outdir <output-directory>

Arguments

Modes

Outputs

create-update

Create an update package for updating a running Fuchsia system.

ffx assembly create-update                    \
  --packages packages.json                    \
  --partitions partitions.json                \
  --system-a images.json                      \
  --system-r recovery_images.jso              \
  --board-name "board"                        \
  --version-file version.txt                  \
  --epoch 0                                   \
  --outdir <output-directory>

Arguments

Outputs

Image Assembly Config

The image assembly config specifies the contents of the Fuchsia system that is put into the images.

{
  // The set of packages included when flashing or updating a device, and should
  // not be removed by the garbage collector.
  base: [ "path/to/package_manifest.json" ],

  // The set of packages included when flashing or updating a device, but can be
  // removed by the garbage collector.
  cache: [ "path/to/package_manifest.json" ],

  // The set of system-critical packages included in the "System Image"
  // (i.e. base package).
  system: [ "path/to/package_manifest.json" ],

  kernel: {

    // Path on host to the kernel ZBI.
    path: "path/to/kernel.zbi",

    // The arguments to pass to the kernel on boot.
    args: [ "arg1", "arg2" ],
  },

  // Arguments available in the boot service for userspace programs.
  boot_args: [ "arg1", "arg2" ],

  // Files to put in BootFS.
  bootfs_files: [
    {
      source: "path/to/file/on/host",
      destination: "path/to/file/in/bootfs",
    }
  ],

  // Packages to put in BootFS.
  bootfs_packages: [
    "path/to/package_manifest.json",
    "path/to/package_manifest.json",
  ]
}

Images Config

The images config specifies which images to generate and how.

{
  images: [
    <image>,
    <image>,
  ],
}

<image> specifies a single image to generate, and has the following format.

{
  type: "<type>",
  name: "<name>",
  <type-specific-parameters>,
}

<type> can be one of: zbi, vbmeta, or fvm.

zbi type

{
  type: "zbi",

  // The name to give the file: fuchsia.zbi
  name: "fuchsia",

  // The compression format for the ZBI.
  compression: "zstd.max",

  // An optional script to post-process the ZBI.
  // This is often used to prepare the ZBI for the
  postprocessing_script: <post-processing-script>,
}

<post-processing-script> has the following format.

{
  // The path to the script on host.
  // This script _musts_ take the following arguments:
  //   -z <path to ZBI>
  //   -o <output path>
  //   -B <build directory, relative to script's source directory>
  path: "path/to/script/on/host.sh",

  // Additional arguments to pass to the script after the above arguments.
  args: [ "arg1", "arg2" ],
}

VBMeta Type

{
  type: "vbmeta",

  // The name to give the file: fuchsia.vbmeta
  name: "fuchsia",

  // Path on host to the key for signing VBMeta.
  key: "path/to/key/on/host",

  // Path on host to the key metadata to add to the VBMeta.
  key_metadata: "path/to/key/metadata/on/host",

  // Optional descriptors to add to the VBMeta image.
  additional_descriptors: [
    <descriptor>,
    <descriptor>,
  ],
}

VBMeta Descriptor

<descriptor> has the following format.

{
  // Name of the partition.
  name: "mypart",

  // Size of the partition in bytes.
  size: 12345,

  // Custom VBMeta flags to add.
  flags: 1,

  // Minimum AVB version to add.
  min_avb_version: "1.1",
}

FVM Type

{
  type: "fvm",

  // The name to give the file: fvm.blk
  name: "fvm",

  // The size of a slice within the FVM.
  slice_size: 0,

  // The list of filesystems to generate that can be added to the outputs.
  filesystems: [
    <filesystem>,
    <filesystem>,
  ],

  // The FVM images to generate.
  outputs: [
    <fvm-output>,
    <fvm-output>,
  ],
}

Filesystem

<filesystem> can be one of the following.

{
  type: "blobfs",

  // The name of the volume in the FVM.
  name: "blob",

  // Optionally compress the volume file.
  compress: true,

  // Optional deprecated layout.
  layout: "deprecated-padded",

  // Reserve |minimum_data_bytes| and |minimum_inodes| in the FVM, and ensure
  // that the final reserved size does not exceed |maximum_bytes|.
  maximum_bytes: 0,
  minimum_data_bytes: 0,
  minimum_inodes: 0,
}

{
  type: "empty-data",

  // The name of the volume in the FVM.
  name: "empty-data",
}

{
  type: "reserved",

  // The name of the volume in the FVM.
  name: "internal",

  // The number of slices to reserve.
  slices: 1000,
}

FVM Output

<fvm-output> can be one of the following.

{
  type: "standard",

  // The name to give the file: fvm.blk.
  name: "fvm",

  // The filesystems to include in the FVM.
  filesystems: [
    "blob",
    "data",
    "internal",
  ],

  // Whether to compress the FVM.
  compress: true,

  // Shrink the FVM to fit exactly the contents.
  resize_image_file_to_fit: true,

  // After the optional resize, truncate the file to this length.
  truncate_to_length: 0,
}

{
  type: "sparse",

  // The name to give the file: fvm.sparse.blk.
  name: "fvm.sparse",

  // The filesystems to include in the FVM.
  filesystems: [
    "blob",
    "data",
    "internal",
  ],

  // Whether to compress the FVM.
  compress: true,

  // The maximum size the FVM can expand to at runtime.
  // This sets the amount of slice metadata to allocate during construction,
  // which cannot be modified at runtime.
  max_disk_size: 0,
}

{
  type: "nand",

  // The name to give the file: fvm.nand.blk.
  name: "fvm.nand",

  // The filesystems to include in the FVM.
  filesystems: [
    "blob",
    "data",
    "internal",
  ],

  // Whether to compress the FVM.
  compress: true,

  // The maximum size the FVM can expand to at runtime.
  // This sets the amount of slice metadata to allocate during construction,
  // which cannot be modified at runtime.
  max_disk_size: 0,
  block_count: 0,
  oob_size: 0,
  page_size: 0,
  pages_per_block: 0,
}

Example

{
  images: [
    {
      type: "zbi",
      name: "fuchsia",
    },
    {
      type: "vbmeta",
      name: "fuchsia",
      key: "path/to/key",
      key_metadata: "path/to/key/metadata",
    },
    {
      type: "fvm",
      name: "fvm",
      slice_size: 0,
      filesystems: [
        {
          type: "blobfs",
          name: "blob",
          compress: true,
          maximum_bytes: 65536,
          minimum_data_bytes: 0,
          minimum_inodes: 4096,
        },
      ],
      outputs: [
        {
          type: "standard",
          name: "fvm",
          filesystems: [
            "blob",
            "empty-data",
          ],
        },
        {
          type: "sparse",
          name: "fvm.sparse",
          filesystems: [
            "blob",
            "empty-data",
          ],
          compress: true,
          max_disk_size: 65536,
        },
      ],
    },
  ],
}

Images Manifest

[
  <image>,
  <image>,
]

Image

<image> has the following format.

{
  name: "zircon-a",
  path: "path/on/host/to/image",
  type: <image-type>,
}

<image-type> must be one of: zbi, vbmeta, base-package, blob, storage-full, storage-sparse, storage-sparse-blob, or fvm.fastboot.

Example

[
  {
    name: "zircon-a",
    path: "path/to/fuchsia.zbi",
    type: "zbi",
  },
  {
    name: "zircon-a",
    path: "path/to/fuchsia.vbmeta",
    type: "vbmeta",
  }
]

Partitions Config

{

  // The list of bootloader partitions that are not slot-specific.
  booloader_partitions: [
    <bootloader-partition>,
    <bootloader-partition>,
  ],

  // The list of non-bootloader partitions that are slot-specific.
  partitions: [
    <partition>,
    <partition>,
  ],
}

Bootloader Partition

<bootloader-partition> has the following format.

{
  // The name of the partition known to fastboot.
  name: "bootloader",

  // The firmware type provided to the update system.
  // See documentation here:
  //   https://fuchsia.dev/fuchsia-src/concepts/packages/update_pkg
  type: "tpl",

  // Path on host to the image.
  image: "path/on/host/to/image",
}

Partition

<partition> has the following format.

{
  // The name of the partition known to fastboot.
  name: "zircon_a",
  type: "<partition-type>",
  slot: "<partition-slot>",
}

<partition-type> can be one of: ZBI, VBMeta, FVM. <partition-slot> can be one of: A, B, R.

Example

{
  booloader_partitions: [
    {
      name: "bootloader",
      type: "tpl",
      image: "path/to/bootloader.tpl",
    },
  ],
  partitions: [
    {
      name: "zircon_a",
      type: "ZBI",
      slot: "A",
    },
    {
      name: "vbmeta_a",
      type: "VBMeta",
      slot: "A",
    },
    {
      name: "zircon_b",
      type: "ZBI",
      slot: "B",
    },
    {
      name: "vbmeta_b",
      type: "VBMeta",
      slot: "B",
    },
    {
      name: "fvm",
      type: "FVM",
      slot: "A",
    },
  ],
}