release/src/router/lzo/doc/LZO.FAQ

   1 ============================================================================
   2 LZO Frequently Asked Questions
   3 ============================================================================
   4
   5
   6 I hate reading docs - just tell me how to add compression to my program
   7 =======================================================================
   8
   9 This is for the impatient: take a look at examples/simple.c and
  10 examples/lzopack.c and see how easy this is.
  11
  12 But you will come back to read the documentation later, won't you ?
  13
  14
  15 Can you explain the naming conventions of the algorithms ?
  16 ==========================================================
  17
  18 Let's take a look at LZO1X:
  19
  20      The algorithm name is LZO1X.
  21      The algorithm category is LZO1.
  22      Various compression levels are implemented.
  23
  24      LZO1X-999
  25         !---------- algorithm category
  26          !--------- algorithm type
  27            !!!----- compression level (1-9, 99, 999)
  28
  29      LZO1X-1(11)
  30         !---------- algorithm category
  31          !--------- algorithm type
  32            !------- compression level (1-9, 99, 999)
  33              !!---- memory level (memory requirements for compression)
  34
  35 All compression/memory levels generate the same compressed data format,
  36 so e.g. the LZO1X decompressor handles all LZO1X-* compression levels
  37 (for more information about the decompressors see below).
  38
  39 Category LZO1 algorithms: compressed data format is strictly byte aligned
  40 Category LZO2 algorithms: uses bit-shifting, slower decompression
  41
  42
  43 Why are there so many algorithms ?
  44 ==================================
  45
  46 Because of historical reasons - I want to support unlimited
  47 backward compatibility.
  48
  49 Don't get misled by the size of the library - using one algorithm
  50 increases the size of your application by only a few KiB.
  51
  52 If you just want to add a little bit of data compression to your
  53 application you may be looking for miniLZO.
  54 See minilzo/README.LZO for more information.
  55
  56
  57 Which algorithm should I use ?
  58 ==============================
  59
  60 LZO1X seems to be best choice in many cases, so:
  61 - when going for speed use LZO1X-1
  62 - when generating pre-compressed data use LZO1X-999
  63 - if you have little memory available for compression use LZO1X-1(11)
  64   or LZO1X-1(12)
  65
  66 Of course, your mileage may vary, and you are encouraged to run your
  67 own experiments. Try LZO1Y and LZO1F next.
  68
  69
  70 What's the difference between the decompressors per algorithm ?
  71 ===============================================================
  72
  73 Once again let's use LZO1X for explanation:
  74
  75 - lzo1x_decompress
  76     The 'standard' decompressor. Pretty fast - use this whenever possible.
  77
  78     This decompressor expects valid compressed data.
  79     If the compressed data gets corrupted somehow (e.g. transmission
  80     via an erroneous channel, disk errors, ...) it will probably crash
  81     your application because absolutely no additional checks are done.
  82
  83 - lzo1x_decompress_safe
  84     The 'safe' decompressor. Somewhat slower.
  85
  86     This decompressor will catch all compressed data violations and
  87     return an error code in this case - it will never crash.
  88
  89 - lzo1x_decompress_asm
  90     Same as lzo1x_decompress - written in assembler.
  91
  92 - lzo1x_decompress_asm_safe
  93     Same as lzo1x_decompress_safe - written in assembler.
  94
  95 - lzo1x_decompress_asm_fast
  96     Similar to lzo1x_decompress_asm - but even faster.
  97
  98     For reasons of speed this decompressor can write up to 3 bytes
  99     past the end of the decompressed (output) block.
 100     [ technical note: because data is transferred in 32-bit units ]
 101
 102     Use this when you are decompressing from one memory block to
 103     another memory block - just provide output space for 3 extra bytes.
 104     You shouldn't use it if e.g. you are directly decompressing to video
 105     memory (because the extra bytes will be show up on the screen).
 106
 107 - lzo1x_decompress_asm_fast_safe
 108     This is the safe version of lzo1x_decompress_asm_fast.
 109
 110
 111 Notes:
 112 ------
 113 - When using a safe decompressor you must pass the number of
 114   bytes available in 'dst' via the parameter 'dst_len'.
 115
 116 - If you want to be sure that your data is not corrupted you must
 117   use a checksum - just using the safe decompressor is not enough,
 118   because many data errors will not result in a compressed data violation.
 119
 120 - Assembler versions are only available for the i386 family yet.
 121   Please see also asm/i386/00README.TXT
 122
 123 - You should test if the assembler versions are actually faster
 124   than the C version on your machine - some compilers can do a very
 125   good optimization job and they also can optimize the code
 126   for a specific processor.
 127
 128
 129 What is this optimization thing ?
 130 =================================
 131
 132 The compressors use a heuristic approach - they sometimes code
 133 information that doesn't improve compression ratio.
 134
 135 Optimization removes this superfluos information in order to
 136 increase decompression speed.
 137
 138 Optimization works similar to decompression except that the
 139 compressed data is modified as well. The length of the compressed
 140 data block will not change - only the compressed data-bytes will
 141 get rearranged a little bit.
 142
 143 Don't expect too much, though - my tests have shown that the
 144 optimization step improves decompression speed by about 1-3%.
 145
 146
 147 I need even more decompression speed...
 148 =======================================
 149
 150 Many RISC processors (like MIPS) can transfer 32-bit words much
 151 faster than bytes - this can significantly speed up decompression.
 152 So after verifying that everything works fine you can try if activating
 153 the LZO_ALIGNED_OK_4 macro improves LZO1X and LZO1Y decompression
 154 performance. Change the file config.h accordingly and recompile everything.
 155
 156 On an i386 architecture you should evaluate the assembler versions.
 157
 158
 159 How can I reduce memory requirements when (de)compressing ?
 160 ===========================================================
 161
 162 If you cleverly arrange your data, you can do an overlapping (in-place)
 163 decompression which means that you can decompress to the *same*
 164 block where the compressed data resides. This effectively removes
 165 the space requirements for holding the compressed data block.
 166
 167 This technique is essential e.g. for usage in an executable packer.
 168
 169 You can also partly overlay the buffers when doing compression.
 170
 171 See examples/overlap.c for a working example.
 172
 173
 174 Can you give a cookbook for using pre-compressed data ?
 175 =======================================================
 176
 177 Let's assume you use LZO1X-999.
 178
 179 1) pre-compression step
 180    - call lzo_init()
 181    - call lzo1x_999_compress()
 182    - call lzo1x_optimize()
 183    - compute an adler32 checksum of the *compressed* data
 184    - store the compressed data and the checksum in a file
 185    - if you are paranoid you should verify decompression now
 186
 187 2) decompression step within your application
 188    - call lzo_init()
 189    - load your compressed data and the checksum
 190    - optionally verify the checksum of the compressed data
 191      (so that you can use the standard decompressor)
 192    - decompress
 193
 194 See examples/precomp.c and examples/precomp2.c for a working example.
 195
 196
 197 How much can my data expand during compression ?
 198 ================================================
 199
 200 LZO will expand incompressible data by a little amount.
 201 I still haven't computed the exact values, but I suggest using
 202 these formulas for a worst-case expansion calculation:
 203
 204   Algorithm LZO1, LZO1A, LZO1B, LZO1C, LZO1F, LZO1X, LZO1Y, LZO1Z:
 205   ----------------------------------------------------------------
 206     output_block_size = input_block_size + (input_block_size / 16) + 64 + 3
 207
 208     [This is about 106% for a large block size.]
 209
 210   Algorithm LZO2A:
 211   ----------------
 212     output_block_size = input_block_size + (input_block_size / 8) + 128 + 3
 213