Merge tag 'media/v4.19-2' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab...
[linux-2.6-block.git] / Documentation / filesystems / squashfs.txt
CommitLineData
9eb425c0
PL
1SQUASHFS 4.0 FILESYSTEM
2=======================
3
4Squashfs is a compressed read-only filesystem for Linux.
62421645
PL
5It uses zlib, lz4, lzo, or xz compression to compress files, inodes and
6directories. Inodes in the system are very small and all blocks are packed to
7minimise data overhead. Block sizes greater than 4K are supported up to a
8maximum of 1Mbytes (default block size 128K).
9eb425c0
PL
9
10Squashfs is intended for general read-only filesystem use, for archival
11use (i.e. in cases where a .tar.gz file may be used), and in constrained
12block device/memory systems (e.g. embedded systems) where low overhead is
13needed.
14
15Mailing list: squashfs-devel@lists.sourceforge.net
16Web site: www.squashfs.org
17
181. FILESYSTEM FEATURES
19----------------------
20
21Squashfs filesystem features versus Cramfs:
22
23 Squashfs Cramfs
24
edf2e281 25Max filesystem size: 2^64 256 MiB
9eb425c0
PL
26Max file size: ~ 2 TiB 16 MiB
27Max files: unlimited unlimited
28Max directories: unlimited unlimited
29Max entries per directory: unlimited unlimited
30Max block size: 1 MiB 4 KiB
31Metadata compression: yes no
32Directory indexes: yes no
33Sparse file support: yes no
34Tail-end packing (fragments): yes no
35Exportable (NFS etc.): yes no
36Hard link support: yes no
37"." and ".." in readdir: yes no
38Real inode numbers: yes no
3932-bit uids/gids: yes no
40File creation time: yes no
899f4530
PL
41Xattr support: yes no
42ACL support: no no
9eb425c0
PL
43
44Squashfs compresses data, inodes and directories. In addition, inode and
45directory data are highly compacted, and packed on byte boundaries. Each
46compressed inode is on average 8 bytes in length (the exact length varies on
47file type, i.e. regular file, directory, symbolic link, and block/char device
48inodes have different sizes).
49
502. USING SQUASHFS
51-----------------
52
53As squashfs is a read-only filesystem, the mksquashfs program must be used to
54create populated squashfs filesystems. This and other squashfs utilities
55can be obtained from http://www.squashfs.org. Usage instructions can be
56obtained from this site also.
57
812753d6
PL
58The squashfs-tools development tree is now located on kernel.org
59 git://git.kernel.org/pub/scm/fs/squashfs/squashfs-tools.git
9eb425c0
PL
60
613. SQUASHFS FILESYSTEM DESIGN
62-----------------------------
63
4c1d204c
PL
64A squashfs filesystem consists of a maximum of nine parts, packed together on a
65byte alignment:
9eb425c0
PL
66
67 ---------------
68 | superblock |
69 |---------------|
4c1d204c
PL
70 | compression |
71 | options |
72 |---------------|
9eb425c0
PL
73 | datablocks |
74 | & fragments |
75 |---------------|
76 | inode table |
77 |---------------|
78 | directory |
79 | table |
80 |---------------|
81 | fragment |
82 | table |
83 |---------------|
84 | export |
85 | table |
86 |---------------|
87 | uid/gid |
88 | lookup table |
899f4530
PL
89 |---------------|
90 | xattr |
91 | table |
9eb425c0
PL
92 ---------------
93
94Compressed data blocks are written to the filesystem as files are read from
95the source directory, and checked for duplicates. Once all file data has been
89cab5b5
PL
96written the completed inode, directory, fragment, export, uid/gid lookup and
97xattr tables are written.
9eb425c0 98
4c1d204c
PL
993.1 Compression options
100-----------------------
101
102Compressors can optionally support compression specific options (e.g.
103dictionary size). If non-default compression options have been used, then
104these are stored here.
105
1063.2 Inodes
9eb425c0
PL
107----------
108
109Metadata (inodes and directories) are compressed in 8Kbyte blocks. Each
110compressed block is prefixed by a two byte length, the top bit is set if the
111block is uncompressed. A block will be uncompressed if the -noI option is set,
112or if the compressed block was larger than the uncompressed block.
113
114Inodes are packed into the metadata blocks, and are not aligned to block
115boundaries, therefore inodes overlap compressed blocks. Inodes are identified
116by a 48-bit number which encodes the location of the compressed metadata block
117containing the inode, and the byte offset into that block where the inode is
118placed (<block, offset>).
119
120To maximise compression there are different inodes for each file type
121(regular file, directory, device, etc.), the inode contents and length
122varying with the type.
123
124To further maximise compression, two types of regular file inode and
125directory inode are defined: inodes optimised for frequently occurring
126regular files and directories, and extended types where extra
127information has to be stored.
128
4c1d204c 1293.3 Directories
9eb425c0
PL
130---------------
131
132Like inodes, directories are packed into compressed metadata blocks, stored
133in a directory table. Directories are accessed using the start address of
134the metablock containing the directory and the offset into the
135decompressed block (<block, offset>).
136
137Directories are organised in a slightly complex way, and are not simply
138a list of file names. The organisation takes advantage of the
139fact that (in most cases) the inodes of the files will be in the same
140compressed metadata block, and therefore, can share the start block.
141Directories are therefore organised in a two level list, a directory
142header containing the shared start block value, and a sequence of directory
143entries, each of which share the shared start block. A new directory header
144is written once/if the inode start block changes. The directory
145header/directory entry list is repeated as many times as necessary.
146
147Directories are sorted, and can contain a directory index to speed up
148file lookup. Directory indexes store one entry per metablock, each entry
149storing the index/filename mapping to the first directory header
150in each metadata block. Directories are sorted in alphabetical order,
151and at lookup the index is scanned linearly looking for the first filename
152alphabetically larger than the filename being looked up. At this point the
153location of the metadata block the filename is in has been found.
89cab5b5 154The general idea of the index is to ensure only one metadata block needs to be
9eb425c0
PL
155decompressed to do a lookup irrespective of the length of the directory.
156This scheme has the advantage that it doesn't require extra memory overhead
157and doesn't require much extra storage on disk.
158
4c1d204c 1593.4 File data
9eb425c0
PL
160-------------
161
162Regular files consist of a sequence of contiguous compressed blocks, and/or a
163compressed fragment block (tail-end packed block). The compressed size
164of each datablock is stored in a block list contained within the
165file inode.
166
167To speed up access to datablocks when reading 'large' files (256 Mbytes or
168larger), the code implements an index cache that caches the mapping from
169block index to datablock location on disk.
170
171The index cache allows Squashfs to handle large files (up to 1.75 TiB) while
172retaining a simple and space-efficient block list on disk. The cache
173is split into slots, caching up to eight 224 GiB files (128 KiB blocks).
174Larger files use multiple slots, with 1.75 TiB files using all 8 slots.
175The index cache is designed to be memory efficient, and by default uses
17616 KiB.
177
4c1d204c 1783.5 Fragment lookup table
9eb425c0
PL
179-------------------------
180
181Regular files can contain a fragment index which is mapped to a fragment
182location on disk and compressed size using a fragment lookup table. This
183fragment lookup table is itself stored compressed into metadata blocks.
184A second index table is used to locate these. This second index table for
185speed of access (and because it is small) is read at mount time and cached
186in memory.
187
4c1d204c 1883.6 Uid/gid lookup table
9eb425c0
PL
189------------------------
190
191For space efficiency regular files store uid and gid indexes, which are
192converted to 32-bit uids/gids using an id look up table. This table is
193stored compressed into metadata blocks. A second index table is used to
194locate these. This second index table for speed of access (and because it
195is small) is read at mount time and cached in memory.
196
4c1d204c 1973.7 Export table
9eb425c0
PL
198----------------
199
200To enable Squashfs filesystems to be exportable (via NFS etc.) filesystems
201can optionally (disabled with the -no-exports Mksquashfs option) contain
202an inode number to inode disk location lookup table. This is required to
203enable Squashfs to map inode numbers passed in filehandles to the inode
204location on disk, which is necessary when the export code reinstantiates
205expired/flushed inodes.
206
207This table is stored compressed into metadata blocks. A second index table is
208used to locate these. This second index table for speed of access (and because
209it is small) is read at mount time and cached in memory.
210
4c1d204c 2113.8 Xattr table
899f4530
PL
212---------------
213
214The xattr table contains extended attributes for each inode. The xattrs
215for each inode are stored in a list, each list entry containing a type,
216name and value field. The type field encodes the xattr prefix
217("user.", "trusted." etc) and it also encodes how the name/value fields
218should be interpreted. Currently the type indicates whether the value
219is stored inline (in which case the value field contains the xattr value),
220or if it is stored out of line (in which case the value field stores a
221reference to where the actual value is stored). This allows large values
222to be stored out of line improving scanning and lookup performance and it
223also allows values to be de-duplicated, the value being stored once, and
25985edc 224all other occurrences holding an out of line reference to that value.
899f4530
PL
225
226The xattr lists are packed into compressed 8K metadata blocks.
227To reduce overhead in inodes, rather than storing the on-disk
228location of the xattr list inside each inode, a 32-bit xattr id
229is stored. This xattr id is mapped into the location of the xattr
230list using a second xattr id lookup table.
9eb425c0
PL
231
2324. TODOS AND OUTSTANDING ISSUES
233-------------------------------
234
2354.1 Todo list
236-------------
237
899f4530 238Implement ACL support.
9eb425c0
PL
239
2404.2 Squashfs internal cache
241---------------------------
242
243Blocks in Squashfs are compressed. To avoid repeatedly decompressing
244recently accessed data Squashfs uses two small metadata and fragment caches.
245
246The cache is not used for file datablocks, these are decompressed and cached in
247the page-cache in the normal way. The cache is used to temporarily cache
248fragment and metadata blocks which have been read as a result of a metadata
249(i.e. inode or directory) or fragment access. Because metadata and fragments
250are packed together into blocks (to gain greater compression) the read of a
251particular piece of metadata or fragment will retrieve other metadata/fragments
252which have been packed with it, these because of locality-of-reference may be
253read in the near future. Temporarily caching them ensures they are available
254for near future access without requiring an additional read and decompress.
255
256In the future this internal cache may be replaced with an implementation which
257uses the kernel page cache. Because the page cache operates on page sized
258units this may introduce additional complexity in terms of locking and
259associated race conditions.