iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

It's a somewhat calmer cycle for docs this time, as the churn of the mass

Browse Source 
RST conversion is happily mostly behind us.
 
  - A new document on reproducible builds.
 
  - We finally got around to zapping the documentation for hardware support
    that was removed in 2004; one doesn't want to rush these things.
 
  - The usual assortment of fixes, typo corrections, etc.
 
 You'll still find a handful of annoying conflicts against other trees,
 mostly tied to the last RST conversions; resolutions are straightforward
 and the linux-next ones are good.
 -----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCAAdFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl1/J4IACgkQF0NaE2wM
 flhYogf9EgYozCe8RocSq+JjJpZOSFjIGDQv+GwTjOBIdqgO9tSIaY/p0wSkYKil
 jYXyMDF+Xwr8podsUep2F7akBM7j9XJ+XBGJcfOna0ypC9xoejMgWt9fU3YvaWge
 dQJxIQ/iwkDlKNx6uOYgKysLUWFS0EP/nzPhqBo4bZZzhugvrR46D/nQqFNmGihd
 l9yLalJtP5mC0XRUv3hpdAFFFKxdC0R3BGOel2V+slSClp0LEgpdMAuMaKydEDI3
 Ch9ZpIp8fB8kqONCs9/X6083WRsDOMe28KgeGrGHo4Jla6u51QBLQjSVKttFv7xk
 051yNJwDWMxgl+A4gyNLDPXM7Gd7HQ==
 =v4dp
 -----END PGP SIGNATURE-----

Merge tag 'docs-5.4' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "It's a somewhat calmer cycle for docs this time, as the churn of the
  mass RST conversion is happily mostly behind us.

   - A new document on reproducible builds.

   - We finally got around to zapping the documentation for hardware
     support that was removed in 2004; one doesn't want to rush these
     things.

   - The usual assortment of fixes, typo corrections, etc"

* tag 'docs-5.4' of git://git.lwn.net/linux: (67 commits)
  Documentation: kbuild: Add document about reproducible builds
  docs: printk-formats: Stop encouraging use of unnecessary %h[xudi] and %hh[xudi]
  Documentation: Add "earlycon=sbi" to the admin guide
  doc🔒 remove reference to clever use of read-write lock
  devices.txt: improve entry for comedi (char major 98)
  docs: mtd: Update spi nor reference driver
  doc: arm64: fix grammar dtb placed in no attributes region
  Documentation: sysrq: don't recommend 'S' 'U' before 'B'
  mailmap: Update email address for Quentin Perret
  docs: ftrace: clarify when tracing is disabled by the trace file
  docs: process: fix broken link
  Documentation/arm/samsung-s3c24xx: Remove stray U+FEFF character to fix title
  Documentation/arm/sa1100/assabet: Fix 'make assabet_defconfig' command
  Documentation/arm/sa1100: Remove some obsolete documentation
  docs/zh_CN: update Chinese howto.rst for latexdocs making
  Documentation: virt: Fix broken reference to virt tree's index
  docs: Fix typo on pull requests guide
  kernel-doc: Allow anonymous enum
  Documentation: sphinx: Don't parse socket() as identifier reference
  Documentation: sphinx: Add missing comma to list of strings
  ...
This commit is contained in:
Linus Torvalds 2019-09-17 16:22:26 -07:00
commit 7c672abc12
249 changed files with 5159 additions and 3953 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
.mailmap
View File

@ -47,6 +47,8 @@ Boris Brezillon <bbrezillon@kernel.org> <b.brezillon.dev@gmail.com>
Boris Brezillon <bbrezillon@kernel.org> <b.brezillon@overkiz.com>
Brian Avery <b.avery@hp.com>
Brian King <brking@us.ibm.com>
Chao Yu <chao@kernel.org> <chao2.yu@samsung.com>
Chao Yu <chao@kernel.org> <yuchao0@huawei.com>
Christoph Hellwig <hch@lst.de>
Christophe Ricard <christophe.ricard@gmail.com>
Corey Minyard <minyard@acm.org>
@ -80,6 +82,8 @@ Frank Rowand <frowand.list@gmail.com> <frowand@mvista.com>
Frank Rowand <frowand.list@gmail.com> <frank.rowand@am.sony.com>
Frank Rowand <frowand.list@gmail.com> <frank.rowand@sonymobile.com>
Frank Zago <fzago@systemfabricworks.com>
Gao Xiang <xiang@kernel.org> <gaoxiang25@huawei.com>
Gao Xiang <xiang@kernel.org> <hsiangkao@aol.com>
Greg Kroah-Hartman <greg@echidna.(none)>
Greg Kroah-Hartman <gregkh@suse.de>
Greg Kroah-Hartman <greg@kroah.com>
@ -90,6 +94,9 @@ Henrik Kretzschmar <henne@nachtwindheim.de>
Henrik Rydberg <rydberg@bitmath.org>
Herbert Xu <herbert@gondor.apana.org.au>
Jacob Shin <Jacob.Shin@amd.com>
Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@google.com>
Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk@motorola.com>
Jaegeuk Kim <jaegeuk@kernel.org> <jaegeuk.kim@samsung.com>
James Bottomley <jejb@mulgrave.(none)>
James Bottomley <jejb@titanic.il.steeleye.com>
James E Wilson <wilson@specifix.com>
@ -181,6 +188,11 @@ Nguyen Anh Quynh <aquynh@gmail.com>
Nicolas Ferre <nicolas.ferre@microchip.com> <nicolas.ferre@atmel.com>
Nicolas Pitre <nico@fluxnic.net> <nicolas.pitre@linaro.org>
Nicolas Pitre <nico@fluxnic.net> <nico@linaro.org>
Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
Paolo 'Blaisorblade' Giarrusso <blaisorblade@yahoo.it>
Patrick Mochel <mochel@digitalimplant.org>
Paul Burton <paul.burton@mips.com> <paul.burton@imgtec.com>
@ -191,11 +203,7 @@ Pratyush Anand <pratyush.anand@gmail.com> <pratyush.anand@st.com>
Praveen BP <praveenbp@ti.com>
Punit Agrawal <punitagrawal@gmail.com> <punit.agrawal@arm.com>
Qais Yousef <qsyousef@gmail.com> <qais.yousef@imgtec.com>
Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>
Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>
Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>
Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>
Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>
Quentin Perret <qperret@qperret.net> <quentin.perret@arm.com>
Rajesh Shah <rajesh.shah@intel.com>
Ralf Baechle <ralf@linux-mips.org>
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
@ -230,6 +238,7 @@ Sumit Semwal <sumit.semwal@ti.com>
Tejun Heo <htejun@gmail.com>
Thomas Graf <tgraf@suug.ch>
Thomas Pedersen <twp@codeaurora.org>
Todor Tomov <todor.too@gmail.com> <todor.tomov@linaro.org>
Tony Luck <tony.luck@intel.com>
TripleX Chung <xxx.phy@gmail.com> <zhongyu@18mail.cn>
TripleX Chung <xxx.phy@gmail.com> <triplex@zh-kernel.org>

2
Documentation/ABI/stable/sysfs-bus-w1
View File

@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component.
control systems are attached/generate presence for as short as
100 ms - hence the tens-to-hundreds milliseconds scan intervals
are required.
see Documentation/w1/w1.generic for detailed information.
see Documentation/w1/w1-generic.rst for detailed information.
Users: any user space application which wants to know bus scanning
interval

4
Documentation/ABI/stable/sysfs-driver-w1_ds28e04
View File

@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
see Documentation/w1/slaves/w1_ds28e04 for detailed information
see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
see Documentation/w1/slaves/w1_ds28e04 for detailed information
see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100

2
Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
View File

@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq
Date: Apr 2015
Contact: Matt Campbell <mattrcampbell@gmail.com>
Description: Support for the DS28EA00 chain sequence function
see Documentation/w1/slaves/w1_therm for detailed information
see Documentation/w1/slaves/w1_therm.rst for detailed information
Users: any user space application which wants to communicate with DS28EA00

98
Documentation/admin-guide/auxdisplay/cfag12864b.rst Normal file
View File

@ -0,0 +1,98 @@
===================================
cfag12864b LCD Driver Documentation
===================================
:License: GPLv2
:Author & Maintainer: Miguel Ojeda Sandonis
:Date: 2006-10-27
.. INDEX
1. DRIVER INFORMATION
2. DEVICE INFORMATION
3. WIRING
4. USERSPACE PROGRAMMING
1. Driver Information
---------------------
This driver supports a cfag12864b LCD.
2. Device Information
---------------------
:Manufacturer: Crystalfontz
:Device Name: Crystalfontz 12864b LCD Series
:Device Code: cfag12864b
:Webpage: http://www.crystalfontz.com
:Device Webpage: http://www.crystalfontz.com/products/12864b/
:Type: LCD (Liquid Crystal Display)
:Width: 128
:Height: 64
:Colors: 2 (B/N)
:Controller: ks0108
:Controllers: 2
:Pages: 8 each controller
:Addresses: 64 each page
:Data size: 1 byte each address
:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
3. Wiring
---------
The cfag12864b LCD Series don't have official wiring.
The common wiring is done to the parallel port as shown::
Parallel Port cfag12864b
Name Pin# Pin# Name
Strobe ( 1)------------------------------(17) Enable
Data 0 ( 2)------------------------------( 4) Data 0
Data 1 ( 3)------------------------------( 5) Data 1
Data 2 ( 4)------------------------------( 6) Data 2
Data 3 ( 5)------------------------------( 7) Data 3
Data 4 ( 6)------------------------------( 8) Data 4
Data 5 ( 7)------------------------------( 9) Data 5
Data 6 ( 8)------------------------------(10) Data 6
Data 7 ( 9)------------------------------(11) Data 7
(10) [+5v]---( 1) Vdd
(11) [GND]---( 2) Ground
(12) [+5v]---(14) Reset
(13) [GND]---(15) Read / Write
Line (14)------------------------------(13) Controller Select 1
(15)
Init (16)------------------------------(12) Controller Select 2
Select (17)------------------------------(16) Data / Instruction
Ground (18)---[GND] [+5v]---(19) LED +
Ground (19)---[GND]
Ground (20)---[GND] E A Values:
Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
Ground (22)---[GND] | - P1 = Preset = 10 Kohm
Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
Ground (24)---[GND] | |
Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
4. Userspace Programming
------------------------
The cfag12864bfb describes a framebuffer device (/dev/fbX).
It has a size of 1024 bytes = 1 Kbyte.
Each bit represents one pixel. If the bit is high, the pixel will
turn on. If the pixel is low, the pixel will turn off.
You can use the framebuffer as a file: fopen, fwrite, fclose...
Although the LCD won't get updated until the next refresh time arrives.
Also, you can mmap the framebuffer: open & mmap, munmap & close...
which is the best option for most uses.
Check samples/auxdisplay/cfag12864b-example.c
for a real working userspace complete program with usage examples.

16
Documentation/admin-guide/auxdisplay/index.rst Normal file
View File

@ -0,0 +1,16 @@
=========================
Auxiliary Display Support
=========================
.. toctree::
:maxdepth: 1
ks0108.rst
cfag12864b.rst
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

50
Documentation/admin-guide/auxdisplay/ks0108.rst Normal file
View File

@ -0,0 +1,50 @@
==========================================
ks0108 LCD Controller Driver Documentation
==========================================
:License: GPLv2
:Author & Maintainer: Miguel Ojeda Sandonis
:Date: 2006-10-27
.. INDEX
1. DRIVER INFORMATION
2. DEVICE INFORMATION
3. WIRING
1. Driver Information
---------------------
This driver supports the ks0108 LCD controller.
2. Device Information
---------------------
:Manufacturer: Samsung
:Device Name: KS0108 LCD Controller
:Device Code: ks0108
:Webpage: -
:Device Webpage: -
:Type: LCD Controller (Liquid Crystal Display Controller)
:Width: 64
:Height: 64
:Colors: 2 (B/N)
:Pages: 8
:Addresses: 64 each page
:Data size: 1 byte each address
:Memory size: 8 * 64 * 1 = 512 bytes
3. Wiring
---------
The driver supports data parallel port wiring.
If you aren't building LCD related hardware, you should check
your LCD specific wiring information in the same folder.
For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst

6
Documentation/admin-guide/cgroup-v1/blkio-controller.rst
View File

@ -130,12 +130,6 @@ Proportional weight policy files
dev weight
8:16 300
- blkio.leaf_weight[_device]
- Equivalents of blkio.weight[_device] for the purpose of
deciding how much weight tasks in the given cgroup has while
competing with the cgroup's child cgroups. For details,
please refer to Documentation/block/cfq-iosched.txt.
- blkio.time
- disk time allocated to cgroup per device in milliseconds. First
two fields specify the major and minor number of the device and

64
Documentation/filesystems/cifs/AUTHORS → Documentation/admin-guide/cifs/authors.rst
View File

@ -1,5 +1,10 @@
=======
Authors
=======
Original Author
===============
---------------
Steve French (sfrench@samba.org)
The author wishes to express his appreciation and thanks to:
@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
for proving years ago that very good smb/cifs clients could be done on Unix-like
operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
Newbigin and others for their work on the Linux smbfs module. Thanks to
the other members of the Storage Network Industry Association CIFS Technical
Workgroup for their work specifying this highly complex protocol and finally
@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
Patch Contributors
------------------
Zwane Mwaikambo
Andi Kleen
Amrut Joshi
Shobhit Dayal
Sergey Vlasov
Richard Hughes
Yury Umanets
Mark Hamzy (for some of the early cifs IPv6 work)
Domen Puncer
Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
Vince Negri and Dave Stahl (for finding an important caching bug)
Adrian Bunk (kcalloc cleanups)
Miklos Szeredi
Kazeon team for various fixes especially for 2.4 version.
Asser Ferno (Change Notify support)
Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
Gunter Kukkukk (testing and suggestions for support of old servers)
Igor Mammedov (DFS support)
Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
Scott Lovenberg
Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
Shirish Pargaonkar (for many ACL patches over the years)
Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
Paulo Alcantara
Long Li (some great work on RDMA, SMB Direct)
- Zwane Mwaikambo
- Andi Kleen
- Amrut Joshi
- Shobhit Dayal
- Sergey Vlasov
- Richard Hughes
- Yury Umanets
- Mark Hamzy (for some of the early cifs IPv6 work)
- Domen Puncer
- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
- Vince Negri and Dave Stahl (for finding an important caching bug)
- Adrian Bunk (kcalloc cleanups)
- Miklos Szeredi
- Kazeon team for various fixes especially for 2.4 version.
- Asser Ferno (Change Notify support)
- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
- Gunter Kukkukk (testing and suggestions for support of old servers)
- Igor Mammedov (DFS support)
- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
- Scott Lovenberg
- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
- Shirish Pargaonkar (for many ACL patches over the years)
- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
- Paulo Alcantara
- Long Li (some great work on RDMA, SMB Direct)
Test case and Bug Report contributors

4
Documentation/filesystems/cifs/CHANGES → Documentation/admin-guide/cifs/changes.rst
View File

@ -1,3 +1,7 @@
=======
Changes
=======
See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
information (that may be easier to read than parsing the output of
"git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes

21
Documentation/admin-guide/cifs/index.rst Normal file
View File

@ -0,0 +1,21 @@
.. SPDX-License-Identifier: GPL-2.0
====
CIFS
====
.. toctree::
:maxdepth: 2
introduction
usage
todo
changes
authors
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

8
Documentation/filesystems/cifs/cifs.txt → Documentation/admin-guide/cifs/introduction.rst
View File

@ -1,3 +1,7 @@
============
Introduction
============
This is the client VFS module for the SMB3 NAS protocol as well
as for older dialects such as the Common Internet File System (CIFS)
protocol which was the successor to the Server Message Block
@ -33,7 +37,9 @@
tools (including smbinfo and setcifsacl) that can be obtained from
https://git.samba.org/?p=cifs-utils.git
or
git://git.samba.org/cifs-utils.git
mount.cifs should be installed in the directory with the other mount helpers.
@ -41,5 +47,7 @@
For more information on the module see the project wiki page at
https://wiki.samba.org/index.php/LinuxCIFS
and
https://wiki.samba.org/index.php/LinuxCIFS_utils

96
Documentation/filesystems/cifs/TODO → Documentation/admin-guide/cifs/todo.rst
View File

@ -1,3 +1,7 @@
====
TODO
====
Version 2.14 December 21, 2018
A Partial List of Missing Features
@ -8,55 +12,58 @@ for visible, important contributions to this module. Here
is a partial list of the known problems and missing features:
a) SMB3 (and SMB3.1.1) missing optional features:
- multichannel (started), integration with RDMA
- directory leases (improved metadata caching), started (root dir only)
- T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
currently the only two server side copy mechanisms supported)
b) improved sparse file support (fiemap and SEEK_HOLE are implemented
but additional features would be supportable by the protocol).
but additional features would be supportable by the protocol).
c) Directory entry caching relies on a 1 second timer, rather than
using Directory Leases, currently only the root file handle is cached longer
using Directory Leases, currently only the root file handle is cached longer
d) quota support (needs minor kernel change since quota calls
to make it to network filesystems or deviceless filesystems)
to make it to network filesystems or deviceless filesystems)
e) Additional use cases can be optimized to use "compounding"
(e.g. open/query/close and open/setinfo/close) to reduce the number
of roundtrips to the server and improve performance. Various cases
(stat, statfs, create, unlink, mkdir) already have been improved by
using compounding but more can be done. In addition we could significantly
reduce redundant opens by using deferred close (with handle caching leases)
and better using reference counters on file handles.
e) Additional use cases can be optimized to use "compounding" (e.g.
open/query/close and open/setinfo/close) to reduce the number of
roundtrips to the server and improve performance. Various cases
(stat, statfs, create, unlink, mkdir) already have been improved by
using compounding but more can be done. In addition we could
significantly reduce redundant opens by using deferred close (with
handle caching leases) and better using reference counters on file
handles.
f) Finish inotify support so kde and gnome file list windows
will autorefresh (partially complete by Asser). Needs minor kernel
vfs change to support removing D_NOTIFY on a file.
will autorefresh (partially complete by Asser). Needs minor kernel
vfs change to support removing D_NOTIFY on a file.
g) Add GUI tool to configure /proc/fs/cifs settings and for display of
the CIFS statistics (started)
the CIFS statistics (started)
h) implement support for security and trusted categories of xattrs
(requires minor protocol extension) to enable better support for SELINUX
(requires minor protocol extension) to enable better support for SELINUX
i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
feature (may be especially useful for virtualization).
j) Create UID mapping facility so server UIDs can be mapped on a per
mount or a per server basis to client UIDs or nobody if no mapping
exists. Also better integration with winbind for resolving SID owners
mount or a per server basis to client UIDs or nobody if no mapping
exists. Also better integration with winbind for resolving SID owners
k) Add tools to take advantage of more smb3 specific ioctls and features
(passthrough ioctl/fsctl is now implemented in cifs.ko to allow sending
various SMB3 fsctls and query info and set info calls directly from user space)
Add tools to make setting various non-POSIX metadata attributes easier
from tools (e.g. extending what was done in smb-info tool).
(passthrough ioctl/fsctl is now implemented in cifs.ko to allow
sending various SMB3 fsctls and query info and set info calls
directly from user space) Add tools to make setting various non-POSIX
metadata attributes easier from tools (e.g. extending what was done
in smb-info tool).
l) encrypted file support
m) improved stats gathering tools (perhaps integration with nfsometer?)
to extend and make easier to use what is currently in /proc/fs/cifs/Stats
to extend and make easier to use what is currently in /proc/fs/cifs/Stats
n) Add support for claims based ACLs ("DAC")
@ -69,57 +76,58 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
different servers, and the server we are connected to has gone down.
q) Allow mount.cifs to be more verbose in reporting errors with dialect
or unsupported feature errors.
or unsupported feature errors.
r) updating cifs documentation, and user guide.
s) Addressing bugs found by running a broader set of xfstests in standard
file system xfstest suite.
file system xfstest suite.
t) split cifs and smb3 support into separate modules so legacy (and less
secure) CIFS dialect can be disabled in environments that don't need it
and simplify the code.
secure) CIFS dialect can be disabled in environments that don't need it
and simplify the code.
v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
so far).
so far).
w) Add support for additional strong encryption types, and additional spnego
authentication mechanisms (see MS-SMB2)
authentication mechanisms (see MS-SMB2)
x) Finish support for SMB3.1.1 compression
KNOWN BUGS
====================================
Known Bugs
==========
See http://bugzilla.samba.org - search on product "CifsVFS" for
current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
1) existing symbolic links (Windows reparse points) are recognized but
can not be created remotely. They are implemented for Samba and those that
support the CIFS Unix extensions, although earlier versions of Samba
overly restrict the pathnames.
can not be created remotely. They are implemented for Samba and those that
support the CIFS Unix extensions, although earlier versions of Samba
overly restrict the pathnames.
2) follow_link and readdir code does not follow dfs junctions
but recognizes them
but recognizes them
Misc testing to do
==================
1) check out max path names and max path name components against various server
types. Try nested symlinks (8 deep). Return max path name in stat -f information
types. Try nested symlinks (8 deep). Return max path name in stat -f information
2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
cifs/smb3 better
cifs/smb3 better
3) Additional performance testing and optimization using iozone and similar -
there are some easy changes that can be done to parallelize sequential writes,
and when signing is disabled to request larger read sizes (larger than
negotiated size) and send larger write sizes to modern servers.
3) Additional performance testing and optimization using iozone and similar -
there are some easy changes that can be done to parallelize sequential writes,
and when signing is disabled to request larger read sizes (larger than
negotiated size) and send larger write sizes to modern servers.
4) More exhaustively test against less common servers
5) Continue to extend the smb3 "buildbot" which does automated xfstesting
against Windows, Samba and Azure currently - to add additional tests and
to allow the buildbot to execute the tests faster. The URL for the
buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
against Windows, Samba and Azure currently - to add additional tests and
to allow the buildbot to execute the tests faster. The URL for the
buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
6) Address various coverity warnings (most are not bugs per-se, but
the more warnings are addressed, the easier it is to spot real
problems that static analyzers will point out in the future).
the more warnings are addressed, the easier it is to spot real
problems that static analyzers will point out in the future).

560
Documentation/filesystems/cifs/README → Documentation/admin-guide/cifs/usage.rst
View File

File diff suppressed because it is too large Load Diff

0
Documentation/filesystems/cifs/winucase_convert.pl → Documentation/admin-guide/cifs/winucase_convert.pl
View File

11
Documentation/admin-guide/devices.txt
View File

@ -1647,8 +1647,17 @@
0 = /dev/comedi0 First comedi device
1 = /dev/comedi1 Second comedi device
...
47 = /dev/comedi47 48th comedi device
See http://stm.lbl.gov/comedi.
Minors 48 to 255 are reserved for comedi subdevices with
pathnames of the form "/dev/comediX_subdY", where "X" is the
minor number of the associated comedi device and "Y" is the
subdevice number. These subdevice minors are assigned
dynamically, so there is no fixed mapping from subdevice
pathnames to minor numbers.
See http://www.comedi.org/ for information about the Comedi
project.
98 block User-mode virtual block device
0 = /dev/ubda First user-mode block device

5
Documentation/admin-guide/index.rst
View File

@ -77,7 +77,10 @@ configure specific aspects of kernel behavior to your liking.
blockdev/index
ext4
binderfs
cifs/index
xfs
jfs
ufs
pm/index
thunderbolt
LSM/index
@ -98,6 +101,7 @@ configure specific aspects of kernel behavior to your liking.
iostats
kernel-per-CPU-kthreads
laptops/index
auxdisplay/index
lcd-panel-cgram
ldm
lockup-watchdogs
@ -105,6 +109,7 @@ configure specific aspects of kernel behavior to your liking.
pnp
rtc
svga
wimax/index
video-output
.. only:: subproject and html

44
Documentation/filesystems/jfs.txt → Documentation/admin-guide/jfs.rst
View File

@ -1,45 +1,59 @@
===========================================
IBM's Journaled File System (JFS) for Linux
===========================================
JFS Homepage: http://jfs.sourceforge.net/
The following mount options are supported:
(*) == default
iocharset=name Character set to use for converting from Unicode to
iocharset=name
Character set to use for converting from Unicode to
ASCII. The default is to do no conversion. Use
iocharset=utf8 for UTF-8 translations. This requires
CONFIG_NLS_UTF8 to be set in the kernel .config file.
iocharset=none specifies the default behavior explicitly.
resize=value Resize the volume to <value> blocks. JFS only supports
resize=value
Resize the volume to <value> blocks. JFS only supports
growing a volume, not shrinking it. This option is only
valid during a remount, when the volume is mounted
read-write. The resize keyword with no value will grow
the volume to the full size of the partition.
nointegrity Do not write to the journal. The primary use of this option
nointegrity
Do not write to the journal. The primary use of this option
is to allow for higher performance when restoring a volume
from backup media. The integrity of the volume is not
guaranteed if the system abnormally abends.
integrity(*) Commit metadata changes to the journal. Use this option to
integrity(*)
Commit metadata changes to the journal. Use this option to
remount a volume where the nointegrity option was
previously specified in order to restore normal behavior.
errors=continue Keep going on a filesystem error.
errors=remount-ro(*) Remount the filesystem read-only on an error.
errors=panic Panic and halt the machine if an error occurs.
errors=continue
Keep going on a filesystem error.
errors=remount-ro(*)
Remount the filesystem read-only on an error.
errors=panic
Panic and halt the machine if an error occurs.
uid=value Override on-disk uid with specified value
gid=value Override on-disk gid with specified value
umask=value Override on-disk umask with specified octal value. For
directories, the execute bit will be set if the corresponding
uid=value
Override on-disk uid with specified value
gid=value
Override on-disk gid with specified value
umask=value
Override on-disk umask with specified octal value. For
directories, the execute bit will be set if the corresponding
read bit is set.
discard=minlen This enables/disables the use of discard/TRIM commands.
discard The discard/TRIM commands are sent to the underlying
nodiscard(*) block device when blocks are freed. This is useful for SSD
devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl
discard=minlen, discard/nodiscard(*)
This enables/disables the use of discard/TRIM commands.
The discard/TRIM commands are sent to the underlying
block device when blocks are freed. This is useful for SSD
devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl
command is also available together with the nodiscard option.
The value of minlen specifies the minimum blockcount, when
a TRIM command to the block device is considered useful.

4
Documentation/admin-guide/kernel-parameters.txt
View File

@ -1044,6 +1044,10 @@
specified address. The serial port must already be
setup and configured. Options are not yet supported.
sbi
Use RISC-V SBI (Supervisor Binary Interface) for early
console.
smh Use ARM semihosting calls for early console.
s3c2410,<addr>

20
Documentation/admin-guide/sysrq.rst
View File

@ -171,22 +171,20 @@ It seems others find it useful as (System Attention Key) which is
useful when you want to exit a program that will not let you switch consoles.
(For example, X or a svgalib program.)
``reboot(b)`` is good when you're unable to shut down. But you should also
``sync(s)`` and ``umount(u)`` first.
``reboot(b)`` is good when you're unable to shut down, it is an equivalent
of pressing the "reset" button.
``crash(c)`` can be used to manually trigger a crashdump when the system is hung.
Note that this just triggers a crash if there is no dump mechanism available.
``sync(s)`` is great when your system is locked up, it allows you to sync your
disks and will certainly lessen the chance of data loss and fscking. Note
that the sync hasn't taken place until you see the "OK" and "Done" appear
on the screen. (If the kernel is really in strife, you may not ever get the
OK or Done message...)
``sync(s)`` is handy before yanking removable medium or after using a rescue
shell that provides no graceful shutdown -- it will ensure your data is
safely written to the disk. Note that the sync hasn't taken place until you see
the "OK" and "Done" appear on the screen.
``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally
``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved
me many a fsck. Again, the unmount (remount read-only) hasn't taken place until
you see the "OK" and "Done" message appear on the screen.
``umount(u)`` can be used to mark filesystems as properly unmounted. From the
running system's point of view, they will be remounted read-only. The remount
isn't complete until you see the "OK" and "Done" message appear on the screen.
The loglevels ``0``-``9`` are useful when your console is being flooded with
kernel messages you do not want to see. Selecting ``0`` will prevent all but

36
Documentation/filesystems/ufs.txt → Documentation/admin-guide/ufs.rst
View File

@ -1,37 +1,45 @@
USING UFS
=========
Using UFS
=========
mount -t ufs -o ufstype=type_of_ufs device dir
UFS OPTIONS
UFS Options
===========
ufstype=type_of_ufs
UFS is a file system widely used in different operating systems.
The problem are differences among implementations. Features of
some implementations are undocumented, so its hard to recognize
type of ufs automatically. That's why user must specify type of
type of ufs automatically. That's why user must specify type of
ufs manually by mount option ufstype. Possible values are:
old old format of ufs
old
old format of ufs
default value, supported as read-only
44bsd used in FreeBSD, NetBSD, OpenBSD
44bsd
used in FreeBSD, NetBSD, OpenBSD
supported as read-write
ufs2 used in FreeBSD 5.x
ufs2
used in FreeBSD 5.x
supported as read-write
5xbsd synonym for ufs2
5xbsd
synonym for ufs2
sun used in SunOS (Solaris)
sun
used in SunOS (Solaris)
supported as read-write
sunx86 used in SunOS for Intel (Solarisx86)
sunx86
used in SunOS for Intel (Solarisx86)
supported as read-write
hp used in HP-UX
hp
used in HP-UX
supported as read-only
nextstep
@ -47,14 +55,14 @@ ufstype=type_of_ufs
supported as read-only
POSSIBLE PROBLEMS
=================
Possible Problems
-----------------
See next section, if you have any.
BUG REPORTS
===========
Bug Reports
-----------
Any ufs bug report you can send to daniel.pirkl@email.cz or
to dushistov@mail.ru (do not send partition tables bug reports).

145
Documentation/wimax/README.i2400m → Documentation/admin-guide/wimax/i2400m.rst
View File

@ -1,18 +1,23 @@
.. include:: <isonum.txt>
Driver for the Intel Wireless Wimax Connection 2400m
====================================================
Driver for the Intel Wireless Wimax Connection 2400m
====================================================
(C) 2008 Intel Corporation < linux-wimax@intel.com >
:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
This provides a driver for the Intel Wireless WiMAX Connection 2400m
and a basic Linux kernel WiMAX stack.
1. Requirements
===============
* Linux installation with Linux kernel 2.6.22 or newer (if building
from a separate tree)
* Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
Wireless WiMAX/WiFi Link 5x50 series.
* build tools:
+ Linux kernel development package for the target kernel; to
build against your currently running kernel, you need to have
the kernel development package corresponding to the running
@ -22,8 +27,10 @@
+ GNU C Compiler, make
2. Compilation and installation
===============================
2.1. Compilation of the drivers included in the kernel
------------------------------------------------------
Configure the kernel; to enable the WiMAX drivers select Drivers >
Networking Drivers > WiMAX device support. Enable all of them as
@ -36,37 +43,39 @@
Compile and install your kernel as usual.
2.2. Compilation of the drivers distributed as an standalone module
-------------------------------------------------------------------
To compile
To compile::
$ cd source/directory
$ make
$ cd source/directory
$ make
Once built you can load and unload using the provided load.sh script;
load.sh will load the modules, load.sh u will unload them.
To install in the default kernel directories (and enable auto loading
when the device is plugged):
when the device is plugged)::
$ make install
$ depmod -a
$ make install
$ depmod -a
If your kernel development files are located in a non standard
directory or if you want to build for a kernel that is not the
currently running one, set KDIR to the right location:
currently running one, set KDIR to the right location::
$ make KDIR=/path/to/kernel/dev/tree
$ make KDIR=/path/to/kernel/dev/tree
For more information, please contact linux-wimax@intel.com.
3. Installing the firmware
--------------------------
The firmware can be obtained from http://linuxwimax.org or might have
been supplied with your hardware.
It has to be installed in the target system:
*
$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
It has to be installed in the target system::
$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
* NOTE: if your firmware came in an .rpm or .deb file, just install
it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
with other types.
4. Design
=========
This package contains two major parts: a WiMAX kernel stack and a
driver for the Intel i2400m.
@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
API calls should be replaced with the target OS's.
5. Usage
========
To load the driver, follow the instructions in the install section;
once the driver is loaded, plug in the device (unless it is permanently
plugged in). The driver will enumerate the device, upload the firmware
and output messages in the kernel log (dmesg, /var/log/messages or
/var/log/kern.log) such as:
/var/log/kern.log) such as::
...
i2400m_usb 5-4:1.0: firmware interface version 8.0.0
i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
...
i2400m_usb 5-4:1.0: firmware interface version 8.0.0
i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
At this point the device is ready to work.
@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
on how to scan, connect and disconnect.
5.1. Module parameters
----------------------
Module parameters can be set at kernel or module load time or by
echoing values:
echoing values::
$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
To make changes permanent, for example, for the i2400m module, you can
also create a file named /etc/modprobe.d/i2400m containing:
also create a file named /etc/modprobe.d/i2400m containing::
options i2400m idle_mode_disabled=1
options i2400m idle_mode_disabled=1
To find which parameters are supported by a module, run:
To find which parameters are supported by a module, run::
$ modinfo path/to/module.ko
$ modinfo path/to/module.ko
During kernel bootup (if the driver is linked in the kernel), specify
the following to the kernel command line:
the following to the kernel command line::
i2400m.PARAMETER=VALUE
i2400m.PARAMETER=VALUE
5.1.1. i2400m: idle_mode_disabled
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The i2400m module supports a parameter to disable idle mode. This
parameter, once set, will take effect only when the device is
reinitialized by the driver (eg: following a reset or a reconnect).
5.2. Debug operations: debugfs entries
--------------------------------------
The driver will register debugfs entries that allow the user to tweak
debug settings. There are three main container directories where
entries are placed, which correspond to the three blocks a i2400m WiMAX
driver has:
* /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
controls
* /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE
/sys/kernel/debug, those paths will change.
5.2.1. Increasing debug output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The files named *dl_* indicate knobs for controlling the debug output
of different submodules:
*
# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
of different submodules::
# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
By reading the file you can obtain the current value of said debug
level; by writing to it, you can set it.
To increase the debug level of, for example, the i2400m's generic TX
engine, just write:
engine, just write::
$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
Increasing numbers yield increasing debug information; for details of
what is printed and the available levels, check the source. The code
uses 0 for disabled and increasing values until 8.
5.2.2. RX and TX statistics
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
data reception/delivery from the device:
data reception/delivery from the device::
$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
45 1 3 34 3104 48 480
$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
45 1 3 34 3104 48 480
The numbers reported are:
The numbers reported are
* packets/RX-buffer: total, min, max
* RX-buffers: total RX buffers received, accumulated RX buffer size
in bytes, min size received, max size received
@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
Thus, to find the average buffer size received, divide accumulated
RX-buffer / total RX-buffers.
To clear the statistics back to 0, write anything to the rx_stats file:
To clear the statistics back to 0, write anything to the rx_stats file::
$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
Likewise for TX.
@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
to the host. See drivers/net/wimax/i2400m/tx.c.
5.2.3. Tracing messages received from user space
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To echo messages received from user space into the trace pipe that the
i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
1:
*
$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
1::
$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
5.2.4. Performing a device reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By writing a 0, a 1 or a 2 to the file
/sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
(bus specific) reset on the device.
5.2.5. Asking the device to enter power saving mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
device will attempt to enter power saving mode.
6. Troubleshooting
==================
6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed'
6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
----------------------------------------------------------------------
If upon connecting the device, the following is output in the kernel
log:
log::
i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
This means that the driver cannot locate the firmware file named
/lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in

19
Documentation/admin-guide/wimax/index.rst Normal file
View File

@ -0,0 +1,19 @@
.. SPDX-License-Identifier: GPL-2.0
===============
WiMAX subsystem
===============
.. toctree::
:maxdepth: 2
wimax
i2400m
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

36
Documentation/wimax/README.wimax → Documentation/admin-guide/wimax/wimax.rst
View File

@ -1,12 +1,16 @@
.. include:: <isonum.txt>
Linux kernel WiMAX stack
========================
Linux kernel WiMAX stack
========================
(C) 2008 Intel Corporation < linux-wimax@intel.com >
:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
This provides a basic Linux kernel WiMAX stack to provide a common
control API for WiMAX devices, usable from kernel and user space.
1. Design
=========
The WiMAX stack is designed to provide for common WiMAX control
services to current and future WiMAX devices from any vendor.
@ -31,6 +35,7 @@
include/linux/wimax.h.
2. Usage
========
For usage in a driver (registration, API, etc) please refer to the
instructions in the header file include/linux/wimax.h.
@ -40,6 +45,7 @@
control.
2.1. Obtaining debug information: debugfs entries
-------------------------------------------------
The WiMAX stack is compiled, by default, with debug messages that can
be used to diagnose issues. By default, said messages are disabled.
@ -52,20 +58,22 @@
create more subentries below it.
2.1.1. Increasing debug output
------------------------------
The files named *dl_* indicate knobs for controlling the debug output
of different submodules of the WiMAX stack:
*
# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
of different submodules of the WiMAX stack::
NOTE: Of course, if debugfs is mounted in a directory other than
# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
NOTE:
Of course, if debugfs is mounted in a directory other than
/sys/kernel/debug, those paths will change.
By reading the file you can obtain the current value of said debug
@ -74,7 +82,7 @@
To increase the debug level of, for example, the id-table submodule,
just write:
$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
Increasing numbers yield increasing debug information; for details of
what is printed and the available levels, check the source. The code

5
Documentation/admin-guide/xfs.rst
View File

@ -337,11 +337,12 @@ None at present.
Removed Sysctls
===============
============================= =======
Name Removed
---- -------
============================= =======
fs.xfs.xfsbufd_centisec v4.0
fs.xfs.age_buffer_centisecs v4.0
============================= =======
Error handling
==============

51
Documentation/arm/sa1100/adsbitsy.rst
View File

@ -1,51 +0,0 @@
===============================
ADS Bitsy Single Board Computer
===============================
(It is different from Bitsy(iPAQ) of Compaq)
For more details, contact Applied Data Systems or see
http://www.applieddata.net/products.html
The Linux support for this product has been provided by
Woojung Huh <whuh@applieddata.net>
Use 'make adsbitsy_config' before any 'make config'.
This will set up defaults for ADS Bitsy support.
The kernel zImage is linked to be loaded and executed at 0xc0400000.
Linux can be used with the ADS BootLoader that ships with the
newer rev boards. See their documentation on how to load Linux.
Supported peripherals
=====================
- SA1100 LCD frame buffer (8/16bpp...sort of)
- SA1111 USB Master
- SA1100 serial port
- pcmcia, compact flash
- touchscreen(ucb1200)
- console on LCD screen
- serial ports (ttyS[0-2])
- ttyS0 is default for serial console
To do
=====
- everything else! :-)
Notes
=====
- The flash on board is divided into 3 partitions.
You should be careful to use flash on board.
Its partition is different from GraphicsClient Plus and GraphicsMaster
- 16bpp mode requires a different cable than what ships with the board.
Contact ADS or look through the manual to wire your own. Currently,
if you compile with 16bit mode support and switch into a lower bpp
mode, the timing is off so the image is corrupted. This will be
fixed soon.
Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!

2
Documentation/arm/sa1100/assabet.rst
View File

@ -14,7 +14,7 @@ Building the kernel
To build the kernel with current defaults::
make assabet_config
make assabet_defconfig
make oldconfig
make zImage

69
Documentation/arm/sa1100/brutus.rst
View File

@ -1,69 +0,0 @@
======
Brutus
======
Brutus is an evaluation platform for the SA1100 manufactured by Intel.
For more details, see:
http://developer.intel.com
To compile for Brutus, you must issue the following commands::
make brutus_config
make config
[accept all the defaults]
make zImage
The resulting kernel will end up in linux/arch/arm/boot/zImage. This file
must be loaded at 0xc0008000 in Brutus's memory and execution started at
0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon
entry.
But prior to execute the kernel, a ramdisk image must also be loaded in
memory. Use memory address 0xd8000000 for this. Note that the file
containing the (compressed) ramdisk image must not exceed 4 MB.
Typically, you'll need angelboot to load the kernel.
The following angelboot.opt file should be used::
base 0xc0008000
entry 0xc0008000
r0 0x00000000
r1 0x00000010
device /dev/ttyS0
options "9600 8N1"
baud 115200
otherfile ramdisk_img.gz
otherbase 0xd8000000
Then load the kernel and ramdisk with::
angelboot -f angelboot.opt zImage
The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your
host PC) is used by angel to load the kernel and ramdisk image. The serial
console is provided through the second Brutus serial port. To access it,
you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow
control.
Currently supported
===================
- RS232 serial ports
- audio output
- LCD screen
- keyboard
The actual Brutus support may not be complete without extra patches.
If such patches exist, they should be found from
ftp.netwinder.org/users/n/nico.
A full PCMCIA support is still missing, although it's possible to hack
some drivers in order to drive already inserted cards at boot time with
little modifications.
Any contribution is welcome.
Please send patches to nico@fluxnic.net
Have Fun !

25
Documentation/arm/sa1100/freebird.rst
View File

@ -1,25 +0,0 @@
========
Freebird
========
Freebird-1.1 is produced by Legend(C), Inc.
`http://web.archive.org/web/*/http://www.legend.com.cn`
and software/linux maintained by Coventive(C), Inc.
(http://www.coventive.com)
Based on the Nicolas's strongarm kernel tree.
Maintainer:
Chester Kuo
- <chester@coventive.com>
- <chester@linux.org.tw>
Author:
- Tim wu <timwu@coventive.com>
- CIH <cih@coventive.com>
- Eric Peng <ericpeng@coventive.com>
- Jeff Lee <jeff_lee@coventive.com>
- Allen Cheng
- Tony Liu <tonyliu@coventive.com>

102
Documentation/arm/sa1100/graphicsclient.rst
View File

@ -1,102 +0,0 @@
=============================================
ADS GraphicsClient Plus Single Board Computer
=============================================
For more details, contact Applied Data Systems or see
http://www.applieddata.net/products.html
The original Linux support for this product has been provided by
Nicolas Pitre <nico@fluxnic.net>. Continued development work by
Woojung Huh <whuh@applieddata.net>
It's currently possible to mount a root filesystem via NFS providing a
complete Linux environment. Otherwise a ramdisk image may be used. The
board supports MTD/JFFS, so you could also mount something on there.
Use 'make graphicsclient_config' before any 'make config'. This will set up
defaults for GraphicsClient Plus support.
The kernel zImage is linked to be loaded and executed at 0xc0200000.
Also the following registers should have the specified values upon entry::
r0 = 0
r1 = 29 (this is the GraphicsClient architecture number)
Linux can be used with the ADS BootLoader that ships with the
newer rev boards. See their documentation on how to load Linux.
Angel is not available for the GraphicsClient Plus AFAIK.
There is a board known as just the GraphicsClient that ADS used to
produce but has end of lifed. This code will not work on the older
board with the ADS bootloader, but should still work with Angel,
as outlined below. In any case, if you're planning on deploying
something en masse, you should probably get the newer board.
If using Angel on the older boards, here is a typical angel.opt option file
if the kernel is loaded through the Angel Debug Monitor::
base 0xc0200000
entry 0xc0200000
r0 0x00000000
r1 0x0000001d
device /dev/ttyS1
options "38400 8N1"
baud 115200
#otherfile ramdisk.gz
#otherbase 0xc0800000
exec minicom
Then the kernel (and ramdisk if otherfile/otherbase lines above are
uncommented) would be loaded with::
angelboot -f angelboot.opt zImage
Here it is assumed that the board is connected to ttyS1 on your PC
and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow
control by default.
If any other bootloader is used, ensure it accomplish the same, especially
for r0/r1 register values before jumping into the kernel.
Supported peripherals
=====================
- SA1100 LCD frame buffer (8/16bpp...sort of)
- on-board SMC 92C96 ethernet NIC
- SA1100 serial port
- flash memory access (MTD/JFFS)
- pcmcia
- touchscreen(ucb1200)
- ps/2 keyboard
- console on LCD screen
- serial ports (ttyS[0-2])
- ttyS0 is default for serial console
- Smart I/O (ADC, keypad, digital inputs, etc)
See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
and example user space code. ps/2 keybd is multiplexed through this driver
To do
=====
- UCB1200 audio with new ucb_generic layer
- everything else! :-)
Notes
=====
- The flash on board is divided into 3 partitions. mtd0 is where
the ADS boot ROM and zImage is stored. It's been marked as
read-only to keep you from blasting over the bootloader. :) mtd1 is
for the ramdisk.gz image. mtd2 is user flash space and can be
utilized for either JFFS or if you're feeling crazy, running ext2
on top of it. If you're not using the ADS bootloader, you're
welcome to blast over the mtd1 partition also.
- 16bpp mode requires a different cable than what ships with the board.
Contact ADS or look through the manual to wire your own. Currently,
if you compile with 16bit mode support and switch into a lower bpp
mode, the timing is off so the image is corrupted. This will be
fixed soon.
Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!

60
Documentation/arm/sa1100/graphicsmaster.rst
View File

@ -1,60 +0,0 @@
========================================
ADS GraphicsMaster Single Board Computer
========================================
For more details, contact Applied Data Systems or see
http://www.applieddata.net/products.html
The original Linux support for this product has been provided by
Nicolas Pitre <nico@fluxnic.net>. Continued development work by
Woojung Huh <whuh@applieddata.net>
Use 'make graphicsmaster_config' before any 'make config'.
This will set up defaults for GraphicsMaster support.
The kernel zImage is linked to be loaded and executed at 0xc0400000.
Linux can be used with the ADS BootLoader that ships with the
newer rev boards. See their documentation on how to load Linux.
Supported peripherals
=====================
- SA1100 LCD frame buffer (8/16bpp...sort of)
- SA1111 USB Master
- on-board SMC 92C96 ethernet NIC
- SA1100 serial port
- flash memory access (MTD/JFFS)
- pcmcia, compact flash
- touchscreen(ucb1200)
- ps/2 keyboard
- console on LCD screen
- serial ports (ttyS[0-2])
- ttyS0 is default for serial console
- Smart I/O (ADC, keypad, digital inputs, etc)
See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
and example user space code. ps/2 keybd is multiplexed through this driver
To do
=====
- everything else! :-)
Notes
=====
- The flash on board is divided into 3 partitions. mtd0 is where
the zImage is stored. It's been marked as read-only to keep you
from blasting over the bootloader. :) mtd1 is
for the ramdisk.gz image. mtd2 is user flash space and can be
utilized for either JFFS or if you're feeling crazy, running ext2
on top of it. If you're not using the ADS bootloader, you're
welcome to blast over the mtd1 partition also.
- 16bpp mode requires a different cable than what ships with the board.
Contact ADS or look through the manual to wire your own. Currently,
if you compile with 16bit mode support and switch into a lower bpp
mode, the timing is off so the image is corrupted. This will be
fixed soon.
Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!

21
Documentation/arm/sa1100/huw_webpanel.rst
View File

@ -1,21 +0,0 @@
=======================
Hoeft & Wessel Webpanel
=======================
The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG
If you want more information, please visit
http://www.hoeft-wessel.de
To build the kernel::
make huw_webpanel_config
make oldconfig
[accept all defaults]
make zImage
Mostly of the work is done by:
Roman Jordan jor@hoeft-wessel.de
Christoph Schulz schu@hoeft-wessel.de
2000/12/18/

12
Documentation/arm/sa1100/index.rst
View File

@ -7,19 +7,7 @@ Intel StrongARM 1100
.. toctree::
:maxdepth: 1
adsbitsy
assabet
brutus
cerf
freebird
graphicsclient
graphicsmaster
huw_webpanel
itsy
lart
nanoengine
pangolin
pleb
serial_uart
tifon
yopy

47
Documentation/arm/sa1100/itsy.rst
View File

@ -1,47 +0,0 @@
====
Itsy
====
Itsy is a research project done by the Western Research Lab, and Systems
Research Center in Palo Alto, CA. The Itsy project is one of several
research projects at Compaq that are related to pocket computing.
For more information, see:
http://www.hpl.hp.com/downloads/crl/itsy/
Notes on initial 2.4 Itsy support (8/27/2000) :
The port was done on an Itsy version 1.5 machine with a daughtercard with
64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for
serial console (to see what you're doing). No other devices have been
enabled.
To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support.
Disable Flash and LCD support. and then do a make zImage.
Finally, you will need to cd to arch/arm/boot/tools and execute a make there
to build the params-itsy program used to boot the kernel.
In order to install the port of 2.4 to the itsy, You will need to set the
configuration parameters in the monitor as follows::
Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
Make sure the start-routine address is set to 0x00060000.
Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the
flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000
("p 1 0x00340000"). Finally flash an initial ramdisk into 0xC8000000
("p 2 0x0") We used ramdisk-2-30.gz from the 0.11 version directory on
handhelds.org.
The serial connection we established was at:
8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
params-itsy program, and in the kernel itself. This can be changed, but
not easily. The monitor parameters are easily changed, the params program
setup is assembly outl's, and the kernel is a configuration item specific to
the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.)
This should get you a properly booting 2.4 kernel on the itsy.

11
Documentation/arm/sa1100/nanoengine.rst
View File

@ -1,11 +0,0 @@
==========
nanoEngine
==========
"nanoEngine" is a SA1110 based single board computer from
Bright Star Engineering Inc. See www.brightstareng.com/arm
for more info.
(Ref: Stuart Adams <sja@brightstareng.com>)
Also visit Larry Doolittle's "Linux for the nanoEngine" site:
http://www.brightstareng.com/arm/nanoeng.htm

29
Documentation/arm/sa1100/pangolin.rst
View File

@ -1,29 +0,0 @@
========
Pangolin
========
Pangolin is a StrongARM 1110-based evaluation platform produced
by Dialogue Technology (http://www.dialogue.com.tw/).
It has EISA slots for ease of configuration with SDRAM/Flash
memory card, USB/Serial/Audio card, Compact Flash card,
PCMCIA/IDE card and TFT-LCD card.
To compile for Pangolin, you must issue the following commands::
make pangolin_config
make oldconfig
make zImage
Supported peripherals
=====================
- SA1110 serial port (UART1/UART2/UART3)
- flash memory access
- compact flash driver
- UDA1341 sound driver
- SA1100 LCD controller for 800x600 16bpp TFT-LCD
- MQ-200 driver for 800x600 16bpp TFT-LCD
- Penmount(touch panel) driver
- PCMCIA driver
- SMC91C94 LAN driver
- IDE driver (experimental)

13
Documentation/arm/sa1100/pleb.rst
View File

@ -1,13 +0,0 @@
====
PLEB
====
The PLEB project was started as a student initiative at the School of
Computer Science and Engineering, University of New South Wales to make a
pocket computer capable of running the Linux Kernel.
PLEB support has yet to be fully integrated.
For more information, see:
http://www.cse.unsw.edu.au

7
Documentation/arm/sa1100/tifon.rst
View File

@ -1,7 +0,0 @@
=====
Tifon
=====
More info has to come...
Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se>

5
Documentation/arm/sa1100/yopy.rst
View File

@ -1,5 +0,0 @@
====
Yopy
====
See http://www.yopydeveloper.org for more.

2
Documentation/arm/samsung-s3c24xx/index.rst
View File

@ -1,6 +1,6 @@
.. SPDX-License-Identifier: GPL-2.0
==========================
==========================
Samsung S3C24XX SoC Family
==========================

1
Documentation/arm/sh-mobile/.gitignore vendored
View File

@ -1 +0,0 @@
vrl4

105
Documentation/auxdisplay/cfag12864b
View File

@ -1,105 +0,0 @@
===================================
cfag12864b LCD Driver Documentation
===================================
License: GPLv2
Author & Maintainer: Miguel Ojeda Sandonis
Date: 2006-10-27
--------
0. INDEX
--------
1. DRIVER INFORMATION
2. DEVICE INFORMATION
3. WIRING
4. USERSPACE PROGRAMMING
---------------------
1. DRIVER INFORMATION
---------------------
This driver supports a cfag12864b LCD.
---------------------
2. DEVICE INFORMATION
---------------------
Manufacturer: Crystalfontz
Device Name: Crystalfontz 12864b LCD Series
Device Code: cfag12864b
Webpage: http://www.crystalfontz.com
Device Webpage: http://www.crystalfontz.com/products/12864b/
Type: LCD (Liquid Crystal Display)
Width: 128
Height: 64
Colors: 2 (B/N)
Controller: ks0108
Controllers: 2
Pages: 8 each controller
Addresses: 64 each page
Data size: 1 byte each address
Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
---------
3. WIRING
---------
The cfag12864b LCD Series don't have official wiring.
The common wiring is done to the parallel port as shown:
Parallel Port cfag12864b
Name Pin# Pin# Name
Strobe ( 1)------------------------------(17) Enable
Data 0 ( 2)------------------------------( 4) Data 0
Data 1 ( 3)------------------------------( 5) Data 1
Data 2 ( 4)------------------------------( 6) Data 2
Data 3 ( 5)------------------------------( 7) Data 3
Data 4 ( 6)------------------------------( 8) Data 4
Data 5 ( 7)------------------------------( 9) Data 5
Data 6 ( 8)------------------------------(10) Data 6
Data 7 ( 9)------------------------------(11) Data 7
(10) [+5v]---( 1) Vdd
(11) [GND]---( 2) Ground
(12) [+5v]---(14) Reset
(13) [GND]---(15) Read / Write
Line (14)------------------------------(13) Controller Select 1
(15)
Init (16)------------------------------(12) Controller Select 2
Select (17)------------------------------(16) Data / Instruction
Ground (18)---[GND] [+5v]---(19) LED +
Ground (19)---[GND]
Ground (20)---[GND] E A Values:
Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
Ground (22)---[GND] | - P1 = Preset = 10 Kohm
Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
Ground (24)---[GND] | |
Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
------------------------
4. USERSPACE PROGRAMMING
------------------------
The cfag12864bfb describes a framebuffer device (/dev/fbX).
It has a size of 1024 bytes = 1 Kbyte.
Each bit represents one pixel. If the bit is high, the pixel will
turn on. If the pixel is low, the pixel will turn off.
You can use the framebuffer as a file: fopen, fwrite, fclose...
Although the LCD won't get updated until the next refresh time arrives.
Also, you can mmap the framebuffer: open & mmap, munmap & close...
which is the best option for most uses.
Check samples/auxdisplay/cfag12864b-example.c
for a real working userspace complete program with usage examples.

55
Documentation/auxdisplay/ks0108
View File

@ -1,55 +0,0 @@
==========================================
ks0108 LCD Controller Driver Documentation
==========================================
License: GPLv2
Author & Maintainer: Miguel Ojeda Sandonis
Date: 2006-10-27
--------
0. INDEX
--------
1. DRIVER INFORMATION
2. DEVICE INFORMATION
3. WIRING
---------------------
1. DRIVER INFORMATION
---------------------
This driver supports the ks0108 LCD controller.
---------------------
2. DEVICE INFORMATION
---------------------
Manufacturer: Samsung
Device Name: KS0108 LCD Controller
Device Code: ks0108
Webpage: -
Device Webpage: -
Type: LCD Controller (Liquid Crystal Display Controller)
Width: 64
Height: 64
Colors: 2 (B/N)
Pages: 8
Addresses: 64 each page
Data size: 1 byte each address
Memory size: 8 * 64 * 1 = 512 bytes
---------
3. WIRING
---------
The driver supports data parallel port wiring.
If you aren't building LCD related hardware, you should check
your LCD specific wiring information in the same folder.
For example, check Documentation/auxdisplay/cfag12864b.

3
Documentation/core-api/index.rst
View File

@ -25,6 +25,7 @@ Core utilities
librs
genalloc
errseq
packing
printk-formats
circular-buffers
generic-radix-tree
@ -48,7 +49,7 @@ Interfaces for kernel debugging
debug-objects
tracepoint
.. only:: subproject
.. only:: subproject and html
Indices
=======

81
Documentation/packing.txt → Documentation/core-api/packing.rst
View File

@ -30,6 +30,7 @@ The solution
------------
This API deals with 2 basic operations:
- Packing a CPU-usable number into a memory buffer (with hardware
constraints/quirks)
- Unpacking a memory buffer (which has hardware constraints/quirks)
@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
1. Normally (no quirks), we would do it like this:
63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
7 6 5 4
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
3 2 1 0
::
63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
7 6 5 4
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
3 2 1 0
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
LSByte (0) of the u64 sits at memory offset 7.
@ -63,10 +66,12 @@ comments as "logical" notation.
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
7 6 5 4
24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
3 2 1 0
::
56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
7 6 5 4
24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
3 2 1 0
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
inverts bit offsets inside a byte.
@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
4 5 6 7
7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
0 1 2 3
::
39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
4 5 6 7
7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
0 1 2 3
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
byte from each 4-byte word is placed at its mirrored position compared to
@ -86,18 +93,22 @@ the boundary of that word.
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
like this:
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
4 5 6 7
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
0 1 2 3
::
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
4 5 6 7
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
0 1 2 3
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
3 2 1 0
63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
7 6 5 4
::
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
3 2 1 0
63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
7 6 5 4
In this case the 8 byte memory region is interpreted as follows: first
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@ -107,28 +118,34 @@ the more significant 4-byte word.
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
this:
24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
3 2 1 0
56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
7 6 5 4
::
24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
3 2 1 0
56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
7 6 5 4
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
this:
7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
0 1 2 3
39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
4 5 6 7
::
7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
0 1 2 3
39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
4 5 6 7
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
are set, it looks like this:
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
0 1 2 3
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
4 5 6 7
::
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
0 1 2 3
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
4 5 6 7
We always think of our offsets as if there were no quirk, and we translate

16
Documentation/core-api/printk-formats.rst
View File

@ -13,10 +13,10 @@ Integer types
If variable is of Type, use printk format specifier:
------------------------------------------------------------
char %hhd or %hhx
unsigned char %hhu or %hhx
short int %hd or %hx
unsigned short int %hu or %hx
char %d or %x
unsigned char %u or %x
short int %d or %x
unsigned short int %u or %x
int %d or %x
unsigned int %u or %x
long %ld or %lx
@ -25,10 +25,10 @@ Integer types
unsigned long long %llu or %llx
size_t %zu or %zx
ssize_t %zd or %zx
s8 %hhd or %hhx
u8 %hhu or %hhx
s16 %hd or %hx
u16 %hu or %hx
s8 %d or %x
u8 %u or %x
s16 %d or %x
u16 %u or %x
s32 %d or %x
u32 %u or %x
s64 %lld or %llx

2
Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
View File

@ -42,7 +42,7 @@ Optional properties:
This means that no unrelated I2C transactions are allowed on the parent I2C
adapter for the complete multiplexed I2C transaction.
The properties of mux-locked and parent-locked multiplexers are discussed
in more detail in Documentation/i2c/i2c-topology.
in more detail in Documentation/i2c/i2c-topology.rst.
For each i2c child node, an I2C child bus will be created. They will
be numbered based on their order in the device tree.

2
Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt
View File

@ -4,7 +4,7 @@ Allwinner SUN8I audio codec
On Sun8i-A33 SoCs, the audio is separated in different parts:
- A DAI driver. It uses the "sun4i-i2s" driver which is
documented here:
Documentation/devicetree/bindings/sound/sun4i-i2s.txt
Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml
- An analog part of the codec which is handled as PRCM registers.
See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
- An digital part of the codec which is documented in this current

130
Documentation/devicetree/writing-schema.md
View File

@ -1,130 +0,0 @@
# Writing DeviceTree Bindings in json-schema
Devicetree bindings are written using json-schema vocabulary. Schema files are
written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
considered more human readable and has some advantages such as allowing
comments (Prefixed with '#').
## Schema Contents
Each schema doc is a structured json-schema which is defined by a set of
top-level properties. Generally, there is one binding defined per file. The
top-level json-schema properties used are:
- __$id__ - A json-schema unique identifier string. The string must be a valid
URI typically containing the binding's filename and path. For DT schema, it must
begin with "http://devicetree.org/schemas/". The URL is used in constructing
references to other files specified in schema "$ref" properties. A $ref values
with a leading '/' will have the hostname prepended. A $ref value a relative
path or filename only will be prepended with the hostname and path components
of the current schema file's '$id' value. A URL is used even for local files,
but there may not actually be files present at those locations.
- __$schema__ - Indicates the meta-schema the schema file adheres to.
- __title__ - A one line description on the contents of the binding schema.
- __maintainers__ - A DT specific property. Contains a list of email address(es)
for maintainers of this binding.
- __description__ - Optional. A multi-line text block containing any detailed
information about this binding. It should contain things such as what the block
or device does, standards the device conforms to, and links to datasheets for
more information.
- __select__ - Optional. A json-schema used to match nodes for applying the
schema. By default without 'select', nodes are matched against their possible
compatible string values or node name. Most bindings should not need select.
- __allOf__ - Optional. A list of other schemas to include. This is used to
include other schemas the binding conforms to. This may be schemas for a
particular class of devices such as I2C or SPI controllers.
- __properties__ - A set of sub-schema defining all the DT properties for the
binding. The exact schema syntax depends on whether properties are known,
common properties (e.g. 'interrupts') or are binding/vendor specific properties.
A property can also define a child DT node with child properties defined
under it.
For more details on properties sections, see 'Property Schema' section.
- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
- __required__ - A list of DT properties from the 'properties' section that
must always be present.
- __examples__ - Optional. A list of one or more DTS hunks implementing the
binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
Unless noted otherwise, all properties are required.
## Property Schema
The 'properties' section of the schema contains all the DT properties for a
binding. Each property contains a set of constraints using json-schema
vocabulary for that property. The properties schemas are what is used for
validation of DT files.
For common properties, only additional constraints not covered by the common
binding schema need to be defined such as how many values are valid or what
possible values are valid.
Vendor specific properties will typically need more detailed schema. With the
exception of boolean properties, they should have a reference to a type in
schemas/types.yaml. A "description" property is always required.
The Devicetree schemas don't exactly match the YAML encoded DT data produced by
dtc. They are simplified to make them more compact and avoid a bunch of
boilerplate. The tools process the schema files to produce the final schema for
validation. There are currently 2 transformations the tools perform.
The default for arrays in json-schema is they are variable sized and allow more
entries than explicitly defined. This can be restricted by defining 'minItems',
'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
size is desired in most cases, so these properties are added based on the
number of entries in an 'items' list.
The YAML Devicetree format also makes all string values an array and scalar
values a matrix (in order to define groupings) even when only a single value
is present. Single entries in schemas are fixed up to match this encoding.
## Testing
### Dependencies
The DT schema project must be installed in order to validate the DT schema
binding documents and validate DTS files using the DT schema. The DT schema
project can be installed with pip:
`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
dtc must also be built with YAML output support enabled. This requires that
libyaml and its headers be installed on the host system.
### Running checks
The DT schema binding documents must be validated using the meta-schema (the
schema for the schema) to ensure they are both valid json-schema and valid
binding schema. All of the DT binding documents can be validated using the
`dt_binding_check` target:
`make dt_binding_check`
In order to perform validation of DT source files, use the `dtbs_check` target:
`make dtbs_check`
This will first run the `dt_binding_check` which generates the processed schema.
It is also possible to run checks with a single schema file by setting the
'DT_SCHEMA_FILES' variable to a specific schema file.
`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
## json-schema Resources
[JSON-Schema Specifications](http://json-schema.org/)
[Using JSON Schema Book](http://usingjsonschema.com/)

153
Documentation/devicetree/writing-schema.rst Normal file
View File

@ -0,0 +1,153 @@
:orphan:
Writing DeviceTree Bindings in json-schema
==========================================
Devicetree bindings are written using json-schema vocabulary. Schema files are
written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
considered more human readable and has some advantages such as allowing
comments (Prefixed with '#').
Schema Contents
---------------
Each schema doc is a structured json-schema which is defined by a set of
top-level properties. Generally, there is one binding defined per file. The
top-level json-schema properties used are:
$id
A json-schema unique identifier string. The string must be a valid
URI typically containing the binding's filename and path. For DT schema, it must
begin with "http://devicetree.org/schemas/". The URL is used in constructing
references to other files specified in schema "$ref" properties. A $ref values
with a leading '/' will have the hostname prepended. A $ref value a relative
path or filename only will be prepended with the hostname and path components
of the current schema file's '$id' value. A URL is used even for local files,
but there may not actually be files present at those locations.
$schema
Indicates the meta-schema the schema file adheres to.
title
A one line description on the contents of the binding schema.
maintainers
A DT specific property. Contains a list of email address(es)
for maintainers of this binding.
description
Optional. A multi-line text block containing any detailed
information about this binding. It should contain things such as what the block
or device does, standards the device conforms to, and links to datasheets for
more information.
select
Optional. A json-schema used to match nodes for applying the
schema. By default without 'select', nodes are matched against their possible
compatible string values or node name. Most bindings should not need select.
allOf
Optional. A list of other schemas to include. This is used to
include other schemas the binding conforms to. This may be schemas for a
particular class of devices such as I2C or SPI controllers.
properties
A set of sub-schema defining all the DT properties for the
binding. The exact schema syntax depends on whether properties are known,
common properties (e.g. 'interrupts') or are binding/vendor specific properties.
A property can also define a child DT node with child properties defined
under it.
For more details on properties sections, see 'Property Schema' section.
patternProperties
Optional. Similar to 'properties', but names are regex.
required
A list of DT properties from the 'properties' section that
must always be present.
examples
Optional. A list of one or more DTS hunks implementing the
binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
Unless noted otherwise, all properties are required.
Property Schema
---------------
The 'properties' section of the schema contains all the DT properties for a
binding. Each property contains a set of constraints using json-schema
vocabulary for that property. The properties schemas are what is used for
validation of DT files.
For common properties, only additional constraints not covered by the common
binding schema need to be defined such as how many values are valid or what
possible values are valid.
Vendor specific properties will typically need more detailed schema. With the
exception of boolean properties, they should have a reference to a type in
schemas/types.yaml. A "description" property is always required.
The Devicetree schemas don't exactly match the YAML encoded DT data produced by
dtc. They are simplified to make them more compact and avoid a bunch of
boilerplate. The tools process the schema files to produce the final schema for
validation. There are currently 2 transformations the tools perform.
The default for arrays in json-schema is they are variable sized and allow more
entries than explicitly defined. This can be restricted by defining 'minItems',
'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
size is desired in most cases, so these properties are added based on the
number of entries in an 'items' list.
The YAML Devicetree format also makes all string values an array and scalar
values a matrix (in order to define groupings) even when only a single value
is present. Single entries in schemas are fixed up to match this encoding.
Testing
-------
Dependencies
~~~~~~~~~~~~
The DT schema project must be installed in order to validate the DT schema
binding documents and validate DTS files using the DT schema. The DT schema
project can be installed with pip::
pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
dtc must also be built with YAML output support enabled. This requires that
libyaml and its headers be installed on the host system.
Running checks
~~~~~~~~~~~~~~
The DT schema binding documents must be validated using the meta-schema (the
schema for the schema) to ensure they are both valid json-schema and valid
binding schema. All of the DT binding documents can be validated using the
``dt_binding_check`` target::
make dt_binding_check
In order to perform validation of DT source files, use the `dtbs_check` target::
make dtbs_check
This will first run the `dt_binding_check` which generates the processed schema.
It is also possible to run checks with a single schema file by setting the
``DT_SCHEMA_FILES`` variable to a specific schema file.
::
make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
json-schema Resources
---------------------
`JSON-Schema Specifications <http://json-schema.org/>`_
`Using JSON Schema Book <http://usingjsonschema.com/>`_

2
Documentation/driver-api/dmaengine/index.rst
View File

@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
pxa_dma
.. only:: subproject
.. only:: subproject and html
Indices
=======

2
Documentation/driver-api/index.rst
View File

@ -65,6 +65,7 @@ available subsections can be seen below.
dmaengine/index
slimbus
soundwire/index
thermal/index
fpga/index
acpi/index
backlight/lp855x-driver.rst
@ -75,6 +76,7 @@ available subsections can be seen below.
dell_rbu
edid
eisa
ipmb
isa
isapnp
generic-counter

2
Documentation/driver-api/ipmb.rst
View File

@ -83,7 +83,7 @@ Instantiate the device
----------------------
After loading the driver, you can instantiate the device as
described in 'Documentation/i2c/instantiating-devices'.
described in 'Documentation/i2c/instantiating-devices.rst'.
If you have multiple BMCs, each connected to your Satellite MC via
a different I2C bus, you can instantiate a device for each of
those BMCs.

2
Documentation/driver-api/mtd/spi-nor.rst
View File

@ -59,7 +59,7 @@ Part III - How can drivers use the framework?
The main API is spi_nor_scan(). Before you call the hook, a driver should
initialize the necessary fields for spi_nor{}. Please see
drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c
drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
when you want to write a new driver for a SPI NOR controller.
Another API is spi_nor_restore(), this is used to restore the status of SPI
flash chip such as addressing mode. Call it whenever detach the driver from

2
Documentation/driver-api/soundwire/index.rst
View File

@ -10,7 +10,7 @@ SoundWire Documentation
error_handling
locking
.. only:: subproject
.. only:: subproject and html
Indices
=======

0
Documentation/thermal/cpu-cooling-api.rst → Documentation/driver-api/thermal/cpu-cooling-api.rst
View File

0
Documentation/thermal/exynos_thermal.rst → Documentation/driver-api/thermal/exynos_thermal.rst
View File

0
Documentation/thermal/exynos_thermal_emulation.rst → Documentation/driver-api/thermal/exynos_thermal_emulation.rst
View File

2
Documentation/thermal/index.rst → Documentation/driver-api/thermal/index.rst
View File

@ -1,4 +1,4 @@
:orphan:
.. SPDX-License-Identifier: GPL-2.0
=======
Thermal

0
Documentation/thermal/intel_powerclamp.rst → Documentation/driver-api/thermal/intel_powerclamp.rst
View File

0
Documentation/thermal/nouveau_thermal.rst → Documentation/driver-api/thermal/nouveau_thermal.rst
View File

0
Documentation/thermal/power_allocator.rst → Documentation/driver-api/thermal/power_allocator.rst
View File

12
Documentation/thermal/sysfs-api.rst → Documentation/driver-api/thermal/sysfs-api.rst
View File

@ -552,7 +552,7 @@ emul_temp
sustainable_power
An estimate of the sustained power that can be dissipated by
the thermal zone. Used by the power allocator governor. For
more information see Documentation/thermal/power_allocator.rst
more information see Documentation/driver-api/thermal/power_allocator.rst
Unit: milliwatts
@ -563,7 +563,7 @@ k_po
controller during temperature overshoot. Temperature overshoot
is when the current temperature is above the "desired
temperature" trip point. For more information see
Documentation/thermal/power_allocator.rst
Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@ -572,7 +572,7 @@ k_pu
controller during temperature undershoot. Temperature undershoot
is when the current temperature is below the "desired
temperature" trip point. For more information see
Documentation/thermal/power_allocator.rst
Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@ -580,14 +580,14 @@ k_i
The integral term of the power allocator governor's PID
controller. This term allows the PID controller to compensate
for long term drift. For more information see
Documentation/thermal/power_allocator.rst
Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
k_d
The derivative term of the power allocator governor's PID
controller. For more information see
Documentation/thermal/power_allocator.rst
Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@ -598,7 +598,7 @@ integral_cutoff
example, if integral_cutoff is 0, then the integral term only
accumulates error when temperature is above the desired
temperature trip point. For more information see
Documentation/thermal/power_allocator.rst
Documentation/driver-api/thermal/power_allocator.rst
Unit: millidegree Celsius

2
Documentation/thermal/x86_pkg_temperature_thermal.rst → Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
View File

@ -40,7 +40,7 @@ This contains two trip points:
- trip_point_1_temp
User can set any temperature between 0 to TJ-Max temperature. Temperature units
are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
thermal sys-fs details.
Any value other than 0 in these trip points, can trigger thermal notifications.

2
Documentation/features/locking/queued-rwlocks/arch-support.txt
View File

@ -30,5 +30,5 @@
| um: | TODO |
| unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
| xtensa: | ok |
-----------------------

4
Documentation/features/locking/queued-spinlocks/arch-support.txt
View File

@ -9,7 +9,7 @@
| alpha: | TODO |
| arc: | TODO |
| arm: | TODO |
| arm64: | TODO |
| arm64: | ok |
| c6x: | TODO |
| csky: | TODO |
| h8300: | TODO |
@ -30,5 +30,5 @@
| um: | TODO |
| unicore32: | TODO |
| x86: | ok |
| xtensa: | TODO |
| xtensa: | ok |
-----------------------

34
Documentation/features/locking/rwsem-optimized/arch-support.txt
View File

@ -1,34 +0,0 @@
#
# Feature name: rwsem-optimized
# Kconfig: !RWSEM_GENERIC_SPINLOCK
# description: arch provides optimized rwsem APIs
#
-----------------------
| arch |status|
-----------------------
| alpha: | ok |
| arc: | TODO |
| arm: | ok |
| arm64: | ok |
| c6x: | TODO |
| csky: | TODO |
| h8300: | TODO |
| hexagon: | TODO |
| ia64: | ok |
| m68k: | TODO |
| microblaze: | TODO |
| mips: | TODO |
| nds32: | TODO |
| nios2: | TODO |
| openrisc: | TODO |
| parisc: | TODO |
| powerpc: | TODO |
| riscv: | TODO |
| s390: | ok |
| sh: | ok |
| sparc: | ok |
| um: | ok |
| unicore32: | TODO |
| x86: | ok |
| xtensa: | ok |
-----------------------

4
Documentation/filesystems/coda.txt
View File

@ -421,14 +421,14 @@ kernel support.
The CodaCred structure defines a variety of user and group ids as
they are set for the calling process. The vuid_t and guid_t are 32 bit
they are set for the calling process. The vuid_t and vgid_t are 32 bit
unsigned integers. It also defines group membership in an array. On
Unix the CodaCred has proven sufficient to implement good security
semantics for Coda but the structure may have to undergo modification
for the Windows environment when these mature.
struct CodaCred {
vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid*/
vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */
vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */
vgid_t cr_groups[NGROUPS]; /* Group membership for caller */
};

40
Documentation/filesystems/directory-locking → Documentation/filesystems/directory-locking.rst
View File

@ -1,12 +1,17 @@
Locking scheme used for directory operations is based on two
=================
Directory Locking
=================
Locking scheme used for directory operations is based on two
kinds of locks - per-inode (->i_rwsem) and per-filesystem
(->s_vfs_rename_mutex).
When taking the i_rwsem on multiple non-directory objects, we
When taking the i_rwsem on multiple non-directory objects, we
always acquire the locks in order by increasing address. We'll call
that "inode pointer" order in the following.
For our purposes all operations fall in 5 classes:
For our purposes all operations fall in 5 classes:
1) read access. Locking rules: caller locks directory we are accessing.
The lock is taken shared.
@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange
case) shared.
5) link creation. Locking rules:
* lock parent
* check that source is not a directory
* lock source
* call the method.
All locks are exclusive.
6) cross-directory rename. The trickiest in the whole bunch. Locking
rules:
* lock the filesystem
* lock parents in "ancestors first" order.
* find source and target.
* if old parent is equal to or is a descendent of target
fail with -ENOTEMPTY
fail with -ENOTEMPTY
* if new parent is equal to or is a descendent of source
fail with -ELOOP
fail with -ELOOP
* If it's an exchange, lock both the source and the target.
* If the target exists, lock it. If the source is a non-directory,
lock it. If we need to lock both, do so in inode pointer order.
* call the method.
All ->i_rwsem are taken exclusive. Again, we might get away with locking
the the source (and target in exchange case) shared.
@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller.
If no directory is its own ancestor, the scheme above is deadlock-free.
Proof:
First of all, at any moment we have a partial ordering of the
objects - A < B iff A is an ancestor of B.
objects - A < B iff A is an ancestor of B.
That ordering can change. However, the following is true:
@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B.
non-directory object, except renames, which take locks on source and
target in inode pointer order in the case they are not directories.)
Now consider the minimal deadlock. Each process is blocked on
Now consider the minimal deadlock. Each process is blocked on
attempt to acquire some lock and already holds at least one lock. Let's
consider the set of contended locks. First of all, filesystem lock is
not contended, since any process blocked on it is not holding any locks.
Thus all processes are blocked on ->i_rwsem.
By (3), any process holding a non-directory lock can only be
By (3), any process holding a non-directory lock can only be
waiting on another non-directory lock with a larger address. Therefore
the process holding the "largest" such lock can always make progress, and
non-directory objects are not included in the set of contended locks.
Thus link creation can't be a part of deadlock - it can't be
Thus link creation can't be a part of deadlock - it can't be
blocked on source and it means that it doesn't hold any locks.
Any contended object is either held by cross-directory rename or
Any contended object is either held by cross-directory rename or
has a child that is also contended. Indeed, suppose that it is held by
operation other than cross-directory rename. Then the lock this operation
is blocked on belongs to child of that object due to (1).
It means that one of the operations is cross-directory rename.
It means that one of the operations is cross-directory rename.
Otherwise the set of contended objects would be infinite - each of them
would have a contended child and we had assumed that no object is its
own descendent. Moreover, there is exactly one cross-directory rename
(see above).
Consider the object blocking the cross-directory rename. One
Consider the object blocking the cross-directory rename. One
of its descendents is locked by cross-directory rename (otherwise we
would again have an infinite set of contended objects). But that
means that cross-directory rename is taking locks out of order. Due
@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor.
Contradiction. I.e. deadlock is impossible. Q.E.D.
These operations are guaranteed to avoid loop creation. Indeed,
These operations are guaranteed to avoid loop creation. Indeed,
the only operation that could introduce loops is cross-directory rename.
Since the only new (parent, child) pair added by rename() is (new parent,
source), such loop would have to contain these objects and the rest of it
@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when
we had acquired filesystem lock and rename() would fail with -ELOOP in that
case.
While this locking scheme works for arbitrary DAGs, it relies on
While this locking scheme works for arbitrary DAGs, it relies on
ability to check that directory is a descendent of another object. Current
implementation assumes that directory graph is a tree. This assumption is
also preserved by all operations (cross-directory rename on a tree that would
not introduce a cycle will leave it a tree and link() fails for directories).
Notice that "directory" in the above == "anything that might have
Notice that "directory" in the above == "anything that might have
children", so if we are going to introduce hybrid objects we will need
either to make sure that link(2) doesn't work for them or to make changes
in is_subdir() that would make it work even in presence of such beasts.

4
Documentation/filesystems/index.rst
View File

@ -20,6 +20,10 @@ algorithms work.
path-lookup
api-summary
splice
locking
directory-locking
porting
Filesystem support layers
=========================

257
Documentation/filesystems/Locking → Documentation/filesystems/locking.rst
View File

@ -1,14 +1,22 @@
The text below describes the locking rules for VFS-related methods.
=======
Locking
=======
The text below describes the locking rules for VFS-related methods.
It is (believed to be) up-to-date. *Please*, if you change anything in
prototypes or locking protocols - update this file. And update the relevant
instances in the tree, don't leave that to maintainers of filesystems/devices/
etc. At the very least, put the list of dubious cases in the end of this file.
Don't turn it into log - maintainers of out-of-the-tree code are supposed to
be able to use diff(1).
Thing currently missing here: socket operations. Alexey?
--------------------------- dentry_operations --------------------------
prototypes:
Thing currently missing here: socket operations. Alexey?
dentry_operations
=================
prototypes::
int (*d_revalidate)(struct dentry *, unsigned int);
int (*d_weak_revalidate)(struct dentry *, unsigned int);
int (*d_hash)(const struct dentry *, struct qstr *);
@ -24,23 +32,30 @@ prototypes:
struct dentry *(*d_real)(struct dentry *, const struct inode *);
locking rules:
rename_lock ->d_lock may block rcu-walk
d_revalidate: no no yes (ref-walk) maybe
d_weak_revalidate:no no yes no
d_hash no no no maybe
d_compare: yes no no maybe
d_delete: no yes no no
d_init: no no yes no
d_release: no no yes no
d_prune: no yes no no
d_iput: no no yes no
d_dname: no no no no
d_automount: no no yes no
d_manage: no no yes (ref-walk) maybe
d_real no no yes no
--------------------------- inode_operations ---------------------------
prototypes:
================== =========== ======== ============== ========
ops rename_lock ->d_lock may block rcu-walk
================== =========== ======== ============== ========
d_revalidate: no no yes (ref-walk) maybe
d_weak_revalidate: no no yes no
d_hash no no no maybe
d_compare: yes no no maybe
d_delete: no yes no no
d_init: no no yes no
d_release: no no yes no
d_prune: no yes no no
d_iput: no no yes no
d_dname: no no no no
d_automount: no no yes no
d_manage: no no yes (ref-walk) maybe
d_real no no yes no
================== =========== ======== ============== ========
inode_operations
================
prototypes::
int (*create) (struct inode *,struct dentry *,umode_t, bool);
struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
int (*link) (struct dentry *,struct inode *,struct dentry *);
@ -68,7 +83,10 @@ prototypes:
locking rules:
all may block
i_rwsem(inode)
============ =============================================
ops i_rwsem(inode)
============ =============================================
lookup: shared
create: exclusive
link: exclusive (both)
@ -89,17 +107,21 @@ fiemap: no
update_time: no
atomic_open: exclusive
tmpfile: no
============ =============================================
Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
exclusive on victim.
cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
See Documentation/filesystems/directory-locking for more detailed discussion
See Documentation/filesystems/directory-locking.rst for more detailed discussion
of the locking scheme for directory operations.
----------------------- xattr_handler operations -----------------------
prototypes:
xattr_handler operations
========================
prototypes::
bool (*list)(struct dentry *dentry);
int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
struct inode *inode, const char *name, void *buffer,
@ -110,13 +132,20 @@ prototypes:
locking rules:
all may block
i_rwsem(inode)
===== ==============
ops i_rwsem(inode)
===== ==============
list: no
get: no
set: exclusive
===== ==============
super_operations
================
prototypes::
--------------------------- super_operations ---------------------------
prototypes:
struct inode *(*alloc_inode)(struct super_block *sb);
void (*free_inode)(struct inode *);
void (*destroy_inode)(struct inode *);
@ -138,7 +167,10 @@ prototypes:
locking rules:
All may block [not true, see below]
s_umount
====================== ============ ========================
ops s_umount note
====================== ============ ========================
alloc_inode:
free_inode: called from RCU callback
destroy_inode:
@ -157,6 +189,7 @@ show_options: no (namespace_sem)
quota_read: no (see below)
quota_write: no (see below)
bdev_try_to_free_page: no (see below)
====================== ============ ========================
->statfs() has s_umount (shared) when called by ustat(2) (native or
compat), but that's an accident of bad API; s_umount is used to pin
@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to
identify the superblock. Everything else (statfs(), fstatfs(), etc.)
doesn't hold it when calling ->statfs() - superblock is pinned down
by resolving the pathname passed to syscall.
->quota_read() and ->quota_write() functions are both guaranteed to
be the only ones operating on the quota file by the quota code (via
dqio_sem) (unless an admin really wants to screw up something and
writes to quota files with quotas on). For other details about locking
see also dquot_operations section.
->bdev_try_to_free_page is called from the ->releasepage handler of
the block device inode. See there for more details.
--------------------------- file_system_type ---------------------------
prototypes:
file_system_type
================
prototypes::
struct dentry *(*mount) (struct file_system_type *, int,
const char *, void *);
void (*kill_sb) (struct super_block *);
locking rules:
may block
======= =========
ops may block
======= =========
mount yes
kill_sb yes
======= =========
->mount() returns ERR_PTR or the root dentry; its superblock should be locked
on return.
->kill_sb() takes a write-locked superblock, does all shutdown work on it,
unlocks and drops the reference.
--------------------------- address_space_operations --------------------------
prototypes:
address_space_operations
========================
prototypes::
int (*writepage)(struct page *page, struct writeback_control *wbc);
int (*readpage)(struct file *, struct page *);
int (*writepages)(struct address_space *, struct writeback_control *);
@ -218,14 +264,16 @@ prototypes:
locking rules:
All except set_page_dirty and freepage may block
PageLocked(page) i_rwsem
====================== ======================== =========
ops PageLocked(page) i_rwsem
====================== ======================== =========
writepage: yes, unlocks (see below)
readpage: yes, unlocks
writepages:
set_page_dirty no
readpages:
write_begin: locks the page exclusive
write_end: yes, unlocks exclusive
write_begin: locks the page exclusive
write_end: yes, unlocks exclusive
bmap:
invalidatepage: yes
releasepage: yes
@ -239,17 +287,18 @@ is_partially_uptodate: yes
error_remove_page: yes
swap_activate: no
swap_deactivate: no
====================== ======================== =========
->write_begin(), ->write_end() and ->readpage() may be called from
->write_begin(), ->write_end() and ->readpage() may be called from
the request handler (/dev/loop).
->readpage() unlocks the page, either synchronously or via I/O
->readpage() unlocks the page, either synchronously or via I/O
completion.
->readpages() populates the pagecache with the passed pages and starts
->readpages() populates the pagecache with the passed pages and starts
I/O against them. They come unlocked upon I/O completion.
->writepage() is used for two purposes: for "memory cleansing" and for
->writepage() is used for two purposes: for "memory cleansing" and for
"sync". These are quite different operations and the behaviour may differ
depending upon the mode.
@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the
radix tree. This incoherency can lead to all sorts of hard-to-debug problems
in the filesystem like having dirty inodes at umount and losing written data.
->writepages() is used for periodic writeback and for syscall-initiated
->writepages() is used for periodic writeback and for syscall-initiated
sync operations. The address_space should start I/O against at least
*nr_to_write pages. *nr_to_write must be decremented for each page which is
written. The address_space implementation may write more (or less) pages
than *nr_to_write asks for, but it should try to be reasonably close. If
nr_to_write is NULL, all dirty pages must be written.
``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page
which is written. The address_space implementation may write more (or less)
pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
If nr_to_write is NULL, all dirty pages must be written.
writepages should _only_ write pages which are present on
mapping->io_pages.
->set_page_dirty() is called from various places in the kernel
->set_page_dirty() is called from various places in the kernel
when the target page is marked as needing writeback. It may be called
under spinlock (it cannot block) and is sometimes called with the page
not locked.
->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
filesystems and by the swapper. The latter will eventually go away. Please,
keep it that way and don't breed new callers.
->invalidatepage() is called when the filesystem must attempt to drop
->invalidatepage() is called when the filesystem must attempt to drop
some or all of the buffers from the page when it is being truncated. It
returns zero on success. If ->invalidatepage is zero, the kernel uses
block_invalidatepage() instead.
->releasepage() is called when the kernel is about to try to drop the
->releasepage() is called when the kernel is about to try to drop the
buffers from the page in preparation for freeing it. It returns zero to
indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
the kernel assumes that the fs has no private interest in the buffers.
->freepage() is called when the kernel is done dropping the page
->freepage() is called when the kernel is done dropping the page
from the page cache.
->launder_page() may be called prior to releasing a page if
->launder_page() may be called prior to releasing a page if
it is still found to be dirty. It returns zero if the page was successfully
cleaned, or an error value if not. Note that in order to prevent the page
getting mapped back in and redirtied, it needs to be kept locked
across the entire operation.
->swap_activate will be called with a non-zero argument on
->swap_activate will be called with a non-zero argument on
files backing (non block device backed) swapfiles. A return value
of zero indicates success, in which case this file can be used for
backing swapspace. The swapspace operations will be proxied to the
address space operations.
->swap_deactivate() will be called in the sys_swapoff()
->swap_deactivate() will be called in the sys_swapoff()
path after ->swap_activate() returned success.
----------------------- file_lock_operations ------------------------------
prototypes:
file_lock_operations
====================
prototypes::
void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
void (*fl_release_private)(struct file_lock *);
locking rules:
inode->i_lock may block
=================== ============= =========
ops inode->i_lock may block
=================== ============= =========
fl_copy_lock: yes no
fl_release_private: maybe maybe[1]
fl_release_private: maybe maybe[1]_
=================== ============= =========
[1]: ->fl_release_private for flock or POSIX locks is currently allowed
to block. Leases however can still be freed while the i_lock is held and
so fl_release_private called on a lease should not block.
.. [1]:
->fl_release_private for flock or POSIX locks is currently allowed
to block. Leases however can still be freed while the i_lock is held and
so fl_release_private called on a lease should not block.
lock_manager_operations
=======================
prototypes::
----------------------- lock_manager_operations ---------------------------
prototypes:
void (*lm_notify)(struct file_lock *); /* unblock callback */
int (*lm_grant)(struct file_lock *, struct file_lock *, int);
void (*lm_break)(struct file_lock *); /* break_lease callback */
@ -368,24 +428,33 @@ prototypes:
locking rules:
inode->i_lock blocked_lock_lock may block
========== ============= ================= =========
ops inode->i_lock blocked_lock_lock may block
========== ============= ================= =========
lm_notify: yes yes no
lm_grant: no no no
lm_break: yes no no
lm_change yes no no
========== ============= ================= =========
buffer_head
===========
prototypes::
--------------------------- buffer_head -----------------------------------
prototypes:
void (*b_end_io)(struct buffer_head *bh, int uptodate);
locking rules:
called from interrupts. In other words, extreme care is needed here.
called from interrupts. In other words, extreme care is needed here.
bh is locked, but that's all warranties we have here. Currently only RAID1,
highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
call this method upon the IO completion.
--------------------------- block_device_operations -----------------------
prototypes:
block_device_operations
=======================
prototypes::
int (*open) (struct block_device *, fmode_t);
int (*release) (struct gendisk *, fmode_t);
int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
@ -399,7 +468,10 @@ prototypes:
void (*swap_slot_free_notify) (struct block_device *, unsigned long);
locking rules:
bd_mutex
======================= ===================
ops bd_mutex
======================= ===================
open: yes
release: yes
ioctl: no
@ -410,6 +482,7 @@ unlock_native_capacity: no
revalidate_disk: no
getgeo: no
swap_slot_free_notify: no (see below)
======================= ===================
media_changed, unlock_native_capacity and revalidate_disk are called only from
check_disk_change().
@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock
held.
--------------------------- file_operations -------------------------------
prototypes:
file_operations
===============
prototypes::
loff_t (*llseek) (struct file *, loff_t, int);
ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
@ -455,7 +531,6 @@ prototypes:
size_t, unsigned int);
int (*setlease)(struct file *, long, struct file_lock **, void **);
long (*fallocate)(struct file *, int, loff_t, loff_t);
};
locking rules:
All may block.
@ -490,8 +565,11 @@ in sys_read() and friends.
the lease within the individual filesystem to record the result of the
operation
--------------------------- dquot_operations -------------------------------
prototypes:
dquot_operations
================
prototypes::
int (*write_dquot) (struct dquot *);
int (*acquire_dquot) (struct dquot *);
int (*release_dquot) (struct dquot *);
@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations.
What filesystem should expect from the generic quota functions:
FS recursion Held locks when called
============== ============ =========================
ops FS recursion Held locks when called
============== ============ =========================
write_dquot: yes dqonoff_sem or dqptr_sem
acquire_dquot: yes dqonoff_sem or dqptr_sem
release_dquot: yes dqonoff_sem or dqptr_sem
mark_dirty: no -
write_info: yes dqonoff_sem
============== ============ =========================
FS recursion means calling ->quota_read() and ->quota_write() from superblock
operations.
More details about quota locking can be found in fs/dquot.c.
--------------------------- vm_operations_struct -----------------------------
prototypes:
vm_operations_struct
====================
prototypes::
void (*open)(struct vm_area_struct*);
void (*close)(struct vm_area_struct*);
vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
@ -525,7 +609,10 @@ prototypes:
int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
locking rules:
mmap_sem PageLocked(page)
============= ======== ===========================
ops mmap_sem PageLocked(page)
============= ======== ===========================
open: yes
close: yes
fault: yes can return with page locked
@ -533,8 +620,9 @@ map_pages: yes
page_mkwrite: yes can return with page locked
pfn_mkwrite: yes
access: yes
============= ======== ===========================
->fault() is called when a previously not present pte is about
->fault() is called when a previously not present pte is about
to be faulted in. The filesystem must find and return the page associated
with the passed in "pgoff" in the vm_fault structure. If it is possible that
the page may be truncated and/or invalidated, then the filesystem must lock
@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block
subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
locked. The VM will unlock the page.
->map_pages() is called when VM asks to map easy accessible pages.
->map_pages() is called when VM asks to map easy accessible pages.
Filesystem should find and map pages associated with offsets from "start_pgoff"
till "end_pgoff". ->map_pages() is called with page table locked and must
not block. If it's not possible to reach a page without blocking,
@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in
"pte" field in vm_fault structure. Pointers to entries for other offsets
should be calculated relative to "pte".
->page_mkwrite() is called when a previously read-only pte is
->page_mkwrite() is called when a previously read-only pte is
about to become writeable. The filesystem again must ensure that there are
no truncate/invalidate races, and then return with the page locked. If
the page has been truncated, the filesystem should not look up a new page
like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
will cause the VM to retry the fault.
->pfn_mkwrite() is the same as page_mkwrite but when the pte is
->pfn_mkwrite() is the same as page_mkwrite but when the pte is
VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
after this call is to make the pte read-write, unless pfn_mkwrite returns
an error.
->access() is called when get_user_pages() fails in
->access() is called when get_user_pages() fails in
access_process_vm(), typically used to debug a process through
/proc/pid/mem or ptrace. This function is needed only for
VM_IO | VM_PFNMAP VMAs.
================================================================================
--------------------------------------------------------------------------------
Dubious stuff
(if you break something or notice that it is broken and do not fix it yourself

31
Documentation/filesystems/nfs/Exporting → Documentation/filesystems/nfs/exporting.rst
View File

@ -1,3 +1,4 @@
:orphan:
Making Filesystems Exportable
=============================
@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix
for the object. This leads to two related but distinct features of
the dcache that are not needed for normal filesystem access.
1/ The dcache must sometimes contain objects that are not part of the
1. The dcache must sometimes contain objects that are not part of the
proper prefix. i.e that are not connected to the root.
2/ The dcache must be prepared for a newly found (via ->lookup) directory
2. The dcache must be prepared for a newly found (via ->lookup) directory
to already have a (non-connected) dentry, and must be able to move
that dentry into place (based on the parent and name in the
->lookup). This is particularly needed for directories as
@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access.
To implement these features, the dcache has:
a/ A dentry flag DCACHE_DISCONNECTED which is set on
a. A dentry flag DCACHE_DISCONNECTED which is set on
any dentry that might not be part of the proper prefix.
This is set when anonymous dentries are created, and cleared when a
dentry is noticed to be a child of a dentry which is in the proper
@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on
dentries. That guarantees that we won't need to hunt them down upon
umount.
b/ A primitive for creation of secondary roots - d_obtain_root(inode).
b. A primitive for creation of secondary roots - d_obtain_root(inode).
Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the
per-superblock list (->s_roots), so they can be located at umount
time for eviction purposes.
c/ Helper routines to allocate anonymous dentries, and to help attach
c. Helper routines to allocate anonymous dentries, and to help attach
loose directory dentries at lookup time. They are:
d_obtain_alias(inode) will return a dentry for the given inode.
If the inode already has a dentry, one of those is returned.
If it doesn't, a new anonymous (IS_ROOT and
DCACHE_DISCONNECTED) dentry is allocated and attached.
DCACHE_DISCONNECTED) dentry is allocated and attached.
In the case of a directory, care is taken that only one dentry
can ever be attached.
d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
either the passed-in dentry or a preexisting alias for the given inode
(such as an anonymous one created by d_obtain_alias), if appropriate.
It returns NULL when the passed-in dentry is used, following the calling
convention of ->lookup.
Filesystem Issues
-----------------
For a filesystem to be exportable it must:
1/ provide the filehandle fragment routines described below.
2/ make sure that d_splice_alias is used rather than d_add
1. provide the filehandle fragment routines described below.
2. make sure that d_splice_alias is used rather than d_add
when ->lookup finds an inode for a given parent and name.
If inode is NULL, d_splice_alias(inode, dentry) is equivalent to
If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::
d_add(dentry, inode), NULL
Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
Typically the ->lookup routine will simply end with a:
Typically the ->lookup routine will simply end with a::
return d_splice_alias(inode, dentry);
}
A file system implementation declares that instances of the filesystem
A file system implementation declares that instances of the filesystem
are exportable by setting the s_export_op field in the struct
super_block. This field must point to a "struct export_operations"
struct which has the following members:

686
Documentation/filesystems/porting
View File

@ -1,686 +0,0 @@
Changes since 2.5.0:
---
[recommended]
New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
sb_set_blocksize() and sb_min_blocksize().
Use them.
(sb_find_get_block() replaces 2.4's get_hash_table())
---
[recommended]
New methods: ->alloc_inode() and ->destroy_inode().
Remove inode->u.foo_inode_i
Declare
struct foo_inode_info {
/* fs-private stuff */
struct inode vfs_inode;
};
static inline struct foo_inode_info *FOO_I(struct inode *inode)
{
return list_entry(inode, struct foo_inode_info, vfs_inode);
}
Use FOO_I(inode) instead of &inode->u.foo_inode_i;
Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
foo_inode_info and return the address of ->vfs_inode, the latter should free
FOO_I(inode) (see in-tree filesystems for examples).
Make them ->alloc_inode and ->destroy_inode in your super_operations.
Keep in mind that now you need explicit initialization of private data
typically between calling iget_locked() and unlocking the inode.
At some point that will become mandatory.
---
[mandatory]
Change of file_system_type method (->read_super to ->get_sb)
->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
Turn your foo_read_super() into a function that would return 0 in case of
success and negative number in case of error (-EINVAL unless you have more
informative error value to report). Call it foo_fill_super(). Now declare
int foo_get_sb(struct file_system_type *fs_type,
int flags, const char *dev_name, void *data, struct vfsmount *mnt)
{
return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
mnt);
}
(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
filesystem).
Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
foo_get_sb.
---
[mandatory]
Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
Most likely there is no need to change anything, but if you relied on
global exclusion between renames for some internal purpose - you need to
change your internal locking. Otherwise exclusion warranties remain the
same (i.e. parents and victim are locked, etc.).
---
[informational]
Now we have the exclusion between ->lookup() and directory removal (by
->rmdir() and ->rename()). If you used to need that exclusion and do
it by internal locking (most of filesystems couldn't care less) - you
can relax your locking.
---
[mandatory]
->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
and ->readdir() are called without BKL now. Grab it on entry, drop upon return
- that will guarantee the same locking you used to have. If your method or its
parts do not need BKL - better yet, now you can shift lock_kernel() and
unlock_kernel() so that they would protect exactly what needs to be
protected.
---
[mandatory]
BKL is also moved from around sb operations. BKL should have been shifted into
individual fs sb_op functions. If you don't need it, remove it.
---
[informational]
check for ->link() target not being a directory is done by callers. Feel
free to drop it...
---
[informational]
->link() callers hold ->i_mutex on the object we are linking to. Some of your
problems might be over...
---
[mandatory]
new file_system_type method - kill_sb(superblock). If you are converting
an existing filesystem, set it according to ->fs_flags:
FS_REQUIRES_DEV - kill_block_super
FS_LITTER - kill_litter_super
neither - kill_anon_super
FS_LITTER is gone - just remove it from fs_flags.
---
[mandatory]
FS_SINGLE is gone (actually, that had happened back when ->get_sb()
went in - and hadn't been documented ;-/). Just remove it from fs_flags
(and see ->get_sb() entry for other actions).
---
[mandatory]
->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
watch for ->i_mutex-grabbing code that might be used by your ->setattr().
Callers of notify_change() need ->i_mutex now.
---
[recommended]
New super_block field "struct export_operations *s_export_op" for
explicit support for exporting, e.g. via NFS. The structure is fully
documented at its declaration in include/linux/fs.h, and in
Documentation/filesystems/nfs/Exporting.
Briefly it allows for the definition of decode_fh and encode_fh operations
to encode and decode filehandles, and allows the filesystem to use
a standard helper function for decode_fh, and provide file-system specific
support for this helper, particularly get_parent.
It is planned that this will be required for exporting once the code
settles down a bit.
[mandatory]
s_export_op is now required for exporting a filesystem.
isofs, ext2, ext3, resierfs, fat
can be used as examples of very different filesystems.
---
[mandatory]
iget4() and the read_inode2 callback have been superseded by iget5_locked()
which has the following prototype,
struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
int (*test)(struct inode *, void *),
int (*set)(struct inode *, void *),
void *data);
'test' is an additional function that can be used when the inode
number is not sufficient to identify the actual file object. 'set'
should be a non-blocking function that initializes those parts of a
newly created inode to allow the test function to succeed. 'data' is
passed as an opaque value to both test and set functions.
When the inode has been created by iget5_locked(), it will be returned with the
I_NEW flag set and will still be locked. The filesystem then needs to finalize
the initialization. Once the inode is initialized it must be unlocked by
calling unlock_new_inode().
The filesystem is responsible for setting (and possibly testing) i_ino
when appropriate. There is also a simpler iget_locked function that
just takes the superblock and inode number as arguments and does the
test and set for you.
e.g.
inode = iget_locked(sb, ino);
if (inode->i_state & I_NEW) {
err = read_inode_from_disk(inode);
if (err < 0) {
iget_failed(inode);
return err;
}
unlock_new_inode(inode);
}
Note that if the process of setting up a new inode fails, then iget_failed()
should be called on the inode to render it dead, and an appropriate error
should be passed back to the caller.
---
[recommended]
->getattr() finally getting used. See instances in nfs, minix, etc.
---
[mandatory]
->revalidate() is gone. If your filesystem had it - provide ->getattr()
and let it call whatever you had as ->revlidate() + (for symlinks that
had ->revalidate()) add calls in ->follow_link()/->readlink().
---
[mandatory]
->d_parent changes are not protected by BKL anymore. Read access is safe
if at least one of the following is true:
* filesystem has no cross-directory rename()
* we know that parent had been locked (e.g. we are looking at
->d_parent of ->lookup() argument).
* we are called from ->rename().
* the child's ->d_lock is held
Audit your code and add locking if needed. Notice that any place that is
not protected by the conditions above is risky even in the old tree - you
had been relying on BKL and that's prone to screwups. Old tree had quite
a few holes of that kind - unprotected access to ->d_parent leading to
anything from oops to silent memory corruption.
---
[mandatory]
FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
(see rootfs for one kind of solution and bdev/socket/pipe for another).
---
[recommended]
Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
is still alive, but only because of the mess in drivers/s390/block/dasd.c.
As soon as it gets fixed is_read_only() will die.
---
[mandatory]
->permission() is called without BKL now. Grab it on entry, drop upon
return - that will guarantee the same locking you used to have. If
your method or its parts do not need BKL - better yet, now you can
shift lock_kernel() and unlock_kernel() so that they would protect
exactly what needs to be protected.
---
[mandatory]
->statfs() is now called without BKL held. BKL should have been
shifted into individual fs sb_op functions where it's not clear that
it's safe to remove it. If you don't need it, remove it.
---
[mandatory]
is_read_only() is gone; use bdev_read_only() instead.
---
[mandatory]
destroy_buffers() is gone; use invalidate_bdev().
---
[mandatory]
fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
deliberate; as soon as struct block_device * is propagated in a reasonable
way by that code fixing will become trivial; until then nothing can be
done.
[mandatory]
block truncatation on error exit from ->write_begin, and ->direct_IO
moved from generic methods (block_write_begin, cont_write_begin,
nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
ext2_write_failed and callers for an example.
[mandatory]
->truncate is gone. The whole truncate sequence needs to be
implemented in ->setattr, which is now mandatory for filesystems
implementing on-disk size changes. Start with a copy of the old inode_setattr
and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
be in order of zeroing blocks using block_truncate_page or similar helpers,
size update and on finally on-disk truncation which should not fail.
setattr_prepare (which used to be inode_change_ok) now includes the size checks
for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
[mandatory]
->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
be used instead. It gets called whenever the inode is evicted, whether it has
remaining links or not. Caller does *not* evict the pagecache or inode-associated
metadata buffers; the method has to use truncate_inode_pages_final() to get rid
of those. Caller makes sure async writeback cannot be running for the inode while
(or after) ->evict_inode() is called.
->drop_inode() returns int now; it's called on final iput() with
inode->i_lock held and it returns true if filesystems wants the inode to be
dropped. As before, generic_drop_inode() is still the default and it's been
updated appropriately. generic_delete_inode() is also alive and it consists
simply of return 1. Note that all actual eviction work is done by caller after
->drop_inode() returns.
As before, clear_inode() must be called exactly once on each call of
->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
before, if you are using inode-associated metadata buffers (i.e.
mark_buffer_dirty_inode()), it's your responsibility to call
invalidate_inode_buffers() before clear_inode().
NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
free the on-disk inode, you may end up doing that while ->write_inode() is writing
to it.
---
[mandatory]
.d_delete() now only advises the dcache as to whether or not to cache
unreferenced dentries, and is now only called when the dentry refcount goes to
0. Even on 0 refcount transition, it must be able to tolerate being called 0,
1, or more times (eg. constant, idempotent).
---
[mandatory]
.d_compare() calling convention and locking rules are significantly
changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
look at examples of other filesystems) for guidance.
---
[mandatory]
.d_hash() calling convention and locking rules are significantly
changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
look at examples of other filesystems) for guidance.
---
[mandatory]
dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
for details of what locks to replace dcache_lock with in order to protect
particular things. Most of the time, a filesystem only needs ->d_lock, which
protects *all* the dcache state of a given dentry.
--
[mandatory]
Filesystems must RCU-free their inodes, if they can have been accessed
via rcu-walk path walk (basically, if the file can have had a path name in the
vfs namespace).
Even though i_dentry and i_rcu share storage in a union, we will
initialize the former in inode_init_always(), so just leave it alone in
the callback. It used to be necessary to clean it there, but not anymore
(starting at 3.2).
--
[recommended]
vfs now tries to do path walking in "rcu-walk mode", which avoids
atomic operations and scalability hazards on dentries and inodes (see
Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
(above) are examples of the changes required to support this. For more complex
filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
no changes are required to the filesystem. However, this is costly and loses
the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
are rcu-walk aware, shown below. Filesystems should take advantage of this
where possible.
--
[mandatory]
d_revalidate is a callback that is made on every path element (if
the filesystem provides it), which requires dropping out of rcu-walk mode. This
may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
returned if the filesystem cannot handle rcu-walk. See
Documentation/filesystems/vfs.rst for more details.
permission is an inode permission check that is called on many or all
directory inodes on the way down a path walk (to check for exec permission). It
must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
Documentation/filesystems/vfs.rst for more details.
--
[mandatory]
In ->fallocate() you must check the mode option passed in. If your
filesystem does not support hole punching (deallocating space in the middle of a
file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
so the i_size should not change when hole punching, even when puching the end of
a file off.
--
[mandatory]
->get_sb() is gone. Switch to use of ->mount(). Typically it's just
a matter of switching from calling get_sb_... to mount_... and changing the
function type. If you were doing it manually, just switch from setting ->mnt_root
to some pointer to returning that pointer. On errors return ERR_PTR(...).
--
[mandatory]
->permission() and generic_permission()have lost flags
argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
generic_permission() has also lost the check_acl argument; ACL checking
has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
to read an ACL from disk.
--
[mandatory]
If you implement your own ->llseek() you must handle SEEK_HOLE and
SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
support it in some way. The generic handler assumes that the entire file is
data and there is a virtual hole at the end of the file. So if the provided
offset is less than i_size and SEEK_DATA is specified, return the same offset.
If the above is true for the offset and you are given SEEK_HOLE, return the end
of the file. If the offset is i_size or greater return -ENXIO in either case.
[mandatory]
If you have your own ->fsync() you must make sure to call
filemap_write_and_wait_range() so that all dirty pages are synced out properly.
You must also keep in mind that ->fsync() is not called with i_mutex held
anymore, so if you require i_mutex locking you must make sure to take it and
release it yourself.
--
[mandatory]
d_alloc_root() is gone, along with a lot of bugs caused by code
misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
allocates and returns a new dentry instantiated with the passed in inode.
On failure NULL is returned and the passed in inode is dropped so the reference
to inode is consumed in all cases and failure handling need not do any cleanup
for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
and also requires no further error handling. Typical usage is:
inode = foofs_new_inode(....);
s->s_root = d_make_root(inode);
if (!s->s_root)
/* Nothing needed for the inode cleanup */
return -ENOMEM;
...
--
[mandatory]
The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
->lookup() do *not* take struct nameidata anymore; just the flags.
--
[mandatory]
->create() doesn't take struct nameidata *; unlike the previous
two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
local filesystems can ignore tha argument - they are guaranteed that the
object doesn't exist. It's remote/distributed ones that might care...
--
[mandatory]
FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
in your dentry operations instead.
--
[mandatory]
vfs_readdir() is gone; switch to iterate_dir() instead
--
[mandatory]
->readdir() is gone now; switch to ->iterate()
[mandatory]
vfs_follow_link has been removed. Filesystems must use nd_set_link
from ->follow_link for normal symlinks, or nd_jump_link for magic
/proc/<pid> style links.
--
[mandatory]
iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
called with both ->i_lock and inode_hash_lock held; the former is *not*
taken anymore, so verify that your callbacks do not rely on it (none
of the in-tree instances did). inode_hash_lock is still held,
of course, so they are still serialized wrt removal from inode hash,
as well as wrt set() callback of iget5_locked().
--
[mandatory]
d_materialise_unique() is gone; d_splice_alias() does everything you
need now. Remember that they have opposite orders of arguments ;-/
--
[mandatory]
f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
it entirely.
--
[mandatory]
never call ->read() and ->write() directly; use __vfs_{read,write} or
wrappers; instead of checking for ->write or ->read being NULL, look for
FMODE_CAN_{WRITE,READ} in file->f_mode.
--
[mandatory]
do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
instead.
--
[mandatory]
->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
---
[recommended]
for embedded ("fast") symlinks just set inode->i_link to wherever the
symlink body is and use simple_follow_link() as ->follow_link().
--
[mandatory]
calling conventions for ->follow_link() have changed. Instead of returning
cookie and using nd_set_link() to store the body to traverse, we return
the body to traverse and store the cookie using explicit void ** argument.
nameidata isn't passed at all - nd_jump_link() doesn't need it and
nd_[gs]et_link() is gone.
--
[mandatory]
calling conventions for ->put_link() have changed. It gets inode instead of
dentry, it does not get nameidata at all and it gets called only when cookie
is non-NULL. Note that link body isn't available anymore, so if you need it,
store it as cookie.
--
[mandatory]
any symlink that might use page_follow_link_light/page_put_link() must
have inode_nohighmem(inode) called before anything might start playing with
its pagecache. No highmem pages should end up in the pagecache of such
symlinks. That includes any preseeding that might be done during symlink
creation. __page_symlink() will honour the mapping gfp flags, so once
you've done inode_nohighmem() it's safe to use, but if you allocate and
insert the page manually, make sure to use the right gfp flags.
--
[mandatory]
->follow_link() is replaced with ->get_link(); same API, except that
* ->get_link() gets inode as a separate argument
* ->get_link() may be called in RCU mode - in that case NULL
dentry is passed
--
[mandatory]
->get_link() gets struct delayed_call *done now, and should do
set_delayed_call() where it used to set *cookie.
->put_link() is gone - just give the destructor to set_delayed_call()
in ->get_link().
--
[mandatory]
->getxattr() and xattr_handler.get() get dentry and inode passed separately.
dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
called before we attach dentry to inode.
--
[mandatory]
symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
it's a symlink. Checking ->i_mode is really needed now. In-tree we had
to fix shmem_destroy_callback() that used to take that kind of shortcut;
watch out, since that shortcut is no longer valid.
--
[mandatory]
->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
they used to - they just take it exclusive. However, ->lookup() may be
called with parent locked shared. Its instances must not
* use d_instantiate) and d_rehash() separately - use d_add() or
d_splice_alias() instead.
* use d_rehash() alone - call d_add(new_dentry, NULL) instead.
* in the unlikely case when (read-only) access to filesystem
data structures needs exclusion for some reason, arrange it
yourself. None of the in-tree filesystems needed that.
* rely on ->d_parent and ->d_name not changing after dentry has
been fed to d_add() or d_splice_alias(). Again, none of the
in-tree instances relied upon that.
We are guaranteed that lookups of the same name in the same directory
will not happen in parallel ("same" in the sense of your ->d_compare()).
Lookups on different names in the same directory can and do happen in
parallel now.
--
[recommended]
->iterate_shared() is added; it's a parallel variant of ->iterate().
Exclusion on struct file level is still provided (as well as that
between it and lseek on the same struct file), but if your directory
has been opened several times, you can get these called in parallel.
Exclusion between that method and all directory-modifying ones is
still provided, of course.
Often enough ->iterate() can serve as ->iterate_shared() without any
changes - it is a read-only operation, after all. If you have any
per-inode or per-dentry in-core data structures modified by ->iterate(),
you might need something to serialize the access to them. If you
do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
that; look for in-tree examples.
Old method is only used if the new one is absent; eventually it will
be removed. Switch while you still can; the old one won't stay.
--
[mandatory]
->atomic_open() calls without O_CREAT may happen in parallel.
--
[mandatory]
->setxattr() and xattr_handler.set() get dentry and inode passed separately.
dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
--
[mandatory]
->d_compare() doesn't get parent as a separate argument anymore. If you
used it for finding the struct super_block involved, dentry->d_sb will
work just as well; if it's something more complicated, use dentry->d_parent.
Just be careful not to assume that fetching it more than once will yield
the same value - in RCU mode it could change under you.
--
[mandatory]
->rename() has an added flags argument. Any flags not handled by the
filesystem should result in EINVAL being returned.
--
[recommended]
->readlink is optional for symlinks. Don't set, unless filesystem needs
to fake something for readlink(2).
--
[mandatory]
->getattr() is now passed a struct path rather than a vfsmount and
dentry separately, and it now has request_mask and query_flags arguments
to specify the fields and sync type requested by statx. Filesystems not
supporting any statx-specific features may ignore the new arguments.
--
[mandatory]
->atomic_open() calling conventions have changed. Gone is int *opened,
along with FILE_OPENED/FILE_CREATED. In place of those we have
FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
value for 'called finish_no_open(), open it yourself' case has become
0, not 1. Since finish_no_open() itself is returning 0 now, that part
does not need any changes in ->atomic_open() instances.
--
[mandatory]
alloc_file() has become static now; two wrappers are to be used instead.
alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
when dentry needs to be created; that's the majority of old alloc_file()
users. Calling conventions: on success a reference to new struct file
is returned and callers reference to inode is subsumed by that. On
failure, ERR_PTR() is returned and no caller's references are affected,
so the caller needs to drop the inode reference it held.
alloc_file_clone(file, flags, ops) does not affect any caller's references.
On success you get a new struct file sharing the mount/dentry with the
original, on failure - ERR_PTR().
--
[mandatory]
->clone_file_range() and ->dedupe_file_range have been replaced with
->remap_file_range(). See Documentation/filesystems/vfs.rst for more
information.
--
[recommended]
->lookup() instances doing an equivalent of
if (IS_ERR(inode))
return ERR_CAST(inode);
return d_splice_alias(inode, dentry);
don't need to bother with the check - d_splice_alias() will do the
right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
inode to d_splice_alias() will also do the right thing (equivalent of
d_add(dentry, NULL); return NULL;), so that kind of special cases
also doesn't need a separate treatment.
--
[strongly recommended]
take the RCU-delayed parts of ->destroy_inode() into a new method -
->free_inode(). If ->destroy_inode() becomes empty - all the better,
just get rid of it. Synchronous work (e.g. the stuff that can't
be done from an RCU callback, or any WARN_ON() where we want the
stack trace) *might* be movable to ->evict_inode(); however,
that goes only for the things that are not needed to balance something
done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
might have accumulated over the life of in-core inode, ->evict_inode()
might be a fit.
Rules for inode destruction:
* if ->destroy_inode() is non-NULL, it gets called
* if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
* combination of NULL ->destroy_inode and NULL ->free_inode is
treated as NULL/free_inode_nonrcu, to preserve the compatibility.
Note that the callback (be it via ->free_inode() or explicit call_rcu()
in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
as the matter of fact, the superblock and all associated structures
might be already gone. The filesystem driver is guaranteed to be still
there, but that's it. Freeing memory in the callback is fine; doing
more than that is possible, but requires a lot of care and is best
avoided.
--
[mandatory]
DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
business doing so.
--
[mandatory]
d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
very suspect (and won't work in modules). Such uses are very likely to
be misspelled d_alloc_anon().

852
Documentation/filesystems/porting.rst Normal file
View File

@ -0,0 +1,852 @@
====================
Changes since 2.5.0:
====================
---
**recommended**
New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
sb_set_blocksize() and sb_min_blocksize().
Use them.
(sb_find_get_block() replaces 2.4's get_hash_table())
---
**recommended**
New methods: ->alloc_inode() and ->destroy_inode().
Remove inode->u.foo_inode_i
Declare::
struct foo_inode_info {
/* fs-private stuff */
struct inode vfs_inode;
};
static inline struct foo_inode_info *FOO_I(struct inode *inode)
{
return list_entry(inode, struct foo_inode_info, vfs_inode);
}
Use FOO_I(inode) instead of &inode->u.foo_inode_i;
Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
foo_inode_info and return the address of ->vfs_inode, the latter should free
FOO_I(inode) (see in-tree filesystems for examples).
Make them ->alloc_inode and ->destroy_inode in your super_operations.
Keep in mind that now you need explicit initialization of private data
typically between calling iget_locked() and unlocking the inode.
At some point that will become mandatory.
---
**mandatory**
Change of file_system_type method (->read_super to ->get_sb)
->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
Turn your foo_read_super() into a function that would return 0 in case of
success and negative number in case of error (-EINVAL unless you have more
informative error value to report). Call it foo_fill_super(). Now declare::
int foo_get_sb(struct file_system_type *fs_type,
int flags, const char *dev_name, void *data, struct vfsmount *mnt)
{
return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
mnt);
}
(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
filesystem).
Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
foo_get_sb.
---
**mandatory**
Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
Most likely there is no need to change anything, but if you relied on
global exclusion between renames for some internal purpose - you need to
change your internal locking. Otherwise exclusion warranties remain the
same (i.e. parents and victim are locked, etc.).
---
**informational**
Now we have the exclusion between ->lookup() and directory removal (by
->rmdir() and ->rename()). If you used to need that exclusion and do
it by internal locking (most of filesystems couldn't care less) - you
can relax your locking.
---
**mandatory**
->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
and ->readdir() are called without BKL now. Grab it on entry, drop upon return
- that will guarantee the same locking you used to have. If your method or its
parts do not need BKL - better yet, now you can shift lock_kernel() and
unlock_kernel() so that they would protect exactly what needs to be
protected.
---
**mandatory**
BKL is also moved from around sb operations. BKL should have been shifted into
individual fs sb_op functions. If you don't need it, remove it.
---
**informational**
check for ->link() target not being a directory is done by callers. Feel
free to drop it...
---
**informational**
->link() callers hold ->i_mutex on the object we are linking to. Some of your
problems might be over...
---
**mandatory**
new file_system_type method - kill_sb(superblock). If you are converting
an existing filesystem, set it according to ->fs_flags::
FS_REQUIRES_DEV - kill_block_super
FS_LITTER - kill_litter_super
neither - kill_anon_super
FS_LITTER is gone - just remove it from fs_flags.
---
**mandatory**
FS_SINGLE is gone (actually, that had happened back when ->get_sb()
went in - and hadn't been documented ;-/). Just remove it from fs_flags
(and see ->get_sb() entry for other actions).
---
**mandatory**
->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
watch for ->i_mutex-grabbing code that might be used by your ->setattr().
Callers of notify_change() need ->i_mutex now.
---
**recommended**
New super_block field ``struct export_operations *s_export_op`` for
explicit support for exporting, e.g. via NFS. The structure is fully
documented at its declaration in include/linux/fs.h, and in
Documentation/filesystems/nfs/exporting.rst.
Briefly it allows for the definition of decode_fh and encode_fh operations
to encode and decode filehandles, and allows the filesystem to use
a standard helper function for decode_fh, and provide file-system specific
support for this helper, particularly get_parent.
It is planned that this will be required for exporting once the code
settles down a bit.
**mandatory**
s_export_op is now required for exporting a filesystem.
isofs, ext2, ext3, resierfs, fat
can be used as examples of very different filesystems.
---
**mandatory**
iget4() and the read_inode2 callback have been superseded by iget5_locked()
which has the following prototype::
struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
int (*test)(struct inode *, void *),
int (*set)(struct inode *, void *),
void *data);
'test' is an additional function that can be used when the inode
number is not sufficient to identify the actual file object. 'set'
should be a non-blocking function that initializes those parts of a
newly created inode to allow the test function to succeed. 'data' is
passed as an opaque value to both test and set functions.
When the inode has been created by iget5_locked(), it will be returned with the
I_NEW flag set and will still be locked. The filesystem then needs to finalize
the initialization. Once the inode is initialized it must be unlocked by
calling unlock_new_inode().
The filesystem is responsible for setting (and possibly testing) i_ino
when appropriate. There is also a simpler iget_locked function that
just takes the superblock and inode number as arguments and does the
test and set for you.
e.g.::
inode = iget_locked(sb, ino);
if (inode->i_state & I_NEW) {
err = read_inode_from_disk(inode);
if (err < 0) {
iget_failed(inode);
return err;
}
unlock_new_inode(inode);
}
Note that if the process of setting up a new inode fails, then iget_failed()
should be called on the inode to render it dead, and an appropriate error
should be passed back to the caller.
---
**recommended**
->getattr() finally getting used. See instances in nfs, minix, etc.
---
**mandatory**
->revalidate() is gone. If your filesystem had it - provide ->getattr()
and let it call whatever you had as ->revlidate() + (for symlinks that
had ->revalidate()) add calls in ->follow_link()/->readlink().
---
**mandatory**
->d_parent changes are not protected by BKL anymore. Read access is safe
if at least one of the following is true:
* filesystem has no cross-directory rename()
* we know that parent had been locked (e.g. we are looking at
->d_parent of ->lookup() argument).
* we are called from ->rename().
* the child's ->d_lock is held
Audit your code and add locking if needed. Notice that any place that is
not protected by the conditions above is risky even in the old tree - you
had been relying on BKL and that's prone to screwups. Old tree had quite
a few holes of that kind - unprotected access to ->d_parent leading to
anything from oops to silent memory corruption.
---
**mandatory**
FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
(see rootfs for one kind of solution and bdev/socket/pipe for another).
---
**recommended**
Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
is still alive, but only because of the mess in drivers/s390/block/dasd.c.
As soon as it gets fixed is_read_only() will die.
---
**mandatory**
->permission() is called without BKL now. Grab it on entry, drop upon
return - that will guarantee the same locking you used to have. If
your method or its parts do not need BKL - better yet, now you can
shift lock_kernel() and unlock_kernel() so that they would protect
exactly what needs to be protected.
---
**mandatory**
->statfs() is now called without BKL held. BKL should have been
shifted into individual fs sb_op functions where it's not clear that
it's safe to remove it. If you don't need it, remove it.
---
**mandatory**
is_read_only() is gone; use bdev_read_only() instead.
---
**mandatory**
destroy_buffers() is gone; use invalidate_bdev().
---
**mandatory**
fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
deliberate; as soon as struct block_device * is propagated in a reasonable
way by that code fixing will become trivial; until then nothing can be
done.
**mandatory**
block truncatation on error exit from ->write_begin, and ->direct_IO
moved from generic methods (block_write_begin, cont_write_begin,
nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
ext2_write_failed and callers for an example.
**mandatory**
->truncate is gone. The whole truncate sequence needs to be
implemented in ->setattr, which is now mandatory for filesystems
implementing on-disk size changes. Start with a copy of the old inode_setattr
and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
be in order of zeroing blocks using block_truncate_page or similar helpers,
size update and on finally on-disk truncation which should not fail.
setattr_prepare (which used to be inode_change_ok) now includes the size checks
for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
**mandatory**
->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
be used instead. It gets called whenever the inode is evicted, whether it has
remaining links or not. Caller does *not* evict the pagecache or inode-associated
metadata buffers; the method has to use truncate_inode_pages_final() to get rid
of those. Caller makes sure async writeback cannot be running for the inode while
(or after) ->evict_inode() is called.
->drop_inode() returns int now; it's called on final iput() with
inode->i_lock held and it returns true if filesystems wants the inode to be
dropped. As before, generic_drop_inode() is still the default and it's been
updated appropriately. generic_delete_inode() is also alive and it consists
simply of return 1. Note that all actual eviction work is done by caller after
->drop_inode() returns.
As before, clear_inode() must be called exactly once on each call of
->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
before, if you are using inode-associated metadata buffers (i.e.
mark_buffer_dirty_inode()), it's your responsibility to call
invalidate_inode_buffers() before clear_inode().
NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
free the on-disk inode, you may end up doing that while ->write_inode() is writing
to it.
---
**mandatory**
.d_delete() now only advises the dcache as to whether or not to cache
unreferenced dentries, and is now only called when the dentry refcount goes to
0. Even on 0 refcount transition, it must be able to tolerate being called 0,
1, or more times (eg. constant, idempotent).
---
**mandatory**
.d_compare() calling convention and locking rules are significantly
changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
look at examples of other filesystems) for guidance.
---
**mandatory**
.d_hash() calling convention and locking rules are significantly
changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
look at examples of other filesystems) for guidance.
---
**mandatory**
dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
for details of what locks to replace dcache_lock with in order to protect
particular things. Most of the time, a filesystem only needs ->d_lock, which
protects *all* the dcache state of a given dentry.
---
**mandatory**
Filesystems must RCU-free their inodes, if they can have been accessed
via rcu-walk path walk (basically, if the file can have had a path name in the
vfs namespace).
Even though i_dentry and i_rcu share storage in a union, we will
initialize the former in inode_init_always(), so just leave it alone in
the callback. It used to be necessary to clean it there, but not anymore
(starting at 3.2).
---
**recommended**
vfs now tries to do path walking in "rcu-walk mode", which avoids
atomic operations and scalability hazards on dentries and inodes (see
Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
(above) are examples of the changes required to support this. For more complex
filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
no changes are required to the filesystem. However, this is costly and loses
the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
are rcu-walk aware, shown below. Filesystems should take advantage of this
where possible.
---
**mandatory**
d_revalidate is a callback that is made on every path element (if
the filesystem provides it), which requires dropping out of rcu-walk mode. This
may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
returned if the filesystem cannot handle rcu-walk. See
Documentation/filesystems/vfs.rst for more details.
permission is an inode permission check that is called on many or all
directory inodes on the way down a path walk (to check for exec permission). It
must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
Documentation/filesystems/vfs.rst for more details.
---
**mandatory**
In ->fallocate() you must check the mode option passed in. If your
filesystem does not support hole punching (deallocating space in the middle of a
file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
so the i_size should not change when hole punching, even when puching the end of
a file off.
---
**mandatory**
->get_sb() is gone. Switch to use of ->mount(). Typically it's just
a matter of switching from calling ``get_sb_``... to ``mount_``... and changing
the function type. If you were doing it manually, just switch from setting
->mnt_root to some pointer to returning that pointer. On errors return
ERR_PTR(...).
---
**mandatory**
->permission() and generic_permission()have lost flags
argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
generic_permission() has also lost the check_acl argument; ACL checking
has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
to read an ACL from disk.
---
**mandatory**
If you implement your own ->llseek() you must handle SEEK_HOLE and
SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
support it in some way. The generic handler assumes that the entire file is
data and there is a virtual hole at the end of the file. So if the provided
offset is less than i_size and SEEK_DATA is specified, return the same offset.
If the above is true for the offset and you are given SEEK_HOLE, return the end
of the file. If the offset is i_size or greater return -ENXIO in either case.
**mandatory**
If you have your own ->fsync() you must make sure to call
filemap_write_and_wait_range() so that all dirty pages are synced out properly.
You must also keep in mind that ->fsync() is not called with i_mutex held
anymore, so if you require i_mutex locking you must make sure to take it and
release it yourself.
---
**mandatory**
d_alloc_root() is gone, along with a lot of bugs caused by code
misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
allocates and returns a new dentry instantiated with the passed in inode.
On failure NULL is returned and the passed in inode is dropped so the reference
to inode is consumed in all cases and failure handling need not do any cleanup
for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
and also requires no further error handling. Typical usage is::
inode = foofs_new_inode(....);
s->s_root = d_make_root(inode);
if (!s->s_root)
/* Nothing needed for the inode cleanup */
return -ENOMEM;
...
---
**mandatory**
The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
->lookup() do *not* take struct nameidata anymore; just the flags.
---
**mandatory**
->create() doesn't take ``struct nameidata *``; unlike the previous
two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
local filesystems can ignore tha argument - they are guaranteed that the
object doesn't exist. It's remote/distributed ones that might care...
---
**mandatory**
FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
in your dentry operations instead.
---
**mandatory**
vfs_readdir() is gone; switch to iterate_dir() instead
---
**mandatory**
->readdir() is gone now; switch to ->iterate()
**mandatory**
vfs_follow_link has been removed. Filesystems must use nd_set_link
from ->follow_link for normal symlinks, or nd_jump_link for magic
/proc/<pid> style links.
---
**mandatory**
iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
called with both ->i_lock and inode_hash_lock held; the former is *not*
taken anymore, so verify that your callbacks do not rely on it (none
of the in-tree instances did). inode_hash_lock is still held,
of course, so they are still serialized wrt removal from inode hash,
as well as wrt set() callback of iget5_locked().
---
**mandatory**
d_materialise_unique() is gone; d_splice_alias() does everything you
need now. Remember that they have opposite orders of arguments ;-/
---
**mandatory**
f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
it entirely.
---
**mandatory**
never call ->read() and ->write() directly; use __vfs_{read,write} or
wrappers; instead of checking for ->write or ->read being NULL, look for
FMODE_CAN_{WRITE,READ} in file->f_mode.
---
**mandatory**
do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
instead.
---
**mandatory**
->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
---
**recommended**
for embedded ("fast") symlinks just set inode->i_link to wherever the
symlink body is and use simple_follow_link() as ->follow_link().
---
**mandatory**
calling conventions for ->follow_link() have changed. Instead of returning
cookie and using nd_set_link() to store the body to traverse, we return
the body to traverse and store the cookie using explicit void ** argument.
nameidata isn't passed at all - nd_jump_link() doesn't need it and
nd_[gs]et_link() is gone.
---
**mandatory**
calling conventions for ->put_link() have changed. It gets inode instead of
dentry, it does not get nameidata at all and it gets called only when cookie
is non-NULL. Note that link body isn't available anymore, so if you need it,
store it as cookie.
---
**mandatory**
any symlink that might use page_follow_link_light/page_put_link() must
have inode_nohighmem(inode) called before anything might start playing with
its pagecache. No highmem pages should end up in the pagecache of such
symlinks. That includes any preseeding that might be done during symlink
creation. __page_symlink() will honour the mapping gfp flags, so once
you've done inode_nohighmem() it's safe to use, but if you allocate and
insert the page manually, make sure to use the right gfp flags.
---
**mandatory**
->follow_link() is replaced with ->get_link(); same API, except that
* ->get_link() gets inode as a separate argument
* ->get_link() may be called in RCU mode - in that case NULL
dentry is passed
---
**mandatory**
->get_link() gets struct delayed_call ``*done`` now, and should do
set_delayed_call() where it used to set ``*cookie``.
->put_link() is gone - just give the destructor to set_delayed_call()
in ->get_link().
---
**mandatory**
->getxattr() and xattr_handler.get() get dentry and inode passed separately.
dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
called before we attach dentry to inode.
---
**mandatory**
symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
it's a symlink. Checking ->i_mode is really needed now. In-tree we had
to fix shmem_destroy_callback() that used to take that kind of shortcut;
watch out, since that shortcut is no longer valid.
---
**mandatory**
->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
they used to - they just take it exclusive. However, ->lookup() may be
called with parent locked shared. Its instances must not
* use d_instantiate) and d_rehash() separately - use d_add() or
d_splice_alias() instead.
* use d_rehash() alone - call d_add(new_dentry, NULL) instead.
* in the unlikely case when (read-only) access to filesystem
data structures needs exclusion for some reason, arrange it
yourself. None of the in-tree filesystems needed that.
* rely on ->d_parent and ->d_name not changing after dentry has
been fed to d_add() or d_splice_alias(). Again, none of the
in-tree instances relied upon that.
We are guaranteed that lookups of the same name in the same directory
will not happen in parallel ("same" in the sense of your ->d_compare()).
Lookups on different names in the same directory can and do happen in
parallel now.
---
**recommended**
->iterate_shared() is added; it's a parallel variant of ->iterate().
Exclusion on struct file level is still provided (as well as that
between it and lseek on the same struct file), but if your directory
has been opened several times, you can get these called in parallel.
Exclusion between that method and all directory-modifying ones is
still provided, of course.
Often enough ->iterate() can serve as ->iterate_shared() without any
changes - it is a read-only operation, after all. If you have any
per-inode or per-dentry in-core data structures modified by ->iterate(),
you might need something to serialize the access to them. If you
do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
that; look for in-tree examples.
Old method is only used if the new one is absent; eventually it will
be removed. Switch while you still can; the old one won't stay.
---
**mandatory**
->atomic_open() calls without O_CREAT may happen in parallel.
---
**mandatory**
->setxattr() and xattr_handler.set() get dentry and inode passed separately.
dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
---
**mandatory**
->d_compare() doesn't get parent as a separate argument anymore. If you
used it for finding the struct super_block involved, dentry->d_sb will
work just as well; if it's something more complicated, use dentry->d_parent.
Just be careful not to assume that fetching it more than once will yield
the same value - in RCU mode it could change under you.
---
**mandatory**
->rename() has an added flags argument. Any flags not handled by the
filesystem should result in EINVAL being returned.
---
**recommended**
->readlink is optional for symlinks. Don't set, unless filesystem needs
to fake something for readlink(2).
---
**mandatory**
->getattr() is now passed a struct path rather than a vfsmount and
dentry separately, and it now has request_mask and query_flags arguments
to specify the fields and sync type requested by statx. Filesystems not
supporting any statx-specific features may ignore the new arguments.
---
**mandatory**
->atomic_open() calling conventions have changed. Gone is ``int *opened``,
along with FILE_OPENED/FILE_CREATED. In place of those we have
FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
value for 'called finish_no_open(), open it yourself' case has become
0, not 1. Since finish_no_open() itself is returning 0 now, that part
does not need any changes in ->atomic_open() instances.
---
**mandatory**
alloc_file() has become static now; two wrappers are to be used instead.
alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
when dentry needs to be created; that's the majority of old alloc_file()
users. Calling conventions: on success a reference to new struct file
is returned and callers reference to inode is subsumed by that. On
failure, ERR_PTR() is returned and no caller's references are affected,
so the caller needs to drop the inode reference it held.
alloc_file_clone(file, flags, ops) does not affect any caller's references.
On success you get a new struct file sharing the mount/dentry with the
original, on failure - ERR_PTR().
---
**mandatory**
->clone_file_range() and ->dedupe_file_range have been replaced with
->remap_file_range(). See Documentation/filesystems/vfs.rst for more
information.
---
**recommended**
->lookup() instances doing an equivalent of::
if (IS_ERR(inode))
return ERR_CAST(inode);
return d_splice_alias(inode, dentry);
don't need to bother with the check - d_splice_alias() will do the
right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
inode to d_splice_alias() will also do the right thing (equivalent of
d_add(dentry, NULL); return NULL;), so that kind of special cases
also doesn't need a separate treatment.
---
**strongly recommended**
take the RCU-delayed parts of ->destroy_inode() into a new method -
->free_inode(). If ->destroy_inode() becomes empty - all the better,
just get rid of it. Synchronous work (e.g. the stuff that can't
be done from an RCU callback, or any WARN_ON() where we want the
stack trace) *might* be movable to ->evict_inode(); however,
that goes only for the things that are not needed to balance something
done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
might have accumulated over the life of in-core inode, ->evict_inode()
might be a fit.
Rules for inode destruction:
* if ->destroy_inode() is non-NULL, it gets called
* if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
* combination of NULL ->destroy_inode and NULL ->free_inode is
treated as NULL/free_inode_nonrcu, to preserve the compatibility.
Note that the callback (be it via ->free_inode() or explicit call_rcu()
in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
as the matter of fact, the superblock and all associated structures
might be already gone. The filesystem driver is guaranteed to be still
there, but that's it. Freeing memory in the callback is fine; doing
more than that is possible, but requires a lot of care and is best
avoided.
---
**mandatory**
DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
business doing so.
---
**mandatory**
d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
very suspect (and won't work in modules). Such uses are very likely to
be misspelled d_alloc_anon().

70
Documentation/filesystems/ubifs-authentication.md → Documentation/filesystems/ubifs-authentication.rst
View File

@ -1,8 +1,11 @@
% UBIFS Authentication
% sigma star gmbh
% 2018
:orphan:
# Introduction
.. UBIFS Authentication
.. sigma star gmbh
.. 2018
Introduction
============
UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to
@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption.
## MTD, UBI & UBIFS
MTD, UBI & UBIFS
----------------
On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that
@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
leveling and some flash specifics are left to UBI, while UBIFS focuses on
scalability, performance and recoverability.
::
+------------+ +*******+ +-----------+ +-----+
| | * UBIFS * | UBI-BLOCK | | ... |
@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP].
### UBIFS Index & Tree Node Cache
UBIFS Index & Tree Node Cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
marked as dirty are written to the flash to update the persisted index.
### Journal
Journal
~~~~~~~
To avoid wearing out the flash, the index is only persisted (*commited*) when
certain conditions are met (eg. `fsync(2)`). The journal is used to record
certain conditions are met (eg. ``fsync(2)``). The journal is used to record
any changes (in form of inode nodes, data nodes etc.) between commits
of the index. During mount, the journal is read from the flash and replayed
onto the TNC (which will be created on-demand from the on-flash index).
UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
amount of log area LEBs is configured on filesystem creation (using
`mkfs.ubifs`) and stored in the superblock node. The log area contains only
``mkfs.ubifs``) and stored in the superblock node. The log area contains only
two types of nodes: *reference nodes* and *commit start nodes*. A commit start
node is written whenever an index commit is performed. Reference nodes are
written on every journal update. Each reference node points to the position of
@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
because of a power cut. If the recovery fails, UBIFS will not mount. An error
for every other LEB will directly cause UBIFS to fail the mount operation.
::
| ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
containing their buds
### LEB Property Tree/Table
LEB Property Tree/Table
~~~~~~~~~~~~~~~~~~~~~~~
The LEB property tree is used to store per-LEB information. This includes the
LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
the LEB. The type is important, because UBIFS never mixes index nodes with data
nodes on a single LEB and thus each LEB has a specific purpose. This again is
useful for free space calculations. See [UBIFS-WP] for more details.
@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation.
[1] Since LEBs can only be appended and never overwritten, there is a
difference between free space ie. the remaining space left on the LEB to be
written to without erasing it and previously written content that is obsolete
but can't be overwritten without erasing the full LEB.
.. [1] Since LEBs can only be appended and never overwritten, there is a
difference between free space ie. the remaining space left on the LEB to be
written to without erasing it and previously written content that is obsolete
but can't be overwritten without erasing the full LEB.
# UBIFS Authentication
UBIFS Authentication
====================
This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash.
## Threat Model
Threat Model
------------
UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and
@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device.
## Authentication
Authentication
--------------
To be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is:
@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
### Index Authentication
Index Authentication
~~~~~~~~~~~~~~~~~~~~
Through UBIFS' concept of a wandering tree, it already takes care of only
updating and persisting changed parts from leaf node up to the root node
@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
the storage overhead which is precious for users of UBIFS (ie. embedded
devices).
::
+---------------+
| Master Node |
@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node.
### Journal Authentication
Journal Authentication
~~~~~~~~~~~~~~~~~~~~~~
The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the
@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
authentication node. The tail of the journal which may not have a authentication
node cannot be authenticated and is skipped during journal replay.
We get this picture for journal authentication:
We get this picture for journal authentication::
,,,,,,,,
,......,...........................................
@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
modified on feature flag or similar changes, but never on file changes.
### LPT Authentication
LPT Authentication
~~~~~~~~~~~~~~~~~~
The location of the LPT root node on the flash is stored in the UBIFS master
node. Since the LPT is written and read atomically on every commit, there is
@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
LTP hash stored there with the hash computed from the read on-flash LPT.
## Key Management
Key Management
--------------
For simplicity, UBIFS authentication uses a single key to compute the HMACs
of superblock, master, commit start and reference nodes. This key has to be
@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2].
# Future Extensions
Future Extensions
=================
In certain cases where a vendor wants to provide an authenticated filesystem
image to customers, it should be possible to do so without sharing the secret
@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
will then have to be provided beforehand in the normal way.
# References
References
==========
[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html

2
Documentation/filesystems/vfs.rst
View File

@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist.
VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on
are called from a process context. Filesystem locking is described in
the document Documentation/filesystems/Locking.
the document Documentation/filesystems/locking.rst.
Directory Entry Cache (dcache)

2
Documentation/hwmon/adm1021.rst
View File

@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
If nothing happens when loading the adm1021 module, and you are certain
that your specific Xeon processor model includes compatible sensors, you
will have to explicitly instantiate the sensor chips from user-space. See
method 4 in Documentation/i2c/instantiating-devices. Possible slave
method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
only temp2 will be correct and temp1 will have to be ignored.

2
Documentation/hwmon/adm1275.rst
View File

@ -75,7 +75,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
The ADM1075, unlike many other PMBus devices, does not support internal voltage

2
Documentation/hwmon/hih6130.rst
View File

@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
can be used in the board setup code.
Please see Documentation/i2c/instantiating-devices for details on how to
Please see Documentation/i2c/instantiating-devices.rst for details on how to
instantiate I2C devices.
sysfs-Interface

2
Documentation/hwmon/ibm-cffps.rst
View File

@ -17,7 +17,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries

2
Documentation/hwmon/lm25066.rst
View File

@ -76,7 +76,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/max16064.rst
View File

@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/max16065.rst
View File

@ -79,7 +79,7 @@ Usage Notes
This driver does not probe for devices, since there is no register which
can be safely used to identify the chip. You will have to instantiate
the devices explicitly. Please see Documentation/i2c/instantiating-devices for
the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
WARNING: Do not access chip registers using the i2cdump command, and do not use

2
Documentation/hwmon/max20751.rst
View File

@ -30,7 +30,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/max34440.rst
View File

@ -83,7 +83,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
For MAX34446, the value of the currX_crit attribute determines if current or

2
Documentation/hwmon/max6650.rst
View File

@ -55,7 +55,7 @@ Usage notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Module parameters

2
Documentation/hwmon/max8688.rst
View File

@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/menf21bmc.rst
View File

@ -28,7 +28,7 @@ Usage Notes
This driver is part of the MFD driver named "menf21bmc" and does
not auto-detect devices.
You will have to instantiate the MFD driver explicitly.
Please see Documentation/i2c/instantiating-devices for
Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries

2
Documentation/hwmon/pcf8591.rst
View File

@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
The PCF8591 is plainly impossible to detect! Thus the driver won't even
try. You have to explicitly instantiate the device at the relevant
address (in the interval [0x48..0x4f]) either through platform data, or
using the sysfs interface. See Documentation/i2c/instantiating-devices
using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
for details.
Directories are being created for each instantiated PCF8591:

2
Documentation/hwmon/sht3x.rst
View File

@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
The device communicates with the I2C protocol. Sensors can have the I2C
addresses 0x44 or 0x45, depending on the wiring. See
Documentation/i2c/instantiating-devices for methods to instantiate the device.
Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
There are two options configurable by means of sht3x_platform_data:

2
Documentation/hwmon/shtc1.rst
View File

@ -45,7 +45,7 @@ chips, a humidity and temperature sensor. Temperature is measured in degrees
celsius, relative humidity is expressed as a percentage.
The device communicates with the I2C protocol. All sensors are set to I2C
address 0x70. See Documentation/i2c/instantiating-devices for methods to
address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
instantiate the device.
There are two options configurable by means of shtc1_platform_data:

2
Documentation/hwmon/tmp103.rst
View File

@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
Documentation/hwmon/sysfs-interface.rst under Temperatures).
Please refer how to instantiate this driver:
Documentation/i2c/instantiating-devices
Documentation/i2c/instantiating-devices.rst

2
Documentation/hwmon/tps40422.rst
View File

@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/ucd9000.rst
View File

@ -64,7 +64,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/ucd9200.rst
View File

@ -40,7 +40,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

2
Documentation/hwmon/via686a.rst
View File

@ -40,7 +40,7 @@ all as a 686A.
The Via 686a southbridge has integrated hardware monitor functionality.
It also has an I2C bus, but this driver only supports the hardware monitor.
For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
The Via 686a implements three temperature sensors, two fan rotation speed
sensors, five voltage sensors and alarms.

2
Documentation/hwmon/zl6100.rst
View File

@ -121,7 +121,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices for
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
.. warning::

13
Documentation/i2c/busses/i2c-ali1535 → Documentation/i2c/busses/i2c-ali1535.rst
View File

@ -1,16 +1,19 @@
=========================
Kernel driver i2c-ali1535
=========================
Supported adapters:
* Acer Labs, Inc. ALI 1535 (south bridge)
Datasheet: Now under NDA
http://www.ali.com.tw/
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Mark D. Studebaker <mdsxyz123@yahoo.com>,
Dan Eaton <dan.eaton@rocketlogix.com>,
Stephen Rousset<stephen.rousset@rocketlogix.com>
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Dan Eaton <dan.eaton@rocketlogix.com>,
- Stephen Rousset<stephen.rousset@rocketlogix.com>
Description
-----------

3
Documentation/i2c/busses/i2c-ali1563 → Documentation/i2c/busses/i2c-ali1563.rst
View File

@ -1,7 +1,10 @@
=========================
Kernel driver i2c-ali1563
=========================
Supported adapters:
* Acer Labs, Inc. ALI 1563 (south bridge)
Datasheet: Now under NDA
http://www.ali.com.tw/

64
Documentation/i2c/busses/i2c-ali15x3 → Documentation/i2c/busses/i2c-ali15x3.rst
View File

@ -1,20 +1,23 @@
=========================
Kernel driver i2c-ali15x3
=========================
Supported adapters:
* Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
Datasheet: Now under NDA
http://www.ali.com.tw/
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Mark D. Studebaker <mdsxyz123@yahoo.com>
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>
Module Parameters
-----------------
* force_addr: int
Initialize the base address of the i2c controller
Initialize the base address of the i2c controller
Notes
@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
lspci. Don't use this unless the driver complains that the base address is
not set.
Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
Example::
modprobe i2c-ali15x3 force_addr=0xe800
SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
by a power cycle. Cause unknown (see Issues below).
@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
M1541 and M1543C South Bridges.
The M1543C is a South bridge for desktop systems.
The M1541 is a South bridge for portable systems.
They are part of the following ALI chipsets:
* "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
100MHz CPU Front Side bus
100MHz CPU Front Side bus
* "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
CPU Front Side bus
CPU Front Side bus
Some Aladdin V motherboards:
Asus P5A
Atrend ATC-5220
BCM/GVC VP1541
Biostar M5ALA
Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
enable the 7101 device! **)
Iwill XA100 Plus
Micronics C200
Microstar (MSI) MS-5169
- Asus P5A
- Atrend ATC-5220
- BCM/GVC VP1541
- Biostar M5ALA
- Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
enable the 7101 device!)
- Iwill XA100 Plus
- Micronics C200
- Microstar (MSI) MS-5169
* "Aladdin IV" includes the M1541 Socket 7 North bridge
with host bus up to 83.3 MHz.
with host bus up to 83.3 MHz.
For an overview of these chips see http://www.acerlabs.com. At this time the
full data sheets on the web site are password protected, however if you
contact the ALI office in San Jose they may give you the password.
The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
output of lspci will show something similar to the following:
output of lspci will show something similar to the following::
00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
** IMPORTANT **
** If you have a M1533 or M1543C on the board and you get
** "ali15x3: Error: Can't detect ali15x3!"
** then run lspci.
** If you see the 1533 and 5229 devices but NOT the 7101 device,
** then you must enable ACPI, the PMU, SMB, or something similar
** in the BIOS.
** The driver won't work if it can't find the M7101 device.
.. important::
If you have a M1533 or M1543C on the board and you get
"ali15x3: Error: Can't detect ali15x3!"
then run lspci.
If you see the 1533 and 5229 devices but NOT the 7101 device,
then you must enable ACPI, the PMU, SMB, or something similar
in the BIOS.
The driver won't work if it can't find the M7101 device.
The SMB controller is part of the M7101 device, which is an ACPI-compliant
Power Management Unit (PMU).
@ -109,4 +120,3 @@ There may be electrical problems on this board.
On the P5A, the W83781D sensor chip is on both the ISA and
SMBus. Therefore the SMBus hangs can generally be avoided
by accessing the W83781D on the ISA bus only.

Some files were not shown because too many files have changed in this diff Show More