* 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
* [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.
From: Vandana BN @ 2019-06-29 14:32 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
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 +-
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
^ permalink raw reply related
* Re: [PATCH 00/10] Intel(R) Speed Select Technology
From: Andy Shevchenko @ 2019-06-29 14:29 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: <20190626223851.19138-1-srinivas.pandruvada@linux.intel.com>
On Thu, Jun 27, 2019 at 1:39 AM Srinivas Pandruvada
<srinivas.pandruvada@linux.intel.com> wrote:
>
> Intel® Speed Select Technology (Intel® SST) — A powerful new collection of
> features giving more granular control over CPU performance for optimized total
> cost of ownership and performance. With Intel® SST, one server can be configured
> for power and performance for variety of diverse workload requirements. In the
> Linux submission code. we are using ISST to specify Intel® SST to avoid confusion
> with existing use of SST for "Smart Sound Technology".
>
> Refer to these links for overview of the technology released with some Intel® Xeon®
> Scalable processor (5218N, 6230N, and 6252N):
> https://www.intel.com/content/www/us/en/architecture-and-technology/speed-select-technology-article.html
> https://builders.intel.com/docs/networkbuilders/intel-speed-select-technology-base-frequency-enhancing-performance.pdf
>
> The next generation of Intel® Xeon® processors are adding more features to the
> Intel® Speed Select Technology and allow dynamic configuration of these features
> from OS-software level instead from BIOS. This submission is adding new features
> and dynamic configuration capabilities .
>
>
> Intel SST Features:
>
> Intel® SST—Performance Profile (PP or perf-profile):
> This feature allows one server to be configured for different workload requirements
> instead of deploying different servers based on the workload requirement reducing total
> cost of ownership. With a single server deployed, the same server can be reconfigured
> dynamically to one of the supported profiles to suit the specific workload requirements.
> This feature introduces a mechanism that allows multiple optimized performance profiles
> per system via static and/or dynamic adjustment of TDP level and other performance
> parameters.
>
> Intel® SST—Core power (CP or core-power):
> An Interface that allows user to define per core priority. This defines a mechanism
> to distribute power among cores when there is a power constrained scenario. This defines
> a class of service configuration. Each CPU core can be tied to a class of service and hence
> an associated priority.
>
> Intel® SST—Base Frequency (BF or base-freq):
> The Intel® SST-BF feature lets user control and direct base frequency. If some critical
> workload threads demand constant high guaranteed performance, then this feature can be
> used to execute the thread at higher base frequency on specific set of CPUs.
>
> Intel® SST—Turbo frequency (TF or turbo-freq):
> Enables the ability to set different all core turbo ratio limits to cores based on the priority.
> Using this features some cores can be configured to get higher turbo frequency by designating
> them as high priority at the cost of lower or no turbo frequency on the low priority cores.
>
> Implementation
>
> The Intel® SST features are implemented in the firmware executing in the the power
> management unit (we are calling PUNIT here for short). The mechanism to control these
> features are specific to firmware implementation for Intel® Xeon® CPUs and are not architectural
> features. The interface mechanism and semantics of the messages can change in future Xeon
> CPUs. Hence there is minimal kernel implementation by offering direct communication
> to PUNIT via set of IOCTLs. The actual messages which can be sent to PUNIT are specified
> in the following document link:
>
> https://github.com/intel/CommsPowerManagement/blob/master/intel_sst_os_interface/mailbox.md
>
> The idea here is that user space software like cloud orchestration software based on their workload
> requirement configure the system. There is a full featured "Intel Speed Select" utility
> submitted to kernel power tools, which can be used to validate and exercise the features.
>
> Types of PUNIT interfaces
> There are two types of interfaces. One using Mail box communications, which is facilitated
> by a PCI device or in some Xeon® CPUs using MSRs; and other using an MMIO interface, which is
> used primarily for core prioritization. For hiding details a single character device is created
> to handle IOCTLs. The following block diagram shows the implementation overview.
>
>
> User User Space tool(intel-speed-select)/Cloud Orchestration software
> IOCTLs
> ---------------------------------------character device------------------------------
> kernel Common driver handling IOCTLs
> Mail Box drivers(PCI & MSR) PCI MMIO driver
> --------------------------------------------------------------------------
> Hardware PUNIT
>
>
>
Pushed to my review and testing queue, thanks!
> Srinivas Pandruvada (10):
> platform/x86: ISST: Update ioctl-number.txt for Intel Speed Select
> interface
> platform/x86: ISST: Add common API to register and handle ioctls
> platform/x86: ISST: Store per CPU information
> platform/x86: ISST: Add IOCTL to Translate Linux logical CPU to PUNIT
> CPU number
> platform/x86: ISST: Add Intel Speed Select mmio interface
> platform/x86: ISST: Add Intel Speed Select mailbox interface via PCI
> platform/x86: ISST: Add Intel Speed Select mailbox interface via MSRs
> platform/x86: ISST: Add Intel Speed Select PUNIT MSR interface
> platform/x86: ISST: Restore state on resume
> tools/power/x86: A tool to validate Intel Speed Select commands
>
> Documentation/ioctl/ioctl-number.txt | 1 +
> drivers/platform/x86/Kconfig | 2 +
> drivers/platform/x86/Makefile | 1 +
> .../x86/intel_speed_select_if/Kconfig | 17 +
> .../x86/intel_speed_select_if/Makefile | 10 +
> .../intel_speed_select_if/isst_if_common.c | 672 +++++++
> .../intel_speed_select_if/isst_if_common.h | 69 +
> .../intel_speed_select_if/isst_if_mbox_msr.c | 216 +++
> .../intel_speed_select_if/isst_if_mbox_pci.c | 214 +++
> .../x86/intel_speed_select_if/isst_if_mmio.c | 180 ++
> include/uapi/linux/isst_if.h | 172 ++
> tools/power/x86/intel_speed_select/Makefile | 31 +
> tools/power/x86/intel_speed_select/isst.h | 231 +++
> .../x86/intel_speed_select/isst_config.c | 1607 +++++++++++++++++
> .../power/x86/intel_speed_select/isst_core.c | 721 ++++++++
> .../x86/intel_speed_select/isst_display.c | 479 +++++
> 16 files changed, 4623 insertions(+)
> create mode 100644 drivers/platform/x86/intel_speed_select_if/Kconfig
> create mode 100644 drivers/platform/x86/intel_speed_select_if/Makefile
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_common.c
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_common.h
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_mbox_msr.c
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_mbox_pci.c
> create mode 100644 drivers/platform/x86/intel_speed_select_if/isst_if_mmio.c
> create mode 100644 include/uapi/linux/isst_if.h
> create mode 100644 tools/power/x86/intel_speed_select/Makefile
> create mode 100644 tools/power/x86/intel_speed_select/isst.h
> create mode 100644 tools/power/x86/intel_speed_select/isst_config.c
> create mode 100644 tools/power/x86/intel_speed_select/isst_core.c
> create mode 100644 tools/power/x86/intel_speed_select/isst_display.c
>
> --
> 2.17.2
>
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Wolfram Sang @ 2019-06-29 10:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Rudolf Marek,
Seth Heasley, Neil Horman, Vadim Pasternak, Michael Shych,
Ajay Gupta, Peter Korsgaard, Andrew Lunn, Jim Cromie, Mark Brown,
Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, Alessandro Zummo, Alexandre Belloni,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <3997b54a2e73887b96ec665573f08ded78b71421.1561756511.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 595 bytes --]
On Fri, Jun 28, 2019 at 06:23:14PM -0300, Mauro Carvalho Chehab wrote:
> Convert each file at I2C subsystem, renaming them to .rst and
> adding to the driver-api book.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
I glimpsed over it and it looks basically OK. I won't have time to
actually review all of this. But I trust you and we can fix things
later. So:
Acked-by: Wolfram Sang <wsa@the-dreams.de>
I assume this goes in via your or doc-tree?
> Next/merge.log | 6 +-
This file doesn't exist upstream, though.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* Re: [PATCH] docs: packing: move it to core-api book and adjust markups
From: Mike Rapoport @ 2019-06-29 10:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vladimir Oltean, Mike Rapoport, Andrew Morton,
Randy Dunlap, Matthew Wilcox, Kent Overstreet, Arnd Bergmann,
Jonathan Neuschäfer, David S. Miller, netdev
In-Reply-To: <46cb79dbc4bbff3e5a4e77b548df1e92c105ed0f.1561804613.git.mchehab+samsung@kernel.org>
On Sat, Jun 29, 2019 at 07:37:02AM -0300, Mauro Carvalho Chehab wrote:
> The packing.txt file was misplaced, as docs should be part of
> a documentation book, and not at the root dir.
>
> So, move it to the core-api directory and add to its index.
>
> Also, ensure that the file will be properly parsed and the bitmap
> ascii artwork will use a monotonic font.
>
> Fixes: 554aae35007e ("lib: Add support for generic packing operations")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> Documentation/core-api/index.rst | 1 +
> .../{packing.txt => core-api/packing.rst} | 81 +++++++++++--------
> 2 files changed, 50 insertions(+), 32 deletions(-)
> rename Documentation/{packing.txt => core-api/packing.rst} (61%)
>
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index d1e5b95bf86d..aebb16d7771f 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -25,6 +25,7 @@ Core utilities
> librs
> genalloc
> errseq
> + packing
> printk-formats
> circular-buffers
> generic-radix-tree
> diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
> similarity index 61%
> rename from Documentation/packing.txt
> rename to Documentation/core-api/packing.rst
> index f830c98645f1..d8c341fe383e 100644
> --- a/Documentation/packing.txt
> +++ b/Documentation/core-api/packing.rst
> @@ -30,6 +30,7 @@ The solution
> ------------
>
> This API deals with 2 basic operations:
> +
> - Packing a CPU-usable number into a memory buffer (with hardware
> constraints/quirks)
> - Unpacking a memory buffer (which has hardware constraints/quirks)
> @@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
>
> 1. Normally (no quirks), we would do it like this:
>
> -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> -7 6 5 4
> -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> -3 2 1 0
> +::
> +
> + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> + 7 6 5 4
> + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> + 3 2 1 0
>
> That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
> LSByte (0) of the u64 sits at memory offset 7.
> @@ -63,10 +66,12 @@ comments as "logical" notation.
>
> 2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
>
> -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> -7 6 5 4
> -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> -3 2 1 0
> +::
> +
> + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> + 7 6 5 4
> + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> + 3 2 1 0
>
> That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
> inverts bit offsets inside a byte.
> @@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
>
> 3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
>
> -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> -4 5 6 7
> -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> -0 1 2 3
> +::
> +
> + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> + 4 5 6 7
> + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> + 0 1 2 3
>
> Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
> byte from each 4-byte word is placed at its mirrored position compared to
> @@ -86,18 +93,22 @@ the boundary of that word.
> 4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
> like this:
>
> -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> -4 5 6 7
> -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> -0 1 2 3
> +::
> +
> + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> + 4 5 6 7
> + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> + 0 1 2 3
>
>
> 5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
>
> -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> -3 2 1 0
> -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> -7 6 5 4
> +::
> +
> + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
> + 3 2 1 0
> + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
> + 7 6 5 4
>
> In this case the 8 byte memory region is interpreted as follows: first
> 4 bytes correspond to the least significant 4-byte word, next 4 bytes to
> @@ -107,28 +118,34 @@ the more significant 4-byte word.
> 6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
> this:
>
> -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> -3 2 1 0
> -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> -7 6 5 4
> +::
> +
> + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
> + 3 2 1 0
> + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
> + 7 6 5 4
>
>
> 7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
> this:
>
> -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> -0 1 2 3
> -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> -4 5 6 7
> +::
> +
> + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
> + 0 1 2 3
> + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
> + 4 5 6 7
>
>
> 8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
> are set, it looks like this:
>
> -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> -0 1 2 3
> -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> -4 5 6 7
> +::
> +
> + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
> + 0 1 2 3
> + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
> + 4 5 6 7
>
>
> We always think of our offsets as if there were no quirk, and we translate
> --
> 2.21.0
>
--
Sincerely yours,
Mike.
^ permalink raw reply
* [PATCH] docs: packing: move it to core-api book and adjust markups
From: Mauro Carvalho Chehab @ 2019-06-29 10:37 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Vladimir Oltean, Mike Rapoport, Andrew Morton,
Randy Dunlap, Matthew Wilcox, Kent Overstreet, Arnd Bergmann,
Jonathan Neuschäfer, David S. Miller, netdev
The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.
So, move it to the core-api directory and add to its index.
Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.
Fixes: 554aae35007e ("lib: Add support for generic packing operations")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/core-api/index.rst | 1 +
.../{packing.txt => core-api/packing.rst} | 81 +++++++++++--------
2 files changed, 50 insertions(+), 32 deletions(-)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index d1e5b95bf86d..aebb16d7771f 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@ Core utilities
librs
genalloc
errseq
+ packing
printk-formats
circular-buffers
generic-radix-tree
diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
similarity index 61%
rename from Documentation/packing.txt
rename to Documentation/core-api/packing.rst
index f830c98645f1..d8c341fe383e 100644
--- a/Documentation/packing.txt
+++ b/Documentation/core-api/packing.rst
@@ -30,6 +30,7 @@ The solution
------------
This API deals with 2 basic operations:
+
- Packing a CPU-usable number into a memory buffer (with hardware
constraints/quirks)
- Unpacking a memory buffer (which has hardware constraints/quirks)
@@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
1. Normally (no quirks), we would do it like this:
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
+::
+
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
LSByte (0) of the u64 sits at memory offset 7.
@@ -63,10 +66,12 @@ comments as "logical" notation.
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
+::
+
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
inverts bit offsets inside a byte.
@@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
+::
+
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
byte from each 4-byte word is placed at its mirrored position compared to
@@ -86,18 +93,22 @@ the boundary of that word.
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
like this:
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
+::
+
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
+::
+
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
In this case the 8 byte memory region is interpreted as follows: first
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@@ -107,28 +118,34 @@ the more significant 4-byte word.
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
this:
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
+::
+
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
this:
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
+::
+
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
are set, it looks like this:
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
+::
+
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
We always think of our offsets as if there were no quirk, and we translate
--
2.21.0
^ permalink raw reply related
* [PATCH] docs: ipmb: place it at driver-api and convert to ReST
From: Mauro Carvalho Chehab @ 2019-06-29 10:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Greg Kroah-Hartman, Randy Dunlap,
Rafael J. Wysocki, Logan Gunthorpe, Asmaa Mnebhi, Corey Minyard,
vadimp
No new doc should be added at the main Documentation/ directory.
Instead, new docs should be added as ReST files, within the
Kernel documentation body.
Fixes: 51bd6f291583 ("Add support for IPMB driver")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
.../{IPMB.txt => driver-api/ipmb.rst} | 62 ++++++++++---------
2 files changed, 33 insertions(+), 30 deletions(-)
rename Documentation/{IPMB.txt => driver-api/ipmb.rst} (71%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index e33849b948c7..e49c34bf16c0 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -75,6 +75,7 @@ available subsections can be seen below.
dell_rbu
edid
eisa
+ ipmb
isa
isapnp
generic-counter
diff --git a/Documentation/IPMB.txt b/Documentation/driver-api/ipmb.rst
similarity index 71%
rename from Documentation/IPMB.txt
rename to Documentation/driver-api/ipmb.rst
index cd20c9764705..3ec3baed84c4 100644
--- a/Documentation/IPMB.txt
+++ b/Documentation/driver-api/ipmb.rst
@@ -32,11 +32,11 @@ This driver works with the I2C driver and a userspace
program such as OpenIPMI:
1) It is an I2C slave backend driver. So, it defines a callback
-function to set the Satellite MC as an I2C slave.
-This callback function handles the received IPMI requests.
+ function to set the Satellite MC as an I2C slave.
+ This callback function handles the received IPMI requests.
2) It defines the read and write functions to enable a user
-space program (such as OpenIPMI) to communicate with the kernel.
+ space program (such as OpenIPMI) to communicate with the kernel.
Load the IPMB driver
@@ -48,34 +48,35 @@ CONFIG_IPMB_DEVICE_INTERFACE=y
1) If you want the driver to be loaded at boot time:
-a) Add this entry to your ACPI table, under the appropriate SMBus:
+a) Add this entry to your ACPI table, under the appropriate SMBus::
-Device (SMB0) // Example SMBus host controller
-{
- Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
- Name (_UID, 0) // Unique ID of particular host controller
- :
- :
- Device (IPMB)
- {
- Name (_HID, "IPMB0001") // IPMB device interface
- Name (_UID, 0) // Unique device identifier
- }
-}
+ Device (SMB0) // Example SMBus host controller
+ {
+ Name (_HID, "<Vendor-Specific HID>") // Vendor-Specific HID
+ Name (_UID, 0) // Unique ID of particular host controller
+ :
+ :
+ Device (IPMB)
+ {
+ Name (_HID, "IPMB0001") // IPMB device interface
+ Name (_UID, 0) // Unique device identifier
+ }
+ }
-b) Example for device tree:
+b) Example for device tree::
-&i2c2 {
- status = "okay";
+ &i2c2 {
+ status = "okay";
- ipmb@10 {
- compatible = "ipmb-dev";
- reg = <0x10>;
- };
-};
+ ipmb@10 {
+ compatible = "ipmb-dev";
+ reg = <0x10>;
+ };
+ };
-2) Manually from Linux:
-modprobe ipmb-dev-int
+2) Manually from Linux::
+
+ modprobe ipmb-dev-int
Instantiate the device
@@ -86,15 +87,16 @@ described in 'Documentation/i2c/instantiating-devices.rst'.
If you have multiple BMCs, each connected to your Satellite MC via
a different I2C bus, you can instantiate a device for each of
those BMCs.
+
The name of the instantiated device contains the I2C bus number
-associated with it as follows:
+associated with it as follows::
-BMC1 ------ IPMB/I2C bus 1 ---------| /dev/ipmb-1
+ BMC1 ------ IPMB/I2C bus 1 ---------| /dev/ipmb-1
Satellite MC
-BMC1 ------ IPMB/I2C bus 2 ---------| /dev/ipmb-2
+ BMC1 ------ IPMB/I2C bus 2 ---------| /dev/ipmb-2
For instance, you can instantiate the ipmb-dev-int device from
-user space at the 7 bit address 0x10 on bus 2:
+user space at the 7 bit address 0x10 on bus 2::
# echo ipmb-dev 0x1010 > /sys/bus/i2c/devices/i2c-2/new_device
--
2.21.0
^ permalink raw reply related
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Matthew Wilcox @ 2019-06-29 1:41 UTC (permalink / raw)
To: Sheriff Esseson
Cc: skhan, corbet, linux-doc, linux-kernel, linux-xfs,
linux-kernel-mentees
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.
Don't quote the entire previous patch when submitting a new one.
> Rid Documentation/filesystems/index.rst of ".rst" in toc-tree references.
>
> CC xfs-list.
>
> Correct email indentation.
This text should be below the --- line, and it should be marked as "v2:"
And you didn't update the MAINTAINERS file.
> +For boolean mount options, the names with the "(*)" prefix is the
> +default behaviour. For example, take an behaviour enabled by default to be a one (1) or,
This line is too long. Doesn't checkpatch.pl complain?
> + 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.
Darrick mentioned the indentation was weird here, and you haven't fixed that.
> + 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
line length
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-29 1:25 UTC (permalink / raw)
To: skhan
Cc: skhan, corbet, linux-doc, linux-kernel, linux-xfs,
linux-kernel-mentees
In-Reply-To: <20190628214302.GA12096@localhost>
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>
> ---
> Documentation/filesystems/index.rst | 1 +
> .../filesystems/{xfs.txt => xfs.rst} | 190 ++++++++++--------
> 2 files changed, 103 insertions(+), 88 deletions(-)
> rename Documentation/filesystems/{xfs.txt => xfs.rst} (74%)
>
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index 1131c34d7..be91fe616 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
> :maxdepth: 2
>
> binderfs.rst
> + xfs.rst
> diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
> similarity index 74%
> rename from Documentation/filesystems/xfs.txt
> rename to Documentation/filesystems/xfs.rst
> index a5cbb5e0e..5e29e1583 100644
> --- a/Documentation/filesystems/xfs.txt
> +++ b/Documentation/filesystems/xfs.rst
> @@ -1,4 +1,4 @@
> -
> +======================
> The SGI XFS Filesystem
> ======================
>
> @@ -18,10 +18,10 @@ Mount Options
> =============
>
> When mounting an XFS filesystem, the following options are accepted.
> -For boolean mount options, the names with the (*) suffix is the
> +For boolean mount options, the names with the "(*)" prefix is the
> default behaviour.
>
> - allocsize=size
> + 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)
> @@ -34,181 +34,195 @@ default behaviour.
> to the file. Specifying a fixed allocsize value turns off
> the dynamic behaviour.
>
> - attr2
> - noattr2
> + [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
> + ``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.
> + bit indicating that ``attr2`` behaviour is active. If either
> + mount options 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.
>
> - discard
> - nodiscard (*)
> + (*)[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
> + 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 (*)
> + 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
> + 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
> + ``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
> + 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
> + (*)[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
> + 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
> + 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.
> + more than 32 bits of significance.
>
> - inode32 is provided for backwards compatibility with older
> + ``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
> + 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
> + (*)[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" 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"
> + 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.
> + is the same as if ``nolargeio`` was specified.
>
> - logbufs=value
> - Set the number of in-memory log buffers. Valid numbers
> + 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
> + 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.
> + 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.
> + ``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).
> + 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.
> + logdev=<device>
> + Use ``device`` as an external log.
> + In an XFS filesystem, the log section can be separate from
> + the data section or contained within it.
>
> - noalign
> + 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
> + 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.
> + 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
> + Filesystems mounted ``norecovery`` must be mounted read-only or
> the mount will fail.
>
> - nouuid
> + 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
> + and often used in combination with ``norecovery`` for mounting
> read-only snapshots.
>
> - noquota
> + noquota
> Forcibly turns off all quota accounting and enforcement
> within the filesystem.
>
> - uquota/usrquota/uqnoenforce/quota
> + uquota/usrquota/uqnoenforce/quota
> User disk quota accounting enabled, and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + enforced. Refer to **xfs_quota(8)** for further details.
>
> - gquota/grpquota/gqnoenforce
> + gquota/grpquota/gqnoenforce
> Group disk quota accounting enabled and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + enforced. Refer to **xfs_quota(8)** for further details.
>
> - pquota/prjquota/pqnoenforce
> + pquota/prjquota/pqnoenforce
> Project disk quota accounting enabled and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + 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
> + 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 and swidth parameters specified must be compatible
> + 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. Valid swidth values
> - are any integer multiple of a valid sunit value.
> + general, that means the only valid changes to ``sunit`` are
> + increasing it by a power-of-2 multiple.
>
> - Typically the only time these mount options are necessary if
> - after an underlying RAID device has had it's geometry
> + 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
> + 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
> + 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
> @@ -302,27 +316,27 @@ The following sysctls are available for the XFS filesystem:
>
> 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
> + 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
> + 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
> + 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
> + 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
> + 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)
> --
> 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>
---
Documentation/filesystems/index.rst | 5 +-
.../filesystems/{xfs.txt => xfs.rst} | 193 ++++++++++--------
2 files changed, 107 insertions(+), 91 deletions(-)
rename Documentation/filesystems/{xfs.txt => xfs.rst} (73%)
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.txt b/Documentation/filesystems/xfs.rst
similarity index 73%
rename from Documentation/filesystems/xfs.txt
rename to Documentation/filesystems/xfs.rst
index a5cbb5e0e..a8357cbd3 100644
--- a/Documentation/filesystems/xfs.txt
+++ b/Documentation/filesystems/xfs.rst
@@ -1,4 +1,4 @@
-
+======================
The SGI XFS Filesystem
======================
@@ -18,10 +18,11 @@ 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.
+For boolean mount options, the names with the "(*)" prefix is the
+default behaviour. For example, take an behaviour enabled by default to be a one (1) or,
+a zero (0) otherwise, ``(*)[no]default`` would be 0 and ``[no](*)default`` a 1.
- allocsize=size
+ 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)
@@ -34,181 +35,195 @@ default behaviour.
to the file. Specifying a fixed allocsize value turns off
the dynamic behaviour.
- attr2
- noattr2
+ [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
+ ``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.
+ bit indicating that ``attr2`` behaviour is active. If either
+ mount options 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.
- discard
- nodiscard (*)
+ (*)[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
+ 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 (*)
+ 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
+ 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
+ ``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
+ 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
+ (*)[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
+ 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
+ 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.
+ more than 32 bits of significance.
- inode32 is provided for backwards compatibility with older
+ ``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
+ 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
+ (*)[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" 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"
+ 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.
+ is the same as if ``nolargeio`` was specified.
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
+ 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
+ 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.
+ 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.
+ ``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).
+ 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.
+ logdev=<device>
+ Use ``device`` as an external log.
+ In an XFS filesystem, the log section can be separate from
+ the data section or contained within it.
- noalign
+ 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
+ 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.
+ 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
+ Filesystems mounted ``norecovery`` must be mounted read-only or
the mount will fail.
- nouuid
+ 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
+ and often used in combination with ``norecovery`` for mounting
read-only snapshots.
- noquota
+ noquota
Forcibly turns off all quota accounting and enforcement
within the filesystem.
- uquota/usrquota/uqnoenforce/quota
+ uquota/usrquota/uqnoenforce/quota
User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
+ enforced. Refer to **xfs_quota(8)** for further details.
- gquota/grpquota/gqnoenforce
+ gquota/grpquota/gqnoenforce
Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
+ enforced. Refer to **xfs_quota(8)** for further details.
- pquota/prjquota/pqnoenforce
+ pquota/prjquota/pqnoenforce
Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
+ 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
+ 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 and swidth parameters specified must be compatible
+ 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. Valid swidth values
- are any integer multiple of a valid sunit value.
+ general, that means the only valid changes to ``sunit`` are
+ increasing it by a power-of-2 multiple.
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
+ 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
+ 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
+ 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
@@ -302,27 +317,27 @@ The following sysctls are available for the XFS filesystem:
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
+ 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
+ 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
+ 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
+ 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
+ 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)
--
2.22.0
^ permalink raw reply related
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Alexandre Belloni @ 2019-06-28 21:41 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <3997b54a2e73887b96ec665573f08ded78b71421.1561756511.git.mchehab+samsung@kernel.org>
On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> index 225a8df1d4e9..1803f3cab39f 100644
> --- a/drivers/rtc/rtc-ds1374.c
> +++ b/drivers/rtc/rtc-ds1374.c
> @@ -14,7 +14,7 @@
> */
> /*
> * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> - * recommened in .../Documentation/i2c/writing-clients section
> + * recommened in .../Documentation/i2c/writing-clients.rst section
> * "Sending and receiving", using SMBus level communication is preferred.
> */
>
Honestly, the whole comment could be removed. The current trend is to
move everything to regmap anyway.
However, I'm fine with that change if you want to keep it that way (and
probably scripted).
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply
* Re: [PATCH 1/5] docs: convert markdown documents to ReST
From: Rob Herring @ 2019-06-28 22:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel@vger.kernel.org, Jonathan Corbet, Mark Rutland,
devicetree
In-Reply-To: <7a5734d147788ffb817c8122dbb0ff619a718a71.1561756511.git.mchehab+samsung@kernel.org>
On Fri, Jun 28, 2019 at 3:23 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The documentation standard is ReST and not markdown.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/devicetree/writing-schema.md | 130 ---------------
> Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++
I wasn't really ever intending to integrate this into the rest of the
kernel docs, but I'm not tied to any format so:
Acked-by: Rob Herring <robh@kernel.org>
> ...entication.md => ubifs-authentication.rst} | 70 +++++---
> 3 files changed, 197 insertions(+), 156 deletions(-)
> delete mode 100644 Documentation/devicetree/writing-schema.md
> create mode 100644 Documentation/devicetree/writing-schema.rst
> rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Darrick J. Wong @ 2019-06-28 22:18 UTC (permalink / raw)
To: Matthew Wilcox
Cc: Sheriff Esseson, skhan, corbet, linux-doc, linux-kernel,
linux-xfs
In-Reply-To: <20190628215106.GE4286@bombadil.infradead.org>
On Fri, Jun 28, 2019 at 02:51:06PM -0700, Matthew Wilcox wrote:
> On Fri, Jun 28, 2019 at 10:43:02PM +0100, Sheriff Esseson wrote:
> > Convert xfs.txt to ReST, markup and rename accordingly. Update
> > Documentation/index.rst.
>
> Didn't get_maintainers.pl suggest that you cc the linux-xfs mailing list?
No, because we suck. :(
> You also need to update MAINTAINERS.
Yes, please. :)
> > 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>
> > ---
> > Documentation/filesystems/index.rst | 1 +
> > .../filesystems/{xfs.txt => xfs.rst} | 190 ++++++++++--------
> > 2 files changed, 103 insertions(+), 88 deletions(-)
> > rename Documentation/filesystems/{xfs.txt => xfs.rst} (74%)
> >
> > diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> > index 1131c34d7..be91fe616 100644
> > --- a/Documentation/filesystems/index.rst
> > +++ b/Documentation/filesystems/index.rst
> > @@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
> > :maxdepth: 2
> >
> > binderfs.rst
> > + xfs.rst
>
> I believe the convention is to not include the .rst suffix (and yes,
> binderfs is wrong here).
>
> > diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
> > similarity index 74%
> > rename from Documentation/filesystems/xfs.txt
> > rename to Documentation/filesystems/xfs.rst
> > index a5cbb5e0e..5e29e1583 100644
> > --- a/Documentation/filesystems/xfs.txt
> > +++ b/Documentation/filesystems/xfs.rst
> > @@ -1,4 +1,4 @@
> > -
> > +======================
> > The SGI XFS Filesystem
> > ======================
> >
> > @@ -18,10 +18,10 @@ Mount Options
> > =============
> >
> > When mounting an XFS filesystem, the following options are accepted.
> > -For boolean mount options, the names with the (*) suffix is the
> > +For boolean mount options, the names with the "(*)" prefix is the
> > default behaviour.
> >
> > - allocsize=size
> > + 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)
> > @@ -34,181 +34,195 @@ default behaviour.
> > to the file. Specifying a fixed allocsize value turns off
> > the dynamic behaviour.
> >
> > - attr2
> > - noattr2
> > + [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
> > + ``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.
> > + bit indicating that ``attr2`` behaviour is active. If either
> > + mount options is set, then that becomes the new default used
"If either mount option is set..."
> > + 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.
> >
> > - discard
> > - nodiscard (*)
> > + (*)[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
> > + 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 (*)
> > + 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
> > + 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
> > + ``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
> > + 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
> > + (*)[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
> > + 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
> > + 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.
> > + more than 32 bits of significance.
> >
> > - inode32 is provided for backwards compatibility with older
> > + ``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
> > + 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
> > + (*)[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" 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"
> > + If ``largeio`` specified, a filesystem that was created with a
"If ``largeio`` is specified..."
> > + ``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.
> > + is the same as if ``nolargeio`` was specified.
> >
> > - logbufs=value
> > - Set the number of in-memory log buffers. Valid numbers
> > + 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
> > + 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.
> > + 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.
Why the indentation here?
> > 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.
> > + ``logbsize`` must be an integer multiple of the
> > + "log stripe unit" configured at mkfs time.
Or here?
> >
> > The default value for for version 1 logs is 32768, while the
> > - default value for version 2 logs is MAX(32768, log_sunit).
> > + 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.
> > + logdev=<device>
> > + Use ``device`` as an external log.
"...as an external log (metadata journal)."
> > + In an XFS filesystem, the log section can be separate from
> > + the data section or contained within it.
s/section/device/
Hmm, maybe it's time to just call them devices like everyone else on
Linux does. I'd guess "section" is a holdover from IRIX(?)
> >
> > - noalign
> > + 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.
Why indent here?
> > + 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
> > + 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.
> > + 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
> > + Filesystems mounted ``norecovery`` must be mounted read-only or
> > the mount will fail.
> >
> > - nouuid
> > + 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
> > + and often used in combination with ``norecovery`` for mounting
> > read-only snapshots.
> >
> > - noquota
> > + noquota
> > Forcibly turns off all quota accounting and enforcement
> > within the filesystem.
> >
> > - uquota/usrquota/uqnoenforce/quota
> > + uquota/usrquota/uqnoenforce/quota
> > User disk quota accounting enabled, and limits (optionally)
> > - enforced. Refer to xfs_quota(8) for further details.
> > + enforced. Refer to **xfs_quota(8)** for further details.
> >
> > - gquota/grpquota/gqnoenforce
> > + gquota/grpquota/gqnoenforce
> > Group disk quota accounting enabled and limits (optionally)
> > - enforced. Refer to xfs_quota(8) for further details.
> > + enforced. Refer to **xfs_quota(8)** for further details.
> >
> > - pquota/prjquota/pqnoenforce
> > + pquota/prjquota/pqnoenforce
> > Project disk quota accounting enabled and limits (optionally)
> > - enforced. Refer to xfs_quota(8) for further details.
> > + 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
> > + 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
Long line?
> > + block units. This option is only relevant to filesystems
> > that were created with non-zero data alignment parameters.
> >
> > - The sunit and swidth parameters specified must be compatible
> > + 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. Valid swidth values
> > - are any integer multiple of a valid sunit value.
> > + general, that means the only valid changes to ``sunit`` are
> > + increasing it by a power-of-2 multiple.
> >
> > - Typically the only time these mount options are necessary if
> > - after an underlying RAID device has had it's geometry
> > + 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
> > + 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
Line too long.
> > + block units. This option, like ``sunit`` above, is only
> > + relevant to filesystems that were created with non-zero data alignment parameters.
Why indent here?
> > +
> > + 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
> > + 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
> > @@ -302,27 +316,27 @@ The following sysctls are available for the XFS filesystem:
> >
> > 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
> > + 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
> > + 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
> > + 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
> > + 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
> > + by the **xfs_io(8)** chattr command on a directory to be
> > inherited by files in that directory.
Otherwise, this looks good. Thank you for taking on this conversion!
--D
> >
> > fs.xfs.rotorstep (Min: 1 Default: 1 Max: 256)
> > --
> > 2.22.0
> >
^ permalink raw reply
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Alexandre Belloni @ 2019-06-28 22:10 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <20190628185445.71eb824b@coco.lan>
On 28/06/2019 18:54:45-0300, Mauro Carvalho Chehab wrote:
> Em Fri, 28 Jun 2019 23:41:38 +0200
> Alexandre Belloni <alexandre.belloni@bootlin.com> escreveu:
>
> > On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> > > diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> > > index 225a8df1d4e9..1803f3cab39f 100644
> > > --- a/drivers/rtc/rtc-ds1374.c
> > > +++ b/drivers/rtc/rtc-ds1374.c
> > > @@ -14,7 +14,7 @@
> > > */
> > > /*
> > > * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> > > - * recommened in .../Documentation/i2c/writing-clients section
> > > + * recommened in .../Documentation/i2c/writing-clients.rst section
> > > * "Sending and receiving", using SMBus level communication is preferred.
> > > */
> > >
> >
> > Honestly, the whole comment could be removed. The current trend is to
> > move everything to regmap anyway.
> >
> > However, I'm fine with that change if you want to keep it that way (and
> > probably scripted).
>
> While the conversion was manually made, the renames were scripted,
> and checked with:
>
> ./scripts/documentation-file-ref-check
>
> Otherwise I would very likely fix the typo:
>
> recommened -> recommended
>
> :-)
>
> I can certainly add new patch at this (before or after patch 3/5 - as you
> prefer) in order to get rid of the comment, but I would avoid doing a
> somewhat unrelated changes at the same documentation patch.
>
I'm okay with that.
--
Alexandre Belloni, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply
* Re: [PATCH 3/5] docs: i2c: convert to ReST and add to driver-api bookset
From: Mauro Carvalho Chehab @ 2019-06-28 21:54 UTC (permalink / raw)
To: Alexandre Belloni
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Peter Rosin, Rob Herring, Mark Rutland,
Jean Delvare, Guenter Roeck, Andreas Werner, Wolfram Sang,
Rudolf Marek, Seth Heasley, Neil Horman, Vadim Pasternak,
Michael Shych, Ajay Gupta, Peter Korsgaard, Andrew Lunn,
Jim Cromie, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, Alessandro Zummo,
linux-i2c, devicetree, linux-hwmon, linux-spi, linux-iio,
linux-rtc
In-Reply-To: <20190628214138.GU3692@piout.net>
Em Fri, 28 Jun 2019 23:41:38 +0200
Alexandre Belloni <alexandre.belloni@bootlin.com> escreveu:
> On 28/06/2019 18:23:14-0300, Mauro Carvalho Chehab wrote:
> > diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
> > index 225a8df1d4e9..1803f3cab39f 100644
> > --- a/drivers/rtc/rtc-ds1374.c
> > +++ b/drivers/rtc/rtc-ds1374.c
> > @@ -14,7 +14,7 @@
> > */
> > /*
> > * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
> > - * recommened in .../Documentation/i2c/writing-clients section
> > + * recommened in .../Documentation/i2c/writing-clients.rst section
> > * "Sending and receiving", using SMBus level communication is preferred.
> > */
> >
>
> Honestly, the whole comment could be removed. The current trend is to
> move everything to regmap anyway.
>
> However, I'm fine with that change if you want to keep it that way (and
> probably scripted).
While the conversion was manually made, the renames were scripted,
and checked with:
./scripts/documentation-file-ref-check
Otherwise I would very likely fix the typo:
recommened -> recommended
:-)
I can certainly add new patch at this (before or after patch 3/5 - as you
prefer) in order to get rid of the comment, but I would avoid doing a
somewhat unrelated changes at the same documentation patch.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Shuah Khan @ 2019-06-28 21:53 UTC (permalink / raw)
To: Sheriff Esseson; +Cc: corbet, linux-doc, linux-kernel
In-Reply-To: <20190628214302.GA12096@localhost>
Hi Sheriff,
On 6/28/19 3:43 PM, 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.
>
The commit log looks odd with these indentations.
> Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
> ---
> Documentation/filesystems/index.rst | 1 +
> .../filesystems/{xfs.txt => xfs.rst} | 190 ++++++++++--------
> 2 files changed, 103 insertions(+), 88 deletions(-)
> rename Documentation/filesystems/{xfs.txt => xfs.rst} (74%)
>
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index 1131c34d7..be91fe616 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
> :maxdepth: 2
>
> binderfs.rst
> + xfs.rst
> diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
> similarity index 74%
> rename from Documentation/filesystems/xfs.txt
> rename to Documentation/filesystems/xfs.rst
> index a5cbb5e0e..5e29e1583 100644
> --- a/Documentation/filesystems/xfs.txt
> +++ b/Documentation/filesystems/xfs.rst
> @@ -1,4 +1,4 @@
> -
> +======================
> The SGI XFS Filesystem
> ======================
>
> @@ -18,10 +18,10 @@ Mount Options
> =============
>
> When mounting an XFS filesystem, the following options are accepted.
> -For boolean mount options, the names with the (*) suffix is the
> +For boolean mount options, the names with the "(*)" prefix is the
> default behaviour.
>
> - allocsize=size
> + 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)
> @@ -34,181 +34,195 @@ default behaviour.
> to the file. Specifying a fixed allocsize value turns off
> the dynamic behaviour.
>
> - attr2
> - noattr2
> + [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
> + ``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.
> + bit indicating that ``attr2`` behaviour is active. If either
> + mount options 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.
>
> - discard
> - nodiscard (*)
> + (*)[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
> + 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 (*)
> + 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
> + 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
> + ``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
> + 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
> + (*)[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
> + 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
> + 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.
> + more than 32 bits of significance.
>
> - inode32 is provided for backwards compatibility with older
> + ``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
> + 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
> + (*)[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" 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"
> + 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.
> + is the same as if ``nolargeio`` was specified.
>
> - logbufs=value
> - Set the number of in-memory log buffers. Valid numbers
> + 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
> + 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.
> + 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.
> + ``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).
> + 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.
> + logdev=<device>
> + Use ``device`` as an external log.
> + In an XFS filesystem, the log section can be separate from
> + the data section or contained within it.
>
> - noalign
> + 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
> + 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.
> + 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
> + Filesystems mounted ``norecovery`` must be mounted read-only or
> the mount will fail.
>
> - nouuid
> + 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
> + and often used in combination with ``norecovery`` for mounting
> read-only snapshots.
>
> - noquota
> + noquota
> Forcibly turns off all quota accounting and enforcement
> within the filesystem.
>
> - uquota/usrquota/uqnoenforce/quota
> + uquota/usrquota/uqnoenforce/quota
> User disk quota accounting enabled, and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + enforced. Refer to **xfs_quota(8)** for further details.
>
> - gquota/grpquota/gqnoenforce
> + gquota/grpquota/gqnoenforce
> Group disk quota accounting enabled and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + enforced. Refer to **xfs_quota(8)** for further details.
>
> - pquota/prjquota/pqnoenforce
> + pquota/prjquota/pqnoenforce
> Project disk quota accounting enabled and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + 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
> + 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 and swidth parameters specified must be compatible
> + 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. Valid swidth values
> - are any integer multiple of a valid sunit value.
> + general, that means the only valid changes to ``sunit`` are
> + increasing it by a power-of-2 multiple.
>
> - Typically the only time these mount options are necessary if
> - after an underlying RAID device has had it's geometry
> + 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
> + 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
> + 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
> @@ -302,27 +316,27 @@ The following sysctls are available for the XFS filesystem:
>
> 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
> + 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
> + 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
> + 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
> + 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
> + 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)
>
^ permalink raw reply
* Re: [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Matthew Wilcox @ 2019-06-28 21:51 UTC (permalink / raw)
To: Sheriff Esseson
Cc: skhan, corbet, linux-doc, linux-kernel, linux-xfs,
Darrick J. Wong
In-Reply-To: <20190628214302.GA12096@localhost>
On Fri, Jun 28, 2019 at 10:43:02PM +0100, Sheriff Esseson wrote:
> Convert xfs.txt to ReST, markup and rename accordingly. Update
> Documentation/index.rst.
Didn't get_maintainers.pl suggest that you cc the linux-xfs mailing list?
You also need to update MAINTAINERS.
> 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>
> ---
> Documentation/filesystems/index.rst | 1 +
> .../filesystems/{xfs.txt => xfs.rst} | 190 ++++++++++--------
> 2 files changed, 103 insertions(+), 88 deletions(-)
> rename Documentation/filesystems/{xfs.txt => xfs.rst} (74%)
>
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index 1131c34d7..be91fe616 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
> :maxdepth: 2
>
> binderfs.rst
> + xfs.rst
I believe the convention is to not include the .rst suffix (and yes,
binderfs is wrong here).
> diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
> similarity index 74%
> rename from Documentation/filesystems/xfs.txt
> rename to Documentation/filesystems/xfs.rst
> index a5cbb5e0e..5e29e1583 100644
> --- a/Documentation/filesystems/xfs.txt
> +++ b/Documentation/filesystems/xfs.rst
> @@ -1,4 +1,4 @@
> -
> +======================
> The SGI XFS Filesystem
> ======================
>
> @@ -18,10 +18,10 @@ Mount Options
> =============
>
> When mounting an XFS filesystem, the following options are accepted.
> -For boolean mount options, the names with the (*) suffix is the
> +For boolean mount options, the names with the "(*)" prefix is the
> default behaviour.
>
> - allocsize=size
> + 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)
> @@ -34,181 +34,195 @@ default behaviour.
> to the file. Specifying a fixed allocsize value turns off
> the dynamic behaviour.
>
> - attr2
> - noattr2
> + [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
> + ``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.
> + bit indicating that ``attr2`` behaviour is active. If either
> + mount options 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.
>
> - discard
> - nodiscard (*)
> + (*)[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
> + 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 (*)
> + 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
> + 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
> + ``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
> + 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
> + (*)[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
> + 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
> + 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.
> + more than 32 bits of significance.
>
> - inode32 is provided for backwards compatibility with older
> + ``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
> + 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
> + (*)[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" 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"
> + 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.
> + is the same as if ``nolargeio`` was specified.
>
> - logbufs=value
> - Set the number of in-memory log buffers. Valid numbers
> + 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
> + 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.
> + 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.
> + ``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).
> + 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.
> + logdev=<device>
> + Use ``device`` as an external log.
> + In an XFS filesystem, the log section can be separate from
> + the data section or contained within it.
>
> - noalign
> + 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
> + 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.
> + 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
> + Filesystems mounted ``norecovery`` must be mounted read-only or
> the mount will fail.
>
> - nouuid
> + 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
> + and often used in combination with ``norecovery`` for mounting
> read-only snapshots.
>
> - noquota
> + noquota
> Forcibly turns off all quota accounting and enforcement
> within the filesystem.
>
> - uquota/usrquota/uqnoenforce/quota
> + uquota/usrquota/uqnoenforce/quota
> User disk quota accounting enabled, and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + enforced. Refer to **xfs_quota(8)** for further details.
>
> - gquota/grpquota/gqnoenforce
> + gquota/grpquota/gqnoenforce
> Group disk quota accounting enabled and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + enforced. Refer to **xfs_quota(8)** for further details.
>
> - pquota/prjquota/pqnoenforce
> + pquota/prjquota/pqnoenforce
> Project disk quota accounting enabled and limits (optionally)
> - enforced. Refer to xfs_quota(8) for further details.
> + 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
> + 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 and swidth parameters specified must be compatible
> + 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. Valid swidth values
> - are any integer multiple of a valid sunit value.
> + general, that means the only valid changes to ``sunit`` are
> + increasing it by a power-of-2 multiple.
>
> - Typically the only time these mount options are necessary if
> - after an underlying RAID device has had it's geometry
> + 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
> + 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
> + 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
> @@ -302,27 +316,27 @@ The following sysctls are available for the XFS filesystem:
>
> 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
> + 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
> + 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
> + 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
> + 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
> + 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)
> --
> 2.22.0
>
^ permalink raw reply
* Re: [RFC PATCH 1/3] mm: Introduce VM_IBT for CET legacy code bitmap
From: Andy Lutomirski @ 2019-06-28 21:49 UTC (permalink / raw)
To: Yu-cheng Yu
Cc: x86, H. Peter Anvin, Thomas Gleixner, Ingo Molnar, linux-kernel,
linux-doc, 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-1-yu-cheng.yu@intel.com>
> On Jun 28, 2019, at 12:41 PM, Yu-cheng Yu <yu-cheng.yu@intel.com> wrote:
>
> The previous discussion of the IBT legacy code bitmap is here:
>
> https://lkml.org/lkml/2019/6/6/1032
>
> When CET Indirect Branch Tracking (IBT) is enabled, the processor expects
> every branch target is an ENDBR instruction, or the target's address is
> marked as legacy in the legacy code bitmap. The bitmap covers the whole
> user-mode address space (TASK_SIZE_MAX for 64-bit, TASK_SIZE for IA32),
> and each bit represents one page of linear address range.
>
> This patch introduces VM_IBT for the bitmap.
There’s no need to allocate a bit for this and to clutter up the fault code with special cases. Use _install_special_mapping(), please. If you need to make it more flexible to cover your use case, please do so.
^ permalink raw reply
* [PATCH v1] Doc : fs : convert xfs.txt to ReST
From: Sheriff Esseson @ 2019-06-28 21:43 UTC (permalink / raw)
To: skhan; +Cc: corbet, linux-doc, linux-kernel
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>
---
Documentation/filesystems/index.rst | 1 +
.../filesystems/{xfs.txt => xfs.rst} | 190 ++++++++++--------
2 files changed, 103 insertions(+), 88 deletions(-)
rename Documentation/filesystems/{xfs.txt => xfs.rst} (74%)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 1131c34d7..be91fe616 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
:maxdepth: 2
binderfs.rst
+ xfs.rst
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.rst
similarity index 74%
rename from Documentation/filesystems/xfs.txt
rename to Documentation/filesystems/xfs.rst
index a5cbb5e0e..5e29e1583 100644
--- a/Documentation/filesystems/xfs.txt
+++ b/Documentation/filesystems/xfs.rst
@@ -1,4 +1,4 @@
-
+======================
The SGI XFS Filesystem
======================
@@ -18,10 +18,10 @@ Mount Options
=============
When mounting an XFS filesystem, the following options are accepted.
-For boolean mount options, the names with the (*) suffix is the
+For boolean mount options, the names with the "(*)" prefix is the
default behaviour.
- allocsize=size
+ 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)
@@ -34,181 +34,195 @@ default behaviour.
to the file. Specifying a fixed allocsize value turns off
the dynamic behaviour.
- attr2
- noattr2
+ [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
+ ``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.
+ bit indicating that ``attr2`` behaviour is active. If either
+ mount options 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.
- discard
- nodiscard (*)
+ (*)[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
+ 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 (*)
+ 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
+ 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
+ ``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
+ 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
+ (*)[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
+ 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
+ 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.
+ more than 32 bits of significance.
- inode32 is provided for backwards compatibility with older
+ ``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
+ 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
+ (*)[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" 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"
+ 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.
+ is the same as if ``nolargeio`` was specified.
- logbufs=value
- Set the number of in-memory log buffers. Valid numbers
+ 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
+ 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.
+ 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.
+ ``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).
+ 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.
+ logdev=<device>
+ Use ``device`` as an external log.
+ In an XFS filesystem, the log section can be separate from
+ the data section or contained within it.
- noalign
+ 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
+ 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.
+ 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
+ Filesystems mounted ``norecovery`` must be mounted read-only or
the mount will fail.
- nouuid
+ 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
+ and often used in combination with ``norecovery`` for mounting
read-only snapshots.
- noquota
+ noquota
Forcibly turns off all quota accounting and enforcement
within the filesystem.
- uquota/usrquota/uqnoenforce/quota
+ uquota/usrquota/uqnoenforce/quota
User disk quota accounting enabled, and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
+ enforced. Refer to **xfs_quota(8)** for further details.
- gquota/grpquota/gqnoenforce
+ gquota/grpquota/gqnoenforce
Group disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
+ enforced. Refer to **xfs_quota(8)** for further details.
- pquota/prjquota/pqnoenforce
+ pquota/prjquota/pqnoenforce
Project disk quota accounting enabled and limits (optionally)
- enforced. Refer to xfs_quota(8) for further details.
+ 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
+ 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 and swidth parameters specified must be compatible
+ 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. Valid swidth values
- are any integer multiple of a valid sunit value.
+ general, that means the only valid changes to ``sunit`` are
+ increasing it by a power-of-2 multiple.
- Typically the only time these mount options are necessary if
- after an underlying RAID device has had it's geometry
+ 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
+ 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
+ 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
@@ -302,27 +316,27 @@ The following sysctls are available for the XFS filesystem:
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
+ 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
+ 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
+ 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
+ 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
+ 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)
--
2.22.0
^ permalink raw reply related
* Re: [PATCH v5 17/18] kernel/sysctl-test: Add null pointer test for sysctl.c:proc_dointvec()
From: Luis Chamberlain @ 2019-06-28 21:37 UTC (permalink / raw)
To: Brendan Higgins, Dominik Brodowski
Cc: Iurii Zaikin, linux-api, Michael Kerrisk (man-pages),
Frank Rowand, Greg KH, Josh Poimboeuf, Kees Cook, Kieran Bingham,
Peter Zijlstra, Rob Herring, Stephen Boyd, shuah,
Theodore Ts'o, Masahiro Yamada, devicetree, dri-devel,
kunit-dev, open list:DOCUMENTATION, linux-fsdevel, linux-kbuild,
Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK,
linux-nvdimm, linux-um, Sasha Levin, Bird, Timothy,
Amir Goldstein, Dan Carpenter, Daniel Vetter, Jeff Dike,
Joel Stanley, Julia Lawall, Kevin Hilman, Knut Omang,
Logan Gunthorpe, Michael Ellerman, Petr Mladek, Randy Dunlap,
Richard Weinberger, David Rientjes, Steven Rostedt, wfg
In-Reply-To: <CAFd5g45VJ9yfuESUc=E0ydJyN+mk1b1kyHSCYvO2x9KPC7+3GQ@mail.gmail.com>
On Fri, Jun 28, 2019 at 01:01:54AM -0700, Brendan Higgins wrote:
> On Wed, Jun 26, 2019 at 11:10 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> >
> > On Wed, Jun 26, 2019 at 09:07:43PM -0700, Iurii Zaikin wrote:
> > > On Tue, Jun 25, 2019 at 7:17 PM Luis Chamberlain <mcgrof@kernel.org> wrote:
> > > > > +static void sysctl_test_dointvec_table_maxlen_unset(struct kunit *test)
> > > > > +{
> > > > > + struct ctl_table table = {
> > > > > + .procname = "foo",
> > > > > + .data = &test_data.int_0001,
> > > > > + .maxlen = 0,
> > > > > + .mode = 0644,
> > > > > + .proc_handler = proc_dointvec,
> > > > > + .extra1 = &i_zero,
> > > > > + .extra2 = &i_one_hundred,
> > > > > + };
> > > > > + void *buffer = kunit_kzalloc(test, sizeof(int), GFP_USER);
> > > > > + size_t len;
> > > > > + loff_t pos;
> > > > > +
> > > > > + len = 1234;
> > > > > + KUNIT_EXPECT_EQ(test, 0, proc_dointvec(&table, 0, buffer, &len, &pos));
> > > > > + KUNIT_EXPECT_EQ(test, (size_t)0, len);
> > > > > + len = 1234;
> > > > > + KUNIT_EXPECT_EQ(test, 0, proc_dointvec(&table, 1, buffer, &len, &pos));
> > > > > + KUNIT_EXPECT_EQ(test, (size_t)0, len);
> > > > > +}
> > > >
> > > > In a way this is also testing for general kernel API changes. This is and the
> > > > last one were good examples. So this is not just testing functionality
> > > > here. There is no wrong or write answer if 0 or -EINVAL was returned
> > > > other than the fact that we have been doing this for years.
> > > >
> > > > Its a perhaps small but important difference for some of these tests. I
> > > > *do* think its worth clarifying through documentation which ones are
> > > > testing for API consistency Vs proper correctness.
> > >
> > > You make a good point that the test codifies the existing behavior of
> > > the function in lieu of formal documentation. However, the test cases
> > > were derived from examining the source code of the function under test
> > > and attempting to cover all branches. The assertions were added only
> > > for the values that appeared to be set deliberately in the
> > > implementation. And it makes sense to me to test that the code does
> > > exactly what the implementation author intended.
> >
> > I'm not arguing against adding them. I'm suggesting that it is different
> > to test for API than for correctness of intended functionality, and
> > it would be wise to make it clear which test cases are for API and which
> > for correctness.
>
> I see later on that some of the API stuff you are talking about is
> public APIs from the standpoint of user (outside of LInux) visible.
Right, UAPI.
> To
> be clear, is that what you mean by public APIs throughout, or would
> you distinguish between correctness tests, internal API tests, and
> external API tests?
I would definitely recommend distingishing between all of these.
Kernel API (or just call it API), UAPI, and correctness.
> > This will come up later for other kunit tests and it would be great
> > to set precendent so that other kunit tests can follow similar
> > practices to ensure its clear what is API realted Vs correctness of
> > intended functionality.
> >
> > In fact, I'm not yet sure if its possible to test public kernel API to
> > userspace with kunit, but if it is possible... well, that could make
> > linux-api folks happy as they could enable us to codify interpreation of
> > what is expected into kunit test cases, and we'd ensure that the
> > codified interpretation is not only documented in man pages but also
> > through formal kunit test cases.
> >
> > A regression in linux-api then could be formalized through a proper
> > kunit tests case. And if an API evolves, it would force developers to
> > update the respective kunit which codifies that contract.
>
> Yep, I think that is long term hope. Some of the file system interface
> stuff that requires a filesystem to be mounted somewhere might get a
> little weird/difficult, but I suspect we should be able to do it
> eventually. I mean it's all just C code right? Should mostly boil down
> to someone figuring out how to do it the first time.
There used to be hacks in the kernel the call syscalls in a few places.
This was cleaned up and addressed via Dominik Brodowski's series last
year in March:
http://lkml.kernel.org/r/20180325162527.GA17492@light.dominikbrodowski.net
An example commit: d300b610812f3 ("kernel: use kernel_wait4() instead of
sys_wait4()").
So it would seem the work is done, and you'd just have to use the
respective exposed kernel_syscallname() calls, or add some if you
want to test a specific syscall in kernel space.
Luis
^ permalink raw reply
* [PATCH 4/5] docs: w1: convert to ReST and add to the kAPI group of docs
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Evgeniy Polyakov
In-Reply-To: <cover.1561756511.git.mchehab+samsung@kernel.org>
The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
Documentation/index.rst | 1 +
Documentation/w1/index.rst | 22 +++++
.../w1/masters/{ds2482 => ds2482.rst} | 17 +++-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +++
Documentation/w1/masters/mxc-w1 | 12 ---
Documentation/w1/masters/mxc-w1.rst | 17 ++++
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +--
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +++--
Documentation/w1/slaves/index.rst | 16 ++++
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 2 +
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 ++
Documentation/w1/slaves/w1_ds2423 | 47 ----------
Documentation/w1/slaves/w1_ds2423.rst | 54 ++++++++++++
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 ++-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 ++
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 15 ++--
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 ++-
.../w1/{w1.generic => w1-generic.rst} | 88 +++++++++++--------
.../w1/{w1.netlink => w1-netlink.rst} | 83 +++++++++--------
23 files changed, 306 insertions(+), 164 deletions(-)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
delete mode 100644 Documentation/w1/masters/mxc-w1
create mode 100644 Documentation/w1/masters/mxc-w1.rst
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (97%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
delete mode 100644 Documentation/w1/slaves/w1_ds2423
create mode 100644 Documentation/w1/slaves/w1_ds2423.rst
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (79%)
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b4ae92..992dfb183ed0 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component.
control systems are attached/generate presence for as short as
100 ms - hence the tens-to-hundreds milliseconds scan intervals
are required.
- see Documentation/w1/w1.generic for detailed information.
+ see Documentation/w1/w1-generic.rst for detailed information.
Users: any user space application which wants to know bus scanning
interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def14f28..534e63731a49 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq
Date: Apr 2015
Contact: Matt Campbell <mattrcampbell@gmail.com>
Description: Support for the DS28EA00 chain sequence function
- see Documentation/w1/slaves/w1_therm for detailed information
+ see Documentation/w1/slaves/w1_therm.rst for detailed information
Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ded1081e8d5f..38ece18f5d1e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ w1/index
watchdog/index
input/index
hwmon/index
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 000000000000..4ca0698357c4
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,22 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+ :maxdepth: 1
+
+
+ w1-generic.rst
+ w1-netlink.rst
+ masters/index
+ slaves/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst
similarity index 71%
rename from Documentation/w1/masters/ds2482
rename to Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..7f1558d39310 100644
--- a/Documentation/w1/masters/ds2482
+++ b/Documentation/w1/masters/ds2482.rst
@@ -1,13 +1,19 @@
+====================
Kernel driver ds2482
====================
Supported chips:
+
* Maxim DS2482-100, Maxim DS2482-800
+
Prefix: 'ds2482'
+
Addresses scanned: None
+
Datasheets:
- http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
- http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
Author: Ben Gardner <bgardner@wabtec.com>
@@ -23,9 +29,12 @@ General Remarks
---------------
Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
However, the device cannot be detected without writing to the i2c bus, so no
detection is done. You should instantiate the device explicitly.
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
+
+ $ modprobe ds2482
+ $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst
similarity index 98%
rename from Documentation/w1/masters/ds2490
rename to Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490.rst
@@ -1,7 +1,9 @@
+====================
Kernel driver ds2490
====================
Supported chips:
+
* Maxim DS2490 based
Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
low-level operational chip.
Notes and limitations.
+
- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
- The 5V strong pullup is supported with a minimum of 5.9mA and a
maximum of 30.4 mA. (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
reattaching would clear the problem. usbmon output in the guest and
host did not explain the problem. My guess is a bug in either qemu
or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 000000000000..4442a98850ad
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ ds2482
+ ds2490
+ mxc-w1
+ omap-hdq
+ w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1
deleted file mode 100644
index 38be1ad65532..000000000000
--- a/Documentation/w1/masters/mxc-w1
+++ /dev/null
@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
- * Freescale MX27, MX31 and probably other i.MX SoCs
- Datasheets:
- http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
- Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
- Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst
new file mode 100644
index 000000000000..334f9893103f
--- /dev/null
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+ * Freescale MX27, MX31 and probably other i.MX SoCs
+
+ Datasheets:
+
+ - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+ - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+ Originally based on Freescale code, prepared for mainline by
+ Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst
similarity index 90%
rename from Documentation/w1/masters/omap-hdq
rename to Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
--- a/Documentation/w1/masters/omap-hdq
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
========================================
Supported chips:
================
- HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
A useful link about HDQ basics:
===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
Please note to load both the modules with a different ID if required, but note
that the ID used should be same for both master and slave driver loading.
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+ insmod omap_hdq.ko W1_ID=2
+ inamod w1_bq27000.ko F_ID=2
The driver also supports 1-wire mode. In this mode, there is no need to
pass slave ID as parameter. The driver will auto-detect slaves connected
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst
similarity index 75%
rename from Documentation/w1/masters/w1-gpio
rename to Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
--- a/Documentation/w1/masters/w1-gpio
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -1,3 +1,4 @@
+=====================
Kernel driver w1-gpio
=====================
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
Example (mach-at91)
-------------------
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+ #include <linux/gpio/machine.h>
+ #include <linux/w1-gpio.h>
+
+ static struct gpiod_lookup_table foo_w1_gpiod_table = {
.dev_id = "w1-gpio",
.table = {
GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
},
-};
+ };
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+ static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
.ext_pullup_enable_pin = -EINVAL,
-};
+ };
-static struct platform_device foo_w1_device = {
+ static struct platform_device foo_w1_device = {
.name = "w1-gpio",
.id = -1,
.dev.platform_data = &foo_w1_gpio_pdata,
-};
+ };
-...
+ ...
at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
gpiod_add_lookup_table(&foo_w1_gpiod_table);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000000..d0697b202f09
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ w1_ds2406
+ w1_ds2413
+ w1_ds2423
+ w1_ds2438
+ w1_ds28e04
+ w1_ds28e17
+ w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst
similarity index 97%
rename from Documentation/w1/slaves/w1_ds2406
rename to Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..ec82f2614721 100644
--- a/Documentation/w1/slaves/w1_ds2406
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -1,7 +1,9 @@
+=======================
w1_ds2406 kernel driver
=======================
Supported chips:
+
* Maxim DS2406 (and other family 0x12) addressable switches
Author: Scott Alfter <scott@alfter.us>
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst
similarity index 81%
rename from Documentation/w1/slaves/w1_ds2413
rename to Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
--- a/Documentation/w1/slaves/w1_ds2413
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -1,11 +1,16 @@
+=======================
Kernel driver w1_ds2413
=======================
Supported chips:
+
* Maxim DS2413 1-Wire Dual Channel Addressable Switch
supported family codes:
+
+ ================ ====
W1_FAMILY_DS2413 0x3A
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -20,11 +25,13 @@ Reading state
The "state" file provides one-byte value which is in the same format as for
the chip PIO_ACCESS_READ command (refer the datasheet for details):
+======== =============================================================
Bit 0: PIOA Pin State
Bit 1: PIOA Output Latch State
Bit 2: PIOB Pin State
Bit 3: PIOB Output Latch State
Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
This file is readonly.
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
It is writable, you can write one-byte value to this sysfs file.
Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+======== ======================================
Bit 0: PIOA
Bit 1: PIOB
Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
The chip has some kind of basic protection against transmission errors.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423
deleted file mode 100644
index 3f98b505a0ee..000000000000
--- a/Documentation/w1/slaves/w1_ds2423
+++ /dev/null
@@ -1,47 +0,0 @@
-Kernel driver w1_ds2423
-=======================
-
-Supported chips:
- * Maxim DS2423 based counter devices.
-
-supported family codes:
- W1_THERM_DS2423 0x1D
-
-Author: Mika Laitio <lamikr@pilppa.org>
-
-Description
------------
-
-Support is provided through the sysfs w1_slave file. Each opening and
-read sequence of w1_slave file initiates the read of counters and ram
-available in DS2423 pages 12 - 15.
-
-Result of each page is provided as an ASCII output where each counter
-value and associated ram buffer is outpputed to own line.
-
-Each lines will contain the values of 42 bytes read from the counter and
-memory page along the crc=YES or NO for indicating whether the read operation
-was successful and CRC matched.
-If the operation was successful, there is also in the end of each line
-a counter value expressed as an integer after c=
-
-Meaning of 42 bytes represented is following:
- - 1 byte from ram page
- - 4 bytes for the counter value
- - 4 zero bytes
- - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
- - 31 remaining bytes from the ram page
- - crc=YES/NO indicating whether read was ok and crc matched
- - c=<int> current counter value
-
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
-
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst
new file mode 100644
index 000000000000..755d659ad997
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+ * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+ =============== ====
+ W1_THERM_DS2423 0x1D
+ =============== ====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+ 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds2438
rename to Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
--- a/Documentation/w1/slaves/w1_ds2438
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
=======================
Supported chips:
+
* Maxim DS2438 Smart Battery Monitor
supported family codes:
+ ================ ====
W1_FAMILY_DS2438 0x26
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
command of the chip.
Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+ general purpose A/D input (VAD)
+vdd:
+ battery input (VDD)
After the voltage conversion the value is returned as decimal ASCII.
Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds28e04
rename to Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
--- a/Documentation/w1/slaves/w1_ds28e04
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e04
========================
Supported chips:
+
* Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E04 0x1C
+ ================= ====
Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst
similarity index 88%
rename from Documentation/w1/slaves/w1_ds28e17
rename to Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..36fd0517ea30 100644
--- a/Documentation/w1/slaves/w1_ds28e17
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e17
========================
Supported chips:
+
* Maxim DS28E17 1-Wire-to-I2C Master Bridge
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E17 0x19
+ ================= ====
Author: Jan Kandziora <jjj@gmx.de>
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
connected to a "native" I2C bus master.
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
- SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+ SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+ SYMLINK+="i2c-$attr{name}"
+
may be used to create stable /dev/i2c- entries based on the unique id of the
DS28E17 chip.
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst
similarity index 95%
rename from Documentation/w1/slaves/w1_therm
rename to Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
--- a/Documentation/w1/slaves/w1_therm
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -1,7 +1,9 @@
+======================
Kernel driver w1_therm
-====================
+======================
Supported chips:
+
* Maxim ds18*20 based temperature sensors.
* Maxim ds1825 based temperature sensors.
@@ -13,12 +15,16 @@ Description
w1_therm provides basic temperature conversion for ds18*20 devices, and the
ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+==================== ====
W1_THERM_DS18S20 0x10
W1_THERM_DS1822 0x22
W1_THERM_DS18B20 0x28
W1_THERM_DS1825 0x3B
W1_THERM_DS28EA00 0x42
+==================== ====
Support is provided through the sysfs w1_slave file. Each open and
read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
In case the detection of parasite devices using this command fails
(seems to be the case with some DS18S20) the strong pullup can
be force-enabled.
+
If the strong pullup is enabled, the master's strong pullup will be
driven when the conversion is taking place, provided the master driver
does support the strong pullup (or it falls back to a pullup
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst
similarity index 59%
rename from Documentation/w1/w1.generic
rename to Documentation/w1/w1-generic.rst
index c51b1ab012d0..da4e8b4e9b01 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1-generic.rst
@@ -1,5 +1,7 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
The 1-wire bus is a simple master-slave bus that communicates via a single
signal wire (plus ground, so two wires).
@@ -12,14 +14,16 @@ communication with slaves.
All w1 slave devices must be connected to a w1 bus master device.
Example w1 master devices:
- DS9490 usb device
- W1-over-GPIO
- DS2482 (i2c to w1 bridge)
- Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+ - DS9490 usb device
+ - W1-over-GPIO
+ - DS2482 (i2c to w1 bridge)
+ - Emulated devices, such as a RS232 converter, parallel port adapter, etc
What does the w1 subsystem do?
-------------------------------------------------------------------
+------------------------------
+
When a w1 master driver registers with the w1 subsystem, the following occurs:
- sysfs entries for that w1 master are created
@@ -43,24 +47,28 @@ be read, since no device was selected.
W1 device families
-------------------------------------------------------------------
+------------------
+
Slave devices are handled by a driver written for a family of w1 devices.
A family driver populates a struct w1_family_ops (see w1_family.h) and
registers with the w1 subsystem.
Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
+
+w1_therm
+ - (ds18?20 thermal sensor family driver)
provides temperature reading function which is bound to ->rbin() method
of the above w1_family_ops structure.
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
+w1_smem
+ - driver for simple 64bit memory cell provides ID reading method.
You can call above methods by reading appropriate sysfs files.
What does a w1 master driver need to implement?
-------------------------------------------------------------------
+-----------------------------------------------
The driver for w1 bus master must provide at minimum two functions.
@@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details.
w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-w1_master_add - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
- - (rw) maximum number of slaves to search for at a time
-w1_master_name - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove - (rw) manually remove a slave device
-w1_master_search - (rw) the number of searches left to do,
- -1=continual (default)
-w1_master_slave_count
- - (ro) the number of slaves found
-w1_master_slaves - (ro) the names of the slaves, one per line
-w1_master_timeout - (ro) the delay in seconds between searches
-w1_master_timeout_us
- - (ro) the delay in microseconds beetwen searches
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx> A directory for a found device. The format is
+ family-serial
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+w1_master_add (rw) manually register a slave device
+w1_master_attempts (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove (rw) manually remove a slave device
+w1_master_search (rw) the number of searches left to do,
+ -1=continual (default)
+w1_master_slave_count (ro) the number of slaves found
+w1_master_slaves (ro) the names of the slaves, one per line
+w1_master_timeout (ro) the delay in seconds between searches
+w1_master_timeout_us (ro) the delay in microseconds beetwen searches
+========================= =====================================================
If you have a w1 bus that never changes (you don't add or remove devices),
you can set the module parameter search_count to a small positive number
@@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments
w1_master_attempts by 1.
w1 slave sysfs interface
-------------------------------------------------------------------
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-name - the device name, usually the same as the directory name
-w1_slave - (optional) a binary file whose meaning depends on the
- family driver
-rw - (optional) created for slave devices which do not have
- appropriate family driver. Allows to read/write binary data.
+------------------------
+
+=================== ============================================================
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+name the device name, usually the same as the directory name
+w1_slave (optional) a binary file whose meaning depends on the
+ family driver
+rw (optional) created for slave devices which do not have
+ appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst
similarity index 79%
rename from Documentation/w1/w1.netlink
rename to Documentation/w1/w1-netlink.rst
index 94ad4c420828..138a53c2f950 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1-netlink.rst
@@ -1,22 +1,26 @@
-Userspace communication protocol over connector [1].
+===============================================
+Userspace communication protocol over connector
+===============================================
-
-Message types.
+Message types
=============
There are three types of messages between w1 core and userspace:
+
1. Events. They are generated each time a new master or slave device
- is found either due to automatic or requested search.
+ is found either due to automatic or requested search.
2. Userspace commands.
3. Replies to userspace commands.
-Protocol.
+Protocol
========
-[struct cn_msg] - connector header.
+::
+
+ [struct cn_msg] - connector header.
Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
+ [struct w1_netlink_msg] - w1 netlink header.
__u8 type - message type.
W1_LIST_MASTERS
list current bus masters
@@ -40,7 +44,7 @@ Protocol.
} mst;
} id;
-[struct w1_netlink_cmd] - command for given master or slave device.
+ [struct w1_netlink_cmd] - command for given master or slave device.
__u8 cmd - command opcode.
W1_CMD_READ - read command
W1_CMD_WRITE - write command
@@ -71,18 +75,18 @@ when it is added to w1 core.
Currently replies to userspace commands are only generated for read
command request. One reply is generated exactly for one w1_netlink_cmd
read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
+messages looks like the following::
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
+ [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+ cn_msg.len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
+ w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+ w1_netlink_cmd.len = cmd->len;
Replies to W1_LIST_MASTERS should send a message back to the userspace
which will contain list of all registered master ids in the following
-format:
+format::
cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
w1_netlink_msg) plus number of masters multiplied by 4)
@@ -90,39 +94,47 @@ format:
number of masters multiplied by 4 (u32 size))
id0 ... idN
- Each message is at most 4k in size, so if number of master devices
- exceeds this, it will be split into several messages.
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
W1 search and alarm search commands.
-request:
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
+
+request::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+ [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
-reply:
[cn_msg, ack = 1 and increasing, 0 means the last message,
seq is equal to the request seq]
[w1_netlink_msg type = W1_MASTER_CMD]
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
len is equal to number of IDs multiplied by 8]
[64bit-id0 ... 64bit-idN]
+
Length in each header corresponds to the size of the data behind it, so
w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
- Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
+Can be zero.
+
+::
+
+ w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+ cn_msg->len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
N*8;
-W1 reset command.
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
+W1 reset command::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_RESET]
+ [w1_netlink_cmd cmd = W1_CMD_RESET]
-Command status replies.
+Command status replies
======================
Each command (either root, master or slave with or without w1_netlink_cmd
@@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
even if there were errors, only length mismatch interrupts message processing.
-Operation steps in w1 core when new command is received.
+Operation steps in w1 core when new command is received
=======================================================
When new message (w1_netlink_msg) is received w1 core detects if it is
@@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked
and next w1_netlink_msg header processing started.
-Connector [1] specific documentation.
+Connector [1] specific documentation
====================================
Each connector message includes two u32 fields as "address".
@@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and
acknowledge number is set to seq+1.
-Additional documantion, source code examples.
-============================================
+Additional documentation, source code examples
+==============================================
1. Documentation/driver-api/connector.rst
2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
+
+ This archive includes userspace application w1d.c which uses
+ read/write/search commands for all master/slave devices found on the bus.
--
2.21.0
^ permalink raw reply related
* [PATCH 2/5] docs: misc-devices: convert files without extension to ReST
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Jean Delvare, Eric Piel, Arnd Bergmann,
Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
platform-driver-x86
In-Reply-To: <cover.1561756511.git.mchehab+samsung@kernel.org>
Those files are also text files. Convert them to ReST and add
to the misc-files index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../misc-devices/{eeprom => eeprom.rst} | 43 +++++++++------
.../{ics932s401 => ics932s401.rst} | 7 ++-
Documentation/misc-devices/index.rst | 5 ++
.../misc-devices/{isl29003 => isl29003.rst} | 15 +++++-
.../misc-devices/{lis3lv02d => lis3lv02d.rst} | 20 ++++---
.../misc-devices/{max6875 => max6875.rst} | 52 ++++++++++++++-----
MAINTAINERS | 4 +-
drivers/misc/isl29003.c | 2 +-
drivers/platform/x86/Kconfig | 2 +-
9 files changed, 108 insertions(+), 42 deletions(-)
rename Documentation/misc-devices/{eeprom => eeprom.rst} (76%)
rename Documentation/misc-devices/{ics932s401 => ics932s401.rst} (94%)
rename Documentation/misc-devices/{isl29003 => isl29003.rst} (77%)
rename Documentation/misc-devices/{lis3lv02d => lis3lv02d.rst} (90%)
rename Documentation/misc-devices/{max6875 => max6875.rst} (83%)
diff --git a/Documentation/misc-devices/eeprom b/Documentation/misc-devices/eeprom.rst
similarity index 76%
rename from Documentation/misc-devices/eeprom
rename to Documentation/misc-devices/eeprom.rst
index ba692011f221..008249675ccc 100644
--- a/Documentation/misc-devices/eeprom
+++ b/Documentation/misc-devices/eeprom.rst
@@ -1,11 +1,17 @@
+====================
Kernel driver eeprom
====================
Supported chips:
+
* Any EEPROM chip in the designated address range
+
Prefix: 'eeprom'
+
Addresses scanned: I2C 0x50 - 0x57
+
Datasheets: Publicly available from:
+
Atmel (www.atmel.com),
Catalyst (www.catsemi.com),
Fairchild (www.fairchildsemi.com),
@@ -16,7 +22,9 @@ Supported chips:
Xicor (www.xicor.com),
and others.
- Chip Size (bits) Address
+ ========= ============= ============================================
+ Chip Size (bits) Address
+ ========= ============= ============================================
24C01 1K 0x50 (shadows at 0x51 - 0x57)
24C01A 1K 0x50 - 0x57 (Typical device on DIMMs)
24C02 2K 0x50 - 0x57
@@ -24,7 +32,7 @@ Supported chips:
(additional data at 0x51, 0x53, 0x55, 0x57)
24C08 8K 0x50, 0x54 (additional data at 0x51, 0x52,
0x53, 0x55, 0x56, 0x57)
- 24C16 16K 0x50 (additional data at 0x51 - 0x57)
+ 24C16 16K 0x50 (additional data at 0x51 - 0x57)
Sony 2K 0x57
Atmel 34C02B 2K 0x50 - 0x57, SW write protect at 0x30-37
@@ -33,14 +41,15 @@ Supported chips:
Fairchild 34W02 2K 0x50 - 0x57, SW write protect at 0x30-37
Microchip 24AA52 2K 0x50 - 0x57, SW write protect at 0x30-37
ST M34C02 2K 0x50 - 0x57, SW write protect at 0x30-37
+ ========= ============= ============================================
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Jean Delvare <jdelvare@suse.de>,
- Greg Kroah-Hartman <greg@kroah.com>,
- IBM Corp.
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Jean Delvare <jdelvare@suse.de>,
+ - Greg Kroah-Hartman <greg@kroah.com>,
+ - IBM Corp.
Description
-----------
@@ -74,23 +83,25 @@ this address will write protect the memory array permanently, and the
device will no longer respond at the 0x30-37 address. The eeprom driver
does not support this register.
-Lacking functionality:
+Lacking functionality
+---------------------
* Full support for larger devices (24C04, 24C08, 24C16). These are not
-typically found on a PC. These devices will appear as separate devices at
-multiple addresses.
+ typically found on a PC. These devices will appear as separate devices at
+ multiple addresses.
* Support for really large devices (24C32, 24C64, 24C128, 24C256, 24C512).
-These devices require two-byte address fields and are not supported.
+ These devices require two-byte address fields and are not supported.
* Enable Writing. Again, no technical reason why not, but making it easy
-to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy
-to disable the DIMMs (potentially preventing the computer from booting)
-until the values are restored somehow.
+ to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy
+ to disable the DIMMs (potentially preventing the computer from booting)
+ until the values are restored somehow.
-Use:
+Use
+---
After inserting the module (and any other required SMBus/i2c modules), you
-should have some EEPROM directories in /sys/bus/i2c/devices/* of names such
+should have some EEPROM directories in ``/sys/bus/i2c/devices/*`` of names such
as "0-0050". Inside each of these is a series of files, the eeprom file
contains the binary data from EEPROM.
diff --git a/Documentation/misc-devices/ics932s401 b/Documentation/misc-devices/ics932s401.rst
similarity index 94%
rename from Documentation/misc-devices/ics932s401
rename to Documentation/misc-devices/ics932s401.rst
index bdac67ff6e3f..613ee54a9c21 100644
--- a/Documentation/misc-devices/ics932s401
+++ b/Documentation/misc-devices/ics932s401.rst
@@ -1,10 +1,15 @@
+========================
Kernel driver ics932s401
-======================
+========================
Supported chips:
+
* IDT ICS932S401
+
Prefix: 'ics932s401'
+
Addresses scanned: I2C 0x69
+
Datasheet: Publicly available at the IDT website
Author: Darrick J. Wong
diff --git a/Documentation/misc-devices/index.rst b/Documentation/misc-devices/index.rst
index dfd1f45a3127..a57f92dfe49a 100644
--- a/Documentation/misc-devices/index.rst
+++ b/Documentation/misc-devices/index.rst
@@ -14,4 +14,9 @@ fit into other categories.
.. toctree::
:maxdepth: 2
+ eeprom
ibmvmc
+ ics932s401
+ isl29003
+ lis3lv02d
+ max6875
diff --git a/Documentation/misc-devices/isl29003 b/Documentation/misc-devices/isl29003.rst
similarity index 77%
rename from Documentation/misc-devices/isl29003
rename to Documentation/misc-devices/isl29003.rst
index 80b952fd32ff..0cc38aed6c00 100644
--- a/Documentation/misc-devices/isl29003
+++ b/Documentation/misc-devices/isl29003.rst
@@ -1,10 +1,15 @@
+======================
Kernel driver isl29003
-=====================
+======================
Supported chips:
+
* Intersil ISL29003
+
Prefix: 'isl29003'
+
Addresses scanned: none
+
Datasheet:
http://www.intersil.com/data/fn/fn7464.pdf
@@ -37,25 +42,33 @@ Sysfs entries
-------------
range:
+ == ===========================
0: 0 lux to 1000 lux (default)
1: 0 lux to 4000 lux
2: 0 lux to 16,000 lux
3: 0 lux to 64,000 lux
+ == ===========================
resolution:
+ == =====================
0: 2^16 cycles (default)
1: 2^12 cycles
2: 2^8 cycles
3: 2^4 cycles
+ == =====================
mode:
+ == =================================================
0: diode1's current (unsigned 16bit) (default)
1: diode1's current (unsigned 16bit)
2: difference between diodes (l1 - l2, signed 15bit)
+ == =================================================
power_state:
+ == =================================================
0: device is disabled (default)
1: device is enabled
+ == =================================================
lux (read only):
returns the value from the last sensor reading
diff --git a/Documentation/misc-devices/lis3lv02d b/Documentation/misc-devices/lis3lv02d.rst
similarity index 90%
rename from Documentation/misc-devices/lis3lv02d
rename to Documentation/misc-devices/lis3lv02d.rst
index f89960a0ff95..959bd2b822cf 100644
--- a/Documentation/misc-devices/lis3lv02d
+++ b/Documentation/misc-devices/lis3lv02d.rst
@@ -1,3 +1,4 @@
+=======================
Kernel driver lis3lv02d
=======================
@@ -8,8 +9,8 @@ Supported chips:
LIS331DLH (16 bits)
Authors:
- Yan Burman <burman.yan@gmail.com>
- Eric Piel <eric.piel@tremplin-utc.net>
+ - Yan Burman <burman.yan@gmail.com>
+ - Eric Piel <eric.piel@tremplin-utc.net>
Description
@@ -25,11 +26,15 @@ neverball). The accelerometer data is readable via
to mg values (1/1000th of earth gravity).
Sysfs attributes under /sys/devices/platform/lis3lv02d/:
-position - 3D position that the accelerometer reports. Format: "(x,y,z)"
-rate - read reports the sampling rate of the accelerometer device in HZ.
+
+position
+ - 3D position that the accelerometer reports. Format: "(x,y,z)"
+rate
+ - read reports the sampling rate of the accelerometer device in HZ.
write changes sampling rate of the accelerometer device.
Only values which are supported by HW are accepted.
-selftest - performs selftest for the chip as specified by chip manufacturer.
+selftest
+ - performs selftest for the chip as specified by chip manufacturer.
This driver also provides an absolute input class device, allowing
the laptop to act as a pinball machine-esque joystick. Joystick device can be
@@ -69,11 +74,12 @@ Axes orientation
For better compatibility between the various laptops. The values reported by
the accelerometer are converted into a "standard" organisation of the axes
(aka "can play neverball out of the box"):
+
* When the laptop is horizontal the position reported is about 0 for X and Y
- and a positive value for Z
+ and a positive value for Z
* If the left side is elevated, X increases (becomes positive)
* If the front side (where the touchpad is) is elevated, Y decreases
- (becomes negative)
+ (becomes negative)
* If the laptop is put upside-down, Z becomes negative
If your laptop model is not recognized (cf "dmesg"), you can send an
diff --git a/Documentation/misc-devices/max6875 b/Documentation/misc-devices/max6875.rst
similarity index 83%
rename from Documentation/misc-devices/max6875
rename to Documentation/misc-devices/max6875.rst
index 2f2bd0b17b5d..ad419ac22a5b 100644
--- a/Documentation/misc-devices/max6875
+++ b/Documentation/misc-devices/max6875.rst
@@ -1,12 +1,16 @@
+=====================
Kernel driver max6875
=====================
Supported chips:
+
* Maxim MAX6874, MAX6875
+
Prefix: 'max6875'
+
Addresses scanned: None (see below)
- Datasheet:
- http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf
+
+ Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf
Author: Ben Gardner <bgardner@wabtec.com>
@@ -24,9 +28,13 @@ registers.
The Maxim MAX6874 is a similar, mostly compatible device, with more inputs
and outputs:
- vin gpi vout
+
+=========== === === ====
+- vin gpi vout
+=========== === === ====
MAX6874 6 4 8
MAX6875 4 3 5
+=========== === === ====
See the datasheet for more information.
@@ -41,13 +49,16 @@ General Remarks
---------------
Valid addresses for the MAX6875 are 0x50 and 0x52.
+
Valid addresses for the MAX6874 are 0x50, 0x52, 0x54 and 0x56.
+
The driver does not probe any address, so you explicitly instantiate the
devices.
-Example:
-$ modprobe max6875
-$ echo max6875 0x50 > /sys/bus/i2c/devices/i2c-0/new_device
+Example::
+
+ $ modprobe max6875
+ $ echo max6875 0x50 > /sys/bus/i2c/devices/i2c-0/new_device
The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple
addresses. For example, for address 0x50, it also reserves 0x51.
@@ -58,52 +69,67 @@ Programming the chip using i2c-dev
----------------------------------
Use the i2c-dev interface to access and program the chips.
+
Reads and writes are performed differently depending on the address range.
The configuration registers are at addresses 0x00 - 0x45.
+
Use i2c_smbus_write_byte_data() to write a register and
i2c_smbus_read_byte_data() to read a register.
+
The command is the register number.
Examples:
-To write a 1 to register 0x45:
+
+To write a 1 to register 0x45::
+
i2c_smbus_write_byte_data(fd, 0x45, 1);
-To read register 0x45:
+To read register 0x45::
+
value = i2c_smbus_read_byte_data(fd, 0x45);
The configuration EEPROM is at addresses 0x8000 - 0x8045.
+
The user EEPROM is at addresses 0x8100 - 0x82ff.
Use i2c_smbus_write_word_data() to write a byte to EEPROM.
The command is the upper byte of the address: 0x80, 0x81, or 0x82.
-The data word is the lower part of the address or'd with data << 8.
+The data word is the lower part of the address or'd with data << 8::
+
cmd = address >> 8;
val = (address & 0xff) | (data << 8);
Example:
-To write 0x5a to address 0x8003:
+
+To write 0x5a to address 0x8003::
+
i2c_smbus_write_word_data(fd, 0x80, 0x5a03);
Reading data from the EEPROM is a little more complicated.
+
Use i2c_smbus_write_byte_data() to set the read address and then
i2c_smbus_read_byte() or i2c_smbus_read_i2c_block_data() to read the data.
Example:
-To read data starting at offset 0x8100, first set the address:
+
+To read data starting at offset 0x8100, first set the address::
+
i2c_smbus_write_byte_data(fd, 0x81, 0x00);
-And then read the data
+And then read the data::
+
value = i2c_smbus_read_byte(fd);
- or
+or::
count = i2c_smbus_read_i2c_block_data(fd, 0x84, 16, buffer);
The block read should read 16 bytes.
+
0x84 is the block read command.
See the datasheet for more details.
diff --git a/MAINTAINERS b/MAINTAINERS
index a49698b3becd..5d4da1035a03 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8956,7 +8956,7 @@ F: include/linux/leds.h
LEGACY EEPROM DRIVER
M: Jean Delvare <jdelvare@suse.com>
S: Maintained
-F: Documentation/misc-devices/eeprom
+F: Documentation/misc-devices/eeprom.rst
F: drivers/misc/eeprom/eeprom.c
LEGO MINDSTORMS EV3
@@ -9242,7 +9242,7 @@ F: Documentation/memory-barriers.txt
LIS3LV02D ACCELEROMETER DRIVER
M: Eric Piel <eric.piel@tremplin-utc.net>
S: Maintained
-F: Documentation/misc-devices/lis3lv02d
+F: Documentation/misc-devices/lis3lv02d.rst
F: drivers/misc/lis3lv02d/
F: drivers/platform/x86/hp_accel.c
diff --git a/drivers/misc/isl29003.c b/drivers/misc/isl29003.c
index 5d0d0c3bad85..c12406f610d5 100644
--- a/drivers/misc/isl29003.c
+++ b/drivers/misc/isl29003.c
@@ -3,7 +3,7 @@
* isl29003.c - Linux kernel module for
* Intersil ISL29003 ambient light sensor
*
- * See file:Documentation/misc-devices/isl29003
+ * See file:Documentation/misc-devices/isl29003.rst
*
* Copyright (c) 2009 Daniel Mack <daniel@caiaq.de>
*
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index e09aa0087024..7fdfe107fe33 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -341,7 +341,7 @@ config HP_ACCEL
Support for a led indicating disk protection will be provided as
hp::hddprotect. For more information on the feature, refer to
- Documentation/misc-devices/lis3lv02d.
+ Documentation/misc-devices/lis3lv02d.rst.
To compile this driver as a module, choose M here: the module will
be called hp_accel.
--
2.21.0
^ permalink raw reply related
* [PATCH 5/5] docs: spi: convert to ReST and add it to the kABI bookset
From: Mauro Carvalho Chehab @ 2019-06-28 21:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Mark Brown, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-spi, linux-iio
In-Reply-To: <cover.1561756511.git.mchehab+samsung@kernel.org>
While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../spi/{butterfly => butterfly.rst} | 44 ++++----
Documentation/spi/index.rst | 23 ++++
Documentation/spi/{pxa2xx => pxa2xx.rst} | 94 ++++++++--------
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 ++-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 3 +
.../spi/{spi-summary => spi-summary.rst} | 103 ++++++++++--------
Documentation/spi/{spidev => spidev.rst} | 30 +++--
drivers/iio/dummy/iio_simple_dummy.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
13 files changed, 198 insertions(+), 127 deletions(-)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 38ece18f5d1e..bcaddbfa817f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ spi/index
w1/index
watchdog/index
input/index
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
similarity index 71%
rename from Documentation/spi/butterfly
rename to Documentation/spi/butterfly.rst
index 9927af7a629c..e614a589547c 100644
--- a/Documentation/spi/butterfly
+++ b/Documentation/spi/butterfly.rst
@@ -1,3 +1,4 @@
+===================================================
spi_butterfly - parport-to-butterfly adapter driver
===================================================
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
connector pins (used also on non-Butterfly AVR boards). On the parport
side this is like "sp12" programming cables.
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PB1/SCK = pin 2/D0
- RESET = J403.nRST = pin 3/D1
- VCC = J403.VCC_EXT = pin 8/D6
- MOSI = J403.PB2/MOSI = pin 9/D7
- MISO = J403.PB3/MISO = pin 11/S7,nBUSY
- GND = J403.GND = pin 23/GND
+ ====== ============= ===================
+ SCK J403.PB1/SCK pin 2/D0
+ RESET J403.nRST pin 3/D1
+ VCC J403.VCC_EXT pin 8/D6
+ MOSI J403.PB2/MOSI pin 9/D7
+ MISO J403.PB3/MISO pin 11/S7,nBUSY
+ GND J403.GND pin 23/GND
+ ====== ============= ===================
Then to let Linux master that bus to talk to the DataFlash chip, you must
(a) flash new firmware that disables SPI (set PRR.2, and disable pullups
by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
(c) cable in the chipselect.
+ ====== ============ ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- VCC = J400.VCC_EXT = pin 7/D5
- SELECT = J400.PB0/nSS = pin 17/C3,nSELECT
- GND = J400.GND = pin 24/GND
+ ====== ============ ===================
+ VCC J400.VCC_EXT pin 7/D5
+ SELECT J400.PB0/nSS pin 17/C3,nSELECT
+ GND J400.GND pin 24/GND
+ ====== ============ ===================
Or you could flash firmware making the AVR into an SPI slave (keeping the
DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
while letting either Linux or the AVR use the DataFlash. There are plenty
of spare parport pins to wire this one up, such as:
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PE4/USCK = pin 5/D3
- MOSI = J403.PE5/DI = pin 6/D4
- MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT
- GND = J403.GND = pin 22/GND
-
- IRQ = J402.PF4 = pin 10/S6,ACK
- GND = J402.GND(P2) = pin 25/GND
+ ====== ============= ===================
+ SCK J403.PE4/USCK pin 5/D3
+ MOSI J403.PE5/DI pin 6/D4
+ MISO J403.PE6/DO pin 12/S5,nPAPEROUT
+ GND J403.GND pin 22/GND
+ IRQ J402.PF4 pin 10/S6,ACK
+ GND J402.GND(P2) pin 25/GND
+ ====== ============= ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 000000000000..bad6259a7bb6
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ spi-summary
+ spidev
+ butterfly
+ pxa2xx
+ spi-lm70llp
+ spi-sc18is602
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
+
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
similarity index 83%
rename from Documentation/spi/pxa2xx
rename to Documentation/spi/pxa2xx.rst
index 551325b66b23..457faef8be74 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx.rst
@@ -1,8 +1,10 @@
+==============================
PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
- Support for any PXA2xx SSP
- SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
-----------------------------------
Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
"platform device". The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
-struct pxa2xx_spi_controller {
+ struct pxa2xx_spi_controller {
u16 num_chipselect;
u8 enable_dma;
-};
+ };
The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
NSSP MASTER SAMPLE
------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
-static struct resource pxa_spi_nssp_resources[] = {
+ static struct resource pxa_spi_nssp_resources[] = {
[0] = {
.start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
.end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
.end = IRQ_NSSP,
.flags = IORESOURCE_IRQ,
},
-};
+ };
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+ static struct pxa2xx_spi_controller pxa_nssp_master_info = {
.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
.enable_dma = 1, /* Enables NSSP DMA */
-};
+ };
-static struct platform_device pxa_spi_nssp = {
+ static struct platform_device pxa_spi_nssp = {
.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
.resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
.dev = {
.platform_data = &pxa_nssp_master_info, /* Passed to driver */
},
-};
+ };
-static struct platform_device *devices[] __initdata = {
+ static struct platform_device *devices[] __initdata = {
&pxa_spi_nssp,
-};
+ };
-static void __init board_init(void)
-{
+ static void __init board_init(void)
+ {
(void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+ }
Declaring Slave Devices
-----------------------
Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
Each slave device attached to the PXA must provide slave specific configuration
information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
will uses the configuration whenever the driver communicates with the slave
device. All fields are optional.
-struct pxa2xx_spi_chip {
+::
+
+ struct pxa2xx_spi_chip {
u8 tx_threshold;
u8 rx_threshold;
u8 dma_burst_size;
u32 timeout;
u8 enable_loopback;
void (*cs_control)(u32 command);
-};
+ };
The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
used to configure the SSP hardware fifo. These fields are critical to the
performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
.tx_threshold = 8,
.rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
"spi_board_info.controller_data" field. Below is a sample configuration using
the PXA255 NSSP.
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+ /* Chip Select control for the CS8415A SPI slave device */
+ static void cs8415a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(2) = GPIO_bit(2);
else
GPSR(2) = GPIO_bit(2);
-}
+ }
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+ /* Chip Select control for the CS8405A SPI slave device */
+ static void cs8405a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(3) = GPIO_bit(3);
else
GPSR(3) = GPIO_bit(3);
-}
+ }
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+ static struct pxa2xx_spi_chip cs8415a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+ };
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+ static struct pxa2xx_spi_chip cs8405a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+ };
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
{
.modalias = "cs8415a", /* Name of spi_driver for this device */
.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
.controller_data = &cs8405a_chip_info, /* Master chip config */
.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
},
-};
+ };
-static void __init streetracer_init(void)
-{
+ static void __init streetracer_init(void)
+ {
spi_register_board_info(streetracer_spi_board_info,
ARRAY_SIZE(streetracer_spi_board_info));
-}
+ }
DMA and PIO I/O Support
@@ -210,22 +216,22 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The
mode supports both coherent and stream based DMA mappings.
The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
-if !enable_dma then
+ if !enable_dma then
always use PIO transfers
-if spi_message.len > 8191 then
+ if spi_message.len > 8191 then
print "rate limited" warning
use PIO transfers
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+ if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
use coherent DMA mode
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+ if rx_buf and tx_buf are aligned on 8 byte boundary then
use streaming DMA mode
-otherwise
+ otherwise
use PIO transfer
THANKS TO
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
similarity index 88%
rename from Documentation/spi/spi-lm70llp
rename to Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
--- a/Documentation/spi/spi-lm70llp
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -1,8 +1,11 @@
+==============================================
spi_lm70llp : LM70-LLP parport-to-SPI adapter
==============================================
Supported board/chip:
+
* National Semiconductor LM70 LLP evaluation board
+
Datasheet: http://www.national.com/pf/LM/LM70.html
Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
The hardware interfacing on the LM70 LLP eval board is as follows:
+ ======== == ========= ==========
Parallel LM70 LLP
- Port Direction JP2 Header
- ----------- --------- ----------------
+ Port . Direction JP2 Header
+ ======== == ========= ==========
D0 2 - -
D1 3 --> V+ 5
D2 4 --> V+ 5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
D7 9 --> SI/O 5
GND 25 - GND 7
Select 13 <-- SI/O 1
- ----------- --------- ----------------
+ ======== == ========= ==========
Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
Thanks to
---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
similarity index 97%
rename from Documentation/spi/spi-sc18is602
rename to Documentation/spi/spi-sc18is602.rst
index 0feffd5af411..2a31dc722321 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -1,8 +1,11 @@
+===========================
Kernel driver spi-sc18is602
===========================
Supported chips:
+
* NXP SI18IS602/602B/603
+
Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
Author:
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
similarity index 93%
rename from Documentation/spi/spi-summary
rename to Documentation/spi/spi-summary.rst
index 1a63194b74d7..96b3f8b8b3db 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary.rst
@@ -1,3 +1,4 @@
+====================================
Overview of Linux kernel SPI support
====================================
@@ -139,12 +140,14 @@ a command and then reading its response.
There are two types of SPI driver, here called:
- Controller drivers ... controllers may be built into System-On-Chip
+ Controller drivers ...
+ controllers may be built into System-On-Chip
processors, and often support both Master and Slave roles.
These drivers touch hardware registers and may use DMA.
Or they can be PIO bitbangers, needing just GPIO pins.
- Protocol drivers ... these pass messages through the controller
+ Protocol drivers ...
+ these pass messages through the controller
driver to communicate with a Slave or Master device on the
other side of an SPI link.
@@ -160,7 +163,7 @@ those two types of drivers.
There is a minimal core of SPI programming interfaces, focussing on
using the driver model to connect controller and protocol drivers using
device tables provided by board specific initialization code. SPI
-shows up in sysfs in several locations:
+shows up in sysfs in several locations::
/sys/devices/.../CTLR ... physical node for a given SPI controller
@@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
That information is normally provided by board-specific code, even for
chips that do support some of automated discovery/enumeration.
-DECLARE CONTROLLERS
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
The first kind of information is a list of what SPI controllers exist.
For System-on-Chip (SOC) based boards, these will usually be platform
@@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several
SPI-capable controllers, and only the ones actually usable on a given
board should normally be set up and registered.
-So for example arch/.../mach-*/board-*.c files might have code like:
+So for example arch/.../mach-*/board-*.c files might have code like::
#include <mach/spi.h> /* for mysoc_spi_data */
@@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
...
}
-And SOC-specific utility code might look something like:
+And SOC-specific utility code might look something like::
#include <mach/spi.h>
@@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use
an external clock, where another derives the SPI clock from current
settings of some master clock.
-
-DECLARE SLAVE DEVICES
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
The second kind of information is a list of what SPI slave devices exist
on the target board, often with some board-specific data needed for the
@@ -278,7 +282,7 @@ driver to work correctly.
Normally your arch/.../mach-*/board-*.c files would provide a small table
listing the SPI devices on each board. (This would typically be only a
-small handful.) That might look like:
+small handful.) That might look like::
static struct ads7846_platform_data ads_info = {
.vref_delay_usecs = 100,
@@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller
-driver is registered:
+driver is registered::
spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
@@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
The widely used "card" style computers bundle memory, cpu, and little else
onto a card that's maybe just thirty square centimeters. On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
about the devices on the mainboard into which such a card is plugged. That
certainly includes SPI devices hooked up through the card connectors!
-NON-STATIC CONFIGURATIONS
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
Developer boards often play by different rules than product boards, and one
example is the potential need to hotplug SPI devices and/or controllers.
@@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
Most SPI drivers are currently kernel drivers, but there's also support
for userspace drivers. Here we talk only about kernel drivers.
-SPI protocol drivers somewhat resemble platform device drivers:
+SPI protocol drivers somewhat resemble platform device drivers::
static struct spi_driver CHIP_driver = {
.driver = {
@@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code
might look like this unless you're creating a device which is managing
a bus (appearing under /sys/class/spi_master).
+::
+
static int CHIP_probe(struct spi_device *spi)
{
struct CHIP *chip;
@@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
to get the driver-private data allocated for that device.
+::
+
struct spi_master *master;
struct CONTROLLER *c;
@@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
will reverse the effect of spi_register_master().
-BUS NUMBERING
+Bus Numbering
+^^^^^^^^^^^^^
Bus numbering is important, since that's how Linux identifies a given
SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
@@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
this as a non-static configuration (see above).
-SPI MASTER METHODS
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
- master->setup(struct spi_device *spi)
+``master->setup(struct spi_device *spi)``
This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep.
@@ -528,37 +539,37 @@ SPI MASTER METHODS
change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices.
- ** BUG ALERT: for some reason the first version of
- ** many spi_master drivers seems to get this wrong.
- ** When you code setup(), ASSUME that the controller
- ** is actively processing transfers for another device.
+ .. note::
- master->cleanup(struct spi_device *spi)
+ BUG ALERT: for some reason the first version of
+ many spi_master drivers seems to get this wrong.
+ When you code setup(), ASSUME that the controller
+ is actively processing transfers for another device.
+
+``master->cleanup(struct spi_device *spi)``
Your controller driver may use spi_device.controller_state to hold
state it dynamically associates with that device. If you do that,
be sure to provide the cleanup() method to free that state.
- master->prepare_transfer_hardware(struct spi_master *master)
+``master->prepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that a message is coming in soon, so the subsystem requests the
driver to prepare the transfer hardware by issuing this call.
This may sleep.
- master->unprepare_transfer_hardware(struct spi_master *master)
+``master->unprepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that there are no more messages pending in the queue and it may
relax the hardware (e.g. by power management calls). This may sleep.
- master->transfer_one_message(struct spi_master *master,
- struct spi_message *mesg)
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
The subsystem calls the driver to transfer a single message while
queuing transfers that arrive in the meantime. When the driver is
finished with this message, it must call
spi_finalize_current_message() so the subsystem can issue the next
message. This may sleep.
- master->transfer_one(struct spi_master *master, struct spi_device *spi,
- struct spi_transfer *transfer)
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
The subsystem calls the driver to transfer a single transfer while
queuing transfers that arrive in the meantime. When the driver is
finished with this transfer, it must call
@@ -568,19 +579,20 @@ SPI MASTER METHODS
not call your transfer_one callback.
Return values:
- negative errno: error
- 0: transfer is finished
- 1: transfer is still in progress
- master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
- u8 hold_clk_cycles, u8 inactive_clk_cycles)
+ * negative errno: error
+ * 0: transfer is finished
+ * 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI master controller
for configuring device specific CS setup, hold and inactive timing
requirements.
- DEPRECATED METHODS
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
- master->transfer(struct spi_device *spi, struct spi_message *message)
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
This must not sleep. Its responsibility is to arrange that the
transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete, and
@@ -590,7 +602,8 @@ SPI MASTER METHODS
implemented.
-SPI MESSAGE QUEUE
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
If you are happy with the standard queueing mechanism provided by the
SPI subsystem, just implement the queued methods specified above. Using
@@ -619,13 +632,13 @@ THANKS TO
Contributors to Linux-SPI discussions include (in alphabetical order,
by last name):
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
similarity index 90%
rename from Documentation/spi/spidev
rename to Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
--- a/Documentation/spi/spidev
+++ b/Documentation/spi/spidev.rst
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
SPI devices have a limited userspace API, supporting basic half-duplex
read() and write() access to SPI slave devices. Using ioctl() requests,
full duplex transfers and device I/O configuration are also available.
+::
+
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
busybox; it's less featureful, but often enough.) For a SPI device with
chipselect C on bus B, you should see:
- /dev/spidevB.C ... character special device, major number 153 with
+ /dev/spidevB.C ...
+ character special device, major number 153 with
a dynamically chosen minor device number. This is the node
that userspace programs will open, created by "udev" or "mdev".
- /sys/devices/.../spiB.C ... as usual, the SPI device node will
+ /sys/devices/.../spiB.C ...
+ as usual, the SPI device node will
be a child of its SPI master controller.
- /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+ /sys/class/spidev/spidevB.C ...
+ created when the "spidev" driver
binds to that device. (Directory or symlink, based on whether
or not you enabled the "deprecated sysfs files" Kconfig option.)
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
Several ioctl() requests let your driver read or override the device's current
settings for data transfer parameters:
- SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+ SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+ pass a pointer to a byte which will
return (RD) or assign (WR) the SPI transfer mode. Use the constants
SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
Note that this request is limited to SPI mode flags that fit in a
single byte.
- SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+ SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+ pass a pointer to a uin32_t
which will return (RD) or assign (WR) the full SPI transfer mode,
not limited to the bits that fit in one byte.
- SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+ SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+ pass a pointer to a byte
which will return (RD) or assign (WR) the bit justification used to
transfer SPI words. Zero indicates MSB-first; other values indicate
the less common LSB-first encoding. In both cases the specified value
is right-justified in each word, so that unused (TX) or undefined (RX)
bits are in the MSBs.
- SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+ SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+ pass a pointer to
a byte which will return (RD) or assign (WR) the number of bits in
each SPI transfer word. The value zero signifies eight bits.
- SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+ SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+ pass a pointer to a
u32 which will return (RD) or assign (WR) the maximum SPI transfer
speed, in Hz. The controller can't necessarily assign that specific
clock speed.
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index d28974ad9e0e..6cb02299a215 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
* i2c:
* Documentation/i2c/writing-clients.rst
* spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
*/
static const struct iio_sw_device_ops iio_dummy_device_ops = {
.probe = iio_dummy_probe,
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 3a1d8f1170de..d5a24fe983e7 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -543,7 +543,7 @@ config SPI_PXA2XX
help
This enables using a PXA2xx or Sodaville SSP port as a SPI master
controller. The driver can be configured to use any SSP port and
- additional documentation can be found a Documentation/spi/pxa2xx.
+ additional documentation can be found a Documentation/spi/pxa2xx.rst.
config SPI_PXA2XX_PCI
def_tristate SPI_PXA2XX && PCI && COMMON_CLK
diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
index 8c77d1114ad3..7e71a351f3b7 100644
--- a/drivers/spi/spi-butterfly.c
+++ b/drivers/spi/spi-butterfly.c
@@ -23,7 +23,7 @@
* with a battery powered AVR microcontroller and lots of goodies. You
* can use GCC to develop firmware for this.
*
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
* and use this custom parallel port cable.
*/
diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
index f18f912c9dea..174dba29b1dd 100644
--- a/drivers/spi/spi-lm70llp.c
+++ b/drivers/spi/spi-lm70llp.c
@@ -34,7 +34,7 @@
* available (on page 4) here:
* http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
*
- * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is
* (heavily) based on spi-butterfly by David Brownell.
*
* The LM70 LLP connects to the PC parallel port in the following manner:
diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
index e066d3b0d6d8..0e91489edfe6 100644
--- a/include/linux/platform_data/sc18is602.h
+++ b/include/linux/platform_data/sc18is602.h
@@ -4,7 +4,7 @@
*
* Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
*
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
*/
/**
--
2.21.0
^ permalink raw reply related
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