Linux의 XZ data 압축

XZ Embedded와 지원 filter

이 문서는 0BSD license로 제공된다. XZ는 높은 압축률을 제공하는 범용 data compression format이며 Linux의 XZ decompressor는 XZ Embedded라고 부른다.

XZ Embedded는 LZMA2 filter를 지원하고 executable code를 위한 BCJ(Branch/Call/Jump) filter도 선택적으로 지원한다. integrity check에는 CRC32를 지원한다.

XZ Embedded home page에는 Linux kernel에 필요하지 않은 선택적 추가 기능과 kernel 밖에서 code를 사용하는 정보가 포함된 최신 version이 있다. userspace에서는 XZ Utils가 zlib과 비슷한 compression library와 gzip과 비슷한 command-line tool을 제공한다.

.. SPDX-License-Identifier: 0BSD

============================
XZ data compression in Linux
============================

Introduction
============

XZ is a general purpose data compression format with high compression
ratio. The XZ decompressor in Linux is called XZ Embedded. It supports
the LZMA2 filter and optionally also Branch/Call/Jump (BCJ) filters
for executable code. CRC32 is supported for integrity checking.

See the `XZ Embedded`_ home page for the latest version which includes
a few optional extra features that aren't required in the Linux kernel
and information about using the code outside the Linux kernel.

For userspace, `XZ Utils`_ provide a zlib-like compression library
and a gzip-like command line tool.

.. _XZ Embedded: https://tukaani.org/xz/embedded.html
.. _XZ Utils: https://tukaani.org/xz/

Kernel의 XZ 관련 구성 요소

`xz_dec` module은 `include/linux/xz.h`에 single-call, 즉 buffer-to-buffer API와 multi-call, 즉 stateful API를 제공한다.

kernel image, initramfs, initrd를 풀 때는 `lib/decompress_unxz.c`의 wrapper를 사용한다. API는 `include/linux/decompress/generic.h`에 정의된 다른 `decompress_*.c` file과 같다.

kernel makefile은 XZ Utils의 `xz` tool을 요구하는 command 세 가지를 제공한다. `$(call if_changed,xzkern)`은 `scripts/xz_wrap.sh`를 실행해 architecture 최적화 option과 큰 LZMA2 dictionary로 kernel image를 압축한다.

`$(call if_changed,xzkern_with_size)`는 `xzkern`과 같지만 uncompressed file size를 담은 4-byte trailer를 붙인다. 일부 architecture의 boot code가 이 trailer를 요구한다.

그 밖의 data는 `$(call if_needed,xzmisc)`로 압축할 수 있으며 BCJ filter 없이 1 MiB LZMA2 dictionary를 사용한다.

XZ related components in the kernel
===================================

The xz_dec module provides XZ decompressor with single-call (buffer
to buffer) and multi-call (stateful) APIs in include/linux/xz.h.

For decompressing the kernel image, initramfs, and initrd, there
is a wrapper function in lib/decompress_unxz.c. Its API is the
same as in other decompress_*.c files, which is defined in
include/linux/decompress/generic.h.

For kernel makefiles, three commands are provided for use with
``$(call if_changed)``. They require the xz tool from XZ Utils.

- ``$(call if_changed,xzkern)`` is for compressing the kernel image.
  It runs the script scripts/xz_wrap.sh which uses arch-optimized
  options and a big LZMA2 dictionary.

- ``$(call if_changed,xzkern_with_size)`` is like ``xzkern`` above but
  this also appends a four-byte trailer containing the uncompressed size
  of the file. The trailer is needed by the boot code on some archs.

- Other things can be compressed with ``$(call if_needed,xzmisc)``
  which will use no BCJ filter and 1 MiB LZMA2 dictionary.

CRC32 integrity check 선택

XZ Embedded는 CRC32 또는 integrity check가 없는 stream만 지원한다. kernel이 decode할 file을 만들 때 다른 check type을 사용하면 안 된다.

XZ Utils의 liblzma로 encode할 때는 `LZMA_CHECK_CRC32` 또는 `LZMA_CHECK_NONE`을 사용한다. `xz` command에서는 기본 `--check=crc64`를 `--check=crc32` 또는 `--check=none`으로 덮어써야 한다.

uncompressed data의 integrity를 다른 layer가 이미 검증하지 않는 한 CRC32 사용을 강하게 권장한다. 다른 layer가 검증한다면 이중 검사는 CPU cycle 낭비가 될 수 있다.

header에는 항상 CRC32가 있고 decoder가 이를 검증한다. 변경하거나 끌 수 있는 integrity check는 실제 uncompressed data에 대한 check뿐이다.

Notes on compression options
============================

Since the XZ Embedded supports only streams with CRC32 or no integrity
check, make sure that you don't use some other integrity check type
when encoding files that are supposed to be decoded by the kernel.
With liblzma from XZ Utils, you need to use either ``LZMA_CHECK_CRC32``
or ``LZMA_CHECK_NONE`` when encoding. With the ``xz`` command line tool,
use ``--check=crc32`` or ``--check=none`` to override the default
``--check=crc64``.

Using CRC32 is strongly recommended unless there is some other layer
which will verify the integrity of the uncompressed data anyway.
Double checking the integrity would probably be waste of CPU cycles.
Note that the headers will always have a CRC32 which will be validated
by the decoder; you can only change the integrity check type (or
disable it) for the actual uncompressed data.

Dictionary memory와 compression option

userspace의 LZMA2는 보통 수 MiB dictionary를 사용하며 decoder는 dictionary를 RAM에 보유해야 한다.

multi-call mode에서는 dictionary가 decoder state 일부로 할당된다. 합리적인 in-kernel 최대 크기는 target hardware에 따라 다르다. desktop은 수 MiB도 괜찮지만 일부 embedded system에는 64 KiB에서 1 MiB가 더 적절하다.

single-call mode에서는 output buffer 자체를 dictionary buffer로 사용한다. 따라서 dictionary size가 decompressor memory 사용량에 영향을 주지 않고, 30 KiB보다 조금 작은 base data structure만 따로 할당된다.

single-call에서 최상의 압축률을 얻으려면 dictionary가 uncompressed data만큼 커야 한다. PowerPC를 제외하고 kernel 자체를 decompress하는 작업이 대표적인 single-call 사용 사례다.

XZ Utils preset은 kernel용 file에 최적이 아닐 수 있으므로 dictionary size 같은 값을 custom setting으로 지정할 수 있다. single-thread mode가 더 작은 file을 만들 수 있어 이를 명시하는 것을 권장한다. 예제는 `xz --threads=1 --check=crc32 --lzma2=dict=512KiB inputfile`이다.

In userspace, LZMA2 is typically used with dictionary sizes of several
megabytes. The decoder needs to have the dictionary in RAM:

- In multi-call mode the dictionary is allocated as part of the
  decoder state. The reasonable maximum dictionary size for in-kernel
  use will depend on the target hardware: a few megabytes is fine for
  desktop systems while 64 KiB to 1 MiB might be more appropriate on
  some embedded systems.

- In single-call mode the output buffer is used as the dictionary
  buffer. That is, the size of the dictionary doesn't affect the
  decompressor memory usage at all. Only the base data structures
  are allocated which take a little less than 30 KiB of memory.
  For the best compression, the dictionary should be at least
  as big as the uncompressed data. A notable example of single-call
  mode is decompressing the kernel itself (except on PowerPC).

The compression presets in XZ Utils may not be optimal when creating
files for the kernel, so don't hesitate to use custom settings to,
for example, set the dictionary size. Also, xz may produce a smaller
file in single-threaded mode so setting that explicitly is recommended.
Example::

    xz --threads=1 --check=crc32 --lzma2=dict=512KiB inputfile

xz_dec API reference

`xz_dec` API는 `#include <linux/xz.h>`로 사용할 수 있다. 구체적인 선언과 계약은 `include/linux/xz.h`에서 가져오는 kernel-doc 내용이 이 절에 렌더링된다.

xz_dec API
==========

This is available with ``#include <linux/xz.h>``.

.. kernel-doc:: include/linux/xz.h