* Re: [linux-kernel-mentees] [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-30 16:50 UTC (permalink / raw)
To: skhan
Cc: linux-kernel-mentees, darrick.wong, linux-xfs, corbet, linux-doc,
linux-kernel
On Sat, Jun 29, 2019 at 09:57:59PM +0100, Sheriff Esseson wrote:
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> In v3:
> Update MAINTAINERS. Fix Indentation/long line issues. Insert Sphinx tag.
>
> --
> 2.22.0
>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v4:
dax.txt :
fix broken reference to xfs.rst
Documentation/filesystems/dax.txt | 2 +-
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 468 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
5 files changed, 473 insertions(+), 474 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt
index 6d2c0d340..c333285b8 100644
--- a/Documentation/filesystems/dax.txt
+++ b/Documentation/filesystems/dax.txt
@@ -76,7 +76,7 @@ exposure of uninitialized data through mmap.
These filesystems may be used for inspiration:
- ext2: see Documentation/filesystems/ext2.txt
- ext4: see Documentation/filesystems/ext4/
-- xfs: see Documentation/filesystems/xfs.txt
+- xfs: see Documentation/filesystems/xfs.rst
Handling Media Errors
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..d36ef042c
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,468 @@
+.. SPDX-License-Identifier: GPL-2.0
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ allocsize=<size>
+ Sets the buffered I/O end-of-file preallocation size when doing delayed
+ allocation writeout (default size is 64KiB). Valid values for this
+ option are page size (typically 4KiB) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [no]attr2
+ The options enable/disable an "opportunistic" improvement to be made in
+ the way inline extended attributes are stored on-disk. When the new
+ form is used for the first time when ``attr2`` is selected (either when
+ setting or removing extended attributes) the on-disk superblock feature
+ bit field will be updated to reflect this format being in use.
+
+ The default behaviour is determined by the on-disk feature bit
+ indicating that ``attr2`` behaviour is active. If either mount option is
+ set, then that becomes the new default used by the filesystem. However
+ on CRC enabled filesystems, the ``attr2`` format is always used , and so
+ will reject the ``noattr2`` mount option if it is set.
+
+ (*)[no]discard
+ Enable/disable the issuing of commands to let the block device reclaim
+ space freed by the filesystem. This is useful for SSD devices, thinly
+ provisioned LUNs and virtual machine images, but may have a performance
+ impact.
+
+ Note: It is currently recommended that you use the ``fstrim``
+ application to discard unused blocks rather than the ``discard`` mount
+ option because the performance impact of this option is quite severe.
+
+ grpid/bsdgroups
+ nogrpid/(*)sysvgroups
+ These options define what group ID a newly created file gets. When
+ ``grpid`` is set, it takes the group ID of the directory in which it is
+ created; otherwise it takes the ``fsgid`` of the current process, unless
+ the directory has the ``setgid`` bit set, in which case it takes the
+ ``gid`` from the parent directory, and also gets the ``setgid`` bit set
+ if it is a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[no]ikeep
+ When ``ikeep`` is specified, XFS does not delete empty inode clusters
+ and keeps them around on disk. When ``noikeep`` is specified, empty
+ inode clusters are returned to the free space pool.
+
+ inode32 | (*)inode64
+ When ``inode32`` is specified, it indicates that XFS limits inode
+ creation to locations which will not result in inode numbers with more
+ than 32 bits of significance.
+
+ When ``inode64`` is specified, it indicates that XFS is allowed to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``inode32`` is provided for backwards compatibility with older systems
+ and applications, since 64 bits inode numbers might cause problems for
+ some applications that cannot handle large inode numbers. If
+ applications are in use which do not handle inode numbers bigger than 32
+ bits, the ``inode32`` option should be specified.
+
+
+ (*)[no]largeio
+ If ``nolargeio`` is specified, the optimal I/O reported in st_blksize by
+ **stat(2)** will be as small as possible to allow user applications to
+ avoid inefficient read/modify/write I/O. This is typically the page
+ size of the machine, as this is the granularity of the page cache.
+
+ If ``largeio`` is specified, a filesystem that was created with a
+ ``swidth`` specified will return the ``swidth`` value (in bytes) in
+ st_blksize. If the filesystem does not have a ``swidth`` specified but
+ does specify an ``allocsize`` then ``allocsize`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ logbufs=<value>
+ Set the number of in-memory log buffers to ``value``. Valid numbers
+ range from 2-8 inclusive.
+
+ The default value is 8 buffers.
+
+ If the memory cost of 8 log buffers is too high on small systems, then
+ it may be reduced at some cost to performance on metadata intensive
+ workloads. The ``logbsize`` option below controls the size of each
+ buffer and so is also relevant to this case.
+
+ logbsize=<value>
+ Set the size of each in-memory log buffer to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. Valid sizes for
+ version 1 and version 2 logs are 16384 (16k) and 32768 (32k). Valid
+ sizes for version 2 logs also include 65536 (64k), 131072 (128k) and
+ 262144 (256k). The ``logbsize`` must be an integer multiple of the
+ "log stripe unit" configured at mkfs time.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ rtdev=<device>
+ An XFS filesystem has up to three parts: a data section, a log section,
+ and a real-time section. The real-time section is optional. If
+ enabled, ``rtdev`` sets ``device`` to be used as an external real-time
+ section, similar to ``logdev`` above.
+
+ noalign
+ Data allocations will not be aligned at stripe unit boundaries. This is
+ only relevant to filesystems created with non-zero data alignment
+ parameters (sunit, swidth) by mkfs.
+
+ norecovery
+ The filesystem will be mounted without running log recovery. If the
+ filesystem was not cleanly unmounted, it is likely to be inconsistent
+ when mounted in ``norecovery`` mode. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ nouuid
+ Don't check for double mounted file systems using the file system uuid.
+ This is useful to mount LVM snapshot volumes, and often used in
+ combination with ``norecovery`` for mounting read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ sunit=<value>
+ Used to specify the stripe unit for a RAID device or (in conjunction
+ with ``swidth`` below) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ The ``sunit`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid changes to ``sunit`` are increasing it by a power-of-2 multiple.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+ swidth=<value>
+ Used to specify the stripe width for a RAID device or (in conjunction
+ with ``sunit`` above) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ The ``swidth`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid swidth values are any integer multiple of a valid ``sunit`` value.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+
+ swalloc
+ Data allocations will be rounded up to stripe width boundaries when the
+ current end of file is being extended and the file size is larger than
+ the stripe width size.
+
+ wsync
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "sync" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodump" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "noatime" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nosymlinks" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodefrag" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- allocsize=size
- Sets the buffered I/O end-of-file preallocation size when
- doing delayed allocation writeout (default size is 64KiB).
- Valid values for this option are page size (typically 4KiB)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- The options enable/disable an "opportunistic" improvement to
- be made in the way inline extended attributes are stored
- on-disk. When the new form is used for the first time when
- attr2 is selected (either when setting or removing extended
- attributes) the on-disk superblock feature bit field will be
- updated to reflect this format being in use.
-
- The default behaviour is determined by the on-disk feature
- bit indicating that attr2 behaviour is active. If either
- mount option it set, then that becomes the new default used
- by the filesystem.
-
- CRC enabled filesystems always use the attr2 format, and so
- will reject the noattr2 mount option if it is set.
-
- discard
- nodiscard (*)
- Enable/disable the issuing of commands to let the block
- device reclaim space freed by the filesystem. This is
- useful for SSD devices, thinly provisioned LUNs and virtual
- machine images, but may have a performance impact.
-
- Note: It is currently recommended that you use the fstrim
- application to discard unused blocks rather than the discard
- mount option because the performance impact of this option
- is quite severe.
-
- grpid/bsdgroups
- nogrpid/sysvgroups (*)
- These options define what group ID a newly created file
- gets. When grpid is set, it takes the group ID of the
- directory in which it is created; otherwise it takes the
- fsgid of the current process, unless the directory has the
- setgid bit set, in which case it takes the gid from the
- parent directory, and also gets the setgid bit set if it is
- a directory itself.
-
- filestreams
- Make the data allocator use the filestreams allocation mode
- across the entire filesystem rather than just on directories
- configured to use it.
-
- ikeep
- noikeep (*)
- When ikeep is specified, XFS does not delete empty inode
- clusters and keeps them around on disk. When noikeep is
- specified, empty inode clusters are returned to the free
- space pool.
-
- inode32
- inode64 (*)
- When inode32 is specified, it indicates that XFS limits
- inode creation to locations which will not result in inode
- numbers with more than 32 bits of significance.
-
- When inode64 is specified, it indicates that XFS is allowed
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- inode32 is provided for backwards compatibility with older
- systems and applications, since 64 bits inode numbers might
- cause problems for some applications that cannot handle
- large inode numbers. If applications are in use which do
- not handle inode numbers bigger than 32 bits, the inode32
- option should be specified.
-
-
- largeio
- nolargeio (*)
- If "nolargeio" is specified, the optimal I/O reported in
- st_blksize by stat(2) will be as small as possible to allow
- user applications to avoid inefficient read/modify/write
- I/O. This is typically the page size of the machine, as
- this is the granularity of the page cache.
-
- If "largeio" specified, a filesystem that was created with a
- "swidth" specified will return the "swidth" value (in bytes)
- in st_blksize. If the filesystem does not have a "swidth"
- specified but does specify an "allocsize" then "allocsize"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
- range from 2-8 inclusive.
-
- The default value is 8 buffers.
-
- If the memory cost of 8 log buffers is too high on small
- systems, then it may be reduced at some cost to performance
- on metadata intensive workloads. The logbsize option below
- controls the size of each buffer and so is also relevant to
- this case.
-
- logbsize=value
- Set the size of each in-memory log buffer. The size may be
- specified in bytes, or in kilobytes with a "k" suffix.
- Valid sizes for version 1 and version 2 logs are 16384 (16k)
- and 32768 (32k). Valid sizes for version 2 logs also
- include 65536 (64k), 131072 (128k) and 262144 (256k). The
- logbsize must be an integer multiple of the log
- stripe unit configured at mkfs time.
-
- The default value for for version 1 logs is 32768, while the
- default value for version 2 logs is MAX(32768, log_sunit).
-
- logdev=device and rtdev=device
- Use an external log (metadata journal) and/or real-time device.
- An XFS filesystem has up to three parts: a data section, a log
- section, and a real-time section. The real-time section is
- optional, and the log section can be separate from the data
- section or contained within it.
-
- noalign
- Data allocations will not be aligned at stripe unit
- boundaries. This is only relevant to filesystems created
- with non-zero data alignment parameters (sunit, swidth) by
- mkfs.
-
- norecovery
- The filesystem will be mounted without running log recovery.
- If the filesystem was not cleanly unmounted, it is likely to
- be inconsistent when mounted in "norecovery" mode.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- nouuid
- Don't check for double mounted file systems using the file
- system uuid. This is useful to mount LVM snapshot volumes,
- and often used in combination with "norecovery" for mounting
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- sunit=value and swidth=value
- Used to specify the stripe unit and width for a RAID device
- or a stripe volume. "value" must be specified in 512-byte
- block units. These options are only relevant to filesystems
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters specified must be compatible
- with the existing filesystem alignment characteristics. In
- general, that means the only valid changes to sunit are
- increasing it by a power-of-2 multiple. Valid swidth values
- are any integer multiple of a valid sunit value.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
- modified, such as adding a new disk to a RAID5 lun and
- reshaping it.
-
- swalloc
- Data allocations will be rounded up to stripe width boundaries
- when the current end of file is being extended and the file
- size is larger than the stripe width size.
-
- wsync
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "sync" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodump" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "noatime" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nosymlinks" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodefrag" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [linux-kernel-mentees] [PATCH] Doc : doc-guide : Fix a typo
From: Jonathan Corbet @ 2019-06-30 13:40 UTC (permalink / raw)
To: Sheriff Esseson; +Cc: skhan, linux-kernel-mentees, linux-doc, linux-kernel
In-Reply-To: <20190630071707.GA12881@localhost>
On Sun, 30 Jun 2019 08:17:07 +0100
Sheriff Esseson <sheriffesseson@gmail.com> wrote:
> > fix the disjunction by replacing "of" with "or".
> >
> > Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> > ---
> > --
> > 2.22.0
> >
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> changes in v2:
> - cc-ed Corbet.
>
> Documentation/doc-guide/kernel-doc.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
So why are you sending me this again? I applied it a few days ago and
told you so at the time.
jon
^ permalink raw reply
* Re: [linux-kernel-mentees] [PATCH] Doc : doc-guide : Fix a typo
From: Sheriff Esseson @ 2019-06-30 7:17 UTC (permalink / raw)
To: skhan; +Cc: linux-kernel-mentees, corbet, linux-doc, linux-kernel
In-Reply-To: <20190628060111.24851-1-sheriffesseson@gmail.com>
On Fri, Jun 28, 2019 at 07:01:11AM +0100, Sheriff Esseson wrote:
> fix the disjunction by replacing "of" with "or".
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
> --
> 2.22.0
>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
changes in v2:
- cc-ed Corbet.
Documentation/doc-guide/kernel-doc.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index f96059767..192c36af3 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -359,7 +359,7 @@ Domain`_ references.
``monospaced font``.
Useful if you need to use special characters that would otherwise have some
- meaning either by kernel-doc script of by reStructuredText.
+ meaning either by kernel-doc script or by reStructuredText.
This is particularly useful if you need to use things like ``%ph`` inside
a function description.
--
2.22.0
^ permalink raw reply related
* RE: [PATCH] Documentation: misc-devices: mei: Convert mei txt files to reST
From: Winkler, Tomas @ 2019-06-30 6:23 UTC (permalink / raw)
To: Shreeya Patel, skhan@linuxfoundation.org, corbet@lwn.net,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-kernel-mentees@lists.linuxfoundation.org
In-Reply-To: <20190629213203.5887-1-shreeya.patel23498@gmail.com>
> -----Original Message-----
> From: Shreeya Patel [mailto:shreeya.patel23498@gmail.com]
> Sent: Sunday, June 30, 2019 00:32
> To: skhan@linuxfoundation.org; corbet@lwn.net; Winkler, Tomas
> <tomas.winkler@intel.com>; linux-doc@vger.kernel.org; linux-
> kernel@vger.kernel.org; linux-kernel-mentees@lists.linuxfoundation.org
> Subject: [PATCH] Documentation: misc-devices: mei: Convert mei txt files to
> reST
>
> Convert the MEI misc device's documentation files from .txt to
> reStructuredText format. Make a minor change of correcting the wrong macro
> name MEI_CONNECT_CLIENT_IOCTL to IOCTL_MEI_CONNECT_CLIENT.
> Add an index file in mei as there are two sections for it in the documentation.
>
> Signed-off-by: Shreeya Patel <shreeya.patel23498@gmail.com>
> ---
Sorry you are late, we've already done that, it should be merged via Greg's char-misc tree.
Thanks
Tomas
> I am not sure if I have placed the Documentation in the right place so I would
> like to get some suggestions from the MAINTAINERS on this part.
>
> Documentation/misc-devices/index.rst | 1 +
> Documentation/misc-devices/mei/index.rst | 15 +
> .../misc-devices/mei/mei-client-bus.rst | 151 +++++++++
> .../misc-devices/mei/mei-client-bus.txt | 141 ---------
> Documentation/misc-devices/mei/mei.rst | 289 ++++++++++++++++++
> Documentation/misc-devices/mei/mei.txt | 266 ----------------
> 6 files changed, 456 insertions(+), 407 deletions(-) create mode 100644
> Documentation/misc-devices/mei/index.rst
> create mode 100644 Documentation/misc-devices/mei/mei-client-bus.rst
> delete mode 100644 Documentation/misc-devices/mei/mei-client-bus.txt
> create mode 100644 Documentation/misc-devices/mei/mei.rst
> delete mode 100644 Documentation/misc-devices/mei/mei.txt
>
> diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-
> devices/index.rst
> index dfd1f45a3127..e788a12b2b19 100644
> --- a/Documentation/misc-devices/index.rst
> +++ b/Documentation/misc-devices/index.rst
> @@ -15,3 +15,4 @@ fit into other categories.
> :maxdepth: 2
>
> ibmvmc
> + mei/index
> diff --git a/Documentation/misc-devices/mei/index.rst b/Documentation/misc-
> devices/mei/index.rst
> new file mode 100644
> index 000000000000..3018098ad075
> --- /dev/null
> +++ b/Documentation/misc-devices/mei/index.rst
> @@ -0,0 +1,15 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================================
> ==
> +Intel(R) Management Engine Interface Kernel Driver (Intel(R) MEI)
> +===============================================================
> ==
> +
> +.. class:: toc-title
> +
> + Table of contents
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + mei
> + mei-client-bus
> diff --git a/Documentation/misc-devices/mei/mei-client-bus.rst
> b/Documentation/misc-devices/mei/mei-client-bus.rst
> new file mode 100644
> index 000000000000..82d455afae78
> --- /dev/null
> +++ b/Documentation/misc-devices/mei/mei-client-bus.rst
> @@ -0,0 +1,151 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============================================
> +Intel(R) Management Engine (ME) Client bus API
> +==============================================
> +
> +
> +Rationale
> +=========
> +
> +MEI misc character device is useful for dedicated applications to send
> +and receive data to the many FW appliance found in Intel's ME from the user
> space.
> +However for some of the ME functionalities it make sense to leverage
> +existing software stack and expose them through existing kernel subsystems.
> +
> +In order to plug seamlessly into the kernel device driver model we add
> +kernel virtual bus abstraction on top of the MEI driver. This allows
> +implementing linux kernel drivers for the various MEI features as a stand
> alone entities found in their respective subsystem.
> +Existing device drivers can even potentially be re-used by adding an
> +MEI CL bus layer to the existing code.
> +
> +
> +MEI CL bus API
> +==============
> +
> +A driver implementation for an MEI Client is very similar to existing
> +bus based device drivers. The driver registers itself as an MEI CL bus
> +driver through the :c:type:`mei_cl_driver` structure:
> +
> +::
> +
> + struct mei_cl_driver {
> + struct device_driver driver;
> + const char *name;
> +
> + const struct mei_cl_device_id *id_table;
> +
> + int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id
> *id);
> + int (*remove)(struct mei_cl_device *dev);
> + };
> +
> + struct mei_cl_id {
> + char name[MEI_NAME_SIZE];
> + kernel_ulong_t driver_info;
> + };
> +
> +
> +The :c:type:`mei_cl_id` structure allows the driver to bind itself against a
> device name.
> +
> +To actually register a driver on the ME Client bus one must call the
> +:c:func:`mei_cl_add_driver()` API. This is typically called at module init time.
> +
> +Once registered on the ME Client bus, a driver will typically try to do
> +some I/O on this bus and this should be done through the
> +:c:func:`mei_cl_send()` and :c:func:`mei_cl_recv()` routines. The latter is
> synchronous (blocks and sleeps until data shows up).
> +In order for drivers to be notified of pending events waiting for them (e.g.
> +an Rx event) they can register an event handler through the
> +:c:func:`mei_cl_register_event_cb()` routine. Currently only the
> +:c:macro:`MEI_EVENT_RX` event will trigger an event handler call and
> +the driver implementation is supposed to call :c:func:`mei_recv()` from
> +the event handler in order to fetch the pending received buffers.
> +
> +
> +Example
> +=======
> +
> +As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
> +The driver init and exit routines for this device would look like:
> +
> +::
> +
> + #define CONTACT_DRIVER_NAME "contact"
> +
> + static struct mei_cl_device_id contact_mei_cl_tbl[] = {
> + { CONTACT_DRIVER_NAME, },
> + /* required last entry */
> + { }
> + };
> + MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
> +
> + static struct mei_cl_driver contact_driver = {
> + .id_table = contact_mei_tbl,
> + .name = CONTACT_DRIVER_NAME,
> + .probe = contact_probe,
> + .remove = contact_remove,
> + };
> +
> + static int contact_init(void)
> + {
> + int r;
> +
> + r = mei_cl_driver_register(&contact_driver);
> + if (r) {
> + pr_err(CONTACT_DRIVER_NAME ": driver registration
> failed\n");
> + return r;
> + }
> +
> + return 0;
> + }
> +
> + static void __exit contact_exit(void)
> + {
> + mei_cl_driver_unregister(&contact_driver);
> + }
> +
> + module_init(contact_init);
> + module_exit(contact_exit);
> +
> +And the driver's simplified probe routine would look like that:
> +
> +::
> +
> + int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id
> *id)
> + {
> + struct contact_driver *contact;
> +
> + [...]
> + mei_cl_enable_device(dev);
> +
> + mei_cl_register_event_cb(dev, contact_event_cb, contact);
> +
> + return 0;
> + }
> +
> +In the probe routine the driver first enable the MEI device and then
> +registers an ME bus event handler which is as close as it can get to
> +registering a threaded IRQ handler.
> +The handler implementation will typically call some I/O routine
> +depending on the pending events:
> +
> +::
> +
> + #define MAX_NFC_PAYLOAD 128
> +
> + static void contact_event_cb(struct mei_cl_device *dev, u32 events,
> + void *context)
> + {
> + struct contact_driver *contact = context;
> +
> + if (events & BIT(MEI_EVENT_RX)) {
> + u8 payload[MAX_NFC_PAYLOAD];
> + int payload_size;
> +
> + payload_size = mei_recv(dev, payload,
> MAX_NFC_PAYLOAD);
> + if (payload_size <= 0)
> + return;
> +
> + /* Hook to the NFC subsystem */
> + nfc_hci_recv_frame(contact->hdev, payload,
> payload_size);
> + }
> + }
> diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt
> b/Documentation/misc-devices/mei/mei-client-bus.txt
> deleted file mode 100644
> index 743be4ec8989..000000000000
> --- a/Documentation/misc-devices/mei/mei-client-bus.txt
> +++ /dev/null
> @@ -1,141 +0,0 @@
> -Intel(R) Management Engine (ME) Client bus API -
> ==============================================
> -
> -
> -Rationale
> -=========
> -
> -MEI misc character device is useful for dedicated applications to send and
> receive -data to the many FW appliance found in Intel's ME from the user
> space.
> -However for some of the ME functionalities it make sense to leverage existing
> software -stack and expose them through existing kernel subsystems.
> -
> -In order to plug seamlessly into the kernel device driver model we add kernel
> virtual -bus abstraction on top of the MEI driver. This allows implementing linux
> kernel drivers -for the various MEI features as a stand alone entities found in
> their respective subsystem.
> -Existing device drivers can even potentially be re-used by adding an MEI CL
> bus layer to -the existing code.
> -
> -
> -MEI CL bus API
> -==============
> -
> -A driver implementation for an MEI Client is very similar to existing bus -based
> device drivers. The driver registers itself as an MEI CL bus driver through -the
> mei_cl_driver structure:
> -
> -struct mei_cl_driver {
> - struct device_driver driver;
> - const char *name;
> -
> - const struct mei_cl_device_id *id_table;
> -
> - int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
> - int (*remove)(struct mei_cl_device *dev);
> -};
> -
> -struct mei_cl_id {
> - char name[MEI_NAME_SIZE];
> - kernel_ulong_t driver_info;
> -};
> -
> -The mei_cl_id structure allows the driver to bind itself against a device name.
> -
> -To actually register a driver on the ME Client bus one must call the
> mei_cl_add_driver() -API. This is typically called at module init time.
> -
> -Once registered on the ME Client bus, a driver will typically try to do some I/O
> on -this bus and this should be done through the mei_cl_send() and
> mei_cl_recv() -routines. The latter is synchronous (blocks and sleeps until data
> shows up).
> -In order for drivers to be notified of pending events waiting for them (e.g.
> -an Rx event) they can register an event handler through the
> -mei_cl_register_event_cb() routine. Currently only the MEI_EVENT_RX event -
> will trigger an event handler call and the driver implementation is supposed -to
> call mei_recv() from the event handler in order to fetch the pending -received
> buffers.
> -
> -
> -Example
> -=======
> -
> -As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
> -The driver init and exit routines for this device would look like:
> -
> -#define CONTACT_DRIVER_NAME "contact"
> -
> -static struct mei_cl_device_id contact_mei_cl_tbl[] = {
> - { CONTACT_DRIVER_NAME, },
> -
> - /* required last entry */
> - { }
> -};
> -MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
> -
> -static struct mei_cl_driver contact_driver = {
> - .id_table = contact_mei_tbl,
> - .name = CONTACT_DRIVER_NAME,
> -
> - .probe = contact_probe,
> - .remove = contact_remove,
> -};
> -
> -static int contact_init(void)
> -{
> - int r;
> -
> - r = mei_cl_driver_register(&contact_driver);
> - if (r) {
> - pr_err(CONTACT_DRIVER_NAME ": driver registration
> failed\n");
> - return r;
> - }
> -
> - return 0;
> -}
> -
> -static void __exit contact_exit(void)
> -{
> - mei_cl_driver_unregister(&contact_driver);
> -}
> -
> -module_init(contact_init);
> -module_exit(contact_exit);
> -
> -And the driver's simplified probe routine would look like that:
> -
> -int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id) -{
> - struct contact_driver *contact;
> -
> - [...]
> - mei_cl_enable_device(dev);
> -
> - mei_cl_register_event_cb(dev, contact_event_cb, contact);
> -
> - return 0;
> -}
> -
> -In the probe routine the driver first enable the MEI device and then registers -
> an ME bus event handler which is as close as it can get to registering a -
> threaded IRQ handler.
> -The handler implementation will typically call some I/O routine depending on -
> the pending events:
> -
> -#define MAX_NFC_PAYLOAD 128
> -
> -static void contact_event_cb(struct mei_cl_device *dev, u32 events,
> - void *context)
> -{
> - struct contact_driver *contact = context;
> -
> - if (events & BIT(MEI_EVENT_RX)) {
> - u8 payload[MAX_NFC_PAYLOAD];
> - int payload_size;
> -
> - payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
> - if (payload_size <= 0)
> - return;
> -
> - /* Hook to the NFC subsystem */
> - nfc_hci_recv_frame(contact->hdev, payload, payload_size);
> - }
> -}
> diff --git a/Documentation/misc-devices/mei/mei.rst b/Documentation/misc-
> devices/mei/mei.rst
> new file mode 100644
> index 000000000000..e91ac2570b4d
> --- /dev/null
> +++ b/Documentation/misc-devices/mei/mei.rst
> @@ -0,0 +1,289 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +====================================
> +Intel(R) Management Engine Interface
> +====================================
> +
> +Introduction
> +============
> +
> +The Intel Management Engine (Intel ME) is an isolated and protected
> +computing resource (Co-processor) residing inside certain Intel
> +chipsets. The Intel ME provides support for computer/IT management
> +features. The feature set depends on the Intel chipset SKU.
> +
> +The Intel Management Engine Interface (Intel MEI, previously known as
> +HECI) is the interface between the Host and Intel ME. This interface is
> +exposed to the host as a PCI device. The Intel MEI Driver is in charge
> +of the communication channel between a host application and the Intel ME
> feature.
> +
> +Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
> +each client has its own protocol. The protocol is message-based with a
> +header and payload up to 512 bytes.
> +
> +Prominent usage of the Intel ME Interface is to communicate with
> +Intel(R) Active Management Technology (Intel AMT) implemented in
> +firmware running on the Intel ME.
> +
> +Intel AMT provides the ability to manage a host remotely out-of-band
> +(OOB) even when the operating system running on the host processor has
> +crashed or is in a sleep state.
> +
> +Some examples of Intel AMT usage are:
> + * Monitoring hardware state and platform components
> + * Remote power off/on (useful for green computing or overnight IT
> + maintenance)
> + * OS updates
> + * Storage of useful platform information such as software assets
> + * Built-in hardware KVM
> + * Selective network isolation of Ethernet and IP protocol flows based
> + on policies set by a remote management console
> + * IDE device redirection from remote management console
> +
> +Intel AMT (OOB) communication is based on SOAP (deprecated starting
> +with Release 6.0) over HTTP/S or WS-Management protocol over HTTP/S
> +that are received from a remote management console application.
> +
> +For more information about Intel AMT:
> +`<http://software.intel.com/sites/manageability/AMT_Implementation_and_
> +Reference_Guide>`_
> +
> +
> +Intel MEI Driver
> +================
> +
> +The driver exposes a misc device called :file:`/dev/mei`.
> +
> +An application maintains communication with an Intel ME feature while
> +:file:`/dev/mei` is open. The binding to a specific feature is
> +performed by calling :c:macro:`IOCTL_MEI_CONNECT_CLIENT`, which passes
> the desired UUID.
> +The number of instances of an Intel ME feature that can be opened at
> +the same time depends on the Intel ME feature, but most of the features
> +allow only a single instance.
> +
> +The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
> +simultaneous user connected applications. The Intel MEI driver handles
> +this internally by maintaining request queues for the applications.
> +
> +The driver is transparent to data that are passed between firmware
> +feature and host application.
> +
> +Because some of the Intel ME features can change the system
> +configuration, the driver by default allows only a privileged user to
> +access it.
> +
> +A code snippet for an application communicating with Intel AMTHI client:
> +
> +::
> +
> + struct mei_connect_client_data data;
> + fd = open(MEI_DEVICE);
> +
> + data.d.in_client_uuid = AMTHI_UUID;
> +
> + ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
> +
> + printf("Ver=%d, MaxLen=%ld\n",
> + data.d.in_client_uuid.protocol_version,
> + data.d.in_client_uuid.max_msg_length);
> +
> + [...]
> +
> + write(fd, amthi_req_data, amthi_req_data_len);
> +
> + [...]
> +
> + read(fd, &amthi_res_data, amthi_res_data_len);
> +
> + [...]
> +
> + close(fd);
> +
> +
> +IOCTL
> +=====
> +
> +The Intel MEI Driver supports the following IOCTL commands:
> +
> +
> +:c:macro:`IOCTL_MEI_CONNECT_CLIENT`
> +-------------------------------------
> +Connect to firmware Feature (client)
> +
> +**Usage:**
> +
> +::
> +
> + struct mei_connect_client_data clientData;
> + ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
> +
> +**Inputs:**
> + :c:type:`mei_connect_client_data` - structure contain the following
> + input field.
> +
> + :c:data:`in_client_uuid` - UUID of the FW Feature that needs to connect
> to.
> +
> +**Outputs:**
> + :c:data:`out_client_properties` - Client Properties: MTU and Protocol
> Version.
> +
> +**Error returns:**
> + | :c:macro:`EINVAL` - Wrong IOCTL Number.
> + | :c:macro:`ENODEV` - Device or Connection is not initialized or ready.
> (e.g. Wrong UUID).
> + | :c:macro:`ENOMEM` - Unable to allocate memory to client internal
> data.
> + | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
> + | :c:macro:`EBUSY` - Connection Already Open.
> +
> +**Notes:**
> + :c:data:`max_msg_length` (MTU) in client properties describes the
> maximum
> + data that can be sent or received. (e.g. if MTU=2K, can send
> + requests up to bytes 2k and received responses up to 2k bytes).
> +
> +
> +:c:macro:`IOCTL_MEI_NOTIFY_SET`
> +-------------------------------
> +Enable or disable event notifications
> +
> +**Usage:**
> +
> +::
> +
> + uint32_t enable;
> + ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
> +
> +**Inputs:**
> + | :c:data:`uint32_t enable = 1;`
> + | or
> + | :c:data:`uint32_t enable[disable] = 0;`
> +
> +**Error returns:**
> + | :c:macro:`EINVAL` - Wrong IOCTL Number.
> + | :c:macro:`ENODEV` - Device is not initialized or the client not
> connected.
> + | :c:macro:`ENOMEM` - Unable to allocate memory to client internal
> data.
> + | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
> + | :c:macro:`EOPNOTSUPP` - if the device doesn't support the feature.
> +
> +**Notes:**
> + The client must be connected in order to enable notification events.
> +
> +
> +:c:macro:`IOCTL_MEI_NOTIFY_GET`
> +-------------------------------
> +Retrieve event
> +
> +**Usage:**
> +
> +::
> +
> + uint32_t event;
> + ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
> +
> +**Outputs:**
> + | 1 - if an event is pending.
> + | 0 - if there is no even pending.
> +
> +**Error returns:**
> + | :c:macro:`EINVAL` - Wrong IOCTL Number.
> + | :c:macro:`ENODEV` - Device is not initialized or the client not
> connected.
> + | :c:macro:`ENOMEM` - Unable to allocate memory to client internal
> data.
> + | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
> + | :c:macro:`EOPNOTSUPP` - if the device doesn't support the feature.
> +
> +**Notes:**
> + The client must be connected and event notification has to be enabled
> + in order to receive an event.
> +
> +
> +Intel ME Applications
> +=====================
> +
> +1) Intel Local Management Service (Intel LMS)
> +
> + Applications running locally on the platform communicate with Intel AMT
> Release
> + 2.0 and later releases in the same way that network applications do via
> SOAP
> + over HTTP (deprecated starting with Release 6.0) or with WS-
> Management over
> + SOAP over HTTP. This means that some Intel AMT features can be
> accessed from a
> + local application using the same network interface as a remote
> application
> + communicating with Intel AMT over the network.
> +
> + When a local application sends a message addressed to the local Intel
> AMT host
> + name, the Intel LMS, which listens for traffic directed to the host name,
> + intercepts the message and routes it to the Intel MEI.
> + For more information:
> +
> `<http://software.intel.com/sites/manageability/AMT_Implementation_and_Re
> ference_Guide>`_
> + Under "About Intel AMT" => "Local Access"
> +
> + For downloading Intel LMS:
> +
> + `<http://software.intel.com/en-us/articles/download-the-latest-intel-a
> + mt-open-source-drivers/>`_
> +
> + The Intel LMS opens a connection using the Intel MEI driver to the Intel
> LMS
> + firmware feature using a defined UUID and then communicates with the
> feature
> + using a protocol called Intel AMT Port Forwarding Protocol (Intel APF
> protocol).
> + The protocol is used to maintain multiple sessions with Intel AMT from a
> + single application.
> +
> + See the protocol specification in the `Intel AMT Software Development
> Kit (SDK)
> +
> <http://software.intel.com/sites/manageability/AMT_Implementation_and_Ref
> erence_Guide>`_
> + Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
> + => "Information for Intel(R) vPro(TM) Gateway Developers"
> + => "Description of the Intel AMT Port Forwarding (APF) Protocol"
> +
> +2) Intel AMT Remote configuration using a Local Agent
> +
> + A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
> + without requiring installing additional data to enable setup. The remote
> + configuration process may involve an ISV-developed remote
> configuration
> + agent that runs on the host.
> + For more information:
> +
> `<http://software.intel.com/sites/manageability/AMT_Implementation_and_Re
> ference_Guide>`_
> + Under "Setup and Configuration of Intel AMT" =>
> + "SDK Tools Supporting Setup and Configuration" =>
> + "Using the Local Agent Sample"
> +
> + An open source Intel AMT configuration utility, implementing a local
> agent
> + that accesses the Intel MEI driver, can be found here:
> +
> + `<http://software.intel.com/en-us/articles/download-the-latest-intel-a
> + mt-open-source-drivers/>`
> +
> +
> +Intel AMT OS Health Watchdog
> +============================
> +
> +The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
> +Whenever the OS hangs or crashes, Intel AMT will send an event to any
> +subscriber to this event. This mechanism means that IT knows when a
> +platform crashes even when there is a hard failure on the host.
> +
> +The Intel AMT Watchdog is composed of two parts:
> + 1) Firmware feature - receives the heartbeats
> + and sends an event when the heartbeats stop.
> + 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
> + configures the watchdog and sends the heartbeats.
> +
> +The Intel iAMT watchdog MEI driver uses the kernel watchdog API to
> +configure the Intel AMT Watchdog and to send heartbeats to it. The
> +default timeout of the watchdog is 120 seconds.
> +
> +If the Intel AMT is not enabled in the firmware then the watchdog
> +client won't enumerate on the me client bus and watchdog devices won't be
> exposed.
> +
> +
> +Supported Chipsets
> +==================
> +
> +| 7 Series Chipset Family
> +| 6 Series Chipset Family
> +| 5 Series Chipset Family
> +| 4 Series Chipset Family
> +| Mobile 4 Series Chipset Family
> +| ICH9
> +| 82946GZ/GL
> +| 82G35 Express
> +| 82Q963/Q965
> +| 82P965/G965
> +| Mobile PM965/GM965
> +| Mobile GME965/GLE960
> +| 82Q35 Express
> +| 82G33/G31/P35/P31 Express
> +| 82Q33 Express
> +| 82X38/X48 Express
> +
> +---
> +linux-mei@linux.intel.com
> diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-
> devices/mei/mei.txt
> deleted file mode 100644
> index 2b80a0cd621f..000000000000
> --- a/Documentation/misc-devices/mei/mei.txt
> +++ /dev/null
> @@ -1,266 +0,0 @@
> -Intel(R) Management Engine Interface (Intel(R) MEI) -
> ===================================================
> -
> -Introduction
> -============
> -
> -The Intel Management Engine (Intel ME) is an isolated and protected
> computing -resource (Co-processor) residing inside certain Intel chipsets. The
> Intel ME -provides support for computer/IT management features. The feature
> set -depends on the Intel chipset SKU.
> -
> -The Intel Management Engine Interface (Intel MEI, previously known as HECI)
> -is the interface between the Host and Intel ME. This interface is exposed -to
> the host as a PCI device. The Intel MEI Driver is in charge of the -
> communication channel between a host application and the Intel ME feature.
> -
> -Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and -each
> client has its own protocol. The protocol is message-based with a -header and
> payload up to 512 bytes.
> -
> -Prominent usage of the Intel ME Interface is to communicate with Intel(R) -
> Active Management Technology (Intel AMT) implemented in firmware running
> on -the Intel ME.
> -
> -Intel AMT provides the ability to manage a host remotely out-of-band (OOB) -
> even when the operating system running on the host processor has crashed or -
> is in a sleep state.
> -
> -Some examples of Intel AMT usage are:
> - - Monitoring hardware state and platform components
> - - Remote power off/on (useful for green computing or overnight IT
> - maintenance)
> - - OS updates
> - - Storage of useful platform information such as software assets
> - - Built-in hardware KVM
> - - Selective network isolation of Ethernet and IP protocol flows based
> - on policies set by a remote management console
> - - IDE device redirection from remote management console
> -
> -Intel AMT (OOB) communication is based on SOAP (deprecated -starting with
> Release 6.0) over HTTP/S or WS-Management protocol over -HTTP/S that are
> received from a remote management console application.
> -
> -For more information about Intel AMT:
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> -
> -
> -Intel MEI Driver
> -================
> -
> -The driver exposes a misc device called /dev/mei.
> -
> -An application maintains communication with an Intel ME feature while -
> /dev/mei is open. The binding to a specific feature is performed by calling -
> MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID.
> -The number of instances of an Intel ME feature that can be opened -at the
> same time depends on the Intel ME feature, but most of the -features allow
> only a single instance.
> -
> -The Intel AMT Host Interface (Intel AMTHI) feature supports multiple -
> simultaneous user connected applications. The Intel MEI driver -handles this
> internally by maintaining request queues for the applications.
> -
> -The driver is transparent to data that are passed between firmware feature -
> and host application.
> -
> -Because some of the Intel ME features can change the system -configuration,
> the driver by default allows only a privileged -user to access it.
> -
> -A code snippet for an application communicating with Intel AMTHI client:
> -
> - struct mei_connect_client_data data;
> - fd = open(MEI_DEVICE);
> -
> - data.d.in_client_uuid = AMTHI_UUID;
> -
> - ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
> -
> - printf("Ver=%d, MaxLen=%ld\n",
> - data.d.in_client_uuid.protocol_version,
> - data.d.in_client_uuid.max_msg_length);
> -
> - [...]
> -
> - write(fd, amthi_req_data, amthi_req_data_len);
> -
> - [...]
> -
> - read(fd, &amthi_res_data, amthi_res_data_len);
> -
> - [...]
> - close(fd);
> -
> -
> -IOCTL
> -=====
> -
> -The Intel MEI Driver supports the following IOCTL commands:
> - IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client).
> -
> - usage:
> - struct mei_connect_client_data clientData;
> - ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
> -
> - inputs:
> - mei_connect_client_data struct contain the following
> - input field:
> -
> - in_client_uuid - UUID of the FW Feature that needs
> - to connect to.
> - outputs:
> - out_client_properties - Client Properties: MTU and Protocol
> Version.
> -
> - error returns:
> - EINVAL Wrong IOCTL Number
> - ENODEV Device or Connection is not initialized or
> ready.
> - (e.g. Wrong UUID)
> - ENOMEM Unable to allocate memory to client internal
> data.
> - EFAULT Fatal Error (e.g. Unable to access user input data)
> - EBUSY Connection Already Open
> -
> - Notes:
> - max_msg_length (MTU) in client properties describes the maximum
> - data that can be sent or received. (e.g. if MTU=2K, can send
> - requests up to bytes 2k and received responses up to 2k bytes).
> -
> - IOCTL_MEI_NOTIFY_SET: enable or disable event notifications
> -
> - Usage:
> - uint32_t enable;
> - ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
> -
> - Inputs:
> - uint32_t enable = 1;
> - or
> - uint32_t enable[disable] = 0;
> -
> - Error returns:
> - EINVAL Wrong IOCTL Number
> - ENODEV Device is not initialized or the client not
> connected
> - ENOMEM Unable to allocate memory to client internal
> data.
> - EFAULT Fatal Error (e.g. Unable to access user input data)
> - EOPNOTSUPP if the device doesn't support the feature
> -
> - Notes:
> - The client must be connected in order to enable notification events
> -
> -
> - IOCTL_MEI_NOTIFY_GET : retrieve event
> -
> - Usage:
> - uint32_t event;
> - ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
> -
> - Outputs:
> - 1 - if an event is pending
> - 0 - if there is no even pending
> -
> - Error returns:
> - EINVAL Wrong IOCTL Number
> - ENODEV Device is not initialized or the client not
> connected
> - ENOMEM Unable to allocate memory to client internal
> data.
> - EFAULT Fatal Error (e.g. Unable to access user input data)
> - EOPNOTSUPP if the device doesn't support the feature
> -
> - Notes:
> - The client must be connected and event notification has to be enabled
> - in order to receive an event
> -
> -
> -Intel ME Applications
> -=====================
> -
> - 1) Intel Local Management Service (Intel LMS)
> -
> - Applications running locally on the platform communicate with Intel
> AMT Release
> - 2.0 and later releases in the same way that network applications do
> via SOAP
> - over HTTP (deprecated starting with Release 6.0) or with WS-
> Management over
> - SOAP over HTTP. This means that some Intel AMT features can be
> accessed from a
> - local application using the same network interface as a remote
> application
> - communicating with Intel AMT over the network.
> -
> - When a local application sends a message addressed to the local Intel
> AMT host
> - name, the Intel LMS, which listens for traffic directed to the host
> name,
> - intercepts the message and routes it to the Intel MEI.
> - For more information:
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> - Under "About Intel AMT" => "Local Access"
> -
> - For downloading Intel LMS:
> - http://software.intel.com/en-us/articles/download-the-latest-intel-
> amt-open-source-drivers/
> -
> - The Intel LMS opens a connection using the Intel MEI driver to the
> Intel LMS
> - firmware feature using a defined UUID and then communicates with
> the feature
> - using a protocol called Intel AMT Port Forwarding Protocol (Intel APF
> protocol).
> - The protocol is used to maintain multiple sessions with Intel AMT
> from a
> - single application.
> -
> - See the protocol specification in the Intel AMT Software Development
> Kit (SDK)
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> - Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
> - => "Information for Intel(R) vPro(TM) Gateway Developers"
> - => "Description of the Intel AMT Port Forwarding (APF) Protocol"
> -
> - 2) Intel AMT Remote configuration using a Local Agent
> -
> - A Local Agent enables IT personnel to configure Intel AMT out-of-the-
> box
> - without requiring installing additional data to enable setup. The
> remote
> - configuration process may involve an ISV-developed remote
> configuration
> - agent that runs on the host.
> - For more information:
> -
> http://software.intel.com/sites/manageability/AMT_Implementation_and_Refe
> rence_Guide
> - Under "Setup and Configuration of Intel AMT" =>
> - "SDK Tools Supporting Setup and Configuration" =>
> - "Using the Local Agent Sample"
> -
> - An open source Intel AMT configuration utility, implementing a local
> agent
> - that accesses the Intel MEI driver, can be found here:
> - http://software.intel.com/en-us/articles/download-the-latest-intel-
> amt-open-source-drivers/
> -
> -
> -Intel AMT OS Health Watchdog
> -============================
> -
> -The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
> -Whenever the OS hangs or crashes, Intel AMT will send an event -to any
> subscriber to this event. This mechanism means that -IT knows when a platform
> crashes even when there is a hard failure on the host.
> -
> -The Intel AMT Watchdog is composed of two parts:
> - 1) Firmware feature - receives the heartbeats
> - and sends an event when the heartbeats stop.
> - 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
> - configures the watchdog and sends the heartbeats.
> -
> -The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
> -the Intel AMT Watchdog and to send heartbeats to it. The default timeout of
> the -watchdog is 120 seconds.
> -
> -If the Intel AMT is not enabled in the firmware then the watchdog client won't
> enumerate -on the me client bus and watchdog devices won't be exposed.
> -
> -
> -Supported Chipsets
> -==================
> -
> -7 Series Chipset Family
> -6 Series Chipset Family
> -5 Series Chipset Family
> -4 Series Chipset Family
> -Mobile 4 Series Chipset Family
> -ICH9
> -82946GZ/GL
> -82G35 Express
> -82Q963/Q965
> -82P965/G965
> -Mobile PM965/GM965
> -Mobile GME965/GLE960
> -82Q35 Express
> -82G33/G31/P35/P31 Express
> -82Q33 Express
> -82X38/X48 Express
> -
> ----
> -linux-mei@linux.intel.com
> --
> 2.17.1
^ permalink raw reply
* Re: [PATCH 0/2] hwspinlock: add the 'in_atomic' API
From: Bjorn Andersson @ 2019-06-30 4:08 UTC (permalink / raw)
To: Fabien Dessenne
Cc: Ohad Ben-Cohen, Jonathan Corbet, linux-remoteproc, linux-doc,
linux-kernel, Benjamin Gaignard, Alexandre Torgue
In-Reply-To: <1551974303-24542-1-git-send-email-fabien.dessenne@st.com>
On Thu 07 Mar 07:58 PST 2019, Fabien Dessenne wrote:
> In its current implementation, the hwspinlock framework relies on jiffies
> to handle the timeout of the hwspin_lock_timeout_xxx() API.
> In an atomic context (or more precisely when irq are disabled) jiffies does not
> increase, which prevents the timeout to reach its target value (infinite loop).
>
> Note that there is already an hwspinlock user that runs in atomic context
> (drivers/irqchip/irq-stm32-exti.c) and that has to handle by itself the
> timeout.
>
> The first patch of the series completes the Documentation (the 'raw' API
> is not documented), and the second patch provides with the 'in_atomic' API.
>
Applied
Thanks,
Bjorn
> Fabien Dessenne (2):
> hwspinlock: document the hwspinlock 'raw' API
> hwspinlock: add the 'in_atomic' API
>
> Documentation/hwspinlock.txt | 81 ++++++++++++++++++++++++++++++++++++
> drivers/hwspinlock/hwspinlock_core.c | 43 +++++++++++++------
> include/linux/hwspinlock.h | 61 +++++++++++++++++++++++++--
> 3 files changed, 169 insertions(+), 16 deletions(-)
>
> --
> 2.7.4
>
^ permalink raw reply
* Re: [PATCH] binfmt_elf: Extract .note.gnu.property from an ELF file
From: Andy Lutomirski @ 2019-06-29 23:51 UTC (permalink / raw)
To: Florian Weimer
Cc: Andy Lutomirski, Dave Martin, Yu-cheng Yu, X86 ML, H. Peter Anvin,
Thomas Gleixner, Ingo Molnar, LKML, open list:DOCUMENTATION,
Linux-MM, linux-arch, Linux API, Arnd Bergmann, Balbir Singh,
Cyrill Gorcunov, Dave Hansen, Eugene Syromiatnikov, H.J. Lu,
Jann Horn, Jonathan Corbet, Kees Cook, Mike Kravetz, Nadav Amit,
Oleg Nesterov, Pavel Machek, Peter Zijlstra, Randy Dunlap,
Ravi V. Shankar, Vedvyas Shanbhogue, Szabolcs Nagy, libc-alpha
In-Reply-To: <87ef3fweoq.fsf@oldenburg2.str.redhat.com>
On Thu, Jun 27, 2019 at 2:39 AM Florian Weimer <fweimer@redhat.com> wrote:
>
> * Andy Lutomirski:
>
> > Also, I don't think there's any actual requirement that the upstream
> > kernel recognize existing CET-enabled RHEL 8 binaries as being
> > CET-enabled. I tend to think that RHEL 8 jumped the gun here.
>
> The ABI was supposed to be finalized and everyone involved thought it
> had been reviewed by the GNU gABI community and other interested
> parties. It had been included in binutils for several releases.
>
> From my point of view, the kernel is just a consumer of the ABI. The
> kernel would not change an instruction encoding if it doesn't like it
> for some reason, either.
I read the only relevant gABI thing I could find easily, and it seems
to document the "gnu property" thing. I have no problem with that.
>
> > While the upstream kernel should make some reasonble effort to make
> > sure that RHEL 8 binaries will continue to run, I don't see why we
> > need to go out of our way to keep the full set of mitigations
> > available for binaries that were developed against a non-upstream
> > kernel.
>
> They were developed against the ABI specification.
>
> I do not have a strong opinion what the kernel should do going forward.
> I just want to make clear what happened.
I admit that I'm not really clear on exactly what RHEL 8 shipped.
Some of this stuff is very much an ELF ABI that belongs to the
toolchain, but some if it is kernel API. For example, the IBT legacy
bitmap API is very much in flux, and I don't think anything credible
has been submitted for upstream inclusion. Does RHEL 8's glibc
attempt to cope with the case where some libraries are CET-compatible
and some are not? If so, how does this work? What, if any, services
does the RHEL 8 kernel provide in this direction?
^ permalink raw reply
* Re: [RFC PATCH 3/3] Prevent user from writing to IBT bitmap.
From: Andy Lutomirski @ 2019-06-29 23:44 UTC (permalink / raw)
To: Yu-cheng Yu
Cc: X86 ML, H. Peter Anvin, Thomas Gleixner, Ingo Molnar, LKML,
open list:DOCUMENTATION, Linux-MM, linux-arch, Linux API,
Arnd Bergmann, Balbir Singh, Borislav Petkov, Cyrill Gorcunov,
Dave Hansen, Eugene Syromiatnikov, Florian Weimer, H.J. Lu,
Jann Horn, Jonathan Corbet, Kees Cook, Mike Kravetz, Nadav Amit,
Oleg Nesterov, Pavel Machek, Peter Zijlstra, Randy Dunlap,
Ravi V. Shankar, Vedvyas Shanbhogue, Dave Martin
In-Reply-To: <20190628194158.2431-3-yu-cheng.yu@intel.com>
On Fri, Jun 28, 2019 at 12:50 PM Yu-cheng Yu <yu-cheng.yu@intel.com> wrote:
>
> The IBT bitmap is visiable from user-mode, but not writable.
>
> Signed-off-by: Yu-cheng Yu <yu-cheng.yu@intel.com>
>
> ---
> arch/x86/mm/fault.c | 7 +++++++
> 1 file changed, 7 insertions(+)
>
> diff --git a/arch/x86/mm/fault.c b/arch/x86/mm/fault.c
> index 59f4f66e4f2e..231196abb62e 100644
> --- a/arch/x86/mm/fault.c
> +++ b/arch/x86/mm/fault.c
> @@ -1454,6 +1454,13 @@ void do_user_addr_fault(struct pt_regs *regs,
> * we can handle it..
> */
> good_area:
> +#define USER_MODE_WRITE (FAULT_FLAG_WRITE | FAULT_FLAG_USER)
> + if (((flags & USER_MODE_WRITE) == USER_MODE_WRITE) &&
> + (vma->vm_flags & VM_IBT)) {
> + bad_area_access_error(regs, hw_error_code, address, vma);
> + return;
> + }
> +
Just make the VMA have VM_WRITE and VM_MAYWRITE clear. No new code
like this should be required.
^ permalink raw reply
* Re: [RFC PATCH 2/3] Introduce arch_prctl(ARCH_X86_CET_MARK_LEGACY_CODE)
From: Andy Lutomirski @ 2019-06-29 23:43 UTC (permalink / raw)
To: Yu-cheng Yu
Cc: X86 ML, H. Peter Anvin, Thomas Gleixner, Ingo Molnar, LKML,
open list:DOCUMENTATION, Linux-MM, linux-arch, Linux API,
Arnd Bergmann, Balbir Singh, Borislav Petkov, Cyrill Gorcunov,
Dave Hansen, Eugene Syromiatnikov, Florian Weimer, H.J. Lu,
Jann Horn, Jonathan Corbet, Kees Cook, Mike Kravetz, Nadav Amit,
Oleg Nesterov, Pavel Machek, Peter Zijlstra, Randy Dunlap,
Ravi V. Shankar, Vedvyas Shanbhogue, Dave Martin
In-Reply-To: <20190628194158.2431-2-yu-cheng.yu@intel.com>
> On Jun 28, 2019, at 12:41 PM, Yu-cheng Yu <yu-cheng.yu@intel.com> wrote:
>
> The CET legacy code bitmap covers the whole user-mode address space and is
> located at the top of the user-mode address space. It is allocated only
> when the first time arch_prctl(ARCH_X86_MARK_LEGACY_CODE) is called from
> an application.
>
> Introduce:
>
> arch_prctl(ARCH_X86_MARK_LEGACY_CODE, unsigned long *buf)
> Mark an address range as IBT legacy code.
How about defining a struct for this?
The change log should discuss where the bitmap goes and how it’s allocated.
> +static int alloc_bitmap(void)
> +{
> + unsigned long addr;
> + u64 msr_ia32_u_cet;
> +
> + addr = do_mmap_locked(NULL, IBT_BITMAP_ADDR, IBT_BITMAP_SIZE,
> + PROT_READ | PROT_WRITE,
> + MAP_ANONYMOUS | MAP_PRIVATE | MAP_FIXED_NOREPLACE,
> + VM_IBT | VM_NORESERVE, NULL);
> +
> + if (IS_ERR((void *)addr))
> + return addr;
> +
> + current->thread.cet.ibt_bitmap_addr = addr;
addr is a constant. Why are you storing it? If it ends up not being
constant, you should wire up mremap like the vDSO does.
> +static int set_user_bits(unsigned long __user *buf, unsigned long buf_size,
> + unsigned long start_bit, unsigned long end_bit, unsigned long set)
> +{
> + unsigned long start_ul, end_ul, total_ul;
> + int i, j, r;
> +
> + if (round_up(end_bit, BITS_PER_BYTE) / BITS_PER_BYTE > buf_size)
> + end_bit = buf_size * BITS_PER_BYTE - 1;
> +
> + start_ul = start_bit / BITS_PER_LONG;
> + end_ul = end_bit / BITS_PER_LONG;
> + total_ul = (end_ul - start_ul + 1);
> +
> + i = start_bit % BITS_PER_LONG;
> + j = end_bit % BITS_PER_LONG;
> +
> + r = 0;
> + put_user_try {
put_user_try is obsolete. Just use get_user(), etc.
Also, I must be missing something fundamental, because this series
claims that user code can't write directly to the bitmap. This means
that this entire function shouldn't work at all.
^ permalink raw reply
* Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands
From: Srinivas Pandruvada @ 2019-06-29 22:17 UTC (permalink / raw)
To: Andy Shevchenko
Cc: Darren Hart, Andy Shevchenko, Andriy Shevchenko, Jonathan Corbet,
Rafael J. Wysocki, Alan Cox, Len Brown, prarit, darcari,
Linux Documentation List, Linux Kernel Mailing List,
Platform Driver
In-Reply-To: <CAHp75VduxgJ6k4J2bB83Xbif0D0AGkxyDAdwvN64ybxdxXHXcw@mail.gmail.com>
On Sat, 2019-06-29 at 19:03 +0300, Andy Shevchenko wrote:
> On Sat, Jun 29, 2019 at 5:53 PM Srinivas Pandruvada
> <srinivas.pandruvada@linux.intel.com> wrote:
> > On Sat, 2019-06-29 at 17:31 +0300, Andy Shevchenko wrote:
> > > On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
> > > <srinivas.pandruvada@linux.intel.com> wrote:
> > > I need an Ack from tools/power maintainer(s) for this.
> > > Also see below.
> >
> > MAINTAINER file doesn't call for any special name in this folder.
>
> And this tells me perhaps this driver needs a MAINTAINER record?
I will submit a MAINTAINER file update. I was waiting for reviews.
Thanks,
Srinivas
>
> > $./scripts/get_maintainer.pl 0010-tools-power-x86-A-tool-to-
> > validate-
> > Intel-Speed-Selec.patch
> > Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
> > (commit_signer:1/1=100%,authored:1/1=100%,added_lines:31/31=100%,ad
> > ded_
> > lines:231/231=100%,added_lines:1607/1607=100%,added_lines:721/721=1
> > 00%,
> > added_lines:479/479=100%)
> > linux-kernel@vger.kernel.org (open list)
> >
> > Len and Rafael can you ACK this tool patch?
>
>
^ permalink raw reply
* [PATCH] Documentation: misc-devices: mei: Convert mei txt files to reST
From: Shreeya Patel @ 2019-06-29 21:32 UTC (permalink / raw)
To: skhan, corbet, tomas.winkler, linux-doc, linux-kernel,
linux-kernel-mentees
Convert the MEI misc device's documentation files from .txt to
reStructuredText format. Make a minor change of correcting the
wrong macro name MEI_CONNECT_CLIENT_IOCTL to IOCTL_MEI_CONNECT_CLIENT.
Add an index file in mei as there are two sections for it in the
documentation.
Signed-off-by: Shreeya Patel <shreeya.patel23498@gmail.com>
---
I am not sure if I have placed the Documentation in the right place
so I would like to get some suggestions from the MAINTAINERS on this
part.
Documentation/misc-devices/index.rst | 1 +
Documentation/misc-devices/mei/index.rst | 15 +
.../misc-devices/mei/mei-client-bus.rst | 151 +++++++++
.../misc-devices/mei/mei-client-bus.txt | 141 ---------
Documentation/misc-devices/mei/mei.rst | 289 ++++++++++++++++++
Documentation/misc-devices/mei/mei.txt | 266 ----------------
6 files changed, 456 insertions(+), 407 deletions(-)
create mode 100644 Documentation/misc-devices/mei/index.rst
create mode 100644 Documentation/misc-devices/mei/mei-client-bus.rst
delete mode 100644 Documentation/misc-devices/mei/mei-client-bus.txt
create mode 100644 Documentation/misc-devices/mei/mei.rst
delete mode 100644 Documentation/misc-devices/mei/mei.txt
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index dfd1f45a3127..e788a12b2b19 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -15,3 +15,4 @@ fit into other categories.
:maxdepth: 2
ibmvmc
+ mei/index
diff --git a/Documentation/misc-devices/mei/index.rst b/Documentation/misc-devices/mei/index.rst
new file mode 100644
index 000000000000..3018098ad075
--- /dev/null
+++ b/Documentation/misc-devices/mei/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================================================
+Intel(R) Management Engine Interface Kernel Driver (Intel(R) MEI)
+=================================================================
+
+.. class:: toc-title
+
+ Table of contents
+
+.. toctree::
+ :maxdepth: 2
+
+ mei
+ mei-client-bus
diff --git a/Documentation/misc-devices/mei/mei-client-bus.rst b/Documentation/misc-devices/mei/mei-client-bus.rst
new file mode 100644
index 000000000000..82d455afae78
--- /dev/null
+++ b/Documentation/misc-devices/mei/mei-client-bus.rst
@@ -0,0 +1,151 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================================
+Intel(R) Management Engine (ME) Client bus API
+==============================================
+
+
+Rationale
+=========
+
+MEI misc character device is useful for dedicated applications to send and receive
+data to the many FW appliance found in Intel's ME from the user space.
+However for some of the ME functionalities it make sense to leverage existing software
+stack and expose them through existing kernel subsystems.
+
+In order to plug seamlessly into the kernel device driver model we add kernel virtual
+bus abstraction on top of the MEI driver. This allows implementing linux kernel drivers
+for the various MEI features as a stand alone entities found in their respective subsystem.
+Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to
+the existing code.
+
+
+MEI CL bus API
+==============
+
+A driver implementation for an MEI Client is very similar to existing bus
+based device drivers. The driver registers itself as an MEI CL bus driver through
+the :c:type:`mei_cl_driver` structure:
+
+::
+
+ struct mei_cl_driver {
+ struct device_driver driver;
+ const char *name;
+
+ const struct mei_cl_device_id *id_table;
+
+ int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
+ int (*remove)(struct mei_cl_device *dev);
+ };
+
+ struct mei_cl_id {
+ char name[MEI_NAME_SIZE];
+ kernel_ulong_t driver_info;
+ };
+
+
+The :c:type:`mei_cl_id` structure allows the driver to bind itself against a device name.
+
+To actually register a driver on the ME Client bus one must call the :c:func:`mei_cl_add_driver()`
+API. This is typically called at module init time.
+
+Once registered on the ME Client bus, a driver will typically try to do some I/O on
+this bus and this should be done through the :c:func:`mei_cl_send()` and :c:func:`mei_cl_recv()`
+routines. The latter is synchronous (blocks and sleeps until data shows up).
+In order for drivers to be notified of pending events waiting for them (e.g.
+an Rx event) they can register an event handler through the
+:c:func:`mei_cl_register_event_cb()` routine. Currently only the :c:macro:`MEI_EVENT_RX` event
+will trigger an event handler call and the driver implementation is supposed
+to call :c:func:`mei_recv()` from the event handler in order to fetch the pending
+received buffers.
+
+
+Example
+=======
+
+As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
+The driver init and exit routines for this device would look like:
+
+::
+
+ #define CONTACT_DRIVER_NAME "contact"
+
+ static struct mei_cl_device_id contact_mei_cl_tbl[] = {
+ { CONTACT_DRIVER_NAME, },
+ /* required last entry */
+ { }
+ };
+ MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
+
+ static struct mei_cl_driver contact_driver = {
+ .id_table = contact_mei_tbl,
+ .name = CONTACT_DRIVER_NAME,
+ .probe = contact_probe,
+ .remove = contact_remove,
+ };
+
+ static int contact_init(void)
+ {
+ int r;
+
+ r = mei_cl_driver_register(&contact_driver);
+ if (r) {
+ pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
+ return r;
+ }
+
+ return 0;
+ }
+
+ static void __exit contact_exit(void)
+ {
+ mei_cl_driver_unregister(&contact_driver);
+ }
+
+ module_init(contact_init);
+ module_exit(contact_exit);
+
+And the driver's simplified probe routine would look like that:
+
+::
+
+ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
+ {
+ struct contact_driver *contact;
+
+ [...]
+ mei_cl_enable_device(dev);
+
+ mei_cl_register_event_cb(dev, contact_event_cb, contact);
+
+ return 0;
+ }
+
+In the probe routine the driver first enable the MEI device and then registers
+an ME bus event handler which is as close as it can get to registering a
+threaded IRQ handler.
+The handler implementation will typically call some I/O routine depending on
+the pending events:
+
+::
+
+ #define MAX_NFC_PAYLOAD 128
+
+ static void contact_event_cb(struct mei_cl_device *dev, u32 events,
+ void *context)
+ {
+ struct contact_driver *contact = context;
+
+ if (events & BIT(MEI_EVENT_RX)) {
+ u8 payload[MAX_NFC_PAYLOAD];
+ int payload_size;
+
+ payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
+ if (payload_size <= 0)
+ return;
+
+ /* Hook to the NFC subsystem */
+ nfc_hci_recv_frame(contact->hdev, payload, payload_size);
+ }
+ }
diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt b/Documentation/misc-devices/mei/mei-client-bus.txt
deleted file mode 100644
index 743be4ec8989..000000000000
--- a/Documentation/misc-devices/mei/mei-client-bus.txt
+++ /dev/null
@@ -1,141 +0,0 @@
-Intel(R) Management Engine (ME) Client bus API
-==============================================
-
-
-Rationale
-=========
-
-MEI misc character device is useful for dedicated applications to send and receive
-data to the many FW appliance found in Intel's ME from the user space.
-However for some of the ME functionalities it make sense to leverage existing software
-stack and expose them through existing kernel subsystems.
-
-In order to plug seamlessly into the kernel device driver model we add kernel virtual
-bus abstraction on top of the MEI driver. This allows implementing linux kernel drivers
-for the various MEI features as a stand alone entities found in their respective subsystem.
-Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to
-the existing code.
-
-
-MEI CL bus API
-==============
-
-A driver implementation for an MEI Client is very similar to existing bus
-based device drivers. The driver registers itself as an MEI CL bus driver through
-the mei_cl_driver structure:
-
-struct mei_cl_driver {
- struct device_driver driver;
- const char *name;
-
- const struct mei_cl_device_id *id_table;
-
- int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
- int (*remove)(struct mei_cl_device *dev);
-};
-
-struct mei_cl_id {
- char name[MEI_NAME_SIZE];
- kernel_ulong_t driver_info;
-};
-
-The mei_cl_id structure allows the driver to bind itself against a device name.
-
-To actually register a driver on the ME Client bus one must call the mei_cl_add_driver()
-API. This is typically called at module init time.
-
-Once registered on the ME Client bus, a driver will typically try to do some I/O on
-this bus and this should be done through the mei_cl_send() and mei_cl_recv()
-routines. The latter is synchronous (blocks and sleeps until data shows up).
-In order for drivers to be notified of pending events waiting for them (e.g.
-an Rx event) they can register an event handler through the
-mei_cl_register_event_cb() routine. Currently only the MEI_EVENT_RX event
-will trigger an event handler call and the driver implementation is supposed
-to call mei_recv() from the event handler in order to fetch the pending
-received buffers.
-
-
-Example
-=======
-
-As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
-The driver init and exit routines for this device would look like:
-
-#define CONTACT_DRIVER_NAME "contact"
-
-static struct mei_cl_device_id contact_mei_cl_tbl[] = {
- { CONTACT_DRIVER_NAME, },
-
- /* required last entry */
- { }
-};
-MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
-
-static struct mei_cl_driver contact_driver = {
- .id_table = contact_mei_tbl,
- .name = CONTACT_DRIVER_NAME,
-
- .probe = contact_probe,
- .remove = contact_remove,
-};
-
-static int contact_init(void)
-{
- int r;
-
- r = mei_cl_driver_register(&contact_driver);
- if (r) {
- pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
- return r;
- }
-
- return 0;
-}
-
-static void __exit contact_exit(void)
-{
- mei_cl_driver_unregister(&contact_driver);
-}
-
-module_init(contact_init);
-module_exit(contact_exit);
-
-And the driver's simplified probe routine would look like that:
-
-int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
-{
- struct contact_driver *contact;
-
- [...]
- mei_cl_enable_device(dev);
-
- mei_cl_register_event_cb(dev, contact_event_cb, contact);
-
- return 0;
-}
-
-In the probe routine the driver first enable the MEI device and then registers
-an ME bus event handler which is as close as it can get to registering a
-threaded IRQ handler.
-The handler implementation will typically call some I/O routine depending on
-the pending events:
-
-#define MAX_NFC_PAYLOAD 128
-
-static void contact_event_cb(struct mei_cl_device *dev, u32 events,
- void *context)
-{
- struct contact_driver *contact = context;
-
- if (events & BIT(MEI_EVENT_RX)) {
- u8 payload[MAX_NFC_PAYLOAD];
- int payload_size;
-
- payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
- if (payload_size <= 0)
- return;
-
- /* Hook to the NFC subsystem */
- nfc_hci_recv_frame(contact->hdev, payload, payload_size);
- }
-}
diff --git a/Documentation/misc-devices/mei/mei.rst b/Documentation/misc-devices/mei/mei.rst
new file mode 100644
index 000000000000..e91ac2570b4d
--- /dev/null
+++ b/Documentation/misc-devices/mei/mei.rst
@@ -0,0 +1,289 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Intel(R) Management Engine Interface
+====================================
+
+Introduction
+============
+
+The Intel Management Engine (Intel ME) is an isolated and protected computing
+resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
+provides support for computer/IT management features. The feature set
+depends on the Intel chipset SKU.
+
+The Intel Management Engine Interface (Intel MEI, previously known as HECI)
+is the interface between the Host and Intel ME. This interface is exposed
+to the host as a PCI device. The Intel MEI Driver is in charge of the
+communication channel between a host application and the Intel ME feature.
+
+Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
+each client has its own protocol. The protocol is message-based with a
+header and payload up to 512 bytes.
+
+Prominent usage of the Intel ME Interface is to communicate with Intel(R)
+Active Management Technology (Intel AMT) implemented in firmware running on
+the Intel ME.
+
+Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
+even when the operating system running on the host processor has crashed or
+is in a sleep state.
+
+Some examples of Intel AMT usage are:
+ * Monitoring hardware state and platform components
+ * Remote power off/on (useful for green computing or overnight IT
+ maintenance)
+ * OS updates
+ * Storage of useful platform information such as software assets
+ * Built-in hardware KVM
+ * Selective network isolation of Ethernet and IP protocol flows based
+ on policies set by a remote management console
+ * IDE device redirection from remote management console
+
+Intel AMT (OOB) communication is based on SOAP (deprecated
+starting with Release 6.0) over HTTP/S or WS-Management protocol over
+HTTP/S that are received from a remote management console application.
+
+For more information about Intel AMT:
+`<http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide>`_
+
+
+Intel MEI Driver
+================
+
+The driver exposes a misc device called :file:`/dev/mei`.
+
+An application maintains communication with an Intel ME feature while
+:file:`/dev/mei` is open. The binding to a specific feature is performed by calling
+:c:macro:`IOCTL_MEI_CONNECT_CLIENT`, which passes the desired UUID.
+The number of instances of an Intel ME feature that can be opened
+at the same time depends on the Intel ME feature, but most of the
+features allow only a single instance.
+
+The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
+simultaneous user connected applications. The Intel MEI driver
+handles this internally by maintaining request queues for the applications.
+
+The driver is transparent to data that are passed between firmware feature
+and host application.
+
+Because some of the Intel ME features can change the system
+configuration, the driver by default allows only a privileged
+user to access it.
+
+A code snippet for an application communicating with Intel AMTHI client:
+
+::
+
+ struct mei_connect_client_data data;
+ fd = open(MEI_DEVICE);
+
+ data.d.in_client_uuid = AMTHI_UUID;
+
+ ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
+
+ printf("Ver=%d, MaxLen=%ld\n",
+ data.d.in_client_uuid.protocol_version,
+ data.d.in_client_uuid.max_msg_length);
+
+ [...]
+
+ write(fd, amthi_req_data, amthi_req_data_len);
+
+ [...]
+
+ read(fd, &amthi_res_data, amthi_res_data_len);
+
+ [...]
+
+ close(fd);
+
+
+IOCTL
+=====
+
+The Intel MEI Driver supports the following IOCTL commands:
+
+
+:c:macro:`IOCTL_MEI_CONNECT_CLIENT`
+-------------------------------------
+Connect to firmware Feature (client)
+
+**Usage:**
+
+::
+
+ struct mei_connect_client_data clientData;
+ ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
+
+**Inputs:**
+ :c:type:`mei_connect_client_data` - structure contain the following
+ input field.
+
+ :c:data:`in_client_uuid` - UUID of the FW Feature that needs to connect to.
+
+**Outputs:**
+ :c:data:`out_client_properties` - Client Properties: MTU and Protocol Version.
+
+**Error returns:**
+ | :c:macro:`EINVAL` - Wrong IOCTL Number.
+ | :c:macro:`ENODEV` - Device or Connection is not initialized or ready. (e.g. Wrong UUID).
+ | :c:macro:`ENOMEM` - Unable to allocate memory to client internal data.
+ | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
+ | :c:macro:`EBUSY` - Connection Already Open.
+
+**Notes:**
+ :c:data:`max_msg_length` (MTU) in client properties describes the maximum
+ data that can be sent or received. (e.g. if MTU=2K, can send
+ requests up to bytes 2k and received responses up to 2k bytes).
+
+
+:c:macro:`IOCTL_MEI_NOTIFY_SET`
+-------------------------------
+Enable or disable event notifications
+
+**Usage:**
+
+::
+
+ uint32_t enable;
+ ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
+
+**Inputs:**
+ | :c:data:`uint32_t enable = 1;`
+ | or
+ | :c:data:`uint32_t enable[disable] = 0;`
+
+**Error returns:**
+ | :c:macro:`EINVAL` - Wrong IOCTL Number.
+ | :c:macro:`ENODEV` - Device is not initialized or the client not connected.
+ | :c:macro:`ENOMEM` - Unable to allocate memory to client internal data.
+ | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
+ | :c:macro:`EOPNOTSUPP` - if the device doesn't support the feature.
+
+**Notes:**
+ The client must be connected in order to enable notification events.
+
+
+:c:macro:`IOCTL_MEI_NOTIFY_GET`
+-------------------------------
+Retrieve event
+
+**Usage:**
+
+::
+
+ uint32_t event;
+ ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
+
+**Outputs:**
+ | 1 - if an event is pending.
+ | 0 - if there is no even pending.
+
+**Error returns:**
+ | :c:macro:`EINVAL` - Wrong IOCTL Number.
+ | :c:macro:`ENODEV` - Device is not initialized or the client not connected.
+ | :c:macro:`ENOMEM` - Unable to allocate memory to client internal data.
+ | :c:macro:`EFAULT` - Fatal Error (e.g. Unable to access user input data).
+ | :c:macro:`EOPNOTSUPP` - if the device doesn't support the feature.
+
+**Notes:**
+ The client must be connected and event notification has to be enabled
+ in order to receive an event.
+
+
+Intel ME Applications
+=====================
+
+1) Intel Local Management Service (Intel LMS)
+
+ Applications running locally on the platform communicate with Intel AMT Release
+ 2.0 and later releases in the same way that network applications do via SOAP
+ over HTTP (deprecated starting with Release 6.0) or with WS-Management over
+ SOAP over HTTP. This means that some Intel AMT features can be accessed from a
+ local application using the same network interface as a remote application
+ communicating with Intel AMT over the network.
+
+ When a local application sends a message addressed to the local Intel AMT host
+ name, the Intel LMS, which listens for traffic directed to the host name,
+ intercepts the message and routes it to the Intel MEI.
+ For more information:
+ `<http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide>`_
+ Under "About Intel AMT" => "Local Access"
+
+ For downloading Intel LMS:
+ `<http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/>`_
+
+ The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
+ firmware feature using a defined UUID and then communicates with the feature
+ using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
+ The protocol is used to maintain multiple sessions with Intel AMT from a
+ single application.
+
+ See the protocol specification in the `Intel AMT Software Development Kit (SDK)
+ <http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide>`_
+ Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
+ => "Information for Intel(R) vPro(TM) Gateway Developers"
+ => "Description of the Intel AMT Port Forwarding (APF) Protocol"
+
+2) Intel AMT Remote configuration using a Local Agent
+
+ A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
+ without requiring installing additional data to enable setup. The remote
+ configuration process may involve an ISV-developed remote configuration
+ agent that runs on the host.
+ For more information:
+ `<http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide>`_
+ Under "Setup and Configuration of Intel AMT" =>
+ "SDK Tools Supporting Setup and Configuration" =>
+ "Using the Local Agent Sample"
+
+ An open source Intel AMT configuration utility, implementing a local agent
+ that accesses the Intel MEI driver, can be found here:
+ `<http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/>`
+
+
+Intel AMT OS Health Watchdog
+============================
+
+The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
+Whenever the OS hangs or crashes, Intel AMT will send an event
+to any subscriber to this event. This mechanism means that
+IT knows when a platform crashes even when there is a hard failure on the host.
+
+The Intel AMT Watchdog is composed of two parts:
+ 1) Firmware feature - receives the heartbeats
+ and sends an event when the heartbeats stop.
+ 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
+ configures the watchdog and sends the heartbeats.
+
+The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
+the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the
+watchdog is 120 seconds.
+
+If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate
+on the me client bus and watchdog devices won't be exposed.
+
+
+Supported Chipsets
+==================
+
+| 7 Series Chipset Family
+| 6 Series Chipset Family
+| 5 Series Chipset Family
+| 4 Series Chipset Family
+| Mobile 4 Series Chipset Family
+| ICH9
+| 82946GZ/GL
+| 82G35 Express
+| 82Q963/Q965
+| 82P965/G965
+| Mobile PM965/GM965
+| Mobile GME965/GLE960
+| 82Q35 Express
+| 82G33/G31/P35/P31 Express
+| 82Q33 Express
+| 82X38/X48 Express
+
+---
+linux-mei@linux.intel.com
diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt
deleted file mode 100644
index 2b80a0cd621f..000000000000
--- a/Documentation/misc-devices/mei/mei.txt
+++ /dev/null
@@ -1,266 +0,0 @@
-Intel(R) Management Engine Interface (Intel(R) MEI)
-===================================================
-
-Introduction
-============
-
-The Intel Management Engine (Intel ME) is an isolated and protected computing
-resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
-provides support for computer/IT management features. The feature set
-depends on the Intel chipset SKU.
-
-The Intel Management Engine Interface (Intel MEI, previously known as HECI)
-is the interface between the Host and Intel ME. This interface is exposed
-to the host as a PCI device. The Intel MEI Driver is in charge of the
-communication channel between a host application and the Intel ME feature.
-
-Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
-each client has its own protocol. The protocol is message-based with a
-header and payload up to 512 bytes.
-
-Prominent usage of the Intel ME Interface is to communicate with Intel(R)
-Active Management Technology (Intel AMT) implemented in firmware running on
-the Intel ME.
-
-Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
-even when the operating system running on the host processor has crashed or
-is in a sleep state.
-
-Some examples of Intel AMT usage are:
- - Monitoring hardware state and platform components
- - Remote power off/on (useful for green computing or overnight IT
- maintenance)
- - OS updates
- - Storage of useful platform information such as software assets
- - Built-in hardware KVM
- - Selective network isolation of Ethernet and IP protocol flows based
- on policies set by a remote management console
- - IDE device redirection from remote management console
-
-Intel AMT (OOB) communication is based on SOAP (deprecated
-starting with Release 6.0) over HTTP/S or WS-Management protocol over
-HTTP/S that are received from a remote management console application.
-
-For more information about Intel AMT:
-http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
-
-
-Intel MEI Driver
-================
-
-The driver exposes a misc device called /dev/mei.
-
-An application maintains communication with an Intel ME feature while
-/dev/mei is open. The binding to a specific feature is performed by calling
-MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID.
-The number of instances of an Intel ME feature that can be opened
-at the same time depends on the Intel ME feature, but most of the
-features allow only a single instance.
-
-The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
-simultaneous user connected applications. The Intel MEI driver
-handles this internally by maintaining request queues for the applications.
-
-The driver is transparent to data that are passed between firmware feature
-and host application.
-
-Because some of the Intel ME features can change the system
-configuration, the driver by default allows only a privileged
-user to access it.
-
-A code snippet for an application communicating with Intel AMTHI client:
-
- struct mei_connect_client_data data;
- fd = open(MEI_DEVICE);
-
- data.d.in_client_uuid = AMTHI_UUID;
-
- ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
-
- printf("Ver=%d, MaxLen=%ld\n",
- data.d.in_client_uuid.protocol_version,
- data.d.in_client_uuid.max_msg_length);
-
- [...]
-
- write(fd, amthi_req_data, amthi_req_data_len);
-
- [...]
-
- read(fd, &amthi_res_data, amthi_res_data_len);
-
- [...]
- close(fd);
-
-
-IOCTL
-=====
-
-The Intel MEI Driver supports the following IOCTL commands:
- IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client).
-
- usage:
- struct mei_connect_client_data clientData;
- ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
-
- inputs:
- mei_connect_client_data struct contain the following
- input field:
-
- in_client_uuid - UUID of the FW Feature that needs
- to connect to.
- outputs:
- out_client_properties - Client Properties: MTU and Protocol Version.
-
- error returns:
- EINVAL Wrong IOCTL Number
- ENODEV Device or Connection is not initialized or ready.
- (e.g. Wrong UUID)
- ENOMEM Unable to allocate memory to client internal data.
- EFAULT Fatal Error (e.g. Unable to access user input data)
- EBUSY Connection Already Open
-
- Notes:
- max_msg_length (MTU) in client properties describes the maximum
- data that can be sent or received. (e.g. if MTU=2K, can send
- requests up to bytes 2k and received responses up to 2k bytes).
-
- IOCTL_MEI_NOTIFY_SET: enable or disable event notifications
-
- Usage:
- uint32_t enable;
- ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
-
- Inputs:
- uint32_t enable = 1;
- or
- uint32_t enable[disable] = 0;
-
- Error returns:
- EINVAL Wrong IOCTL Number
- ENODEV Device is not initialized or the client not connected
- ENOMEM Unable to allocate memory to client internal data.
- EFAULT Fatal Error (e.g. Unable to access user input data)
- EOPNOTSUPP if the device doesn't support the feature
-
- Notes:
- The client must be connected in order to enable notification events
-
-
- IOCTL_MEI_NOTIFY_GET : retrieve event
-
- Usage:
- uint32_t event;
- ioctl(fd, IOCTL_MEI_NOTIFY_GET, &event);
-
- Outputs:
- 1 - if an event is pending
- 0 - if there is no even pending
-
- Error returns:
- EINVAL Wrong IOCTL Number
- ENODEV Device is not initialized or the client not connected
- ENOMEM Unable to allocate memory to client internal data.
- EFAULT Fatal Error (e.g. Unable to access user input data)
- EOPNOTSUPP if the device doesn't support the feature
-
- Notes:
- The client must be connected and event notification has to be enabled
- in order to receive an event
-
-
-Intel ME Applications
-=====================
-
- 1) Intel Local Management Service (Intel LMS)
-
- Applications running locally on the platform communicate with Intel AMT Release
- 2.0 and later releases in the same way that network applications do via SOAP
- over HTTP (deprecated starting with Release 6.0) or with WS-Management over
- SOAP over HTTP. This means that some Intel AMT features can be accessed from a
- local application using the same network interface as a remote application
- communicating with Intel AMT over the network.
-
- When a local application sends a message addressed to the local Intel AMT host
- name, the Intel LMS, which listens for traffic directed to the host name,
- intercepts the message and routes it to the Intel MEI.
- For more information:
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "About Intel AMT" => "Local Access"
-
- For downloading Intel LMS:
- http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
- The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
- firmware feature using a defined UUID and then communicates with the feature
- using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
- The protocol is used to maintain multiple sessions with Intel AMT from a
- single application.
-
- See the protocol specification in the Intel AMT Software Development Kit (SDK)
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
- => "Information for Intel(R) vPro(TM) Gateway Developers"
- => "Description of the Intel AMT Port Forwarding (APF) Protocol"
-
- 2) Intel AMT Remote configuration using a Local Agent
-
- A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
- without requiring installing additional data to enable setup. The remote
- configuration process may involve an ISV-developed remote configuration
- agent that runs on the host.
- For more information:
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "Setup and Configuration of Intel AMT" =>
- "SDK Tools Supporting Setup and Configuration" =>
- "Using the Local Agent Sample"
-
- An open source Intel AMT configuration utility, implementing a local agent
- that accesses the Intel MEI driver, can be found here:
- http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
-
-Intel AMT OS Health Watchdog
-============================
-
-The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
-Whenever the OS hangs or crashes, Intel AMT will send an event
-to any subscriber to this event. This mechanism means that
-IT knows when a platform crashes even when there is a hard failure on the host.
-
-The Intel AMT Watchdog is composed of two parts:
- 1) Firmware feature - receives the heartbeats
- and sends an event when the heartbeats stop.
- 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
- configures the watchdog and sends the heartbeats.
-
-The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
-the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the
-watchdog is 120 seconds.
-
-If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate
-on the me client bus and watchdog devices won't be exposed.
-
-
-Supported Chipsets
-==================
-
-7 Series Chipset Family
-6 Series Chipset Family
-5 Series Chipset Family
-4 Series Chipset Family
-Mobile 4 Series Chipset Family
-ICH9
-82946GZ/GL
-82G35 Express
-82Q963/Q965
-82P965/G965
-Mobile PM965/GM965
-Mobile GME965/GLE960
-82Q35 Express
-82G33/G31/P35/P31 Express
-82Q33 Express
-82X38/X48 Express
-
----
-linux-mei@linux.intel.com
--
2.17.1
^ permalink raw reply related
* Re: [linux-kernel-mentees] [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 20:59 UTC (permalink / raw)
To: skhan
Cc: linux-xfs, darrick.wong, corbet, linux-doc, linux-kernel,
linux-kernel-mentees
In-Reply-To: <20190629150155.GB10491@localhost>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v3:
Update MAINTAINERS. Fix Indentation/long line issues. Insert Sphinx tag.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 468 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 472 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..d36ef042c
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,468 @@
+.. SPDX-License-Identifier: GPL-2.0
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ allocsize=<size>
+ Sets the buffered I/O end-of-file preallocation size when doing delayed
+ allocation writeout (default size is 64KiB). Valid values for this
+ option are page size (typically 4KiB) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [no]attr2
+ The options enable/disable an "opportunistic" improvement to be made in
+ the way inline extended attributes are stored on-disk. When the new
+ form is used for the first time when ``attr2`` is selected (either when
+ setting or removing extended attributes) the on-disk superblock feature
+ bit field will be updated to reflect this format being in use.
+
+ The default behaviour is determined by the on-disk feature bit
+ indicating that ``attr2`` behaviour is active. If either mount option is
+ set, then that becomes the new default used by the filesystem. However
+ on CRC enabled filesystems, the ``attr2`` format is always used , and so
+ will reject the ``noattr2`` mount option if it is set.
+
+ (*)[no]discard
+ Enable/disable the issuing of commands to let the block device reclaim
+ space freed by the filesystem. This is useful for SSD devices, thinly
+ provisioned LUNs and virtual machine images, but may have a performance
+ impact.
+
+ Note: It is currently recommended that you use the ``fstrim``
+ application to discard unused blocks rather than the ``discard`` mount
+ option because the performance impact of this option is quite severe.
+
+ grpid/bsdgroups
+ nogrpid/(*)sysvgroups
+ These options define what group ID a newly created file gets. When
+ ``grpid`` is set, it takes the group ID of the directory in which it is
+ created; otherwise it takes the ``fsgid`` of the current process, unless
+ the directory has the ``setgid`` bit set, in which case it takes the
+ ``gid`` from the parent directory, and also gets the ``setgid`` bit set
+ if it is a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[no]ikeep
+ When ``ikeep`` is specified, XFS does not delete empty inode clusters
+ and keeps them around on disk. When ``noikeep`` is specified, empty
+ inode clusters are returned to the free space pool.
+
+ inode32 | (*)inode64
+ When ``inode32`` is specified, it indicates that XFS limits inode
+ creation to locations which will not result in inode numbers with more
+ than 32 bits of significance.
+
+ When ``inode64`` is specified, it indicates that XFS is allowed to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``inode32`` is provided for backwards compatibility with older systems
+ and applications, since 64 bits inode numbers might cause problems for
+ some applications that cannot handle large inode numbers. If
+ applications are in use which do not handle inode numbers bigger than 32
+ bits, the ``inode32`` option should be specified.
+
+
+ (*)[no]largeio
+ If ``nolargeio`` is specified, the optimal I/O reported in st_blksize by
+ **stat(2)** will be as small as possible to allow user applications to
+ avoid inefficient read/modify/write I/O. This is typically the page
+ size of the machine, as this is the granularity of the page cache.
+
+ If ``largeio`` is specified, a filesystem that was created with a
+ ``swidth`` specified will return the ``swidth`` value (in bytes) in
+ st_blksize. If the filesystem does not have a ``swidth`` specified but
+ does specify an ``allocsize`` then ``allocsize`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ logbufs=<value>
+ Set the number of in-memory log buffers to ``value``. Valid numbers
+ range from 2-8 inclusive.
+
+ The default value is 8 buffers.
+
+ If the memory cost of 8 log buffers is too high on small systems, then
+ it may be reduced at some cost to performance on metadata intensive
+ workloads. The ``logbsize`` option below controls the size of each
+ buffer and so is also relevant to this case.
+
+ logbsize=<value>
+ Set the size of each in-memory log buffer to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. Valid sizes for
+ version 1 and version 2 logs are 16384 (16k) and 32768 (32k). Valid
+ sizes for version 2 logs also include 65536 (64k), 131072 (128k) and
+ 262144 (256k). The ``logbsize`` must be an integer multiple of the
+ "log stripe unit" configured at mkfs time.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ rtdev=<device>
+ An XFS filesystem has up to three parts: a data section, a log section,
+ and a real-time section. The real-time section is optional. If
+ enabled, ``rtdev`` sets ``device`` to be used as an external real-time
+ section, similar to ``logdev`` above.
+
+ noalign
+ Data allocations will not be aligned at stripe unit boundaries. This is
+ only relevant to filesystems created with non-zero data alignment
+ parameters (sunit, swidth) by mkfs.
+
+ norecovery
+ The filesystem will be mounted without running log recovery. If the
+ filesystem was not cleanly unmounted, it is likely to be inconsistent
+ when mounted in ``norecovery`` mode. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ nouuid
+ Don't check for double mounted file systems using the file system uuid.
+ This is useful to mount LVM snapshot volumes, and often used in
+ combination with ``norecovery`` for mounting read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ sunit=<value>
+ Used to specify the stripe unit for a RAID device or (in conjunction
+ with ``swidth`` below) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ The ``sunit`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid changes to ``sunit`` are increasing it by a power-of-2 multiple.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+ swidth=<value>
+ Used to specify the stripe width for a RAID device or (in conjunction
+ with ``sunit`` above) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ The ``swidth`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid swidth values are any integer multiple of a valid ``sunit`` value.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+
+ swalloc
+ Data allocations will be rounded up to stripe width boundaries when the
+ current end of file is being extended and the file size is larger than
+ the stripe width size.
+
+ wsync
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "sync" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodump" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "noatime" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nosymlinks" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodefrag" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- allocsize=size
- Sets the buffered I/O end-of-file preallocation size when
- doing delayed allocation writeout (default size is 64KiB).
- Valid values for this option are page size (typically 4KiB)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- The options enable/disable an "opportunistic" improvement to
- be made in the way inline extended attributes are stored
- on-disk. When the new form is used for the first time when
- attr2 is selected (either when setting or removing extended
- attributes) the on-disk superblock feature bit field will be
- updated to reflect this format being in use.
-
- The default behaviour is determined by the on-disk feature
- bit indicating that attr2 behaviour is active. If either
- mount option it set, then that becomes the new default used
- by the filesystem.
-
- CRC enabled filesystems always use the attr2 format, and so
- will reject the noattr2 mount option if it is set.
-
- discard
- nodiscard (*)
- Enable/disable the issuing of commands to let the block
- device reclaim space freed by the filesystem. This is
- useful for SSD devices, thinly provisioned LUNs and virtual
- machine images, but may have a performance impact.
-
- Note: It is currently recommended that you use the fstrim
- application to discard unused blocks rather than the discard
- mount option because the performance impact of this option
- is quite severe.
-
- grpid/bsdgroups
- nogrpid/sysvgroups (*)
- These options define what group ID a newly created file
- gets. When grpid is set, it takes the group ID of the
- directory in which it is created; otherwise it takes the
- fsgid of the current process, unless the directory has the
- setgid bit set, in which case it takes the gid from the
- parent directory, and also gets the setgid bit set if it is
- a directory itself.
-
- filestreams
- Make the data allocator use the filestreams allocation mode
- across the entire filesystem rather than just on directories
- configured to use it.
-
- ikeep
- noikeep (*)
- When ikeep is specified, XFS does not delete empty inode
- clusters and keeps them around on disk. When noikeep is
- specified, empty inode clusters are returned to the free
- space pool.
-
- inode32
- inode64 (*)
- When inode32 is specified, it indicates that XFS limits
- inode creation to locations which will not result in inode
- numbers with more than 32 bits of significance.
-
- When inode64 is specified, it indicates that XFS is allowed
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- inode32 is provided for backwards compatibility with older
- systems and applications, since 64 bits inode numbers might
- cause problems for some applications that cannot handle
- large inode numbers. If applications are in use which do
- not handle inode numbers bigger than 32 bits, the inode32
- option should be specified.
-
-
- largeio
- nolargeio (*)
- If "nolargeio" is specified, the optimal I/O reported in
- st_blksize by stat(2) will be as small as possible to allow
- user applications to avoid inefficient read/modify/write
- I/O. This is typically the page size of the machine, as
- this is the granularity of the page cache.
-
- If "largeio" specified, a filesystem that was created with a
- "swidth" specified will return the "swidth" value (in bytes)
- in st_blksize. If the filesystem does not have a "swidth"
- specified but does specify an "allocsize" then "allocsize"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
- range from 2-8 inclusive.
-
- The default value is 8 buffers.
-
- If the memory cost of 8 log buffers is too high on small
- systems, then it may be reduced at some cost to performance
- on metadata intensive workloads. The logbsize option below
- controls the size of each buffer and so is also relevant to
- this case.
-
- logbsize=value
- Set the size of each in-memory log buffer. The size may be
- specified in bytes, or in kilobytes with a "k" suffix.
- Valid sizes for version 1 and version 2 logs are 16384 (16k)
- and 32768 (32k). Valid sizes for version 2 logs also
- include 65536 (64k), 131072 (128k) and 262144 (256k). The
- logbsize must be an integer multiple of the log
- stripe unit configured at mkfs time.
-
- The default value for for version 1 logs is 32768, while the
- default value for version 2 logs is MAX(32768, log_sunit).
-
- logdev=device and rtdev=device
- Use an external log (metadata journal) and/or real-time device.
- An XFS filesystem has up to three parts: a data section, a log
- section, and a real-time section. The real-time section is
- optional, and the log section can be separate from the data
- section or contained within it.
-
- noalign
- Data allocations will not be aligned at stripe unit
- boundaries. This is only relevant to filesystems created
- with non-zero data alignment parameters (sunit, swidth) by
- mkfs.
-
- norecovery
- The filesystem will be mounted without running log recovery.
- If the filesystem was not cleanly unmounted, it is likely to
- be inconsistent when mounted in "norecovery" mode.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- nouuid
- Don't check for double mounted file systems using the file
- system uuid. This is useful to mount LVM snapshot volumes,
- and often used in combination with "norecovery" for mounting
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- sunit=value and swidth=value
- Used to specify the stripe unit and width for a RAID device
- or a stripe volume. "value" must be specified in 512-byte
- block units. These options are only relevant to filesystems
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters specified must be compatible
- with the existing filesystem alignment characteristics. In
- general, that means the only valid changes to sunit are
- increasing it by a power-of-2 multiple. Valid swidth values
- are any integer multiple of a valid sunit value.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
- modified, such as adding a new disk to a RAID5 lun and
- reshaping it.
-
- swalloc
- Data allocations will be rounded up to stripe width boundaries
- when the current end of file is being extended and the file
- size is larger than the stripe width size.
-
- wsync
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "sync" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodump" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "noatime" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nosymlinks" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodefrag" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [linux-kernel-mentees] [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 20:57 UTC (permalink / raw)
To: skhan
Cc: linux-xfs, darrick.wong, corbet, linux-doc, linux-kernel,
linux-kernel-mentees
In-Reply-To: <20190629150155.GB10491@localhost>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v3:
Update MAINTAINERS. Fix Indentation/long line issues. Insert Sphinx tag.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 468 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 472 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..d36ef042c
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,468 @@
+.. SPDX-License-Identifier: GPL-2.0
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ allocsize=<size>
+ Sets the buffered I/O end-of-file preallocation size when doing delayed
+ allocation writeout (default size is 64KiB). Valid values for this
+ option are page size (typically 4KiB) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [no]attr2
+ The options enable/disable an "opportunistic" improvement to be made in
+ the way inline extended attributes are stored on-disk. When the new
+ form is used for the first time when ``attr2`` is selected (either when
+ setting or removing extended attributes) the on-disk superblock feature
+ bit field will be updated to reflect this format being in use.
+
+ The default behaviour is determined by the on-disk feature bit
+ indicating that ``attr2`` behaviour is active. If either mount option is
+ set, then that becomes the new default used by the filesystem. However
+ on CRC enabled filesystems, the ``attr2`` format is always used , and so
+ will reject the ``noattr2`` mount option if it is set.
+
+ (*)[no]discard
+ Enable/disable the issuing of commands to let the block device reclaim
+ space freed by the filesystem. This is useful for SSD devices, thinly
+ provisioned LUNs and virtual machine images, but may have a performance
+ impact.
+
+ Note: It is currently recommended that you use the ``fstrim``
+ application to discard unused blocks rather than the ``discard`` mount
+ option because the performance impact of this option is quite severe.
+
+ grpid/bsdgroups
+ nogrpid/(*)sysvgroups
+ These options define what group ID a newly created file gets. When
+ ``grpid`` is set, it takes the group ID of the directory in which it is
+ created; otherwise it takes the ``fsgid`` of the current process, unless
+ the directory has the ``setgid`` bit set, in which case it takes the
+ ``gid`` from the parent directory, and also gets the ``setgid`` bit set
+ if it is a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[no]ikeep
+ When ``ikeep`` is specified, XFS does not delete empty inode clusters
+ and keeps them around on disk. When ``noikeep`` is specified, empty
+ inode clusters are returned to the free space pool.
+
+ inode32 | (*)inode64
+ When ``inode32`` is specified, it indicates that XFS limits inode
+ creation to locations which will not result in inode numbers with more
+ than 32 bits of significance.
+
+ When ``inode64`` is specified, it indicates that XFS is allowed to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``inode32`` is provided for backwards compatibility with older systems
+ and applications, since 64 bits inode numbers might cause problems for
+ some applications that cannot handle large inode numbers. If
+ applications are in use which do not handle inode numbers bigger than 32
+ bits, the ``inode32`` option should be specified.
+
+
+ (*)[no]largeio
+ If ``nolargeio`` is specified, the optimal I/O reported in st_blksize by
+ **stat(2)** will be as small as possible to allow user applications to
+ avoid inefficient read/modify/write I/O. This is typically the page
+ size of the machine, as this is the granularity of the page cache.
+
+ If ``largeio`` is specified, a filesystem that was created with a
+ ``swidth`` specified will return the ``swidth`` value (in bytes) in
+ st_blksize. If the filesystem does not have a ``swidth`` specified but
+ does specify an ``allocsize`` then ``allocsize`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ logbufs=<value>
+ Set the number of in-memory log buffers to ``value``. Valid numbers
+ range from 2-8 inclusive.
+
+ The default value is 8 buffers.
+
+ If the memory cost of 8 log buffers is too high on small systems, then
+ it may be reduced at some cost to performance on metadata intensive
+ workloads. The ``logbsize`` option below controls the size of each
+ buffer and so is also relevant to this case.
+
+ logbsize=<value>
+ Set the size of each in-memory log buffer to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. Valid sizes for
+ version 1 and version 2 logs are 16384 (16k) and 32768 (32k). Valid
+ sizes for version 2 logs also include 65536 (64k), 131072 (128k) and
+ 262144 (256k). The ``logbsize`` must be an integer multiple of the
+ "log stripe unit" configured at mkfs time.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ rtdev=<device>
+ An XFS filesystem has up to three parts: a data section, a log section,
+ and a real-time section. The real-time section is optional. If
+ enabled, ``rtdev`` sets ``device`` to be used as an external real-time
+ section, similar to ``logdev`` above.
+
+ noalign
+ Data allocations will not be aligned at stripe unit boundaries. This is
+ only relevant to filesystems created with non-zero data alignment
+ parameters (sunit, swidth) by mkfs.
+
+ norecovery
+ The filesystem will be mounted without running log recovery. If the
+ filesystem was not cleanly unmounted, it is likely to be inconsistent
+ when mounted in ``norecovery`` mode. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ nouuid
+ Don't check for double mounted file systems using the file system uuid.
+ This is useful to mount LVM snapshot volumes, and often used in
+ combination with ``norecovery`` for mounting read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ sunit=<value>
+ Used to specify the stripe unit for a RAID device or (in conjunction
+ with ``swidth`` below) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ The ``sunit`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid changes to ``sunit`` are increasing it by a power-of-2 multiple.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+ swidth=<value>
+ Used to specify the stripe width for a RAID device or (in conjunction
+ with ``sunit`` above) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ The ``swidth`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid swidth values are any integer multiple of a valid ``sunit`` value.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+
+ swalloc
+ Data allocations will be rounded up to stripe width boundaries when the
+ current end of file is being extended and the file size is larger than
+ the stripe width size.
+
+ wsync
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "sync" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodump" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "noatime" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nosymlinks" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodefrag" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- allocsize=size
- Sets the buffered I/O end-of-file preallocation size when
- doing delayed allocation writeout (default size is 64KiB).
- Valid values for this option are page size (typically 4KiB)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- The options enable/disable an "opportunistic" improvement to
- be made in the way inline extended attributes are stored
- on-disk. When the new form is used for the first time when
- attr2 is selected (either when setting or removing extended
- attributes) the on-disk superblock feature bit field will be
- updated to reflect this format being in use.
-
- The default behaviour is determined by the on-disk feature
- bit indicating that attr2 behaviour is active. If either
- mount option it set, then that becomes the new default used
- by the filesystem.
-
- CRC enabled filesystems always use the attr2 format, and so
- will reject the noattr2 mount option if it is set.
-
- discard
- nodiscard (*)
- Enable/disable the issuing of commands to let the block
- device reclaim space freed by the filesystem. This is
- useful for SSD devices, thinly provisioned LUNs and virtual
- machine images, but may have a performance impact.
-
- Note: It is currently recommended that you use the fstrim
- application to discard unused blocks rather than the discard
- mount option because the performance impact of this option
- is quite severe.
-
- grpid/bsdgroups
- nogrpid/sysvgroups (*)
- These options define what group ID a newly created file
- gets. When grpid is set, it takes the group ID of the
- directory in which it is created; otherwise it takes the
- fsgid of the current process, unless the directory has the
- setgid bit set, in which case it takes the gid from the
- parent directory, and also gets the setgid bit set if it is
- a directory itself.
-
- filestreams
- Make the data allocator use the filestreams allocation mode
- across the entire filesystem rather than just on directories
- configured to use it.
-
- ikeep
- noikeep (*)
- When ikeep is specified, XFS does not delete empty inode
- clusters and keeps them around on disk. When noikeep is
- specified, empty inode clusters are returned to the free
- space pool.
-
- inode32
- inode64 (*)
- When inode32 is specified, it indicates that XFS limits
- inode creation to locations which will not result in inode
- numbers with more than 32 bits of significance.
-
- When inode64 is specified, it indicates that XFS is allowed
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- inode32 is provided for backwards compatibility with older
- systems and applications, since 64 bits inode numbers might
- cause problems for some applications that cannot handle
- large inode numbers. If applications are in use which do
- not handle inode numbers bigger than 32 bits, the inode32
- option should be specified.
-
-
- largeio
- nolargeio (*)
- If "nolargeio" is specified, the optimal I/O reported in
- st_blksize by stat(2) will be as small as possible to allow
- user applications to avoid inefficient read/modify/write
- I/O. This is typically the page size of the machine, as
- this is the granularity of the page cache.
-
- If "largeio" specified, a filesystem that was created with a
- "swidth" specified will return the "swidth" value (in bytes)
- in st_blksize. If the filesystem does not have a "swidth"
- specified but does specify an "allocsize" then "allocsize"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
- range from 2-8 inclusive.
-
- The default value is 8 buffers.
-
- If the memory cost of 8 log buffers is too high on small
- systems, then it may be reduced at some cost to performance
- on metadata intensive workloads. The logbsize option below
- controls the size of each buffer and so is also relevant to
- this case.
-
- logbsize=value
- Set the size of each in-memory log buffer. The size may be
- specified in bytes, or in kilobytes with a "k" suffix.
- Valid sizes for version 1 and version 2 logs are 16384 (16k)
- and 32768 (32k). Valid sizes for version 2 logs also
- include 65536 (64k), 131072 (128k) and 262144 (256k). The
- logbsize must be an integer multiple of the log
- stripe unit configured at mkfs time.
-
- The default value for for version 1 logs is 32768, while the
- default value for version 2 logs is MAX(32768, log_sunit).
-
- logdev=device and rtdev=device
- Use an external log (metadata journal) and/or real-time device.
- An XFS filesystem has up to three parts: a data section, a log
- section, and a real-time section. The real-time section is
- optional, and the log section can be separate from the data
- section or contained within it.
-
- noalign
- Data allocations will not be aligned at stripe unit
- boundaries. This is only relevant to filesystems created
- with non-zero data alignment parameters (sunit, swidth) by
- mkfs.
-
- norecovery
- The filesystem will be mounted without running log recovery.
- If the filesystem was not cleanly unmounted, it is likely to
- be inconsistent when mounted in "norecovery" mode.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- nouuid
- Don't check for double mounted file systems using the file
- system uuid. This is useful to mount LVM snapshot volumes,
- and often used in combination with "norecovery" for mounting
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- sunit=value and swidth=value
- Used to specify the stripe unit and width for a RAID device
- or a stripe volume. "value" must be specified in 512-byte
- block units. These options are only relevant to filesystems
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters specified must be compatible
- with the existing filesystem alignment characteristics. In
- general, that means the only valid changes to sunit are
- increasing it by a power-of-2 multiple. Valid swidth values
- are any integer multiple of a valid sunit value.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
- modified, such as adding a new disk to a RAID5 lun and
- reshaping it.
-
- swalloc
- Data allocations will be rounded up to stripe width boundaries
- when the current end of file is being extended and the file
- size is larger than the stripe width size.
-
- wsync
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "sync" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodump" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "noatime" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nosymlinks" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodefrag" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH v5] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Mauro Carvalho Chehab @ 2019-06-29 16:48 UTC (permalink / raw)
To: Vandana BN
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <20190629162501.4901-1-bnvandana@gmail.com>
Em Sat, 29 Jun 2019 21:55:01 +0530
Vandana BN <bnvandana@gmail.com> escreveu:
> This patch converts new-machine.txt and register-banks.txt
> to ReST format, No content change.
> Added interfaces.rst to contain kernel-doc markups from index.rst
> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
> Added SPDX tag in index.rst
> Fixed broken reference in arch/sh/Kconfig.cpu
>
> Signed-off-by: Vandana BN <bnvandana@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> Documentation/sh/index.rst | 65 +------
> Documentation/sh/interface.rst | 59 ++++++
> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
> ...{register-banks.txt => register-banks.rst} | 8 +-
> arch/sh/Kconfig.cpu | 2 +-
> 5 files changed, 164 insertions(+), 141 deletions(-)
> create mode 100644 Documentation/sh/interface.rst
> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>
> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
> index bc8db7ba894a..fec3c405b6b9 100644
> --- a/Documentation/sh/index.rst
> +++ b/Documentation/sh/index.rst
> @@ -1,59 +1,14 @@
> -=======================
> -SuperH Interfaces Guide
> -=======================
> +.. SPDX-License-Identifier: GPL-2.0
>
> -:Author: Paul Mundt
> -
> -Memory Management
> -=================
> -
> -SH-4
> -----
> -
> -Store Queue API
> -~~~~~~~~~~~~~~~
> -
> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> - :export:
> -
> -SH-5
> -----
> -
> -TLB Interfaces
> -~~~~~~~~~~~~~~
> -
> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> - :internal:
> -
> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> - :internal:
> +====================
> +SuperH Documentation
> +====================
>
> -Machine Specific Interfaces
> -===========================
> -
> -mach-dreamcast
> ---------------
> -
> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> - :internal:
> -
> -mach-x3proto
> -------------
> -
> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> - :export:
> -
> -Busses
> -======
> -
> -SuperHyway
> -----------
> -
> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> - :export:
> +:Author: Paul Mundt
>
> -Maple
> ------
> +.. toctree::
> + :maxdepth: 2
>
> -.. kernel-doc:: drivers/sh/maple/maple.c
> - :export:
> + interface
> + new-machine
> + register-banks
> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
> new file mode 100644
> index 000000000000..bc8db7ba894a
> --- /dev/null
> +++ b/Documentation/sh/interface.rst
> @@ -0,0 +1,59 @@
> +=======================
> +SuperH Interfaces Guide
> +=======================
> +
> +:Author: Paul Mundt
> +
> +Memory Management
> +=================
> +
> +SH-4
> +----
> +
> +Store Queue API
> +~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> + :export:
> +
> +SH-5
> +----
> +
> +TLB Interfaces
> +~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> + :internal:
> +
> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> + :internal:
> +
> +Machine Specific Interfaces
> +===========================
> +
> +mach-dreamcast
> +--------------
> +
> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> + :internal:
> +
> +mach-x3proto
> +------------
> +
> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> + :export:
> +
> +Busses
> +======
> +
> +SuperHyway
> +----------
> +
> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> + :export:
> +
> +Maple
> +-----
> +
> +.. kernel-doc:: drivers/sh/maple/maple.c
> + :export:
> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
> similarity index 79%
> rename from Documentation/sh/new-machine.txt
> rename to Documentation/sh/new-machine.rst
> index e0961a66130b..b16c33342642 100644
> --- a/Documentation/sh/new-machine.txt
> +++ b/Documentation/sh/new-machine.rst
> @@ -1,8 +1,8 @@
> +================================
> +Adding a new board to LinuxSH
> +================================
>
> - Adding a new board to LinuxSH
> - ================================
> -
> - Paul Mundt <lethal@linux-sh.org>
> +Paul Mundt <lethal@linux-sh.org>
>
> This document attempts to outline what steps are necessary to add support
> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
> companion chip type, and CPU type. Looking at a tree view of this directory
> hierarchy looks like the following:
>
> -Board-specific code:
> -
> -.
> -|-- arch
> -| `-- sh
> -| `-- boards
> -| |-- adx
> -| | `-- board-specific files
> -| |-- bigsur
> -| | `-- board-specific files
> -| |
> -| ... more boards here ...
> -|
> -`-- include
> - `-- asm-sh
> - |-- adx
> - | `-- board-specific headers
> - |-- bigsur
> - | `-- board-specific headers
> - |
> - .. more boards here ...
> -
> -Next, for companion chips:
> -.
> -`-- arch
> - `-- sh
> - `-- cchips
> - `-- hd6446x
> - `-- hd64461
> - `-- cchip-specific files
> +Board-specific code::
> +
> + .
> + |-- arch
> + | `-- sh
> + | `-- boards
> + | |-- adx
> + | | `-- board-specific files
> + | |-- bigsur
> + | | `-- board-specific files
> + | |
> + | ... more boards here ...
> + |
> + `-- include
> + `-- asm-sh
> + |-- adx
> + | `-- board-specific headers
> + |-- bigsur
> + | `-- board-specific headers
> + |
> + .. more boards here ...
> +
> +Next, for companion chips::
> +
> + .
> + `-- arch
> + `-- sh
> + `-- cchips
> + `-- hd6446x
> + `-- hd64461
> + `-- cchip-specific files
>
> ... and so on. Headers for the companion chips are treated the same way as
> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
> hd64461-specific headers.
>
> -Finally, CPU family support is also abstracted:
> -.
> -|-- arch
> -| `-- sh
> -| |-- kernel
> -| | `-- cpu
> -| | |-- sh2
> -| | | `-- SH-2 generic files
> -| | |-- sh3
> -| | | `-- SH-3 generic files
> -| | `-- sh4
> -| | `-- SH-4 generic files
> -| `-- mm
> -| `-- This is also broken out per CPU family, so each family can
> -| have their own set of cache/tlb functions.
> -|
> -`-- include
> - `-- asm-sh
> - |-- cpu-sh2
> - | `-- SH-2 specific headers
> - |-- cpu-sh3
> - | `-- SH-3 specific headers
> - `-- cpu-sh4
> - `-- SH-4 specific headers
> +Finally, CPU family support is also abstracted::
> +
> + .
> + |-- arch
> + | `-- sh
> + | |-- kernel
> + | | `-- cpu
> + | | |-- sh2
> + | | | `-- SH-2 generic files
> + | | |-- sh3
> + | | | `-- SH-3 generic files
> + | | `-- sh4
> + | | `-- SH-4 generic files
> + | `-- mm
> + | `-- This is also broken out per CPU family, so each family can
> + | have their own set of cache/tlb functions.
> + |
> + `-- include
> + `-- asm-sh
> + |-- cpu-sh2
> + | `-- SH-2 specific headers
> + |-- cpu-sh3
> + | `-- SH-3 specific headers
> + `-- cpu-sh4
> + `-- SH-4 specific headers
>
> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
> need to be dealt with by the CPU family specific code.
> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
> get_system_type() and platform_setup(). For our imaginary board, this
> might look something like:
>
> -/*
> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> - */
> -#include <linux/init.h>
> +.. code-block:: c
> +
> + /*
> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> + */
> + #include <linux/init.h>
>
> -const char *get_system_type(void)
> -{
> - return "FooTech Vaporboard";
> -}
> + const char *get_system_type(void)
> + {
> + return "FooTech Vaporboard";
> + }
>
> -int __init platform_setup(void)
> -{
> + int __init platform_setup(void)
> + {
> /*
> * If our hardware actually existed, we would do real
> * setup here. Though it's also sane to leave this empty
> @@ -136,7 +140,8 @@ int __init platform_setup(void)
> /* And whatever else ... */
>
> return 0;
> -}
> + }
> +
>
> Our new imaginary board will also have to tie into the machvec in order for it
> to be of any use.
> @@ -172,16 +177,17 @@ sufficient.
> vector.
>
> Note that these prototypes are generated automatically by setting
> - __IO_PREFIX to something sensible. A typical example would be:
> + __IO_PREFIX to something sensible. A typical example would be::
>
> #define __IO_PREFIX vapor
> #include <asm/io_generic.h>
>
> +
> somewhere in the board-specific header. Any boards being ported that still
> have a legacy io.h should remove it entirely and switch to the new model.
>
> - Add machine vector definitions to the board's setup.c. At a bare minimum,
> - this must be defined as something like:
> + this must be defined as something like::
>
> struct sh_machine_vector mv_vapor __initmv = {
> .mv_name = "vapor",
> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
> require the proper entry here and there in order to get things done.
>
> The first thing to do is to add an entry to arch/sh/Kconfig, under the
> -"System type" menu:
> +"System type" menu::
>
> -config SH_VAPOR
> - bool "Vapor"
> - help
> + config SH_VAPOR
> + bool "Vapor"
> + help
> select Vapor if configuring for a FooTech Vaporboard.
>
> next, this has to be added into arch/sh/Makefile. All boards require a
> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
> implicit checks for your board if you need this somewhere throughout the
> common code, such as:
>
> +::
> +
> /* Make sure we're on the FooTech Vaporboard */
> if (!mach_is_vapor())
> return -ENODEV;
> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
> Looking at the 'make help' output, you should now see something like:
>
> Architecture specific targets (sh):
> - zImage - Compressed kernel image (arch/sh/boot/zImage)
> - adx_defconfig - Build for adx
> - cqreek_defconfig - Build for cqreek
> - dreamcast_defconfig - Build for dreamcast
> -...
> - vapor_defconfig - Build for vapor
> +
> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
> + - adx_defconfig - Build for adx
> + - cqreek_defconfig - Build for cqreek
> + - dreamcast_defconfig - Build for dreamcast
> + - ...
> + - vapor_defconfig - Build for vapor
>
> which then allows you to do:
>
> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
> similarity index 90%
> rename from Documentation/sh/register-banks.txt
> rename to Documentation/sh/register-banks.rst
> index a6719f2f6594..acccfaf80355 100644
> --- a/Documentation/sh/register-banks.txt
> +++ b/Documentation/sh/register-banks.rst
> @@ -1,8 +1,9 @@
> - Notes on register bank usage in the kernel
> - ==========================================
> +==========================================
> +Notes on register bank usage in the kernel
> +==========================================
>
> Introduction
> -------------
> +============
>
> The SH-3 and SH-4 CPU families traditionally include a single partial register
> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
> - The SR.IMASK interrupt handler makes use of this to set the
> interrupt priority level (used by local_irq_enable())
> - r7_bank (current)
> -
> diff --git a/arch/sh/Kconfig.cpu b/arch/sh/Kconfig.cpu
> index 4a4edc7e03d4..07ad7597cbe7 100644
> --- a/arch/sh/Kconfig.cpu
> +++ b/arch/sh/Kconfig.cpu
> @@ -94,7 +94,7 @@ config CPU_HAS_SR_RB
> that are lacking this bit must have another method in place for
> accomplishing what is taken care of by the banked registers.
>
> - See <file:Documentation/sh/register-banks.txt> for further
> + See <file:Documentation/sh/register-banks.rst> for further
> information on SR.RB and register banking in the kernel in general.
>
> config CPU_HAS_PTEAEX
> --
> 2.17.1
>
Thanks,
Mauro
^ permalink raw reply
* [PATCH v5] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Vandana BN @ 2019-06-29 16:25 UTC (permalink / raw)
To: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, mchehab
Cc: skhan, gregkh, linux-kernel-mentees, Vandana BN
In-Reply-To: <20190627063347.11137-1-bnvandana@gmail.com>
This patch converts new-machine.txt and register-banks.txt
to ReST format, No content change.
Added interfaces.rst to contain kernel-doc markups from index.rst
Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
Added SPDX tag in index.rst
Fixed broken reference in arch/sh/Kconfig.cpu
Signed-off-by: Vandana BN <bnvandana@gmail.com>
---
Documentation/sh/index.rst | 65 +------
Documentation/sh/interface.rst | 59 ++++++
.../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
...{register-banks.txt => register-banks.rst} | 8 +-
arch/sh/Kconfig.cpu | 2 +-
5 files changed, 164 insertions(+), 141 deletions(-)
create mode 100644 Documentation/sh/interface.rst
rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
index bc8db7ba894a..fec3c405b6b9 100644
--- a/Documentation/sh/index.rst
+++ b/Documentation/sh/index.rst
@@ -1,59 +1,14 @@
-=======================
-SuperH Interfaces Guide
-=======================
+.. SPDX-License-Identifier: GPL-2.0
-:Author: Paul Mundt
-
-Memory Management
-=================
-
-SH-4
-----
-
-Store Queue API
-~~~~~~~~~~~~~~~
-
-.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
- :export:
-
-SH-5
-----
-
-TLB Interfaces
-~~~~~~~~~~~~~~
-
-.. kernel-doc:: arch/sh/mm/tlb-sh5.c
- :internal:
-
-.. kernel-doc:: arch/sh/include/asm/tlb_64.h
- :internal:
+====================
+SuperH Documentation
+====================
-Machine Specific Interfaces
-===========================
-
-mach-dreamcast
---------------
-
-.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
- :internal:
-
-mach-x3proto
-------------
-
-.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
- :export:
-
-Busses
-======
-
-SuperHyway
-----------
-
-.. kernel-doc:: drivers/sh/superhyway/superhyway.c
- :export:
+:Author: Paul Mundt
-Maple
------
+.. toctree::
+ :maxdepth: 2
-.. kernel-doc:: drivers/sh/maple/maple.c
- :export:
+ interface
+ new-machine
+ register-banks
diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
new file mode 100644
index 000000000000..bc8db7ba894a
--- /dev/null
+++ b/Documentation/sh/interface.rst
@@ -0,0 +1,59 @@
+=======================
+SuperH Interfaces Guide
+=======================
+
+:Author: Paul Mundt
+
+Memory Management
+=================
+
+SH-4
+----
+
+Store Queue API
+~~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+ :export:
+
+SH-5
+----
+
+TLB Interfaces
+~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/mm/tlb-sh5.c
+ :internal:
+
+.. kernel-doc:: arch/sh/include/asm/tlb_64.h
+ :internal:
+
+Machine Specific Interfaces
+===========================
+
+mach-dreamcast
+--------------
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+ :internal:
+
+mach-x3proto
+------------
+
+.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
+ :export:
+
+Busses
+======
+
+SuperHyway
+----------
+
+.. kernel-doc:: drivers/sh/superhyway/superhyway.c
+ :export:
+
+Maple
+-----
+
+.. kernel-doc:: drivers/sh/maple/maple.c
+ :export:
diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
similarity index 79%
rename from Documentation/sh/new-machine.txt
rename to Documentation/sh/new-machine.rst
index e0961a66130b..b16c33342642 100644
--- a/Documentation/sh/new-machine.txt
+++ b/Documentation/sh/new-machine.rst
@@ -1,8 +1,8 @@
+================================
+Adding a new board to LinuxSH
+================================
- Adding a new board to LinuxSH
- ================================
-
- Paul Mundt <lethal@linux-sh.org>
+Paul Mundt <lethal@linux-sh.org>
This document attempts to outline what steps are necessary to add support
for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
@@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
companion chip type, and CPU type. Looking at a tree view of this directory
hierarchy looks like the following:
-Board-specific code:
-
-.
-|-- arch
-| `-- sh
-| `-- boards
-| |-- adx
-| | `-- board-specific files
-| |-- bigsur
-| | `-- board-specific files
-| |
-| ... more boards here ...
-|
-`-- include
- `-- asm-sh
- |-- adx
- | `-- board-specific headers
- |-- bigsur
- | `-- board-specific headers
- |
- .. more boards here ...
-
-Next, for companion chips:
-.
-`-- arch
- `-- sh
- `-- cchips
- `-- hd6446x
- `-- hd64461
- `-- cchip-specific files
+Board-specific code::
+
+ .
+ |-- arch
+ | `-- sh
+ | `-- boards
+ | |-- adx
+ | | `-- board-specific files
+ | |-- bigsur
+ | | `-- board-specific files
+ | |
+ | ... more boards here ...
+ |
+ `-- include
+ `-- asm-sh
+ |-- adx
+ | `-- board-specific headers
+ |-- bigsur
+ | `-- board-specific headers
+ |
+ .. more boards here ...
+
+Next, for companion chips::
+
+ .
+ `-- arch
+ `-- sh
+ `-- cchips
+ `-- hd6446x
+ `-- hd64461
+ `-- cchip-specific files
... and so on. Headers for the companion chips are treated the same way as
board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
hd64461-specific headers.
-Finally, CPU family support is also abstracted:
-.
-|-- arch
-| `-- sh
-| |-- kernel
-| | `-- cpu
-| | |-- sh2
-| | | `-- SH-2 generic files
-| | |-- sh3
-| | | `-- SH-3 generic files
-| | `-- sh4
-| | `-- SH-4 generic files
-| `-- mm
-| `-- This is also broken out per CPU family, so each family can
-| have their own set of cache/tlb functions.
-|
-`-- include
- `-- asm-sh
- |-- cpu-sh2
- | `-- SH-2 specific headers
- |-- cpu-sh3
- | `-- SH-3 specific headers
- `-- cpu-sh4
- `-- SH-4 specific headers
+Finally, CPU family support is also abstracted::
+
+ .
+ |-- arch
+ | `-- sh
+ | |-- kernel
+ | | `-- cpu
+ | | |-- sh2
+ | | | `-- SH-2 generic files
+ | | |-- sh3
+ | | | `-- SH-3 generic files
+ | | `-- sh4
+ | | `-- SH-4 generic files
+ | `-- mm
+ | `-- This is also broken out per CPU family, so each family can
+ | have their own set of cache/tlb functions.
+ |
+ `-- include
+ `-- asm-sh
+ |-- cpu-sh2
+ | `-- SH-2 specific headers
+ |-- cpu-sh3
+ | `-- SH-3 specific headers
+ `-- cpu-sh4
+ `-- SH-4 specific headers
It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
need to be dealt with by the CPU family specific code.
@@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
get_system_type() and platform_setup(). For our imaginary board, this
might look something like:
-/*
- * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
- */
-#include <linux/init.h>
+.. code-block:: c
+
+ /*
+ * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
+ */
+ #include <linux/init.h>
-const char *get_system_type(void)
-{
- return "FooTech Vaporboard";
-}
+ const char *get_system_type(void)
+ {
+ return "FooTech Vaporboard";
+ }
-int __init platform_setup(void)
-{
+ int __init platform_setup(void)
+ {
/*
* If our hardware actually existed, we would do real
* setup here. Though it's also sane to leave this empty
@@ -136,7 +140,8 @@ int __init platform_setup(void)
/* And whatever else ... */
return 0;
-}
+ }
+
Our new imaginary board will also have to tie into the machvec in order for it
to be of any use.
@@ -172,16 +177,17 @@ sufficient.
vector.
Note that these prototypes are generated automatically by setting
- __IO_PREFIX to something sensible. A typical example would be:
+ __IO_PREFIX to something sensible. A typical example would be::
#define __IO_PREFIX vapor
#include <asm/io_generic.h>
+
somewhere in the board-specific header. Any boards being ported that still
have a legacy io.h should remove it entirely and switch to the new model.
- Add machine vector definitions to the board's setup.c. At a bare minimum,
- this must be defined as something like:
+ this must be defined as something like::
struct sh_machine_vector mv_vapor __initmv = {
.mv_name = "vapor",
@@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
require the proper entry here and there in order to get things done.
The first thing to do is to add an entry to arch/sh/Kconfig, under the
-"System type" menu:
+"System type" menu::
-config SH_VAPOR
- bool "Vapor"
- help
+ config SH_VAPOR
+ bool "Vapor"
+ help
select Vapor if configuring for a FooTech Vaporboard.
next, this has to be added into arch/sh/Makefile. All boards require a
@@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
implicit checks for your board if you need this somewhere throughout the
common code, such as:
+::
+
/* Make sure we're on the FooTech Vaporboard */
if (!mach_is_vapor())
return -ENODEV;
@@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
Looking at the 'make help' output, you should now see something like:
Architecture specific targets (sh):
- zImage - Compressed kernel image (arch/sh/boot/zImage)
- adx_defconfig - Build for adx
- cqreek_defconfig - Build for cqreek
- dreamcast_defconfig - Build for dreamcast
-...
- vapor_defconfig - Build for vapor
+
+ - zImage - Compressed kernel image (arch/sh/boot/zImage)
+ - adx_defconfig - Build for adx
+ - cqreek_defconfig - Build for cqreek
+ - dreamcast_defconfig - Build for dreamcast
+ - ...
+ - vapor_defconfig - Build for vapor
which then allows you to do:
diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
similarity index 90%
rename from Documentation/sh/register-banks.txt
rename to Documentation/sh/register-banks.rst
index a6719f2f6594..acccfaf80355 100644
--- a/Documentation/sh/register-banks.txt
+++ b/Documentation/sh/register-banks.rst
@@ -1,8 +1,9 @@
- Notes on register bank usage in the kernel
- ==========================================
+==========================================
+Notes on register bank usage in the kernel
+==========================================
Introduction
-------------
+============
The SH-3 and SH-4 CPU families traditionally include a single partial register
bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
@@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
- The SR.IMASK interrupt handler makes use of this to set the
interrupt priority level (used by local_irq_enable())
- r7_bank (current)
-
diff --git a/arch/sh/Kconfig.cpu b/arch/sh/Kconfig.cpu
index 4a4edc7e03d4..07ad7597cbe7 100644
--- a/arch/sh/Kconfig.cpu
+++ b/arch/sh/Kconfig.cpu
@@ -94,7 +94,7 @@ config CPU_HAS_SR_RB
that are lacking this bit must have another method in place for
accomplishing what is taken care of by the banked registers.
- See <file:Documentation/sh/register-banks.txt> for further
+ See <file:Documentation/sh/register-banks.rst> for further
information on SR.RB and register banking in the kernel in general.
config CPU_HAS_PTEAEX
--
2.17.1
^ permalink raw reply related
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Vandana BN @ 2019-06-29 16:19 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <20190629130242.413b4672@coco.lan>
On 29/06/19 9:32 PM, Mauro Carvalho Chehab wrote:
> Em Sat, 29 Jun 2019 21:26:29 +0530
> Vandana BN <bnvandana@gmail.com> escreveu:
>
>> On 29/06/19 8:20 PM, Mauro Carvalho Chehab wrote:
>>> Em Sat, 29 Jun 2019 20:02:45 +0530
>>> Vandana BN <bnvandana@gmail.com> escreveu:
>>>
>>>> This patch converts new-machine.txt and register-banks.txt
>>>> to ReST format, No content change.
>>>> Added interfaces.rst to contain kernel-doc markups from index.rst
>>>> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
>>>> Added SPDX tag in index.rst
>>>>
>>>> Signed-off-by: Vandana BN <bnvandana@gmail.com>
>>> Looks good to me. Just a final thing to do.
>>>
>>> Be sure to run:
>>>
>>> ./scripts/documentation-file-ref-check
>>>
>>> in order to check that you're not breaking any references to the file.
>>> If it breaks, please adjust the reference to reflect the file
>>> rename.
>>>
>>> After fixing the broken reference, feel free do add:
>>>
>>> Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>> Thanks Mauro,
>>
>> i don't not see any broken references.
> Then maybe the script is broken. A simple grep here (linux-next) shows
> one such reference:
>
> git grep Documentation/sh/
> MAINTAINERS:F: Documentation/sh/
> arch/sh/Kconfig.cpu: See <file:Documentation/sh/register-banks.txt> for further
>
Oh ok, yes i see it now..
Will fix and send a patch.
>>>> ---
>>>> Documentation/sh/index.rst | 65 +------
>>>> Documentation/sh/interface.rst | 59 ++++++
>>>> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
>>>> ...{register-banks.txt => register-banks.rst} | 8 +-
>>>> 4 files changed, 163 insertions(+), 140 deletions(-)
>>>> create mode 100644 Documentation/sh/interface.rst
>>>> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
>>>> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>>>>
>>>> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
>>>> index bc8db7ba894a..fec3c405b6b9 100644
>>>> --- a/Documentation/sh/index.rst
>>>> +++ b/Documentation/sh/index.rst
>>>> @@ -1,59 +1,14 @@
>>>> -=======================
>>>> -SuperH Interfaces Guide
>>>> -=======================
>>>> +.. SPDX-License-Identifier: GPL-2.0
>>>>
>>>> -:Author: Paul Mundt
>>>> -
>>>> -Memory Management
>>>> -=================
>>>> -
>>>> -SH-4
>>>> -----
>>>> -
>>>> -Store Queue API
>>>> -~~~~~~~~~~~~~~~
>>>> -
>>>> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>>>> - :export:
>>>> -
>>>> -SH-5
>>>> -----
>>>> -
>>>> -TLB Interfaces
>>>> -~~~~~~~~~~~~~~
>>>> -
>>>> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>>>> - :internal:
>>>> -
>>>> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>>>> - :internal:
>>>> +====================
>>>> +SuperH Documentation
>>>> +====================
>>>>
>>>> -Machine Specific Interfaces
>>>> -===========================
>>>> -
>>>> -mach-dreamcast
>>>> ---------------
>>>> -
>>>> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>>>> - :internal:
>>>> -
>>>> -mach-x3proto
>>>> -------------
>>>> -
>>>> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>>>> - :export:
>>>> -
>>>> -Busses
>>>> -======
>>>> -
>>>> -SuperHyway
>>>> -----------
>>>> -
>>>> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>>>> - :export:
>>>> +:Author: Paul Mundt
>>>>
>>>> -Maple
>>>> ------
>>>> +.. toctree::
>>>> + :maxdepth: 2
>>>>
>>>> -.. kernel-doc:: drivers/sh/maple/maple.c
>>>> - :export:
>>>> + interface
>>>> + new-machine
>>>> + register-banks
>>>> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
>>>> new file mode 100644
>>>> index 000000000000..bc8db7ba894a
>>>> --- /dev/null
>>>> +++ b/Documentation/sh/interface.rst
>>>> @@ -0,0 +1,59 @@
>>>> +=======================
>>>> +SuperH Interfaces Guide
>>>> +=======================
>>>> +
>>>> +:Author: Paul Mundt
>>>> +
>>>> +Memory Management
>>>> +=================
>>>> +
>>>> +SH-4
>>>> +----
>>>> +
>>>> +Store Queue API
>>>> +~~~~~~~~~~~~~~~
>>>> +
>>>> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>>>> + :export:
>>>> +
>>>> +SH-5
>>>> +----
>>>> +
>>>> +TLB Interfaces
>>>> +~~~~~~~~~~~~~~
>>>> +
>>>> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>>>> + :internal:
>>>> +
>>>> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>>>> + :internal:
>>>> +
>>>> +Machine Specific Interfaces
>>>> +===========================
>>>> +
>>>> +mach-dreamcast
>>>> +--------------
>>>> +
>>>> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>>>> + :internal:
>>>> +
>>>> +mach-x3proto
>>>> +------------
>>>> +
>>>> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>>>> + :export:
>>>> +
>>>> +Busses
>>>> +======
>>>> +
>>>> +SuperHyway
>>>> +----------
>>>> +
>>>> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>>>> + :export:
>>>> +
>>>> +Maple
>>>> +-----
>>>> +
>>>> +.. kernel-doc:: drivers/sh/maple/maple.c
>>>> + :export:
>>>> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
>>>> similarity index 79%
>>>> rename from Documentation/sh/new-machine.txt
>>>> rename to Documentation/sh/new-machine.rst
>>>> index e0961a66130b..b16c33342642 100644
>>>> --- a/Documentation/sh/new-machine.txt
>>>> +++ b/Documentation/sh/new-machine.rst
>>>> @@ -1,8 +1,8 @@
>>>> +================================
>>>> +Adding a new board to LinuxSH
>>>> +================================
>>>>
>>>> - Adding a new board to LinuxSH
>>>> - ================================
>>>> -
>>>> - Paul Mundt <lethal@linux-sh.org>
>>>> +Paul Mundt <lethal@linux-sh.org>
>>>>
>>>> This document attempts to outline what steps are necessary to add support
>>>> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
>>>> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
>>>> companion chip type, and CPU type. Looking at a tree view of this directory
>>>> hierarchy looks like the following:
>>>>
>>>> -Board-specific code:
>>>> -
>>>> -.
>>>> -|-- arch
>>>> -| `-- sh
>>>> -| `-- boards
>>>> -| |-- adx
>>>> -| | `-- board-specific files
>>>> -| |-- bigsur
>>>> -| | `-- board-specific files
>>>> -| |
>>>> -| ... more boards here ...
>>>> -|
>>>> -`-- include
>>>> - `-- asm-sh
>>>> - |-- adx
>>>> - | `-- board-specific headers
>>>> - |-- bigsur
>>>> - | `-- board-specific headers
>>>> - |
>>>> - .. more boards here ...
>>>> -
>>>> -Next, for companion chips:
>>>> -.
>>>> -`-- arch
>>>> - `-- sh
>>>> - `-- cchips
>>>> - `-- hd6446x
>>>> - `-- hd64461
>>>> - `-- cchip-specific files
>>>> +Board-specific code::
>>>> +
>>>> + .
>>>> + |-- arch
>>>> + | `-- sh
>>>> + | `-- boards
>>>> + | |-- adx
>>>> + | | `-- board-specific files
>>>> + | |-- bigsur
>>>> + | | `-- board-specific files
>>>> + | |
>>>> + | ... more boards here ...
>>>> + |
>>>> + `-- include
>>>> + `-- asm-sh
>>>> + |-- adx
>>>> + | `-- board-specific headers
>>>> + |-- bigsur
>>>> + | `-- board-specific headers
>>>> + |
>>>> + .. more boards here ...
>>>> +
>>>> +Next, for companion chips::
>>>> +
>>>> + .
>>>> + `-- arch
>>>> + `-- sh
>>>> + `-- cchips
>>>> + `-- hd6446x
>>>> + `-- hd64461
>>>> + `-- cchip-specific files
>>>>
>>>> ... and so on. Headers for the companion chips are treated the same way as
>>>> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
>>>> hd64461-specific headers.
>>>>
>>>> -Finally, CPU family support is also abstracted:
>>>> -.
>>>> -|-- arch
>>>> -| `-- sh
>>>> -| |-- kernel
>>>> -| | `-- cpu
>>>> -| | |-- sh2
>>>> -| | | `-- SH-2 generic files
>>>> -| | |-- sh3
>>>> -| | | `-- SH-3 generic files
>>>> -| | `-- sh4
>>>> -| | `-- SH-4 generic files
>>>> -| `-- mm
>>>> -| `-- This is also broken out per CPU family, so each family can
>>>> -| have their own set of cache/tlb functions.
>>>> -|
>>>> -`-- include
>>>> - `-- asm-sh
>>>> - |-- cpu-sh2
>>>> - | `-- SH-2 specific headers
>>>> - |-- cpu-sh3
>>>> - | `-- SH-3 specific headers
>>>> - `-- cpu-sh4
>>>> - `-- SH-4 specific headers
>>>> +Finally, CPU family support is also abstracted::
>>>> +
>>>> + .
>>>> + |-- arch
>>>> + | `-- sh
>>>> + | |-- kernel
>>>> + | | `-- cpu
>>>> + | | |-- sh2
>>>> + | | | `-- SH-2 generic files
>>>> + | | |-- sh3
>>>> + | | | `-- SH-3 generic files
>>>> + | | `-- sh4
>>>> + | | `-- SH-4 generic files
>>>> + | `-- mm
>>>> + | `-- This is also broken out per CPU family, so each family can
>>>> + | have their own set of cache/tlb functions.
>>>> + |
>>>> + `-- include
>>>> + `-- asm-sh
>>>> + |-- cpu-sh2
>>>> + | `-- SH-2 specific headers
>>>> + |-- cpu-sh3
>>>> + | `-- SH-3 specific headers
>>>> + `-- cpu-sh4
>>>> + `-- SH-4 specific headers
>>>>
>>>> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
>>>> need to be dealt with by the CPU family specific code.
>>>> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
>>>> get_system_type() and platform_setup(). For our imaginary board, this
>>>> might look something like:
>>>>
>>>> -/*
>>>> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>>>> - */
>>>> -#include <linux/init.h>
>>>> +.. code-block:: c
>>>> +
>>>> + /*
>>>> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>>>> + */
>>>> + #include <linux/init.h>
>>>>
>>>> -const char *get_system_type(void)
>>>> -{
>>>> - return "FooTech Vaporboard";
>>>> -}
>>>> + const char *get_system_type(void)
>>>> + {
>>>> + return "FooTech Vaporboard";
>>>> + }
>>>>
>>>> -int __init platform_setup(void)
>>>> -{
>>>> + int __init platform_setup(void)
>>>> + {
>>>> /*
>>>> * If our hardware actually existed, we would do real
>>>> * setup here. Though it's also sane to leave this empty
>>>> @@ -136,7 +140,8 @@ int __init platform_setup(void)
>>>> /* And whatever else ... */
>>>>
>>>> return 0;
>>>> -}
>>>> + }
>>>> +
>>>>
>>>> Our new imaginary board will also have to tie into the machvec in order for it
>>>> to be of any use.
>>>> @@ -172,16 +177,17 @@ sufficient.
>>>> vector.
>>>>
>>>> Note that these prototypes are generated automatically by setting
>>>> - __IO_PREFIX to something sensible. A typical example would be:
>>>> + __IO_PREFIX to something sensible. A typical example would be::
>>>>
>>>> #define __IO_PREFIX vapor
>>>> #include <asm/io_generic.h>
>>>>
>>>> +
>>>> somewhere in the board-specific header. Any boards being ported that still
>>>> have a legacy io.h should remove it entirely and switch to the new model.
>>>>
>>>> - Add machine vector definitions to the board's setup.c. At a bare minimum,
>>>> - this must be defined as something like:
>>>> + this must be defined as something like::
>>>>
>>>> struct sh_machine_vector mv_vapor __initmv = {
>>>> .mv_name = "vapor",
>>>> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
>>>> require the proper entry here and there in order to get things done.
>>>>
>>>> The first thing to do is to add an entry to arch/sh/Kconfig, under the
>>>> -"System type" menu:
>>>> +"System type" menu::
>>>>
>>>> -config SH_VAPOR
>>>> - bool "Vapor"
>>>> - help
>>>> + config SH_VAPOR
>>>> + bool "Vapor"
>>>> + help
>>>> select Vapor if configuring for a FooTech Vaporboard.
>>>>
>>>> next, this has to be added into arch/sh/Makefile. All boards require a
>>>> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
>>>> implicit checks for your board if you need this somewhere throughout the
>>>> common code, such as:
>>>>
>>>> +::
>>>> +
>>>> /* Make sure we're on the FooTech Vaporboard */
>>>> if (!mach_is_vapor())
>>>> return -ENODEV;
>>>> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
>>>> Looking at the 'make help' output, you should now see something like:
>>>>
>>>> Architecture specific targets (sh):
>>>> - zImage - Compressed kernel image (arch/sh/boot/zImage)
>>>> - adx_defconfig - Build for adx
>>>> - cqreek_defconfig - Build for cqreek
>>>> - dreamcast_defconfig - Build for dreamcast
>>>> -...
>>>> - vapor_defconfig - Build for vapor
>>>> +
>>>> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
>>>> + - adx_defconfig - Build for adx
>>>> + - cqreek_defconfig - Build for cqreek
>>>> + - dreamcast_defconfig - Build for dreamcast
>>>> + - ...
>>>> + - vapor_defconfig - Build for vapor
>>>>
>>>> which then allows you to do:
>>>>
>>>> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
>>>> similarity index 90%
>>>> rename from Documentation/sh/register-banks.txt
>>>> rename to Documentation/sh/register-banks.rst
>>>> index a6719f2f6594..acccfaf80355 100644
>>>> --- a/Documentation/sh/register-banks.txt
>>>> +++ b/Documentation/sh/register-banks.rst
>>>> @@ -1,8 +1,9 @@
>>>> - Notes on register bank usage in the kernel
>>>> - ==========================================
>>>> +==========================================
>>>> +Notes on register bank usage in the kernel
>>>> +==========================================
>>>>
>>>> Introduction
>>>> -------------
>>>> +============
>>>>
>>>> The SH-3 and SH-4 CPU families traditionally include a single partial register
>>>> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
>>>> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
>>>> - The SR.IMASK interrupt handler makes use of this to set the
>>>> interrupt priority level (used by local_irq_enable())
>>>> - r7_bank (current)
>>>> -
>>>> --
>>>> 2.17.1
>>>>
>>>
>>> Thanks,
>>> Mauro
>> Regards,
>>
>> Vandana.
>>
>
>
> Thanks,
> Mauro
Thanks,
Vandana.
^ permalink raw reply
* Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands
From: Andy Shevchenko @ 2019-06-29 16:03 UTC (permalink / raw)
To: Srinivas Pandruvada
Cc: Darren Hart, Andy Shevchenko, Andriy Shevchenko, Jonathan Corbet,
Rafael J. Wysocki, Alan Cox, Len Brown, prarit, darcari,
Linux Documentation List, Linux Kernel Mailing List,
Platform Driver
In-Reply-To: <1c4238f7d18d316df82d3ba1618fecdcf014f98a.camel@linux.intel.com>
On Sat, Jun 29, 2019 at 5:53 PM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
> On Sat, 2019-06-29 at 17:31 +0300, Andy Shevchenko wrote:
> > On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
> > <srinivas.pandruvada@linux.intel.com> wrote:
> > I need an Ack from tools/power maintainer(s) for this.
> > Also see below.
> MAINTAINER file doesn't call for any special name in this folder.
And this tells me perhaps this driver needs a MAINTAINER record?
> $./scripts/get_maintainer.pl 0010-tools-power-x86-A-tool-to-validate-
> Intel-Speed-Selec.patch
> Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:31/31=100%,added_
> lines:231/231=100%,added_lines:1607/1607=100%,added_lines:721/721=100%,
> added_lines:479/479=100%)
> linux-kernel@vger.kernel.org (open list)
>
> Len and Rafael can you ACK this tool patch?
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Mauro Carvalho Chehab @ 2019-06-29 16:02 UTC (permalink / raw)
To: Vandana BN
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <4549aead-e916-a889-6c18-f695086fb72c@gmail.com>
Em Sat, 29 Jun 2019 21:26:29 +0530
Vandana BN <bnvandana@gmail.com> escreveu:
> On 29/06/19 8:20 PM, Mauro Carvalho Chehab wrote:
> > Em Sat, 29 Jun 2019 20:02:45 +0530
> > Vandana BN <bnvandana@gmail.com> escreveu:
> >
> >> This patch converts new-machine.txt and register-banks.txt
> >> to ReST format, No content change.
> >> Added interfaces.rst to contain kernel-doc markups from index.rst
> >> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
> >> Added SPDX tag in index.rst
> >>
> >> Signed-off-by: Vandana BN <bnvandana@gmail.com>
> > Looks good to me. Just a final thing to do.
> >
> > Be sure to run:
> >
> > ./scripts/documentation-file-ref-check
> >
> > in order to check that you're not breaking any references to the file.
> > If it breaks, please adjust the reference to reflect the file
> > rename.
> >
> > After fixing the broken reference, feel free do add:
> >
> > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
>
> Thanks Mauro,
>
> i don't not see any broken references.
Then maybe the script is broken. A simple grep here (linux-next) shows
one such reference:
git grep Documentation/sh/
MAINTAINERS:F: Documentation/sh/
arch/sh/Kconfig.cpu: See <file:Documentation/sh/register-banks.txt> for further
>
> >> ---
> >> Documentation/sh/index.rst | 65 +------
> >> Documentation/sh/interface.rst | 59 ++++++
> >> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
> >> ...{register-banks.txt => register-banks.rst} | 8 +-
> >> 4 files changed, 163 insertions(+), 140 deletions(-)
> >> create mode 100644 Documentation/sh/interface.rst
> >> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
> >> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
> >>
> >> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
> >> index bc8db7ba894a..fec3c405b6b9 100644
> >> --- a/Documentation/sh/index.rst
> >> +++ b/Documentation/sh/index.rst
> >> @@ -1,59 +1,14 @@
> >> -=======================
> >> -SuperH Interfaces Guide
> >> -=======================
> >> +.. SPDX-License-Identifier: GPL-2.0
> >>
> >> -:Author: Paul Mundt
> >> -
> >> -Memory Management
> >> -=================
> >> -
> >> -SH-4
> >> -----
> >> -
> >> -Store Queue API
> >> -~~~~~~~~~~~~~~~
> >> -
> >> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> >> - :export:
> >> -
> >> -SH-5
> >> -----
> >> -
> >> -TLB Interfaces
> >> -~~~~~~~~~~~~~~
> >> -
> >> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> >> - :internal:
> >> -
> >> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> >> - :internal:
> >> +====================
> >> +SuperH Documentation
> >> +====================
> >>
> >> -Machine Specific Interfaces
> >> -===========================
> >> -
> >> -mach-dreamcast
> >> ---------------
> >> -
> >> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> >> - :internal:
> >> -
> >> -mach-x3proto
> >> -------------
> >> -
> >> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> >> - :export:
> >> -
> >> -Busses
> >> -======
> >> -
> >> -SuperHyway
> >> -----------
> >> -
> >> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> >> - :export:
> >> +:Author: Paul Mundt
> >>
> >> -Maple
> >> ------
> >> +.. toctree::
> >> + :maxdepth: 2
> >>
> >> -.. kernel-doc:: drivers/sh/maple/maple.c
> >> - :export:
> >> + interface
> >> + new-machine
> >> + register-banks
> >> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
> >> new file mode 100644
> >> index 000000000000..bc8db7ba894a
> >> --- /dev/null
> >> +++ b/Documentation/sh/interface.rst
> >> @@ -0,0 +1,59 @@
> >> +=======================
> >> +SuperH Interfaces Guide
> >> +=======================
> >> +
> >> +:Author: Paul Mundt
> >> +
> >> +Memory Management
> >> +=================
> >> +
> >> +SH-4
> >> +----
> >> +
> >> +Store Queue API
> >> +~~~~~~~~~~~~~~~
> >> +
> >> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> >> + :export:
> >> +
> >> +SH-5
> >> +----
> >> +
> >> +TLB Interfaces
> >> +~~~~~~~~~~~~~~
> >> +
> >> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> >> + :internal:
> >> +
> >> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> >> + :internal:
> >> +
> >> +Machine Specific Interfaces
> >> +===========================
> >> +
> >> +mach-dreamcast
> >> +--------------
> >> +
> >> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> >> + :internal:
> >> +
> >> +mach-x3proto
> >> +------------
> >> +
> >> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> >> + :export:
> >> +
> >> +Busses
> >> +======
> >> +
> >> +SuperHyway
> >> +----------
> >> +
> >> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> >> + :export:
> >> +
> >> +Maple
> >> +-----
> >> +
> >> +.. kernel-doc:: drivers/sh/maple/maple.c
> >> + :export:
> >> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
> >> similarity index 79%
> >> rename from Documentation/sh/new-machine.txt
> >> rename to Documentation/sh/new-machine.rst
> >> index e0961a66130b..b16c33342642 100644
> >> --- a/Documentation/sh/new-machine.txt
> >> +++ b/Documentation/sh/new-machine.rst
> >> @@ -1,8 +1,8 @@
> >> +================================
> >> +Adding a new board to LinuxSH
> >> +================================
> >>
> >> - Adding a new board to LinuxSH
> >> - ================================
> >> -
> >> - Paul Mundt <lethal@linux-sh.org>
> >> +Paul Mundt <lethal@linux-sh.org>
> >>
> >> This document attempts to outline what steps are necessary to add support
> >> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
> >> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
> >> companion chip type, and CPU type. Looking at a tree view of this directory
> >> hierarchy looks like the following:
> >>
> >> -Board-specific code:
> >> -
> >> -.
> >> -|-- arch
> >> -| `-- sh
> >> -| `-- boards
> >> -| |-- adx
> >> -| | `-- board-specific files
> >> -| |-- bigsur
> >> -| | `-- board-specific files
> >> -| |
> >> -| ... more boards here ...
> >> -|
> >> -`-- include
> >> - `-- asm-sh
> >> - |-- adx
> >> - | `-- board-specific headers
> >> - |-- bigsur
> >> - | `-- board-specific headers
> >> - |
> >> - .. more boards here ...
> >> -
> >> -Next, for companion chips:
> >> -.
> >> -`-- arch
> >> - `-- sh
> >> - `-- cchips
> >> - `-- hd6446x
> >> - `-- hd64461
> >> - `-- cchip-specific files
> >> +Board-specific code::
> >> +
> >> + .
> >> + |-- arch
> >> + | `-- sh
> >> + | `-- boards
> >> + | |-- adx
> >> + | | `-- board-specific files
> >> + | |-- bigsur
> >> + | | `-- board-specific files
> >> + | |
> >> + | ... more boards here ...
> >> + |
> >> + `-- include
> >> + `-- asm-sh
> >> + |-- adx
> >> + | `-- board-specific headers
> >> + |-- bigsur
> >> + | `-- board-specific headers
> >> + |
> >> + .. more boards here ...
> >> +
> >> +Next, for companion chips::
> >> +
> >> + .
> >> + `-- arch
> >> + `-- sh
> >> + `-- cchips
> >> + `-- hd6446x
> >> + `-- hd64461
> >> + `-- cchip-specific files
> >>
> >> ... and so on. Headers for the companion chips are treated the same way as
> >> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
> >> hd64461-specific headers.
> >>
> >> -Finally, CPU family support is also abstracted:
> >> -.
> >> -|-- arch
> >> -| `-- sh
> >> -| |-- kernel
> >> -| | `-- cpu
> >> -| | |-- sh2
> >> -| | | `-- SH-2 generic files
> >> -| | |-- sh3
> >> -| | | `-- SH-3 generic files
> >> -| | `-- sh4
> >> -| | `-- SH-4 generic files
> >> -| `-- mm
> >> -| `-- This is also broken out per CPU family, so each family can
> >> -| have their own set of cache/tlb functions.
> >> -|
> >> -`-- include
> >> - `-- asm-sh
> >> - |-- cpu-sh2
> >> - | `-- SH-2 specific headers
> >> - |-- cpu-sh3
> >> - | `-- SH-3 specific headers
> >> - `-- cpu-sh4
> >> - `-- SH-4 specific headers
> >> +Finally, CPU family support is also abstracted::
> >> +
> >> + .
> >> + |-- arch
> >> + | `-- sh
> >> + | |-- kernel
> >> + | | `-- cpu
> >> + | | |-- sh2
> >> + | | | `-- SH-2 generic files
> >> + | | |-- sh3
> >> + | | | `-- SH-3 generic files
> >> + | | `-- sh4
> >> + | | `-- SH-4 generic files
> >> + | `-- mm
> >> + | `-- This is also broken out per CPU family, so each family can
> >> + | have their own set of cache/tlb functions.
> >> + |
> >> + `-- include
> >> + `-- asm-sh
> >> + |-- cpu-sh2
> >> + | `-- SH-2 specific headers
> >> + |-- cpu-sh3
> >> + | `-- SH-3 specific headers
> >> + `-- cpu-sh4
> >> + `-- SH-4 specific headers
> >>
> >> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
> >> need to be dealt with by the CPU family specific code.
> >> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
> >> get_system_type() and platform_setup(). For our imaginary board, this
> >> might look something like:
> >>
> >> -/*
> >> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> >> - */
> >> -#include <linux/init.h>
> >> +.. code-block:: c
> >> +
> >> + /*
> >> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> >> + */
> >> + #include <linux/init.h>
> >>
> >> -const char *get_system_type(void)
> >> -{
> >> - return "FooTech Vaporboard";
> >> -}
> >> + const char *get_system_type(void)
> >> + {
> >> + return "FooTech Vaporboard";
> >> + }
> >>
> >> -int __init platform_setup(void)
> >> -{
> >> + int __init platform_setup(void)
> >> + {
> >> /*
> >> * If our hardware actually existed, we would do real
> >> * setup here. Though it's also sane to leave this empty
> >> @@ -136,7 +140,8 @@ int __init platform_setup(void)
> >> /* And whatever else ... */
> >>
> >> return 0;
> >> -}
> >> + }
> >> +
> >>
> >> Our new imaginary board will also have to tie into the machvec in order for it
> >> to be of any use.
> >> @@ -172,16 +177,17 @@ sufficient.
> >> vector.
> >>
> >> Note that these prototypes are generated automatically by setting
> >> - __IO_PREFIX to something sensible. A typical example would be:
> >> + __IO_PREFIX to something sensible. A typical example would be::
> >>
> >> #define __IO_PREFIX vapor
> >> #include <asm/io_generic.h>
> >>
> >> +
> >> somewhere in the board-specific header. Any boards being ported that still
> >> have a legacy io.h should remove it entirely and switch to the new model.
> >>
> >> - Add machine vector definitions to the board's setup.c. At a bare minimum,
> >> - this must be defined as something like:
> >> + this must be defined as something like::
> >>
> >> struct sh_machine_vector mv_vapor __initmv = {
> >> .mv_name = "vapor",
> >> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
> >> require the proper entry here and there in order to get things done.
> >>
> >> The first thing to do is to add an entry to arch/sh/Kconfig, under the
> >> -"System type" menu:
> >> +"System type" menu::
> >>
> >> -config SH_VAPOR
> >> - bool "Vapor"
> >> - help
> >> + config SH_VAPOR
> >> + bool "Vapor"
> >> + help
> >> select Vapor if configuring for a FooTech Vaporboard.
> >>
> >> next, this has to be added into arch/sh/Makefile. All boards require a
> >> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
> >> implicit checks for your board if you need this somewhere throughout the
> >> common code, such as:
> >>
> >> +::
> >> +
> >> /* Make sure we're on the FooTech Vaporboard */
> >> if (!mach_is_vapor())
> >> return -ENODEV;
> >> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
> >> Looking at the 'make help' output, you should now see something like:
> >>
> >> Architecture specific targets (sh):
> >> - zImage - Compressed kernel image (arch/sh/boot/zImage)
> >> - adx_defconfig - Build for adx
> >> - cqreek_defconfig - Build for cqreek
> >> - dreamcast_defconfig - Build for dreamcast
> >> -...
> >> - vapor_defconfig - Build for vapor
> >> +
> >> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
> >> + - adx_defconfig - Build for adx
> >> + - cqreek_defconfig - Build for cqreek
> >> + - dreamcast_defconfig - Build for dreamcast
> >> + - ...
> >> + - vapor_defconfig - Build for vapor
> >>
> >> which then allows you to do:
> >>
> >> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
> >> similarity index 90%
> >> rename from Documentation/sh/register-banks.txt
> >> rename to Documentation/sh/register-banks.rst
> >> index a6719f2f6594..acccfaf80355 100644
> >> --- a/Documentation/sh/register-banks.txt
> >> +++ b/Documentation/sh/register-banks.rst
> >> @@ -1,8 +1,9 @@
> >> - Notes on register bank usage in the kernel
> >> - ==========================================
> >> +==========================================
> >> +Notes on register bank usage in the kernel
> >> +==========================================
> >>
> >> Introduction
> >> -------------
> >> +============
> >>
> >> The SH-3 and SH-4 CPU families traditionally include a single partial register
> >> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
> >> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
> >> - The SR.IMASK interrupt handler makes use of this to set the
> >> interrupt priority level (used by local_irq_enable())
> >> - r7_bank (current)
> >> -
> >> --
> >> 2.17.1
> >>
> >
> >
> > Thanks,
> > Mauro
>
> Regards,
>
> Vandana.
>
Thanks,
Mauro
^ permalink raw reply
* Re: [linux-kernel-mentees] [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 16:02 UTC (permalink / raw)
To: skhan
Cc: linux-kernel-mentees, darrick.wong, linux-xfs, corbet, linux-doc,
linux-kernel
In-Reply-To: <20190629150155.GB10491@localhost>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v2:
Update MAINTAINERS. Fix indentation/long line issues. cc Darick and xfs mailist.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 467 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 471 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..f52046b96
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,467 @@
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ allocsize=<size>
+ Sets the buffered I/O end-of-file preallocation size when doing delayed
+ allocation writeout (default size is 64KiB). Valid values for this
+ option are page size (typically 4KiB) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [no]attr2
+ The options enable/disable an "opportunistic" improvement to be made in
+ the way inline extended attributes are stored on-disk. When the new
+ form is used for the first time when ``attr2`` is selected (either when
+ setting or removing extended attributes) the on-disk superblock feature
+ bit field will be updated to reflect this format being in use.
+
+ The default behaviour is determined by the on-disk feature bit
+ indicating that ``attr2`` behaviour is active. If either mount option is
+ set, then that becomes the new default used by the filesystem. However
+ on CRC enabled filesystems, the ``attr2`` format is always used , and so
+ will reject the ``noattr2`` mount option if it is set.
+
+ (*)[no]discard
+ Enable/disable the issuing of commands to let the block device reclaim
+ space freed by the filesystem. This is useful for SSD devices, thinly
+ provisioned LUNs and virtual machine images, but may have a performance
+ impact.
+
+ Note: It is currently recommended that you use the ``fstrim``
+ application to discard unused blocks rather than the ``discard`` mount
+ option because the performance impact of this option is quite severe.
+
+ grpid/bsdgroups
+ nogrpid/(*)sysvgroups
+ These options define what group ID a newly created file gets. When
+ ``grpid`` is set, it takes the group ID of the directory in which it is
+ created; otherwise it takes the ``fsgid`` of the current process, unless
+ the directory has the ``setgid`` bit set, in which case it takes the
+ ``gid`` from the parent directory, and also gets the ``setgid`` bit set
+ if it is a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[no]ikeep
+ When ``ikeep`` is specified, XFS does not delete empty inode clusters
+ and keeps them around on disk. When ``noikeep`` is specified, empty
+ inode clusters are returned to the free space pool.
+
+ inode32 | (*)inode64
+ When ``inode32`` is specified, it indicates that XFS limits inode
+ creation to locations which will not result in inode numbers with more
+ than 32 bits of significance.
+
+ When ``inode64`` is specified, it indicates that XFS is allowed to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``inode32`` is provided for backwards compatibility with older systems
+ and applications, since 64 bits inode numbers might cause problems for
+ some applications that cannot handle large inode numbers. If
+ applications are in use which do not handle inode numbers bigger than 32
+ bits, the ``inode32`` option should be specified.
+
+
+ (*)[no]largeio
+ If ``nolargeio`` is specified, the optimal I/O reported in st_blksize by
+ **stat(2)** will be as small as possible to allow user applications to
+ avoid inefficient read/modify/write I/O. This is typically the page
+ size of the machine, as this is the granularity of the page cache.
+
+ If ``largeio`` is specified, a filesystem that was created with a
+ ``swidth`` specified will return the ``swidth`` value (in bytes) in
+ st_blksize. If the filesystem does not have a ``swidth`` specified but
+ does specify an ``allocsize`` then ``allocsize`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ logbufs=<value>
+ Set the number of in-memory log buffers to ``value``. Valid numbers
+ range from 2-8 inclusive.
+
+ The default value is 8 buffers.
+
+ If the memory cost of 8 log buffers is too high on small systems, then
+ it may be reduced at some cost to performance on metadata intensive
+ workloads. The ``logbsize`` option below controls the size of each
+ buffer and so is also relevant to this case.
+
+ logbsize=<value>
+ Set the size of each in-memory log buffer to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. Valid sizes for
+ version 1 and version 2 logs are 16384 (16k) and 32768 (32k). Valid
+ sizes for version 2 logs also include 65536 (64k), 131072 (128k) and
+ 262144 (256k). The ``logbsize`` must be an integer multiple of the
+ "log stripe unit" configured at mkfs time.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ rtdev=<device>
+ An XFS filesystem has up to three parts: a data section, a log section,
+ and a real-time section. The real-time section is optional. If
+ enabled, ``rtdev`` sets ``device`` to be used as an external real-time
+ section, similar to ``logdev`` above.
+
+ noalign
+ Data allocations will not be aligned at stripe unit boundaries. This is
+ only relevant to filesystems created with non-zero data alignment
+ parameters (sunit, swidth) by mkfs.
+
+ norecovery
+ The filesystem will be mounted without running log recovery. If the
+ filesystem was not cleanly unmounted, it is likely to be inconsistent
+ when mounted in ``norecovery`` mode. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ nouuid
+ Don't check for double mounted file systems using the file system uuid.
+ This is useful to mount LVM snapshot volumes, and often used in
+ combination with ``norecovery`` for mounting read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ sunit=<value>
+ Used to specify the stripe unit for a RAID device or (in conjunction
+ with ``swidth`` below) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ The ``sunit`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid changes to ``sunit`` are increasing it by a power-of-2 multiple.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+ swidth=<value>
+ Used to specify the stripe width for a RAID device or (in conjunction
+ with ``sunit`` above) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ The ``swidth`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid swidth values are any integer multiple of a valid ``sunit`` value.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+
+ swalloc
+ Data allocations will be rounded up to stripe width boundaries when the
+ current end of file is being extended and the file size is larger than
+ the stripe width size.
+
+ wsync
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "sync" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodump" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "noatime" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nosymlinks" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodefrag" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- allocsize=size
- Sets the buffered I/O end-of-file preallocation size when
- doing delayed allocation writeout (default size is 64KiB).
- Valid values for this option are page size (typically 4KiB)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- The options enable/disable an "opportunistic" improvement to
- be made in the way inline extended attributes are stored
- on-disk. When the new form is used for the first time when
- attr2 is selected (either when setting or removing extended
- attributes) the on-disk superblock feature bit field will be
- updated to reflect this format being in use.
-
- The default behaviour is determined by the on-disk feature
- bit indicating that attr2 behaviour is active. If either
- mount option it set, then that becomes the new default used
- by the filesystem.
-
- CRC enabled filesystems always use the attr2 format, and so
- will reject the noattr2 mount option if it is set.
-
- discard
- nodiscard (*)
- Enable/disable the issuing of commands to let the block
- device reclaim space freed by the filesystem. This is
- useful for SSD devices, thinly provisioned LUNs and virtual
- machine images, but may have a performance impact.
-
- Note: It is currently recommended that you use the fstrim
- application to discard unused blocks rather than the discard
- mount option because the performance impact of this option
- is quite severe.
-
- grpid/bsdgroups
- nogrpid/sysvgroups (*)
- These options define what group ID a newly created file
- gets. When grpid is set, it takes the group ID of the
- directory in which it is created; otherwise it takes the
- fsgid of the current process, unless the directory has the
- setgid bit set, in which case it takes the gid from the
- parent directory, and also gets the setgid bit set if it is
- a directory itself.
-
- filestreams
- Make the data allocator use the filestreams allocation mode
- across the entire filesystem rather than just on directories
- configured to use it.
-
- ikeep
- noikeep (*)
- When ikeep is specified, XFS does not delete empty inode
- clusters and keeps them around on disk. When noikeep is
- specified, empty inode clusters are returned to the free
- space pool.
-
- inode32
- inode64 (*)
- When inode32 is specified, it indicates that XFS limits
- inode creation to locations which will not result in inode
- numbers with more than 32 bits of significance.
-
- When inode64 is specified, it indicates that XFS is allowed
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- inode32 is provided for backwards compatibility with older
- systems and applications, since 64 bits inode numbers might
- cause problems for some applications that cannot handle
- large inode numbers. If applications are in use which do
- not handle inode numbers bigger than 32 bits, the inode32
- option should be specified.
-
-
- largeio
- nolargeio (*)
- If "nolargeio" is specified, the optimal I/O reported in
- st_blksize by stat(2) will be as small as possible to allow
- user applications to avoid inefficient read/modify/write
- I/O. This is typically the page size of the machine, as
- this is the granularity of the page cache.
-
- If "largeio" specified, a filesystem that was created with a
- "swidth" specified will return the "swidth" value (in bytes)
- in st_blksize. If the filesystem does not have a "swidth"
- specified but does specify an "allocsize" then "allocsize"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
- range from 2-8 inclusive.
-
- The default value is 8 buffers.
-
- If the memory cost of 8 log buffers is too high on small
- systems, then it may be reduced at some cost to performance
- on metadata intensive workloads. The logbsize option below
- controls the size of each buffer and so is also relevant to
- this case.
-
- logbsize=value
- Set the size of each in-memory log buffer. The size may be
- specified in bytes, or in kilobytes with a "k" suffix.
- Valid sizes for version 1 and version 2 logs are 16384 (16k)
- and 32768 (32k). Valid sizes for version 2 logs also
- include 65536 (64k), 131072 (128k) and 262144 (256k). The
- logbsize must be an integer multiple of the log
- stripe unit configured at mkfs time.
-
- The default value for for version 1 logs is 32768, while the
- default value for version 2 logs is MAX(32768, log_sunit).
-
- logdev=device and rtdev=device
- Use an external log (metadata journal) and/or real-time device.
- An XFS filesystem has up to three parts: a data section, a log
- section, and a real-time section. The real-time section is
- optional, and the log section can be separate from the data
- section or contained within it.
-
- noalign
- Data allocations will not be aligned at stripe unit
- boundaries. This is only relevant to filesystems created
- with non-zero data alignment parameters (sunit, swidth) by
- mkfs.
-
- norecovery
- The filesystem will be mounted without running log recovery.
- If the filesystem was not cleanly unmounted, it is likely to
- be inconsistent when mounted in "norecovery" mode.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- nouuid
- Don't check for double mounted file systems using the file
- system uuid. This is useful to mount LVM snapshot volumes,
- and often used in combination with "norecovery" for mounting
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- sunit=value and swidth=value
- Used to specify the stripe unit and width for a RAID device
- or a stripe volume. "value" must be specified in 512-byte
- block units. These options are only relevant to filesystems
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters specified must be compatible
- with the existing filesystem alignment characteristics. In
- general, that means the only valid changes to sunit are
- increasing it by a power-of-2 multiple. Valid swidth values
- are any integer multiple of a valid sunit value.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
- modified, such as adding a new disk to a RAID5 lun and
- reshaping it.
-
- swalloc
- Data allocations will be rounded up to stripe width boundaries
- when the current end of file is being extended and the file
- size is larger than the stripe width size.
-
- wsync
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "sync" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodump" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "noatime" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nosymlinks" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodefrag" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands
From: Andy Shevchenko @ 2019-06-29 16:00 UTC (permalink / raw)
To: Srinivas Pandruvada
Cc: Darren Hart, Andy Shevchenko, Andriy Shevchenko, Jonathan Corbet,
Rafael J. Wysocki, Alan Cox, Len Brown, prarit, darcari,
Linux Documentation List, Linux Kernel Mailing List,
Platform Driver
In-Reply-To: <1c4238f7d18d316df82d3ba1618fecdcf014f98a.camel@linux.intel.com>
On Sat, Jun 29, 2019 at 5:53 PM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
> On Sat, 2019-06-29 at 17:31 +0300, Andy Shevchenko wrote:
> > On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
> > <srinivas.pandruvada@linux.intel.com> wrote:
> > > +++ b/tools/power/x86/intel_speed_select/Makefile
> >
> > My experience with some tools are not good in order of their build
> > process.
> > Can this one use tools build infrastructure from the day 1?
> Can you give some pointers?
Sure.
At least simple ones are under tools/gpio, tools/iio, etc.
You may compare them to see what's different and what's common and
base Makefile here on that.
I dunno if there is any tool under tools/power to use that, it might
give an example of `descend` feature in Makefile.
> > > @@ -0,0 +1,31 @@
> > > +# SPDX-License-Identifier: GPL-2.0
> > > +CC = $(CROSS_COMPILE)gcc
> > > +BUILD_OUTPUT := $(CURDIR)
> > > +PREFIX ?= /usr
> > > +DESTDIR ?=
> > > +
> > > +override CFLAGS += -D__EXPORTED_HEADERS__ -Wall -D_GNU_SOURCE
> > > +override CFLAGS += -I$(CURDIR)/../../../../include/uapi/
> > > +override CFLAGS += -I$(CURDIR)/../../../../include/
> > > +
> > > +%: %.c
> > > + @mkdir -p $(BUILD_OUTPUT)
> > > + $(CC) $(CFLAGS) $< -o $(BUILD_OUTPUT)/$@ $(LDFLAGS)
> > > +
> > > +DEPS = isst.h
> > > +OBJ = isst_config.o isst_core.o isst_display.o
> > > +
> > > +%.o: %.c $(DEPS)
> > > + $(CC) -c -o $(BUILD_OUTPUT)/$@ $< $(CFLAGS)
> > > +
> > > +intel-speed-select: $(OBJ)
> > > + $(CC) -o $(BUILD_OUTPUT)/$@ $^ $(CFLAGS)
> > > +
> > > +.PHONY : clean
> > > +clean :
> > > + @rm -f $(BUILD_OUTPUT)/intel-speed-select
> > > + @rm -f $(BUILD_OUTPUT)/*.o
> > > +
> > > +install : intel-speed-select
> > > + install -d $(DESTDIR)$(PREFIX)/sbin
> > > + install $(BUILD_OUTPUT)/intel-speed-select
> > > $(DESTDIR)$(PREFIX)/sbin/intel-speed-select
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Vandana BN @ 2019-06-29 15:56 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <20190629115014.4aec058d@coco.lan>
On 29/06/19 8:20 PM, Mauro Carvalho Chehab wrote:
> Em Sat, 29 Jun 2019 20:02:45 +0530
> Vandana BN <bnvandana@gmail.com> escreveu:
>
>> This patch converts new-machine.txt and register-banks.txt
>> to ReST format, No content change.
>> Added interfaces.rst to contain kernel-doc markups from index.rst
>> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
>> Added SPDX tag in index.rst
>>
>> Signed-off-by: Vandana BN <bnvandana@gmail.com>
> Looks good to me. Just a final thing to do.
>
> Be sure to run:
>
> ./scripts/documentation-file-ref-check
>
> in order to check that you're not breaking any references to the file.
> If it breaks, please adjust the reference to reflect the file
> rename.
>
> After fixing the broken reference, feel free do add:
>
> Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Thanks Mauro,
i don't not see any broken references.
>> ---
>> Documentation/sh/index.rst | 65 +------
>> Documentation/sh/interface.rst | 59 ++++++
>> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
>> ...{register-banks.txt => register-banks.rst} | 8 +-
>> 4 files changed, 163 insertions(+), 140 deletions(-)
>> create mode 100644 Documentation/sh/interface.rst
>> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
>> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>>
>> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
>> index bc8db7ba894a..fec3c405b6b9 100644
>> --- a/Documentation/sh/index.rst
>> +++ b/Documentation/sh/index.rst
>> @@ -1,59 +1,14 @@
>> -=======================
>> -SuperH Interfaces Guide
>> -=======================
>> +.. SPDX-License-Identifier: GPL-2.0
>>
>> -:Author: Paul Mundt
>> -
>> -Memory Management
>> -=================
>> -
>> -SH-4
>> -----
>> -
>> -Store Queue API
>> -~~~~~~~~~~~~~~~
>> -
>> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>> - :export:
>> -
>> -SH-5
>> -----
>> -
>> -TLB Interfaces
>> -~~~~~~~~~~~~~~
>> -
>> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>> - :internal:
>> -
>> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>> - :internal:
>> +====================
>> +SuperH Documentation
>> +====================
>>
>> -Machine Specific Interfaces
>> -===========================
>> -
>> -mach-dreamcast
>> ---------------
>> -
>> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>> - :internal:
>> -
>> -mach-x3proto
>> -------------
>> -
>> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>> - :export:
>> -
>> -Busses
>> -======
>> -
>> -SuperHyway
>> -----------
>> -
>> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>> - :export:
>> +:Author: Paul Mundt
>>
>> -Maple
>> ------
>> +.. toctree::
>> + :maxdepth: 2
>>
>> -.. kernel-doc:: drivers/sh/maple/maple.c
>> - :export:
>> + interface
>> + new-machine
>> + register-banks
>> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
>> new file mode 100644
>> index 000000000000..bc8db7ba894a
>> --- /dev/null
>> +++ b/Documentation/sh/interface.rst
>> @@ -0,0 +1,59 @@
>> +=======================
>> +SuperH Interfaces Guide
>> +=======================
>> +
>> +:Author: Paul Mundt
>> +
>> +Memory Management
>> +=================
>> +
>> +SH-4
>> +----
>> +
>> +Store Queue API
>> +~~~~~~~~~~~~~~~
>> +
>> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>> + :export:
>> +
>> +SH-5
>> +----
>> +
>> +TLB Interfaces
>> +~~~~~~~~~~~~~~
>> +
>> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>> + :internal:
>> +
>> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>> + :internal:
>> +
>> +Machine Specific Interfaces
>> +===========================
>> +
>> +mach-dreamcast
>> +--------------
>> +
>> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>> + :internal:
>> +
>> +mach-x3proto
>> +------------
>> +
>> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>> + :export:
>> +
>> +Busses
>> +======
>> +
>> +SuperHyway
>> +----------
>> +
>> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>> + :export:
>> +
>> +Maple
>> +-----
>> +
>> +.. kernel-doc:: drivers/sh/maple/maple.c
>> + :export:
>> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
>> similarity index 79%
>> rename from Documentation/sh/new-machine.txt
>> rename to Documentation/sh/new-machine.rst
>> index e0961a66130b..b16c33342642 100644
>> --- a/Documentation/sh/new-machine.txt
>> +++ b/Documentation/sh/new-machine.rst
>> @@ -1,8 +1,8 @@
>> +================================
>> +Adding a new board to LinuxSH
>> +================================
>>
>> - Adding a new board to LinuxSH
>> - ================================
>> -
>> - Paul Mundt <lethal@linux-sh.org>
>> +Paul Mundt <lethal@linux-sh.org>
>>
>> This document attempts to outline what steps are necessary to add support
>> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
>> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
>> companion chip type, and CPU type. Looking at a tree view of this directory
>> hierarchy looks like the following:
>>
>> -Board-specific code:
>> -
>> -.
>> -|-- arch
>> -| `-- sh
>> -| `-- boards
>> -| |-- adx
>> -| | `-- board-specific files
>> -| |-- bigsur
>> -| | `-- board-specific files
>> -| |
>> -| ... more boards here ...
>> -|
>> -`-- include
>> - `-- asm-sh
>> - |-- adx
>> - | `-- board-specific headers
>> - |-- bigsur
>> - | `-- board-specific headers
>> - |
>> - .. more boards here ...
>> -
>> -Next, for companion chips:
>> -.
>> -`-- arch
>> - `-- sh
>> - `-- cchips
>> - `-- hd6446x
>> - `-- hd64461
>> - `-- cchip-specific files
>> +Board-specific code::
>> +
>> + .
>> + |-- arch
>> + | `-- sh
>> + | `-- boards
>> + | |-- adx
>> + | | `-- board-specific files
>> + | |-- bigsur
>> + | | `-- board-specific files
>> + | |
>> + | ... more boards here ...
>> + |
>> + `-- include
>> + `-- asm-sh
>> + |-- adx
>> + | `-- board-specific headers
>> + |-- bigsur
>> + | `-- board-specific headers
>> + |
>> + .. more boards here ...
>> +
>> +Next, for companion chips::
>> +
>> + .
>> + `-- arch
>> + `-- sh
>> + `-- cchips
>> + `-- hd6446x
>> + `-- hd64461
>> + `-- cchip-specific files
>>
>> ... and so on. Headers for the companion chips are treated the same way as
>> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
>> hd64461-specific headers.
>>
>> -Finally, CPU family support is also abstracted:
>> -.
>> -|-- arch
>> -| `-- sh
>> -| |-- kernel
>> -| | `-- cpu
>> -| | |-- sh2
>> -| | | `-- SH-2 generic files
>> -| | |-- sh3
>> -| | | `-- SH-3 generic files
>> -| | `-- sh4
>> -| | `-- SH-4 generic files
>> -| `-- mm
>> -| `-- This is also broken out per CPU family, so each family can
>> -| have their own set of cache/tlb functions.
>> -|
>> -`-- include
>> - `-- asm-sh
>> - |-- cpu-sh2
>> - | `-- SH-2 specific headers
>> - |-- cpu-sh3
>> - | `-- SH-3 specific headers
>> - `-- cpu-sh4
>> - `-- SH-4 specific headers
>> +Finally, CPU family support is also abstracted::
>> +
>> + .
>> + |-- arch
>> + | `-- sh
>> + | |-- kernel
>> + | | `-- cpu
>> + | | |-- sh2
>> + | | | `-- SH-2 generic files
>> + | | |-- sh3
>> + | | | `-- SH-3 generic files
>> + | | `-- sh4
>> + | | `-- SH-4 generic files
>> + | `-- mm
>> + | `-- This is also broken out per CPU family, so each family can
>> + | have their own set of cache/tlb functions.
>> + |
>> + `-- include
>> + `-- asm-sh
>> + |-- cpu-sh2
>> + | `-- SH-2 specific headers
>> + |-- cpu-sh3
>> + | `-- SH-3 specific headers
>> + `-- cpu-sh4
>> + `-- SH-4 specific headers
>>
>> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
>> need to be dealt with by the CPU family specific code.
>> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
>> get_system_type() and platform_setup(). For our imaginary board, this
>> might look something like:
>>
>> -/*
>> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>> - */
>> -#include <linux/init.h>
>> +.. code-block:: c
>> +
>> + /*
>> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>> + */
>> + #include <linux/init.h>
>>
>> -const char *get_system_type(void)
>> -{
>> - return "FooTech Vaporboard";
>> -}
>> + const char *get_system_type(void)
>> + {
>> + return "FooTech Vaporboard";
>> + }
>>
>> -int __init platform_setup(void)
>> -{
>> + int __init platform_setup(void)
>> + {
>> /*
>> * If our hardware actually existed, we would do real
>> * setup here. Though it's also sane to leave this empty
>> @@ -136,7 +140,8 @@ int __init platform_setup(void)
>> /* And whatever else ... */
>>
>> return 0;
>> -}
>> + }
>> +
>>
>> Our new imaginary board will also have to tie into the machvec in order for it
>> to be of any use.
>> @@ -172,16 +177,17 @@ sufficient.
>> vector.
>>
>> Note that these prototypes are generated automatically by setting
>> - __IO_PREFIX to something sensible. A typical example would be:
>> + __IO_PREFIX to something sensible. A typical example would be::
>>
>> #define __IO_PREFIX vapor
>> #include <asm/io_generic.h>
>>
>> +
>> somewhere in the board-specific header. Any boards being ported that still
>> have a legacy io.h should remove it entirely and switch to the new model.
>>
>> - Add machine vector definitions to the board's setup.c. At a bare minimum,
>> - this must be defined as something like:
>> + this must be defined as something like::
>>
>> struct sh_machine_vector mv_vapor __initmv = {
>> .mv_name = "vapor",
>> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
>> require the proper entry here and there in order to get things done.
>>
>> The first thing to do is to add an entry to arch/sh/Kconfig, under the
>> -"System type" menu:
>> +"System type" menu::
>>
>> -config SH_VAPOR
>> - bool "Vapor"
>> - help
>> + config SH_VAPOR
>> + bool "Vapor"
>> + help
>> select Vapor if configuring for a FooTech Vaporboard.
>>
>> next, this has to be added into arch/sh/Makefile. All boards require a
>> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
>> implicit checks for your board if you need this somewhere throughout the
>> common code, such as:
>>
>> +::
>> +
>> /* Make sure we're on the FooTech Vaporboard */
>> if (!mach_is_vapor())
>> return -ENODEV;
>> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
>> Looking at the 'make help' output, you should now see something like:
>>
>> Architecture specific targets (sh):
>> - zImage - Compressed kernel image (arch/sh/boot/zImage)
>> - adx_defconfig - Build for adx
>> - cqreek_defconfig - Build for cqreek
>> - dreamcast_defconfig - Build for dreamcast
>> -...
>> - vapor_defconfig - Build for vapor
>> +
>> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
>> + - adx_defconfig - Build for adx
>> + - cqreek_defconfig - Build for cqreek
>> + - dreamcast_defconfig - Build for dreamcast
>> + - ...
>> + - vapor_defconfig - Build for vapor
>>
>> which then allows you to do:
>>
>> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
>> similarity index 90%
>> rename from Documentation/sh/register-banks.txt
>> rename to Documentation/sh/register-banks.rst
>> index a6719f2f6594..acccfaf80355 100644
>> --- a/Documentation/sh/register-banks.txt
>> +++ b/Documentation/sh/register-banks.rst
>> @@ -1,8 +1,9 @@
>> - Notes on register bank usage in the kernel
>> - ==========================================
>> +==========================================
>> +Notes on register bank usage in the kernel
>> +==========================================
>>
>> Introduction
>> -------------
>> +============
>>
>> The SH-3 and SH-4 CPU families traditionally include a single partial register
>> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
>> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
>> - The SR.IMASK interrupt handler makes use of this to set the
>> interrupt priority level (used by local_irq_enable())
>> - r7_bank (current)
>> -
>> --
>> 2.17.1
>>
>
>
> Thanks,
> Mauro
Regards,
Vandana.
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Jonathan Corbet @ 2019-06-29 15:14 UTC (permalink / raw)
To: Sheriff Esseson
Cc: skhan, darrick.wong, linux-xfs, linux-doc, linux-kernel,
linux-kernel-mentees
In-Reply-To: <20190629150155.GB10491@localhost>
On Sat, 29 Jun 2019 16:01:55 +0100
Sheriff Esseson <sheriffesseson@gmail.com> wrote:
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> In v2.1:
> cc mentees list.
Please do us a favor?
1) Post each patch standalone, without quoted text, ready to be applied.
2) Wait a little while between postings so that you can address more than
one comment at a time.
OK, two favors - off-by-one errors are my specialty...:)
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 15:01 UTC (permalink / raw)
To: skhan
Cc: darrick.wong, linux-xfs, corbet, linux-doc, linux-kernel,
linux-kernel-mentees
In-Reply-To: <20190629145433.GA10491@localhost>
On Sat, Jun 29, 2019 at 03:54:33PM +0100, Sheriff Esseson wrote:
> On Sat, Jun 29, 2019 at 02:25:08AM +0100, Sheriff Esseson wrote:
> > On Fri, Jun 28, 2019 at 10:43:24PM +0100, Sheriff Esseson wrote:
> > > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > > Documentation/index.rst.
> > >
> > > While at it, make "value" in "option=value" form xfs options definable by
> > > the user, by embedding in angle "<>" brackets, rather than something
> > > predifined elsewhere. This is inline with the conventions in manuals.
> > >
> > > Also, make defaults of boolean options prefixed with "(*)". This is
> > > so that options can be compressed to "[no]option" and on a single line, which renders
> > > consistently and nicely in htmldocs.
> > > lastly, enforce a "one option, one definition" policy to keep things
> > > consistent and simple.
> > >
> > > Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> > > ---
> > > --
> > > 2.22.0
> > >
> >
> > Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
> >
> > CC xfs-list.
> >
> > Correct email indentation.
> >
> > Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> > ---
> > --
> > 2.22.0
> >
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
>
> In v2:
> Update MAINTAINERS.
> fix indentation/long lines issues.
> cc Darick and xfs mailing list.
>
> --
> 2.22.0
>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v2.1:
cc mentees list.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 467 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 471 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..f52046b96
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,467 @@
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ allocsize=<size>
+ Sets the buffered I/O end-of-file preallocation size when doing delayed
+ allocation writeout (default size is 64KiB). Valid values for this
+ option are page size (typically 4KiB) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [no]attr2
+ The options enable/disable an "opportunistic" improvement to be made in
+ the way inline extended attributes are stored on-disk. When the new
+ form is used for the first time when ``attr2`` is selected (either when
+ setting or removing extended attributes) the on-disk superblock feature
+ bit field will be updated to reflect this format being in use.
+
+ The default behaviour is determined by the on-disk feature bit
+ indicating that ``attr2`` behaviour is active. If either mount option is
+ set, then that becomes the new default used by the filesystem. However
+ on CRC enabled filesystems, the ``attr2`` format is always used , and so
+ will reject the ``noattr2`` mount option if it is set.
+
+ (*)[no]discard
+ Enable/disable the issuing of commands to let the block device reclaim
+ space freed by the filesystem. This is useful for SSD devices, thinly
+ provisioned LUNs and virtual machine images, but may have a performance
+ impact.
+
+ Note: It is currently recommended that you use the ``fstrim``
+ application to discard unused blocks rather than the ``discard`` mount
+ option because the performance impact of this option is quite severe.
+
+ grpid/bsdgroups
+ nogrpid/(*)sysvgroups
+ These options define what group ID a newly created file gets. When
+ ``grpid`` is set, it takes the group ID of the directory in which it is
+ created; otherwise it takes the ``fsgid`` of the current process, unless
+ the directory has the ``setgid`` bit set, in which case it takes the
+ ``gid`` from the parent directory, and also gets the ``setgid`` bit set
+ if it is a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[no]ikeep
+ When ``ikeep`` is specified, XFS does not delete empty inode clusters
+ and keeps them around on disk. When ``noikeep`` is specified, empty
+ inode clusters are returned to the free space pool.
+
+ inode32 | (*)inode64
+ When ``inode32`` is specified, it indicates that XFS limits inode
+ creation to locations which will not result in inode numbers with more
+ than 32 bits of significance.
+
+ When ``inode64`` is specified, it indicates that XFS is allowed to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``inode32`` is provided for backwards compatibility with older systems
+ and applications, since 64 bits inode numbers might cause problems for
+ some applications that cannot handle large inode numbers. If
+ applications are in use which do not handle inode numbers bigger than 32
+ bits, the ``inode32`` option should be specified.
+
+
+ (*)[no]largeio
+ If ``nolargeio`` is specified, the optimal I/O reported in st_blksize by
+ **stat(2)** will be as small as possible to allow user applications to
+ avoid inefficient read/modify/write I/O. This is typically the page
+ size of the machine, as this is the granularity of the page cache.
+
+ If ``largeio`` is specified, a filesystem that was created with a
+ ``swidth`` specified will return the ``swidth`` value (in bytes) in
+ st_blksize. If the filesystem does not have a ``swidth`` specified but
+ does specify an ``allocsize`` then ``allocsize`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ logbufs=<value>
+ Set the number of in-memory log buffers to ``value``. Valid numbers
+ range from 2-8 inclusive.
+
+ The default value is 8 buffers.
+
+ If the memory cost of 8 log buffers is too high on small systems, then
+ it may be reduced at some cost to performance on metadata intensive
+ workloads. The ``logbsize`` option below controls the size of each
+ buffer and so is also relevant to this case.
+
+ logbsize=<value>
+ Set the size of each in-memory log buffer to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. Valid sizes for
+ version 1 and version 2 logs are 16384 (16k) and 32768 (32k). Valid
+ sizes for version 2 logs also include 65536 (64k), 131072 (128k) and
+ 262144 (256k). The ``logbsize`` must be an integer multiple of the
+ "log stripe unit" configured at mkfs time.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ rtdev=<device>
+ An XFS filesystem has up to three parts: a data section, a log section,
+ and a real-time section. The real-time section is optional. If
+ enabled, ``rtdev`` sets ``device`` to be used as an external real-time
+ section, similar to ``logdev`` above.
+
+ noalign
+ Data allocations will not be aligned at stripe unit boundaries. This is
+ only relevant to filesystems created with non-zero data alignment
+ parameters (sunit, swidth) by mkfs.
+
+ norecovery
+ The filesystem will be mounted without running log recovery. If the
+ filesystem was not cleanly unmounted, it is likely to be inconsistent
+ when mounted in ``norecovery`` mode. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ nouuid
+ Don't check for double mounted file systems using the file system uuid.
+ This is useful to mount LVM snapshot volumes, and often used in
+ combination with ``norecovery`` for mounting read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ sunit=<value>
+ Used to specify the stripe unit for a RAID device or (in conjunction
+ with ``swidth`` below) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ The ``sunit`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid changes to ``sunit`` are increasing it by a power-of-2 multiple.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+ swidth=<value>
+ Used to specify the stripe width for a RAID device or (in conjunction
+ with ``sunit`` above) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ The ``swidth`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid swidth values are any integer multiple of a valid ``sunit`` value.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+
+ swalloc
+ Data allocations will be rounded up to stripe width boundaries when the
+ current end of file is being extended and the file size is larger than
+ the stripe width size.
+
+ wsync
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "sync" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodump" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "noatime" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nosymlinks" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodefrag" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- allocsize=size
- Sets the buffered I/O end-of-file preallocation size when
- doing delayed allocation writeout (default size is 64KiB).
- Valid values for this option are page size (typically 4KiB)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- The options enable/disable an "opportunistic" improvement to
- be made in the way inline extended attributes are stored
- on-disk. When the new form is used for the first time when
- attr2 is selected (either when setting or removing extended
- attributes) the on-disk superblock feature bit field will be
- updated to reflect this format being in use.
-
- The default behaviour is determined by the on-disk feature
- bit indicating that attr2 behaviour is active. If either
- mount option it set, then that becomes the new default used
- by the filesystem.
-
- CRC enabled filesystems always use the attr2 format, and so
- will reject the noattr2 mount option if it is set.
-
- discard
- nodiscard (*)
- Enable/disable the issuing of commands to let the block
- device reclaim space freed by the filesystem. This is
- useful for SSD devices, thinly provisioned LUNs and virtual
- machine images, but may have a performance impact.
-
- Note: It is currently recommended that you use the fstrim
- application to discard unused blocks rather than the discard
- mount option because the performance impact of this option
- is quite severe.
-
- grpid/bsdgroups
- nogrpid/sysvgroups (*)
- These options define what group ID a newly created file
- gets. When grpid is set, it takes the group ID of the
- directory in which it is created; otherwise it takes the
- fsgid of the current process, unless the directory has the
- setgid bit set, in which case it takes the gid from the
- parent directory, and also gets the setgid bit set if it is
- a directory itself.
-
- filestreams
- Make the data allocator use the filestreams allocation mode
- across the entire filesystem rather than just on directories
- configured to use it.
-
- ikeep
- noikeep (*)
- When ikeep is specified, XFS does not delete empty inode
- clusters and keeps them around on disk. When noikeep is
- specified, empty inode clusters are returned to the free
- space pool.
-
- inode32
- inode64 (*)
- When inode32 is specified, it indicates that XFS limits
- inode creation to locations which will not result in inode
- numbers with more than 32 bits of significance.
-
- When inode64 is specified, it indicates that XFS is allowed
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- inode32 is provided for backwards compatibility with older
- systems and applications, since 64 bits inode numbers might
- cause problems for some applications that cannot handle
- large inode numbers. If applications are in use which do
- not handle inode numbers bigger than 32 bits, the inode32
- option should be specified.
-
-
- largeio
- nolargeio (*)
- If "nolargeio" is specified, the optimal I/O reported in
- st_blksize by stat(2) will be as small as possible to allow
- user applications to avoid inefficient read/modify/write
- I/O. This is typically the page size of the machine, as
- this is the granularity of the page cache.
-
- If "largeio" specified, a filesystem that was created with a
- "swidth" specified will return the "swidth" value (in bytes)
- in st_blksize. If the filesystem does not have a "swidth"
- specified but does specify an "allocsize" then "allocsize"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
- range from 2-8 inclusive.
-
- The default value is 8 buffers.
-
- If the memory cost of 8 log buffers is too high on small
- systems, then it may be reduced at some cost to performance
- on metadata intensive workloads. The logbsize option below
- controls the size of each buffer and so is also relevant to
- this case.
-
- logbsize=value
- Set the size of each in-memory log buffer. The size may be
- specified in bytes, or in kilobytes with a "k" suffix.
- Valid sizes for version 1 and version 2 logs are 16384 (16k)
- and 32768 (32k). Valid sizes for version 2 logs also
- include 65536 (64k), 131072 (128k) and 262144 (256k). The
- logbsize must be an integer multiple of the log
- stripe unit configured at mkfs time.
-
- The default value for for version 1 logs is 32768, while the
- default value for version 2 logs is MAX(32768, log_sunit).
-
- logdev=device and rtdev=device
- Use an external log (metadata journal) and/or real-time device.
- An XFS filesystem has up to three parts: a data section, a log
- section, and a real-time section. The real-time section is
- optional, and the log section can be separate from the data
- section or contained within it.
-
- noalign
- Data allocations will not be aligned at stripe unit
- boundaries. This is only relevant to filesystems created
- with non-zero data alignment parameters (sunit, swidth) by
- mkfs.
-
- norecovery
- The filesystem will be mounted without running log recovery.
- If the filesystem was not cleanly unmounted, it is likely to
- be inconsistent when mounted in "norecovery" mode.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- nouuid
- Don't check for double mounted file systems using the file
- system uuid. This is useful to mount LVM snapshot volumes,
- and often used in combination with "norecovery" for mounting
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- sunit=value and swidth=value
- Used to specify the stripe unit and width for a RAID device
- or a stripe volume. "value" must be specified in 512-byte
- block units. These options are only relevant to filesystems
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters specified must be compatible
- with the existing filesystem alignment characteristics. In
- general, that means the only valid changes to sunit are
- increasing it by a power-of-2 multiple. Valid swidth values
- are any integer multiple of a valid sunit value.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
- modified, such as adding a new disk to a RAID5 lun and
- reshaping it.
-
- swalloc
- Data allocations will be rounded up to stripe width boundaries
- when the current end of file is being extended and the file
- size is larger than the stripe width size.
-
- wsync
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "sync" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodump" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "noatime" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nosymlinks" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodefrag" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH v7 1/2] fTPM: firmware TPM running in TEE
From: Sasha Levin @ 2019-06-29 15:01 UTC (permalink / raw)
To: Jarkko Sakkinen
Cc: peterhuewe, jgg, corbet, linux-kernel, linux-doc, linux-integrity,
linux-kernel, thiruan, bryankel, tee-dev, ilias.apalodimas,
sumit.garg, rdunlap
In-Reply-To: <673dd30d03e8ed9825bb46ef21b2efef015f6f2a.camel@linux.intel.com>
On Thu, Jun 27, 2019 at 02:31:35AM +0300, Jarkko Sakkinen wrote:
>On Tue, 2019-06-25 at 16:13 -0400, Sasha Levin wrote:
>> +static const uuid_t ftpm_ta_uuid =
>> + UUID_INIT(0xBC50D971, 0xD4C9, 0x42C4,
>> + 0x82, 0xCB, 0x34, 0x3F, 0xB7, 0xF3, 0x78, 0x96);
>> +
>> +/**
>> + * ftpm_tee_tpm_op_recv - retrieve fTPM response.
>> + *
>
>Should not have an empty line here.
>
>> + * @chip: the tpm_chip description as specified in driver/char/tpm/tpm.h.
>> + * @buf: the buffer to store data.
>> + * @count: the number of bytes to read.
Jarkko, w.r.t your comment above, there is an empty line between the
function name and variables in drivers/char/tpm, and in particular
tpm_crb.c which you authored and I used as reference. Do you want us to
diverge here?
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 14:54 UTC (permalink / raw)
To: skhan; +Cc: darrick.wong, linux-xfs, corbet, linux-doc, linux-kernel
In-Reply-To: <20190629010733.GA31770@localhost>
On Sat, Jun 29, 2019 at 02:25:08AM +0100, Sheriff Esseson wrote:
> On Fri, Jun 28, 2019 at 10:43:24PM +0100, Sheriff Esseson wrote:
> > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > Documentation/index.rst.
> >
> > While at it, make "value" in "option=value" form xfs options definable by
> > the user, by embedding in angle "<>" brackets, rather than something
> > predifined elsewhere. This is inline with the conventions in manuals.
> >
> > Also, make defaults of boolean options prefixed with "(*)". This is
> > so that options can be compressed to "[no]option" and on a single line, which renders
> > consistently and nicely in htmldocs.
> > lastly, enforce a "one option, one definition" policy to keep things
> > consistent and simple.
> >
> > Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> > ---
> > --
> > 2.22.0
> >
>
> Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
>
> CC xfs-list.
>
> Correct email indentation.
>
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
> --
> 2.22.0
>
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
In v2:
Update MAINTAINERS.
fix indentation/long lines issues.
cc Darick and xfs mailing list.
Documentation/filesystems/index.rst | 5 +-
Documentation/filesystems/xfs.rst | 467 +++++++++++++++++++++++++++
Documentation/filesystems/xfs.txt | 470 ----------------------------
MAINTAINERS | 2 +-
4 files changed, 471 insertions(+), 473 deletions(-)
create mode 100644 Documentation/filesystems/xfs.rst
delete mode 100644 Documentation/filesystems/xfs.txt
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..a4cf5fca4 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -16,7 +16,7 @@ algorithms work.
.. toctree::
:maxdepth: 2
- path-lookup.rst
+ path-lookup
api-summary
splice
@@ -40,4 +40,5 @@ Documentation for individual filesystem types can be found here.
.. toctree::
:maxdepth: 2
- binderfs.rst
+ binderfs
+ xfs
diff --git a/Documentation/filesystems/xfs.rst b/Documentation/filesystems/xfs.rst
new file mode 100644
index 000000000..f52046b96
--- /dev/null
+++ b/Documentation/filesystems/xfs.rst
@@ -0,0 +1,467 @@
+======================
+The SGI XFS Filesystem
+======================
+
+XFS is a high performance journaling filesystem which originated
+on the SGI IRIX platform. It is completely multi-threaded, can
+support large files and large filesystems, extended attributes,
+variable block sizes, is extent based, and makes extensive use of
+Btrees (directories, extents, free space) to aid both performance
+and scalability.
+
+Refer to the documentation at https://xfs.wiki.kernel.org/
+for further details. This implementation is on-disk compatible
+with the IRIX version of XFS.
+
+
+Mount Options
+=============
+
+When mounting an XFS filesystem, the following options are accepted. For
+boolean mount options, the names with the "(*)" prefix is the default behaviour.
+For example, take a behaviour enabled by default to be a one (1) or, a zero (0)
+otherwise, ``(*)[no]default`` would be 0 while ``[no](*)default`` , a 1.
+
+ allocsize=<size>
+ Sets the buffered I/O end-of-file preallocation size when doing delayed
+ allocation writeout (default size is 64KiB). Valid values for this
+ option are page size (typically 4KiB) through to 1GiB, inclusive, in
+ power-of-2 increments.
+
+ The default behaviour is for dynamic end-of-file preallocation size,
+ which uses a set of heuristics to optimise the preallocation size based
+ on the current allocation patterns within the file and the access
+ patterns to the file. Specifying a fixed allocsize value turns off the
+ dynamic behaviour.
+
+ [no]attr2
+ The options enable/disable an "opportunistic" improvement to be made in
+ the way inline extended attributes are stored on-disk. When the new
+ form is used for the first time when ``attr2`` is selected (either when
+ setting or removing extended attributes) the on-disk superblock feature
+ bit field will be updated to reflect this format being in use.
+
+ The default behaviour is determined by the on-disk feature bit
+ indicating that ``attr2`` behaviour is active. If either mount option is
+ set, then that becomes the new default used by the filesystem. However
+ on CRC enabled filesystems, the ``attr2`` format is always used , and so
+ will reject the ``noattr2`` mount option if it is set.
+
+ (*)[no]discard
+ Enable/disable the issuing of commands to let the block device reclaim
+ space freed by the filesystem. This is useful for SSD devices, thinly
+ provisioned LUNs and virtual machine images, but may have a performance
+ impact.
+
+ Note: It is currently recommended that you use the ``fstrim``
+ application to discard unused blocks rather than the ``discard`` mount
+ option because the performance impact of this option is quite severe.
+
+ grpid/bsdgroups
+ nogrpid/(*)sysvgroups
+ These options define what group ID a newly created file gets. When
+ ``grpid`` is set, it takes the group ID of the directory in which it is
+ created; otherwise it takes the ``fsgid`` of the current process, unless
+ the directory has the ``setgid`` bit set, in which case it takes the
+ ``gid`` from the parent directory, and also gets the ``setgid`` bit set
+ if it is a directory itself.
+
+ filestreams
+ Make the data allocator use the filestreams allocation mode across the
+ entire filesystem rather than just on directories configured to use it.
+
+ (*)[no]ikeep
+ When ``ikeep`` is specified, XFS does not delete empty inode clusters
+ and keeps them around on disk. When ``noikeep`` is specified, empty
+ inode clusters are returned to the free space pool.
+
+ inode32 | (*)inode64
+ When ``inode32`` is specified, it indicates that XFS limits inode
+ creation to locations which will not result in inode numbers with more
+ than 32 bits of significance.
+
+ When ``inode64`` is specified, it indicates that XFS is allowed to
+ create inodes at any location in the filesystem, including those which
+ will result in inode numbers occupying more than 32 bits of
+ significance.
+
+ ``inode32`` is provided for backwards compatibility with older systems
+ and applications, since 64 bits inode numbers might cause problems for
+ some applications that cannot handle large inode numbers. If
+ applications are in use which do not handle inode numbers bigger than 32
+ bits, the ``inode32`` option should be specified.
+
+
+ (*)[no]largeio
+ If ``nolargeio`` is specified, the optimal I/O reported in st_blksize by
+ **stat(2)** will be as small as possible to allow user applications to
+ avoid inefficient read/modify/write I/O. This is typically the page
+ size of the machine, as this is the granularity of the page cache.
+
+ If ``largeio`` is specified, a filesystem that was created with a
+ ``swidth`` specified will return the ``swidth`` value (in bytes) in
+ st_blksize. If the filesystem does not have a ``swidth`` specified but
+ does specify an ``allocsize`` then ``allocsize`` (in bytes) will be
+ returned instead. Otherwise the behaviour is the same as if
+ ``nolargeio`` was specified.
+
+ logbufs=<value>
+ Set the number of in-memory log buffers to ``value``. Valid numbers
+ range from 2-8 inclusive.
+
+ The default value is 8 buffers.
+
+ If the memory cost of 8 log buffers is too high on small systems, then
+ it may be reduced at some cost to performance on metadata intensive
+ workloads. The ``logbsize`` option below controls the size of each
+ buffer and so is also relevant to this case.
+
+ logbsize=<value>
+ Set the size of each in-memory log buffer to ``value``. The size may be
+ specified in bytes, or in kilobytes with a "k" suffix. Valid sizes for
+ version 1 and version 2 logs are 16384 (16k) and 32768 (32k). Valid
+ sizes for version 2 logs also include 65536 (64k), 131072 (128k) and
+ 262144 (256k). The ``logbsize`` must be an integer multiple of the
+ "log stripe unit" configured at mkfs time.
+
+ The default value for for version 1 logs is 32768, while the default
+ value for version 2 logs is ``MAX(32768, log_sunit)``.
+
+ logdev=<device>
+ Use ``device`` as an external log (metadata journal). In an XFS
+ filesystem, the log device can be separate from the data device or
+ contained within it.
+
+ rtdev=<device>
+ An XFS filesystem has up to three parts: a data section, a log section,
+ and a real-time section. The real-time section is optional. If
+ enabled, ``rtdev`` sets ``device`` to be used as an external real-time
+ section, similar to ``logdev`` above.
+
+ noalign
+ Data allocations will not be aligned at stripe unit boundaries. This is
+ only relevant to filesystems created with non-zero data alignment
+ parameters (sunit, swidth) by mkfs.
+
+ norecovery
+ The filesystem will be mounted without running log recovery. If the
+ filesystem was not cleanly unmounted, it is likely to be inconsistent
+ when mounted in ``norecovery`` mode. Some files or directories may not
+ be accessible because of this. Filesystems mounted ``norecovery`` must
+ be mounted read-only or the mount will fail.
+
+ nouuid
+ Don't check for double mounted file systems using the file system uuid.
+ This is useful to mount LVM snapshot volumes, and often used in
+ combination with ``norecovery`` for mounting read-only snapshots.
+
+ noquota
+ Forcibly turns off all quota accounting and enforcement
+ within the filesystem.
+
+ uquota/usrquota/uqnoenforce/quota
+ User disk quota accounting enabled, and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ gquota/grpquota/gqnoenforce
+ Group disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ pquota/prjquota/pqnoenforce
+ Project disk quota accounting enabled and limits (optionally) enforced.
+ Refer to **xfs_quota(8)** for further details.
+
+ sunit=<value>
+ Used to specify the stripe unit for a RAID device or (in conjunction
+ with ``swidth`` below) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option is only relevant to filesystems that
+ were created with non-zero data alignment parameters.
+
+ The ``sunit`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid changes to ``sunit`` are increasing it by a power-of-2 multiple.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+ swidth=<value>
+ Used to specify the stripe width for a RAID device or (in conjunction
+ with ``sunit`` above) a stripe volume. ``value`` must be specified in
+ 512-byte block units. This option, like ``sunit`` above, is only
+ relevant to filesystems that were created with non-zero data alignment
+ parameters.
+
+ The ``swidth`` parameter specified must be compatible with the existing
+ filesystem alignment characteristics. In general, that means the only
+ valid swidth values are any integer multiple of a valid ``sunit`` value.
+
+ Typically, this mount option is necessary only after an underlying RAID
+ device has had its geometry modified, such as adding a new disk to a
+ RAID5 lun and reshaping it.
+
+
+ swalloc
+ Data allocations will be rounded up to stripe width boundaries when the
+ current end of file is being extended and the file size is larger than
+ the stripe width size.
+
+ wsync
+ When specified, all filesystem namespace operations are executed
+ synchronously. This ensures that when the namespace operation (create,
+ unlink, etc) completes, the change to the namespace is on stable
+ storage. This is useful in HA setups where failover must not result in
+ clients seeing inconsistent namespace presentation during or after a
+ failover event.
+
+
+Deprecated Mount Options
+========================
+
+ Name Removal Schedule
+ ---- ----------------
+
+
+Removed Mount Options
+=====================
+
+ Name Removed
+ ---- -------
+ delaylog/nodelaylog v4.0
+ ihashsize v4.0
+ irixsgid v4.0
+ osyncisdsync/osyncisosync v4.0
+ barrier v4.19
+ nobarrier v4.19
+
+
+sysctls
+=======
+
+The following sysctls are available for the XFS filesystem:
+
+ fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
+ Setting this to "1" clears accumulated XFS statistics
+ in /proc/fs/xfs/stat. It then immediately resets to "0".
+
+ fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
+ The interval at which the filesystem flushes metadata
+ out to disk and runs internal cache cleanup routines.
+
+ fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
+ The interval at which the filesystem ages filestreams cache
+ references and returns timed-out AGs back to the free stream
+ pool.
+
+ fs.xfs.speculative_prealloc_lifetime
+ (Units: seconds Min: 1 Default: 300 Max: 86400)
+ The interval at which the background scanning for inodes
+ with unused speculative preallocation runs. The scan
+ removes unused preallocation from clean inodes and releases
+ the unused space back to the free pool.
+
+ fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
+ A volume knob for error reporting when internal errors occur.
+ This will generate detailed messages & backtraces for filesystem
+ shutdowns, for example. Current threshold values are:
+
+ XFS_ERRLEVEL_OFF: 0
+ XFS_ERRLEVEL_LOW: 1
+ XFS_ERRLEVEL_HIGH: 5
+
+ fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
+ Causes certain error conditions to call BUG(). Value is a bitmask;
+ OR together the tags which represent errors which should cause panics:
+
+ XFS_NO_PTAG 0
+ XFS_PTAG_IFLUSH 0x00000001
+ XFS_PTAG_LOGRES 0x00000002
+ XFS_PTAG_AILDELETE 0x00000004
+ XFS_PTAG_ERROR_REPORT 0x00000008
+ XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
+ XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
+ XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
+ XFS_PTAG_FSBLOCK_ZERO 0x00000080
+ XFS_PTAG_VERIFIER_ERROR 0x00000100
+
+ This option is intended for debugging only.
+
+ fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
+ Controls whether symlinks are created with mode 0777 (default)
+ or whether their mode is affected by the umask (irix mode).
+
+ fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
+ Controls files created in SGID directories.
+ If the group ID of the new file does not match the effective group
+ ID or one of the supplementary group IDs of the parent dir, the
+ ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
+ is set.
+
+ fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "sync" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodump" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "noatime" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nosymlinks" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
+ Setting this to "1" will cause the "nodefrag" flag set
+ by the **xfs_io(8)** chattr command on a directory to be
+ inherited by files in that directory.
+
+ fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
+ In "inode32" allocation mode, this option determines how many
+ files the allocator attempts to allocate in the same allocation
+ group before moving to the next allocation group. The intent
+ is to control the rate at which the allocator moves between
+ allocation groups when allocating extents for new files.
+
+Deprecated Sysctls
+==================
+
+None at present.
+
+
+Removed Sysctls
+===============
+
+ Name Removed
+ ---- -------
+ fs.xfs.xfsbufd_centisec v4.0
+ fs.xfs.age_buffer_centisecs v4.0
+
+
+Error handling
+==============
+
+XFS can act differently according to the type of error found during its
+operation. The implementation introduces the following concepts to the error
+handler:
+
+ -failure speed:
+ Defines how fast XFS should propagate an error upwards when a specific
+ error is found during the filesystem operation. It can propagate
+ immediately, after a defined number of retries, after a set time period,
+ or simply retry forever.
+
+ -error classes:
+ Specifies the subsystem the error configuration will apply to, such as
+ metadata IO or memory allocation. Different subsystems will have
+ different error handlers for which behaviour can be configured.
+
+ -error handlers:
+ Defines the behavior for a specific error.
+
+The filesystem behavior during an error can be set via sysfs files. Each
+error handler works independently - the first condition met by an error handler
+for a specific class will cause the error to be propagated rather than reset and
+retried.
+
+The action taken by the filesystem when the error is propagated is context
+dependent - it may cause a shut down in the case of an unrecoverable error,
+it may be reported back to userspace, or it may even be ignored because
+there's nothing useful we can with the error or anyone we can report it to (e.g.
+during unmount).
+
+The configuration files are organized into the following hierarchy for each
+mounted filesystem:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+Where:
+ <dev>
+ The short device name of the mounted filesystem. This is the same device
+ name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
+
+ <class>
+ The subsystem the error configuration belongs to. As of 4.9, the defined
+ classes are:
+
+ - "metadata": applies metadata buffer write IO
+
+ <error>
+ The individual error handler configurations.
+
+
+Each filesystem has "global" error configuration options defined in their top
+level directory:
+
+ /sys/fs/xfs/<dev>/error/
+
+ fail_at_unmount (Min: 0 Default: 1 Max: 1)
+ Defines the filesystem error behavior at unmount time.
+
+ If set to a value of 1, XFS will override all other error configurations
+ during unmount and replace them with "immediate fail" characteristics.
+ i.e. no retries, no retry timeout. This will always allow unmount to
+ succeed when there are persistent errors present.
+
+ If set to 0, the configured retry behaviour will continue until all
+ retries and/or timeouts have been exhausted. This will delay unmount
+ completion when there are persistent errors, and it may prevent the
+ filesystem from ever unmounting fully in the case of "retry forever"
+ handler configurations.
+
+ Note: there is no guarantee that fail_at_unmount can be set while an
+ unmount is in progress. It is possible that the sysfs entries are
+ removed by the unmounting filesystem before a "retry forever" error
+ handler configuration causes unmount to hang, and hence the filesystem
+ must be configured appropriately before unmount begins to prevent
+ unmount hangs.
+
+Each filesystem has specific error class handlers that define the error
+propagation behaviour for specific errors. There is also a "default" error
+handler defined, which defines the behaviour for all errors that don't have
+specific handlers defined. Where multiple retry constraints are configuredi for
+a single error, the first retry configuration that expires will cause the error
+to be propagated. The handler configurations are found in the directory:
+
+ /sys/fs/xfs/<dev>/error/<class>/<error>/
+
+ max_retries (Min: -1 Default: Varies Max: INTMAX)
+ Defines the allowed number of retries of a specific error before
+ the filesystem will propagate the error. The retry count for a given
+ error context (e.g. a specific metadata buffer) is reset every time
+ there is a successful completion of the operation.
+
+ Setting the value to "-1" will cause XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will make XFS retry the
+ operation "N" times before propagating the error.
+
+ retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
+ Define the amount of time (in seconds) that the filesystem is
+ allowed to retry its operations when the specific error is
+ found.
+
+ Setting the value to "-1" will allow XFS to retry forever for this
+ specific error.
+
+ Setting the value to "0" will cause XFS to fail immediately when the
+ specific error is reported.
+
+ Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
+ operation for up to "N" seconds before propagating the error.
+
+Note: The default behaviour for a specific error handler is dependent on both
+the class and error context. For example, the default values for
+"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
+to "fail immediately" behaviour. This is done because ENODEV is a fatal,
+unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
deleted file mode 100644
index a5cbb5e0e..000000000
--- a/Documentation/filesystems/xfs.txt
+++ /dev/null
@@ -1,470 +0,0 @@
-
-The SGI XFS Filesystem
-======================
-
-XFS is a high performance journaling filesystem which originated
-on the SGI IRIX platform. It is completely multi-threaded, can
-support large files and large filesystems, extended attributes,
-variable block sizes, is extent based, and makes extensive use of
-Btrees (directories, extents, free space) to aid both performance
-and scalability.
-
-Refer to the documentation at https://xfs.wiki.kernel.org/
-for further details. This implementation is on-disk compatible
-with the IRIX version of XFS.
-
-
-Mount Options
-=============
-
-When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
-default behaviour.
-
- allocsize=size
- Sets the buffered I/O end-of-file preallocation size when
- doing delayed allocation writeout (default size is 64KiB).
- Valid values for this option are page size (typically 4KiB)
- through to 1GiB, inclusive, in power-of-2 increments.
-
- The default behaviour is for dynamic end-of-file
- preallocation size, which uses a set of heuristics to
- optimise the preallocation size based on the current
- allocation patterns within the file and the access patterns
- to the file. Specifying a fixed allocsize value turns off
- the dynamic behaviour.
-
- attr2
- noattr2
- The options enable/disable an "opportunistic" improvement to
- be made in the way inline extended attributes are stored
- on-disk. When the new form is used for the first time when
- attr2 is selected (either when setting or removing extended
- attributes) the on-disk superblock feature bit field will be
- updated to reflect this format being in use.
-
- The default behaviour is determined by the on-disk feature
- bit indicating that attr2 behaviour is active. If either
- mount option it set, then that becomes the new default used
- by the filesystem.
-
- CRC enabled filesystems always use the attr2 format, and so
- will reject the noattr2 mount option if it is set.
-
- discard
- nodiscard (*)
- Enable/disable the issuing of commands to let the block
- device reclaim space freed by the filesystem. This is
- useful for SSD devices, thinly provisioned LUNs and virtual
- machine images, but may have a performance impact.
-
- Note: It is currently recommended that you use the fstrim
- application to discard unused blocks rather than the discard
- mount option because the performance impact of this option
- is quite severe.
-
- grpid/bsdgroups
- nogrpid/sysvgroups (*)
- These options define what group ID a newly created file
- gets. When grpid is set, it takes the group ID of the
- directory in which it is created; otherwise it takes the
- fsgid of the current process, unless the directory has the
- setgid bit set, in which case it takes the gid from the
- parent directory, and also gets the setgid bit set if it is
- a directory itself.
-
- filestreams
- Make the data allocator use the filestreams allocation mode
- across the entire filesystem rather than just on directories
- configured to use it.
-
- ikeep
- noikeep (*)
- When ikeep is specified, XFS does not delete empty inode
- clusters and keeps them around on disk. When noikeep is
- specified, empty inode clusters are returned to the free
- space pool.
-
- inode32
- inode64 (*)
- When inode32 is specified, it indicates that XFS limits
- inode creation to locations which will not result in inode
- numbers with more than 32 bits of significance.
-
- When inode64 is specified, it indicates that XFS is allowed
- to create inodes at any location in the filesystem,
- including those which will result in inode numbers occupying
- more than 32 bits of significance.
-
- inode32 is provided for backwards compatibility with older
- systems and applications, since 64 bits inode numbers might
- cause problems for some applications that cannot handle
- large inode numbers. If applications are in use which do
- not handle inode numbers bigger than 32 bits, the inode32
- option should be specified.
-
-
- largeio
- nolargeio (*)
- If "nolargeio" is specified, the optimal I/O reported in
- st_blksize by stat(2) will be as small as possible to allow
- user applications to avoid inefficient read/modify/write
- I/O. This is typically the page size of the machine, as
- this is the granularity of the page cache.
-
- If "largeio" specified, a filesystem that was created with a
- "swidth" specified will return the "swidth" value (in bytes)
- in st_blksize. If the filesystem does not have a "swidth"
- specified but does specify an "allocsize" then "allocsize"
- (in bytes) will be returned instead. Otherwise the behaviour
- is the same as if "nolargeio" was specified.
-
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
- range from 2-8 inclusive.
-
- The default value is 8 buffers.
-
- If the memory cost of 8 log buffers is too high on small
- systems, then it may be reduced at some cost to performance
- on metadata intensive workloads. The logbsize option below
- controls the size of each buffer and so is also relevant to
- this case.
-
- logbsize=value
- Set the size of each in-memory log buffer. The size may be
- specified in bytes, or in kilobytes with a "k" suffix.
- Valid sizes for version 1 and version 2 logs are 16384 (16k)
- and 32768 (32k). Valid sizes for version 2 logs also
- include 65536 (64k), 131072 (128k) and 262144 (256k). The
- logbsize must be an integer multiple of the log
- stripe unit configured at mkfs time.
-
- The default value for for version 1 logs is 32768, while the
- default value for version 2 logs is MAX(32768, log_sunit).
-
- logdev=device and rtdev=device
- Use an external log (metadata journal) and/or real-time device.
- An XFS filesystem has up to three parts: a data section, a log
- section, and a real-time section. The real-time section is
- optional, and the log section can be separate from the data
- section or contained within it.
-
- noalign
- Data allocations will not be aligned at stripe unit
- boundaries. This is only relevant to filesystems created
- with non-zero data alignment parameters (sunit, swidth) by
- mkfs.
-
- norecovery
- The filesystem will be mounted without running log recovery.
- If the filesystem was not cleanly unmounted, it is likely to
- be inconsistent when mounted in "norecovery" mode.
- Some files or directories may not be accessible because of this.
- Filesystems mounted "norecovery" must be mounted read-only or
- the mount will fail.
-
- nouuid
- Don't check for double mounted file systems using the file
- system uuid. This is useful to mount LVM snapshot volumes,
- and often used in combination with "norecovery" for mounting
- read-only snapshots.
-
- noquota
- Forcibly turns off all quota accounting and enforcement
- within the filesystem.
-
- uquota/usrquota/uqnoenforce/quota
- User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- gquota/grpquota/gqnoenforce
- Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- pquota/prjquota/pqnoenforce
- Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
-
- sunit=value and swidth=value
- Used to specify the stripe unit and width for a RAID device
- or a stripe volume. "value" must be specified in 512-byte
- block units. These options are only relevant to filesystems
- that were created with non-zero data alignment parameters.
-
- The sunit and swidth parameters specified must be compatible
- with the existing filesystem alignment characteristics. In
- general, that means the only valid changes to sunit are
- increasing it by a power-of-2 multiple. Valid swidth values
- are any integer multiple of a valid sunit value.
-
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
- modified, such as adding a new disk to a RAID5 lun and
- reshaping it.
-
- swalloc
- Data allocations will be rounded up to stripe width boundaries
- when the current end of file is being extended and the file
- size is larger than the stripe width size.
-
- wsync
- When specified, all filesystem namespace operations are
- executed synchronously. This ensures that when the namespace
- operation (create, unlink, etc) completes, the change to the
- namespace is on stable storage. This is useful in HA setups
- where failover must not result in clients seeing
- inconsistent namespace presentation during or after a
- failover event.
-
-
-Deprecated Mount Options
-========================
-
- Name Removal Schedule
- ---- ----------------
-
-
-Removed Mount Options
-=====================
-
- Name Removed
- ---- -------
- delaylog/nodelaylog v4.0
- ihashsize v4.0
- irixsgid v4.0
- osyncisdsync/osyncisosync v4.0
- barrier v4.19
- nobarrier v4.19
-
-
-sysctls
-=======
-
-The following sysctls are available for the XFS filesystem:
-
- fs.xfs.stats_clear (Min: 0 Default: 0 Max: 1)
- Setting this to "1" clears accumulated XFS statistics
- in /proc/fs/xfs/stat. It then immediately resets to "0".
-
- fs.xfs.xfssyncd_centisecs (Min: 100 Default: 3000 Max: 720000)
- The interval at which the filesystem flushes metadata
- out to disk and runs internal cache cleanup routines.
-
- fs.xfs.filestream_centisecs (Min: 1 Default: 3000 Max: 360000)
- The interval at which the filesystem ages filestreams cache
- references and returns timed-out AGs back to the free stream
- pool.
-
- fs.xfs.speculative_prealloc_lifetime
- (Units: seconds Min: 1 Default: 300 Max: 86400)
- The interval at which the background scanning for inodes
- with unused speculative preallocation runs. The scan
- removes unused preallocation from clean inodes and releases
- the unused space back to the free pool.
-
- fs.xfs.error_level (Min: 0 Default: 3 Max: 11)
- A volume knob for error reporting when internal errors occur.
- This will generate detailed messages & backtraces for filesystem
- shutdowns, for example. Current threshold values are:
-
- XFS_ERRLEVEL_OFF: 0
- XFS_ERRLEVEL_LOW: 1
- XFS_ERRLEVEL_HIGH: 5
-
- fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256)
- Causes certain error conditions to call BUG(). Value is a bitmask;
- OR together the tags which represent errors which should cause panics:
-
- XFS_NO_PTAG 0
- XFS_PTAG_IFLUSH 0x00000001
- XFS_PTAG_LOGRES 0x00000002
- XFS_PTAG_AILDELETE 0x00000004
- XFS_PTAG_ERROR_REPORT 0x00000008
- XFS_PTAG_SHUTDOWN_CORRUPT 0x00000010
- XFS_PTAG_SHUTDOWN_IOERROR 0x00000020
- XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040
- XFS_PTAG_FSBLOCK_ZERO 0x00000080
- XFS_PTAG_VERIFIER_ERROR 0x00000100
-
- This option is intended for debugging only.
-
- fs.xfs.irix_symlink_mode (Min: 0 Default: 0 Max: 1)
- Controls whether symlinks are created with mode 0777 (default)
- or whether their mode is affected by the umask (irix mode).
-
- fs.xfs.irix_sgid_inherit (Min: 0 Default: 0 Max: 1)
- Controls files created in SGID directories.
- If the group ID of the new file does not match the effective group
- ID or one of the supplementary group IDs of the parent dir, the
- ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
- is set.
-
- fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "sync" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodump (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodump" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_noatime (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "noatime" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nosymlinks (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nosymlinks" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.inherit_nodefrag (Min: 0 Default: 1 Max: 1)
- Setting this to "1" will cause the "nodefrag" flag set
- by the xfs_io(8) chattr command on a directory to be
- inherited by files in that directory.
-
- fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
- In "inode32" allocation mode, this option determines how many
- files the allocator attempts to allocate in the same allocation
- group before moving to the next allocation group. The intent
- is to control the rate at which the allocator moves between
- allocation groups when allocating extents for new files.
-
-Deprecated Sysctls
-==================
-
-None at present.
-
-
-Removed Sysctls
-===============
-
- Name Removed
- ---- -------
- fs.xfs.xfsbufd_centisec v4.0
- fs.xfs.age_buffer_centisecs v4.0
-
-
-Error handling
-==============
-
-XFS can act differently according to the type of error found during its
-operation. The implementation introduces the following concepts to the error
-handler:
-
- -failure speed:
- Defines how fast XFS should propagate an error upwards when a specific
- error is found during the filesystem operation. It can propagate
- immediately, after a defined number of retries, after a set time period,
- or simply retry forever.
-
- -error classes:
- Specifies the subsystem the error configuration will apply to, such as
- metadata IO or memory allocation. Different subsystems will have
- different error handlers for which behaviour can be configured.
-
- -error handlers:
- Defines the behavior for a specific error.
-
-The filesystem behavior during an error can be set via sysfs files. Each
-error handler works independently - the first condition met by an error handler
-for a specific class will cause the error to be propagated rather than reset and
-retried.
-
-The action taken by the filesystem when the error is propagated is context
-dependent - it may cause a shut down in the case of an unrecoverable error,
-it may be reported back to userspace, or it may even be ignored because
-there's nothing useful we can with the error or anyone we can report it to (e.g.
-during unmount).
-
-The configuration files are organized into the following hierarchy for each
-mounted filesystem:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
-Where:
- <dev>
- The short device name of the mounted filesystem. This is the same device
- name that shows up in XFS kernel error messages as "XFS(<dev>): ..."
-
- <class>
- The subsystem the error configuration belongs to. As of 4.9, the defined
- classes are:
-
- - "metadata": applies metadata buffer write IO
-
- <error>
- The individual error handler configurations.
-
-
-Each filesystem has "global" error configuration options defined in their top
-level directory:
-
- /sys/fs/xfs/<dev>/error/
-
- fail_at_unmount (Min: 0 Default: 1 Max: 1)
- Defines the filesystem error behavior at unmount time.
-
- If set to a value of 1, XFS will override all other error configurations
- during unmount and replace them with "immediate fail" characteristics.
- i.e. no retries, no retry timeout. This will always allow unmount to
- succeed when there are persistent errors present.
-
- If set to 0, the configured retry behaviour will continue until all
- retries and/or timeouts have been exhausted. This will delay unmount
- completion when there are persistent errors, and it may prevent the
- filesystem from ever unmounting fully in the case of "retry forever"
- handler configurations.
-
- Note: there is no guarantee that fail_at_unmount can be set while an
- unmount is in progress. It is possible that the sysfs entries are
- removed by the unmounting filesystem before a "retry forever" error
- handler configuration causes unmount to hang, and hence the filesystem
- must be configured appropriately before unmount begins to prevent
- unmount hangs.
-
-Each filesystem has specific error class handlers that define the error
-propagation behaviour for specific errors. There is also a "default" error
-handler defined, which defines the behaviour for all errors that don't have
-specific handlers defined. Where multiple retry constraints are configuredi for
-a single error, the first retry configuration that expires will cause the error
-to be propagated. The handler configurations are found in the directory:
-
- /sys/fs/xfs/<dev>/error/<class>/<error>/
-
- max_retries (Min: -1 Default: Varies Max: INTMAX)
- Defines the allowed number of retries of a specific error before
- the filesystem will propagate the error. The retry count for a given
- error context (e.g. a specific metadata buffer) is reset every time
- there is a successful completion of the operation.
-
- Setting the value to "-1" will cause XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will make XFS retry the
- operation "N" times before propagating the error.
-
- retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day)
- Define the amount of time (in seconds) that the filesystem is
- allowed to retry its operations when the specific error is
- found.
-
- Setting the value to "-1" will allow XFS to retry forever for this
- specific error.
-
- Setting the value to "0" will cause XFS to fail immediately when the
- specific error is reported.
-
- Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the
- operation for up to "N" seconds before propagating the error.
-
-Note: The default behaviour for a specific error handler is dependent on both
-the class and error context. For example, the default values for
-"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults
-to "fail immediately" behaviour. This is done because ENODEV is a fatal,
-unrecoverable error no matter how many times the metadata IO is retried.
diff --git a/MAINTAINERS b/MAINTAINERS
index d0ed73599..66e972e9a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -17364,7 +17364,7 @@ L: linux-xfs@vger.kernel.org
W: http://xfs.org/
T: git git://git.kernel.org/pub/scm/fs/xfs/xfs-linux.git
S: Supported
-F: Documentation/filesystems/xfs.txt
+F: Documentation/filesystems/xfs.rst
F: fs/xfs/
XILINX AXI ETHERNET DRIVER
--
2.22.0
^ permalink raw reply related
* Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Mauro Carvalho Chehab @ 2019-06-29 14:50 UTC (permalink / raw)
To: Vandana BN
Cc: Yoshinori Sato, Rich Felker, Jonathan Corbet, linux-sh, linux-doc,
linux-kernel, skhan, gregkh, linux-kernel-mentees
In-Reply-To: <20190629143245.3580-1-bnvandana@gmail.com>
Em Sat, 29 Jun 2019 20:02:45 +0530
Vandana BN <bnvandana@gmail.com> escreveu:
> This patch converts new-machine.txt and register-banks.txt
> to ReST format, No content change.
> Added interfaces.rst to contain kernel-doc markups from index.rst
> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
> Added SPDX tag in index.rst
>
> Signed-off-by: Vandana BN <bnvandana@gmail.com>
Looks good to me. Just a final thing to do.
Be sure to run:
./scripts/documentation-file-ref-check
in order to check that you're not breaking any references to the file.
If it breaks, please adjust the reference to reflect the file
rename.
After fixing the broken reference, feel free do add:
Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> Documentation/sh/index.rst | 65 +------
> Documentation/sh/interface.rst | 59 ++++++
> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
> ...{register-banks.txt => register-banks.rst} | 8 +-
> 4 files changed, 163 insertions(+), 140 deletions(-)
> create mode 100644 Documentation/sh/interface.rst
> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>
> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
> index bc8db7ba894a..fec3c405b6b9 100644
> --- a/Documentation/sh/index.rst
> +++ b/Documentation/sh/index.rst
> @@ -1,59 +1,14 @@
> -=======================
> -SuperH Interfaces Guide
> -=======================
> +.. SPDX-License-Identifier: GPL-2.0
>
> -:Author: Paul Mundt
> -
> -Memory Management
> -=================
> -
> -SH-4
> -----
> -
> -Store Queue API
> -~~~~~~~~~~~~~~~
> -
> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> - :export:
> -
> -SH-5
> -----
> -
> -TLB Interfaces
> -~~~~~~~~~~~~~~
> -
> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> - :internal:
> -
> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> - :internal:
> +====================
> +SuperH Documentation
> +====================
>
> -Machine Specific Interfaces
> -===========================
> -
> -mach-dreamcast
> ---------------
> -
> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> - :internal:
> -
> -mach-x3proto
> -------------
> -
> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> - :export:
> -
> -Busses
> -======
> -
> -SuperHyway
> -----------
> -
> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> - :export:
> +:Author: Paul Mundt
>
> -Maple
> ------
> +.. toctree::
> + :maxdepth: 2
>
> -.. kernel-doc:: drivers/sh/maple/maple.c
> - :export:
> + interface
> + new-machine
> + register-banks
> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
> new file mode 100644
> index 000000000000..bc8db7ba894a
> --- /dev/null
> +++ b/Documentation/sh/interface.rst
> @@ -0,0 +1,59 @@
> +=======================
> +SuperH Interfaces Guide
> +=======================
> +
> +:Author: Paul Mundt
> +
> +Memory Management
> +=================
> +
> +SH-4
> +----
> +
> +Store Queue API
> +~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
> + :export:
> +
> +SH-5
> +----
> +
> +TLB Interfaces
> +~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
> + :internal:
> +
> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
> + :internal:
> +
> +Machine Specific Interfaces
> +===========================
> +
> +mach-dreamcast
> +--------------
> +
> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
> + :internal:
> +
> +mach-x3proto
> +------------
> +
> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
> + :export:
> +
> +Busses
> +======
> +
> +SuperHyway
> +----------
> +
> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
> + :export:
> +
> +Maple
> +-----
> +
> +.. kernel-doc:: drivers/sh/maple/maple.c
> + :export:
> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
> similarity index 79%
> rename from Documentation/sh/new-machine.txt
> rename to Documentation/sh/new-machine.rst
> index e0961a66130b..b16c33342642 100644
> --- a/Documentation/sh/new-machine.txt
> +++ b/Documentation/sh/new-machine.rst
> @@ -1,8 +1,8 @@
> +================================
> +Adding a new board to LinuxSH
> +================================
>
> - Adding a new board to LinuxSH
> - ================================
> -
> - Paul Mundt <lethal@linux-sh.org>
> +Paul Mundt <lethal@linux-sh.org>
>
> This document attempts to outline what steps are necessary to add support
> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
> companion chip type, and CPU type. Looking at a tree view of this directory
> hierarchy looks like the following:
>
> -Board-specific code:
> -
> -.
> -|-- arch
> -| `-- sh
> -| `-- boards
> -| |-- adx
> -| | `-- board-specific files
> -| |-- bigsur
> -| | `-- board-specific files
> -| |
> -| ... more boards here ...
> -|
> -`-- include
> - `-- asm-sh
> - |-- adx
> - | `-- board-specific headers
> - |-- bigsur
> - | `-- board-specific headers
> - |
> - .. more boards here ...
> -
> -Next, for companion chips:
> -.
> -`-- arch
> - `-- sh
> - `-- cchips
> - `-- hd6446x
> - `-- hd64461
> - `-- cchip-specific files
> +Board-specific code::
> +
> + .
> + |-- arch
> + | `-- sh
> + | `-- boards
> + | |-- adx
> + | | `-- board-specific files
> + | |-- bigsur
> + | | `-- board-specific files
> + | |
> + | ... more boards here ...
> + |
> + `-- include
> + `-- asm-sh
> + |-- adx
> + | `-- board-specific headers
> + |-- bigsur
> + | `-- board-specific headers
> + |
> + .. more boards here ...
> +
> +Next, for companion chips::
> +
> + .
> + `-- arch
> + `-- sh
> + `-- cchips
> + `-- hd6446x
> + `-- hd64461
> + `-- cchip-specific files
>
> ... and so on. Headers for the companion chips are treated the same way as
> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
> hd64461-specific headers.
>
> -Finally, CPU family support is also abstracted:
> -.
> -|-- arch
> -| `-- sh
> -| |-- kernel
> -| | `-- cpu
> -| | |-- sh2
> -| | | `-- SH-2 generic files
> -| | |-- sh3
> -| | | `-- SH-3 generic files
> -| | `-- sh4
> -| | `-- SH-4 generic files
> -| `-- mm
> -| `-- This is also broken out per CPU family, so each family can
> -| have their own set of cache/tlb functions.
> -|
> -`-- include
> - `-- asm-sh
> - |-- cpu-sh2
> - | `-- SH-2 specific headers
> - |-- cpu-sh3
> - | `-- SH-3 specific headers
> - `-- cpu-sh4
> - `-- SH-4 specific headers
> +Finally, CPU family support is also abstracted::
> +
> + .
> + |-- arch
> + | `-- sh
> + | |-- kernel
> + | | `-- cpu
> + | | |-- sh2
> + | | | `-- SH-2 generic files
> + | | |-- sh3
> + | | | `-- SH-3 generic files
> + | | `-- sh4
> + | | `-- SH-4 generic files
> + | `-- mm
> + | `-- This is also broken out per CPU family, so each family can
> + | have their own set of cache/tlb functions.
> + |
> + `-- include
> + `-- asm-sh
> + |-- cpu-sh2
> + | `-- SH-2 specific headers
> + |-- cpu-sh3
> + | `-- SH-3 specific headers
> + `-- cpu-sh4
> + `-- SH-4 specific headers
>
> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
> need to be dealt with by the CPU family specific code.
> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
> get_system_type() and platform_setup(). For our imaginary board, this
> might look something like:
>
> -/*
> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> - */
> -#include <linux/init.h>
> +.. code-block:: c
> +
> + /*
> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
> + */
> + #include <linux/init.h>
>
> -const char *get_system_type(void)
> -{
> - return "FooTech Vaporboard";
> -}
> + const char *get_system_type(void)
> + {
> + return "FooTech Vaporboard";
> + }
>
> -int __init platform_setup(void)
> -{
> + int __init platform_setup(void)
> + {
> /*
> * If our hardware actually existed, we would do real
> * setup here. Though it's also sane to leave this empty
> @@ -136,7 +140,8 @@ int __init platform_setup(void)
> /* And whatever else ... */
>
> return 0;
> -}
> + }
> +
>
> Our new imaginary board will also have to tie into the machvec in order for it
> to be of any use.
> @@ -172,16 +177,17 @@ sufficient.
> vector.
>
> Note that these prototypes are generated automatically by setting
> - __IO_PREFIX to something sensible. A typical example would be:
> + __IO_PREFIX to something sensible. A typical example would be::
>
> #define __IO_PREFIX vapor
> #include <asm/io_generic.h>
>
> +
> somewhere in the board-specific header. Any boards being ported that still
> have a legacy io.h should remove it entirely and switch to the new model.
>
> - Add machine vector definitions to the board's setup.c. At a bare minimum,
> - this must be defined as something like:
> + this must be defined as something like::
>
> struct sh_machine_vector mv_vapor __initmv = {
> .mv_name = "vapor",
> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
> require the proper entry here and there in order to get things done.
>
> The first thing to do is to add an entry to arch/sh/Kconfig, under the
> -"System type" menu:
> +"System type" menu::
>
> -config SH_VAPOR
> - bool "Vapor"
> - help
> + config SH_VAPOR
> + bool "Vapor"
> + help
> select Vapor if configuring for a FooTech Vaporboard.
>
> next, this has to be added into arch/sh/Makefile. All boards require a
> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
> implicit checks for your board if you need this somewhere throughout the
> common code, such as:
>
> +::
> +
> /* Make sure we're on the FooTech Vaporboard */
> if (!mach_is_vapor())
> return -ENODEV;
> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
> Looking at the 'make help' output, you should now see something like:
>
> Architecture specific targets (sh):
> - zImage - Compressed kernel image (arch/sh/boot/zImage)
> - adx_defconfig - Build for adx
> - cqreek_defconfig - Build for cqreek
> - dreamcast_defconfig - Build for dreamcast
> -...
> - vapor_defconfig - Build for vapor
> +
> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
> + - adx_defconfig - Build for adx
> + - cqreek_defconfig - Build for cqreek
> + - dreamcast_defconfig - Build for dreamcast
> + - ...
> + - vapor_defconfig - Build for vapor
>
> which then allows you to do:
>
> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
> similarity index 90%
> rename from Documentation/sh/register-banks.txt
> rename to Documentation/sh/register-banks.rst
> index a6719f2f6594..acccfaf80355 100644
> --- a/Documentation/sh/register-banks.txt
> +++ b/Documentation/sh/register-banks.rst
> @@ -1,8 +1,9 @@
> - Notes on register bank usage in the kernel
> - ==========================================
> +==========================================
> +Notes on register bank usage in the kernel
> +==========================================
>
> Introduction
> -------------
> +============
>
> The SH-3 and SH-4 CPU families traditionally include a single partial register
> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
> - The SR.IMASK interrupt handler makes use of this to set the
> interrupt priority level (used by local_irq_enable())
> - r7_bank (current)
> -
> --
> 2.17.1
>
Thanks,
Mauro
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox