Format:LZFSE
| 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