The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/contrib/xz-embedded/

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

Name Size Last modified (GMT) Description
Back Parent directory 2019-04-21 12:38:34
Folder freebsd/ 2019-04-21 12:38:33
Folder linux/ 2019-04-21 12:38:33
Folder userspace/ 2019-04-21 12:38:33
File COPYING 322 bytes 2019-04-21 12:38:33
File README 7085 bytes 2019-04-21 12:38:33

    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. See userspace/xzminidec.c for an example program.
   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-32,
   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 Integrity check support
   88 
   89     XZ Embedded always supports the integrity check types None and
   90     CRC32. Support for CRC64 is optional. SHA-256 is currently not
   91     supported in XZ Embedded although the .xz format does support it.
   92     The xz tool from XZ Utils uses CRC64 by default, but CRC32 is usually
   93     enough in embedded systems to keep the code size smaller.
   94 
   95     If you want support for CRC64, you need to copy linux/lib/xz/xz_crc64.c
   96     into your application, and #define XZ_USE_CRC64 in xz_config.h or in
   97     compiler flags.
   98 
   99     When using the internal CRC32 or CRC64, their lookup tables need to be
  100     initialized with xz_crc32_init() and xz_crc64_init(), respectively.
  101     See xz.h for details.
  102 
  103     To use external CRC32 or CRC64 code instead of the code from
  104     xz_crc32.c or xz_crc64.c, the following #defines may be used
  105     in xz_config.h or in compiler flags:
  106 
  107         #define XZ_INTERNAL_CRC32 0
  108         #define XZ_INTERNAL_CRC64 0
  109 
  110     Then it is up to you to provide compatible xz_crc32() or xz_crc64()
  111     functions.
  112 
  113     If the .xz file being decompressed uses an integrity check type that
  114     isn't supported by XZ Embedded, it is treated as an error and the
  115     file cannot be decompressed. For multi-call mode, this can be modified
  116     by #defining XZ_DEC_ANY_CHECK. Then xz_dec_run() will return
  117     XZ_UNSUPPORTED_CHECK when unsupported check type is detected. After
  118     that decompression can be continued normally except that the
  119     integrity check won't be verified. In single-call mode there's
  120     no way to continue decoding, so XZ_DEC_ANY_CHECK is almost useless
  121     in single-call mode.
  122 
  123 BCJ filter support
  124 
  125     If you want support for one or more BCJ filters, you need to copy also
  126     linux/lib/xz/xz_dec_bcj.c into your application, and use appropriate
  127     #defines in xz_config.h or in compiler flags. You don't need these
  128     #defines in the code that just uses XZ Embedded via xz.h, but having
  129     them always #defined doesn't hurt either.
  130 
  131         #define             Instruction set     BCJ filter endianness
  132         XZ_DEC_X86          x86-32 or x86-64    Little endian only
  133         XZ_DEC_POWERPC      PowerPC             Big endian only
  134         XZ_DEC_IA64         Itanium (IA-64)     Big or little endian
  135         XZ_DEC_ARM          ARM                 Little endian only
  136         XZ_DEC_ARMTHUMB     ARM-Thumb           Little endian only
  137         XZ_DEC_SPARC        SPARC               Big or little endian
  138 
  139     While some architectures are (partially) bi-endian, the endianness
  140     setting doesn't change the endianness of the instructions on all
  141     architectures. That's why Itanium and SPARC filters work for both big
  142     and little endian executables (Itanium has little endian instructions
  143     and SPARC has big endian instructions).
  144 
  145     There currently is no filter for little endian PowerPC or big endian
  146     ARM or ARM-Thumb. Implementing filters for them can be considered if
  147     there is a need for such filters in real-world applications.
  148 
  149 Notes about shared libraries
  150 
  151     If you are including XZ Embedded into a shared library, you very
  152     probably should rename the xz_* functions to prevent symbol
  153     conflicts in case your library is linked against some other library
  154     or application that also has XZ Embedded in it (which may even be
  155     a different version of XZ Embedded). TODO: Provide an easy way
  156     to do this.
  157 
  158     Please don't create a shared library of XZ Embedded itself unless
  159     it is fine to rebuild everything depending on that shared library
  160     everytime you upgrade to a newer version of XZ Embedded. There are
  161     no API or ABI stability guarantees between different versions of
  162     XZ Embedded.
  163 

[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.