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

Pull documentation update from Jon Corbet:
 "There is a nice new document from Neil on how pathname lookups work
  and some new CAN driver documentation.  Beyond that, we have
  kernel-doc fixes, a bit more work to support reproducible builds, and
  the usual collection of small fixes"

* tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits)
  Documentation: add new description of path-name lookup.
  Documentation/vm/slub.txt: document slabinfo-gnuplot.sh
  Doc: ABI/stable: Fix typo in ABI/stable
  doc: Clarify that nmi_watchdog param is for hardlockups
  Typo correction for description in gpio document.
  DocBook: Fix kernel-doc to be case-insensitive for private:
  kernel-docs.txt: update kernelnewbies reference
  Doc:kvm: Fix typo in Doc/virtual/kvm
  Documentation/Changes: Add bc in "Current Minimal Requirements" section
  Documentation/email-clients.txt: remove trailing whitespace
  DocBook: Use a fixed encoding for output
  MAINTAINERS: The docs tree has moved
  Docs/kernel-parameters: Add earlycon devicetree usage
  SubmittingPatches: make Subject examples match the de facto standard
  Documentation: gpio: mention that <function>-gpio has been deprecated
  Documentation: cgroups: just fix a few typos
  Documentation: Update kselftest.txt
  Documentation: DMA API: Be more explicit that nents is always the same
  Documentation: Update the default value of crashkernel low
  zram: update documentation
  ...

1 files changed, 77 insertions, 20 deletions

diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt
index fd1a1aad49a9..4636b94518da 100644
--- a/Documentation/networking/can.txt
+++ b/Documentation/networking/can.txt
@@ -1018,25 +1018,34 @@ solution for a couple of reasons:
 
     $ ip link set can0 type can help
     Usage: ip link set DEVICE type can
-    	[ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
-    	[ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
-     	  phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
-
-    	[ loopback { on | off } ]
-    	[ listen-only { on | off } ]
-    	[ triple-sampling { on | off } ]
-
-    	[ restart-ms TIME-MS ]
-    	[ restart ]
-
-    	Where: BITRATE       := { 1..1000000 }
-    	       SAMPLE-POINT  := { 0.000..0.999 }
-    	       TQ            := { NUMBER }
-    	       PROP-SEG      := { 1..8 }
-    	       PHASE-SEG1    := { 1..8 }
-    	       PHASE-SEG2    := { 1..8 }
-    	       SJW           := { 1..4 }
-    	       RESTART-MS    := { 0 | NUMBER }
+        [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
+        [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
+          phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
+
+        [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
+        [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
+          dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
+
+        [ loopback { on | off } ]
+        [ listen-only { on | off } ]
+        [ triple-sampling { on | off } ]
+        [ one-shot { on | off } ]
+        [ berr-reporting { on | off } ]
+        [ fd { on | off } ]
+        [ fd-non-iso { on | off } ]
+        [ presume-ack { on | off } ]
+
+        [ restart-ms TIME-MS ]
+        [ restart ]
+
+        Where: BITRATE       := { 1..1000000 }
+               SAMPLE-POINT  := { 0.000..0.999 }
+               TQ            := { NUMBER }
+               PROP-SEG      := { 1..8 }
+               PHASE-SEG1    := { 1..8 }
+               PHASE-SEG2    := { 1..8 }
+               SJW           := { 1..4 }
+               RESTART-MS    := { 0 | NUMBER }
 
   - Display CAN device details and statistics:
 
@@ -1178,7 +1187,55 @@ solution for a couple of reasons:
   The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
   N.B. CAN FD capable devices can also handle and send legacy CAN frames.
 
-  FIXME: Add details about the CAN FD controller configuration when available.
+  When configuring CAN FD capable CAN controllers an additional 'data' bitrate
+  has to be set. This bitrate for the data phase of the CAN FD frame has to be
+  at least the bitrate which was configured for the arbitration phase. This
+  second bitrate is specified analogue to the first bitrate but the bitrate
+  setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate,
+  dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
+  within the configuration process the controller option "fd on" can be
+  specified to enable the CAN FD mode in the CAN controller. This controller
+  option also switches the device MTU to 72 (CANFD_MTU).
+
+  The first CAN FD specification presented as whitepaper at the International
+  CAN Conference 2012 needed to be improved for data integrity reasons.
+  Therefore two CAN FD implementations have to be distinguished today:
+
+  - ISO compliant:     The ISO 11898-1:2015 CAN FD implementation (default)
+  - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
+
+  Finally there are three types of CAN FD controllers:
+
+  1. ISO compliant (fixed)
+  2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
+  3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
+
+  The current ISO/non-ISO mode is announced by the CAN controller driver via
+  netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
+  The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
+  switchable CAN FD controllers only.
+
+  Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate:
+
+    $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
+                                   dbitrate 4000000 dsample-point 0.8 fd on
+    $ ip -details link show can0
+    5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \
+             mode DEFAULT group default qlen 10
+    link/can  promiscuity 0
+    can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
+          bitrate 500000 sample-point 0.750
+          tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
+          pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \
+          brp-inc 1
+          dbitrate 4000000 dsample-point 0.800
+          dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
+          pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \
+          dbrp-inc 1
+          clock 80000000
+
+  Example when 'fd-non-iso on' is added on this switchable CAN FD adapter:
+   can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
 
   6.7 Supported CAN hardware