MAINTAINERS | 7 + block/meson.build | 5 +- block/overlaybd.c | 1962 ++++++++++++++++++++++++ docs/system/qemu-block-drivers.rst.inc | 37 + meson.build | 9 + meson_options.txt | 4 + qapi/block-core.json | 39 + scripts/meson-buildoptions.sh | 6 + tests/qemu-iotests/tests/overlaybd | 795 ++++++++++ tests/qemu-iotests/tests/overlaybd.out | 10 + 10 files changed, 2873 insertions(+), 1 deletion(-) create mode 100644 block/overlaybd.c create mode 100755 tests/qemu-iotests/tests/overlaybd create mode 100644 tests/qemu-iotests/tests/overlaybd.out
Overlaybd (overlay block device) is a novel layered
image format based on block-diff representation. It
was originally designed for fast launching of containers,
and it is also feasible for virtual machines.
It features:
(1) small index with variable-length block size;
(2) fast lookup with linearized B+ tree and SIMD; (binary search for now);
(3) O(1) lookup at any number of depth (internal backing chain);
(4) optionally fast decompression with lz4 or zstd;
(5) OCI-compatible layering and manifest.
Signed-off-by: Huiba Li <huiba.lhb@alibaba-inc.com>
---
MAINTAINERS | 7 +
block/meson.build | 5 +-
block/overlaybd.c | 1962 ++++++++++++++++++++++++
docs/system/qemu-block-drivers.rst.inc | 37 +
meson.build | 9 +
meson_options.txt | 4 +
qapi/block-core.json | 39 +
scripts/meson-buildoptions.sh | 6 +
tests/qemu-iotests/tests/overlaybd | 795 ++++++++++
tests/qemu-iotests/tests/overlaybd.out | 10 +
10 files changed, 2873 insertions(+), 1 deletion(-)
create mode 100644 block/overlaybd.c
create mode 100755 tests/qemu-iotests/tests/overlaybd
create mode 100644 tests/qemu-iotests/tests/overlaybd.out
diff --git a/MAINTAINERS b/MAINTAINERS
index 6be9c5725b..a71264490b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4436,6 +4436,13 @@ L: qemu-block@nongnu.org
S: Supported
F: block/dmg.c
+overlaybd
+M: Huiba Li <huiba.lhb@alibaba-inc.com>
+L: qemu-block@nongnu.org
+S: Supported
+F: block/overlaybd.c
+F: tests/qemu-iotests/tests/overlaybd*
+
parallels
M: Stefan Hajnoczi <stefanha@redhat.com>
M: Denis V. Lunev <den@openvz.org>
diff --git a/block/meson.build b/block/meson.build
index bc419aebf0..48fdac8b0b 100644
--- a/block/meson.build
+++ b/block/meson.build
@@ -39,7 +39,7 @@ block_ss.add(files(
'throttle.c',
'throttle-groups.c',
'write-threshold.c',
-), zstd, zlib)
+), zstd, zlib, lz4)
system_ss.add(when: 'CONFIG_TCG', if_true: files('blkreplay.c'))
system_ss.add(files('block-ram-registrar.c'))
@@ -69,6 +69,9 @@ endif
if get_option('bochs').allowed()
block_ss.add(files('bochs.c'))
endif
+if get_option('overlaybd').allowed()
+ block_ss.add(files('overlaybd.c'))
+endif
if get_option('vvfat').allowed()
block_ss.add(files('vvfat.c'))
endif
diff --git a/block/overlaybd.c b/block/overlaybd.c
new file mode 100644
index 0000000000..9d3b5eb437
--- /dev/null
+++ b/block/overlaybd.c
@@ -0,0 +1,1962 @@
+/*
+ *
+ * Read-only block driver for OverlayBD images
+ *
+ * An OverlayBD image is a stack of layer files. Each layer is an LSMT
+ * blob: a 4096-byte header, a data region,
+ * a sorted index of 16-byte LBA mappings, and a 4096-byte trailer. The
+ * driver merges the per-layer indexes top-down (a top layer's mapping
+ * wins its whole extent; lower layers only fill holes) and serves reads
+ * at 512-byte sector granularity. Holes and zeroed mappings read as
+ * zeros.
+ *
+ * Layers may optionally be wrapped in a single-entry tar and/or
+ * compressed with ZFile (block-wise LZ4 or ZSTD with a jump table).
+ *
+ * The layer stack is given either by an OCI image manifest, whose layer
+ * digests name blobs in a local directory (manifest option, or the file
+ * child for -drive file=... usage), or as an explicit bottom-first
+ * "layers" array.
+ *
+ * See also the reference implementation:
+ * https://github.com/containerd/overlaybd
+ *
+ * Specifications for the on-disk formats:
+ * LSMT layer blob format (header, data, index, trailer)
+ * https://github.com/containerd/overlaybd/blob/main/src/overlaybd/lsmt/format_spec.md
+ * ZFile block compression format (jump table, LZ4/ZSTD)
+ * https://github.com/containerd/overlaybd/blob/main/src/overlaybd/zfile/format_spec.md
+ *
+ * The layer blobs are named by an OCI image manifest; the remaining OCI
+ * specifications are listed where the manifest is parsed:
+ * https://github.com/opencontainers/image-spec/blob/main/manifest.md
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#include "qemu/osdep.h"
+#include "qapi/error.h"
+#include "block/block-io.h"
+#include "block/block_int.h"
+#include "block/qdict.h"
+#include "qemu/module.h"
+#include "qemu/bswap.h"
+#include "qemu/crc32c.h"
+#include "qemu/cutils.h"
+#include "qemu/memalign.h"
+#include "qobject/qjson.h"
+#include "qobject/qdict.h"
+#include "qobject/qlist.h"
+
+#ifdef CONFIG_LZ4
+#include <lz4.h>
+#endif
+#ifdef CONFIG_ZSTD
+#include <zstd.h>
+#endif
+
+/*
+ *
+ * On-disk format definitions below mirror the reference implementation
+ * (containerd/overlaybd: lsmt/file.cpp HeaderTrailer, lsmt/index.h,
+ * zfile/zfile.cpp HeaderTrailer, zfile/compressor.h CompressOptions)
+ * field for field; per-struct citations mark the source of each layout.
+ * Metadata is little-endian on disk and is read through explicit
+ * little-endian accessors, which also sidesteps the signedness of
+ * ldl_le_p() for the 32-bit fields.
+ */
+
+static const char lsmt_magic0[8] = "LSMT\0\1\2";
+static const uint8_t lsmt_magic1[16] = {
+ 0x65, 0x7e, 0x63, 0xd2, 0x94, 0x44, 0x08, 0x4c,
+ 0xa2, 0xd2, 0xc8, 0xec, 0x4f, 0xcf, 0xae, 0x8a
+};
+static const char zfile_magic0[8] = "ZFile\0\1";
+static const uint8_t zfile_magic1[16] = "tuji.yyf@Alibaba";
+
+/* LSMT::HeaderTrailer::SPACE, lsmt/file.cpp */
+#define LSMT_HT_SPACE 4096
+/* LSMT::MAX_LSMT_RO_INDEX_SIZE, lsmt/index.h */
+#define LSMT_MAX_RO_INDEX_ENTRIES 1000000LL
+/* LSMT::MAX_LSMT_INDEX_SIZE, lsmt/index.h: cap on the merged index */
+#define LSMT_MAX_MERGED_ENTRIES 128000000LL
+/* LSMT::MAX_STACK_LAYERS, lsmt/file.h */
+#define LSMT_MAX_LAYERS 255
+/* LSMT::Segment::INVALID_OFFSET, lsmt/index.h */
+#define LSMT_INVALID_OFFSET (((uint64_t)1 << 50) - 1)
+#define LSMT_MOFFSET_BEGIN (LSMT_HT_SPACE / BDRV_SECTOR_SIZE)
+
+/* LSMT::HeaderTrailer::FLAG_SHIFT_*, lsmt/file.cpp */
+#define LSMT_FLAG_HEADER (1u << 0)
+#define LSMT_FLAG_DATA_FILE (1u << 1)
+#define LSMT_FLAG_SEALED (1u << 2)
+
+/*
+ * LSMT::HeaderTrailer, lsmt/file.cpp: a packed struct with byte-aligned
+ * fields only (no bitfields), identical to the upstream definition less
+ * the C++ methods, and covering the whole LSMT_HT_SPACE block that is
+ * read and written. Upstream stops at user_tag (sizeof == 390) and
+ * keeps the tail outside the type, reading the block into a raw buffer
+ * and casting it; format_spec.md:32 documents that tail as a header
+ * field, so it is declared here instead.
+ */
+typedef struct QEMU_PACKED OverlaybdLSMTHeader {
+ uint64_t magic0;
+ uint8_t magic1[16];
+ uint32_t size; /* 390: the fields above, tail excluded */
+ uint32_t flags;
+ uint64_t index_offset;
+ uint64_t index_size; /* # of 16-byte index entries */
+ uint64_t virtual_size; /* bytes */
+ uint8_t uuid[37]; /* UUID::String */
+ uint8_t parent_uuid[37]; /* UUID::String */
+ uint16_t reserved;
+ uint8_t version;
+ uint8_t sub_version;
+ uint8_t user_tag[256]; /* TAG_SIZE */
+ uint8_t reserved_space[3706];
+} OverlaybdLSMTHeader;
+
+QEMU_BUILD_BUG_ON(sizeof(OverlaybdLSMTHeader) != LSMT_HT_SPACE);
+
+/* ZFile::HeaderTrailer::SPACE, zfile/zfile.cpp */
+#define ZFILE_HT_SPACE 512
+/*
+ * ZFile::MAX_READ_SIZE, zfile/zfile.h: upstream uses this one constant
+ * both as the block size cap and as the size of BlockReader's
+ * compressed-data read window. Only the block size cap is needed here --
+ * the read window is sized to the request.
+ */
+#define ZFILE_MAX_BLOCK_SIZE 65536
+/*
+ * qemu-side hardening: a jump table entry is image-controlled, so cap the
+ * compressed size of one block to bound the read window. Upstream has no
+ * span cap; it ERANGEs when a block overflows its 64 KiB window instead.
+ */
+#define ZFILE_MAX_SPAN (1u << 20)
+/* ZFile::CompressOptions::LZ4 / ZSTD, zfile/compressor.h */
+#define ZFILE_ALGO_LZ4 1
+#define ZFILE_ALGO_ZSTD 2
+
+/* ZFile::HeaderTrailer::FLAG_SHIFT_*, zfile/zfile.cpp */
+#define ZFILE_FLAG_HEADER (1ULL << 0)
+#define ZFILE_FLAG_DATA_FILE (1ULL << 1)
+#define ZFILE_FLAG_SEALED (1ULL << 2)
+#define ZFILE_FLAG_HEADER_OVERWRITE (1ULL << 3)
+#define ZFILE_FLAG_DIGEST (1ULL << 4)
+#define ZFILE_FLAG_INDEX_COMPRESSED (1ULL << 5)
+
+/* ZFile::CompressOptions, zfile/compressor.h: sizeof == 24 */
+typedef struct QEMU_PACKED OverlaybdCompressOptions {
+ uint32_t block_size;
+ uint8_t algo;
+ uint8_t level;
+ uint8_t use_dict;
+ uint8_t __padding_0;
+ uint32_t reserved;
+ uint32_t dict_size;
+ uint8_t verify;
+ uint8_t __padding_1[7];
+} OverlaybdCompressOptions;
+
+/*
+ * ZFile::HeaderTrailer, zfile/zfile.cpp, embedding ZFile::CompressOptions
+ * at offset 72: upstream is not packed, but every member is naturally
+ * aligned at these offsets, so a packed C struct has the identical
+ * layout. As with the LSMT header, the ZFILE_HT_SPACE tail that
+ * upstream keeps outside the type is declared here, per
+ * format_spec.md:39 (offset 89 ~ 511, of which opt.__padding_1 already
+ * covers 89 ~ 95).
+ */
+typedef struct QEMU_PACKED OverlaybdZFileHeader {
+ uint64_t magic0;
+ uint8_t magic1[16];
+ uint32_t size; /* 96: the fields above, tail excluded */
+ uint32_t digest; /* CRC32C of bytes 28..511, digest zeroed */
+ uint64_t flags;
+ uint64_t index_offset;
+ uint64_t index_size; /* # of u32 jump-table entries (blocks) */
+ uint64_t original_file_size;
+ uint32_t index_crc;
+ uint32_t reserved_0;
+ OverlaybdCompressOptions opt;
+ uint8_t reserved_space[416];
+} OverlaybdZFileHeader;
+
+QEMU_BUILD_BUG_ON(sizeof(OverlaybdCompressOptions) != 24);
+QEMU_BUILD_BUG_ON(sizeof(OverlaybdZFileHeader) != ZFILE_HT_SPACE);
+
+/* ZFile::MAX_ZFILE_INDEX_SIZE, zfile/zfile.cpp */
+#define ZFILE_MAX_INDEX_ENTRIES 1000000000LL
+
+/* crc32c_salt()'s seed, zfile/zfile.cpp: per-block CRCs are salted */
+#define ZFILE_CRC_SALT 100007
+
+/*
+ * ZFile::JumpTable, zfile/zfile.cpp: within-group offsets are uint16_t,
+ * so one group spans at most UINT16_MAX + 1 bytes of compressed data.
+ */
+#define ZFILE_JUMP_GROUP_BYTES (UINT16_MAX + 1u)
+
+#define ZFILE_INDEX_CHUNK_BYTES (1 << 20) /* ZFile::load_jump_table delta */
+#define ZFILE_INDEX_MAX_COROUTINES 32
+
+/*
+ * In-memory 16-byte index entry. The field assignment mirrors the
+ * on-disk SegmentMapping (lo = lba:50 | length:14, hi = moffset:55 |
+ * zeroed:1 | tag:8, the tag slot holding the serving layer at runtime,
+ * like the reference implementation), but this struct deliberately does
+ * NOT map the disk image: bitfields are forbidden in packed or
+ * exact-layout structures (docs/devel/style.rst), so on-disk bytes are
+ * decoded by overlaybd_decode_entry() with explicit little-endian loads
+ * and the bit order below is compiler-managed, never exposed.
+ */
+typedef struct OverlaybdSegment {
+ uint64_t lba:50;
+ uint64_t length:14;
+ uint64_t moffset:55;
+ uint64_t zeroed:1;
+ uint64_t layer:8;
+} OverlaybdSegment;
+
+QEMU_BUILD_BUG_ON(sizeof(OverlaybdSegment) != 16);
+
+typedef struct OverlaybdZfile {
+ uint64_t index_offset; /* jump table offset, ZFile-relative bytes */
+ uint64_t index_size;
+ uint64_t original_file_size;
+ uint32_t block_size;
+ uint8_t algo;
+ bool verify;
+ /*
+ * ZFile::JumpTable, zfile/zfile.cpp: block @i starts at
+ * partial_offset[i >> group_shift] + deltas[i], except at a group
+ * boundary where the delta is zero.
+ */
+ uint64_t *partial_offset;
+ uint16_t *deltas;
+ unsigned group_shift;
+} OverlaybdZfile;
+
+typedef struct OverlaybdLayer {
+ BdrvChild *child;
+ bool is_zfile;
+ uint64_t base_offset; /* tar prefix length in the child, bytes */
+ uint64_t view_size;
+ OverlaybdZfile zf;
+ /* LSMT metadata, in ZFile-virtual space for compressed layers */
+ uint64_t index_offset;
+ OverlaybdSegment *index;
+ size_t index_count;
+ uint64_t virtual_size;
+} OverlaybdLayer;
+
+typedef struct BDRVOverlaybdState {
+ OverlaybdLayer *layers; /* top-first: layers[0] is the topmost layer */
+ int nb_layers;
+ OverlaybdSegment *merged;
+ size_t merged_cap;
+ size_t merged_count;
+ uint64_t virtual_size;
+} BDRVOverlaybdState;
+
+/*
+ * Load one on-disk 16-byte index entry (two little-endian u64:
+ * lo = lba:50 | length:14, hi = moffset:55 | zeroed:1 | tag:8) into the
+ * host-side entry. The on-disk tag is discarded; the merge assigns
+ * layers.
+ */
+static void overlaybd_decode_entry(const uint8_t *p, OverlaybdSegment *out)
+{
+ uint64_t lo = ldq_le_p(p);
+ uint64_t hi = ldq_le_p(p + 8);
+
+ out->lba = lo & (((uint64_t)1 << 50) - 1);
+ out->length = (lo >> 50) & ((1u << 14) - 1);
+ out->moffset = hi & (((uint64_t)1 << 55) - 1);
+ out->zeroed = (hi >> 55) & 1;
+ out->layer = 0;
+}
+
+static bool overlaybd_has_magic(const void *ht, const void *magic0,
+ const void *magic1)
+{
+ return memcmp(ht, magic0, 8) == 0 &&
+ memcmp((const uint8_t *)ht + 8, magic1, 16) == 0;
+}
+
+static bool overlaybd_is_lsmt_header(const uint8_t *buf)
+{
+ return overlaybd_has_magic(buf, lsmt_magic0, lsmt_magic1);
+}
+
+static bool overlaybd_is_zfile_header(const uint8_t *buf)
+{
+ return overlaybd_has_magic(buf, zfile_magic0, zfile_magic1);
+}
+
+static bool overlaybd_is_tar_header(const uint8_t *hdr)
+{
+ return memcmp(hdr + 257, "ustar", 5) == 0 &&
+ (hdr[156] == '0' || hdr[156] == '\0' || hdr[156] == 'x');
+}
+
+static bool overlaybd_verify_lsmt_block(const OverlaybdLSMTHeader *ht,
+ bool is_trailer)
+{
+ uint32_t flags;
+
+ if (!overlaybd_has_magic(ht, lsmt_magic0, lsmt_magic1)) {
+ return false;
+ }
+ flags = le32_to_cpu(ht->flags);
+ if (is_trailer) {
+ return !(flags & LSMT_FLAG_HEADER) &&
+ (flags & LSMT_FLAG_DATA_FILE) &&
+ (flags & LSMT_FLAG_SEALED);
+ }
+ return flags & LSMT_FLAG_HEADER;
+}
+
+/*
+ * Upstream's crc32::crc32c_extend() is the raw CRC-32C recurrence with no
+ * post-conditioning, while qemu's crc32c() inverts once on return, so XOR
+ * the result to recover upstream's value for any seed. A wrong convention
+ * here fails silently against real images: nothing but the digest mismatches.
+ */
+static uint32_t overlaybd_crc32c(uint32_t seed, const void *buf, size_t len)
+{
+ return crc32c(seed, buf, len) ^ 0xffffffff;
+}
+
+static bool overlaybd_zfile_verify_digest(OverlaybdZFileHeader *blk)
+{
+ uint32_t crc, saved = le32_to_cpu(blk->digest);
+
+ blk->digest = 0;
+ crc = overlaybd_crc32c(0, blk, sizeof(*blk));
+ blk->digest = cpu_to_le32(saved);
+ return crc == saved;
+}
+
+static bool overlaybd_zfile_verify_block(OverlaybdZFileHeader *blk,
+ bool is_trailer)
+{
+ uint64_t flags;
+
+ if (!overlaybd_has_magic(blk, zfile_magic0, zfile_magic1)) {
+ return false;
+ }
+ flags = le64_to_cpu(blk->flags);
+ if (is_trailer) {
+ if ((flags & ZFILE_FLAG_HEADER) || !(flags & ZFILE_FLAG_DATA_FILE) ||
+ !(flags & ZFILE_FLAG_SEALED)) {
+ return false;
+ }
+ } else {
+ if (!(flags & ZFILE_FLAG_HEADER)) {
+ return false;
+ }
+ }
+ if (flags & ZFILE_FLAG_DIGEST && !overlaybd_zfile_verify_digest(blk)) {
+ return false;
+ }
+ return true;
+}
+
+/*
+ * Locate a header/trailer block of @ht_space bytes near the end of the
+ * layer and return its offset, relative to the child, or -errno. The
+ * block found is also copied to @ht_out, which must hold @ht_space bytes:
+ * it has already been read and validated here, so re-reading it at the
+ * returned offset would be a second I/O for the same bytes.
+ *
+ * The end of the layer is not the end of the child: a tar wrapper pads
+ * its entry to a blocking factor, so the scan must stop at
+ * base_offset + view_size. That end is still not exact for a bare layer,
+ * whose view_size is just bdrv_getlength() rounded up to 512 bytes, so
+ * scan the last @ht_space + 511 bytes for the magic (the same approach
+ * as dmg_find_koly_offset()), taking the match closest to the end.
+ */
+static int64_t GRAPH_RDLOCK
+overlaybd_scan_trailer(OverlaybdLayer *l, size_t ht_space, bool is_zfile,
+ void *ht_out)
+{
+ int64_t end = l->base_offset + l->view_size;
+ int64_t window, off, found = -ENOENT;
+ uint8_t *buf;
+ int ret;
+
+ window = (int64_t)ht_space + 511;
+ off = end > window ? end - window : 0;
+ window = end - off;
+
+ buf = g_malloc(window);
+ ret = bdrv_pread(l->child, off, window, buf, 0);
+ if (ret < 0) {
+ g_free(buf);
+ return ret;
+ }
+ for (int64_t i = (int64_t)window - ht_space; i >= 0; i--) {
+ bool ok;
+
+ /* copy the whole block: the ZFile digest covers all 512 bytes */
+ if (is_zfile) {
+ OverlaybdZFileHeader blk;
+
+ memcpy(&blk, buf + i, sizeof(blk));
+ ok = overlaybd_zfile_verify_block(&blk, true);
+ } else {
+ OverlaybdLSMTHeader blk;
+
+ memcpy(&blk, buf + i, sizeof(blk));
+ ok = overlaybd_verify_lsmt_block(&blk, true);
+ }
+ if (ok) {
+ memcpy(ht_out, buf + i, ht_space);
+ found = off + i;
+ break;
+ }
+ }
+ g_free(buf);
+ return found;
+}
+
+/*
+ * ZFile::JumpTable::build(), zfile/zfile.cpp: turn the on-disk u32
+ * block lengths into one absolute offset per group plus uint16_t
+ * within-group prefix sums. @offset_begin is where block 0 lives,
+ * relative to the ZFile.
+ */
+static int overlaybd_zfile_build_table(OverlaybdZfile *zf,
+ const uint32_t *table,
+ uint64_t offset_begin, Error **errp)
+{
+ uint64_t group_size = ZFILE_JUMP_GROUP_BYTES / zf->block_size;
+ uint64_t min_span = zf->verify ? 4 : 0;
+ uint64_t raw_offset = offset_begin;
+ uint32_t span;
+
+ zf->group_shift = ctz64(group_size);
+ /*
+ * g_try_new, not g_new: both sizes come from the image, and a hostile
+ * header can ask for gigabytes (at block_size 65536, group_size is 1
+ * and partial_offset costs 8 bytes per entry).
+ */
+ zf->partial_offset = g_try_new(uint64_t, zf->index_size / group_size + 1);
+ zf->deltas = g_try_new(uint16_t, zf->index_size + 1);
+ if (!zf->partial_offset || !zf->deltas) {
+ return -ENOMEM;
+ }
+ zf->partial_offset[0] = raw_offset;
+ zf->deltas[0] = 0;
+
+ for (uint64_t i = 1; i <= zf->index_size; i++) {
+ span = ldl_le_p((const uint8_t *)&table[i - 1]);
+
+ if (span <= min_span || span > ZFILE_MAX_SPAN) {
+ error_setg(errp, "invalid ZFile block size in jump table");
+ return -EINVAL;
+ }
+ raw_offset += span;
+ if (i % group_size == 0) {
+ zf->partial_offset[i / group_size] = raw_offset;
+ zf->deltas[i] = 0;
+ continue;
+ }
+ if ((uint64_t)zf->deltas[i - 1] + span >= UINT16_MAX) {
+ error_setg(errp, "ZFile compressed blocks in one jump table "
+ "group exceed %d bytes", UINT16_MAX);
+ return -ERANGE;
+ }
+ zf->deltas[i] = zf->deltas[i - 1] + span;
+ }
+ return 0;
+}
+
+/* ZFile::JumpTable::operator[], zfile/zfile.cpp */
+static uint64_t overlaybd_zfile_block_off(const OverlaybdZfile *zf,
+ uint64_t idx)
+{
+ uint64_t part = zf->partial_offset[idx >> zf->group_shift];
+
+ if (idx & ((1ULL << zf->group_shift) - 1)) {
+ return part + zf->deltas[idx];
+ }
+ return part;
+}
+
+typedef struct OverlaybdZfileLoad {
+ BdrvChild *child;
+ int64_t offset; /* table start, relative to the child */
+ uint8_t *table;
+ uint64_t bytes; /* table size */
+ uint64_t next; /* first byte no coroutine has claimed yet */
+ int nb_done;
+ int ret;
+} OverlaybdZfileLoad;
+
+/*
+ * The caller holds the graph rdlock across the whole open, so these
+ * coroutines take no further lock. They share the one cursor in @load:
+ * claiming a chunk reads load->next then advances it with no yield between,
+ * and coroutines in one AioContext never run concurrently, so the chunks are
+ * partitioned with no locking. Inputs are copied to locals here; only next,
+ * ret and nb_done stay shared (a private next would spin on chunk 0 forever).
+ */
+static void coroutine_fn GRAPH_RDLOCK
+overlaybd_zfile_load_co(void *opaque)
+{
+ OverlaybdZfileLoad *load = opaque;
+ BdrvChild *child = load->child;
+ int64_t offset = load->offset;
+ uint8_t *table = load->table;
+ uint64_t bytes = load->bytes;
+
+ while (load->next < bytes) {
+ uint64_t off = load->next;
+ uint64_t len = MIN(bytes - off, (uint64_t)ZFILE_INDEX_CHUNK_BYTES);
+ int ret;
+
+ load->next = off + len;
+
+ ret = bdrv_co_pread(child, offset + off, len, table + off, 0);
+ if (ret < 0) {
+ if (load->ret == 0) {
+ load->ret = ret;
+ }
+ break;
+ }
+ }
+ load->nb_done++;
+}
+
+static int GRAPH_RDLOCK
+overlaybd_zfile_load_table(OverlaybdLayer *l, uint32_t *table, Error **errp)
+{
+ OverlaybdZfile *zf = &l->zf;
+ uint64_t bytes = zf->index_size * sizeof(uint32_t);
+ int ret;
+
+ if (bytes <= ZFILE_INDEX_CHUNK_BYTES) {
+ ret = bdrv_pread(l->child, l->base_offset + zf->index_offset,
+ bytes, table, 0);
+ } else {
+ OverlaybdZfileLoad load = {
+ .child = l->child,
+ .offset = l->base_offset + zf->index_offset,
+ .table = (uint8_t *)table,
+ .bytes = bytes,
+ };
+ int nb_chunks = DIV_ROUND_UP(bytes, ZFILE_INDEX_CHUNK_BYTES);
+ int nb_cos = MIN(nb_chunks, ZFILE_INDEX_MAX_COROUTINES);
+
+ for (int i = 0; i < nb_cos; i++) {
+ qemu_coroutine_enter(qemu_coroutine_create(overlaybd_zfile_load_co,
+ &load));
+ }
+ BDRV_POLL_WHILE(l->child->bs, load.nb_done < nb_cos);
+ ret = load.ret;
+ }
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read ZFile jump table");
+ }
+ return ret;
+}
+
+static int GRAPH_RDLOCK
+overlaybd_zfile_open(OverlaybdLayer *l, Error **errp)
+{
+ BdrvChild *child = l->child;
+ OverlaybdZfile *zf = &l->zf;
+ OverlaybdZFileHeader ht;
+ uint64_t flags, index_offset, index_size, original_file_size;
+ uint32_t *table = NULL;
+ uint32_t block_size;
+ uint8_t algo, verify;
+ int64_t child_size, zfile_end;
+ uint64_t end_reserve;
+ int ret;
+
+ child_size = bdrv_getlength(child->bs);
+ if (child_size < 0) {
+ error_setg_errno(errp, -child_size, "could not get layer file size");
+ return child_size;
+ }
+ child_size -= l->base_offset;
+ if (child_size < 2 * ZFILE_HT_SPACE) {
+ error_setg(errp, "layer file too small to be a ZFile");
+ return -EINVAL;
+ }
+
+ ret = bdrv_pread(child, l->base_offset, sizeof(ht), &ht, 0);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read ZFile header");
+ return ret;
+ }
+ if (!overlaybd_zfile_verify_block(&ht, false)) {
+ error_setg(errp, "invalid ZFile header");
+ return -EINVAL;
+ }
+
+ flags = le64_to_cpu(ht.flags);
+ /*
+ * The layer's own end, not the child's: a tar wrapper pads its entry.
+ * bdrv_getlength() also rounds up, so when there is a trailer the
+ * scanned trailer position gives the exact end instead.
+ */
+ zfile_end = l->view_size;
+ end_reserve = 0;
+ if (!(flags & ZFILE_FLAG_HEADER_OVERWRITE)) {
+ /*
+ * Without HEADER_OVERWRITE the trailer carries the final metadata,
+ * so the header is dead once its flags have been read and the
+ * trailer is read into the same block -- as upstream does.
+ */
+ int64_t trl_off = overlaybd_scan_trailer(l, ZFILE_HT_SPACE, true,
+ &ht);
+
+ if (trl_off < 0) {
+ error_setg(errp, "invalid ZFile trailer");
+ return -EINVAL;
+ }
+ flags = le64_to_cpu(ht.flags);
+ zfile_end = trl_off + ZFILE_HT_SPACE - (int64_t)l->base_offset;
+ end_reserve = ZFILE_HT_SPACE;
+ }
+
+ if (flags & ZFILE_FLAG_INDEX_COMPRESSED) {
+ error_setg(errp, "compressed ZFile jump table is not supported");
+ return -ENOTSUP;
+ }
+
+ index_offset = le64_to_cpu(ht.index_offset);
+ index_size = le64_to_cpu(ht.index_size);
+ original_file_size = le64_to_cpu(ht.original_file_size);
+ block_size = le32_to_cpu(ht.opt.block_size);
+ algo = ht.opt.algo;
+ verify = ht.opt.verify;
+
+ if (ht.opt.use_dict != 0) {
+ error_setg(errp, "ZFile with dictionary is not supported");
+ return -ENOTSUP;
+ }
+ if (block_size == 0 || block_size > ZFILE_MAX_BLOCK_SIZE ||
+ !is_power_of_2(block_size)) {
+ error_setg(errp, "invalid ZFile block size %" PRIu32, block_size);
+ return -EINVAL;
+ }
+ if (algo != ZFILE_ALGO_LZ4 && algo != ZFILE_ALGO_ZSTD) {
+ error_setg(errp, "unknown ZFile compression algorithm %" PRIu8, algo);
+ return -EINVAL;
+ }
+#ifndef CONFIG_LZ4
+ if (algo == ZFILE_ALGO_LZ4) {
+ error_setg(errp, "LZ4-compressed layer, but qemu was compiled "
+ "without lz4 support");
+ return -ENOTSUP;
+ }
+#endif
+#ifndef CONFIG_ZSTD
+ if (algo == ZFILE_ALGO_ZSTD) {
+ error_setg(errp, "ZSTD-compressed layer, but qemu was compiled "
+ "without zstd support");
+ return -ENOTSUP;
+ }
+#endif
+
+ if (index_size > ZFILE_MAX_INDEX_ENTRIES) {
+ error_setg(errp, "ZFile index size %" PRIu64 " exceeds maximum "
+ "%lld", index_size, ZFILE_MAX_INDEX_ENTRIES);
+ return -EINVAL;
+ }
+ /*
+ * order the checks so each subtraction is guarded by the previous
+ * condition (no unsigned wraparound on adversarial values)
+ */
+ if (index_offset < ZFILE_HT_SPACE ||
+ index_offset > (uint64_t)zfile_end - end_reserve ||
+ index_size * 4 > (uint64_t)zfile_end - end_reserve - index_offset) {
+ error_setg(errp, "invalid ZFile jump table location");
+ return -EINVAL;
+ }
+ if ((index_size - 1) * block_size >= original_file_size ||
+ original_file_size > index_size * block_size) {
+ error_setg(errp, "ZFile block count does not match content size");
+ return -EINVAL;
+ }
+
+ zf->index_offset = index_offset;
+ zf->index_size = index_size;
+ zf->original_file_size = original_file_size;
+ zf->block_size = block_size;
+ zf->algo = algo;
+ zf->verify = verify;
+
+ table = qemu_try_blockalign(l->child->bs,
+ index_size * sizeof(uint32_t));
+ if (!table) {
+ return -ENOMEM;
+ }
+ ret = overlaybd_zfile_load_table(l, table, errp);
+ if (ret < 0) {
+ goto out;
+ }
+ /*
+ * like the reference implementation, the jump table CRC is only
+ * checked when the digest flag is set (it is garbage otherwise)
+ */
+ if ((flags & ZFILE_FLAG_DIGEST) && le32_to_cpu(ht.index_crc) !=
+ overlaybd_crc32c(0, table, index_size * sizeof(uint32_t))) {
+ error_setg(errp, "ZFile jump table CRC mismatch");
+ ret = -EIO;
+ goto out;
+ }
+
+ ret = overlaybd_zfile_build_table(zf, table,
+ ZFILE_HT_SPACE +
+ le32_to_cpu(ht.opt.dict_size), errp);
+ if (ret < 0) {
+ goto out;
+ }
+ if (overlaybd_zfile_block_off(zf, zf->index_size) > zf->index_offset) {
+ error_setg(errp, "ZFile data region overlaps the jump table");
+ ret = -EINVAL;
+ goto out;
+ }
+
+ l->view_size = zf->original_file_size;
+ ret = 0;
+out:
+ qemu_vfree(table);
+ return ret;
+}
+
+/*
+ * Forward-only cursor into a QEMUIOVector. Seeding it and committing each
+ * block's bytes are the same advance, so they share one. The blocks of a
+ * request are written contiguously in increasing order, so a full pass costs
+ * O(niov) rather than the O(niov * nblocks) of qemu_iovec_subvec_niov(),
+ * which rescans from iov[0] -- expensive for the one-iovec-per-guest-page
+ * qiov that virtio-blk normally hands us.
+ */
+typedef struct OverlaybdQiovCursor {
+ struct iovec *iov;
+ struct iovec *end;
+ uint8_t *cur;
+ size_t left;
+} OverlaybdQiovCursor;
+
+static void overlaybd_qiov_cursor_advance(OverlaybdQiovCursor *c, size_t n)
+{
+ while (c->cur && n >= c->left) {
+ n -= c->left;
+ if (++c->iov >= c->end) {
+ c->cur = NULL;
+ c->left = 0;
+ return;
+ }
+ c->cur = (uint8_t *)c->iov->iov_base;
+ c->left = c->iov->iov_len;
+ }
+ if (c->cur) {
+ c->cur += n;
+ c->left -= n;
+ }
+}
+
+/*
+ * Point @c at byte 0 of @qiov. @qiov is NULL on the buf path, which
+ * leaves the cursor exhausted, so every test of it fails closed.
+ */
+static void overlaybd_qiov_cursor_init(OverlaybdQiovCursor *c,
+ QEMUIOVector *qiov)
+{
+ c->iov = qiov ? qiov->iov : NULL;
+ c->end = qiov ? qiov->iov + qiov->niov : NULL;
+ c->cur = c->iov < c->end ? (uint8_t *)c->iov->iov_base : NULL;
+ c->left = c->cur ? c->iov->iov_len : 0;
+}
+
+/*
+ * All I/O goes through bdrv_pread() (a mixed wrapper), so this is
+ * callable from both GS and coroutine contexts.
+ */
+static int coroutine_mixed_fn GRAPH_RDLOCK
+overlaybd_zfile_read(OverlaybdLayer *l, uint64_t off, uint64_t bytes,
+ void *buf, QEMUIOVector *qiov, size_t qiov_off)
+{
+ OverlaybdZfile *zf = &l->zf;
+ uint32_t bsz = zf->block_size;
+ uint64_t first, last, base, need;
+ uint8_t *cbuf = NULL;
+ uint8_t *scratch = NULL;
+ OverlaybdQiovCursor c;
+ int ret;
+
+ assert(off + bytes <= zf->original_file_size);
+
+ /*
+ * also keeps "off + bytes - 1" below from wrapping when both are 0,
+ * which a caller reading an empty index can legitimately ask for
+ */
+ if (bytes == 0) {
+ return 0;
+ }
+
+ first = off / bsz;
+ last = (off + bytes - 1) / bsz;
+ /*
+ * One read covers the compressed bytes of every block the request spans,
+ * so the loop below never refills. A hostile jump table can still make
+ * @need many times larger than @bytes, hence qemu_try_blockalign() rather
+ * than the aborting qemu_blockalign(); aligning to the child's
+ * opt_mem_alignment lets an already-aligned request reach the protocol
+ * driver without being bounced.
+ */
+ base = overlaybd_zfile_block_off(zf, first);
+ need = overlaybd_zfile_block_off(zf, last + 1) - base;
+
+ /*
+ * One allocation for both: the compressed window, then the one-block
+ * decompression scratch behind it. bdrv_pread() writes only the first
+ * @need bytes so the two never overlap, and only the window goes to the
+ * block layer, so only its start needs the alignment.
+ */
+ cbuf = qemu_try_blockalign(l->child->bs, need + bsz);
+ if (!cbuf) {
+ return -ENOMEM;
+ }
+ scratch = cbuf + need;
+
+ ret = bdrv_pread(l->child, l->base_offset + base, need, cbuf, 0);
+ if (ret < 0) {
+ goto out;
+ }
+
+ overlaybd_qiov_cursor_init(&c, qiov);
+ overlaybd_qiov_cursor_advance(&c, qiov_off);
+
+ for (uint64_t bi = first; bi <= last; bi++) {
+ uint64_t bstart = bi * (uint64_t)bsz;
+ uint64_t expected = MIN((uint64_t)bsz,
+ zf->original_file_size - bstart);
+ uint64_t cp_begin = bstart > off ? 0 : off - bstart;
+ uint64_t cp_len = MIN(expected, off + bytes - bstart) - cp_begin;
+ uint64_t dst_off = bstart + cp_begin - off;
+ uint64_t off_blk = overlaybd_zfile_block_off(zf, bi);
+ uint64_t span = overlaybd_zfile_block_off(zf, bi + 1) - off_blk;
+ uint64_t clen = span - (zf->verify ? 4 : 0);
+ const uint8_t *cdata;
+ uint8_t *dst = NULL, *dec;
+
+ cdata = cbuf + (off_blk - base);
+
+ /*
+ * BlockReader::crc32_code(), zfile/zfile.cpp: the salted CRC trails
+ * the compressed data and covers exactly those bytes. Upstream
+ * retries three times before failing, which cannot help against a
+ * read-only child.
+ */
+ if (zf->verify) {
+ uint32_t want = ldl_le_p(cdata + clen);
+
+ if (want != overlaybd_crc32c(ZFILE_CRC_SALT, cdata, clen)) {
+ ret = -EIO;
+ goto out;
+ }
+ }
+
+ if (cp_begin == 0 && cp_len == expected) {
+ if (buf) {
+ dst = (uint8_t *)buf + dst_off;
+ } else if (c.cur && cp_len <= c.left) {
+ dst = c.cur;
+ }
+ }
+ dec = dst ? dst : scratch;
+
+ ret = -EIO;
+#ifdef CONFIG_LZ4
+ if (zf->algo == ZFILE_ALGO_LZ4) {
+ int r = LZ4_decompress_safe((const char *)cdata, (char *)dec,
+ clen, expected);
+
+ if (r >= 0 && (uint64_t)r == expected) {
+ ret = 0;
+ }
+ }
+#endif
+#ifdef CONFIG_ZSTD
+ if (zf->algo == ZFILE_ALGO_ZSTD) {
+ size_t r = ZSTD_decompress(dec, expected, cdata, clen);
+
+ if (!ZSTD_isError(r) && r == expected) {
+ ret = 0;
+ }
+ }
+#endif
+ if (ret < 0) {
+ goto out;
+ }
+ if (!dst) {
+ if (buf) {
+ memcpy((uint8_t *)buf + dst_off, scratch + cp_begin, cp_len);
+ } else {
+ qemu_iovec_from_buf(qiov, qiov_off + dst_off,
+ scratch + cp_begin, cp_len);
+ }
+ }
+
+ overlaybd_qiov_cursor_advance(&c, cp_len);
+ }
+
+ ret = 0;
+out:
+ qemu_vfree(cbuf);
+ return ret;
+}
+
+static int GRAPH_RDLOCK
+overlaybd_pread_view(OverlaybdLayer *l, uint64_t off, int64_t bytes, void *buf)
+{
+ if (l->is_zfile) {
+ return overlaybd_zfile_read(l, off, bytes, buf, NULL, 0);
+ }
+ return bdrv_pread(l->child, l->base_offset + off, bytes, buf, 0);
+}
+
+/*
+ * Load and validate the LSMT header/trailer/index of a layer. All
+ * metadata comes from the trailer; the header is only a format sniff
+ * (real images may have garbage header fields).
+ */
+static int GRAPH_RDLOCK
+overlaybd_lsmt_open(OverlaybdLayer *l, Error **errp)
+{
+ OverlaybdLSMTHeader ht;
+ OverlaybdSegment *index = NULL;
+ uint8_t *raw = NULL;
+ uint64_t index_offset, index_size, virtual_size, moffset_end;
+ uint64_t index_bound;
+ uint64_t prev_end = 0;
+ size_t count = 0;
+ int ret;
+
+ if (l->view_size < 2 * LSMT_HT_SPACE) {
+ error_setg(errp, "layer too small to be an LSMT image");
+ return -EINVAL;
+ }
+
+ ret = overlaybd_pread_view(l, 0, LSMT_HT_SPACE, &ht);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read LSMT header");
+ return ret;
+ }
+ if (!overlaybd_verify_lsmt_block(&ht, false)) {
+ error_setg(errp, "invalid LSMT header");
+ return -EINVAL;
+ }
+
+ /*
+ * The header is only a format sniff, so reading the trailer into the
+ * same block is safe. index_bound is where the index must end: the
+ * trailer start, which for a bare layer is not view_size - SPACE
+ * because bdrv_getlength() over-reports (tar padding, rounding).
+ */
+ if (l->is_zfile) {
+ /* in the ZFile virtual space the content size is exact */
+ ret = overlaybd_pread_view(l, l->view_size - LSMT_HT_SPACE,
+ LSMT_HT_SPACE, &ht);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read LSMT trailer");
+ return ret;
+ }
+ index_bound = l->view_size - LSMT_HT_SPACE;
+ } else {
+ int64_t trl_off = overlaybd_scan_trailer(l, LSMT_HT_SPACE, false,
+ &ht);
+
+ if (trl_off < 0) {
+ error_setg(errp, "invalid LSMT trailer (not a sealed data "
+ "layer?)");
+ return trl_off < -ENOENT ? trl_off : -EINVAL;
+ }
+ index_bound = (uint64_t)(trl_off - (int64_t)l->base_offset);
+ }
+ if (!overlaybd_verify_lsmt_block(&ht, true)) {
+ error_setg(errp, "invalid LSMT trailer (not a sealed data layer?)");
+ return -EINVAL;
+ }
+
+ index_offset = le64_to_cpu(ht.index_offset);
+ index_size = le64_to_cpu(ht.index_size);
+ virtual_size = le64_to_cpu(ht.virtual_size);
+
+ if (index_size > LSMT_MAX_RO_INDEX_ENTRIES) {
+ error_setg(errp, "LSMT index of %" PRIu64 " entries exceeds maximum "
+ "%" PRId64, index_size, LSMT_MAX_RO_INDEX_ENTRIES);
+ return -EINVAL;
+ }
+ if (index_offset < LSMT_HT_SPACE ||
+ index_offset > index_bound ||
+ index_size * 16 > index_bound - index_offset) {
+ error_setg(errp, "invalid LSMT index location");
+ return -EINVAL;
+ }
+
+ /*
+ * both sizes come from the image, so the allocating variants that
+ * abort on OOM are not acceptable here; out: frees either pointer
+ */
+ index = g_try_new(OverlaybdSegment, index_size);
+ raw = qemu_try_blockalign(l->child->bs, index_size * 16);
+ if (!index || !raw) {
+ ret = -ENOMEM;
+ goto out;
+ }
+ ret = overlaybd_pread_view(l, index_offset, index_size * 16, raw);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read LSMT index");
+ goto out;
+ }
+
+ moffset_end = index_offset / BDRV_SECTOR_SIZE;
+ for (uint64_t i = 0; i < index_size; i++) {
+ OverlaybdSegment seg, *out;
+
+ overlaybd_decode_entry(raw + i * 16, &seg);
+ if (seg.lba == LSMT_INVALID_OFFSET || seg.length == 0) {
+ continue;
+ }
+ if (count > 0 && seg.lba < prev_end) {
+ error_setg(errp, "LSMT index is disordered or overlapping");
+ ret = -EINVAL;
+ goto out;
+ }
+ if (seg.zeroed) {
+ if (seg.moffset < LSMT_MOFFSET_BEGIN ||
+ seg.moffset > moffset_end) {
+ error_setg(errp, "LSMT zeroed entry moffset out of range");
+ ret = -EINVAL;
+ goto out;
+ }
+ } else {
+ if (seg.moffset < LSMT_MOFFSET_BEGIN ||
+ seg.moffset >= moffset_end ||
+ seg.moffset + seg.length > moffset_end) {
+ error_setg(errp, "LSMT entry moffset out of range");
+ ret = -EINVAL;
+ goto out;
+ }
+ }
+ out = &index[count++];
+ *out = seg;
+ prev_end = seg.lba + seg.length;
+ }
+
+ l->index_offset = index_offset;
+ l->index = index;
+ index = NULL;
+ l->index_count = count;
+ l->virtual_size = virtual_size;
+ ret = 0;
+out:
+ qemu_vfree(raw);
+ g_free(index);
+ return ret;
+}
+
+static int GRAPH_RDLOCK
+overlaybd_detect_tar(OverlaybdLayer *l, int64_t child_size, Error **errp)
+{
+ uint8_t hdr[512];
+ uint64_t hoff = 0;
+ int ret;
+
+ l->base_offset = 0;
+ l->view_size = child_size;
+
+ if (child_size < 1024) {
+ return 0;
+ }
+ ret = bdrv_pread(l->child, 0, sizeof(hdr), hdr, 0);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read layer file header");
+ return ret;
+ }
+ if (memcmp(hdr + 257, "ustar", 5) != 0) {
+ return 0;
+ }
+ if (!overlaybd_is_tar_header(hdr)) {
+ error_setg(errp, "unsupported tar layer layout");
+ return -EINVAL;
+ }
+ if (hdr[156] == 'x') {
+ /*
+ * pax extended header: its size field gives the length of the
+ * attribute block that precedes the real ustar header
+ */
+ char size[13];
+ unsigned long long pax_size;
+
+ memcpy(size, hdr + 124, 12);
+ size[12] = 0;
+ if (qemu_strtou64(size, NULL, 8, &pax_size) < 0) {
+ pax_size = 0;
+ }
+ hoff = ZFILE_HT_SPACE +
+ DIV_ROUND_UP(pax_size, ZFILE_HT_SPACE) * ZFILE_HT_SPACE;
+ if (hoff + 2 * ZFILE_HT_SPACE > (uint64_t)child_size) {
+ error_setg(errp, "tar layer too small");
+ return -EINVAL;
+ }
+ ret = bdrv_pread(l->child, hoff, sizeof(hdr), hdr, 0);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read tar file header");
+ return ret;
+ }
+ if (memcmp(hdr + 257, "ustar", 5) != 0 ||
+ (hdr[156] != '0' && hdr[156] != '\0')) {
+ error_setg(errp, "unsupported tar layer layout");
+ return -EINVAL;
+ }
+ }
+
+ l->base_offset = hoff + ZFILE_HT_SPACE;
+ l->view_size = child_size - l->base_offset;
+ if (hdr[124] < 0x80) {
+ /*
+ * prefer the tar entry size: it is authoritative when the tar
+ * entry is padded
+ */
+ char size[13];
+ unsigned long long tar_size;
+
+ memcpy(size, hdr + 124, 12);
+ size[12] = 0;
+ if (!qemu_strtou64(size, NULL, 8, &tar_size) &&
+ tar_size > 0 && tar_size <= l->view_size) {
+ l->view_size = tar_size;
+ }
+ }
+ return 0;
+}
+
+static int GRAPH_RDLOCK
+overlaybd_open_layer(OverlaybdLayer *l, Error **errp)
+{
+ uint8_t buf[512];
+ int64_t child_size;
+ int ret;
+
+ child_size = bdrv_getlength(l->child->bs);
+ if (child_size < 0) {
+ error_setg_errno(errp, -child_size, "could not get layer file size");
+ return child_size;
+ }
+
+ ret = overlaybd_detect_tar(l, child_size, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ if (l->view_size < 2 * ZFILE_HT_SPACE) {
+ error_setg(errp, "layer file too small");
+ return -EINVAL;
+ }
+
+ ret = bdrv_pread(l->child, l->base_offset, sizeof(buf), buf, 0);
+ if (ret < 0) {
+ error_setg_errno(errp, -ret, "could not read layer file header");
+ return ret;
+ }
+ if (overlaybd_is_zfile_header(buf) &&
+ (ldq_le_p(buf + 32) & ZFILE_FLAG_HEADER)) {
+ l->is_zfile = true;
+ ret = overlaybd_zfile_open(l, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ }
+
+ return overlaybd_lsmt_open(l, errp);
+}
+
+/*
+ * First index whose entry covers or follows @sector: entries are sorted
+ * and non-overlapping, so entry ends are monotonically increasing.
+ * This matches the reference implementation's lower_bound(), which
+ * searches by entry end so that an entry covering @sector is found.
+ */
+static size_t overlaybd_find_segment(const OverlaybdSegment *a, size_t n,
+ uint64_t sector)
+{
+ size_t lo = 0, hi = n;
+
+ while (lo < hi) {
+ size_t mid = (lo + hi) / 2;
+
+ if (a[mid].lba + a[mid].length <= sector) {
+ lo = mid + 1;
+ } else {
+ hi = mid;
+ }
+ }
+ return lo;
+}
+
+/*
+ * Merge the per-layer indexes into s->merged: layers[0] is the topmost
+ * layer; a layer's mapping wins its whole extent, lower layers fill the
+ * holes. Entries pushed for [begin, end) are edge-trimmed to that range.
+ */
+static bool overlaybd_merge_level(BDRVOverlaybdState *s, int level,
+ uint64_t begin, uint64_t end, size_t *count)
+{
+ OverlaybdLayer *l;
+ size_t i, size0 = *count;
+ uint64_t begin0 = begin;
+
+ if (level >= s->nb_layers || begin >= end) {
+ return true;
+ }
+ l = &s->layers[level];
+ for (i = overlaybd_find_segment(l->index, l->index_count, begin);
+ i < l->index_count && l->index[i].lba < end; i++) {
+ OverlaybdSegment *e = &l->index[i];
+
+ if (e->lba > begin &&
+ !overlaybd_merge_level(s, level + 1, begin, e->lba, count)) {
+ return false;
+ }
+ if (*count == s->merged_cap) {
+ /*
+ * One input entry can be emitted several times when it is
+ * split by ranges covered (or zeroed) at upper layers, so the
+ * output can exceed the sum of the input indexes -- hence the
+ * cap, which upstream enforces at the same point. Grow into a
+ * temporary so that a failed realloc leaves s->merged valid
+ * for overlaybd_close() to free.
+ */
+ size_t cap = s->merged_cap ? s->merged_cap * 2 : 64;
+ OverlaybdSegment *grown;
+
+ if (cap > LSMT_MAX_MERGED_ENTRIES) {
+ return false;
+ }
+ grown = g_try_renew(OverlaybdSegment, s->merged, cap);
+ if (!grown) {
+ return false;
+ }
+ s->merged = grown;
+ s->merged_cap = cap;
+ }
+ s->merged[*count] = *e;
+ s->merged[*count].layer = level;
+ (*count)++;
+ begin = e->lba + e->length;
+ }
+ if (begin < end &&
+ !overlaybd_merge_level(s, level + 1, begin, end, count)) {
+ return false;
+ }
+ if (*count > size0) {
+ OverlaybdSegment *first = &s->merged[size0];
+ OverlaybdSegment *last = &s->merged[*count - 1];
+
+ if (first->lba < begin0) {
+ uint64_t delta = begin0 - first->lba;
+
+ first->length -= delta;
+ first->lba = begin0;
+ if (!first->zeroed) {
+ first->moffset += delta;
+ }
+ }
+ if (last->lba + last->length > end) {
+ last->length = end - last->lba;
+ }
+ }
+ return true;
+}
+
+static int coroutine_fn GRAPH_RDLOCK
+overlaybd_co_preadv(BlockDriverState *bs, int64_t offset, int64_t bytes,
+ QEMUIOVector *qiov, BdrvRequestFlags flags)
+{
+ BDRVOverlaybdState *s = bs->opaque;
+ uint64_t cur = offset >> BDRV_SECTOR_BITS;
+ uint64_t end = cur + (bytes >> BDRV_SECTOR_BITS);
+ size_t done = 0;
+ int ret = 0;
+
+ assert(QEMU_IS_ALIGNED(offset, BDRV_SECTOR_SIZE));
+ assert(QEMU_IS_ALIGNED(bytes, BDRV_SECTOR_SIZE));
+
+ while (cur < end) {
+ OverlaybdSegment *e;
+ OverlaybdLayer *l;
+ uint64_t run, run_end;
+ size_t idx = overlaybd_find_segment(s->merged, s->merged_count, cur);
+
+ if (idx == s->merged_count || s->merged[idx].lba >= end) {
+ qemu_iovec_memset(qiov, done, 0, (end - cur) * BDRV_SECTOR_SIZE);
+ break;
+ }
+ e = &s->merged[idx];
+ if (e->lba > cur) {
+ run = (e->lba - cur) * BDRV_SECTOR_SIZE;
+ qemu_iovec_memset(qiov, done, 0, run);
+ done += run;
+ cur = e->lba;
+ }
+ run_end = MIN(end, e->lba + e->length);
+ run = (run_end - cur) * BDRV_SECTOR_SIZE;
+ if (e->zeroed) {
+ qemu_iovec_memset(qiov, done, 0, run);
+ } else {
+ int64_t off = (e->moffset + (cur - e->lba)) * BDRV_SECTOR_SIZE;
+
+ l = &s->layers[e->layer];
+ if (l->is_zfile) {
+ ret = overlaybd_zfile_read(l, off, run, NULL, qiov, done);
+ } else {
+ ret = bdrv_co_preadv_part(l->child, l->base_offset + off, run,
+ qiov, done, 0);
+ }
+ if (ret < 0) {
+ return ret;
+ }
+ }
+ done += run;
+ cur = run_end;
+ }
+ return ret;
+}
+
+static void overlaybd_refresh_limits(BlockDriverState *bs, Error **errp)
+{
+ bs->bl.request_alignment = BDRV_SECTOR_SIZE;
+}
+
+static int overlaybd_probe(const uint8_t *buf, int buf_size,
+ const char *filename)
+{
+ if (buf_size < 24) {
+ return 0;
+ }
+ /*
+ * Only a bare LSMT or ZFile magic is distinctive enough to claim a file.
+ * A tar-wrapped layer shows just its entry header here, the payload
+ * starting past the 512-byte probe window, and tar is far too generic a
+ * container to claim on that evidence -- every unrelated archive would
+ * then fail to open instead of being read as raw. So a tar-wrapped layer
+ * must be named explicitly (-f overlaybd, file.driver=,
+ * layers.<n>.driver= or a manifest), all of which bypass probing.
+ */
+ if (overlaybd_is_lsmt_header(buf) || overlaybd_is_zfile_header(buf)) {
+ return 100;
+ }
+ return 0;
+}
+
+static void overlaybd_close(BlockDriverState *bs)
+{
+ BDRVOverlaybdState *s = bs->opaque;
+ int i;
+
+ bdrv_graph_wrlock_drained();
+ for (i = 0; i < s->nb_layers; i++) {
+ if (s->layers[i].child) {
+ bdrv_unref_child(bs, s->layers[i].child);
+ s->layers[i].child = NULL;
+ }
+ }
+ bdrv_graph_wrunlock();
+
+ for (i = 0; i < s->nb_layers; i++) {
+ g_free(s->layers[i].zf.partial_offset);
+ g_free(s->layers[i].zf.deltas);
+ g_free(s->layers[i].index);
+ }
+ g_free(s->layers);
+ s->layers = NULL;
+ s->nb_layers = 0;
+ g_free(s->merged);
+ s->merged = NULL;
+ s->merged_count = 0;
+}
+
+/*
+ * Manifest handling: the layer stack comes either from an OCI image manifest
+ * (manifest option, or the file child content) or from an explicit
+ * bottom-first "layers" array. Of a manifest only "schemaVersion" (must be 2)
+ * and "layers" (non-empty, bottom-first) are read, and of each layer
+ * descriptor only "digest"; everything else -- the top-level "mediaType",
+ * "annotations", "subject" and the whole "config" descriptor -- is ignored,
+ * so the image config blob is never fetched.
+ *
+ * Blobs are named after the root they live under: ROOT/<alg>/<hex> for an OCI
+ * image layout's blobs/ or an explicit blob-path, or ROOT/<hex> when ROOT is
+ * itself an <alg> directory, i.e. the manifest is a sibling of the layers it
+ * names (an OCI layout read from inside blobs/sha256/, or a containerd
+ * content store).
+ *
+ * Specifications:
+ * image manifest (schemaVersion, layers)
+ * https://github.com/opencontainers/image-spec/blob/main/manifest.md
+ * descriptor "digest" grammar, narrowed by overlaybd_parse_digest()
+ * https://github.com/opencontainers/image-spec/blob/main/descriptor.md
+ * the blobs/<alg>/<hex> directory layout
+ * https://github.com/opencontainers/image-spec/blob/main/image-layout.md
+ */
+
+typedef enum {
+ OBD_BLOB_DIR,
+ OBD_BLOB_SIBLING,
+} OverlaybdBlobKind;
+
+typedef struct OverlaybdBlobRoot {
+ char *path;
+ OverlaybdBlobKind kind;
+ GPtrArray *blobs;
+} OverlaybdBlobRoot;
+
+#define OCI_DIGEST_ALG_MAX 32
+#define OCI_DIGEST_HEX_MAX 128
+/* an OCI image manifest is a few kilobytes; anything larger is not one */
+#define OCI_MANIFEST_MAX_SIZE (1u << 20)
+
+static char *overlaybd_blob_path(const OverlaybdBlobRoot *root,
+ const char *alg, const char *hex)
+{
+ switch (root->kind) {
+ case OBD_BLOB_SIBLING:
+ return g_strdup_printf("%s/%s", root->path, hex);
+ case OBD_BLOB_DIR:
+ return g_strdup_printf("%s/%s/%s", root->path, alg, hex);
+ }
+ g_assert_not_reached();
+}
+
+/*
+ * Validate a digest and split it into algorithm and hex parts. Both are used
+ * verbatim as path components, so anything outside the OCI grammar -- in
+ * particular "." and "/" -- is rejected. The grammar also allows separators
+ * in the algorithm and uppercase hex; both are excluded on purpose, since
+ * every tool in practice emits a lowercase "sha256" and narrowing the set
+ * costs nothing.
+ */
+static int overlaybd_parse_digest(const char *digest, char **alg, char **hex,
+ Error **errp)
+{
+ static const char alg_chars[] = "abcdefghijklmnopqrstuvwxyz0123456789";
+ static const char hex_chars[] = "0123456789abcdef";
+ const char *colon = strchr(digest, ':');
+ size_t alen, hlen;
+
+ if (!colon || strchr(colon + 1, ':')) {
+ goto invalid;
+ }
+ alen = colon - digest;
+ hlen = strlen(colon + 1);
+ if (alen < 1 || alen > OCI_DIGEST_ALG_MAX ||
+ hlen < 1 || hlen > OCI_DIGEST_HEX_MAX ||
+ strspn(digest, alg_chars) != alen ||
+ strspn(colon + 1, hex_chars) != hlen) {
+ goto invalid;
+ }
+
+ *alg = g_strndup(digest, alen);
+ *hex = g_strdup(colon + 1);
+ return 0;
+
+invalid:
+ error_setg(errp, "invalid layer digest '%s'", digest);
+ return -EINVAL;
+}
+
+static int overlaybd_reject_url(const char *what, const char *ref,
+ Error **errp)
+{
+ if (path_has_protocol(ref)) {
+ error_setg(errp, "%s '%s' is a URL; only local files are supported",
+ what, ref);
+ return -ENOTSUP;
+ }
+ return 0;
+}
+
+/*
+ * Put an explicit file child reference under @key, so that the blob is
+ * opened without format probing. A bare string reference would instead be
+ * looked up as a node name.
+ */
+static void overlaybd_put_child(QDict *options, const char *key,
+ const char *value)
+{
+ /* two variables: reassigning a g_autofree one leaks the old value */
+ g_autofree char *drv_key = g_strdup_printf("%s.driver", key);
+ g_autofree char *ref = g_strdup_printf("%s.filename", key);
+
+ qdict_put_str(options, drv_key, "file");
+ qdict_put_str(options, ref, value);
+}
+
+static int overlaybd_blob_root_from_option(const char *blob_path,
+ OverlaybdBlobRoot *root,
+ Error **errp)
+{
+ char *end;
+ int ret;
+
+ ret = overlaybd_reject_url("blob-path", blob_path, errp);
+ if (ret < 0) {
+ return ret;
+ }
+
+ root->path = g_strdup(blob_path);
+ end = root->path + strlen(root->path);
+ while (end > root->path && end[-1] == '/') {
+ *--end = '\0';
+ }
+ if (!*root->path) {
+ error_setg(errp, "blob-path is empty");
+ g_free(root->path);
+ root->path = NULL;
+ return -EINVAL;
+ }
+ root->kind = OBD_BLOB_DIR;
+ return 0;
+}
+
+static int overlaybd_derive_blob_root(const char *manifest, const char *alg,
+ OverlaybdBlobRoot *root, Error **errp)
+{
+ g_autofree char *dir = NULL;
+ g_autofree char *base = NULL;
+ g_autofree char *alg_dir = NULL;
+
+ root->path = NULL;
+
+ dir = g_path_get_dirname(manifest);
+ base = g_path_get_basename(dir);
+ if (strcmp(base, alg) == 0) {
+ root->path = g_strdup(dir);
+ root->kind = OBD_BLOB_SIBLING;
+ return 0;
+ }
+
+ /*
+ * Otherwise the blobs are grouped by algorithm in a directory beside
+ * the manifest, either directly or under the blobs/ of an OCI image
+ * layout. The root is that directory's parent, since a directory root
+ * composes ROOT/<alg>/<hex>.
+ */
+ alg_dir = g_build_filename(dir, alg, NULL);
+ if (g_file_test(alg_dir, G_FILE_TEST_IS_DIR)) {
+ root->path = g_strdup(dir);
+ } else {
+ root->path = g_build_filename(dir, "blobs", NULL);
+ if (!g_file_test(root->path, G_FILE_TEST_IS_DIR)) {
+ error_setg(errp, "could not find the blobs of manifest '%s': no "
+ "%s/ or blobs/ directory beside it; give blob-path",
+ manifest, alg);
+ g_free(root->path);
+ root->path = NULL;
+ return -ENOENT;
+ }
+ }
+ root->kind = OBD_BLOB_DIR;
+ return 0;
+}
+
+static int overlaybd_parse_manifest(const char *content, QDict **manifest_out,
+ Error **errp)
+{
+ QDict *manifest;
+ QObject *obj;
+ int64_t version;
+
+ obj = qobject_from_json(content, errp);
+ if (!obj) {
+ return -EINVAL;
+ }
+ manifest = qobject_to(QDict, obj);
+ if (!manifest) {
+ error_setg(errp, "overlaybd manifest root is not a JSON object");
+ qobject_unref(obj);
+ return -EINVAL;
+ }
+
+ version = qdict_get_try_int(manifest, "schemaVersion", 0);
+ if (version != 2) {
+ error_setg(errp, "unsupported OCI schemaVersion %" PRId64 ", "
+ "expected 2", version);
+ qobject_unref(obj);
+ return -ENOTSUP;
+ }
+ if (!qobject_to(QList, qdict_get(manifest, "layers"))) {
+ error_setg(errp, "overlaybd manifest has no \"layers\" array");
+ qobject_unref(obj);
+ return -EINVAL;
+ }
+ *manifest_out = manifest;
+ return 0;
+}
+
+static int overlaybd_paths_from_manifest(QDict *manifest, const char *location,
+ OverlaybdBlobRoot *root, Error **errp)
+{
+ QList *layers = qobject_to(QList, qdict_get(manifest, "layers"));
+ const QListEntry *entry;
+ int i = 0, ret;
+
+ for (entry = qlist_first(layers); entry; entry = qlist_next(entry)) {
+ QDict *desc = qobject_to(QDict, entry->value);
+ const char *digest = desc ? qdict_get_try_str(desc, "digest") : NULL;
+ g_autofree char *alg = NULL;
+ g_autofree char *hex = NULL;
+
+ if (!digest) {
+ error_setg(errp, "layers[%d] has no digest", i);
+ return -EINVAL;
+ }
+ ret = overlaybd_parse_digest(digest, &alg, &hex, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ if (i == 0 && !root->path) {
+ ret = overlaybd_derive_blob_root(location, alg, root, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ }
+ g_ptr_array_add(root->blobs, overlaybd_blob_path(root, alg, hex));
+ i++;
+ }
+ if (i == 0) {
+ error_setg(errp, "overlaybd manifest has no layers");
+ return -EINVAL;
+ }
+ return 0;
+}
+
+static int overlaybd_layers_from_options(QDict *options, int nb_layers,
+ Error **errp)
+{
+ int i;
+
+ for (i = 0; i < nb_layers; i++) {
+ char key[32];
+ const char *val;
+ int n, ret;
+
+ n = snprintf(key, sizeof(key), "layers.%d", i);
+ assert(n < (int)sizeof(key));
+
+ val = qdict_get_try_str(options, key);
+ if (val) {
+ g_autofree char *path = g_strdup(val);
+
+ ret = overlaybd_reject_url("layer", path, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ qdict_del(options, key);
+ overlaybd_put_child(options, key, path);
+ }
+ }
+ return 0;
+}
+
+static int overlaybd_open_layers(BlockDriverState *bs, QDict *options,
+ const OverlaybdBlobRoot *root, int nb_layers,
+ BdrvChild *file_layer, Error **errp)
+{
+ BDRVOverlaybdState *s = bs->opaque;
+ int ret;
+ int i;
+
+ if (nb_layers > LSMT_MAX_LAYERS) {
+ error_setg(errp, "too many overlaybd layers (%d, maximum %d)",
+ nb_layers, LSMT_MAX_LAYERS);
+ return -EINVAL;
+ }
+
+ s->layers = g_new0(OverlaybdLayer, nb_layers);
+ s->nb_layers = nb_layers;
+
+ if (file_layer) {
+ s->layers[0].child = file_layer;
+ } else {
+ for (i = 0; i < nb_layers; i++) {
+ BdrvChild *child;
+ char key[32];
+ int n;
+
+ if (root) {
+ n = snprintf(key, sizeof(key), "layer.%d", i);
+ assert(n < (int)sizeof(key));
+ overlaybd_put_child(options, key, root->blobs->pdata[i]);
+ } else {
+ n = snprintf(key, sizeof(key), "layers.%d", i);
+ assert(n < (int)sizeof(key));
+ }
+
+ child = bdrv_open_child(NULL, options, key, bs, &child_of_bds,
+ BDRV_CHILD_DATA | BDRV_CHILD_METADATA,
+ false, errp);
+ if (!child) {
+ ret = -EINVAL;
+ goto fail;
+ }
+ /*
+ * fill top-first: the last path (bottom-first) is the top
+ * layer
+ */
+ s->layers[nb_layers - 1 - i].child = child;
+ }
+ }
+
+ bdrv_graph_rdlock_main_loop();
+ for (i = 0; i < nb_layers; i++) {
+ ret = overlaybd_open_layer(&s->layers[i], errp);
+ if (ret < 0) {
+ goto unlock_fail;
+ }
+ }
+
+ s->merged_cap = 64;
+ s->merged = g_new(OverlaybdSegment, s->merged_cap);
+ if (!overlaybd_merge_level(s, 0, 0, UINT64_MAX, &s->merged_count)) {
+ error_setg(errp, "failed to merge overlaybd layer indexes");
+ ret = -EINVAL;
+ goto unlock_fail;
+ }
+
+ s->virtual_size = 0;
+ for (i = 0; i < nb_layers; i++) {
+ if (s->layers[i].virtual_size != 0) {
+ s->virtual_size = s->layers[i].virtual_size;
+ break;
+ }
+ }
+ if (s->virtual_size == 0) {
+ error_setg(errp, "overlaybd image has zero virtual size");
+ ret = -EINVAL;
+ goto unlock_fail;
+ }
+ /* DIV_ROUND_UP() below would wrap around to a zero-length image */
+ if (s->virtual_size > UINT64_MAX - (BDRV_SECTOR_SIZE - 1)) {
+ error_setg(errp, "overlaybd image virtual size %" PRIu64 " is too "
+ "large", s->virtual_size);
+ ret = -EINVAL;
+ goto unlock_fail;
+ }
+
+ bs->total_sectors = DIV_ROUND_UP(s->virtual_size, BDRV_SECTOR_SIZE);
+ bdrv_graph_rdunlock_main_loop();
+ return 0;
+
+unlock_fail:
+ bdrv_graph_rdunlock_main_loop();
+fail:
+ return ret;
+}
+
+static int overlaybd_open(BlockDriverState *bs, QDict *options, int flags,
+ Error **errp)
+{
+ g_autofree char *manifest_opt = NULL;
+ g_autofree char *blob_path = NULL;
+ OverlaybdBlobRoot root = { 0 };
+ const OverlaybdBlobRoot *blobs = NULL;
+ QDict *manifest = NULL;
+ const char *location = NULL;
+ char *content = NULL;
+ BdrvChild *file_layer = NULL;
+ bool use_file_child;
+ int nb_layers = 0;
+ int ret;
+
+ GLOBAL_STATE_CODE();
+
+ bdrv_graph_rdlock_main_loop();
+ ret = bdrv_apply_auto_read_only(bs, NULL, errp);
+ bdrv_graph_rdunlock_main_loop();
+ if (ret < 0) {
+ return ret;
+ }
+
+ qdict_flatten(options);
+
+ /* copy before deleting: qdict_get_try_str() borrows from the entry */
+ manifest_opt = g_strdup(qdict_get_try_str(options, "manifest"));
+ blob_path = g_strdup(qdict_get_try_str(options, "blob-path"));
+ qdict_del(options, "manifest");
+ qdict_del(options, "blob-path");
+ use_file_child = qdict_haskey(options, "file");
+ nb_layers = qdict_array_entries(options, "layers.");
+ if (nb_layers < 0) {
+ error_setg(errp, "option layers is not a valid array");
+ return -EINVAL;
+ }
+ if ((manifest_opt != NULL) + use_file_child + (nb_layers > 0) > 1) {
+ error_setg(errp, "only one of manifest, file or layers may be given");
+ return -EINVAL;
+ }
+ if (!manifest_opt && !use_file_child && nb_layers == 0) {
+ error_setg(errp, "either manifest, file or layers is required");
+ return -EINVAL;
+ }
+ if (blob_path && !manifest_opt && !use_file_child) {
+ error_setg(errp, "blob-path requires a manifest");
+ return -EINVAL;
+ }
+
+ if (manifest_opt) {
+ gsize len;
+
+ ret = overlaybd_reject_url("manifest", manifest_opt, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ if (!g_file_get_contents(manifest_opt, &content, &len, NULL)) {
+ error_setg(errp, "could not read overlaybd manifest '%s'",
+ manifest_opt);
+ return -ENOENT;
+ }
+ location = manifest_opt;
+ } else if (use_file_child) {
+ uint8_t sniff[512];
+ const uint8_t *p, *end;
+ int64_t len;
+
+ ret = bdrv_open_file_child(NULL, options, "file", bs, errp);
+ if (ret < 0) {
+ return ret;
+ }
+ /*
+ * The file child is either an OCI image manifest or a single layer,
+ * possibly inside a tar and/or ZFile shell. No layer magic starts
+ * with '{', so a JSON document is a manifest and anything else is a
+ * layer; overlaybd_open_layer() peels the shells and requires an
+ * LSMT core.
+ */
+ bdrv_graph_rdlock_main_loop();
+ len = bdrv_getlength(bs->file->bs);
+ if (len < 0) {
+ bdrv_graph_rdunlock_main_loop();
+ error_setg_errno(errp, -len, "could not get the file child size");
+ ret = len;
+ goto out;
+ }
+ memset(sniff, 0, sizeof(sniff));
+ ret = bdrv_pread(bs->file, 0, MIN((uint64_t)len, sizeof(sniff)),
+ sniff, 0);
+ if (ret < 0) {
+ bdrv_graph_rdunlock_main_loop();
+ error_setg_errno(errp, -ret, "could not read the file child");
+ goto out;
+ }
+ location = bs->file->bs->filename;
+ end = sniff + MIN((uint64_t)len, sizeof(sniff));
+ for (p = sniff; p < end && g_ascii_isspace(*p); p++) {
+ }
+ if (p == end || *p != '{') {
+ file_layer = bs->file;
+ nb_layers = 1;
+ bdrv_graph_rdunlock_main_loop();
+ } else {
+ /*
+ * @len comes from the child rather than from overlaybd, so it
+ * cannot be handed to g_malloc() unchecked; a real manifest is
+ * a few kilobytes.
+ */
+ if (len > OCI_MANIFEST_MAX_SIZE) {
+ bdrv_graph_rdunlock_main_loop();
+ error_setg(errp, "file child starts like a JSON manifest but "
+ "is %" PRId64 " bytes, above the %u byte limit",
+ len, OCI_MANIFEST_MAX_SIZE);
+ ret = -EINVAL;
+ goto out;
+ }
+ content = g_malloc(len + 1);
+ ret = bdrv_pread(bs->file, 0, len, content, 0);
+ if (ret >= 0) {
+ content[len] = 0;
+ ret = 0;
+ } else {
+ error_setg_errno(errp, -ret,
+ "could not read overlaybd manifest");
+ }
+ bdrv_graph_rdunlock_main_loop();
+ if (ret < 0) {
+ goto out;
+ }
+ }
+ }
+
+ if (!file_layer) {
+ if (content) {
+ ret = overlaybd_parse_manifest(content, &manifest, errp);
+ if (ret < 0) {
+ goto out;
+ }
+ root.blobs = g_ptr_array_new_with_free_func(g_free);
+ if (blob_path) {
+ ret = overlaybd_blob_root_from_option(blob_path, &root, errp);
+ if (ret < 0) {
+ goto out;
+ }
+ }
+ ret = overlaybd_paths_from_manifest(manifest, location, &root,
+ errp);
+ if (ret < 0) {
+ goto out;
+ }
+ nb_layers = root.blobs->len;
+ blobs = &root;
+ } else {
+ ret = overlaybd_layers_from_options(options, nb_layers, errp);
+ if (ret < 0) {
+ goto out;
+ }
+ }
+ }
+
+ ret = overlaybd_open_layers(bs, options, blobs, nb_layers, file_layer,
+ errp);
+
+out:
+ g_free(root.path);
+ if (root.blobs) {
+ g_ptr_array_free(root.blobs, TRUE);
+ }
+ qobject_unref(manifest);
+ g_free(content);
+ if (ret < 0) {
+ overlaybd_close(bs);
+ }
+ return ret;
+}
+
+static BlockDriver bdrv_overlaybd = {
+ .format_name = "overlaybd",
+ .instance_size = sizeof(BDRVOverlaybdState),
+ .bdrv_probe = overlaybd_probe,
+ .bdrv_open = overlaybd_open,
+ .bdrv_child_perm = bdrv_default_perms,
+ .bdrv_refresh_limits = overlaybd_refresh_limits,
+ .bdrv_co_preadv = overlaybd_co_preadv,
+ .bdrv_close = overlaybd_close,
+ .is_format = true,
+};
+
+static void bdrv_overlaybd_init(void)
+{
+ bdrv_register(&bdrv_overlaybd);
+}
+
+block_init(bdrv_overlaybd_init);
diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc
index 675daa72f9..2569f42e52 100644
--- a/docs/system/qemu-block-drivers.rst.inc
+++ b/docs/system/qemu-block-drivers.rst.inc
@@ -391,6 +391,43 @@ More disk image file formats are supported in a read-only mode.
Apple disk image.
+.. program:: image-formats
+.. option:: overlaybd
+
+ Overlaybd image, the layered format used by containerd's overlaybd
+ snapshotter. Each layer holds over-written data blocks, optionally
+ compressed block-wise with LZ4 or ZSTD and optionally wrapped in a
+ single-file tar. Only sealed layers can be read; compressed layers
+ need QEMU built with lz4 / zstd support respectively. See
+ https://github.com/containerd/overlaybd for the format specification.
+
+ The layer stack is given by exactly one of:
+
+ - ``manifest=<path>``: an OCI image manifest whose ``layers`` array
+ (bottom-first, of each entry only ``digest`` is used) names the layer
+ blobs, plus an optional ``blob-path=<root>`` saying where they are.
+ The root defaults to the blobs beside the manifest, which covers an
+ OCI image layout and a containerd content store.
+
+ - ``layers.<n>.driver=file,layers.<n>.filename=<path>``: an explicit
+ bottom-first list, the first element the base layer and the last the
+ top layer.
+
+ - a ``file`` child holding a manifest or a single sealed layer, as
+ ``-drive file=<path>`` provides. A manifest must be named with
+ ``format=overlaybd``, since probing cannot recognise JSON.
+
+ A bare layer is detected by probing; a tar-wrapped one is not, as
+ probing sees only the tar entry header, so it must be named explicitly
+ via ``-f overlaybd``, a ``file`` child, ``layers.<n>`` or a manifest.
+ Tar-wrapped layers are usually shipped gzip-compressed and must be
+ unpacked first, since the driver reads an uncompressed tar.
+
+ For example::
+
+ qemu-img info --image-opts driver=overlaybd,manifest=manifest.json,\
+ blob-path=/var/lib/containerd/io.containerd.content.v1.content/blobs
+
.. program:: image-formats
.. option:: parallels
diff --git a/meson.build b/meson.build
index cfac634cf1..d7468db2a7 100644
--- a/meson.build
+++ b/meson.build
@@ -1391,6 +1391,12 @@ if not get_option('zstd').auto() or have_block
required: get_option('zstd'),
method: 'pkg-config')
endif
+lz4 = not_found
+if not get_option('lz4').auto() or have_block
+ lz4 = dependency('liblz4', version: '>=1.8.0',
+ required: get_option('lz4'),
+ method: 'pkg-config')
+endif
qpl = not_found
if not get_option('qpl').auto() or have_system
qpl = dependency('qpl', version: '>=1.5.0',
@@ -2542,6 +2548,7 @@ config_host_data.set('CONFIG_CRYPTO_SM3', crypto_sm3.found())
config_host_data.set('CONFIG_HOGWEED', hogweed.found())
config_host_data.set('CONFIG_MALLOC_TRIM', has_malloc_trim)
config_host_data.set('CONFIG_ZSTD', zstd.found())
+config_host_data.set('CONFIG_LZ4', lz4.found())
config_host_data.set('CONFIG_QPL', qpl.found())
config_host_data.set('CONFIG_UADK', uadk.found())
config_host_data.set('CONFIG_QATZIP', qatzip.found())
@@ -4856,6 +4863,7 @@ if have_block
summary_info += {'bochs support': get_option('bochs').allowed()}
summary_info += {'cloop support': get_option('cloop').allowed()}
summary_info += {'dmg support': get_option('dmg').allowed()}
+ summary_info += {'overlaybd support': get_option('overlaybd').allowed()}
summary_info += {'qcow v1 support': get_option('qcow1').allowed()}
summary_info += {'vdi support': get_option('vdi').allowed()}
summary_info += {'vhdx support': get_option('vhdx').allowed()}
@@ -4989,6 +4997,7 @@ summary_info += {'snappy support': snappy}
summary_info += {'bzip2 support': libbzip2}
summary_info += {'lzfse support': liblzfse}
summary_info += {'zstd support': zstd}
+summary_info += {'lz4 support': lz4}
summary_info += {'Query Processing Library support': qpl}
summary_info += {'UADK Library support': uadk}
summary_info += {'qatzip support': qatzip}
diff --git a/meson_options.txt b/meson_options.txt
index 6c2de6296f..a1b2ca6e56 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -270,6 +270,8 @@ option('xkbcommon', type : 'feature', value : 'auto',
description: 'xkbcommon support')
option('zstd', type : 'feature', value : 'auto',
description: 'zstd compression support')
+option('lz4', type : 'feature', value : 'auto',
+ description: 'lz4 compression support')
option('qpl', type : 'feature', value : 'auto',
description: 'Query Processing Library support')
option('uadk', type : 'feature', value : 'auto',
@@ -339,6 +341,8 @@ option('cloop', type: 'feature', value: 'auto',
description: 'cloop image format support')
option('dmg', type: 'feature', value: 'auto',
description: 'dmg image format support')
+option('overlaybd', type: 'feature', value: 'auto',
+ description: 'overlaybd image format support')
option('qcow1', type: 'feature', value: 'auto',
description: 'qcow1 image format support')
option('vdi', type: 'feature', value: 'auto',
diff --git a/qapi/block-core.json b/qapi/block-core.json
index aed2888147..18a3fe8a95 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -3390,6 +3390,7 @@
'iscsi',
'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme',
{ 'name': 'nvme-io_uring', 'if': 'CONFIG_BLKIO' },
+ 'overlaybd',
'parallels', 'preallocate', 'qcow', 'qcow2', 'qed', 'quorum',
'raw', 'rbd',
{ 'name': 'replication', 'if': 'CONFIG_REPLICATION' },
@@ -4182,6 +4183,43 @@
'data': { 'path': 'str' },
'if': 'CONFIG_BLKIO' }
+##
+# @BlockdevOptionsOverlaybd:
+#
+# Driver specific block device options for overlaybd (read-only).
+#
+# @manifest: an OCI image manifest naming the layer stack. Its
+# "layers" array is read bottom-first and only the "digest" of
+# each entry is used; the image config blob is never fetched.
+#
+# @blob-path: directory the layer digests are resolved against.
+# Optional, and derived from @manifest when absent. Blobs are
+# looked up as BLOB-PATH/<alg>/<hex>, i.e. the blobs/ of an OCI
+# image layout. A derived root is the blobs/ directory beside
+# the manifest, except when the manifest is itself a blob, as in
+# an OCI image layout addressed by digest or a containerd content
+# store, in which case the layers are its siblings,
+# BLOB-PATH/<hex>.
+#
+# @layers: explicit layer list, bottom-first: the first element is the
+# base layer, the last element is the top layer (the same order as
+# the "layers" array of an OCI image manifest)
+#
+# @file: the image to open, which may be either an OCI image manifest
+# or a bare sealed layer file, i.e. a single-layer image
+#
+# Exactly one of @manifest, @layers and @file must be given, and
+# @blob-path only with a manifest. Every reference is a local file;
+# a URL is rejected.
+#
+# Since: 11.2
+##
+{ 'struct': 'BlockdevOptionsOverlaybd',
+ 'data': { '*manifest': 'str',
+ '*blob-path': 'str',
+ '*layers': [ 'BlockdevRef' ],
+ '*file': 'BlockdevRef' } }
+
##
# @BlockdevOptionsVirtioBlkVfioPci:
#
@@ -4905,6 +4943,7 @@
'nvme': 'BlockdevOptionsNVMe',
'nvme-io_uring': { 'type': 'BlockdevOptionsNvmeIoUring',
'if': 'CONFIG_BLKIO' },
+ 'overlaybd': 'BlockdevOptionsOverlaybd',
'parallels': 'BlockdevOptionsGenericFormat',
'preallocate':'BlockdevOptionsPreallocate',
'qcow2': 'BlockdevOptionsQcow2',
diff --git a/scripts/meson-buildoptions.sh b/scripts/meson-buildoptions.sh
index 08c9fbb62c..a7bfcce254 100644
--- a/scripts/meson-buildoptions.sh
+++ b/scripts/meson-buildoptions.sh
@@ -153,6 +153,7 @@ meson_options_help() {
printf "%s\n" ' libvduse build VDUSE Library'
printf "%s\n" ' linux-aio Linux AIO support'
printf "%s\n" ' linux-io-uring Linux io_uring support'
+ printf "%s\n" ' lz4 lz4 compression support'
printf "%s\n" ' lzfse lzfse support for DMG images'
printf "%s\n" ' lzo lzo compression support'
printf "%s\n" ' malloc-trim enable libc malloc_trim() for memory optimization'
@@ -168,6 +169,7 @@ meson_options_help() {
printf "%s\n" ' nvmm NVMM acceleration support'
printf "%s\n" ' opengl OpenGL support'
printf "%s\n" ' oss OSS sound support'
+ printf "%s\n" ' overlaybd overlaybd image format support'
printf "%s\n" ' pa PulseAudio sound support'
printf "%s\n" ' parallels parallels image format support'
printf "%s\n" ' passt passt network backend support'
@@ -404,6 +406,8 @@ _meson_option_parse() {
--disable-linux-io-uring) printf "%s" -Dlinux_io_uring=disabled ;;
--localedir=*) quote_sh "-Dlocaledir=$2" ;;
--localstatedir=*) quote_sh "-Dlocalstatedir=$2" ;;
+ --enable-lz4) printf "%s" -Dlz4=enabled ;;
+ --disable-lz4) printf "%s" -Dlz4=disabled ;;
--enable-lzfse) printf "%s" -Dlzfse=enabled ;;
--disable-lzfse) printf "%s" -Dlzfse=disabled ;;
--enable-lzo) printf "%s" -Dlzo=enabled ;;
@@ -438,6 +442,8 @@ _meson_option_parse() {
--disable-opengl) printf "%s" -Dopengl=disabled ;;
--enable-oss) printf "%s" -Doss=enabled ;;
--disable-oss) printf "%s" -Doss=disabled ;;
+ --enable-overlaybd) printf "%s" -Doverlaybd=enabled ;;
+ --disable-overlaybd) printf "%s" -Doverlaybd=disabled ;;
--enable-pa) printf "%s" -Dpa=enabled ;;
--disable-pa) printf "%s" -Dpa=disabled ;;
--enable-parallels) printf "%s" -Dparallels=enabled ;;
diff --git a/tests/qemu-iotests/tests/overlaybd b/tests/qemu-iotests/tests/overlaybd
new file mode 100755
index 0000000000..7ce102426f
--- /dev/null
+++ b/tests/qemu-iotests/tests/overlaybd
@@ -0,0 +1,795 @@
+#!/usr/bin/env python3
+# group: rw quick
+#
+# Test the read-only overlaybd block driver
+#
+# Builds a 3-layer stack (plain sealed LSMT base, LZ4 zfile middle layer
+# with a zeroed range, ZSTD zfile top layer inside a tar wrapper with
+# dirty header fields) plus a standalone LZ4 zfile of 16-byte blocks
+# whose jump table exceeds 1 MiB, with pure-Python encoders -- LZ4
+# literal-only and match-based blocks and ZSTD Raw_Blocks are valid
+# without any compression library -- and verifies byte-exact reads
+# through all interface forms plus the error paths.
+#
+# Copyright (c) 2026 Huiba Li <huiba.lhb@alibaba-inc.com>
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import hashlib
+import json
+import os
+import shutil
+import struct
+
+import iotests
+from iotests import file_path, log, qemu_img
+
+BLOCK = 4096
+NBLOCKS = 256 # 1 MiB virtual image
+SECTORS_PER_BLOCK = BLOCK // 512
+
+LSMT_MAGIC0 = b'LSMT\x00\x01\x02\x00'
+LSMT_MAGIC1 = bytes([
+ 0x65, 0x7e, 0x63, 0xd2, 0x94, 0x44, 0x08, 0x4c,
+ 0xa2, 0xd2, 0xc8, 0xec, 0x4f, 0xcf, 0xae, 0x8a
+])
+ZFILE_MAGIC0 = b'ZFile\x00\x01\x00'
+ZFILE_MAGIC1 = b'tuji.yyf@Alibaba'
+
+
+def _crc32c_table() -> list:
+ table = []
+ for i in range(256):
+ c = i
+ for _ in range(8):
+ c = (0x82f63b78 ^ (c >> 1)) if (c & 1) else (c >> 1)
+ table.append(c)
+ return table
+
+
+CRC32C_TABLE = _crc32c_table()
+
+# zfile.cpp's NOI_WELL_KNOWN_PRIME: per-block CRCs are computed with this
+# seed rather than 0
+CRC32C_SALT = 100007
+
+
+def crc32c(data: bytes, crc: int = 0) -> int:
+ """Raw CRC-32C accumulation -- no init inversion and no final xor.
+
+ This is overlaybd's crc32::crc32c_extend(), which is NOT the standard
+ init-0xFFFFFFFF/xorout-0xFFFFFFFF CRC-32C. The two disagree on every
+ input, and a fixture that used the standard form would agree with a
+ driver that made the same mistake, so both would look correct while
+ rejecting every real image.
+ """
+ table = CRC32C_TABLE
+ for b in data:
+ crc = table[(crc ^ b) & 0xff] ^ (crc >> 8)
+ return crc
+
+
+def lz4_block_literals(data: bytes) -> bytes:
+ out = bytearray()
+ n = len(data)
+ if n < 15:
+ out.append(n << 4)
+ else:
+ out.append(15 << 4)
+ rest = n - 15
+ while rest >= 255:
+ out.append(255)
+ rest -= 255
+ out.append(rest)
+ out += data
+ return bytes(out)
+
+
+def lz4_block_zeros(n: int) -> bytes:
+ """LZ4 block decoding to @n zero bytes.
+
+ One literal, one offset-1 match, then the five trailing literals the
+ format requires; a block that ends in a match is rejected by
+ LZ4_decompress_safe, so this only works for n >= 12.
+ """
+ match = n - 6
+ assert match >= 4
+ out = bytearray()
+ ml = match - 4
+ nib = min(ml, 15)
+ out.append((1 << 4) | nib)
+ out.append(0)
+ out += struct.pack('<H', 1)
+ ml -= nib
+ if nib == 15:
+ while ml >= 255:
+ out.append(255)
+ ml -= 255
+ out.append(ml)
+ out.append(5 << 4)
+ out += bytes(5)
+ return bytes(out)
+
+
+def zstd_frame_raw(data: bytes) -> bytes:
+ out = bytearray(b'\x28\xb5\x2f\xfd\xe0')
+ out += struct.pack('<Q', len(data))
+ off = 0
+ while True:
+ chunk = data[off:off + 128 * 1024]
+ last = 1 if off + len(chunk) >= len(data) else 0
+ out += struct.pack('<I', (len(chunk) << 3) | last)[:3]
+ out += chunk
+ off += len(chunk)
+ if last:
+ break
+ return bytes(out)
+
+
+def fill_base(b: int) -> bytes:
+ return bytes((b * 7 + 13 + i) & 0xff for i in range(BLOCK))
+
+
+def fill_mid(b: int) -> bytes:
+ return bytes((b * 11 + 29 + i * 3) & 0xff for i in range(BLOCK))
+
+
+def fill_top(b: int) -> bytes:
+ return bytes((b * 5 + 101 + i * 7) & 0xff for i in range(BLOCK))
+
+
+def lsmt_header(flags: int, index_off: int, index_size: int,
+ virtual_size: int) -> bytes:
+ ht = bytearray(4096)
+ ht[0:8] = LSMT_MAGIC0
+ ht[8:24] = LSMT_MAGIC1
+ struct.pack_into('<I', ht, 24, 390)
+ struct.pack_into('<I', ht, 28, flags)
+ struct.pack_into('<Q', ht, 32, index_off)
+ struct.pack_into('<Q', ht, 40, index_size)
+ struct.pack_into('<Q', ht, 48, virtual_size)
+ return bytes(ht)
+
+
+def build_lsmt(spec: dict, pattern) -> bytes:
+ """spec maps 4K block index -> 1 (data) or 2 (zeroed); missing = hole."""
+ out = bytearray(4096)
+ data = bytearray()
+ slot_of = {}
+ for b in sorted(k for k, v in spec.items() if v == 1):
+ slot_of[b] = (4096 >> 9) + len(data) // BLOCK * SECTORS_PER_BLOCK
+ data += pattern(b)
+ index_off = 4096 + len(data)
+
+ index = bytearray()
+ keys = sorted(spec.keys())
+ i = 0
+ while i < len(keys):
+ j = i
+ while j + 1 < len(keys) and keys[j + 1] == keys[j] + 1 \
+ and spec[keys[j + 1]] == spec[keys[i]]:
+ j += 1
+ first, count = keys[i], keys[j] - keys[i] + 1
+ assert count * SECTORS_PER_BLOCK <= (1 << 14) - 1
+ lba = first * SECTORS_PER_BLOCK
+ length = count * SECTORS_PER_BLOCK
+ if spec[keys[i]] == 2:
+ moffset, zeroed = 8, 1
+ else:
+ moffset, zeroed = slot_of[first], 0
+ lo = lba | (length << 50)
+ hi = moffset | (zeroed << 55)
+ index += struct.pack('<QQ', lo, hi)
+ i = j + 1
+
+ out += data
+ out += index
+
+ for flags in (2 | 4, 1 | 2): # trailer first, then header
+ ht = lsmt_header(flags, index_off, len(index) // 16, NBLOCKS * BLOCK)
+ if flags & 1: # header goes over the placeholder
+ out[0:4096] = ht
+ else:
+ out += ht
+ return bytes(out)
+
+
+def wrap_zfile(content: bytes, algo: int, garbage: bool = False,
+ block: int = BLOCK, overwrite: bool = False,
+ bad_block_crc: bool = False) -> bytes:
+ """Wrap into a ZFile blob: algo 1 = LZ4, 2 = ZSTD. With garbage, the
+ digest flag is clear and the digest/crc fields carry junk, like real
+ baselayer files. With overwrite, the header carries the final metadata
+ and the trailer is left out -- upstream's HEADER_OVERWRITE shape, which
+ is what zfile_compress produces when it rewrites the header in place.
+
+ With bad_block_crc the first block's trailing CRC is wrong while its
+ compressed bytes stay valid, so only the driver's per-block checksum
+ can notice; corrupting the compressed stream instead would be caught
+ by the decompressor and would prove nothing about the checksum.
+
+ All-zero blocks use the compact match encoding: the reference jump
+ table stores in-group offsets as uint16, so the compressed blocks of
+ a group must together stay under 64 KiB, which literal-only encoding
+ cannot manage at a small block size."""
+ zero_chunk = bytes(block)
+ zero_c = lz4_block_zeros(block) if algo == 1 else None
+ body = bytearray()
+ jump = bytearray()
+ for off in range(0, len(content), block):
+ chunk = content[off:off + block]
+ if algo == 1:
+ if chunk == zero_chunk:
+ cdata = zero_c
+ else:
+ cdata = lz4_block_literals(chunk)
+ else:
+ cdata = zstd_frame_raw(chunk)
+ body += cdata
+ crc = crc32c(cdata, CRC32C_SALT)
+ if bad_block_crc and off == 0:
+ crc ^= 0xffffffff
+ body += struct.pack('<I', crc)
+ jump += struct.pack('<I', len(cdata) + 4)
+
+ out = bytearray()
+ index_off = 512 + len(body)
+ for is_header in (True, False):
+ if overwrite and not is_header:
+ break # the header already carries the final metadata
+ ht = bytearray(512)
+ ht[0:8] = ZFILE_MAGIC0
+ ht[8:24] = ZFILE_MAGIC1
+ struct.pack_into('<I', ht, 24, 96)
+ flags = (1 if is_header else 0) | 2 | 4 | (1 << 4)
+ if overwrite:
+ flags |= 1 << 3
+ struct.pack_into('<Q', ht, 32, flags)
+ struct.pack_into('<Q', ht, 40, index_off)
+ struct.pack_into('<Q', ht, 48, len(content) // block
+ + (1 if len(content) % block else 0))
+ struct.pack_into('<Q', ht, 56, len(content))
+ struct.pack_into('<I', ht, 64, crc32c(bytes(jump)))
+ struct.pack_into('<I', ht, 72, block)
+ ht[76] = algo
+ ht[88] = 1
+ if garbage:
+ struct.pack_into('<Q', ht, 32,
+ (1 if is_header else 0) | 2 | 4)
+ struct.pack_into('<I', ht, 28,
+ 0xfeedface if is_header else 0xdeadbeef)
+ struct.pack_into('<I', ht, 64, 0xdeadbeef)
+ ht[300:304] = b'\x01\x02\x03\x04'
+ else:
+ struct.pack_into('<I', ht, 28, crc32c(bytes(ht)))
+ out += ht
+ if is_header:
+ out += body
+ out += jump
+ return bytes(out)
+
+
+# tar's default blocking factor: 20 x 512-byte records
+TAR_BLOCKING = 10240
+
+
+def wrap_tar(content: bytes) -> bytes:
+ """Tar wrapper with the padding a real archiver writes, so that the
+ archive ends well past the layer and the driver has to locate the
+ layer trailer from the entry size rather than from the file size."""
+ hdr = bytearray(512)
+ hdr[0:9] = b'layer.bin'
+ hdr[156] = ord('0')
+ # slice assignment lengths must match exactly, or the bytearray
+ # silently shrinks: 11 octal digits into the 12-byte size field
+ # (the 12th byte stays NUL), 6 digits into the 8-byte checksum
+ hdr[124:135] = b'%011o' % len(content)
+ hdr[257:263] = b'ustar\x00'
+ hdr[263:265] = b'00'
+ hdr[148:156] = b' ' * 8
+ hdr[148:154] = b'%06o' % (sum(hdr) & 0o777777)
+ out = bytes(hdr) + content
+ out += bytes(-len(out) % 512)
+ out += bytes(1024)
+ out += bytes(-len(out) % TAR_BLOCKING)
+ return out
+
+
+# A ZFile of 16-byte blocks needs a jump table above 1 MiB (the point
+# where the driver switches to parallel loading) once the content passes
+# 4 MiB. 16 is the smallest block size whose all-zero LZ4 block still
+# fits the uint16 in-group deltas, so the data region is that big.
+BIG_BLOCK = 16
+BIG_DATA = 4259840
+BIG_VIRT_SECTORS = 24
+
+
+def fill_big(tag: int) -> bytes:
+ return bytes((tag * 31 + i * 5 + 7) & 0xff for i in range(4096))
+
+
+def build_big_lsmt() -> tuple:
+ """LSMT blob with two mapped 4K blocks, at the start and at the far
+ end of an otherwise zero data region, plus the expected image.
+
+ The two blocks are 4 MiB apart, so reading them back exercises jump
+ table lookups in two different groups.
+ """
+ index_off = 4096 + BIG_DATA
+ far_moff = (index_off - 4096) // 512
+ index = struct.pack('<QQ', 8 << 50, 8)
+ index += struct.pack('<QQ', 8 | (8 << 50), far_moff)
+
+ blob = bytearray(4096)
+ blob += fill_big(1)
+ blob += bytes(BIG_DATA - 2 * 4096)
+ blob += fill_big(2)
+ blob += index
+ assert len(blob) == index_off + len(index)
+
+ for flags in (2 | 4, 1 | 2):
+ ht = lsmt_header(flags, index_off, len(index) // 16,
+ BIG_VIRT_SECTORS * 512)
+ if flags & 1:
+ blob[0:4096] = ht
+ else:
+ blob += ht
+
+ expected = fill_big(1) + fill_big(2) + bytes(4096)
+ return bytes(blob), expected
+
+
+def corrupt_jump_table(src: str, dst: str, span: int) -> None:
+ """Copy a ZFile with every jump table entry rewritten to @span, fixing
+ up the index CRC and both header/trailer digests so that only the
+ entry values differ."""
+ with open(src, 'rb') as f:
+ img = bytearray(f.read())
+
+ index_off = struct.unpack_from('<Q', img, 40)[0]
+ index_size = struct.unpack_from('<Q', img, 48)[0]
+ for i in range(index_size):
+ struct.pack_into('<I', img, index_off + i * 4, span)
+
+ crc = crc32c(bytes(img[index_off:index_off + index_size * 4]))
+ for ht_off in (0, len(img) - 512):
+ ht = img[ht_off:ht_off + 512]
+ struct.pack_into('<I', ht, 28, 0)
+ struct.pack_into('<I', ht, 64, crc)
+ struct.pack_into('<I', ht, 28, crc32c(bytes(ht)))
+ img[ht_off:ht_off + 512] = ht
+
+ with open(dst, 'wb') as f:
+ f.write(img)
+
+
+mid_img = file_path('mid_lz4.zfile')
+top_img = file_path('top_zstd.tar')
+top_plain_img = file_path('top_plain.lsmt')
+oci_dir = file_path('oci.d')
+oci_blobs = os.path.join(oci_dir, 'blobs')
+oci_exported = os.path.join(oci_dir, 'manifest.json')
+alg_dir = file_path('algdir.d')
+alg_manifest = os.path.join(alg_dir, 'manifest.json')
+probe_img = file_path('probe.zfile')
+converted = file_path('converted.raw')
+garbage_img = file_path('garbage.bin')
+garbage_zfile = file_path('garbage.zfile')
+big_img = file_path('big_index.zfile')
+small_img = file_path('small_lz4.zfile')
+overwrite_img = file_path('overwrite_lz4.zfile')
+huge_img = file_path('huge_vsize.lsmt')
+overrun_img = file_path('overrun_index.lsmt')
+corrupt_img = file_path('corrupt_index.zfile')
+badcrc_img = file_path('bad_block_crc.zfile')
+junk_tar = file_path('junk.tar')
+badver_json = file_path('bad_schema_version.json')
+nolayers_json = file_path('no_layers.json')
+traverse_json = file_path('digest_traversal.json')
+missing_json = file_path('missing_blob.json')
+
+TOP_BLOCKS = {b: 1 for b in list(range(0, 51)) + list(range(150, 201))}
+MID_BLOCKS = {b: 1 for b in range(60, 161)}
+MID_BLOCKS.update({b: 2 for b in range(210, 221)})
+
+
+def expected_block(b: int) -> bytes:
+ if b in TOP_BLOCKS:
+ return fill_top(b)
+ if b in MID_BLOCKS:
+ return fill_mid(b) if MID_BLOCKS[b] == 1 else bytes(BLOCK)
+ return fill_base(b)
+
+
+def expected_image() -> bytes:
+ return b''.join(expected_block(b) for b in range(NBLOCKS))
+
+
+def top_only_image() -> bytes:
+ return b''.join(fill_top(b) if b in TOP_BLOCKS else bytes(BLOCK)
+ for b in range(NBLOCKS))
+
+
+OCI_MANIFEST_MEDIA_TYPE = 'application/vnd.oci.image.manifest.v1+json'
+OCI_LAYER_MEDIA_TYPE = 'application/vnd.oci.image.layer.v1.tar'
+OCI_EMPTY_MEDIA_TYPE = 'application/vnd.oci.empty.v1+json'
+
+
+def write_blob(data: bytes) -> str:
+ digest = 'sha256:' + hashlib.sha256(data).hexdigest()
+ alg, hexsum = digest.split(':', 1)
+ d = os.path.join(oci_blobs, alg)
+ os.makedirs(d, exist_ok=True)
+ with open(os.path.join(d, hexsum), 'wb') as f:
+ f.write(data)
+ return digest
+
+
+def digest_path(digest: str) -> str:
+ alg, hexsum = digest.split(':', 1)
+ return os.path.join(oci_blobs, alg, hexsum)
+
+
+def build_oci_manifest(layers: list) -> tuple:
+ """Write @layers (bottom-first) as blobs plus a manifest listing them.
+ Returns the manifest blob's path and the layer blob paths.
+
+ The image config blob is written as well, since the driver has to
+ ignore it, but index.json is left out: the tests name the manifest
+ directly instead of resolving it through the index."""
+ cfg = b'{}'
+ digests = [write_blob(data) for data in layers]
+ manifest = json.dumps({
+ 'schemaVersion': 2,
+ 'mediaType': OCI_MANIFEST_MEDIA_TYPE,
+ 'config': {'mediaType': OCI_EMPTY_MEDIA_TYPE,
+ 'digest': write_blob(cfg), 'size': len(cfg)},
+ 'layers': [{'mediaType': OCI_LAYER_MEDIA_TYPE,
+ 'digest': d, 'size': len(data)}
+ for d, data in zip(digests, layers)],
+ 'annotations': {'org.opencontainers.image.ref.name': 'latest'},
+ }).encode()
+ return digest_path(write_blob(manifest)), [digest_path(d) for d in digests]
+
+
+def mutated_manifest(src: str, dst: str, mutate) -> str:
+ with open(src) as f:
+ m = json.load(f)
+ mutate(m)
+ with open(dst, 'w') as f:
+ json.dump(m, f)
+ return dst
+
+
+def huge_virtual_size(src: str, dst: str) -> None:
+ """Copy an LSMT with virtual_size set to the value that makes the
+ driver's sectors conversion wrap around to a zero-length image. An
+ LSMT header carries no digest, so both copies can be patched raw."""
+ with open(src, 'rb') as f:
+ img = bytearray(f.read())
+ for off in (48, len(img) - 4096 + 48):
+ struct.pack_into('<Q', img, off, (1 << 64) - 1)
+ with open(dst, 'wb') as f:
+ f.write(img)
+
+
+def overrun_lsmt_index(src: str, dst: str, pad: int = 256) -> None:
+ """Copy a bare LSMT with @pad bytes of trailing junk after its trailer,
+ whose trailer then declares index entries reaching into that junk.
+
+ The padding is what makes the case reachable: the driver's view of the
+ layer ends at the child's length, so a bound taken at view_size - 4096
+ accepts the overrun, while the trailer position the backward scan
+ actually found is @pad bytes earlier. @pad must stay under 512 or the
+ scan window no longer reaches the trailer. An LSMT header carries no
+ digest, so the copy can be patched raw."""
+ assert pad < 512 and pad % 16 == 0
+ with open(src, 'rb') as f:
+ img = bytearray(f.read())
+ for off in (40, len(img) - 4096 + 40):
+ n = struct.unpack_from('<Q', img, off)[0]
+ struct.pack_into('<Q', img, off, n + pad // 16)
+ img += bytes(pad)
+ with open(dst, 'wb') as f:
+ f.write(img)
+
+
+def make_fixtures() -> tuple:
+ base = build_lsmt({b: 1 for b in range(NBLOCKS)}, fill_base)
+ mid = wrap_zfile(build_lsmt(MID_BLOCKS, fill_mid), algo=1)
+ top = wrap_tar(wrap_zfile(build_lsmt(TOP_BLOCKS, fill_top),
+ algo=2, garbage=True))
+
+ with open(mid_img, 'wb') as f:
+ f.write(mid)
+ with open(top_img, 'wb') as f:
+ f.write(top)
+ with open(top_plain_img, 'wb') as f:
+ f.write(build_lsmt(TOP_BLOCKS, fill_top))
+ with open(garbage_img, 'wb') as f:
+ f.write(os.urandom(32 * 1024))
+ with open(garbage_zfile, 'wb') as f:
+ f.write(wrap_zfile(os.urandom(64 * 1024), algo=1))
+ with open(junk_tar, 'wb') as f:
+ f.write(wrap_tar(os.urandom(64 * 1024)))
+ with open(small_img, 'wb') as f:
+ f.write(wrap_zfile(build_lsmt({0: 1}, fill_base), algo=1))
+ with open(overwrite_img, 'wb') as f:
+ f.write(wrap_zfile(build_lsmt(TOP_BLOCKS, fill_top), algo=1,
+ overwrite=True))
+ huge_virtual_size(top_plain_img, huge_img)
+ overrun_lsmt_index(top_plain_img, overrun_img)
+
+ os.mkdir(oci_dir)
+ manifest, blobs = build_oci_manifest([base, mid, top])
+ shutil.copyfile(manifest, oci_exported)
+
+ os.mkdir(alg_dir)
+ os.mkdir(os.path.join(alg_dir, 'sha256'))
+ for blob in blobs:
+ shutil.copyfile(blob, os.path.join(alg_dir, 'sha256',
+ os.path.basename(blob)))
+ shutil.copyfile(manifest, alg_manifest)
+
+ big_blob, big_expected = build_big_lsmt()
+ with open(big_img, 'wb') as f:
+ f.write(wrap_zfile(big_blob, algo=1, block=BIG_BLOCK))
+ return big_expected, manifest, blobs
+
+
+def codec_supported(algo: int) -> bool:
+ """
+ True unless the driver says this codec was not compiled in.
+
+ Keyed on the driver's own message, not on the exit status: a probe
+ that only checked the status would also report "not compiled in"
+ when the read path is merely broken, turning a real failure into a
+ silent not-run.
+ """
+ name = {1: 'lz4', 2: 'zstd'}[algo]
+ with open(probe_img, 'wb') as f:
+ f.write(wrap_zfile(build_lsmt({0: 1}, fill_base), algo=algo))
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,layers.0.driver=file,'
+ f'layers.0.filename={probe_img}', check=False)
+ return f'without {name} support' not in res.stdout
+
+
+def convert(opts: str, out: str):
+ return qemu_img('convert', '--image-opts', '-O', 'raw', opts, out,
+ check=False)
+
+
+for algo in (1, 2):
+ if not codec_supported(algo):
+ iotests.notrun(f'zfile algo {algo} not compiled in')
+
+
+def read_converted(path: str) -> bytes:
+ with open(path, 'rb') as f:
+ return f.read()
+
+
+def probed_format(path: str) -> str:
+ res = qemu_img('info', path, check=False)
+ for line in res.stdout.splitlines():
+ if line.startswith('file format:'):
+ return line.split(':', 1)[1].strip()
+ return ''
+
+
+def expect(cond: bool, msg: str) -> None:
+ if not cond:
+ raise AssertionError(msg)
+
+
+def test_overlaybd() -> None:
+ big_expected, manifest, blobs = make_fixtures()
+ # the manifest is itself a blob in blobs/sha256/, so the blob root is
+ # derived from its own path -- the OCI image layout and containerd
+ # content store shapes
+ cfg = f'driver=overlaybd,manifest={manifest}'
+
+ res = qemu_img('info', '--image-opts', cfg)
+ expect('virtual size: 1 MiB' in res.stdout, 'unexpected info output')
+
+ ret = convert(cfg, converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == expected_image(),
+ 'manifest mode: content mismatch')
+ log('manifest mode: byte-exact')
+
+ for name, opts in (
+ ('explicit blob-path',
+ f'driver=overlaybd,manifest={manifest},blob-path={oci_blobs}'),
+ ('exported manifest',
+ f'driver=overlaybd,manifest={oci_exported},'
+ f'blob-path={oci_blobs}'),
+ ('exported manifest, derived blob-path',
+ f'driver=overlaybd,manifest={oci_exported}'),
+ ('manifest beside an <alg> directory',
+ f'driver=overlaybd,manifest={alg_manifest}')):
+ ret = convert(opts, converted)
+ expect(ret.returncode == 0, ret.stderr or f'{name}: convert failed')
+ expect(read_converted(converted) == expected_image(),
+ f'{name}: content mismatch')
+ log('blob-path forms: byte-exact')
+
+ layers = (f'driver=overlaybd,'
+ f'layers.0.driver=file,layers.0.filename={blobs[0]},'
+ f'layers.1.driver=file,layers.1.filename={blobs[1]},'
+ f'layers.2.driver=file,layers.2.filename={blobs[2]}')
+ ret = convert(layers, converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == expected_image(),
+ 'layers mode: content mismatch')
+ log('layers mode: byte-exact')
+
+ single = f'driver=overlaybd,layers.0.driver=file,' \
+ f'layers.0.filename={top_plain_img}'
+ ret = convert(single, converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == top_only_image(),
+ 'single layer: content mismatch')
+ log('single plain layer: byte-exact')
+
+ single = f'driver=overlaybd,layers.0.driver=file,' \
+ f'layers.0.filename={overwrite_img}'
+ ret = convert(single, converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == top_only_image(),
+ 'overwrite header: content mismatch')
+ log('header-overwrite zfile: byte-exact')
+
+ # the file child given as a dict reference carries the manifest
+ # (a bare string "file" would be a node-name reference, which is
+ # why -drive file=... passes the filename as a parameter); the blob
+ # root has to be derived from the child's own filename
+ ret = convert(f'driver=overlaybd,file.driver=file,'
+ f'file.filename={manifest}', converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == expected_image(),
+ 'file-manifest mode: content mismatch')
+ log('file child as manifest: byte-exact')
+
+ ret = convert(f'driver=overlaybd,file.driver=file,'
+ f'file.filename={top_img}', converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == top_only_image(),
+ 'file layer mode: content mismatch')
+ log('file child as tar layer: byte-exact')
+
+ # probing sees only the first 512 bytes: a bare LSMT and a bare ZFile
+ # match on their magic, but a tar shell shows nothing there except a
+ # generic entry header, so tars are deliberately not claimed -- every
+ # unrelated tar would then fail to open, and probing has no fallback
+ expect(probed_format(top_plain_img) == 'overlaybd', 'LSMT not probed')
+ expect(probed_format(mid_img) == 'overlaybd', 'ZFile not probed')
+ expect(probed_format(top_img) == 'raw', 'tar layer claimed by probing')
+ expect(probed_format(garbage_img) == 'raw', 'garbage not probed as raw')
+ log('format probing verified')
+
+ big = f'driver=overlaybd,layers.0.driver=file,' \
+ f'layers.0.filename={big_img}'
+ res = qemu_img('info', '--image-opts', big)
+ expect('virtual size: 12 KiB' in res.stdout, 'unexpected info output')
+ ret = convert(big, converted)
+ expect(ret.returncode == 0, ret.stderr or 'convert failed')
+ expect(read_converted(converted) == big_expected,
+ 'big jump table: content mismatch')
+ log('1 MiB jump table: byte-exact')
+
+ # error paths (qemu_img() merges stdout and stderr)
+ res = qemu_img('info', '--image-opts', 'driver=overlaybd', check=False)
+ expect('either manifest, file or layers is required' in res.stdout,
+ 'missing options: wrong error')
+ res = qemu_img('info', '--image-opts',
+ 'driver=overlaybd,manifest=/nonexistent.json', check=False)
+ expect('could not read overlaybd manifest' in res.stdout,
+ 'missing manifest: wrong error')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,manifest={manifest},'
+ f'layers.0.driver=file,'
+ f'layers.0.filename={mid_img}', check=False)
+ expect('only one of manifest, file or layers may be given' in res.stdout,
+ 'conflicting options: wrong error')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,blob-path={oci_blobs},'
+ f'layers.0.driver=file,'
+ f'layers.0.filename={mid_img}', check=False)
+ expect('blob-path requires a manifest' in res.stdout,
+ 'blob-path without manifest: wrong error')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,manifest={manifest},blob-path=/',
+ check=False)
+ expect('blob-path is empty' in res.stdout,
+ 'empty blob-path: wrong error')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,layers.0.driver=file,'
+ f'layers.0.filename={garbage_img}', check=False)
+ expect('invalid LSMT header' in res.stdout,
+ 'garbage layer: wrong error')
+ res = qemu_img('info', '-f', 'overlaybd', junk_tar, check=False)
+ expect('invalid LSMT header' in res.stdout,
+ 'tar of garbage: wrong error')
+ # probing cannot see past a shell: it claims this on the ZFile magic,
+ # so the payload is only verified once the ZFile is open
+ res = qemu_img('info', garbage_zfile, check=False)
+ expect('invalid LSMT header' in res.stdout,
+ 'ZFile of garbage: wrong error')
+
+ mutated_manifest(manifest, badver_json,
+ lambda m: m.update(schemaVersion=1))
+ mutated_manifest(manifest, nolayers_json, lambda m: m.pop('layers'))
+ mutated_manifest(manifest, traverse_json,
+ lambda m: m['layers'][0].update(
+ digest='sha256:../../../../../../../etc/passwd'))
+ mutated_manifest(manifest, missing_json,
+ lambda m: m['layers'][0].update(
+ digest='sha256:' + '0' * 64))
+ for name, path, want in (
+ ('schemaVersion', badver_json, 'unsupported OCI schemaVersion'),
+ ('no layers', nolayers_json, 'has no "layers" array'),
+ ('digest traversal', traverse_json, 'invalid layer digest')):
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,manifest={path},'
+ f'blob-path={oci_blobs}', check=False)
+ expect(want in res.stdout, f'{name}: wrong error: {res.stdout}')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,manifest={missing_json},'
+ f'blob-path={oci_blobs}', check=False)
+ expect(f'{oci_blobs}/sha256/' + '0' * 64 in res.stdout,
+ f'missing blob: wrong error: {res.stdout}')
+
+ for name, opts in (
+ ('manifest URL',
+ 'driver=overlaybd,manifest=http://127.0.0.1:1/manifest.json'),
+ ('blob-path URL',
+ f'driver=overlaybd,manifest={manifest},'
+ 'blob-path=http://127.0.0.1:1/blobs'),
+ ('layer URL',
+ 'driver=overlaybd,layers.0=http://127.0.0.1:1/blobs/sha256/0')):
+ res = qemu_img('info', '--image-opts', opts, check=False)
+ expect('only local files are supported' in res.stdout,
+ f'{name}: wrong error: {res.stdout[-200:]}')
+
+ # 30000-byte blocks: the running in-group offset no longer fits u16
+ corrupt_jump_table(small_img, corrupt_img, 30000)
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,layers.0.driver=file,'
+ f'layers.0.filename={corrupt_img}', check=False)
+ expect('jump table group exceed' in res.stdout,
+ 'oversized jump table group: wrong error')
+ # A valid compressed block whose trailing CRC is wrong. Opening the LSMT
+ # layer reads its header, which is ZFile block 0, so only the driver's
+ # per-block checksum can turn this into an error; without it the block
+ # decodes fine and the corruption is never noticed.
+ with open(badcrc_img, 'wb') as f:
+ f.write(wrap_zfile(build_lsmt({0: 1}, fill_base), algo=1,
+ bad_block_crc=True))
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,layers.0.driver=file,'
+ f'layers.0.filename={badcrc_img}', check=False)
+ expect(res.returncode != 0 and 'Input/output error' in res.stdout,
+ f'corrupt block CRC: rc={res.returncode} {res.stdout[-200:]}')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,layers.0.driver=file,'
+ f'layers.0.filename={huge_img}', check=False)
+ expect('virtual size 18446744073709551615 is too large' in res.stdout,
+ f'huge virtual size: wrong error: {res.stdout}')
+ res = qemu_img('info', '--image-opts',
+ f'driver=overlaybd,layers.0.driver=file,'
+ f'layers.0.filename={overrun_img}', check=False)
+ expect('invalid LSMT index location' in res.stdout,
+ f'overrunning LSMT index: wrong error: {res.stdout[-200:]}')
+ log('error paths verified')
+
+ # file_path() only removes plain files, so the layout directories go
+ # explicitly (as tests/vvfat does)
+ shutil.rmtree(oci_dir)
+ shutil.rmtree(alg_dir)
+
+
+if __name__ == '__main__':
+ iotests.script_main(test_overlaybd, supported_fmts=['raw'],
+ supported_protocols=['file'])
diff --git a/tests/qemu-iotests/tests/overlaybd.out b/tests/qemu-iotests/tests/overlaybd.out
new file mode 100644
index 0000000000..be1352fbce
--- /dev/null
+++ b/tests/qemu-iotests/tests/overlaybd.out
@@ -0,0 +1,10 @@
+manifest mode: byte-exact
+blob-path forms: byte-exact
+layers mode: byte-exact
+single plain layer: byte-exact
+header-overwrite zfile: byte-exact
+file child as manifest: byte-exact
+file child as tar layer: byte-exact
+format probing verified
+1 MiB jump table: byte-exact
+error paths verified
--
2.54.0 (Apple Git-157)© 2016 - 2026 Red Hat, Inc.