[linux.git] / Documentation / lzo.txt

===========================================================
LZO stream format as understood by Linux's LZO decompressor
===========================================================

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

  This is not a specification. No specification seems to be publicly available
  for the LZO stream format. This document describes what input format the LZO
  decompressor as implemented in the Linux kernel understands. The file subject
  of this analysis is lib/lzo/lzo1x_decompress_safe.c. No analysis was made on
  the compressor nor on any other implementations though it seems likely that
  the format matches the standard one. The purpose of this document is to
  better understand what the code does in order to propose more efficient fixes
  for future bug reports.

Description
===========

  The stream is composed of a series of instructions, operands, and data. The
  instructions consist in a few bits representing an opcode, and bits forming
  the operands for the instruction, whose size and position depend on the
  opcode and on the number of literals copied by previous instruction. The
  operands are used to indicate:

    - a distance when copying data from the dictionary (past output buffer)
    - a length (number of bytes to copy from dictionary)
    - the number of literals to copy, which is retained in variable "state"
      as a piece of information for next instructions.

  Optionally depending on the opcode and operands, extra data may follow. These
  extra data can be a complement for the operand (eg: a length or a distance
  encoded on larger values), or a literal to be copied to the output buffer.

  The first byte of the block follows a different encoding from other bytes, it
  seems to be optimized for literal use only, since there is no dictionary yet
  prior to that byte.

  Lengths are always encoded on a variable size starting with a small number
  of bits in the operand. If the number of bits isn't enough to represent the
  length, up to 255 may be added in increments by consuming more bytes with a
  rate of at most 255 per extra byte (thus the compression ratio cannot exceed
  around 255:1). The variable length encoding using #bits is always the same::

       length = byte & ((1 << #bits) - 1)
       if (!length) {
               length = ((1 << #bits) - 1)
               length += 255*(number of zero bytes)
               length += first-non-zero-byte
       }
       length += constant (generally 2 or 3)

  For references to the dictionary, distances are relative to the output
  pointer. Distances are encoded using very few bits belonging to certain
  ranges, resulting in multiple copy instructions using different encodings.
  Certain encodings involve one extra byte, others involve two extra bytes
  forming a little-endian 16-bit quantity (marked LE16 below).

  After any instruction except the large literal copy, 0, 1, 2 or 3 literals
  are copied before starting the next instruction. The number of literals that
  were copied may change the meaning and behaviour of the next instruction. In
  practice, only one instruction needs to know whether 0, less than 4, or more
  literals were copied. This is the information stored in the <state> variable
  in this implementation. This number of immediate literals to be copied is
  generally encoded in the last two bits of the instruction but may also be
  taken from the last two bits of an extra operand (eg: distance).

  End of stream is declared when a block copy of distance 0 is seen. Only one
  instruction may encode this distance (0001HLLL), it takes one LE16 operand
  for the distance, thus requiring 3 bytes.

  .. important::

     In the code some length checks are missing because certain instructions
     are called under the assumption that a certain number of bytes follow
     because it has already been guaranteed before parsing the instructions.
     They just have to "refill" this credit if they consume extra bytes. This
     is an implementation design choice independent on the algorithm or
     encoding.

Byte sequences
==============

  First byte encoding::

      0..17   : follow regular instruction encoding, see below. It is worth
                noting that codes 16 and 17 will represent a block copy from
                the dictionary which is empty, and that they will always be
                invalid at this place.

      18..21  : copy 0..3 literals
                state = (byte - 17) = 0..3  [ copy <state> literals ]
                skip byte

      22..255 : copy literal string
                length = (byte - 17) = 4..238
                state = 4 [ don't copy extra literals ]
                skip byte

  Instruction encoding::

      0 0 0 0 X X X X  (0..15)
        Depends on the number of literals copied by the last instruction.
        If last instruction did not copy any literal (state == 0), this
        encoding will be a copy of 4 or more literal, and must be interpreted
        like this :

           0 0 0 0 L L L L  (0..15)  : copy long literal string
           length = 3 + (L ?: 15 + (zero_bytes * 255) + non_zero_byte)
           state = 4  (no extra literals are copied)

        If last instruction used to copy between 1 to 3 literals (encoded in
        the instruction's opcode or distance), the instruction is a copy of a
        2-byte block from the dictionary within a 1kB distance. It is worth
        noting that this instruction provides little savings since it uses 2
        bytes to encode a copy of 2 other bytes but it encodes the number of
        following literals for free. It must be interpreted like this :

           0 0 0 0 D D S S  (0..15)  : copy 2 bytes from <= 1kB distance
           length = 2
           state = S (copy S literals after this block)
         Always followed by exactly one byte : H H H H H H H H
           distance = (H << 2) + D + 1

        If last instruction used to copy 4 or more literals (as detected by
        state == 4), the instruction becomes a copy of a 3-byte block from the
        dictionary from a 2..3kB distance, and must be interpreted like this :

           0 0 0 0 D D S S  (0..15)  : copy 3 bytes from 2..3 kB distance
           length = 3
           state = S (copy S literals after this block)
         Always followed by exactly one byte : H H H H H H H H
           distance = (H << 2) + D + 2049

      0 0 0 1 H L L L  (16..31)
           Copy of a block within 16..48kB distance (preferably less than 10B)
           length = 2 + (L ?: 7 + (zero_bytes * 255) + non_zero_byte)
        Always followed by exactly one LE16 :  D D D D D D D D : D D D D D D S S
           distance = 16384 + (H << 14) + D
           state = S (copy S literals after this block)
           End of stream is reached if distance == 16384

      0 0 1 L L L L L  (32..63)
           Copy of small block within 16kB distance (preferably less than 34B)
           length = 2 + (L ?: 31 + (zero_bytes * 255) + non_zero_byte)
        Always followed by exactly one LE16 :  D D D D D D D D : D D D D D D S S
           distance = D + 1
           state = S (copy S literals after this block)

      0 1 L D D D S S  (64..127)
           Copy 3-4 bytes from block within 2kB distance
           state = S (copy S literals after this block)
           length = 3 + L
         Always followed by exactly one byte : H H H H H H H H
           distance = (H << 3) + D + 1

      1 L L D D D S S  (128..255)
           Copy 5-8 bytes from block within 2kB distance
           state = S (copy S literals after this block)
           length = 5 + L
         Always followed by exactly one byte : H H H H H H H H
           distance = (H << 3) + D + 1

Authors
=======

  This document was written by Willy Tarreau <[email protected]> on 2014/07/19 during an
  analysis of the decompression code available in Linux 3.16-rc5. The code is
  tricky, it is possible that this document contains mistakes or that a few
  corner cases were overlooked. In any case, please report any doubt, fix, or
  proposed updates to the author(s) so that the document can be updated.
Commit	Line	Data
7b001bff	1	===========================================================
d98a0526 WT	2	LZO stream format as understood by Linux's LZO decompressor
	3	===========================================================
	4
	5	Introduction
7b001bff	6	============
d98a0526 WT	7
	8	This is not a specification. No specification seems to be publicly available
	9	for the LZO stream format. This document describes what input format the LZO
	10	decompressor as implemented in the Linux kernel understands. The file subject
	11	of this analysis is lib/lzo/lzo1x_decompress_safe.c. No analysis was made on
	12	the compressor nor on any other implementations though it seems likely that
	13	the format matches the standard one. The purpose of this document is to
	14	better understand what the code does in order to propose more efficient fixes
	15	for future bug reports.
	16
	17	Description
7b001bff	18	===========
d98a0526 WT	19
	20	The stream is composed of a series of instructions, operands, and data. The
	21	instructions consist in a few bits representing an opcode, and bits forming
	22	the operands for the instruction, whose size and position depend on the
	23	opcode and on the number of literals copied by previous instruction. The
7b001bff	24	operands are used to indicate:
d98a0526 WT	25
	26	- a distance when copying data from the dictionary (past output buffer)
	27	- a length (number of bytes to copy from dictionary)
	28	- the number of literals to copy, which is retained in variable "state"
	29	as a piece of information for next instructions.
	30
	31	Optionally depending on the opcode and operands, extra data may follow. These
	32	extra data can be a complement for the operand (eg: a length or a distance
	33	encoded on larger values), or a literal to be copied to the output buffer.
	34
	35	The first byte of the block follows a different encoding from other bytes, it
	36	seems to be optimized for literal use only, since there is no dictionary yet
	37	prior to that byte.
	38
	39	Lengths are always encoded on a variable size starting with a small number
	40	of bits in the operand. If the number of bits isn't enough to represent the
	41	length, up to 255 may be added in increments by consuming more bytes with a
	42	rate of at most 255 per extra byte (thus the compression ratio cannot exceed
7b001bff	43	around 255:1). The variable length encoding using #bits is always the same::
d98a0526 WT	44
	45	length = byte & ((1 << #bits) - 1)
	46	if (!length) {
	47	length = ((1 << #bits) - 1)
	48	length += 255*(number of zero bytes)
	49	length += first-non-zero-byte
	50	}
	51	length += constant (generally 2 or 3)
	52
	53	For references to the dictionary, distances are relative to the output
	54	pointer. Distances are encoded using very few bits belonging to certain
	55	ranges, resulting in multiple copy instructions using different encodings.
	56	Certain encodings involve one extra byte, others involve two extra bytes
	57	forming a little-endian 16-bit quantity (marked LE16 below).
	58
	59	After any instruction except the large literal copy, 0, 1, 2 or 3 literals
	60	are copied before starting the next instruction. The number of literals that
	61	were copied may change the meaning and behaviour of the next instruction. In
	62	practice, only one instruction needs to know whether 0, less than 4, or more
	63	literals were copied. This is the information stored in the <state> variable
	64	in this implementation. This number of immediate literals to be copied is
	65	generally encoded in the last two bits of the instruction but may also be
	66	taken from the last two bits of an extra operand (eg: distance).
	67
	68	End of stream is declared when a block copy of distance 0 is seen. Only one
	69	instruction may encode this distance (0001HLLL), it takes one LE16 operand
	70	for the distance, thus requiring 3 bytes.
	71
7b001bff MCC	72	.. important::
	73
	74	In the code some length checks are missing because certain instructions
	75	are called under the assumption that a certain number of bytes follow
	76	because it has already been guaranteed before parsing the instructions.
	77	They just have to "refill" this credit if they consume extra bytes. This
	78	is an implementation design choice independent on the algorithm or
	79	encoding.
d98a0526 WT	80
d98a0526 WT	81	Byte sequences
7b001bff	82	==============
d98a0526	83
7b001bff	84	First byte encoding::
d98a0526 WT	85
	86	0..17 : follow regular instruction encoding, see below. It is worth
	87	noting that codes 16 and 17 will represent a block copy from
	88	the dictionary which is empty, and that they will always be
	89	invalid at this place.
	90
	91	18..21 : copy 0..3 literals
	92	state = (byte - 17) = 0..3 [ copy <state> literals ]
	93	skip byte
	94
	95	22..255 : copy literal string
	96	length = (byte - 17) = 4..238
	97	state = 4 [ don't copy extra literals ]
	98	skip byte
	99
7b001bff	100	Instruction encoding::
d98a0526 WT	101
	102	0 0 0 0 X X X X (0..15)
	103	Depends on the number of literals copied by the last instruction.
	104	If last instruction did not copy any literal (state == 0), this
	105	encoding will be a copy of 4 or more literal, and must be interpreted
	106	like this :
	107
	108	0 0 0 0 L L L L (0..15) : copy long literal string
	109	length = 3 + (L ?: 15 + (zero_bytes * 255) + non_zero_byte)
	110	state = 4 (no extra literals are copied)
	111
	112	If last instruction used to copy between 1 to 3 literals (encoded in
	113	the instruction's opcode or distance), the instruction is a copy of a
	114	2-byte block from the dictionary within a 1kB distance. It is worth
	115	noting that this instruction provides little savings since it uses 2
	116	bytes to encode a copy of 2 other bytes but it encodes the number of
	117	following literals for free. It must be interpreted like this :
	118
	119	0 0 0 0 D D S S (0..15) : copy 2 bytes from <= 1kB distance
	120	length = 2
	121	state = S (copy S literals after this block)
	122	Always followed by exactly one byte : H H H H H H H H
	123	distance = (H << 2) + D + 1
	124
	125	If last instruction used to copy 4 or more literals (as detected by
	126	state == 4), the instruction becomes a copy of a 3-byte block from the
	127	dictionary from a 2..3kB distance, and must be interpreted like this :
	128
	129	0 0 0 0 D D S S (0..15) : copy 3 bytes from 2..3 kB distance
	130	length = 3
	131	state = S (copy S literals after this block)
	132	Always followed by exactly one byte : H H H H H H H H
	133	distance = (H << 2) + D + 2049
	134
	135	0 0 0 1 H L L L (16..31)
	136	Copy of a block within 16..48kB distance (preferably less than 10B)
	137	length = 2 + (L ?: 7 + (zero_bytes * 255) + non_zero_byte)
	138	Always followed by exactly one LE16 : D D D D D D D D : D D D D D D S S
	139	distance = 16384 + (H << 14) + D
	140	state = S (copy S literals after this block)
	141	End of stream is reached if distance == 16384
	142
	143	0 0 1 L L L L L (32..63)
	144	Copy of small block within 16kB distance (preferably less than 34B)
	145	length = 2 + (L ?: 31 + (zero_bytes * 255) + non_zero_byte)
	146	Always followed by exactly one LE16 : D D D D D D D D : D D D D D D S S
	147	distance = D + 1
	148	state = S (copy S literals after this block)
	149
	150	0 1 L D D D S S (64..127)
	151	Copy 3-4 bytes from block within 2kB distance
	152	state = S (copy S literals after this block)
	153	length = 3 + L
	154	Always followed by exactly one byte : H H H H H H H H
	155	distance = (H << 3) + D + 1
	156
	157	1 L L D D D S S (128..255)
	158	Copy 5-8 bytes from block within 2kB distance
	159	state = S (copy S literals after this block)
	160	length = 5 + L
	161	Always followed by exactly one byte : H H H H H H H H
	162	distance = (H << 3) + D + 1
	163
	164	Authors
7b001bff	165	=======
d98a0526 WT	166
	167	This document was written by Willy Tarreau <[email protected]> on 2014/07/19 during an
	168	analysis of the decompression code available in Linux 3.16-rc5. The code is
	169	tricky, it is possible that this document contains mistakes or that a few
	170	corner cases were overlooked. In any case, please report any doubt, fix, or
	171	proposed updates to the author(s) so that the document can be updated.