xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Pull Documentation updates from Jonathan Corbet:
 "It's been a relatively busy cycle for docs:

   - A fair pile of RST conversions, many from Mauro. These create more
     than the usual number of simple but annoying merge conflicts with
     other trees, unfortunately. He has a lot more of these waiting on
     the wings that, I think, will go to you directly later on.

   - A new document on how to use merges and rebases in kernel repos,
     and one on Spectre vulnerabilities.

   - Various improvements to the build system, including automatic
     markup of function() references because some people, for reasons I
     will never understand, were of the opinion that
     :c:func:``function()`` is unattractive and not fun to type.

   - We now recommend using sphinx 1.7, but still support back to 1.4.

   - Lots of smaller improvements, warning fixes, typo fixes, etc"

* tag 'docs-5.3' of git://git.lwn.net/linux: (129 commits)
  docs: automarkup.py: ignore exceptions when seeking for xrefs
  docs: Move binderfs to admin-guide
  Disable Sphinx SmartyPants in HTML output
  doc: RCU callback locks need only _bh, not necessarily _irq
  docs: format kernel-parameters -- as code
  Doc : doc-guide : Fix a typo
  platform: x86: get rid of a non-existent document
  Add the RCU docs to the core-api manual
  Documentation: RCU: Add TOC tree hooks
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU basic concepts to reST
  docs: filesystems: Remove uneeded .rst extension on toctables
  scripts/sphinx-pre-install: fix out-of-tree build
  docs: zh_CN: submitting-drivers.rst: Remove a duplicated Documentation/
  Documentation: PGP: update for newer HW devices
  Documentation: Add section about CPU vulnerabilities for Spectre
  Documentation: platform: Delete x86-laptop-drivers.txt
  docs: Note that :c:func: should no longer be used
  ...
This commit is contained in:
Linus Torvalds
2019-07-09 12:34:26 -07:00
parent 7011b7e1b7 454f96f2b7
commit e9a83bd232
416 changed files with 12093 additions and 8515 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
Documentation/driver-api/basics.rst
View File

@@ -115,9 +115,6 @@ Kernel utility functions
.. kernel-doc:: kernel/rcu/tree.c
:export:
.. kernel-doc:: kernel/rcu/tree_plugin.h
:export:
.. kernel-doc:: kernel/rcu/update.c
:export:

6
Documentation/driver-api/clk.rst
View File

@@ -175,9 +175,9 @@ the following::
To take advantage of your data you'll need to support valid operations
for your clk::
struct clk_ops clk_foo_ops {
.enable = &clk_foo_enable;
.disable = &clk_foo_disable;
struct clk_ops clk_foo_ops = {
.enable = &clk_foo_enable,
.disable = &clk_foo_disable,
};
Implement the above functions using container_of::

2
Documentation/driver-api/firmware/other_interfaces.rst
View File

@@ -33,7 +33,7 @@ of the requests on to a secure monitor (EL3).
:functions: stratix10_svc_client_msg
.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h
:functions: stratix10_svc_command_reconfig_payload
:functions: stratix10_svc_command_config_type
.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h
:functions: stratix10_svc_cb_data

2
Documentation/driver-api/gpio/board.rst
View File

@@ -101,7 +101,7 @@ with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
}
For more information about the ACPI GPIO bindings see
Documentation/acpi/gpio-properties.txt.
Documentation/firmware-guide/acpi/gpio-properties.rst.
Platform Data
-------------

2
Documentation/driver-api/gpio/consumer.rst
View File

@@ -435,7 +435,7 @@ case, it will be handled by the GPIO subsystem automatically. However, if the
_DSD is not present, the mappings between GpioIo()/GpioInt() resources and GPIO
connection IDs need to be provided by device drivers.
For details refer to Documentation/acpi/gpio-properties.txt
For details refer to Documentation/firmware-guide/acpi/gpio-properties.rst
Interacting With the Legacy GPIO Subsystem

1
Documentation/driver-api/iio/hw-consumer.rst
View File

@@ -45,7 +45,6 @@ A typical IIO HW consumer setup looks like this::
More details
============
.. kernel-doc:: include/linux/iio/hw-consumer.h
.. kernel-doc:: drivers/iio/buffer/industrialio-hw-consumer.c
:export:

242
Documentation/driver-api/pps.rst Normal file
View File

@@ -0,0 +1,242 @@
:orphan:
======================
PPS - Pulse Per Second
======================
Copyright (C) 2007 Rodolfo Giometti <giometti@enneenne.com>
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.
Overview
--------
LinuxPPS provides a programming interface (API) to define in the
system several PPS sources.
PPS means "pulse per second" and a PPS source is just a device which
provides a high precision signal each second so that an application
can use it to adjust system clock time.
A PPS source can be connected to a serial port (usually to the Data
Carrier Detect pin) or to a parallel port (ACK-pin) or to a special
CPU's GPIOs (this is the common case in embedded systems) but in each
case when a new pulse arrives the system must apply to it a timestamp
and record it for userland.
Common use is the combination of the NTPD as userland program, with a
GPS receiver as PPS source, to obtain a wallclock-time with
sub-millisecond synchronisation to UTC.
RFC considerations
------------------
While implementing a PPS API as RFC 2783 defines and using an embedded
CPU GPIO-Pin as physical link to the signal, I encountered a deeper
problem:
At startup it needs a file descriptor as argument for the function
time_pps_create().
This implies that the source has a /dev/... entry. This assumption is
OK for the serial and parallel port, where you can do something
useful besides(!) the gathering of timestamps as it is the central
task for a PPS API. But this assumption does not work for a single
purpose GPIO line. In this case even basic file-related functionality
(like read() and write()) makes no sense at all and should not be a
precondition for the use of a PPS API.
The problem can be simply solved if you consider that a PPS source is
not always connected with a GPS data source.
So your programs should check if the GPS data source (the serial port
for instance) is a PPS source too, and if not they should provide the
possibility to open another device as PPS source.
In LinuxPPS the PPS sources are simply char devices usually mapped
into files /dev/pps0, /dev/pps1, etc.
PPS with USB to serial devices
------------------------------
It is possible to grab the PPS from an USB to serial device. However,
you should take into account the latencies and jitter introduced by
the USB stack. Users have reported clock instability around +-1ms when
synchronized with PPS through USB. With USB 2.0, jitter may decrease
down to the order of 125 microseconds.
This may be suitable for time server synchronization with NTP because
of its undersampling and algorithms.
If your device doesn't report PPS, you can check that the feature is
supported by its driver. Most of the time, you only need to add a call
to usb_serial_handle_dcd_change after checking the DCD status (see
ch341 and pl2303 examples).
Coding example
--------------
To register a PPS source into the kernel you should define a struct
pps_source_info as follows::
static struct pps_source_info pps_ktimer_info = {
.name = "ktimer",
.path = "",
.mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT |
PPS_ECHOASSERT |
PPS_CANWAIT | PPS_TSFMT_TSPEC,
.echo = pps_ktimer_echo,
.owner = THIS_MODULE,
};
and then calling the function pps_register_source() in your
initialization routine as follows::
source = pps_register_source(&pps_ktimer_info,
PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
The pps_register_source() prototype is::
int pps_register_source(struct pps_source_info *info, int default_params)
where "info" is a pointer to a structure that describes a particular
PPS source, "default_params" tells the system what the initial default
parameters for the device should be (it is obvious that these parameters
must be a subset of ones defined in the struct
pps_source_info which describe the capabilities of the driver).
Once you have registered a new PPS source into the system you can
signal an assert event (for example in the interrupt handler routine)
just using::
pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
where "ts" is the event's timestamp.
The same function may also run the defined echo function
(pps_ktimer_echo(), passing to it the "ptr" pointer) if the user
asked for that... etc..
Please see the file drivers/pps/clients/pps-ktimer.c for example code.
SYSFS support
-------------
If the SYSFS filesystem is enabled in the kernel it provides a new class::
$ ls /sys/class/pps/
pps0/ pps1/ pps2/
Every directory is the ID of a PPS sources defined in the system and
inside you find several files::
$ ls -F /sys/class/pps/pps0/
assert dev mode path subsystem@
clear echo name power/ uevent
Inside each "assert" and "clear" file you can find the timestamp and a
sequence number::
$ cat /sys/class/pps/pps0/assert
1170026870.983207967#8
Where before the "#" is the timestamp in seconds; after it is the
sequence number. Other files are:
* echo: reports if the PPS source has an echo function or not;
* mode: reports available PPS functioning modes;
* name: reports the PPS source's name;
* path: reports the PPS source's device path, that is the device the
PPS source is connected to (if it exists).
Testing the PPS support
-----------------------
In order to test the PPS support even without specific hardware you can use
the pps-ktimer driver (see the client subsection in the PPS configuration menu)
and the userland tools available in your distribution's pps-tools package,
http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
Once you have enabled the compilation of pps-ktimer just modprobe it (if
not statically compiled)::
# modprobe pps-ktimer
and the run ppstest as follow::
$ ./ppstest /dev/pps1
trying PPS source "/dev/pps1"
found PPS source "/dev/pps1"
ok, found 1 source(s), now start fetching data...
source 0 - assert 1186592699.388832443, sequence: 364 - clear 0.000000000, sequence: 0
source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0
source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0
Please note that to compile userland programs, you need the file timepps.h.
This is available in the pps-tools repository mentioned above.
Generators
----------
Sometimes one needs to be able not only to catch PPS signals but to produce
them also. For example, running a distributed simulation, which requires
computers' clock to be synchronized very tightly. One way to do this is to
invent some complicated hardware solutions but it may be neither necessary
nor affordable. The cheap way is to load a PPS generator on one of the
computers (master) and PPS clients on others (slaves), and use very simple
cables to deliver signals using parallel ports, for example.
Parallel port cable pinout::
pin name master slave
1 STROBE *------ *
2 D0 * | *
3 D1 * | *
4 D2 * | *
5 D3 * | *
6 D4 * | *
7 D5 * | *
8 D6 * | *
9 D7 * | *
10 ACK * ------*
11 BUSY * *
12 PE * *
13 SEL * *
14 AUTOFD * *
15 ERROR * *
16 INIT * *
17 SELIN * *
18-25 GND *-----------*
Please note that parallel port interrupt occurs only on high->low transition,
so it is used for PPS assert edge. PPS clear edge can be determined only
using polling in the interrupt handler which actually can be done way more
precisely because interrupt handling delays can be quite big and random. So
current parport PPS generator implementation (pps_gen_parport module) is
geared towards using the clear edge for time synchronization.
Clear edge polling is done with disabled interrupts so it's better to select
delay between assert and clear edge as small as possible to reduce system
latencies. But if it is too small slave won't be able to capture clear edge
transition. The default of 30us should be good enough in most situations.
The delay can be selected using 'delay' pps_gen_parport module parameter.

96
Documentation/driver-api/ptp.rst Normal file
View File

@@ -0,0 +1,96 @@
:orphan:
===========================================
PTP hardware clock infrastructure for Linux
===========================================
This patch set introduces support for IEEE 1588 PTP clocks in
Linux. Together with the SO_TIMESTAMPING socket options, this
presents a standardized method for developing PTP user space
programs, synchronizing Linux with external clocks, and using the
ancillary features of PTP hardware clocks.
A new class driver exports a kernel interface for specific clock
drivers and a user space interface. The infrastructure supports a
complete set of PTP hardware clock functionality.
+ Basic clock operations
- Set time
- Get time
- Shift the clock by a given offset atomically
- Adjust clock frequency
+ Ancillary clock features
- Time stamp external events
- Period output signals configurable from user space
- Synchronization of the Linux system time via the PPS subsystem
PTP hardware clock kernel API
=============================
A PTP clock driver registers itself with the class driver. The
class driver handles all of the dealings with user space. The
author of a clock driver need only implement the details of
programming the clock hardware. The clock driver notifies the class
driver of asynchronous events (alarms and external time stamps) via
a simple message passing interface.
The class driver supports multiple PTP clock drivers. In normal use
cases, only one PTP clock is needed. However, for testing and
development, it can be useful to have more than one clock in a
single system, in order to allow performance comparisons.
PTP hardware clock user space API
=================================
The class driver also creates a character device for each
registered clock. User space can use an open file descriptor from
the character device as a POSIX clock id and may call
clock_gettime, clock_settime, and clock_adjtime. These calls
implement the basic clock operations.
User space programs may control the clock using standardized
ioctls. A program may query, enable, configure, and disable the
ancillary clock features. User space can receive time stamped
events via blocking read() and poll().
Writing clock drivers
=====================
Clock drivers include include/linux/ptp_clock_kernel.h and register
themselves by presenting a 'struct ptp_clock_info' to the
registration method. Clock drivers must implement all of the
functions in the interface. If a clock does not offer a particular
ancillary feature, then the driver should just return -EOPNOTSUPP
from those functions.
Drivers must ensure that all of the methods in interface are
reentrant. Since most hardware implementations treat the time value
as a 64 bit integer accessed as two 32 bit registers, drivers
should use spin_lock_irqsave/spin_unlock_irqrestore to protect
against concurrent access. This locking cannot be accomplished in
class driver, since the lock may also be needed by the clock
driver's interrupt service routine.
Supported hardware
==================
* Freescale eTSEC gianfar
- 2 Time stamp external triggers, programmable polarity (opt. interrupt)
- 2 Alarm registers (optional interrupt)
- 3 Periodic signals (optional interrupt)
* National DP83640
- 6 GPIOs programmable as inputs or outputs
- 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
used as general inputs or outputs
- GPIO inputs can time stamp external triggers
- GPIO outputs can produce periodic signals
- 1 interrupt pin
* Intel IXP465
- Auxiliary Slave/Master Mode Snapshot (optional interrupt)
- Target Time (optional interrupt)

4
Documentation/driver-api/target.rst
View File

@@ -10,8 +10,8 @@ TBD
Target core device interfaces
=============================
.. kernel-doc:: drivers/target/target_core_device.c
:export:
This section is blank because no kerneldoc comments have been added to
drivers/target/target_core_device.c.
Target core transport interfaces
================================