aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/filesystems
diff options
context:
space:
mode:
authorDavid Woodhouse <David.Woodhouse@intel.com>2008-10-13 12:13:56 -0400
committerDavid Woodhouse <David.Woodhouse@intel.com>2008-10-13 12:13:56 -0400
commite758936e02700ff88a0b08b722a3847b95283ef2 (patch)
tree50c919bef1b459a778b85159d5929de95b6c4a01 /Documentation/filesystems
parent239cfbde1f5843c4a24199f117d5f67f637d72d5 (diff)
parent4480f15b3306f43bbb0310d461142b4e897ca45b (diff)
Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6
Conflicts: include/asm-x86/statfs.h
Diffstat (limited to 'Documentation/filesystems')
-rw-r--r--Documentation/filesystems/Locking15
-rw-r--r--Documentation/filesystems/ext4.txt19
-rw-r--r--Documentation/filesystems/fiemap.txt228
-rw-r--r--Documentation/filesystems/ntfs.txt4
-rw-r--r--Documentation/filesystems/proc.txt88
5 files changed, 303 insertions, 51 deletions
diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking
index 680fb566b928..8362860e21a7 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/Locking
@@ -144,8 +144,8 @@ prototypes:
144 void (*kill_sb) (struct super_block *); 144 void (*kill_sb) (struct super_block *);
145locking rules: 145locking rules:
146 may block BKL 146 may block BKL
147get_sb yes yes 147get_sb yes no
148kill_sb yes yes 148kill_sb yes no
149 149
150->get_sb() returns error or 0 with locked superblock attached to the vfsmount 150->get_sb() returns error or 0 with locked superblock attached to the vfsmount
151(exclusive on ->s_umount). 151(exclusive on ->s_umount).
@@ -409,12 +409,12 @@ ioctl: yes (see below)
409unlocked_ioctl: no (see below) 409unlocked_ioctl: no (see below)
410compat_ioctl: no 410compat_ioctl: no
411mmap: no 411mmap: no
412open: maybe (see below) 412open: no
413flush: no 413flush: no
414release: no 414release: no
415fsync: no (see below) 415fsync: no (see below)
416aio_fsync: no 416aio_fsync: no
417fasync: yes (see below) 417fasync: no
418lock: yes 418lock: yes
419readv: no 419readv: no
420writev: no 420writev: no
@@ -431,13 +431,6 @@ For many filesystems, it is probably safe to acquire the inode
431semaphore. Note some filesystems (i.e. remote ones) provide no 431semaphore. Note some filesystems (i.e. remote ones) provide no
432protection for i_size so you will need to use the BKL. 432protection for i_size so you will need to use the BKL.
433 433
434->open() locking is in-transit: big lock partially moved into the methods.
435The only exception is ->open() in the instances of file_operations that never
436end up in ->i_fop/->proc_fops, i.e. ones that belong to character devices
437(chrdev_open() takes lock before replacing ->f_op and calling the secondary
438method. As soon as we fix the handling of module reference counters all
439instances of ->open() will be called without the BKL.
440
441Note: ext2_release() was *the* source of contention on fs-intensive 434Note: ext2_release() was *the* source of contention on fs-intensive
442loads and dropping BKL on ->release() helps to get rid of that (we still 435loads and dropping BKL on ->release() helps to get rid of that (we still
443grab BKL for cases when we close a file that had been opened r/w, but that 436grab BKL for cases when we close a file that had been opened r/w, but that
diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt
index 0d5394920a31..eb154ef36c2a 100644
--- a/Documentation/filesystems/ext4.txt
+++ b/Documentation/filesystems/ext4.txt
@@ -32,9 +32,9 @@ Mailing list: linux-ext4@vger.kernel.org
32 you will need to merge your changes with the version from e2fsprogs 32 you will need to merge your changes with the version from e2fsprogs
33 1.41.x. 33 1.41.x.
34 34
35 - Create a new filesystem using the ext4dev filesystem type: 35 - Create a new filesystem using the ext4 filesystem type:
36 36
37 # mke2fs -t ext4dev /dev/hda1 37 # mke2fs -t ext4 /dev/hda1
38 38
39 Or configure an existing ext3 filesystem to support extents and set 39 Or configure an existing ext3 filesystem to support extents and set
40 the test_fs flag to indicate that it's ok for an in-development 40 the test_fs flag to indicate that it's ok for an in-development
@@ -47,13 +47,13 @@ Mailing list: linux-ext4@vger.kernel.org
47 47
48 # tune2fs -I 256 /dev/hda1 48 # tune2fs -I 256 /dev/hda1
49 49
50 (Note: we currently do not have tools to convert an ext4dev 50 (Note: we currently do not have tools to convert an ext4
51 filesystem back to ext3; so please do not do try this on production 51 filesystem back to ext3; so please do not do try this on production
52 filesystems.) 52 filesystems.)
53 53
54 - Mounting: 54 - Mounting:
55 55
56 # mount -t ext4dev /dev/hda1 /wherever 56 # mount -t ext4 /dev/hda1 /wherever
57 57
58 - When comparing performance with other filesystems, remember that 58 - When comparing performance with other filesystems, remember that
59 ext3/4 by default offers higher data integrity guarantees than most. 59 ext3/4 by default offers higher data integrity guarantees than most.
@@ -177,6 +177,11 @@ barrier=<0|1(*)> This enables/disables the use of write barriers in
177 your disks are battery-backed in one way or another, 177 your disks are battery-backed in one way or another,
178 disabling barriers may safely improve performance. 178 disabling barriers may safely improve performance.
179 179
180inode_readahead=n This tuning parameter controls the maximum
181 number of inode table blocks that ext4's inode
182 table readahead algorithm will pre-read into
183 the buffer cache. The default value is 32 blocks.
184
180orlov (*) This enables the new Orlov block allocator. It is 185orlov (*) This enables the new Orlov block allocator. It is
181 enabled by default. 186 enabled by default.
182 187
@@ -218,6 +223,11 @@ errors=remount-ro(*) Remount the filesystem read-only on an error.
218errors=continue Keep going on a filesystem error. 223errors=continue Keep going on a filesystem error.
219errors=panic Panic and halt the machine if an error occurs. 224errors=panic Panic and halt the machine if an error occurs.
220 225
226data_err=ignore(*) Just print an error message if an error occurs
227 in a file data buffer in ordered mode.
228data_err=abort Abort the journal if an error occurs in a file
229 data buffer in ordered mode.
230
221grpid Give objects the same group ID as their creator. 231grpid Give objects the same group ID as their creator.
222bsdgroups 232bsdgroups
223 233
@@ -252,6 +262,7 @@ stripe=n Number of filesystem blocks that mballoc will try
252delalloc (*) Deferring block allocation until write-out time. 262delalloc (*) Deferring block allocation until write-out time.
253nodelalloc Disable delayed allocation. Blocks are allocation 263nodelalloc Disable delayed allocation. Blocks are allocation
254 when data is copied from user to page cache. 264 when data is copied from user to page cache.
265
255Data Mode 266Data Mode
256========= 267=========
257There are 3 different data modes: 268There are 3 different data modes:
diff --git a/Documentation/filesystems/fiemap.txt b/Documentation/filesystems/fiemap.txt
new file mode 100644
index 000000000000..1e3defcfe50b
--- /dev/null
+++ b/Documentation/filesystems/fiemap.txt
@@ -0,0 +1,228 @@
1============
2Fiemap Ioctl
3============
4
5The fiemap ioctl is an efficient method for userspace to get file
6extent mappings. Instead of block-by-block mapping (such as bmap), fiemap
7returns a list of extents.
8
9
10Request Basics
11--------------
12
13A fiemap request is encoded within struct fiemap:
14
15struct fiemap {
16 __u64 fm_start; /* logical offset (inclusive) at
17 * which to start mapping (in) */
18 __u64 fm_length; /* logical length of mapping which
19 * userspace cares about (in) */
20 __u32 fm_flags; /* FIEMAP_FLAG_* flags for request (in/out) */
21 __u32 fm_mapped_extents; /* number of extents that were
22 * mapped (out) */
23 __u32 fm_extent_count; /* size of fm_extents array (in) */
24 __u32 fm_reserved;
25 struct fiemap_extent fm_extents[0]; /* array of mapped extents (out) */
26};
27
28
29fm_start, and fm_length specify the logical range within the file
30which the process would like mappings for. Extents returned mirror
31those on disk - that is, the logical offset of the 1st returned extent
32may start before fm_start, and the range covered by the last returned
33extent may end after fm_length. All offsets and lengths are in bytes.
34
35Certain flags to modify the way in which mappings are looked up can be
36set in fm_flags. If the kernel doesn't understand some particular
37flags, it will return EBADR and the contents of fm_flags will contain
38the set of flags which caused the error. If the kernel is compatible
39with all flags passed, the contents of fm_flags will be unmodified.
40It is up to userspace to determine whether rejection of a particular
41flag is fatal to it's operation. This scheme is intended to allow the
42fiemap interface to grow in the future but without losing
43compatibility with old software.
44
45fm_extent_count specifies the number of elements in the fm_extents[] array
46that can be used to return extents. If fm_extent_count is zero, then the
47fm_extents[] array is ignored (no extents will be returned), and the
48fm_mapped_extents count will hold the number of extents needed in
49fm_extents[] to hold the file's current mapping. Note that there is
50nothing to prevent the file from changing between calls to FIEMAP.
51
52The following flags can be set in fm_flags:
53
54* FIEMAP_FLAG_SYNC
55If this flag is set, the kernel will sync the file before mapping extents.
56
57* FIEMAP_FLAG_XATTR
58If this flag is set, the extents returned will describe the inodes
59extended attribute lookup tree, instead of it's data tree.
60
61
62Extent Mapping
63--------------
64
65Extent information is returned within the embedded fm_extents array
66which userspace must allocate along with the fiemap structure. The
67number of elements in the fiemap_extents[] array should be passed via
68fm_extent_count. The number of extents mapped by kernel will be
69returned via fm_mapped_extents. If the number of fiemap_extents
70allocated is less than would be required to map the requested range,
71the maximum number of extents that can be mapped in the fm_extent[]
72array will be returned and fm_mapped_extents will be equal to
73fm_extent_count. In that case, the last extent in the array will not
74complete the requested range and will not have the FIEMAP_EXTENT_LAST
75flag set (see the next section on extent flags).
76
77Each extent is described by a single fiemap_extent structure as
78returned in fm_extents.
79
80struct fiemap_extent {
81 __u64 fe_logical; /* logical offset in bytes for the start of
82 * the extent */
83 __u64 fe_physical; /* physical offset in bytes for the start
84 * of the extent */
85 __u64 fe_length; /* length in bytes for the extent */
86 __u64 fe_reserved64[2];
87 __u32 fe_flags; /* FIEMAP_EXTENT_* flags for this extent */
88 __u32 fe_reserved[3];
89};
90
91All offsets and lengths are in bytes and mirror those on disk. It is valid
92for an extents logical offset to start before the request or it's logical
93length to extend past the request. Unless FIEMAP_EXTENT_NOT_ALIGNED is
94returned, fe_logical, fe_physical, and fe_length will be aligned to the
95block size of the file system. With the exception of extents flagged as
96FIEMAP_EXTENT_MERGED, adjacent extents will not be merged.
97
98The fe_flags field contains flags which describe the extent returned.
99A special flag, FIEMAP_EXTENT_LAST is always set on the last extent in
100the file so that the process making fiemap calls can determine when no
101more extents are available, without having to call the ioctl again.
102
103Some flags are intentionally vague and will always be set in the
104presence of other more specific flags. This way a program looking for
105a general property does not have to know all existing and future flags
106which imply that property.
107
108For example, if FIEMAP_EXTENT_DATA_INLINE or FIEMAP_EXTENT_DATA_TAIL
109are set, FIEMAP_EXTENT_NOT_ALIGNED will also be set. A program looking
110for inline or tail-packed data can key on the specific flag. Software
111which simply cares not to try operating on non-aligned extents
112however, can just key on FIEMAP_EXTENT_NOT_ALIGNED, and not have to
113worry about all present and future flags which might imply unaligned
114data. Note that the opposite is not true - it would be valid for
115FIEMAP_EXTENT_NOT_ALIGNED to appear alone.
116
117* FIEMAP_EXTENT_LAST
118This is the last extent in the file. A mapping attempt past this
119extent will return nothing.
120
121* FIEMAP_EXTENT_UNKNOWN
122The location of this extent is currently unknown. This may indicate
123the data is stored on an inaccessible volume or that no storage has
124been allocated for the file yet.
125
126* FIEMAP_EXTENT_DELALLOC
127 - This will also set FIEMAP_EXTENT_UNKNOWN.
128Delayed allocation - while there is data for this extent, it's
129physical location has not been allocated yet.
130
131* FIEMAP_EXTENT_ENCODED
132This extent does not consist of plain filesystem blocks but is
133encoded (e.g. encrypted or compressed). Reading the data in this
134extent via I/O to the block device will have undefined results.
135
136Note that it is *always* undefined to try to update the data
137in-place by writing to the indicated location without the
138assistance of the filesystem, or to access the data using the
139information returned by the FIEMAP interface while the filesystem
140is mounted. In other words, user applications may only read the
141extent data via I/O to the block device while the filesystem is
142unmounted, and then only if the FIEMAP_EXTENT_ENCODED flag is
143clear; user applications must not try reading or writing to the
144filesystem via the block device under any other circumstances.
145
146* FIEMAP_EXTENT_DATA_ENCRYPTED
147 - This will also set FIEMAP_EXTENT_ENCODED
148The data in this extent has been encrypted by the file system.
149
150* FIEMAP_EXTENT_NOT_ALIGNED
151Extent offsets and length are not guaranteed to be block aligned.
152
153* FIEMAP_EXTENT_DATA_INLINE
154 This will also set FIEMAP_EXTENT_NOT_ALIGNED
155Data is located within a meta data block.
156
157* FIEMAP_EXTENT_DATA_TAIL
158 This will also set FIEMAP_EXTENT_NOT_ALIGNED
159Data is packed into a block with data from other files.
160
161* FIEMAP_EXTENT_UNWRITTEN
162Unwritten extent - the extent is allocated but it's data has not been
163initialized. This indicates the extent's data will be all zero if read
164through the filesystem but the contents are undefined if read directly from
165the device.
166
167* FIEMAP_EXTENT_MERGED
168This will be set when a file does not support extents, i.e., it uses a block
169based addressing scheme. Since returning an extent for each block back to
170userspace would be highly inefficient, the kernel will try to merge most
171adjacent blocks into 'extents'.
172
173
174VFS -> File System Implementation
175---------------------------------
176
177File systems wishing to support fiemap must implement a ->fiemap callback on
178their inode_operations structure. The fs ->fiemap call is responsible for
179defining it's set of supported fiemap flags, and calling a helper function on
180each discovered extent:
181
182struct inode_operations {
183 ...
184
185 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start,
186 u64 len);
187
188->fiemap is passed struct fiemap_extent_info which describes the
189fiemap request:
190
191struct fiemap_extent_info {
192 unsigned int fi_flags; /* Flags as passed from user */
193 unsigned int fi_extents_mapped; /* Number of mapped extents */
194 unsigned int fi_extents_max; /* Size of fiemap_extent array */
195 struct fiemap_extent *fi_extents_start; /* Start of fiemap_extent array */
196};
197
198It is intended that the file system should not need to access any of this
199structure directly.
200
201
202Flag checking should be done at the beginning of the ->fiemap callback via the
203fiemap_check_flags() helper:
204
205int fiemap_check_flags(struct fiemap_extent_info *fieinfo, u32 fs_flags);
206
207The struct fieinfo should be passed in as recieved from ioctl_fiemap(). The
208set of fiemap flags which the fs understands should be passed via fs_flags. If
209fiemap_check_flags finds invalid user flags, it will place the bad values in
210fieinfo->fi_flags and return -EBADR. If the file system gets -EBADR, from
211fiemap_check_flags(), it should immediately exit, returning that error back to
212ioctl_fiemap().
213
214
215For each extent in the request range, the file system should call
216the helper function, fiemap_fill_next_extent():
217
218int fiemap_fill_next_extent(struct fiemap_extent_info *info, u64 logical,
219 u64 phys, u64 len, u32 flags, u32 dev);
220
221fiemap_fill_next_extent() will use the passed values to populate the
222next free extent in the fm_extents array. 'General' extent flags will
223automatically be set from specific flags on behalf of the calling file
224system so that the userspace API is not broken.
225
226fiemap_fill_next_extent() returns 0 on success, and 1 when the
227user-supplied fm_extents array is full. If an error is encountered
228while copying the extent to user memory, -EFAULT will be returned.
diff --git a/Documentation/filesystems/ntfs.txt b/Documentation/filesystems/ntfs.txt
index e79ee2db183a..ac2a261c5f7d 100644
--- a/Documentation/filesystems/ntfs.txt
+++ b/Documentation/filesystems/ntfs.txt
@@ -40,7 +40,7 @@ Web site
40======== 40========
41 41
42There is plenty of additional information on the linux-ntfs web site 42There is plenty of additional information on the linux-ntfs web site
43at http://linux-ntfs.sourceforge.net/ 43at http://www.linux-ntfs.org/
44 44
45The web site has a lot of additional information, such as a comprehensive 45The web site has a lot of additional information, such as a comprehensive
46FAQ, documentation on the NTFS on-disk format, information on the Linux-NTFS 46FAQ, documentation on the NTFS on-disk format, information on the Linux-NTFS
@@ -272,7 +272,7 @@ And you would know that /dev/hda2 has a size of 37768814 - 4209030 + 1 =
272For Win2k and later dynamic disks, you can for example use the ldminfo utility 272For Win2k and later dynamic disks, you can for example use the ldminfo utility
273which is part of the Linux LDM tools (the latest version at the time of 273which is part of the Linux LDM tools (the latest version at the time of
274writing is linux-ldm-0.0.8.tar.bz2). You can download it from: 274writing is linux-ldm-0.0.8.tar.bz2). You can download it from:
275 http://linux-ntfs.sourceforge.net/downloads.html 275 http://www.linux-ntfs.org/
276Simply extract the downloaded archive (tar xvjf linux-ldm-0.0.8.tar.bz2), go 276Simply extract the downloaded archive (tar xvjf linux-ldm-0.0.8.tar.bz2), go
277into it (cd linux-ldm-0.0.8) and change to the test directory (cd test). You 277into it (cd linux-ldm-0.0.8) and change to the test directory (cd test). You
278will find the precompiled (i386) ldminfo utility there. NOTE: You will not be 278will find the precompiled (i386) ldminfo utility there. NOTE: You will not be
diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt
index 64557821ee59..d831d24d2a6c 100644
--- a/Documentation/filesystems/proc.txt
+++ b/Documentation/filesystems/proc.txt
@@ -923,45 +923,44 @@ CPUs.
923The "procs_blocked" line gives the number of processes currently blocked, 923The "procs_blocked" line gives the number of processes currently blocked,
924waiting for I/O to complete. 924waiting for I/O to complete.
925 925
926
9261.9 Ext4 file system parameters 9271.9 Ext4 file system parameters
927------------------------------ 928------------------------------
928Ext4 file system have one directory per partition under /proc/fs/ext4/
929# ls /proc/fs/ext4/hdc/
930group_prealloc max_to_scan mb_groups mb_history min_to_scan order2_req
931stats stream_req
932
933mb_groups:
934This file gives the details of multiblock allocator buddy cache of free blocks
935
936mb_history:
937Multiblock allocation history.
938
939stats:
940This file indicate whether the multiblock allocator should start collecting
941statistics. The statistics are shown during unmount
942 929
943group_prealloc: 930Information about mounted ext4 file systems can be found in
944The multiblock allocator normalize the block allocation request to 931/proc/fs/ext4. Each mounted filesystem will have a directory in
945group_prealloc filesystem blocks if we don't have strip value set. 932/proc/fs/ext4 based on its device name (i.e., /proc/fs/ext4/hdc or
946The stripe value can be specified at mount time or during mke2fs. 933/proc/fs/ext4/dm-0). The files in each per-device directory are shown
934in Table 1-10, below.
947 935
948max_to_scan: 936Table 1-10: Files in /proc/fs/ext4/<devname>
949How long multiblock allocator can look for a best extent (in found extents) 937..............................................................................
950 938 File Content
951min_to_scan: 939 mb_groups details of multiblock allocator buddy cache of free blocks
952How long multiblock allocator must look for a best extent 940 mb_history multiblock allocation history
953 941 stats controls whether the multiblock allocator should start
954order2_req: 942 collecting statistics, which are shown during the unmount
955Multiblock allocator use 2^N search using buddies only for requests greater 943 group_prealloc the multiblock allocator will round up allocation
956than or equal to order2_req. The request size is specfied in file system 944 requests to a multiple of this tuning parameter if the
957blocks. A value of 2 indicate only if the requests are greater than or equal 945 stripe size is not set in the ext4 superblock
958to 4 blocks. 946 max_to_scan The maximum number of extents the multiblock allocator
947 will search to find the best extent
948 min_to_scan The minimum number of extents the multiblock allocator
949 will search to find the best extent
950 order2_req Tuning parameter which controls the minimum size for
951 requests (as a power of 2) where the buddy cache is
952 used
953 stream_req Files which have fewer blocks than this tunable
954 parameter will have their blocks allocated out of a
955 block group specific preallocation pool, so that small
956 files are packed closely together. Each large file
957 will have its blocks allocated out of its own unique
958 preallocation pool.
959inode_readahead Tuning parameter which controls the maximum number of
960 inode table blocks that ext4's inode table readahead
961 algorithm will pre-read into the buffer cache
962..............................................................................
959 963
960stream_req:
961Files smaller than stream_req are served by the stream allocator, whose
962purpose is to pack requests as close each to other as possible to
963produce smooth I/O traffic. Avalue of 16 indicate that file smaller than 16
964filesystem block size will use group based preallocation.
965 964
966------------------------------------------------------------------------------ 965------------------------------------------------------------------------------
967Summary 966Summary
@@ -1339,6 +1338,25 @@ Enables/Disables the protection of the per-process proc entries "maps" and
1339"smaps". When enabled, the contents of these files are visible only to 1338"smaps". When enabled, the contents of these files are visible only to
1340readers that are allowed to ptrace() the given process. 1339readers that are allowed to ptrace() the given process.
1341 1340
1341msgmni
1342------
1343
1344Maximum number of message queue ids on the system.
1345This value scales to the amount of lowmem. It is automatically recomputed
1346upon memory add/remove or ipc namespace creation/removal.
1347When a value is written into this file, msgmni's value becomes fixed, i.e. it
1348is not recomputed anymore when one of the above events occurs.
1349Use auto_msgmni to change this behavior.
1350
1351auto_msgmni
1352-----------
1353
1354Enables/Disables automatic recomputing of msgmni upon memory add/remove or
1355upon ipc namespace creation/removal (see the msgmni description above).
1356Echoing "1" into this file enables msgmni automatic recomputing.
1357Echoing "0" turns it off.
1358auto_msgmni default value is 1.
1359
1342 1360
13432.4 /proc/sys/vm - The virtual memory subsystem 13612.4 /proc/sys/vm - The virtual memory subsystem
1344----------------------------------------------- 1362-----------------------------------------------
@@ -2394,6 +2412,8 @@ The following 4 memory types are supported:
2394 - (bit 1) anonymous shared memory 2412 - (bit 1) anonymous shared memory
2395 - (bit 2) file-backed private memory 2413 - (bit 2) file-backed private memory
2396 - (bit 3) file-backed shared memory 2414 - (bit 3) file-backed shared memory
2415 - (bit 4) ELF header pages in file-backed private memory areas (it is
2416 effective only if the bit 2 is cleared)
2397 2417
2398 Note that MMIO pages such as frame buffer are never dumped and vDSO pages 2418 Note that MMIO pages such as frame buffer are never dumped and vDSO pages
2399 are always dumped regardless of the bitmask status. 2419 are always dumped regardless of the bitmask status.