add lvds1024*800

hc

2024-01-31 f70575805708cabdedea7498aaa3f710fde4d920

 kernel/Documentation/filesystems/index.rst
..
..
@@ -1,362 +1,122 @@
1
-=====================
2
-Linux Filesystems API
3
-=====================
1
+.. _filesystems_index:
4
2
 
5
-The Linux VFS
6
-=============
3
+===============================
4
+Filesystems in the Linux kernel
5
+===============================
7
6
 
8
-The Filesystem types
9
---------------------
7
+This under-development manual will, some glorious day, provide
8
+comprehensive information on how the Linux virtual filesystem (VFS) layer
9
+works, along with the filesystems that sit below it.  For now, what we have
10
+can be found below.
10
11
 
11
-.. kernel-doc:: include/linux/fs.h
12
-   :internal:
13
-
14
-The Directory Cache
15
--------------------
16
-
17
-.. kernel-doc:: fs/dcache.c
18
-   :export:
19
-
20
-.. kernel-doc:: include/linux/dcache.h
21
-   :internal:
22
-
23
-Inode Handling
24
---------------
25
-
26
-.. kernel-doc:: fs/inode.c
27
-   :export:
28
-
29
-.. kernel-doc:: fs/bad_inode.c
30
-   :export:
31
-
32
-Registration and Superblocks
33
-----------------------------
34
-
35
-.. kernel-doc:: fs/super.c
36
-   :export:
37
-
38
-File Locks
39
-----------
40
-
41
-.. kernel-doc:: fs/locks.c
42
-   :export:
43
-
44
-.. kernel-doc:: fs/locks.c
45
-   :internal:
46
-
47
-Other Functions
48
----------------
49
-
50
-.. kernel-doc:: fs/mpage.c
51
-   :export:
52
-
53
-.. kernel-doc:: fs/namei.c
54
-   :export:
55
-
56
-.. kernel-doc:: fs/buffer.c
57
-   :export:
58
-
59
-.. kernel-doc:: block/bio.c
60
-   :export:
61
-
62
-.. kernel-doc:: fs/seq_file.c
63
-   :export:
64
-
65
-.. kernel-doc:: fs/filesystems.c
66
-   :export:
67
-
68
-.. kernel-doc:: fs/fs-writeback.c
69
-   :export:
70
-
71
-.. kernel-doc:: fs/block_dev.c
72
-   :export:
73
-
74
-.. kernel-doc:: fs/anon_inodes.c
75
-   :export:
76
-
77
-.. kernel-doc:: fs/attr.c
78
-   :export:
79
-
80
-.. kernel-doc:: fs/d_path.c
81
-   :export:
82
-
83
-.. kernel-doc:: fs/dax.c
84
-   :export:
85
-
86
-.. kernel-doc:: fs/direct-io.c
87
-   :export:
88
-
89
-.. kernel-doc:: fs/file_table.c
90
-   :export:
91
-
92
-.. kernel-doc:: fs/libfs.c
93
-   :export:
94
-
95
-.. kernel-doc:: fs/posix_acl.c
96
-   :export:
97
-
98
-.. kernel-doc:: fs/stat.c
99
-   :export:
100
-
101
-.. kernel-doc:: fs/sync.c
102
-   :export:
103
-
104
-.. kernel-doc:: fs/xattr.c
105
-   :export:
106
-
107
-The proc filesystem
108
-===================
109
-
110
-sysctl interface
111
-----------------
112
-
113
-.. kernel-doc:: kernel/sysctl.c
114
-   :export:
115
-
116
-proc filesystem interface
117
--------------------------
118
-
119
-.. kernel-doc:: fs/proc/base.c
120
-   :internal:
121
-
122
-Events based on file descriptors
123
-================================
124
-
125
-.. kernel-doc:: fs/eventfd.c
126
-   :export:
127
-
128
-The Filesystem for Exporting Kernel Objects
129
-===========================================
130
-
131
-.. kernel-doc:: fs/sysfs/file.c
132
-   :export:
133
-
134
-.. kernel-doc:: fs/sysfs/symlink.c
135
-   :export:
136
-
137
-The debugfs filesystem
12
+Core VFS documentation
138
13
 ======================
139
14
 
140
-debugfs interface
141
------------------
142
-
143
-.. kernel-doc:: fs/debugfs/inode.c
144
-   :export:
145
-
146
-.. kernel-doc:: fs/debugfs/file.c
147
-   :export:
148
-
149
-The Linux Journalling API
150
-=========================
151
-
152
-Overview
153
---------
154
-
155
-Details
156
-~~~~~~~
157
-
158
-The journalling layer is easy to use. You need to first of all create a
159
-journal_t data structure. There are two calls to do this dependent on
160
-how you decide to allocate the physical media on which the journal
161
-resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
162
-filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
163
-for journal stored on a raw device (in a continuous range of blocks). A
164
-journal_t is a typedef for a struct pointer, so when you are finally
165
-finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
166
-any used kernel memory.
167
-
168
-Once you have got your journal_t object you need to 'mount' or load the
169
-journal file. The journalling layer expects the space for the journal
170
-was already allocated and initialized properly by the userspace tools.
171
-When loading the journal you must call :c:func:`jbd2_journal_load` to process
172
-journal contents. If the client file system detects the journal contents
173
-does not need to be processed (or even need not have valid contents), it
174
-may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
175
-calling :c:func:`jbd2_journal_load`.
176
-
177
-Note that jbd2_journal_wipe(..,0) calls
178
-:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
179
-transactions in the journal and similarly :c:func:`jbd2_journal_load` will
180
-call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
181
-:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
182
-
183
-Now you can go ahead and start modifying the underlying filesystem.
184
-Almost.
185
-
186
-You still need to actually journal your filesystem changes, this is done
187
-by wrapping them into transactions. Additionally you also need to wrap
188
-the modification of each of the buffers with calls to the journal layer,
189
-so it knows what the modifications you are actually making are. To do
190
-this use :c:func:`jbd2_journal_start` which returns a transaction handle.
191
-
192
-:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
193
-which indicates the end of a transaction are nestable calls, so you can
194
-reenter a transaction if necessary, but remember you must call
195
-:c:func:`jbd2_journal_stop` the same number of times as
196
-:c:func:`jbd2_journal_start` before the transaction is completed (or more
197
-accurately leaves the update phase). Ext4/VFS makes use of this feature to
198
-simplify handling of inode dirtying, quota support, etc.
199
-
200
-Inside each transaction you need to wrap the modifications to the
201
-individual buffers (blocks). Before you start to modify a buffer you
202
-need to call :c:func:`jbd2_journal_get_create_access()` /
203
-:c:func:`jbd2_journal_get_write_access()` /
204
-:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
205
-journalling layer to copy the unmodified
206
-data if it needs to. After all the buffer may be part of a previously
207
-uncommitted transaction. At this point you are at last ready to modify a
208
-buffer, and once you are have done so you need to call
209
-:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
210
-buffer you now know is now longer required to be pushed back on the
211
-device you can call :c:func:`jbd2_journal_forget` in much the same way as you
212
-might have used :c:func:`bforget` in the past.
213
-
214
-A :c:func:`jbd2_journal_flush` may be called at any time to commit and
215
-checkpoint all your transactions.
216
-
217
-Then at umount time , in your :c:func:`put_super` you can then call
218
-:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
219
-
220
-Unfortunately there a couple of ways the journal layer can cause a
221
-deadlock. The first thing to note is that each task can only have a
222
-single outstanding transaction at any one time, remember nothing commits
223
-until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
224
-the transaction at the end of each file/inode/address etc. operation you
225
-perform, so that the journalling system isn't re-entered on another
226
-journal. Since transactions can't be nested/batched across differing
227
-journals, and another filesystem other than yours (say ext4) may be
228
-modified in a later syscall.
229
-
230
-The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
231
-if there isn't enough space in the journal for your transaction (based
232
-on the passed nblocks param) - when it blocks it merely(!) needs to wait
233
-for transactions to complete and be committed from other tasks, so
234
-essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
235
-deadlocks you must treat :c:func:`jbd2_journal_start` /
236
-:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
237
-your semaphore ordering rules to prevent
238
-deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
239
-behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
240
-easily as on :c:func:`jbd2_journal_start`.
241
-
242
-Try to reserve the right number of blocks the first time. ;-). This will
243
-be the maximum number of blocks you are going to touch in this
244
-transaction. I advise having a look at at least ext4_jbd.h to see the
245
-basis on which ext4 uses to make these decisions.
246
-
247
-Another wriggle to watch out for is your on-disk block allocation
248
-strategy. Why? Because, if you do a delete, you need to ensure you
249
-haven't reused any of the freed blocks until the transaction freeing
250
-these blocks commits. If you reused these blocks and crash happens,
251
-there is no way to restore the contents of the reallocated blocks at the
252
-end of the last fully committed transaction. One simple way of doing
253
-this is to mark blocks as free in internal in-memory block allocation
254
-structures only after the transaction freeing them commits. Ext4 uses
255
-journal commit callback for this purpose.
256
-
257
-With journal commit callbacks you can ask the journalling layer to call
258
-a callback function when the transaction is finally committed to disk,
259
-so that you can do some of your own management. You ask the journalling
260
-layer for calling the callback by simply setting
261
-``journal->j_commit_callback`` function pointer and that function is
262
-called after each transaction commit. You can also use
263
-``transaction->t_private_list`` for attaching entries to a transaction
264
-that need processing when the transaction commits.
265
-
266
-JBD2 also provides a way to block all transaction updates via
267
-:c:func:`jbd2_journal_lock_updates()` /
268
-:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
269
-window with a clean and stable fs for a moment. E.g.
270
-
271
-::
272
-
273
-
274
-        jbd2_journal_lock_updates() //stop new stuff happening..
275
-        jbd2_journal_flush()        // checkpoint everything.
276
-        ..do stuff on stable fs
277
-        jbd2_journal_unlock_updates() // carry on with filesystem use.
278
-
279
-The opportunities for abuse and DOS attacks with this should be obvious,
280
-if you allow unprivileged userspace to trigger codepaths containing
281
-these calls.
282
-
283
-Summary
284
-~~~~~~~
285
-
286
-Using the journal is a matter of wrapping the different context changes,
287
-being each mount, each modification (transaction) and each changed
288
-buffer to tell the journalling layer about them.
289
-
290
-Data Types
291
-----------
292
-
293
-The journalling layer uses typedefs to 'hide' the concrete definitions
294
-of the structures used. As a client of the JBD2 layer you can just rely
295
-on the using the pointer as a magic cookie of some sort. Obviously the
296
-hiding is not enforced as this is 'C'.
297
-
298
-Structures
299
-~~~~~~~~~~
300
-
301
-.. kernel-doc:: include/linux/jbd2.h
302
-   :internal:
303
-
304
-Functions
305
----------
306
-
307
-The functions here are split into two groups those that affect a journal
308
-as a whole, and those which are used to manage transactions
309
-
310
-Journal Level
311
-~~~~~~~~~~~~~
312
-
313
-.. kernel-doc:: fs/jbd2/journal.c
314
-   :export:
315
-
316
-.. kernel-doc:: fs/jbd2/recovery.c
317
-   :internal:
318
-
319
-Transasction Level
320
-~~~~~~~~~~~~~~~~~~
321
-
322
-.. kernel-doc:: fs/jbd2/transaction.c
323
-
324
-See also
325
---------
326
-
327
-`Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen
328
-Tweedie <http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz>`__
329
-
330
-`Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
331
-Tweedie <http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html>`__
332
-
333
-splice API
334
-==========
335
-
336
-splice is a method for moving blocks of data around inside the kernel,
337
-without continually transferring them between the kernel and user space.
338
-
339
-.. kernel-doc:: fs/splice.c
340
-
341
-pipes API
342
-=========
343
-
344
-Pipe interfaces are all for in-kernel (builtin image) use. They are not
345
-exported for use by modules.
346
-
347
-.. kernel-doc:: include/linux/pipe_fs_i.h
348
-   :internal:
349
-
350
-.. kernel-doc:: fs/pipe.c
351
-
352
-Encryption API
353
-==============
354
-
355
-A library which filesystems can hook into to support transparent
356
-encryption of files and directories.
15
+See these manuals for documentation about the VFS layer itself and how its
16
+algorithms work.
357
17
 
358
18
 .. toctree::
359
-    :maxdepth: 2
19
+   :maxdepth: 2
360
20
 
361
-    fscrypt
362
-    fsverity
21
+   vfs
22
+   path-lookup
23
+   api-summary
24
+   splice
25
+   locking
26
+   directory-locking
27
+   devpts
28
+   dnotify
29
+   fiemap
30
+   files
31
+   locks
32
+   mandatory-locking
33
+   mount_api
34
+   quota
35
+   seq_file
36
+   sharedsubtree
37
+
38
+   automount-support
39
+
40
+   caching/index
41
+
42
+   porting
43
+
44
+Filesystem support layers
45
+=========================
46
+
47
+Documentation for the support code within the filesystem layer for use in
48
+filesystem implementations.
49
+
50
+.. toctree::
51
+   :maxdepth: 2
52
+
53
+   journalling
54
+   fscrypt
55
+   fsverity
56
+
57
+Filesystems
58
+===========
59
+
60
+Documentation for filesystem implementations.
61
+
62
+.. toctree::
63
+   :maxdepth: 2
64
+
65
+   9p
66
+   adfs
67
+   affs
68
+   afs
69
+   autofs
70
+   autofs-mount-control
71
+   befs
72
+   bfs
73
+   btrfs
74
+   cifs/cifsroot
75
+   ceph
76
+   coda
77
+   configfs
78
+   cramfs
79
+   debugfs
80
+   dlmfs
81
+   ecryptfs
82
+   efivarfs
83
+   erofs
84
+   ext2
85
+   ext3
86
+   f2fs
87
+   gfs2
88
+   gfs2-uevents
89
+   gfs2-glocks
90
+   hfs
91
+   hfsplus
92
+   hpfs
93
+   fuse
94
+   fuse-io
95
+   inotify
96
+   isofs
97
+   nilfs2
98
+   nfs/index
99
+   ntfs
100
+   ocfs2
101
+   ocfs2-online-filecheck
102
+   omfs
103
+   orangefs
104
+   overlayfs
105
+   proc
106
+   qnx6
107
+   ramfs-rootfs-initramfs
108
+   relay
109
+   romfs
110
+   spufs/index
111
+   squashfs
112
+   sysfs
113
+   sysv-fs
114
+   tmpfs
115
+   ubifs
116
+   ubifs-authentication.rst
117
+   udf
118
+   virtiofs
119
+   vfat
120
+   xfs-delayed-logging-design
121
+   xfs-self-describing-metadata
122
+   zonefs