Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:LZFSE

From ReverseEngineering.wiki
Format
On this wiki Facts · Code · Notes · Topics

Apple's compression format (LZFSE, with its LZVN fallback): a stream of blocks, each starting with a 4-byte magic 'bvx1', 'bvx2', 'bvxn', 'bvx-' and ending with 'bvx$'; LZFSE is LZ77 with finite-state-entropy coding, LZVN a byte-oriented LZ with an opcode table.

LZFSE is the compression used by Apple (iOS/macOS firmware payloads, APFS/HFS+ file compression variants, Compression framework algorithm COMPRESSION_LZFSE) and published as BSD-3-Clause source in github.com/lzfse/lzfse. It has no file header: the stream is a sequence of blocks, each recognised by a 4-byte little-endian magic made of the ASCII letters bvx plus one character.

Identification

Bytes ASCII Block
62 76 78 31 bvx1 LZFSE compressed block, frequency tables stored uncompressed (v1 header)
62 76 78 32 bvx2 LZFSE compressed block, frequency tables stored compressed (v2 header)
62 76 78 6E bvxn LZVN compressed block
62 76 78 2D bvx- uncompressed (raw) block
62 76 78 24 bvx$ end of stream (4 bytes, no body)

Source: src/lzfse_internal.h lines 276-281 at e634ca58b4 (the LZFSE_*_BLOCK_MAGIC constants; the decoder switch is in src/lzfse_decode_base.c lines 336-516). The decoder returns an error for any other magic. A raw buffer therefore normally starts with bvx2 (or bvx1/bvxn/bvx- for small or incompressible inputs) and ends with bvx$. See Fact:LZFSE/magic/Block magics.

Block headers

All fields little endian. See Fact:LZFSE/struct/Block headers.

  • Uncompressed block: magic, n_raw_bytes (u32), then that many raw bytes (8-byte header).
  • LZVN block: magic, n_raw_bytes (u32, decoded size), n_payload_bytes (u32, encoded size), then the LZVN opcode stream (12-byte header). The decoder starts each block with the previous-distance register d_prev = 0.
  • bvx1: magic, n_raw_bytes, n_payload_bytes, n_literals, n_matches, n_literal_payload_bytes, n_lmd_payload_bytes, literal_bits (i32), four literal states (u16), lmd_bits (i32), l/m/d states (u16 each), then the normalized frequency tables as plain u16 arrays: 20 L symbols, 20 M symbols, 64 D symbols, 256 literal symbols.
  • bvx2: magic, n_raw_bytes, then three u64 words that pack the same counters (20-bit n_literals, n_literal_payload_bytes, n_matches, n_lmd_payload_bytes; 10-bit literal states; 3-bit bit counts; 32-bit total header_size; 10/10/10-bit l/m/d states), followed by the frequency tables in a variable-length Huffman-style encoding. The stored header is truncated to header_size.

LZFSE model

Blocks hold at most 10000 matches (LZFSE_MATCHES_PER_BLOCK) and 4 x 10000 literal bytes; the entropy coder is tANS/FSE with 64 states for L (literal length) and M (match length), 256 for D (distance) and 1024 for literals (4 interleaved literal streams), with symbol counts 20, 20, 64 and 256 (lzfse_internal.h lines 89-98). Each match is an (L, M, D) triplet: literal count, match length and distance.

LZVN

LZVN is a byte-oriented LZ (no entropy coder) driven by a 256-entry opcode table in src/lzvn_decode_base.c (table from line 50). Opcode classes there: sml_d, med_d, lrg_d, pre_d (matches with small/medium/large/previous distance), sml_l/lrg_l (literals), sml_m/lrg_m (match continuation), nop and eos. Specific entries read: 0x06 is end of stream, 0x0E and 0x16 are nop, 0xA0-0xBF are med_d, 0xE0 is lrg_l and 0xE1-0xEF sml_l, 0xF0 is lrg_m and 0xF1-0xFF sml_m, 0x1E and 0xD0-0xDF and 0x70-0x7F are undefined. LZVN is used alone for inputs under a size threshold: Unverified: the encoder chooses LZVN for small buffers and LZFSE otherwise.

Related

Format:LZ4, Format:Zstandard, Technique:Identifying compression libraries in binaries. Unverified: Apple's own Compression framework and the kernel use this same stream format, with the lzfse repository documenting a compatible implementation.

Code & repositories

  • https://github.com/lzfse/lzfse @ e634ca58b4821d9f3d560cdc6df5dec02ffc93fd · license: BSD-3-Clause
    Apple's reference LZFSE/LZVN encoder and decoder (BSD-3-Clause): src/lzfse_internal.h has block magics and headers, src/lzvn_decode_base.c the LZVN opcode table.
    Tested on: source read, not run · checked 2026-10-19; last activity 2022-09-05