github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-06-07 14:04:54 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

Merge e9f8ca0ae7 ("Merge tag 'for-5.6/dm-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/device-mapper/linux-dm") into android-mainline

Browse Source 
Baby steps in the 5.6-rc1 merge cycle to make things easier to review
and debug.

Signed-off-by: Greg Kroah-Hartman <gregkh@google.com>
Change-Id: I2d3a69b5256f71ae18b500b0ef145f93e4255dbc
This commit is contained in:
Greg Kroah-Hartman 2020-02-03 10:42:29 +00:00
commit 2fa0ed8af5
1063 changed files with 33606 additions and 50759 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CREDITS
View File

@ -3302,7 +3302,9 @@ S: France
N: Aleksa Sarai
E: cyphar@cyphar.com
W: https://www.cyphar.com/
D: `pids` cgroup subsystem
D: /sys/fs/cgroup/pids
D: openat2(2)
S: Sydney, Australia
N: Dipankar Sarma
E: dipankar@in.ibm.com

4
Documentation/ABI/testing/configfs-usb-gadget
View File

@ -16,6 +16,10 @@ Description:
write UDC's name found in /sys/class/udc/*
to bind a gadget, empty string "" to unbind.
max_speed - maximum speed the driver supports. Valid
names are super-speed-plus, super-speed,
high-speed, full-speed, and low-speed.
bDeviceClass - USB device class code
bDeviceSubClass - USB device subclass code
bDeviceProtocol - USB device protocol code

13
Documentation/ABI/testing/sysfs-bus-iio
View File

@ -1726,3 +1726,16 @@ Contact: linux-iio@vger.kernel.org
Description:
List of valid periods (in seconds) for which the light intensity
must be above the threshold level before interrupt is asserted.
What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency
KernelVersion: 5.5
Contact: linux-iio@vger.kernel.org
Description:
Center frequency in Hz for a notch filter. Used i.e. for line
noise suppression.
What: /sys/bus/iio/devices/iio:deviceX/in_temp_thermocouple_type
KernelVersion: 5.5
Contact: linux-iio@vger.kernel.org
Description:
One of the following thermocouple types: B, E, J, K, N, R, S, T.

19
Documentation/ABI/testing/sysfs-bus-iio-dma-buffer Normal file
View File

@ -0,0 +1,19 @@
What: /sys/bus/iio/devices/iio:deviceX/buffer/length_align_bytes
KernelVersion: 5.4
Contact: linux-iio@vger.kernel.org
Description:
DMA buffers tend to have a alignment requirement for the
buffers. If this alignment requirement is not met samples might
be dropped from the buffer.
This property reports the alignment requirements in bytes.
This means that the buffer size in bytes needs to be a integer
multiple of the number reported by this file.
The alignment requirements in number of sample sets will depend
on the enabled channels and the bytes per channel. This means
that the alignment requirement in samples sets might change
depending on which and how many channels are enabled. Whereas
the alignment requirement reported in bytes by this property
will remain static and does not depend on which channels are
enabled.

46
Documentation/ABI/testing/usb-charger-uevent Normal file
View File

@ -0,0 +1,46 @@
What: Raise a uevent when a USB charger is inserted or removed
Date: 2020-01-14
KernelVersion: 5.6
Contact: linux-usb@vger.kernel.org
Description: There are two USB charger states:
USB_CHARGER_ABSENT
USB_CHARGER_PRESENT
There are five USB charger types:
USB_CHARGER_UNKNOWN_TYPE: Charger type is unknown
USB_CHARGER_SDP_TYPE: Standard Downstream Port
USB_CHARGER_CDP_TYPE: Charging Downstream Port
USB_CHARGER_DCP_TYPE: Dedicated Charging Port
USB_CHARGER_ACA_TYPE: Accessory Charging Adapter
https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement
Here are two examples taken using udevadm monitor -p when
USB charger is online:
UDEV change /devices/soc0/usbphynop1 (platform)
ACTION=change
DEVPATH=/devices/soc0/usbphynop1
DRIVER=usb_phy_generic
MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
OF_COMPATIBLE_0=usb-nop-xceiv
OF_COMPATIBLE_N=1
OF_FULLNAME=/usbphynop1
OF_NAME=usbphynop1
SEQNUM=2493
SUBSYSTEM=platform
USB_CHARGER_STATE=USB_CHARGER_PRESENT
USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE
USEC_INITIALIZED=227422826
USB charger is offline:
KERNEL change /devices/soc0/usbphynop1 (platform)
ACTION=change
DEVPATH=/devices/soc0/usbphynop1
DRIVER=usb_phy_generic
MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
OF_COMPATIBLE_0=usb-nop-xceiv
OF_COMPATIBLE_N=1
OF_FULLNAME=/usbphynop1
OF_NAME=usbphynop1
SEQNUM=2494
SUBSYSTEM=platform
USB_CHARGER_STATE=USB_CHARGER_ABSENT
USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE

63
Documentation/admin-guide/blockdev/zram.rst
View File

@ -1,15 +1,15 @@
========================================
zram: Compressed RAM based block devices
zram: Compressed RAM-based block devices
========================================
Introduction
============
The zram module creates RAM based block devices named /dev/zram<id>
The zram module creates RAM-based block devices named /dev/zram<id>
(<id> = 0, 1, ...). Pages written to these disks are compressed and stored
in memory itself. These disks allow very fast I/O and compression provides
good amounts of memory savings. Some of the usecases include /tmp storage,
use as swap disks, various caches under /var and maybe many more :)
good amounts of memory savings. Some of the use cases include /tmp storage,
use as swap disks, various caches under /var and maybe many more. :)
Statistics for individual zram devices are exported through sysfs nodes at
/sys/block/zram<id>/
@ -43,17 +43,17 @@ The list of possible return codes:
======== =============================================================
-EBUSY an attempt to modify an attribute that cannot be changed once
the device has been initialised. Please reset device first;
the device has been initialised. Please reset device first.
-ENOMEM zram was not able to allocate enough memory to fulfil your
needs;
needs.
-EINVAL invalid input has been provided.
======== =============================================================
If you use 'echo', the returned value that is changed by 'echo' utility,
If you use 'echo', the returned value is set by the 'echo' utility,
and, in general case, something like::
echo 3 > /sys/block/zram0/max_comp_streams
if [ $? -ne 0 ];
if [ $? -ne 0 ]; then
handle_error
fi
@ -65,7 +65,8 @@ should suffice.
::
modprobe zram num_devices=4
This creates 4 devices: /dev/zram{0,1,2,3}
This creates 4 devices: /dev/zram{0,1,2,3}
num_devices parameter is optional and tells zram how many devices should be
pre-created. Default: 1.
@ -73,12 +74,12 @@ pre-created. Default: 1.
2) Set max number of compression streams
========================================
Regardless the value passed to this attribute, ZRAM will always
allocate multiple compression streams - one per online CPUs - thus
Regardless of the value passed to this attribute, ZRAM will always
allocate multiple compression streams - one per online CPU - thus
allowing several concurrent compression operations. The number of
allocated compression streams goes down when some of the CPUs
become offline. There is no single-compression-stream mode anymore,
unless you are running a UP system or has only 1 CPU online.
unless you are running a UP system or have only 1 CPU online.
To find out how many streams are currently available::
@ -89,7 +90,7 @@ To find out how many streams are currently available::
Using comp_algorithm device attribute one can see available and
currently selected (shown in square brackets) compression algorithms,
change selected compression algorithm (once the device is initialised
or change the selected compression algorithm (once the device is initialised
there is no way to change compression algorithm).
Examples::
@ -167,9 +168,9 @@ Examples::
zram provides a control interface, which enables dynamic (on-demand) device
addition and removal.
In order to add a new /dev/zramX device, perform read operation on hot_add
attribute. This will return either new device's device id (meaning that you
can use /dev/zram<id>) or error code.
In order to add a new /dev/zramX device, perform a read operation on the hot_add
attribute. This will return either the new device's device id (meaning that you
can use /dev/zram<id>) or an error code.
Example::
@ -186,8 +187,8 @@ execute::
Per-device statistics are exported as various nodes under /sys/block/zram<id>/
A brief description of exported device attributes. For more details please
read Documentation/ABI/testing/sysfs-block-zram.
A brief description of exported device attributes follows. For more details
please read Documentation/ABI/testing/sysfs-block-zram.
====================== ====== ===============================================
Name access description
@ -245,7 +246,7 @@ whitespace:
File /sys/block/zram<id>/mm_stat
The stat file represents device's mm statistics. It consists of a single
The mm_stat file represents the device's mm statistics. It consists of a single
line of text and contains the following stats separated by whitespace:
================ =============================================================
@ -261,7 +262,7 @@ line of text and contains the following stats separated by whitespace:
Unit: bytes
mem_limit the maximum amount of memory ZRAM can use to store
the compressed data
mem_used_max the maximum amount of memory zram have consumed to
mem_used_max the maximum amount of memory zram has consumed to
store the data
same_pages the number of same element filled pages written to this disk.
No memory is allocated for such pages.
@ -271,7 +272,7 @@ line of text and contains the following stats separated by whitespace:
File /sys/block/zram<id>/bd_stat
The stat file represents device's backing device statistics. It consists of
The bd_stat file represents a device's backing device statistics. It consists of
a single line of text and contains the following stats separated by whitespace:
============== =============================================================
@ -316,9 +317,9 @@ To use the feature, admin should set up backing device via::
echo /dev/sda5 > /sys/block/zramX/backing_dev
before disksize setting. It supports only partition at this moment.
If admin want to use incompressible page writeback, they could do via::
If admin wants to use incompressible page writeback, they could do via::
echo huge > /sys/block/zramX/write
echo huge > /sys/block/zramX/writeback
To use idle page writeback, first, user need to declare zram pages
as idle::
@ -326,7 +327,7 @@ as idle::
echo all > /sys/block/zramX/idle
From now on, any pages on zram are idle pages. The idle mark
will be removed until someone request access of the block.
will be removed until someone requests access of the block.
IOW, unless there is access request, those pages are still idle pages.
Admin can request writeback of those idle pages at right timing via::
@ -341,16 +342,16 @@ to guarantee storage health for entire product life.
To overcome the concern, zram supports "writeback_limit" feature.
The "writeback_limit_enable"'s default value is 0 so that it doesn't limit
any writeback. IOW, if admin want to apply writeback budget, he should
any writeback. IOW, if admin wants to apply writeback budget, he should
enable writeback_limit_enable via::
$ echo 1 > /sys/block/zramX/writeback_limit_enable
Once writeback_limit_enable is set, zram doesn't allow any writeback
until admin set the budget via /sys/block/zramX/writeback_limit.
until admin sets the budget via /sys/block/zramX/writeback_limit.
(If admin doesn't enable writeback_limit_enable, writeback_limit's value
assigned via /sys/block/zramX/writeback_limit is meaninless.)
assigned via /sys/block/zramX/writeback_limit is meaningless.)
If admin want to limit writeback as per-day 400M, he could do it
like below::
@ -361,13 +362,13 @@ like below::
/sys/block/zram0/writeback_limit.
$ echo 1 > /sys/block/zram0/writeback_limit_enable
If admin want to allow further write again once the bugdet is exausted,
If admins want to allow further write again once the bugdet is exhausted,
he could do it like below::
$ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \
/sys/block/zram0/writeback_limit
If admin want to see remaining writeback budget since he set::
If admin wants to see remaining writeback budget since last set::
$ cat /sys/block/zramX/writeback_limit
@ -375,12 +376,12 @@ If admin want to disable writeback limit, he could do::
$ echo 0 > /sys/block/zramX/writeback_limit_enable
The writeback_limit count will reset whenever you reset zram(e.g.,
The writeback_limit count will reset whenever you reset zram (e.g.,
system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of
writeback happened until you reset the zram to allocate extra writeback
budget in next setting is user's job.
If admin want to measure writeback count in a certain period, he could
If admin wants to measure writeback count in a certain period, he could
know it via /sys/block/zram0/bd_stat's 3rd column.
memory tracking

2
Documentation/admin-guide/device-mapper/dm-raid.rst
View File

@ -419,3 +419,5 @@ Version History
rebuild errors.
1.15.0 Fix size extensions not being synchronized in case of new MD bitmap
pages allocated; also fix those not occuring after previous reductions
1.15.1 Fix argument count and arguments for rebuild/write_mostly/journal_(dev|mode)
on the status line.

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

@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
device-mapper/index
efi-stub
ext4
nfs/index
gpio/index
highuid
hw_random

5
Documentation/filesystems/nfs/fault_injection.txt → Documentation/admin-guide/nfs/fault_injection.rst
View File

@ -1,6 +1,7 @@
===================
NFS Fault Injection
===================
Fault Injection
===============
Fault injection is a method for forcing errors that may not normally occur, or
may be difficult to reproduce. Forcing these errors in a controlled environment
can help the developer find and fix bugs before their code is shipped in a

15
Documentation/admin-guide/nfs/index.rst Normal file
View File

@ -0,0 +1,15 @@
=============
NFS
=============
.. toctree::
:maxdepth: 1
nfs-client
nfsroot
nfs-rdma
nfsd-admin-interfaces
nfs-idmapper
pnfs-block-server
pnfs-scsi-server
fault_injection

79
Documentation/filesystems/nfs/nfs.txt → Documentation/admin-guide/nfs/nfs-client.rst
View File

@ -1,3 +1,6 @@
==========
NFS Client
==========
The NFS client
==============
@ -59,10 +62,11 @@ The DNS resolver
NFSv4 allows for one server to refer the NFS client to data that has been
migrated onto another server by means of the special "fs_locations"
attribute. See
http://tools.ietf.org/html/rfc3530#section-6
and
http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and
`Implementation Guide for Referrals in NFSv4`_.
.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6
.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
The fs_locations information can take the form of either an ip address and
a path, or a DNS hostname and a path. The latter requires the NFS client to
@ -78,8 +82,8 @@ Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual
(2) If no valid entry exists, the helper script '/sbin/nfs_cache_getent'
(may be changed using the 'nfs.cache_getent' kernel boot parameter)
is run, with two arguments:
- the cache name, "dns_resolve"
- the hostname to resolve
- the cache name, "dns_resolve"
- the hostname to resolve
(3) After looking up the corresponding ip address, the helper script
writes the result into the rpc_pipefs pseudo-file
@ -94,43 +98,44 @@ Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual
script, and <ttl> is the 'time to live' of this cache entry (in
units of seconds).
Note: If <ip address> is invalid, say the string "0", then a negative
entry is created, which will cause the kernel to treat the hostname
as having no valid DNS translation.
.. note::
If <ip address> is invalid, say the string "0", then a negative
entry is created, which will cause the kernel to treat the hostname
as having no valid DNS translation.
A basic sample /sbin/nfs_cache_getent
=====================================
.. code-block:: sh
#!/bin/bash
#
ttl=600
#
cut=/usr/bin/cut
getent=/usr/bin/getent
rpc_pipefs=/var/lib/nfs/rpc_pipefs
#
die()
{
echo "Usage: $0 cache_name entry_name"
exit 1
}
#!/bin/bash
#
ttl=600
#
cut=/usr/bin/cut
getent=/usr/bin/getent
rpc_pipefs=/var/lib/nfs/rpc_pipefs
#
die()
{
echo "Usage: $0 cache_name entry_name"
exit 1
}
[ $# -lt 2 ] && die
cachename="$1"
cache_path=${rpc_pipefs}/cache/${cachename}/channel
case "${cachename}" in
dns_resolve)
name="$2"
result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )"
[ -z "${result}" ] && result="0"
;;
*)
die
;;
esac
echo "${result} ${name} ${ttl}" >${cache_path}
[ $# -lt 2 ] && die
cachename="$1"
cache_path=${rpc_pipefs}/cache/${cachename}/channel
case "${cachename}" in
dns_resolve)
name="$2"
result="$(${getent} hosts ${name} | ${cut} -f1 -d\ )"
[ -z "${result}" ] && result="0"
;;
*)
die
;;
esac
echo "${result} ${name} ${ttl}" >${cache_path}

31
Documentation/filesystems/nfs/idmapper.txt → Documentation/admin-guide/nfs/nfs-idmapper.rst
View File

@ -1,7 +1,7 @@
=============
NFS ID Mapper
=============
=========
ID Mapper
=========
Id mapper is used by NFS to translate user and group ids into names, and to
translate user and group names into ids. Part of this translation involves
performing an upcall to userspace to request the information. There are two
@ -20,22 +20,24 @@ legacy rpc.idmap daemon for the id mapping. This result will be stored
in a custom NFS idmap cache.
===========
Configuring
===========
The file /etc/request-key.conf will need to be modified so /sbin/request-key can
direct the upcall. The following line should be added:
#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...
#====== ======= =============== =============== ===============================
create id_resolver * * /usr/sbin/nfs.idmap %k %d 600
``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...``
``#====== ======= =============== =============== ===============================``
``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600``
This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap.
The last parameter, 600, defines how many seconds into the future the key will
expire. This parameter is optional for /usr/sbin/nfs.idmap. When the timeout
is not specified, nfs.idmap will default to 600 seconds.
id mapper uses for key descriptions:
id mapper uses for key descriptions::
uid: Find the UID for the given user
gid: Find the GID for the given group
user: Find the user name for the given UID
@ -45,23 +47,24 @@ You can handle any of these individually, rather than using the generic upcall
program. If you would like to use your own program for a uid lookup then you
would edit your request-key.conf so it look similar to this:
#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...
#====== ======= =============== =============== ===============================
create id_resolver uid:* * /some/other/program %k %d 600
create id_resolver * * /usr/sbin/nfs.idmap %k %d 600
``#OP TYPE DESCRIPTION CALLOUT INFO PROGRAM ARG1 ARG2 ARG3 ...``
``#====== ======= =============== =============== ===============================``
``create id_resolver uid:* * /some/other/program %k %d 600``
``create id_resolver * * /usr/sbin/nfs.idmap %k %d 600``
Notice that the new line was added above the line for the generic program.
request-key will find the first matching line and corresponding program. In
this case, /some/other/program will handle all uid lookups and
/usr/sbin/nfs.idmap will handle gid, user, and group lookups.
See <file:Documentation/security/keys/request-key.rst> for more information
See Documentation/security/keys/request-key.rst for more information
about the request-key function.
=========
nfs.idmap
=========
nfs.idmap is designed to be called by request-key, and should not be run "by
hand". This program takes two arguments, a serialized key and a key
description. The serialized key is first converted into a key_serial_t, and

292
Documentation/admin-guide/nfs/nfs-rdma.rst Normal file
View File

@ -0,0 +1,292 @@
===================
Setting up NFS/RDMA
===================
:Author:
NetApp and Open Grid Computing (May 29, 2008)
.. warning::
This document is probably obsolete.
Overview
========
This document describes how to install and setup the Linux NFS/RDMA client
and server software.
The NFS/RDMA client was first included in Linux 2.6.24. The NFS/RDMA server
was first included in the following release, Linux 2.6.25.
In our testing, we have obtained excellent performance results (full 10Gbit
wire bandwidth at minimal client CPU) under many workloads. The code passes
the full Connectathon test suite and operates over both Infiniband and iWARP
RDMA adapters.
Getting Help
============
If you get stuck, you can ask questions on the
nfs-rdma-devel@lists.sourceforge.net mailing list.
Installation
============
These instructions are a step by step guide to building a machine for
use with NFS/RDMA.
- Install an RDMA device
Any device supported by the drivers in drivers/infiniband/hw is acceptable.
Testing has been performed using several Mellanox-based IB cards, the
Ammasso AMS1100 iWARP adapter, and the Chelsio cxgb3 iWARP adapter.
- Install a Linux distribution and tools
The first kernel release to contain both the NFS/RDMA client and server was
Linux 2.6.25 Therefore, a distribution compatible with this and subsequent
Linux kernel release should be installed.
The procedures described in this document have been tested with
distributions from Red Hat's Fedora Project (http://fedora.redhat.com/).
- Install nfs-utils-1.1.2 or greater on the client
An NFS/RDMA mount point can be obtained by using the mount.nfs command in
nfs-utils-1.1.2 or greater (nfs-utils-1.1.1 was the first nfs-utils
version with support for NFS/RDMA mounts, but for various reasons we
recommend using nfs-utils-1.1.2 or greater). To see which version of
mount.nfs you are using, type:
.. code-block:: sh
$ /sbin/mount.nfs -V
If the version is less than 1.1.2 or the command does not exist,
you should install the latest version of nfs-utils.
Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs
Uncompress the package and follow the installation instructions.
If you will not need the idmapper and gssd executables (you do not need
these to create an NFS/RDMA enabled mount command), the installation
process can be simplified by disabling these features when running
configure:
.. code-block:: sh
$ ./configure --disable-gss --disable-nfsv4
To build nfs-utils you will need the tcp_wrappers package installed. For
more information on this see the package's README and INSTALL files.
After building the nfs-utils package, there will be a mount.nfs binary in
the utils/mount directory. This binary can be used to initiate NFS v2, v3,
or v4 mounts. To initiate a v4 mount, the binary must be called
mount.nfs4. The standard technique is to create a symlink called
mount.nfs4 to mount.nfs.
This mount.nfs binary should be installed at /sbin/mount.nfs as follows:
.. code-block:: sh
$ sudo cp utils/mount/mount.nfs /sbin/mount.nfs
In this location, mount.nfs will be invoked automatically for NFS mounts
by the system mount command.
.. note::
mount.nfs and therefore nfs-utils-1.1.2 or greater is only needed
on the NFS client machine. You do not need this specific version of
nfs-utils on the server. Furthermore, only the mount.nfs command from
nfs-utils-1.1.2 is needed on the client.
- Install a Linux kernel with NFS/RDMA
The NFS/RDMA client and server are both included in the mainline Linux
kernel version 2.6.25 and later. This and other versions of the Linux
kernel can be found at: https://www.kernel.org/pub/linux/kernel/
Download the sources and place them in an appropriate location.
- Configure the RDMA stack
Make sure your kernel configuration has RDMA support enabled. Under
Device Drivers -> InfiniBand support, update the kernel configuration
to enable InfiniBand support [NOTE: the option name is misleading. Enabling
InfiniBand support is required for all RDMA devices (IB, iWARP, etc.)].
Enable the appropriate IB HCA support (mlx4, mthca, ehca, ipath, etc.) or
iWARP adapter support (amso, cxgb3, etc.).
If you are using InfiniBand, be sure to enable IP-over-InfiniBand support.
- Configure the NFS client and server
Your kernel configuration must also have NFS file system support and/or
NFS server support enabled. These and other NFS related configuration
options can be found under File Systems -> Network File Systems.
- Build, install, reboot
The NFS/RDMA code will be enabled automatically if NFS and RDMA
are turned on. The NFS/RDMA client and server are configured via the hidden
SUNRPC_XPRT_RDMA config option that depends on SUNRPC and INFINIBAND. The
value of SUNRPC_XPRT_RDMA will be:
#. N if either SUNRPC or INFINIBAND are N, in this case the NFS/RDMA client
and server will not be built
#. M if both SUNRPC and INFINIBAND are on (M or Y) and at least one is M,
in this case the NFS/RDMA client and server will be built as modules
#. Y if both SUNRPC and INFINIBAND are Y, in this case the NFS/RDMA client
and server will be built into the kernel
Therefore, if you have followed the steps above and turned no NFS and RDMA,
the NFS/RDMA client and server will be built.
Build a new kernel, install it, boot it.
Check RDMA and NFS Setup
========================
Before configuring the NFS/RDMA software, it is a good idea to test
your new kernel to ensure that the kernel is working correctly.
In particular, it is a good idea to verify that the RDMA stack
is functioning as expected and standard NFS over TCP/IP and/or UDP/IP
is working properly.
- Check RDMA Setup
If you built the RDMA components as modules, load them at
this time. For example, if you are using a Mellanox Tavor/Sinai/Arbel
card:
.. code-block:: sh
$ modprobe ib_mthca
$ modprobe ib_ipoib
If you are using InfiniBand, make sure there is a Subnet Manager (SM)
running on the network. If your IB switch has an embedded SM, you can
use it. Otherwise, you will need to run an SM, such as OpenSM, on one
of your end nodes.
If an SM is running on your network, you should see the following:
.. code-block:: sh
$ cat /sys/class/infiniband/driverX/ports/1/state
4: ACTIVE
where driverX is mthca0, ipath5, ehca3, etc.
To further test the InfiniBand software stack, use IPoIB (this
assumes you have two IB hosts named host1 and host2):
.. code-block:: sh
host1$ ip link set dev ib0 up
host1$ ip address add dev ib0 a.b.c.x
host2$ ip link set dev ib0 up
host2$ ip address add dev ib0 a.b.c.y
host1$ ping a.b.c.y
host2$ ping a.b.c.x
For other device types, follow the appropriate procedures.
- Check NFS Setup
For the NFS components enabled above (client and/or server),
test their functionality over standard Ethernet using TCP/IP or UDP/IP.
NFS/RDMA Setup
==============
We recommend that you use two machines, one to act as the client and
one to act as the server.
One time configuration:
-----------------------
- On the server system, configure the /etc/exports file and start the NFS/RDMA server.
Exports entries with the following formats have been tested::
/vol0 192.168.0.47(fsid=0,rw,async,insecure,no_root_squash)
/vol0 192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash)
The IP address(es) is(are) the client's IPoIB address for an InfiniBand
HCA or the client's iWARP address(es) for an RNIC.
.. note::
The "insecure" option must be used because the NFS/RDMA client does
not use a reserved port.
Each time a machine boots:
--------------------------
- Load and configure the RDMA drivers
For InfiniBand using a Mellanox adapter:
.. code-block:: sh
$ modprobe ib_mthca
$ modprobe ib_ipoib
$ ip li set dev ib0 up
$ ip addr add dev ib0 a.b.c.d
.. note::
Please use unique addresses for the client and server!
- Start the NFS server
If the NFS/RDMA server was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in
kernel config), load the RDMA transport module:
.. code-block:: sh
$ modprobe svcrdma
Regardless of how the server was built (module or built-in), start the
server:
.. code-block:: sh
$ /etc/init.d/nfs start
or
.. code-block:: sh
$ service nfs start
Instruct the server to listen on the RDMA transport:
.. code-block:: sh
$ echo rdma 20049 > /proc/fs/nfsd/portlist
- On the client system
If the NFS/RDMA client was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in
kernel config), load the RDMA client module:
.. code-block:: sh
$ modprobe xprtrdma.ko
Regardless of how the client was built (module or built-in), use this
command to mount the NFS/RDMA server:
.. code-block:: sh
$ mount -o rdma,port=20049 <IPoIB-server-name-or-address>:/<export> /mnt
To verify that the mount is using RDMA, run "cat /proc/mounts" and check
the "proto" field for the given mount.
Congratulations! You're using NFS/RDMA!

19
Documentation/filesystems/nfs/nfsd-admin-interfaces.txt → Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst
View File

@ -1,5 +1,6 @@
==================================
Administrative interfaces for nfsd
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
==================================
Note that normally these interfaces are used only by the utilities in
nfs-utils.
@ -13,18 +14,16 @@ nfsd/threads.
Before doing that, NFSD can be told which sockets to listen on by
writing to nfsd/portlist; that write may be:
- an ascii-encoded file descriptor, which should refer to a
bound (and listening, for tcp) socket, or
- "transportname port", where transportname is currently either
"udp", "tcp", or "rdma".
- an ascii-encoded file descriptor, which should refer to a
bound (and listening, for tcp) socket, or
- "transportname port", where transportname is currently either
"udp", "tcp", or "rdma".
If nfsd is started without doing any of these, then it will create one
udp and one tcp listener at port 2049 (see nfsd_init_socks).
On startup, nfsd and lockd grace periods start.
nfsd is shut down by a write of 0 to nfsd/threads. All locks and state
are thrown away at that point.
On startup, nfsd and lockd grace periods start. nfsd is shut down by a write of
0 to nfsd/threads. All locks and state are thrown away at that point.
Between startup and shutdown, the number of threads may be adjusted up
or down by additional writes to nfsd/threads or by writes to
@ -34,7 +33,7 @@ For more detail about files under nfsd/ and what they control, see
fs/nfsd/nfsctl.c; most of them have detailed comments.
Implementation notes
^^^^^^^^^^^^^^^^^^^^
====================
Note that the rpc server requires the caller to serialize addition and
removal of listening sockets, and startup and shutdown of the server.

149
Documentation/filesystems/nfs/nfsroot.txt → Documentation/admin-guide/nfs/nfsroot.rst
View File

@ -1,27 +1,34 @@
===============================================
Mounting the root filesystem via NFS (nfsroot)
===============================================
Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
Updated 2006 by Horms <horms@verge.net.au>
Updated 2018 by Chris Novakovic <chris@chrisn.me.uk>
:Authors:
Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
Updated 2006 by Horms <horms@verge.net.au>
Updated 2018 by Chris Novakovic <chris@chrisn.me.uk>
In order to use a diskless system, such as an X-terminal or printer server
for example, it is necessary for the root filesystem to be present on a
non-disk device. This may be an initramfs (see Documentation/filesystems/
ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a
filesystem mounted via NFS. The following text describes on how to use NFS
for the root filesystem. For the rest of this text 'client' means the
diskless system, and 'server' means the NFS server.
In order to use a diskless system, such as an X-terminal or printer server for
example, it is necessary for the root filesystem to be present on a non-disk
device. This may be an initramfs (see
Documentation/filesystems/ramfs-rootfs-initramfs.txt), a ramdisk (see
Documentation/admin-guide/initrd.rst) or a filesystem mounted via NFS. The
following text describes on how to use NFS for the root filesystem. For the rest
of this text 'client' means the diskless system, and 'server' means the NFS
server.
1.) Enabling nfsroot capabilities
-----------------------------
Enabling nfsroot capabilities
=============================
In order to use nfsroot, NFS client support needs to be selected as
built-in during configuration. Once this has been selected, the nfsroot
@ -34,8 +41,8 @@ DHCP, BOOTP and RARP is safe.
2.) Kernel command line
-------------------
Kernel command line
===================
When the kernel has been loaded by a boot loader (see below) it needs to be
told what root fs device to use. And in the case of nfsroot, where to find
@ -44,19 +51,17 @@ This can be established using the following kernel command line parameters:
root=/dev/nfs
This is necessary to enable the pseudo-NFS-device. Note that it's not a
real device but just a synonym to tell the kernel to use NFS instead of
a real device.
nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
If the `nfsroot' parameter is NOT given on the command line,
the default "/tftpboot/%s" will be used.
the default ``"/tftpboot/%s"`` will be used.
<server-ip> Specifies the IP address of the NFS server.
The default address is determined by the `ip' parameter
The default address is determined by the ip parameter
(see below). This parameter allows the use of different
servers for IP autoconfiguration and NFS.
@ -66,7 +71,8 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
IP address.
<nfs-options> Standard NFS options. All options are separated by commas.
The following defaults are used:
The following defaults are used::
port = as given by server portmap daemon
rsize = 4096
wsize = 4096
@ -79,13 +85,11 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
flags = hard, nointr, noposix, cto, ac
ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:
<dns0-ip>:<dns1-ip>:<ntp0-ip>
ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>:<ntp0-ip>
This parameter tells the kernel how to configure IP addresses of devices
and also how to set up the IP routing table. It was originally called
`nfsaddrs', but now the boot-time IP configuration works independently of
NFS, so it was renamed to `ip' and the old name remained as an alias for
nfsaddrs, but now the boot-time IP configuration works independently of
NFS, so it was renamed to ip and the old name remained as an alias for
compatibility reasons.
If this parameter is missing from the kernel command line, all fields are
@ -93,17 +97,17 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:
this means that the kernel tries to configure everything using
autoconfiguration.
The <autoconf> parameter can appear alone as the value to the `ip'
The <autoconf> parameter can appear alone as the value to the ip
parameter (without all the ':' characters before). If the value is
"ip=off" or "ip=none", no autoconfiguration will take place, otherwise
autoconfiguration will take place. The most common way to use this
is "ip=dhcp".
<client-ip> IP address of the client.
Default: Determined using autoconfiguration.
<server-ip> IP address of the NFS server. If RARP is used to determine
<server-ip> IP address of the NFS server.
If RARP is used to determine
the client address and this parameter is NOT empty only
replies from the specified server are accepted.
@ -115,19 +119,19 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:
(see below).
Default: Determined using autoconfiguration.
The address of the autoconfiguration server is used.
The address of the autoconfiguration server is used.
<gw-ip> IP address of a gateway if the server is on a different subnet.
Default: Determined using autoconfiguration.
<netmask> Netmask for local network interface. If unspecified
the netmask is derived from the client IP address assuming
classful addressing.
<netmask> Netmask for local network interface.
If unspecified the netmask is derived from the client IP address
assuming classful addressing.
Default: Determined using autoconfiguration.
<hostname> Name of the client. If a '.' character is present, anything
<hostname> Name of the client.
If a '.' character is present, anything
before the first '.' is used as the client's hostname, and anything
after it is used as its NIS domain name. May be supplied by
autoconfiguration, but its absence will not trigger autoconfiguration.
@ -138,21 +142,21 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:
Default: Client IP address is used in ASCII notation.
<device> Name of network device to use.
Default: If the host only has one device, it is used.
Otherwise the device is determined using
autoconfiguration. This is done by sending
autoconfiguration requests out of all devices,
and using the device that received the first reply.
Otherwise the device is determined using
autoconfiguration. This is done by sending
autoconfiguration requests out of all devices,
and using the device that received the first reply.
<autoconf> Method to use for autoconfiguration. In the case of options
which specify multiple autoconfiguration protocols,
<autoconf> Method to use for autoconfiguration.
In the case of options
which specify multiple autoconfiguration protocols,
requests are sent using all protocols, and the first one
to reply is used.
Only autoconfiguration protocols that have been compiled
into the kernel will be used, regardless of the value of
this option.
this option::
off or none: don't use autoconfiguration
(do static IP assignment instead)
@ -221,7 +225,6 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:
nfsrootdebug
This parameter enables debugging messages to appear in the kernel
log at boot time so that administrators can verify that the correct
NFS mount options, server address, and root path are passed to the
@ -229,36 +232,32 @@ nfsrootdebug
rdinit=<executable file>
To specify which file contains the program that starts system
initialization, administrators can use this command line parameter.
The default value of this parameter is "/init". If the specified
file exists and the kernel can execute it, root filesystem related
kernel command line parameters, including `nfsroot=', are ignored.
kernel command line parameters, including 'nfsroot=', are ignored.
A description of the process of mounting the root file system can be
found in:
Documentation/driver-api/early-userspace/early_userspace_support.rst
found in Documentation/driver-api/early-userspace/early_userspace_support.rst
3.) Boot Loader
----------
Boot Loader
===========
To get the kernel into memory different approaches can be used.
They depend on various facilities being available:
3.1) Booting from a floppy using syslinux
- Booting from a floppy using syslinux
When building kernels, an easy way to create a boot floppy that uses
syslinux is to use the zdisk or bzdisk make targets which use zimage
and bzimage images respectively. Both targets accept the
FDARGS parameter which can be used to set the kernel command line.
e.g.
e.g::
make bzdisk FDARGS="root=/dev/nfs"
Note that the user running this command will need to have
@ -267,32 +266,36 @@ They depend on various facilities being available:
For more information on syslinux, including how to create bootdisks
for prebuilt kernels, see http://syslinux.zytor.com/
N.B: Previously it was possible to write a kernel directly to
a floppy using dd, configure the boot device using rdev, and
boot using the resulting floppy. Linux no longer supports this
method of booting.
.. note::
Previously it was possible to write a kernel directly to
a floppy using dd, configure the boot device using rdev, and
boot using the resulting floppy. Linux no longer supports this
method of booting.
3.2) Booting from a cdrom using isolinux
- Booting from a cdrom using isolinux
When building kernels, an easy way to create a bootable cdrom that
uses isolinux is to use the isoimage target which uses a bzimage
image. Like zdisk and bzdisk, this target accepts the FDARGS
parameter which can be used to set the kernel command line.
e.g.
e.g::
make isoimage FDARGS="root=/dev/nfs"
The resulting iso image will be arch/<ARCH>/boot/image.iso
This can be written to a cdrom using a variety of tools including
cdrecord.
e.g.
e.g::
cdrecord dev=ATAPI:1,0,0 arch/x86/boot/image.iso
For more information on isolinux, including how to create bootdisks
for prebuilt kernels, see http://syslinux.zytor.com/
3.2) Using LILO
- Using LILO
When using LILO all the necessary command line parameters may be
specified using the 'append=' directive in the LILO configuration
file.
@ -300,15 +303,19 @@ They depend on various facilities being available:
However, to use the 'root=' directive you also need to create
a dummy root device, which may be removed after LILO is run.
mknod /dev/boot255 c 0 255
e.g::
mknod /dev/boot255 c 0 255
For information on configuring LILO, please refer to its documentation.
3.3) Using GRUB
- Using GRUB
When using GRUB, kernel parameter are simply appended after the kernel
specification: kernel <kernel> <parameters>
3.4) Using loadlin
- Using loadlin
loadlin may be used to boot Linux from a DOS command prompt without
requiring a local hard disk to mount as root. This has not been
thoroughly tested by the authors of this document, but in general
@ -317,7 +324,8 @@ They depend on various facilities being available:
Please refer to the loadlin documentation for further information.
3.5) Using a boot ROM
- Using a boot ROM
This is probably the most elegant way of booting a diskless client.
With a boot ROM the kernel is loaded using the TFTP protocol. The
authors of this document are not aware of any no commercial boot
@ -326,7 +334,8 @@ They depend on various facilities being available:
etherboot, both of which are available on sunsite.unc.edu, and both
of which contain everything you need to boot a diskless Linux client.
3.6) Using pxelinux
- Using pxelinux
Pxelinux may be used to boot linux using the PXE boot loader
which is present on many modern network cards.
@ -342,8 +351,8 @@ They depend on various facilities being available:
4.) Credits
-------
Credits
=======
The nfsroot code in the kernel and the RARP support have been written
by Gero Kuhlmann <gero@gkminix.han.de>.

25
Documentation/filesystems/nfs/pnfs-block-server.txt → Documentation/admin-guide/nfs/pnfs-block-server.rst
View File

@ -1,4 +1,6 @@
===================================
pNFS block layout server user guide
===================================
The Linux NFS server now supports the pNFS block layout extension. In this
case the NFS server acts as Metadata Server (MDS) for pNFS, which in addition
@ -22,16 +24,19 @@ If the nfsd server needs to fence a non-responding client it calls
/sbin/nfsd-recall-failed with the first argument set to the IP address of
the client, and the second argument set to the device node without the /dev
prefix for the file system to be fenced. Below is an example file that shows
how to translate the device into a serial number from SCSI EVPD 0x80:
how to translate the device into a serial number from SCSI EVPD 0x80::
cat > /sbin/nfsd-recall-failed << EOF
#!/bin/sh
cat > /sbin/nfsd-recall-failed << EOF
CLIENT="$1"
DEV="/dev/$2"
EVPD=`sg_inq --page=0x80 ${DEV} | \
grep "Unit serial number:" | \
awk -F ': ' '{print $2}'`
.. code-block:: sh
echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log
EOF
#!/bin/sh
CLIENT="$1"
DEV="/dev/$2"
EVPD=`sg_inq --page=0x80 ${DEV} | \
grep "Unit serial number:" | \
awk -F ': ' '{print $2}'`
echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log
EOF

1
Documentation/filesystems/nfs/pnfs-scsi-server.txt → Documentation/admin-guide/nfs/pnfs-scsi-server.rst
View File

@ -1,4 +1,5 @@
==================================
pNFS SCSI layout server user guide
==================================

30
Documentation/admin-guide/thunderbolt.rst
View File

@ -1,6 +1,28 @@
=============
Thunderbolt
=============
.. SPDX-License-Identifier: GPL-2.0
======================
USB4 and Thunderbolt
======================
USB4 is the public specification based on Thunderbolt 3 protocol with
some differences at the register level among other things. Connection
manager is an entity running on the host router (host controller)
responsible for enumerating routers and establishing tunnels. A
connection manager can be implemented either in firmware or software.
Typically PCs come with a firmware connection manager for Thunderbolt 3
and early USB4 capable systems. Apple systems on the other hand use
software connection manager and the later USB4 compliant devices follow
the suit.
The Linux Thunderbolt driver supports both and can detect at runtime which
connection manager implementation is to be used. To be on the safe side the
software connection manager in Linux also advertises security level
``user`` which means PCIe tunneling is disabled by default. The
documentation below applies to both implementations with the exception that
the software connection manager only supports ``user`` security level and
is expected to be accompanied with an IOMMU based DMA protection.
Security levels and how to use them
-----------------------------------
The interface presented here is not meant for end users. Instead there
should be a userspace tool that handles all the low-level details, keeps
a database of the authorized devices and prompts users for new connections.
@ -18,8 +40,6 @@ This will authorize all devices automatically when they appear. However,
keep in mind that this bypasses the security levels and makes the system
vulnerable to DMA attacks.
Security levels and how to use them
-----------------------------------
Starting with Intel Falcon Ridge Thunderbolt controller there are 4
security levels available. Intel Titan Ridge added one more security level
(usbonly). The reason for these is the fact that the connected devices can

9
Documentation/asm-annotations.rst
View File

@ -73,10 +73,11 @@ The new macros are prefixed with the ``SYM_`` prefix and can be divided into
three main groups:
1. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with
standard C calling conventions, i.e. the stack contains a return address at
the predefined place and a return from the function can happen in a
standard way. When frame pointers are enabled, save/restore of frame
pointer shall happen at the start/end of a function, respectively, too.
standard C calling conventions. For example, on x86, this means that the
stack contains a return address at the predefined place and a return from
the function can happen in a standard way. When frame pointers are enabled,
save/restore of frame pointer shall happen at the start/end of a function,
respectively, too.
Checking tools like ``objtool`` should ensure such marked functions conform
to these rules. The tools can also easily annotate these functions with

2
Documentation/block/biovecs.rst
View File

@ -47,7 +47,7 @@ Having a real iterator, and making biovecs immutable, has a number of
advantages:
* Before, iterating over bios was very awkward when you weren't processing
exactly one bvec at a time - for example, bio_copy_data() in fs/bio.c,
exactly one bvec at a time - for example, bio_copy_data() in block/bio.c,
which copies the contents of one bio into another. Because the biovecs
wouldn't necessarily be the same size, the old code was tricky convoluted -
it had to walk two different bios at the same time, keeping both bi_idx and

3
Documentation/dev-tools/kunit/faq.rst
View File

@ -29,7 +29,8 @@ Yes, well, mostly.
For the most part, the KUnit core framework (what you use to write the tests)
can compile to any architecture; it compiles like just another part of the
kernel and runs when the kernel boots. However, there is some infrastructure,
kernel and runs when the kernel boots, or when built as a module, when the
module is loaded. However, there is some infrastructure,
like the KUnit Wrapper (``tools/testing/kunit/kunit.py``) that does not support
other architectures.

3
Documentation/dev-tools/kunit/index.rst
View File

@ -49,6 +49,9 @@ to a standalone program that can be run like any other program directly inside
of a host operating system; to be clear, it does not require any virtualization
support; it is just a regular program.
Alternatively, kunit and kunit tests can be built as modules and tests will
run when the test module is loaded.
KUnit is fast. Excluding build time, from invocation to completion KUnit can run
several dozen tests in only 10 to 20 seconds; this might not sound like a big
deal to some people, but having such fast and easy to run tests fundamentally

16
Documentation/dev-tools/kunit/usage.rst
View File

@ -539,6 +539,22 @@ Interspersed in the kernel logs you might see the following:
Congratulations, you just ran a KUnit test on the x86 architecture!
In a similar manner, kunit and kunit tests can also be built as modules,
so if you wanted to run tests in this way you might add the following config
options to your ``.config``:
.. code-block:: none
CONFIG_KUNIT=m
CONFIG_KUNIT_EXAMPLE_TEST=m
Once the kernel is built and installed, a simple
.. code-block:: bash
modprobe example-test
...will run the tests.
Writing new tests for other architectures
-----------------------------------------

4
Documentation/devicetree/bindings/connector/usb-connector.txt
View File

@ -1,8 +1,8 @@
USB Connector
=============
USB connector node represents physical USB connector. It should be
a child of USB interface controller.
A USB connector node represents a physical USB connector. It should be
a child of a USB interface controller.
Required properties:
- compatible: describes type of the connector, must be one of:

47
Documentation/devicetree/bindings/gpio/qcom,wcd934x-gpio.yaml Normal file
View File

@ -0,0 +1,47 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/gpio/qcom,wcd934x-gpio.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: WCD9340/WCD9341 GPIO controller
maintainers:
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
description: |
Qualcomm Technologies Inc WCD9340/WCD9341 Audio Codec has integrated
gpio controller to control 5 gpios on the chip.
properties:
compatible:
enum:
- qcom,wcd9340-gpio
- qcom,wcd9341-gpio
reg:
maxItems: 1
gpio-controller: true
'#gpio-cells':
const: 2
required:
- compatible
- reg
- gpio-controller
- "#gpio-cells"
additionalProperties: false
examples:
- |
wcdgpio: gpio@42 {
compatible = "qcom,wcd9340-gpio";
reg = <0x042 0x2>;
gpio-controller;
#gpio-cells = <2>;
};
...

3
Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
View File

@ -18,7 +18,8 @@ Required Properties:
- "renesas,gpio-r8a7793": for R8A7793 (R-Car M2-N) compatible GPIO controller.
- "renesas,gpio-r8a7794": for R8A7794 (R-Car E2) compatible GPIO controller.
- "renesas,gpio-r8a7795": for R8A7795 (R-Car H3) compatible GPIO controller.
- "renesas,gpio-r8a7796": for R8A7796 (R-Car M3-W) compatible GPIO controller.
- "renesas,gpio-r8a7796": for R8A77960 (R-Car M3-W) compatible GPIO controller.
- "renesas,gpio-r8a77961": for R8A77961 (R-Car M3-W+) compatible GPIO controller.
- "renesas,gpio-r8a77965": for R8A77965 (R-Car M3-N) compatible GPIO controller.
- "renesas,gpio-r8a77970": for R8A77970 (R-Car V3M) compatible GPIO controller.
- "renesas,gpio-r8a77980": for R8A77980 (R-Car V3H) compatible GPIO controller.

69
Documentation/devicetree/bindings/gpio/xylon,logicvc-gpio.yaml Normal file
View File

@ -0,0 +1,69 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2019 Bootlin
%YAML 1.2
---
$id: "http://devicetree.org/schemas/gpio/xylon,logicvc-gpio.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"
title: Xylon LogiCVC GPIO controller
maintainers:
- Paul Kocialkowski <paul.kocialkowski@bootlin.com>
description: |
The LogiCVC GPIO describes the GPIO block included in the LogiCVC display
controller. These are meant to be used for controlling display-related
signals.
The controller exposes GPIOs from the display and power control registers,
which are mapped by the driver as follows:
- GPIO[4:0] (display control) mapped to index 0-4
- EN_BLIGHT (power control) mapped to index 5
- EN_VDD (power control) mapped to index 6
- EN_VEE (power control) mapped to index 7
- V_EN (power control) mapped to index 8
properties:
$nodename:
pattern: "^gpio@[0-9a-f]+$"
compatible:
enum:
- xylon,logicvc-3.02.a-gpio
reg:
maxItems: 1
"#gpio-cells":
const: 2
gpio-controller: true
gpio-line-names:
minItems: 1
maxItems: 9
required:
- compatible
- reg
- "#gpio-cells"
- gpio-controller
examples:
- |
logicvc: logicvc@43c00000 {
compatible = "xylon,logicvc-3.02.a", "syscon", "simple-mfd";
reg = <0x43c00000 0x6000>;
#address-cells = <1>;
#size-cells = <1>;
logicvc_gpio: gpio@40 {
compatible = "xylon,logicvc-3.02.a-gpio";
reg = <0x40 0x40>;
gpio-controller;
#gpio-cells = <2>;
gpio-line-names = "GPIO0", "GPIO1", "GPIO2", "GPIO3", "GPIO4",
"EN_BLIGHT", "EN_VDD", "EN_VEE", "V_EN";
};
};

49
Documentation/devicetree/bindings/iio/accel/adi,adis16240.yaml Normal file
View File

@ -0,0 +1,49 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/accel/adi,adis16240.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: ADIS16240 Programmable Impact Sensor and Recorder driver
maintainers:
- Alexandru Ardelean <alexandru.ardelean@analog.com>
description: |
ADIS16240 Programmable Impact Sensor and Recorder driver that supports
SPI interface.
https://www.analog.com/en/products/adis16240.html
properties:
compatible:
enum:
- adi,adis16240
reg:
maxItems: 1
interrupts:
maxItems: 1
required:
- compatible
- reg
- interrupts
examples:
- |
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
spi0 {
#address-cells = <1>;
#size-cells = <0>;
/* Example for a SPI device node */
accelerometer@0 {
compatible = "adi,adis16240";
reg = <0>;
spi-max-frequency = <2500000>;
interrupt-parent = <&gpio0>;
interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
};
};

7
Documentation/devicetree/bindings/iio/accel/bma180.txt
View File

@ -1,11 +1,14 @@
* Bosch BMA180 / BMA250 triaxial acceleration sensor
* Bosch BMA180 / BMA25x triaxial acceleration sensor
http://omapworld.com/BMA180_111_1002839.pdf
http://ae-bst.resource.bosch.com/media/products/dokumente/bma250/bst-bma250-ds002-05.pdf
Required properties:
- compatible : should be "bosch,bma180" or "bosch,bma250"
- compatible : should be one of:
"bosch,bma180"
"bosch,bma250"
"bosch,bma254"
- reg : the I2C address of the sensor
Optional properties:

54
Documentation/devicetree/bindings/iio/accel/bosch,bma400.yaml Normal file
View File

@ -0,0 +1,54 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/accel/bosch,bma400.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Bosch BMA400 triaxial acceleration sensor
maintainers:
- Dan Robertson <dan@dlrobertson.com>
description: |
Acceleration and temperature iio sensors with an i2c interface
Specifications about the sensor can be found at:
https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMA400-DS000.pdf
properties:
compatible:
enum:
- bosch,bma400
reg:
maxItems: 1
vdd-supply:
description: phandle to the regulator that provides power to the accelerometer
vddio-supply:
description: phandle to the regulator that provides power to the sensor's IO
interrupts:
maxItems: 1
required:
- compatible
- reg
examples:
- |
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
accelerometer@14 {
compatible = "bosch,bma400";
reg = <0x14>;
vdd-supply = <&vdd>;
vddio-supply = <&vddio>;
interrupt-parent = <&gpio0>;
interrupts = <0 IRQ_TYPE_LEVEL_HIGH>;
};
};

7
Documentation/devicetree/bindings/iio/accel/kionix,kxcjk1013.txt
View File

@ -9,9 +9,16 @@ Required properties:
"kionix,kxtf9"
- reg: i2c slave address
Optional properties:
- mount-matrix: an optional 3x3 mounting rotation matrix
Example:
kxtf9@f {
compatible = "kionix,kxtf9";
reg = <0x0F>;
mount-matrix = "0", "1", "0",
"1", "0", "0",
"0", "0", "1";
};

54
Documentation/devicetree/bindings/iio/adc/adi,ad7091r5.yaml Normal file
View File

@ -0,0 +1,54 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/adc/adi,ad7091r5.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Analog Devices AD7091R5 4-Channel 12-Bit ADC
maintainers:
- Beniamin Bia <beniamin.bia@analog.com>
description: |
Analog Devices AD7091R5 4-Channel 12-Bit ADC
https://www.analog.com/media/en/technical-documentation/data-sheets/ad7091r-5.pdf
properties:
compatible:
enum:
- adi,ad7091r5
reg:
maxItems: 1
vref-supply:
description:
Phandle to the vref power supply
interrupts:
maxItems: 1
required:
- compatible
- reg
additionalProperties: false
examples:
- |
#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/interrupt-controller/irq.h>
i2c {
#address-cells = <1>;
#size-cells = <0>;
adc@2f {
compatible = "adi,ad7091r5";
reg = <0x2f>;
interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
interrupt-parent = <&gpio>;
};
};
...

47
Documentation/devicetree/bindings/iio/adc/lltc,ltc2496.yaml Normal file
View File

@ -0,0 +1,47 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/adc/lltc,ltc2496.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Linear Technology / Analog Devices LTC2496 ADC
maintainers:
- Lars-Peter Clausen <lars@metafoo.de>
- Michael Hennerich <Michael.Hennerich@analog.com>
- Stefan Popa <stefan.popa@analog.com>
properties:
compatible:
enum:
- lltc,ltc2496
vref-supply:
description: phandle to an external regulator providing the reference voltage
allOf:
- $ref: /schemas/types.yaml#/definitions/phandle
reg:
description: spi chipselect number according to the usual spi bindings
spi-max-frequency:
description: maximal spi bus frequency supported
required:
- compatible
- vref-supply
- reg
examples:
- |
spi {
#address-cells = <1>;
#size-cells = <0>;
adc@0 {
compatible = "lltc,ltc2496";
reg = <0>;
vref-supply = <&ltc2496_reg>;
spi-max-frequency = <2000000>;
};
};

13
Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.txt
View File

@ -1,13 +0,0 @@
Device-Tree bindings for sigma delta modulator
Required properties:
- compatible: should be "ads1201", "sd-modulator". "sd-modulator" can be use
as a generic SD modulator if modulator not specified in compatible list.
- #io-channel-cells = <0>: See the IIO bindings section "IIO consumers".
Example node:
ads1202: adc {
compatible = "sd-modulator";
#io-channel-cells = <0>;
};

37
Documentation/devicetree/bindings/iio/adc/sigma-delta-modulator.yaml Normal file
View File

@ -0,0 +1,37 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/adc/sigma-delta-modulator.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Device-Tree bindings for sigma delta modulator
maintainers:
- Arnaud Pouliquen <arnaud.pouliquen@st.com>
properties:
compatible:
description: |
"sd-modulator" can be used as a generic SD modulator,
if the modulator is not specified in the compatible list.
enum:
- sd-modulator
- ads1201
'#io-channel-cells':
const: 0
required:
- compatible
- '#io-channel-cells'
additionalProperties: false
examples:
- |
ads1202: adc {
compatible = "sd-modulator";
#io-channel-cells = <0>;
};
...

1
Documentation/devicetree/bindings/iio/imu/adi,adis16480.txt
View File

@ -8,6 +8,7 @@ Required properties for the ADIS16480:
* "adi,adis16480"
* "adi,adis16485"
* "adi,adis16488"
* "adi,adis16490"
* "adi,adis16495-1"
* "adi,adis16495-2"
* "adi,adis16495-3"

51
Documentation/devicetree/bindings/iio/pressure/asc,dlhl60d.yaml Normal file
View File

@ -0,0 +1,51 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/pressure/asc,dlhl60d.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: All Sensors DLH series low voltage digital pressure sensors
maintainers:
- Tomislav Denis <tomislav.denis@avl.com>
description: |
Bindings for the All Sensors DLH series pressure sensors.
Specifications about the sensors can be found at:
http://www.allsensors.com/cad/DS-0355_Rev_B.PDF
properties:
compatible:
enum:
- asc,dlhl60d
- asc,dlhl60g
reg:
description: I2C device address
maxItems: 1
interrupts:
description: interrupt mapping for EOC(data ready) pin
maxItems: 1
required:
- compatible
- reg
examples:
- |
#include <dt-bindings/interrupt-controller/irq.h>
i2c0 {
#address-cells = <1>;
#size-cells = <0>;
pressure@29 {
compatible = "asc,dlhl60d";
reg = <0x29>;
interrupt-parent = <&gpio0>;
interrupts = <10 IRQ_TYPE_EDGE_RISING>;
};
};
...

51
Documentation/devicetree/bindings/iio/proximity/parallax-ping.yaml Normal file
View File

@ -0,0 +1,51 @@
# SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iio/proximity/parallax-ping.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Parallax PING))) and LaserPING range finder
maintainers:
- Andreas Klinger <ak@it-klinger.de>
description: |
Bit-banging driver using one GPIO:
- ping-gpios is raised by the driver to start measurement
- direction of ping-gpio is then switched into input with an interrupt
for receiving distance value as PWM signal
Specifications about the devices can be found at:
http://parallax.com/sites/default/files/downloads/28041-LaserPING-2m-Rangefinder-Guide.pdf
http://parallax.com/sites/default/files/downloads/28015-PING-Documentation-v1.6.pdf
properties:
compatible:
enum:
- parallax,ping
- parallax,laserping
ping-gpios:
description:
Definition of the GPIO for the triggering and echo (output and input)
This GPIO is set for about 5 us by the driver to tell the device it
should initiate the measurement cycle. Afterwards the GPIO is switched
to input direction with an interrupt. The device sets it and the
length of the input signal corresponds to the measured distance.
It needs to be an GPIO which is able to deliver an interrupt because
the time between two interrupts is measured in the driver.
See Documentation/devicetree/bindings/gpio/gpio.txt for information
on how to specify a consumer gpio.
maxItems: 1
required:
- compatible
- ping-gpios
examples:
- |
#include <dt-bindings/gpio/gpio.h>
proximity {
compatible = "parallax,laserping";
ping-gpios = <&gpio0 26 GPIO_ACTIVE_HIGH>;
};

7
Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt
View File

@ -5,7 +5,10 @@ Maxim thermocouple support
Required properties:
- compatible: must be "maxim,max31855" or "maxim,max6675"
- compatible: must be "maxim,max6675" or one of the following:
"maxim,max31855k", "maxim,max31855j", "maxim,max31855n",
"maxim,max31855s", "maxim,max31855t", "maxim,max31855e",
"maxim,max31855r"; the generic "max,max31855" is deprecated.
- reg: SPI chip select number for the device
- spi-max-frequency: must be 4300000
- spi-cpha: must be defined for max6675 to enable SPI mode 1
@ -15,7 +18,7 @@ Required properties:
Example:
max31855@0 {
compatible = "maxim,max31855";
compatible = "maxim,max31855k";
reg = <0>;
spi-max-frequency = <4300000>;
};

77
Documentation/devicetree/bindings/interconnect/qcom,msm8916.yaml Normal file
View File

@ -0,0 +1,77 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/interconnect/qcom,msm8916.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm MSM8916 Network-On-Chip interconnect
maintainers:
- Georgi Djakov <georgi.djakov@linaro.org>
description: |
The Qualcomm MSM8916 interconnect providers support adjusting the
bandwidth requirements between the various NoC fabrics.
properties:
compatible:
enum:
- qcom,msm8916-bimc
- qcom,msm8916-pcnoc
- qcom,msm8916-snoc
reg:
maxItems: 1
'#interconnect-cells':
const: 1
clock-names:
items:
- const: bus
- const: bus_a
clocks:
items:
- description: Bus Clock
- description: Bus A Clock
required:
- compatible
- reg
- '#interconnect-cells'
- clock-names
- clocks
additionalProperties: false
examples:
- |
#include <dt-bindings/clock/qcom,rpmcc.h>
bimc: interconnect@400000 {
compatible = "qcom,msm8916-bimc";
reg = <0x00400000 0x62000>;
#interconnect-cells = <1>;
clock-names = "bus", "bus_a";
clocks = <&rpmcc RPM_SMD_BIMC_CLK>,
<&rpmcc RPM_SMD_BIMC_A_CLK>;
};
pcnoc: interconnect@500000 {
compatible = "qcom,msm8916-pcnoc";
reg = <0x00500000 0x11000>;
#interconnect-cells = <1>;
clock-names = "bus", "bus_a";
clocks = <&rpmcc RPM_SMD_PCNOC_CLK>,
<&rpmcc RPM_SMD_PCNOC_A_CLK>;
};
snoc: interconnect@580000 {
compatible = "qcom,msm8916-snoc";
reg = <0x00580000 0x14000>;
#interconnect-cells = <1>;
clock-names = "bus", "bus_a";
clocks = <&rpmcc RPM_SMD_SNOC_CLK>,
<&rpmcc RPM_SMD_SNOC_A_CLK>;
};

50
Documentation/devicetree/bindings/mfd/xylon,logicvc.yaml Normal file
View File

@ -0,0 +1,50 @@
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
# Copyright 2019 Bootlin
%YAML 1.2
---
$id: "http://devicetree.org/schemas/mfd/xylon,logicvc.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"
title: Xylon LogiCVC multi-function device
maintainers:
- Paul Kocialkowski <paul.kocialkowski@bootlin.com>
description: |
The LogiCVC is a display controller that also contains a GPIO controller.
As a result, a multi-function device is exposed as parent of the display
and GPIO blocks.
properties:
compatible:
items:
- enum:
- xylon,logicvc-3.02.a
- const: syscon
- const: simple-mfd
reg:
maxItems: 1
select:
properties:
compatible:
contains:
enum:
- xylon,logicvc-3.02.a
required:
- compatible
required:
- compatible
- reg
examples:
- |
logicvc: logicvc@43c00000 {
compatible = "xylon,logicvc-3.02.a", "syscon", "simple-mfd";
reg = <0x43c00000 0x6000>;
#address-cells = <1>;
#size-cells = <1>;
};

3
Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
View File

@ -2,7 +2,7 @@ Freescale i.MX6 On-Chip OTP Controller (OCOTP) device tree bindings
This binding represents the on-chip eFuse OTP controller found on
i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ, i.MX6SLL,
i.MX7D/S, i.MX7ULP, i.MX8MQ, i.MX8MM and i.MX8MN SoCs.
i.MX7D/S, i.MX7ULP, i.MX8MQ, i.MX8MM, i.MX8MN and i.MX8MP SoCs.
Required properties:
- compatible: should be one of
@ -17,6 +17,7 @@ Required properties:
"fsl,imx8mq-ocotp" (i.MX8MQ),
"fsl,imx8mm-ocotp" (i.MX8MM),
"fsl,imx8mn-ocotp" (i.MX8MN),
"fsl,imx8mp-ocotp" (i.MX8MP),
followed by "syscon".
- #address-cells : Should be 1
- #size-cells : Should be 1

84
Documentation/devicetree/bindings/nvmem/qcom,spmi-sdam.yaml Normal file
View File

@ -0,0 +1,84 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/nvmem/qcom,spmi-sdam.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Qualcomm Technologies, Inc. SPMI SDAM DT bindings
maintainers:
- Shyam Kumar Thella <sthella@codeaurora.org>
description: |
The SDAM provides scratch register space for the PMIC clients. This
memory can be used by software to store information or communicate
to/from the PBUS.
allOf:
- $ref: "nvmem.yaml#"
properties:
compatible:
enum:
- qcom,spmi-sdam
reg:
maxItems: 1
"#address-cells":
const: 1
"#size-cells":
const: 1
ranges: true
required:
- compatible
- reg
- ranges
patternProperties:
"^.*@[0-9a-f]+$":
type: object
properties:
reg:
maxItems: 1
description:
Offset and size in bytes within the storage device.
bits:
$ref: /schemas/types.yaml#/definitions/uint32-array
maxItems: 1
items:
items:
- minimum: 0
maximum: 7
description:
Offset in bit within the address range specified by reg.
- minimum: 1
description:
Size in bit within the address range specified by reg.
required:
- reg
additionalProperties: false
examples:
- |
sdam_1: nvram@b000 {
#address-cells = <1>;
#size-cells = <1>;
compatible = "qcom,spmi-sdam";
reg = <0xb000 0x100>;
ranges = <0 0xb000 0x100>;
/* Data cells */
restart_reason: restart@50 {
reg = <0x50 0x1>;
bits = <6 2>;
};
};
...

135
Documentation/devicetree/bindings/phy/allwinner,sun9i-a80-usb-phy.yaml Normal file
View File

@ -0,0 +1,135 @@
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/phy/allwinner,sun9i-a80-usb-phy.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Allwinner A80 USB PHY Device Tree Bindings
maintainers:
- Chen-Yu Tsai <wens@csie.org>
- Maxime Ripard <mripard@kernel.org>
properties:
"#phy-cells":
const: 0
compatible:
const: allwinner,sun9i-a80-usb-phy
reg:
maxItems: 1
clocks:
anyOf:
- description: Main PHY Clock
- items:
- description: Main PHY clock
- description: HSIC 12MHz clock
- description: HSIC 480MHz clock
clock-names:
oneOf:
- const: phy
- items:
- const: phy
- const: hsic_12M
- const: hsic_480M
resets:
anyOf:
- description: Normal USB PHY reset
- items:
- description: Normal USB PHY reset
- description: HSIC Reset
reset-names:
oneOf:
- const: phy
- items:
- const: phy
- const: hsic
phy_type:
const: hsic
description:
When absent, the PHY type will be assumed to be normal USB.
phy-supply:
description:
Regulator that powers VBUS
required:
- "#phy-cells"
- compatible
- reg
- clocks
- clock-names
- resets
- reset-names
additionalProperties: false
if:
properties:
phy_type:
const: hsic
required:
- phy_type
then:
properties:
clocks:
maxItems: 3
clock-names:
maxItems: 3
resets:
maxItems: 2
reset-names:
maxItems: 2
examples:
- |
#include <dt-bindings/clock/sun9i-a80-usb.h>
#include <dt-bindings/reset/sun9i-a80-usb.h>
usbphy1: phy@a00800 {
compatible = "allwinner,sun9i-a80-usb-phy";
reg = <0x00a00800 0x4>;
clocks = <&usb_clocks CLK_USB0_PHY>;
clock-names = "phy";
resets = <&usb_clocks RST_USB0_PHY>;
reset-names = "phy";
phy-supply = <&reg_usb1_vbus>;
#phy-cells = <0>;
};
- |
#include <dt-bindings/clock/sun9i-a80-usb.h>
#include <dt-bindings/reset/sun9i-a80-usb.h>
usbphy3: phy@a02800 {
compatible = "allwinner,sun9i-a80-usb-phy";
reg = <0x00a02800 0x4>;
clocks = <&usb_clocks CLK_USB2_PHY>,
<&usb_clocks CLK_USB_HSIC>,
<&usb_clocks CLK_USB2_HSIC>;
clock-names = "phy",
"hsic_12M",
"hsic_480M";
resets = <&usb_clocks RST_USB2_PHY>,
<&usb_clocks RST_USB2_HSIC>;
reset-names = "phy",
"hsic";
phy_type = "hsic";
phy-supply = <&reg_usb3_vbus>;
#phy-cells = <0>;
};

69
Documentation/devicetree/bindings/phy/brcm,brcmstb-usb-phy.txt
View File

@ -1,30 +1,49 @@
Broadcom STB USB PHY
Required properties:
- compatible: brcm,brcmstb-usb-phy
- reg: two offset and length pairs.
The first pair specifies a manditory set of memory mapped
registers used for general control of the PHY.
The second pair specifies optional registers used by some of
the SoCs that support USB 3.x
- #phy-cells: Shall be 1 as it expects one argument for setting
the type of the PHY. Possible values are:
- PHY_TYPE_USB2 for USB1.1/2.0 PHY
- PHY_TYPE_USB3 for USB3.x PHY
- compatible: should be one of
"brcm,brcmstb-usb-phy"
"brcm,bcm7216-usb-phy"
"brcm,bcm7211-usb-phy"
- reg and reg-names properties requirements are specific to the
compatible string.
"brcm,brcmstb-usb-phy":
- reg: 1 or 2 offset and length pairs. One for the base CTRL registers
and an optional pair for systems with USB 3.x support
- reg-names: not specified
"brcm,bcm7216-usb-phy":
- reg: 3 offset and length pairs for CTRL, XHCI_EC and XHCI_GBL
registers
- reg-names: "ctrl", "xhci_ec", "xhci_gbl"
"brcm,bcm7211-usb-phy":
- reg: 5 offset and length pairs for CTRL, XHCI_EC, XHCI_GBL,
USB_PHY and USB_MDIO registers and an optional pair
for the BDC registers
- reg-names: "ctrl", "xhci_ec", "xhci_gbl", "usb_phy", "usb_mdio", "bdc_ec"
- #phy-cells: Shall be 1 as it expects one argument for setting
the type of the PHY. Possible values are:
- PHY_TYPE_USB2 for USB1.1/2.0 PHY
- PHY_TYPE_USB3 for USB3.x PHY
Optional Properties:
- clocks : clock phandles.
- clock-names: String, clock name.
- interrupts: wakeup interrupt
- interrupt-names: "wakeup"
- brcm,ipp: Boolean, Invert Port Power.
Possible values are: 0 (Don't invert), 1 (Invert)
- brcm,ioc: Boolean, Invert Over Current detection.
Possible values are: 0 (Don't invert), 1 (Invert)
NOTE: one or both of the following two properties must be set
- brcm,has-xhci: Boolean indicating the phy has an XHCI phy.
- brcm,has-eohci: Boolean indicating the phy has an EHCI/OHCI phy.
- dr_mode: String, PHY Device mode.
Possible values are: "host", "peripheral ", "drd" or "typec-pd"
If this property is not defined, the phy will default to "host" mode.
- brcm,syscon-piarbctl: phandle to syscon for handling config registers
NOTE: one or both of the following two properties must be set
- brcm,has-xhci: Boolean indicating the phy has an XHCI phy.
- brcm,has-eohci: Boolean indicating the phy has an EHCI/OHCI phy.
Example:
@ -41,3 +60,27 @@ usbphy_0: usb-phy@f0470200 {
clocks = <&usb20>, <&usb30>;
clock-names = "sw_usb", "sw_usb3";
};
usb-phy@29f0200 {
reg = <0x29f0200 0x200>,
<0x29c0880 0x30>,
<0x29cc100 0x534>,
<0x2808000 0x24>,
<0x2980080 0x8>;
reg-names = "ctrl",
"xhci_ec",
"xhci_gbl",
"usb_phy",
"usb_mdio";
brcm,ioc = <0x0>;
brcm,ipp = <0x0>;
compatible = "brcm,bcm7211-usb-phy";
interrupts = <0x30>;
interrupt-parent = <&vpu_intr1_nosec_intc>;
interrupt-names = "wake";
#phy-cells = <0x1>;
brcm,has-xhci;
syscon-piarbctl = <&syscon_piarbctl>;
clocks = <&scmi_clk 256>;
clock-names = "sw_usb";
};

1
Documentation/devicetree/bindings/phy/brcm-sata-phy.txt
View File

@ -2,6 +2,7 @@
Required properties:
- compatible: should be one or more of
"brcm,bcm7216-sata-phy"
"brcm,bcm7425-sata-phy"
"brcm,bcm7445-sata-phy"
"brcm,iproc-ns2-sata-phy"

56
Documentation/devicetree/bindings/phy/intel,lgm-emmc-phy.yaml Normal file
View File

@ -0,0 +1,56 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/phy/intel,lgm-emmc-phy.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Intel Lightning Mountain(LGM) eMMC PHY Device Tree Bindings
maintainers:
- Ramuthevar Vadivel Murugan <vadivel.muruganx.ramuthevar@linux.intel.com>
description: |+
Bindings for eMMC PHY on Intel's Lightning Mountain SoC, syscon
node is used to reference the base address of eMMC phy registers.
The eMMC PHY node should be the child of a syscon node with the
required property:
- compatible: Should be one of the following:
"intel,lgm-syscon", "syscon"
- reg:
maxItems: 1
properties:
compatible:
const: intel,lgm-emmc-phy
"#phy-cells":
const: 0
reg:
maxItems: 1
clocks:
maxItems: 1
required:
- "#phy-cells"
- compatible
- reg
- clocks
examples:
- |
sysconf: chiptop@e0200000 {
compatible = "intel,lgm-syscon", "syscon";
reg = <0xe0200000 0x100>;
emmc-phy: emmc-phy@a8 {
compatible = "intel,lgm-emmc-phy";
reg = <0x00a8 0x10>;
clocks = <&emmc>;
#phy-cells = <0>;
};
};
...

13
Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt
View File

@ -2,21 +2,24 @@ Cadence Sierra PHY
-----------------------
Required properties:
- compatible: cdns,sierra-phy-t0
- clocks: Must contain an entry in clock-names.
See ../clocks/clock-bindings.txt for details.
- clock-names: Must be "phy_clk"
- compatible: Must be "cdns,sierra-phy-t0" for Sierra in Cadence platform
Must be "ti,sierra-phy-t0" for Sierra in TI's J721E SoC.
- resets: Must contain an entry for each in reset-names.
See ../reset/reset.txt for details.
- reset-names: Must include "sierra_reset" and "sierra_apb".
"sierra_reset" must control the reset line to the PHY.
"sierra_apb" must control the reset line to the APB PHY
interface.
interface ("sierra_apb" is optional).
- reg: register range for the PHY.
- #address-cells: Must be 1
- #size-cells: Must be 0
Optional properties:
- clocks: Must contain an entry in clock-names.
See ../clocks/clock-bindings.txt for details.
- clock-names: Must contain "cmn_refclk_dig_div" and
"cmn_refclk1_dig_div" for configuring the frequency of
the clock to the lanes. "phy_clk" is deprecated.
- cdns,autoconf: A boolean property whose presence indicates that the
PHY registers will be configured by hardware. If not
present, all sub-node optional properties must be

5
Documentation/devicetree/bindings/phy/rockchip,px30-dsi-dphy.yaml
View File

@ -13,9 +13,6 @@ properties:
"#phy-cells":
const: 0
"#clock-cells":
const: 0
compatible:
enum:
- rockchip,px30-dsi-dphy
@ -49,7 +46,6 @@ properties:
required:
- "#phy-cells"
- "#clock-cells"
- compatible
- reg
- clocks
@ -66,7 +62,6 @@ examples:
reg = <0x0 0xff2e0000 0x0 0x10000>;
clocks = <&pmucru 13>, <&cru 12>;
clock-names = "ref", "pclk";
#clock-cells = <0>;
resets = <&cru 12>;
reset-names = "apb";
#phy-cells = <0>;

37
Documentation/devicetree/bindings/phy/sun9i-usb-phy.txt
View File

@ -1,37 +0,0 @@
Allwinner sun9i USB PHY
-----------------------
Required properties:
- compatible : should be one of
* allwinner,sun9i-a80-usb-phy
- reg : a list of offset + length pairs
- #phy-cells : from the generic phy bindings, must be 0
- phy_type : "hsic" for HSIC usage;
other values or absence of this property indicates normal USB
- clocks : phandle + clock specifier for the phy clocks
- clock-names : depending on the "phy_type" property,
* "phy" for normal USB
* "hsic_480M", "hsic_12M" for HSIC
- resets : a list of phandle + reset specifier pairs
- reset-names : depending on the "phy_type" property,
* "phy" for normal USB
* "hsic" for HSIC
Optional Properties:
- phy-supply : from the generic phy bindings, a phandle to a regulator that
provides power to VBUS.
It is recommended to list all clocks and resets available.
The driver will only use those matching the phy_type.
Example:
usbphy1: phy@a01800 {
compatible = "allwinner,sun9i-a80-usb-phy";
reg = <0x00a01800 0x4>;
clocks = <&usb_phy_clk 2>, <&usb_phy_clk 10>,
<&usb_phy_clk 3>;
clock-names = "hsic_480M", "hsic_12M", "phy";
resets = <&usb_phy_clk 18>, <&usb_phy_clk 19>;
reset-names = "hsic", "phy";
#phy-cells = <0>;
};

221
Documentation/devicetree/bindings/phy/ti,phy-j721e-wiz.yaml Normal file
View File

@ -0,0 +1,221 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (C) 2019 Texas Instruments Incorporated - http://www.ti.com/
%YAML 1.2
---
$id: "http://devicetree.org/schemas/phy/ti,phy-j721e-wiz.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"
title: TI J721E WIZ (SERDES Wrapper)
maintainers:
- Kishon Vijay Abraham I <kishon@ti.com>
properties:
compatible:
enum:
- ti,j721e-wiz-16g
- ti,j721e-wiz-10g
power-domains:
maxItems: 1
clocks:
maxItems: 3
description: clock-specifier to represent input to the WIZ
clock-names:
items:
- const: fck
- const: core_ref_clk
- const: ext_ref_clk
num-lanes:
minimum: 1
maximum: 4
"#address-cells":
const: 1
"#size-cells":
const: 1
"#reset-cells":
const: 1
ranges: true
assigned-clocks:
maxItems: 2
assigned-clock-parents:
maxItems: 2
typec-dir-gpios:
maxItems: 1
description:
GPIO to signal Type-C cable orientation for lane swap.
If GPIO is active, lane 0 and lane 1 of SERDES will be swapped to
achieve the funtionality of an external type-C plug flip mux.
typec-dir-debounce-ms:
minimum: 100
maximum: 1000
default: 100
description:
Number of milliseconds to wait before sampling typec-dir-gpio.
If not specified, the default debounce of 100ms will be used.
Type-C spec states minimum CC pin debounce of 100 ms and maximum
of 200 ms. However, some solutions might need more than 200 ms.
patternProperties:
"^pll[0|1]-refclk$":
type: object
description: |
WIZ node should have subnodes for each of the PLLs present in
the SERDES.
properties:
clocks:
maxItems: 2
description: Phandle to clock nodes representing the two inputs to PLL.
"#clock-cells":
const: 0
assigned-clocks:
maxItems: 1
assigned-clock-parents:
maxItems: 1
required:
- clocks
- "#clock-cells"
- assigned-clocks
- assigned-clock-parents
"^cmn-refclk1?-dig-div$":
type: object
description:
WIZ node should have subnodes for each of the PMA common refclock
provided by the SERDES.
properties:
clocks:
maxItems: 1
description: Phandle to the clock node representing the input to the
divider clock.
"#clock-cells":
const: 0
required:
- clocks
- "#clock-cells"
"^refclk-dig$":
type: object
description: |
WIZ node should have subnode for refclk_dig to select the reference
clock source for the reference clock used in the PHY and PMA digital
logic.
properties:
clocks:
maxItems: 4
description: Phandle to four clock nodes representing the inputs to
refclk_dig
"#clock-cells":
const: 0
assigned-clocks:
maxItems: 1
assigned-clock-parents:
maxItems: 1
required:
- clocks
- "#clock-cells"
- assigned-clocks
- assigned-clock-parents
"^serdes@[0-9a-f]+$":
type: object
description: |
WIZ node should have '1' subnode for the SERDES. It could be either
Sierra SERDES or Torrent SERDES. Sierra SERDES should follow the
bindings specified in
Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt
Torrent SERDES should follow the bindings specified in
Documentation/devicetree/bindings/phy/phy-cadence-dp.txt
required:
- compatible
- power-domains
- clocks
- clock-names
- num-lanes
- "#address-cells"
- "#size-cells"
- "#reset-cells"
- ranges
examples:
- |
#include <dt-bindings/soc/ti,sci_pm_domain.h>
wiz@5000000 {
compatible = "ti,j721e-wiz-16g";
#address-cells = <1>;
#size-cells = <1>;
power-domains = <&k3_pds 292 TI_SCI_PD_EXCLUSIVE>;
clocks = <&k3_clks 292 5>, <&k3_clks 292 11>, <&dummy_cmn_refclk>;
clock-names = "fck", "core_ref_clk", "ext_ref_clk";
assigned-clocks = <&k3_clks 292 11>, <&k3_clks 292 0>;
assigned-clock-parents = <&k3_clks 292 15>, <&k3_clks 292 4>;
num-lanes = <2>;
#reset-cells = <1>;
ranges = <0x5000000 0x5000000 0x10000>;
pll0-refclk {
clocks = <&k3_clks 293 13>, <&dummy_cmn_refclk>;
#clock-cells = <0>;
assigned-clocks = <&wiz1_pll0_refclk>;
assigned-clock-parents = <&k3_clks 293 13>;
};
pll1-refclk {
clocks = <&k3_clks 293 0>, <&dummy_cmn_refclk1>;
#clock-cells = <0>;
assigned-clocks = <&wiz1_pll1_refclk>;
assigned-clock-parents = <&k3_clks 293 0>;
};
cmn-refclk-dig-div {
clocks = <&wiz1_refclk_dig>;
#clock-cells = <0>;
};
cmn-refclk1-dig-div {
clocks = <&wiz1_pll1_refclk>;
#clock-cells = <0>;
};
refclk-dig {
clocks = <&k3_clks 292 11>, <&k3_clks 292 0>, <&dummy_cmn_refclk>, <&dummy_cmn_refclk1>;
#clock-cells = <0>;
assigned-clocks = <&wiz0_refclk_dig>;
assigned-clock-parents = <&k3_clks 292 11>;
};
serdes@5000000 {
compatible = "cdns,ti,sierra-phy-t0";
reg-names = "serdes";
reg = <0x5000000 0x10000>;
#address-cells = <1>;
#size-cells = <0>;
resets = <&serdes_wiz0 0>;
reset-names = "sierra_reset";
clocks = <&wiz0_cmn_refclk_dig_div>, <&wiz0_cmn_refclk1_dig_div>;
clock-names = "cmn_refclk_dig_div", "cmn_refclk1_dig_div";
};
};

9
Documentation/devicetree/bindings/pinctrl/aspeed,ast2600-pinctrl.yaml
View File

@ -54,8 +54,9 @@ patternProperties:
TACH10, TACH11, TACH12, TACH13, TACH14, TACH15, TACH2, TACH3,
TACH4, TACH5, TACH6, TACH7, TACH8, TACH9, THRU0, THRU1, THRU2,
THRU3, TXD1, TXD2, TXD3, TXD4, UART10, UART11, UART12, UART13,
UART6, UART7, UART8, UART9, VB, VGAHS, VGAVS, WDTRST1, WDTRST2,
WDTRST3, WDTRST4, ]
UART6, UART7, UART8, UART9, USBAD, USBADP, USB2AH, USB2AHP,
USB2BD, USB2BH, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3,
WDTRST4, ]
groups:
allOf:
- $ref: "/schemas/types.yaml#/definitions/string"
@ -85,8 +86,8 @@ patternProperties:
TACH10, TACH11, TACH12, TACH13, TACH14, TACH15, TACH2, TACH3,
TACH4, TACH5, TACH6, TACH7, TACH8, TACH9, THRU0, THRU1, THRU2,
THRU3, TXD1, TXD2, TXD3, TXD4, UART10, UART11, UART12G0,
UART12G1, UART13G0, UART13G1, UART6, UART7, UART8, UART9, VB,
VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4, ]
UART12G1, UART13G0, UART13G1, UART6, UART7, UART8, UART9, USBA,
USBB, VB, VGAHS, VGAVS, WDTRST1, WDTRST2, WDTRST3, WDTRST4, ]
required:
- compatible

69
Documentation/devicetree/bindings/pinctrl/fsl,imx8mp-pinctrl.yaml Normal file
View File

@ -0,0 +1,69 @@
# SPDX-License-Identifier: GPL-2.0
%YAML 1.2
---
$id: http://devicetree.org/schemas/pinctrl/fsl,imx8mp-pinctrl.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Freescale IMX8MP IOMUX Controller
maintainers:
- Anson Huang <Anson.Huang@nxp.com>
description:
Please refer to fsl,imx-pinctrl.txt and pinctrl-bindings.txt in this directory
for common binding part and usage.
properties:
compatible:
const: fsl,imx8mp-iomuxc
reg:
maxItems: 1
# Client device subnode's properties
patternProperties:
'grp$':
type: object
description:
Pinctrl node's client devices use subnodes for desired pin configuration.
Client device subnodes use below standard properties.
properties:
fsl,pins:
allOf:
- $ref: /schemas/types.yaml#/definitions/uint32-array
description:
each entry consists of 6 integers and represents the mux and config
setting for one pin. The first 5 integers <mux_reg conf_reg input_reg
mux_val input_val> are specified using a PIN_FUNC_ID macro, which can
be found in <arch/arm64/boot/dts/freescale/imx8mp-pinfunc.h>. The last
integer CONFIG is the pad setting value like pull-up on this pin. Please
refer to i.MX8M Plus Reference Manual for detailed CONFIG settings.
required:
- fsl,pins
additionalProperties: false
required:
- compatible
- reg
additionalProperties: false
examples:
# Pinmux controller node
- |
iomuxc: pinctrl@30330000 {
compatible = "fsl,imx8mp-iomuxc";
reg = <0x30330000 0x10000>;
pinctrl_uart2: uart2grp {
fsl,pins = <
0x228 0x488 0x5F0 0x0 0x6 0x49
0x228 0x488 0x000 0x0 0x0 0x49
>;
};
};
...

8
Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
View File

@ -10,9 +10,9 @@ GPIO port configuration registers and it is typical to refer to pins using the
naming scheme "PxN" where x is a character identifying the GPIO port with
which the pin is associated and N is an integer from 0 to 31 identifying the
pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and
PB31 is the last pin in GPIO port B. The jz4740 and the x1000 contains 4 GPIO
ports, PA to PD, for a total of 128 pins. The jz4760, the jz4770 and the jz4780
contains 6 GPIO ports, PA to PF, for a total of 192 pins.
PB31 is the last pin in GPIO port B. The jz4740, the x1000 and the x1830
contains 4 GPIO ports, PA to PD, for a total of 128 pins. The jz4760, the
jz4770 and the jz4780 contains 6 GPIO ports, PA to PF, for a total of 192 pins.
Required properties:
@ -28,6 +28,7 @@ Required properties:
- "ingenic,x1000-pinctrl"
- "ingenic,x1000e-pinctrl"
- "ingenic,x1500-pinctrl"
- "ingenic,x1830-pinctrl"
- reg: Address range of the pinctrl registers.
@ -40,6 +41,7 @@ Required properties for sub-nodes (GPIO chips):
- "ingenic,jz4770-gpio"
- "ingenic,jz4780-gpio"
- "ingenic,x1000-gpio"
- "ingenic,x1830-gpio"
- reg: The GPIO bank number.
- interrupt-controller: Marks the device node as an interrupt controller.
- interrupts: Interrupt specifier for the controllers interrupt.

75
Documentation/devicetree/bindings/pinctrl/intel,lgm-io.yaml Normal file
View File

@ -0,0 +1,75 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/pinctrl/intel,lgm-io.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Intel Lightning Mountain SoC pinmux & GPIO controller binding
maintainers:
- Rahul Tanwar <rahul.tanwar@linux.intel.com>
description: |
Pinmux & GPIO controller controls pin multiplexing & configuration including
GPIO function selection & GPIO attributes configuration.
properties:
compatible:
const: intel,lgm-io
reg:
maxItems: 1
# Client device subnode's properties
patternProperties:
'-pins$':
type: object
allOf:
- $ref: pincfg-node.yaml#
- $ref: pinmux-node.yaml#
description:
Pinctrl node's client devices use subnodes for desired pin configuration.
Client device subnodes use below standard properties.
properties:
function: true
groups: true
pins: true
pinmux: true
bias-pull-up: true
bias-pull-down: true
drive-strength: true
slew-rate: true
drive-open-drain: true
output-enable: true
required:
- function
- groups
additionalProperties: false
required:
- compatible
- reg
additionalProperties: false
examples:
# Pinmux controller node
- |
pinctrl: pinctrl@e2880000 {
compatible = "intel,lgm-io";
reg = <0xe2880000 0x100000>;
uart0-pins {
pins = <64>, /* UART_RX0 */
<65>; /* UART_TX0 */
function = "CONSOLE_UART0";
pinmux = <1>,
<1>;
groups = "CONSOLE_UART0";
};
};
...

116
Documentation/devicetree/bindings/pinctrl/intel,lgm-pinctrl.yaml
View File

@ -1,116 +0,0 @@
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/bindings/pinctrl/intel,lgm-pinctrl.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#
title: Intel Lightning Mountain SoC pinmux & GPIO controller binding
maintainers:
- Rahul Tanwar <rahul.tanwar@linux.intel.com>
description: |
Pinmux & GPIO controller controls pin multiplexing & configuration including
GPIO function selection & GPIO attributes configuration.
Please refer to [1] for details of the common pinctrl bindings used by the
client devices.
[1] Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
properties:
compatible:
const: intel,lgm-io
reg:
maxItems: 1
# Client device subnode's properties
patternProperties:
'-pins$':
type: object
description:
Pinctrl node's client devices use subnodes for desired pin configuration.
Client device subnodes use below standard properties.
properties:
function:
$ref: /schemas/types.yaml#/definitions/string
description:
A string containing the name of the function to mux to the group.
groups:
$ref: /schemas/types.yaml#/definitions/string-array
description:
An array of strings identifying the list of groups.
pins:
$ref: /schemas/types.yaml#/definitions/uint32-array
description:
List of pins to select with this function.
pinmux:
description: The applicable mux group.
allOf:
- $ref: "/schemas/types.yaml#/definitions/uint32-array"
bias-pull-up:
type: boolean
bias-pull-down:
type: boolean
drive-strength:
description: |
Selects the drive strength for the specified pins in mA.
0: 2 mA
1: 4 mA
2: 8 mA
3: 12 mA
allOf:
- $ref: /schemas/types.yaml#/definitions/uint32
- enum: [0, 1, 2, 3]
slew-rate:
type: boolean
description: |
Sets slew rate for specified pins.
0: slow slew
1: fast slew
drive-open-drain:
type: boolean
output-enable:
type: boolean
required:
- function
- groups
additionalProperties: false
required:
- compatible
- reg
additionalProperties: false
examples:
# Pinmux controller node
- |
pinctrl: pinctrl@e2880000 {
compatible = "intel,lgm-pinctrl";
reg = <0xe2880000 0x100000>;
uart0-pins {
pins = <64>, /* UART_RX0 */
<65>; /* UART_TX0 */
function = "CONSOLE_UART0";
pinmux = <1>,
<1>;
groups = "CONSOLE_UART0";
};
};
...

2
Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml
View File

@ -114,7 +114,7 @@ properties:
specific binding for the hardware defines whether the entries are integers
or strings, and their meaning.
group:
groups:
$ref: /schemas/types.yaml#/definitions/string-array
description:
the group to apply the properties to, if the driver supports

5
Documentation/devicetree/bindings/pinctrl/qcom,sc7180-pinctrl.txt
View File

@ -125,8 +125,9 @@ to specify in a pin configuration subnode:
mi2s_1, mi2s_2, mss_lte, m_voc, pa_indicator, phase_flag,
PLL_BIST, pll_bypassnl, pll_reset, prng_rosc, qdss,
qdss_cti, qlink_enable, qlink_request, qspi_clk, qspi_cs,
qspi_data, qup00, qup01, qup02, qup03, qup04, qup05,
qup10, qup11, qup12, qup13, qup14, qup15, sdc1_tb,
qspi_data, qup00, qup01, qup02_i2c, qup02_uart, qup03,
qup04_i2c, qup04_uart, qup05, qup10, qup11_i2c, qup11_uart,
qup12, qup13_i2c, qup13_uart, qup14, qup15, sdc1_tb,
sdc2_tb, sd_write, sp_cmu, tgu_ch0, tgu_ch1, tgu_ch2,
tgu_ch3, tsense_pwm1, tsense_pwm2, uim1, uim2, uim_batt,
usb_phy, vfr_1, _V_GPIO, _V_PPS_IN, _V_PPS_OUT,

10
Documentation/devicetree/bindings/slimbus/bus.txt
View File

@ -32,6 +32,10 @@ Required property for SLIMbus child node if it is present:
Product Code, shall be in lower case hexadecimal with leading
zeroes suppressed
Optional property for SLIMbus child node if it is present:
- slim-ifc-dev - Should be phandle to SLIMBus Interface device.
Required for devices which deal with streams.
SLIMbus example for Qualcomm's slimbus manager component:
slim@28080000 {
@ -43,8 +47,14 @@ SLIMbus example for Qualcomm's slimbus manager component:
#address-cells = <2>;
#size-cell = <0>;
codec_ifd: ifd@0,0{
compatible = "slim217,60";
reg = <0 0>;
};
codec: wcd9310@1,0{
compatible = "slim217,60";
reg = <1 0>;
slim-ifc-dev = <&codec_ifd>;
};
};

167
Documentation/devicetree/bindings/soundwire/qcom,sdw.txt Normal file
View File

@ -0,0 +1,167 @@
Qualcomm SoundWire Controller Bindings
This binding describes the Qualcomm SoundWire Controller along with its
board specific bus parameters.
- compatible:
Usage: required
Value type: <stringlist>
Definition: must be "qcom,soundwire-v<MAJOR>.<MINOR>.<STEP>",
Example:
"qcom,soundwire-v1.3.0"
"qcom,soundwire-v1.5.0"
"qcom,soundwire-v1.6.0"
- reg:
Usage: required
Value type: <prop-encoded-array>
Definition: the base address and size of SoundWire controller
address space.
- interrupts:
Usage: required
Value type: <prop-encoded-array>
Definition: should specify the SoundWire Controller IRQ
- clock-names:
Usage: required
Value type: <stringlist>
Definition: should be "iface" for SoundWire Controller interface clock
- clocks:
Usage: required
Value type: <prop-encoded-array>
Definition: should specify the SoundWire Controller interface clock
- #sound-dai-cells:
Usage: required
Value type: <u32>
Definition: must be 1 for digital audio interfaces on the controller.
- qcom,dout-ports:
Usage: required
Value type: <u32>
Definition: must be count of data out ports
- qcom,din-ports:
Usage: required
Value type: <u32>
Definition: must be count of data in ports
- qcom,ports-offset1:
Usage: required
Value type: <prop-encoded-array>
Definition: should specify payload transport window offset1 of each
data port. Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-offset2:
Usage: required
Value type: <prop-encoded-array>
Definition: should specify payload transport window offset2 of each
data port. Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-sinterval-low:
Usage: required
Value type: <prop-encoded-array>
Definition: should be sample interval low of each data port.
Out ports followed by In ports. Used for Sample Interval
calculation.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-word-length:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be size of payload channel sample.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-block-pack-mode:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be 0 or 1 to indicate the block packing mode.
0 to indicate Blocks are per Channel
1 to indicate Blocks are per Port.
Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-block-group-count:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be in range 1 to 4 to indicate how many sample
intervals are combined into a payload.
Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-lane-control:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be in range 0 to 7 to identify which data lane
the data port uses.
Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-hstart:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be number identifying lowerst numbered coloum in
SoundWire Frame, i.e. left edge of the Transport sub-frame
for each port. Values between 0 and 15 are valid.
Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,ports-hstop:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be number identifying highest numbered coloum in
SoundWire Frame, i.e. the right edge of the Transport
sub-frame for each port. Values between 0 and 15 are valid.
Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
- qcom,dports-type:
Usage: optional
Value type: <prop-encoded-array>
Definition: should be one of the following types
0 for reduced port
1 for simple ports
2 for full port
Out ports followed by In ports.
More info in MIPI Alliance SoundWire 1.0 Specifications.
Note:
More Information on detail of encoding of these fields can be
found in MIPI Alliance SoundWire 1.0 Specifications.
= SoundWire devices
Each subnode of the bus represents SoundWire device attached to it.
The properties of these nodes are defined by the individual bindings.
= EXAMPLE
The following example represents a SoundWire controller on DB845c board
which has controller integrated inside WCD934x codec on SDM845 SoC.
soundwire: soundwire@c85 {
compatible = "qcom,soundwire-v1.3.0";
reg = <0xc85 0x20>;
interrupts = <20 IRQ_TYPE_EDGE_RISING>;
clocks = <&wcc>;
clock-names = "iface";
#sound-dai-cells = <1>;
qcom,dports-type = <0>;
qcom,dout-ports = <6>;
qcom,din-ports = <2>;
qcom,ports-sinterval-low = /bits/ 8 <0x07 0x1F 0x3F 0x7 0x1F 0x3F 0x0F 0x0F>;
qcom,ports-offset1 = /bits/ 8 <0x01 0x02 0x0C 0x6 0x12 0x0D 0x07 0x0A >;
qcom,ports-offset2 = /bits/ 8 <0x00 0x00 0x1F 0x00 0x00 0x1F 0x00 0x00>;
/* Left Speaker */
left{
....
};
/* Right Speaker */
right{
....
};
};

2
Documentation/devicetree/bindings/soundwire/soundwire-controller.yaml
View File

@ -69,6 +69,7 @@ examples:
reg = <0 1>;
powerdown-gpios = <&wcdpinctrl 2 0>;
#thermal-sensor-cells = <0>;
#sound-dai-cells = <0>;
};
speaker@0,2 {
@ -76,6 +77,7 @@ examples:
reg = <0 2>;
powerdown-gpios = <&wcdpinctrl 2 0>;
#thermal-sensor-cells = <0>;
#sound-dai-cells = <0>;
};
};

4
Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt
View File

@ -15,6 +15,10 @@ Required properties:
"qcom,ci-hdrc"
"chipidea,usb2"
"xlnx,zynq-usb-2.20a"
"nvidia,tegra20-udc"
"nvidia,tegra30-udc"
"nvidia,tegra114-udc"
"nvidia,tegra124-udc"
- reg: base address and length of the registers
- interrupts: interrupt for the USB controller

57
Documentation/devicetree/bindings/usb/mediatek,musb.txt Normal file
View File

@ -0,0 +1,57 @@
MediaTek musb DRD/OTG controller
-------------------------------------------
Required properties:
- compatible : should be one of:
"mediatek,mt2701-musb"
...
followed by "mediatek,mtk-musb"
- reg : specifies physical base address and size of
the registers
- interrupts : interrupt used by musb controller
- interrupt-names : must be "mc"
- phys : PHY specifier for the OTG phy
- dr_mode : should be one of "host", "peripheral" or "otg",
refer to usb/generic.txt
- clocks : a list of phandle + clock-specifier pairs, one for
each entry in clock-names
- clock-names : must contain "main", "mcu", "univpll"
for clocks of controller
Optional properties:
- power-domains : a phandle to USB power domain node to control USB's
MTCMOS
Required child nodes:
usb connector node as defined in bindings/connector/usb-connector.txt
Optional properties:
- id-gpios : input GPIO for USB ID pin.
- vbus-gpios : input GPIO for USB VBUS pin.
- vbus-supply : reference to the VBUS regulator, needed when supports
dual-role mode
- usb-role-switch : use USB Role Switch to support dual-role switch, see
usb/generic.txt.
Example:
usb2: usb@11200000 {
compatible = "mediatek,mt2701-musb",
"mediatek,mtk-musb";
reg = <0 0x11200000 0 0x1000>;
interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_LOW>;
interrupt-names = "mc";
phys = <&u2port2 PHY_TYPE_USB2>;
dr_mode = "otg";
clocks = <&pericfg CLK_PERI_USB0>,
<&pericfg CLK_PERI_USB0_MCU>,
<&pericfg CLK_PERI_USB_SLV>;
clock-names = "main","mcu","univpll";
power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>;
usb-role-switch;
connector{
compatible = "gpio-usb-b-connector", "usb-b-connector";
type = "micro";
id-gpios = <&pio 44 GPIO_ACTIVE_HIGH>;
vbus-supply = <&usb_vbus>;
};
};

6
Documentation/devicetree/bindings/vendor-prefixes.yaml
View File

@ -109,6 +109,8 @@ patternProperties:
description: Artesyn Embedded Technologies Inc.
"^asahi-kasei,.*":
description: Asahi Kasei Corp.
"^asc,.*":
description: All Sensors Corporation
"^aspeed,.*":
description: ASPEED Technology Inc.
"^asus,.*":
@ -717,6 +719,8 @@ patternProperties:
description: Panasonic Corporation
"^parade,.*":
description: Parade Technologies Inc.
"^parallax,.*":
description: Parallax Inc.
"^pda,.*":
description: Precision Design Associates, Inc.
"^pericom,.*":
@ -1060,6 +1064,8 @@ patternProperties:
description: Xilinx
"^xunlong,.*":
description: Shenzhen Xunlong Software CO.,Limited
"^xylon,.*":
description: Xylon
"^yones-toptech,.*":
description: Yones Toptech Co., Ltd.
"^ysoft,.*":

294
Documentation/doc-guide/contributing.rst Normal file
View File

@ -0,0 +1,294 @@
.. SPDX-License-Identifier: GPL-2.0
How to help improve kernel documentation
========================================
Documentation is an important part of any software-development project.
Good documentation helps to bring new developers in and helps established
developers work more effectively. Without top-quality documentation, a lot
of time is wasted in reverse-engineering the code and making avoidable
mistakes.
Unfortunately, the kernel's documentation currently falls far short of what
it needs to be to support a project of this size and importance.
This guide is for contributors who would like to improve that situation.
Kernel documentation improvements can be made by developers at a variety of
skill levels; they are a relatively easy way to learn the kernel process in
general and find a place in the community. The bulk of what follows is the
documentation maintainer's list of tasks that most urgently need to be
done.
The documentation TODO list
---------------------------
There is an endless list of tasks that need to be carried out to get our
documentation to where it should be. This list contains a number of
important items, but is far from exhaustive; if you see a different way to
improve the documentation, please do not hold back!
Addressing warnings
~~~~~~~~~~~~~~~~~~~
The documentation build currently spews out an unbelievable number of
warnings. When you have that many, you might as well have none at all;
people ignore them, and they will never notice when their work adds new
ones. For this reason, eliminating warnings is one of the highest-priority
tasks on the documentation TODO list. The task itself is reasonably
straightforward, but it must be approached in the right way to be
successful.
Warnings issued by a compiler for C code can often be dismissed as false
positives, leading to patches aimed at simply shutting the compiler up.
Warnings from the documentation build almost always point at a real
problem; making those warnings go away requires understanding the problem
and fixing it at its source. For this reason, patches fixing documentation
warnings should probably not say "fix a warning" in the changelog title;
they should indicate the real problem that has been fixed.
Another important point is that documentation warnings are often created by
problems in kerneldoc comments in C code. While the documentation
maintainer appreciates being copied on fixes for these warnings, the
documentation tree is often not the right one to actually carry those
fixes; they should go to the maintainer of the subsystem in question.
For example, in a documentation build I grabbed a pair of warnings nearly
at random::
./drivers/devfreq/devfreq.c:1818: warning: bad line:
- Resource-managed devfreq_register_notifier()
./drivers/devfreq/devfreq.c:1854: warning: bad line:
- Resource-managed devfreq_unregister_notifier()
(The lines were split for readability).
A quick look at the source file named above turned up a couple of kerneldoc
comments that look like this::
/**
* devm_devfreq_register_notifier()
- Resource-managed devfreq_register_notifier()
* @dev: The devfreq user device. (parent of devfreq)
* @devfreq: The devfreq object.
* @nb: The notifier block to be unregistered.
* @list: DEVFREQ_TRANSITION_NOTIFIER.
*/
The problem is the missing "*", which confuses the build system's
simplistic idea of what C comment blocks look like. This problem had been
present since that comment was added in 2016 — a full four years. Fixing
it was a matter of adding the missing asterisks. A quick look at the
history for that file showed what the normal format for subject lines is,
and ``scripts/get_maintainer.pl`` told me who should receive it. The
resulting patch looked like this::
[PATCH] PM / devfreq: Fix two malformed kerneldoc comments
Two kerneldoc comments in devfreq.c fail to adhere to the required format,
resulting in these doc-build warnings:
./drivers/devfreq/devfreq.c:1818: warning: bad line:
- Resource-managed devfreq_register_notifier()
./drivers/devfreq/devfreq.c:1854: warning: bad line:
- Resource-managed devfreq_unregister_notifier()
Add a couple of missing asterisks and make kerneldoc a little happier.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
drivers/devfreq/devfreq.c | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
index 57f6944d65a6..00c9b80b3d33 100644
--- a/drivers/devfreq/devfreq.c
+++ b/drivers/devfreq/devfreq.c
@@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res)
/**
* devm_devfreq_register_notifier()
- - Resource-managed devfreq_register_notifier()
+ * - Resource-managed devfreq_register_notifier()
* @dev: The devfreq user device. (parent of devfreq)
* @devfreq: The devfreq object.
* @nb: The notifier block to be unregistered.
@@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
/**
* devm_devfreq_unregister_notifier()
- - Resource-managed devfreq_unregister_notifier()
+ * - Resource-managed devfreq_unregister_notifier()
* @dev: The devfreq user device. (parent of devfreq)
* @devfreq: The devfreq object.
* @nb: The notifier block to be unregistered.
--
2.24.1
The entire process only took a few minutes. Of course, I then found that
somebody else had fixed it in a separate tree, highlighting another lesson:
always check linux-next to see if a problem has been fixed before you dig
into it.
Other fixes will take longer, especially those relating to structure
members or function parameters that lack documentation. In such cases, it
is necessary to work out what the role of those members or parameters is
and describe them correctly. Overall, this task gets a little tedious at
times, but it's highly important. If we can actually eliminate warnings
from the documentation build, then we can start expecting developers to
avoid adding new ones.
Languishing kerneldoc comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Developers are encouraged to write kerneldoc comments for their code, but
many of those comments are never pulled into the docs build. That makes
this information harder to find and, for example, makes Sphinx unable to
generate links to that documentation. Adding ``kernel-doc`` directives to
the documentation to bring those comments in can help the community derive
the full value of the work that has gone into creating them.
The ``scripts/find-unused-docs.sh`` tool can be used to find these
overlooked comments.
Note that the most value comes from pulling in the documentation for
exported functions and data structures. Many subsystems also have
kerneldoc comments for internal use; those should not be pulled into the
documentation build unless they are placed in a document that is
specifically aimed at developers working within the relevant subsystem.
Typo fixes
~~~~~~~~~~
Fixing typographical or formatting errors in the documentation is a quick
way to figure out how to create and send patches, and it is a useful
service. I am always willing to accept such patches. That said, once you
have fixed a few, please consider moving on to more advanced tasks, leaving
some typos for the next beginner to address.
Please note that some things are *not* typos and should not be "fixed":
- Both American and British English spellings are allowed within the
kernel documentation. There is no need to fix one by replacing it with
the other.
- The question of whether a period should be followed by one or two spaces
is not to be debated in the context of kernel documentation. Other
areas of rational disagreement, such as the "Oxford comma", are also
off-topic here.
As with any patch to any project, please consider whether your change is
really making things better.
Ancient documentation
~~~~~~~~~~~~~~~~~~~~~
Some kernel documentation is current, maintained, and useful. Some
documentation is ... not. Dusty, old, and inaccurate documentation can
mislead readers and casts doubt on our documentation as a whole. Anything
that can be done to address such problems is more than welcome.
Whenever you are working with a document, please consider whether it is
current, whether it needs updating, or whether it should perhaps be removed
altogether. There are a number of warning signs that you can pay attention
to here:
- References to 2.x kernels
- Pointers to SourceForge repositories
- Nothing but typo fixes in the history for several years
- Discussion of pre-Git workflows
The best thing to do, of course, would be to bring the documentation
current, adding whatever information is needed. Such work often requires
the cooperation of developers familiar with the subsystem in question, of
course. Developers are often more than willing to cooperate with people
working to improve the documentation when asked nicely, and when their
answers are listened to and acted upon.
Some documentation is beyond hope; we occasionally find documents that
refer to code that was removed from the kernel long ago, for example.
There is surprising resistance to removing obsolete documentation, but we
should do that anyway. Extra cruft in our documentation helps nobody.
In cases where there is perhaps some useful information in a badly outdated
document, and you are unable to update it, the best thing to do may be to
add a warning at the beginning. The following text is recommended::
.. warning ::
This document is outdated and in need of attention. Please use
this information with caution, and please consider sending patches
to update it.
That way, at least our long-suffering readers have been warned that the
document may lead them astray.
Documentation coherency
~~~~~~~~~~~~~~~~~~~~~~~
The old-timers around here will remember the Linux books that showed up on
the shelves in the 1990s. They were simply collections of documentation
files scrounged from various locations on the net. The books have (mostly)
improved since then, but the kernel's documentation is still mostly built
on that model. It is thousands of files, almost each of which was written
in isolation from all of the others. We don't have a coherent body of
kernel documentation; we have thousands of individual documents.
We have been trying to improve the situation through the creation of
a set of "books" that group documentation for specific readers. These
include:
- :doc:`../admin-guide/index`
- :doc:`../core-api/index`
- :doc:`../driver-api/index`
- :doc:`../userspace-api/index`
As well as this book on documentation itself.
Moving documents into the appropriate books is an important task and needs
to continue. There are a couple of challenges associated with this work,
though. Moving documentation files creates short-term pain for the people
who work with those files; they are understandably unenthusiastic about
such changes. Usually the case can be made to move a document once; we
really don't want to keep shifting them around, though.
Even when all documents are in the right place, though, we have only
managed to turn a big pile into a group of smaller piles. The work of
trying to knit all of those documents together into a single whole has not
yet begun. If you have bright ideas on how we could proceed on that front,
we would be more than happy to hear them.
Stylesheet improvements
~~~~~~~~~~~~~~~~~~~~~~~
With the adoption of Sphinx we have much nicer-looking HTML output than we
once did. But it could still use a lot of improvement; Donald Knuth and
Edward Tufte would be unimpressed. That requires tweaking our stylesheets
to create more typographically sound, accessible, and readable output.
Be warned: if you take on this task you are heading into classic bikeshed
territory. Expect a lot of opinions and discussion for even relatively
obvious changes. That is, alas, the nature of the world we live in.
Non-LaTeX PDF build
~~~~~~~~~~~~~~~~~~~
This is a decidedly nontrivial task for somebody with a lot of time and
Python skills. The Sphinx toolchain is relatively small and well
contained; it is easy to add to a development system. But building PDF or
EPUB output requires installing LaTeX, which is anything but small or well
contained. That would be a nice thing to eliminate.
The original hope had been to use the rst2pdf tool (https://rst2pdf.org/)
for PDF generation, but it turned out to not be up to the task.
Development work on rst2pdf seems to have picked up again in recent times,
though, which is a hopeful sign. If a suitably motivated developer were to
work with that project to make rst2pdf work with the kernel documentation
build, the world would be eternally grateful.
Write more documentation
~~~~~~~~~~~~~~~~~~~~~~~~
Naturally, there are massive parts of the kernel that are severely
underdocumented. If you have the knowledge to document a specific kernel
subsystem and the desire to do so, please do not hesitate to do some
writing and contribute the result to the kernel. Untold numbers of kernel
developers and users will thank you.

2
Documentation/doc-guide/index.rst
View File

@ -10,6 +10,8 @@ How to write kernel documentation
sphinx
kernel-doc
parse-headers
contributing
maintainer-profile
.. only:: subproject and html

44
Documentation/doc-guide/maintainer-profile.rst Normal file
View File

@ -0,0 +1,44 @@
.. SPDX-License-Identifier: GPL-2.0
Documentation subsystem maintainer entry profile
================================================
The documentation "subsystem" is the central coordinating point for the
kernel's documentation and associated infrastructure. It covers the
hierarchy under Documentation/ (with the exception of
Documentation/device-tree), various utilities under scripts/ and, at least
some of the time, LICENSES/.
It's worth noting, though, that the boundaries of this subsystem are rather
fuzzier than normal. Many other subsystem maintainers like to keep control
of portions of Documentation/, and many more freely apply changes there
when it is convenient. Beyond that, much of the kernel's documentation is
found in the source as kerneldoc comments; those are usually (but not
always) maintained by the relevant subsystem maintainer.
The mailing list for documentation is linux-doc@vger.kernel.org. Patches
should be made against the docs-next tree whenever possible.
Submit checklist addendum
-------------------------
When making documentation changes, you should actually build the
documentation and ensure that no new errors or warnings have been
introduced. Generating HTML documents and looking at the result will help
to avoid unsightly misunderstandings about how things will be rendered.
Key cycle dates
---------------
Patches can be sent anytime, but response will be slower than usual during
the merge window. The docs tree tends to close late before the merge
window opens, since the risk of regressions from documentation patches is
low.
Review cadence
--------------
I am the sole maintainer for the documentation subsystem, and I am doing
the work on my own time, so the response to patches will occasionally be
slow. I try to always send out a notification when a patch is merged (or
when I decide that one cannot be). Do not hesitate to send a ping if you
have not heard back within a week of sending a patch.

2
Documentation/driver-api/driver-model/devres.rst
View File

@ -267,6 +267,8 @@ DRM
GPIO
devm_gpiod_get()
devm_gpiod_get_array()
devm_gpiod_get_array_optional()
devm_gpiod_get_index()
devm_gpiod_get_index_optional()
devm_gpiod_get_optional()

5
Documentation/driver-api/gpio/driver.rst
View File

@ -507,11 +507,6 @@ available but we try to move away from this:
cascaded irq has to be handled by a threaded interrupt handler.
Apart from that it works exactly like the chained irqchip.
- DEPRECATED: gpiochip_set_chained_irqchip(): sets up a chained cascaded irq
handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip*
as handler data. Notice that we pass is as the handler data, since the
irqchip data is likely used by the parent irqchip.
- gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a
gpio_chip from a parent IRQ. As the parent IRQ has usually been
explicitly requested by the driver, this does very little more than

8
Documentation/driver-api/gpio/drivers-on-gpio.rst
View File

@ -95,7 +95,7 @@ to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The
MTD NOR flash has add-ons for extra GPIO lines too, though the address bus is
usually connected directly to the flash.
Use those instead of talking directly to the GPIOs using sysfs; they integrate
with kernel frameworks better than your userspace code could. Needless to say,
just using the appropriate kernel drivers will simplify and speed up your
embedded hacking in particular by providing ready-made components.
Use those instead of talking directly to the GPIOs from userspace; they
integrate with kernel frameworks better than your userspace code could.
Needless to say, just using the appropriate kernel drivers will simplify and
speed up your embedded hacking in particular by providing ready-made components.

1
Documentation/driver-api/gpio/index.rst
View File

@ -8,6 +8,7 @@ Contents:
:maxdepth: 2
intro
using-gpio
driver
consumer
board

50
Documentation/driver-api/gpio/using-gpio.rst Normal file
View File

@ -0,0 +1,50 @@
=========================
Using GPIO Lines in Linux
=========================
The Linux kernel exists to abstract and present hardware to users. GPIO lines
as such are normally not user facing abstractions. The most obvious, natural
and preferred way to use GPIO lines is to let kernel hardware drivers deal
with them.
For examples of already existing generic drivers that will also be good
examples for any other kernel drivers you want to author, refer to
:doc:`drivers-on-gpio`
For any kind of mass produced system you want to support, such as servers,
laptops, phones, tablets, routers, and any consumer or office or business goods
using appropriate kernel drivers is paramount. Submit your code for inclusion
in the upstream Linux kernel when you feel it is mature enough and you will get
help to refine it, see :doc:`../../process/submitting-patches`.
In Linux GPIO lines also have a userspace ABI.
The userspace ABI is intended for one-off deployments. Examples are prototypes,
factory lines, maker community projects, workshop specimen, production tools,
industrial automation, PLC-type use cases, door controllers, in short a piece
of specialized equipment that is not produced by the numbers, requiring
operators to have a deep knowledge of the equipment and knows about the
software-hardware interface to be set up. They should not have a natural fit
to any existing kernel subsystem and not be a good fit for an operating system,
because of not being reusable or abstract enough, or involving a lot of non
computer hardware related policy.
Applications that have a good reason to use the industrial I/O (IIO) subsystem
from userspace will likely be a good fit for using GPIO lines from userspace as
well.
Do not under any circumstances abuse the GPIO userspace ABI to cut corners in
any product development projects. If you use it for prototyping, then do not
productify the prototype: rewrite it using proper kernel drivers. Do not under
any circumstances deploy any uniform products using GPIO from userspace.
The userspace ABI is a character device for each GPIO hardware unit (GPIO chip).
These devices will appear on the system as ``/dev/gpiochip0`` thru
``/dev/gpiochipN``. Examples of how to directly use the userspace ABI can be
found in the kernel tree ``tools/gpio`` subdirectory.
For structured and managed applications, we recommend that you make use of the
libgpiod_ library. This provides helper abstractions, command line utlities
and arbitration for multiple simultaneous consumers on the same GPIO chip.
.. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/

22
Documentation/driver-api/interconnect.rst
View File

@ -91,3 +91,25 @@ Interconnect consumers are the clients which use the interconnect APIs to
get paths between endpoints and set their bandwidth/latency/QoS requirements
for these interconnect paths. These interfaces are not currently
documented.
Interconnect debugfs interfaces
-------------------------------
Like several other subsystems interconnect will create some files for debugging
and introspection. Files in debugfs are not considered ABI so application
software shouldn't rely on format details change between kernel versions.
``/sys/kernel/debug/interconnect/interconnect_summary``:
Show all interconnect nodes in the system with their aggregated bandwidth
request. Indented under each node show bandwidth requests from each device.
``/sys/kernel/debug/interconnect/interconnect_graph``:
Show the interconnect graph in the graphviz dot format. It shows all
interconnect nodes and links in the system and groups together nodes from the
same provider as subgraphs. The format is human-readable and can also be piped
through dot to generate diagrams in many graphical formats::
$ cat /sys/kernel/debug/interconnect/interconnect_graph | \
dot -Tsvg > interconnect_graph.svg

24
Documentation/filesystems/adfs.txt
View File

@ -1,3 +1,27 @@
Filesystems supported by ADFS
-----------------------------
The ADFS module supports the following Filecore formats which have:
- new maps
- new directories or big directories
In terms of the named formats, this means we support:
- E and E+, with or without boot block
- F and F+
We fully support reading files from these filesystems, and writing to
existing files within their existing allocation. Essentially, we do
not support changing any of the filesystem metadata.
This is intended to support loopback mounted Linux native filesystems
on a RISC OS Filecore filesystem, but will allow the data within files
to be changed.
If write support (ADFS_FS_RW) is configured, we allow rudimentary
directory updates, specifically updating the access mode and timestamp.
Mount options for ADFS
----------------------

2
Documentation/filesystems/automount-support.txt
View File

@ -9,7 +9,7 @@ also be requested by userspace.
IN-KERNEL AUTOMOUNTING
======================
See section "Mount Traps" of Documentation/filesystems/autofs.txt
See section "Mount Traps" of Documentation/filesystems/autofs.rst
Then from userspace, you can just do something like:

2
Documentation/filesystems/index.rst
View File

@ -47,4 +47,6 @@ Documentation for filesystem implementations.
:maxdepth: 2
autofs
overlayfs
virtiofs
vfat

274
Documentation/filesystems/nfs/nfs-rdma.txt
View File

@ -1,274 +0,0 @@
################################################################################
# #
# NFS/RDMA README #
# #
################################################################################
Author: NetApp and Open Grid Computing
Date: May 29, 2008
Table of Contents
~~~~~~~~~~~~~~~~~
- Overview
- Getting Help
- Installation
- Check RDMA and NFS Setup
- NFS/RDMA Setup
Overview
~~~~~~~~
This document describes how to install and setup the Linux NFS/RDMA client
and server software.
The NFS/RDMA client was first included in Linux 2.6.24. The NFS/RDMA server
was first included in the following release, Linux 2.6.25.
In our testing, we have obtained excellent performance results (full 10Gbit
wire bandwidth at minimal client CPU) under many workloads. The code passes
the full Connectathon test suite and operates over both Infiniband and iWARP
RDMA adapters.
Getting Help
~~~~~~~~~~~~
If you get stuck, you can ask questions on the
nfs-rdma-devel@lists.sourceforge.net
mailing list.
Installation
~~~~~~~~~~~~
These instructions are a step by step guide to building a machine for
use with NFS/RDMA.
- Install an RDMA device
Any device supported by the drivers in drivers/infiniband/hw is acceptable.
Testing has been performed using several Mellanox-based IB cards, the
Ammasso AMS1100 iWARP adapter, and the Chelsio cxgb3 iWARP adapter.
- Install a Linux distribution and tools
The first kernel release to contain both the NFS/RDMA client and server was
Linux 2.6.25 Therefore, a distribution compatible with this and subsequent
Linux kernel release should be installed.
The procedures described in this document have been tested with
distributions from Red Hat's Fedora Project (http://fedora.redhat.com/).
- Install nfs-utils-1.1.2 or greater on the client
An NFS/RDMA mount point can be obtained by using the mount.nfs command in
nfs-utils-1.1.2 or greater (nfs-utils-1.1.1 was the first nfs-utils
version with support for NFS/RDMA mounts, but for various reasons we
recommend using nfs-utils-1.1.2 or greater). To see which version of
mount.nfs you are using, type:
$ /sbin/mount.nfs -V
If the version is less than 1.1.2 or the command does not exist,
you should install the latest version of nfs-utils.
Download the latest package from:
http://www.kernel.org/pub/linux/utils/nfs
Uncompress the package and follow the installation instructions.
If you will not need the idmapper and gssd executables (you do not need
these to create an NFS/RDMA enabled mount command), the installation
process can be simplified by disabling these features when running
configure:
$ ./configure --disable-gss --disable-nfsv4
To build nfs-utils you will need the tcp_wrappers package installed. For
more information on this see the package's README and INSTALL files.
After building the nfs-utils package, there will be a mount.nfs binary in
the utils/mount directory. This binary can be used to initiate NFS v2, v3,
or v4 mounts. To initiate a v4 mount, the binary must be called
mount.nfs4. The standard technique is to create a symlink called
mount.nfs4 to mount.nfs.
This mount.nfs binary should be installed at /sbin/mount.nfs as follows:
$ sudo cp utils/mount/mount.nfs /sbin/mount.nfs
In this location, mount.nfs will be invoked automatically for NFS mounts
by the system mount command.
NOTE: mount.nfs and therefore nfs-utils-1.1.2 or greater is only needed
on the NFS client machine. You do not need this specific version of
nfs-utils on the server. Furthermore, only the mount.nfs command from
nfs-utils-1.1.2 is needed on the client.
- Install a Linux kernel with NFS/RDMA
The NFS/RDMA client and server are both included in the mainline Linux
kernel version 2.6.25 and later. This and other versions of the Linux
kernel can be found at:
https://www.kernel.org/pub/linux/kernel/
Download the sources and place them in an appropriate location.
- Configure the RDMA stack
Make sure your kernel configuration has RDMA support enabled. Under
Device Drivers -> InfiniBand support, update the kernel configuration
to enable InfiniBand support [NOTE: the option name is misleading. Enabling
InfiniBand support is required for all RDMA devices (IB, iWARP, etc.)].
Enable the appropriate IB HCA support (mlx4, mthca, ehca, ipath, etc.) or
iWARP adapter support (amso, cxgb3, etc.).
If you are using InfiniBand, be sure to enable IP-over-InfiniBand support.
- Configure the NFS client and server
Your kernel configuration must also have NFS file system support and/or
NFS server support enabled. These and other NFS related configuration
options can be found under File Systems -> Network File Systems.
- Build, install, reboot
The NFS/RDMA code will be enabled automatically if NFS and RDMA
are turned on. The NFS/RDMA client and server are configured via the hidden
SUNRPC_XPRT_RDMA config option that depends on SUNRPC and INFINIBAND. The
value of SUNRPC_XPRT_RDMA will be:
- N if either SUNRPC or INFINIBAND are N, in this case the NFS/RDMA client
and server will not be built
- M if both SUNRPC and INFINIBAND are on (M or Y) and at least one is M,
in this case the NFS/RDMA client and server will be built as modules
- Y if both SUNRPC and INFINIBAND are Y, in this case the NFS/RDMA client
and server will be built into the kernel
Therefore, if you have followed the steps above and turned no NFS and RDMA,
the NFS/RDMA client and server will be built.
Build a new kernel, install it, boot it.
Check RDMA and NFS Setup
~~~~~~~~~~~~~~~~~~~~~~~~
Before configuring the NFS/RDMA software, it is a good idea to test
your new kernel to ensure that the kernel is working correctly.
In particular, it is a good idea to verify that the RDMA stack
is functioning as expected and standard NFS over TCP/IP and/or UDP/IP
is working properly.
- Check RDMA Setup
If you built the RDMA components as modules, load them at
this time. For example, if you are using a Mellanox Tavor/Sinai/Arbel
card:
$ modprobe ib_mthca
$ modprobe ib_ipoib
If you are using InfiniBand, make sure there is a Subnet Manager (SM)
running on the network. If your IB switch has an embedded SM, you can
use it. Otherwise, you will need to run an SM, such as OpenSM, on one
of your end nodes.
If an SM is running on your network, you should see the following:
$ cat /sys/class/infiniband/driverX/ports/1/state
4: ACTIVE
where driverX is mthca0, ipath5, ehca3, etc.
To further test the InfiniBand software stack, use IPoIB (this
assumes you have two IB hosts named host1 and host2):
host1$ ip link set dev ib0 up
host1$ ip address add dev ib0 a.b.c.x
host2$ ip link set dev ib0 up
host2$ ip address add dev ib0 a.b.c.y
host1$ ping a.b.c.y
host2$ ping a.b.c.x
For other device types, follow the appropriate procedures.
- Check NFS Setup
For the NFS components enabled above (client and/or server),
test their functionality over standard Ethernet using TCP/IP or UDP/IP.
NFS/RDMA Setup
~~~~~~~~~~~~~~
We recommend that you use two machines, one to act as the client and
one to act as the server.
One time configuration:
- On the server system, configure the /etc/exports file and
start the NFS/RDMA server.
Exports entries with the following formats have been tested:
/vol0 192.168.0.47(fsid=0,rw,async,insecure,no_root_squash)
/vol0 192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash)
The IP address(es) is(are) the client's IPoIB address for an InfiniBand
HCA or the client's iWARP address(es) for an RNIC.
NOTE: The "insecure" option must be used because the NFS/RDMA client does
not use a reserved port.
Each time a machine boots:
- Load and configure the RDMA drivers
For InfiniBand using a Mellanox adapter:
$ modprobe ib_mthca
$ modprobe ib_ipoib
$ ip li set dev ib0 up
$ ip addr add dev ib0 a.b.c.d
NOTE: use unique addresses for the client and server
- Start the NFS server
If the NFS/RDMA server was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in
kernel config), load the RDMA transport module:
$ modprobe svcrdma
Regardless of how the server was built (module or built-in), start the
server:
$ /etc/init.d/nfs start
or
$ service nfs start
Instruct the server to listen on the RDMA transport:
$ echo rdma 20049 > /proc/fs/nfsd/portlist
- On the client system
If the NFS/RDMA client was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in
kernel config), load the RDMA client module:
$ modprobe xprtrdma.ko
Regardless of how the client was built (module or built-in), use this
command to mount the NFS/RDMA server:
$ mount -o rdma,port=20049 <IPoIB-server-name-or-address>:/<export> /mnt
To verify that the mount is using RDMA, run "cat /proc/mounts" and check
the "proto" field for the given mount.
Congratulations! You're using NFS/RDMA!

68
Documentation/filesystems/path-lookup.rst
View File

@ -13,6 +13,7 @@ It has subsequently been updated to reflect changes in the kernel
including:
- per-directory parallel name lookup.
- ``openat2()`` resolution restriction flags.
Introduction to pathname lookup
===============================
@ -235,6 +236,13 @@ renamed. If ``d_lookup`` finds that a rename happened while it
unsuccessfully scanned a chain in the hash table, it simply tries
again.
``rename_lock`` is also used to detect and defend against potential attacks
against ``LOOKUP_BENEATH`` and ``LOOKUP_IN_ROOT`` when resolving ".." (where
the parent directory is moved outside the root, bypassing the ``path_equal()``
check). If ``rename_lock`` is updated during the lookup and the path encounters
a "..", a potential attack occurred and ``handle_dots()`` will bail out with
``-EAGAIN``.
inode->i_rwsem
~~~~~~~~~~~~~~
@ -348,6 +356,13 @@ any changes to any mount points while stepping up. This locking is
needed to stabilize the link to the mounted-on dentry, which the
refcount on the mount itself doesn't ensure.
``mount_lock`` is also used to detect and defend against potential attacks
against ``LOOKUP_BENEATH`` and ``LOOKUP_IN_ROOT`` when resolving ".." (where
the parent directory is moved outside the root, bypassing the ``path_equal()``
check). If ``mount_lock`` is updated during the lookup and the path encounters
a "..", a potential attack occurred and ``handle_dots()`` will bail out with
``-EAGAIN``.
RCU
~~~
@ -405,6 +420,10 @@ is requested. Keeping a reference in the ``nameidata`` ensures that
only one root is in effect for the entire path walk, even if it races
with a ``chroot()`` system call.
It should be noted that in the case of ``LOOKUP_IN_ROOT`` or
``LOOKUP_BENEATH``, the effective root becomes the directory file descriptor
passed to ``openat2()`` (which exposes these ``LOOKUP_`` flags).
The root is needed when either of two conditions holds: (1) either the
pathname or a symbolic link starts with a "'/'", or (2) a "``..``"
component is being handled, since "``..``" from the root must always stay
@ -1149,7 +1168,7 @@ so ``NULL`` is returned to indicate that the symlink can be released and
the stack frame discarded.
The other case involves things in ``/proc`` that look like symlinks but
aren't really::
aren't really (and are therefore commonly referred to as "magic-links")::
$ ls -l /proc/self/fd/1
lrwx------ 1 neilb neilb 64 Jun 13 10:19 /proc/self/fd/1 -> /dev/pts/4
@ -1286,7 +1305,9 @@ A few flags
A suitable way to wrap up this tour of pathname walking is to list
the various flags that can be stored in the ``nameidata`` to guide the
lookup process. Many of these are only meaningful on the final
component, others reflect the current state of the pathname lookup.
component, others reflect the current state of the pathname lookup, and some
apply restrictions to all path components encountered in the path lookup.
And then there is ``LOOKUP_EMPTY``, which doesn't fit conceptually with
the others. If this is not set, an empty pathname causes an error
very early on. If it is set, empty pathnames are not considered to be
@ -1310,13 +1331,48 @@ longer needed.
``LOOKUP_JUMPED`` means that the current dentry was chosen not because
it had the right name but for some other reason. This happens when
following "``..``", following a symlink to ``/``, crossing a mount point
or accessing a "``/proc/$PID/fd/$FD``" symlink. In this case the
filesystem has not been asked to revalidate the name (with
``d_revalidate()``). In such cases the inode may still need to be
revalidated, so ``d_op->d_weak_revalidate()`` is called if
or accessing a "``/proc/$PID/fd/$FD``" symlink (also known as a "magic
link"). In this case the filesystem has not been asked to revalidate the
name (with ``d_revalidate()``). In such cases the inode may still need
to be revalidated, so ``d_op->d_weak_revalidate()`` is called if
``LOOKUP_JUMPED`` is set when the look completes - which may be at the
final component or, when creating, unlinking, or renaming, at the penultimate component.
Resolution-restriction flags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to allow userspace to protect itself against certain race conditions
and attack scenarios involving changing path components, a series of flags are
available which apply restrictions to all path components encountered during
path lookup. These flags are exposed through ``openat2()``'s ``resolve`` field.
``LOOKUP_NO_SYMLINKS`` blocks all symlink traversals (including magic-links).
This is distinctly different from ``LOOKUP_FOLLOW``, because the latter only
relates to restricting the following of trailing symlinks.
``LOOKUP_NO_MAGICLINKS`` blocks all magic-link traversals. Filesystems must
ensure that they return errors from ``nd_jump_link()``, because that is how
``LOOKUP_NO_MAGICLINKS`` and other magic-link restrictions are implemented.
``LOOKUP_NO_XDEV`` blocks all ``vfsmount`` traversals (this includes both
bind-mounts and ordinary mounts). Note that the ``vfsmount`` which contains the
lookup is determined by the first mountpoint the path lookup reaches --
absolute paths start with the ``vfsmount`` of ``/``, and relative paths start
with the ``dfd``'s ``vfsmount``. Magic-links are only permitted if the
``vfsmount`` of the path is unchanged.
``LOOKUP_BENEATH`` blocks any path components which resolve outside the
starting point of the resolution. This is done by blocking ``nd_jump_root()``
as well as blocking ".." if it would jump outside the starting point.
``rename_lock`` and ``mount_lock`` are used to detect attacks against the
resolution of "..". Magic-links are also blocked.
``LOOKUP_IN_ROOT`` resolves all path components as though the starting point
were the filesystem root. ``nd_jump_root()`` brings the resolution back to to
the starting point, and ".." at the starting point will act as a no-op. As with
``LOOKUP_BENEATH``, ``rename_lock`` and ``mount_lock`` are used to detect
attacks against ".." resolution. Magic-links are also blocked.
Final-component flags
~~~~~~~~~~~~~~~~~~~~~

387
Documentation/filesystems/vfat.rst Normal file
View File

@ -0,0 +1,387 @@
====
VFAT
====
USING VFAT
==========
To use the vfat filesystem, use the filesystem type 'vfat'. i.e.::
mount -t vfat /dev/fd0 /mnt
No special partition formatter is required,
'mkdosfs' will work fine if you want to format from within Linux.
VFAT MOUNT OPTIONS
==================
**uid=###**
Set the owner of all files on this filesystem.
The default is the uid of current process.
**gid=###**
Set the group of all files on this filesystem.
The default is the gid of current process.
**umask=###**
The permission mask (for files and directories, see *umask(1)*).
The default is the umask of current process.
**dmask=###**
The permission mask for the directory.
The default is the umask of current process.
**fmask=###**
The permission mask for files.
The default is the umask of current process.
**allow_utime=###**
This option controls the permission check of mtime/atime.
**-20**: If current process is in group of file's group ID,
you can change timestamp.
**-2**: Other users can change timestamp.
The default is set from dmask option. If the directory is
writable, utime(2) is also allowed. i.e. ~dmask & 022.
Normally utime(2) checks current process is owner of
the file, or it has CAP_FOWNER capability. But FAT
filesystem doesn't have uid/gid on disk, so normal
check is too unflexible. With this option you can
relax it.
**codepage=###**
Sets the codepage number for converting to shortname
characters on FAT filesystem.
By default, FAT_DEFAULT_CODEPAGE setting is used.
**iocharset=<name>**
Character set to use for converting between the
encoding is used for user visible filename and 16 bit
Unicode characters. Long filenames are stored on disk
in Unicode format, but Unix for the most part doesn't
know how to deal with Unicode.
By default, FAT_DEFAULT_IOCHARSET setting is used.
There is also an option of doing UTF-8 translations
with the utf8 option.
.. note:: ``iocharset=utf8`` is not recommended. If unsure, you should consider
the utf8 option instead.
**utf8=<bool>**
UTF-8 is the filesystem safe version of Unicode that
is used by the console. It can be enabled or disabled
for the filesystem with this option.
If 'uni_xlate' gets set, UTF-8 gets disabled.
By default, FAT_DEFAULT_UTF8 setting is used.
**uni_xlate=<bool>**
Translate unhandled Unicode characters to special
escaped sequences. This would let you backup and
restore filenames that are created with any Unicode
characters. Until Linux supports Unicode for real,
this gives you an alternative. Without this option,
a '?' is used when no translation is possible. The
escape character is ':' because it is otherwise
illegal on the vfat filesystem. The escape sequence
that gets used is ':' and the four digits of hexadecimal
unicode.
**nonumtail=<bool>**
When creating 8.3 aliases, normally the alias will
end in '~1' or tilde followed by some number. If this
option is set, then if the filename is
"longfilename.txt" and "longfile.txt" does not
currently exist in the directory, longfile.txt will
be the short alias instead of longfi~1.txt.
**usefree**
Use the "free clusters" value stored on FSINFO. It will
be used to determine number of free clusters without
scanning disk. But it's not used by default, because
recent Windows don't update it correctly in some
case. If you are sure the "free clusters" on FSINFO is
correct, by this option you can avoid scanning disk.
**quiet**
Stops printing certain warning messages.
**check=s|r|n**
Case sensitivity checking setting.
**s**: strict, case sensitive
**r**: relaxed, case insensitive
**n**: normal, default setting, currently case insensitive
**nocase**
This was deprecated for vfat. Use ``shortname=win95`` instead.
**shortname=lower|win95|winnt|mixed**
Shortname display/create setting.
**lower**: convert to lowercase for display,
emulate the Windows 95 rule for create.
**win95**: emulate the Windows 95 rule for display/create.
**winnt**: emulate the Windows NT rule for display/create.
**mixed**: emulate the Windows NT rule for display,
emulate the Windows 95 rule for create.
Default setting is `mixed`.
**tz=UTC**
Interpret timestamps as UTC rather than local time.
This option disables the conversion of timestamps
between local time (as used by Windows on FAT) and UTC
(which Linux uses internally). This is particularly
useful when mounting devices (like digital cameras)
that are set to UTC in order to avoid the pitfalls of
local time.
**time_offset=minutes**
Set offset for conversion of timestamps from local time
used by FAT to UTC. I.e. <minutes> minutes will be subtracted
from each timestamp to convert it to UTC used internally by
Linux. This is useful when time zone set in ``sys_tz`` is
not the time zone used by the filesystem. Note that this
option still does not provide correct time stamps in all
cases in presence of DST - time stamps in a different DST
setting will be off by one hour.
**showexec**
If set, the execute permission bits of the file will be
allowed only if the extension part of the name is .EXE,
.COM, or .BAT. Not set by default.
**debug**
Can be set, but unused by the current implementation.
**sys_immutable**
If set, ATTR_SYS attribute on FAT is handled as
IMMUTABLE flag on Linux. Not set by default.
**flush**
If set, the filesystem will try to flush to disk more
early than normal. Not set by default.
**rodir**
FAT has the ATTR_RO (read-only) attribute. On Windows,
the ATTR_RO of the directory will just be ignored,
and is used only by applications as a flag (e.g. it's set
for the customized folder).
If you want to use ATTR_RO as read-only flag even for
the directory, set this option.
**errors=panic|continue|remount-ro**
specify FAT behavior on critical errors: panic, continue
without doing anything or remount the partition in
read-only mode (default behavior).
**discard**
If set, issues discard/TRIM commands to the block
device when blocks are freed. This is useful for SSD devices
and sparse/thinly-provisoned LUNs.
**nfs=stale_rw|nostale_ro**
Enable this only if you want to export the FAT filesystem
over NFS.
**stale_rw**: This option maintains an index (cache) of directory
*inodes* by *i_logstart* which is used by the nfs-related code to
improve look-ups. Full file operations (read/write) over NFS is
supported but with cache eviction at NFS server, this could
result in ESTALE issues.
**nostale_ro**: This option bases the *inode* number and filehandle
on the on-disk location of a file in the MS-DOS directory entry.
This ensures that ESTALE will not be returned after a file is
evicted from the inode cache. However, it means that operations
such as rename, create and unlink could cause filehandles that
previously pointed at one file to point at a different file,
potentially causing data corruption. For this reason, this
option also mounts the filesystem readonly.
To maintain backward compatibility, ``'-o nfs'`` is also accepted,
defaulting to "stale_rw".
**dos1xfloppy <bool>: 0,1,yes,no,true,false**
If set, use a fallback default BIOS Parameter Block
configuration, determined by backing device size. These static
parameters match defaults assumed by DOS 1.x for 160 kiB,
180 kiB, 320 kiB, and 360 kiB floppies and floppy images.
LIMITATION
==========
The fallocated region of file is discarded at umount/evict time
when using fallocate with FALLOC_FL_KEEP_SIZE.
So, User should assume that fallocated region can be discarded at
last close if there is memory pressure resulting in eviction of
the inode from the memory. As a result, for any dependency on
the fallocated region, user should make sure to recheck fallocate
after reopening the file.
TODO
====
Need to get rid of the raw scanning stuff. Instead, always use
a get next directory entry approach. The only thing left that uses
raw scanning is the directory renaming code.
POSSIBLE PROBLEMS
=================
- vfat_valid_longname does not properly checked reserved names.
- When a volume name is the same as a directory name in the root
directory of the filesystem, the directory name sometimes shows
up as an empty file.
- autoconv option does not work correctly.
TEST SUITE
==========
If you plan to make any modifications to the vfat filesystem, please
get the test suite that comes with the vfat distribution at
`<http://web.archive.org/web/*/http://bmrc.berkeley.edu/people/chaffee/vfat.html>`_
This tests quite a few parts of the vfat filesystem and additional
tests for new features or untested features would be appreciated.
NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM
=============================================
This documentation was provided by Galen C. Hunt gchunt@cs.rochester.edu and
lightly annotated by Gordon Chaffee.
This document presents a very rough, technical overview of my
knowledge of the extended FAT file system used in Windows NT 3.5 and
Windows 95. I don't guarantee that any of the following is correct,
but it appears to be so.
The extended FAT file system is almost identical to the FAT
file system used in DOS versions up to and including *6.223410239847*
:-). The significant change has been the addition of long file names.
These names support up to 255 characters including spaces and lower
case characters as opposed to the traditional 8.3 short names.
Here is the description of the traditional FAT entry in the current
Windows 95 filesystem::
struct directory { // Short 8.3 names
unsigned char name[8]; // file name
unsigned char ext[3]; // file extension
unsigned char attr; // attribute byte
unsigned char lcase; // Case for base and extension
unsigned char ctime_ms; // Creation time, milliseconds
unsigned char ctime[2]; // Creation time
unsigned char cdate[2]; // Creation date
unsigned char adate[2]; // Last access date
unsigned char reserved[2]; // reserved values (ignored)
unsigned char time[2]; // time stamp
unsigned char date[2]; // date stamp
unsigned char start[2]; // starting cluster number
unsigned char size[4]; // size of the file
};
The lcase field specifies if the base and/or the extension of an 8.3
name should be capitalized. This field does not seem to be used by
Windows 95 but it is used by Windows NT. The case of filenames is not
completely compatible from Windows NT to Windows 95. It is not completely
compatible in the reverse direction, however. Filenames that fit in
the 8.3 namespace and are written on Windows NT to be lowercase will
show up as uppercase on Windows 95.
.. note:: Note that the ``start`` and ``size`` values are actually little
endian integer values. The descriptions of the fields in this
structure are public knowledge and can be found elsewhere.
With the extended FAT system, Microsoft has inserted extra
directory entries for any files with extended names. (Any name which
legally fits within the old 8.3 encoding scheme does not have extra
entries.) I call these extra entries slots. Basically, a slot is a
specially formatted directory entry which holds up to 13 characters of
a file's extended name. Think of slots as additional labeling for the
directory entry of the file to which they correspond. Microsoft
prefers to refer to the 8.3 entry for a file as its alias and the
extended slot directory entries as the file name.
The C structure for a slot directory entry follows::
struct slot { // Up to 13 characters of a long name
unsigned char id; // sequence number for slot
unsigned char name0_4[10]; // first 5 characters in name
unsigned char attr; // attribute byte
unsigned char reserved; // always 0
unsigned char alias_checksum; // checksum for 8.3 alias
unsigned char name5_10[12]; // 6 more characters in name
unsigned char start[2]; // starting cluster number
unsigned char name11_12[4]; // last 2 characters in name
};
If the layout of the slots looks a little odd, it's only
because of Microsoft's efforts to maintain compatibility with old
software. The slots must be disguised to prevent old software from
panicking. To this end, a number of measures are taken:
1) The attribute byte for a slot directory entry is always set
to 0x0f. This corresponds to an old directory entry with
attributes of "hidden", "system", "read-only", and "volume
label". Most old software will ignore any directory
entries with the "volume label" bit set. Real volume label
entries don't have the other three bits set.
2) The starting cluster is always set to 0, an impossible
value for a DOS file.
Because the extended FAT system is backward compatible, it is
possible for old software to modify directory entries. Measures must
be taken to ensure the validity of slots. An extended FAT system can
verify that a slot does in fact belong to an 8.3 directory entry by
the following:
1) Positioning. Slots for a file always immediately proceed
their corresponding 8.3 directory entry. In addition, each
slot has an id which marks its order in the extended file
name. Here is a very abbreviated view of an 8.3 directory
entry and its corresponding long name slots for the file
"My Big File.Extension which is long"::
<proceeding files...>
<slot #3, id = 0x43, characters = "h is long">
<slot #2, id = 0x02, characters = "xtension whic">
<slot #1, id = 0x01, characters = "My Big File.E">
<directory entry, name = "MYBIGFIL.EXT">
.. note:: Note that the slots are stored from last to first. Slots
are numbered from 1 to N. The Nth slot is ``or'ed`` with
0x40 to mark it as the last one.
2) Checksum. Each slot has an alias_checksum value. The
checksum is calculated from the 8.3 name using the
following algorithm::
for (sum = i = 0; i < 11; i++) {
sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i]
}
3) If there is free space in the final slot, a Unicode ``NULL (0x0000)``
is stored after the final character. After that, all unused
characters in the final slot are set to Unicode 0xFFFF.
Finally, note that the extended name is stored in Unicode. Each Unicode
character takes either two or four bytes, UTF-16LE encoded.

347
Documentation/filesystems/vfat.txt
View File

@ -1,347 +0,0 @@
USING VFAT
----------------------------------------------------------------------
To use the vfat filesystem, use the filesystem type 'vfat'. i.e.
mount -t vfat /dev/fd0 /mnt
No special partition formatter is required. mkdosfs will work fine
if you want to format from within Linux.
VFAT MOUNT OPTIONS
----------------------------------------------------------------------
uid=### -- Set the owner of all files on this filesystem.
The default is the uid of current process.
gid=### -- Set the group of all files on this filesystem.
The default is the gid of current process.
umask=### -- The permission mask (for files and directories, see umask(1)).
The default is the umask of current process.
dmask=### -- The permission mask for the directory.
The default is the umask of current process.
fmask=### -- The permission mask for files.
The default is the umask of current process.
allow_utime=### -- This option controls the permission check of mtime/atime.
20 - If current process is in group of file's group ID,
you can change timestamp.
2 - Other users can change timestamp.
The default is set from `dmask' option. (If the directory is
writable, utime(2) is also allowed. I.e. ~dmask & 022)
Normally utime(2) checks current process is owner of
the file, or it has CAP_FOWNER capability. But FAT
filesystem doesn't have uid/gid on disk, so normal
check is too unflexible. With this option you can
relax it.
codepage=### -- Sets the codepage number for converting to shortname
characters on FAT filesystem.
By default, FAT_DEFAULT_CODEPAGE setting is used.
iocharset=<name> -- Character set to use for converting between the
encoding is used for user visible filename and 16 bit
Unicode characters. Long filenames are stored on disk
in Unicode format, but Unix for the most part doesn't
know how to deal with Unicode.
By default, FAT_DEFAULT_IOCHARSET setting is used.
There is also an option of doing UTF-8 translations
with the utf8 option.
NOTE: "iocharset=utf8" is not recommended. If unsure,
you should consider the following option instead.
utf8=<bool> -- UTF-8 is the filesystem safe version of Unicode that
is used by the console. It can be enabled or disabled
for the filesystem with this option.
If 'uni_xlate' gets set, UTF-8 gets disabled.
By default, FAT_DEFAULT_UTF8 setting is used.
uni_xlate=<bool> -- Translate unhandled Unicode characters to special
escaped sequences. This would let you backup and
restore filenames that are created with any Unicode
characters. Until Linux supports Unicode for real,
this gives you an alternative. Without this option,
a '?' is used when no translation is possible. The
escape character is ':' because it is otherwise
illegal on the vfat filesystem. The escape sequence
that gets used is ':' and the four digits of hexadecimal
unicode.
nonumtail=<bool> -- When creating 8.3 aliases, normally the alias will
end in '~1' or tilde followed by some number. If this
option is set, then if the filename is
"longfilename.txt" and "longfile.txt" does not
currently exist in the directory, 'longfile.txt' will
be the short alias instead of 'longfi~1.txt'.
usefree -- Use the "free clusters" value stored on FSINFO. It'll
be used to determine number of free clusters without
scanning disk. But it's not used by default, because
recent Windows don't update it correctly in some
case. If you are sure the "free clusters" on FSINFO is
correct, by this option you can avoid scanning disk.
quiet -- Stops printing certain warning messages.
check=s|r|n -- Case sensitivity checking setting.
s: strict, case sensitive
r: relaxed, case insensitive
n: normal, default setting, currently case insensitive
nocase -- This was deprecated for vfat. Use shortname=win95 instead.
shortname=lower|win95|winnt|mixed
-- Shortname display/create setting.
lower: convert to lowercase for display,
emulate the Windows 95 rule for create.
win95: emulate the Windows 95 rule for display/create.
winnt: emulate the Windows NT rule for display/create.
mixed: emulate the Windows NT rule for display,
emulate the Windows 95 rule for create.
Default setting is `mixed'.
tz=UTC -- Interpret timestamps as UTC rather than local time.
This option disables the conversion of timestamps
between local time (as used by Windows on FAT) and UTC
(which Linux uses internally). This is particularly
useful when mounting devices (like digital cameras)
that are set to UTC in order to avoid the pitfalls of
local time.
time_offset=minutes
-- Set offset for conversion of timestamps from local time
used by FAT to UTC. I.e. <minutes> minutes will be subtracted
from each timestamp to convert it to UTC used internally by
Linux. This is useful when time zone set in sys_tz is
not the time zone used by the filesystem. Note that this
option still does not provide correct time stamps in all
cases in presence of DST - time stamps in a different DST
setting will be off by one hour.
showexec -- If set, the execute permission bits of the file will be
allowed only if the extension part of the name is .EXE,
.COM, or .BAT. Not set by default.
debug -- Can be set, but unused by the current implementation.
sys_immutable -- If set, ATTR_SYS attribute on FAT is handled as
IMMUTABLE flag on Linux. Not set by default.
flush -- If set, the filesystem will try to flush to disk more
early than normal. Not set by default.
rodir -- FAT has the ATTR_RO (read-only) attribute. On Windows,
the ATTR_RO of the directory will just be ignored,
and is used only by applications as a flag (e.g. it's set
for the customized folder).
If you want to use ATTR_RO as read-only flag even for
the directory, set this option.
errors=panic|continue|remount-ro
-- specify FAT behavior on critical errors: panic, continue
without doing anything or remount the partition in
read-only mode (default behavior).
discard -- If set, issues discard/TRIM commands to the block
device when blocks are freed. This is useful for SSD devices
and sparse/thinly-provisoned LUNs.
nfs=stale_rw|nostale_ro
Enable this only if you want to export the FAT filesystem
over NFS.
stale_rw: This option maintains an index (cache) of directory
inodes by i_logstart which is used by the nfs-related code to
improve look-ups. Full file operations (read/write) over NFS is
supported but with cache eviction at NFS server, this could
result in ESTALE issues.
nostale_ro: This option bases the inode number and filehandle
on the on-disk location of a file in the MS-DOS directory entry.
This ensures that ESTALE will not be returned after a file is
evicted from the inode cache. However, it means that operations
such as rename, create and unlink could cause filehandles that
previously pointed at one file to point at a different file,
potentially causing data corruption. For this reason, this
option also mounts the filesystem readonly.
To maintain backward compatibility, '-o nfs' is also accepted,
defaulting to stale_rw
dos1xfloppy -- If set, use a fallback default BIOS Parameter Block
configuration, determined by backing device size. These static
parameters match defaults assumed by DOS 1.x for 160 kiB,
180 kiB, 320 kiB, and 360 kiB floppies and floppy images.
<bool>: 0,1,yes,no,true,false
LIMITATION
---------------------------------------------------------------------
* The fallocated region of file is discarded at umount/evict time
when using fallocate with FALLOC_FL_KEEP_SIZE.
So, User should assume that fallocated region can be discarded at
last close if there is memory pressure resulting in eviction of
the inode from the memory. As a result, for any dependency on
the fallocated region, user should make sure to recheck fallocate
after reopening the file.
TODO
----------------------------------------------------------------------
* Need to get rid of the raw scanning stuff. Instead, always use
a get next directory entry approach. The only thing left that uses
raw scanning is the directory renaming code.
POSSIBLE PROBLEMS
----------------------------------------------------------------------
* vfat_valid_longname does not properly checked reserved names.
* When a volume name is the same as a directory name in the root
directory of the filesystem, the directory name sometimes shows
up as an empty file.
* autoconv option does not work correctly.
BUG REPORTS
----------------------------------------------------------------------
If you have trouble with the VFAT filesystem, mail bug reports to
chaffee@bmrc.cs.berkeley.edu. Please specify the filename
and the operation that gave you trouble.
TEST SUITE
----------------------------------------------------------------------
If you plan to make any modifications to the vfat filesystem, please
get the test suite that comes with the vfat distribution at
http://web.archive.org/web/*/http://bmrc.berkeley.edu/
people/chaffee/vfat.html
This tests quite a few parts of the vfat filesystem and additional
tests for new features or untested features would be appreciated.
NOTES ON THE STRUCTURE OF THE VFAT FILESYSTEM
----------------------------------------------------------------------
(This documentation was provided by Galen C. Hunt <gchunt@cs.rochester.edu>
and lightly annotated by Gordon Chaffee).
This document presents a very rough, technical overview of my
knowledge of the extended FAT file system used in Windows NT 3.5 and
Windows 95. I don't guarantee that any of the following is correct,
but it appears to be so.
The extended FAT file system is almost identical to the FAT
file system used in DOS versions up to and including 6.223410239847
:-). The significant change has been the addition of long file names.
These names support up to 255 characters including spaces and lower
case characters as opposed to the traditional 8.3 short names.
Here is the description of the traditional FAT entry in the current
Windows 95 filesystem:
struct directory { // Short 8.3 names
unsigned char name[8]; // file name
unsigned char ext[3]; // file extension
unsigned char attr; // attribute byte
unsigned char lcase; // Case for base and extension
unsigned char ctime_ms; // Creation time, milliseconds
unsigned char ctime[2]; // Creation time
unsigned char cdate[2]; // Creation date
unsigned char adate[2]; // Last access date
unsigned char reserved[2]; // reserved values (ignored)
unsigned char time[2]; // time stamp
unsigned char date[2]; // date stamp
unsigned char start[2]; // starting cluster number
unsigned char size[4]; // size of the file
};
The lcase field specifies if the base and/or the extension of an 8.3
name should be capitalized. This field does not seem to be used by
Windows 95 but it is used by Windows NT. The case of filenames is not
completely compatible from Windows NT to Windows 95. It is not completely
compatible in the reverse direction, however. Filenames that fit in
the 8.3 namespace and are written on Windows NT to be lowercase will
show up as uppercase on Windows 95.
Note that the "start" and "size" values are actually little
endian integer values. The descriptions of the fields in this
structure are public knowledge and can be found elsewhere.
With the extended FAT system, Microsoft has inserted extra
directory entries for any files with extended names. (Any name which
legally fits within the old 8.3 encoding scheme does not have extra
entries.) I call these extra entries slots. Basically, a slot is a
specially formatted directory entry which holds up to 13 characters of
a file's extended name. Think of slots as additional labeling for the
directory entry of the file to which they correspond. Microsoft
prefers to refer to the 8.3 entry for a file as its alias and the
extended slot directory entries as the file name.
The C structure for a slot directory entry follows:
struct slot { // Up to 13 characters of a long name
unsigned char id; // sequence number for slot
unsigned char name0_4[10]; // first 5 characters in name
unsigned char attr; // attribute byte
unsigned char reserved; // always 0
unsigned char alias_checksum; // checksum for 8.3 alias
unsigned char name5_10[12]; // 6 more characters in name
unsigned char start[2]; // starting cluster number
unsigned char name11_12[4]; // last 2 characters in name
};
If the layout of the slots looks a little odd, it's only
because of Microsoft's efforts to maintain compatibility with old
software. The slots must be disguised to prevent old software from
panicking. To this end, a number of measures are taken:
1) The attribute byte for a slot directory entry is always set
to 0x0f. This corresponds to an old directory entry with
attributes of "hidden", "system", "read-only", and "volume
label". Most old software will ignore any directory
entries with the "volume label" bit set. Real volume label
entries don't have the other three bits set.
2) The starting cluster is always set to 0, an impossible
value for a DOS file.
Because the extended FAT system is backward compatible, it is
possible for old software to modify directory entries. Measures must
be taken to ensure the validity of slots. An extended FAT system can
verify that a slot does in fact belong to an 8.3 directory entry by
the following:
1) Positioning. Slots for a file always immediately proceed
their corresponding 8.3 directory entry. In addition, each
slot has an id which marks its order in the extended file
name. Here is a very abbreviated view of an 8.3 directory
entry and its corresponding long name slots for the file
"My Big File.Extension which is long":
<proceeding files...>
<slot #3, id = 0x43, characters = "h is long">
<slot #2, id = 0x02, characters = "xtension whic">
<slot #1, id = 0x01, characters = "My Big File.E">
<directory entry, name = "MYBIGFIL.EXT">
Note that the slots are stored from last to first. Slots
are numbered from 1 to N. The Nth slot is or'ed with 0x40
to mark it as the last one.
2) Checksum. Each slot has an "alias_checksum" value. The
checksum is calculated from the 8.3 name using the
following algorithm:
for (sum = i = 0; i < 11; i++) {
sum = (((sum&1)<<7)|((sum&0xfe)>>1)) + name[i]
}
3) If there is free space in the final slot, a Unicode NULL (0x0000)
is stored after the final character. After that, all unused
characters in the final slot are set to Unicode 0xFFFF.
Finally, note that the extended name is stored in Unicode. Each Unicode
character takes either two or four bytes, UTF-16LE encoded.

246
Documentation/isdn/avmb1.rst
View File

@ -1,246 +0,0 @@
================================
Driver for active AVM Controller
================================
The driver provides a kernel capi2.0 Interface (kernelcapi) and
on top of this a User-Level-CAPI2.0-interface (capi)
and a driver to connect isdn4linux with CAPI2.0 (capidrv).
The lowlevel interface can be used to implement a CAPI2.0
also for passive cards since July 1999.
The author can be reached at calle@calle.in-berlin.de.
The command avmcapictrl is part of the isdn4k-utils.
t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
Currently supported cards:
- B1 ISA (all versions)
- B1 PCI
- T1/T1B (HEMA card)
- M1
- M2
- B1 PCMCIA
Installing
----------
You need at least /dev/capi20 to load the firmware.
::
mknod /dev/capi20 c 68 0
mknod /dev/capi20.00 c 68 1
mknod /dev/capi20.01 c 68 2
.
.
.
mknod /dev/capi20.19 c 68 20
Running
-------
To use the card you need the t4-files to download the firmware.
AVM GmbH provides several t4-files for the different D-channel
protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
if you configure as modules load the modules this way::
insmod /lib/modules/current/misc/capiutil.o
insmod /lib/modules/current/misc/b1.o
insmod /lib/modules/current/misc/kernelcapi.o
insmod /lib/modules/current/misc/capidrv.o
insmod /lib/modules/current/misc/capi.o
if you have an B1-PCI card load the module b1pci.o::
insmod /lib/modules/current/misc/b1pci.o
and load the firmware with::
avmcapictrl load /lib/isdn/b1.t4 1
if you have an B1-ISA card load the module b1isa.o
and add the card by calling::
avmcapictrl add 0x150 15
and load the firmware by calling::
avmcapictrl load /lib/isdn/b1.t4 1
if you have an T1-ISA card load the module t1isa.o
and add the card by calling::
avmcapictrl add 0x450 15 T1 0
and load the firmware by calling::
avmcapictrl load /lib/isdn/t1.t4 1
if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
before you insert the card.
Leased Lines with B1
--------------------
Init card and load firmware.
For an D64S use "FV: 1" as phone number
For an D64S2 use "FV: 1" and "FV: 2" for multilink
or "FV: 1,2" to use CAPI channel bundling.
/proc-Interface
-----------------
/proc/capi::
dr-xr-xr-x 2 root root 0 Jul 1 14:03 .
dr-xr-xr-x 82 root root 0 Jun 30 19:08 ..
-r--r--r-- 1 root root 0 Jul 1 14:03 applications
-r--r--r-- 1 root root 0 Jul 1 14:03 applstats
-r--r--r-- 1 root root 0 Jul 1 14:03 capi20
-r--r--r-- 1 root root 0 Jul 1 14:03 capidrv
-r--r--r-- 1 root root 0 Jul 1 14:03 controller
-r--r--r-- 1 root root 0 Jul 1 14:03 contrstats
-r--r--r-- 1 root root 0 Jul 1 14:03 driver
-r--r--r-- 1 root root 0 Jul 1 14:03 ncci
-r--r--r-- 1 root root 0 Jul 1 14:03 users
/proc/capi/applications:
applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
level3cnt:
capi_register parameter
datablkcnt:
capi_register parameter
ncci-cnt:
current number of nccis (connections)
recvqueuelen:
number of messages on receive queue
for example::
1 -2 16 2048 1 0
2 2 7 2048 1 0
/proc/capi/applstats:
applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
recvctlmsg:
capi messages received without DATA_B3_IND
recvdatamsg:
capi DATA_B3_IND received
sentctlmsg:
capi messages sent without DATA_B3_REQ
sentdatamsg:
capi DATA_B3_REQ sent
for example::
1 2057 1699 1721 1699
/proc/capi/capi20: statistics of capi.o (/dev/capi20)
minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
minor:
minor device number of capi device
nopen:
number of calls to devices open
nrecvdropmsg:
capi messages dropped (messages in recvqueue in close)
nrecvctlmsg:
capi messages received without DATA_B3_IND
nrecvdatamsg:
capi DATA_B3_IND received
nsentctlmsg:
capi messages sent without DATA_B3_REQ
nsentdatamsg:
capi DATA_B3_REQ sent
for example::
1 2 18 0 16 2
/proc/capi/capidrv: statistics of capidrv.o (capi messages)
nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
nrecvctlmsg:
capi messages received without DATA_B3_IND
nrecvdatamsg:
capi DATA_B3_IND received
nsentctlmsg:
capi messages sent without DATA_B3_REQ
nsentdatamsg:
capi DATA_B3_REQ sent
for example:
2780 2226 2256 2226
/proc/capi/controller:
controller drivername state cardname controllerinfo
for example::
1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
/proc/capi/contrstats:
controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
nrecvctlmsg:
capi messages received without DATA_B3_IND
nrecvdatamsg:
capi DATA_B3_IND received
nsentctlmsg:
capi messages sent without DATA_B3_REQ
nsentdatamsg:
capi DATA_B3_REQ sent
for example::
1 2845 2272 2310 2274
2 2 0 2 0
3 2 0 2 0
/proc/capi/driver:
drivername ncontroller
for example::
b1pci 1
t1isa 1
b1pcmcia 1
b1isa 0
/proc/capi/ncci:
apllid ncci winsize sendwindow
for example::
1 0x10101 8 0
/proc/capi/users: kernelmodules that use the kernelcapi.
name
for example::
capidrv
capi20
Questions
---------
Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
linux-avmb1@calle.in-berlin.de mailing list by sending
a mail to majordomo@calle.in-berlin.de with
subscribe linux-avmb1
in the body.
German documentation and several scripts can be found at
ftp://ftp.avm.de/cardware/b1/linux/
Bugs
----
If you find any please let me know.
Enjoy,
Carsten Paeth (calle@calle.in-berlin.de)

465
Documentation/isdn/gigaset.rst
View File

@ -1,465 +0,0 @@
==========================
GigaSet 307x Device Driver
==========================
1. Requirements
=================
1.1. Hardware
-------------
This driver supports the connection of the Gigaset 307x/417x family of
ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
connection. The following devices are reported to be compatible:
Bases:
- Siemens Gigaset 3070/3075 isdn
- Siemens Gigaset 4170/4175 isdn
- Siemens Gigaset SX205/255
- Siemens Gigaset SX353
- T-Com Sinus 45 [AB] isdn
- T-Com Sinus 721X[A] [SE]
- Vox Chicago 390 ISDN (KPN Telecom)
RS232 data boxes:
- Siemens Gigaset M101 Data
- T-Com Sinus 45 Data 1
USB data boxes:
- Siemens Gigaset M105 Data
- Siemens Gigaset USB Adapter DECT
- T-Com Sinus 45 Data 2
- T-Com Sinus 721 data
- Chicago 390 USB (KPN)
See also http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
http://gigaset307x.sourceforge.net/
We had also reports from users of Gigaset M105 who could use the drivers
with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
If you have another device that works with our driver, please let us know.
Chances of getting an USB device to work are good if the output of::
lsusb
at the command line contains one of the following::
ID 0681:0001
ID 0681:0002
ID 0681:0009
ID 0681:0021
ID 0681:0022
1.2. Software
-------------
The driver works with the Kernel CAPI subsystem and can be used with any
software which is able to use CAPI 2.0 for ISDN connections (voice or data).
There are some user space tools available at
https://sourceforge.net/projects/gigaset307x/
which provide access to additional device specific functions like SMS,
phonebook or call journal.
2. How to use the driver
==========================
2.1. Modules
------------
For the devices to work, the proper kernel modules have to be loaded.
This normally happens automatically when the system detects the USB
device (base, M105) or when the line discipline is attached (M101). It
can also be triggered manually using the modprobe(8) command, for example
for troubleshooting or to pass module parameters.
The module ser_gigaset provides a serial line discipline N_GIGASET_M101
which uses the regular serial port driver to access the device, and must
therefore be attached to the serial device to which the M101 is connected.
The ldattach(8) command (included in util-linux-ng release 2.14 or later)
can be used for that purpose, for example::
ldattach GIGASET_M101 /dev/ttyS1
This will open the device file, attach the line discipline to it, and
then sleep in the background, keeping the device open so that the line
discipline remains active. To deactivate it, kill the daemon, for example
with::
killall ldattach
before disconnecting the device. To have this happen automatically at
system startup/shutdown on an LSB compatible system, create and activate
an appropriate LSB startup script /etc/init.d/gigaset. (The init name
'gigaset' is officially assigned to this project by LANANA.)
Alternatively, just add the 'ldattach' command line to /etc/rc.local.
The modules accept the following parameters:
=============== ========== ==========================================
Module Parameter Meaning
gigaset debug debug level (see section 3.2.)
startmode initial operation mode (see section 2.5.):
bas_gigaset ) 1=CAPI (default), 0=Unimodem
ser_gigaset )
usb_gigaset ) cidmode initial Call-ID mode setting (see section
2.5.): 1=on (default), 0=off
=============== ========== ==========================================
Depending on your distribution you may want to create a separate module
configuration file like /etc/modprobe.d/gigaset.conf for these.
2.2. Device nodes for user space programs
-----------------------------------------
The device can be accessed from user space (eg. by the user space tools
mentioned in 1.2.) through the device nodes:
- /dev/ttyGS0 for M101 (RS232 data boxes)
- /dev/ttyGU0 for M105 (USB data boxes)
- /dev/ttyGB0 for the base driver (direct USB connection)
If you connect more than one device of a type, they will get consecutive
device nodes, eg. /dev/ttyGU1 for a second M105.
You can also set a "default device" for the user space tools to use when
no device node is given as parameter, by creating a symlink /dev/ttyG to
one of them, eg.::
ln -s /dev/ttyGB0 /dev/ttyG
The devices accept the following device specific ioctl calls
(defined in gigaset_dev.h):
``ioctl(int fd, GIGASET_REDIR, int *cmd);``
If cmd==1, the device is set to be controlled exclusively through the
character device node; access from the ISDN subsystem is blocked.
If cmd==0, the device is set to be used from the ISDN subsystem and does
not communicate through the character device node.
``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
(ser_gigaset and usb_gigaset only)
If cmd==1, the device is set to adapter configuration mode where commands
are interpreted by the M10x DECT adapter itself instead of being
forwarded to the base station. In this mode, the device accepts the
commands described in Siemens document "AT-Kommando Alignment M10x Data"
for setting the operation mode, associating with a base station and
querying parameters like field strengh and signal quality.
Note that there is no ioctl command for leaving adapter configuration
mode and returning to regular operation. In order to leave adapter
configuration mode, write the command ATO to the device.
``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
(usb_gigaset only)
Set the break characters on an M105's internal serial adapter to the six
bytes stored in brkchars[]. Unused bytes should be set to zero.
ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
Retrieve version information from the driver. version[0] must be set to
one of:
- GIGVER_DRIVER: retrieve driver version
- GIGVER_COMPAT: retrieve interface compatibility version
- GIGVER_FWBASE: retrieve the firmware version of the base
Upon return, version[] is filled with the requested version information.
2.3. CAPI
---------
The devices will show up as CAPI controllers as soon as the
corresponding driver module is loaded, and can then be used with
CAPI 2.0 kernel and user space applications. For user space access,
the module capi.ko must be loaded.
Most distributions handle loading and unloading of the various CAPI
modules automatically via the command capiinit(1) from the capi4k-utils
package or a similar mechanism. Note that capiinit(1) cannot unload the
Gigaset drivers because it doesn't support more than one module per
driver.
2.5. Unimodem mode
------------------
In this mode the device works like a modem connected to a serial port
(the /dev/ttyGU0, ... mentioned above) which understands the commands::
ATZ init, reset
=> OK or ERROR
ATD
ATDT dial
=> OK, CONNECT,
BUSY,
NO DIAL TONE,
NO CARRIER,
NO ANSWER
<pause>+++<pause> change to command mode when connected
ATH hangup
You can use some configuration tool of your distribution to configure this
"modem" or configure pppd/wvdial manually. There are some example ppp
configuration files and chat scripts in the gigaset-VERSION/ppp directory
in the driver packages from https://sourceforge.net/projects/gigaset307x/.
Please note that the USB drivers are not able to change the state of the
control lines. This means you must use "Stupid Mode" if you are using
wvdial or you should use the nocrtscts option of pppd.
You must also assure that the ppp_async module is loaded with the parameter
flag_time=0. You can do this e.g. by adding a line like::
options ppp_async flag_time=0
to an appropriate module configuration file, like::
/etc/modprobe.d/gigaset.conf.
Unimodem mode is needed for making some devices [e.g. SX100] work which
do not support the regular Gigaset command set. If debug output (see
section 3.2.) shows something like this when dialing::
CMD Received: ERROR
Available Params: 0
Connection State: 0, Response: -1
gigaset_process_response: resp_code -1 in ConState 0 !
Timeout occurred
then switching to unimodem mode may help.
If you have installed the command line tool gigacontr, you can enter
unimodem mode using::
gigacontr --mode unimodem
You can switch back using::
gigacontr --mode isdn
You can also put the driver directly into Unimodem mode when it's loaded,
by passing the module parameter startmode=0 to the hardware specific
module, e.g.::
modprobe usb_gigaset startmode=0
or by adding a line like::
options usb_gigaset startmode=0
to an appropriate module configuration file, like::
/etc/modprobe.d/gigaset.conf
2.6. Call-ID (CID) mode
-----------------------
Call-IDs are numbers used to tag commands to, and responses from, the
Gigaset base in order to support the simultaneous handling of multiple
ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
mode"). Without Call-IDs (in Unimodem mode), only a very limited set of
functions is available. It allows outgoing data connections only, but
does not signal incoming calls or other base events.
DECT cordless data devices (M10x) permanently occupy the cordless
connection to the base while Call-IDs are activated. As the Gigaset
bases only support one DECT data connection at a time, this prevents
other DECT cordless data devices from accessing the base.
During active operation, the driver switches to the necessary mode
automatically. However, for the reasons above, the mode chosen when
the device is not in use (idle) can be selected by the user.
- If you want to receive incoming calls, you can use the default
settings (CID mode).
- If you have several DECT data devices (M10x) which you want to use
in turn, select Unimodem mode by passing the parameter "cidmode=0" to
the appropriate driver module (ser_gigaset or usb_gigaset).
If you want both of these at once, you are out of luck.
You can also use the tty class parameter "cidmode" of the device to
change its CID mode while the driver is loaded, eg.::
echo 0 > /sys/class/tty/ttyGU0/cidmode
2.7. Dialing Numbers
--------------------
provided by an application for dialing out must
be a public network number according to the local dialing plan, without
any dial prefix for getting an outside line.
Internal calls can be made by providing an internal extension number
prefixed with ``**`` (two asterisks) as the called party number. So to dial
eg. the first registered DECT handset, give ``**11`` as the called party
number. Dialing ``***`` (three asterisks) calls all extensions
simultaneously (global call).
Unimodem mode does not support internal calls.
2.8. Unregistered Wireless Devices (M101/M105)
----------------------------------------------
The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
the M101 and M105 wireless devices to be used as ISDN devices for ISDN
connections through a Gigaset base. Therefore they assume that the device
is registered to a DECT base.
If the M101/M105 device is not registered to a base, initialization of
the device fails, and a corresponding error message is logged by the
driver. In that situation, a restricted set of functions is available
which includes, in particular, those necessary for registering the device
to a base or for switching it between Fixed Part and Portable Part
modes. See the gigacontr(8) manpage for details.
3. Troubleshooting
====================
3.1. Solutions to frequently reported problems
----------------------------------------------
Problem:
You have a slow provider and isdn4linux gives up dialing too early.
Solution:
Load the isdn module using the dialtimeout option. You can do this e.g.
by adding a line like::
options isdn dialtimeout=15
to /etc/modprobe.d/gigaset.conf or a similar file.
Problem:
The isdnlog program emits error messages or just doesn't work.
Solution:
Isdnlog supports only the HiSax driver. Do not attempt to use it with
other drivers such as Gigaset.
Problem:
You have two or more DECT data adapters (M101/M105) and only the
first one you turn on works.
Solution:
Select Unimodem mode for all DECT data adapters. (see section 2.5.)
Problem:
Messages like this::
usb_gigaset 3-2:1.0: Could not initialize the device.
appear in your syslog.
Solution:
Check whether your M10x wireless device is correctly registered to the
Gigaset base. (see section 2.7.)
3.2. Telling the driver to provide more information
---------------------------------------------------
Building the driver with the "Gigaset debugging" kernel configuration
option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
information useful for debugging.
You can control the amount of debugging information the driver produces by
writing an appropriate value to /sys/module/gigaset/parameters/debug,
e.g.::
echo 0 > /sys/module/gigaset/parameters/debug
switches off debugging output completely,
::
echo 0x302020 > /sys/module/gigaset/parameters/debug
enables a reasonable set of debugging output messages. These values are
bit patterns where every bit controls a certain type of debugging output.
See the constants DEBUG_* in the source file gigaset.h for details.
The initial value can be set using the debug parameter when loading the
module "gigaset", e.g. by adding a line::
options gigaset debug=0
to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
Generated debugging information can be found
- as output of the command::
dmesg
- in system log files written by your syslog daemon, usually
in /var/log/, e.g. /var/log/messages.
3.3. Reporting problems and bugs
--------------------------------
If you can't solve problems with the driver on your own, feel free to
use one of the forums, bug trackers, or mailing lists on
https://sourceforge.net/projects/gigaset307x
or write an electronic mail to the maintainers.
Try to provide as much information as possible, such as
- distribution
- kernel version (uname -r)
- gcc version (gcc --version)
- hardware architecture (uname -m, ...)
- type and firmware version of your device (base and wireless module,
if any)
- output of "lsusb -v" (if using an USB device)
- error messages
- relevant system log messages (it would help if you activate debug
output as described in 3.2.)
For help with general configuration problems not specific to our driver,
such as isdn4linux and network configuration issues, please refer to the
appropriate forums and newsgroups.
3.4. Reporting problem solutions
--------------------------------
If you solved a problem with our drivers, wrote startup scripts for your
distribution, ... feel free to contact us (using one of the places
mentioned in 3.3.). We'd like to add scripts, hints, documentation
to the driver and/or the project web page.
4. Links, other software
==========================
- Sourceforge project developing this driver and associated tools
https://sourceforge.net/projects/gigaset307x
- Yahoo! Group on the Siemens Gigaset family of devices
https://de.groups.yahoo.com/group/Siemens-Gigaset
- Siemens Gigaset/T-Sinus compatibility table
http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
5. Credits
============
Thanks to
Karsten Keil
for his help with isdn4linux
Deti Fliegl
for his base driver code
Dennis Dietrich
for his kernel 2.6 patches
Andreas Rummel
for his work and logs to get unimodem mode working
Andreas Degert
for his logs and patches to get cx 100 working
Dietrich Feist
for his generous donation of one M105 and two M101 cordless adapters
Christoph Schweers
for his generous donation of a M34 device
and all the other people who sent logs and other information.

196
Documentation/isdn/hysdn.rst
View File

@ -1,196 +0,0 @@
============
Hysdn Driver
============
The hysdn driver has been written by
Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
under the GNU General Public License.
The CAPI 2.0-support was added by Ulrich Albrecht (ualbrecht@hypercope.de)
for Hypercope GmbH Aachen, Germany.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.. Table of contents
1. About the driver
2. Loading/Unloading the driver
3. Entries in the /proc filesystem
4. The /proc/net/hysdn/cardconfX file
5. The /proc/net/hysdn/cardlogX file
6. Where to get additional info and help
1. About the driver
===================
The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
enable ISDN support in the kernel config and support for HYSDN cards in
the active cards submenu. The driver may only be compiled and used if
support for loadable modules and the process filesystem have been enabled.
These cards provide two different interfaces to the kernel. Without the
optional CAPI 2.0 support, they register as ethernet card. IP-routing
to a ISDN-destination is performed on the card itself. All necessary
handlers for various protocols like ppp and others as well as config info
and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
compliant devices with either CAPI 2.0 applications
(check isdn4k-utils) or -using the capidrv module- as a regular
isdn4linux device. This is done via the same mechanism as with the
active AVM cards and in fact uses the same module.
2. Loading/Unloading the driver
===============================
The module has no command line parameters and auto detects up to 10 cards
in the id-range 0-9.
If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
subdir need to be closed and all ethernet interfaces allocated by this
driver must be shut down. Otherwise the module counter will avoid a module
unload.
If you are using the CAPI 2.0-interface, make sure to load/modprobe the
kernelcapi-module first.
If you plan to use the capidrv-link to isdn4linux, make sure to load
capidrv.o after all modules using this driver (i.e. after hysdn and
any avm-specific modules).
3. Entries in the /proc filesystem
==================================
When the module has been loaded it adds the directory hysdn in the
/proc/net tree. This directory contains exactly 2 file entries for each
card. One is called cardconfX and the other cardlogX, where X is the
card id number from 0 to 9.
The cards are numbered in the order found in the PCI config data.
4. The /proc/net/hysdn/cardconfX file
=====================================
This file may be read to get by everyone to get info about the cards type,
actual state, available features and used resources.
The first 3 entries (id, bus and slot) are PCI info fields, the following
type field gives the information about the cards type:
- 4 -> Ergo card (server card with 2 b-chans)
- 5 -> Metro card (server card with 4 or 8 b-chans)
- 6 -> Champ card (client card with 2 b-chans)
The following 3 fields show the hardware assignments for irq, iobase and the
dual ported memory (dp-mem).
The fields b-chans and fax-chans announce the available card resources of
this types for the user.
The state variable indicates the actual drivers state for this card with the
following assignments.
- 0 -> card has not been booted since driver load
- 1 -> card booting is actually in progess
- 2 -> card is in an error state due to a previous boot failure
- 3 -> card is booted and active
And the last field (device) shows the name of the ethernet device assigned
to this card. Up to the first successful boot this field only shows a -
to tell that no net device has been allocated up to now. Once a net device
has been allocated it remains assigned to this card, even if a card is
rebooted and an boot error occurs.
Writing to the cardconfX file boots the card or transfers config lines to
the cards firmware. The type of data is automatically detected when the
first data is written. Only root has write access to this file.
The firmware boot files are normally called hyclient.pof for client cards
and hyserver.pof for server cards.
After successfully writing the boot file, complete config files or single
config lines may be copied to this file.
If an error occurs the return value given to the writing process has the
following additional codes (decimal):
==== ============================================
1000 Another process is currently bootng the card
1001 Invalid firmware header
1002 Boards dual-port RAM test failed
1003 Internal firmware handler error
1004 Boot image size invalid
1005 First boot stage (bootstrap loader) failed
1006 Second boot stage failure
1007 Timeout waiting for card ready during boot
1008 Operation only allowed in booted state
1009 Config line too long
1010 Invalid channel number
1011 Timeout sending config data
==== ============================================
Additional info about error reasons may be fetched from the log output.
5. The /proc/net/hysdn/cardlogX file
====================================
The cardlogX file entry may be opened multiple for reading by everyone to
get the cards and drivers log data. Card messages always start with the
keyword LOG. All other lines are output from the driver.
The driver log data may be redirected to the syslog by selecting the
appropriate bitmask. The cards log messages will always be send to this
interface but never to the syslog.
A root user may write a decimal or hex (with 0x) value t this file to select
desired output options. As mentioned above the cards log dat is always
written to the cardlog file independent of the following options only used
to check and debug the driver itself:
For example::
echo "0x34560078" > /proc/net/hysdn/cardlog0
to output the hex log mask 34560078 for card 0.
The written value is regarded as an unsigned 32-Bit value, bit ored for
desired output. The following bits are already assigned:
========== ============================================================
0x80000000 All driver log data is alternatively via syslog
0x00000001 Log memory allocation errors
0x00000010 Firmware load start and close are logged
0x00000020 Log firmware record parser
0x00000040 Log every firmware write actions
0x00000080 Log all card related boot messages
0x00000100 Output all config data sent for debugging purposes
0x00000200 Only non comment config lines are shown wth channel
0x00000400 Additional conf log output
0x00001000 Log the asynchronous scheduler actions (config and log)
0x00100000 Log all open and close actions to /proc/net/hysdn/card files
0x00200000 Log all actions from /proc file entries
0x00010000 Log network interface init and deinit
========== ============================================================
6. Where to get additional info and help
========================================
If you have any problems concerning the driver or configuration contact
the Hypercope support team (support@hypercope.de) and or the authors
Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
Ulrich Albrecht (ualbrecht@hypercope.de).

3
Documentation/isdn/index.rst
View File

@ -9,9 +9,6 @@ ISDN
interface_capi
avmb1
gigaset
hysdn
m_isdn
credits

71
Documentation/isdn/interface_capi.rst
View File

@ -26,13 +26,6 @@ This standard is freely available from https://www.capi.org.
2. Driver and Device Registration
=================================
CAPI drivers optionally register themselves with Kernel CAPI by calling the
Kernel CAPI function register_capi_driver() with a pointer to a struct
capi_driver. This structure must be filled with the name and revision of the
driver, and optionally a pointer to a callback function, add_card(). The
registration can be revoked by calling the function unregister_capi_driver()
with a pointer to the same struct capi_driver.
CAPI drivers must register each of the ISDN devices they control with Kernel
CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
struct capi_ctr before they can be used. This structure must be filled with
@ -89,9 +82,6 @@ register_capi_driver():
the name of the driver, as a zero-terminated ASCII string
``char revision[32]``
the revision number of the driver, as a zero-terminated ASCII string
``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
a callback function pointer (may be NULL)
4.2 struct capi_ctr
-------------------
@ -178,12 +168,6 @@ to be set by the driver before calling attach_capi_ctr():
pointer to a callback function returning the entry for the device in
the CAPI controller info table, /proc/capi/controller
``const struct file_operations *proc_fops``
pointers to callback functions for the device's proc file
system entry, /proc/capi/controllers/<n>; pointer to the device's
capi_ctr structure is available from struct proc_dir_entry::data
which is available from struct inode.
Note:
Callback functions except send_message() are never called in interrupt
context.
@ -267,25 +251,10 @@ _cmstruct alternative representation for CAPI parameters of type 'struct'
_cmsg structure members.
=========== =================================================================
Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
messages between their transport encoding described in the CAPI 2.0 standard
and their _cmsg structure representation. Note that capi_cmsg2message() does
not know or check the size of its destination buffer. The caller must make
sure it is big enough to accommodate the resulting CAPI message.
5. Lower Layer Interface Functions
==================================
(declared in <linux/isdn/capilli.h>)
::
void register_capi_driver(struct capi_driver *drvr)
void unregister_capi_driver(struct capi_driver *drvr)
register/unregister a driver with Kernel CAPI
::
int attach_capi_ctr(struct capi_ctr *ctrlr)
@ -300,13 +269,6 @@ register/unregister a device (controller) with Kernel CAPI
signal controller ready/not ready
::
void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
void capi_ctr_resume_output(struct capi_ctr *ctrlr)
signal suspend/resume
::
void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
@ -319,21 +281,6 @@ for forwarding to the specified application
6. Helper Functions and Macros
==============================
Library functions (from <linux/isdn/capilli.h>):
::
void capilib_new_ncci(struct list_head *head, u16 applid,
u32 ncci, u32 winsize)
void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
void capilib_release_appl(struct list_head *head, u16 applid)
void capilib_release(struct list_head *head)
void capilib_data_b3_conf(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
u16 capilib_data_b3_req(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
Macros to extract/set element values from/in a CAPI message header
(from <linux/isdn/capiutil.h>):
@ -357,24 +304,6 @@ CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
Library functions for working with _cmsg structures
(from <linux/isdn/capiutil.h>):
``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
storing the result in ``*msg``.
``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
in ``*cmsg``.
``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
Fills the header part and address field of the _cmsg structure ``*cmsg``
with the given values, zeroing the remainder of the structure so only
parameters with non-default values need to be changed before sending
the message.
``void capi_cmsg_answer(_cmsg *cmsg)``
Sets the low bit of the Subcommand field in ``*cmsg``, thereby
converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
``char *capi_cmd2str(u8 Command, u8 Subcommand)``
Returns the CAPI 2.0 message name corresponding to the given command
and subcommand values, as a static ASCII string. The return value may

4
Documentation/kernel-hacking/hacking.rst
View File

@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
namespace. Symbol Namespaces are documented in
``Documentation/kbuild/namespaces.rst``.
``Documentation/core-api/symbol-namespaces.rst``.
:c:func:`EXPORT_SYMBOL_NS_GPL()`
--------------------------------
@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
namespace. Symbol Namespaces are documented in
``Documentation/kbuild/namespaces.rst``.
``Documentation/core-api/symbol-namespaces.rst``.
Routines and Conventions
========================

3
Documentation/locking/locktorture.rst
View File

@ -103,8 +103,7 @@ stat_interval
Number of seconds between statistics-related printk()s.
By default, locktorture will report stats every 60 seconds.
Setting the interval to zero causes the statistics to
be printed -only- when the module is unloaded, and this
is the default.
be printed -only- when the module is unloaded.
stutter
The length of time to run the test before pausing for this

1
Documentation/maintainer/maintainer-entry-profile.rst
View File

@ -99,4 +99,5 @@ to do something different in the near future.
.. toctree::
:maxdepth: 1
../doc-guide/maintainer-profile
../nvdimm/maintainer-entry-profile

1
Documentation/misc-devices/xilinx_sdfec.rst
View File

@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0+
====================
Xilinx SD-FEC Driver
====================

3
Documentation/nvdimm/maintainer-entry-profile.rst
View File

@ -33,7 +33,8 @@ Those tests need to be passed before the patches go upstream, but not
necessarily before initial posting. Contact the list if you need help
getting the test environment set up.
### ACPI Device Specific Methods (_DSM)
ACPI Device Specific Methods (_DSM)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before patches enabling for a new _DSM family will be considered it must
be assigned a format-interface-code from the NVDIMM Sub-team of the ACPI
Specification Working Group. In general, the stance of the subsystem is

23
Documentation/process/embargoed-hardware-issues.rst
View File

@ -1,3 +1,5 @@
.. _embargoed_hardware_issues:
Embargoed hardware issues
=========================
@ -36,7 +38,10 @@ issue according to our documented process.
The list is encrypted and email to the list can be sent by either PGP or
S/MIME encrypted and must be signed with the reporter's PGP key or S/MIME
certificate. The list's PGP key and S/MIME certificate are available from
https://www.kernel.org/....
the following URLs:
- PGP: https://www.kernel.org/static/files/hardware-security.asc
- S/MIME: https://www.kernel.org/static/files/hardware-security.crt
While hardware security issues are often handled by the affected hardware
vendor, we welcome contact from researchers or individuals who have
@ -55,14 +60,14 @@ Operation of mailing-lists
^^^^^^^^^^^^^^^^^^^^^^^^^^
The encrypted mailing-lists which are used in our process are hosted on
Linux Foundation's IT infrastructure. By providing this service Linux
Foundation's director of IT Infrastructure security technically has the
ability to access the embargoed information, but is obliged to
confidentiality by his employment contract. Linux Foundation's director of
IT Infrastructure security is also responsible for the kernel.org
infrastructure.
Linux Foundation's IT infrastructure. By providing this service, members
of Linux Foundation's IT operations personnel technically have the
ability to access the embargoed information, but are obliged to
confidentiality by their employment contract. Linux Foundation IT
personnel are also responsible for operating and managing the rest of
kernel.org infrastructure.
The Linux Foundation's current director of IT Infrastructure security is
The Linux Foundation's current director of IT Project infrastructure is
Konstantin Ryabitsev.
@ -274,7 +279,7 @@ software decrypts the email and re-encrypts it individually for each
subscriber with the subscriber's PGP key or S/MIME certificate. Details
about the mailing-list software and the setup which is used to ensure the
security of the lists and protection of the data can be found here:
https://www.kernel.org/....
https://korg.wiki.kernel.org/userdoc/remail.
List keys
^^^^^^^^^

4
Documentation/riscv/boot-image-header.rst
View File

@ -22,7 +22,7 @@ The following 64-byte header is present in decompressed Linux kernel image::
u64 res2 = 0; /* Reserved */
u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */
u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */
u32 res4; /* Reserved for PE COFF offset */
u32 res3; /* Reserved for PE COFF offset */
This header format is compliant with PE/COFF header and largely inspired from
ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common
@ -34,7 +34,7 @@ Notes
- This header can also be reused to support EFI stub for RISC-V in future. EFI
specification needs PE/COFF image header in the beginning of the kernel image
in order to load it as an EFI application. In order to support EFI stub,
code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should
code0 should be replaced with "MZ" magic string and res3(at offset 0x3c) should
point to the rest of the PE/COFF header.
- version field indicate header version number

7
Documentation/sphinx/automarkup.py
View File

@ -5,8 +5,13 @@
# has been done.
#
from docutils import nodes
import sphinx
from sphinx import addnodes
from sphinx.environment import NoUri
if sphinx.version_info[0] < 2 or \
sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1:
from sphinx.environment import NoUri
else:
from sphinx.errors import NoUri
import re
#

18
Documentation/trace/ftrace.rst
View File

@ -95,7 +95,8 @@ of ftrace. Here is a list of some of the key files:
current_tracer:
This is used to set or display the current tracer
that is configured.
that is configured. Changing the current tracer clears
the ring buffer content as well as the "snapshot" buffer.
available_tracers:
@ -126,7 +127,8 @@ of ftrace. Here is a list of some of the key files:
This file holds the output of the trace in a human
readable format (described below). Note, tracing is temporarily
disabled when the file is open for reading. Once all readers
are closed, tracing is re-enabled.
are closed, tracing is re-enabled. Opening this file for
writing with the O_TRUNC flag clears the ring buffer content.
trace_pipe:
@ -185,7 +187,8 @@ of ftrace. Here is a list of some of the key files:
CPU buffer and not total size of all buffers. The
trace buffers are allocated in pages (blocks of memory
that the kernel uses for allocation, usually 4 KB in size).
If the last page allocated has room for more bytes
A few extra pages may be allocated to accommodate buffer management
meta-data. If the last page allocated has room for more bytes
than requested, the rest of the page will be used,
making the actual allocation bigger than requested or shown.
( Note, the size may not be a multiple of the page size
@ -235,7 +238,7 @@ of ftrace. Here is a list of some of the key files:
This interface also allows for commands to be used. See the
"Filter commands" section for more details.
As a speed up, since processing strings can't be quite expensive
As a speed up, since processing strings can be quite expensive
and requires a check of all functions registered to tracing, instead
an index can be written into this file. A number (starting with "1")
written will instead select the same corresponding at the line position
@ -382,7 +385,7 @@ of ftrace. Here is a list of some of the key files:
By default, 128 comms are saved (see "saved_cmdlines" above). To
increase or decrease the amount of comms that are cached, echo
in a the number of comms to cache, into this file.
the number of comms to cache into this file.
saved_tgids:
@ -490,6 +493,9 @@ of ftrace. Here is a list of some of the key files:
# echo global > trace_clock
Setting a clock clears the ring buffer content as well as the
"snapshot" buffer.
trace_marker:
This is a very useful file for synchronizing user space
@ -3324,7 +3330,7 @@ directories after it is created.
As you can see, the new directory looks similar to the tracing directory
itself. In fact, it is very similar, except that the buffer and
events are agnostic from the main director, or from any other
events are agnostic from the main directory, or from any other
instances that are created.
The files in the new directory work just like the files with the

2
Documentation/trace/ring-buffer-design.txt
View File

@ -37,7 +37,7 @@ commit_page - a pointer to the page with the last finished non-nested write.
cmpxchg - hardware-assisted atomic transaction that performs the following:
A = B iff previous A == C
A = B if previous A == C
R = cmpxchg(A, C, B) is saying that we replace A with B if and only if
current A is equal to C, and we put the old (current) A into R

4
Documentation/translations/ko_KR/memory-barriers.txt
View File

@ -2413,7 +2413,7 @@ _않습니다_.
알고 있는, - inb() 나 writel() 과 같은 - 적절한 액세스 루틴을 통해 이루어져야만
합니다. 이것들은 대부분의 경우에는 명시적 메모리 배리어 와 함께 사용될 필요가
없습니다만, 완화된 메모리 액세스 속성으로 I/O 메모리 윈도우로의 참조를 위해
액세스 함수가 사용된다면 순서를 강제하기 위해 _madatory_ 메모리 배리어가
액세스 함수가 사용된다면 순서를 강제하기 위해 _mandatory_ 메모리 배리어가
필요합니다.
더 많은 정보를 위해선 Documentation/driver-api/device-io.rst 를 참고하십시오.
@ -2528,7 +2528,7 @@ I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에
이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서
보장을 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스나 delay()
루프 (예:앞의 2-5 항목) 에 대해 순서를 보장하지 않습니다만 디폴트 I/O
기능으로 매핑된 __iomem 포인터에 대해 동작할 때, 같은 CPU 쓰레드에 의해
기능으로 매핑된 __iomem 포인터에 대해 동작할 때, 같은 CPU 쓰레드에 의한
같은 주변장치로의 액세스에는 순서가 맞춰질 것이 보장됩니다.
(*) readsX(), writesX():

228
Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst Normal file
View File

@ -0,0 +1,228 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/embargoed-hardware-issues.rst <embargoed_hardware_issues>`
:Translator: Alex Shi <alex.shi@linux.alibaba.com>
被限制的硬件问题
================
范围
----
导致安全问题的硬件问题与只影响Linux内核的纯软件错误是不同的安全错误类别。
必须区别对待诸如熔毁(Meltdown)、Spectre、L1TF等硬件问题，因为它们通常会影响
所有操作系统（“OS”），因此需要在不同的OS供应商、发行版、硬件供应商和其他各方
之间进行协调。对于某些问题，软件缓解可能依赖于微码或固件更新，这需要进一步的
协调。
.. _zh_Contact:
接触
----
Linux内核硬件安全小组独立于普通的Linux内核安全小组。
该小组只负责协调被限制的硬件安全问题。Linux内核中纯软件安全漏洞的报告不由该
小组处理，报告者将被引导至常规Linux内核安全小组(:ref:`Documentation/admin-guide/
<securitybugs>`)联系。
可以通过电子邮件 <hardware-security@kernel.org> 与小组联系。这是一份私密的安全
官名单，他们将帮助您根据我们的文档化流程协调问题。
邮件列表是加密的，发送到列表的电子邮件可以通过PGP或S/MIME加密，并且必须使用报告
者的PGP密钥或S/MIME证书签名。该列表的PGP密钥和S/MIME证书可从
https://www.kernel.org/.... 获得。
虽然硬件安全问题通常由受影响的硬件供应商处理，但我们欢迎发现潜在硬件缺陷的研究
人员或个人与我们联系。
硬件安全官
^^^^^^^^^^
目前的硬件安全官小组:
- Linus Torvalds（Linux基金会院士）
- Greg Kroah Hartman（Linux基金会院士）
- Thomas Gleixner（Linux基金会院士）
邮件列表的操作
^^^^^^^^^^^^^^
处理流程中使用的加密邮件列表托管在Linux Foundation的IT基础设施上。通过提供这项
服务，Linux基金会的IT基础设施安全总监在技术上有能力访问被限制的信息，但根据他
的雇佣合同，他必须保密。Linux基金会的IT基础设施安全总监还负责 kernel.org 基础
设施。
Linux基金会目前的IT基础设施安全总监是 Konstantin Ryabitsev。
保密协议
--------
Linux内核硬件安全小组不是正式的机构，因此无法签订任何保密协议。核心社区意识到
这些问题的敏感性，并提供了一份谅解备忘录。
谅解备忘录
----------
Linux内核社区深刻理解在不同操作系统供应商、发行商、硬件供应商和其他各方之间
进行协调时，保持硬件安全问题处于限制状态的要求。
Linux内核社区在过去已经成功地处理了硬件安全问题，并且有必要的机制允许在限制
限制下进行符合社区的开发。
Linux内核社区有一个专门的硬件安全小组负责初始联系，并监督在限制规则下处理
此类问题的过程。
硬件安全小组确定开发人员（领域专家），他们将组成特定问题的初始响应小组。最初
的响应小组可以引入更多的开发人员（领域专家）以最佳的技术方式解决这个问题。
所有相关开发商承诺遵守限制规定，并对收到的信息保密。违反承诺将导致立即从当前
问题中排除，并从所有相关邮件列表中删除。此外，硬件安全小组还将把违反者排除在
未来的问题之外。这一后果的影响在我们社区是一种非常有效的威慑。如果发生违规
情况，硬件安全小组将立即通知相关方。如果您或任何人发现潜在的违规行为，请立即
向硬件安全人员报告。
流程
^^^^
由于Linux内核开发的全球分布式特性，面对面的会议几乎不可能解决硬件安全问题。
由于时区和其他因素，电话会议很难协调，只能在绝对必要时使用。加密电子邮件已被
证明是解决此类问题的最有效和最安全的通信方法。
开始披露
""""""""
披露内容首先通过电子邮件联系Linux内核硬件安全小组。此初始联系人应包含问题的
描述和任何已知受影响硬件的列表。如果您的组织制造或分发受影响的硬件，我们建议
您也考虑哪些其他硬件可能会受到影响。
硬件安全小组将提供一个特定于事件的加密邮件列表，用于与报告者进行初步讨论、
进一步披露和协调。
硬件安全小组将向披露方提供一份开发人员（领域专家）名单，在与开发人员确认他们
将遵守本谅解备忘录和文件化流程后，应首先告知开发人员有关该问题的信息。这些开发
人员组成初始响应小组，并在初始接触后负责处理问题。硬件安全小组支持响应小组，
但不一定参与缓解开发过程。
虽然个别开发人员可能通过其雇主受到保密协议的保护，但他们不能以Linux内核开发
人员的身份签订个别保密协议。但是，他们将同意遵守这一书面程序和谅解备忘录。
披露方应提供已经或应该被告知该问题的所有其他实体的联系人名单。这有几个目的:
- 披露的实体列表允许跨行业通信，例如其他操作系统供应商、硬件供应商等。
- 可联系已披露的实体，指定应参与缓解措施开发的专家。
- 如果需要处理某一问题的专家受雇于某一上市实体或某一上市实体的成员，则响应
小组可要求该实体披露该专家。这确保专家也是实体反应小组的一部分。
披露
""""
披露方通过特定的加密邮件列表向初始响应小组提供详细信息。
根据我们的经验，这些问题的技术文档通常是一个足够的起点，最好通过电子邮件进行
进一步的技术澄清。
缓解开发
""""""""
初始响应小组设置加密邮件列表，或在适当的情况下重新修改现有邮件列表。
使用邮件列表接近于正常的Linux开发过程，并且在过去已经成功地用于为各种硬件安全
问题开发缓解措施。
邮件列表的操作方式与正常的Linux开发相同。发布、讨论和审查修补程序，如果同意，
则应用于非公共git存储库，参与开发人员只能通过安全连接访问该存储库。存储库包含
针对主线内核的主开发分支，并根据需要为稳定的内核版本提供向后移植分支。
最初的响应小组将根据需要从Linux内核开发人员社区中确定更多的专家。引进专家可以
在开发过程中的任何时候发生，需要及时处理。
如果专家受雇于披露方提供的披露清单上的实体或其成员，则相关实体将要求其参与。
否则，披露方将被告知专家参与的情况。谅解备忘录涵盖了专家，要求披露方确认参与。
如果披露方有令人信服的理由提出异议，则必须在五个工作日内提出异议，并立即与事件
小组解决。如果披露方在五个工作日内未作出回应，则视为默许。
在确认或解决异议后，专家由事件小组披露，并进入开发过程。
协调发布
""""""""
有关各方将协商限制结束的日期和时间。此时，准备好的缓解措施集成到相关的内核树中
并发布。
虽然我们理解硬件安全问题需要协调限制时间，但限制时间应限制在所有有关各方制定、
测试和准备缓解措施所需的最短时间内。人为地延长限制时间以满足会议讨论日期或其他
非技术原因，会给相关的开发人员和响应小组带来了更多的工作和负担，因为补丁需要
保持最新，以便跟踪正在进行的上游内核开发，这可能会造成冲突的更改。
CVE分配
"""""""
硬件安全小组和初始响应小组都不分配CVE，开发过程也不需要CVE。如果CVE是由披露方
提供的，则可用于文档中。
流程专使
--------
为了协助这一进程，我们在各组织设立了专使，他们可以回答有关报告流程和进一步处理
的问题或提供指导。专使不参与特定问题的披露，除非响应小组或相关披露方提出要求。
现任专使名单:
============= ========================================================
ARM
AMD Tom Lendacky <tom.lendacky@amd.com>
IBM
Intel Tony Luck <tony.luck@intel.com>
Qualcomm Trilok Soni <tsoni@codeaurora.org>
Microsoft Sasha Levin <sashal@kernel.org>
VMware
Xen Andrew Cooper <andrew.cooper3@citrix.com>
Canonical Tyler Hicks <tyhicks@canonical.com>
Debian Ben Hutchings <ben@decadent.org.uk>
Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Red Hat Josh Poimboeuf <jpoimboe@redhat.com>
SUSE Jiri Kosina <jkosina@suse.cz>
Amazon
Google Kees Cook <keescook@chromium.org>
============= ========================================================
如果要将您的组织添加到专使名单中，请与硬件安全小组联系。被提名的专使必须完全
理解和支持我们的过程，并且在Linux内核社区中很容易联系。
加密邮件列表
------------
我们使用加密邮件列表进行通信。这些列表的工作原理是，发送到列表的电子邮件使用
列表的PGP密钥或列表的/MIME证书进行加密。邮件列表软件对电子邮件进行解密，并
使用订阅者的PGP密钥或S/MIME证书为每个订阅者分别对其进行重新加密。有关邮件列表
软件和用于确保列表安全和数据保护的设置的详细信息，请访问:
https://www.kernel.org/....
关键点
^^^^^^
初次接触见 :ref:`zh_Contact`. 对于特定于事件的邮件列表，密钥和S/MIME证书通过
特定列表发送的电子邮件传递给订阅者。
订阅事件特定列表
^^^^^^^^^^^^^^^^
订阅由响应小组处理。希望参与通信的披露方将潜在订户的列表发送给响应组，以便
响应组可以验证订阅请求。
每个订户都需要通过电子邮件向响应小组发送订阅请求。电子邮件必须使用订阅服务器
的PGP密钥或S/MIME证书签名。如果使用PGP密钥，则必须从公钥服务器获得该密钥，
并且理想情况下该密钥连接到Linux内核的PGP信任网。另请参见:
https://www.kernel.org/signature.html.
响应小组验证订阅者，并将订阅者添加到列表中。订阅后，订阅者将收到来自邮件列表
的电子邮件，该邮件列表使用列表的PGP密钥或列表的/MIME证书签名。订阅者的电子邮件
客户端可以从签名中提取PGP密钥或S/MIME证书，以便订阅者可以向列表发送加密电子
邮件。

3
Documentation/translations/zh_CN/process/index.rst
View File

@ -31,6 +31,8 @@
development-process
email-clients
license-rules
kernel-enforcement-statement
kernel-driver-statement
其它大多数开发人员感兴趣的社区指南：
@ -43,6 +45,7 @@
stable-api-nonsense
stable-kernel-rules
management-style
embargoed-hardware-issues
这些是一些总体技术指南，由于缺乏更好的地方，现在已经放在这里

199
Documentation/translations/zh_CN/process/kernel-driver-statement.rst Normal file
View File

@ -0,0 +1,199 @@
.. _cn_process_statement_driver:
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>`
:Translator: Alex Shi <alex.shi@linux.alibaba.com>
内核驱动声明
------------
关于Linux内核模块的立场声明
===========================
我们，以下署名的Linux内核开发人员，认为任何封闭源Linux内核模块或驱动程序都是
有害的和不可取的。我们已经一再发现它们对Linux用户，企业和更大的Linux生态系统
有害。这样的模块否定了Linux开发模型的开放性，稳定性，灵活性和可维护性，并使
他们的用户无法使用Linux社区的专业知识。提供闭源内核模块的供应商迫使其客户
放弃Linux的主要优势或选择新的供应商。因此，为了充分利用开源所提供的成本节省和
共享支持优势，我们敦促供应商采取措施，以开源内核代码在Linux上为其客户提供支持。
我们只为自己说话，而不是我们今天可能会为之工作，过去或将来会为之工作的任何公司。
- Dave Airlie
- Nick Andrew
- Jens Axboe
- Ralf Baechle
- Felipe Balbi
- Ohad Ben-Cohen
- Muli Ben-Yehuda
- Jiri Benc
- Arnd Bergmann
- Thomas Bogendoerfer
- Vitaly Bordug
- James Bottomley
- Josh Boyer
- Neil Brown
- Mark Brown
- David Brownell
- Michael Buesch
- Franck Bui-Huu
- Adrian Bunk
- François Cami
- Ralph Campbell
- Luiz Fernando N. Capitulino
- Mauro Carvalho Chehab
- Denis Cheng
- Jonathan Corbet
- Glauber Costa
- Alan Cox
- Magnus Damm
- Ahmed S. Darwish
- Robert P. J. Day
- Hans de Goede
- Arnaldo Carvalho de Melo
- Helge Deller
- Jean Delvare
- Mathieu Desnoyers
- Sven-Thorsten Dietrich
- Alexey Dobriyan
- Daniel Drake
- Alex Dubov
- Randy Dunlap
- Michael Ellerman
- Pekka Enberg
- Jan Engelhardt
- Mark Fasheh
- J. Bruce Fields
- Larry Finger
- Jeremy Fitzhardinge
- Mike Frysinger
- Kumar Gala
- Robin Getz
- Liam Girdwood
- Jan-Benedict Glaw
- Thomas Gleixner
- Brice Goglin
- Cyrill Gorcunov
- Andy Gospodarek
- Thomas Graf
- Krzysztof Halasa
- Harvey Harrison
- Stephen Hemminger
- Michael Hennerich
- Tejun Heo
- Benjamin Herrenschmidt
- Kristian Høgsberg
- Henrique de Moraes Holschuh
- Marcel Holtmann
- Mike Isely
- Takashi Iwai
- Olof Johansson
- Dave Jones
- Jesper Juhl
- Matthias Kaehlcke
- Kenji Kaneshige
- Jan Kara
- Jeremy Kerr
- Russell King
- Olaf Kirch
- Roel Kluin
- Hans-Jürgen Koch
- Auke Kok
- Peter Korsgaard
- Jiri Kosina
- Aaro Koskinen
- Mariusz Kozlowski
- Greg Kroah-Hartman
- Michael Krufky
- Aneesh Kumar
- Clemens Ladisch
- Christoph Lameter
- Gunnar Larisch
- Anders Larsen
- Grant Likely
- John W. Linville
- Yinghai Lu
- Tony Luck
- Pavel Machek
- Matt Mackall
- Paul Mackerras
- Roland McGrath
- Patrick McHardy
- Kyle McMartin
- Paul Menage
- Thierry Merle
- Eric Miao
- Akinobu Mita
- Ingo Molnar
- James Morris
- Andrew Morton
- Paul Mundt
- Oleg Nesterov
- Luca Olivetti
- S.Çağlar Onur
- Pierre Ossman
- Keith Owens
- Venkatesh Pallipadi
- Nick Piggin
- Nicolas Pitre
- Evgeniy Polyakov
- Richard Purdie
- Mike Rapoport
- Sam Ravnborg
- Gerrit Renker
- Stefan Richter
- David Rientjes
- Luis R. Rodriguez
- Stefan Roese
- Francois Romieu
- Rami Rosen
- Stephen Rothwell
- Maciej W. Rozycki
- Mark Salyzyn
- Yoshinori Sato
- Deepak Saxena
- Holger Schurig
- Amit Shah
- Yoshihiro Shimoda
- Sergei Shtylyov
- Kay Sievers
- Sebastian Siewior
- Rik Snel
- Jes Sorensen
- Alexey Starikovskiy
- Alan Stern
- Timur Tabi
- Hirokazu Takata
- Eliezer Tamir
- Eugene Teo
- Doug Thompson
- FUJITA Tomonori
- Dmitry Torokhov
- Marcelo Tosatti
- Steven Toth
- Theodore Tso
- Matthias Urlichs
- Geert Uytterhoeven
- Arjan van de Ven
- Ivo van Doorn
- Rik van Riel
- Wim Van Sebroeck
- Hans Verkuil
- Horst H. von Brand
- Dmitri Vorobiev
- Anton Vorontsov
- Daniel Walker
- Johannes Weiner
- Harald Welte
- Matthew Wilcox
- Dan J. Williams
- Darrick J. Wong
- David Woodhouse
- Chris Wright
- Bryan Wu
- Rafael J. Wysocki
- Herbert Xu
- Vlad Yasevich
- Peter Zijlstra
- Bartlomiej Zolnierkiewicz

151
Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst Normal file
View File

@ -0,0 +1,151 @@
.. _cn_process_statement_kernel:
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>`
:Translator: Alex Shi <alex.shi@linux.alibaba.com>
Linux 内核执行声明
------------------
作为Linux内核的开发人员，我们对如何使用我们的软件以及如何实施软件许可证有着
浓厚的兴趣。遵守GPL-2.0的互惠共享义务对我们软件和社区的长期可持续性至关重要。
虽然有权强制执行对我们社区的贡献中的单独版权权益，但我们有共同的利益，即确保
个人强制执行行动的方式有利于我们的社区，不会对我们软件生态系统的健康和增长
产生意外的负面影响。为了阻止无益的执法行动，我们同意代表我们自己和我们版权
利益的任何继承人对Linux内核用户作出以下符合我们开发社区最大利益的承诺:
尽管有GPL-2.0的终止条款，我们同意，采用以下GPL-3.0条款作为我们许可证下的
附加许可，作为任何对许可证下权利的非防御性主张，这符合我们开发社区的最佳
利益。
但是，如果您停止所有违反本许可证的行为，则您从特定版权持有人处获得的
许可证将被恢复：（a）暂时恢复，除非版权持有人明确并最终终止您的许可证；
以及（b）永久恢复, 如果版权持有人未能在你终止违反后60天内以合理方式
通知您违反本许可证的行为，则永久恢复您的许可证。
此外，如果版权所有者以某种合理的方式通知您违反了本许可，这是您第一次
从该版权所有者处收到违反本许可的通知（对于任何作品），并且您在收到通知
后的30天内纠正违规行为。则您从特定版权所有者处获得的许可将永久恢复.
我们提供这些保证的目的是鼓励更多地使用该软件。我们希望公司和个人使用、修改和
分发此软件。我们希望以公开和透明的方式与用户合作，以消除我们对法规遵从性或强制
执行的任何不确定性，这些不确定性可能会限制我们软件的采用。我们将法律行动视为
最后手段，只有在其他社区努力未能解决这一问题时才采取行动。
最后，一旦一个不合规问题得到解决，我们希望用户会感到欢迎，加入我们为之努力的
这个项目。共同努力，我们会更强大。
除了下面提到的以外，我们只为自己说话，而不是为今天、过去或将来可能为之工作的
任何公司说话。
- Laura Abbott
- Bjorn Andersson (Linaro)
- Andrea Arcangeli
- Neil Armstrong
- Jens Axboe
- Pablo Neira Ayuso
- Khalid Aziz
- Ralf Baechle
- Felipe Balbi
- Arnd Bergmann
- Ard Biesheuvel
- Tim Bird
- Paolo Bonzini
- Christian Borntraeger
- Mark Brown (Linaro)
- Paul Burton
- Javier Martinez Canillas
- Rob Clark
- Kees Cook (Google)
- Jonathan Corbet
- Dennis Dalessandro
- Vivien Didelot (Savoir-faire Linux)
- Hans de Goede
- Mel Gorman (SUSE)
- Sven Eckelmann
- Alex Elder (Linaro)
- Fabio Estevam
- Larry Finger
- Bhumika Goyal
- Andy Gross
- Juergen Gross
- Shawn Guo
- Ulf Hansson
- Stephen Hemminger (Microsoft)
- Tejun Heo
- Rob Herring
- Masami Hiramatsu
- Michal Hocko
- Simon Horman
- Johan Hovold (Hovold Consulting AB)
- Christophe JAILLET
- Olof Johansson
- Lee Jones (Linaro)
- Heiner Kallweit
- Srinivas Kandagatla
- Jan Kara
- Shuah Khan (Samsung)
- David Kershner
- Jaegeuk Kim
- Namhyung Kim
- Colin Ian King
- Jeff Kirsher
- Greg Kroah-Hartman (Linux Foundation)
- Christian König
- Vinod Koul
- Krzysztof Kozlowski
- Viresh Kumar
- Aneesh Kumar K.V
- Julia Lawall
- Doug Ledford
- Chuck Lever (Oracle)
- Daniel Lezcano
- Shaohua Li
- Xin Long
- Tony Luck
- Catalin Marinas (Arm Ltd)
- Mike Marshall
- Chris Mason
- Paul E. McKenney
- Arnaldo Carvalho de Melo
- David S. Miller
- Ingo Molnar
- Kuninori Morimoto
- Trond Myklebust
- Martin K. Petersen (Oracle)
- Borislav Petkov
- Jiri Pirko
- Josh Poimboeuf
- Sebastian Reichel (Collabora)
- Guenter Roeck
- Joerg Roedel
- Leon Romanovsky
- Steven Rostedt (VMware)
- Frank Rowand
- Ivan Safonov
- Anna Schumaker
- Jes Sorensen
- K.Y. Srinivasan
- David Sterba (SUSE)
- Heiko Stuebner
- Jiri Kosina (SUSE)
- Willy Tarreau
- Dmitry Torokhov
- Linus Torvalds
- Thierry Reding
- Rik van Riel
- Luis R. Rodriguez
- Geert Uytterhoeven (Glider bvba)
- Eduardo Valentin (Amazon.com)
- Daniel Vetter
- Linus Walleij
- Richard Weinberger
- Dan Williams
- Rafael J. Wysocki
- Arvind Yadav
- Masahiro Yamada
- Wei Yongjun
- Lv Zheng
- Marc Zyngier (Arm Ltd)

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