Annotation of /trunk/mkinitrd-magellan/busybox/archival/libunarchive/unxz/README


XZ Embedded
===========

    XZ Embedded is a relatively small, limited implementation of the .xz
    file format. Currently only decoding is implemented.

    XZ Embedded was written for use in the Linux kernel, but the code can
    be easily used in other environments too, including regular userspace
    applications.

    This README contains information that is useful only when the copy
    of XZ Embedded isn't part of the Linux kernel tree. You should also
    read linux/Documentation/xz.txt even if you aren't using XZ Embedded
    as part of Linux; information in that file is not repeated in this
    README.

Compiling the Linux kernel module

    The xz_dec module depends on crc32 module, so make sure that you have
    it enabled (CONFIG_CRC32).

    Building the xz_dec and xz_dec_test modules without support for BCJ
    filters:

        cd linux/lib/xz
        make -C /path/to/kernel/source \
                KCPPFLAGS=-I"$(pwd)/../../include" M="$(pwd)" \
                CONFIG_XZ_DEC=m CONFIG_XZ_DEC_TEST=m

    Building the xz_dec and xz_dec_test modules with support for BCJ
    filters:

        cd linux/lib/xz
        make -C /path/to/kernel/source \
                KCPPFLAGS=-I"$(pwd)/../../include" M="$(pwd)" \
                CONFIG_XZ_DEC=m CONFIG_XZ_DEC_TEST=m CONFIG_XZ_DEC_BCJ=y \
                CONFIG_XZ_DEC_X86=y CONFIG_XZ_DEC_POWERPC=y \
                CONFIG_XZ_DEC_IA64=y CONFIG_XZ_DEC_ARM=y \
                CONFIG_XZ_DEC_ARMTHUMB=y CONFIG_XZ_DEC_SPARC=y

    If you want only one or a few of the BCJ filters, omit the appropriate
    variables. CONFIG_XZ_DEC_BCJ=y is always required to build the support
    code shared between all BCJ filters.

    Most people don't need the xz_dec_test module. You can skip building
    it by omitting CONFIG_XZ_DEC_TEST=m from the make command line.

Compiler requirements

    XZ Embedded should compile as either GNU-C89 (used in the Linux
    kernel) or with any C99 compiler. Getting the code to compile with
    non-GNU C89 compiler or a C++ compiler should be quite easy as
    long as there is a data type for unsigned 64-bit integer (or the
    code is modified not to support large files, which needs some more
    care than just using 32-bit integer instead of 64-bit).

    If you use GCC, try to use a recent version. For example, on x86,
    xz_dec_lzma2.c compiled with GCC 3.3.6 is 15-25 % slower than when
    compiled with GCC 4.3.3.

Embedding into userspace applications

    To embed the XZ decoder, copy the following files into a single
    directory in your source code tree:

        linux/include/linux/xz.h
        linux/lib/xz/xz_crc32.c
        linux/lib/xz/xz_dec_lzma2.c
        linux/lib/xz/xz_dec_stream.c
        linux/lib/xz/xz_lzma2.h
        linux/lib/xz/xz_private.h
        linux/lib/xz/xz_stream.h
        userspace/xz_config.h

    Alternatively, xz.h may be placed into a different directory but then
    that directory must be in the compiler include path when compiling
    the .c files.

    Your code should use only the functions declared in xz.h. The rest of
    the .h files are meant only for internal use in XZ Embedded.

    You may want to modify xz_config.h to be more suitable for your build
    environment. Probably you should at least skim through it even if the
    default file works as is.

BCJ filter support

    If you want support for one or more BCJ filters, you need to copy also
    linux/lib/xz/xz_dec_bcj.c into your application, and use appropriate
    #defines in xz_config.h or in compiler flags. You don't need these
    #defines in the code that just uses XZ Embedded via xz.h, but having
    them always #defined doesn't hurt either.

        #define             Instruction set     BCJ filter endianness
        XZ_DEC_X86          x86 or x86-64       Little endian only
        XZ_DEC_POWERPC      PowerPC             Big endian only
        XZ_DEC_IA64         Itanium (IA-64)     Big or little endian
        XZ_DEC_ARM          ARM                 Little endian only
        XZ_DEC_ARMTHUMB     ARM-Thumb           Little endian only
        XZ_DEC_SPARC        SPARC               Big or little endian

    While some architectures are (partially) bi-endian, the endianness
    setting doesn't change the endianness of the instructions on all
    architectures. That's why Itanium and SPARC filters work for both big
    and little endian executables (Itanium has little endian instructions
    and SPARC has big endian instructions).

    There currently is no filter for little endian PowerPC or big endian
    ARM or ARM-Thumb. Implementing filters for them can be considered if
    there is a need for such filters in real-world applications.

Notes about shared libraries

    If you are including XZ Embedded into a shared library, you very
    probably should rename the xz_* functions to prevent symbol
    conflicts in case your library is linked against some other library
    or application that also has XZ Embedded in it (which may even be
    a different version of XZ Embedded). TODO: Provide an easy way
    to do this.

    Please don't create a shared library of XZ Embedded itself unless
    it is fine to rebuild everything depending on that shared library
    everytime you upgrade to a newer version of XZ Embedded. There are
    no API or ABI stability guarantees between different versions of
    XZ Embedded.

Specifying the calling convention

    XZ_FUNC macro was included to support declaring functions with __init
    in Linux. Outside Linux, it can be used to specify the calling
    convention on systems that support multiple calling conventions.
    For example, on Windows, you may make all functions use the stdcall
    calling convention by defining XZ_FUNC=__stdcall when building and
    using the functions from XZ Embedded.

1	niro	1123
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.
136