diff --git a/Documentation/applications/system/lzf/index.rst b/Documentation/applications/system/lzf/index.rst index 4fe8c761d39b0..01ee313861ea2 100644 --- a/Documentation/applications/system/lzf/index.rst +++ b/Documentation/applications/system/lzf/index.rst @@ -1,3 +1,165 @@ ============================ ``lzf`` LZF compression tool ============================ + +Overview +======== + +The ``lzf`` command compresses and decompresses files using the LZF +algorithm by Marc Alexander Lehmann. LZF is a very lightweight +compression format optimized for speed; it trades a modest compression +ratio for fast decompression that is nearly as fast as a memory copy. + +The tool reads input files (or ``stdin`` when no files are given), +writes the result to a derived output file (or ``stdout``), and +optionally removes the original on success. + +File format +----------- + +An LZF stream consists of zero or more blocks. Each block starts +with the two-byte magic ``ZV`` followed by a type byte: + +- **Type 0** (5-byte header): uncompressed literal — 2-byte length, + then raw data. +- **Type 1** (7-byte header): compressed — 2-byte compressed length, + 2-byte uncompressed length, then LZF-compressed data. + +A ``\x00`` byte signals end-of-stream. + +Configuration +============= + +Enable the command with ``CONFIG_SYSTEM_LZF`` (tristate). This +option depends on ``CONFIG_LIBC_LZF``, which provides the core +compression and decompression library. + +Additional configuration symbols: + +- ``CONFIG_SYSTEM_LZF_BLOG`` — Log2 of the block size used for + compression and decompression (default ``10``, range 9–12). The + actual block size is ``(1 << BLOG) - 1`` bytes. Larger values may + yield slightly better compression at the cost of more static memory + (approximately ``2 * (1 << BLOG)`` bytes of ``.bss``). +- ``CONFIG_SYSTEM_LZF_PROGNAME`` — Program name registered with NSH + (default ``"lzf"``). +- ``CONFIG_SYSTEM_LZF_PRIORITY`` — Task priority (default ``100``). +- ``CONFIG_SYSTEM_LZF_STACKSIZE`` — Task stack size (default + ``DEFAULT_TASK_STACKSIZE``). + +Usage +===== + +.. code-block:: console + + lzf [-cdfvh] [-b ] [file ...] + lzf -h + +When no ``file`` arguments are given, ``lzf`` reads from ``stdin`` +and writes to ``stdout``. The ``-f`` flag is required in this mode +if the data direction would otherwise be a terminal (to prevent +accidental interactive use). + +When files are given, the output file name is derived automatically: + +- **Compress** (default or ``-c``): the first ``.`` in the filename is + replaced with ``_``, and a ``.lzf`` suffix is appended. For + example, ``data.bin`` becomes ``data_bin.lzf``. +- **Decompress** (``-d``): the ``.lzf`` suffix is stripped and the + first ``_`` is replaced back with ``.``. For example, + ``data_bin.lzf`` becomes ``data.bin``. + +On success the original file is removed (replaced). + +Options +======= + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + * - ``-c`` + - Compress (default mode). + * - ``-d`` + - Decompress. + * - ``-f`` + - Force overwrite of the output file. Also suppresses the + terminal-safety check when reading from ``stdin`` or writing + to ``stdout``. + * - ``-h`` + - Show usage information and exit. + * - ``-v`` + - Verbose mode. Prints the compression ratio and the output + filename for each processed file on ``stderr``. + * - ``-b `` + - Set the block size in bytes. Must be between 1 and + ``(1 << CONFIG_SYSTEM_LZF_BLOG) - 1``. Values outside this + range are silently clamped to the compiled-in default. + +Environment +----------- + +When ``CONFIG_DISABLE_ENVIRON`` is not set, the ``LZF_BLOCKSIZE`` +environment variable can override the default block size. The +command-line ``-b`` option takes precedence over the environment +variable. + +Examples +======== + +Compress a file (replaces ``sensor.log`` with +``sensor_log.lzf``): + +.. code-block:: console + + nsh> lzf sensor.log + +Decompress a file (replaces ``sensor_log.lzf`` with +``sensor.log``): + +.. code-block:: console + + nsh> lzf -d sensor_log.lzf + +Compress with verbose output showing the ratio: + +.. code-block:: console + + nsh> lzf -v largefile.dat + +Compress from ``stdin`` to ``stdout`` (pipeline): + +.. code-block:: console + + nsh> cat data.bin | lzf -f > data.bin.lzf + +Decompress from ``stdin`` to ``stdout``: + +.. code-block:: console + + nsh> cat data.bin.lzf | lzf -df > data.bin + +Set a smaller block size for low-memory systems: + +.. code-block:: console + + nsh> lzf -b 512 sensor.log + +Notes +===== + +- The default mode is compress; ``-c`` is optional but may be used for + clarity. +- ``-c`` and ``-d`` are mutually exclusive. If both are specified the + last one on the command line wins. +- When run in FLAT or PROTECTED build modes (``CONFIG_SYSTEM_LZF`` set + to ``y``), the tool serializes concurrent invocations via a mutex + because the compression hash table and I/O buffers are statically + allocated. In KERNEL build mode (``CONFIG_SYSTEM_LZF`` set to ``m``) + each instance has its own address space and no serialization is + needed. +- The LZF library is provided under a BSD-2-Clause license. +- The output file is created with mode ``0600`` (owner read/write only). +- If the output file already exists and ``-f`` is not given, the + command fails with an error.