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