3
0

README 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  1. XZ Embedded
  2. ===========
  3. XZ Embedded is a relatively small, limited implementation of the .xz
  4. file format. Currently only decoding is implemented.
  5. XZ Embedded was written for use in the Linux kernel, but the code can
  6. be easily used in other environments too, including regular userspace
  7. applications. See userspace/xzminidec.c for an example program.
  8. This README contains information that is useful only when the copy
  9. of XZ Embedded isn't part of the Linux kernel tree. You should also
  10. read linux/Documentation/xz.txt even if you aren't using XZ Embedded
  11. as part of Linux; information in that file is not repeated in this
  12. README.
  13. Compiling the Linux kernel module
  14. The xz_dec module depends on crc32 module, so make sure that you have
  15. it enabled (CONFIG_CRC32).
  16. Building the xz_dec and xz_dec_test modules without support for BCJ
  17. filters:
  18. cd linux/lib/xz
  19. make -C /path/to/kernel/source \
  20. KCPPFLAGS=-I"$(pwd)/../../include" M="$(pwd)" \
  21. CONFIG_XZ_DEC=m CONFIG_XZ_DEC_TEST=m
  22. Building the xz_dec and xz_dec_test modules with support for BCJ
  23. filters:
  24. cd linux/lib/xz
  25. make -C /path/to/kernel/source \
  26. KCPPFLAGS=-I"$(pwd)/../../include" M="$(pwd)" \
  27. CONFIG_XZ_DEC=m CONFIG_XZ_DEC_TEST=m CONFIG_XZ_DEC_BCJ=y \
  28. CONFIG_XZ_DEC_X86=y CONFIG_XZ_DEC_POWERPC=y \
  29. CONFIG_XZ_DEC_IA64=y CONFIG_XZ_DEC_ARM=y \
  30. CONFIG_XZ_DEC_ARMTHUMB=y CONFIG_XZ_DEC_SPARC=y
  31. If you want only one or a few of the BCJ filters, omit the appropriate
  32. variables. CONFIG_XZ_DEC_BCJ=y is always required to build the support
  33. code shared between all BCJ filters.
  34. Most people don't need the xz_dec_test module. You can skip building
  35. it by omitting CONFIG_XZ_DEC_TEST=m from the make command line.
  36. Compiler requirements
  37. XZ Embedded should compile as either GNU-C89 (used in the Linux
  38. kernel) or with any C99 compiler. Getting the code to compile with
  39. non-GNU C89 compiler or a C++ compiler should be quite easy as
  40. long as there is a data type for unsigned 64-bit integer (or the
  41. code is modified not to support large files, which needs some more
  42. care than just using 32-bit integer instead of 64-bit).
  43. If you use GCC, try to use a recent version. For example, on x86-32,
  44. xz_dec_lzma2.c compiled with GCC 3.3.6 is 15-25 % slower than when
  45. compiled with GCC 4.3.3.
  46. Embedding into userspace applications
  47. To embed the XZ decoder, copy the following files into a single
  48. directory in your source code tree:
  49. linux/include/linux/xz.h
  50. linux/lib/xz/xz_crc32.c
  51. linux/lib/xz/xz_dec_lzma2.c
  52. linux/lib/xz/xz_dec_stream.c
  53. linux/lib/xz/xz_lzma2.h
  54. linux/lib/xz/xz_private.h
  55. linux/lib/xz/xz_stream.h
  56. userspace/xz_config.h
  57. Alternatively, xz.h may be placed into a different directory but then
  58. that directory must be in the compiler include path when compiling
  59. the .c files.
  60. Your code should use only the functions declared in xz.h. The rest of
  61. the .h files are meant only for internal use in XZ Embedded.
  62. You may want to modify xz_config.h to be more suitable for your build
  63. environment. Probably you should at least skim through it even if the
  64. default file works as is.
  65. BCJ filter support
  66. If you want support for one or more BCJ filters, you need to copy also
  67. linux/lib/xz/xz_dec_bcj.c into your application, and use appropriate
  68. #defines in xz_config.h or in compiler flags. You don't need these
  69. #defines in the code that just uses XZ Embedded via xz.h, but having
  70. them always #defined doesn't hurt either.
  71. #define Instruction set BCJ filter endianness
  72. XZ_DEC_X86 x86-32 or x86-64 Little endian only
  73. XZ_DEC_POWERPC PowerPC Big endian only
  74. XZ_DEC_IA64 Itanium (IA-64) Big or little endian
  75. XZ_DEC_ARM ARM Little endian only
  76. XZ_DEC_ARMTHUMB ARM-Thumb Little endian only
  77. XZ_DEC_SPARC SPARC Big or little endian
  78. While some architectures are (partially) bi-endian, the endianness
  79. setting doesn't change the endianness of the instructions on all
  80. architectures. That's why Itanium and SPARC filters work for both big
  81. and little endian executables (Itanium has little endian instructions
  82. and SPARC has big endian instructions).
  83. There currently is no filter for little endian PowerPC or big endian
  84. ARM or ARM-Thumb. Implementing filters for them can be considered if
  85. there is a need for such filters in real-world applications.
  86. Notes about shared libraries
  87. If you are including XZ Embedded into a shared library, you very
  88. probably should rename the xz_* functions to prevent symbol
  89. conflicts in case your library is linked against some other library
  90. or application that also has XZ Embedded in it (which may even be
  91. a different version of XZ Embedded). TODO: Provide an easy way
  92. to do this.
  93. Please don't create a shared library of XZ Embedded itself unless
  94. it is fine to rebuild everything depending on that shared library
  95. everytime you upgrade to a newer version of XZ Embedded. There are
  96. no API or ABI stability guarantees between different versions of
  97. XZ Embedded.
  98. Specifying the calling convention
  99. XZ_FUNC macro was included to support declaring functions with __init
  100. in Linux. Outside Linux, it can be used to specify the calling
  101. convention on systems that support multiple calling conventions.
  102. For example, on Windows, you may make all functions use the stdcall
  103. calling convention by defining XZ_FUNC=__stdcall when building and
  104. using the functions from XZ Embedded.