Silicon Blade

Lesson

Working with WKS Files in Yocto

How `*.wks` files define disk layouts for custom Yocto images and how to use them with `wic`.

The Yocto Project Platform Development Lesson 12 of 12

*.wks files are the Yocto Project’s way of defining the partition layout for generated images. They describe how wic should assemble boot partitions, root filesystems, bootloaders, and other partitions for media such as SD cards, eMMC, USB, and SATA devices.

Why wks Files Matter

A wks file is not the image itself; it is a recipe for image creation.

  • It describes which partitions to create.
  • It defines the filesystem type and size hints for each partition.
  • It tells wic where to place the root filesystem and boot artifacts.
  • It controls how the bootloader is installed and how the partition table is written.

This makes wks files essential when the default Yocto image types do not match your board’s storage layout.

The wks Workflow in Yocto

The typical flow is:

  1. Build a Yocto image recipe.
  2. Generate a root filesystem artifact such as rootfs.tar.bz2 or rootfs.wic.
  3. Use wic plus a wks file to build a full deployable block image.

In practice, Yocto can build these automatically when you set:

IMAGE_FSTYPES += "wic"
WKS_FILE = "my-board.wks"

That tells the build to pass the named wks file to wic during image generation.

Basic wks Structure

A wks file is a plain text file with directives such as part, bootloader, and imgdata.

  • part defines a partition and its contents.
  • bootloader controls partition table type and bootloader installation.
  • imgdata or bootimg can describe the final image container.

Common part options

--source

What to place in the partition, for example bootimg, rootfs, or hostdir.

--ondisk

Which target device the partition belongs to, such as mmcblk0 or sda.

--fstype

The filesystem type, such as ext4, fat32, or ubifs.

--label

The filesystem label written into the partition.

--size

A size hint for the partition in MiB.

Typical Partition Layouts

A simple embedded board usually needs:

  • a boot partition for firmware, kernel, and device tree
  • a root filesystem partition for the OS
  • optionally a data or persistent partition
  • optionally a dedicated U-Boot environment partition

For example, a minimal layout might look like this:

part --source bootimg --ondisk mmcblk0 --fstype=vfat --label boot --size=64
part --source rootfs --ondisk mmcblk0 --fstype=ext4 --label rootfs --size=2048

A more advanced layout may use GPT, A/B rootfs partitions, or a separate --source rootfs partition for OTA support.

Bootloader and Partition Table Directives

The bootloader directive is where you choose the partition table format and any extra bootloader options.

Common options include:

  • bootloader --ptable=gpt
  • bootloader --ptable=mbr
  • bootloader --append="..."

The exact bootloader directives depend on the boot firmware and board requirements. Some boards also need a raw bootloader image placed in a fixed offset.

Example wks File

A simple wks example:

part --source bootimg --ondisk mmcblk0 --fstype=vfat --label boot --size=64
part --source rootfs --ondisk mmcblk0 --fstype=ext4 --label rootfs --size=2048

A slightly richer example with a separate data partition:

part --source bootimg --ondisk mmcblk0 --fstype=vfat --label boot --size=64
part --source rootfs --ondisk mmcblk0 --fstype=ext4 --label rootfs --size=2048
part --source hostdir --ondisk mmcblk0 --fstype=ext4 --label data --size=512 --sourceparams="/path/to/data"

Integrating wks with Yocto

In your image recipe or local configuration, set:

IMAGE_FSTYPES += "wic"
WKS_FILE = "my-board.wks"

If you need multiple image types, you can also set:

WKS_TYPES = "sdimg"

Use WKS_FILE with the exact name of the .wks file placed in meta-yourlayer/wic/ or ${THISDIR}/files/ depending on your layer layout.

Troubleshooting wic Images

If the generated image does not boot, the common causes are:

  • wrong partition table type for the board
  • bootloader or kernel not installed in the expected location
  • incorrect partition labels or filesystem types
  • bad alignment or size assumptions

Inspect the generated image with tools like fdisk, parted, and hexdump to confirm the partition map and on-disk layout.

Best Practices

  • Keep wks files readable and simple.
  • Use explicit partition labels.
  • Prefer --size hints that are large enough for your rootfs.
  • Validate on real hardware or a representative emulator.
  • Document board-specific layout requirements in the wks file.