From 9f446781616ccc317ba081d0f367f37ee94ed42f Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Mon, 30 Oct 2017 14:15:36 +0100 Subject: drm/TODO: Clarify DRM_DEV_* conversion Not everyone agrees this is the best thing, so make it really clear that maintainers need to be asked first, then the conversion. We've had a few newbies that did this the other way round, got their patches rejected, which isn't the best newbie experience. Cc: Sean Paul Acked-by: Sean Paul Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171030131536.11654-1-daniel.vetter@ffwll.ch --- Documentation/gpu/todo.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 96f8ec7dbe4e..e9840d693a86 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -179,6 +179,10 @@ don't do this, drivers used dev_info/warn/err to make this differentiation. We now have DRM_DEV_* variants of the drm print macros, so we can start to convert those drivers back to using drm-formwatted specific log messages. +Before you start this conversion please contact the relevant maintainers to make +sure your work will be merged - not everyone agrees that the DRM dmesg macros +are better. + Contact: Sean Paul, Maintainer of the driver you plan to convert Core refactorings -- cgit From 2ac9d363376a3bae4854ddc1089442d63bf6c3b0 Mon Sep 17 00:00:00 2001 From: Philippe CORNU Date: Thu, 26 Oct 2017 13:48:08 +0200 Subject: dt-bindings: display: stm32: add a 2nd endpoint ltdc can have up to 2 endpoints: - dpi external gpios: for rgb panels or external bridge ICs. - dpi internal ios: connected internally to dsi. Note: Refer to the reference manual to know if the dsi is present on your device. Signed-off-by: Philippe Cornu Acked-by: Rob Herring Signed-off-by: Benjamin Gaignard Link: https://patchwork.freedesktop.org/patch/msgid/1509018489-19641-2-git-send-email-philippe.cornu@st.com --- Documentation/devicetree/bindings/display/st,stm32-ltdc.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt index 74b5ac7b26d6..029252253ad4 100644 --- a/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt +++ b/Documentation/devicetree/bindings/display/st,stm32-ltdc.txt @@ -10,7 +10,11 @@ - "lcd" for the clock feeding the output pixel clock & IP clock. - resets: reset to be used by the device (defined by use of RCC macro). Required nodes: - - Video port for RGB output. + - Video port for DPI RGB output: ltdc has one video port with up to 2 + endpoints: + - for external dpi rgb panel or bridge, using gpios. + - for internal dpi input of the MIPI DSI host controller. + Note: These 2 endpoints cannot be activated simultaneously. * STMicroelectronics STM32 DSI controller specific extensions to Synopsys DesignWare MIPI DSI host controller -- cgit From 5926466f543342a098da68b8f771c169dfa8b914 Mon Sep 17 00:00:00 2001 From: Sandy Huang Date: Tue, 14 Nov 2017 19:27:34 +0800 Subject: dt-bindings: add document for rk3126-vop Signed-off-by: Sandy Huang Acked-by: Rob Herring Link: https://patchwork.freedesktop.org/patch/msgid/1510658855-90223-1-git-send-email-hjc@rock-chips.com --- Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt index 5d835d9c1ba8..eeda3597011e 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt @@ -7,6 +7,7 @@ buffer to an external LCD interface. Required properties: - compatible: value should be one of the following "rockchip,rk3036-vop"; + "rockchip,rk3126-vop"; "rockchip,rk3288-vop"; "rockchip,rk3368-vop"; "rockchip,rk3366-vop"; -- cgit From a269574489d4fd4615562090b130cfc79309176e Mon Sep 17 00:00:00 2001 From: Sagar Arun Kamble Date: Thu, 16 Nov 2017 19:02:41 +0530 Subject: drm/i915/guc: Rename i915_guc_submission.c|h to intel_guc_submission.c|h With all component structures and functions named appropriately, change the names of GuC submission source files. There were bunch of style issues in guc_submission.c that are highlighted now by checkpatch. Fix those. Update name in Documentation/gpu. (Joonas) v2: Rebase. v3: Rebase. Signed-off-by: Sagar Arun Kamble Cc: Michal Wajdeczko Cc: Michal Winiarski Cc: Chris Wilson Cc: Joonas Lahtinen Acked-by: Chris Wilson Acked-by: Joonas Lahtinen Acked-by: Oscar Mateo Reviewed-by: Michal Wajdeczko Link: https://patchwork.freedesktop.org/patch/msgid/1510839162-25197-6-git-send-email-sagar.a.kamble@intel.com Signed-off-by: Chris Wilson --- Documentation/gpu/i915.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 2e7ee0313c1c..21577eabaf78 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -350,10 +350,10 @@ GuC-specific firmware loader GuC-based command submission ---------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c :doc: GuC-based command submission -.. kernel-doc:: drivers/gpu/drm/i915/i915_guc_submission.c +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c :internal: GuC Firmware Layout -- cgit From 870a0b12d0918c8e08d3895e4754a38da2a1850c Mon Sep 17 00:00:00 2001 From: Lukasz Majewski Date: Tue, 7 Nov 2017 16:30:58 +0100 Subject: drm/panel: simple: Add Tianma TM070RVHG71 panel support The Tianma TM070RVHG71 is a 7" WVGA (800x480) TFT LCD panel connected via LVDS and can be supported by the simple-panel binding. Signed-off-by: Lukasz Majewski Acked-by: Rob Herring Signed-off-by: Thierry Reding Link: https://patchwork.freedesktop.org/patch/msgid/20171107153058.5554-1-lukma@denx.de --- .../bindings/display/panel/tianma,tm070rvhg71.txt | 29 ++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt b/Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt new file mode 100644 index 000000000000..b25261e63a6d --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/tianma,tm070rvhg71.txt @@ -0,0 +1,29 @@ +Tianma Micro-electronics TM070RVHG71 7.0" WXGA TFT LCD panel + +Required properties: +- compatible: should be "tianma,tm070rvhg71" +- power-supply: single regulator to provide the supply voltage +- backlight: phandle of the backlight device attached to the panel + +Required nodes: +- port: LVDS port mapping to connect this display + +This panel needs single power supply voltage. Its backlight is conntrolled +via PWM signal. + +Example: +-------- + +Example device-tree definition when connected to iMX6Q based board + + panel: panel-lvds0 { + compatible = "tianma,tm070rvhg71"; + backlight = <&backlight_lvds>; + power-supply = <®_lvds>; + + port { + panel_in_lvds0: endpoint { + remote-endpoint = <&lvds0_out>; + }; + }; + }; -- cgit From 65c766cad8f81a65790580576a50abd21e3dea44 Mon Sep 17 00:00:00 2001 From: Lukasz Majewski Date: Sat, 21 Oct 2017 00:18:37 +0200 Subject: drm/panel: simple: Add Mitsubishi AA070MC01 panel support The Mitsubishi AA070MC01 is a 7.0" WVGA (800x480) TFT panel working in 8 bit ISP mode (pin 19 "mode" HIGH for 20 pin TFT connector). Signed-off-by: Lukasz Majewski Acked-by: Rob Herring Signed-off-by: Thierry Reding Link: https://patchwork.freedesktop.org/patch/msgid/1508537917-1723-1-git-send-email-lukma@denx.de --- .../devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 Documentation/devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt new file mode 100644 index 000000000000..7d8f6eeef6d9 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/mitsubishi,aa070mc01.txt @@ -0,0 +1,7 @@ +Mitsubishi "AA070MC01 7.0" WVGA TFT LCD panel + +Required properties: +- compatible: should be "mitsubishi,aa070mc01-ca1" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. -- cgit From 847989e548ee76f06fd51b61c1fb887d1e86a239 Mon Sep 17 00:00:00 2001 From: Rajat Jain Date: Tue, 3 Oct 2017 11:19:21 -0700 Subject: HID: i2c-hid: Allow ACPI systems to specify "post-power-on-delay-ms" The property "post-power-on-delay-ms" allows a platform to specify the delay needed after power-on, but only via device trees currently. Use device_property_* instead of of_* reads to allow ACPI systems to also provide the same information. This is useful for Wacom hardware on ACPI systems. Signed-off-by: Rajat Jain Signed-off-by: Jiri Kosina --- Documentation/devicetree/bindings/input/hid-over-i2c.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/input/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index 28e8bd8b7d64..4d3da9d91de4 100644 --- a/Documentation/devicetree/bindings/input/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt @@ -31,7 +31,7 @@ device-specific compatible properties, which should be used in addition to the - vdd-supply: phandle of the regulator that provides the supply voltage. - post-power-on-delay-ms: time required by the device after enabling its regulators - before it is ready for communication. Must be used with 'vdd-supply'. + or powering it on, before it is ready for communication. Example: -- cgit From c16292578ffa437c77e17d5d3da20330a10b8a86 Mon Sep 17 00:00:00 2001 From: Yixun Lan Date: Fri, 10 Nov 2017 16:46:49 +0800 Subject: dt-bindings: reset: Add bindings for the Meson-AXG SoC Reset Controller Add DT bindings for the Meson-AXG SoC Reset Controller include file, and also slightly update documentation. Signed-off-by: Yixun Lan Reviewed-by: Neil Armstrong Signed-off-by: Philipp Zabel --- Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt index e746b631793a..28ef6c295c76 100644 --- a/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt +++ b/Documentation/devicetree/bindings/reset/amlogic,meson-reset.txt @@ -5,7 +5,8 @@ Please also refer to reset.txt in this directory for common reset controller binding usage. Required properties: -- compatible: Should be "amlogic,meson8b-reset" or "amlogic,meson-gxbb-reset" +- compatible: Should be "amlogic,meson8b-reset", "amlogic,meson-gxbb-reset" or + "amlogic,meson-axg-reset". - reg: should contain the register address base - #reset-cells: 1, see below -- cgit From 0021ca8ef7cad34a8077073ec3aaf638117681f5 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 30 Oct 2017 18:29:57 +0100 Subject: ARM: shmobile: Document Renesas M3-W-based Salvator-XS board DT bindings The Renesas Salvator-XS (Salvator-X 2nd version) development board can be equipped with either an R-Car H3 ES2.0 or M3-W ES1.x SiP, which are pin-compatible. Document board part number and compatible values for the version with R-Car M3-W. Signed-off-by: Geert Uytterhoeven Acked-by: Rob Herring Signed-off-by: Simon Horman --- Documentation/devicetree/bindings/arm/shmobile.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index 020d758fc0c5..062520a0e74c 100644 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -104,6 +104,8 @@ Boards: compatible = "renesas,salvator-x", "renesas,r8a7796" - Salvator-XS (Salvator-X 2nd version, RTP0RC7795SIPB0012S) compatible = "renesas,salvator-xs", "renesas,r8a7795" + - Salvator-XS (Salvator-X 2nd version, RTP0RC7796SIPB0012S) + compatible = "renesas,salvator-xs", "renesas,r8a7796" - SILK (RTP0RC7794LCB00011S) compatible = "renesas,silk", "renesas,r8a7794" - SK-RZG1E (YR8A77450S000BE) -- cgit From 53e82bc779b1702a3b99c6eb02399726039aaaa8 Mon Sep 17 00:00:00 2001 From: Andreas Färber Date: Mon, 11 Sep 2017 00:36:53 +0200 Subject: dt-bindings: arm: actions: Add S700 and CubieBoard7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the Actions Semi S700 SoC and the Cubietech CubieBoard7. Acked-by: Rob Herring Signed-off-by: Andreas Färber --- Documentation/devicetree/bindings/arm/actions.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/actions.txt b/Documentation/devicetree/bindings/arm/actions.txt index ced764a8549e..544a8855fad5 100644 --- a/Documentation/devicetree/bindings/arm/actions.txt +++ b/Documentation/devicetree/bindings/arm/actions.txt @@ -25,6 +25,21 @@ Root node property compatible must contain, depending on board: - LeMaker Guitar Base Board rev. B: "lemaker,guitar-bb-rev-b", "lemaker,guitar" +S700 SoC +======== + +Required root node properties: + +- compatible : must contain "actions,s700" + + +Boards: + +Root node property compatible must contain, depending on board: + + - Cubietech CubieBoard7: "cubietech,cubieboard7" + + S900 SoC ======== -- cgit From afc7e586048c97ad26aac65f12df02f3c82f44e4 Mon Sep 17 00:00:00 2001 From: Andreas Färber Date: Sun, 10 Sep 2017 03:32:19 +0200 Subject: dt-bindings: power: Add Actions Semi S700 SPS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define power domains for Actions Semi S700 SoC Smart Power System (SPS). Acked-by: Rob Herring Signed-off-by: Andreas Färber --- Documentation/devicetree/bindings/power/actions,owl-sps.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/actions,owl-sps.txt b/Documentation/devicetree/bindings/power/actions,owl-sps.txt index 007b9a7ae723..78edd63641e8 100644 --- a/Documentation/devicetree/bindings/power/actions,owl-sps.txt +++ b/Documentation/devicetree/bindings/power/actions,owl-sps.txt @@ -2,10 +2,12 @@ Actions Semi Owl Smart Power System (SPS) Required properties: - compatible : "actions,s500-sps" for S500 + "actions,s700-sps" for S700 - reg : Offset and length of the register set for the device. - #power-domain-cells : Must be 1. See macros in: include/dt-bindings/power/owl-s500-powergate.h for S500 + include/dt-bindings/power/owl-s700-powergate.h for S700 Example: -- cgit From 91ca5c592f15c7390495abb6eb38327dc6b4563c Mon Sep 17 00:00:00 2001 From: Andreas Färber Date: Tue, 14 Nov 2017 01:07:37 +0100 Subject: dt-bindings: Add vendor prefix for Allo.com MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ALLO is a Canadian-Indian manufacturer of telecommunications hardware. Cc: Ioan B. Acked-by: Rob Herring Acked-by: Sudeep Kumar Signed-off-by: Andreas Färber --- Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 0994bdd82cd3..9bce76f3118d 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -15,6 +15,7 @@ adi Analog Devices, Inc. advantech Advantech Corporation aeroflexgaisler Aeroflex Gaisler AB al Annapurna Labs +allo Allo.com allwinner Allwinner Technology Co., Ltd. alphascale AlphaScale Integrated Circuits Systems, Inc. altr Altera Corp. -- cgit From 86628db248d225fc829e23370d4fa2050dfb57f1 Mon Sep 17 00:00:00 2001 From: Andreas Färber Date: Tue, 14 Nov 2017 00:53:40 +0100 Subject: dt-bindings: arm: actions: Add Sparky MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define a binding for Allo.com Sparky SBC. Cc: Ioan B. Acked-by: Rob Herring Acked-by: Sudeep Kumar Signed-off-by: Andreas Färber --- Documentation/devicetree/bindings/arm/actions.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/actions.txt b/Documentation/devicetree/bindings/arm/actions.txt index ced764a8549e..1eab59c1f034 100644 --- a/Documentation/devicetree/bindings/arm/actions.txt +++ b/Documentation/devicetree/bindings/arm/actions.txt @@ -21,6 +21,7 @@ Boards: Root node property compatible must contain, depending on board: + - Allo.com Sparky: "allo,sparky" - Cubietech CubieBoard6: "cubietech,cubieboard6" - LeMaker Guitar Base Board rev. B: "lemaker,guitar-bb-rev-b", "lemaker,guitar" -- cgit From e96bd3970894758087f934860aa1c7c076a1e76c Mon Sep 17 00:00:00 2001 From: Johan Hovold Date: Thu, 9 Nov 2017 18:07:20 +0100 Subject: dt-bindings: usb: add interface binding Add a new binding for USB interface nodes, which are child nodes of USB device nodes and addressed by interface number and configuration value tuples. Also add a new binding for USB combined nodes, which are special case nodes for simple USB devices for which they replace the device and interface nodes. For completeness, define the already used terms "host-controller node", "device node" and "hub node". Signed-off-by: Johan Hovold Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/usb/usb-device.txt | 68 +++++++++++++++++++++- 1 file changed, 66 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/usb-device.txt b/Documentation/devicetree/bindings/usb/usb-device.txt index 1b27cebb47f4..036be172b1ae 100644 --- a/Documentation/devicetree/bindings/usb/usb-device.txt +++ b/Documentation/devicetree/bindings/usb/usb-device.txt @@ -4,8 +4,49 @@ Usually, we only use device tree for hard wired USB device. The reference binding doc is from: http://www.devicetree.org/open-firmware/bindings/usb/usb-1_0.ps +Four types of device-tree nodes are defined: "host-controller nodes" +representing USB host controllers, "device nodes" representing USB devices, +"interface nodes" representing USB interfaces and "combined nodes" +representing simple USB devices. -Required properties: +A combined node shall be used instead of a device node and an interface node +for devices of class 0 or 9 (hub) with a single configuration and a single +interface. + +A "hub node" is a combined node or an interface node that represents a USB +hub. + + +Required properties for device nodes: +- compatible: "usbVID,PID", where VID is the vendor id and PID the product id. + The textual representation of VID and PID shall be in lower case hexadecimal + with leading zeroes suppressed. The other compatible strings from the above + standard binding could also be used, but a device adhering to this binding + may leave out all except for "usbVID,PID". +- reg: the number of the USB hub port or the USB host-controller port to which + this device is attached. The range is 1-255. + + +Required properties for device nodes with interface nodes: +- #address-cells: shall be 2 +- #size-cells: shall be 0 + + +Required properties for interface nodes: +- compatible: "usbifVID,PID.configCN.IN", where VID is the vendor id, PID is + the product id, CN is the configuration value and IN is the interface + number. The textual representation of VID, PID, CN and IN shall be in lower + case hexadecimal with leading zeroes suppressed. The other compatible + strings from the above standard binding could also be used, but a device + adhering to this binding may leave out all except for + "usbifVID,PID.configCN.IN". +- reg: the interface number and configuration value + +The configuration component is not included in the textual representation of +an interface-node unit address for configuration 1. + + +Required properties for combined nodes: - compatible: "usbVID,PID", where VID is the vendor id and PID the product id. The textual representation of VID and PID shall be in lower case hexadecimal with leading zeroes suppressed. The other compatible strings from the above @@ -31,8 +72,31 @@ Example: #address-cells = <1>; #size-cells = <0>; - hub@1 { /* hub connected to port 1 */ + hub@1 { /* hub connected to port 1 */ compatible = "usb5e3,608"; reg = <1>; }; + + device@2 { /* device connected to port 2 */ + compatible = "usb123,4567"; + reg = <2>; + }; + + device@3 { /* device connected to port 3 */ + compatible = "usb123,abcd"; + reg = <3>; + + #address-cells = <2>; + #size-cells = <0>; + + interface@0 { /* interface 0 of configuration 1 */ + compatible = "usbif123,abcd.config1.0"; + reg = <0 1>; + }; + + interface@0,2 { /* interface 0 of configuration 2 */ + compatible = "usbif123,abcd.config2.0"; + reg = <0 2>; + }; + }; }; -- cgit From bcfab39df88e31992371818eb8753f4b2b94ca80 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Wed, 8 Nov 2017 14:03:25 -0200 Subject: dt-bindings: serial: fsl-imx-uart: Remove 'fsl,irda-mode' property 'fsl,irda-mode' property has been removed since commit afe9cbb1a6ad ("serial: imx: drop support for IRDA"), so remove it from the binding document. Signed-off-by: Fabio Estevam Acked-by: Rob Herring Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/serial/fsl-imx-uart.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt index 860a9559839a..6b789f2ee879 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt @@ -6,7 +6,6 @@ Required properties: - interrupts : Should contain uart interrupt Optional properties: -- fsl,irda-mode : Indicate the uart supports irda mode - fsl,dte-mode : Indicate the uart works in DTE mode. The uart works in DCE mode by default. - rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt -- cgit From 525ba62c96abec9130b8edb877d1128864cee01c Mon Sep 17 00:00:00 2001 From: Andrey Smirnov Date: Thu, 9 Nov 2017 08:05:53 -0800 Subject: serdev: Introduce devm_serdev_device_open() Add code implementing managed version of serdev_device_open() for serdev device drivers that "open" the device during driver's lifecycle only once (e.g. opened in .probe() and closed in .remove()). Cc: linux-kernel@vger.kernel.org Cc: linux-serial@vger.kernel.org Cc: Rob Herring Cc: cphealy@gmail.com Cc: Guenter Roeck Cc: Lucas Stach Cc: Nikita Yushchenko Cc: Lee Jones Cc: Greg Kroah-Hartman Cc: Pavel Machek Cc: Andy Shevchenko Cc: Johan Hovold Cc: Sebastian Reichel Acked-by: Rob Herring Reviewed-by: Sebastian Reichel Reviewed-by: Guenter Roeck Signed-off-by: Andrey Smirnov Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-model/devres.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index c180045eb43b..7c1bb3d0c222 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -384,6 +384,9 @@ RESET devm_reset_control_get() devm_reset_controller_register() +SERDEV + devm_serdev_device_open() + SLAVE DMA ENGINE devm_acpi_dma_controller_register() -- cgit From 6abe9ea8a5a5904d935b8a482117a7fd9b25f09e Mon Sep 17 00:00:00 2001 From: Lukas Wunner Date: Fri, 24 Nov 2017 23:26:40 +0100 Subject: dt-bindings: serial: Add common rs485 binding for RTS polarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit rs485 allows for robust half-duplex serial communication. It is often implemented by attaching an rs485 transceiver to a UART. The UART's RTS line is wired to the transceiver's Transmit Enable pin and determines whether the transceiver is sending or receiving. Examples for such transceivers are Maxim MAX13451E and TI SN65HVD1781A: https://datasheets.maximintegrated.com/en/ds/MAX13450E-MAX13451E.pdf http://www.ti.com/lit/ds/symlink/sn65hvd1781a-q1.pdf In the devicetree, the transceiver itself is not represented, only the UART is. A few rs485-specific dt-bindings already exist and these go into the UART's device node. This commit adds a binding to set the RTS polarity. Most (if not all) transceivers require the Transmit Enable pin be driven high for sending, but in some cases boards may negate the pin and RTS must then be driven low. Consequently the polarity defaults to active high but can be inverted with the newly added "rs485-rts-active-low" binding. Document this binding in rs485.txt and in the two drivers fsl-imx-uart and fsl-lpuart that are about to be amended with support for it. Curiously, the omap_serial driver defaults to active low and already supports an "rs485-rts-active-high" binding to invert the polarity. This is left unchanged to retain compatibility, but the binding is herewith documented. Cc: Mark Jackson Cc: Michał Oleszczyk Cc: Rafael Gago Castano Cc: Sascha Hauer Acked-by: Rob Herring Signed-off-by: Lukas Wunner Acked-by: Uwe Kleine-König Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/serial/fsl-imx-uart.txt | 3 ++- Documentation/devicetree/bindings/serial/fsl-lpuart.txt | 3 ++- Documentation/devicetree/bindings/serial/omap_serial.txt | 1 + Documentation/devicetree/bindings/serial/rs485.txt | 1 + 4 files changed, 6 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt index 6b789f2ee879..afcfbc34e243 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt @@ -8,7 +8,8 @@ Required properties: Optional properties: - fsl,dte-mode : Indicate the uart works in DTE mode. The uart works in DCE mode by default. -- rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt +- rs485-rts-delay, rs485-rts-active-low, rs485-rx-during-tx, + linux,rs485-enabled-at-boot-time: see rs485.txt Please check Documentation/devicetree/bindings/serial/serial.txt for the complete list of generic properties. diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt index 59567b51cf09..6bd3f2e93d61 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt @@ -16,7 +16,8 @@ Required properties: Optional properties: - dmas: A list of two dma specifiers, one for each entry in dma-names. - dma-names: should contain "tx" and "rx". -- rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt +- rs485-rts-delay, rs485-rts-active-low, rs485-rx-during-tx, + linux,rs485-enabled-at-boot-time: see rs485.txt Note: Optional properties for DMA support. Write them both or both not. diff --git a/Documentation/devicetree/bindings/serial/omap_serial.txt b/Documentation/devicetree/bindings/serial/omap_serial.txt index 43eac675f21f..4b0f05adb228 100644 --- a/Documentation/devicetree/bindings/serial/omap_serial.txt +++ b/Documentation/devicetree/bindings/serial/omap_serial.txt @@ -20,6 +20,7 @@ Optional properties: node and a DMA channel number. - dma-names : "rx" for receive channel, "tx" for transmit channel. - rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt +- rs485-rts-active-high: drive RTS high when sending (default is low). Example: diff --git a/Documentation/devicetree/bindings/serial/rs485.txt b/Documentation/devicetree/bindings/serial/rs485.txt index b8415936dfdb..b7c29f74ebb2 100644 --- a/Documentation/devicetree/bindings/serial/rs485.txt +++ b/Documentation/devicetree/bindings/serial/rs485.txt @@ -12,6 +12,7 @@ Optional properties: * b is the delay between end of data sent and rts signal in milliseconds it corresponds to the delay after sending data and actual release of the line. If this property is not specified, <0 0> is assumed. +- rs485-rts-active-low: drive RTS low when sending (default is high). - linux,rs485-enabled-at-boot-time: empty property telling to enable the rs485 feature at boot time. It can be disabled later with proper ioctl. - rs485-rx-during-tx: empty property that enables the receiving of data even -- cgit From 5cf0c7f6502f26332b46fa87914553a4d6ae75ac Mon Sep 17 00:00:00 2001 From: Alan Tull Date: Wed, 15 Nov 2017 14:20:12 -0600 Subject: fpga: mgr: API change to replace fpga load functions with single function fpga-mgr has three methods for programming FPGAs, depending on whether the image is in a scatter gather list, a contiguous buffer, or a firmware file. This makes it difficult to write upper layers as the caller has to assume whether the FPGA image is in a sg table, as a single buffer, or a firmware file. This commit moves these parameters to struct fpga_image_info and adds a single function for programming fpgas. New functions: * fpga_mgr_load - given fpga manager and struct fpga_image_info, program the fpga. * fpga_image_info_alloc - alloc a struct fpga_image_info. * fpga_image_info_free - free a struct fpga_image_info. These three functions are unexported: * fpga_mgr_buf_load_sg * fpga_mgr_buf_load * fpga_mgr_firmware_load Also use devm_kstrdup to copy firmware_name so we aren't making assumptions about where it comes from when allocing/freeing the struct fpga_image_info. API documentation has been updated and a new document for FPGA region has been added. Signed-off-by: Alan Tull Acked-by: Moritz Fischer Signed-off-by: Greg Kroah-Hartman --- Documentation/fpga/fpga-mgr.txt | 119 ++++++++++++++++--------------------- Documentation/fpga/fpga-region.txt | 95 +++++++++++++++++++++++++++++ Documentation/fpga/overview.txt | 23 +++++++ 3 files changed, 169 insertions(+), 68 deletions(-) create mode 100644 Documentation/fpga/fpga-region.txt create mode 100644 Documentation/fpga/overview.txt (limited to 'Documentation') diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt index 78f197fadfd1..6ebc714f4b03 100644 --- a/Documentation/fpga/fpga-mgr.txt +++ b/Documentation/fpga/fpga-mgr.txt @@ -11,61 +11,53 @@ hidden away in a low level driver which registers a set of ops with the core. The FPGA image data itself is very manufacturer specific, but for our purposes it's just binary data. The FPGA manager core won't parse it. +The FPGA image to be programmed can be in a scatter gather list, a single +contiguous buffer, or a firmware file. Because allocating contiguous kernel +memory for the buffer should be avoided, users are encouraged to use a scatter +gather list instead if possible. + +The particulars for programming the image are presented in a structure (struct +fpga_image_info). This struct contains parameters such as pointers to the +FPGA image as well as image-specific particulars such as whether the image was +built for full or partial reconfiguration. API Functions: ============== -To program the FPGA from a file or from a buffer: -------------------------------------------------- - - int fpga_mgr_buf_load(struct fpga_manager *mgr, - struct fpga_image_info *info, - const char *buf, size_t count); - -Load the FPGA from an image which exists as a contiguous buffer in -memory. Allocating contiguous kernel memory for the buffer should be avoided, -users are encouraged to use the _sg interface instead of this. - - int fpga_mgr_buf_load_sg(struct fpga_manager *mgr, - struct fpga_image_info *info, - struct sg_table *sgt); +To program the FPGA: +-------------------- -Load the FPGA from an image from non-contiguous in memory. Callers can -construct a sg_table using alloc_page backed memory. + int fpga_mgr_load(struct fpga_manager *mgr, + struct fpga_image_info *info); - int fpga_mgr_firmware_load(struct fpga_manager *mgr, - struct fpga_image_info *info, - const char *image_name); - -Load the FPGA from an image which exists as a file. The image file must be on -the firmware search path (see the firmware class documentation). If successful, +Load the FPGA from an image which is indicated in the info. If successful, the FPGA ends up in operating mode. Return 0 on success or a negative error code. -A FPGA design contained in a FPGA image file will likely have particulars that -affect how the image is programmed to the FPGA. These are contained in struct -fpga_image_info. Currently the only such particular is a single flag bit -indicating whether the image is for full or partial reconfiguration. +To allocate or free a struct fpga_image_info: +--------------------------------------------- + + struct fpga_image_info *fpga_image_info_alloc(struct device *dev); + + void fpga_image_info_free(struct fpga_image_info *info); To get/put a reference to a FPGA manager: ----------------------------------------- struct fpga_manager *of_fpga_mgr_get(struct device_node *node); struct fpga_manager *fpga_mgr_get(struct device *dev); - -Given a DT node or device, get an exclusive reference to a FPGA manager. - void fpga_mgr_put(struct fpga_manager *mgr); -Release the reference. +Given a DT node or device, get an exclusive reference to a FPGA manager. +fpga_mgr_put releases the reference. To register or unregister the low level FPGA-specific driver: ------------------------------------------------------------- int fpga_mgr_register(struct device *dev, const char *name, - const struct fpga_manager_ops *mops, - void *priv); + const struct fpga_manager_ops *mops, + void *priv); void fpga_mgr_unregister(struct device *dev); @@ -78,59 +70,50 @@ How to write an image buffer to a supported FPGA /* Include to get the API */ #include -/* device node that specifies the FPGA manager to use */ -struct device_node *mgr_node = ... - -/* FPGA image is in this buffer. count is size of the buffer. */ -char *buf = ... -int count = ... +struct fpga_manager *mgr; +struct fpga_image_info *info; +int ret; /* struct with information about the FPGA image to program. */ -struct fpga_image_info info; +info = fpga_image_info_alloc(dev); /* flags indicates whether to do full or partial reconfiguration */ -info.flags = 0; - -int ret; +info->flags = FPGA_MGR_PARTIAL_RECONFIG; -/* Get exclusive control of FPGA manager */ -struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); +/* + * At this point, indicate where the image is. This is pseudo-code; you're + * going to use one of these three. + */ +if (image is in a scatter gather table) { -/* Load the buffer to the FPGA */ -ret = fpga_mgr_buf_load(mgr, &info, buf, count); - -/* Release the FPGA manager */ -fpga_mgr_put(mgr); + info->sgt = [your scatter gather table] +} else if (image is in a buffer) { -How to write an image file to a supported FPGA -============================================== -/* Include to get the API */ -#include + info->buf = [your image buffer] + info->count = [image buffer size] -/* device node that specifies the FPGA manager to use */ -struct device_node *mgr_node = ... +} else if (image is in a firmware file) { -/* FPGA image is in this file which is in the firmware search path */ -const char *path = "fpga-image-9.rbf" + info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL); -/* struct with information about the FPGA image to program. */ -struct fpga_image_info info; - -/* flags indicates whether to do full or partial reconfiguration */ -info.flags = 0; - -int ret; +} -/* Get exclusive control of FPGA manager */ -struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); +/* + * Get a reference to FPGA manager. This example uses the device node of the + * manager. You could use fpga_mgr_get() instead if you have the device instead + * of the device node. + */ +mgr = of_fpga_mgr_get(mgr_node); -/* Get the firmware image (path) and load it to the FPGA */ -ret = fpga_mgr_firmware_load(mgr, &info, path); +/* Load the buffer to the FPGA */ +ret = fpga_mgr_buf_load(mgr, &info, buf, count); /* Release the FPGA manager */ fpga_mgr_put(mgr); +/* Deallocate the image info if you're done with it */ +fpga_image_info_free(info); How to support a new FPGA device ================================ diff --git a/Documentation/fpga/fpga-region.txt b/Documentation/fpga/fpga-region.txt new file mode 100644 index 000000000000..139a02ba1ff6 --- /dev/null +++ b/Documentation/fpga/fpga-region.txt @@ -0,0 +1,95 @@ +FPGA Regions + +Alan Tull 2017 + +CONTENTS + - Introduction + - The FPGA region API + - Usage example + +Introduction +============ + +This document is meant to be an brief overview of the FPGA region API usage. A +more conceptual look at regions can be found in [1]. + +For the purposes of this API document, let's just say that a region associates +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an +FPGA or the whole FPGA. The API provides a way to register a region and to +program a region. + +Currently the only layer above fpga-region.c in the kernel is the Device Tree +support (of-fpga-region.c) described in [1]. The DT support layer uses regions +to program the FPGA and then DT to handle enumeration. The common region code +is intended to be used by other schemes that have other ways of accomplishing +enumeration after programming. + +An fpga-region can be set up to know the following things: +* which FPGA manager to use to do the programming +* which bridges to disable before programming and enable afterwards. + +Additional info needed to program the FPGA image is passed in the struct +fpga_image_info [2] including: +* pointers to the image as either a scatter-gather buffer, a contiguous + buffer, or the name of firmware file +* flags indicating specifics such as whether the image if for partial + reconfiguration. + +=================== +The FPGA region API +=================== + +To register or unregister a region: +----------------------------------- + + int fpga_region_register(struct device *dev, + struct fpga_region *region); + int fpga_region_unregister(struct fpga_region *region); + +An example of usage can be seen in the probe function of [3] + +To program an FPGA: +------------------- + int fpga_region_program_fpga(struct fpga_region *region); + +This function operates on info passed in the fpga_image_info +(region->info). + +This function will attempt to: + * lock the region's mutex + * lock the region's FPGA manager + * build a list of FPGA bridges if a method has been specified to do so + * disable the bridges + * program the FPGA + * re-enable the bridges + * release the locks + +============= +Usage example +============= + +First, allocate the info struct: + + info = fpga_image_info_alloc(dev); + if (!info) + return -ENOMEM; + +Set flags as needed, i.e. + + info->flags |= FPGA_MGR_PARTIAL_RECONFIG; + +Point to your FPGA image, such as: + + info->sgt = &sgt; + +Add info to region and do the programming: + + region->info = info; + ret = fpga_region_program_fpga(region); + +Then enumerate whatever hardware has appeared in the FPGA. + +-- +[1] ../devicetree/bindings/fpga/fpga-region.txt +[2] ./fpga-mgr.txt +[3] ../../drivers/fpga/of-fpga-region.c diff --git a/Documentation/fpga/overview.txt b/Documentation/fpga/overview.txt new file mode 100644 index 000000000000..0f1236e7e675 --- /dev/null +++ b/Documentation/fpga/overview.txt @@ -0,0 +1,23 @@ +Linux kernel FPGA support + +Alan Tull 2017 + +The main point of this project has been to separate the out the upper layers +that know when to reprogram a FPGA from the lower layers that know how to +reprogram a specific FPGA device. The intention is to make this manufacturer +agnostic, understanding that of course the FPGA images are very device specific +themselves. + +The framework in the kernel includes: +* low level FPGA manager drivers that know how to program a specific device +* the fpga-mgr framework they are registered with +* low level FPGA bridge drivers for hard/soft bridges which are intended to + be disable during FPGA programming +* the fpga-bridge framework they are registered with +* the fpga-region framework which associates and controls managers and bridges + as reconfigurable regions +* the of-fpga-region support for reprogramming FPGAs when device tree overlays + are applied. + +I would encourage you the user to add code that creates FPGA regions rather +that trying to control managers and bridges separately. -- cgit From ebf877a51ad7b65e4ab024f021b60a4f7928864a Mon Sep 17 00:00:00 2001 From: Alan Tull Date: Wed, 15 Nov 2017 14:20:13 -0600 Subject: fpga: mgr: separate getting/locking FPGA manager Previously when the user gets a FPGA manager, it was locked and nobody else could use it for programming. This commit makes it straightforward to save a reference to an FPGA manager and only lock it when programming the FPGA. Add functions that get an FPGA manager's mutex for exclusive use: * fpga_mgr_lock * fpga_mgr_unlock The following functions no longer lock an FPGA manager's mutex: * of_fpga_mgr_get * fpga_mgr_get * fpga_mgr_put Signed-off-by: Alan Tull Acked-by: Moritz Fischer Signed-off-by: Greg Kroah-Hartman --- Documentation/fpga/fpga-mgr.txt | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt index 6ebc714f4b03..cc6413ed6fc9 100644 --- a/Documentation/fpga/fpga-mgr.txt +++ b/Documentation/fpga/fpga-mgr.txt @@ -48,8 +48,20 @@ To get/put a reference to a FPGA manager: struct fpga_manager *fpga_mgr_get(struct device *dev); void fpga_mgr_put(struct fpga_manager *mgr); -Given a DT node or device, get an exclusive reference to a FPGA manager. -fpga_mgr_put releases the reference. +Given a DT node or device, get a reference to a FPGA manager. This pointer +can be saved until you are ready to program the FPGA. fpga_mgr_put releases +the reference. + + +To get exclusive control of a FPGA manager: +------------------------------------------- + + int fpga_mgr_lock(struct fpga_manager *mgr); + void fpga_mgr_unlock(struct fpga_manager *mgr); + +The user should call fpga_mgr_lock and verify that it returns 0 before +attempting to program the FPGA. Likewise, the user should call +fpga_mgr_unlock when done programming the FPGA. To register or unregister the low level FPGA-specific driver: @@ -67,13 +79,21 @@ device." How to write an image buffer to a supported FPGA ================================================ -/* Include to get the API */ #include struct fpga_manager *mgr; struct fpga_image_info *info; int ret; +/* + * Get a reference to FPGA manager. The manager is not locked, so you can + * hold onto this reference without it preventing programming. + * + * This example uses the device node of the manager. Alternatively, use + * fpga_mgr_get(dev) instead if you have the device. + */ +mgr = of_fpga_mgr_get(mgr_node); + /* struct with information about the FPGA image to program. */ info = fpga_image_info_alloc(dev); @@ -99,17 +119,14 @@ if (image is in a scatter gather table) { } -/* - * Get a reference to FPGA manager. This example uses the device node of the - * manager. You could use fpga_mgr_get() instead if you have the device instead - * of the device node. - */ -mgr = of_fpga_mgr_get(mgr_node); +/* Get exclusive control of FPGA manager */ +ret = fpga_mgr_lock(mgr); /* Load the buffer to the FPGA */ ret = fpga_mgr_buf_load(mgr, &info, buf, count); /* Release the FPGA manager */ +fpga_mgr_unlock(mgr); fpga_mgr_put(mgr); /* Deallocate the image info if you're done with it */ -- cgit From f82f59cf665562aa1ce6097827d958382724dce4 Mon Sep 17 00:00:00 2001 From: Fabien DESSENNE Date: Thu, 19 Oct 2017 17:10:29 +0200 Subject: dt-bindings: Document STM32 CRYP bindings Document device tree bindings for the STM32 CRYP. Signed-off-by: Fabien Dessenne Acked-by: Rob Herring Signed-off-by: Herbert Xu --- .../devicetree/bindings/crypto/st,stm32-cryp.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt new file mode 100644 index 000000000000..970487fa40b8 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/st,stm32-cryp.txt @@ -0,0 +1,19 @@ +* STMicroelectronics STM32 CRYP + +Required properties: +- compatible: Should be "st,stm32f756-cryp". +- reg: The address and length of the peripheral registers space +- clocks: The input clock of the CRYP instance +- interrupts: The CRYP interrupt + +Optional properties: +- resets: The input reset of the CRYP instance + +Example: +crypto@50060000 { + compatible = "st,stm32f756-cryp"; + reg = <0x50060000 0x400>; + interrupts = <79>; + clocks = <&rcc 0 STM32F7_AHB2_CLOCK(CRYP)>; + resets = <&rcc STM32F7_AHB2_RESET(CRYP)>; +}; -- cgit From 67fe2fa8cfb2deed0ec5f072a163083e36eaa0b1 Mon Sep 17 00:00:00 2001 From: Florian Fainelli Date: Tue, 7 Nov 2017 16:44:47 -0800 Subject: dt-bindings: rng: Incorporate brcm,bcm6368.txt binding Since the same block is used on BCM2835 and BCM6368, merge the bindings and remove the brcm,bcm6368.txt binding document. Acked-by: Rob Herring Signed-off-by: Florian Fainelli Signed-off-by: Herbert Xu --- .../devicetree/bindings/rng/brcm,bcm2835.txt | 22 +++++++++++++++++++--- .../devicetree/bindings/rng/brcm,bcm6368.txt | 17 ----------------- 2 files changed, 19 insertions(+), 20 deletions(-) delete mode 100644 Documentation/devicetree/bindings/rng/brcm,bcm6368.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt b/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt index 26542690b578..627b29531a32 100644 --- a/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt +++ b/Documentation/devicetree/bindings/rng/brcm,bcm2835.txt @@ -1,11 +1,19 @@ -BCM2835 Random number generator +BCM2835/6368 Random number generator Required properties: -- compatible : should be "brcm,bcm2835-rng" or "brcm,bcm-nsp-rng" or - "brcm,bcm5301x-rng" +- compatible : should be one of + "brcm,bcm2835-rng" + "brcm,bcm-nsp-rng" + "brcm,bcm5301x-rng" or + "brcm,bcm6368-rng" - reg : Specifies base physical address and size of the registers. +Optional properties: + +- clocks : phandle to clock-controller plus clock-specifier pair +- clock-names : "ipsec" as a clock name + Example: rng { @@ -17,3 +25,11 @@ rng@18033000 { compatible = "brcm,bcm-nsp-rng"; reg = <0x18033000 0x14>; }; + +random: rng@10004180 { + compatible = "brcm,bcm6368-rng"; + reg = <0x10004180 0x14>; + + clocks = <&periph_clk 18>; + clock-names = "ipsec"; +}; diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt b/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt deleted file mode 100644 index 4b5ac600bfbd..000000000000 --- a/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt +++ /dev/null @@ -1,17 +0,0 @@ -BCM6368 Random number generator - -Required properties: - -- compatible : should be "brcm,bcm6368-rng" -- reg : Specifies base physical address and size of the registers -- clocks : phandle to clock-controller plus clock-specifier pair -- clock-names : "ipsec" as a clock name - -Example: - random: rng@10004180 { - compatible = "brcm,bcm6368-rng"; - reg = <0x10004180 0x14>; - - clocks = <&periph_clk 18>; - clock-names = "ipsec"; - }; -- cgit From 23eb61d304f9a6a6ec507ee27dd2b6c631c26c14 Mon Sep 17 00:00:00 2001 From: Gilad Ben-Yossef Date: Thu, 16 Nov 2017 06:15:28 +0000 Subject: dt-bindings: add device tree binding for Arm TrustZone CryptoCell crypto engine The Arm TrustZone CryptoCell is a hardware security engine. This patch adds DT bindings for its Rich Execution Environment crypto engine. A driver supporting this device is already present in the staging tree. Signed-off-by: Gilad Ben-Yossef Acked-by: Rob Herring Signed-off-by: Herbert Xu --- .../devicetree/bindings/crypto/arm-cryptocell.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 Documentation/devicetree/bindings/crypto/arm-cryptocell.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt new file mode 100644 index 000000000000..cec8d5d74e26 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt @@ -0,0 +1,22 @@ +Arm TrustZone CryptoCell cryptographic engine + +Required properties: +- compatible: Should be "arm,cryptocell-712-ree". +- reg: Base physical address of the engine and length of memory mapped region. +- interrupts: Interrupt number for the device. + +Optional properties: +- interrupt-parent: The phandle for the interrupt controller that services + interrupts for this device. +- clocks: Reference to the crypto engine clock. +- dma-coherent: Present if dma operations are coherent. + +Examples: + + arm_cc712: crypto@80000000 { + compatible = "arm,cryptocell-712-ree"; + interrupt-parent = <&intc>; + interrupts = < 0 30 4 >; + reg = < 0x80000000 0x10000 >; + + }; -- cgit From eebd0732136fd293c8f15a435978c1c34cd7f32f Mon Sep 17 00:00:00 2001 From: Sergei Shtylyov Date: Fri, 24 Nov 2017 23:47:39 +0300 Subject: arm64: renesas: document V3MSK board bindings Document the V3M Starter Kit device tree bindings, listing it as a supported board. This allows to use checkpatch.pl to validate .dts files referring to the V3MSK board. Signed-off-by: Sergei Shtylyov Acked-by: Rob Herring Signed-off-by: Simon Horman --- Documentation/devicetree/bindings/arm/shmobile.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index 062520a0e74c..5c3af7ef0761 100644 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -112,6 +112,8 @@ Boards: compatible = "renesas,sk-rzg1e", "renesas,r8a7745" - SK-RZG1M (YR8A77430S000BE) compatible = "renesas,sk-rzg1m", "renesas,r8a7743" + - V3MSK + compatible = "renesas,v3msk", "renesas,r8a77970" - Wheat compatible = "renesas,wheat", "renesas,r8a7792" -- cgit From 5c7f2accdb818564a069cc61db8e3e1ba7ff4938 Mon Sep 17 00:00:00 2001 From: Jian-Hong Pan Date: Sat, 18 Nov 2017 23:55:01 +0800 Subject: doc: linux-wpan: Fulfill the description of missed 802.15.4 APIs There are more functions and operations which must be used or implemented in each IEEE 802.15.4 device driver, but are not mentioned in the Device drivers API section of Documentation/networking/ieee802154.txt. Therefore, I want to fulfill the missed part into the documentation with this patch. Signed-off-by: Jian-Hong Pan Acked-by: Alexander Aring Signed-off-by: Stefan Schmidt --- Documentation/networking/ieee802154.txt | 40 +++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt index 057e9fdbfac9..e74d8e1da0e2 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.txt @@ -97,6 +97,46 @@ The include/net/mac802154.h defines following functions: - void ieee802154_unregister_hw(struct ieee802154_hw *hw): freeing registered PHY + - void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, + u8 lqi): + telling 802.15.4 module there is a new received frame in the skb with + the RF Link Quality Indicator (LQI) from the hardware device + + - void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, + bool ifs_handling): + telling 802.15.4 module the frame in the skb is or going to be + transmitted through the hardware device + +The device driver must implement the following callbacks in the IEEE 802.15.4 +operations structure at least: +struct ieee802154_ops { + ... + int (*start)(struct ieee802154_hw *hw); + void (*stop)(struct ieee802154_hw *hw); + ... + int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); + int (*ed)(struct ieee802154_hw *hw, u8 *level); + int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); + ... +}; + + - int start(struct ieee802154_hw *hw): + handler that 802.15.4 module calls for the hardware device initialization. + + - void stop(struct ieee802154_hw *hw): + handler that 802.15.4 module calls for the hardware device cleanup. + + - int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): + handler that 802.15.4 module calls for each frame in the skb going to be + transmitted through the hardware device. + + - int ed(struct ieee802154_hw *hw, u8 *level): + handler that 802.15.4 module calls for Energy Detection from the hardware + device. + + - int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): + set radio for listening on specific channel of the hardware device. + Moreover IEEE 802.15.4 device operations structure should be filled. Fake drivers -- cgit From 44fde7bbcc100ab4d37e74f219e8c17fc906fab7 Mon Sep 17 00:00:00 2001 From: Michael Hennerich Date: Tue, 28 Nov 2017 13:53:11 +0100 Subject: net: ieee802154: adf7242: Add support for ADF7241 devices This adds support for ADF7241 Low Power IEEE 802.15.4 Zero-IF 2.4 GHz Transceivers Signed-off-by: Michael Hennerich Signed-off-by: Stefan Schmidt --- Documentation/devicetree/bindings/net/ieee802154/adf7242.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt b/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt index dea5124cdc52..d24172cc6d32 100644 --- a/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt +++ b/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt @@ -1,7 +1,7 @@ * ADF7242 IEEE 802.15.4 * Required properties: - - compatible: should be "adi,adf7242" + - compatible: should be "adi,adf7242", "adi,adf7241" - spi-max-frequency: maximal bus speed (12.5 MHz) - reg: the chipselect index - interrupts: the interrupt generated by the device via pin IRQ1. -- cgit From 5c0bb261d26189e1d7ece001b0accc7e14e6b20c Mon Sep 17 00:00:00 2001 From: Shannon Nelson Date: Mon, 20 Nov 2017 14:26:07 -0800 Subject: xfrm: add documentation for xfrm device offload api Add a writeup on how to use the XFRM device offload API, and mention this new file in the index. Signed-off-by: Shannon Nelson Signed-off-by: Steffen Klassert --- Documentation/networking/00-INDEX | 2 + Documentation/networking/xfrm_device.txt | 132 +++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 Documentation/networking/xfrm_device.txt (limited to 'Documentation') diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index 7a79b3587dd3..f5d642c01dd3 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -228,6 +228,8 @@ x25.txt - general info on X.25 development. x25-iface.txt - description of the X.25 Packet Layer to LAPB device interface. +xfrm_device.txt + - description of XFRM offload API xfrm_proc.txt - description of the statistics package for XFRM. xfrm_sync.txt diff --git a/Documentation/networking/xfrm_device.txt b/Documentation/networking/xfrm_device.txt new file mode 100644 index 000000000000..2d9d588cd34b --- /dev/null +++ b/Documentation/networking/xfrm_device.txt @@ -0,0 +1,132 @@ + +=============================================== +XFRM device - offloading the IPsec computations +=============================================== +Shannon Nelson + + +Overview +======== + +IPsec is a useful feature for securing network traffic, but the +computational cost is high: a 10Gbps link can easily be brought down +to under 1Gbps, depending on the traffic and link configuration. +Luckily, there are NICs that offer a hardware based IPsec offload which +can radically increase throughput and decrease CPU utilization. The XFRM +Device interface allows NIC drivers to offer to the stack access to the +hardware offload. + +Userland access to the offload is typically through a system such as +libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can +be handy when experimenting. An example command might look something +like this: + + ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ + reqid 0x07 replay-window 32 \ + aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \ + sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ + offload dev eth4 dir in + +Yes, that's ugly, but that's what shell scripts and/or libreswan are for. + + + +Callbacks to implement +====================== + +/* from include/linux/netdevice.h */ +struct xfrmdev_ops { + int (*xdo_dev_state_add) (struct xfrm_state *x); + void (*xdo_dev_state_delete) (struct xfrm_state *x); + void (*xdo_dev_state_free) (struct xfrm_state *x); + bool (*xdo_dev_offload_ok) (struct sk_buff *skb, + struct xfrm_state *x); +}; + +The NIC driver offering ipsec offload will need to implement these +callbacks to make the offload available to the network stack's +XFRM subsytem. Additionally, the feature bits NETIF_F_HW_ESP and +NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. + + + +Flow +==== + +At probe time and before the call to register_netdev(), the driver should +set up local data structures and XFRM callbacks, and set the feature bits. +The XFRM code's listener will finish the setup on NETDEV_REGISTER. + + adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops; + adapter->netdev->features |= NETIF_F_HW_ESP; + adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP; + +When new SAs are set up with a request for "offload" feature, the +driver's xdo_dev_state_add() will be given the new SA to be offloaded +and an indication of whether it is for Rx or Tx. The driver should + - verify the algorithm is supported for offloads + - store the SA information (key, salt, target-ip, protocol, etc) + - enable the HW offload of the SA + +The driver can also set an offload_handle in the SA, an opaque void pointer +that can be used to convey context into the fast-path offload requests. + + xs->xso.offload_handle = context; + + +When the network stack is preparing an IPsec packet for an SA that has +been setup for offload, it first calls into xdo_dev_offload_ok() with +the skb and the intended offload state to ask the driver if the offload +will serviceable. This can check the packet information to be sure the +offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and +return true of false to signify its support. + +When ready to send, the driver needs to inspect the Tx packet for the +offload information, including the opaque context, and set up the packet +send accordingly. + + xs = xfrm_input_state(skb); + context = xs->xso.offload_handle; + set up HW for send + +The stack has already inserted the appropriate IPsec headers in the +packet data, the offload just needs to do the encryption and fix up the +header values. + + +When a packet is received and the HW has indicated that it offloaded a +decryption, the driver needs to add a reference to the decoded SA into +the packet's skb. At this point the data should be decrypted but the +IPsec headers are still in the packet data; they are removed later up +the stack in xfrm_input(). + + find and hold the SA that was used to the Rx skb + get spi, protocol, and destination IP from packet headers + xs = find xs from (spi, protocol, dest_IP) + xfrm_state_hold(xs); + + store the state information into the skb + skb->sp = secpath_dup(skb->sp); + skb->sp->xvec[skb->sp->len++] = xs; + skb->sp->olen++; + + indicate the success and/or error status of the offload + xo = xfrm_offload(skb); + xo->flags = CRYPTO_DONE; + xo->status = crypto_status; + + hand the packet to napi_gro_receive() as usual + + +When the SA is removed by the user, the driver's xdo_dev_state_delete() +is asked to disable the offload. Later, xdo_dev_state_free() is called +from a garbage collection routine after all reference counts to the state +have been removed and any remaining resources can be cleared for the +offload state. How these are used by the driver will depend on specific +hardware needs. + +As a netdev is set to DOWN the XFRM stack's netdev listener will call +xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded +states. + + -- cgit From 6200248f41582a410fd0f81dcbe9732ebf6b3560 Mon Sep 17 00:00:00 2001 From: Xingyu Chen Date: Mon, 20 Nov 2017 18:08:50 +0800 Subject: documentation: Add compatibles for Amlogic Meson AXG pin controllers Add compatibles for Amlogic Meson AXG pin controllers Reviewed-by: Neil Armstrong Signed-off-by: Xingyu Chen Signed-off-by: Yixun Lan Acked-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt index 2392557ede27..2c12f9789116 100644 --- a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -9,6 +9,8 @@ Required properties for the root node: "amlogic,meson-gxbb-aobus-pinctrl" "amlogic,meson-gxl-periphs-pinctrl" "amlogic,meson-gxl-aobus-pinctrl" + "amlogic,meson-axg-periphs-pinctrl" + "amlogic,meson-axg-aobus-pinctrl" - reg: address and size of registers controlling irq functionality === GPIO sub-nodes === -- cgit From 0fc66ddfaf8bb8f73c965f24928f8815b470304e Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Wed, 29 Nov 2017 16:34:38 +0100 Subject: Documentation: net: dsa: Cut set_addr() documentation This is not supported anymore, devices needing a MAC address just assign one at random, it's just a driver pecularity. Signed-off-by: Linus Walleij Reviewed-by: Andrew Lunn Signed-off-by: David S. Miller --- Documentation/networking/dsa/dsa.txt | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/dsa/dsa.txt b/Documentation/networking/dsa/dsa.txt index b8b40753133e..25170ad7d25b 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.txt @@ -385,11 +385,6 @@ Switch configuration avoid relying on what a previous software agent such as a bootloader/firmware may have previously configured. -- set_addr: Some switches require the programming of the management interface's - Ethernet MAC address, switch drivers can also disable ageing of MAC addresses - on the management interface and "hardcode"/"force" this MAC address for the - CPU/management interface as an optimization - PHY devices and link management ------------------------------- -- cgit From 6e8e9a01ec2a35dcb502a216d5c84452ebbed90c Mon Sep 17 00:00:00 2001 From: Noralf Trønnes Date: Mon, 6 Nov 2017 20:18:11 +0100 Subject: drm/tinydrm: Use drm_mode_config_helper_suspend/resume() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace driver's code with the generic helpers that do the same thing. Remove todo entry. Signed-off-by: Noralf Trønnes Reviewed-by: Stefan Agner Link: https://patchwork.freedesktop.org/patch/msgid/20171106191812.38927-6-noralf@tronnes.org --- Documentation/gpu/todo.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index e9840d693a86..a44f379d2b25 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -404,11 +404,6 @@ those drivers as simple as possible, so lots of room for refactoring: a drm_device wrong. Doesn't matter, since everyone else gets it wrong too :-) -- With the fbdev pointer in dev->mode_config we could also make - suspend/resume helpers entirely generic, at least if we add a - dev->mode_config.suspend_state. We could even provide a generic pm_ops - structure with those. - - also rework the drm_framebuffer_funcs->dirty hook wire-up, see above. Contact: Noralf Trønnes, Daniel Vetter -- cgit From 3233fc0a691a351b6c1f6ff080b2a7d893337d20 Mon Sep 17 00:00:00 2001 From: Noralf Trønnes Date: Mon, 6 Nov 2017 20:18:12 +0100 Subject: drm/docs: Add todo entry for simple modeset suspend/resume MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add entry for conversion of drivers to new helpers. Signed-off-by: Noralf Trønnes Reviewed-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171106191812.38927-7-noralf@tronnes.org --- Documentation/gpu/todo.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index a44f379d2b25..6bce1beafabe 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -185,6 +185,15 @@ are better. Contact: Sean Paul, Maintainer of the driver you plan to convert +Convert drivers to use simple modeset suspend/resume +---------------------------------------------------- + +Most drivers (except i915 and nouveau) that use +drm_atomic_helper_suspend/resume() can probably be converted to use +drm_mode_config_helper_suspend/resume(). + +Contact: Maintainer of the driver you plan to convert + Core refactorings ================= -- cgit From 525d70a9390a577fcec57e71e142b876a0c226cd Mon Sep 17 00:00:00 2001 From: Pankaj Bansal Date: Fri, 24 Nov 2017 18:52:10 +0530 Subject: Documentation: can: flexcan: Add big-endian property to device tree The FlexCAN controller can be modelled as little or big endian depending on SOC design. This device tree property identifies the controller endianness and the driver reads/writes controller registers based on that. This is optional property. i.e. if this property is not present in device tree node then controller is assumed to be little endian. if this property is present then controller is assumed to be big endian. Signed-off-by: Pankaj Bansal Reviewed-by: Poonam Aggrwal Acked-by: Rob Herring Signed-off-by: Marc Kleine-Budde --- Documentation/devicetree/bindings/net/can/fsl-flexcan.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt index 56d6cc336e1c..bfc0c433654f 100644 --- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt +++ b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt @@ -18,6 +18,12 @@ Optional properties: - xceiver-supply: Regulator that powers the CAN transceiver +- big-endian: This means the registers of FlexCAN controller are big endian. + This is optional property.i.e. if this property is not present in + device tree node then controller is assumed to be little endian. + if this property is present then controller is assumed to be big + endian. + Example: can@1c000 { -- cgit From 00720277a517e6dcc4773fb413711fe0131ee9bd Mon Sep 17 00:00:00 2001 From: Wei-Ning Huang Date: Thu, 12 Oct 2017 14:21:43 +0800 Subject: HID: hid-multitouch: support fine-grain orientation reporting The current hid-multitouch driver only allow the report of two orientations, vertical and horizontal. We use the Azimuth orientation usage 0x3F under the Digitizer usage page to report orientation if the device supports it. Changelog: v1 -> v2: - Fix commit message. - Remove resolution reporting for ABS_MT_ORIENTATION. v2 -> v3: - Fix commit message. v3 -> v4: - Fix ABS_MT_ORIENTATION ABS param range. - Don't set ABS_MT_ORIENTATION in ABS_DG_HEIGHT when it is already set by ABS_DG_AZIMUTH. v4 -> v5: - Improve multi-touch-protocol.rst documentation. Signed-off-by: Wei-Ning Huang Signed-off-by: Wei-Ning Huang Reviewed-by: Dmitry Torokhov Reviewed-by: Henrik Rydberg Signed-off-by: Jiri Kosina --- Documentation/input/multi-touch-protocol.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 8035868c56bc..b51751a0cd5d 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -269,10 +269,11 @@ ABS_MT_ORIENTATION The orientation of the touching ellipse. The value should describe a signed quarter of a revolution clockwise around the touch center. The signed value range is arbitrary, but zero should be returned for an ellipse aligned with - the Y axis of the surface, a negative value when the ellipse is turned to - the left, and a positive value when the ellipse is turned to the - right. When completely aligned with the X axis, the range max should be - returned. + the Y axis (north) of the surface, a negative value when the ellipse is + turned to the left, and a positive value when the ellipse is turned to the + right. When aligned with the X axis in the positive direction, the range + max should be returned; when aligned with the X axis in the negative + direction, the range -max should be returned. Touch ellipsis are symmetrical by default. For devices capable of true 360 degree orientation, the reported orientation must exceed the range max to -- cgit From 2bade36cae87070e66261f4ec96740773e80d95d Mon Sep 17 00:00:00 2001 From: David Lechner Date: Sun, 19 Nov 2017 14:12:05 -0600 Subject: dt-bindings: Add vendor prefix for ilitek MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds the vendor prefix ilitek for ILI Technology Corporation (ILITEK). This prefix is already used several places and I will be adding more. Signed-off-by: David Lechner Acked-by: Rob Herring Signed-off-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/1511122328-31133-2-git-send-email-david@lechnology.com --- Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 6cf1dc5bc77e..cf41a3380071 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -150,6 +150,7 @@ i2se I2SE GmbH ibm International Business Machines (IBM) idt Integrated Device Technologies, Inc. ifi Ingenieurburo Fur Ic-Technologie (I/F/I) +ilitek ILI Technology Corporation (ILITEK) img Imagination Technologies Ltd. infineon Infineon Technologies inforce Inforce Computing -- cgit From 3fd8d9e00f44b7057aa02a50b06e8320cc822526 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Sun, 19 Nov 2017 14:12:06 -0600 Subject: dt-bindings: Add binding for Ilitek ILI9225 display panels MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds a new binding for display panels that use an Ilitek ILI9225 controller. The "ilitek,ili9225-2.2in-176x220" device listed has no identification markings whatsoever and an hour of googling turned up nothing, hence the use of the size and resolution in the name instead of a model name. An example of this nameless device can be found at: https://github.com/Nkawu/TFT_22_ILI9225 Signed-off-by: David Lechner Acked-by: Rob Herring Signed-off-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/1511122328-31133-3-git-send-email-david@lechnology.com --- .../devicetree/bindings/display/ilitek,ili9225.txt | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 Documentation/devicetree/bindings/display/ilitek,ili9225.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/ilitek,ili9225.txt b/Documentation/devicetree/bindings/display/ilitek,ili9225.txt new file mode 100644 index 000000000000..21607a541c33 --- /dev/null +++ b/Documentation/devicetree/bindings/display/ilitek,ili9225.txt @@ -0,0 +1,25 @@ +Ilitek ILI9225 display panels + +This binding is for display panels using an Ilitek ILI9225 controller in SPI +mode. + +Required properties: +- compatible: "ilitek,ili9225-2.2in-176x220" +- rs-gpios: Register select signal +- reset-gpios: Reset pin + +The node for this driver must be a child node of a SPI controller, hence +all mandatory properties described in ../spi/spi-bus.txt must be specified. + +Optional properties: +- rotation: panel rotation in degrees counter clockwise (0,90,180,270) + +Example: + display@0{ + compatible = "ilitek,ili9225-2.2in-176x220"; + reg = <0>; + spi-max-frequency = <12000000>; + rs-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio0 8 GPIO_ACTIVE_HIGH>; + rotation = <270>; + }; -- cgit From 16ba0dc6eaf4d152126a855bc5c9a31f05abadb4 Mon Sep 17 00:00:00 2001 From: Eugen Hristev Date: Wed, 15 Nov 2017 14:56:45 +0200 Subject: dt-bindings: iio: at91-sama5d2_adc: add optional dma property Added property for DMA configuration of the device. Signed-off-by: Eugen Hristev Acked-by: Rob Herring Signed-off-by: Jonathan Cameron --- Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt index 552e7a83951d..6469a4cd2a6d 100644 --- a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt @@ -17,6 +17,11 @@ Required properties: This property uses the IRQ edge types values: IRQ_TYPE_EDGE_RISING , IRQ_TYPE_EDGE_FALLING or IRQ_TYPE_EDGE_BOTH +Optional properties: + - dmas: Phandle to dma channel for the ADC. + - dma-names: Must be "rx" when dmas property is being used. + See ../../dma/dma.txt for details. + Example: adc: adc@fc030000 { @@ -31,4 +36,6 @@ adc: adc@fc030000 { vddana-supply = <&vdd_3v3_lp_reg>; vref-supply = <&vdd_3v3_lp_reg>; atmel,trigger-edge-type = ; + dmas = <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) | AT91_XDMAC_DT_PERID(25))>; + dma-names = "rx"; } -- cgit From f44cd758121a341aa96ed89b88e3a08857b406ba Mon Sep 17 00:00:00 2001 From: Peter Meerwald-Stadler Date: Mon, 6 Nov 2017 00:25:00 +0100 Subject: Documentation: iio: Fix typo Signed-off-by: Peter Meerwald-Stadler Signed-off-by: Jonathan Cameron --- Documentation/ABI/testing/sysfs-bus-iio | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 2e3f919485f4..a478740e2783 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1290,7 +1290,7 @@ KernelVersion: 3.4 Contact: linux-iio@vger.kernel.org Description: Unit-less light intensity. Modifiers both and ir indicate - that measurements contains visible and infrared light + that measurements contain visible and infrared light components or just infrared light, respectively. Modifier uv indicates that measurements contain ultraviolet light components. -- cgit From 098c5a6a14b7cb7727f370bcdcca693b3098e37f Mon Sep 17 00:00:00 2001 From: Fabrice Gasnier Date: Wed, 25 Oct 2017 11:27:43 +0200 Subject: dt-bindings: iio: adc: stm32: add support for diff channels STM32H7 ADC channels may be configured either as single-ended or differential. Add 'st,adc-diff-channels' property to support differential channels. Differential channels are defined as a pair of positive and negative inputs: vinp & vinn. Signed-off-by: Fabrice Gasnier Acked-by: Rob Herring Signed-off-by: Jonathan Cameron --- .../devicetree/bindings/iio/adc/st,stm32-adc.txt | 24 ++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt index 48bfcaa3ffcd..e8bb8243e92c 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt @@ -62,6 +62,15 @@ Required properties: - st,adc-channels: List of single-ended channels muxed for this ADC. It can have up to 16 channels on stm32f4 or 20 channels on stm32h7, numbered from 0 to 15 or 19 (resp. for in0..in15 or in0..in19). +- st,adc-diff-channels: List of differential channels muxed for this ADC. + Depending on part used, some channels can be configured as differential + instead of single-ended (e.g. stm32h7). List here positive and negative + inputs pairs as , ,... vinp and vinn are numbered + from 0 to 19 on stm32h7) + Note: At least one of "st,adc-channels" or "st,adc-diff-channels" is required. + Both properties can be used together. Some channels can be used as + single-ended and some other ones as differential (mixed). But channels + can't be configured both as single-ended and differential (invalid). - #io-channel-cells = <1>: See the IIO bindings section "IIO consumers" in Documentation/devicetree/bindings/iio/iio-bindings.txt @@ -111,3 +120,18 @@ Example: ... other adc child nodes follow... }; + +Example to setup: +- channel 1 as single-ended +- channels 2 & 3 as differential (with resp. 6 & 7 negative inputs) + + adc: adc@40022000 { + compatible = "st,stm32h7-adc-core"; + ... + adc1: adc@0 { + compatible = "st,stm32h7-adc"; + ... + st,adc-channels = <1>; + st,adc-diff-channels = <2 6>, <3 7>; + }; + }; -- cgit From 02c5dff52b3e1eb38513699e17cdf973a5a40322 Mon Sep 17 00:00:00 2001 From: Peter Meerwald-Stadler Date: Fri, 27 Oct 2017 21:45:43 +0200 Subject: dt-bindings: iio: health: Add MAX30105 support to max30102.txt Signed-off-by: Peter Meerwald-Stadler Acked-by: Matt Ranostay Cc: Rob Herring Signed-off-by: Jonathan Cameron --- Documentation/devicetree/bindings/iio/health/max30102.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iio/health/max30102.txt b/Documentation/devicetree/bindings/iio/health/max30102.txt index 8629c18b0e78..ef2ca0a0306f 100644 --- a/Documentation/devicetree/bindings/iio/health/max30102.txt +++ b/Documentation/devicetree/bindings/iio/health/max30102.txt @@ -1,9 +1,11 @@ Maxim MAX30102 heart rate and pulse oximeter sensor +Maxim MAX30105 optical particle-sensing module * https://datasheets.maximintegrated.com/en/ds/MAX30102.pdf +* https://datasheets.maximintegrated.com/en/ds/MAX30105.pdf Required properties: - - compatible: must be "maxim,max30102" + - compatible: must be "maxim,max30102" or "maxim,max30105" - reg: the I2C address of the sensor - interrupt-parent: should be the phandle for the interrupt controller - interrupts: the sole interrupt generated by the device @@ -12,8 +14,10 @@ Required properties: interrupt client node bindings. Optional properties: - - maxim,red-led-current-microamp: configuration for RED LED current + - maxim,red-led-current-microamp: configuration for red LED current - maxim,ir-led-current-microamp: configuration for IR LED current + - maxim,green-led-current-microamp: configuration for green LED current + (max30105 only) Note that each step is approximately 200 microamps, ranging from 0 uA to 50800 uA. -- cgit From edf7550a1f93a88be2bf743b5d352b278d1b789c Mon Sep 17 00:00:00 2001 From: Joel Stanley Date: Tue, 31 Oct 2017 12:42:03 +1030 Subject: iio: adc: aspeed: Deassert reset in probe The ASPEED SoC must deassert a reset in order to use the ADC peripheral. The device tree bindings are updated to document the resets phandle, and the example is updated to match what is expected for both the reset and clock phandle. Note that the bindings should have always had the reset controller, as the hardware is unusable without it. Signed-off-by: Joel Stanley Signed-off-by: Jonathan Cameron --- Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt b/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt index 674e133b7cd7..034fc2ba100e 100644 --- a/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/aspeed_adc.txt @@ -8,6 +8,7 @@ Required properties: - reg: memory window mapping address and length - clocks: Input clock used to derive the sample clock. Expected to be the SoC's APB clock. +- resets: Reset controller phandle - #io-channel-cells: Must be set to <1> to indicate channels are selected by index. @@ -15,6 +16,7 @@ Example: adc@1e6e9000 { compatible = "aspeed,ast2400-adc"; reg = <0x1e6e9000 0xb0>; - clocks = <&clk_apb>; + clocks = <&syscon ASPEED_CLK_APB>; + resets = <&syscon ASPEED_RESET_ADC>; #io-channel-cells = <1>; }; -- cgit From eed48a3beba0b1da725c77288091bfa6395d232d Mon Sep 17 00:00:00 2001 From: Lorenzo Bianconi Date: Thu, 23 Nov 2017 23:59:06 +0100 Subject: dt-bindings: iio: light: add UVIS25 device bindings Acked-by: Rob Herring Signed-off-by: Lorenzo Bianconi Signed-off-by: Jonathan Cameron --- .../devicetree/bindings/iio/light/uvis25.txt | 23 ++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 Documentation/devicetree/bindings/iio/light/uvis25.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iio/light/uvis25.txt b/Documentation/devicetree/bindings/iio/light/uvis25.txt new file mode 100644 index 000000000000..3041207e3f3c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/uvis25.txt @@ -0,0 +1,23 @@ +* ST UVIS25 uv sensor + +Required properties: +- compatible: should be "st,uvis25" +- reg: i2c address of the sensor / spi cs line + +Optional properties: +- interrupt-parent: should be the phandle for the interrupt controller +- interrupts: interrupt mapping for IRQ. It should be configured with + flags IRQ_TYPE_LEVEL_HIGH, IRQ_TYPE_EDGE_RISING, IRQ_TYPE_LEVEL_LOW or + IRQ_TYPE_EDGE_FALLING. + + Refer to interrupt-controller/interrupts.txt for generic interrupt + client node bindings. + +Example: + +uvis25@47 { + compatible = "st,uvis25"; + reg = <0x47>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_EDGE_RISING>; +}; -- cgit From 461774659add8b73d558c69d532a1a6ff32d627e Mon Sep 17 00:00:00 2001 From: Xingyu Chen Date: Tue, 7 Nov 2017 22:10:20 +0800 Subject: dt-bindings: iio: adc: update the doc for SAR ADC Update the doc as the SAR ADC modules doesn't require "sana" clock. Singed-off-by: Xingyu Chen Signed-off-by: Yixun Lan Acked-by: Rob Herring Signed-off-by: Jonathan Cameron --- Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt index f413e82c8b83..1e6ee3deb4fa 100644 --- a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt @@ -15,7 +15,6 @@ Required properties: - "clkin" for the reference clock (typically XTAL) - "core" for the SAR ADC core clock optional clocks: - - "sana" for the analog clock - "adc_clk" for the ADC (sampling) clock - "adc_sel" for the ADC (sampling) clock mux - vref-supply: the regulator supply for the ADC reference voltage -- cgit From 3881c4a56e5941c21c08d9476c68d2cc65005f68 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 28 Nov 2017 16:49:45 +0900 Subject: dt-bindings: pinctrl: uniphier: add UniPhier pinctrl binding The driver has been in the tree for a while, but its binding document is missing. Hence, here it is. Signed-off-by: Masahiro Yamada Acked-by: Rob Herring Signed-off-by: Linus Walleij --- .../pinctrl/socionext,uniphier-pinctrl.txt | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.txt new file mode 100644 index 000000000000..8173b12138ad --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/socionext,uniphier-pinctrl.txt @@ -0,0 +1,27 @@ +UniPhier SoCs pin controller + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-ld4-pinctrl" - for LD4 SoC + "socionext,uniphier-pro4-pinctrl" - for Pro4 SoC + "socionext,uniphier-sld8-pinctrl" - for sLD8 SoC + "socionext,uniphier-pro5-pinctrl" - for Pro5 SoC + "socionext,uniphier-pxs2-pinctrl" - for PXs2 SoC + "socionext,uniphier-ld6b-pinctrl" - for LD6b SoC + "socionext,uniphier-ld11-pinctrl" - for LD11 SoC + "socionext,uniphier-ld20-pinctrl" - for LD20 SoC + "socionext,uniphier-pxs3-pinctrl" - for PXs3 SoC + +Note: +The UniPhier pinctrl should be a subnode of a "syscon" compatible node. + +Example: + soc-glue@5f800000 { + compatible = "socionext,uniphier-pro4-soc-glue", + "simple-mfd", "syscon"; + reg = <0x5f800000 0x2000>; + + pinctrl: pinctrl { + compatible = "socionext,uniphier-pro4-pinctrl"; + }; + }; -- cgit From 12bb14aa480db6438b1b95a1fcddfb3810b11134 Mon Sep 17 00:00:00 2001 From: Dave Gerlach Date: Wed, 17 Jun 2015 14:52:09 -0500 Subject: Documentation: dt: Update ti,emif bindings Update the Texas Instruments EMIF binding document to include the device tree bindings for ti,emif-am3352 and ti,emif-am4372 which are used by the ti-emif-sram driver to provide low-level PM functionality. Acked-by: Rob Herring Acked-by: Tony Lindgren Signed-off-by: Dave Gerlach Signed-off-by: Santosh Shilimkar --- .../devicetree/bindings/memory-controllers/ti/emif.txt | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt index fd823d6091b2..29a99871e808 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt +++ b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt @@ -23,6 +23,13 @@ Required properties: the value shall be "emif" where is the number of the EMIF instance with base 1. +Required only for "ti,emif-am3352" and "ti,emif-am4372": +- sram : Phandles for generic sram driver nodes, + first should be type 'protect-exec' for the driver to use to copy + and run PM functions, second should be regular pool to be used for + data region for code. See Documentation/devicetree/bindings/sram/sram.txt + for more details. + Optional properties: - cs1-used : Have this property if CS1 of this EMIF instance has a memory part attached to it. If there is a memory @@ -44,7 +51,7 @@ Optional properties: - hw-caps-temp-alert : Have this property if the controller has capability for generating SDRAM temperature alerts -Example: +-Examples: emif1: emif@0x4c000000 { compatible = "ti,emif-4d"; @@ -56,3 +63,11 @@ emif1: emif@0x4c000000 { hw-caps-ll-interface; hw-caps-temp-alert; }; + +/* From am33xx.dtsi */ +emif: emif@4c000000 { + compatible = "ti,emif-am3352"; + reg = <0x4C000000 0x1000>; + sram = <&pm_sram_code + &pm_sram_data>; +}; -- cgit From 14911c6f48ec9571343ac36ae02f2db68bf9e7f9 Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Tue, 28 Nov 2017 16:53:32 +0100 Subject: i2c: gpio: add fault injector Add fault injection capabilities to the i2c-gpio driver. When connected to another I2C bus, it can create unusual states which the other I2C bus master driver needs to handle. Only for debugging! Signed-off-by: Wolfram Sang --- Documentation/i2c/gpio-fault-injection | 54 ++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 Documentation/i2c/gpio-fault-injection (limited to 'Documentation') diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection new file mode 100644 index 000000000000..e0c4f775e239 --- /dev/null +++ b/Documentation/i2c/gpio-fault-injection @@ -0,0 +1,54 @@ +Linux I2C fault injection +========================= + +The GPIO based I2C bus master driver can be configured to provide fault +injection capabilities. It is then meant to be connected to another I2C bus +which is driven by the I2C bus master driver under test. The GPIO fault +injection driver can create special states on the bus which the other I2C bus +master driver should handle gracefully. + +Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an +'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually +mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO +driven I2C bus. Each subdirectory will contain files to trigger the fault +injection. They will be described now along with their intended use-cases. + +"scl" +----- + +By reading this file, you get the current state of SCL. By writing, you can +change its state to either force it low or to release it again. So, by using +"echo 0 > scl" you force SCL low and thus, no communication will be possible +because the bus master under test will not be able to clock. It should detect +the condition of SCL being unresponsive and report an error to the upper +layers. + +"sda" +----- + +By reading this file, you get the current state of SDA. By writing, you can +change its state to either force it low or to release it again. So, by using +"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus +master under test should detect this condition and trigger a bus recovery (see +I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C +core (see 'struct bus_recovery_info'). However, the bus recovery will not +succeed because SDA is still pinned low until you manually release it again +with "echo 1 > sda". A test with an automatic release can be done with the +'incomplete_transfer' file. + +"incomplete_transfer" +--------------------- + +This file is write only and you need to write the address of an existing I2C +client device to it. Then, a transfer to this device will be started, but it +will stop at the ACK phase after the address of the client has been +transmitted. Because the device will ACK its presence, this results in SDA +being pulled low by the device while SCL is high. So, similar to the "sda" file +above, the bus master under test should detect this condition and try a bus +recovery. This time, however, it should succeed and the device should release +SDA after toggling SCL. Please note: there are I2C client devices which detect +a stuck SDA on their side and release it on their own after a few milliseconds. +Also, there are external devices deglitching and monitoring the I2C bus. They +can also detect a stuck SDA and will init a bus recovery on their own. If you +want to implement bus recovery in a bus master driver, make sure you checked +your hardware setup carefully before. -- cgit From d4e01186ae1c6045b5a508741f2446dffec7511c Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Sat, 4 Nov 2017 21:20:07 +0100 Subject: i2c: add docs to clarify DMA handling Reviewed-by: Jonathan Cameron Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Wolfram Sang Signed-off-by: Wolfram Sang --- Documentation/i2c/DMA-considerations | 67 ++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 Documentation/i2c/DMA-considerations (limited to 'Documentation') diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations new file mode 100644 index 000000000000..966610aa4620 --- /dev/null +++ b/Documentation/i2c/DMA-considerations @@ -0,0 +1,67 @@ +================= +Linux I2C and DMA +================= + +Given that i2c is a low-speed bus, over which the majority of messages +transferred are small, it is not considered a prime user of DMA access. At this +time of writing, only 10% of I2C bus master drivers have DMA support +implemented. And the vast majority of transactions are so small that setting up +DMA for it will likely add more overhead than a plain PIO transfer. + +Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe. +It does not seem reasonable to apply additional burdens when the feature is so +rarely used. However, it is recommended to use a DMA-safe buffer if your +message size is likely applicable for DMA. Most drivers have this threshold +around 8 bytes (as of today, this is mostly an educated guess, however). For +any message of 16 byte or larger, it is probably a really good idea. Please +note that other subsystems you use might add requirements. E.g., if your +I2C bus master driver is using USB as a bridge, then you need to have DMA +safe buffers always, because USB requires it. + +Clients +------- + +For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE +flag with it. Then, the I2C core and drivers know they can safely operate DMA +on it. Note that using this flag is optional. I2C host drivers which are not +updated to use this flag will work like before. And like before, they risk +using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in +more and more clients and host drivers is the planned way forward. Note also +that setting this flag makes only sense in kernel space. User space data is +copied into kernel space anyhow. The I2C core makes sure the destination +buffers in kernel space are always DMA capable. Also, when the core emulates +SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users +of i2c_master_send() and i2c_master_recv() functions can now use DMA safe +variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they +know their buffers are DMA safe. Users of i2c_transfer() must set the +I2C_M_DMA_SAFE flag manually. + +Masters +------- + +Bus master drivers wishing to implement safe DMA can use helper functions from +the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a +certain threshold is met:: + + dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte); + +If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a +bounce buffer. But you don't need to care about that detail, just use the +returned buffer. If NULL is returned, the threshold was not met or a bounce +buffer could not be allocated. Fall back to PIO in that case. + +In any case, a buffer obtained from above needs to be released. It ensures data +is copied back to the message and a potentially used bounce buffer is freed:: + + i2c_release_dma_safe_msg_buf(msg, dma_buf); + +The bounce buffer handling from the core is generic and simple. It will always +allocate a new bounce buffer. If you want a more sophisticated handling (e.g. +reusing pre-allocated buffers), you are free to implement your own. + +Please also check the in-kernel documentation for details. The i2c-sh_mobile +driver can be used as a reference example how to use the above helpers. + +Final note: If you plan to use DMA with I2C (or with anything else, actually) +make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help +you find various issues which can be complex to debug otherwise. -- cgit From 006c23327f8de8575508c458131b304188d426f7 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 3 Dec 2017 15:36:20 -0800 Subject: documentation/gpu/i915: fix docs build error after file rename Fix documentation build errors after intel_guc_loader.c was renamed to intel_guc_fw.c. Error: Cannot open file ../drivers/gpu/drm/i915/intel_guc_loader.c WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno -function GuC-specific firmware loader ../drivers/gpu/drm/i915/intel_guc_loader.c' failed with return code 1 Error: Cannot open file ../drivers/gpu/drm/i915/intel_guc_loader.c Error: Cannot open file ../drivers/gpu/drm/i915/intel_guc_loader.c WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno -internal ../drivers/gpu/drm/i915/intel_guc_loader.c' failed with return code 2 Fixes: e8668bbcb0f9 ("drm/i915/guc: Rename intel_guc_loader.c to intel_guc_fw.c") Signed-off-by: Randy Dunlap Cc: Michal Wajdeczko Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/1b214f53-47f5-bef3-f58e-8136de5678ed@infradead.org --- Documentation/gpu/i915.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 21577eabaf78..84021142a8f3 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -341,10 +341,10 @@ GuC GuC-specific firmware loader ---------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c :doc: GuC-specific firmware loader -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c +.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c :internal: GuC-based command submission -- cgit From faf4a3ff36137aaa8de1a8da99a92f6e712903f1 Mon Sep 17 00:00:00 2001 From: Fabrizio Castro Date: Fri, 13 Oct 2017 16:22:19 +0100 Subject: dt-bindings: display: rcar-du: Document R8A774[35] DU Add device tree bindings for r8a7743 and r8a7745 DUs. r8a7743 DU is similar to the one from r8a7791, r8a7745 DU is similar to the one from r8a7794. Signed-off-by: Fabrizio Castro Reviewed-by: Biju Das Reviewed-by: Laurent Pinchart [Don't reference R8A779[0123456] and R8A774[35] explicitly] [Number all DPAD, HDMI and LVDS ports] Signed-off-by: Laurent Pinchart --- .../devicetree/bindings/display/renesas,du.txt | 30 ++++++++++++---------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index 4bbd1e9bf3be..cd48aba3bc8c 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -3,6 +3,8 @@ Required Properties: - compatible: must be one of the following. + - "renesas,du-r8a7743" for R8A7743 (RZ/G1M) compatible DU + - "renesas,du-r8a7745" for R8A7745 (RZ/G1E) compatible DU - "renesas,du-r8a7779" for R8A7779 (R-Car H1) compatible DU - "renesas,du-r8a7790" for R8A7790 (R-Car H2) compatible DU - "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU @@ -27,10 +29,10 @@ Required Properties: - clock-names: Name of the clocks. This property is model-dependent. - R8A7779 uses a single functional clock. The clock doesn't need to be named. - - R8A779[0123456] use one functional clock per channel and one clock per - LVDS encoder (if available). The functional clocks must be named "du.x" - with "x" being the channel numerical index. The LVDS clocks must be - named "lvds.x" with "x" being the LVDS encoder numerical index. + - All other DU instances use one functional clock per channel and one + clock per LVDS encoder (if available). The functional clocks must be + named "du.x" with "x" being the channel numerical index. The LVDS clocks + must be named "lvds.x" with "x" being the LVDS encoder numerical index. - In addition to the functional and encoder clocks, all DU versions also support externally supplied pixel clocks. Those clocks are optional. When supplied they must be named "dclkin.x" with "x" being the input @@ -49,16 +51,18 @@ bindings specified in Documentation/devicetree/bindings/graph.txt. The following table lists for each supported model the port number corresponding to each DU output. - Port 0 Port1 Port2 Port3 + Port0 Port1 Port2 Port3 ----------------------------------------------------------------------------- - R8A7779 (H1) DPAD 0 DPAD 1 - - - R8A7790 (H2) DPAD LVDS 0 LVDS 1 - - R8A7791 (M2-W) DPAD LVDS 0 - - - R8A7792 (V2H) DPAD 0 DPAD 1 - - - R8A7793 (M2-N) DPAD LVDS 0 - - - R8A7794 (E2) DPAD 0 DPAD 1 - - - R8A7795 (H3) DPAD HDMI 0 HDMI 1 LVDS - R8A7796 (M3-W) DPAD HDMI LVDS - + R8A7743 (RZ/G1M) DPAD 0 LVDS 0 - - + R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - + R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - + R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - + R8A7791 (R-Car M2-W) DPAD 0 LVDS 0 - - + R8A7792 (R-Car V2H) DPAD 0 DPAD 1 - - + R8A7793 (R-Car M2-N) DPAD 0 LVDS 0 - - + R8A7794 (R-Car E2) DPAD 0 DPAD 1 - - + R8A7795 (R-Car H3) DPAD 0 HDMI 0 HDMI 1 LVDS 0 + R8A7796 (R-Car M3-W) DPAD 0 HDMI 0 LVDS 0 - Example: R8A7795 (R-Car H3) ES2.0 DU -- cgit From b38defdb44fb0377b38896e38ac1fc8482e68f76 Mon Sep 17 00:00:00 2001 From: Brijesh Singh Date: Mon, 4 Dec 2017 10:57:23 -0600 Subject: Documentation/virtual/kvm: Add AMD Secure Encrypted Virtualization (SEV) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create a Documentation entry to describe the AMD Secure Encrypted Virtualization (SEV) feature. Cc: Thomas Gleixner Cc: Ingo Molnar Cc: "H. Peter Anvin" Cc: Paolo Bonzini Cc: "Radim Krčmář" Cc: Jonathan Corbet Cc: Borislav Petkov Cc: Tom Lendacky Cc: kvm@vger.kernel.org Cc: x86@kernel.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Brijesh Singh Reviewed-by: Borislav Petkov --- Documentation/virtual/kvm/00-INDEX | 3 ++ .../virtual/kvm/amd-memory-encryption.rst | 45 ++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 Documentation/virtual/kvm/amd-memory-encryption.rst (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/00-INDEX b/Documentation/virtual/kvm/00-INDEX index 69fe1a8b7ad1..3da73aabff5a 100644 --- a/Documentation/virtual/kvm/00-INDEX +++ b/Documentation/virtual/kvm/00-INDEX @@ -26,3 +26,6 @@ s390-diag.txt - Diagnose hypercall description (for IBM S/390) timekeeping.txt - timekeeping virtualization for x86-based architectures. +amd-memory-encryption.txt + - notes on AMD Secure Encrypted Virtualization feature and SEV firmware + command description diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst new file mode 100644 index 000000000000..a8ef21e737db --- /dev/null +++ b/Documentation/virtual/kvm/amd-memory-encryption.rst @@ -0,0 +1,45 @@ +====================================== +Secure Encrypted Virtualization (SEV) +====================================== + +Overview +======== + +Secure Encrypted Virtualization (SEV) is a feature found on AMD processors. + +SEV is an extension to the AMD-V architecture which supports running +virtual machines (VMs) under the control of a hypervisor. When enabled, +the memory contents of a VM will be transparently encrypted with a key +unique to that VM. + +The hypervisor can determine the SEV support through the CPUID +instruction. The CPUID function 0x8000001f reports information related +to SEV:: + + 0x8000001f[eax]: + Bit[1] indicates support for SEV + ... + [ecx]: + Bits[31:0] Number of encrypted guests supported simultaneously + +If support for SEV is present, MSR 0xc001_0010 (MSR_K8_SYSCFG) and MSR 0xc001_0015 +(MSR_K7_HWCR) can be used to determine if it can be enabled:: + + 0xc001_0010: + Bit[23] 1 = memory encryption can be enabled + 0 = memory encryption can not be enabled + + 0xc001_0015: + Bit[0] 1 = memory encryption can be enabled + 0 = memory encryption can not be enabled + +When SEV support is available, it can be enabled in a specific VM by +setting the SEV bit before executing VMRUN.:: + + VMCB[0x90]: + Bit[1] 1 = SEV is enabled + 0 = SEV is disabled + +SEV hardware uses ASIDs to associate a memory encryption key with a VM. +Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value +defined in the CPUID 0x8000001f[ecx] field. -- cgit From 5acc5c063196b4a531a761a954023c1848ec832b Mon Sep 17 00:00:00 2001 From: Brijesh Singh Date: Mon, 4 Dec 2017 10:57:26 -0600 Subject: KVM: Introduce KVM_MEMORY_ENCRYPT_OP ioctl MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit If the hardware supports memory encryption then the KVM_MEMORY_ENCRYPT_OP ioctl can be used by qemu to issue a platform specific memory encryption commands. Cc: Thomas Gleixner Cc: Ingo Molnar Cc: "H. Peter Anvin" Cc: Paolo Bonzini Cc: "Radim Krčmář" Cc: Joerg Roedel Cc: Borislav Petkov Cc: Tom Lendacky Cc: x86@kernel.org Cc: kvm@vger.kernel.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Brijesh Singh Reviewed-by: Paolo Bonzini Reviewed-by: Borislav Petkov --- Documentation/virtual/kvm/api.txt | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index f670e4b9e7f3..c8755be35543 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -3394,6 +3394,22 @@ invalid, if invalid pages are written to (e.g. after the end of memory) or if no page table is present for the addresses (e.g. when using hugepages). +4.109 KVM_MEMORY_ENCRYPT_OP + +Capability: basic +Architectures: x86 +Type: system +Parameters: an opaque platform specific structure (in/out) +Returns: 0 on success; -1 on error + +If the platform supports creating encrypted VMs then this ioctl can be used +for issuing platform-specific memory encryption commands to manage those +encrypted VMs. + +Currently, this ioctl is used for issuing Secure Encrypted Virtualization +(SEV) commands on AMD Processors. The SEV commands are defined in +Documentation/virtual/kvm/amd-memory-encryption.txt. + 5. The kvm_run structure ------------------------ -- cgit From 69eaedee411c1fc1cf123520897a96b7cf04d8a0 Mon Sep 17 00:00:00 2001 From: Brijesh Singh Date: Mon, 4 Dec 2017 10:57:26 -0600 Subject: KVM: Introduce KVM_MEMORY_ENCRYPT_{UN,}REG_REGION ioctl MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit If hardware supports memory encryption then KVM_MEMORY_ENCRYPT_REG_REGION and KVM_MEMORY_ENCRYPT_UNREG_REGION ioctl's can be used by userspace to register/unregister the guest memory regions which may contain the encrypted data (e.g guest RAM, PCI BAR, SMRAM etc). Cc: Thomas Gleixner Cc: Ingo Molnar Cc: "H. Peter Anvin" Cc: Paolo Bonzini Cc: "Radim Krčmář" Cc: Joerg Roedel Cc: Borislav Petkov Cc: Tom Lendacky Cc: x86@kernel.org Cc: kvm@vger.kernel.org Cc: linux-kernel@vger.kernel.org Improvements-by: Borislav Petkov Signed-off-by: Brijesh Singh Reviewed-by: Borislav Petkov --- Documentation/virtual/kvm/api.txt | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index c8755be35543..c2ced6a44bbb 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -3410,6 +3410,40 @@ Currently, this ioctl is used for issuing Secure Encrypted Virtualization (SEV) commands on AMD Processors. The SEV commands are defined in Documentation/virtual/kvm/amd-memory-encryption.txt. +4.110 KVM_MEMORY_ENCRYPT_REG_REGION + +Capability: basic +Architectures: x86 +Type: system +Parameters: struct kvm_enc_region (in) +Returns: 0 on success; -1 on error + +This ioctl can be used to register a guest memory region which may +contain encrypted data (e.g. guest RAM, SMRAM etc). + +It is used in the SEV-enabled guest. When encryption is enabled, a guest +memory region may contain encrypted data. The SEV memory encryption +engine uses a tweak such that two identical plaintext pages, each at +different locations will have differing ciphertexts. So swapping or +moving ciphertext of those pages will not result in plaintext being +swapped. So relocating (or migrating) physical backing pages for the SEV +guest will require some additional steps. + +Note: The current SEV key management spec does not provide commands to +swap or migrate (move) ciphertext pages. Hence, for now we pin the guest +memory region registered with the ioctl. + +4.111 KVM_MEMORY_ENCRYPT_UNREG_REGION + +Capability: basic +Architectures: x86 +Type: system +Parameters: struct kvm_enc_region (in) +Returns: 0 on success; -1 on error + +This ioctl can be used to unregister the guest memory region registered +with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above. + 5. The kvm_run structure ------------------------ -- cgit From dc48bae01e5a23ae67758e8fe31cdc439202b190 Mon Sep 17 00:00:00 2001 From: Brijesh Singh Date: Mon, 4 Dec 2017 10:57:33 -0600 Subject: KVM: Define SEV key management command id MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define Secure Encrypted Virtualization (SEV) key management command id and structure. The command definition is available in SEV KM spec 0.14 (http://support.amd.com/TechDocs/55766_SEV-KM API_Specification.pdf) and Documentation/virtual/kvm/amd-memory-encryption.txt. Cc: Thomas Gleixner Cc: Ingo Molnar Cc: "H. Peter Anvin" Cc: Paolo Bonzini Cc: "Radim Krčmář" Cc: Joerg Roedel Cc: Borislav Petkov Cc: Tom Lendacky Cc: Jonathan Corbet Cc: x86@kernel.org Cc: kvm@vger.kernel.org Cc: linux-kernel@vger.kernel.org Improvements-by: Borislav Petkov Signed-off-by: Brijesh Singh Reviewed-by: Borislav Petkov --- .../virtual/kvm/amd-memory-encryption.rst | 202 +++++++++++++++++++++ 1 file changed, 202 insertions(+) (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst index a8ef21e737db..71d6d257074f 100644 --- a/Documentation/virtual/kvm/amd-memory-encryption.rst +++ b/Documentation/virtual/kvm/amd-memory-encryption.rst @@ -43,3 +43,205 @@ setting the SEV bit before executing VMRUN.:: SEV hardware uses ASIDs to associate a memory encryption key with a VM. Hence, the ASID for the SEV-enabled guests must be from 1 to a maximum value defined in the CPUID 0x8000001f[ecx] field. + +SEV Key Management +================== + +The SEV guest key management is handled by a separate processor called the AMD +Secure Processor (AMD-SP). Firmware running inside the AMD-SP provides a secure +key management interface to perform common hypervisor activities such as +encrypting bootstrap code, snapshot, migrating and debugging the guest. For more +information, see the SEV Key Management spec [api-spec]_ + +KVM implements the following commands to support common lifecycle events of SEV +guests, such as launching, running, snapshotting, migrating and decommissioning. + +1. KVM_SEV_INIT +--------------- + +The KVM_SEV_INIT command is used by the hypervisor to initialize the SEV platform +context. In a typical workflow, this command should be the first command issued. + +Returns: 0 on success, -negative on error + +2. KVM_SEV_LAUNCH_START +----------------------- + +The KVM_SEV_LAUNCH_START command is used for creating the memory encryption +context. To create the encryption context, user must provide a guest policy, +the owner's public Diffie-Hellman (PDH) key and session information. + +Parameters: struct kvm_sev_launch_start (in/out) + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_start { + __u32 handle; /* if zero then firmware creates a new handle */ + __u32 policy; /* guest's policy */ + + __u64 dh_uaddr; /* userspace address pointing to the guest owner's PDH key */ + __u32 dh_len; + + __u64 session_addr; /* userspace address which points to the guest session information */ + __u32 session_len; + }; + +On success, the 'handle' field contains a new handle and on error, a negative value. + +For more details, see SEV spec Section 6.2. + +3. KVM_SEV_LAUNCH_UPDATE_DATA +----------------------------- + +The KVM_SEV_LAUNCH_UPDATE_DATA is used for encrypting a memory region. It also +calculates a measurement of the memory contents. The measurement is a signature +of the memory contents that can be sent to the guest owner as an attestation +that the memory was encrypted correctly by the firmware. + +Parameters (in): struct kvm_sev_launch_update_data + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_update { + __u64 uaddr; /* userspace address to be encrypted (must be 16-byte aligned) */ + __u32 len; /* length of the data to be encrypted (must be 16-byte aligned) */ + }; + +For more details, see SEV spec Section 6.3. + +4. KVM_SEV_LAUNCH_MEASURE +------------------------- + +The KVM_SEV_LAUNCH_MEASURE command is used to retrieve the measurement of the +data encrypted by the KVM_SEV_LAUNCH_UPDATE_DATA command. The guest owner may +wait to provide the guest with confidential information until it can verify the +measurement. Since the guest owner knows the initial contents of the guest at +boot, the measurement can be verified by comparing it to what the guest owner +expects. + +Parameters (in): struct kvm_sev_launch_measure + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_measure { + __u64 uaddr; /* where to copy the measurement */ + __u32 len; /* length of measurement blob */ + }; + +For more details on the measurement verification flow, see SEV spec Section 6.4. + +5. KVM_SEV_LAUNCH_FINISH +------------------------ + +After completion of the launch flow, the KVM_SEV_LAUNCH_FINISH command can be +issued to make the guest ready for the execution. + +Returns: 0 on success, -negative on error + +6. KVM_SEV_GUEST_STATUS +----------------------- + +The KVM_SEV_GUEST_STATUS command is used to retrieve status information about a +SEV-enabled guest. + +Parameters (out): struct kvm_sev_guest_status + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_guest_status { + __u32 handle; /* guest handle */ + __u32 policy; /* guest policy */ + __u8 state; /* guest state (see enum below) */ + }; + +SEV guest state: + +:: + + enum { + SEV_STATE_INVALID = 0; + SEV_STATE_LAUNCHING, /* guest is currently being launched */ + SEV_STATE_SECRET, /* guest is being launched and ready to accept the ciphertext data */ + SEV_STATE_RUNNING, /* guest is fully launched and running */ + SEV_STATE_RECEIVING, /* guest is being migrated in from another SEV machine */ + SEV_STATE_SENDING /* guest is getting migrated out to another SEV machine */ + }; + +7. KVM_SEV_DBG_DECRYPT +---------------------- + +The KVM_SEV_DEBUG_DECRYPT command can be used by the hypervisor to request the +firmware to decrypt the data at the given memory region. + +Parameters (in): struct kvm_sev_dbg + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_dbg { + __u64 src_uaddr; /* userspace address of data to decrypt */ + __u64 dst_uaddr; /* userspace address of destination */ + __u32 len; /* length of memory region to decrypt */ + }; + +The command returns an error if the guest policy does not allow debugging. + +8. KVM_SEV_DBG_ENCRYPT +---------------------- + +The KVM_SEV_DEBUG_ENCRYPT command can be used by the hypervisor to request the +firmware to encrypt the data at the given memory region. + +Parameters (in): struct kvm_sev_dbg + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_dbg { + __u64 src_uaddr; /* userspace address of data to encrypt */ + __u64 dst_uaddr; /* userspace address of destination */ + __u32 len; /* length of memory region to encrypt */ + }; + +The command returns an error if the guest policy does not allow debugging. + +9. KVM_SEV_LAUNCH_SECRET +------------------------ + +The KVM_SEV_LAUNCH_SECRET command can be used by the hypervisor to inject secret +data after the measurement has been validated by the guest owner. + +Parameters (in): struct kvm_sev_launch_secret + +Returns: 0 on success, -negative on error + +:: + + struct kvm_sev_launch_secret { + __u64 hdr_uaddr; /* userspace address containing the packet header */ + __u32 hdr_len; + + __u64 guest_uaddr; /* the guest memory region where the secret should be injected */ + __u32 guest_len; + + __u64 trans_uaddr; /* the hypervisor memory region which contains the secret */ + __u32 trans_len; + }; + +References +========== + +.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf +.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM%20API_Specification.pdf +.. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34) +.. [kvm-forum] http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf -- cgit From 0e43238999737a7ec1cd732c03c2137f31c0be80 Mon Sep 17 00:00:00 2001 From: Peter Rosin Date: Mon, 4 Dec 2017 14:57:08 +0100 Subject: ARM: dts: at91: add devicetree for the Axentia Nattis with Natte power The Axentia Nattis is a device designed for presenting departures for public transport systems. The Natte helper board provides power and features a battery of battery chargers. Signed-off-by: Peter Rosin Signed-off-by: Alexandre Belloni --- Documentation/devicetree/bindings/arm/axentia.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/axentia.txt b/Documentation/devicetree/bindings/arm/axentia.txt index ea3fb96ae465..de58f2463880 100644 --- a/Documentation/devicetree/bindings/arm/axentia.txt +++ b/Documentation/devicetree/bindings/arm/axentia.txt @@ -10,6 +10,15 @@ compatible = "axentia,linea", and following the rules from atmel-at91.txt for a sama5d31 SoC. +Nattis v2 board with Natte v2 power board +----------------------------------------- + +Required root node properties: +compatible = "axentia,nattis-2", "axentia,natte-2", "axentia,linea", + "atmel,sama5d31", "atmel,sama5d3", "atmel,sama5"; +and following the rules from above for the axentia,linea CPU module. + + TSE-850 v3 board ---------------- -- cgit From 43347d56c8d9dd732cee2f8efd384ad21dd1f6c4 Mon Sep 17 00:00:00 2001 From: Miroslav Benes Date: Wed, 15 Nov 2017 14:50:13 +0100 Subject: livepatch: send a fake signal to all blocking tasks Live patching consistency model is of LEAVE_PATCHED_SET and SWITCH_THREAD. This means that all tasks in the system have to be marked one by one as safe to call a new patched function. Safe means when a task is not (sleeping) in a set of patched functions. That is, no patched function is on the task's stack. Another clearly safe place is the boundary between kernel and userspace. The patching waits for all tasks to get outside of the patched set or to cross the boundary. The transition is completed afterwards. The problem is that a task can block the transition for quite a long time, if not forever. It could sleep in a set of patched functions, for example. Luckily we can force the task to leave the set by sending it a fake signal, that is a signal with no data in signal pending structures (no handler, no sign of proper signal delivered). Suspend/freezer use this to freeze the tasks as well. The task gets TIF_SIGPENDING set and is woken up (if it has been sleeping in the kernel before) or kicked by rescheduling IPI (if it was running on other CPU). This causes the task to go to kernel/userspace boundary where the signal would be handled and the task would be marked as safe in terms of live patching. There are tasks which are not affected by this technique though. The fake signal is not sent to kthreads. They should be handled differently. They can be woken up so they leave the patched set and their TIF_PATCH_PENDING can be cleared thanks to stack checking. For the sake of completeness, if the task is in TASK_RUNNING state but not currently running on some CPU it doesn't get the IPI, but it would eventually handle the signal anyway. Second, if the task runs in the kernel (in TASK_RUNNING state) it gets the IPI, but the signal is not handled on return from the interrupt. It would be handled on return to the userspace in the future when the fake signal is sent again. Stack checking deals with these cases in a better way. If the task was sleeping in a syscall it would be woken by our fake signal, it would check if TIF_SIGPENDING is set (by calling signal_pending() predicate) and return ERESTART* or EINTR. Syscalls with ERESTART* return values are restarted in case of the fake signal (see do_signal()). EINTR is propagated back to the userspace program. This could disturb the program, but... * each process dealing with signals should react accordingly to EINTR return values. * syscalls returning EINTR happen to be quite common situation in the system even if no fake signal is sent. * freezer sends the fake signal and does not deal with EINTR anyhow. Thus EINTR values are returned when the system is resumed. The very safe marking is done in architectures' "entry" on syscall and interrupt/exception exit paths, and in a stack checking functions of livepatch. TIF_PATCH_PENDING is cleared and the next recalc_sigpending() drops TIF_SIGPENDING. In connection with this, also call klp_update_patch_state() before do_signal(), so that recalc_sigpending() in dequeue_signal() can clear TIF_PATCH_PENDING immediately and thus prevent a double call of do_signal(). Note that the fake signal is not sent to stopped/traced tasks. Such task prevents the patching to finish till it continues again (is not traced anymore). Last, sending the fake signal is not automatic. It is done only when admin requests it by writing 1 to signal sysfs attribute in livepatch sysfs directory. Signed-off-by: Miroslav Benes Cc: Oleg Nesterov Cc: Michael Ellerman Cc: Thomas Gleixner Cc: Ingo Molnar Cc: "H. Peter Anvin" Cc: Andy Lutomirski Cc: linuxppc-dev@lists.ozlabs.org Cc: x86@kernel.org Acked-by: Michael Ellerman (powerpc) Signed-off-by: Jiri Kosina --- Documentation/ABI/testing/sysfs-kernel-livepatch | 12 ++++++++++++ Documentation/livepatch/livepatch.txt | 11 +++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index d5d39748382f..3bb9d5bc1ce3 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -33,6 +33,18 @@ Description: An attribute which indicates whether the patch is currently in transition. +What: /sys/kernel/livepatch//signal +Date: Nov 2017 +KernelVersion: 4.15.0 +Contact: live-patching@vger.kernel.org +Description: + A writable attribute that allows administrator to affect the + course of an existing transition. Writing 1 sends a fake + signal to all remaining blocking tasks. The fake signal + means that no proper signal is delivered (there is no data in + signal pending structures). Tasks are interrupted or woken up, + and forced to change their patched state. + What: /sys/kernel/livepatch// Date: Nov 2014 KernelVersion: 3.19.0 diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index ecdb18104ab0..9bcdef277a36 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -176,8 +176,12 @@ If a patch is in transition, this file shows 0 to indicate the task is unpatched and 1 to indicate it's patched. Otherwise, if no patch is in transition, it shows -1. Any tasks which are blocking the transition can be signaled with SIGSTOP and SIGCONT to force them to change their -patched state. - +patched state. This may be harmful to the system though. +/sys/kernel/livepatch//signal attribute provides a better alternative. +Writing 1 to the attribute sends a fake signal to all remaining blocking +tasks. No proper signal is actually delivered (there is no data in signal +pending structures). Tasks are interrupted or woken up, and forced to change +their patched state. 3.1 Adding consistency model support to new architectures --------------------------------------------------------- @@ -435,6 +439,9 @@ Information about the registered patches can be found under /sys/kernel/livepatch. The patches could be enabled and disabled by writing there. +/sys/kernel/livepatch//signal attribute allows administrator to affect a +patching operation. + See Documentation/ABI/testing/sysfs-kernel-livepatch for more details. -- cgit From 404d1a3edc3873b339198ec3f3d6a09be2ddda4f Mon Sep 17 00:00:00 2001 From: Hans de Goede Date: Sat, 25 Nov 2017 20:35:48 +0100 Subject: drm: Add panel orientation quirks, v6. Some x86 clamshell design devices use portrait tablet screens and a display engine which cannot rotate in hardware, so the firmware just leaves things as is and we cannot figure out that the display is oriented non upright from the hardware. So at least on x86, we need a quirk table for this. This commit adds a DMI based quirk table which is initially populated with 5 such devices: Asus T100HA, GPD Pocket, GPD win, I.T.Works TW891 and the VIOS LTH17. This quirk table will be used by the drm code to let userspace know that the display is not mounted upright inside the devices case through a new panel orientation drm-connector property, as well as to tell fbcon to rotate the console so that it shows the right way up. Changes in v5: -Add a kernel-doc comment documenting drm_get_panel_orientation_quirk() -Remove board_* matches from the dmi-matches for the VIOS LTH17 laptop, keeping only the (identical) sys_vendor and product_name matches. This is necessary because an older version of the bios has board_vendor set to VOIS instead of VIOS Changes in v6: -Add reference to added kernel-docs in Documentation/gpu/drm-kms-helpers.rst Reviewed-by: Daniel Vetter Signed-off-by: Hans de Goede Link: https://patchwork.freedesktop.org/patch/msgid/20171125193553.23986-3-hdegoede@redhat.com --- Documentation/gpu/drm-kms-helpers.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 13dd237418cc..3ea622876b67 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -163,6 +163,9 @@ Panel Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_panel.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c + :export: + Display Port Helper Functions Reference ======================================= -- cgit From eaf2ea3156b658abf9ff9a8e2aa1aa71ec7bdcab Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 18 Nov 2017 17:46:59 -0800 Subject: scsi: fix another I2O typo Correct another typo I20 to I2O. Signed-off-by: Randy Dunlap Signed-off-by: Martin K. Petersen --- Documentation/driver-api/scsi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 9ae03171daca..87e9e0c0ecd8 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -332,5 +332,5 @@ todo ~~~~ Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, -FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports, +FireWire, ATAPI devices, Infiniband, I2O, iSCSI, Parallel ports, netlink... -- cgit From a52d97ca0d44b7f5096136afaa9714e973091ad3 Mon Sep 17 00:00:00 2001 From: Jian Hu Date: Mon, 4 Dec 2017 14:00:16 +0800 Subject: dt-bindings: pwm: Update bindings for the Meson-AXG Update the doc to explicitly support Meson-AXG Signed-off-by: Jian Hu Signed-off-by: Yixun Lan Reviewed-by: Rob Herring Signed-off-by: Thierry Reding --- Documentation/devicetree/bindings/pwm/pwm-meson.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pwm/pwm-meson.txt b/Documentation/devicetree/bindings/pwm/pwm-meson.txt index 1ee81321c35e..1fa3f7182133 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-meson.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-meson.txt @@ -5,6 +5,8 @@ Required properties: - compatible: Shall contain "amlogic,meson8b-pwm" or "amlogic,meson-gxbb-pwm" or "amlogic,meson-gxbb-ao-pwm" + or "amlogic,meson-axg-ee-pwm" + or "amlogic,meson-axg-ao-pwm" - #pwm-cells: Should be 3. See pwm.txt in this directory for a description of the cells format. -- cgit From b92ac66a1819602b1427ac72d4a70c10ba7640ad Mon Sep 17 00:00:00 2001 From: Sergei Shtylyov Date: Fri, 10 Nov 2017 20:59:01 +0300 Subject: pinctrl: sh-pfc: Add R8A77970 PFC support Add the PFC support for the R8A77970 SoC including pin groups for some on-chip devices such as CAN-FD, [H]SCIF, I2C, INTC-EX, MMC, MSIOF, PWM, VIN... Based on the original (and large) patch by Daisuke Matsushita . Signed-off-by: Vladimir Barinov Signed-off-by: Sergei Shtylyov Acked-by: Rob Herring [geert: Drop EtherAVB for now] Signed-off-by: Geert Uytterhoeven --- Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index 9b4f8041c36a..bb1790e0b176 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -24,6 +24,7 @@ Required Properties: - "renesas,pfc-r8a7794": for R8A7794 (R-Car E2) compatible pin-controller. - "renesas,pfc-r8a7795": for R8A7795 (R-Car H3) compatible pin-controller. - "renesas,pfc-r8a7796": for R8A7796 (R-Car M3-W) compatible pin-controller. + - "renesas,pfc-r8a77970": for R8A77970 (R-Car V3M) compatible pin-controller. - "renesas,pfc-r8a77995": for R8A77995 (R-Car D3) compatible pin-controller. - "renesas,pfc-sh73a0": for SH73A0 (SH-Mobile AG5) compatible pin-controller. -- cgit From 8796c8923d9c4297723ae51c832ea166964970c1 Mon Sep 17 00:00:00 2001 From: Russell King Date: Fri, 1 Dec 2017 10:24:47 +0000 Subject: phylink: add documentation for kernel APIs Add kernel-doc documentation for phylink kernel APIs, and link it into the networking kapi documentation under "Network device support". Signed-off-by: Russell King Reviewed-by: Florian Fainelli Signed-off-by: David S. Miller --- Documentation/networking/kapi.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/kapi.rst b/Documentation/networking/kapi.rst index 580289f345da..df4141b72f24 100644 --- a/Documentation/networking/kapi.rst +++ b/Documentation/networking/kapi.rst @@ -145,3 +145,15 @@ PHY Support .. kernel-doc:: drivers/net/phy/mdio_bus.c :internal: + +PHYLINK +------- + + PHYLINK interfaces traditional network drivers with PHYLIB, fixed-links, + and SFF modules (eg, hot-pluggable SFP) that may contain PHYs. PHYLINK + provides management of the link state and link modes. + +.. kernel-doc:: include/linux/phylink.h + :internal: + +.. kernel-doc:: drivers/net/phy/phylink.c -- cgit From 0a6fcd3fc14d3913966e9385d646bb05b5b47fae Mon Sep 17 00:00:00 2001 From: Russell King Date: Fri, 1 Dec 2017 10:24:53 +0000 Subject: sfp: add documentation for kernel APIs Add kernel-doc documentation for sfp kernel APIs, and link it into the networking kapi documentation under "Network device support". Signed-off-by: Russell King Reviewed-by: Florian Fainelli Signed-off-by: David S. Miller --- Documentation/networking/kapi.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/kapi.rst b/Documentation/networking/kapi.rst index df4141b72f24..f03ae64be8bc 100644 --- a/Documentation/networking/kapi.rst +++ b/Documentation/networking/kapi.rst @@ -157,3 +157,15 @@ PHYLINK :internal: .. kernel-doc:: drivers/net/phy/phylink.c + +SFP support +----------- + +.. kernel-doc:: drivers/net/phy/sfp-bus.c + :internal: + +.. kernel-doc:: include/linux/sfp.h + :internal: + +.. kernel-doc:: drivers/net/phy/sfp-bus.c + :export: -- cgit From bafbdd527d569c8200521f2f7579f65a044271be Mon Sep 17 00:00:00 2001 From: Sergei Shtylyov Date: Mon, 4 Dec 2017 13:35:05 +0100 Subject: phylib: Add device reset GPIO support The PHY devices sometimes do have their reset signal (maybe even power supply?) tied to some GPIO and sometimes it also does happen that a boot loader does not leave it deasserted. So far this issue has been attacked from (as I believe) a wrong angle: by teaching the MAC driver to manipulate the GPIO in question; that solution, when applied to the device trees, led to adding the PHY reset GPIO properties to the MAC device node, with one exception: Cadence MACB driver which could handle the "reset-gpios" prop in a PHY device subnode. I believe that the correct approach is to teach the 'phylib' to get the MDIO device reset GPIO from the device tree node corresponding to this device -- which this patch is doing... Note that I had to modify the AT803x PHY driver as it would stop working otherwise -- it made use of the reset GPIO for its own purposes... Signed-off-by: Sergei Shtylyov Acked-by: Rob Herring [geert: Propagate actual errors from fwnode_get_named_gpiod()] [geert: Avoid destroying initial setup] [geert: Consolidate GPIO descriptor acquiring code] Signed-off-by: Geert Uytterhoeven Tested-by: Richard Leitner Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/phy.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 77d0b2a61ffa..c05479f5ac7c 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -53,6 +53,8 @@ Optional Properties: to ensure the integrated PHY is used. The absence of this property indicates the muxers should be configured so that the external PHY is used. +- reset-gpios: The GPIO phandle and specifier for the PHY reset signal. + Example: ethernet-phy@0 { -- cgit From 34f15bf31e739af1e1b60c4fdc3e93b21ad9ff50 Mon Sep 17 00:00:00 2001 From: Daniel Borkmann Date: Wed, 6 Dec 2017 01:12:41 +0100 Subject: bpf, doc: add faq about bpf development process In the same spirit of netdev FAQ, start a BPF FAQ as a collection of expectations and/or workflow details in the context of BPF patch processing. Signed-off-by: Daniel Borkmann Acked-by: Alexei Starovoitov Signed-off-by: Alexei Starovoitov --- Documentation/bpf/bpf_devel_QA.txt | 519 +++++++++++++++++++++++++++++++++++++ 1 file changed, 519 insertions(+) create mode 100644 Documentation/bpf/bpf_devel_QA.txt (limited to 'Documentation') diff --git a/Documentation/bpf/bpf_devel_QA.txt b/Documentation/bpf/bpf_devel_QA.txt new file mode 100644 index 000000000000..cefef855dea4 --- /dev/null +++ b/Documentation/bpf/bpf_devel_QA.txt @@ -0,0 +1,519 @@ +This document provides information for the BPF subsystem about various +workflows related to reporting bugs, submitting patches, and queueing +patches for stable kernels. + +For general information about submitting patches, please refer to +Documentation/process/. This document only describes additional specifics +related to BPF. + +Reporting bugs: +--------------- + +Q: How do I report bugs for BPF kernel code? + +A: Since all BPF kernel development as well as bpftool and iproute2 BPF + loader development happens through the netdev kernel mailing list, + please report any found issues around BPF to the following mailing + list: + + netdev@vger.kernel.org + + This may also include issues related to XDP, BPF tracing, etc. + + Given netdev has a high volume of traffic, please also add the BPF + maintainers to Cc (from kernel MAINTAINERS file): + + Alexei Starovoitov + Daniel Borkmann + + In case a buggy commit has already been identified, make sure to keep + the actual commit authors in Cc as well for the report. They can + typically be identified through the kernel's git tree. + + Please do *not* report BPF issues to bugzilla.kernel.org since it + is a guarantee that the reported issue will be overlooked. + +Submitting patches: +------------------- + +Q: To which mailing list do I need to submit my BPF patches? + +A: Please submit your BPF patches to the netdev kernel mailing list: + + netdev@vger.kernel.org + + Historically, BPF came out of networking and has always been maintained + by the kernel networking community. Although these days BPF touches + many other subsystems as well, the patches are still routed mainly + through the networking community. + + In case your patch has changes in various different subsystems (e.g. + tracing, security, etc), make sure to Cc the related kernel mailing + lists and maintainers from there as well, so they are able to review + the changes and provide their Acked-by's to the patches. + +Q: Where can I find patches currently under discussion for BPF subsystem? + +A: All patches that are Cc'ed to netdev are queued for review under netdev + patchwork project: + + http://patchwork.ozlabs.org/project/netdev/list/ + + Those patches which target BPF, are assigned to a 'bpf' delegate for + further processing from BPF maintainers. The current queue with + patches under review can be found at: + + https://patchwork.ozlabs.org/project/netdev/list/?delegate=77147 + + Once the patches have been reviewed by the BPF community as a whole + and approved by the BPF maintainers, their status in patchwork will be + changed to 'Accepted' and the submitter will be notified by mail. This + means that the patches look good from a BPF perspective and have been + applied to one of the two BPF kernel trees. + + In case feedback from the community requires a respin of the patches, + their status in patchwork will be set to 'Changes Requested', and purged + from the current review queue. Likewise for cases where patches would + get rejected or are not applicable to the BPF trees (but assigned to + the 'bpf' delegate). + +Q: How do the changes make their way into Linux? + +A: There are two BPF kernel trees (git repositories). Once patches have + been accepted by the BPF maintainers, they will be applied to one + of the two BPF trees: + + https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git/ + https://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git/ + + The bpf tree itself is for fixes only, whereas bpf-next for features, + cleanups or other kind of improvements ("next-like" content). This is + analogous to net and net-next trees for networking. Both bpf and + bpf-next will only have a master branch in order to simplify against + which branch patches should get rebased to. + + Accumulated BPF patches in the bpf tree will regularly get pulled + into the net kernel tree. Likewise, accumulated BPF patches accepted + into the bpf-next tree will make their way into net-next tree. net and + net-next are both run by David S. Miller. From there, they will go + into the kernel mainline tree run by Linus Torvalds. To read up on the + process of net and net-next being merged into the mainline tree, see + the netdev FAQ under: + + Documentation/networking/netdev-FAQ.txt + + Occasionally, to prevent merge conflicts, we might send pull requests + to other trees (e.g. tracing) with a small subset of the patches, but + net and net-next are always the main trees targeted for integration. + + The pull requests will contain a high-level summary of the accumulated + patches and can be searched on netdev kernel mailing list through the + following subject lines (yyyy-mm-dd is the date of the pull request): + + pull-request: bpf yyyy-mm-dd + pull-request: bpf-next yyyy-mm-dd + +Q: How do I indicate which tree (bpf vs. bpf-next) my patch should be + applied to? + +A: The process is the very same as described in the netdev FAQ, so + please read up on it. The subject line must indicate whether the + patch is a fix or rather "next-like" content in order to let the + maintainers know whether it is targeted at bpf or bpf-next. + + For fixes eventually landing in bpf -> net tree, the subject must + look like: + + git format-patch --subject-prefix='PATCH bpf' start..finish + + For features/improvements/etc that should eventually land in + bpf-next -> net-next, the subject must look like: + + git format-patch --subject-prefix='PATCH bpf-next' start..finish + + If unsure whether the patch or patch series should go into bpf + or net directly, or bpf-next or net-next directly, it is not a + problem either if the subject line says net or net-next as target. + It is eventually up to the maintainers to do the delegation of + the patches. + + If it is clear that patches should go into bpf or bpf-next tree, + please make sure to rebase the patches against those trees in + order to reduce potential conflicts. + + In case the patch or patch series has to be reworked and sent out + again in a second or later revision, it is also required to add a + version number (v2, v3, ...) into the subject prefix: + + git format-patch --subject-prefix='PATCH net-next v2' start..finish + + When changes have been requested to the patch series, always send the + whole patch series again with the feedback incorporated (never send + individual diffs on top of the old series). + +Q: What does it mean when a patch gets applied to bpf or bpf-next tree? + +A: It means that the patch looks good for mainline inclusion from + a BPF point of view. + + Be aware that this is not a final verdict that the patch will + automatically get accepted into net or net-next trees eventually: + + On the netdev kernel mailing list reviews can come in at any point + in time. If discussions around a patch conclude that they cannot + get included as-is, we will either apply a follow-up fix or drop + them from the trees entirely. Therefore, we also reserve to rebase + the trees when deemed necessary. After all, the purpose of the tree + is to i) accumulate and stage BPF patches for integration into trees + like net and net-next, and ii) run extensive BPF test suite and + workloads on the patches before they make their way any further. + + Once the BPF pull request was accepted by David S. Miller, then + the patches end up in net or net-next tree, respectively, and + make their way from there further into mainline. Again, see the + netdev FAQ for additional information e.g. on how often they are + merged to mainline. + +Q: How long do I need to wait for feedback on my BPF patches? + +A: We try to keep the latency low. The usual time to feedback will + be around 2 or 3 business days. It may vary depending on the + complexity of changes and current patch load. + +Q: How often do you send pull requests to major kernel trees like + net or net-next? + +A: Pull requests will be sent out rather often in order to not + accumulate too many patches in bpf or bpf-next. + + As a rule of thumb, expect pull requests for each tree regularly + at the end of the week. In some cases pull requests could additionally + come also in the middle of the week depending on the current patch + load or urgency. + +Q: Are patches applied to bpf-next when the merge window is open? + +A: For the time when the merge window is open, bpf-next will not be + processed. This is roughly analogous to net-next patch processing, + so feel free to read up on the netdev FAQ about further details. + + During those two weeks of merge window, we might ask you to resend + your patch series once bpf-next is open again. Once Linus released + a v*-rc1 after the merge window, we continue processing of bpf-next. + + For non-subscribers to kernel mailing lists, there is also a status + page run by David S. Miller on net-next that provides guidance: + + http://vger.kernel.org/~davem/net-next.html + +Q: I made a BPF verifier change, do I need to add test cases for + BPF kernel selftests? + +A: If the patch has changes to the behavior of the verifier, then yes, + it is absolutely necessary to add test cases to the BPF kernel + selftests suite. If they are not present and we think they are + needed, then we might ask for them before accepting any changes. + + In particular, test_verifier.c is tracking a high number of BPF test + cases, including a lot of corner cases that LLVM BPF back end may + generate out of the restricted C code. Thus, adding test cases is + absolutely crucial to make sure future changes do not accidentally + affect prior use-cases. Thus, treat those test cases as: verifier + behavior that is not tracked in test_verifier.c could potentially + be subject to change. + +Q: When should I add code to samples/bpf/ and when to BPF kernel + selftests? + +A: In general, we prefer additions to BPF kernel selftests rather than + samples/bpf/. The rationale is very simple: kernel selftests are + regularly run by various bots to test for kernel regressions. + + The more test cases we add to BPF selftests, the better the coverage + and the less likely it is that those could accidentally break. It is + not that BPF kernel selftests cannot demo how a specific feature can + be used. + + That said, samples/bpf/ may be a good place for people to get started, + so it might be advisable that simple demos of features could go into + samples/bpf/, but advanced functional and corner-case testing rather + into kernel selftests. + + If your sample looks like a test case, then go for BPF kernel selftests + instead! + +Q: When should I add code to the bpftool? + +A: The main purpose of bpftool (under tools/bpf/bpftool/) is to provide + a central user space tool for debugging and introspection of BPF programs + and maps that are active in the kernel. If UAPI changes related to BPF + enable for dumping additional information of programs or maps, then + bpftool should be extended as well to support dumping them. + +Q: When should I add code to iproute2's BPF loader? + +A: For UAPI changes related to the XDP or tc layer (e.g. cls_bpf), the + convention is that those control-path related changes are added to + iproute2's BPF loader as well from user space side. This is not only + useful to have UAPI changes properly designed to be usable, but also + to make those changes available to a wider user base of major + downstream distributions. + +Q: Do you accept patches as well for iproute2's BPF loader? + +A: Patches for the iproute2's BPF loader have to be sent to: + + netdev@vger.kernel.org + + While those patches are not processed by the BPF kernel maintainers, + please keep them in Cc as well, so they can be reviewed. + + The official git repository for iproute2 is run by Stephen Hemminger + and can be found at: + + https://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git/ + + The patches need to have a subject prefix of '[PATCH iproute2 master]' + or '[PATCH iproute2 net-next]'. 'master' or 'net-next' describes the + target branch where the patch should be applied to. Meaning, if kernel + changes went into the net-next kernel tree, then the related iproute2 + changes need to go into the iproute2 net-next branch, otherwise they + can be targeted at master branch. The iproute2 net-next branch will get + merged into the master branch after the current iproute2 version from + master has been released. + + Like BPF, the patches end up in patchwork under the netdev project and + are delegated to 'shemminger' for further processing: + + http://patchwork.ozlabs.org/project/netdev/list/?delegate=389 + +Q: What is the minimum requirement before I submit my BPF patches? + +A: When submitting patches, always take the time and properly test your + patches *prior* to submission. Never rush them! If maintainers find + that your patches have not been properly tested, it is a good way to + get them grumpy. Testing patch submissions is a hard requirement! + + Note, fixes that go to bpf tree *must* have a Fixes: tag included. The + same applies to fixes that target bpf-next, where the affected commit + is in net-next (or in some cases bpf-next). The Fixes: tag is crucial + in order to identify follow-up commits and tremendously helps for people + having to do backporting, so it is a must have! + + We also don't accept patches with an empty commit message. Take your + time and properly write up a high quality commit message, it is + essential! + + Think about it this way: other developers looking at your code a month + from now need to understand *why* a certain change has been done that + way, and whether there have been flaws in the analysis or assumptions + that the original author did. Thus providing a proper rationale and + describing the use-case for the changes is a must. + + Patch submissions with >1 patch must have a cover letter which includes + a high level description of the series. This high level summary will + then be placed into the merge commit by the BPF maintainers such that + it is also accessible from the git log for future reference. + +Q: What do I need to consider when adding a new instruction or feature + that would require BPF JIT and/or LLVM integration as well? + +A: We try hard to keep all BPF JITs up to date such that the same user + experience can be guaranteed when running BPF programs on different + architectures without having the program punt to the less efficient + interpreter in case the in-kernel BPF JIT is enabled. + + If you are unable to implement or test the required JIT changes for + certain architectures, please work together with the related BPF JIT + developers in order to get the feature implemented in a timely manner. + Please refer to the git log (arch/*/net/) to locate the necessary + people for helping out. + + Also always make sure to add BPF test cases (e.g. test_bpf.c and + test_verifier.c) for new instructions, so that they can receive + broad test coverage and help run-time testing the various BPF JITs. + + In case of new BPF instructions, once the changes have been accepted + into the Linux kernel, please implement support into LLVM's BPF back + end. See LLVM section below for further information. + +Stable submission: +------------------ + +Q: I need a specific BPF commit in stable kernels. What should I do? + +A: In case you need a specific fix in stable kernels, first check whether + the commit has already been applied in the related linux-*.y branches: + + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/ + + If not the case, then drop an email to the BPF maintainers with the + netdev kernel mailing list in Cc and ask for the fix to be queued up: + + netdev@vger.kernel.org + + The process in general is the same as on netdev itself, see also the + netdev FAQ document. + +Q: Do you also backport to kernels not currently maintained as stable? + +A: No. If you need a specific BPF commit in kernels that are currently not + maintained by the stable maintainers, then you are on your own. + + The current stable and longterm stable kernels are all listed here: + + https://www.kernel.org/ + +Q: The BPF patch I am about to submit needs to go to stable as well. What + should I do? + +A: The same rules apply as with netdev patch submissions in general, see + netdev FAQ under: + + Documentation/networking/netdev-FAQ.txt + + Never add "Cc: stable@vger.kernel.org" to the patch description, but + ask the BPF maintainers to queue the patches instead. This can be done + with a note, for example, under the "---" part of the patch which does + not go into the git log. Alternatively, this can be done as a simple + request by mail instead. + +Q: Where do I find currently queued BPF patches that will be submitted + to stable? + +A: Once patches that fix critical bugs got applied into the bpf tree, they + are queued up for stable submission under: + + http://patchwork.ozlabs.org/bundle/bpf/stable/?state=* + + They will be on hold there at minimum until the related commit made its + way into the mainline kernel tree. + + After having been under broader exposure, the queued patches will be + submitted by the BPF maintainers to the stable maintainers. + +Testing patches: +---------------- + +Q: Which BPF kernel selftests version should I run my kernel against? + +A: If you run a kernel xyz, then always run the BPF kernel selftests from + that kernel xyz as well. Do not expect that the BPF selftest from the + latest mainline tree will pass all the time. + + In particular, test_bpf.c and test_verifier.c have a large number of + test cases and are constantly updated with new BPF test sequences, or + existing ones are adapted to verifier changes e.g. due to verifier + becoming smarter and being able to better track certain things. + +LLVM: +----- + +Q: Where do I find LLVM with BPF support? + +A: The BPF back end for LLVM is upstream in LLVM since version 3.7.1. + + All major distributions these days ship LLVM with BPF back end enabled, + so for the majority of use-cases it is not required to compile LLVM by + hand anymore, just install the distribution provided package. + + LLVM's static compiler lists the supported targets through 'llc --version', + make sure BPF targets are listed. Example: + + $ llc --version + LLVM (http://llvm.org/): + LLVM version 6.0.0svn + Optimized build. + Default target: x86_64-unknown-linux-gnu + Host CPU: skylake + + Registered Targets: + bpf - BPF (host endian) + bpfeb - BPF (big endian) + bpfel - BPF (little endian) + x86 - 32-bit X86: Pentium-Pro and above + x86-64 - 64-bit X86: EM64T and AMD64 + + For developers in order to utilize the latest features added to LLVM's + BPF back end, it is advisable to run the latest LLVM releases. Support + for new BPF kernel features such as additions to the BPF instruction + set are often developed together. + + All LLVM releases can be found at: http://releases.llvm.org/ + +Q: Got it, so how do I build LLVM manually anyway? + +A: You need cmake and gcc-c++ as build requisites for LLVM. Once you have + that set up, proceed with building the latest LLVM and clang version + from the git repositories: + + $ git clone http://llvm.org/git/llvm.git + $ cd llvm/tools + $ git clone --depth 1 http://llvm.org/git/clang.git + $ cd ..; mkdir build; cd build + $ cmake .. -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ + -DBUILD_SHARED_LIBS=OFF \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_BUILD_RUNTIME=OFF + $ make -j $(getconf _NPROCESSORS_ONLN) + + The built binaries can then be found in the build/bin/ directory, where + you can point the PATH variable to. + +Q: Should I notify BPF kernel maintainers about issues in LLVM's BPF code + generation back end or about LLVM generated code that the verifier + refuses to accept? + +A: Yes, please do! LLVM's BPF back end is a key piece of the whole BPF + infrastructure and it ties deeply into verification of programs from the + kernel side. Therefore, any issues on either side need to be investigated + and fixed whenever necessary. + + Therefore, please make sure to bring them up at netdev kernel mailing + list and Cc BPF maintainers for LLVM and kernel bits: + + Yonghong Song + Alexei Starovoitov + Daniel Borkmann + + LLVM also has an issue tracker where BPF related bugs can be found: + + https://bugs.llvm.org/buglist.cgi?quicksearch=bpf + + However, it is better to reach out through mailing lists with having + maintainers in Cc. + +Q: I have added a new BPF instruction to the kernel, how can I integrate + it into LLVM? + +A: LLVM has a -mcpu selector for the BPF back end in order to allow the + selection of BPF instruction set extensions. By default the 'generic' + processor target is used, which is the base instruction set (v1) of BPF. + + LLVM has an option to select -mcpu=probe where it will probe the host + kernel for supported BPF instruction set extensions and selects the + optimal set automatically. + + For cross-compilation, a specific version can be select manually as well. + + $ llc -march bpf -mcpu=help + Available CPUs for this target: + + generic - Select the generic processor. + probe - Select the probe processor. + v1 - Select the v1 processor. + v2 - Select the v2 processor. + [...] + + Newly added BPF instructions to the Linux kernel need to follow the same + scheme, bump the instruction set version and implement probing for the + extensions such that -mcpu=probe users can benefit from the optimization + transparently when upgrading their kernels. + + If you are unable to implement support for the newly added BPF instruction + please reach out to BPF developers for help. + + By the way, the BPF kernel selftests run with -mcpu=probe for better + test coverage. + +Happy BPF hacking! -- cgit From e3447a67c96f4456829bafb11d0fa05b790f56b3 Mon Sep 17 00:00:00 2001 From: Tirupathi Reddy Date: Tue, 21 Nov 2017 14:41:05 +0530 Subject: dt-bindings: Add qcom spmi_pmic clock divider bindings This patch adds device tree bindings for Qualcomm SPMI PMIC clock divider module. Signed-off-by: Tirupathi Reddy [sboyd: Moved file to match compatible of binding] Signed-off-by: Stephen Boyd --- .../devicetree/bindings/clock/qcom,spmi-clkdiv.txt | 59 ++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt b/Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt new file mode 100644 index 000000000000..7474aba36607 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,spmi-clkdiv.txt @@ -0,0 +1,59 @@ +Qualcomm Technologies, Inc. SPMI PMIC clock divider (clkdiv) + +clkdiv configures the clock frequency of a set of outputs on the PMIC. +These clocks are typically wired through alternate functions on +gpio pins. + +======================= +Properties +======================= + +- compatible + Usage: required + Value type: + Definition: must be "qcom,spmi-clkdiv". + +- reg + Usage: required + Value type: + Definition: base address of CLKDIV peripherals. + +- qcom,num-clkdivs + Usage: required + Value type: + Definition: number of CLKDIV peripherals. + +- clocks: + Usage: required + Value type: + Definition: reference to the xo clock. + +- clock-names: + Usage: required + Value type: + Definition: must be "xo". + +- #clock-cells: + Usage: required + Value type: + Definition: shall contain 1. + +======= +Example +======= + +pm8998_clk_divs: clock-controller@5b00 { + compatible = "qcom,spmi-clkdiv"; + reg = <0x5b00>; + #clock-cells = <1>; + qcom,num-clkdivs = <3>; + clocks = <&xo_board>; + clock-names = "xo"; + + assigned-clocks = <&pm8998_clk_divs 1>, + <&pm8998_clk_divs 2>, + <&pm8998_clk_divs 3>; + assigned-clock-rates = <9600000>, + <9600000>, + <9600000>; +}; -- cgit From a4a124c349cfbf731a649c1e7d3efab6e44831c9 Mon Sep 17 00:00:00 2001 From: Leo Yan Date: Fri, 17 Nov 2017 17:27:30 +0800 Subject: dt-bindings: clk: Hi3660: Document stub clock Document the DT binding for stub clock which is used for CPU, GPU and DDR frequency scaling. Acked-by: Rob Herring Signed-off-by: Leo Yan Signed-off-by: Stephen Boyd --- Documentation/devicetree/bindings/clock/hi3660-clock.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/hi3660-clock.txt b/Documentation/devicetree/bindings/clock/hi3660-clock.txt index 0035a7ecaf20..946da7cee54f 100644 --- a/Documentation/devicetree/bindings/clock/hi3660-clock.txt +++ b/Documentation/devicetree/bindings/clock/hi3660-clock.txt @@ -13,12 +13,18 @@ Required Properties: - "hisilicon,hi3660-pmuctrl" - "hisilicon,hi3660-sctrl" - "hisilicon,hi3660-iomcu" + - "hisilicon,hi3660-stub-clk" - reg: physical base address of the controller and length of memory mapped region. - #clock-cells: should be 1. +Optional Properties: + +- mboxes: Phandle to the mailbox for sending message to MCU. + (See: ../mailbox/hisilicon,hi3660-mailbox.txt for more info) + Each clock is assigned an identifier and client nodes use this identifier to specify the clock which they consume. -- cgit From ad63da85f45fa55c270e5681e9b985605ec51f8d Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Sat, 2 Dec 2017 12:23:09 +0100 Subject: pinctrl: gemini: Support drive strength setting The Gemini pin controller can set drive strength for a few select groups of pins (not individually). Implement this for GMAC0 and 1 (ethernet ports), IDE and PCI. Cc: devicetree@vger.kernel.org Reviewed-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt index d857b67fab72..4346ff2dd8e6 100644 --- a/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/cortina,gemini-pinctrl.txt @@ -17,6 +17,9 @@ and generic pin config nodes. Supported configurations: - skew-delay is supported on the Ethernet pins +- drive-strength with 4, 8, 12 or 16 mA as argument is supported for + entire groups on the groups "idegrp", "gmii_gmac0_grp", "gmii_gmac1_grp" + and "pcigrp". Example: -- cgit From f17aea430fff4b95ac94e8625096cd82544e9054 Mon Sep 17 00:00:00 2001 From: Quentin Schulz Date: Tue, 5 Dec 2017 15:46:42 +0100 Subject: dt-bindings: gpio: gpio-axp209: add pinctrl features The X-Powers AXP209 has 3 GPIOs. GPIO0/1 can each act either as a GPIO, an ADC or a LDO regulator. GPIO2 can only act as a GPIO. This adds the pinctrl features to the driver so GPIO0/1 can be used as ADC or LDO regulator. Signed-off-by: Quentin Schulz Acked-by: Rob Herring Acked-by: Maxime Ripard Signed-off-by: Linus Walleij --- .../devicetree/bindings/gpio/gpio-axp209.txt | 36 +++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt index a6611304dd3c..0d77597c3f92 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt @@ -1,8 +1,13 @@ -AXP209 GPIO controller +AXP209 GPIO & pinctrl controller This driver follows the usual GPIO bindings found in Documentation/devicetree/bindings/gpio/gpio.txt +This driver follows the usual pinctrl bindings found in +Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + +This driver employs the per-pin muxing pattern. + Required properties: - compatible: Should be "x-powers,axp209-gpio" - #gpio-cells: Should be two. The first cell is the pin number and the @@ -28,3 +33,32 @@ axp209: pmic@34 { #gpio-cells = <2>; }; }; + +The GPIOs can be muxed to other functions and therefore, must be a subnode of +axp_gpio. + +Example: + +&axp_gpio { + gpio0_adc: gpio0-adc { + pins = "GPIO0"; + function = "adc"; + }; +}; + +&example_node { + pinctrl-names = "default"; + pinctrl-0 = <&gpio0_adc>; +}; + +GPIOs and their functions +------------------------- + +Each GPIO is independent from the other (i.e. GPIO0 in gpio_in function does +not force GPIO1 and GPIO2 to be in gpio_in function as well). + +GPIO | Functions +------------------------ +GPIO0 | gpio_in, gpio_out, ldo, adc +GPIO1 | gpio_in, gpio_out, ldo, adc +GPIO2 | gpio_in, gpio_out -- cgit From e1190083b89bd0d53c83b647ff313d9f004c6772 Mon Sep 17 00:00:00 2001 From: Quentin Schulz Date: Tue, 5 Dec 2017 15:46:46 +0100 Subject: pinctrl: axp209: add support for AXP813 GPIOs The AXP813 has only two GPIOs. GPIO0 can either be used as a GPIO, an LDO regulator or an ADC. GPIO1 can be used either as a GPIO or an LDO regulator. Moreover, the status bit of the GPIOs when in input mode is not offset by 4 unlike the AXP209. Signed-off-by: Quentin Schulz Acked-by: Maxime Ripard Acked-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/gpio/gpio-axp209.txt | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt index 0d77597c3f92..fc42b2caa06d 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt @@ -9,7 +9,9 @@ Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt This driver employs the per-pin muxing pattern. Required properties: -- compatible: Should be "x-powers,axp209-gpio" +- compatible: Should be one of: + - "x-powers,axp209-gpio" + - "x-powers,axp813-gpio" - #gpio-cells: Should be two. The first cell is the pin number and the second is the GPIO flags. - gpio-controller: Marks the device node as a GPIO controller. @@ -57,8 +59,17 @@ GPIOs and their functions Each GPIO is independent from the other (i.e. GPIO0 in gpio_in function does not force GPIO1 and GPIO2 to be in gpio_in function as well). +axp209 +------ GPIO | Functions ------------------------ GPIO0 | gpio_in, gpio_out, ldo, adc GPIO1 | gpio_in, gpio_out, ldo, adc GPIO2 | gpio_in, gpio_out + +axp813 +------ +GPIO | Functions +------------------------ +GPIO0 | gpio_in, gpio_out, ldo, adc +GPIO1 | gpio_in, gpio_out, ldo -- cgit From c99a2be790b07752d8cc694434d3450afd4c5a00 Mon Sep 17 00:00:00 2001 From: Miroslav Benes Date: Wed, 22 Nov 2017 11:29:21 +0100 Subject: livepatch: force transition to finish If a task sleeps in a set of patched functions uninterruptedly, it could block the whole transition indefinitely. Thus it may be useful to clear its TIF_PATCH_PENDING to allow the process to finish. Admin can do that now by writing to force sysfs attribute in livepatch sysfs directory. TIF_PATCH_PENDING is then cleared for all tasks and the transition can finish successfully. Important note! Administrator should not use this feature without a clearance from a patch distributor. It must be checked that by doing so the consistency model guarantees are not violated. Removal (rmmod) of patch modules is permanently disabled when the feature is used. It cannot be guaranteed there is no task sleeping in such module. Signed-off-by: Miroslav Benes Acked-by: Josh Poimboeuf Reviewed-by: Petr Mladek Signed-off-by: Jiri Kosina --- Documentation/ABI/testing/sysfs-kernel-livepatch | 14 ++++++++++++++ Documentation/livepatch/livepatch.txt | 18 ++++++++++++++++-- 2 files changed, 30 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index 3bb9d5bc1ce3..dac7e1e62a8b 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -45,6 +45,20 @@ Description: signal pending structures). Tasks are interrupted or woken up, and forced to change their patched state. +What: /sys/kernel/livepatch//force +Date: Nov 2017 +KernelVersion: 4.15.0 +Contact: live-patching@vger.kernel.org +Description: + A writable attribute that allows administrator to affect the + course of an existing transition. Writing 1 clears + TIF_PATCH_PENDING flag of all tasks and thus forces the tasks to + the patched or unpatched state. Administrator should not + use this feature without a clearance from a patch + distributor. Removal (rmmod) of patch modules is permanently + disabled when the feature is used. See + Documentation/livepatch/livepatch.txt for more information. + What: /sys/kernel/livepatch// Date: Nov 2014 KernelVersion: 3.19.0 diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index 9bcdef277a36..896ba8941702 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -183,6 +183,20 @@ tasks. No proper signal is actually delivered (there is no data in signal pending structures). Tasks are interrupted or woken up, and forced to change their patched state. +Administrator can also affect a transition through +/sys/kernel/livepatch//force attribute. Writing 1 there clears +TIF_PATCH_PENDING flag of all tasks and thus forces the tasks to the patched +state. Important note! The force attribute is intended for cases when the +transition gets stuck for a long time because of a blocking task. Administrator +is expected to collect all necessary data (namely stack traces of such blocking +tasks) and request a clearance from a patch distributor to force the transition. +Unauthorized usage may cause harm to the system. It depends on the nature of the +patch, which functions are (un)patched, and which functions the blocking tasks +are sleeping in (/proc//stack may help here). Removal (rmmod) of patch +modules is permanently disabled when the force feature is used. It cannot be +guaranteed there is no task sleeping in such module. It implies unbounded +reference count if a patch module is disabled and enabled in a loop. + 3.1 Adding consistency model support to new architectures --------------------------------------------------------- @@ -439,8 +453,8 @@ Information about the registered patches can be found under /sys/kernel/livepatch. The patches could be enabled and disabled by writing there. -/sys/kernel/livepatch//signal attribute allows administrator to affect a -patching operation. +/sys/kernel/livepatch//signal and /sys/kernel/livepatch//force +attributes allow administrator to affect a patching operation. See Documentation/ABI/testing/sysfs-kernel-livepatch for more details. -- cgit From 9402f8eb9bed7a3dc6ff776dfa7f0b78750f21ed Mon Sep 17 00:00:00 2001 From: Felix Fietkau Date: Tue, 21 Nov 2017 10:50:51 +0100 Subject: dt-bindings: net: add mt76 wireless device binding Add documentation describing how device tree can be used to configure wireless chips supported by the mt76 driver. Signed-off-by: Felix Fietkau Signed-off-by: Kalle Valo --- .../bindings/net/wireless/mediatek,mt76.txt | 32 ++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt new file mode 100644 index 000000000000..0c17a0ec9b7b --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt @@ -0,0 +1,32 @@ +* MediaTek mt76xx devices + +This node provides properties for configuring the MediaTek mt76xx wireless +device. The node is expected to be specified as a child node of the PCI +controller to which the wireless chip is connected. + +Optional properties: + +- mac-address: See ethernet.txt in the parent directory +- local-mac-address: See ethernet.txt in the parent directory +- ieee80211-freq-limit: See ieee80211.txt +- mediatek,mtd-eeprom: Specify a MTD partition + offset containing EEPROM data + +Optional nodes: +- led: Properties for a connected LED + Optional properties: + - led-sources: See Documentation/devicetree/bindings/leds/common.txt + +&pcie { + pcie0 { + wifi@0,0 { + compatible = "mediatek,mt76"; + reg = <0x0000 0 0 0 0>; + ieee80211-freq-limit = <5000000 6000000>; + mediatek,mtd-eeprom = <&factory 0x8000>; + + led { + led-sources = <2>; + }; + }; + }; +}; -- cgit From 942fc649a3bebdf9a4a0e21dc6631ba3fea28d54 Mon Sep 17 00:00:00 2001 From: Neil Armstrong Date: Wed, 6 Dec 2017 12:54:25 +0100 Subject: dt-bindings: display: amlogic, meson-vpu: Add optional power domain property The Video Processing Unit power domain was setup by the Vendor U-Boot, add support for an optional Power Domain phandle to setup it from the kernel. Acked-by: Rob Herring Signed-off-by: Neil Armstrong Tested-by: Jerome Brunet Reviewed-by: Jerome Brunet Link: https://patchwork.freedesktop.org/patch/msgid/1512561268-29806-2-git-send-email-narmstrong@baylibre.com --- Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt index 00f74bad1e95..057b81335775 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt @@ -64,6 +64,10 @@ Required properties: - reg-names: should contain the names of the previous memory regions - interrupts: should contain the VENC Vsync interrupt number +Optional properties: +- power-domains: Optional phandle to associated power domain as described in + the file ../power/power_domain.txt + Required nodes: The connections to the VPU output video ports are modeled using the OF graph -- cgit From 133e8ee9a1e8dd9be3ba92ab88f73df507c3ce37 Mon Sep 17 00:00:00 2001 From: Neil Armstrong Date: Wed, 6 Dec 2017 12:54:26 +0100 Subject: dt-bindings: display: amlogic, meson-dw-hdmi: Add optional HDMI 5V regulator On reference boards and derivatives, the HDMI Logic is powered by an external 5V regulator. This regulator was set by the Vendor U-Boot, add optional support for it. Acked-by: Rob Herring Signed-off-by: Neil Armstrong Tested-by: Jerome Brunet Reviewed-by: Jerome Brunet Link: https://patchwork.freedesktop.org/patch/msgid/1512561268-29806-3-git-send-email-narmstrong@baylibre.com --- Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt index 7f040edc16fe..bf4a18047309 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-dw-hdmi.txt @@ -48,6 +48,10 @@ Required properties: Documentation/devicetree/bindings/reset/reset.txt, the reset-names should be "hdmitx_apb", "hdmitx", "hdmitx_phy" +Optional properties: +- hdmi-supply: Optional phandle to an external 5V regulator to power the HDMI + logic, as described in the file ../regulator/regulator.txt + Required nodes: The connections to the HDMI ports are modeled using the OF graph -- cgit From f550f2dd7c7e881eb296c2fa4e5f0bebeb4311c9 Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Sun, 12 Nov 2017 06:27:29 -0500 Subject: media: dt-bindings: et8ek8: Document support for flash and lens devices Document dts support of LED/focus. Signed-off-by: Pavel Machek Reviewed-by: Sebastian Reichel Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt b/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt index 0b7b6a4d84ff..e80d5891b7ed 100644 --- a/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt +++ b/Documentation/devicetree/bindings/media/i2c/toshiba,et8ek8.txt @@ -20,6 +20,13 @@ Mandatory properties is in hardware standby mode when the signal is in the low state. +Optional properties +------------------- + +- flash-leds: See ../video-interfaces.txt +- lens-focus: See ../video-interfaces.txt + + Endpoint node mandatory properties ---------------------------------- -- cgit From e0fc62a6552f3d9c21e73cc65844f9aad1892cf7 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Tue, 26 Sep 2017 20:27:09 +0200 Subject: w1: w1-gpio: Convert to use GPIO descriptors The w1 master driver includes a complete open drain emulation reimplementation among other things. This converts the driver and all board files using it to use GPIO descriptors associated with the device to look up the GPIO wire, as well ass the optional pull-up GPIO line. When probed from the device tree, the driver will just pick descriptors and use them right off. For the two board files in the kernel, we add descriptor lookups so we do not need to keep any old platform data handling around for the GPIO lines. As the platform data is also a state container for this driver, we augment it to contain the GPIO descriptors. w1_gpio_write_bit_dir() and w1_gpio_write_bit_val() are gone since this pair was a reimplementation of open drain emulation which is now handled by gpiolib. The special "linux,open-drain" flag is a bit of mishap here: it has the same semantic as the same flags in I2C: it means that something in the platform is setting up the line as open drain behind our back. We handle this the same way as in I2C. To drive the pull-up, we need to bypass open drain emulation in gpiolib for the line, and this is done by driving it high using gpiod_set_raw_value() which has been augmented to have the semantic of overriding the open drain emulation. We also augment the documentation to reflect the way to pass GPIO descriptors from the machine. Acked-by: Evgeniy Polyakov Signed-off-by: Linus Walleij --- Documentation/w1/masters/w1-gpio | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio index af5d3b4aa851..623961d9e83f 100644 --- a/Documentation/w1/masters/w1-gpio +++ b/Documentation/w1/masters/w1-gpio @@ -8,17 +8,27 @@ Description ----------- GPIO 1-wire bus master driver. The driver uses the GPIO API to control the -wire and the GPIO pin can be specified using platform data. +wire and the GPIO pin can be specified using GPIO machine descriptor tables. +It is also possible to define the master using device tree, see +Documentation/devicetree/bindings/w1/w1-gpio.txt Example (mach-at91) ------------------- +#include #include +static struct gpiod_lookup_table foo_w1_gpiod_table = { + .dev_id = "w1-gpio", + .table = { + GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0, + GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN), + }, +}; + static struct w1_gpio_platform_data foo_w1_gpio_pdata = { - .pin = AT91_PIN_PB20, - .is_open_drain = 1, + .ext_pullup_enable_pin = -EINVAL, }; static struct platform_device foo_w1_device = { @@ -30,4 +40,5 @@ static struct platform_device foo_w1_device = { ... at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1); at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1); + gpiod_add_lookup_table(&foo_w1_gpiod_table); platform_device_register(&foo_w1_device); -- cgit From b84cf26924cfe405993fc45fa2911cde38f3c3ac Mon Sep 17 00:00:00 2001 From: Mike Snitzer Date: Mon, 4 Dec 2017 10:26:21 -0500 Subject: dm raid: bump target version to reflect numerous fixes Also update Documentation accordingly. Signed-off-by: Mike Snitzer --- Documentation/device-mapper/dm-raid.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index 32df07e29f68..7b22375091fa 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -343,5 +343,7 @@ Version History 1.11.0 Fix table line argument order (wrong raid10_copies/raid10_format sequence) 1.11.1 Add raid4/5/6 journal write-back support via journal_mode option -1.12.1 fix for MD deadlock between mddev_suspend() and md_write_start() available +1.12.1 Fix for MD deadlock between mddev_suspend() and md_write_start() available 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A') +1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an + state races. -- cgit From 15ae0be9c671e912a6749d821bc69ccfff766c19 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Thu, 23 Nov 2017 09:05:06 -0500 Subject: media: cec-core.rst: document the new adap_monitor_pin_enable op Document what this op does. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/cec-core.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'Documentation') diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index d37e107f2fde..62b9a1448177 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -103,6 +103,7 @@ your driver: /* Low-level callbacks */ int (*adap_enable)(struct cec_adapter *adap, bool enable); int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, u32 signal_free_time, struct cec_msg *msg); @@ -144,6 +145,19 @@ called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional Note that adap_monitor_all_enable must return 0 if enable is false. +To enable/disable the 'monitor pin' mode: + +.. c:function:: + int (*adap_monitor_pin_enable)(struct cec_adapter *adap, bool enable); + +If enabled, then the adapter should be put in a mode to also monitor CEC pin +changes. Not all hardware supports this and this function is only called if +the CEC_CAP_MONITOR_PIN capability is set. This callback is optional +(some hardware may always be in 'monitor pin' mode). + +Note that adap_monitor_pin_enable must return 0 if enable is false. + + To program a new logical address: .. c:function:: -- cgit From 5fd29937dec4b64aa91a3207742cd8c720cd0595 Mon Sep 17 00:00:00 2001 From: Fabrizio Castro Date: Fri, 8 Dec 2017 17:59:06 +0200 Subject: dt-bindings: usb-xhci: Document r8a7743 support Document r8a7743 xhci support. The driver will use the fallback compatible string "renesas,rcar-gen2-xhci", therefore no driver change is needed. Signed-off-by: Fabrizio Castro Reviewed-by: Yoshihiro Shimoda Signed-off-by: Mathias Nyman Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/usb/usb-xhci.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index ae6e484a8d7c..a53107132cc3 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -7,12 +7,14 @@ Required properties: - "marvell,armada3700-xhci" for Armada 37xx SoCs - "marvell,armada-375-xhci" for Armada 375 SoCs - "marvell,armada-380-xhci" for Armada 38x SoCs + - "renesas,xhci-r8a7743" for r8a7743 SoC - "renesas,xhci-r8a7790" for r8a7790 SoC - "renesas,xhci-r8a7791" for r8a7791 SoC - "renesas,xhci-r8a7793" for r8a7793 SoC - "renesas,xhci-r8a7795" for r8a7795 SoC - "renesas,xhci-r8a7796" for r8a7796 SoC - - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 compatible device + - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 or RZ/G1 compatible + device - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 compatible device - "xhci-platform" (deprecated) -- cgit From dfba2174dc421ecad8dc50741054a305cd3ba681 Mon Sep 17 00:00:00 2001 From: Lu Baolu Date: Fri, 8 Dec 2017 17:59:10 +0200 Subject: usb: xhci: Add DbC support in xHCI driver xHCI compatible USB host controllers(i.e. super-speed USB3 controllers) can be implemented with the Debug Capability(DbC). It presents a debug device which is fully compliant with the USB framework and provides the equivalent of a very high performance full-duplex serial link. The debug capability operation model and registers interface are defined in 7.6.8 of the xHCI specification, revision 1.1. The DbC debug device shares a root port with the xHCI host. By default, the debug capability is disabled and the root port is assigned to xHCI. When the DbC is enabled, the root port will be assigned to the DbC debug device, and the xHCI sees nothing on this port. This implementation uses a sysfs node named under the xHCI device to manage the enabling and disabling of the debug capability. When the debug capability is enabled, it will present a debug device through the debug port. This debug device is fully compliant with the USB3 framework, and it can be enumerated by a debug host on the other end of the USB link. As soon as the debug device is configured, a TTY serial device named /dev/ttyDBC0 will be created. Signed-off-by: Lu Baolu Signed-off-by: Mathias Nyman Signed-off-by: Greg Kroah-Hartman --- .../ABI/testing/sysfs-bus-pci-drivers-xhci_hcd | 25 ++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd new file mode 100644 index 000000000000..0088aba4caa8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-xhci_hcd @@ -0,0 +1,25 @@ +What: /sys/bus/pci/drivers/xhci_hcd/.../dbc +Date: June 2017 +Contact: Lu Baolu +Description: + xHCI compatible USB host controllers (i.e. super-speed + USB3 controllers) are often implemented with the Debug + Capability (DbC). It can present a debug device which + is fully compliant with the USB framework and provides + the equivalent of a very high performance full-duplex + serial link for debug purpose. + + The DbC debug device shares a root port with xHCI host. + When the DbC is enabled, the root port will be assigned + to the Debug Capability. Otherwise, it will be assigned + to xHCI. + + Writing "enable" to this attribute will enable the DbC + functionality and the shared root port will be assigned + to the DbC device. Writing "disable" to this attribute + will disable the DbC functionality and the shared root + port will roll back to the xHCI. + + Reading this attribute gives the state of the DbC. It + can be one of the following states: disabled, enabled, + initialized, connected, configured and stalled. -- cgit From ab725cbec3e83dc29cc00b733bd26063b588fa98 Mon Sep 17 00:00:00 2001 From: Adam Wallis Date: Fri, 8 Dec 2017 17:59:13 +0200 Subject: usb: xhci: allow imod-interval to be configurable The xHCI driver currently has the IMOD set to 160, which translates to an IMOD interval of 40,000ns (160 * 250)ns Commit 0cbd4b34cda9 ("xhci: mediatek: support MTK xHCI host controller") introduced a QUIRK for the MTK platform to adjust this interval to 20, which translates to an IMOD interval of 5,000ns (20 * 250)ns. This is due to the fact that the MTK controller IMOD interval is 8 times as much as defined in xHCI spec. Instead of adding more quirk bits for additional platforms, this patch introduces the ability for vendors to set the IMOD_INTERVAL as is optimal for their platform. By using device_property_read_u32() on "imod-interval-ns", the IMOD INTERVAL can be specified in nano seconds. If no interval is specified, the default of 40,000ns (IMOD=160) will be used. No bounds checking has been implemented due to the fact that a vendor may have violated the spec and would need to specify a value outside of the max 8,000 IRQs/second limit specified in the xHCI spec. Tested-by: Chunfeng Yun Reviewed-by: Rob Herring Signed-off-by: Adam Wallis Signed-off-by: Mathias Nyman Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt | 2 ++ Documentation/devicetree/bindings/usb/usb-xhci.txt | 1 + 2 files changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt index 30595964876a..9ff560298498 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt @@ -46,6 +46,7 @@ Optional properties: - pinctrl-names : a pinctrl state named "default" must be defined - pinctrl-0 : pin control group See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + - imod-interval-ns: default interrupt moderation interval is 5000ns Example: usb30: usb@11270000 { @@ -66,6 +67,7 @@ usb30: usb@11270000 { usb3-lpm-capable; mediatek,syscon-wakeup = <&pericfg>; mediatek,wakeup-src = <1>; + imod-interval-ns = <10000>; }; 2nd: dual-role mode with xHCI driver diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index a53107132cc3..e2ea59bbca93 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -31,6 +31,7 @@ Optional properties: - usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM - usb3-lpm-capable: determines if platform is USB3 LPM capable - quirk-broken-port-ped: set if the controller has broken port disable mechanism + - imod-interval-ns: default interrupt moderation interval is 5000ns Example: usb@f0931000 { -- cgit From 16e791e7659645e6d8ea6286d210a24ee473d6c2 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Fri, 8 Dec 2017 11:53:37 -0200 Subject: doc: usb: chipidea: Fix typo in 'enumerate' Fix the spelling of 'enumerate' in this document. Signed-off-by: Fabio Estevam Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/chipidea.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt index edf7cdfddc88..d1eedc01b00a 100644 --- a/Documentation/usb/chipidea.txt +++ b/Documentation/usb/chipidea.txt @@ -23,13 +23,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers 2) Connect 2 boards with usb cable with one end is micro A plug, the other end is micro B plug. - The A-device(with micro A plug inserted) should enumrate B-device. + The A-device(with micro A plug inserted) should enumerate B-device. 3) Role switch On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - B-device should take host role and enumrate A-device. + B-device should take host role and enumerate A-device. 4) A-device switch back to host. On B-device: @@ -40,13 +40,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers side by answering the polling from B-Host, this can be done on A-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - A-device should switch back to host and enumrate B-device. + A-device should switch back to host and enumerate B-device. 5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, - A-device should enumrate B-device again. + A-device should enumerate B-device again. 6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, - A-device should NOT enumrate B-device. + A-device should NOT enumerate B-device. if A-device wants to use bus: On A-device: @@ -67,7 +67,7 @@ cat /sys/kernel/debug/ci_hdrc.0/registers On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - A-device should resume usb bus and enumrate B-device. + A-device should resume usb bus and enumerate B-device. 1.3 Reference document ---------------------- -- cgit From 70a39e1075019eef753649ac01ed594ac9016be6 Mon Sep 17 00:00:00 2001 From: Pavel Machek Date: Fri, 10 Nov 2017 11:39:37 +0100 Subject: Add support for bq27521 battery monitor This adds basic support for BQ27521 battery monitor, used in Nokia N9 and N950. In particular, battery voltage is important to be able to tell when the battery is almost empty. Emptying battery on N950 is pretty painful, as flasher needs to be used to recover phone in such case. Signed-off-by: Pavel Machek Acked-by: Andrew F. Davis Acked-by: Rob Herring Signed-off-by: Sebastian Reichel --- Documentation/devicetree/bindings/power/supply/bq27xxx.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/supply/bq27xxx.txt b/Documentation/devicetree/bindings/power/supply/bq27xxx.txt index 6858e1a804ad..615c1cb6889f 100644 --- a/Documentation/devicetree/bindings/power/supply/bq27xxx.txt +++ b/Documentation/devicetree/bindings/power/supply/bq27xxx.txt @@ -15,6 +15,7 @@ Required properties: * "ti,bq27520g2" - BQ27520-g2 * "ti,bq27520g3" - BQ27520-g3 * "ti,bq27520g4" - BQ27520-g4 + * "ti,bq27521" - BQ27521 * "ti,bq27530" - BQ27530 * "ti,bq27531" - BQ27531 * "ti,bq27541" - BQ27541 -- cgit From d3820952ea1b49f46e340e2d366b080d3ddeea65 Mon Sep 17 00:00:00 2001 From: Noralf Trønnes Date: Fri, 8 Dec 2017 20:37:42 +0100 Subject: drm/tinydrm: Use drm_fb_cma_fbdev_init_with_funcs/fini() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use drm_fb_cma_fbdev_init_with_funcs() and drm_fb_cma_fbdev_fini() which relies on the fact that drm_device holds a pointer to the drm_fb_helper structure. This means that the driver doesn't have to keep track of that. Also use the drm_fb_helper functions directly. Remove todo entry. Cc: David Lechner Signed-off-by: Noralf Trønnes Acked-by: David Lechner Acked-by: Daniel Vetter Tested-by: David Lechner Link: https://patchwork.freedesktop.org/patch/msgid/20171208193743.34450-11-noralf@tronnes.org --- Documentation/gpu/todo.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index af614746d9c5..f421a54527d2 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -395,11 +395,6 @@ those drivers as simple as possible, so lots of room for refactoring: one of the ideas for having a shared dsi/dbi helper, abstracting away the transport details more. -- tinydrm_lastclose could be drm_fb_helper_lastclose. Only thing we need - for that is to store the drm_fb_helper pointer somewhere in - drm_device->mode_config. And then we could roll that out to all the - drivers. - - tinydrm_gem_cma_prime_import_sg_table should probably go into the cma helpers, as a _vmapped variant (since not every driver needs the vmap). And tinydrm_gem_cma_free_object could the be merged into -- cgit From 42bf02ec6e420e541af9a47437d0bdf961ca2972 Mon Sep 17 00:00:00 2001 From: Roger Quadros Date: Tue, 31 Oct 2017 15:11:55 +0200 Subject: usb: dwc3: Allow disabling of metastability workaround Some platforms (e.g. TI's DRA7 USB2 instance) have more trouble with the metastability workaround as it supports only a High-Speed PHY and the PHY can enter into an Erratic state [1] when the controller is set in SuperSpeed mode as part of the metastability workaround. This causes upto 2 seconds delay in enumeration on DRA7's USB2 instance in gadget mode. If these platforms can be better off without the workaround, provide a device tree property to suggest that so the workaround is avoided. [1] Device mode enumeration trace showing PHY Erratic Error. irq/90-dwc3-969 [000] d... 52.323145: dwc3_event: event (00000901): Erratic Error [U0] irq/90-dwc3-969 [000] d... 52.560646: dwc3_event: event (00000901): Erratic Error [U0] irq/90-dwc3-969 [000] d... 52.798144: dwc3_event: event (00000901): Erratic Error [U0] Signed-off-by: Roger Quadros Signed-off-by: Felipe Balbi --- Documentation/devicetree/bindings/usb/dwc3.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 52fb41046b34..44e8bab159ad 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -47,6 +47,8 @@ Optional properties: from P0 to P1/P2/P3 without delay. - snps,dis-tx-ipgap-linecheck-quirk: when set, disable u2mac linestate check during HS transmit. + - snps,dis_metastability_quirk: when set, disable metastability workaround. + CAUTION: use only if you are absolutely sure of it. - snps,is-utmi-l1-suspend: true when DWC3 asserts output signal utmi_l1_suspend_n, false when asserts utmi_sleep_n - snps,hird-threshold: HIRD threshold -- cgit From 24fd3190817e96b2a57531986bfb6e951df3ee96 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Fri, 8 Dec 2017 12:11:33 -0200 Subject: dt-bindings: fec: Make the phy-reset-gpio polarity explicit The GPIO polarity passed to phy-reset-gpio is ignored by the FEC driver and it is assumed to be active low. It can be active high only when the 'phy-reset-active-high' property is present. The current examples pass active high polarity and work fine, but in order to improve the documentation make it explicit what the real polarity is. Signed-off-by: Fabio Estevam Acked-by: Fugang Duan Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/fsl-fec.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt index f0dc94409107..2d41fb96ce0a 100644 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ b/Documentation/devicetree/bindings/net/fsl-fec.txt @@ -59,7 +59,7 @@ ethernet@83fec000 { reg = <0x83fec000 0x4000>; interrupts = <87>; phy-mode = "mii"; - phy-reset-gpios = <&gpio2 14 0>; /* GPIO2_14 */ + phy-reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; /* GPIO2_14 */ local-mac-address = [00 04 9F 01 1B B9]; phy-supply = <®_fec_supply>; }; @@ -71,7 +71,7 @@ ethernet@83fec000 { reg = <0x83fec000 0x4000>; interrupts = <87>; phy-mode = "mii"; - phy-reset-gpios = <&gpio2 14 0>; /* GPIO2_14 */ + phy-reset-gpios = <&gpio2 14 GPIO_ACTIVE_LOW>; /* GPIO2_14 */ local-mac-address = [00 04 9F 01 1B B9]; phy-supply = <®_fec_supply>; phy-handle = <ðphy>; -- cgit From 19326ef0874e8fdcf4d6d6fe97e85b2dac69a954 Mon Sep 17 00:00:00 2001 From: Akinobu Mita Date: Thu, 12 Oct 2017 12:03:34 -0400 Subject: media: dt-bindings: media: xilinx: fix typo in example Fix typo s/:/;/ Cc: Rob Herring Cc: Hyun Kwon Signed-off-by: Akinobu Mita Acked-by: Rob Herring Reviewed-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt b/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt index 9dd86b3db937..439351ab2a79 100644 --- a/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt +++ b/Documentation/devicetree/bindings/media/xilinx/xlnx,v-tpg.txt @@ -66,6 +66,6 @@ Example: tpg1_out: endpoint { remote-endpoint = <&switch_in0>; }; - }: + }; }; }; -- cgit From ae1ba1676b88e6c62368a433c7e2d0417e9879fd Mon Sep 17 00:00:00 2001 From: Matthew Garrett Date: Tue, 7 Nov 2017 07:18:35 -0800 Subject: EVM: Allow userland to permit modification of EVM-protected metadata When EVM is enabled it forbids modification of metadata protected by EVM unless there is already a valid EVM signature. If any modification is made, the kernel will then generate a new EVM HMAC. However, this does not map well on use cases which use only asymmetric EVM signatures, as in this scenario the kernel is unable to generate new signatures. This patch extends the /sys/kernel/security/evm interface to allow userland to request that modification of these xattrs be permitted. This is only permitted if no keys have already been loaded. In this configuration, modifying the metadata will invalidate the EVM appraisal on the file in question. This allows packaging systems to write out new files, set the relevant extended attributes and then move them into place. There's also some refactoring of the use of evm_initialized in order to avoid heading down codepaths that assume there's a key available. Signed-off-by: Matthew Garrett Signed-off-by: Mimi Zohar --- Documentation/ABI/testing/evm | 54 ++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 19 deletions(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm index 9578247e1792..d12cb2eae9ee 100644 --- a/Documentation/ABI/testing/evm +++ b/Documentation/ABI/testing/evm @@ -14,30 +14,46 @@ Description: generated either locally or remotely using an asymmetric key. These keys are loaded onto root's keyring using keyctl, and EVM is then enabled by - echoing a value to /evm: + echoing a value to /evm made up of the + following bits: - 1: enable HMAC validation and creation - 2: enable digital signature validation - 3: enable HMAC and digital signature validation and HMAC - creation + Bit Effect + 0 Enable HMAC validation and creation + 1 Enable digital signature validation + 2 Permit modification of EVM-protected metadata at + runtime. Not supported if HMAC validation and + creation is enabled. + 31 Disable further runtime modification of EVM policy - Further writes will be blocked if HMAC support is enabled or - if bit 32 is set: + For example: - echo 0x80000002 >/evm + echo 1 >/evm - will enable digital signature validation and block - further writes to /evm. + will enable HMAC validation and creation - Until this is done, EVM can not create or validate the - 'security.evm' xattr, but returns INTEGRITY_UNKNOWN. - Loading keys and signaling EVM should be done as early - as possible. Normally this is done in the initramfs, - which has already been measured as part of the trusted - boot. For more information on creating and loading - existing trusted/encrypted keys, refer to: + echo 0x80000003 >/evm - Documentation/security/keys/trusted-encrypted.rst. Both dracut - (via 97masterkey and 98integrity) and systemd (via + will enable HMAC and digital signature validation and + HMAC creation and disable all further modification of policy. + + echo 0x80000006 >/evm + + will enable digital signature validation, permit + modification of EVM-protected metadata and + disable all further modification of policy + + Note that once a key has been loaded, it will no longer be + possible to enable metadata modification. + + Until key loading has been signaled EVM can not create + or validate the 'security.evm' xattr, but returns + INTEGRITY_UNKNOWN. Loading keys and signaling EVM + should be done as early as possible. Normally this is + done in the initramfs, which has already been measured + as part of the trusted boot. For more information on + creating and loading existing trusted/encrypted keys, + refer to: + Documentation/security/keys/trusted-encrypted.rst. Both + dracut (via 97masterkey and 98integrity) and systemd (via core/ima-setup) have support for loading keys at boot time. -- cgit From 51e028e44e64ff3c78750e1ab79be67b68dd8aef Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 9 Dec 2017 17:21:04 +0100 Subject: Documentation: mono: Update links and s/CVS/Git/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The URLs in mono.rst redirect to pages on www.mono-project.com, so let's update them. I took the liberty to update the compilation instructions to the Linux-specific version, because readers of the kernel documentation will most likely use Linux. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/mono.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst index cdddc099af64..59e6d59f0ed9 100644 --- a/Documentation/admin-guide/mono.rst +++ b/Documentation/admin-guide/mono.rst @@ -9,14 +9,14 @@ This will allow you to execute Mono-based .NET binaries just like any other program after you have done the following: 1) You MUST FIRST install the Mono CLR support, either by downloading - a binary package, a source tarball or by installing from CVS. Binary + a binary package, a source tarball or by installing from Git. Binary packages for several distributions can be found at: - http://go-mono.com/download.html + http://www.mono-project.com/download/ Instructions for compiling Mono can be found at: - http://www.go-mono.com/compiling.html + http://www.mono-project.com/docs/compiling-mono/linux/ Once the Mono CLR support has been installed, just check that ``/usr/bin/mono`` (which could be located elsewhere, for example -- cgit From c1de03a4cee1e71b3ad7680b9faef87fb09b91d4 Mon Sep 17 00:00:00 2001 From: Marco Donato Torsello Date: Fri, 8 Dec 2017 19:10:54 +0100 Subject: Documentation: kernel-hacking: corrected a typo Corrected a typo. Signed-off-by: Marco Donato Torsello Signed-off-by: Jonathan Corbet --- Documentation/kernel-hacking/hacking.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index daf3883b2694..5192d7f78eca 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -523,7 +523,7 @@ this expression is true, or ``-ERESTARTSYS`` if a signal is received. The Waking Up Queued Tasks ---------------------- -Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake +Call :c:func:`wake_up()` (``include/linux/wait.h``), which will wake up every process in the queue. The exception is if one has ``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will not be woken. There are other variants of this basic function available -- cgit From 3ece7805105ef5967fd88547ac958c6d59329e9c Mon Sep 17 00:00:00 2001 From: Stefan Tatschner Date: Fri, 8 Dec 2017 01:12:09 +0100 Subject: Documentation/driver-api/usb: Replace dead link This link is dead: $ curl -vI http://usb.cs.tum.edu/usbdoc * Could not resolve host: usb.cs.tum.edu * Closing connection 0 curl: (6) Could not resolve host: usb.cs.tum.edu I found the document somewhere else. Let's replace it. Signed-off-by: Stefan Tatschner Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/writing_usb_driver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 69f077dcdb78..4fe1c06b6a13 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -321,6 +321,6 @@ linux-usb-devel Mailing List Archives: http://marc.theaimsgroup.com/?l=linux-usb-devel Programming Guide for Linux USB Device Drivers: -http://usb.cs.tum.edu/usbdoc +http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf USB Home Page: http://www.usb.org -- cgit From b6e859f6cdd1686c021dcb3e18591d0b28ce8867 Mon Sep 17 00:00:00 2001 From: Elena Reshetova Date: Tue, 5 Dec 2017 12:46:35 +0200 Subject: docs: refcount_t documentation Some functions from refcount_t API provide different memory ordering guarantees that their atomic counterparts. This adds a document outlining these differences ( Documentation/core-api/refcount-vs-atomic.rst) as well as some other minor improvements. Signed-off-by: Elena Reshetova Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/core-api/index.rst | 1 + Documentation/core-api/refcount-vs-atomic.rst | 150 ++++++++++++++++++++++++++ Documentation/driver-api/basics.rst | 21 ++-- 3 files changed, 166 insertions(+), 6 deletions(-) create mode 100644 Documentation/core-api/refcount-vs-atomic.rst (limited to 'Documentation') diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d5bbe035316d..d4d54b05d6c5 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -14,6 +14,7 @@ Core utilities kernel-api assoc_array atomic_ops + refcount-vs-atomic cpu_hotplug local_ops workqueue diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst new file mode 100644 index 000000000000..83351c258cdb --- /dev/null +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -0,0 +1,150 @@ +=================================== +refcount_t API compared to atomic_t +=================================== + +.. contents:: :local: + +Introduction +============ + +The goal of refcount_t API is to provide a minimal API for implementing +an object's reference counters. While a generic architecture-independent +implementation from lib/refcount.c uses atomic operations underneath, +there are a number of differences between some of the ``refcount_*()`` and +``atomic_*()`` functions with regards to the memory ordering guarantees. +This document outlines the differences and provides respective examples +in order to help maintainers validate their code against the change in +these memory ordering guarantees. + +The terms used through this document try to follow the formal LKMM defined in +github.com/aparri/memory-model/blob/master/Documentation/explanation.txt + +memory-barriers.txt and atomic_t.txt provide more background to the +memory ordering in general and for atomic operations specifically. + +Relevant types of memory ordering +================================= + +.. note:: The following section only covers some of the memory + ordering types that are relevant for the atomics and reference + counters and used through this document. For a much broader picture + please consult memory-barriers.txt document. + +In the absence of any memory ordering guarantees (i.e. fully unordered) +atomics & refcounters only provide atomicity and +program order (po) relation (on the same CPU). It guarantees that +each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions +are executed in program order on a single CPU. +This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and +compare-and-swap primitives. + +A strong (full) memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before any po-later instruction is executed on the same CPU. +It also guarantees that all po-earlier stores on the same CPU +and all propagated stores from other CPUs must propagate to all +other CPUs before any po-later instruction is executed on the original +CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`. + +A RELEASE memory ordering guarantees that all prior loads and +stores (all po-earlier instructions) on the same CPU are completed +before the operation. It also guarantees that all po-earlier +stores on the same CPU and all propagated stores from other CPUs +must propagate to all other CPUs before the release operation +(A-cumulative property). This is implemented using +:c:func:`smp_store_release`. + +A control dependency (on success) for refcounters guarantees that +if a reference for an object was successfully obtained (reference +counter increment or addition happened, function returned true), +then further stores are ordered against this operation. +Control dependency on stores are not implemented using any explicit +barriers, but rely on CPU not to speculate on stores. This is only +a single CPU relation and provides no guarantees for other CPUs. + + +Comparison of functions +======================= + +case 1) - non-"Read/Modify/Write" (RMW) ops +------------------------------------------- + +Function changes: + + * :c:func:`atomic_set` --> :c:func:`refcount_set` + * :c:func:`atomic_read` --> :c:func:`refcount_read` + +Memory ordering guarantee changes: + + * none (both fully unordered) + + +case 2) - increment-based ops that return no value +-------------------------------------------------- + +Function changes: + + * :c:func:`atomic_inc` --> :c:func:`refcount_inc` + * :c:func:`atomic_add` --> :c:func:`refcount_add` + +Memory ordering guarantee changes: + + * none (both fully unordered) + +case 3) - decrement-based RMW ops that return no value +------------------------------------------------------ + +Function changes: + + * :c:func:`atomic_dec` --> :c:func:`refcount_dec` + +Memory ordering guarantee changes: + + * fully unordered --> RELEASE ordering + + +case 4) - increment-based RMW ops that return a value +----------------------------------------------------- + +Function changes: + + * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero` + * no atomic counterpart --> :c:func:`refcount_add_not_zero` + +Memory ordering guarantees changes: + + * fully ordered --> control dependency on success for stores + +.. note:: We really assume here that necessary ordering is provided as a + result of obtaining pointer to the object! + + +case 5) - decrement-based RMW ops that return a value +----------------------------------------------------- + +Function changes: + + * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test` + * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test` + * no atomic counterpart --> :c:func:`refcount_dec_if_one` + * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + control dependency + +.. note:: :c:func:`atomic_add_unless` only provides full order on success. + + +case 6) - lock-based RMW +------------------------ + +Function changes: + + * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock` + * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + control dependency + hold + :c:func:`spin_lock` on success diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 73fa7d42bbba..826e85d50a16 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -13,12 +13,6 @@ Driver device table .. kernel-doc:: include/linux/mod_devicetable.h :internal: -Atomic and pointer manipulation -------------------------------- - -.. kernel-doc:: arch/x86/include/asm/atomic.h - :internal: - Delaying, scheduling, and timer routines ---------------------------------------- @@ -85,6 +79,21 @@ Internal Functions .. kernel-doc:: kernel/kthread.c :export: +Reference counting +------------------ + +.. kernel-doc:: include/linux/refcount.h + :internal: + +.. kernel-doc:: lib/refcount.c + :export: + +Atomics +------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + Kernel objects manipulation --------------------------- -- cgit From 9727a0144bd99f4a189a2ededd52c53299079d8a Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 4 Dec 2017 10:27:29 +1100 Subject: doc: add maintainer book There is currently very little documentation in the kernel on maintainer level tasks. In particular there are no documents on creating pull requests to submit to Linus. Quoting Greg Kroah-Hartman on LKML: Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. (quote references: kernel summit, Europe 2017) Create a new kernel documentation book 'how to be a maintainer' (suggested by Jonathan Corbet). Add chapters on 'configuring git' and 'creating a pull request'. Most of the content was written by Linus Torvalds and Greg Kroah-Hartman in discussion on LKML. This is stated at the start of one of the chapters and the original email thread is referenced in 'pull-requests.rst'. Signed-off-by: Tobin C. Harding Reviewed-by: Greg Kroah-Hartman Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + Documentation/maintainer/conf.py | 10 ++ Documentation/maintainer/configure-git.rst | 34 ++++++ Documentation/maintainer/index.rst | 10 ++ Documentation/maintainer/pull-requests.rst | 178 +++++++++++++++++++++++++++++ 5 files changed, 233 insertions(+) create mode 100644 Documentation/maintainer/conf.py create mode 100644 Documentation/maintainer/configure-git.rst create mode 100644 Documentation/maintainer/index.rst create mode 100644 Documentation/maintainer/pull-requests.rst (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index cb7f1ba5b3b1..a4fb34dddcf3 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -52,6 +52,7 @@ merged much easier. dev-tools/index doc-guide/index kernel-hacking/index + maintainer/index Kernel API documentation ------------------------ diff --git a/Documentation/maintainer/conf.py b/Documentation/maintainer/conf.py new file mode 100644 index 000000000000..81e9eb7a7884 --- /dev/null +++ b/Documentation/maintainer/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'maintainer.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst new file mode 100644 index 000000000000..78bbbb0d2c84 --- /dev/null +++ b/Documentation/maintainer/configure-git.rst @@ -0,0 +1,34 @@ +.. _configuregit: + +Configure Git +============= + +This chapter describes maintainer level git configuration. + +Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst +` should be signed with the developers public GPG key. Signed +tags can be created by passing the ``-u`` flag to ``git tag``. However, +since you would *usually* use the same key for the same project, you can +set it once with +:: + + git config user.signingkey "keyname" + +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand: +:: + + [user] + name = Jane Developer + email = jd@domain.org + signingkey = jd@domain.org + +You may need to tell ``git`` to use ``gpg2`` +:: + + [gpg] + program = /path/to/gpg2 + +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file) +:: + + export GPG_TTY=$(tty) diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst new file mode 100644 index 000000000000..fa84ac9cae39 --- /dev/null +++ b/Documentation/maintainer/index.rst @@ -0,0 +1,10 @@ +========================== +Kernel Maintainer Handbook +========================== + +.. toctree:: + :maxdepth: 2 + + configure-git + pull-requests + diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst new file mode 100644 index 000000000000..a19db3458b56 --- /dev/null +++ b/Documentation/maintainer/pull-requests.rst @@ -0,0 +1,178 @@ +.. _pullrequests: + +Creating Pull Requests +====================== + +This chapter describes how maintainers can create and submit pull requests +to other maintainers. This is useful for transferring changes from one +maintainers tree to another maintainers tree. + +This document was written by Tobin C. Harding (who at that time, was not an +experienced maintainer) primarily from comments made by Greg Kroah-Hartman +and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet and +Mauro Carvalho Chehab. Misrepresentation was unintentional but inevitable, +please direct abuse to Tobin C. Harding . + +Original email thread:: + + http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com + + +Create Branch +------------- + +To start with you will need to have all the changes you wish to include in +the pull request on a separate branch. Typically you will base this branch +off of a branch in the developers tree whom you intend to send the pull +request to. + +In order to create the pull request you must first tag the branch that you +have just created. It is recommended that you choose a meaningful tag name, +in a way that you and others can understand, even after some time. A good +practice is to include in the name an indicator of the sybsystem of origin +and the target kernel version. + +Greg offers the following. A pull request with miscellaneous stuff for +drivers/char, to be applied at the Kernel version 4.15-rc1 could be named +as ``char-misc-4.15-rc1``. If such tag would be produced from a branch +named ``char-misc-next``, you would be using the following command:: + + git tag -s char-misc-4.15-rc1 char-misc-next + +that will create a signed tag called ``char-misc-4.15-rc1`` based on the +last commit in the ``char-misc-next`` branch, and sign it with your gpg key +(see :ref:`Documentation/maintainer/configure_git.rst `). + +Linus will only accept pull requests based on a signed tag. Other +maintainers may differ. + +When you run the above command ``git`` will drop you into an editor and ask +you to describe the tag. In this case, you are describing a pull request, +so outline what is contained here, why it should be merged, and what, if +any, testing has been done. All of this information will end up in the tag +itself, and then in the merge commit that the maintainer makes if/when they +merge the pull request. So write it up well, as it will be in the kernel +tree for forever. + +As said by Linus:: + + Anyway, at least to me, the important part is the *message*. I want + to understand what I'm pulling, and why I should pull it. I also + want to use that message as the message for the merge, so it should + not just make sense to me, but make sense as a historical record + too. + + Note that if there is something odd about the pull request, that + should very much be in the explanation. If you're touching files + that you don't maintain, explain _why_. I will see it in the + diffstat anyway, and if you didn't mention it, I'll just be extra + suspicious. And when you send me new stuff after the merge window + (or even bug-fixes, but ones that look scary), explain not just + what they do and why they do it, but explain the _timing_. What + happened that this didn't go through the merge window.. + + I will take both what you write in the email pull request _and_ in + the signed tag, so depending on your workflow, you can either + describe your work in the signed tag (which will also automatically + make it into the pull request email), or you can make the signed + tag just a placeholder with nothing interesting in it, and describe + the work later when you actually send me the pull request. + + And yes, I will edit the message. Partly because I tend to do just + trivial formatting (the whole indentation and quoting etc), but + partly because part of the message may make sense for me at pull + time (describing the conflicts and your personal issues for sending + it right now), but may not make sense in the context of a merge + commit message, so I will try to make it all make sense. I will + also fix any speeling mistaeks and bad grammar I notice, + particularly for non-native speakers (but also for native ones + ;^). But I may miss some, or even add some. + + Linus + +Greg gives, as an example pull request:: + + Char/Misc patches for 4.15-rc1 + + Here is the big char/misc patch set for the 4.15-rc1 merge window. + Contained in here is the normal set of new functions added to all + of these crazy drivers, as well as the following brand new + subsystems: + - time_travel_controller: Finally a set of drivers for the + latest time travel bus architecture that provides i/o to + the CPU before it asked for it, allowing uninterrupted + processing + - relativity_shifters: due to the affect that the + time_travel_controllers have on the overall system, there + was a need for a new set of relativity shifter drivers to + accommodate the newly formed black holes that would + threaten to suck CPUs into them. This subsystem handles + this in a way to successfully neutralize the problems. + There is a Kconfig option to force these to be enabled + when needed, so problems should not occur. + + All of these patches have been successfully tested in the latest + linux-next releases, and the original problems that it found have + all been resolved (apologies to anyone living near Canberra for the + lack of the Kconfig options in the earlier versions of the + linux-next tree creations.) + + Signed-off-by: Your-name-here + + +The tag message format is just like a git commit id. One line at the top +for a "summary subject" and be sure to sign-off at the bottom. + +Now that you have a local signed tag, you need to push it up to where it +can be retrieved:: + + git push origin char-misc-4.15-rc1 + + +Create Pull Request +------------------- + +The last thing to do is create the pull request message. ``git`` handily +will do this for you with the ``git request-pull`` command, but it needs a +bit of help determining what you want to pull, and on what to base the pull +against (to show the correct changes to be pulled and the diffstat). The +following command(s) will generate a pull request:: + + git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1 + +Quoting Greg:: + + This is asking git to compare the difference from the + 'char-misc-4.15-rc1' tag location, to the head of the 'master' + branch (which in my case points to the last location in Linus's + tree that I diverged from, usually a -rc release) and to use the + git:// protocol to pull from. If you wish to use https://, that + can be used here instead as well (but note that some people behind + firewalls will have problems with https git pulls). + + If the char-misc-4.15-rc1 tag is not present in the repo that I am + asking to be pulled from, git will complain saying it is not there, + a handy way to remember to actually push it to a public location. + + The output of 'git request-pull' will contain the location of the + git tree and specific tag to pull from, and the full text + description of that tag (which is why you need to provide good + information in that tag). It will also create a diffstat of the + pull request, and a shortlog of the individual commits that the + pull request will provide. + +Linus responded that he tends to prefer the ``git://`` protocol. Other +maintainers may have different preferences. Also, note that if you are +creating pull requests without a signed tag then ``https://`` may be a +better choice. Please see the original thread for the full discussion. + + +Submit Pull Request +------------------- + +A pull request is submitted in the same way as an ordinary patch. Send as +inline email to the maintainer and CC LKML and any sub-system specific +lists if required. Pull requests to Linus typically have a subject line +something like:: + + [GIT PULL] changes for v4.15-rc1 -- cgit From 40af6390837539f1e43a0223ebc99ed65e2eda82 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 11 Dec 2017 14:46:10 -0700 Subject: docs: Add an intro note to the maintainers handbook ...just enough to say what the purpose is and to solicit more contributions. Signed-off-by: Jonathan Corbet --- Documentation/maintainer/index.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index fa84ac9cae39..2a14916930cb 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -2,6 +2,10 @@ Kernel Maintainer Handbook ========================== +This document is the humble beginning of a manual for kernel maintainers. +There is a lot yet to go here! Please feel free to propose (and write) +additions to this manual. + .. toctree:: :maxdepth: 2 -- cgit From aa73f28e1d5b01eadeedc0926dac5c4ed3defc60 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Fri, 8 Dec 2017 11:53:37 -0200 Subject: doc: usb: chipidea: Fix typo in 'enumerate' Fix the spelling of 'enumerate' in this document. Signed-off-by: Fabio Estevam Signed-off-by: Jonathan Corbet --- Documentation/usb/chipidea.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt index edf7cdfddc88..d1eedc01b00a 100644 --- a/Documentation/usb/chipidea.txt +++ b/Documentation/usb/chipidea.txt @@ -23,13 +23,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers 2) Connect 2 boards with usb cable with one end is micro A plug, the other end is micro B plug. - The A-device(with micro A plug inserted) should enumrate B-device. + The A-device(with micro A plug inserted) should enumerate B-device. 3) Role switch On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - B-device should take host role and enumrate A-device. + B-device should take host role and enumerate A-device. 4) A-device switch back to host. On B-device: @@ -40,13 +40,13 @@ cat /sys/kernel/debug/ci_hdrc.0/registers side by answering the polling from B-Host, this can be done on A-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - A-device should switch back to host and enumrate B-device. + A-device should switch back to host and enumerate B-device. 5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, - A-device should enumrate B-device again. + A-device should enumerate B-device again. 6) Remove B-device(unplug micro B plug) and insert again after 10 seconds, - A-device should NOT enumrate B-device. + A-device should NOT enumerate B-device. if A-device wants to use bus: On A-device: @@ -67,7 +67,7 @@ cat /sys/kernel/debug/ci_hdrc.0/registers On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - A-device should resume usb bus and enumrate B-device. + A-device should resume usb bus and enumerate B-device. 1.3 Reference document ---------------------- -- cgit From d22881dc13b62baf32e69e16fd4f8bdbe2aa3e4e Mon Sep 17 00:00:00 2001 From: Scott Wood Date: Sun, 10 Dec 2017 01:48:46 -0600 Subject: Documentation: Better document the hardlockup_panic sysctl Commit ac1f591249d95372f ("kernel/watchdog.c: add sysctl knob hardlockup_panic") added the hardlockup_panic sysctl, but did not add it to Documentation/sysctl/kernel.txt. Add this, and reference it from the corresponding entry in Documentation/admin-guide/kernel-parameters.txt. Signed-off-by: Scott Wood Acked-by: Christoph von Recklinghausen Acked-by: Don Zickus Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 3 +++ Documentation/sysctl/kernel.txt | 14 ++++++++++++++ 2 files changed, 17 insertions(+) (limited to 'Documentation') diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 6571fbfdb2a1..dfb7c35b5826 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2538,6 +2538,9 @@ This is useful when you use a panic=... timeout and need the box quickly up again. + These settings can be accessed at runtime via + the nmi_watchdog and hardlockup_panic sysctls. + netpoll.carrier_timeout= [NET] Specifies amount of time (in seconds) that netpoll should wait for a carrier. By default netpoll diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 694968c7523c..63663039acb7 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -34,6 +34,7 @@ show up in /proc/sys/kernel: - hostname - hotplug - hardlockup_all_cpu_backtrace +- hardlockup_panic - hung_task_panic - hung_task_check_count - hung_task_timeout_secs @@ -313,6 +314,19 @@ will be initiated. 1: on detection capture more debug information. ============================================================== +hardlockup_panic: + +This parameter can be used to control whether the kernel panics +when a hard lockup is detected. + + 0 - don't panic on hard lockup + 1 - panic on hard lockup + +See Documentation/lockup-watchdogs.txt for more information. This can +also be set using the nmi_watchdog kernel parameter. + +============================================================== + hotplug: Path for the hotplug policy agent. -- cgit From 3abaa5ccd92231fd445b2599f13aca32aa003478 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 29 Nov 2017 12:32:38 -0800 Subject: Documentation: add Sorting section to kernel-api Add sort() and list_sort() to the kernel API documentation in a new "Sorting" section. Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- Documentation/core-api/kernel-api.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 2d9da6c40a4d..5d2d5f83579c 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -139,6 +139,15 @@ Division Functions .. kernel-doc:: lib/gcd.c :export: +Sorting +------- + +.. kernel-doc:: lib/sort.c + :export: + +.. kernel-doc:: lib/list_sort.c + :export: + Memory Management in Linux ========================== -- cgit From d063623b6ae7c326d21a2713dd38cab15d794c1c Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 29 Nov 2017 12:32:42 -0800 Subject: Documentation: add UUID/GUID to kernel-api Update kernel-doc notation in lib/uuid.c and then add UUID/GUID function interfaces to kernel-api. Signed-off-by: Randy Dunlap [jc: tweaked the uuid_is_valid() kerneldoc] Signed-off-by: Jonathan Corbet --- Documentation/core-api/kernel-api.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 5d2d5f83579c..e7fadf02c511 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -148,6 +148,12 @@ Sorting .. kernel-doc:: lib/list_sort.c :export: +UUID/GUID +--------- + +.. kernel-doc:: lib/uuid.c + :export: + Memory Management in Linux ========================== -- cgit From b7d4ec395673bf8b21de064f181cc94096e0a0c7 Mon Sep 17 00:00:00 2001 From: "Darren Hart (VMware)" Date: Mon, 20 Nov 2017 14:39:33 -0800 Subject: Documentation/kbuild: Add guidance for the use of default Document the preference [1] for new CONFIG options to "default n" (or not use default at all) in order to minimizes changes to the config, especially to avoid "make oldconfig" growing unnecessarily from release to release. Document the exceptions where it is acceptable to use "default y/m" for new CONFIG options. 1. https://lkml.org/lkml/2017/11/18/257 Cc: "Yann E. MORIN" Cc: Masahiro Yamada Cc: Michal Marek Cc: Jonathan Corbet Cc: linux-kbuild@vger.kernel.org Cc: linux-doc@vger.kernel.org Signed-off-by: Darren Hart (VMware) Signed-off-by: Jonathan Corbet --- Documentation/kbuild/kconfig-language.txt | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'Documentation') diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index 262722d8867b..688e41ebb4da 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -77,6 +77,27 @@ applicable everywhere (see syntax). Optionally, dependencies only for this default value can be added with "if". + The default value deliberately defaults to 'n' in order to avoid bloating the + build. With few exceptions, new config options should not change this. The + intent is for "make oldconfig" to add as little as possible to the config from + release to release. + + Note: + Things that merit "default y/m" include: + + a) A new Kconfig option for something that used to always be built + should be "default y". + + b) A new gatekeeping Kconfig option that hides/shows other Kconfig + options (but does not generate any code of its own), should be + "default y" so people will see those other options. + + c) Sub-driver behavior or similar options for a driver that is + "default n". This allows you to provide sane defaults. + + d) Hardware or infrastructure that everybody expects, such as CONFIG_NET + or CONFIG_BLOCK. These are rare exceptions. + - type definition + default value: "def_bool"/"def_tristate" ["if" ] This is a shorthand notation for a type definition plus a value. -- cgit From 241f67c8cccc94d79166173197bd6117cfa94ae9 Mon Sep 17 00:00:00 2001 From: "Darren Hart (VMware)" Date: Mon, 20 Nov 2017 14:39:34 -0800 Subject: Documentation/process: Add CONFIG default value to submit-checklist Add default value review to the submit checklist, referring to the preference for "default n" from the previous patch added to Documentation/kbuild/kconfig-language.txt. Cc: "Yann E. MORIN" Cc: Masahiro Yamada Cc: Michal Marek Cc: Jonathan Corbet Cc: linux-kbuild@vger.kernel.org Cc: linux-doc@vger.kernel.org Signed-off-by: Darren Hart (VMware) Signed-off-by: Jonathan Corbet --- Documentation/process/submit-checklist.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index a0d9d34bfb6d..7d04ab38007d 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -37,7 +37,9 @@ and elsewhere regarding submitting Linux kernel patches. You should be able to justify all violations that remain in your patch. -6) Any new or modified ``CONFIG`` options don't muck up the config menu. +6) Any new or modified ``CONFIG`` options do not muck up the config menu and + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. 7) All new ``Kconfig`` options have help text. -- cgit From 2a7c7cba38f4176af081de74e82b61aeae4feaa1 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 11 Dec 2017 15:20:04 -0700 Subject: docs: Remove "could not extract kernel version" warning This warning will happen for every normal kernel docs build and doesn't carry any useful information. Should anybody actually depend on this "version" variable (which isn't clear to me), the "unknown version" value will be clue enough. Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/conf.py b/Documentation/conf.py index 63857d33778c..62ac5a9f3a9f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -88,7 +88,6 @@ finally: if makefile_version and makefile_patchlevel: version = release = makefile_version + '.' + makefile_patchlevel else: - sys.stderr.write('Warning: Could not extract kernel version\n') version = release = "unknown version" # The language for content autogenerated by Sphinx. Refer to documentation -- cgit From e8fd31c5543240d866492769e0e3b6a54b1df7b7 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 10 Dec 2017 10:11:44 -0800 Subject: scsi: documentation: add scsi_common.c to SCSI driver-api Add exported functions from scsi_common.c to the SCSI driver API documentation. Signed-off-by: Randy Dunlap Cc: Nicholas Bellinger Signed-off-by: Martin K. Petersen --- Documentation/driver-api/scsi.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 87e9e0c0ecd8..3ae337929721 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -224,6 +224,14 @@ mid to lowlevel SCSI driver interface .. kernel-doc:: drivers/scsi/hosts.c :export: +drivers/scsi/scsi_common.c +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +general support functions + +.. kernel-doc:: drivers/scsi/scsi_common.c + :export: + Transport classes ----------------- -- cgit From aa15d3d257f9edcb8d15ed27e228d1c0080cb919 Mon Sep 17 00:00:00 2001 From: Alan Stern Date: Mon, 11 Dec 2017 11:58:21 -0500 Subject: USB: remove the URB_NO_FSBR flag The URB_NO_FSBR flag has never really been used. It was introduced as a potential way for UHCI to minimize PCI bus usage (by not attempting full-speed bulk and control transfers more than once per frame), but the flag was not set by any drivers. There's no point in keeping it around. This patch simplifies the API by removing it. Unfortunately, it does have to be kept as part of the usbfs ABI, but at least we can document in include/uapi/linux/usbdevice_fs.h that it doesn't do anything. Signed-off-by: Alan Stern Acked-by: Shuah Khan Signed-off-by: Greg Kroah-Hartman --- Documentation/usb/usbip_protocol.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/usb/usbip_protocol.txt b/Documentation/usb/usbip_protocol.txt index 16b6fe27284c..c7a0f4c7e7f1 100644 --- a/Documentation/usb/usbip_protocol.txt +++ b/Documentation/usb/usbip_protocol.txt @@ -274,7 +274,6 @@ USBIP_CMD_SUBMIT: Submit an URB URB_SHORT_NOT_OK | 0x00000001 | only in | only in | only in | no URB_ISO_ASAP | 0x00000002 | no | no | no | yes URB_NO_TRANSFER_DMA_MAP | 0x00000004 | yes | yes | yes | yes - URB_NO_FSBR | 0x00000020 | yes | no | no | no URB_ZERO_PACKET | 0x00000040 | no | no | only out | no URB_NO_INTERRUPT | 0x00000080 | yes | yes | yes | yes URB_FREE_BUFFER | 0x00000100 | yes | yes | yes | yes -- cgit From 0132a1a5d44d2cd32a249dbe999a88c2134a6bd1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 12 Dec 2017 12:38:37 +0100 Subject: docs: fix, intel_guc_loader.c has been moved to intel_guc_fw.c With commit d9e2e0143c the 'GuC-specific firmware loader' doc section was removed from intel_guc_loader.c without a replacement. So lets remove it from the Kernel-doc:: .. kernel-doc:: drivers/gpu/drm/i915/intel_guc_loader.c :doc: GuC-specific firmware loader With commit e8668bbcb0 intel_guc_loader.c was renamed to to intel_guc_fw.c and to name just one, intel_guc_init_hw() was renamed to intel_guc_fw_upload(). Since we get errors in the Sphinx build like: - Error: Cannot open file ./drivers/gpu/drm/i915/intel_guc_loader.c Change the kernel-doc directive from intel_guc_loader.c to intel_guc_fw.c Signed-off-by: Markus Heiser [danvet: Rebase onto the partial fix 006c23327f8d ("documentation/gpu/i915: fix docs build error after file rename")] Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/1513078717-12373-1-git-send-email-markus.heiser@darmarit.de --- Documentation/gpu/i915.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 84021142a8f3..41dc881b00dc 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -341,9 +341,6 @@ GuC GuC-specific firmware loader ---------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c - :doc: GuC-specific firmware loader - .. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c :internal: -- cgit From 5cc2066d7326932570e957e15dab3cd01a420bc9 Mon Sep 17 00:00:00 2001 From: Lei YU Date: Mon, 20 Nov 2017 13:53:43 +0800 Subject: dt-bindings: Add W83773G as a trivial device Signed-off-by: Lei YU [robh: improve commit subject] Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/trivial-devices.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/trivial-devices.txt b/Documentation/devicetree/bindings/trivial-devices.txt index 5f3143f97098..390b99583ff7 100644 --- a/Documentation/devicetree/bindings/trivial-devices.txt +++ b/Documentation/devicetree/bindings/trivial-devices.txt @@ -151,6 +151,7 @@ national,lm85 Temperature sensor with integrated fan control national,lm92 ±0.33°C Accurate, 12-Bit + Sign Temperature Sensor and Thermal Window Comparator with Two-Wire Interface nuvoton,npct501 i2c trusted platform module (TPM) nuvoton,npct601 i2c trusted platform module (TPM2) +nuvoton,w83773g Nuvoton Temperature Sensor nxp,pca9556 Octal SMBus and I2C registered interface nxp,pca9557 8-bit I2C-bus and SMBus I/O port with reset nxp,pcf2127 Real-time clock -- cgit From aa199b746678e22ce986505c52e796b8481c555e Mon Sep 17 00:00:00 2001 From: Ludovic Barre Date: Fri, 8 Dec 2017 14:56:34 +0100 Subject: dt-bindings: arm: document supported STM32 SoC family This adds a list of supported STM32 SoC bindings. Signed-off-by: Gwenael Treuveur Signed-off-by: Ludovic Barre Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/arm/stm32.txt | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 Documentation/devicetree/bindings/arm/stm32.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/stm32.txt b/Documentation/devicetree/bindings/arm/stm32.txt new file mode 100644 index 000000000000..05762b08a7bb --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32.txt @@ -0,0 +1,9 @@ +STMicroelectronics STM32 Platforms Device Tree Bindings + +Each device tree must specify which STM32 SoC it uses, +using one of the following compatible strings: + + st,stm32f429 + st,stm32f469 + st,stm32f746 + st,stm32h743 -- cgit From 00644f9bd38b89c7844ab516644a90cc1e06dd64 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Tue, 12 Dec 2017 15:59:17 -0600 Subject: dt-bindings: Add optional nvmem BD address bindings to ti,wlink-st This adds optional nvmem consumer properties to the ti,wlink-st device tree bindings to allow specifying the BD address. Reviewed-by: Rob Herring Signed-off-by: David Lechner Signed-off-by: Marcel Holtmann --- Documentation/devicetree/bindings/net/ti,wilink-st.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/ti,wilink-st.txt b/Documentation/devicetree/bindings/net/ti,wilink-st.txt index 1649c1f66b07..a45a508d66d0 100644 --- a/Documentation/devicetree/bindings/net/ti,wilink-st.txt +++ b/Documentation/devicetree/bindings/net/ti,wilink-st.txt @@ -32,6 +32,9 @@ Optional properties: See ../clocks/clock-bindings.txt for details. - clock-names : Must include the following entry: "ext_clock" (External clock provided to the TI combo chip). + - nvmem-cells: phandle to nvmem data cell that contains a 6 byte BD address + with the most significant byte first (big-endian). + - nvmem-cell-names: "bd-address" (required when nvmem-cells is specified) Example: @@ -43,5 +46,7 @@ Example: enable-gpios = <&gpio1 7 GPIO_ACTIVE_HIGH>; clocks = <&clk32k_wl18xx>; clock-names = "ext_clock"; + nvmem-cells = <&bd_address>; + nvmem-cell-names = "bd-address"; }; }; -- cgit From 0458bb62a2a454ed4dd83c893bc3a5e12038388e Mon Sep 17 00:00:00 2001 From: Alexandre Belloni Date: Fri, 8 Dec 2017 16:46:09 +0100 Subject: dt-bindings: pinctrl: Add bindings for Microsemi Ocelot Add the documentation for the Microsemi Ocelot pinmuxing and gpio controller. Cc: Linus Walleij Cc: linux-gpio@vger.kernel.org Signed-off-by: Alexandre Belloni Acked-by: Rob Herring Signed-off-by: Linus Walleij --- .../bindings/pinctrl/mscc,ocelot-pinctrl.txt | 39 ++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt new file mode 100644 index 000000000000..24a210e0c59a --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt @@ -0,0 +1,39 @@ +Microsemi Ocelot pin controller Device Tree Bindings +---------------------------------------------------- + +Required properties: + - compatible : Should be "mscc,ocelot-pinctrl" + - reg : Address and length of the register set for the device + - gpio-controller : Indicates this device is a GPIO controller + - #gpio-cells : Must be 2. + The first cell is the pin number and the + second cell specifies GPIO flags, as defined in + . + - gpio-ranges : Range of pins managed by the GPIO controller. + + +The ocelot-pinctrl driver uses the generic pin multiplexing and generic pin +configuration documented in pinctrl-bindings.txt. + +The following generic properties are supported: + - function + - pins + +Example: + gpio: pinctrl@71070034 { + compatible = "mscc,ocelot-pinctrl"; + reg = <0x71070034 0x28>; + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&gpio 0 0 22>; + + uart_pins: uart-pins { + pins = "GPIO_6", "GPIO_7"; + function = "uart"; + }; + + uart2_pins: uart2-pins { + pins = "GPIO_12", "GPIO_13"; + function = "uart2"; + }; + }; -- cgit From 07c7edd0db441f83eeee087470add5be280cc018 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Tue, 12 Dec 2017 18:29:30 -0600 Subject: dt-bindings: net: add TI CC2560 Bluetooth chip This adds a compatible string for the Texas Instruments CC2560 Bluetooth chip to the existing TI WiLink shared transport bindings. These chips are similar enough that the same bindings work for both. The file is renamed to ti-bluetooth.txt to make it more generic. Signed-off-by: David Lechner Signed-off-by: Marcel Holtmann --- .../devicetree/bindings/net/ti,wilink-st.txt | 52 ------------------ .../devicetree/bindings/net/ti-bluetooth.txt | 61 ++++++++++++++++++++++ 2 files changed, 61 insertions(+), 52 deletions(-) delete mode 100644 Documentation/devicetree/bindings/net/ti,wilink-st.txt create mode 100644 Documentation/devicetree/bindings/net/ti-bluetooth.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/ti,wilink-st.txt b/Documentation/devicetree/bindings/net/ti,wilink-st.txt deleted file mode 100644 index a45a508d66d0..000000000000 --- a/Documentation/devicetree/bindings/net/ti,wilink-st.txt +++ /dev/null @@ -1,52 +0,0 @@ -TI WiLink 7/8 (wl12xx/wl18xx) Shared Transport BT/FM/GPS devices - -TI WiLink devices have a UART interface for providing Bluetooth, FM radio, -and GPS over what's called "shared transport". The shared transport is -standard BT HCI protocol with additional channels for the other functions. - -These devices also have a separate WiFi interface as described in -wireless/ti,wlcore.txt. - -This bindings follows the UART slave device binding in -../serial/slave-device.txt. - -Required properties: - - compatible: should be one of the following: - "ti,wl1271-st" - "ti,wl1273-st" - "ti,wl1281-st" - "ti,wl1283-st" - "ti,wl1285-st" - "ti,wl1801-st" - "ti,wl1805-st" - "ti,wl1807-st" - "ti,wl1831-st" - "ti,wl1835-st" - "ti,wl1837-st" - -Optional properties: - - enable-gpios : GPIO signal controlling enabling of BT. Active high. - - vio-supply : Vio input supply (1.8V) - - vbat-supply : Vbat input supply (2.9-4.8V) - - clocks : Must contain an entry, for each entry in clock-names. - See ../clocks/clock-bindings.txt for details. - - clock-names : Must include the following entry: - "ext_clock" (External clock provided to the TI combo chip). - - nvmem-cells: phandle to nvmem data cell that contains a 6 byte BD address - with the most significant byte first (big-endian). - - nvmem-cell-names: "bd-address" (required when nvmem-cells is specified) - -Example: - -&serial0 { - compatible = "ns16550a"; - ... - bluetooth { - compatible = "ti,wl1835-st"; - enable-gpios = <&gpio1 7 GPIO_ACTIVE_HIGH>; - clocks = <&clk32k_wl18xx>; - clock-names = "ext_clock"; - nvmem-cells = <&bd_address>; - nvmem-cell-names = "bd-address"; - }; -}; diff --git a/Documentation/devicetree/bindings/net/ti-bluetooth.txt b/Documentation/devicetree/bindings/net/ti-bluetooth.txt new file mode 100644 index 000000000000..6d03ff8c7068 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ti-bluetooth.txt @@ -0,0 +1,61 @@ +Texas Instruments Bluetooth Chips +--------------------------------- + +This documents the binding structure and common properties for serial +attached TI Bluetooth devices. The following chips are included in this +binding: + +* TI CC256x Bluetooth devices +* TI WiLink 7/8 (wl12xx/wl18xx) Shared Transport BT/FM/GPS devices + +TI WiLink devices have a UART interface for providing Bluetooth, FM radio, +and GPS over what's called "shared transport". The shared transport is +standard BT HCI protocol with additional channels for the other functions. + +TI WiLink devices also have a separate WiFi interface as described in +wireless/ti,wlcore.txt. + +This bindings follows the UART slave device binding in +../serial/slave-device.txt. + +Required properties: + - compatible: should be one of the following: + "ti,cc2560" + "ti,wl1271-st" + "ti,wl1273-st" + "ti,wl1281-st" + "ti,wl1283-st" + "ti,wl1285-st" + "ti,wl1801-st" + "ti,wl1805-st" + "ti,wl1807-st" + "ti,wl1831-st" + "ti,wl1835-st" + "ti,wl1837-st" + +Optional properties: + - enable-gpios : GPIO signal controlling enabling of BT. Active high. + - vio-supply : Vio input supply (1.8V) + - vbat-supply : Vbat input supply (2.9-4.8V) + - clocks : Must contain an entry, for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names : Must include the following entry: + "ext_clock" (External clock provided to the TI combo chip). + - nvmem-cells: phandle to nvmem data cell that contains a 6 byte BD address + with the most significant byte first (big-endian). + - nvmem-cell-names: "bd-address" (required when nvmem-cells is specified) + +Example: + +&serial0 { + compatible = "ns16550a"; + ... + bluetooth { + compatible = "ti,wl1835-st"; + enable-gpios = <&gpio1 7 GPIO_ACTIVE_HIGH>; + clocks = <&clk32k_wl18xx>; + clock-names = "ext_clock"; + nvmem-cells = <&bd_address>; + nvmem-cell-names = "bd-address"; + }; +}; -- cgit From afc996a368a58606ac946715fcef60f25c75d483 Mon Sep 17 00:00:00 2001 From: Sinan Kaya Date: Wed, 13 Dec 2017 02:20:47 -0500 Subject: Documentation: DT: qcom_hidma: Bump HW revision for the bugfixed HW A new version of the HIDMA IP has been released with bug fixes. Bumping the hardware version to differentiate from others. Signed-off-by: Sinan Kaya Reviewed-by: Rob Herring Signed-off-by: Vinod Koul --- Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt index 55492c264d17..5d93d6de57d9 100644 --- a/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt +++ b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt @@ -47,8 +47,8 @@ When the OS is not in control of the management interface (i.e. it's a guest), the channel nodes appear on their own, not under a management node. Required properties: -- compatible: must contain "qcom,hidma-1.0" for initial HW or "qcom,hidma-1.1" -for MSI capable HW. +- compatible: must contain "qcom,hidma-1.0" for initial HW or + "qcom,hidma-1.1"/"qcom,hidma-1.2" for MSI capable HW. - reg: Addresses for the transfer and event channel - interrupts: Should contain the event interrupt - desc-count: Number of asynchronous requests this channel can handle -- cgit From f580fd3f9d78cf0425ab98950796c578d8a82167 Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Mon, 26 Jun 2017 17:33:12 +0200 Subject: dt-bindings: misc: Add Tegra186 MISC registers bindings The MISC register block found on Tegra186 SoCs contains registers that can be used to identify a given chip and various strapping options. Signed-off-by: Thierry Reding --- .../devicetree/bindings/misc/nvidia,tegra186-misc.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt new file mode 100644 index 000000000000..892ba4384abc --- /dev/null +++ b/Documentation/devicetree/bindings/misc/nvidia,tegra186-misc.txt @@ -0,0 +1,12 @@ +NVIDIA Tegra186 MISC register block + +The MISC register block found on Tegra186 SoCs contains registers that can be +used to identify a given chip and various strapping options. + +Required properties: +- compatible: Must be: + - Tegra186: "nvidia,tegra186-misc" +- reg: Should contain 2 entries: The first entry gives the physical address + and length of the register region which contains revision and debug + features. The second entry specifies the physical address and length + of the register region indicating the strapping options. -- cgit From 029ab5eaf091ce5eaa1f3017f66fd1d10f431d61 Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Wed, 13 Dec 2017 12:53:43 +0100 Subject: dt-bindings: memory: Add Tegra186 support As opposed to earlier incarnations, the memory controller on Tegra186 no longer implements an SMMU. Instead the SMMU is a regular ARM SMMU and in a separate IP block. However, the memory controller programs the SMMU stream IDs for each of the memory clients. Add a header file with definitions for each of these stream IDs and mark the #iommu-cells property as required on Tegra30 to Tegra210 in the device tree bindings. Signed-off-by: Thierry Reding --- .../devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt index 8dbe47013c2b..14968b048cd3 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra30-mc.txt @@ -12,6 +12,8 @@ Required properties: - clock-names: Must include the following entries: - mc: the module's clock input - interrupts: The interrupt outputs from the controller. + +Required properties for Tegra30, Tegra114, Tegra124, Tegra132 and Tegra210: - #iommu-cells: Should be 1. The single cell of the IOMMU specifier defines the SWGROUP of the master. -- cgit From 91cc07069291d83b3fa90615373640e028068aaf Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Wed, 30 Aug 2017 12:04:07 +0200 Subject: dt-bindings: display: tegra: Update SOR for Tegra186 Update the SOR bindings for Tegra186, in which a new property is required to identify the instance of the SOR interface and the clock tree has slightly changed as well. Signed-off-by: Thierry Reding --- .../bindings/display/tegra/nvidia,tegra20-host1x.txt | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index 844e0103fb0d..593be44a53c9 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -206,21 +206,33 @@ of the following host1x client modules: - "nvidia,tegra132-sor": for Tegra132 - "nvidia,tegra210-sor": for Tegra210 - "nvidia,tegra210-sor1": for Tegra210 + - "nvidia,tegra186-sor": for Tegra186 + - "nvidia,tegra186-sor1": for Tegra186 - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt outputs from the controller. - clocks: Must contain an entry for each entry in clock-names. See ../clocks/clock-bindings.txt for details. - clock-names: Must include the following entries: - sor: clock input for the SOR hardware - - source: source clock for the SOR clock + - out: SOR output clock - parent: input for the pixel clock - dp: reference clock for the SOR clock - safe: safe reference for the SOR clock during power up + + For Tegra186 and later: + - pad: SOR pad output clock (on Tegra186 and later) + + Obsolete: + - source: source clock for the SOR clock (obsolete, use "out" instead) + - resets: Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names: Must include the following entries: - sor + Required properties on Tegra186 and later: + - nvidia,interface: index of the SOR interface + Optional properties: - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection -- cgit From 3a30ae6ef3cba29c83ca791bde0d06f182d5678d Mon Sep 17 00:00:00 2001 From: Richard Leitner Date: Mon, 11 Dec 2017 13:16:57 +0100 Subject: phylib: Add device reset delay support Some PHYs need a minimum time after the reset gpio was asserted and/or deasserted. To ensure we meet these timing requirements add two new optional devicetree parameters for the phy: reset-delay-us and reset-post-delay-us. Signed-off-by: Richard Leitner Reviewed-by: Geert Uytterhoeven Reviewed-by: Andrew Lunn Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/phy.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index c05479f5ac7c..72860ce7f610 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -55,6 +55,12 @@ Optional Properties: - reset-gpios: The GPIO phandle and specifier for the PHY reset signal. +- reset-delay-us: Delay after the reset was asserted in microseconds. + If this property is missing the delay will be skipped. + +- reset-post-delay-us: Delay after the reset was deasserted in microseconds. + If this property is missing the delay will be skipped. + Example: ethernet-phy@0 { @@ -62,4 +68,8 @@ ethernet-phy@0 { interrupt-parent = <&PIC>; interrupts = <35 IRQ_TYPE_EDGE_RISING>; reg = <0>; + + reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; + reset-delay-us = <1000>; + reset-post-delay-us = <2000>; }; -- cgit From 11e4723206683ad59f8e9dc7771e7b44a37f7b62 Mon Sep 17 00:00:00 2001 From: Heinz Mauelshagen Date: Wed, 13 Dec 2017 17:13:18 +0100 Subject: dm raid: stop keeping raid set frozen altogether In order to avoid redoing synchronization/recovery/reshape partially, the raid set got frozen until after all passed in table line flags had been cleared. The related table reload sequence had to be precisely followed, or reshaping may lead to data corruption caused by the active mapping carrying on with a reshape when the inactive mapping already had retrieved a stale reshape position. Harden by retrieving the actual resync/recovery/reshape position during resume whilst the active table is suspended thus avoiding to keep the raid set frozen altogether. This prevents superfluous redoing of an already resynchronized or recovered segment and, most importantly, potential for redoing of an already reshaped segment causing data corruption. Fixes: d39f0010e ("dm raid: fix raid_resume() to keep raid set frozen as needed") Signed-off-by: Heinz Mauelshagen Signed-off-by: Mike Snitzer --- Documentation/device-mapper/dm-raid.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index 7b22375091fa..390c145f01d7 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -347,3 +347,4 @@ Version History 1.13.0 Fix dev_health status at end of "recover" (was 'a', now 'A') 1.13.1 Fix deadlock caused by early md_stop_writes(). Also fix size an state races. +1.13.2 Fix raid redundancy validation and avoid keeping raid set frozen -- cgit From 7268586baa530312041e597b518b5c6a05110df1 Mon Sep 17 00:00:00 2001 From: Yuchung Cheng Date: Tue, 12 Dec 2017 13:10:40 -0800 Subject: tcp: pause Fast Open globally after third consecutive timeout Prior to this patch, active Fast Open is paused on a specific destination IP address if the previous connections to the IP address have experienced recurring timeouts . But recent experiments by Microsoft (https://goo.gl/cykmn7) and Mozilla browsers indicate the isssue is often caused by broken middle-boxes sitting close to the client. Therefore it is much better user experience if Fast Open is disabled out-right globally to avoid experiencing further timeouts on connections toward other destinations. This patch changes the destination-IP disablement to global disablement if a connection experiencing recurring timeouts or aborts due to timeout. Repeated incidents would still exponentially increase the pause time, starting from an hour. This is extremely conservative but an unfortunate compromise to minimize bad experience due to broken middle-boxes. Reported-by: Dragana Damjanovic Reported-by: Patrick McManus Signed-off-by: Yuchung Cheng Reviewed-by: Wei Wang Reviewed-by: Neal Cardwell Reviewed-by: Eric Dumazet Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 46c7e1085efc..3f2c40d8e6aa 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -606,6 +606,7 @@ tcp_fastopen_blackhole_timeout_sec - INTEGER This time period will grow exponentially when more blackhole issues get detected right after Fastopen is re-enabled and will reset to initial value when the blackhole issue goes away. + 0 to disable the blackhole detection. By default, it is set to 1hr. tcp_syn_retries - INTEGER -- cgit From 4ad5a3217a193e933bc41168b000672417486c87 Mon Sep 17 00:00:00 2001 From: Roman Gushchin Date: Wed, 13 Dec 2017 19:49:03 +0000 Subject: cgroup, docs: document cgroup v2 device controller Add the corresponding section in cgroup v2 documentation. Signed-off-by: Roman Gushchin Cc: Tejun Heo Cc: Alexei Starovoitov Cc: kernel-team@fb.com Cc: cgroups@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Tejun Heo --- Documentation/cgroup-v2.txt | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index 2cddab7efb20..d6efabb487e3 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -53,10 +53,11 @@ v1 is available under Documentation/cgroup-v1/. 5-3-2. Writeback 5-4. PID 5-4-1. PID Interface Files - 5-5. RDMA - 5-5-1. RDMA Interface Files - 5-6. Misc - 5-6-1. perf_event + 5-5. Device + 5-6. RDMA + 5-6-1. RDMA Interface Files + 5-7. Misc + 5-7-1. perf_event 6. Namespace 6-1. Basics 6-2. The Root and Views @@ -1429,6 +1430,30 @@ through fork() or clone(). These will return -EAGAIN if the creation of a new process would cause a cgroup policy to be violated. +Device controller +----------------- + +Device controller manages access to device files. It includes both +creation of new device files (using mknod), and access to the +existing device files. + +Cgroup v2 device controller has no interface files and is implemented +on top of cgroup BPF. To control access to device files, a user may +create bpf programs of the BPF_CGROUP_DEVICE type and attach them +to cgroups. On an attempt to access a device file, corresponding +BPF programs will be executed, and depending on the return value +the attempt will succeed or fail with -EPERM. + +A BPF_CGROUP_DEVICE program takes a pointer to the bpf_cgroup_dev_ctx +structure, which describes the device access attempt: access type +(mknod/read/write) and device (type, major and minor numbers). +If the program returns 0, the attempt fails with -EPERM, otherwise +it succeeds. + +An example of BPF_CGROUP_DEVICE program may be found in the kernel +source tree in the tools/testing/selftests/bpf/dev_cgroup.c file. + + RDMA ---- -- cgit From f8d0dfed511e7eacb4afe3244266d862f9695aab Mon Sep 17 00:00:00 2001 From: Yixun Lan Date: Mon, 11 Dec 2017 22:13:44 +0800 Subject: dt-bindings: clock: add compatible variant for the Meson-AXG Update the documentation to support clock driver for the Amlogic's Meson-AXG SoC. Acked-by: Rob Herring Signed-off-by: Yixun Lan Signed-off-by: Jerome Brunet --- Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt index 924040769186..e2b377ed6f91 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt @@ -5,8 +5,11 @@ controllers within the SoC. Required Properties: -- compatible: should be "amlogic,gxbb-clkc" for GXBB SoC, - or "amlogic,gxl-clkc" for GXL and GXM SoC. +- compatible: should be: + "amlogic,gxbb-clkc" for GXBB SoC, + "amlogic,gxl-clkc" for GXL and GXM SoC, + "amlogic,axg-clkc" for AXG SoC. + - reg: physical base address of the clock controller and length of memory mapped region. -- cgit From 94e53262a2ac32f4afe8c9b07badf513b0540dd8 Mon Sep 17 00:00:00 2001 From: Dmitry Osipenko Date: Mon, 11 Dec 2017 19:26:07 -0500 Subject: media: dt: bindings: Add binding for NVIDIA Tegra Video Decoder Engine Add binding documentation for the Video Decoder Engine which is found on NVIDIA Tegra20/30/114/124/132 SoC's. Signed-off-by: Dmitry Osipenko Acked-by: Rob Herring Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../devicetree/bindings/media/nvidia,tegra-vde.txt | 55 ++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt new file mode 100644 index 000000000000..470237ed6fe5 --- /dev/null +++ b/Documentation/devicetree/bindings/media/nvidia,tegra-vde.txt @@ -0,0 +1,55 @@ +NVIDIA Tegra Video Decoder Engine + +Required properties: +- compatible : Must contain one of the following values: + - "nvidia,tegra20-vde" + - "nvidia,tegra30-vde" + - "nvidia,tegra114-vde" + - "nvidia,tegra124-vde" + - "nvidia,tegra132-vde" +- reg : Must contain an entry for each entry in reg-names. +- reg-names : Must include the following entries: + - sxe + - bsev + - mbe + - ppe + - mce + - tfe + - ppb + - vdma + - frameid +- iram : Must contain phandle to the mmio-sram device node that represents + IRAM region used by VDE. +- interrupts : Must contain an entry for each entry in interrupt-names. +- interrupt-names : Must include the following entries: + - sync-token + - bsev + - sxe +- clocks : Must include the following entries: + - vde +- resets : Must include the following entries: + - vde + +Example: + +video-codec@6001a000 { + compatible = "nvidia,tegra20-vde"; + reg = <0x6001a000 0x1000 /* Syntax Engine */ + 0x6001b000 0x1000 /* Video Bitstream Engine */ + 0x6001c000 0x100 /* Macroblock Engine */ + 0x6001c200 0x100 /* Post-processing Engine */ + 0x6001c400 0x100 /* Motion Compensation Engine */ + 0x6001c600 0x100 /* Transform Engine */ + 0x6001c800 0x100 /* Pixel prediction block */ + 0x6001ca00 0x100 /* Video DMA */ + 0x6001d800 0x300 /* Video frame controls */>; + reg-names = "sxe", "bsev", "mbe", "ppe", "mce", + "tfe", "ppb", "vdma", "frameid"; + iram = <&vde_pool>; /* IRAM region */ + interrupts = , /* Sync token interrupt */ + , /* BSE-V interrupt */ + ; /* SXE interrupt */ + interrupt-names = "sync-token", "bsev", "sxe"; + clocks = <&tegra_car TEGRA20_CLK_VDE>; + resets = <&tegra_car 61>; +}; -- cgit From 40fb0eab30ba44bcfc5eb29eb8c78a30025f9e12 Mon Sep 17 00:00:00 2001 From: Sven Eckelmann Date: Fri, 8 Dec 2017 11:37:41 +0100 Subject: dt: bindings: add new dt entry for ath10k calibration variant The bus + bmi-chip-id + bmi-board-id is not enough to identify the correct board data file on QCA4019 based devices. Multiple different boards share the same values. Only the original reference designs can currently be identified and loaded from the board-2.bin. But these will not result in the correct calibration data when combined with the pre-calibration data from the device. An additional "variant" information has to be provided (via SMBIOS or DT) to select the correct board data for a design which was modified by an ODM. Signed-off-by: Sven Eckelmann Signed-off-by: Kalle Valo --- Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index 74d7f0af209c..3d2a031217da 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -41,6 +41,9 @@ Optional properties: - qcom,msi_addr: MSI interrupt address. - qcom,msi_base: Base value to add before writing MSI data into MSI address register. +- qcom,ath10k-calibration-variant: string to search for in the board-2.bin + variant list with the same bus and device + specific ids - qcom,ath10k-calibration-data : calibration data + board specific data as an array, the length can vary between hw versions. -- cgit From 4e3cd001fde13dfd4a91888f908b2a07fd0a4047 Mon Sep 17 00:00:00 2001 From: Sean Young Date: Thu, 8 Jun 2017 05:10:41 -0400 Subject: media: lirc: remove LIRCCODE and LIRC_GET_LENGTH LIRCCODE is a lirc mode where a driver produces driver-dependent codes for receive and transmit. No driver uses this any more. The LIRC_GET_LENGTH ioctl was used for this mode only. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/lirc.h.rst.exceptions | 5 +++ Documentation/media/uapi/rc/lirc-dev-intro.rst | 15 -------- Documentation/media/uapi/rc/lirc-func.rst | 1 - Documentation/media/uapi/rc/lirc-get-features.rst | 7 +--- Documentation/media/uapi/rc/lirc-get-length.rst | 44 ---------------------- Documentation/media/uapi/rc/lirc-get-rec-mode.rst | 4 +- Documentation/media/uapi/rc/lirc-get-send-mode.rst | 3 +- 7 files changed, 9 insertions(+), 70 deletions(-) delete mode 100644 Documentation/media/uapi/rc/lirc-get-length.rst (limited to 'Documentation') diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index c130617a9986..63ba1d341905 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -28,6 +28,10 @@ ignore define LIRC_CAN_SEND_MASK ignore define LIRC_CAN_REC_MASK ignore define LIRC_CAN_SET_REC_DUTY_CYCLE +# Obsolete ioctls + +ignore ioctl LIRC_GET_LENGTH + # Undocumented macros ignore define PULSE_BIT @@ -40,3 +44,4 @@ ignore define LIRC_VALUE_MASK ignore define LIRC_MODE2_MASK ignore define LIRC_MODE_RAW +ignore define LIRC_MODE_LIRCCODE diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index d1936eeb9ce0..3cacf9aeac40 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -72,21 +72,6 @@ on the following table. this packet will be sent, with the number of microseconds with no IR. -.. _lirc-mode-lirccode: - -``LIRC_MODE_LIRCCODE`` - - This mode can be used for IR receive and send. - - The IR signal is decoded internally by the receiver, or encoded by the - transmitter. The LIRC interface represents the scancode as byte string, - which might not be a u32, it can be any length. The value is entirely - driver dependent. This mode is used by some older lirc drivers. - - The length of each code depends on the driver, which can be retrieved - with :ref:`lirc_get_length`. This length is used both - for transmitting and receiving IR. - .. _lirc-mode-pulse: ``LIRC_MODE_PULSE`` diff --git a/Documentation/media/uapi/rc/lirc-func.rst b/Documentation/media/uapi/rc/lirc-func.rst index 9b5a772ec96c..ddb4620de294 100644 --- a/Documentation/media/uapi/rc/lirc-func.rst +++ b/Documentation/media/uapi/rc/lirc-func.rst @@ -18,7 +18,6 @@ LIRC Function Reference lirc-set-send-duty-cycle lirc-get-timeout lirc-set-rec-timeout - lirc-get-length lirc-set-rec-carrier lirc-set-rec-carrier-range lirc-set-send-carrier diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst index 64f89a4f9d9c..50c2c26d8e89 100644 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ b/Documentation/media/uapi/rc/lirc-get-features.rst @@ -62,8 +62,7 @@ LIRC features ``LIRC_CAN_REC_LIRCCODE`` - The driver is capable of receiving using - :ref:`LIRC_MODE_LIRCCODE `. + Unused. Kept just to avoid breaking uAPI. .. _LIRC-CAN-SET-SEND-CARRIER: @@ -170,9 +169,7 @@ LIRC features ``LIRC_CAN_SEND_LIRCCODE`` - The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_LIRCCODE `. - + Unused. Kept just to avoid breaking uAPI. Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-get-length.rst b/Documentation/media/uapi/rc/lirc-get-length.rst deleted file mode 100644 index 3990af5de0e9..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-length.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _lirc_get_length: - -********************* -ioctl LIRC_GET_LENGTH -********************* - -Name -==== - -LIRC_GET_LENGTH - Retrieves the code length in bits. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_LENGTH, __u32 *length ) - :name: LIRC_GET_LENGTH - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``length`` - length, in bits - - -Description -=========== - -Retrieves the code length in bits (only for -:ref:`LIRC_MODE_LIRCCODE `). -Reads on the device must be done in blocks matching the bit count. -The bit could should be rounded up so that it matches full bytes. - - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst index a4eb6c0a26e9..b89de9add921 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst @@ -34,9 +34,7 @@ Description =========== Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 ` -and :ref:`LIRC_MODE_LIRCCODE ` are supported for IR -receive. Use :ref:`lirc_get_features` to find out which modes the driver -supports. +is supported for IR receive. Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst index a169b234290e..e686b21689a0 100644 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst @@ -36,8 +36,7 @@ Description Get/set current transmit mode. -Only :ref:`LIRC_MODE_PULSE ` and -:ref:`LIRC_MODE_LIRCCODE ` is supported by for IR send, +Only :ref:`LIRC_MODE_PULSE ` is supported by for IR send, depending on the driver. Use :ref:`lirc_get_features` to find out which modes the driver supports. -- cgit From bf01c82474bf1f5c07d90a0959a95ff51374cc6f Mon Sep 17 00:00:00 2001 From: Sean Young Date: Tue, 26 Sep 2017 07:56:39 -0400 Subject: media: lirc: remove name from lirc_dev This is a duplicate of rcdev->driver_name. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/lirc-dev-intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index 3cacf9aeac40..a3fa3c1ef169 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -18,7 +18,7 @@ Example dmesg output upon a driver registering w/LIRC: $ dmesg |grep lirc_dev lirc_dev: IR Remote Control driver registered, major 248 - rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0 + rc rc0: lirc_dev: driver mceusb registered at minor = 0 What you should see for a chardev: -- cgit From a6ddd4fecbb02d8ec5a865621bd2b746d585a01c Mon Sep 17 00:00:00 2001 From: Sean Young Date: Tue, 26 Sep 2017 09:34:47 -0400 Subject: media: lirc: remove last remnants of lirc kapi rc-core has replaced the lirc kapi many years ago, and now with the last driver ported to rc-core, we can finally remove it. Note this has no effect on userspace. All future IR drivers should use the rc-core api. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/rc-core.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst index a45895886257..41c2256dbf6a 100644 --- a/Documentation/media/kapi/rc-core.rst +++ b/Documentation/media/kapi/rc-core.rst @@ -7,8 +7,3 @@ Remote Controller core .. kernel-doc:: include/media/rc-core.h .. kernel-doc:: include/media/rc-map.h - -LIRC -~~~~ - -.. kernel-doc:: include/media/lirc_dev.h -- cgit From 7d402db89b5b6d3ca5128937dc04653df8668978 Mon Sep 17 00:00:00 2001 From: Sean Young Date: Sat, 25 Feb 2017 06:51:34 -0500 Subject: media: lirc: document LIRC_MODE_SCANCODE Lirc supports a new mode which requires documentation. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/lirc.h.rst.exceptions | 26 +++++++++++ Documentation/media/uapi/rc/lirc-dev-intro.rst | 51 +++++++++++++++++++--- Documentation/media/uapi/rc/lirc-get-features.rst | 16 +++++++ Documentation/media/uapi/rc/lirc-get-rec-mode.rst | 3 +- Documentation/media/uapi/rc/lirc-get-send-mode.rst | 3 +- Documentation/media/uapi/rc/lirc-read.rst | 15 +++++-- Documentation/media/uapi/rc/lirc-write.rst | 19 ++++++-- 7 files changed, 118 insertions(+), 15 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index 63ba1d341905..c6e3a35d2c4e 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -32,6 +32,32 @@ ignore define LIRC_CAN_SET_REC_DUTY_CYCLE ignore ioctl LIRC_GET_LENGTH +# rc protocols + +ignore symbol RC_PROTO_UNKNOWN +ignore symbol RC_PROTO_OTHER +ignore symbol RC_PROTO_RC5 +ignore symbol RC_PROTO_RC5X_20 +ignore symbol RC_PROTO_RC5_SZ +ignore symbol RC_PROTO_JVC +ignore symbol RC_PROTO_SONY12 +ignore symbol RC_PROTO_SONY15 +ignore symbol RC_PROTO_SONY20 +ignore symbol RC_PROTO_NEC +ignore symbol RC_PROTO_NECX +ignore symbol RC_PROTO_NEC32 +ignore symbol RC_PROTO_SANYO +ignore symbol RC_PROTO_MCIR2_KBD +ignore symbol RC_PROTO_MCIR2_MSE +ignore symbol RC_PROTO_RC6_0 +ignore symbol RC_PROTO_RC6_6A_20 +ignore symbol RC_PROTO_RC6_6A_24 +ignore symbol RC_PROTO_RC6_6A_32 +ignore symbol RC_PROTO_RC6_MCE +ignore symbol RC_PROTO_SHARP +ignore symbol RC_PROTO_XMP +ignore symbol RC_PROTO_CEC + # Undocumented macros ignore define PULSE_BIT diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index a3fa3c1ef169..47c6c218e72a 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -6,11 +6,12 @@ Introduction ************ -The LIRC device interface is a bi-directional interface for transporting -raw IR data between userspace and kernelspace. Fundamentally, it is just -a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard -struct file_operations defined on it. With respect to transporting raw -IR data to and fro, the essential fops are read, write and ioctl. +LIRC stands for Linux Infrared Remote Control. The LIRC device interface is +a bi-directional interface for transporting raw IR and decoded scancodes +data between userspace and kernelspace. Fundamentally, it is just a chardev +(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct +file_operations defined on it. With respect to transporting raw IR and +decoded scancodes to and fro, the essential fops are read, write and ioctl. Example dmesg output upon a driver registering w/LIRC: @@ -36,6 +37,46 @@ LIRC modes LIRC supports some modes of receiving and sending IR codes, as shown on the following table. +.. _lirc-mode-scancode: +.. _lirc-scancode-flag-toggle: +.. _lirc-scancode-flag-repeat: + +``LIRC_MODE_SCANCODE`` + + This mode is for both sending and receiving IR. + + For transmitting (aka sending), create a ``struct lirc_scancode`` with + the desired scancode set in the ``scancode`` member, ``rc_proto`` set + the IR protocol, and all other members set to 0. Write this struct to + the lirc device. + + For receiving, you read ``struct lirc_scancode`` from the lirc device, + with ``scancode`` set to the received scancode and the IR protocol + ``rc_proto``. If the scancode maps to a valid key code, this is set + in the ``keycode`` field, else it is set to ``KEY_RESERVED``. + + The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle + bit is set in protocols that support it (e.g. rc-5 and rc-6), or + ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols + that support it (e.g. nec). + + In the Sanyo and NEC protocol, if you hold a button on remote, rather than + repeating the entire scancode, the remote sends a shorter message with + no scancode, which just means button is held, a "repeat". When this is + received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and + keycode is repeated. + + With nec, there is no way to distinguish "button hold" from "repeatedly + pressing the same button". The rc-5 and rc-6 protocols have a toggle bit. + When a button is released and pressed again, the toggle bit is inverted. + If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set. + + The ``timestamp`` field is filled with the time nanoseconds + (in ``CLOCK_MONOTONIC``) when the scancode was decoded. + + An ``enum rc_proto`` in the :ref:`lirc_header` lists all the supported + IR protocols. + .. _lirc-mode-mode2: ``LIRC_MODE_MODE2`` diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst index 50c2c26d8e89..3ee44067de63 100644 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ b/Documentation/media/uapi/rc/lirc-get-features.rst @@ -64,6 +64,14 @@ LIRC features Unused. Kept just to avoid breaking uAPI. +.. _LIRC-CAN-REC-SCANCODE: + +``LIRC_CAN_REC_SCANCODE`` + + The driver is capable of receiving using + :ref:`LIRC_MODE_SCANCODE `. + + .. _LIRC-CAN-SET-SEND-CARRIER: ``LIRC_CAN_SET_SEND_CARRIER`` @@ -171,6 +179,14 @@ LIRC features Unused. Kept just to avoid breaking uAPI. +.. _LIRC-CAN-SEND-SCANCODE: + +``LIRC_CAN_SEND_SCANCODE`` + + The driver supports sending (also called as IR blasting or IR TX) using + :ref:`LIRC_MODE_SCANCODE `. + + Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst index b89de9add921..34919feaf392 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst @@ -34,7 +34,8 @@ Description =========== Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 ` -is supported for IR receive. +and :ref:`LIRC_MODE_SCANCODE ` are supported. +Use :ref:`lirc_get_features` to find out which modes the driver supports. Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst index e686b21689a0..e39383f08e21 100644 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst @@ -36,7 +36,8 @@ Description Get/set current transmit mode. -Only :ref:`LIRC_MODE_PULSE ` is supported by for IR send, +Only :ref:`LIRC_MODE_PULSE ` and +:ref:`LIRC_MODE_SCANCODE ` are supported by for IR send, depending on the driver. Use :ref:`lirc_get_features` to find out which modes the driver supports. diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index ff14a69104e5..51d37ed10194 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -45,13 +45,20 @@ descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, is greater than ``SSIZE_MAX``, the result is unspecified. The exact format of the data depends on what :ref:`lirc_modes` a driver -uses. Use :ref:`lirc_get_features` to get the supported mode. +uses. Use :ref:`lirc_get_features` to get the supported mode, and use +:ref:`lirc_set_rec_mode` set the current active mode. -The generally preferred mode for receive is -:ref:`LIRC_MODE_MODE2 `, -in which packets containing an int value describing an IR signal are +The mode :ref:`LIRC_MODE_MODE2 ` is for raw IR, +in which packets containing an unsigned int value describing an IR signal are read from the chardev. +Alternatively, :ref:`LIRC_MODE_SCANCODE ` can be available, +in this mode scancodes which are either decoded by software decoders, or +by hardware decoders. The ``rc_proto`` member is set to the +protocol used for transmission, and ``scancode`` to the decoded scancode, +and the ``keycode`` set to the keycode or ``KEY_RESERVED``. + + Return Value ============ diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index 2aad0fef4a5b..3d7541bad8b9 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -42,21 +42,32 @@ Description referenced by the file descriptor ``fd`` from the buffer starting at ``buf``. -The exact format of the data depends on what mode a driver uses, use -:ref:`lirc_get_features` to get the supported mode. +The exact format of the data depends on what mode a driver is in, use +:ref:`lirc_get_features` to get the supported modes and use +:ref:`lirc_set_send_mode` set the mode. When in :ref:`LIRC_MODE_PULSE ` mode, the data written to the chardev is a pulse/space sequence of integer values. Pulses and spaces are only marked implicitly by their position. The data must start and end with a pulse, therefore, the data must always include an uneven number of -samples. The write function must block until the data has been transmitted +samples. The write function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the driver returns ``EINVAL``. +When in :ref:`LIRC_MODE_SCANCODE ` mode, one +``struct lirc_scancode`` must be written to the chardev at a time, else +``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, +and the protocol in the ``rc_proto`` member. All other members must be set +to 0, else ``EINVAL`` is returned. If there is no protocol encoder +for the protocol or the scancode is not valid for the specified protocol, +``EINVAL`` is returned. The write function may not wait until the scancode +is transmitted. + + Return Value ============ -On success, the number of bytes read is returned. It is not an error if +On success, the number of bytes written is returned. It is not an error if this number is smaller than the number of bytes requested, or the amount of data required for one frame. On error, -1 is returned, and the ``errno`` variable is set appropriately. The generic error codes are described at the -- cgit From c6b73bfcead9500e6b841cadb44f38324202ef77 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 30 Nov 2017 08:00:45 -0500 Subject: media: RC docs: add enum rc_proto description at the docs This is part of the uAPI. Add it to the documentation again, and fix cross-references. Signed-off-by: Mauro Carvalho Chehab Acked-by: Sean Young --- Documentation/media/uapi/rc/lirc-dev-intro.rst | 19 +++++++++++++------ Documentation/media/uapi/rc/lirc-read.rst | 2 +- Documentation/media/uapi/rc/lirc-write.rst | 4 ++-- 3 files changed, 16 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index 47c6c218e72a..3a74fec66d69 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -46,13 +46,13 @@ on the following table. This mode is for both sending and receiving IR. For transmitting (aka sending), create a ``struct lirc_scancode`` with - the desired scancode set in the ``scancode`` member, ``rc_proto`` set - the IR protocol, and all other members set to 0. Write this struct to + the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` + set the IR protocol, and all other members set to 0. Write this struct to the lirc device. For receiving, you read ``struct lirc_scancode`` from the lirc device, with ``scancode`` set to the received scancode and the IR protocol - ``rc_proto``. If the scancode maps to a valid key code, this is set + :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set in the ``keycode`` field, else it is set to ``KEY_RESERVED``. The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle @@ -74,9 +74,6 @@ on the following table. The ``timestamp`` field is filled with the time nanoseconds (in ``CLOCK_MONOTONIC``) when the scancode was decoded. - An ``enum rc_proto`` in the :ref:`lirc_header` lists all the supported - IR protocols. - .. _lirc-mode-mode2: ``LIRC_MODE_MODE2`` @@ -125,3 +122,13 @@ on the following table. of entries. This mode is used only for IR send. + + +************************** +Remote Controller protocol +************************** + +An enum :c:type:`rc_proto` in the :ref:`lirc_header` lists all the +supported IR protocols: + +.. kernel-doc:: include/uapi/linux/lirc.h diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index 51d37ed10194..c024aaffb8ad 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -54,7 +54,7 @@ read from the chardev. Alternatively, :ref:`LIRC_MODE_SCANCODE ` can be available, in this mode scancodes which are either decoded by software decoders, or -by hardware decoders. The ``rc_proto`` member is set to the +by hardware decoders. The :c:type:`rc_proto` member is set to the protocol used for transmission, and ``scancode`` to the decoded scancode, and the ``keycode`` set to the keycode or ``KEY_RESERVED``. diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index 3d7541bad8b9..dd3d1fe807a6 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -57,8 +57,8 @@ driver returns ``EINVAL``. When in :ref:`LIRC_MODE_SCANCODE ` mode, one ``struct lirc_scancode`` must be written to the chardev at a time, else ``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, -and the protocol in the ``rc_proto`` member. All other members must be set -to 0, else ``EINVAL`` is returned. If there is no protocol encoder +and the protocol in the :c:type:`rc_proto`: member. All other members must be +set to 0, else ``EINVAL`` is returned. If there is no protocol encoder for the protocol or the scancode is not valid for the specified protocol, ``EINVAL`` is returned. The write function may not wait until the scancode is transmitted. -- cgit From d9806f11b36a389f5cb34bf28055b510974177b2 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 13 Dec 2017 04:54:04 -0500 Subject: media: vidioc-g-dv-timings.rst: fix typo (frontporch -> backporch) The description of V4L2_DV_FL_HALF_LINE mixed up frontporch with backporch. It's the backporch that has different sizes for interlaced formats, the frontporch remains constant. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst index 2696380626d4..1a034e825161 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst @@ -267,7 +267,7 @@ EBUSY will also be cleared. * - ``V4L2_DV_FL_HALF_LINE`` - Specific to interlaced formats: if set, then the vertical - frontporch of field 1 (aka the odd field) is really one half-line + backporch of field 1 (aka the odd field) is really one half-line longer and the vertical backporch of field 2 (aka the even field) is really one half-line shorter, so each field has exactly the same number of half-lines. Whether half-lines can be detected or -- cgit From da6c05969785a0f4108a089ef33c55f46ae21775 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 14 Dec 2017 21:30:53 +0100 Subject: drm/atomic: document how to handle driver private objects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DK put some nice docs into the commit introducing driver private state, but in the git history alone it'll be lost. Also, since Ville remove the void* usage it's a good opportunity to give the driver private stuff some tlc on the doc front. Finally try to explain why the "let's just subclass drm_atomic_state" approach wasn't the greatest, and annotate all those functions as deprecated in favour of more standardized driver private states. Also note where we could/should extend driver private states going forward (atm neither locking nor synchronization is handled in core/helpers, which isn't really all that great). v2: Spelling and phrasing improvements (Alex, DK). Cc: Harry Wentland Cc: Dhinakaran Pandiyan Cc: Maarten Lankhorst Cc: Ville Syrjälä Cc: Laurent Pinchart Cc: Rob Clark Cc: Alex Deucher Cc: Ben Skeggs Reviewed-by: Dhinakaran Pandiyan Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171214203054.20141-5-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-kms.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 307284125d7a..420025bd6a9b 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -271,6 +271,12 @@ Taken all together there's two consequences for the atomic design: Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. +Handling Driver Private State +----------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c + :doc: handling driver private state + Atomic Mode Setting Function Reference -------------------------------------- -- cgit From 5fca5ece6af8dd507c0459262766369e057e6d60 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Thu, 14 Dec 2017 21:30:54 +0100 Subject: drm/doc: Move legacy kms helpers to the very end We don't want people to accidentally stumble over there. Also rename the plane helpers to legacy plane helpers. After Ville's patch to make the clipping helper atomic and move it to drm_atomic_helper.c there's nothing left in there that should be useful for modern drivers. v2: Laurent had a few questions around how state is added to drm_atomic_state, tried to clarify that. And spotted another sentence where the docs suggested subclassing. v3: Small polish (Alex). Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171214203054.20141-6-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-kms-helpers.rst | 36 +++++++++++++++++------------------ Documentation/gpu/drm-kms.rst | 8 ++++---- 2 files changed, 22 insertions(+), 22 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 3ea622876b67..e37557b30f62 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -74,15 +74,6 @@ Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Legacy CRTC/Modeset Helper Functions Reference -============================================== - -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: - Simple KMS Helper Reference =========================== @@ -282,15 +273,6 @@ Flip-work Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_flip_work.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - Auxiliary Modeset Helpers ========================= @@ -308,3 +290,21 @@ Framebuffer GEM Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c :export: + +Legacy Plane Helper Reference +============================= + +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c + :export: + +Legacy CRTC/Modeset Helper Functions Reference +============================================== + +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c + :export: diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 420025bd6a9b..2dcf5b42015d 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -263,10 +263,10 @@ Taken all together there's two consequences for the atomic design: - An atomic update is assembled and validated as an entirely free-standing pile of structures within the :c:type:`drm_atomic_state ` - container. Again drivers can subclass that container for their own state - structure tracking needs. Only when a state is committed is it applied to the - driver and modeset objects. This way rolling back an update boils down to - releasing memory and unreferencing objects like framebuffers. + container. Driver private state structures are also tracked in the same + structure; see the next chapter. Only when a state is committed is it applied + to the driver and modeset objects. This way rolling back an update boils down + to releasing memory and unreferencing objects like framebuffers. Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. -- cgit From 3b07d7884ca203d14297974df1b89bed7ff20a8c Mon Sep 17 00:00:00 2001 From: Florian Fainelli Date: Thu, 14 Dec 2017 17:59:40 -0800 Subject: net: dsa: bcm_sf2: Update compatible string for 7278B0 Update the compatible string and Device Tree binding document for 7278B0. Signed-off-by: Florian Fainelli Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt index 9a734d808aa7..b7336b9d6a3c 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -2,7 +2,10 @@ Required properties: -- compatible: should be "brcm,bcm7445-switch-v4.0" or "brcm,bcm7278-switch-v4.0" +- compatible: should be one of + "brcm,bcm7445-switch-v4.0" + "brcm,bcm7278-switch-v4.0" + "brcm,bcm7278-switch-v4.8" - reg: addresses and length of the register sets for the device, must be 6 pairs of register addresses and lengths - interrupts: interrupts for the devices, must be two interrupts -- cgit From d06dfbc6bfec2636eb749ee00e91ef5baf2ac2c6 Mon Sep 17 00:00:00 2001 From: Sven Eckelmann Date: Sun, 19 Nov 2017 15:05:12 +0100 Subject: batman-adv: Add SPDX license identifier to batman-adv.rst The "Linux licensing rules" require that also the restructuredText files are marked with the appropriate SPDX license identifier. Signed-off-by: Sven Eckelmann Signed-off-by: Simon Wunderlich --- Documentation/networking/batman-adv.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/batman-adv.rst b/Documentation/networking/batman-adv.rst index a342b2cc3dc6..245fb6c0ab6f 100644 --- a/Documentation/networking/batman-adv.rst +++ b/Documentation/networking/batman-adv.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ========== batman-adv ========== -- cgit From 20a2742e5784295b9197250b50c40f6d38a55880 Mon Sep 17 00:00:00 2001 From: Tony Lindgren Date: Wed, 13 Dec 2017 16:36:47 -0800 Subject: dt-bindings: ti-sysc: Update binding for timers and capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ti-sysc binding does not yet describe the capabilities of the interconnect target module. So to make the ti-sysc binding usable for configuring the interconnect target module, we need to add few more properties: 1. To detect between omap2 and omap4 timers, let's add compatibles for them for "ti,sysc-omap2-timer" and,sysc-omap4-timer". This makes it easier to pick up the already initialized system timers later on 2. Let's add "ti,sysc-mask" for a mask of features supported by the interconnect target module. This describes what we have available in the various SYSCONFIG registers 3. Let's add "ti,sysc-midle" and "ti,sysc-sidle" lists for the master and slave idle modes supported by the interconnect target module. These describe the values available for MIDLE and SIDLE bits in the SYSCONFIG registers 4. Some interconnect target modules need a short delay after reset before they can be accessed, let's use "ti,sysc-delay-us" for that 5. Let's add "ti,syss-mask" bit to describe the optional SYSSTATUS register bits for reset done bits 6. Let's support the two existing custom quirk properties already listed in Documentation/devicetree/bindings/arm/omap/omap.txt for "ti,no-reset-on-init" and "ti,no-idle-on-init" 7. And finally, let's add a header for the binding for the dts files and the driver to use Cc: Benoît Cousson Cc: Dave Gerlach Cc: Laurent Pinchart Cc: Liam Girdwood Cc: Mark Brown Cc: Mark Rutland Cc: Mauro Carvalho Chehab Cc: Nishanth Menon Cc: Matthijs van Duin Cc: Paul Walmsley Cc: Peter Ujfalusi Cc: Sakari Ailus Cc: Suman Anna Cc: Tero Kristo Cc: Tomi Valkeinen Reviewed-by: Rob Herring Signed-off-by: Tony Lindgren --- Documentation/devicetree/bindings/bus/ti-sysc.txt | 36 +++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/bus/ti-sysc.txt b/Documentation/devicetree/bindings/bus/ti-sysc.txt index fb1790e39398..48bbb0c96835 100644 --- a/Documentation/devicetree/bindings/bus/ti-sysc.txt +++ b/Documentation/devicetree/bindings/bus/ti-sysc.txt @@ -26,6 +26,8 @@ Required standard properties: or one of the following derivative types for hardware needing special workarounds: + "ti,sysc-omap2-timer" + "ti,sysc-omap4-timer" "ti,sysc-omap3430-sr" "ti,sysc-omap3630-sr" "ti,sysc-omap4-sr" @@ -49,6 +51,26 @@ Required standard properties: Optional properties: +- ti,sysc-mask shall contain mask of supported register bits for the + SYSCONFIG register as documented in the Technical Reference + Manual (TRM) for the interconnect target module + +- ti,sysc-midle list of master idle modes supported by the interconnect + target module as documented in the TRM for SYSCONFIG + register MIDLEMODE bits + +- ti,sysc-sidle list of slave idle modes supported by the interconnect + target module as documented in the TRM for SYSCONFIG + register SIDLEMODE bits + +- ti,sysc-delay-us delay needed after OCP softreset before accssing + SYSCONFIG register again + +- ti,syss-mask optional mask of reset done status bits as described in the + TRM for SYSSTATUS registers, typically 1 with some devices + having separate reset done bits for children like OHCI and + EHCI + - clocks clock specifier for each name in the clock-names as specified in the binding documentation for ti-clkctrl, typically available for all interconnect targets on TI SoCs @@ -61,6 +83,9 @@ Optional properties: - ti,hwmods optional TI interconnect module name to use legacy hwmod platform data +- ti,no-reset-on-init interconnect target module should not be reset at init + +- ti,no-idle-on-init interconnect target module should not be idled at init Example: Single instance of MUSB controller on omap4 using interconnect ranges using offsets from l4_cfg second segment (0x4a000000 + 0x80000 = 0x4a0ab000): @@ -74,6 +99,17 @@ using offsets from l4_cfg second segment (0x4a000000 + 0x80000 = 0x4a0ab000): reg-names = "rev", "sysc", "syss"; clocks = <&l3_init_clkctrl OMAP4_USB_OTG_HS_CLKCTRL 0>; clock-names = "fck"; + ti,sysc-mask = <(SYSC_OMAP2_ENAWAKEUP | + SYSC_OMAP2_SOFTRESET | + SYSC_OMAP2_AUTOIDLE)>; + ti,sysc-midle = , + , + ; + ti,sysc-sidle = , + , + , + ; + ti,syss-mask = <1>; #address-cells = <1>; #size-cells = <1>; ranges = <0 0x2b000 0x1000>; -- cgit From 512dc8fed99a361e6caf185b14292ab0a60ebd2f Mon Sep 17 00:00:00 2001 From: Russell King Date: Thu, 14 Dec 2017 10:27:42 +0000 Subject: dt-bindings: add sff,sff binding for SFP support Add "sff,sff" for SFF module support with SFP. These have a different phys_id value, and also have the present and rate select signals omitted compared with their socketed counter-parts. Signed-off-by: Russell King Reviewed-by: Rob Herring Reviewed-by: Florian Fainelli Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/sff,sfp.txt | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/sff,sfp.txt b/Documentation/devicetree/bindings/net/sff,sfp.txt index 60e970ce10ee..f1c441bedf68 100644 --- a/Documentation/devicetree/bindings/net/sff,sfp.txt +++ b/Documentation/devicetree/bindings/net/sff,sfp.txt @@ -3,7 +3,9 @@ Transceiver Required properties: -- compatible : must be "sff,sfp" +- compatible : must be one of + "sff,sfp" for SFP modules + "sff,sff" for soldered down SFF modules Optional Properties: @@ -11,7 +13,8 @@ Optional Properties: interface - mod-def0-gpios : GPIO phandle and a specifier of the MOD-DEF0 (AKA Mod_ABS) - module presence input gpio signal, active (module absent) high + module presence input gpio signal, active (module absent) high. Must + not be present for SFF modules - los-gpios : GPIO phandle and a specifier of the Receiver Loss of Signal Indication input gpio signal, active (signal lost) high @@ -24,10 +27,11 @@ Optional Properties: - rate-select0-gpios : GPIO phandle and a specifier of the Rx Signaling Rate Select (AKA RS0) output gpio signal, low: low Rx rate, high: high Rx rate + Must not be present for SFF modules - rate-select1-gpios : GPIO phandle and a specifier of the Tx Signaling Rate Select (AKA RS1) output gpio signal (SFP+ only), low: low Tx rate, high: - high Tx rate + high Tx rate. Must not be present for SFF modules Example #1: Direct serdes to SFP connection -- cgit From d160c34134782dbd9b0dc06664d2f283c19f0dfa Mon Sep 17 00:00:00 2001 From: Miquel Raynal Date: Thu, 7 Dec 2017 11:12:59 +0100 Subject: dt-bindings: mvebu-uart: update documentation with extended UART Update the device tree binding documentation for the Marvell EBU UART, in order to allow describing the extended UART IP block, in addition to the already supported standard UART IP. This requires adding a new compatible string, the introduction of a clocks property, and extensions to the interrupts property. Signed-off-by: Miquel Raynal Reviewed-by: Gregory CLEMENT Acked-by: Rob Herring Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/serial/mvebu-uart.txt | 50 +++++++++++++++++++--- 1 file changed, 45 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/serial/mvebu-uart.txt b/Documentation/devicetree/bindings/serial/mvebu-uart.txt index d37fabe17bd1..2ae2fee7e023 100644 --- a/Documentation/devicetree/bindings/serial/mvebu-uart.txt +++ b/Documentation/devicetree/bindings/serial/mvebu-uart.txt @@ -1,13 +1,53 @@ -* Marvell UART : Non standard UART used in some of Marvell EBU SoCs (e.g., Armada-3700) +* Marvell UART : Non standard UART used in some of Marvell EBU SoCs + e.g., Armada-3700. Required properties: -- compatible: "marvell,armada-3700-uart" +- compatible: + - "marvell,armada-3700-uart" for the standard variant of the UART + (32 bytes FIFO, no DMA, level interrupts, 8-bit access to the + FIFO, baudrate limited to 230400). + - "marvell,armada-3700-uart-ext" for the extended variant of the + UART (128 bytes FIFO, DMA, front interrupts, 8-bit or 32-bit + accesses to the FIFO, baudrate unlimited by the dividers). - reg: offset and length of the register set for the device. -- interrupts: device interrupt +- clocks: UART reference clock used to derive the baudrate. If no clock + is provided (possible only with the "marvell,armada-3700-uart" + compatible string for backward compatibility), it will only work + if the baudrate was initialized by the bootloader and no baudrate + change will then be possible. +- interrupts: + - Must contain three elements for the standard variant of the IP + (marvell,armada-3700-uart): "uart-sum", "uart-tx" and "uart-rx", + respectively the UART sum interrupt, the UART TX interrupt and + UART RX interrupt. A corresponding interrupt-names property must + be defined. + - Must contain two elements for the extended variant of the IP + (marvell,armada-3700-uart-ext): "uart-tx" and "uart-rx", + respectively the UART TX interrupt and the UART RX interrupt. A + corresponding interrupts-names property must be defined. + - For backward compatibility reasons, a single element interrupts + property is also supported for the standard variant of the IP, + containing only the UART sum interrupt. This form is deprecated + and should no longer be used. Example: - serial@12000 { + uart0: serial@12000 { compatible = "marvell,armada-3700-uart"; reg = <0x12000 0x200>; - interrupts = <43>; + clocks = <&xtalclk>; + interrupts = + , + , + ; + interrupt-names = "uart-sum", "uart-tx", "uart-rx"; + }; + + uart1: serial@12200 { + compatible = "marvell,armada-3700-uart-ext"; + reg = <0x12200 0x30>; + clocks = <&xtalclk>; + interrupts = + , + ; + interrupt-names = "uart-tx", "uart-rx"; }; -- cgit From f3dafaa36b1fb7e50a8eb009d7ff39c3e7bb7756 Mon Sep 17 00:00:00 2001 From: Xingyu Chen Date: Fri, 8 Dec 2017 09:54:17 +0800 Subject: documentation: Add compatibles for Amlogic Meson AXG pin controllers Add compatibles for Amlogic Meson AXG pin controllers Reviewed-by: Neil Armstrong Acked-by: Rob Herring Signed-off-by: Xingyu Chen Signed-off-by: Yixun Lan Signed-off-by: Kevin Hilman --- Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt index 2392557ede27..2c12f9789116 100644 --- a/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/meson,pinctrl.txt @@ -9,6 +9,8 @@ Required properties for the root node: "amlogic,meson-gxbb-aobus-pinctrl" "amlogic,meson-gxl-periphs-pinctrl" "amlogic,meson-gxl-aobus-pinctrl" + "amlogic,meson-axg-periphs-pinctrl" + "amlogic,meson-axg-aobus-pinctrl" - reg: address and size of registers controlling irq functionality === GPIO sub-nodes === -- cgit From 271ba36e7b32916cd161c8af6cffb786a0687af7 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 9 Dec 2017 16:33:02 +0100 Subject: dt-bindings: chosen: Document linux,initrd-{start,end} MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These properties have been in use for a very long time (at least since 2005), but were never documented in chosen.txt. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/chosen.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt index e3b13ea7d2ae..45e79172a646 100644 --- a/Documentation/devicetree/bindings/chosen.txt +++ b/Documentation/devicetree/bindings/chosen.txt @@ -120,3 +120,18 @@ e.g. While this property does not represent a real hardware, the address and the size are expressed in #address-cells and #size-cells, respectively, of the root node. + +linux,initrd-start and linux,initrd-end +--------------------------------------- + +These properties hold the physical start and end address of an initrd that's +loaded by the bootloader. Note that linux,initrd-start is inclusive, but +linux,initrd-end is exclusive. +e.g. + +/ { + chosen { + linux,initrd-start = <0x82000000>; + linux,initrd-end = <0x82800000>; + }; +}; -- cgit From 3b73ad33873e3f9ed2fe06374cef03ec463e0285 Mon Sep 17 00:00:00 2001 From: Nishanth Menon Date: Sat, 9 Dec 2017 13:35:28 -0600 Subject: dt-bindings: mailbox: ti,message-manager: Fix interrupt name error Message Manager's mailbox interrupts are queue based and not proxy specific. The interrupt names are wrong in the binding, however correctly reflected in the example provided. Remove the relation to proxy ID in the documentation of binding. Existing device tree descriptions follow the correct conventions already and documentation update has been missed. Signed-off-by: Nishanth Menon Reviewed-by: Lokesh Vutla Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/mailbox/ti,message-manager.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt b/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt index c3b55b3ede8a..ebf0e3710cee 100644 --- a/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt +++ b/Documentation/devicetree/bindings/mailbox/ti,message-manager.txt @@ -20,9 +20,9 @@ Required properties: order referring to the transfer path. - interrupt-names: Contains interrupt names matching the rx transfer path for a given SoC. Receive interrupts shall be of the - format: "rx__". + format: "rx_". For ti,k2g-message-manager, this shall contain: - "rx_005_002", "rx_057_002" + "rx_005", "rx_057" - interrupts: Contains the interrupt information corresponding to interrupt-names property. -- cgit From 49c22f7b870550ba158f0e660f04641e29401bb8 Mon Sep 17 00:00:00 2001 From: Andreas Färber Date: Sun, 10 Dec 2017 00:25:06 +0100 Subject: dt-bindings: Add Infineon TLV493D-A1B6 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Infineon TLV493D-A1B6 is an I2C-based 3D Magnetic Sensor. Cc: Marius Tarcatu Signed-off-by: Andreas Färber Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/trivial-devices.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/trivial-devices.txt b/Documentation/devicetree/bindings/trivial-devices.txt index 390b99583ff7..2e3740f98c41 100644 --- a/Documentation/devicetree/bindings/trivial-devices.txt +++ b/Documentation/devicetree/bindings/trivial-devices.txt @@ -63,6 +63,7 @@ fsl,sgtl5000 SGTL5000: Ultra Low-Power Audio Codec gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface infineon,slb9635tt Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) infineon,slb9645tt Infineon SLB9645 I2C TPM (new protocol, max 400khz) +infineon,tlv493d-a1b6 Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor isil,isl1208 Intersil ISL1208 Low Power RTC with Battery Backed SRAM isil,isl1218 Intersil ISL1218 Low Power RTC with Battery Backed SRAM isil,isl12022 Intersil ISL12022 Real-time Clock -- cgit From 033dba2ec06c47a9fe1b190bc3281058fb20738d Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sun, 10 Dec 2017 01:02:29 +0900 Subject: kbuild: prepare to remove C files pre-generated by flex and bison In Linux build system convention, pre-generated files are version- controlled with a "_shipped" suffix. During the kernel building, they are simply shipped (copied) removing the suffix. This approach can reduce external tool dependency for the kernel build, but it is tedious to manually regenerate such artifacts from developers' point of view. (We need to do "make REGENERATE_PARSERS=1" every time we touch real source files such as *.l, *.y) Some months ago, I sent out RFC patches to run flex, bison, and gperf during the build. In the review and test, Linus noticed gperf-3.1 had changed the lookup function prototype. Then, the use of gperf in kernel was entirely removed by commit bb3290d91695 ("Remove gperf usage from toolchain"). This time, I tested several versions of flex and bison, and I was not hit by any compatibility issue except a flaw in flex-2.6.3; if you generate lexer for dtc and genksyms with flex-2.6.3, you will see "yywrap redefined" warning. This was not intentional, but a bug, fixed by flex-2.6.4. Otherwise, both flex and bison look fairly stable for a long time. This commit prepares some build rules to remove the _shipped files. Also, document minimal requirement for flex and bison. Rationale for the minimal version: The -Wmissing-prototypes option of GCC warns "no previous prototype" for lexers generated by flex-2.5.34 or older, so I chose 2.5.35 as the required version for flex. Flex-2.5.35 was released in 2008. Bison looks more stable. I did not see any problem with bison-2.0, released in 2004. I did not test bison-1.x, but bison-2.0 should be old enough. Tested flex versions: 2.5.35 2.5.36 2.5.37 2.5.39 2.6.0 2.6.1 2.6.2 2.6.3 (*) 2.6.4 (*) flex-2.6.3 causes "yywrap redefined" warning Tested bison versions: 2.0 2.1 2.2 2.3 2.4 2.4.1 2.5.1 2.6 2.6.1 2.6.2 2.6.3 2.6.4 2.6.5 2.7 2.7.1 3.0 3.0.1 3.0.2 3.0.3 3.0.4 Signed-off-by: Masahiro Yamada --- Documentation/process/changes.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'Documentation') diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 560beaef5a7c..81cdb528ad46 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -32,6 +32,8 @@ you probably needn't concern yourself with isdn4k-utils. GNU C 3.2 gcc --version GNU make 3.81 make --version binutils 2.20 ld -v +flex 2.5.35 flex --version +bison 2.0 bison --version util-linux 2.10o fdformat --version module-init-tools 0.9.10 depmod -V e2fsprogs 1.41.4 e2fsck -V @@ -79,6 +81,19 @@ The build system has, as of 4.13, switched to using thin archives (`ar T`) rather than incremental linking (`ld -r`) for built-in.o intermediate steps. This requires binutils 2.20 or newer. +Flex +---- + +Since Linux 4.16, the build system generates lexical analyzers +during build. This requires flex 2.5.35 or later. + + +Bison +----- + +Since Linux 4.16, the build system generates parsers +during build. This requires bison 2.0 or later. + Perl ---- @@ -333,6 +348,16 @@ Binutils - +Flex +---- + +- + +Bison +----- + +- + OpenSSL ------- -- cgit From c10e65b5874fe08643e40bf8d4d80627cc5e5da5 Mon Sep 17 00:00:00 2001 From: Heiko Stuebner Date: Fri, 8 Dec 2017 22:44:11 +0100 Subject: dt-bindings: gpu: mali-utgard: add rockchip,rk3328-mali compatible The rk3328 quad-core Cortex A53 uses a Mali-450MP2 with 2 PPs, so add a compatible for it. Signed-off-by: Heiko Stuebner Reviewed-by: Rob Herring --- Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt index c6814d7cc2b2..ad876548ab5d 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt +++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt @@ -17,6 +17,7 @@ Required properties: + rockchip,rk3066-mali + rockchip,rk3188-mali + rockchip,rk3228-mali + + rockchip,rk3328-mali + stericsson,db8500-mali - reg: Physical base address and length of the GPU registers -- cgit From da1b0029f527a9b4204e90ba6f14ee139fd76f9e Mon Sep 17 00:00:00 2001 From: Mimi Zohar Date: Thu, 29 Sep 2016 10:04:52 -0400 Subject: ima: support new "hash" and "dont_hash" policy actions The builtin ima_appraise_tcb policy, which is specified on the boot command line, can be replaced with a custom policy, normally early in the boot process. Custom policies can be more restrictive in some ways, like requiring file signatures, but can be less restrictive in other ways, like not appraising mutable files. With a less restrictive policy in place, files in the builtin policy might not be hashed and labeled with a security.ima hash. On reboot, files which should be labeled in the ima_appraise_tcb are not labeled, possibly preventing the system from booting properly. To resolve this problem, this patch extends the existing IMA policy actions "measure", "dont_measure", "appraise", "dont_appraise", and "audit" with "hash" and "dont_hash". The new "hash" action will write the file hash as security.ima, but without requiring the file to be appraised as well. For example, the builtin ima_appraise_tcb policy includes the rule, "appraise fowner=0". Adding the "hash fowner=0" rule to a custom policy, will cause the needed file hashes to be calculated and written as security.ima xattrs. Signed-off-by: Mimi Zohar Signed-off-by: Stefan Berger --- Documentation/ABI/testing/ima_policy | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index e76432b9954d..2028f2d093b2 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -17,7 +17,8 @@ Description: rule format: action [condition ...] - action: measure | dont_measure | appraise | dont_appraise | audit + action: measure | dont_measure | appraise | dont_appraise | + audit | hash | dont_hash condition:= base | lsm [option] base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=] [euid=] [fowner=]] -- cgit From f8d3bc10041914cceef4585a38cfdc071724b2a7 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Fri, 8 Dec 2017 14:46:41 +0100 Subject: eeprom: at25: Add DT support for EEPROMs with odd address bits Certain EEPROMS have a size that is larger than the number of address bytes would allow, and store the MSB of the address in bit 3 of the instruction byte. This can be described in platform data using EE_INSTR_BIT3_IS_ADDR, or in DT using the obsolete legacy "at25,addr-mode" property. But currently there exists no non-deprecated way to describe this in DT. Hence extend the existing "address-width" DT property to allow specifying 9 address bits, and enable support for that in the driver. This has been tested with a Microchip 25LC040A. Signed-off-by: Geert Uytterhoeven Reviewed-by: Rob Herring Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/eeprom/at25.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt index e823d90b802f..b3bde97dc199 100644 --- a/Documentation/devicetree/bindings/eeprom/at25.txt +++ b/Documentation/devicetree/bindings/eeprom/at25.txt @@ -11,7 +11,9 @@ Required properties: - spi-max-frequency : max spi frequency to use - pagesize : size of the eeprom page - size : total eeprom size in bytes -- address-width : number of address bits (one of 8, 16, or 24) +- address-width : number of address bits (one of 8, 9, 16, or 24). + For 9 bits, the MSB of the address is sent as bit 3 of the instruction + byte, before the address byte. Optional properties: - spi-cpha : SPI shifted clock phase, as per spi-bus bindings. -- cgit From cccd6fa435d7e4d1c4f34ac78974519e31aead9a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 23 Sep 2017 06:49:50 -0400 Subject: media: rc-core.rst: add an introduction for RC core The RC core does several assumptions, but those aren't documented anywhere, with could make harder for ones that want to understand what's there. So, add an introduction explaining the basic concepts of RC and how they're related to the RC core implementation. Acked-by: Sakari Ailus Acked-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/rc-core.rst | 77 ++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) (limited to 'Documentation') diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst index 41c2256dbf6a..4759f020d6b2 100644 --- a/Documentation/media/kapi/rc-core.rst +++ b/Documentation/media/kapi/rc-core.rst @@ -4,6 +4,83 @@ Remote Controller devices Remote Controller core ~~~~~~~~~~~~~~~~~~~~~~ +The remote controller core implements infrastructure to receive and send +remote controller keyboard keystrokes and mouse events. + +Every time a key is pressed on a remote controller, a scan code is produced. +Also, on most hardware, keeping a key pressed for more than a few dozens of +milliseconds produce a repeat key event. That's somewhat similar to what +a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the +remote controller core is implemented on the top of the linux input/evdev +interface. + +.. [#f1] + + The main difference is that, on keyboard events, the keyboard controller + produces one event for a key press and another one for key release. On + infrared-based remote controllers, there's no key release event. Instead, + an extra code is produced to indicate key repeats. + +However, most of the remote controllers use infrared (IR) to transmit signals. +As there are several protocols used to modulate infrared signals, one +important part of the core is dedicated to adjust the driver and the core +system to support the infrared protocol used by the emitter. + +The infrared transmission is done by blinking a infrared emitter using a +carrier. The carrier can be switched on or off by the IR transmitter +hardware. When the carrier is switched on, it is called *PULSE*. +When the carrier is switched off, it is called *SPACE*. + +In other words, a typical IR transmission can be viewed as a sequence of +*PULSE* and *SPACE* events, each with a given duration. + +The carrier parameters (frequency, duty cycle) and the intervals for +*PULSE* and *SPACE* events depend on the protocol. +For example, the NEC protocol uses a carrier of 38kHz, and transmissions +start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of +scan code, being 8 bits for address (usually it is a fixed number for a +given remote controller), followed by 8 bits of code. A bit "1" is modulated +with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0" is modulated +with 560µs *PULSE* followed by 560µs *SPACE*. + +At receiver, a simple low-pass filter can be used to convert the received +signal in a sequence of *PULSE/SPACE* events, filtering out the carrier +frequency. Due to that, the receiver doesn't care about the carrier's +actual frequency parameters: all it has to do is to measure the amount +of time it receives *PULSE/SPACE* events. +So, a simple IR receiver hardware will just provide a sequence of timings +for those events to the Kernel. The drivers for hardware with such kind of +receivers are identified by ``RC_DRIVER_IR_RAW``, as defined by +:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a +microcontroller that decode the *PULSE/SPACE* sequence and return scan +codes to the Kernel. Such kind of receivers are identified +by ``RC_DRIVER_SCANCODE``. + +.. [#f2] + + The RC core also supports devices that have just IR emitters, + without any receivers. Right now, all such devices work only in + raw TX mode. Such kind of hardware is identified as + ``RC_DRIVER_IR_RAW_TX``. + +When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR +receivers, it needs to decode the IR protocol, in order to obtain the +corresponding scan code. The protocols supported by the RC core are +defined at enum :c:type:`rc_proto`. + +When the RC code receives a scan code (either directly, by a driver +of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs +to convert into a Linux input event code. This is done via a mapping +table. + +The Kernel has support for mapping tables available on most media +devices. It also supports loading a table in runtime, via some +sysfs nodes. See the :ref:`RC userspace API ` +for more details. + +Remote controller data structures and functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. kernel-doc:: include/media/rc-core.h .. kernel-doc:: include/media/rc-map.h -- cgit From 66f1e6078e120d3503ce43de9715538f1122c304 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Sep 2017 13:35:45 -0400 Subject: media: v4l2-event.rst: improve events description Both v4l2-event.rst and v4l2-event.h have an overview of events, but there are some inconsistencies there: - at v4l2-event, the event's ring buffer is called kevent. Its name is, instead, v4l2_kevent; - Some things are mentioned on both places (with different words), others are either on one of the files. In order to cleanup this mess, put everything at v4l2-event.rst and improve it to be a little more coherent and to have cross references. Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-event.rst | 67 ++++++++++++++++++++++++++------- 1 file changed, 54 insertions(+), 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst index 9938d21ef4d1..5c7e31224ddc 100644 --- a/Documentation/media/kapi/v4l2-event.rst +++ b/Documentation/media/kapi/v4l2-event.rst @@ -5,27 +5,68 @@ V4L2 events The V4L2 events provide a generic way to pass events to user space. The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events. -Events are defined by a type and an optional ID. The ID may refer to a V4L2 -object such as a control ID. If unused, then the ID is 0. +Events are subscribed per-filehandle. An event specification consists of a +``type`` and is optionally associated with an object identified through the +``id`` field. If unused, then the ``id`` is 0. So an event is uniquely +identified by the ``(type, id)`` tuple. -When the user subscribes to an event the driver will allocate a number of -kevent structs for that event. So every (type, ID) event tuple will have -its own set of kevent structs. This guarantees that if a driver is generating -lots of events of one type in a short time, then that will not overwrite -events of another type. +The :c:type:`v4l2_fh` struct has a list of subscribed events on its +``subscribed`` field. -But if you get more events of one type than the number of kevents that were -reserved, then the oldest event will be dropped and the new one added. +When the user subscribes to an event, a :c:type:`v4l2_subscribed_event` +struct is added to :c:type:`v4l2_fh`\ ``.subscribed``, one for every +subscribed event. + +Each :c:type:`v4l2_subscribed_event` struct ends with a +:c:type:`v4l2_kevent` ringbuffer, with the size given by the caller +of :c:func:`v4l2_event_subscribe`. This ringbuffer is used to store any events +raised by the driver. + +So every ``(type, ID)`` event tuple will have its own +:c:type:`v4l2_kevent` ringbuffer. This guarantees that if a driver is +generating lots of events of one type in a short time, then that will +not overwrite events of another type. + +But if you get more events of one type than the size of the +:c:type:`v4l2_kevent` ringbuffer, then the oldest event will be dropped +and the new one added. + +The :c:type:`v4l2_kevent` struct links into the ``available`` +list of the :c:type:`v4l2_fh` struct so :ref:`VIDIOC_DQEVENT` will +know which event to dequeue first. + +Finally, if the event subscription is associated with a particular object +such as a V4L2 control, then that object needs to know about that as well +so that an event can be raised by that object. So the ``node`` field can +be used to link the :c:type:`v4l2_subscribed_event` struct into a list of +such objects. + +So to summarize: + +- struct :c:type:`v4l2_fh` has two lists: one of the ``subscribed`` events, + and one of the ``available`` events. + +- struct :c:type:`v4l2_subscribed_event` has a ringbuffer of raised + (pending) events of that particular type. + +- If struct :c:type:`v4l2_subscribed_event` is associated with a specific + object, then that object will have an internal list of + struct :c:type:`v4l2_subscribed_event` so it knows who subscribed an + event to that object. Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has ``merge()`` and ``replace()`` callbacks which drivers can set. These callbacks are called when a new event is raised and there is no more room. + The ``replace()`` callback allows you to replace the payload of the old event with that of the new event, merging any relevant data from the old payload into the new payload that replaces it. It is called when this event type has -only one kevent struct allocated. The ``merge()`` callback allows you to merge -the oldest event payload into that of the second-oldest event payload. It is -called when there are two or more kevent structs allocated. +a ringbuffer with size is one, i.e. only one event can be stored in the +ringbuffer. + +The ``merge()`` callback allows you to merge the oldest event payload into +that of the second-oldest event payload. It is called when +the ringbuffer has size is greater than one. This way no status information is lost, just the intermediate steps leading up to that state. @@ -73,7 +114,7 @@ The ops argument allows the driver to specify a number of callbacks: Callback Description ======== ============================================================== add called when a new listener gets added (subscribing to the same - event twice will only cause this callback to get called once) + event twice will only cause this callback to get called once) del called when a listener stops listening replace replace event 'old' with event 'new'. merge merge event 'old' into event 'new'. -- cgit From 4839c58f034ae41e2dfdd097240a69622cab4c73 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 28 Sep 2017 18:39:32 -0400 Subject: media: v4l2-dev: convert VFL_TYPE_* into an enum Using enums makes easier to document, as it can use kernel-doc markups. It also allows cross-referencing, with increases the kAPI readability. Please notice that now cx88_querycap() has to have a default for the VFL type, as there are more types than supported by the driver. Acked-By: Mike Isely Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-dev.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst index b29aa616c267..7bb0505b60f1 100644 --- a/Documentation/media/kapi/v4l2-dev.rst +++ b/Documentation/media/kapi/v4l2-dev.rst @@ -196,11 +196,18 @@ device. Which device is registered depends on the type argument. The following types exist: -- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices -- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext) -- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners -- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners -- ``VFL_TYPE_TOUCH``: ``/dev/v4l-touchX`` for touch sensors +========================== ==================== ============================== +:c:type:`vfl_devnode_type` Device name Usage +========================== ==================== ============================== +``VFL_TYPE_GRABBER`` ``/dev/videoX`` for video input/output devices +``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e. + closed captions, teletext) +``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners +``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices +``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio + (SDR) tuners +``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors +========================== ==================== ============================== The last argument gives you a certain amount of control over the device device node number used (i.e. the X in ``videoX``). Normally you will pass -1 -- cgit From dde7edff359461d07074ef2f0c4dc85b775d493f Mon Sep 17 00:00:00 2001 From: Sean Young Date: Mon, 11 Dec 2017 17:12:09 -0500 Subject: media: lirc: when transmitting scancodes, block until transmit is done The semantics for lirc IR transmit with raw IR is that the write call should block until the IR is transmitted. Some drivers have no idea when this actually is (e.g. mceusb), so there is a wait. This is useful for userspace, as it might want to send a IR button press, a gap of a predefined number of milliseconds, and then send a repeat message. It turns out that for transmitting scancodes this feature is even more useful, as user space has no idea how long the IR is. So, maintain the existing semantics for IR scancode transmit. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/lirc-write.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index dd3d1fe807a6..d4566b0a2015 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -60,8 +60,8 @@ When in :ref:`LIRC_MODE_SCANCODE ` mode, one and the protocol in the :c:type:`rc_proto`: member. All other members must be set to 0, else ``EINVAL`` is returned. If there is no protocol encoder for the protocol or the scancode is not valid for the specified protocol, -``EINVAL`` is returned. The write function may not wait until the scancode -is transmitted. +``EINVAL`` is returned. The write function blocks until the scancode +is transmitted by the hardware. Return Value -- cgit From ffd2e8df8d138e7436e218e0a9d3447a18b888e6 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Fri, 1 Dec 2017 11:50:33 -0600 Subject: resource: Set type of "reserve=" user-specified resources When we reserve regions because the user specified a "reserve=" parameter, set the resource type to either IORESOURCE_IO (for regions below 0x10000) or IORESOURCE_MEM. The test for 0x10000 is just a heuristic; obviously there can be memory below 0x10000 as well. Improve documentation of the "reserve=" parameter. Signed-off-by: Bjorn Helgaas --- Documentation/admin-guide/kernel-parameters.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 6571fbfdb2a1..78cdf6a637fc 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -3675,7 +3675,11 @@ [KNL, SMP] Set scheduler's default relax_domain_level. See Documentation/cgroup-v1/cpusets.txt. - reserve= [KNL,BUGS] Force the kernel to ignore some iomem area + reserve= [KNL,BUGS] Force kernel to ignore I/O ports or memory + Format: ,[,,,...] + Reserve I/O ports or memory so the kernel won't use + them. If is less than 0x10000, the region + is assumed to be I/O ports; otherwise it is memory. reservetop= [X86-32] Format: nn[KMG] -- cgit From bbecb07fa0af9a41507ce06d4631fdb3b5059417 Mon Sep 17 00:00:00 2001 From: Uwe Kleine-König Date: Mon, 18 Dec 2017 17:59:07 +0100 Subject: siox: new driver framework for eckelmann SIOX MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SIOX is a bus system invented at Eckelmann AG to control their building management and refrigeration systems. Traditionally the bus was implemented on custom microcontrollers, today Linux based machines are in use, too. The topology on a SIOX bus looks as follows: ,------->--DCLK-->---------------+----------------------. ^ v v ,--------. ,----------------------. ,------ | | | ,--------------. | | | |--->--DOUT-->---|->-|shift register|->-|--->---| | | | `--------------' | | | master | | device | | device | | | ,--------------. | | | |---<--DIN---<---|-<-|shift register|-<-|---<---| | | | `--------------' | | `--------' `----------------------' `------ v ^ ^ `----------DLD-------------------+----------------------' There are two control lines (DCLK and DLD) driven from the bus master to all devices in parallel and two daisy chained data lines, one for input and one for output. DCLK is the clock to shift both chains by a single bit. On an edge of DLD the devices latch both their input and output shift registers. This patch adds a framework for this bus type. Acked-by: Gavin Schenk Signed-off-by: Uwe Kleine-König Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-bus-siox | 87 ++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-bus-siox (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-siox b/Documentation/ABI/testing/sysfs-bus-siox new file mode 100644 index 000000000000..fed7c3765a4e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-siox @@ -0,0 +1,87 @@ +What: /sys/bus/siox/devices/siox-X/active +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + On reading represents the current state of the bus. If it + contains a "0" the bus is stopped and connected devices are + expected to not do anything because their watchdog triggered. + When the file contains a "1" the bus is operated and periodically + does a push-pull cycle to write and read data from the + connected devices. + When writing a "0" or "1" the bus moves to the described state. + +What: /sys/bus/siox/devices/siox-X/device_add +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Write-only file. Write + + + + to add a new device dynamically. is the name that is used to match + to a driver (similar to the platform bus). and define + the length of the input and output shift register in bytes respectively. + defines the 4 bit device type that is check to identify connection + problems. + The new device is added to the end of the existing chain. + +What: /sys/bus/siox/devices/siox-X/device_remove +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Write-only file. A single write removes the last device in the siox chain. + +What: /sys/bus/siox/devices/siox-X/poll_interval_ns +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Defines the interval between two poll cycles in nano seconds. + Note this is rounded to jiffies on writing. On reading the current value + is returned. + +What: /sys/bus/siox/devices/siox-X-Y/connected +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Read-only value. "0" means the Yth device on siox bus X isn't "connected" i.e. + communication with it is not ensured. "1" signals a working connection. + +What: /sys/bus/siox/devices/siox-X-Y/inbytes +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Read-only value reporting the inbytes value provided to siox-X/device_add + +What: /sys/bus/siox/devices/siox-X-Y/status_errors +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Counts the number of time intervals when the read status byte doesn't yield the + expected value. + +What: /sys/bus/siox/devices/siox-X-Y/type +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Read-only value reporting the type value provided to siox-X/device_add. + +What: /sys/bus/siox/devices/siox-X-Y/watchdog +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Read-only value reporting if the watchdog of the siox device is + active. "0" means the watchdog is not active and the device is expected to + be operational. "1" means the watchdog keeps the device in reset. + +What: /sys/bus/siox/devices/siox-X-Y/watchdog_errors +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Read-only value reporting the number to time intervals when the + watchdog was active. + +What: /sys/bus/siox/devices/siox-X-Y/outbytes +KernelVersion: 4.16 +Contact: Gavin Schenk , Uwe Kleine-König +Description: + Read-only value reporting the outbytes value provided to siox-X/device_add. -- cgit From c1b9d4c75cd549e08bd0596d7f9dcc20f7f6e8fa Mon Sep 17 00:00:00 2001 From: "H. Nikolaus Schaller" Date: Tue, 28 Nov 2017 16:48:54 +0100 Subject: omapdrm: panel: fix compatible vendor string for td028ttec1 The vendor name was "toppoly" but other panels and the vendor list have defined it as "tpo". So let's fix it in driver and bindings. We keep the old definition in parallel to stay compatible with potential older DTB setup. Signed-off-by: H. Nikolaus Schaller Signed-off-by: Tomi Valkeinen --- .../bindings/display/panel/toppoly,td028ttec1.txt | 30 ---------------------- .../bindings/display/panel/tpo,td028ttec1.txt | 30 ++++++++++++++++++++++ 2 files changed, 30 insertions(+), 30 deletions(-) delete mode 100644 Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt create mode 100644 Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt b/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt deleted file mode 100644 index 7175dc3740ac..000000000000 --- a/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt +++ /dev/null @@ -1,30 +0,0 @@ -Toppoly TD028TTEC1 Panel -======================== - -Required properties: -- compatible: "toppoly,td028ttec1" - -Optional properties: -- label: a symbolic name for the panel - -Required nodes: -- Video port for DPI input - -Example -------- - -lcd-panel: td028ttec1@0 { - compatible = "toppoly,td028ttec1"; - reg = <0>; - spi-max-frequency = <100000>; - spi-cpol; - spi-cpha; - - label = "lcd"; - port { - lcd_in: endpoint { - remote-endpoint = <&dpi_out>; - }; - }; -}; - diff --git a/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt b/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt new file mode 100644 index 000000000000..ed34253d9fb1 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/tpo,td028ttec1.txt @@ -0,0 +1,30 @@ +Toppoly TD028TTEC1 Panel +======================== + +Required properties: +- compatible: "tpo,td028ttec1" + +Optional properties: +- label: a symbolic name for the panel + +Required nodes: +- Video port for DPI input + +Example +------- + +lcd-panel: td028ttec1@0 { + compatible = "tpo,td028ttec1"; + reg = <0>; + spi-max-frequency = <100000>; + spi-cpol; + spi-cpha; + + label = "lcd"; + port { + lcd_in: endpoint { + remote-endpoint = <&dpi_out>; + }; + }; +}; + -- cgit From 32fdb624236e17f28813eecd9c6e4d6235974de4 Mon Sep 17 00:00:00 2001 From: Peter Ujfalusi Date: Thu, 30 Nov 2017 14:12:35 +0200 Subject: dt-bindings: display/ti: Add optional property to set memory bandwidth limit max-memory-bandwidth can be used to specify the maximum bandwidth dispc can use when reading display data from main memory. In some SoC (am437x for example) we have memory bandwidth limitation which causes underflow in the display subsystem. Signed-off-by: Peter Ujfalusi Acked-by: Rob Herring Signed-off-by: Tomi Valkeinen --- Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt | 5 +++++ Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt | 4 ++++ Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt | 4 ++++ Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt | 4 ++++ Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt | 4 ++++ 5 files changed, 21 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt index c30f9ec189ed..91279f1060fe 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt @@ -47,6 +47,11 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + + HDMI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt index afcd5a86c6a4..ee867c4d1152 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt @@ -28,6 +28,10 @@ Required properties: - ti,hwmods: "dss_dispc" - interrupts: the DISPC interrupt +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt index dc66e1447c31..cd02516a40b6 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt @@ -37,6 +37,10 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt index bc624db8888d..0f85f6b3a5a8 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt @@ -36,6 +36,10 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- diff --git a/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt index 118a486c47bb..20861218649f 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt @@ -36,6 +36,10 @@ Required properties: - clocks: handle to fclk - clock-names: "fck" +Optional properties: +- max-memory-bandwidth: Input memory (from main memory to dispc) bandwidth limit + in bytes per second + RFBI ---- -- cgit From 80313586356c8a06cc969724dea1cc58d2a04d99 Mon Sep 17 00:00:00 2001 From: Jan Kundrát Date: Tue, 12 Dec 2017 16:15:21 +0100 Subject: serial: max310x: Use level-triggered interrupts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I was getting this trace along with a disabled IRQ when I was generating heavy traffic over four daisy-chained UARTs (MAX14830) on my test kit (Marvell Armada AM388, Solidrun Clearfog Base): irq 51: nobody cared (try booting with the "irqpoll" option) CPU: 0 PID: 68 Comm: irq/51-spi1.2 Not tainted 4.14.4 #7 Hardware name: Marvell Armada 380/385 (Device Tree) [] (unwind_backtrace) from [] (show_stack+0x10/0x14) [] (show_stack) from [] (dump_stack+0x84/0x98) [] (dump_stack) from [] (__report_bad_irq+0x28/0xcc) [] (__report_bad_irq) from [] (note_interrupt+0x28c/0x2dc) [] (note_interrupt) from [] (handle_irq_event_percpu+0x4c/0x58) [] (handle_irq_event_percpu) from [] (handle_irq_event+0x44/0x68) [] (handle_irq_event) from [] (handle_edge_irq+0x12c/0x1dc) [] (handle_edge_irq) from [] (generic_handle_irq+0x24/0x34) [] (generic_handle_irq) from [] (mvebu_gpio_irq_handler+0xe0/0x184) [] (mvebu_gpio_irq_handler) from [] (generic_handle_irq+0x24/0x34) [] (generic_handle_irq) from [] (__handle_domain_irq+0x5c/0xb4) [] (__handle_domain_irq) from [] (gic_handle_irq+0x4c/0x90) [] (gic_handle_irq) from [] (__irq_svc+0x6c/0x90) Exception stack(0xeea77c30 to 0xeea77c78) 7c20: 0000000a 018cba80 0000000a f098f680 7c40: 0000020a f098f680 00000008 0000020a 018cba80 00000001 ee9302a0 eea76000 7c60: ef2b2640 eea77c80 c050687c c0506894 80070013 ffffffff [] (__irq_svc) from [] (orion_spi_setup_transfer+0x118/0x20c) [] (orion_spi_setup_transfer) from [] (orion_spi_transfer_one+0x1c/0x26c) [] (orion_spi_transfer_one) from [] (spi_transfer_one_message+0xec/0x500) [] (spi_transfer_one_message) from [] (__spi_pump_messages+0x3f4/0x680) [] (__spi_pump_messages) from [] (__spi_sync+0x1fc/0x200) [] (__spi_sync) from [] (spi_sync+0x24/0x3c) [] (spi_sync) from [] (spi_write_then_read+0xd0/0x17c) [] (spi_write_then_read) from [] (_regmap_raw_read+0xb0/0x250) [] (_regmap_raw_read) from [] (_regmap_bus_read+0x24/0x4c) [] (_regmap_bus_read) from [] (_regmap_read+0x60/0x148) [] (_regmap_read) from [] (regmap_read+0x3c/0x5c) [] (regmap_read) from [] (max310x_port_irq+0x104/0x2dc) [] (max310x_port_irq) from [] (max310x_ist+0x68/0xc0) [] (max310x_ist) from [] (irq_thread_fn+0x1c/0x54) [] (irq_thread_fn) from [] (irq_thread+0x12c/0x1f0) [] (irq_thread) from [] (kthread+0x128/0x158) [] (kthread) from [] (ret_from_fork+0x14/0x24) handlers: [] irq_default_primary_handler threaded [] max310x_ist Disabling IRQ #51 On a multi-UART max310x, each UART has its own interrupt status register which automatically de-asserts the IRQ line upon read. (There are also top-level IRQ indicator registers which are not clear-on-read, but they are not relevant here.) It was quite possible to receive a pending IRQ for, e.g., UART0, enter the threaded IRQ handler, clear the ISR for UART0 which de-asserts the IRQ line, and then race with another event on the same chip, but a different UART channel. That resulted in another edge on the shared-within-the-chip IRQ line which got intercepted by the kernel. That all led to an edge-level interrupt which was not being handled by anybody because our threaded handler hasn't finished yet. As the chip actually uses *level* triggered IRQs, let's convert the example DT bindings to these. Signed-off-by: Jan Kundrát Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/serial/maxim,max310x.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/serial/maxim,max310x.txt b/Documentation/devicetree/bindings/serial/maxim,max310x.txt index 83a919c241b0..0c58052a18bb 100644 --- a/Documentation/devicetree/bindings/serial/maxim,max310x.txt +++ b/Documentation/devicetree/bindings/serial/maxim,max310x.txt @@ -30,7 +30,7 @@ Example: clocks = <&clk20m>; clock-names = "osc"; interrupt-parent = <&gpio3>; - interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + interrupts = <7 IRQ_TYPE_LEVEL_LOW>; gpio-controller; #gpio-cells = <2>; }; -- cgit From b2497c1a7d864c5723e7abfdb1dffb5a9a0f092f Mon Sep 17 00:00:00 2001 From: Jan Kundrát Date: Sat, 9 Dec 2017 00:54:33 +0100 Subject: serial: max310x: Document clock setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As a kernel newcomer, I got bitten by lack of examples on this front. I had troubles figuring out where these clocks could be defined ("/clocks" is where the generic infrastructure expects them). One should also ensure that a unique name is used. Generic names such as "osc" tend to be already used by some board-wide clock crystals. Signed-off-by: Jan Kundrát Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/serial/maxim,max310x.txt | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/serial/maxim,max310x.txt b/Documentation/devicetree/bindings/serial/maxim,max310x.txt index 0c58052a18bb..823f77dd7978 100644 --- a/Documentation/devicetree/bindings/serial/maxim,max310x.txt +++ b/Documentation/devicetree/bindings/serial/maxim,max310x.txt @@ -24,13 +24,27 @@ Optional properties: 1 = active low. Example: + +/ { + clocks { + spi_uart_clk: osc_max14830 { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <3686400>; + }; + + }; +}; + +&spi0 { max14830: max14830@0 { compatible = "maxim,max14830"; reg = <0>; - clocks = <&clk20m>; + clocks = <&spi_uart_clk>; clock-names = "osc"; interrupt-parent = <&gpio3>; interrupts = <7 IRQ_TYPE_LEVEL_LOW>; gpio-controller; #gpio-cells = <2>; }; +}; -- cgit From 32277723ba7e9af0201df2341a3e71ea27605759 Mon Sep 17 00:00:00 2001 From: Finley Xiao Date: Fri, 15 Dec 2017 14:06:08 +0000 Subject: nvmem: rockchip-efuse: parse 'rockchip,efuse-size' The eFuse size is defined in property before, but the length of registers is not equal to the size on some platforms, so we add a new property to redefine it. Signed-off-by: Finley Xiao Acked-by: Rob Herring Signed-off-by: Heiko Stuebner Signed-off-by: Srinivas Kandagatla Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt index 60bec4782806..a6ef46dd1283 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt @@ -12,6 +12,10 @@ Required properties: - clocks: Should be the clock id of eFuse - clock-names: Should be "pclk_efuse" +Optional properties: +- rockchip,efuse-size: Should be exact eFuse size in byte, the eFuse + size in property will be invalid if define this property. + Deprecated properties: - compatible: "rockchip,rockchip-efuse" Old efuse compatible value compatible to rk3066a, rk3188 and rk3288 -- cgit From 9a479b0853bc39e5d9d77adc9b8da167951446e9 Mon Sep 17 00:00:00 2001 From: Finley Xiao Date: Fri, 15 Dec 2017 14:06:09 +0000 Subject: nvmem: rockchip-efuse: add support for rk3328-efuse This adds the necessary data for handling eFuse on the rk3328. Signed-off-by: Finley Xiao Acked-by: Rob Herring Signed-off-by: Heiko Stuebner Signed-off-by: Srinivas Kandagatla Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt index a6ef46dd1283..265bdb7dc8aa 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt @@ -6,6 +6,7 @@ Required properties: - "rockchip,rk3188-efuse" - for RK3188 SoCs. - "rockchip,rk3228-efuse" - for RK3228 SoCs. - "rockchip,rk3288-efuse" - for RK3288 SoCs. + - "rockchip,rk3328-efuse" - for RK3328 SoCs. - "rockchip,rk3368-efuse" - for RK3368 SoCs. - "rockchip,rk3399-efuse" - for RK3399 SoCs. - reg: Should contain the registers location and exact eFuse size -- cgit From fd639726bf15fca8ee1a00dce8e0096d0ad9bd18 Mon Sep 17 00:00:00 2001 From: Uwe Kleine-König Date: Tue, 19 Dec 2017 10:00:13 +0100 Subject: siox: add gpio bus driver MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This bus driver uses GPIOs to control the four SIOX bus lines. Acked-by: Gavin Schenk Signed-off-by: Uwe Kleine-König Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/siox/eckelmann,siox-gpio.txt | 19 +++++++++++++++++++ Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 2 files changed, 20 insertions(+) create mode 100644 Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.txt b/Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.txt new file mode 100644 index 000000000000..55259cf39c25 --- /dev/null +++ b/Documentation/devicetree/bindings/siox/eckelmann,siox-gpio.txt @@ -0,0 +1,19 @@ +Eckelmann SIOX GPIO bus + +Required properties: +- compatible : "eckelmann,siox-gpio" +- din-gpios, dout-gpios, dclk-gpios, dld-gpios: references gpios for the + corresponding bus signals. + +Examples: + + siox { + compatible = "eckelmann,siox-gpio"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_siox>; + + din-gpios = <&gpio6 11 0>; + dout-gpios = <&gpio6 8 0>; + dclk-gpios = <&gpio6 9 0>; + dld-gpios = <&gpio6 10 0>; + }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 0994bdd82cd3..889d1c0f5050 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -97,6 +97,7 @@ dptechnics DPTechnics dragino Dragino Technology Co., Limited ea Embedded Artists AB ebv EBV Elektronik +eckelmann Eckelmann AG edt Emerging Display Technologies eeti eGalax_eMPIA Technology Inc elan Elan Microelectronic Corp. -- cgit From 202318d37613d264e30d71cc32ef442492d6d279 Mon Sep 17 00:00:00 2001 From: Sagar Dharia Date: Mon, 11 Dec 2017 23:42:55 +0000 Subject: Documentation: Add SLIMbus summary SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by MIPI (Mobile Industry Processor Interface) alliance. SLIMbus is a 2-wire implementation, which is used to communicate with peripheral components like audio-codec. The summary of SLIMbus and API is documented in the 'summary' file. Signed-off-by: Sagar Dharia Signed-off-by: Srinivas Kandagatla Reviwed-by: Mark Brown Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/slimbus.rst | 127 +++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 Documentation/driver-api/slimbus.rst (limited to 'Documentation') diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d17a9876b473..ef7c9e0b179c 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -47,6 +47,7 @@ available subsections can be seen below. gpio misc_devices dmaengine/index + slimbus .. only:: subproject and html diff --git a/Documentation/driver-api/slimbus.rst b/Documentation/driver-api/slimbus.rst new file mode 100644 index 000000000000..7555ecd538de --- /dev/null +++ b/Documentation/driver-api/slimbus.rst @@ -0,0 +1,127 @@ +============================ +Linux kernel SLIMbus support +============================ + +Overview +======== + +What is SLIMbus? +---------------- +SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by +MIPI (Mobile Industry Processor Interface) alliance. The bus uses master/slave +configuration, and is a 2-wire multi-drop implementation (clock, and data). + +Currently, SLIMbus is used to interface between application processors of SoCs +(System-on-Chip) and peripheral components (typically codec). SLIMbus uses +Time-Division-Multiplexing to accommodate multiple data channels, and +a control channel. + +The control channel is used for various control functions such as bus +management, configuration and status updates. These messages can be unicast (e.g. +reading/writing device specific values), or multicast (e.g. data channel +reconfiguration sequence is a broadcast message announced to all devices) + +A data channel is used for data-transfer between 2 SLIMbus devices. Data +channel uses dedicated ports on the device. + +Hardware description: +--------------------- +SLIMbus specification has different types of device classifications based on +their capabilities. +A manager device is responsible for enumeration, configuration, and dynamic +channel allocation. Every bus has 1 active manager. + +A generic device is a device providing application functionality (e.g. codec). + +Framer device is responsible for clocking the bus, and transmitting frame-sync +and framing information on the bus. + +Each SLIMbus component has an interface device for monitoring physical layer. + +Typically each SoC contains SLIMbus component having 1 manager, 1 framer device, +1 generic device (for data channel support), and 1 interface device. +External peripheral SLIMbus component usually has 1 generic device (for +functionality/data channel support), and an associated interface device. +The generic device's registers are mapped as 'value elements' so that they can +be written/read using SLIMbus control channel exchanging control/status type of +information. +In case there are multiple framer devices on the same bus, manager device is +responsible to select the active-framer for clocking the bus. + +Per specification, SLIMbus uses "clock gears" to do power management based on +current frequency and bandwidth requirements. There are 10 clock gears and each +gear changes the SLIMbus frequency to be twice its previous gear. + +Each device has a 6-byte enumeration-address and the manager assigns every +device with a 1-byte logical address after the devices report presence on the +bus. + +Software description: +--------------------- +There are 2 types of SLIMbus drivers: + +slim_controller represents a 'controller' for SLIMbus. This driver should +implement duties needed by the SoC (manager device, associated +interface device for monitoring the layers and reporting errors, default +framer device). + +slim_device represents the 'generic device/component' for SLIMbus, and a +slim_driver should implement driver for that slim_device. + +Device notifications to the driver: +----------------------------------- +Since SLIMbus devices have mechanisms for reporting their presence, the +framework allows drivers to bind when corresponding devices report their +presence on the bus. +However, it is possible that the driver needs to be probed +first so that it can enable corresponding SLIMbus device (e.g. power it up and/or +take it out of reset). To support that behavior, the framework allows drivers +to probe first as well (e.g. using standard DeviceTree compatibility field). +This creates the necessity for the driver to know when the device is functional +(i.e. reported present). device_up callback is used for that reason when the +device reports present and is assigned a logical address by the controller. + +Similarly, SLIMbus devices 'report absent' when they go down. A 'device_down' +callback notifies the driver when the device reports absent and its logical +address assignment is invalidated by the controller. + +Another notification "boot_device" is used to notify the slim_driver when +controller resets the bus. This notification allows the driver to take necessary +steps to boot the device so that it's functional after the bus has been reset. + +Driver and Controller APIs: +-------------------------- +.. kernel-doc:: include/linux/slimbus.h + :internal: + +.. kernel-doc:: drivers/slimbus/slimbus.h + :internal: + +.. kernel-doc:: drivers/slimbus/core.c + :export: + +Clock-pause: +------------ +SLIMbus mandates that a reconfiguration sequence (known as clock-pause) be +broadcast to all active devices on the bus before the bus can enter low-power +mode. Controller uses this sequence when it decides to enter low-power mode so +that corresponding clocks and/or power-rails can be turned off to save power. +Clock-pause is exited by waking up framer device (if controller driver initiates +exiting low power mode), or by toggling the data line (if a slave device wants +to initiate it). + +Clock-pause APIs: +~~~~~~~~~~~~~~~~~ +.. kernel-doc:: drivers/slimbus/sched.c + :export: + +Messaging: +---------- +The framework supports regmap and read/write apis to exchange control-information +with a SLIMbus device. APIs can be synchronous or asynchronous. +The header file has more documentation about messaging APIs. + +Messaging APIs: +~~~~~~~~~~~~~~~ +.. kernel-doc:: drivers/slimbus/messaging.c + :export: -- cgit From 2df7296603399cbad9522ce111ea0c5270153990 Mon Sep 17 00:00:00 2001 From: Sagar Dharia Date: Mon, 11 Dec 2017 23:42:56 +0000 Subject: dt-bindings: Add SLIMbus bindings SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by MIPI (Mobile Industry Processor Interface) alliance. SLIMbus is a 2-wire implementation, which is used to communicate with peripheral components like audio-codec. This patch adds device tree bindings for the slimbus. Signed-off-by: Sagar Dharia Signed-off-by: Srinivas Kandagatla Reviewed-by: Rob Herring Reviwed-by: Mark Brown Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/slimbus/bus.txt | 50 +++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 Documentation/devicetree/bindings/slimbus/bus.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/slimbus/bus.txt b/Documentation/devicetree/bindings/slimbus/bus.txt new file mode 100644 index 000000000000..52fa6426388c --- /dev/null +++ b/Documentation/devicetree/bindings/slimbus/bus.txt @@ -0,0 +1,50 @@ +SLIM(Serial Low Power Interchip Media Bus) bus + +SLIMbus is a 2-wire bus, and is used to communicate with peripheral +components like audio-codec. + +Required property for SLIMbus controller node: +- compatible - name of SLIMbus controller + +Child nodes: +Every SLIMbus controller node can contain zero or more child nodes +representing slave devices on the bus. Every SLIMbus slave device is +uniquely determined by the enumeration address containing 4 fields: +Manufacturer ID, Product code, Device index, and Instance value for +the device. +If child node is not present and it is instantiated after device +discovery (slave device reporting itself present). + +In some cases it may be necessary to describe non-probeable device +details such as non-standard ways of powering up a device. In +such cases, child nodes for those devices will be present as +slaves of the SLIMbus controller, as detailed below. + +Required property for SLIMbus child node if it is present: +- reg - Should be ('Device index', 'Instance ID') from SLIMbus + Enumeration Address. + Device Index Uniquely identifies multiple Devices within + a single Component. + Instance ID Is for the cases where multiple Devices of the + same type or Class are attached to the bus. + +- compatible -"slimMID,PID". The textual representation of Manufacturer ID, + Product Code, shall be in lower case hexadecimal with leading + zeroes suppressed + +SLIMbus example for Qualcomm's slimbus manager component: + + slim@28080000 { + compatible = "qcom,apq8064-slim", "qcom,slim"; + reg = <0x28080000 0x2000>, + interrupts = <0 33 0>; + clocks = <&lcc SLIMBUS_SRC>, <&lcc AUDIO_SLIMBUS_CLK>; + clock-names = "iface", "core"; + #address-cells = <2>; + #size-cell = <0>; + + codec: wcd9310@1,0{ + compatible = "slim217,60"; + reg = <1 0>; + }; + }; -- cgit From ba42b2dc6593bf15f50f9f9a8e82889d56af98f4 Mon Sep 17 00:00:00 2001 From: Sagar Dharia Date: Mon, 11 Dec 2017 23:43:04 +0000 Subject: dt-bindings: Add qcom slimbus controller bindings This patch add device tree bindings for Qualcomm slimbus controller. Signed-off-by: Sagar Dharia Signed-off-by: Srinivas Kandagatla Reviewed-by: Rob Herring Reviwed-by: Mark Brown Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/slimbus/slim-qcom-ctrl.txt | 39 ++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt b/Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt new file mode 100644 index 000000000000..922dcb8ff24a --- /dev/null +++ b/Documentation/devicetree/bindings/slimbus/slim-qcom-ctrl.txt @@ -0,0 +1,39 @@ +Qualcomm SLIMbus controller +This controller is used if applications processor driver controls SLIMbus +master component. + +Required properties: + + - #address-cells - refer to Documentation/devicetree/bindings/slimbus/bus.txt + - #size-cells - refer to Documentation/devicetree/bindings/slimbus/bus.txt + + - reg : Offset and length of the register region(s) for the device + - reg-names : Register region name(s) referenced in reg above + Required register resource entries are: + "ctrl": Physical address of controller register blocks + "slew": required for "qcom,apq8064-slim" SOC. + - compatible : should be "qcom,-slim" for SOC specific compatible + followed by "qcom,slim" for fallback. + - interrupts : Interrupt number used by this controller + - clocks : Interface and core clocks used by this SLIMbus controller + - clock-names : Required clock-name entries are: + "iface" : Interface clock for this controller + "core" : Interrupt for controller core's BAM + +Example: + + slim@28080000 { + compatible = "qcom,apq8064-slim", "qcom,slim"; + reg = <0x28080000 0x2000>, <0x80207C 4>; + reg-names = "ctrl", "slew"; + interrupts = <0 33 0>; + clocks = <&lcc SLIMBUS_SRC>, <&lcc AUDIO_SLIMBUS_CLK>; + clock-names = "iface", "core"; + #address-cells = <2>; + #size-cell = <0>; + + wcd9310: audio-codec@1,0{ + compatible = "slim217,60"; + reg = <1 0>; + }; + }; -- cgit From 8ecf4264efef64303d6b6c13d35f7c46024fb2ff Mon Sep 17 00:00:00 2001 From: Sanyog Kale Date: Thu, 14 Dec 2017 11:19:32 +0530 Subject: Documentation: Add SoundWire summary SoundWire is a new Linux bus which implements a new MIPI bus protocol 'SoundWire'. The summary of SoundWire bus and API is documented in the 'summary' file. Signed-off-by: Sanyog Kale Signed-off-by: Hardik T Shah Reviewed-by: Philippe Ombredanne Acked-By: Pierre-Louis Bossart Reviewed-by: Takashi Iwai Signed-off-by: Vinod Koul Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/soundwire/index.rst | 15 ++ Documentation/driver-api/soundwire/summary.rst | 207 +++++++++++++++++++++++++ 3 files changed, 223 insertions(+) create mode 100644 Documentation/driver-api/soundwire/index.rst create mode 100644 Documentation/driver-api/soundwire/summary.rst (limited to 'Documentation') diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index ef7c9e0b179c..e9b41b1634f3 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -48,6 +48,7 @@ available subsections can be seen below. misc_devices dmaengine/index slimbus + soundwire/index .. only:: subproject and html diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst new file mode 100644 index 000000000000..647e94654752 --- /dev/null +++ b/Documentation/driver-api/soundwire/index.rst @@ -0,0 +1,15 @@ +======================= +SoundWire Documentation +======================= + +.. toctree:: + :maxdepth: 1 + + summary + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/soundwire/summary.rst b/Documentation/driver-api/soundwire/summary.rst new file mode 100644 index 000000000000..8193125a2bfb --- /dev/null +++ b/Documentation/driver-api/soundwire/summary.rst @@ -0,0 +1,207 @@ +=========================== +SoundWire Subsystem Summary +=========================== + +SoundWire is a new interface ratified in 2015 by the MIPI Alliance. +SoundWire is used for transporting data typically related to audio +functions. SoundWire interface is optimized to integrate audio devices in +mobile or mobile inspired systems. + +SoundWire is a 2-pin multi-drop interface with data and clock line. It +facilitates development of low cost, efficient, high performance systems. +Broad level key features of SoundWire interface include: + + (1) Transporting all of payload data channels, control information, and setup + commands over a single two-pin interface. + + (2) Lower clock frequency, and hence lower power consumption, by use of DDR + (Dual Data Rate) data transmission. + + (3) Clock scaling and optional multiple data lanes to give wide flexibility + in data rate to match system requirements. + + (4) Device status monitoring, including interrupt-style alerts to the Master. + +The SoundWire protocol supports up to eleven Slave interfaces. All the +interfaces share the common Bus containing data and clock line. Each of the +Slaves can support up to 14 Data Ports. 13 Data Ports are dedicated to audio +transport. Data Port0 is dedicated to transport of Bulk control information, +each of the audio Data Ports (1..14) can support up to 8 Channels in +transmit or receiving mode (typically fixed direction but configurable +direction is enabled by the specification). Bandwidth restrictions to +~19.2..24.576Mbits/s don't however allow for 11*13*8 channels to be +transmitted simultaneously. + +Below figure shows an example of connectivity between a SoundWire Master and +two Slave devices. :: + + +---------------+ +---------------+ + | | Clock Signal | | + | Master |-------+-------------------------------| Slave | + | Interface | | Data Signal | Interface 1 | + | |-------|-------+-----------------------| | + +---------------+ | | +---------------+ + | | + | | + | | + +--+-------+--+ + | | + | Slave | + | Interface 2 | + | | + +-------------+ + + +Terminology +=========== + +The MIPI SoundWire specification uses the term 'device' to refer to a Master +or Slave interface, which of course can be confusing. In this summary and +code we use the term interface only to refer to the hardware. We follow the +Linux device model by mapping each Slave interface connected on the bus as a +device managed by a specific driver. The Linux SoundWire subsystem provides +a framework to implement a SoundWire Slave driver with an API allowing +3rd-party vendors to enable implementation-defined functionality while +common setup/configuration tasks are handled by the bus. + +Bus: +Implements SoundWire Linux Bus which handles the SoundWire protocol. +Programs all the MIPI-defined Slave registers. Represents a SoundWire +Master. Multiple instances of Bus may be present in a system. + +Slave: +Registers as SoundWire Slave device (Linux Device). Multiple Slave devices +can register to a Bus instance. + +Slave driver: +Driver controlling the Slave device. MIPI-specified registers are controlled +directly by the Bus (and transmitted through the Master driver/interface). +Any implementation-defined Slave register is controlled by Slave driver. In +practice, it is expected that the Slave driver relies on regmap and does not +request direct register access. + +Programming interfaces (SoundWire Master interface Driver) +========================================================== + +SoundWire Bus supports programming interfaces for the SoundWire Master +implementation and SoundWire Slave devices. All the code uses the "sdw" +prefix commonly used by SoC designers and 3rd party vendors. + +Each of the SoundWire Master interfaces needs to be registered to the Bus. +Bus implements API to read standard Master MIPI properties and also provides +callback in Master ops for Master driver to implement its own functions that +provides capabilities information. DT support is not implemented at this +time but should be trivial to add since capabilities are enabled with the +``device_property_`` API. + +The Master interface along with the Master interface capabilities are +registered based on board file, DT or ACPI. + +Following is the Bus API to register the SoundWire Bus: + +.. code-block:: c + + int sdw_add_bus_master(struct sdw_bus *bus) + { + if (!bus->dev) + return -ENODEV; + + mutex_init(&bus->lock); + INIT_LIST_HEAD(&bus->slaves); + + /* Check ACPI for Slave devices */ + sdw_acpi_find_slaves(bus); + + /* Check DT for Slave devices */ + sdw_of_find_slaves(bus); + + return 0; + } + +This will initialize sdw_bus object for Master device. "sdw_master_ops" and +"sdw_master_port_ops" callback functions are provided to the Bus. + +"sdw_master_ops" is used by Bus to control the Bus in the hardware specific +way. It includes Bus control functions such as sending the SoundWire +read/write messages on Bus, setting up clock frequency & Stream +Synchronization Point (SSP). The "sdw_master_ops" structure abstracts the +hardware details of the Master from the Bus. + +"sdw_master_port_ops" is used by Bus to setup the Port parameters of the +Master interface Port. Master interface Port register map is not defined by +MIPI specification, so Bus calls the "sdw_master_port_ops" callback +function to do Port operations like "Port Prepare", "Port Transport params +set", "Port enable and disable". The implementation of the Master driver can +then perform hardware-specific configurations. + +Programming interfaces (SoundWire Slave Driver) +=============================================== + +The MIPI specification requires each Slave interface to expose a unique +48-bit identifier, stored in 6 read-only dev_id registers. This dev_id +identifier contains vendor and part information, as well as a field enabling +to differentiate between identical components. An additional class field is +currently unused. Slave driver is written for a specific vendor and part +identifier, Bus enumerates the Slave device based on these two ids. +Slave device and driver match is done based on these two ids . Probe +of the Slave driver is called by Bus on successful match between device and +driver id. A parent/child relationship is enforced between Master and Slave +devices (the logical representation is aligned with the physical +connectivity). + +The information on Master/Slave dependencies is stored in platform data, +board-file, ACPI or DT. The MIPI Software specification defines additional +link_id parameters for controllers that have multiple Master interfaces. The +dev_id registers are only unique in the scope of a link, and the link_id +unique in the scope of a controller. Both dev_id and link_id are not +necessarily unique at the system level but the parent/child information is +used to avoid ambiguity. + +.. code-block:: c + + static const struct sdw_device_id slave_id[] = { + SDW_SLAVE_ENTRY(0x025d, 0x700, 0), + {}, + }; + MODULE_DEVICE_TABLE(sdw, slave_id); + + static struct sdw_driver slave_sdw_driver = { + .driver = { + .name = "slave_xxx", + .pm = &slave_runtime_pm, + }, + .probe = slave_sdw_probe, + .remove = slave_sdw_remove, + .ops = &slave_slave_ops, + .id_table = slave_id, + }; + + +For capabilities, Bus implements API to read standard Slave MIPI properties +and also provides callback in Slave ops for Slave driver to implement own +function that provides capabilities information. Bus needs to know a set of +Slave capabilities to program Slave registers and to control the Bus +reconfigurations. + +Future enhancements to be done +============================== + + (1) Bulk Register Access (BRA) transfers. + + + (2) Multiple data lane support. + +Links +===== + +SoundWire MIPI specification 1.1 is available at: +https://members.mipi.org/wg/All-Members/document/70290 + +SoundWire MIPI DisCo (Discovery and Configuration) specification is +available at: +https://www.mipi.org/specifications/mipi-disco-soundwire + +(publicly accessible with registration or directly accessible to MIPI +members) + +MIPI Alliance Manufacturer ID Page: mid.mipi.org -- cgit From f9d79126195374c285035777b9d6abd24ceba363 Mon Sep 17 00:00:00 2001 From: Athanasios Oikonomou Date: Sat, 16 Dec 2017 07:23:38 -0500 Subject: media: dvb_frontend: add physical layer scrambling support This commit adds a new property DTV_SCRAMBLING_SEQUENCE_INDEX. This 18 bit field, when present, carries the index of the DVB-S2 physical layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. There is no explicit signalling method to convey scrambling sequence index to the receiver. If S2 satellite delivery system descriptor is available it can be used to read the scrambling sequence index (EN 300 468 table 41). By default, gold scrambling sequence index 0 is used. The valid scrambling sequence index range is from 0 to 262142. Increase the DVB API version in order userspace to be aware of the changes. Signed-off-by: Athanasios Oikonomou Acked-by: Ralph Metzler Signed-off-by: Mauro Carvalho Chehab --- .../media/uapi/dvb/fe_property_parameters.rst | 18 ++++++++++++++++++ .../uapi/dvb/frontend-property-satellite-systems.rst | 2 ++ 2 files changed, 20 insertions(+) (limited to 'Documentation') diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst index 6eef507fea50..3524dcae4604 100644 --- a/Documentation/media/uapi/dvb/fe_property_parameters.rst +++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst @@ -987,3 +987,21 @@ Possible values: 0, 1, LNA_AUTO 1, LNA on use the special macro LNA_AUTO to set LNA auto + + +.. _DTV-SCRAMBLING-SEQUENCE-INDEX: + +DTV_SCRAMBLING_SEQUENCE_INDEX +============================= + +Used on DVB-S2. + +This 18 bit field, when present, carries the index of the DVB-S2 physical +layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. +There is no explicit signalling method to convey scrambling sequence index +to the receiver. If S2 satellite delivery system descriptor is available +it can be used to read the scrambling sequence index (EN 300 468 table 41). + +By default, gold scrambling sequence index 0 is used. + +The valid scrambling sequence index range is from 0 to 262142. diff --git a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst index 1f40399c68ff..2929e6999a7a 100644 --- a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst +++ b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst @@ -60,6 +60,8 @@ following parameters: - :ref:`DTV_STREAM_ID ` +- :ref:`DTV_SCRAMBLING_SEQUENCE_INDEX ` + In addition, the :ref:`DTV QoS statistics ` are also valid. -- cgit From fb1f5f79ae96331a0201b4080d34f3bc3b5c0b1d Mon Sep 17 00:00:00 2001 From: Michael Chan Date: Sat, 16 Dec 2017 03:09:40 -0500 Subject: net: Introduce NETIF_F_GRO_HW. Introduce NETIF_F_GRO_HW feature flag for NICs that support hardware GRO. With this flag, we can now independently turn on or off hardware GRO when GRO is on. Previously, drivers were using NETIF_F_GRO to control hardware GRO and so it cannot be independently turned on or off without affecting GRO. Hardware GRO (just like GRO) guarantees that packets can be re-segmented by TSO/GSO to reconstruct the original packet stream. Logically, GRO_HW should depend on GRO since it a subset, but we will let individual drivers enforce this dependency as they see fit. Since NETIF_F_GRO is not propagated between upper and lower devices, NETIF_F_GRO_HW should follow suit since it is a subset of GRO. In other words, a lower device can independent have GRO/GRO_HW enabled or disabled and no feature propagation is required. This will preserve the current GRO behavior. This can be changed later if we decide to propagate GRO/ GRO_HW/RXCSUM from upper to lower devices. Cc: Ariel Elior Cc: everest-linux-l2@cavium.com Signed-off-by: Michael Chan Acked-by: Alexander Duyck Signed-off-by: David S. Miller --- Documentation/networking/netdev-features.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/netdev-features.txt b/Documentation/networking/netdev-features.txt index 7413eb05223b..c77f9d57eb91 100644 --- a/Documentation/networking/netdev-features.txt +++ b/Documentation/networking/netdev-features.txt @@ -163,3 +163,12 @@ This requests that the NIC receive all possible frames, including errored frames (such as bad FCS, etc). This can be helpful when sniffing a link with bad packets on it. Some NICs may receive more packets if also put into normal PROMISC mode. + +* rx-gro-hw + +This requests that the NIC enables Hardware GRO (generic receive offload). +Hardware GRO is basically the exact reverse of TSO, and is generally +stricter than Hardware LRO. A packet stream merged by Hardware GRO must +be re-segmentable by GSO or TSO back to the exact original packet stream. +Hardware GRO is dependent on RXCSUM since every packet successfully merged +by hardware must also have the checksum verified by hardware. -- cgit From 81ee6f1ef9b1e93b2dc0a77211e9809ffbeb7ecb Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sun, 17 Dec 2017 03:34:33 +0100 Subject: dt-bindings: display: panel: Fix compatible string for Toshiba LT089AC29000 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The compatible string for this panel was specified as toshiba,lt089ac29000.txt. I believe this is a mistake. Fixes: 06e733e41f87 ("drm/panel: simple: add Toshiba LT089AC19000") Cc: Lucas Stach Signed-off-by: Jonathan Neuschäfer Acked-by: Lucas Stach Signed-off-by: Rob Herring --- .../devicetree/bindings/display/panel/toshiba,lt089ac29000.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt b/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt index 4c0caaf246c9..89826116628c 100644 --- a/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt +++ b/Documentation/devicetree/bindings/display/panel/toshiba,lt089ac29000.txt @@ -1,7 +1,7 @@ Toshiba 8.9" WXGA (1280x768) TFT LCD panel Required properties: -- compatible: should be "toshiba,lt089ac29000.txt" +- compatible: should be "toshiba,lt089ac29000" - power-supply: as specified in the base binding This binding is compatible with the simple-panel binding, which is specified -- cgit From 05a627ccac268c03da770cc462c63a46ff2eddc7 Mon Sep 17 00:00:00 2001 From: Ludovic Barre Date: Mon, 18 Dec 2017 16:17:44 +0100 Subject: devicetree: bindings: Document supported STM32 SoC family This adds a list of supported STM32 SoC bindings. Signed-off-by: Gwenael Treuveur Signed-off-by: Ludovic Barre Reviewed-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/arm/stm32.txt | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 Documentation/devicetree/bindings/arm/stm32.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/stm32.txt b/Documentation/devicetree/bindings/arm/stm32.txt new file mode 100644 index 000000000000..05762b08a7bb --- /dev/null +++ b/Documentation/devicetree/bindings/arm/stm32.txt @@ -0,0 +1,9 @@ +STMicroelectronics STM32 Platforms Device Tree Bindings + +Each device tree must specify which STM32 SoC it uses, +using one of the following compatible strings: + + st,stm32f429 + st,stm32f469 + st,stm32f746 + st,stm32h743 -- cgit From 4ef4cc13eab265eb3ff56b8269e5a5b96b2169e5 Mon Sep 17 00:00:00 2001 From: Ludovic Barre Date: Mon, 18 Dec 2017 16:17:49 +0100 Subject: pinctrl: stm32: Add STM32MP157 MPU support This driver consists of 2 controllers due to a hole in mapping: -1 controller for GPIO bankA to K. -1 controller for GPIO bankZ. Signed-off-by: Alexandre Torgue Signed-off-by: Ludovic Barre Reviewed-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index 58c2a4c229db..2c46f30b62c5 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -12,6 +12,8 @@ Required properies: "st,stm32f469-pinctrl" "st,stm32f746-pinctrl" "st,stm32h743-pinctrl" + "st,stm32mp157-pinctrl" + "st,stm32mp157-z-pinctrl" - #address-cells: The value of this property must be 1 - #size-cells : The value of this property must be 1 - ranges : defines mapping between pin controller node (parent) to -- cgit From 5fa4b105d12b68b452c836492bde3a57ed732344 Mon Sep 17 00:00:00 2001 From: Sean Wang Date: Tue, 12 Dec 2017 14:24:18 +0800 Subject: dt-bindings: pinctrl: add bindings for MediaTek MT7622 SoC Add devicetree bindings for MediaTek MT7622 pinctrl driver. Signed-off-by: Sean Wang Reviewed-by: Biao Huang Acked-by: Rob Herring Signed-off-by: Linus Walleij --- .../devicetree/bindings/pinctrl/pinctrl-mt7622.txt | 351 +++++++++++++++++++++ 1 file changed, 351 insertions(+) create mode 100644 Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt new file mode 100644 index 000000000000..f18ed99f6e14 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt @@ -0,0 +1,351 @@ +== MediaTek MT7622 pinctrl controller == + +Required properties for the root node: + - compatible: Should be one of the following + "mediatek,mt7622-pinctrl" for MT7622 SoC + - reg: offset and length of the pinctrl space + + - gpio-controller: Marks the device node as a GPIO controller. + - #gpio-cells: Should be two. The first cell is the pin number and the + second is the GPIO flags. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +MT7622 pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, slew rate, etc. + +We support 2 types of configuration nodes. Those nodes can be either pinmux +nodes or pinconf nodes. Each configuration node can consist of multiple nodes +describing the pinmux and pinconf options. + +The name of each subnode doesn't matter as long as it is unique; all subnodes +should be enumerated and processed purely based on their content. + +== pinmux nodes content == + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinmux subnode: + +Required properties are: + - groups: An array of strings. Each string contains the name of a group. + Valid values for these names are listed below. + - function: A string containing the name of the function to mux to the + group. Valid values for function names are listed below. + +== pinconf nodes content == + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pinconf subnode: + +Required properties are: + - pins: An array of strings. Each string contains the name of a pin. + Valid values for these names are listed below. + - groups: An array of strings. Each string contains the name of a group. + Valid values for these names are listed below. + +Optional properies are: + bias-disable, bias-pull, bias-pull-down, input-enable, + input-schmitt-enable, input-schmitt-disable, output-enable + output-low, output-high, drive-strength, slew-rate + + Valid arguments for 'slew-rate' are '0' for no slew rate controlled and '1' for + slower slew rate respectively. + Valid arguments for 'drive-strength', 4, 8, 12, or 16 in mA. + +The following specific properties as defined are valid to specify in a pinconf +subnode: + +Optional properties are: + - mediatek,tdsel: An integer describing the steps for output level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments are from 0 + to 15. + - mediatek,rdsel: An integer describing the steps for input level shifter duty + cycle when asserted (high pulse width adjustment). Valid arguments are from 0 + to 63. + +== Valid values for pins, function and groups on MT7622 == + +Valid values for pins are: +pins can be referenced via the pin names as the below table shown and the +related physical number is also put ahead of those names which helps cross +references to pins between groups to know whether pins assignment conflict +happens among devices try to acquire those available pins. + + Pin #: Valid values for pins + ----------------------------- + PIN 0: "GPIO_A" + PIN 1: "I2S1_IN" + PIN 2: "I2S1_OUT" + PIN 3: "I2S_BCLK" + PIN 4: "I2S_WS" + PIN 5: "I2S_MCLK" + PIN 6: "TXD0" + PIN 7: "RXD0" + PIN 8: "SPI_WP" + PIN 9: "SPI_HOLD" + PIN 10: "SPI_CLK" + PIN 11: "SPI_MOSI" + PIN 12: "SPI_MISO" + PIN 13: "SPI_CS" + PIN 14: "I2C_SDA" + PIN 15: "I2C_SCL" + PIN 16: "I2S2_IN" + PIN 17: "I2S3_IN" + PIN 18: "I2S4_IN" + PIN 19: "I2S2_OUT" + PIN 20: "I2S3_OUT" + PIN 21: "I2S4_OUT" + PIN 22: "GPIO_B" + PIN 23: "MDC" + PIN 24: "MDIO" + PIN 25: "G2_TXD0" + PIN 26: "G2_TXD1" + PIN 27: "G2_TXD2" + PIN 28: "G2_TXD3" + PIN 29: "G2_TXEN" + PIN 30: "G2_TXC" + PIN 31: "G2_RXD0" + PIN 32: "G2_RXD1" + PIN 33: "G2_RXD2" + PIN 34: "G2_RXD3" + PIN 35: "G2_RXDV" + PIN 36: "G2_RXC" + PIN 37: "NCEB" + PIN 38: "NWEB" + PIN 39: "NREB" + PIN 40: "NDL4" + PIN 41: "NDL5" + PIN 42: "NDL6" + PIN 43: "NDL7" + PIN 44: "NRB" + PIN 45: "NCLE" + PIN 46: "NALE" + PIN 47: "NDL0" + PIN 48: "NDL1" + PIN 49: "NDL2" + PIN 50: "NDL3" + PIN 51: "MDI_TP_P0" + PIN 52: "MDI_TN_P0" + PIN 53: "MDI_RP_P0" + PIN 54: "MDI_RN_P0" + PIN 55: "MDI_TP_P1" + PIN 56: "MDI_TN_P1" + PIN 57: "MDI_RP_P1" + PIN 58: "MDI_RN_P1" + PIN 59: "MDI_RP_P2" + PIN 60: "MDI_RN_P2" + PIN 61: "MDI_TP_P2" + PIN 62: "MDI_TN_P2" + PIN 63: "MDI_TP_P3" + PIN 64: "MDI_TN_P3" + PIN 65: "MDI_RP_P3" + PIN 66: "MDI_RN_P3" + PIN 67: "MDI_RP_P4" + PIN 68: "MDI_RN_P4" + PIN 69: "MDI_TP_P4" + PIN 70: "MDI_TN_P4" + PIN 71: "PMIC_SCL" + PIN 72: "PMIC_SDA" + PIN 73: "SPIC1_CLK" + PIN 74: "SPIC1_MOSI" + PIN 75: "SPIC1_MISO" + PIN 76: "SPIC1_CS" + PIN 77: "GPIO_D" + PIN 78: "WATCHDOG" + PIN 79: "RTS3_N" + PIN 80: "CTS3_N" + PIN 81: "TXD3" + PIN 82: "RXD3" + PIN 83: "PERST0_N" + PIN 84: "PERST1_N" + PIN 85: "WLED_N" + PIN 86: "EPHY_LED0_N" + PIN 87: "AUXIN0" + PIN 88: "AUXIN1" + PIN 89: "AUXIN2" + PIN 90: "AUXIN3" + PIN 91: "TXD4" + PIN 92: "RXD4" + PIN 93: "RTS4_N" + PIN 94: "CST4_N" + PIN 95: "PWM1" + PIN 96: "PWM2" + PIN 97: "PWM3" + PIN 98: "PWM4" + PIN 99: "PWM5" + PIN 100: "PWM6" + PIN 101: "PWM7" + PIN 102: "GPIO_E" + +Valid values for function are: + "emmc", "eth", "i2c", "i2s", "ir", "led", "flash", "pcie", + "pmic", "pwm", "sd", "spi", "tdm", "uart", "watchdog" + +Valid values for groups are: +additional data is put followingly with valid value allowing us to know which +applicable function and which relevant pins (in pin#) are able applied for that +group. + + Valid value function pins (in pin#) + ------------------------------------------------------------------------- + "emmc" "emmc" 40, 41, 42, 43, 44, 45, + 47, 48, 49, 50 + "emmc_rst" "emmc" 37 + "esw" "eth" 51, 52, 53, 54, 55, 56, + 57, 58, 59, 60, 61, 62, + 63, 64, 65, 66, 67, 68, + 69, 70 + "esw_p0_p1" "eth" 51, 52, 53, 54, 55, 56, + 57, 58 + "esw_p2_p3_p4" "eth" 59, 60, 61, 62, 63, 64, + 65, 66, 67, 68, 69, 70 + "rgmii_via_esw" "eth" 59, 60, 61, 62, 63, 64, + 65, 66, 67, 68, 69, 70 + "rgmii_via_gmac1" "eth" 59, 60, 61, 62, 63, 64, + 65, 66, 67, 68, 69, 70 + "rgmii_via_gmac2" "eth" 25, 26, 27, 28, 29, 30, + 31, 32, 33, 34, 35, 36 + "mdc_mdio" "eth" 23, 24 + "i2c0" "i2c" 14, 15 + "i2c1_0" "i2c" 55, 56 + "i2c1_1" "i2c" 73, 74 + "i2c1_2" "i2c" 87, 88 + "i2c2_0" "i2c" 57, 58 + "i2c2_1" "i2c" 75, 76 + "i2c2_2" "i2c" 89, 90 + "i2s_in_mclk_bclk_ws" "i2s" 3, 4, 5 + "i2s1_in_data" "i2s" 1 + "i2s2_in_data" "i2s" 16 + "i2s3_in_data" "i2s" 17 + "i2s4_in_data" "i2s" 18 + "i2s_out_mclk_bclk_ws" "i2s" 3, 4, 5 + "i2s1_out_data" "i2s" 2 + "i2s2_out_data" "i2s" 19 + "i2s3_out_data" "i2s" 20 + "i2s4_out_data" "i2s" 21 + "ir_0_tx" "ir" 16 + "ir_1_tx" "ir" 59 + "ir_2_tx" "ir" 99 + "ir_0_rx" "ir" 17 + "ir_1_rx" "ir" 60 + "ir_2_rx" "ir" 100 + "ephy_leds" "led" 86, 91, 92, 93, 94 + "ephy0_led" "led" 86 + "ephy1_led" "led" 91 + "ephy2_led" "led" 92 + "ephy3_led" "led" 93 + "ephy4_led" "led" 94 + "wled" "led" 85 + "par_nand" "flash" 37, 38, 39, 40, 41, 42, + 43, 44, 45, 46, 47, 48, + 49, 50 + "snfi" "flash" 8, 9, 10, 11, 12, 13 + "spi_nor" "flash" 8, 9, 10, 11, 12, 13 + "pcie0_0_waken" "pcie" 14 + "pcie0_1_waken" "pcie" 79 + "pcie1_0_waken" "pcie" 14 + "pcie0_0_clkreq" "pcie" 15 + "pcie0_1_clkreq" "pcie" 80 + "pcie1_0_clkreq" "pcie" 15 + "pcie0_pad_perst" "pcie" 83 + "pcie1_pad_perst" "pcie" 84 + "pmic_bus" "pmic" 71, 72 + "pwm_ch1_0" "pwm" 51 + "pwm_ch1_1" "pwm" 73 + "pwm_ch1_2" "pwm" 95 + "pwm_ch2_0" "pwm" 52 + "pwm_ch2_1" "pwm" 74 + "pwm_ch2_2" "pwm" 96 + "pwm_ch3_0" "pwm" 53 + "pwm_ch3_1" "pwm" 75 + "pwm_ch3_2" "pwm" 97 + "pwm_ch4_0" "pwm" 54 + "pwm_ch4_1" "pwm" 67 + "pwm_ch4_2" "pwm" 76 + "pwm_ch4_3" "pwm" 98 + "pwm_ch5_0" "pwm" 68 + "pwm_ch5_1" "pwm" 77 + "pwm_ch5_2" "pwm" 99 + "pwm_ch6_0" "pwm" 69 + "pwm_ch6_1" "pwm" 78 + "pwm_ch6_2" "pwm" 81 + "pwm_ch6_3" "pwm" 100 + "pwm_ch7_0" "pwm" 70 + "pwm_ch7_1" "pwm" 82 + "pwm_ch7_2" "pwm" 101 + "sd_0" "sd" 16, 17, 18, 19, 20, 21 + "sd_1" "sd" 25, 26, 27, 28, 29, 30 + "spic0_0" "spi" 63, 64, 65, 66 + "spic0_1" "spi" 79, 80, 81, 82 + "spic1_0" "spi" 67, 68, 69, 70 + "spic1_1" "spi" 73, 74, 75, 76 + "spic2_0_wp_hold" "spi" 8, 9 + "spic2_0" "spi" 10, 11, 12, 13 + "tdm_0_out_mclk_bclk_ws" "tdm" 8, 9, 10 + "tdm_0_in_mclk_bclk_ws" "tdm" 11, 12, 13 + "tdm_0_out_data" "tdm" 20 + "tdm_0_in_data" "tdm" 21 + "tdm_1_out_mclk_bclk_ws" "tdm" 57, 58, 59 + "tdm_1_in_mclk_bclk_ws" "tdm" 60, 61, 62 + "tdm_1_out_data" "tdm" 55 + "tdm_1_in_data" "tdm" 56 + "uart0_0_tx_rx" "uart" 6, 7 + "uart1_0_tx_rx" "uart" 55, 56 + "uart1_0_rts_cts" "uart" 57, 58 + "uart1_1_tx_rx" "uart" 73, 74 + "uart1_1_rts_cts" "uart" 75, 76 + "uart2_0_tx_rx" "uart" 3, 4 + "uart2_0_rts_cts" "uart" 1, 2 + "uart2_1_tx_rx" "uart" 51, 52 + "uart2_1_rts_cts" "uart" 53, 54 + "uart2_2_tx_rx" "uart" 59, 60 + "uart2_2_rts_cts" "uart" 61, 62 + "uart2_3_tx_rx" "uart" 95, 96 + "uart3_0_tx_rx" "uart" 57, 58 + "uart3_1_tx_rx" "uart" 81, 82 + "uart3_1_rts_cts" "uart" 79, 80 + "uart4_0_tx_rx" "uart" 61, 62 + "uart4_1_tx_rx" "uart" 91, 92 + "uart4_1_rts_cts" "uart" 93, 94 + "uart4_2_tx_rx" "uart" 97, 98 + "uart4_2_rts_cts" "uart" 95, 96 + "watchdog" "watchdog" 78 + +Example: + + pio: pinctrl@10211000 { + compatible = "mediatek,mt7622-pinctrl"; + reg = <0 0x10211000 0 0x1000>; + gpio-controller; + #gpio-cells = <2>; + + pinctrl_eth_default: eth-default { + mux-mdio { + groups = "mdc_mdio"; + function = "eth"; + drive-strength = <12>; + }; + + mux-gmac2 { + groups = "gmac2"; + function = "eth"; + drive-strength = <12>; + }; + + mux-esw { + groups = "esw"; + function = "eth"; + drive-strength = <8>; + }; + + conf-mdio { + pins = "MDC"; + bias-pull-up; + }; + }; + }; -- cgit From ee05baa0bfe634f747b51c44e1f9355c5ff2e64e Mon Sep 17 00:00:00 2001 From: Noralf Trønnes Date: Fri, 15 Dec 2017 18:51:15 +0100 Subject: drm/docs: Add todo entry for drm_fb_helper_fbdev_setup() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add entry for conversion of drivers to new helpers. Signed-off-by: Noralf Trønnes Reviewed-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20171215175119.36181-4-noralf@tronnes.org --- Documentation/gpu/todo.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'Documentation') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index f421a54527d2..1e593370f64f 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -194,6 +194,24 @@ drm_mode_config_helper_suspend/resume(). Contact: Maintainer of the driver you plan to convert +Convert drivers to use drm_fb_helper_fbdev_setup/teardown() +----------------------------------------------------------- + +Most drivers can use drm_fb_helper_fbdev_setup() except maybe: + +- amdgpu which has special logic to decide whether to call + drm_helper_disable_unused_functions() + +- armada which isn't atomic and doesn't call + drm_helper_disable_unused_functions() + +- i915 which calls drm_fb_helper_initial_config() in a worker + +Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can +probably use drm_fb_helper_fbdev_teardown(). + +Contact: Maintainer of the driver you plan to convert + Core refactorings ================= -- cgit From ca84eaeb3e0520555ee031b5ed26ce1b4b1bbd84 Mon Sep 17 00:00:00 2001 From: Magnus Damm Date: Wed, 20 Dec 2017 09:48:00 -0700 Subject: iommu/ipmmu-vmsa: Add r8a7796 DT binding Update the IPMMU DT binding documentation to include the r8a7796 compat string for R-Car M3-W. Signed-off-by: Magnus Damm Acked-by: Laurent Pinchart Acked-by: Rob Herring Acked-by: Simon Horman Acked-by: Geert Uytterhoeven Signed-off-by: Alex Williamson --- Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt index 857df929a654..43cff3e449d0 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -16,6 +16,7 @@ Required Properties: - "renesas,ipmmu-r8a7793" for the R8A7793 (R-Car M2-N) IPMMU. - "renesas,ipmmu-r8a7794" for the R8A7794 (R-Car E2) IPMMU. - "renesas,ipmmu-r8a7795" for the R8A7795 (R-Car H3) IPMMU. + - "renesas,ipmmu-r8a7796" for the R8A7796 (R-Car M3-W) IPMMU. - "renesas,ipmmu-vmsa" for generic R-Car Gen2 VMSA-compatible IPMMU. - reg: Base address and size of the IPMMU registers. -- cgit From 9327b810bb7e1f3322fe8ed862a62fe0f2c9f14b Mon Sep 17 00:00:00 2001 From: Simon Horman Date: Wed, 20 Dec 2017 09:48:01 -0700 Subject: iommu/ipmmu-vmsa: Add r8a779(70|95) DT bindings Update the IPMMU DT binding documentation to include the r8a77970 (R-Car V3M) and r8a77995 (R-Car D3) compat strings. Based on work for r8a7796 by Magnus Damm. Signed-off-by: Simon Horman Reviewed-by: Geert Uytterhoeven Signed-off-by: Alex Williamson --- Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt index 43cff3e449d0..1fd5d69647ca 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -17,6 +17,8 @@ Required Properties: - "renesas,ipmmu-r8a7794" for the R8A7794 (R-Car E2) IPMMU. - "renesas,ipmmu-r8a7795" for the R8A7795 (R-Car H3) IPMMU. - "renesas,ipmmu-r8a7796" for the R8A7796 (R-Car M3-W) IPMMU. + - "renesas,ipmmu-r8a77970" for the R8A77970 (R-Car V3M) IPMMU. + - "renesas,ipmmu-r8a77995" for the R8A77995 (R-Car D3) IPMMU. - "renesas,ipmmu-vmsa" for generic R-Car Gen2 VMSA-compatible IPMMU. - reg: Base address and size of the IPMMU registers. -- cgit From a227cf4dfd74a873857c9cc017100168d01539ed Mon Sep 17 00:00:00 2001 From: Matthias Brugger Date: Fri, 1 Dec 2017 13:07:06 +0100 Subject: dt-bindings: ARM: Mediatek: Fix ethsys documentation The ethsys registers a reset controller, so we need to specify a reset cell. This patch fixes the documentation. Signed-off-by: Matthias Brugger Reviewed-by: Rob Herring Acked-by: Stephen Boyd --- Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt index 7aa3fa167668..6cc7840ff37a 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt @@ -20,4 +20,5 @@ ethsys: clock-controller@1b000000 { compatible = "mediatek,mt2701-ethsys", "syscon"; reg = <0 0x1b000000 0 0x1000>; #clock-cells = <1>; + #reset-cells = <1>; }; -- cgit From 97bbf6623ebea1517e74c21ee59ff6fe133ce7fd Mon Sep 17 00:00:00 2001 From: Michael Chan Date: Tue, 19 Dec 2017 16:12:56 -0500 Subject: net: Clarify dev_weight documentation for LRO and GRO_HW. Reported-by: Marcelo Ricardo Leitner Signed-off-by: Michael Chan Signed-off-by: David S. Miller --- Documentation/sysctl/net.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index b67044a2575f..35c62f522754 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -95,7 +95,9 @@ dev_weight -------------- The maximum number of packets that kernel can handle on a NAPI interrupt, -it's a Per-CPU variable. +it's a Per-CPU variable. For drivers that support LRO or GRO_HW, a hardware +aggregated packet is counted as one packet in this context. + Default: 64 dev_weight_rx_bias -- cgit From e71802647bfd639a9f53e49a4ef86a2bfdbeb611 Mon Sep 17 00:00:00 2001 From: Bjorn Andersson Date: Wed, 29 Nov 2017 16:00:40 -0800 Subject: soc: qcom: smp2p: Access APCS as mailbox client Attempt to acquire the APCS IPC through the mailbox framework and fall back to the old syscon based approach, to allow us to move away from using the syscon. Signed-off-by: Bjorn Andersson Signed-off-by: Andy Gross --- Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt index af9ca37221ce..a35af2dafdad 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt @@ -17,9 +17,15 @@ processor ID) and a string identifier. Value type: Definition: one entry specifying the smp2p notification interrupt -- qcom,ipc: +- mboxes: Usage: required Value type: + Definition: reference to the associated doorbell in APCS, as described + in mailbox/mailbox.txt + +- qcom,ipc: + Usage: required, unless mboxes is specified + Value type: Definition: three entries specifying the outgoing ipc bit used for signaling the remote end of the smp2p edge: - phandle to a syscon node representing the apcs registers -- cgit From 5a4ecd4b273b81b8e826ec8713b71448c09ffd3f Mon Sep 17 00:00:00 2001 From: Florian Fainelli Date: Wed, 29 Nov 2017 09:52:59 -0800 Subject: dt-bindings: arm: Add entry for Broadcom Brahma-B53 Broadcom's Brahma-B53 CPU is an ARMv8A processor used on a number of DSL, Cable Modem and Set-top-box SoCs. Acked-by: Rob Herring Signed-off-by: Florian Fainelli --- Documentation/devicetree/bindings/arm/cpus.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index a0009b72e9be..f4a777039f03 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -169,6 +169,7 @@ described below. "arm,cortex-r5" "arm,cortex-r7" "brcm,brahma-b15" + "brcm,brahma-b53" "brcm,vulcan" "cavium,thunder" "cavium,thunder2" -- cgit From 911e9322c350df236e4614c1259d52c705245c78 Mon Sep 17 00:00:00 2001 From: Florian Fainelli Date: Wed, 29 Nov 2017 10:33:51 -0800 Subject: dt-bindings: arm: brcmstb: Correct BIUCTRL node documentation Correct the Device Tree bindings for the HIF_CPUBIUCTRL node whose compatible string is actually brcm,bcm-cpu-biu-ctrl. Also document in the binding the fallback property ("brcm,brcmstb-cpu-biu-ctrl") and update the example accordingly. Reviewed-by: Rob Herring Signed-off-by: Florian Fainelli --- .../devicetree/bindings/arm/bcm/brcm,brcmstb.txt | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt index 790e6b0b8306..c052caad36e8 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt @@ -17,21 +17,23 @@ Further, syscon nodes that map platform-specific registers used for general system control is required: - compatible: "brcm,bcm-sun-top-ctrl", "syscon" - - compatible: "brcm,bcm-hif-cpubiuctrl", "syscon" + - compatible: "brcm,bcm-cpu-biu-ctrl", + "brcm,brcmstb-cpu-biu-ctrl", + "syscon" - compatible: "brcm,bcm-hif-continuation", "syscon" -hif-cpubiuctrl node +cpu-biu-ctrl node ------------------- -SoCs with Broadcom Brahma15 ARM-based CPUs have a specific Bus Interface Unit -(BIU) block which controls and interfaces the CPU complex to the different -Memory Controller Ports (MCP), one per memory controller (MEMC). This BIU block -offers a feature called Write Pairing which consists in collapsing two adjacent -cache lines into a single (bursted) write transaction towards the memory -controller (MEMC) to maximize write bandwidth. +SoCs with Broadcom Brahma15 ARM-based and Brahma53 ARM64-based CPUs have a +specific Bus Interface Unit (BIU) block which controls and interfaces the CPU +complex to the different Memory Controller Ports (MCP), one per memory +controller (MEMC). This BIU block offers a feature called Write Pairing which +consists in collapsing two adjacent cache lines into a single (bursted) write +transaction towards the memory controller (MEMC) to maximize write bandwidth. Required properties: - - compatible: must be "brcm,bcm7445-hif-cpubiuctrl", "syscon" + - compatible: must be "brcm,bcm7445-cpu-biu-ctrl", "brcm,brcmstb-cpu-biu-ctrl", "syscon" Optional properties: @@ -52,7 +54,7 @@ example: }; hif_cpubiuctrl: syscon@3e2400 { - compatible = "brcm,bcm7445-hif-cpubiuctrl", "syscon"; + compatible = "brcm,bcm7445-cpu-biu-ctrl", "brcm,brcmstb-cpu-biu-ctrl", "syscon"; reg = <0x3e2400 0x5b4>; brcm,write-pairing; }; -- cgit From caa92ee84ba02aa2619b087d81a9e2e54a2235fd Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Tue, 19 Dec 2017 17:03:42 +0100 Subject: dt-bindings: gpio: rcar: Correct SoC family name for R8A7778 R8A7778 is R-Car (not R-Mobile) M1. Signed-off-by: Geert Uytterhoeven Acked-by: Simon Horman Reviewed-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index a7ac460ad657..9474138d776e 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -5,7 +5,7 @@ Required Properties: - compatible: should contain one or more of the following: - "renesas,gpio-r8a7743": for R8A7743 (RZ/G1M) compatible GPIO controller. - "renesas,gpio-r8a7745": for R8A7745 (RZ/G1E) compatible GPIO controller. - - "renesas,gpio-r8a7778": for R8A7778 (R-Mobile M1) compatible GPIO controller. + - "renesas,gpio-r8a7778": for R8A7778 (R-Car M1) compatible GPIO controller. - "renesas,gpio-r8a7779": for R8A7779 (R-Car H1) compatible GPIO controller. - "renesas,gpio-r8a7790": for R8A7790 (R-Car H2) compatible GPIO controller. - "renesas,gpio-r8a7791": for R8A7791 (R-Car M2-W) compatible GPIO controller. -- cgit From b88a17cb93db369d7820064168dc2ba2484c75c6 Mon Sep 17 00:00:00 2001 From: "weiyi.lu@mediatek.com" Date: Tue, 28 Nov 2017 15:28:17 +0800 Subject: dt-bindings: soc: add MT2712 power dt-bindings Add power dt-bindings for MT2712. Acked-by: Rob Herring Signed-off-by: Weiyi Lu Signed-off-by: Matthias Brugger --- Documentation/devicetree/bindings/soc/mediatek/scpsys.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt index 40056f7990f8..76bf45b893fa 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt @@ -12,11 +12,13 @@ power/power_domain.txt. It provides the power domains defined in - include/dt-bindings/power/mt8173-power.h - include/dt-bindings/power/mt6797-power.h - include/dt-bindings/power/mt2701-power.h +- include/dt-bindings/power/mt2712-power.h - include/dt-bindings/power/mt7622-power.h Required properties: - compatible: Should be one of: - "mediatek,mt2701-scpsys" + - "mediatek,mt2712-scpsys" - "mediatek,mt6797-scpsys" - "mediatek,mt7622-scpsys" - "mediatek,mt8173-scpsys" @@ -27,6 +29,7 @@ Required properties: These are clocks which hardware needs to be enabled before enabling certain power domains. Required clocks for MT2701: "mm", "mfg", "ethif" + Required clocks for MT2712: "mm", "mfg", "venc", "jpgdec", "audio", "vdec" Required clocks for MT6797: "mm", "mfg", "vdec" Required clocks for MT7622: "hif_sel" Required clocks for MT8173: "mm", "mfg", "venc", "venc_lt" -- cgit From dff9cba6f8ef2fe26dadbaebacc7cbf7ed50a327 Mon Sep 17 00:00:00 2001 From: Niklas Cassel Date: Wed, 20 Dec 2017 00:29:34 +0100 Subject: bindings: PCI: artpec: Add support for endpoint mode The PCIe controller integrated in ARTPEC-6 SoCs is capable of operating in endpoint mode. Add endpoint mode support to the artpec6 driver. Signed-off-by: Niklas Cassel Signed-off-by: Lorenzo Pieralisi Acked-by: Rob Herring --- Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt index 4e4aee4439ea..33eef7ae5a23 100644 --- a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt +++ b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt @@ -4,7 +4,8 @@ This PCIe host controller is based on the Synopsys DesignWare PCIe IP and thus inherits all the common properties defined in designware-pcie.txt. Required properties: -- compatible: "axis,artpec6-pcie", "snps,dw-pcie" +- compatible: "axis,artpec6-pcie", "snps,dw-pcie" for ARTPEC-6 in RC mode; + "axis,artpec6-pcie-ep", "snps,dw-pcie" for ARTPEC-6 in EP mode; - reg: base addresses and lengths of the PCIe controller (DBI), the PHY controller, and configuration address space. - reg-names: Must include the following entries: -- cgit From 4c3f9e9cfe5ddacd2af978043056767ac0bb00d2 Mon Sep 17 00:00:00 2001 From: Niklas Cassel Date: Wed, 20 Dec 2017 00:29:38 +0100 Subject: bindings: PCI: artpec: Add support for the ARTPEC-7 SoC Add support for the ARTPEC-7 SoC in the artpec6 driver. The ARTPEC-6 SoC and the ARTPEC-7 SoC are very similar. Unfortunately, some fields in the PCIECFG and PCIESTAT register have changed. Signed-off-by: Niklas Cassel Signed-off-by: Lorenzo Pieralisi Acked-by: Rob Herring --- Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt index 33eef7ae5a23..979dc7b6cfe8 100644 --- a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt +++ b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt @@ -6,6 +6,8 @@ and thus inherits all the common properties defined in designware-pcie.txt. Required properties: - compatible: "axis,artpec6-pcie", "snps,dw-pcie" for ARTPEC-6 in RC mode; "axis,artpec6-pcie-ep", "snps,dw-pcie" for ARTPEC-6 in EP mode; + "axis,artpec7-pcie", "snps,dw-pcie" for ARTPEC-7 in RC mode; + "axis,artpec7-pcie-ep", "snps,dw-pcie" for ARTPEC-7 in EP mode; - reg: base addresses and lengths of the PCIe controller (DBI), the PHY controller, and configuration address space. - reg-names: Must include the following entries: -- cgit From 064cbc4f6a1e910771e6c29cb819b6ee9eb881fc Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 30 Nov 2017 14:32:39 +0100 Subject: platform/x86: samsung-laptop: Grammar s/are can/can/ Signed-off-by: Geert Uytterhoeven Signed-off-by: Andy Shevchenko --- Documentation/ABI/testing/sysfs-driver-samsung-laptop | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop index 63c1ad0212fc..34d3a3359cf4 100644 --- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop @@ -3,7 +3,7 @@ Date: January 1, 2010 KernelVersion: 2.6.33 Contact: Greg Kroah-Hartman Description: Some Samsung laptops have different "performance levels" - that are can be modified by a function key, and by this + that can be modified by a function key, and by this sysfs file. These values don't always make a whole lot of sense, but some users like to modify them to keep their fans quiet at all costs. Reading from this file -- cgit From feffce1d9d9a3c109ed62d76eb4a962511c1bbfe Mon Sep 17 00:00:00 2001 From: Tony Lindgren Date: Wed, 13 Dec 2017 16:36:47 -0800 Subject: ARM: dts: Add generic ti,sysc compatible in addition to the custom ones Otherwise we cannot use generic OF_DEV_AUXDATA match without listing all the compatibles separately for OF_DEV_AUXDATA. Let's also update the binding accordingly. Let's also fix omap4.dtsi to use "ti,sysc-omap4-sr" compatible as we have documented in the binding. This was not noticed earlier as we're still probing SmartReflex driver with platform data. Reviewed-by: Rob Herring Signed-off-by: Tony Lindgren --- Documentation/devicetree/bindings/bus/ti-sysc.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/bus/ti-sysc.txt b/Documentation/devicetree/bindings/bus/ti-sysc.txt index 48bbb0c96835..2957a9ae291f 100644 --- a/Documentation/devicetree/bindings/bus/ti-sysc.txt +++ b/Documentation/devicetree/bindings/bus/ti-sysc.txt @@ -19,6 +19,7 @@ Required standard properties: - compatible shall be one of the following generic types: + "ti,sysc" "ti,sysc-omap2" "ti,sysc-omap4" "ti,sysc-omap4-simple" -- cgit From b3ed23213eab1e08be594ad44b4237588c58af09 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 20 Dec 2017 08:17:15 +1100 Subject: doc: convert printk-formats.txt to rst Documentation/printk-formats.txt is a candidate for conversion to ReStructuredText format. Some effort has already been made to do this conversion even thought the suffix is currently .txt Changes required to complete conversion - Move printk-formats.txt to core-api/printk-formats.rst - Add entry to Documentation/core-api/index.rst - Remove entry from Documentation/00-INDEX - Fix minor grammatical errors. - Order heading adornments as suggested by rst docs. - Use 'Passed by reference' uniformly. - Update pointer documentation around %px specifier. - Fix erroneous double backticks (to commas). - Remove extraneous double backticks (suggested by Jonathan Corbet). - Simplify documentation for kobject. Signed-off-by: Tobin C. Harding [jc: downcased "kernel"] Signed-off-by: Jonathan Corbet --- Documentation/00-INDEX | 2 - Documentation/core-api/index.rst | 1 + Documentation/core-api/printk-formats.rst | 492 ++++++++++++++++++++++++++++++ Documentation/printk-formats.txt | 483 ----------------------------- 4 files changed, 493 insertions(+), 485 deletions(-) create mode 100644 Documentation/core-api/printk-formats.rst delete mode 100644 Documentation/printk-formats.txt (limited to 'Documentation') diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 3bec49c33bbb..7023bfaec21c 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -346,8 +346,6 @@ prctl/ - directory with info on the priveledge control subsystem preempt-locking.txt - info on locking under a preemptive kernel. -printk-formats.txt - - how to get printk format specifiers right process/ - how to work with the mainline kernel development process. pps/ diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d4d54b05d6c5..d55ee6b006ed 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -22,6 +22,7 @@ Core utilities flexible-arrays librs genalloc + printk-formats Interfaces for kernel debugging =============================== diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst new file mode 100644 index 000000000000..258b46435320 --- /dev/null +++ b/Documentation/core-api/printk-formats.rst @@ -0,0 +1,492 @@ +========================================= +How to get printk format specifiers right +========================================= + +:Author: Randy Dunlap +:Author: Andrew Murray + + +Integer types +============= + +:: + + If variable is of Type, use printk format specifier: + ------------------------------------------------------------ + int %d or %x + unsigned int %u or %x + long %ld or %lx + unsigned long %lu or %lx + long long %lld or %llx + unsigned long long %llu or %llx + size_t %zu or %zx + ssize_t %zd or %zx + s32 %d or %x + u32 %u or %x + s64 %lld or %llx + u64 %llu or %llx + + +If is dependent on a config option for its size (e.g., sector_t, +blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a +format specifier of its largest possible type and explicitly cast to it. + +Example:: + + printk("test: sector number/total blocks: %llu/%llu\n", + (unsigned long long)sector, (unsigned long long)blockcount); + +Reminder: sizeof() returns type size_t. + +The kernel's printf does not support %n. Floating point formats (%e, %f, +%g, %a) are also not recognized, for obvious reasons. Use of any +unsupported specifier or length qualifier results in a WARN and early +return from vsnprintf(). + +Pointer types +============= + +A raw pointer value may be printed with %p which will hash the address +before printing. The kernel also supports extended specifiers for printing +pointers of different types. + +Plain Pointers +-------------- + +:: + + %p abcdef12 or 00000000abcdef12 + +Pointers printed without a specifier extension (i.e unadorned %p) are +hashed to prevent leaking information about the kernel memory layout. This +has the added benefit of providing a unique identifier. On 64-bit machines +the first 32 bits are zeroed. If you *really* want the address see %px +below. + +Symbols/Function Pointers +------------------------- + +:: + + %pF versatile_init+0x0/0x110 + %pf versatile_init + %pS versatile_init+0x0/0x110 + %pSR versatile_init+0x9/0x110 + (with __builtin_extract_return_addr() translation) + %ps versatile_init + %pB prev_fn_of_versatile_init+0x88/0x88 + + +The ``F`` and ``f`` specifiers are for printing function pointers, +for example, f->func, &gettimeofday. They have the same result as +``S`` and ``s`` specifiers. But they do an extra conversion on +ia64, ppc64 and parisc64 architectures where the function pointers +are actually function descriptors. + +The ``S`` and ``s`` specifiers can be used for printing symbols +from direct addresses, for example, __builtin_return_address(0), +(void *)regs->ip. They result in the symbol name with (S) or +without (s) offsets. If KALLSYMS are disabled then the symbol +address is printed instead. + +The ``B`` specifier results in the symbol name with offsets and should be +used when printing stack backtraces. The specifier takes into +consideration the effect of compiler optimisations which may occur +when tail-calls are used and marked with the noreturn GCC attribute. + +Examples:: + + printk("Going to call: %pF\n", gettimeofday); + printk("Going to call: %pF\n", p->func); + printk("%s: called from %pS\n", __func__, (void *)_RET_IP_); + printk("%s: called from %pS\n", __func__, + (void *)__builtin_return_address(0)); + printk("Faulted at %pS\n", (void *)regs->ip); + printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack); + +Kernel Pointers +--------------- + +:: + + %pK 01234567 or 0123456789abcdef + +For printing kernel pointers which should be hidden from unprivileged +users. The behaviour of %pK depends on the kptr_restrict sysctl - see +Documentation/sysctl/kernel.txt for more details. + +Unmodified Addresses +-------------------- + +:: + + %px 01234567 or 0123456789abcdef + +For printing pointers when you *really* want to print the address. Please +consider whether or not you are leaking sensitive information about the +kernel memory layout before printing pointers with %px. %px is functionally +equivalent to %lx (or %lu). %px is preferred because it is more uniquely +grep'able. If in the future we need to modify the way the kernel handles +printing pointers we will be better equipped to find the call sites. + +Struct Resources +---------------- + +:: + + %pr [mem 0x60000000-0x6fffffff flags 0x2200] or + [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] + %pR [mem 0x60000000-0x6fffffff pref] or + [mem 0x0000000060000000-0x000000006fffffff pref] + +For printing struct resources. The ``R`` and ``r`` specifiers result in a +printed resource with (R) or without (r) a decoded flags member. + +Passed by reference. + +Physical address types phys_addr_t +---------------------------------- + +:: + + %pa[p] 0x01234567 or 0x0123456789abcdef + +For printing a phys_addr_t type (and its derivatives, such as +resource_size_t) which can vary based on build options, regardless of the +width of the CPU data path. + +Passed by reference. + +DMA address types dma_addr_t +---------------------------- + +:: + + %pad 0x01234567 or 0x0123456789abcdef + +For printing a dma_addr_t type which can vary based on build options, +regardless of the width of the CPU data path. + +Passed by reference. + +Raw buffer as an escaped string +------------------------------- + +:: + + %*pE[achnops] + +For printing raw buffer as an escaped string. For the following buffer:: + + 1b 62 20 5c 43 07 22 90 0d 5d + +A few examples show how the conversion would be done (excluding surrounding +quotes):: + + %*pE "\eb \C\a"\220\r]" + %*pEhp "\x1bb \C\x07"\x90\x0d]" + %*pEa "\e\142\040\\\103\a\042\220\r\135" + +The conversion rules are applied according to an optional combination +of flags (see :c:func:`string_escape_mem` kernel documentation for the +details): + + - a - ESCAPE_ANY + - c - ESCAPE_SPECIAL + - h - ESCAPE_HEX + - n - ESCAPE_NULL + - o - ESCAPE_OCTAL + - p - ESCAPE_NP + - s - ESCAPE_SPACE + +By default ESCAPE_ANY_NP is used. + +ESCAPE_ANY_NP is the sane choice for many cases, in particularly for +printing SSIDs. + +If field width is omitted then 1 byte only will be escaped. + +Raw buffer as a hex string +-------------------------- + +:: + + %*ph 00 01 02 ... 3f + %*phC 00:01:02: ... :3f + %*phD 00-01-02- ... -3f + %*phN 000102 ... 3f + +For printing small buffers (up to 64 bytes long) as a hex string with a +certain separator. For larger buffers consider using +:c:func:`print_hex_dump`. + +MAC/FDDI addresses +------------------ + +:: + + %pM 00:01:02:03:04:05 + %pMR 05:04:03:02:01:00 + %pMF 00-01-02-03-04-05 + %pm 000102030405 + %pmR 050403020100 + +For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` +specifiers result in a printed address with (M) or without (m) byte +separators. The default byte separator is the colon (:). + +Where FDDI addresses are concerned the ``F`` specifier can be used after +the ``M`` specifier to use dash (-) separators instead of the default +separator. + +For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` +specifier to use reversed byte order suitable for visual interpretation +of Bluetooth addresses which are in the little endian order. + +Passed by reference. + +IPv4 addresses +-------------- + +:: + + %pI4 1.2.3.4 + %pi4 001.002.003.004 + %p[Ii]4[hnbl] + +For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` +specifiers result in a printed address with (i4) or without (I4) leading +zeros. + +The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify +host, network, big or little endian order addresses respectively. Where +no specifier is provided the default network/big endian order is used. + +Passed by reference. + +IPv6 addresses +-------------- + +:: + + %pI6 0001:0002:0003:0004:0005:0006:0007:0008 + %pi6 00010002000300040005000600070008 + %pI6c 1:2:3:4:5:6:7:8 + +For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` +specifiers result in a printed address with (I6) or without (i6) +colon-separators. Leading zeros are always used. + +The additional ``c`` specifier can be used with the ``I`` specifier to +print a compressed IPv6 address as described by +http://tools.ietf.org/html/rfc5952 + +Passed by reference. + +IPv4/IPv6 addresses (generic, with port, flowinfo, scope) +--------------------------------------------------------- + +:: + + %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 + %piS 001.002.003.004 or 00010002000300040005000600070008 + %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 + %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 + %p[Ii]S[pfschnbl] + +For printing an IP address without the need to distinguish whether it's of +type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, +specified through ``IS`` or ``iS``, can be passed to this format specifier. + +The additional ``p``, ``f``, and ``s`` specifiers are used to specify port +(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, +flowinfo a ``/`` and scope a ``%``, each followed by the actual value. + +In case of an IPv6 address the compressed IPv6 address as described by +http://tools.ietf.org/html/rfc5952 is being used if the additional +specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in +case of additional specifiers ``p``, ``f`` or ``s`` as suggested by +https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 + +In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` +specifiers can be used as well and are ignored in case of an IPv6 +address. + +Passed by reference. + +Further examples:: + + %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 + %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 + %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 + +UUID/GUID addresses +------------------- + +:: + + %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f + %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F + %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f + %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F + +For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, +``b`` and ``B`` specifiers are used to specify a little endian order in +lower (l) or upper case (L) hex notation - and big endian order in lower (b) +or upper case (B) hex notation. + +Where no additional specifiers are used the default big endian +order with lower case hex notation will be printed. + +Passed by reference. + +dentry names +------------ + +:: + + %pd{,2,3,4} + %pD{,2,3,4} + +For printing dentry name; if we race with :c:func:`d_move`, the name might +be a mix of old and new ones, but it won't oops. %pd dentry is a safer +equivalent of %s dentry->d_name.name we used to use, %pd prints ``n`` +last components. %pD does the same thing for struct file. + +Passed by reference. + +block_device names +------------------ + +:: + + %pg sda, sda1 or loop0p1 + +For printing name of block_device pointers. + +struct va_format +---------------- + +:: + + %pV + +For printing struct va_format structures. These contain a format string +and va_list as follows:: + + struct va_format { + const char *fmt; + va_list *va; + }; + +Implements a "recursive vsnprintf". + +Do not use this feature without some mechanism to verify the +correctness of the format string and va_list arguments. + +Passed by reference. + +kobjects +-------- + +:: + + %pOF[fnpPcCF] + + +For printing kobject based structs (device nodes). Default behaviour is +equivalent to %pOFf. + + - f - device node full_name + - n - device node name + - p - device node phandle + - P - device node path spec (name + @unit) + - F - device node flags + - c - major compatible string + - C - full compatible string + +The separator when using multiple arguments is ':' + +Examples:: + + %pOF /foo/bar@0 - Node full name + %pOFf /foo/bar@0 - Same as above + %pOFfp /foo/bar@0:10 - Node full name + phandle + %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + + major compatible string + + node flags + D - dynamic + d - detached + P - Populated + B - Populated bus + +Passed by reference. + +struct clk +---------- + +:: + + %pC pll1 + %pCn pll1 + %pCr 1560000000 + +For printing struct clk structures. %pC and %pCn print the name +(Common Clock Framework) or address (legacy clock framework) of the +structure; %pCr prints the current clock rate. + +Passed by reference. + +bitmap and its derivatives such as cpumask and nodemask +------------------------------------------------------- + +:: + + %*pb 0779 + %*pbl 0,3-6,8-10 + +For printing bitmap and its derivatives such as cpumask and nodemask, +%*pb outputs the bitmap with field width as the number of bits and %*pbl +output the bitmap as range list with field width as the number of bits. + +Passed by reference. + +Flags bitfields such as page flags, gfp_flags +--------------------------------------------- + +:: + + %pGp referenced|uptodate|lru|active|private + %pGg GFP_USER|GFP_DMA32|GFP_NOWARN + %pGv read|exec|mayread|maywrite|mayexec|denywrite + +For printing flags bitfields as a collection of symbolic constants that +would construct the value. The type of flags is given by the third +character. Currently supported are [p]age flags, [v]ma_flags (both +expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag +names and print order depends on the particular type. + +Note that this format should not be used directly in the +:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() +functions from . + +Passed by reference. + +Network device features +----------------------- + +:: + + %pNF 0x000000000000c000 + +For printing netdev_features_t. + +Passed by reference. + +Thanks +====== + +If you add other %p extensions, please extend with +one or more test cases, if at all feasible. + +Thank you for your cooperation and attention. diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt deleted file mode 100644 index aa0a776c817a..000000000000 --- a/Documentation/printk-formats.txt +++ /dev/null @@ -1,483 +0,0 @@ -========================================= -How to get printk format specifiers right -========================================= - -:Author: Randy Dunlap -:Author: Andrew Murray - -Integer types -============= - -:: - - If variable is of Type, use printk format specifier: - ------------------------------------------------------------ - int %d or %x - unsigned int %u or %x - long %ld or %lx - unsigned long %lu or %lx - long long %lld or %llx - unsigned long long %llu or %llx - size_t %zu or %zx - ssize_t %zd or %zx - s32 %d or %x - u32 %u or %x - s64 %lld or %llx - u64 %llu or %llx - -If is dependent on a config option for its size (e.g., ``sector_t``, -``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``), -use a format specifier of its largest possible type and explicitly cast to it. - -Example:: - - printk("test: sector number/total blocks: %llu/%llu\n", - (unsigned long long)sector, (unsigned long long)blockcount); - -Reminder: ``sizeof()`` result is of type ``size_t``. - -The kernel's printf does not support ``%n``. For obvious reasons, floating -point formats (``%e, %f, %g, %a``) are also not recognized. Use of any -unsupported specifier or length qualifier results in a WARN and early -return from vsnprintf. - -Raw pointer value SHOULD be printed with %p. The kernel supports -the following extended format specifiers for pointer types: - -Pointer Types -============= - -Pointers printed without a specifier extension (i.e unadorned %p) are -hashed to give a unique identifier without leaking kernel addresses to user -space. On 64 bit machines the first 32 bits are zeroed. If you _really_ -want the address see %px below. - -:: - - %p abcdef12 or 00000000abcdef12 - -Symbols/Function Pointers -========================= - -:: - - %pF versatile_init+0x0/0x110 - %pf versatile_init - %pS versatile_init+0x0/0x110 - %pSR versatile_init+0x9/0x110 - (with __builtin_extract_return_addr() translation) - %ps versatile_init - %pB prev_fn_of_versatile_init+0x88/0x88 - -The ``F`` and ``f`` specifiers are for printing function pointers, -for example, f->func, &gettimeofday. They have the same result as -``S`` and ``s`` specifiers. But they do an extra conversion on -ia64, ppc64 and parisc64 architectures where the function pointers -are actually function descriptors. - -The ``S`` and ``s`` specifiers can be used for printing symbols -from direct addresses, for example, __builtin_return_address(0), -(void *)regs->ip. They result in the symbol name with (``S``) or -without (``s``) offsets. If KALLSYMS are disabled then the symbol -address is printed instead. - -The ``B`` specifier results in the symbol name with offsets and should be -used when printing stack backtraces. The specifier takes into -consideration the effect of compiler optimisations which may occur -when tail-call``s are used and marked with the noreturn GCC attribute. - -Examples:: - - printk("Going to call: %pF\n", gettimeofday); - printk("Going to call: %pF\n", p->func); - printk("%s: called from %pS\n", __func__, (void *)_RET_IP_); - printk("%s: called from %pS\n", __func__, - (void *)__builtin_return_address(0)); - printk("Faulted at %pS\n", (void *)regs->ip); - printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack); - -Kernel Pointers -=============== - -:: - - %pK 01234567 or 0123456789abcdef - -For printing kernel pointers which should be hidden from unprivileged -users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see -Documentation/sysctl/kernel.txt for more details. - -Unmodified Addresses -==================== - -:: - - %px 01234567 or 0123456789abcdef - -For printing pointers when you _really_ want to print the address. Please -consider whether or not you are leaking sensitive information about the -Kernel layout in memory before printing pointers with %px. %px is -functionally equivalent to %lx. %px is preferred to %lx because it is more -uniquely grep'able. If, in the future, we need to modify the way the Kernel -handles printing pointers it will be nice to be able to find the call -sites. - -Struct Resources -================ - -:: - - %pr [mem 0x60000000-0x6fffffff flags 0x2200] or - [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] - %pR [mem 0x60000000-0x6fffffff pref] or - [mem 0x0000000060000000-0x000000006fffffff pref] - -For printing struct resources. The ``R`` and ``r`` specifiers result in a -printed resource with (``R``) or without (``r``) a decoded flags member. -Passed by reference. - -Physical addresses types ``phys_addr_t`` -======================================== - -:: - - %pa[p] 0x01234567 or 0x0123456789abcdef - -For printing a ``phys_addr_t`` type (and its derivatives, such as -``resource_size_t``) which can vary based on build options, regardless of -the width of the CPU data path. Passed by reference. - -DMA addresses types ``dma_addr_t`` -================================== - -:: - - %pad 0x01234567 or 0x0123456789abcdef - -For printing a ``dma_addr_t`` type which can vary based on build options, -regardless of the width of the CPU data path. Passed by reference. - -Raw buffer as an escaped string -=============================== - -:: - - %*pE[achnops] - -For printing raw buffer as an escaped string. For the following buffer:: - - 1b 62 20 5c 43 07 22 90 0d 5d - -few examples show how the conversion would be done (the result string -without surrounding quotes):: - - %*pE "\eb \C\a"\220\r]" - %*pEhp "\x1bb \C\x07"\x90\x0d]" - %*pEa "\e\142\040\\\103\a\042\220\r\135" - -The conversion rules are applied according to an optional combination -of flags (see :c:func:`string_escape_mem` kernel documentation for the -details): - - - ``a`` - ESCAPE_ANY - - ``c`` - ESCAPE_SPECIAL - - ``h`` - ESCAPE_HEX - - ``n`` - ESCAPE_NULL - - ``o`` - ESCAPE_OCTAL - - ``p`` - ESCAPE_NP - - ``s`` - ESCAPE_SPACE - -By default ESCAPE_ANY_NP is used. - -ESCAPE_ANY_NP is the sane choice for many cases, in particularly for -printing SSIDs. - -If field width is omitted the 1 byte only will be escaped. - -Raw buffer as a hex string -========================== - -:: - - %*ph 00 01 02 ... 3f - %*phC 00:01:02: ... :3f - %*phD 00-01-02- ... -3f - %*phN 000102 ... 3f - -For printing a small buffers (up to 64 bytes long) as a hex string with -certain separator. For the larger buffers consider to use -:c:func:`print_hex_dump`. - -MAC/FDDI addresses -================== - -:: - - %pM 00:01:02:03:04:05 - %pMR 05:04:03:02:01:00 - %pMF 00-01-02-03-04-05 - %pm 000102030405 - %pmR 050403020100 - -For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` -specifiers result in a printed address with (``M``) or without (``m``) byte -separators. The default byte separator is the colon (``:``). - -Where FDDI addresses are concerned the ``F`` specifier can be used after -the ``M`` specifier to use dash (``-``) separators instead of the default -separator. - -For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` -specifier to use reversed byte order suitable for visual interpretation -of Bluetooth addresses which are in the little endian order. - -Passed by reference. - -IPv4 addresses -============== - -:: - - %pI4 1.2.3.4 - %pi4 001.002.003.004 - %p[Ii]4[hnbl] - -For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` -specifiers result in a printed address with (``i4``) or without (``I4``) -leading zeros. - -The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify -host, network, big or little endian order addresses respectively. Where -no specifier is provided the default network/big endian order is used. - -Passed by reference. - -IPv6 addresses -============== - -:: - - %pI6 0001:0002:0003:0004:0005:0006:0007:0008 - %pi6 00010002000300040005000600070008 - %pI6c 1:2:3:4:5:6:7:8 - -For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` -specifiers result in a printed address with (``I6``) or without (``i6``) -colon-separators. Leading zeros are always used. - -The additional ``c`` specifier can be used with the ``I`` specifier to -print a compressed IPv6 address as described by -http://tools.ietf.org/html/rfc5952 - -Passed by reference. - -IPv4/IPv6 addresses (generic, with port, flowinfo, scope) -========================================================= - -:: - - %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 - %piS 001.002.003.004 or 00010002000300040005000600070008 - %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 - %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 - %p[Ii]S[pfschnbl] - -For printing an IP address without the need to distinguish whether it``s -of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``, -specified through ``IS`` or ``iS``, can be passed to this format specifier. - -The additional ``p``, ``f``, and ``s`` specifiers are used to specify port -(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, -flowinfo a ``/`` and scope a ``%``, each followed by the actual value. - -In case of an IPv6 address the compressed IPv6 address as described by -http://tools.ietf.org/html/rfc5952 is being used if the additional -specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in -case of additional specifiers ``p``, ``f`` or ``s`` as suggested by -https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 - -In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` -specifiers can be used as well and are ignored in case of an IPv6 -address. - -Passed by reference. - -Further examples:: - - %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 - %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 - %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 - -UUID/GUID addresses -=================== - -:: - - %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f - %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F - %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f - %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F - -For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L', -'b' and 'B' specifiers are used to specify a little endian order in -lower ('l') or upper case ('L') hex characters - and big endian order -in lower ('b') or upper case ('B') hex characters. - -Where no additional specifiers are used the default big endian -order with lower case hex characters will be printed. - -Passed by reference. - -dentry names -============ - -:: - - %pd{,2,3,4} - %pD{,2,3,4} - -For printing dentry name; if we race with :c:func:`d_move`, the name might be -a mix of old and new ones, but it won't oops. ``%pd`` dentry is a safer -equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd`` prints -``n`` last components. ``%pD`` does the same thing for struct file. - -Passed by reference. - -block_device names -================== - -:: - - %pg sda, sda1 or loop0p1 - -For printing name of block_device pointers. - -struct va_format -================ - -:: - - %pV - -For printing struct va_format structures. These contain a format string -and va_list as follows:: - - struct va_format { - const char *fmt; - va_list *va; - }; - -Implements a "recursive vsnprintf". - -Do not use this feature without some mechanism to verify the -correctness of the format string and va_list arguments. - -Passed by reference. - -kobjects -======== - -:: - - %pO - - Base specifier for kobject based structs. Must be followed with - character for specific type of kobject as listed below: - - Device tree nodes: - - %pOF[fnpPcCF] - - For printing device tree nodes. The optional arguments are: - f device node full_name - n device node name - p device node phandle - P device node path spec (name + @unit) - F device node flags - c major compatible string - C full compatible string - Without any arguments prints full_name (same as %pOFf) - The separator when using multiple arguments is ':' - - Examples: - - %pOF /foo/bar@0 - Node full name - %pOFf /foo/bar@0 - Same as above - %pOFfp /foo/bar@0:10 - Node full name + phandle - %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + - major compatible string + - node flags - D - dynamic - d - detached - P - Populated - B - Populated bus - - Passed by reference. - - -struct clk -========== - -:: - - %pC pll1 - %pCn pll1 - %pCr 1560000000 - -For printing struct clk structures. ``%pC`` and ``%pCn`` print the name -(Common Clock Framework) or address (legacy clock framework) of the -structure; ``%pCr`` prints the current clock rate. - -Passed by reference. - -bitmap and its derivatives such as cpumask and nodemask -======================================================= - -:: - - %*pb 0779 - %*pbl 0,3-6,8-10 - -For printing bitmap and its derivatives such as cpumask and nodemask, -``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl`` -output the bitmap as range list with field width as the number of bits. - -Passed by reference. - -Flags bitfields such as page flags, gfp_flags -============================================= - -:: - - %pGp referenced|uptodate|lru|active|private - %pGg GFP_USER|GFP_DMA32|GFP_NOWARN - %pGv read|exec|mayread|maywrite|mayexec|denywrite - -For printing flags bitfields as a collection of symbolic constants that -would construct the value. The type of flags is given by the third -character. Currently supported are [p]age flags, [v]ma_flags (both -expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag -names and print order depends on the particular type. - -Note that this format should not be used directly in :c:func:`TP_printk()` part -of a tracepoint. Instead, use the ``show_*_flags()`` functions from -. - -Passed by reference. - -Network device features -======================= - -:: - - %pNF 0x000000000000c000 - -For printing netdev_features_t. - -Passed by reference. - -If you add other ``%p`` extensions, please extend lib/test_printf.c with -one or more test cases, if at all feasible. - - -Thank you for your cooperation and attention. -- cgit From da271403a894f1139b3a49fca8fa19585902890e Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 20 Dec 2017 08:17:16 +1100 Subject: doc: update kptr_restrict documentation Recently the behaviour of printk specifier %pK was changed. The documentation does not currently mirror this. Update documentation for sysctl kptr_restrict. Signed-off-by: Tobin C. Harding Signed-off-by: Jonathan Corbet --- Documentation/sysctl/kernel.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 63663039acb7..412314eebda6 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -391,7 +391,8 @@ kptr_restrict: This toggle indicates whether restrictions are placed on exposing kernel addresses via /proc and other interfaces. -When kptr_restrict is set to (0), the default, there are no restrictions. +When kptr_restrict is set to 0 (the default) the address is hashed before +printing. (This is the equivalent to %p.) When kptr_restrict is set to (1), kernel pointers printed using the %pK format specifier will be replaced with 0's unless the user has CAP_SYSLOG -- cgit From 227d1a61ed87033285d187214f305c27895176f9 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Wed, 20 Dec 2017 08:17:17 +1100 Subject: doc: add documentation on printing kernel addresses Hashing addresses printed with printk specifier %p was implemented recently. During development a number of issues were raised regarding leaking kernel addresses to userspace. Other documentation was updated but security/self-protection missed out. Add self-protection documentation regarding printing kernel addresses. Signed-off-by: Tobin C. Harding Signed-off-by: Jonathan Corbet --- Documentation/security/self-protection.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'Documentation') diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index 60c8bd8b77bf..0f53826c78b9 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -270,6 +270,21 @@ attacks, it is important to defend against exposure of both kernel memory addresses and kernel memory contents (since they may contain kernel addresses or other sensitive things like canary values). +Kernel addresses +---------------- + +Printing kernel addresses to userspace leaks sensitive information about +the kernel memory layout. Care should be exercised when using any printk +specifier that prints the raw address, currently %px, %p[ad], (and %p[sSb] +in certain circumstances [*]). Any file written to using one of these +specifiers should be readable only by privileged processes. + +Kernels 4.14 and older printed the raw address using %p. As of 4.15-rc1 +addresses printed with the specifier %p are hashed before printing. + +[*] If KALLSYMS is enabled and symbol lookup fails, the raw address is +printed. If KALLSYMS is not enabled the raw address is printed. + Unique identifiers ------------------ -- cgit From 651a9ee42a76e4277129af614fbabf0797657f6e Mon Sep 17 00:00:00 2001 From: Adam Borowski Date: Mon, 18 Dec 2017 20:47:27 +0100 Subject: Documentation/filesystems/vfat.txt: fix a remark that implies UCS2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All non-historic operating systems support the full range of Unicode here, thus you can make filenames for example in Gothic (𐌼𐌴𐍉𐍅), the other Gothic (𝓂ℯℴ𝓌) or the third Gothic (𝗆𝖾𝗈𝗐), or declare something as 💩. Characters above U+FFFF are encoded on four bytes. Signed-off-by: Adam Borowski Acked-by: OGAWA Hirofumi Signed-off-by: Jonathan Corbet --- Documentation/filesystems/vfat.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index cf51360e3a9f..91031298beb1 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -344,4 +344,4 @@ the following: characters in the final slot are set to Unicode 0xFFFF. Finally, note that the extended name is stored in Unicode. Each Unicode -character takes two bytes. +character takes either two or four bytes, UTF-16LE encoded. -- cgit From d6f44b3bd870ff5946fcd4293b4c07029d8d93c9 Mon Sep 17 00:00:00 2001 From: Gergo Huszty Date: Wed, 20 Dec 2017 20:07:08 +0100 Subject: Fixed typo in onewire generic doc Onewire devices has 6 byte long unique serial numbers, 1 byte family code and 1 byte CRC. Linux sysfs presents the device folder in the form of familyID-deviceID, so CRC is not shown. The consequence is that the device serial number is always a 12 long hex-string, but doc says 13 in one place. This is corrected by this change. Reference: https://en.wikipedia.org/wiki/1-Wire Signed-off-by: Gergo Huszty Signed-off-by: Jonathan Corbet --- Documentation/w1/w1.generic | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic index b3ffaf8cfab2..c51b1ab012d0 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1.generic @@ -76,7 +76,7 @@ See struct w1_bus_master definition in w1.h for details. w1 master sysfs interface ------------------------------------------------------------------ - - A directory for a found device. The format is family-serial + - A directory for a found device. The format is family-serial bus - (standard) symlink to the w1 bus driver - (standard) symlink to the w1 driver w1_master_add - (rw) manually register a slave device -- cgit From c5531f2af6f2e0dba36db4251b09cd4da9195d9b Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Wed, 13 Dec 2017 13:52:53 +0100 Subject: Documentation: Add Kees Cook to list of enforcement statement endorsers Add my name to the list. Signed-off-by: Kees Cook Signed-off-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/process/kernel-enforcement-statement.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index b3170671a1df..fb5f5a7a5344 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -68,6 +68,7 @@ we might work for today, have in the past, or will in the future. - Paul Burton - Javier Martinez Canillas - Rob Clark + - Kees Cook (Google) - Jonathan Corbet - Dennis Dalessandro - Vivien Didelot (Savoir-faire Linux) -- cgit From 24c6a745533c8f718f9eb29faee83ea1b0438dff Mon Sep 17 00:00:00 2001 From: "Luis R. Rodriguez" Date: Wed, 13 Dec 2017 13:52:54 +0100 Subject: Documentation: Add Luis R. Rodriguez to list of enforcement statement endorsers Add my name to the list. Signed-off-by: Luis R. Rodriguez Signed-off-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/process/kernel-enforcement-statement.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index fb5f5a7a5344..565717e4d3bc 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -144,6 +144,7 @@ we might work for today, have in the past, or will in the future. - Linus Torvalds - Thierry Reding - Rik van Riel + - Luis R. Rodriguez - Geert Uytterhoeven (Glider bvba) - Eduardo Valentin (Amazon.com) - Daniel Vetter -- cgit From 481f2720042685b855be183758d51a8d0e9d009c Mon Sep 17 00:00:00 2001 From: David Sterba Date: Wed, 13 Dec 2017 13:52:55 +0100 Subject: Documentation: Add myself to the enforcement statement list Signed-off-by: David Sterba Signed-off-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/process/kernel-enforcement-statement.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index 565717e4d3bc..a0db6e40fb80 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -137,6 +137,7 @@ we might work for today, have in the past, or will in the future. - Anna Schumaker - Jes Sorensen - K.Y. Srinivasan + - David Sterba (SUSE) - Heiko Stuebner - Jiri Kosina (SUSE) - Willy Tarreau -- cgit From 90b2a01e68167665a3f86c477414e795cd4a0139 Mon Sep 17 00:00:00 2001 From: Lu Baolu Date: Wed, 13 Dec 2017 13:07:44 +0800 Subject: usb: doc: Update document for USB3 debug port usage Update Documentation/driver-api/usb/usb3-debug-port.rst. This update includes the guide for using xHCI debug capability based TTY serial link. Cc: Mathias Nyman Cc: Greg Kroah-Hartman Signed-off-by: Lu Baolu Signed-off-by: Jonathan Corbet --- Documentation/driver-api/usb/usb3-debug-port.rst | 52 ++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index feb1a36a65b7..b9fd131f4723 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -98,3 +98,55 @@ you to check the sanity of the setup. cat /dev/ttyUSB0 done ===== end of bash scripts =============== + +Serial TTY +========== + +The DbC support has been added to the xHCI driver. You can get a +debug device provided by the DbC at runtime. + +In order to use this, you need to make sure your kernel has been +configured to support USB_XHCI_DBGCAP. A sysfs attribute under +the xHCI device node is used to enable or disable DbC. By default, +DbC is disabled:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + disabled + +Enable DbC with the following command:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# echo enable > dbc + +You can check the DbC state at anytime:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + enabled + +Connect the debug target to the debug host with a USB 3.0 super- +speed A-to-A debugging cable. You can see /dev/ttyDBC0 created +on the debug target. You will see below kernel message lines:: + + root@target: tail -f /var/log/kern.log + [ 182.730103] xhci_hcd 0000:00:14.0: DbC connected + [ 191.169420] xhci_hcd 0000:00:14.0: DbC configured + [ 191.169597] xhci_hcd 0000:00:14.0: DbC now attached to /dev/ttyDBC0 + +Accordingly, the DbC state has been brought up to:: + + root@target:/sys/bus/pci/devices/0000:00:14.0# cat dbc + configured + +On the debug host, you will see the debug device has been enumerated. +You will see below kernel message lines:: + + root@host: tail -f /var/log/kern.log + [ 79.454780] usb 2-2.1: new SuperSpeed USB device number 3 using xhci_hcd + [ 79.475003] usb 2-2.1: LPM exit latency is zeroed, disabling LPM. + [ 79.475389] usb 2-2.1: New USB device found, idVendor=1d6b, idProduct=0010 + [ 79.475390] usb 2-2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [ 79.475391] usb 2-2.1: Product: Linux USB Debug Target + [ 79.475392] usb 2-2.1: Manufacturer: Linux Foundation + [ 79.475393] usb 2-2.1: SerialNumber: 0001 + +The debug device works now. You can use any communication or debugging +program to talk between the host and the target. -- cgit From 91b28aeb17ce13065d745a1f92c95011c10ba75a Mon Sep 17 00:00:00 2001 From: Cengiz C Date: Tue, 12 Dec 2017 19:43:09 +0300 Subject: i2c: update i2c-dev.h warning in documentation `Documentation/i2c/dev-interface` gives examples for accessing i2c from userspace. There's a note that warns developers about the two `i2c-dev.h` header files which were shipped with the kernel and i2c-tools separately. However, following i2c-tools commits suggest that the header files are now identical (in functionality) and `i2c_*` helper functions are now defined in a separate header called `i2c/smbus.h`, which is distributed with i2c-tools: commit 652619121974 ("Minimize differences with kernel flavor") commit 93caf007f4cb ("Move SMBus helper functions to include/i2c/smbus.h") Thus, I've converted the warning paragraph into a historical note and updated the suggested header files. Signed-off-by: Cengiz Can Cc: Wolfram Sang Signed-off-by: Jonathan Corbet --- Documentation/i2c/dev-interface | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 5ff19447ac44..d04e6e4964ee 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -17,13 +17,16 @@ i2c-10, ...). All 256 minor device numbers are reserved for i2c. C example ========= -So let's say you want to access an i2c adapter from a C program. The -first thing to do is "#include ". Please note that -there are two files named "i2c-dev.h" out there, one is distributed -with the Linux kernel and is meant to be included from kernel -driver code, the other one is distributed with i2c-tools and is -meant to be included from user-space programs. You obviously want -the second one here. +So let's say you want to access an i2c adapter from a C program. +First, you need to include these two headers: + + #include + #include + +(Please note that there are two files named "i2c-dev.h" out there. One is +distributed with the Linux kernel and the other one is included in the +source tree of i2c-tools. They used to be different in content but since 2012 +they're identical. You should use "linux/i2c-dev.h"). Now, you have to decide which adapter you want to access. You should inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. -- cgit From 2cd6ff4ac02eb81c301cbffed40ac93f0f6bd4a7 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 12 Dec 2017 11:22:25 +0100 Subject: docs: ftrace-uses.rst fix varios code-block directives ftrace-uses.rst is not yet included into any toctree, but since it is a .rst file, it is parsed by the Sphinx build. Thats, why we see some WARNINGS: - trace/ftrace-uses.rst:53: WARNING: Definition list ends without a blank line; unexpected unindent. - trace/ftrace-uses.rst:89: WARNING: Inline emphasis start-string without end-string. - trace/ftrace-uses.rst:89: WARNING: Inline emphasis start-string without end-strin Fixing the code-block directives results in a less noisy build, but the 'not included' WARNING will be stay: - trace/ftrace-uses.rst: WARNING: document isn't included in any toctree Signed-off-by: Markus Heiser Acked-by: Steven Rostedt (VMware) Signed-off-by: Jonathan Corbet --- Documentation/trace/ftrace-uses.rst | 60 ++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 30 deletions(-) (limited to 'Documentation') diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index 8494a801d341..3aed560a12ee 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -42,9 +42,9 @@ as well as what protections the callback will perform and not require ftrace to handle. There is only one field that is needed to be set when registering -an ftrace_ops with ftrace:: +an ftrace_ops with ftrace: -.. code-block: c +.. code-block:: c struct ftrace_ops ops = { .func = my_callback_func, @@ -81,12 +81,12 @@ may take some time to finish. The callback function ===================== -The prototype of the callback function is as follows (as of v4.14):: +The prototype of the callback function is as follows (as of v4.14): -.. code-block: c +.. code-block:: c - void callback_func(unsigned long ip, unsigned long parent_ip, - struct ftrace_ops *op, struct pt_regs *regs); + void callback_func(unsigned long ip, unsigned long parent_ip, + struct ftrace_ops *op, struct pt_regs *regs); @ip This is the instruction pointer of the function that is being traced. @@ -176,10 +176,10 @@ Filtering which functions to trace If a callback is only to be called from specific functions, a filter must be set up. The filters are added by name, or ip if it is known. -.. code-block: c +.. code-block:: c - int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, - int len, int reset); + int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, + int len, int reset); @ops The ops to set the filter with @@ -202,9 +202,9 @@ See Filter Commands in :file:`Documentation/trace/ftrace.txt`. To just trace the schedule function:: -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0); + ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0); To add more functions, call the ftrace_set_filter() more than once with the @reset parameter set to zero. To remove the current filter set and replace it @@ -212,17 +212,17 @@ with new functions defined by @buf, have @reset be non-zero. To remove all the filtered functions and trace all functions:: -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter(&ops, NULL, 0, 1); + ret = ftrace_set_filter(&ops, NULL, 0, 1); Sometimes more than one function has the same name. To trace just a specific function in this case, ftrace_set_filter_ip() can be used. -.. code-block: c +.. code-block:: c - ret = ftrace_set_filter_ip(&ops, ip, 0, 0); + ret = ftrace_set_filter_ip(&ops, ip, 0, 0); Although the ip must be the address where the call to fentry or mcount is located in the function. This function is used by perf and kprobes that @@ -237,10 +237,10 @@ be called by any function. An empty "notrace" list means to allow all functions defined by the filter to be traced. -.. code-block: c +.. code-block:: c - int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, - int len, int reset); + int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, + int len, int reset); This takes the same parameters as ftrace_set_filter() but will add the functions it finds to not be traced. This is a separate list from the @@ -251,7 +251,7 @@ that match @buf to it. Clearing the "notrace" list is the same as clearing the filter list -.. code-block: c +.. code-block:: c ret = ftrace_set_notrace(&ops, NULL, 0, 1); @@ -264,29 +264,29 @@ If a filter is in place, and the @reset is non-zero, and @buf contains a matching glob to functions, the switch will happen during the time of the ftrace_set_filter() call. At no time will all functions call the callback. -.. code-block: c +.. code-block:: c - ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); + ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); - register_ftrace_function(&ops); + register_ftrace_function(&ops); - msleep(10); + msleep(10); - ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1); + ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1); is not the same as: -.. code-block: c +.. code-block:: c - ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); + ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); - register_ftrace_function(&ops); + register_ftrace_function(&ops); - msleep(10); + msleep(10); - ftrace_set_filter(&ops, NULL, 0, 1); + ftrace_set_filter(&ops, NULL, 0, 1); - ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0); + ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0); As the latter will have a short time where all functions will call the callback, between the time of the reset, and the time of the -- cgit From 012e93cbdb28329e615b937bb2bb7d61aee5d0d1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 12 Dec 2017 11:46:51 +0100 Subject: docs: fix process/submit-checklist.rst Sphinx warning add missing indent whitespace to list item, fixes the warning: - process/submit-checklist.rst:41: WARNING: Enumerated list ends without a blank line; unexpected unindent. Signed-off-by: Markus Heiser Reviewed-by: Darren Hart (VMware) Signed-off-by: Jonathan Corbet --- Documentation/process/submit-checklist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 7d04ab38007d..367353c54949 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -38,8 +38,8 @@ and elsewhere regarding submitting Linux kernel patches. your patch. 6) Any new or modified ``CONFIG`` options do not muck up the config menu and - default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value. 7) All new ``Kconfig`` options have help text. -- cgit From 63ac85174a5455bf0ed14fa37515015de33d0fe9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:02 -0200 Subject: docs: kernel-doc.rst: better describe kernel-doc arguments Add a new section to describe kernel-doc arguments, adding examples about how identation should happen, as failing to do that causes Sphinx to do the wrong thing. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 44 +++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 0268335414ce..f1c03c16f03b 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -112,16 +112,17 @@ Example kernel-doc function comment:: /** * foobar() - Brief description of foobar. - * @arg: Description of argument of foobar. + * @argument1: Description of parameter argument1 of foobar. + * @argument2: Description of parameter argument2 of foobar. * * Longer description of foobar. * * Return: Description of return value of foobar. */ - int foobar(int arg) + int foobar(int argument1, char *argument2) The format is similar for documentation for structures, enums, paragraphs, -etc. See the sections below for details. +etc. See the sections below for specific details of each type. The kernel-doc structure is extracted from the comments, and proper `Sphinx C Domain`_ function and type descriptions with anchors are generated for them. The @@ -130,6 +131,43 @@ cross-references. See below for details. .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html + +Parameters and member arguments +------------------------------- + +The kernel-doc function comments describe each parameter to the function and +function typedefs or each member of struct/union, in order, with the +``@argument:`` descriptions. For each non-private member argument, one +``@argument`` definition is needed. + +The ``@argument:`` descriptions begin on the very next line following +the opening brief function description line, with no intervening blank +comment lines. + +The ``@argument:`` descriptions may span multiple lines. + +.. note:: + + If the ``@argument`` description has multiple lines, the continuation + of the description should be starting exactly at the same column as + the previous line, e. g.:: + + * @argument: some long description + * that continues on next lines + + or:: + + * @argument: + * some long description + * that continues on next lines + +If a function or typedef parameter argument is ``...`` (e. g. a variable +number of arguments), its description should be listed in kernel-doc +notation as:: + + * @...: description + + Highlights and cross-references ------------------------------- -- cgit From 01f2c18073e284397f45c94b26e65fd1b66776e4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:03 -0200 Subject: docs: kernel-doc.rst: improve private members description The private members section can now be moved to be together with the arguments section. Move it there and add an example about the usage of public: Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 56 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 26 deletions(-) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index f1c03c16f03b..7cf58c3489de 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -167,6 +167,36 @@ notation as:: * @...: description +Private members +~~~~~~~~~~~~~~~ + +Inside a struct or union description, you can use the ``private:`` and +``public:`` comment tags. Structure fields that are inside a ``private:`` +area are not listed in the generated output documentation. + +The ``private:`` and ``public:`` tags must begin immediately following a +``/*`` comment marker. They may optionally include comments between the +``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; + Highlights and cross-references ------------------------------- @@ -332,32 +362,6 @@ on a line of their own, like all other kernel-doc comments:: int foobar; } -Private members -~~~~~~~~~~~~~~~ - -Inside a struct description, you can use the "private:" and "public:" comment -tags. Structure fields that are inside a "private:" area are not listed in the -generated output documentation. The "private:" and "public:" tags must begin -immediately following a ``/*`` comment marker. They may optionally include -comments between the ``:`` and the ending ``*/`` marker. - -Example:: - - /** - * struct my_struct - short description - * @a: first member - * @b: second member - * - * Longer description - */ - struct my_struct { - int a; - int b; - /* private: internal use only */ - int c; - }; - - Typedef documentation --------------------- -- cgit From fc275bf3b99d2c78e1c132d2199be1cb6a701905 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:04 -0200 Subject: docs: kernel-doc.rst: improve function documentation section Move its contents to happen earlier and improve the description of return values, adding a subsection to it. Most of the contents there came from kernel-doc-nano-HOWTO.txt. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 100 ++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 39 deletions(-) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 7cf58c3489de..3aac228fc346 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -197,6 +197,67 @@ Example:: int d; }; +Function documentation +---------------------- + +The general format of a function and function-like macro kernel-doc comment is:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +The brief description following the function name may span multiple lines, and +ends with an argument description, a blank comment line, or the end of the +comment block. + +Return values +~~~~~~~~~~~~~ + +The return value, if any, should be described in a dedicated section +named ``Return``. + +.. note:: + + #) The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + this will all run together and produce:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + So, in order to produce the desired line breaks, you need to use a + ReST list, e. g.:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) If the descriptive text you provide has lines that begin with + some phrase followed by a colon, each of those phrases will be taken + as a new section heading, with probably won't produce the desired + effect. + Highlights and cross-references ------------------------------- @@ -269,45 +330,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Function documentation ----------------------- - -The general format of a function and function-like macro kernel-doc comment is:: - - /** - * function_name() - Brief description of function. - * @arg1: Describe the first argument. - * @arg2: Describe the second argument. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function function_name() - * that might be useful to those using or modifying it. Begins with an - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description may have multiple paragraphs. - * - * Return: Describe the return value of foobar. - * - * The return value description can also have multiple paragraphs, and should - * be placed at the end of the comment block. - */ - -The brief description following the function name may span multiple lines, and -ends with an ``@argument:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc function comments describe each parameter to the function, in -order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions -must begin on the very next line following the opening brief function -description line, with no intervening blank comment lines. The ``@argument:`` -descriptions may span multiple lines. The continuation lines may contain -indentation. If a function parameter is ``...`` (varargs), it should be listed -in kernel-doc notation as: ``@...:``. - -The return value, if any, should be described in a dedicated section at the end -of the comment starting with "Return:". Structure, union, and enumeration documentation ----------------------------------------------- -- cgit From 553aa3c12e818a142e493a3d44a1eb8cadc2959f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:05 -0200 Subject: docs: kernel-doc.rst: improve structs chapter There is a mess on this chapter: it suggests that even enums and unions should be documented with "struct". That's not the way it should be ;-) Fix it and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++++++++----------------- 1 file changed, 24 insertions(+), 24 deletions(-) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 3aac228fc346..e3e82f8f4de5 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -258,6 +258,30 @@ named ``Return``. as a new section heading, with probably won't produce the desired effect. +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: + + /** + * struct struct_name - Brief description. + * @argument: Description of member member_name. + * + * Description of the structure. + */ + +On the above, ``struct`` is used to mean structs. You can also use ``union`` +and ``enum`` to describe unions and enums. ``argument`` is used +to mean struct and union member names as well as enumerations in an enum. + +The brief description following the structure name may span multiple lines, and +ends with a member description, a blank comment line, or the end of the +comment block. + +The kernel-doc data structure comments describe each member of the structure, +in order, with the member descriptions. + + Highlights and cross-references ------------------------------- @@ -331,30 +355,6 @@ cross-references. For further details, please refer to the `Sphinx C Domain`_ documentation. -Structure, union, and enumeration documentation ------------------------------------------------ - -The general format of a struct, union, and enum kernel-doc comment is:: - - /** - * struct struct_name - Brief description. - * @member_name: Description of member member_name. - * - * Description of the structure. - */ - -Below, "struct" is used to mean structs, unions and enums, and "member" is used -to mean struct and union members as well as enumerations in an enum. - -The brief description following the structure name may span multiple lines, and -ends with a ``@member:`` description, a blank comment line, or the end of the -comment block. - -The kernel-doc data structure comments describe each member of the structure, in -order, with the ``@member:`` descriptions. The ``@member:`` descriptions must -begin on the very next line following the opening brief function description -line, with no intervening blank comment lines. The ``@member:`` descriptions may -span multiple lines. The continuation lines may contain indentation. In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit From bdb76f9e305a45a7a1f0073a4b3a0fae9900bf97 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:06 -0200 Subject: docs: kernel-doc.rst: improve typedef documentation Add documentation about typedefs for function prototypes and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index e3e82f8f4de5..b178857866f8 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -282,6 +282,28 @@ The kernel-doc data structure comments describe each member of the structure, in order, with the member descriptions. +Typedef documentation +--------------------- + +The general format of a typedef kernel-doc comment is:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Typedefs with function prototypes can also be documented:: + + /** + * typedef type_name - Brief description. + * @arg1: description of arg1 + * @arg2: description of arg2 + * + * Description of the type. + */ + typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); + Highlights and cross-references ------------------------------- @@ -384,16 +406,6 @@ on a line of their own, like all other kernel-doc comments:: int foobar; } -Typedef documentation ---------------------- - -The general format of a typedef kernel-doc comment is:: - - /** - * typedef type_name - Brief description. - * - * Description of the type. - */ Overview documentation comments ------------------------------- -- cgit From 93626d7a76e3aa854bb116f5894322e121cd84b1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:07 -0200 Subject: docs: kernel-doc.rst: add documentation about man pages kernel-doc-nano-HOWTO.txt has a chapter about man pages production. While we don't have a working "make manpages" target, add it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index b178857866f8..14c226e8154f 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -452,3 +452,37 @@ file. Data structures visible in kernel include files should also be documented using kernel-doc formatted comments. + +How to use kernel-doc to generate man pages +------------------------------------------- + +If you just want to use kernel-doc to generate man pages you can do this +from the Kernel git tree:: + + $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man + +Using the small ``split-man.pl`` script below:: + + + #!/usr/bin/perl + + if ($#ARGV < 0) { + die "where do I put the results?\n"; + } + + mkdir $ARGV[0],0777; + $state = 0; + while () { + if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { + if ($state == 1) { close OUT } + $state = 1; + $fn = "$ARGV[0]/$1.9"; + print STDERR "Creating $fn\n"; + open OUT, ">$fn" or die "can't open $fn: $!\n"; + print OUT $_; + } elsif ($state != 0) { + print OUT $_; + } + } + + close OUT; -- cgit From 857af3b775940865c215ab168212ebc96ab80f57 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:08 -0200 Subject: docs: get rid of kernel-doc-nano-HOWTO.txt Everything there is already described at Documentation/doc-guide/kernel-doc.rst. So, there's no reason why to keep it anymore. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/00-INDEX | 2 - Documentation/kernel-doc-nano-HOWTO.txt | 322 -------------------------------- 2 files changed, 324 deletions(-) delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt (limited to 'Documentation') diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 7023bfaec21c..7f3a0728ccf2 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -228,8 +228,6 @@ isdn/ - directory with info on the Linux ISDN support, and supported cards. kbuild/ - directory with info about the kernel build process. -kernel-doc-nano-HOWTO.txt - - outdated info about kernel-doc documentation. kdump/ - directory with mini HowTo on getting the crash dump code to work. doc-guide/ diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt deleted file mode 100644 index c23e2c5ab80d..000000000000 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ /dev/null @@ -1,322 +0,0 @@ -NOTE: this document is outdated and will eventually be removed. See -Documentation/doc-guide/ for current information. - -kernel-doc nano-HOWTO -===================== - -How to format kernel-doc comments ---------------------------------- - -In order to provide embedded, 'C' friendly, easy to maintain, -but consistent and extractable documentation of the functions and -data structures in the Linux kernel, the Linux kernel has adopted -a consistent style for documenting functions and their parameters, -and structures and their members. - -The format for this documentation is called the kernel-doc format. -It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. - -This style embeds the documentation within the source files, using -a few simple conventions. The scripts/kernel-doc perl script, the -Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand -these conventions, and are used to extract this embedded documentation -into various documents. - -In order to provide good documentation of kernel functions and data -structures, please use the following conventions to format your -kernel-doc comments in Linux kernel source. - -We definitely need kernel-doc formatted documentation for functions -that are exported to loadable modules using EXPORT_SYMBOL. - -We also look to provide kernel-doc formatted documentation for -functions externally visible to other kernel files (not marked -"static"). - -We also recommend providing kernel-doc formatted documentation -for private (file "static") routines, for consistency of kernel -source code layout. But this is lower priority and at the -discretion of the MAINTAINER of that kernel source file. - -Data structures visible in kernel include files should also be -documented using kernel-doc formatted comments. - -The opening comment mark "/**" is reserved for kernel-doc comments. -Only comments so marked will be considered by the kernel-doc scripts, -and any comment so marked must be in kernel-doc format. Do not use -"/**" to be begin a comment block unless the comment block contains -kernel-doc formatted comments. The closing comment marker for -kernel-doc comments can be either "*/" or "**/", but "*/" is -preferred in the Linux kernel tree. - -Kernel-doc comments should be placed just before the function -or data structure being described. - -Example kernel-doc function comment: - -/** - * foobar() - short function description of foobar - * @arg1: Describe the first argument to foobar. - * @arg2: Describe the second argument to foobar. - * One can provide multiple line descriptions - * for arguments. - * - * A longer description, with more discussion of the function foobar() - * that might be useful to those using or modifying it. Begins with - * empty comment line, and may include additional embedded empty - * comment lines. - * - * The longer description can have multiple paragraphs. - * - * Return: Describe the return value of foobar. - */ - -The short description following the subject can span multiple lines -and ends with an @argument description, an empty line or the end of -the comment block. - -The @argument descriptions must begin on the very next line following -this opening short function description line, with no intervening -empty comment lines. - -If a function parameter is "..." (varargs), it should be listed in -kernel-doc notation as: - * @...: description - -The return value, if any, should be described in a dedicated section -named "Return". - -Example kernel-doc data structure comment. - -/** - * struct blah - the basic blah structure - * @mem1: describe the first member of struct blah - * @mem2: describe the second member of struct blah, - * perhaps with more lines and words. - * - * Longer description of this structure. - */ - -The kernel-doc function comments describe each parameter to the -function, in order, with the @name lines. - -The kernel-doc data structure comments describe each structure member -in the data structure, with the @name lines. - -The longer description formatting is "reflowed", losing your line -breaks. So presenting carefully formatted lists within these -descriptions won't work so well; derived documentation will lose -the formatting. - -See the section below "How to add extractable documentation to your -source files" for more details and notes on how to format kernel-doc -comments. - -Components of the kernel-doc system ------------------------------------ - -Many places in the source tree have extractable documentation in the -form of block comments above functions. The components of this system -are: - -- scripts/kernel-doc - - This is a perl script that hunts for the block comments and can mark - them up directly into DocBook, ReST, man, text, and HTML. (No, not - texinfo.) - -- scripts/docproc.c - - This is a program for converting SGML template files into SGML - files. When a file is referenced it is searched for symbols - exported (EXPORT_SYMBOL), to be able to distinguish between internal - and external functions. - It invokes kernel-doc, giving it the list of functions that - are to be documented. - Additionally it is used to scan the SGML template files to locate - all the files referenced herein. This is used to generate dependency - information as used by make. - -- Makefile - - The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs' - are used to build XML DocBook files, LaTeX files, PDF files, - ePub files and html files in Documentation/. - -How to extract the documentation --------------------------------- - -If you just want to read the ready-made books on the various -subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs', -depending on your preference. If you would rather read a different format, -you can type 'make xmldocs' and then use DocBook tools to convert -Documentation/output/*.xml to a format of your choice (for example, -'db2html ...' if 'make htmldocs' was not defined). - -If you want to see man pages instead, you can do this: - -$ cd linux -$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man -$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man - -Here is split-man.pl: - ---> -#!/usr/bin/perl - -if ($#ARGV < 0) { - die "where do I put the results?\n"; -} - -mkdir $ARGV[0],0777; -$state = 0; -while () { - if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { - if ($state == 1) { close OUT } - $state = 1; - $fn = "$ARGV[0]/$1.9"; - print STDERR "Creating $fn\n"; - open OUT, ">$fn" or die "can't open $fn: $!\n"; - print OUT $_; - } elsif ($state != 0) { - print OUT $_; - } -} - -close OUT; -<-- - -If you just want to view the documentation for one function in one -file, you can do this: - -$ scripts/kernel-doc -man -function fn file | nroff -man | less - -or this: - -$ scripts/kernel-doc -text -function fn file - - -How to add extractable documentation to your source files ---------------------------------------------------------- - -The format of the block comment is like this: - -/** - * function_name(:)? (- short description)? -(* @parameterx(space)*: (description of parameter x)?)* -(* a blank line)? - * (Description:)? (Description of function)? - * (section header: (section description)? )* -(*)?*/ - -All "description" text can span multiple lines, although the -function_name & its short description are traditionally on a single line. -Description text may also contain blank lines (i.e., lines that contain -only a "*"). - -"section header:" names must be unique per function (or struct, -union, typedef, enum). - -Use the section header "Return" for sections describing the return value -of a function. - -Avoid putting a spurious blank line after the function name, or else the -description will be repeated! - -All descriptive text is further processed, scanning for the following special -patterns, which are highlighted appropriately. - -'funcname()' - function -'$ENVVAR' - environment variable -'&struct_name' - name of a structure (up to two words including 'struct') -'@parameter' - name of a parameter -'%CONST' - name of a constant. - -NOTE 1: The multi-line descriptive text you provide does *not* recognize -line breaks, so if you try to format some text nicely, as in: - - Return: - 0 - cool - 1 - invalid arg - 2 - out of memory - -this will all run together and produce: - - Return: 0 - cool 1 - invalid arg 2 - out of memory - -NOTE 2: If the descriptive text you provide has lines that begin with -some phrase followed by a colon, each of those phrases will be taken as -a new section heading, which means you should similarly try to avoid text -like: - - Return: - 0: cool - 1: invalid arg - 2: out of memory - -every line of which would start a new section. Again, probably not -what you were after. - -Take a look around the source tree for examples. - - -kernel-doc for structs, unions, enums, and typedefs ---------------------------------------------------- - -Beside functions you can also write documentation for structs, unions, -enums and typedefs. Instead of the function name you must write the name -of the declaration; the struct/union/enum/typedef must always precede -the name. Nesting of declarations is not supported. -Use the argument mechanism to document members or constants. - -Inside a struct description, you can use the "private:" and "public:" -comment tags. Structure fields that are inside a "private:" area -are not listed in the generated output documentation. The "private:" -and "public:" tags must begin immediately following a "/*" comment -marker. They may optionally include comments between the ":" and the -ending "*/" marker. - -Example: - -/** - * struct my_struct - short description - * @a: first member - * @b: second member - * - * Longer description - */ -struct my_struct { - int a; - int b; -/* private: internal use only */ - int c; -}; - - -Including documentation blocks in source files ----------------------------------------------- - -To facilitate having source code and comments close together, you can -include kernel-doc documentation blocks that are free-form comments -instead of being kernel-doc for functions, structures, unions, -enums, or typedefs. This could be used for something like a -theory of operation for a driver or library code, for example. - -This is done by using a DOC: section keyword with a section title. E.g.: - -/** - * DOC: Theory of Operation - * - * The whizbang foobar is a dilly of a gizmo. It can do whatever you - * want it to do, at any time. It reads your mind. Here's how it works. - * - * foo bar splat - * - * The only drawback to this gizmo is that is can sometimes damage - * hardware, software, or its subject(s). - */ - -DOC: sections are used in ReST files. - -Tim. -*/ -- cgit From 8ad72163165265b686902c182c1b4a913e738a81 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 18 Dec 2017 10:30:13 -0200 Subject: scripts: kernel-doc: parse next structs/unions There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 46 ++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'Documentation') diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 14c226e8154f..722d4525f7cf 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -281,6 +281,52 @@ comment block. The kernel-doc data structure comments describe each member of the structure, in order, with the member descriptions. +Nested structs/unions +~~~~~~~~~~~~~~~~~~~~~ + +It is possible to document nested structs unions, like:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @arg1: - first argument of anonymous union/anonymous struct + * @arg2: - second argument of anonymous union/anonymous struct + * @arg3: - third argument of anonymous union/anonymous struct + * @arg4: - fourth argument of anonymous union/anonymous struct + * @bar.st1.arg1 - first argument of struct st1 on union bar + * @bar.st1.arg2 - second argument of struct st1 on union bar + * @bar.st2.arg1 - first argument of struct st2 on union bar + * @bar.st2.arg2 - second argument of struct st2 on union bar + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int arg1; + int arg2; + } + struct { + void *arg3; + int arg4; + } + } + union { + struct { + int arg1; + int arg2; + } st1; + struct { + void *arg1; + int arg2; + } st2; + } bar; + }; + +.. note:: + + #) When documenting nested structs or unions, if the struct/union ``foo`` + is named, the argument ``bar`` inside it should be documented as + ``@foo.bar:`` + #) When the nested struct/union is anonymous, the argument ``bar`` on it + should be documented as ``@bar:`` Typedef documentation --------------------- -- cgit From 96e9dd55eb15433969b971eb06be3350f69b2d12 Mon Sep 17 00:00:00 2001 From: Chunyan Zhang Date: Thu, 7 Dec 2017 20:57:11 +0800 Subject: dt-bindings: Add Spreadtrum clock binding documentation Introduce a new binding with its documentation for Spreadtrum clock sub-framework. Signed-off-by: Chunyan Zhang Acked-by: Rob Herring Signed-off-by: Stephen Boyd --- Documentation/devicetree/bindings/clock/sprd.txt | 63 ++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 Documentation/devicetree/bindings/clock/sprd.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/sprd.txt b/Documentation/devicetree/bindings/clock/sprd.txt new file mode 100644 index 000000000000..e9d179e882d9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sprd.txt @@ -0,0 +1,63 @@ +Spreadtrum Clock Binding +------------------------ + +Required properties: +- compatible: should contain the following compatible strings: + - "sprd,sc9860-pmu-gate" + - "sprd,sc9860-pll" + - "sprd,sc9860-ap-clk" + - "sprd,sc9860-aon-prediv" + - "sprd,sc9860-apahb-gate" + - "sprd,sc9860-aon-gate" + - "sprd,sc9860-aonsecure-clk" + - "sprd,sc9860-agcp-gate" + - "sprd,sc9860-gpu-clk" + - "sprd,sc9860-vsp-clk" + - "sprd,sc9860-vsp-gate" + - "sprd,sc9860-cam-clk" + - "sprd,sc9860-cam-gate" + - "sprd,sc9860-disp-clk" + - "sprd,sc9860-disp-gate" + - "sprd,sc9860-apapb-gate" + +- #clock-cells: must be 1 + +- clocks : Should be the input parent clock(s) phandle for the clock, this + property here just simply shows which clock group the clocks' + parents are in, since each clk node would represent many clocks + which are defined in the driver. The detailed dependency + relationship (i.e. how many parents and which are the parents) + are implemented in driver code. + +Optional properties: + +- reg: Contain the registers base address and length. It must be configured + only if no 'sprd,syscon' under the node. + +- sprd,syscon: phandle to the syscon which is in the same address area with + the clock, and so we can get regmap for the clocks from the + syscon device. + +Example: + + pmu_gate: pmu-gate { + compatible = "sprd,sc9860-pmu-gate"; + sprd,syscon = <&pmu_regs>; + clocks = <&ext_26m>; + #clock-cells = <1>; + }; + + pll: pll { + compatible = "sprd,sc9860-pll"; + sprd,syscon = <&ana_regs>; + clocks = <&pmu_gate 0>; + #clock-cells = <1>; + }; + + ap_clk: clock-controller@20000000 { + compatible = "sprd,sc9860-ap-clk"; + reg = <0 0x20000000 0 0x400>; + clocks = <&ext_26m>, <&pll 0>, + <&pmu_gate 0>; + #clock-cells = <1>; + }; -- cgit From 36ab04671570fcd0e33868eba83f361d76c36bbf Mon Sep 17 00:00:00 2001 From: Yuantian Tang Date: Wed, 22 Nov 2017 09:40:53 +0800 Subject: clk: qoriq: add more divider clocks support More divider clocks are needed by IP. So enlarge the PLL divider array to accommodate more divider clocks. Signed-off-by: Tang Yuantian Acked-by: Rob Herring Signed-off-by: Stephen Boyd --- Documentation/devicetree/bindings/clock/qoriq-clock.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index 6498e1fdbb33..97f46adac85f 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -78,6 +78,7 @@ second cell is the clock index for the specified type. 2 hwaccel index (n in CLKCGnHWACSR) 3 fman 0 for fm1, 1 for fm2 4 platform pll 0=pll, 1=pll/2, 2=pll/3, 3=pll/4 + 4=pll/5, 5=pll/6, 6=pll/7, 7=pll/8 5 coreclk must be 0 3. Example -- cgit From 51279ef9f64cf7eb8b3f891a2b60fa1aa4938afc Mon Sep 17 00:00:00 2001 From: Sergej Sawazki Date: Sat, 16 Sep 2017 13:44:41 +0200 Subject: clk: si5351: Add DT property to enable PLL reset Add optional output clock DT property to enable PLL reset when a clock output is enabled. Cc: Sebastian Hesselbarth Cc: Rabeeh Khoury Cc: Russell King Signed-off-by: Sergej Sawazki Signed-off-by: Stephen Boyd --- Documentation/devicetree/bindings/clock/silabs,si5351.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/silabs,si5351.txt b/Documentation/devicetree/bindings/clock/silabs,si5351.txt index a6c4ef343b44..f00191cad8cd 100644 --- a/Documentation/devicetree/bindings/clock/silabs,si5351.txt +++ b/Documentation/devicetree/bindings/clock/silabs,si5351.txt @@ -49,6 +49,7 @@ Optional child node properties: - silabs,multisynth-source: source pll A(0) or B(1) of corresponding multisynth divider. - silabs,pll-master: boolean, multisynth can change pll frequency. +- silabs,pll-reset: boolean, clock output can reset its pll. - silabs,disable-state : clock output disable state, shall be 0 = clock output is driven LOW when disabled 1 = clock output is driven HIGH when disabled -- cgit From 1a4bb1d14f7c0c4df418d08eb8e24d1c0e54b06a Mon Sep 17 00:00:00 2001 From: Shannon Nelson Date: Thu, 21 Dec 2017 14:26:18 -0800 Subject: xfrm: update the stats documentation Add a couple of stats that aren't in the documentation file and rework the top description to be a little more readable. Signed-off-by: Shannon Nelson Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_proc.txt | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/xfrm_proc.txt b/Documentation/networking/xfrm_proc.txt index d0d8bafa9016..2eae619ab67b 100644 --- a/Documentation/networking/xfrm_proc.txt +++ b/Documentation/networking/xfrm_proc.txt @@ -5,13 +5,15 @@ Masahide NAKAMURA Transformation Statistics ------------------------- -xfrm_proc is a statistics shown factor dropped by transformation -for developer. -It is a counter designed from current transformation source code -and defined like linux private MIB. -Inbound statistics -~~~~~~~~~~~~~~~~~~ +The xfrm_proc code is a set of statistics showing numbers of packets +dropped by the transformation code and why. These counters are defined +as part of the linux private MIB. These counters can be viewed in +/proc/net/xfrm_stat. + + +Inbound errors +~~~~~~~~~~~~~~ XfrmInError: All errors which is not matched others XfrmInBufferError: @@ -46,6 +48,10 @@ XfrmInPolBlock: Policy discards XfrmInPolError: Policy error +XfrmAcquireError: + State hasn't been fully acquired before use +XfrmFwdHdrError: + Forward routing of a packet is not allowed Outbound errors ~~~~~~~~~~~~~~~ @@ -72,3 +78,5 @@ XfrmOutPolDead: Policy is dead XfrmOutPolError: Policy error +XfrmOutStateInvalid: + State is invalid, perhaps expired -- cgit From c49e800f89296f09eb4130b5d65ce7b7c5d57d46 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Fri, 1 Dec 2017 17:16:57 +0100 Subject: drm/panel: Add DT bindings for Ilitek ILI9322 This adds device tree bindings for the Ilitek ILI9322 320x240 TFT panel driver. Cc: David Lechner Cc: Stefano Babic Cc: Ben Dooks Cc: devicetree@vger.kernel.org Reviewed-by: Rob Herring Signed-off-by: Linus Walleij Link: https://patchwork.freedesktop.org/patch/msgid/20171201161659.9588-1-linus.walleij@linaro.org --- .../bindings/display/panel/ilitek,ili9322.txt | 49 ++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 Documentation/devicetree/bindings/display/panel/ilitek,ili9322.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.txt b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.txt new file mode 100644 index 000000000000..3d5ce6ad6ec7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/ilitek,ili9322.txt @@ -0,0 +1,49 @@ +Ilitek ILI9322 TFT panel driver with SPI control bus + +This is a driver for 320x240 TFT panels, accepting a variety of input +streams that get adapted and scaled to the panel. The panel output has +960 TFT source driver pins and 240 TFT gate driver pins, VCOM, VCOML and +VCOMH outputs. + +Required properties: + - compatible: "dlink,dir-685-panel", "ilitek,ili9322" + (full system-specific compatible is always required to look up configuration) + - reg: address of the panel on the SPI bus + +Optional properties: + - vcc-supply: core voltage supply, see regulator/regulator.txt + - iovcc-supply: voltage supply for the interface input/output signals, + see regulator/regulator.txt + - vci-supply: voltage supply for analog parts, see regulator/regulator.txt + - reset-gpios: a GPIO spec for the reset pin, see gpio/gpio.txt + + The following optional properties only apply to RGB and YUV input modes and + can be omitted for BT.656 input modes: + + - pixelclk-active: see display/panel/display-timing.txt + - de-active: see display/panel/display-timing.txt + - hsync-active: see display/panel/display-timing.txt + - vsync-active: see display/panel/display-timing.txt + +The panel must obey the rules for a SPI slave device as specified in +spi/spi-bus.txt + +The device node can contain one 'port' child node with one child +'endpoint' node, according to the bindings defined in +media/video-interfaces.txt. This node should describe panel's video bus. + +Example: + +panel: display@0 { + compatible = "dlink,dir-685-panel", "ilitek,ili9322"; + reg = <0>; + vcc-supply = <&vdisp>; + iovcc-supply = <&vdisp>; + vci-supply = <&vdisp>; + + port { + panel_in: endpoint { + remote-endpoint = <&display_out>; + }; + }; +}; -- cgit From f76d38b26c114c5e6c8252f3c7dac42bbd69c2c3 Mon Sep 17 00:00:00 2001 From: Łukasz Stelmach Date: Tue, 12 Dec 2017 17:36:04 +0100 Subject: crypto: exynos - Support Exynos5250+ SoCs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add support for PRNG in Exynos5250+ SoCs. Signed-off-by: Łukasz Stelmach Reviewed-by: Krzysztof Kozlowski Signed-off-by: Herbert Xu --- Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt b/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt index 4ca8dd4d7e66..a13fbdb4bd88 100644 --- a/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt +++ b/Documentation/devicetree/bindings/crypto/samsung,exynos-rng4.txt @@ -2,7 +2,9 @@ Exynos Pseudo Random Number Generator Required properties: -- compatible : Should be "samsung,exynos4-rng". +- compatible : One of: + - "samsung,exynos4-rng" for Exynos4210 and Exynos4412 + - "samsung,exynos5250-prng" for Exynos5250+ - reg : Specifies base physical address and size of the registers map. - clocks : Phandle to clock-controller plus clock-specifier pair. - clock-names : "secss" as a clock name. -- cgit From f1ee616214cb22410e939d963bbb2349c2570f02 Mon Sep 17 00:00:00 2001 From: NeilBrown Date: Thu, 21 Dec 2017 09:45:40 +1100 Subject: VFS: don't keep disconnected dentries on d_anon The original purpose of the per-superblock d_anon list was to keep disconnected dentries in the cache between consecutive requests to the NFS server. Dentries can be disconnected if a client holds a file open and repeatedly performs IO on it, and if the server drops the dentry, whether due to memory pressure, server restart, or "echo 3 > /proc/sys/vm/drop_caches". This purpose was thwarted by commit 75a6f82a0d10 ("freeing unlinked file indefinitely delayed") which caused disconnected dentries to be freed as soon as their refcount reached zero. This means that, when a dentry being used by nfsd gets disconnected, a new one needs to be allocated for every request (unless requests overlap). As the dentry has no name, no parent, and no children, there is little of value to cache. As small memory allocations are typically fast (from per-cpu free lists) this likely has little cost. This means that the original purpose of s_anon is no longer relevant: there is no longer any need to keep disconnected dentries on a list so they appear to be hashed. However, s_anon now has a new use. When you mount an NFS filesystem, the dentry stored in s_root is just a placebo. The "real" root dentry is allocated using d_obtain_root() and so it kept on the s_anon list. I don't know the reason for this, but suspect it related to NFSv4 where a mount of "server:/some/path" require NFS to look up the root filehandle on the server, then walk down "/some" and "/path" to get the filehandle to mount. Whatever the reason, NFS depends on the s_anon list and on shrink_dcache_for_umount() pruning all dentries on this list. So we cannot simply remove s_anon. We could just leave the code unchanged, but apart from that being potentially confusing, the (unfair) bit-spin-lock which protects s_anon can become a bottle neck when lots of disconnected dentries are being created. So this patch renames s_anon to s_roots, and stops storing disconnected dentries on the list. Only dentries obtained with d_obtain_root() are now stored on this list. There are many fewer of these (only NFS and NILFS2 use the call, and only during filesystem mount) so contention on the bit-lock will not be a problem. Possibly an alternate solution should be found for NFS and NILFS2, but that would require understanding their needs first. Signed-off-by: NeilBrown Signed-off-by: Al Viro --- Documentation/filesystems/nfs/Exporting | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/Exporting index 520a4becb75c..63889149f532 100644 --- a/Documentation/filesystems/nfs/Exporting +++ b/Documentation/filesystems/nfs/Exporting @@ -56,13 +56,25 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on any dentry that might not be part of the proper prefix. This is set when anonymous dentries are created, and cleared when a dentry is noticed to be a child of a dentry which is in the proper - prefix. - -b/ A per-superblock list "s_anon" of dentries which are the roots of - subtrees that are not in the proper prefix. These dentries, as - well as the proper prefix, need to be released at unmount time. As - these dentries will not be hashed, they are linked together on the - d_hash list_head. + prefix. If the refcount on a dentry with this flag set + becomes zero, the dentry is immediately discarded, rather than being + kept in the dcache. If a dentry that is not already in the dcache + is repeatedly accessed by filehandle (as NFSD might do), an new dentry + will be a allocated for each access, and discarded at the end of + the access. + + Note that such a dentry can acquire children, name, ancestors, etc. + without losing DCACHE_DISCONNECTED - that flag is only cleared when + subtree is successfully reconnected to root. Until then dentries + in such subtree are retained only as long as there are references; + refcount reaching zero means immediate eviction, same as for unhashed + dentries. That guarantees that we won't need to hunt them down upon + umount. + +b/ A primitive for creation of secondary roots - d_obtain_root(inode). + Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the + per-superblock list (->s_roots), so they can be located at umount + time for eviction purposes. c/ Helper routines to allocate anonymous dentries, and to help attach loose directory dentries at lookup time. They are: @@ -77,7 +89,6 @@ c/ Helper routines to allocate anonymous dentries, and to help attach (such as an anonymous one created by d_obtain_alias), if appropriate. It returns NULL when the passed-in dentry is used, following the calling convention of ->lookup. - Filesystem Issues ----------------- -- cgit From 86b3a471cf14bb1dc4d6ef9b1cc5d1aee554890b Mon Sep 17 00:00:00 2001 From: Neil Armstrong Date: Mon, 4 Dec 2017 10:21:06 +0100 Subject: dt-bindings: Add vendor prefix for Solomon Goldentek Display Corporation Solomon Goldentek Display Corporation is a Taiwanese LCD/LCM manufacturer. Company Site: http://www.goldentek.com.tw Acked-by: Rob Herring Signed-off-by: Neil Armstrong Signed-off-by: Shawn Guo --- Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 0994bdd82cd3..b0d3beff47b5 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -305,6 +305,7 @@ seagate Seagate Technology PLC semtech Semtech Corporation sensirion Sensirion AG sff Small Form Factor Committee +sgd Solomon Goldentek Display Corporation sgx SGX Sensortech sharp Sharp Corporation shimafuji Shimafuji Electric, Inc. -- cgit From ca0ccbe3a3581be10b4528f24473b31399bede5b Mon Sep 17 00:00:00 2001 From: Neil Armstrong Date: Mon, 4 Dec 2017 10:21:07 +0100 Subject: dt-bindings: display: Add bindings for SGD GKTW70SDAE4SE Panel The GKTW70SDAE4SE is an LVDS display panel. Their bindings are modelled on the the LVDS panel bindings. Acked-by: Rob Herring Signed-off-by: Neil Armstrong Signed-off-by: Shawn Guo --- .../bindings/display/panel/sgd,gktw70sdae4se.txt | 41 ++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt new file mode 100644 index 000000000000..d06644b555bd --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sgd,gktw70sdae4se.txt @@ -0,0 +1,41 @@ +Solomon Goldentek Display GKTW70SDAE4SE LVDS Display Panel +========================================================== + +The GKTW70SDAE4SE is a 7" WVGA TFT-LCD display panel. + +These DT bindings follow the LVDS panel bindings defined in panel-lvds.txt +with the following device-specific properties. + +Required properties: + +- compatible: Shall contain "sgd,gktw70sdae4se" and "panel-lvds", in that order. + +Example +------- + +panel { + compatible = "sgd,gktw70sdae4se", "panel-lvds"; + + width-mm = <153>; + height-mm = <86>; + + data-mapping = "jeida-18"; + + panel-timing { + clock-frequency = <32000000>; + hactive = <800>; + vactive = <480>; + hback-porch = <39>; + hfront-porch = <39>; + vback-porch = <29>; + vfront-porch = <13>; + hsync-len = <47>; + vsync-len = <2>; + }; + + port { + panel_in: endpoint { + remote-endpoint = <&lvds_encoder>; + }; + }; +}; -- cgit From 0e865fe12a93800cde688ee92834522eda185fbf Mon Sep 17 00:00:00 2001 From: Sebastien Bourdelin Date: Thu, 7 Dec 2017 11:05:49 -0500 Subject: of: documentation: add bindings documentation for TS-7970 This adds the documentation for the TS-7970 by Technologic Systems. Signed-off-by: Sebastien Bourdelin Reviewed-by: Rob Herring Signed-off-by: Shawn Guo --- Documentation/devicetree/bindings/arm/technologic.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/technologic.txt b/Documentation/devicetree/bindings/arm/technologic.txt index 33797acad846..187830bd4f51 100644 --- a/Documentation/devicetree/bindings/arm/technologic.txt +++ b/Documentation/devicetree/bindings/arm/technologic.txt @@ -10,3 +10,9 @@ It can be mounted on a carrier board providing additional peripheral connectors. Required root node properties: - compatible = "technologic,imx6dl-ts4900", "fsl,imx6dl" - compatible = "technologic,imx6q-ts4900", "fsl,imx6q" + +TS-7970 is a System-on-Module based on the Freescale i.MX6 System-on-Chip. +It can be mounted on a carrier board providing additional peripheral connectors. +Required root node properties: + - compatible = "technologic,imx6dl-ts7970", "fsl,imx6dl" + - compatible = "technologic,imx6q-ts7970", "fsl,imx6q" -- cgit From 8b0a08ac9c6d475796df53b12d04c72d593fbf70 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdelin Date: Thu, 7 Dec 2017 12:11:17 -0500 Subject: of: documentation: add bindings documentation for TS-4600 This adds the documentation for the TS-4600 by Technologic Systems. Signed-off-by: Sebastien Bourdelin Acked-by: Rob Herring Signed-off-by: Shawn Guo --- Documentation/devicetree/bindings/arm/technologic.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/technologic.txt b/Documentation/devicetree/bindings/arm/technologic.txt index 187830bd4f51..f1cedc00dcab 100644 --- a/Documentation/devicetree/bindings/arm/technologic.txt +++ b/Documentation/devicetree/bindings/arm/technologic.txt @@ -1,6 +1,11 @@ Technologic Systems Platforms Device Tree Bindings -------------------------------------------------- +TS-4600 is a System-on-Module based on the Freescale i.MX28 System-on-Chip. +It can be mounted on a carrier board providing additional peripheral connectors. +Required root node properties: + - compatible = "technologic,imx28-ts4600", "fsl,imx28" + TS-4800 board Required root node properties: - compatible = "technologic,imx51-ts4800", "fsl,imx51"; -- cgit From 3988ca6af7e2a24655d7725cd317902dabeda6c3 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Sat, 16 Dec 2017 16:03:02 -0200 Subject: dt-bindings: imx-gpcv2: Fix the unit address In the provided example the unit address does not match the 'reg' value, as IMX7_POWER_DOMAIN_PCIE_PHY is defined as 1. Fix the unit address and avoid using defines in reg as per Rob Herring's recommendation. Signed-off-by: Fabio Estevam Reviewed-by: Rob Herring Signed-off-by: Shawn Guo --- Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt b/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt index 02f45c65fd87..9acce75b29ab 100644 --- a/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt +++ b/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt @@ -44,10 +44,10 @@ Example: #address-cells = <1>; #size-cells = <0>; - pgc_pcie_phy: power-domain@3 { + pgc_pcie_phy: power-domain@1 { #power-domain-cells = <0>; - reg = ; + reg = <1>; power-supply = <®_1p0d>; }; }; -- cgit From cfabb7921ccbede2968e5049d433ba3d0e0950af Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Fri, 15 Dec 2017 00:24:57 -0200 Subject: soc: imx: gpc: Add i.MX6SX PCI power domain i.MX6SX has a PCI power domain in PGC. Add support for it. Signed-off-by: Fabio Estevam Acked-by: Lucas Stach Signed-off-by: Shawn Guo --- Documentation/devicetree/bindings/power/fsl,imx-gpc.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt b/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt index e371b262d709..b31d6bbeee16 100644 --- a/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt +++ b/Documentation/devicetree/bindings/power/fsl,imx-gpc.txt @@ -9,6 +9,7 @@ Required properties: - fsl,imx6q-gpc - fsl,imx6qp-gpc - fsl,imx6sl-gpc + - fsl,imx6sx-gpc - reg: should be register base and length as documented in the datasheet - interrupts: Should contain one interrupt specifier for the GPC interrupt @@ -29,6 +30,8 @@ Required properties: PU_DOMAIN 1 The following additional DOMAIN_INDEX value is valid for i.MX6SL: DISPLAY_DOMAIN 2 + The following additional DOMAIN_INDEX value is valid for i.MX6SX: + PCI_DOMAIN 3 - #power-domain-cells: Should be 0 -- cgit From afc3bca4cf9d269dcf9f3abd0d65e45a390f0e59 Mon Sep 17 00:00:00 2001 From: Rob Herring Date: Thu, 21 Dec 2017 12:29:17 -0600 Subject: dt-bindings: Use lower case hex in unit-addresses DT unit addresses should be lower case hex. Fix all the binding examples. Converted with the following command from Krzysztof Kozlowski: sed -e 's/@\([a-fA-F0-9_-]*\) {/@\L\1 {/' -i $(find Documentation/devicetree/bindings -name '*.txt') Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt | 6 +++--- .../devicetree/bindings/arm/samsung/samsung-boards.txt | 2 +- Documentation/devicetree/bindings/clock/exynos3250-clock.txt | 2 +- Documentation/devicetree/bindings/clock/exynos5260-clock.txt | 2 +- Documentation/devicetree/bindings/clock/exynos5410-clock.txt | 2 +- Documentation/devicetree/bindings/clock/exynos5433-clock.txt | 2 +- Documentation/devicetree/bindings/crypto/atmel-crypto.txt | 2 +- .../devicetree/bindings/devfreq/event/exynos-nocp.txt | 2 +- .../devicetree/bindings/display/exynos/exynos_dsim.txt | 2 +- Documentation/devicetree/bindings/display/st,stih4xx.txt | 2 +- Documentation/devicetree/bindings/dma/ste-dma40.txt | 2 +- Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt | 2 +- Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt | 2 +- Documentation/devicetree/bindings/gpio/gpio.txt | 2 +- .../devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt | 2 +- Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt | 2 +- Documentation/devicetree/bindings/input/samsung-keypad.txt | 2 +- .../bindings/input/touchscreen/brcm,iproc-touchscreen.txt | 2 +- Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt | 2 +- Documentation/devicetree/bindings/mailbox/omap-mailbox.txt | 2 +- Documentation/devicetree/bindings/media/s5p-cec.txt | 2 +- Documentation/devicetree/bindings/media/samsung-s5c73m3.txt | 2 +- .../devicetree/bindings/memory-controllers/ti-aemif.txt | 2 +- Documentation/devicetree/bindings/mfd/cros-ec.txt | 2 +- Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt | 2 +- Documentation/devicetree/bindings/net/cpsw.txt | 4 ++-- Documentation/devicetree/bindings/net/davinci-mdio.txt | 4 ++-- Documentation/devicetree/bindings/net/fsl-tsec-phy.txt | 2 +- Documentation/devicetree/bindings/phy/ti-phy.txt | 2 +- .../devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt | 6 +++--- .../devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt | 2 +- .../devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt | 2 +- Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt | 2 +- .../devicetree/bindings/powerpc/fsl/interlaken-lac.txt | 12 ++++++------ .../devicetree/bindings/regulator/st,stm32-vrefbuf.txt | 2 +- Documentation/devicetree/bindings/serial/lantiq_asc.txt | 2 +- Documentation/devicetree/bindings/sound/img,i2s-out.txt | 2 +- Documentation/devicetree/bindings/sound/img,parallel-out.txt | 2 +- Documentation/devicetree/bindings/sound/img,spdif-in.txt | 2 +- Documentation/devicetree/bindings/sound/img,spdif-out.txt | 2 +- Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt | 8 ++++---- Documentation/devicetree/bindings/spi/spi-davinci.txt | 2 +- Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt | 2 +- Documentation/devicetree/bindings/thermal/exynos-thermal.txt | 2 +- Documentation/devicetree/bindings/thermal/thermal.txt | 6 +++--- .../devicetree/bindings/timer/samsung,exynos4210-mct.txt | 2 +- Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt | 2 +- Documentation/devicetree/bindings/watchdog/samsung-wdt.txt | 2 +- 48 files changed, 64 insertions(+), 64 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt index ccaaec6014bd..6c49db7f8ad2 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt @@ -55,7 +55,7 @@ Note: child nodes can be added for auto probing from device tree. Example: adding device info in dtsi file -adc: adc@12D10000 { +adc: adc@12d10000 { compatible = "samsung,exynos-adc-v1"; reg = <0x12D10000 0x100>; interrupts = <0 106 0>; @@ -71,7 +71,7 @@ adc: adc@12D10000 { Example: adding device info in dtsi file for Exynos3250 with additional sclk -adc: adc@126C0000 { +adc: adc@126c0000 { compatible = "samsung,exynos3250-adc", "samsung,exynos-adc-v2; reg = <0x126C0000 0x100>; interrupts = <0 137 0>; @@ -87,7 +87,7 @@ adc: adc@126C0000 { Example: Adding child nodes in dts file -adc@12D10000 { +adc@12d10000 { /* NTC thermistor is a hwmon device */ ncp15wb473@0 { diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt index e13459618581..469ac98ecf8f 100644 --- a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt @@ -72,7 +72,7 @@ Optional nodes: - compatible: only "samsung,secure-firmware" is currently supported - reg: address of non-secure SYSRAM used for communication with firmware - firmware@203F000 { + firmware@203f000 { compatible = "samsung,secure-firmware"; reg = <0x0203F000 0x1000>; }; diff --git a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt index f1738b88c225..7441ed519f02 100644 --- a/Documentation/devicetree/bindings/clock/exynos3250-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos3250-clock.txt @@ -32,7 +32,7 @@ Example 1: Examples of clock controller nodes are listed below. #clock-cells = <1>; }; - cmu_dmc: clock-controller@105C0000 { + cmu_dmc: clock-controller@105c0000 { compatible = "samsung,exynos3250-cmu-dmc"; reg = <0x105C0000 0x2000>; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/exynos5260-clock.txt b/Documentation/devicetree/bindings/clock/exynos5260-clock.txt index 5496b2fac483..c79d31f7f66e 100644 --- a/Documentation/devicetree/bindings/clock/exynos5260-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5260-clock.txt @@ -180,7 +180,7 @@ Example 2: UART controller node that consumes the clock generated by the peri clock controller. Refer to the standard clock bindings for information about 'clocks' and 'clock-names' property. - serial@12C00000 { + serial@12c00000 { compatible = "samsung,exynos4210-uart"; reg = <0x12C00000 0x100>; interrupts = <0 146 0>; diff --git a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt index c68b0d29b3d0..217beb27c30e 100644 --- a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt @@ -41,7 +41,7 @@ Example 2: UART controller node that consumes the clock generated by the clock controller. Refer to the standard clock bindings for information about 'clocks' and 'clock-names' property. - serial@12C20000 { + serial@12c20000 { compatible = "samsung,exynos4210-uart"; reg = <0x12C00000 0x100>; interrupts = <0 51 0>; diff --git a/Documentation/devicetree/bindings/clock/exynos5433-clock.txt b/Documentation/devicetree/bindings/clock/exynos5433-clock.txt index c473dd38dd55..50d5897c9849 100644 --- a/Documentation/devicetree/bindings/clock/exynos5433-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5433-clock.txt @@ -472,7 +472,7 @@ Example 2: Examples of clock controller nodes are listed below. Example 3: UART controller node that consumes the clock generated by the clock controller. - serial_0: serial@14C10000 { + serial_0: serial@14c10000 { compatible = "samsung,exynos5433-uart"; reg = <0x14C10000 0x100>; interrupts = <0 421 0>; diff --git a/Documentation/devicetree/bindings/crypto/atmel-crypto.txt b/Documentation/devicetree/bindings/crypto/atmel-crypto.txt index 7de1a9674c70..6b458bb2440d 100644 --- a/Documentation/devicetree/bindings/crypto/atmel-crypto.txt +++ b/Documentation/devicetree/bindings/crypto/atmel-crypto.txt @@ -75,7 +75,7 @@ Required properties: - clock-frequency: must be present in the i2c controller node. Example: -atecc508a@C0 { +atecc508a@c0 { compatible = "atmel,atecc508a"; reg = <0xC0>; }; diff --git a/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt b/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt index fd459f00aa5a..aeaebd425d1f 100644 --- a/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt +++ b/Documentation/devicetree/bindings/devfreq/event/exynos-nocp.txt @@ -20,7 +20,7 @@ Optional properties: Example : NoC Probe nodes in Device Tree are listed below. - nocp_mem0_0: nocp@10CA1000 { + nocp_mem0_0: nocp@10ca1000 { compatible = "samsung,exynos5420-nocp"; reg = <0x10CA1000 0x200>; }; diff --git a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt index ca5204b3bc21..2fff8b406f4c 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt @@ -54,7 +54,7 @@ Video interfaces: Example: - dsi@11C80000 { + dsi@11c80000 { compatible = "samsung,exynos4210-mipi-dsi"; reg = <0x11C80000 0x10000>; interrupts = <0 79 0>; diff --git a/Documentation/devicetree/bindings/display/st,stih4xx.txt b/Documentation/devicetree/bindings/display/st,stih4xx.txt index a352ed30cd70..6778b3e7ad5b 100644 --- a/Documentation/devicetree/bindings/display/st,stih4xx.txt +++ b/Documentation/devicetree/bindings/display/st,stih4xx.txt @@ -119,7 +119,7 @@ Example: / { ... - vtg_main_slave: sti-vtg-main-slave@fe85A800 { + vtg_main_slave: sti-vtg-main-slave@fe85a800 { compatible = "st,vtg"; reg = <0xfe85A800 0x300>; interrupts = ; diff --git a/Documentation/devicetree/bindings/dma/ste-dma40.txt b/Documentation/devicetree/bindings/dma/ste-dma40.txt index aa7dbd565ad0..99ab5c4d331e 100644 --- a/Documentation/devicetree/bindings/dma/ste-dma40.txt +++ b/Documentation/devicetree/bindings/dma/ste-dma40.txt @@ -15,7 +15,7 @@ Optional properties: Example: - dma: dma-controller@801C0000 { + dma: dma-controller@801c0000 { compatible = "stericsson,db8500-dma40", "stericsson,dma40"; reg = <0x801C0000 0x1000 0x40010000 0x800>; reg-names = "base", "lcpa"; diff --git a/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt index 00611aceed3e..a25c87b650e5 100644 --- a/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/abilis,tb10x-gpio.txt @@ -21,7 +21,7 @@ Documentation/devicetree/bindings/gpio/gpio.txt Example: - gpioa: gpio@FF140000 { + gpioa: gpio@ff140000 { compatible = "abilis,tb10x-gpio"; interrupt-controller; #interrupt-cells = <1>; diff --git a/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt b/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt index 854de130a971..78458adbf4b7 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-stp-xway.txt @@ -27,7 +27,7 @@ Optional properties: Example: -gpio1: stp@E100BB0 { +gpio1: stp@e100bb0 { compatible = "lantiq,gpio-stp-xway"; reg = <0xE100BB0 0x40>; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 802402f6cc5d..b5de08e3b1a2 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -290,7 +290,7 @@ pins 50..69. Example 2: - gpio_pio_i: gpio-controller@14B0 { + gpio_pio_i: gpio-controller@14b0 { #gpio-cells = <2>; compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; reg = <0x1480 0x18>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt index 248a155414c2..548a73cde796 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt @@ -54,7 +54,7 @@ Optional properties: Example: - i2c@12CA0000 { + i2c@12ca0000 { compatible = "acme,some-i2c-device"; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt index 70c054a9a997..60fe90d69f4e 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt @@ -11,7 +11,7 @@ Required properties: Examples: -lpi2c7: lpi2c7@40A50000 { +lpi2c7: lpi2c7@40a50000 { compatible = "fsl,imx8dv-lpi2c"; reg = <0x40A50000 0x10000>; interrupt-parent = <&intc>; diff --git a/Documentation/devicetree/bindings/input/samsung-keypad.txt b/Documentation/devicetree/bindings/input/samsung-keypad.txt index 5305e74e5742..4c5c0a82586d 100644 --- a/Documentation/devicetree/bindings/input/samsung-keypad.txt +++ b/Documentation/devicetree/bindings/input/samsung-keypad.txt @@ -45,7 +45,7 @@ Optional Properties specific to linux: Example: - keypad@100A0000 { + keypad@100a0000 { compatible = "samsung,s5pv210-keypad"; reg = <0x100A0000 0x100>; interrupts = <173>; diff --git a/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt b/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt index ac5dff412e25..f127a2117072 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/brcm,iproc-touchscreen.txt @@ -66,7 +66,7 @@ Example: An example of touchscreen node reg = <0x180a6000 0xc30>; }; - touchscreen: touchscreen@180A6000 { + touchscreen: touchscreen@180a6000 { compatible = "brcm,iproc-touchscreen"; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt index 85f068805dd8..b1682c80b490 100644 --- a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt +++ b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt @@ -56,7 +56,7 @@ Examples: iommus = <&sysmmu_gsc0>; }; - sysmmu_gsc0: sysmmu@13E80000 { + sysmmu_gsc0: sysmmu@13e80000 { compatible = "samsung,exynos-sysmmu"; reg = <0x13E80000 0x1000>; interrupt-parent = <&combiner>; diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt index 9b40c4925aa9..0ef372656a3e 100644 --- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -124,7 +124,7 @@ dsp { }; /* AM33xx */ -mailbox: mailbox@480C8000 { +mailbox: mailbox@480c8000 { compatible = "ti,omap4-mailbox"; reg = <0x480C8000 0x200>; interrupts = <77>; diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt index 6f3756da900f..e847291d4aff 100644 --- a/Documentation/devicetree/bindings/media/s5p-cec.txt +++ b/Documentation/devicetree/bindings/media/s5p-cec.txt @@ -23,7 +23,7 @@ Optional: Example: -hdmicec: cec@100B0000 { +hdmicec: cec@100b0000 { compatible = "samsung,s5p-cec"; reg = <0x100B0000 0x200>; interrupts = <0 114 0>; diff --git a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt index 2c85c4538a6d..21f31fdf5543 100644 --- a/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt +++ b/Documentation/devicetree/bindings/media/samsung-s5c73m3.txt @@ -62,7 +62,7 @@ For more details see description of the SPI busses bindings Example: -i2c@138A000000 { +i2c@138a000000 { ... s5c73m3@3c { compatible = "samsung,s5c73m3"; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt b/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt index 9592717f483f..190437a0c146 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt +++ b/Documentation/devicetree/bindings/memory-controllers/ti-aemif.txt @@ -138,7 +138,7 @@ from the corresponding HW reg. Example for aemif, davinci nand and nor flash chip select shown below. -memory-controller@21000A00 { +memory-controller@21000a00 { compatible = "ti,davinci-aemif"; #address-cells = <2>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/mfd/cros-ec.txt b/Documentation/devicetree/bindings/mfd/cros-ec.txt index 136e0c2da44d..6245c9b1a68b 100644 --- a/Documentation/devicetree/bindings/mfd/cros-ec.txt +++ b/Documentation/devicetree/bindings/mfd/cros-ec.txt @@ -41,7 +41,7 @@ Optional properties (all): Example for I2C: -i2c@12CA0000 { +i2c@12ca0000 { cros-ec@1e { reg = <0x1e>; compatible = "google,cros-ec-i2c"; diff --git a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt index d0a37252eb22..6d60bc3063f5 100644 --- a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt +++ b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt @@ -23,7 +23,7 @@ Optional subnodes: Example: - mlc: flash@200A8000 { + mlc: flash@200a8000 { compatible = "nxp,lpc3220-mlc"; reg = <0x200A8000 0x11000>; interrupts = <11 0>; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index 7cc15c96ea95..4cb4925a28ab 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -61,7 +61,7 @@ file. Examples: - mac: ethernet@4A100000 { + mac: ethernet@4a100000 { compatible = "ti,cpsw"; reg = <0x4A100000 0x1000>; interrupts = <55 0x4>; @@ -91,7 +91,7 @@ Examples: }; (or) - mac: ethernet@4A100000 { + mac: ethernet@4a100000 { compatible = "ti,cpsw"; ti,hwmods = "cpgmac0"; cpdma_channels = <8>; diff --git a/Documentation/devicetree/bindings/net/davinci-mdio.txt b/Documentation/devicetree/bindings/net/davinci-mdio.txt index 621156ca4ffd..e6527de80f10 100644 --- a/Documentation/devicetree/bindings/net/davinci-mdio.txt +++ b/Documentation/devicetree/bindings/net/davinci-mdio.txt @@ -21,7 +21,7 @@ file. Examples: - mdio: davinci_mdio@4A101000 { + mdio: davinci_mdio@4a101000 { compatible = "ti,davinci_mdio"; reg = <0x4A101000 0x1000>; bus_freq = <1000000>; @@ -29,7 +29,7 @@ Examples: (or) - mdio: davinci_mdio@4A101000 { + mdio: davinci_mdio@4a101000 { compatible = "ti,davinci_mdio"; ti,hwmods = "davinci_mdio"; bus_freq = <1000000>; diff --git a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt index db74f0dc290c..594982c6b9f9 100644 --- a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt +++ b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt @@ -136,7 +136,7 @@ Clock Properties: Example: - ptp_clock@24E00 { + ptp_clock@24e00 { compatible = "fsl,etsec-ptp"; reg = <0x24E00 0xB0>; interrupts = <12 0x8 13 0x8>; diff --git a/Documentation/devicetree/bindings/phy/ti-phy.txt b/Documentation/devicetree/bindings/phy/ti-phy.txt index cd13e6157088..57dfda8a7a1d 100644 --- a/Documentation/devicetree/bindings/phy/ti-phy.txt +++ b/Documentation/devicetree/bindings/phy/ti-phy.txt @@ -120,7 +120,7 @@ usb3phy@4a084400 { "refclk"; }; -sata_phy: phy@4A096000 { +sata_phy: phy@4a096000 { compatible = "ti,phy-pipe3-sata"; reg = <0x4A096000 0x80>, /* phy_rx */ <0x4A096400 0x64>, /* phy_tx */ diff --git a/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt b/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt index 2c11866221c2..c591b9cb5ba0 100644 --- a/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt +++ b/Documentation/devicetree/bindings/pinctrl/abilis,tb10x-iomux.txt @@ -49,7 +49,7 @@ explained in Documentation/devicetree/bindings/gpio/gpio.txt. Example ------- -iomux: iomux@FF10601c { +iomux: iomux@ff10601c { compatible = "abilis,tb10x-iomux"; reg = <0xFF10601c 0x4>; pctl_gpio_a: pctl-gpio-a { @@ -59,7 +59,7 @@ iomux: iomux@FF10601c { abilis,function = "uart0"; }; }; -uart@FF100000 { +uart@ff100000 { compatible = "snps,dw-apb-uart"; reg = <0xFF100000 0x100>; clock-frequency = <166666666>; @@ -69,7 +69,7 @@ uart@FF100000 { pinctrl-names = "default"; pinctrl-0 = <&pctl_uart0>; }; -gpioa: gpio@FF140000 { +gpioa: gpio@ff140000 { compatible = "abilis,tb10x-gpio"; reg = <0xFF140000 0x1000>; gpio-controller; diff --git a/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt index 0326154c7925..a72dc3178179 100644 --- a/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/img,pistachio-pinctrl.txt @@ -152,7 +152,7 @@ resetn Example: -------- -pinctrl@18101C00 { +pinctrl@18101c00 { compatible = "img,pistachio-system-pinctrl"; reg = <0x18101C00 0x400>; diff --git a/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt index 8e5216bcd748..4658f105fa09 100644 --- a/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt @@ -163,7 +163,7 @@ Valid values for xRX300 pin names: io42-io43,io48-io61. Example: - gpio: pinmux@E100B10 { + gpio: pinmux@e100b10 { compatible = "lantiq,danube-pinctrl"; pinctrl-names = "default"; pinctrl-0 = <&state_default>; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt index 231fa1db7c5e..afa8a18ea11a 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt @@ -81,7 +81,7 @@ Examples: reg = <0 0x10005000 0 0x1000>; }; - syscfg_pctl_b: syscfg_pctl_b@1020C020 { + syscfg_pctl_b: syscfg_pctl_b@1020c020 { compatible = "mediatek,mt8135-pctl-b-syscfg", "syscon"; reg = <0 0x1020C020 0 0x1000>; }; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt b/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt index 641bc13983e1..ed6a414b2e10 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/interlaken-lac.txt @@ -223,37 +223,37 @@ lac-portals { reg = <0x9000 0x1000>; }; - lportal10: lac-portal@A000 { + lportal10: lac-portal@a000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x20E>; reg = <0xA000 0x1000>; }; - lportal11: lac-portal@B000 { + lportal11: lac-portal@b000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x20F>; reg = <0xB000 0x1000>; }; - lportal12: lac-portal@C000 { + lportal12: lac-portal@c000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x210>; reg = <0xC000 0x1000>; }; - lportal13: lac-portal@D000 { + lportal13: lac-portal@d000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x211>; reg = <0xD000 0x1000>; }; - lportal14: lac-portal@E000 { + lportal14: lac-portal@e000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x212>; reg = <0xE000 0x1000>; }; - lportal15: lac-portal@F000 { + lportal15: lac-portal@f000 { compatible = "fsl,interlaken-lac-portal-v1.0"; fsl,liodn = <0x213>; reg = <0xF000 0x1000>; diff --git a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt index 3944ee3e731e..5ddb8500a929 100644 --- a/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt +++ b/Documentation/devicetree/bindings/regulator/st,stm32-vrefbuf.txt @@ -10,7 +10,7 @@ Required properties: - clocks: Must contain an entry for peripheral clock. Example: - vrefbuf: regulator@58003C00 { + vrefbuf: regulator@58003c00 { compatible = "st,stm32-vrefbuf"; reg = <0x58003C00 0x8>; clocks = <&rcc VREF_CK>; diff --git a/Documentation/devicetree/bindings/serial/lantiq_asc.txt b/Documentation/devicetree/bindings/serial/lantiq_asc.txt index 5b78591aaa46..3acbd309ab9d 100644 --- a/Documentation/devicetree/bindings/serial/lantiq_asc.txt +++ b/Documentation/devicetree/bindings/serial/lantiq_asc.txt @@ -8,7 +8,7 @@ Required properties: Example: -asc1: serial@E100C00 { +asc1: serial@e100c00 { compatible = "lantiq,asc"; reg = <0xE100C00 0x400>; interrupt-parent = <&icu0>; diff --git a/Documentation/devicetree/bindings/sound/img,i2s-out.txt b/Documentation/devicetree/bindings/sound/img,i2s-out.txt index 0159415b3338..6b0ee9b7e11b 100644 --- a/Documentation/devicetree/bindings/sound/img,i2s-out.txt +++ b/Documentation/devicetree/bindings/sound/img,i2s-out.txt @@ -35,7 +35,7 @@ Optional Properties: Example: -i2s_out: i2s-out@18100A00 { +i2s_out: i2s-out@18100a00 { compatible = "img,i2s-out"; reg = <0x18100A00 0x200>; interrupts = ; diff --git a/Documentation/devicetree/bindings/sound/img,parallel-out.txt b/Documentation/devicetree/bindings/sound/img,parallel-out.txt index a3015d2a06e0..37a3f94cc126 100644 --- a/Documentation/devicetree/bindings/sound/img,parallel-out.txt +++ b/Documentation/devicetree/bindings/sound/img,parallel-out.txt @@ -29,7 +29,7 @@ Optional Properties: Example: -parallel_out: parallel-out@18100C00 { +parallel_out: parallel-out@18100c00 { compatible = "img,parallel-out"; reg = <0x18100C00 0x100>; interrupts = ; diff --git a/Documentation/devicetree/bindings/sound/img,spdif-in.txt b/Documentation/devicetree/bindings/sound/img,spdif-in.txt index aab9a81f7e13..f7ea8c87bf34 100644 --- a/Documentation/devicetree/bindings/sound/img,spdif-in.txt +++ b/Documentation/devicetree/bindings/sound/img,spdif-in.txt @@ -29,7 +29,7 @@ Optional Properties: Example: -spdif_in: spdif-in@18100E00 { +spdif_in: spdif-in@18100e00 { compatible = "img,spdif-in"; reg = <0x18100E00 0x100>; interrupts = ; diff --git a/Documentation/devicetree/bindings/sound/img,spdif-out.txt b/Documentation/devicetree/bindings/sound/img,spdif-out.txt index 470a5191e101..413ed8b01870 100644 --- a/Documentation/devicetree/bindings/sound/img,spdif-out.txt +++ b/Documentation/devicetree/bindings/sound/img,spdif-out.txt @@ -29,7 +29,7 @@ Optional Properties: Example: -spdif_out: spdif-out@18100D00 { +spdif_out: spdif-out@18100d00 { compatible = "img,spdif-out"; reg = <0x18100D00 0x100>; interrupts = ; diff --git a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt index 9c1ee52fed5b..4d51f3f5ea98 100644 --- a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt @@ -51,7 +51,7 @@ Optional properties: Example: - sti_uni_player1: sti-uni-player@8D81000 { + sti_uni_player1: sti-uni-player@8d81000 { compatible = "st,stih407-uni-player-hdmi"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -63,7 +63,7 @@ Example: st,tdm-mode = <1>; }; - sti_uni_player2: sti-uni-player@8D82000 { + sti_uni_player2: sti-uni-player@8d82000 { compatible = "st,stih407-uni-player-pcm-out"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -74,7 +74,7 @@ Example: dma-names = "tx"; }; - sti_uni_player3: sti-uni-player@8D85000 { + sti_uni_player3: sti-uni-player@8d85000 { compatible = "st,stih407-uni-player-spdif"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -85,7 +85,7 @@ Example: dma-names = "tx"; }; - sti_uni_reader1: sti-uni-reader@8D84000 { + sti_uni_reader1: sti-uni-reader@8d84000 { compatible = "st,stih407-uni-reader-hdmi"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; diff --git a/Documentation/devicetree/bindings/spi/spi-davinci.txt b/Documentation/devicetree/bindings/spi/spi-davinci.txt index 1925277bfc1e..9f5b4c7c0c08 100644 --- a/Documentation/devicetree/bindings/spi/spi-davinci.txt +++ b/Documentation/devicetree/bindings/spi/spi-davinci.txt @@ -68,7 +68,7 @@ SPI_SOMI/SIMO+-----------------+ +----------- Example of a NOR flash slave device (n25q032) connected to DaVinci SPI controller device over the SPI bus. -spi0:spi@20BF0000 { +spi0:spi@20bf0000 { #address-cells = <1>; #size-cells = <0>; compatible = "ti,dm6446-spi"; diff --git a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt index 6069b95a883d..ce3230c8e28d 100644 --- a/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt +++ b/Documentation/devicetree/bindings/spi/spi-lantiq-ssc.txt @@ -16,7 +16,7 @@ Optional properties: Example: -spi: spi@E100800 { +spi: spi@e100800 { compatible = "lantiq,xrx200-spi", "lantiq,xrx100-spi"; reg = <0xE100800 0x100>; interrupt-parent = <&icu0>; diff --git a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt index 9b4c7b017495..1b596fd38dc4 100644 --- a/Documentation/devicetree/bindings/thermal/exynos-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/exynos-thermal.txt @@ -70,7 +70,7 @@ Following properties are mandatory (depending on SoC): Example 1): - tmu@100C0000 { + tmu@100c0000 { compatible = "samsung,exynos4412-tmu"; interrupt-parent = <&combiner>; reg = <0x100C0000 0x100>; diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt index 44d7cb2cb2c0..1719d47a5e2f 100644 --- a/Documentation/devicetree/bindings/thermal/thermal.txt +++ b/Documentation/devicetree/bindings/thermal/thermal.txt @@ -252,7 +252,7 @@ ocp { /* * A simple IC with a single bandgap temperature sensor. */ - bandgap0: bandgap@0000ED00 { + bandgap0: bandgap@0000ed00 { ... #thermal-sensor-cells = <0>; }; @@ -330,7 +330,7 @@ ocp { /* * A simple IC with several bandgap temperature sensors. */ - bandgap0: bandgap@0000ED00 { + bandgap0: bandgap@0000ed00 { ... #thermal-sensor-cells = <1>; }; @@ -458,7 +458,7 @@ ocp { /* * A simple IC with a single bandgap temperature sensor. */ - bandgap0: bandgap@0000ED00 { + bandgap0: bandgap@0000ed00 { ... #thermal-sensor-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt b/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt index 167d5dab9f64..8f78640ad64c 100644 --- a/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt +++ b/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.txt @@ -51,7 +51,7 @@ Example 2: In this example, the timer interrupts are connected to two separate interrupt controllers. Hence, an interrupt-map is created to map the interrupts to the respective interrupt controllers. - mct@101C0000 { + mct@101c0000 { compatible = "samsung,exynos4210-mct"; reg = <0x101C0000 0x800>; interrupt-parent = <&mct_map>; diff --git a/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt b/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt index 556d06c17c92..4b76bec62af9 100644 --- a/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/pnx4008-wdt.txt @@ -10,7 +10,7 @@ Optional properties: Example: - watchdog@4003C000 { + watchdog@4003c000 { compatible = "nxp,pnx4008-wdt"; reg = <0x4003C000 0x1000>; timeout-sec = <10>; diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt index 1f6e101e299a..46dcb48e75b4 100644 --- a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt @@ -25,7 +25,7 @@ Optional properties: Example: -watchdog@101D0000 { +watchdog@101d0000 { compatible = "samsung,exynos5250-wdt"; reg = <0x101D0000 0x100>; interrupts = <0 42 0>; -- cgit From 0ca30e870ed28da15c871374af109055cd00744f Mon Sep 17 00:00:00 2001 From: Sean Wang Date: Wed, 20 Dec 2017 17:47:05 +0800 Subject: dt-bindings: net: mediatek: add condition to property mediatek, pctl The property "mediatek,pctl" is only required for SoCs such as MT2701 and MT7623, so adding a few words for stating the condition. Signed-off-by: Sean Wang Reviewed-by: Rob Herring Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/mediatek-net.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/mediatek-net.txt b/Documentation/devicetree/bindings/net/mediatek-net.txt index 214eaa9a6683..53c13ee384a4 100644 --- a/Documentation/devicetree/bindings/net/mediatek-net.txt +++ b/Documentation/devicetree/bindings/net/mediatek-net.txt @@ -28,7 +28,7 @@ Required properties: - mediatek,sgmiisys: phandle to the syscon node that handles the SGMII setup which is required for those SoCs equipped with SGMII such as MT7622 SoC. - mediatek,pctl: phandle to the syscon node that handles the ports slew rate - and driver current + and driver current: only for MT2701 and MT7623 SoC Optional properties: - interrupt-parent: Should be the phandle for the interrupt controller -- cgit From d7e9ab3c6d76c6480d6b40525375995c0d8526fc Mon Sep 17 00:00:00 2001 From: Tuomas Tynkkynen Date: Sat, 23 Dec 2017 02:34:12 +0200 Subject: mmc: Don't reference Linux-specific OF_GPIO_ACTIVE_LOW flag in DT binding OF_GPIO_ACTIVE_LOW is a Linux implementation detail. The binding document should be referring to GPIO_ACTIVE_LOW found in include/dt-bindings/gpio/gpio.h. Signed-off-by: Tuomas Tynkkynen Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/mmc/mmc.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index fb11ae8b3b72..467cd7b147ce 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -67,10 +67,10 @@ logic applies to the "wp-inverted" property. CD and WP lines can be implemented on the hardware in one of two ways: as GPIOs, specified in cd-gpios and wp-gpios properties, or as dedicated pins. Polarity of dedicated pins can be specified, using *-inverted properties. GPIO polarity can -also be specified using the OF_GPIO_ACTIVE_LOW flag. This creates an ambiguity +also be specified using the GPIO_ACTIVE_LOW flag. This creates an ambiguity in the latter case. We choose to use the XOR logic for GPIO CD and WP lines. This means, the two properties are "superimposed," for example leaving the -OF_GPIO_ACTIVE_LOW flag clear and specifying the respective *-inverted +GPIO_ACTIVE_LOW flag clear and specifying the respective *-inverted property property results in a double-inversion and actually means the "normal" line polarity is in effect. -- cgit From 62ce85a85e27889dd59a2facf7cac12e3dd7b848 Mon Sep 17 00:00:00 2001 From: Fabio Estevam Date: Tue, 26 Dec 2017 18:49:55 -0200 Subject: dt-bindings: imx6q-pcie: Add required property for i.MX6SX i.MX6SX needs a PCI 'power-domains' entry, so add it to its required properties section. Signed-off-by: Fabio Estevam Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index 149d8f7f86b0..cb33421184a0 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -41,6 +41,7 @@ Optional properties: Additional required properties for imx6sx-pcie: - clock names: Must include the following additional entries: - "pcie_inbound_axi" +- power-domains: Must be set to a phandle pointing to the PCIE_PHY power domain Additional required properties for imx7d-pcie: - power-domains: Must be set to a phandle pointing to PCIE_PHY power domain -- cgit From 04f629f730fcd30c811777d186b15c38737eaa3c Mon Sep 17 00:00:00 2001 From: Richard Leitner Date: Fri, 22 Dec 2017 11:08:09 +0100 Subject: phylib: rename reset-(post-)delay-us to reset-(de)assert-us As suggested by Rob Herring [1] rename the previously introduced reset-{,post-}delay-us bindings to the clearer reset-{,de}assert-us [1] https://patchwork.kernel.org/patch/10104905/ Signed-off-by: Richard Leitner Reviewed-by: Rob Herring Signed-off-by: David S. Miller --- Documentation/devicetree/bindings/net/phy.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 72860ce7f610..d2169a56f5e3 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -55,10 +55,10 @@ Optional Properties: - reset-gpios: The GPIO phandle and specifier for the PHY reset signal. -- reset-delay-us: Delay after the reset was asserted in microseconds. +- reset-assert-us: Delay after the reset was asserted in microseconds. If this property is missing the delay will be skipped. -- reset-post-delay-us: Delay after the reset was deasserted in microseconds. +- reset-deassert-us: Delay after the reset was deasserted in microseconds. If this property is missing the delay will be skipped. Example: @@ -70,6 +70,6 @@ ethernet-phy@0 { reg = <0>; reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; - reset-delay-us = <1000>; - reset-post-delay-us = <2000>; + reset-assert-us = <1000>; + reset-deassert-us = <2000>; }; -- cgit From f8aaf487712be2529f0e757643e04edf0aa9d5cb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Dec 2017 09:35:52 -0500 Subject: media: dvb uAPI docs: document demux mmap/munmap syscalls With the new dmx mmap interface, those two syscalls are now handled by the subsystem. Document them. This patch is based on the V4L2 text for those ioctls. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/dvb/dmx-mmap.rst | 116 ++++++++++++++++++++++++++++ Documentation/media/uapi/dvb/dmx-munmap.rst | 54 +++++++++++++ Documentation/media/uapi/dvb/dmx_fcalls.rst | 2 + 3 files changed, 172 insertions(+) create mode 100644 Documentation/media/uapi/dvb/dmx-mmap.rst create mode 100644 Documentation/media/uapi/dvb/dmx-munmap.rst (limited to 'Documentation') diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst b/Documentation/media/uapi/dvb/dmx-mmap.rst new file mode 100644 index 000000000000..15d107348b9f --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-mmap.rst @@ -0,0 +1,116 @@ +.. _dmx-mmap: + +***************** +Digital TV mmap() +***************** + +Name +==== + +dmx-mmap - Map device memory into application address space + +.. warning:: this API is still experimental + +Synopsis +======== + +.. code-block:: c + + #include + #include + + +.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + :name: dmx-mmap + +Arguments +========= + +``start`` + Map the buffer to this address in the application's address space. + When the ``MAP_FIXED`` flag is specified, ``start`` must be a + multiple of the pagesize and mmap will fail when the specified + address cannot be used. Use of this option is discouraged; + applications should just specify a ``NULL`` pointer here. + +``length`` + Length of the memory area to map. This must be a multiple of the + DVB packet length (188, on most drivers). + +``prot`` + The ``prot`` argument describes the desired memory protection. + Regardless of the device type and the direction of data exchange it + should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read + and write access to image buffers. Drivers should support at least + this combination of flags. + +``flags`` + The ``flags`` parameter specifies the type of the mapped object, + mapping options and whether modifications made to the mapped copy of + the page are private to the process or are to be shared with other + references. + + ``MAP_FIXED`` requests that the driver selects no other address than + the one specified. If the specified address cannot be used, + :ref:`mmap() ` will fail. If ``MAP_FIXED`` is specified, + ``start`` must be a multiple of the pagesize. Use of this option is + discouraged. + + One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. + ``MAP_SHARED`` allows applications to share the mapped memory with + other (e. g. child-) processes. + + .. note:: + + The Linux Digital TV applications should not set the + ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` + flags. + +``fd`` + File descriptor returned by :ref:`open() `. + +``offset`` + Offset of the buffer in device memory, as returned by + :ref:`DMX_QUERYBUF` ioctl. + + +Description +=========== + +The :ref:`mmap() ` function asks to map ``length`` bytes starting at +``offset`` in the memory of the device specified by ``fd`` into the +application address space, preferably at address ``start``. This latter +address is a hint only, and is usually specified as 0. + +Suitable length and offset parameters are queried with the +:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the +:ref:`DMX_REQBUFS` ioctl before they can be queried. + +To unmap buffers the :ref:`munmap() ` function is used. + + +Return Value +============ + +On success :ref:`mmap() ` returns a pointer to the mapped buffer. On +error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set +appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid file descriptor. + +EACCES + ``fd`` is not open for reading and writing. + +EINVAL + The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. + they are too large, or not aligned on a ``PAGESIZE`` boundary.) + + The ``flags`` or ``prot`` value is not supported. + + No buffers have been allocated with the + :ref:`DMX_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. diff --git a/Documentation/media/uapi/dvb/dmx-munmap.rst b/Documentation/media/uapi/dvb/dmx-munmap.rst new file mode 100644 index 000000000000..d77218732bb6 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-munmap.rst @@ -0,0 +1,54 @@ +.. _dmx-munmap: + +************ +DVB munmap() +************ + +Name +==== + +dmx-munmap - Unmap device memory + +.. warning:: This API is still experimental. + + +Synopsis +======== + +.. code-block:: c + + #include + #include + + +.. c:function:: int munmap( void *start, size_t length ) + :name: dmx-munmap + +Arguments +========= + +``start`` + Address of the mapped buffer as returned by the + :ref:`mmap() ` function. + +``length`` + Length of the mapped buffer. This must be the same value as given to + :ref:`mmap() `. + + +Description +=========== + +Unmaps a previously with the :ref:`mmap() ` function mapped +buffer and frees it, if possible. + + +Return Value +============ + +On success :ref:`munmap() ` returns 0, on failure -1 and the +``errno`` variable is set appropriately: + +EINVAL + The ``start`` or ``length`` is incorrect, or no buffers have been + mapped yet. diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst index a17289143220..db19df6dbf70 100644 --- a/Documentation/media/uapi/dvb/dmx_fcalls.rst +++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst @@ -13,6 +13,8 @@ Demux Function Calls dmx-fclose dmx-fread dmx-fwrite + dmx-mmap + dmx-munmap dmx-start dmx-stop dmx-set-filter -- cgit From a1f18fdc72a4dc7315f7bd14d6cb30dde42ce6eb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Dec 2017 10:42:26 -0500 Subject: media: dvb uAPI docs: document mmap-related ioctls 5 new ioctls were added to the DVB demux API, in order to handle memory maped I/O. Add documentation for them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/dvb/dmx-expbuf.rst | 90 +++++++++++++++++++++++++++ Documentation/media/uapi/dvb/dmx-qbuf.rst | 85 +++++++++++++++++++++++++ Documentation/media/uapi/dvb/dmx-querybuf.rst | 65 +++++++++++++++++++ Documentation/media/uapi/dvb/dmx-reqbufs.rst | 76 ++++++++++++++++++++++ Documentation/media/uapi/dvb/dmx_fcalls.rst | 4 ++ 5 files changed, 320 insertions(+) create mode 100644 Documentation/media/uapi/dvb/dmx-expbuf.rst create mode 100644 Documentation/media/uapi/dvb/dmx-qbuf.rst create mode 100644 Documentation/media/uapi/dvb/dmx-querybuf.rst create mode 100644 Documentation/media/uapi/dvb/dmx-reqbufs.rst (limited to 'Documentation') diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst new file mode 100644 index 000000000000..51df34c6fb59 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst @@ -0,0 +1,90 @@ +.. _DMX_EXPBUF: + +**************** +ioctl DMX_EXPBUF +**************** + +Name +==== + +DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) + :name: DMX_EXPBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``argp`` + Pointer to struct :c:type:`dmx_exportbuffer`. + + +Description +=========== + +This ioctl is an extension to the memory mapping I/O method. +It can be used to export a buffer as a DMABUF file at any time after +buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. + +The ``reserved`` array must be zeroed before calling it. + +To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. +Applications must set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dmx_requestbuffers` ``count``) minus one. +Additional flags may be posted in the ``flags`` field. Refer to a manual +for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported. +All other fields must be set to zero. In the +case of multi-planar API, every plane is exported separately using +multiple :ref:`DMX_EXPBUF` calls. + +After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a +driver, on success. This is a DMABUF file descriptor. The application may +pass it to other DMABUF-aware devices. It is recommended to close a DMABUF +file when it is no longer used to allow the associated memory to be reclaimed. + + +Examples +======== + + +.. code-block:: c + + int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) + { + struct dmx_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { + perror("DMX_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; + } + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + A queue is not in MMAP mode or DMABUF exporting is not supported or + ``flags`` or ``index`` fields are invalid. diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst new file mode 100644 index 000000000000..b20b8153d48d --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst @@ -0,0 +1,85 @@ +.. _DMX_QBUF: + +************************* +ioctl DMX_QBUF, DMX_DQBUF +************************* + +Name +==== + +DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) + :name: DMX_QBUF + +.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) + :name: DMX_DQBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``argp`` + Pointer to struct :c:type:`dmx_buffer`. + + +Description +=========== + +Applications call the ``DMX_QBUF`` ioctl to enqueue an empty +(capturing) or filled (output) buffer in the driver's incoming queue. +The semantics depend on the selected I/O method. + +To enqueue a buffer applications set the ``index`` field. Valid index +numbers range from zero to the number of buffers allocated with +:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus +one. The contents of the struct :c:type:`dmx_buffer` returned +by a :ref:`DMX_QUERYBUF` ioctl will do as well. + +The and ``reserved`` field must be set to 0. + +When ``DMX_QBUF`` is called with a pointer to this structure, it locks the +memory pages of the buffer in physical memory, so they cannot be swapped +out to disk. Buffers remain locked until dequeued, until the +the device is closed. + +Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled +(capturing) buffer from the driver's outgoing queue. They just set the ``reserved`` field array to zero. When ``DMX_DQBUF`` is called with a +pointer to this structure, the driver fills the remaining fields or +returns an error code. + +By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing +queue. When the ``O_NONBLOCK`` flag was given to the +:ref:`open() ` function, ``DMX_DQBUF`` returns +immediately with an ``EAGAIN`` error code when no buffer is available. + +The struct :c:type:`dmx_buffer` structure is specified in +:ref:`buffer`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EAGAIN + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no + buffer was in the outgoing queue. + +EINVAL + The ``index`` is out of bounds, or no buffers have been allocated yet. + +EIO + ``DMX_DQBUF`` failed due to an internal error. Can also indicate + temporary problems like signal loss or CRC errors. diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst b/Documentation/media/uapi/dvb/dmx-querybuf.rst new file mode 100644 index 000000000000..46a50f191b10 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-querybuf.rst @@ -0,0 +1,65 @@ +.. _DMX_QUERYBUF: + +****************** +ioctl DMX_QUERYBUF +****************** + +Name +==== + +DMX_QUERYBUF - Query the status of a buffer + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp ) + :name: DMX_QUERYBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``argp`` + Pointer to struct :c:type:`dvb_buffer`. + + +Description +=========== + +This ioctl is part of the mmap streaming I/O method. It can +be used to query the status of a buffer at any time after buffers have +been allocated with the :ref:`DMX_REQBUFS` ioctl. + +The ``reserved`` array must be zeroed before calling it. + +Applications set the ``index`` field. Valid index numbers range from zero +to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dvb_requestbuffers` ``count``) minus one. + +After calling :ref:`DMX_QUERYBUF` with a pointer to this structure, +drivers return an error code or fill the rest of the structure. + +On success, the ``offset`` will contain the offset of the buffer from the +start of the device memory, the ``length`` field its size, and the +``bytesused`` the number of bytes occupied by data in the buffer (payload). + +Return Value +============ + +On success 0 is returned, the ``offset`` will contain the offset of the +buffer from the start of the device memory, the ``length`` field its size, +and the ``bytesused`` the number of bytes occupied by data in the buffer +(payload). + +On error it returns -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + The ``index`` is out of bounds. diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst b/Documentation/media/uapi/dvb/dmx-reqbufs.rst new file mode 100644 index 000000000000..0749623d9d83 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-reqbufs.rst @@ -0,0 +1,76 @@ +.. _DMX_REQBUFS: + +***************** +ioctl DMX_REQBUFS +***************** + +Name +==== + +DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp ) + :name: DMX_REQBUFS + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``argp`` + Pointer to struct :c:type:`dmx_requestbuffers`. + +Description +=========== + +This ioctl is used to initiate a memory mapped or DMABUF based demux I/O. + +Memory mapped buffers are located in device memory and must be allocated +with this ioctl before they can be mapped into the application's address +space. User buffers are allocated by applications themselves, and this +ioctl is merely used to switch the driver into user pointer I/O mode and +to setup some internal structures. Similarly, DMABUF buffers are +allocated by applications through a device driver, and this ioctl only +configures the driver into DMABUF I/O mode without performing any direct +allocation. + +The ``reserved`` array must be zeroed before calling it. + +To allocate device buffers applications initialize all fields of the +struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field +to the desired number of buffers, and ``size`` to the size of each +buffer. + +When the ioctl is called with a pointer to this structure, the driver will +attempt to allocate the requested number of buffers and it stores the actual +number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger +number is also possible when the driver requires more buffers to +function correctly. The actual allocated buffer size can is returned +at ``size``, and can be smaller than what's requested. + +When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP`` +error code. + +Applications can call :ref:`DMX_REQBUFS` again to change the number of +buffers, however this cannot succeed when any buffers are still mapped. +A ``count`` value of zero frees all buffers, after aborting or finishing +any DMA in progress. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EOPNOTSUPP + The the requested I/O method is not supported. diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst index db19df6dbf70..4c391cf2554f 100644 --- a/Documentation/media/uapi/dvb/dmx_fcalls.rst +++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst @@ -24,3 +24,7 @@ Demux Function Calls dmx-get-pes-pids dmx-add-pid dmx-remove-pid + dmx-reqbufs + dmx-querybuf + dmx-expbuf + dmx-qbuf -- cgit From a114a585be4f3173fe454921a0918fb7e71633b0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Dec 2017 10:57:13 -0500 Subject: media: dvb-core: get rid of mmap reserved field The "reserved" field was a way, used at V4L2 API, to add new data to existing structs without breaking userspace. However, there are now clever ways of doing that, without needing to add an uneeded overhead. So, get rid of them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/dvb/dmx-expbuf.rst | 2 -- Documentation/media/uapi/dvb/dmx-qbuf.rst | 2 -- Documentation/media/uapi/dvb/dmx-querybuf.rst | 2 -- Documentation/media/uapi/dvb/dmx-reqbufs.rst | 2 -- 4 files changed, 8 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst index 51df34c6fb59..2d96cfe891df 100644 --- a/Documentation/media/uapi/dvb/dmx-expbuf.rst +++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst @@ -36,8 +36,6 @@ This ioctl is an extension to the memory mapping I/O method. It can be used to export a buffer as a DMABUF file at any time after buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. -The ``reserved`` array must be zeroed before calling it. - To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. Applications must set the ``index`` field. Valid index numbers range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst index b20b8153d48d..b48c4931658e 100644 --- a/Documentation/media/uapi/dvb/dmx-qbuf.rst +++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst @@ -45,8 +45,6 @@ numbers range from zero to the number of buffers allocated with one. The contents of the struct :c:type:`dmx_buffer` returned by a :ref:`DMX_QUERYBUF` ioctl will do as well. -The and ``reserved`` field must be set to 0. - When ``DMX_QBUF`` is called with a pointer to this structure, it locks the memory pages of the buffer in physical memory, so they cannot be swapped out to disk. Buffers remain locked until dequeued, until the diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst b/Documentation/media/uapi/dvb/dmx-querybuf.rst index 46a50f191b10..89481e24bb86 100644 --- a/Documentation/media/uapi/dvb/dmx-querybuf.rst +++ b/Documentation/media/uapi/dvb/dmx-querybuf.rst @@ -36,8 +36,6 @@ This ioctl is part of the mmap streaming I/O method. It can be used to query the status of a buffer at any time after buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. -The ``reserved`` array must be zeroed before calling it. - Applications set the ``index`` field. Valid index numbers range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` (struct :c:type:`dvb_requestbuffers` ``count``) minus one. diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst b/Documentation/media/uapi/dvb/dmx-reqbufs.rst index 0749623d9d83..14b80d60bf35 100644 --- a/Documentation/media/uapi/dvb/dmx-reqbufs.rst +++ b/Documentation/media/uapi/dvb/dmx-reqbufs.rst @@ -42,8 +42,6 @@ allocated by applications through a device driver, and this ioctl only configures the driver into DMABUF I/O mode without performing any direct allocation. -The ``reserved`` array must be zeroed before calling it. - To allocate device buffers applications initialize all fields of the struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field to the desired number of buffers, and ``size`` to the size of each -- cgit From c5a9ef30af363922a237fc4252522ef24d1b073e Mon Sep 17 00:00:00 2001 From: Kunihiko Hayashi Date: Thu, 28 Dec 2017 15:58:11 +0900 Subject: dt-bindings: net: add DT bindings for Socionext UniPhier AVE DT bindings for the AVE ethernet controller found on Socionext's UniPhier platforms. Signed-off-by: Kunihiko Hayashi Signed-off-by: Jassi Brar Acked-by: Rob Herring Reviewed-by: Florian Fainelli Signed-off-by: David S. Miller --- .../bindings/net/socionext,uniphier-ave4.txt | 48 ++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt new file mode 100644 index 000000000000..270ea4efff13 --- /dev/null +++ b/Documentation/devicetree/bindings/net/socionext,uniphier-ave4.txt @@ -0,0 +1,48 @@ +* Socionext AVE ethernet controller + +This describes the devicetree bindings for AVE ethernet controller +implemented on Socionext UniPhier SoCs. + +Required properties: + - compatible: Should be + - "socionext,uniphier-pro4-ave4" : for Pro4 SoC + - "socionext,uniphier-pxs2-ave4" : for PXs2 SoC + - "socionext,uniphier-ld11-ave4" : for LD11 SoC + - "socionext,uniphier-ld20-ave4" : for LD20 SoC + - reg: Address where registers are mapped and size of region. + - interrupts: Should contain the MAC interrupt. + - phy-mode: See ethernet.txt in the same directory. Allow to choose + "rgmii", "rmii", or "mii" according to the PHY. + - phy-handle: Should point to the external phy device. + See ethernet.txt file in the same directory. + - clocks: A phandle to the clock for the MAC. + +Optional properties: + - resets: A phandle to the reset control for the MAC. + - local-mac-address: See ethernet.txt in the same directory. + +Required subnode: + - mdio: A container for child nodes representing phy nodes. + See phy.txt in the same directory. + +Example: + + ether: ethernet@65000000 { + compatible = "socionext,uniphier-ld20-ave4"; + reg = <0x65000000 0x8500>; + interrupts = <0 66 4>; + phy-mode = "rgmii"; + phy-handle = <ðphy>; + clocks = <&sys_clk 6>; + resets = <&sys_rst 6>; + local-mac-address = [00 00 00 00 00 00]; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethphy: ethphy@1 { + reg = <1>; + }; + }; + }; -- cgit From fada1935590f66dc6784981e0d557ca09013c847 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 28 Dec 2017 13:03:51 -0500 Subject: media: move dvb kAPI headers to include/media Except for DVB, all media kAPI headers are at include/media. Move the headers to it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/dtv-ca.rst | 2 +- Documentation/media/kapi/dtv-common.rst | 6 +++--- Documentation/media/kapi/dtv-demux.rst | 8 ++++---- Documentation/media/kapi/dtv-frontend.rst | 8 ++++---- Documentation/media/kapi/dtv-net.rst | 2 +- 5 files changed, 13 insertions(+), 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/kapi/dtv-ca.rst b/Documentation/media/kapi/dtv-ca.rst index a4dd700189b0..fded096b937c 100644 --- a/Documentation/media/kapi/dtv-ca.rst +++ b/Documentation/media/kapi/dtv-ca.rst @@ -1,4 +1,4 @@ Digital TV Conditional Access kABI ---------------------------------- -.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h +.. kernel-doc:: include/media/dvb_ca_en50221.h diff --git a/Documentation/media/kapi/dtv-common.rst b/Documentation/media/kapi/dtv-common.rst index 40cf1033b5e1..c47843b6c81d 100644 --- a/Documentation/media/kapi/dtv-common.rst +++ b/Documentation/media/kapi/dtv-common.rst @@ -7,7 +7,7 @@ Math functions Provide some commonly-used math functions, usually required in order to estimate signal strength and signal to noise measurements in dB. -.. kernel-doc:: drivers/media/dvb-core/dvb_math.h +.. kernel-doc:: include/media/dvb_math.h DVB devices @@ -15,7 +15,7 @@ DVB devices Those functions are responsible for handling the DVB device nodes. -.. kernel-doc:: drivers/media/dvb-core/dvbdev.h +.. kernel-doc:: include/media/dvbdev.h Digital TV Ring buffer ~~~~~~~~~~~~~~~~~~~~~~ @@ -52,4 +52,4 @@ copy it from/to userspace. Resetting the buffer counts as a read and write operation. Two or more writers must be locked against each other. -.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h +.. kernel-doc:: include/media/dvb_ringbuffer.h diff --git a/Documentation/media/kapi/dtv-demux.rst b/Documentation/media/kapi/dtv-demux.rst index 7aa865a2b43f..24857133e4e8 100644 --- a/Documentation/media/kapi/dtv-demux.rst +++ b/Documentation/media/kapi/dtv-demux.rst @@ -8,7 +8,7 @@ The Kernel Digital TV Demux kABI defines a driver-internal interface for registering low-level, hardware specific driver to a hardware independent demux layer. It is only of interest for Digital TV device driver writers. The header file for this kABI is named ``demux.h`` and located in -``drivers/media/dvb-core``. +``include/media``. The demux kABI should be implemented for each demux in the system. It is used to select the TS source of a demux and to manage the demux resources. @@ -69,14 +69,14 @@ callbacks. Digital TV Demux device registration functions and data structures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/dmxdev.h +.. kernel-doc:: include/media/dmxdev.h High-level Digital TV demux interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/dvb_demux.h +.. kernel-doc:: include/media/dvb_demux.h Driver-internal low-level hardware specific driver demux interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/demux.h +.. kernel-doc:: include/media/demux.h diff --git a/Documentation/media/kapi/dtv-frontend.rst b/Documentation/media/kapi/dtv-frontend.rst index f1a2fdaab5ba..472650cdb100 100644 --- a/Documentation/media/kapi/dtv-frontend.rst +++ b/Documentation/media/kapi/dtv-frontend.rst @@ -8,7 +8,7 @@ The Digital TV Frontend kABI defines a driver-internal interface for registering low-level, hardware specific driver to a hardware independent frontend layer. It is only of interest for Digital TV device driver writers. The header file for this API is named ``dvb_frontend.h`` and located in -``drivers/media/dvb-core``. +``include/media/``. Demodulator driver ^^^^^^^^^^^^^^^^^^ @@ -17,7 +17,7 @@ The demodulator driver is responsible to talk with the decoding part of the hardware. Such driver should implement :c:type:`dvb_frontend_ops`, with tells what type of digital TV standards are supported, and points to a series of functions that allow the DVB core to command the hardware via -the code under ``drivers/media/dvb-core/dvb_frontend.c``. +the code under ``include/media/dvb_frontend.c``. A typical example of such struct in a driver ``foo`` is:: @@ -118,7 +118,7 @@ Satellite TV reception is:: .. |delta| unicode:: U+00394 -The ``drivers/media/dvb-core/dvb_frontend.c`` has a kernel thread with is +The ``include/media/dvb_frontend.c`` has a kernel thread with is responsible for tuning the device. It supports multiple algorithms to detect a channel, as defined at enum :c:func:`dvbfe_algo`. @@ -440,4 +440,4 @@ monotonic stats at the right time. Digital TV Frontend functions and types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h +.. kernel-doc:: include/media/dvb_frontend.h diff --git a/Documentation/media/kapi/dtv-net.rst b/Documentation/media/kapi/dtv-net.rst index ced991b73d69..158c7cbd7600 100644 --- a/Documentation/media/kapi/dtv-net.rst +++ b/Documentation/media/kapi/dtv-net.rst @@ -1,4 +1,4 @@ Digital TV Network kABI ----------------------- -.. kernel-doc:: drivers/media/dvb-core/dvb_net.h +.. kernel-doc:: include/media/dvb_net.h -- cgit From 5c06756cf20df5c9b974aaac3be8eb7b0e83c2db Mon Sep 17 00:00:00 2001 From: Andreas Färber Date: Tue, 5 Sep 2017 01:16:00 +0200 Subject: dt-bindings: watchdog: Add Realtek RTD1295 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a binding for the Realtek RTD1295 watchdog. Acked-by: Rob Herring Signed-off-by: Andreas Färber Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- .../devicetree/bindings/watchdog/realtek,rtd119x.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt b/Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt new file mode 100644 index 000000000000..05653054bd5b --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/realtek,rtd119x.txt @@ -0,0 +1,17 @@ +Realtek RTD1295 Watchdog +======================== + +Required properties: + +- compatible : Should be "realtek,rtd1295-watchdog" +- reg : Specifies the physical base address and size of registers +- clocks : Specifies one clock input + + +Example: + + watchdog@98007680 { + compatible = "realtek,rtd1295-watchdog"; + reg = <0x98007680 0x100>; + clocks = <&osc27M>; + }; -- cgit From be17980d9be5a5c1ece83836b24fabce648b92aa Mon Sep 17 00:00:00 2001 From: Mathieu Malaterre Date: Fri, 15 Sep 2017 21:20:40 +0200 Subject: dt: watchdog: Document compatibility with JZ4780 Suggested-by: Zubair Lutfullah Kakakhel Signed-off-by: Mathieu Malaterre Acked-by: Rob Herring Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt index 3c7a1cd13b10..cb44918f01a8 100644 --- a/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/ingenic,jz4740-wdt.txt @@ -1,7 +1,7 @@ -Ingenic Watchdog Timer (WDT) Controller for JZ4740 +Ingenic Watchdog Timer (WDT) Controller for JZ4740 & JZ4780 Required properties: -compatible: "ingenic,jz4740-watchdog" +compatible: "ingenic,jz4740-watchdog" or "ingenic,jz4780-watchdog" reg: Register address and length for watchdog registers Example: -- cgit From ef3c9cc1a57bc1aa2136337c4e670511e46191f5 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Mon, 16 Oct 2017 22:54:23 +0200 Subject: watchdog: gemini/ftwdt010: rename DT bindings The device tree bindings are in two copies and also should be consolidated into a single Faraday Technology FTWDT010 binding since we uncovered that this IP part is a standard IP from Faraday. Cc: devicetree@vger.kernel.org Acked-by: Rob Herring Signed-off-by: Linus Walleij Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- .../bindings/watchdog/cortina,gemin-watchdog.txt | 17 ----------------- .../bindings/watchdog/cortina,gemini-watchdog.txt | 17 ----------------- .../bindings/watchdog/faraday,ftwdt010.txt | 22 ++++++++++++++++++++++ 3 files changed, 22 insertions(+), 34 deletions(-) delete mode 100644 Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt delete mode 100644 Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt create mode 100644 Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt b/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt deleted file mode 100644 index bc4b865d178b..000000000000 --- a/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt +++ /dev/null @@ -1,17 +0,0 @@ -Cortina Systems Gemini SoC Watchdog - -Required properties: -- compatible : must be "cortina,gemini-watchdog" -- reg : shall contain base register location and length -- interrupts : shall contain the interrupt for the watchdog - -Optional properties: -- timeout-sec : the default watchdog timeout in seconds. - -Example: - -watchdog@41000000 { - compatible = "cortina,gemini-watchdog"; - reg = <0x41000000 0x1000>; - interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt b/Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt deleted file mode 100644 index bc4b865d178b..000000000000 --- a/Documentation/devicetree/bindings/watchdog/cortina,gemini-watchdog.txt +++ /dev/null @@ -1,17 +0,0 @@ -Cortina Systems Gemini SoC Watchdog - -Required properties: -- compatible : must be "cortina,gemini-watchdog" -- reg : shall contain base register location and length -- interrupts : shall contain the interrupt for the watchdog - -Optional properties: -- timeout-sec : the default watchdog timeout in seconds. - -Example: - -watchdog@41000000 { - compatible = "cortina,gemini-watchdog"; - reg = <0x41000000 0x1000>; - interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; -}; diff --git a/Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.txt b/Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.txt new file mode 100644 index 000000000000..9ecdb502e605 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/faraday,ftwdt010.txt @@ -0,0 +1,22 @@ +Faraday Technology FTWDT010 watchdog + +This is an IP part from Faraday Technology found in the Gemini +SoCs and others. + +Required properties: +- compatible : must be one of + "faraday,ftwdt010" + "cortina,gemini-watchdog", "faraday,ftwdt010" +- reg : shall contain base register location and length +- interrupts : shall contain the interrupt for the watchdog + +Optional properties: +- timeout-sec : the default watchdog timeout in seconds. + +Example: + +watchdog@41000000 { + compatible = "faraday,ftwdt010"; + reg = <0x41000000 0x1000>; + interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; +}; -- cgit From c94ad30add4e741ab260874e898a6448cdd4ff30 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 30 Oct 2017 16:43:19 +0100 Subject: dt-bindings: watchdog: renesas-wdt: Add support for the r8a77970 wdt Document support for the Watchdog Timer (WDT) Controller in the Renesas R-Car V3M (r8a77970) SoC. Restore sort order while at it. No driver update is needed. Signed-off-by: Geert Uytterhoeven Acked-by: Rob Herring Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- Documentation/devicetree/bindings/watchdog/renesas-wdt.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt b/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt index bf6d1ca58af7..74b2f03c1515 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt @@ -4,10 +4,11 @@ Required properties: - compatible : Should be "renesas,-wdt", and "renesas,rcar-gen3-wdt" or "renesas,rza-wdt" as fallback. Examples with soctypes are: + - "renesas,r7s72100-wdt" (RZ/A1) - "renesas,r8a7795-wdt" (R-Car H3) - "renesas,r8a7796-wdt" (R-Car M3-W) + - "renesas,r8a77970-wdt" (R-Car V3M) - "renesas,r8a77995-wdt" (R-Car D3) - - "renesas,r7s72100-wdt" (RZ/A1) When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first, followed by the generic -- cgit From c5d8d40b28ba0b619f4ef5dd77169b0f1ff77148 Mon Sep 17 00:00:00 2001 From: Eric Long Date: Mon, 6 Nov 2017 10:46:27 +0800 Subject: dt-bindings: watchdog: Add Spreadtrum watchdog documentation This patch adds the documentation for Spreadtrum watchdog driver. Signed-off-by: Eric Long Acked-by: Rob Herring Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- .../devicetree/bindings/watchdog/sprd-wdt.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 Documentation/devicetree/bindings/watchdog/sprd-wdt.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/watchdog/sprd-wdt.txt b/Documentation/devicetree/bindings/watchdog/sprd-wdt.txt new file mode 100644 index 000000000000..aeaf3e0caf47 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/sprd-wdt.txt @@ -0,0 +1,19 @@ +Spreadtrum SoCs Watchdog timer + +Required properties: +- compatible : Should be "sprd,sp9860-wdt". +- reg : Specifies base physical address and size of the registers. +- interrupts : Exactly one interrupt specifier. +- timeout-sec : Contain the default watchdog timeout in seconds. +- clock-names : Contain the input clock names. +- clocks : Phandles to input clocks. + +Example: + watchdog: watchdog@40310000 { + compatible = "sprd,sp9860-wdt"; + reg = <0 0x40310000 0 0x1000>; + interrupts = ; + timeout-sec = <12>; + clock-names = "enable", "rtc_enable"; + clocks = <&clk_aon_apb_gates1 8>, <&clk_aon_apb_rtc_gates 9>; + }; -- cgit From 3525c7c3bd2b7b0b77bdb0ab46a7c5338e188a5a Mon Sep 17 00:00:00 2001 From: Icenowy Zheng Date: Fri, 22 Dec 2017 20:22:33 +0800 Subject: dt-bindings: fix the binding of Allwinner DE2 CCU of A83T and H3 The DE2 CCU is different on A83T and H3 -- the parent of the clocks on A83T is PLL_DE but on H3 it's the DE module clock. This is not noticed when I develop the DE2 CCU driver. Fix the binding by using different compatibles for A83T and H3, adding notes for the PLL_DE usage on A83T, and change the binding example's compatible from A83T to H3 (as it specifies the DE module clock). Fixes: ed74f8a8a679 ("dt-bindings: add binding for the Allwinner DE2 CCU") Signed-off-by: Icenowy Zheng Acked-by: Rob Herring Signed-off-by: Chen-Yu Tsai --- Documentation/devicetree/bindings/clock/sun8i-de2.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/sun8i-de2.txt b/Documentation/devicetree/bindings/clock/sun8i-de2.txt index 631d27cd89d6..f2fa87c4765c 100644 --- a/Documentation/devicetree/bindings/clock/sun8i-de2.txt +++ b/Documentation/devicetree/bindings/clock/sun8i-de2.txt @@ -4,13 +4,14 @@ Allwinner Display Engine 2.0 Clock Control Binding Required properties : - compatible: must contain one of the following compatibles: - "allwinner,sun8i-a83t-de2-clk" + - "allwinner,sun8i-h3-de2-clk" - "allwinner,sun8i-v3s-de2-clk" - "allwinner,sun50i-h5-de2-clk" - reg: Must contain the registers base address and length - clocks: phandle to the clocks feeding the display engine subsystem. Three are needed: - - "mod": the display engine module clock + - "mod": the display engine module clock (on A83T it's the DE PLL) - "bus": the bus clock for the whole display engine subsystem - clock-names: Must contain the clock names described just above - resets: phandle to the reset control for the display engine subsystem. @@ -19,7 +20,7 @@ Required properties : Example: de2_clocks: clock@1000000 { - compatible = "allwinner,sun8i-a83t-de2-clk"; + compatible = "allwinner,sun8i-h3-de2-clk"; reg = <0x01000000 0x100000>; clocks = <&ccu CLK_BUS_DE>, <&ccu CLK_DE>; -- cgit From fffa5274e5ffe837d5a03989e40013e3f42742f2 Mon Sep 17 00:00:00 2001 From: Icenowy Zheng Date: Fri, 22 Dec 2017 20:22:36 +0800 Subject: dt-bindings: simplefb-sunxi: add pipelines for DE2 As we're going to add simplefb support for Allwinner SoCs with DE2, add suitable pipeline strings in the device tree binding. Acked-by: Rob Herring Signed-off-by: Icenowy Zheng Signed-off-by: Chen-Yu Tsai --- .../devicetree/bindings/display/simple-framebuffer-sunxi.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt index a9168ae6946c..d693b8dc9a62 100644 --- a/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt +++ b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt @@ -15,6 +15,10 @@ Required properties: "de_be1-lcd1" "de_be0-lcd0-hdmi" "de_be1-lcd1-hdmi" + "mixer0-lcd0" + "mixer0-lcd0-hdmi" + "mixer1-lcd1-hdmi" + "mixer1-lcd1-tve" Example: -- cgit From e62f5282554cc5263316d30683b59bb67f9df34a Mon Sep 17 00:00:00 2001 From: Yong Zhi Date: Wed, 8 Nov 2017 19:30:37 -0500 Subject: media: doc-rst: add IPU3 raw10 bayer pixel format definitions The formats added by this patch are: V4L2_PIX_FMT_IPU3_SBGGR10 V4L2_PIX_FMT_IPU3_SGBRG10 V4L2_PIX_FMT_IPU3_SGRBG10 V4L2_PIX_FMT_IPU3_SRGGB10 Signed-off-by: Hyungwoo Yang Signed-off-by: Yong Zhi Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/pixfmt-rgb.rst | 1 + .../media/uapi/v4l/pixfmt-srggb10-ipu3.rst | 335 +++++++++++++++++++++ 2 files changed, 336 insertions(+) create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst (limited to 'Documentation') diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst index 4cc27195dc79..cf2ef7df9616 100644 --- a/Documentation/media/uapi/v4l/pixfmt-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst @@ -16,6 +16,7 @@ RGB Formats pixfmt-srggb10p pixfmt-srggb10alaw8 pixfmt-srggb10dpcm8 + pixfmt-srggb10-ipu3 pixfmt-srggb12 pixfmt-srggb12p pixfmt-srggb16 diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst new file mode 100644 index 000000000000..72fbd8f96381 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst @@ -0,0 +1,335 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2_PIX_FMT_IPU3_SBGGR10: +.. _V4L2_PIX_FMT_IPU3_SGBRG10: +.. _V4L2_PIX_FMT_IPU3_SGRBG10: +.. _V4L2_PIX_FMT_IPU3_SRGGB10: + +********************************************************************************************************************************************** +V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') +********************************************************************************************************************************************** + +10-bit Bayer formats + +Description +=========== + +These four pixel formats are used by Intel IPU3 driver, they are raw +sRGB / Bayer formats with 10 bits per sample with every 25 pixels packed +to 32 bytes leaving 6 most significant bits padding in the last byte. +The format is little endian. + +In other respects this format is similar to :ref:`V4L2-PIX-FMT-SRGGB10`. +Below is an example of a small image in V4L2_PIX_FMT_IPU3_SBGGR10 format. + +**Byte Order.** +Each cell is one byte. + +.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| + +.. flat-table:: + + * - start + 0: + - B\ :sub:`0000low` + - G\ :sub:`0001low`\ (bits 7--2) + + B\ :sub:`0000high`\ (bits 1--0) + - B\ :sub:`0002low`\ (bits 7--4) + + G\ :sub:`0001high`\ (bits 3--0) + - G\ :sub:`0003low`\ (bits 7--6) + + B\ :sub:`0002high`\ (bits 5--0) + * - start + 4: + - G\ :sub:`0003high` + - B\ :sub:`0004low` + - G\ :sub:`0005low`\ (bits 7--2) + + B\ :sub:`0004high`\ (bits 1--0) + - B\ :sub:`0006low`\ (bits 7--4) + + G\ :sub:`0005high`\ (bits 3--0) + * - start + 8: + - G\ :sub:`0007low`\ (bits 7--6) + + B\ :sub:`0006high`\ (bits 5--0) + - G\ :sub:`0007high` + - B\ :sub:`0008low` + - G\ :sub:`0009low`\ (bits 7--2) + + B\ :sub:`0008high`\ (bits 1--0) + * - start + 12: + - B\ :sub:`0010low`\ (bits 7--4) + + G\ :sub:`0009high`\ (bits 3--0) + - G\ :sub:`0011low`\ (bits 7--6) + + B\ :sub:`0010high`\ (bits 5--0) + - G\ :sub:`0011high` + - B\ :sub:`0012low` + * - start + 16: + - G\ :sub:`0013low`\ (bits 7--2) + + B\ :sub:`0012high`\ (bits 1--0) + - B\ :sub:`0014low`\ (bits 7--4) + + G\ :sub:`0013high`\ (bits 3--0) + - G\ :sub:`0015low`\ (bits 7--6) + + B\ :sub:`0014high`\ (bits 5--0) + - G\ :sub:`0015high` + * - start + 20 + - B\ :sub:`0016low` + - G\ :sub:`0017low`\ (bits 7--2) + + B\ :sub:`0016high`\ (bits 1--0) + - B\ :sub:`0018low`\ (bits 7--4) + + G\ :sub:`0017high`\ (bits 3--0) + - G\ :sub:`0019low`\ (bits 7--6) + + B\ :sub:`0018high`\ (bits 5--0) + * - start + 24: + - G\ :sub:`0019high` + - B\ :sub:`0020low` + - G\ :sub:`0021low`\ (bits 7--2) + + B\ :sub:`0020high`\ (bits 1--0) + - B\ :sub:`0022low`\ (bits 7--4) + + G\ :sub:`0021high`\ (bits 3--0) + * - start + 28: + - G\ :sub:`0023low`\ (bits 7--6) + + B\ :sub:`0022high`\ (bits 5--0) + - G\ :sub:`0023high` + - B\ :sub:`0024low` + - B\ :sub:`0024high`\ (bits 1--0) + * - start + 32: + - G\ :sub:`0100low` + - R\ :sub:`0101low`\ (bits 7--2) + + G\ :sub:`0100high`\ (bits 1--0) + - G\ :sub:`0102low`\ (bits 7--4) + + R\ :sub:`0101high`\ (bits 3--0) + - R\ :sub:`0103low`\ (bits 7--6) + + G\ :sub:`0102high`\ (bits 5--0) + * - start + 36: + - R\ :sub:`0103high` + - G\ :sub:`0104low` + - R\ :sub:`0105low`\ (bits 7--2) + + G\ :sub:`0104high`\ (bits 1--0) + - G\ :sub:`0106low`\ (bits 7--4) + + R\ :sub:`0105high`\ (bits 3--0) + * - start + 40: + - R\ :sub:`0107low`\ (bits 7--6) + + G\ :sub:`0106high`\ (bits 5--0) + - R\ :sub:`0107high` + - G\ :sub:`0108low` + - R\ :sub:`0109low`\ (bits 7--2) + + G\ :sub:`0108high`\ (bits 1--0) + * - start + 44: + - G\ :sub:`0110low`\ (bits 7--4) + + R\ :sub:`0109high`\ (bits 3--0) + - R\ :sub:`0111low`\ (bits 7--6) + + G\ :sub:`0110high`\ (bits 5--0) + - R\ :sub:`0111high` + - G\ :sub:`0112low` + * - start + 48: + - R\ :sub:`0113low`\ (bits 7--2) + + G\ :sub:`0112high`\ (bits 1--0) + - G\ :sub:`0114low`\ (bits 7--4) + + R\ :sub:`0113high`\ (bits 3--0) + - R\ :sub:`0115low`\ (bits 7--6) + + G\ :sub:`0114high`\ (bits 5--0) + - R\ :sub:`0115high` + * - start + 52: + - G\ :sub:`0116low` + - R\ :sub:`0117low`\ (bits 7--2) + + G\ :sub:`0116high`\ (bits 1--0) + - G\ :sub:`0118low`\ (bits 7--4) + + R\ :sub:`0117high`\ (bits 3--0) + - R\ :sub:`0119low`\ (bits 7--6) + + G\ :sub:`0118high`\ (bits 5--0) + * - start + 56: + - R\ :sub:`0119high` + - G\ :sub:`0120low` + - R\ :sub:`0121low`\ (bits 7--2) + + G\ :sub:`0120high`\ (bits 1--0) + - G\ :sub:`0122low`\ (bits 7--4) + + R\ :sub:`0121high`\ (bits 3--0) + * - start + 60: + - R\ :sub:`0123low`\ (bits 7--6) + + G\ :sub:`0122high`\ (bits 5--0) + - R\ :sub:`0123high` + - G\ :sub:`0124low` + - G\ :sub:`0124high`\ (bits 1--0) + * - start + 64: + - B\ :sub:`0200low` + - G\ :sub:`0201low`\ (bits 7--2) + + B\ :sub:`0200high`\ (bits 1--0) + - B\ :sub:`0202low`\ (bits 7--4) + + G\ :sub:`0201high`\ (bits 3--0) + - G\ :sub:`0203low`\ (bits 7--6) + + B\ :sub:`0202high`\ (bits 5--0) + * - start + 68: + - G\ :sub:`0203high` + - B\ :sub:`0204low` + - G\ :sub:`0205low`\ (bits 7--2) + + B\ :sub:`0204high`\ (bits 1--0) + - B\ :sub:`0206low`\ (bits 7--4) + + G\ :sub:`0205high`\ (bits 3--0) + * - start + 72: + - G\ :sub:`0207low`\ (bits 7--6) + + B\ :sub:`0206high`\ (bits 5--0) + - G\ :sub:`0207high` + - B\ :sub:`0208low` + - G\ :sub:`0209low`\ (bits 7--2) + + B\ :sub:`0208high`\ (bits 1--0) + * - start + 76: + - B\ :sub:`0210low`\ (bits 7--4) + + G\ :sub:`0209high`\ (bits 3--0) + - G\ :sub:`0211low`\ (bits 7--6) + + B\ :sub:`0210high`\ (bits 5--0) + - G\ :sub:`0211high` + - B\ :sub:`0212low` + * - start + 80: + - G\ :sub:`0213low`\ (bits 7--2) + + B\ :sub:`0212high`\ (bits 1--0) + - B\ :sub:`0214low`\ (bits 7--4) + + G\ :sub:`0213high`\ (bits 3--0) + - G\ :sub:`0215low`\ (bits 7--6) + + B\ :sub:`0214high`\ (bits 5--0) + - G\ :sub:`0215high` + * - start + 84: + - B\ :sub:`0216low` + - G\ :sub:`0217low`\ (bits 7--2) + + B\ :sub:`0216high`\ (bits 1--0) + - B\ :sub:`0218low`\ (bits 7--4) + + G\ :sub:`0217high`\ (bits 3--0) + - G\ :sub:`0219low`\ (bits 7--6) + + B\ :sub:`0218high`\ (bits 5--0) + * - start + 88: + - G\ :sub:`0219high` + - B\ :sub:`0220low` + - G\ :sub:`0221low`\ (bits 7--2) + + B\ :sub:`0220high`\ (bits 1--0) + - B\ :sub:`0222low`\ (bits 7--4) + + G\ :sub:`0221high`\ (bits 3--0) + * - start + 92: + - G\ :sub:`0223low`\ (bits 7--6) + + B\ :sub:`0222high`\ (bits 5--0) + - G\ :sub:`0223high` + - B\ :sub:`0224low` + - B\ :sub:`0224high`\ (bits 1--0) + * - start + 96: + - G\ :sub:`0300low` + - R\ :sub:`0301low`\ (bits 7--2) + + G\ :sub:`0300high`\ (bits 1--0) + - G\ :sub:`0302low`\ (bits 7--4) + + R\ :sub:`0301high`\ (bits 3--0) + - R\ :sub:`0303low`\ (bits 7--6) + + G\ :sub:`0302high`\ (bits 5--0) + * - start + 100: + - R\ :sub:`0303high` + - G\ :sub:`0304low` + - R\ :sub:`0305low`\ (bits 7--2) + + G\ :sub:`0304high`\ (bits 1--0) + - G\ :sub:`0306low`\ (bits 7--4) + + R\ :sub:`0305high`\ (bits 3--0) + * - start + 104: + - R\ :sub:`0307low`\ (bits 7--6) + + G\ :sub:`0306high`\ (bits 5--0) + - R\ :sub:`0307high` + - G\ :sub:`0308low` + - R\ :sub:`0309low`\ (bits 7--2) + + G\ :sub:`0308high`\ (bits 1--0) + * - start + 108: + - G\ :sub:`0310low`\ (bits 7--4) + + R\ :sub:`0309high`\ (bits 3--0) + - R\ :sub:`0311low`\ (bits 7--6) + + G\ :sub:`0310high`\ (bits 5--0) + - R\ :sub:`0311high` + - G\ :sub:`0312low` + * - start + 112: + - R\ :sub:`0313low`\ (bits 7--2) + + G\ :sub:`0312high`\ (bits 1--0) + - G\ :sub:`0314low`\ (bits 7--4) + + R\ :sub:`0313high`\ (bits 3--0) + - R\ :sub:`0315low`\ (bits 7--6) + + G\ :sub:`0314high`\ (bits 5--0) + - R\ :sub:`0315high` + * - start + 116: + - G\ :sub:`0316low` + - R\ :sub:`0317low`\ (bits 7--2) + + G\ :sub:`0316high`\ (bits 1--0) + - G\ :sub:`0318low`\ (bits 7--4) + + R\ :sub:`0317high`\ (bits 3--0) + - R\ :sub:`0319low`\ (bits 7--6) + + G\ :sub:`0318high`\ (bits 5--0) + * - start + 120: + - R\ :sub:`0319high` + - G\ :sub:`0320low` + - R\ :sub:`0321low`\ (bits 7--2) + + G\ :sub:`0320high`\ (bits 1--0) + - G\ :sub:`0322low`\ (bits 7--4) + + R\ :sub:`0321high`\ (bits 3--0) + * - start + 124: + - R\ :sub:`0323low`\ (bits 7--6) + + G\ :sub:`0322high`\ (bits 5--0) + - R\ :sub:`0323high` + - G\ :sub:`0324low` + - G\ :sub:`0324high`\ (bits 1--0) -- cgit From 9f577d6db5bf7d76fb9e26894a92fcb4ecb4c832 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 29 Dec 2017 08:23:41 -0500 Subject: media: dvb kAPI docs: document dvb_vb2.h Document the data structures and functions inside this kAPI header. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/dtv-common.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/media/kapi/dtv-common.rst b/Documentation/media/kapi/dtv-common.rst index c47843b6c81d..7a9574f03190 100644 --- a/Documentation/media/kapi/dtv-common.rst +++ b/Documentation/media/kapi/dtv-common.rst @@ -53,3 +53,8 @@ copy it from/to userspace. Two or more writers must be locked against each other. .. kernel-doc:: include/media/dvb_ringbuffer.h + +Digital TV VB2 handler +~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/media/dvb_vb2.h -- cgit From 3f3c11c3c4654ee7554bb13974e81e13a1ce4757 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 29 Dec 2017 08:34:11 -0500 Subject: media: dmx.h documentation: fix a warning /devel/v4l/patchwork/Documentation/output/dmx.h.rst:6: WARNING: undefined label: dmx_dqbuf (if the link has no caption the label must precede a section header) This is defined together with DMX_QBUF. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/dmx.h.rst.exceptions | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions index 629db384104a..63f55a9ae2b1 100644 --- a/Documentation/media/dmx.h.rst.exceptions +++ b/Documentation/media/dmx.h.rst.exceptions @@ -54,3 +54,5 @@ ignore symbol DMX_OUT_DECODER ignore symbol DMX_OUT_TAP ignore symbol DMX_OUT_TS_TAP ignore symbol DMX_OUT_TSDEMUX_TAP + +replace ioctl DMX_DQBUF dmx_qbuf -- cgit From e3401c2d3804ec67f90ac20ce684171a02c8bf3e Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 29 Dec 2017 07:59:13 -0500 Subject: media: v4l: Fix references in Intel IPU3 Bayer documentation The references in Intel IPU3 Bayer format documentation were wrong. Fix them. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst index 72fbd8f96381..99cde5077519 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst @@ -1,9 +1,9 @@ .. -*- coding: utf-8; mode: rst -*- -.. _V4L2_PIX_FMT_IPU3_SBGGR10: -.. _V4L2_PIX_FMT_IPU3_SGBRG10: -.. _V4L2_PIX_FMT_IPU3_SGRBG10: -.. _V4L2_PIX_FMT_IPU3_SRGGB10: +.. _v4l2-pix-fmt-ipu3-sbggr10: +.. _v4l2-pix-fmt-ipu3-sgbrg10: +.. _v4l2-pix-fmt-ipu3-sgrbg10: +.. _v4l2-pix-fmt-ipu3-srggb10: ********************************************************************************************************************************************** V4L2_PIX_FMT_IPU3_SBGGR10 ('ip3b'), V4L2_PIX_FMT_IPU3_SGBRG10 ('ip3g'), V4L2_PIX_FMT_IPU3_SGRBG10 ('ip3G'), V4L2_PIX_FMT_IPU3_SRGGB10 ('ip3r') -- cgit From 8f6d6016898615012ec92957fba65a23b7ae16c9 Mon Sep 17 00:00:00 2001 From: Adrian Fiergolski Date: Mon, 25 Dec 2017 22:26:46 +0100 Subject: i2c: mux: pca954x: add support for NXP PCA984x family This patch extends the current i2c-mux-pca954x driver and adds support for a newer PCA984x family of the I2C switches and multiplexers from NXP. Signed-off-by: Adrian Fiergolski Reviewed-by: Rob Herring Signed-off-by: Peter Rosin --- Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt index aa097045a10e..34d91501342e 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt @@ -1,10 +1,19 @@ * NXP PCA954x I2C bus switch +The driver supports NXP PCA954x and PCA984x I2C mux/switch devices. + Required Properties: - compatible: Must contain one of the following. - "nxp,pca9540", "nxp,pca9542", "nxp,pca9543", "nxp,pca9544", - "nxp,pca9545", "nxp,pca9546", "nxp,pca9547", "nxp,pca9548" + "nxp,pca9540", + "nxp,pca9542", + "nxp,pca9543", + "nxp,pca9544", + "nxp,pca9545", + "nxp,pca9546", "nxp,pca9846", + "nxp,pca9547", "nxp,pca9847", + "nxp,pca9548", "nxp,pca9848", + "nxp,pca9849" - reg: The I2C address of the device. -- cgit From 296cc300bd91c13c51f9f0efa7710392532be0b5 Mon Sep 17 00:00:00 2001 From: Alexandre Belloni Date: Wed, 8 Jun 2016 15:16:49 +0200 Subject: ARM: at91: Document new TCB bindings The current binding for the TCB is not flexible enough for some use cases and prevents proper utilization of all the channels. Acked-by: Rob Herring Cc: devicetree@vger.kernel.org Acked-by: Nicolas Ferre Signed-off-by: Alexandre Belloni --- .../devicetree/bindings/arm/atmel-at91.txt | 32 ------------- .../devicetree/bindings/mfd/atmel-tcb.txt | 56 ++++++++++++++++++++++ 2 files changed, 56 insertions(+), 32 deletions(-) create mode 100644 Documentation/devicetree/bindings/mfd/atmel-tcb.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.txt b/Documentation/devicetree/bindings/arm/atmel-at91.txt index 91cb8e4f2a4f..31220b54d85d 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.txt +++ b/Documentation/devicetree/bindings/arm/atmel-at91.txt @@ -90,38 +90,6 @@ System Timer (ST) required properties: Its subnodes can be: - watchdog: compatible should be "atmel,at91rm9200-wdt" -TC/TCLIB Timer required properties: -- compatible: Should be "atmel,-tcb". - can be "at91rm9200" or "at91sam9x5" -- reg: Should contain registers location and length -- interrupts: Should contain all interrupts for the TC block - Note that you can specify several interrupt cells if the TC - block has one interrupt per channel. -- clock-names: tuple listing input clock names. - Required elements: "t0_clk", "slow_clk" - Optional elements: "t1_clk", "t2_clk" -- clocks: phandles to input clocks. - -Examples: - -One interrupt per TC block: - tcb0: timer@fff7c000 { - compatible = "atmel,at91rm9200-tcb"; - reg = <0xfff7c000 0x100>; - interrupts = <18 4>; - clocks = <&tcb0_clk>; - clock-names = "t0_clk"; - }; - -One interrupt per TC channel in a TC block: - tcb1: timer@fffdc000 { - compatible = "atmel,at91rm9200-tcb"; - reg = <0xfffdc000 0x100>; - interrupts = <26 4 27 4 28 4>; - clocks = <&tcb1_clk>; - clock-names = "t0_clk"; - }; - RSTC Reset Controller required properties: - compatible: Should be "atmel,-rstc". can be "at91sam9260" or "at91sam9g45" or "sama5d3" diff --git a/Documentation/devicetree/bindings/mfd/atmel-tcb.txt b/Documentation/devicetree/bindings/mfd/atmel-tcb.txt new file mode 100644 index 000000000000..c4a83e364cb6 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-tcb.txt @@ -0,0 +1,56 @@ +* Device tree bindings for Atmel Timer Counter Blocks +- compatible: Should be "atmel,-tcb", "simple-mfd", "syscon". + can be "at91rm9200" or "at91sam9x5" +- reg: Should contain registers location and length +- #address-cells: has to be 1 +- #size-cells: has to be 0 +- interrupts: Should contain all interrupts for the TC block + Note that you can specify several interrupt cells if the TC + block has one interrupt per channel. +- clock-names: tuple listing input clock names. + Required elements: "t0_clk", "slow_clk" + Optional elements: "t1_clk", "t2_clk" +- clocks: phandles to input clocks. + +The TCB can expose multiple subdevices: + * a timer + - compatible: Should be "atmel,tcb-timer" + - reg: Should contain the TCB channels to be used. If the + counter width is 16 bits (at91rm9200-tcb), two consecutive + channels are needed. Else, only one channel will be used. + +Examples: + +One interrupt per TC block: + tcb0: timer@fff7c000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfff7c000 0x100>; + interrupts = <18 4>; + clocks = <&tcb0_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + + timer@0 { + compatible = "atmel,tcb-timer"; + reg = <0>, <1>; + }; + + timer@2 { + compatible = "atmel,tcb-timer"; + reg = <2>; + }; + }; + +One interrupt per TC channel in a TC block: + tcb1: timer@fffdc000 { + compatible = "atmel,at91rm9200-tcb", "simple-mfd", "syscon"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0xfffdc000 0x100>; + interrupts = <26 4>, <27 4>, <28 4>; + clocks = <&tcb1_clk>, <&clk32k>; + clock-names = "t0_clk", "slow_clk"; + }; + + -- cgit From fe06a3fa28917defb70483b2da710d5c54156e52 Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Thu, 7 Dec 2017 11:38:28 +0100 Subject: dt-bindings: eeprom: rename to at24.txt This binding documentation is for the at24 driver, so the filename should reflect it. This avoids confusion because we also have an "eeprom" driver in Linux but it doesn't support DT even. Acked-by: Geert Uytterhoeven Signed-off-by: Wolfram Sang Reviewed-by: Rob Herring Signed-off-by: Bartosz Golaszewski --- Documentation/devicetree/bindings/eeprom/at24.txt | 47 ++++++++++++++++++++++ .../devicetree/bindings/eeprom/eeprom.txt | 47 ---------------------- 2 files changed, 47 insertions(+), 47 deletions(-) create mode 100644 Documentation/devicetree/bindings/eeprom/at24.txt delete mode 100644 Documentation/devicetree/bindings/eeprom/eeprom.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt new file mode 100644 index 000000000000..27f2bc15298a --- /dev/null +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -0,0 +1,47 @@ +EEPROMs (I2C) + +Required properties: + + - compatible : should be ",", like these: + + "atmel,24c00", "atmel,24c01", "atmel,24c02", "atmel,24c04", + "atmel,24c08", "atmel,24c16", "atmel,24c32", "atmel,24c64", + "atmel,24c128", "atmel,24c256", "atmel,24c512", "atmel,24c1024" + + "catalyst,24c32" + + "microchip,24c128" + + "ramtron,24c64" + + "renesas,r1ex24002" + + The following manufacturers values have been deprecated: + "at", "at24" + + If there is no specific driver for , a generic + device with and manufacturer "atmel" should be used. + Possible types are: + "24c00", "24c01", "24c02", "24c04", "24c08", "24c16", "24c32", "24c64", + "24c128", "24c256", "24c512", "24c1024", "spd" + + - reg : the I2C address of the EEPROM + +Optional properties: + + - pagesize : the length of the pagesize for writing. Please consult the + manual of your device, that value varies a lot. A wrong value + may result in data loss! If not specified, a safety value of + '1' is used which will be very slow. + + - read-only: this parameterless property disables writes to the eeprom + + - size: total eeprom size in bytes + +Example: + +eeprom@52 { + compatible = "atmel,24c32"; + reg = <0x52>; + pagesize = <32>; +}; diff --git a/Documentation/devicetree/bindings/eeprom/eeprom.txt b/Documentation/devicetree/bindings/eeprom/eeprom.txt deleted file mode 100644 index 27f2bc15298a..000000000000 --- a/Documentation/devicetree/bindings/eeprom/eeprom.txt +++ /dev/null @@ -1,47 +0,0 @@ -EEPROMs (I2C) - -Required properties: - - - compatible : should be ",", like these: - - "atmel,24c00", "atmel,24c01", "atmel,24c02", "atmel,24c04", - "atmel,24c08", "atmel,24c16", "atmel,24c32", "atmel,24c64", - "atmel,24c128", "atmel,24c256", "atmel,24c512", "atmel,24c1024" - - "catalyst,24c32" - - "microchip,24c128" - - "ramtron,24c64" - - "renesas,r1ex24002" - - The following manufacturers values have been deprecated: - "at", "at24" - - If there is no specific driver for , a generic - device with and manufacturer "atmel" should be used. - Possible types are: - "24c00", "24c01", "24c02", "24c04", "24c08", "24c16", "24c32", "24c64", - "24c128", "24c256", "24c512", "24c1024", "spd" - - - reg : the I2C address of the EEPROM - -Optional properties: - - - pagesize : the length of the pagesize for writing. Please consult the - manual of your device, that value varies a lot. A wrong value - may result in data loss! If not specified, a safety value of - '1' is used which will be very slow. - - - read-only: this parameterless property disables writes to the eeprom - - - size: total eeprom size in bytes - -Example: - -eeprom@52 { - compatible = "atmel,24c32"; - reg = <0x52>; - pagesize = <32>; -}; -- cgit From 355dd4ca10b49183272ec54ed9853bb4b95d2391 Mon Sep 17 00:00:00 2001 From: Sven Van Asbroeck Date: Fri, 8 Dec 2017 11:28:31 -0500 Subject: dt-bindings: add eeprom "no-read-rollover" property Adds an optional property for at24 eeproms. This parameterless property indicates that the multi-address eeprom does not automatically roll over reads to the next slave address. Signed-off-by: Sven Van Asbroeck Reviewed-by: Rob Herring Signed-off-by: Bartosz Golaszewski --- Documentation/devicetree/bindings/eeprom/at24.txt | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index 27f2bc15298a..a0415b8471bb 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -38,6 +38,11 @@ Optional properties: - size: total eeprom size in bytes + - no-read-rollover: + This parameterless property indicates that the multi-address + eeprom does not automatically roll over reads to the next + slave address. Please consult the manual of your device. + Example: eeprom@52 { -- cgit From 3f3d8ef7f4eff5909b0cc996718de81de99af1e6 Mon Sep 17 00:00:00 2001 From: Bartosz Golaszewski Date: Tue, 19 Dec 2017 12:09:23 +0100 Subject: dt-bindings: at24: new optional property - wp-gpios AT24 EEPROMs have a write-protect pin, which - when pulled high - inhibits writes to the upper quadrant of memory (although it has been observed that on some chips it disables writing to the entire memory range). On some boards, this pin is connected to a GPIO and pulled high by default, which forces the user to manually change its state before writing. On linux this means that we either need to hog the line all the time, or set the GPIO value before writing from outside of the at24 driver. Add a new optional property to the device tree binding document, which allows to specify the GPIO line to which the write-protect pin is connected. Signed-off-by: Bartosz Golaszewski Reviewed-by: Andy Shevchenko Reviewed-by: Rob Herring --- Documentation/devicetree/bindings/eeprom/at24.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index a0415b8471bb..cbc80e194ac6 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -43,10 +43,13 @@ Optional properties: eeprom does not automatically roll over reads to the next slave address. Please consult the manual of your device. + - wp-gpios: GPIO to which the write-protect pin of the chip is connected. + Example: eeprom@52 { compatible = "atmel,24c32"; reg = <0x52>; pagesize = <32>; + wp-gpios = <&gpio1 3 0>; }; -- cgit From 14ebc28e07e68ff412aa42f7d8b67969e2f63d00 Mon Sep 17 00:00:00 2001 From: Matthew Wilcox Date: Fri, 22 Dec 2017 06:32:16 -0800 Subject: errseq: Add to documentation tree - Move errseq.rst into core-api - Add errseq to the core-api index - Promote the header to a more prominent header type, otherwise we get three entries in the table of contents. - Reformat the table to look nicer and be a little more proportional in terms of horizontal width per bit (the SF bit is still disproportionately large, but there's no way to fix that). - Include errseq kernel-doc in the errseq.rst - Neaten some kernel-doc markup Signed-off-by: Matthew Wilcox Reviewed-by: Jeff Layton Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- Documentation/core-api/errseq.rst | 159 ++++++++++++++++++++++++++++++++++++++ Documentation/core-api/index.rst | 1 + Documentation/errseq.rst | 149 ----------------------------------- 3 files changed, 160 insertions(+), 149 deletions(-) create mode 100644 Documentation/core-api/errseq.rst delete mode 100644 Documentation/errseq.rst (limited to 'Documentation') diff --git a/Documentation/core-api/errseq.rst b/Documentation/core-api/errseq.rst new file mode 100644 index 000000000000..ff332e272405 --- /dev/null +++ b/Documentation/core-api/errseq.rst @@ -0,0 +1,159 @@ +===================== +The errseq_t datatype +===================== + +An errseq_t is a way of recording errors in one place, and allowing any +number of "subscribers" to tell whether it has changed since a previous +point where it was sampled. + +The initial use case for this is tracking errors for file +synchronization syscalls (fsync, fdatasync, msync and sync_file_range), +but it may be usable in other situations. + +It's implemented as an unsigned 32-bit value. The low order bits are +designated to hold an error code (between 1 and MAX_ERRNO). The upper bits +are used as a counter. This is done with atomics instead of locking so that +these functions can be called from any context. + +Note that there is a risk of collisions if new errors are being recorded +frequently, since we have so few bits to use as a counter. + +To mitigate this, the bit between the error value and counter is used as +a flag to tell whether the value has been sampled since a new value was +recorded. That allows us to avoid bumping the counter if no one has +sampled it since the last time an error was recorded. + +Thus we end up with a value that looks something like this: + ++--------------------------------------+----+------------------------+ +| 31..13 | 12 | 11..0 | ++--------------------------------------+----+------------------------+ +| counter | SF | errno | ++--------------------------------------+----+------------------------+ + +The general idea is for "watchers" to sample an errseq_t value and keep +it as a running cursor. That value can later be used to tell whether +any new errors have occurred since that sampling was done, and atomically +record the state at the time that it was checked. This allows us to +record errors in one place, and then have a number of "watchers" that +can tell whether the value has changed since they last checked it. + +A new errseq_t should always be zeroed out. An errseq_t value of all zeroes +is the special (but common) case where there has never been an error. An all +zero value thus serves as the "epoch" if one wishes to know whether there +has ever been an error set since it was first initialized. + +API usage +========= + +Let me tell you a story about a worker drone. Now, he's a good worker +overall, but the company is a little...management heavy. He has to +report to 77 supervisors today, and tomorrow the "big boss" is coming in +from out of town and he's sure to test the poor fellow too. + +They're all handing him work to do -- so much he can't keep track of who +handed him what, but that's not really a big problem. The supervisors +just want to know when he's finished all of the work they've handed him so +far and whether he made any mistakes since they last asked. + +He might have made the mistake on work they didn't actually hand him, +but he can't keep track of things at that level of detail, all he can +remember is the most recent mistake that he made. + +Here's our worker_drone representation:: + + struct worker_drone { + errseq_t wd_err; /* for recording errors */ + }; + +Every day, the worker_drone starts out with a blank slate:: + + struct worker_drone wd; + + wd.wd_err = (errseq_t)0; + +The supervisors come in and get an initial read for the day. They +don't care about anything that happened before their watch begins:: + + struct supervisor { + errseq_t s_wd_err; /* private "cursor" for wd_err */ + spinlock_t s_wd_err_lock; /* protects s_wd_err */ + } + + struct supervisor su; + + su.s_wd_err = errseq_sample(&wd.wd_err); + spin_lock_init(&su.s_wd_err_lock); + +Now they start handing him tasks to do. Every few minutes they ask him to +finish up all of the work they've handed him so far. Then they ask him +whether he made any mistakes on any of it:: + + spin_lock(&su.su_wd_err_lock); + err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err); + spin_unlock(&su.su_wd_err_lock); + +Up to this point, that just keeps returning 0. + +Now, the owners of this company are quite miserly and have given him +substandard equipment with which to do his job. Occasionally it +glitches and he makes a mistake. He sighs a heavy sigh, and marks it +down:: + + errseq_set(&wd.wd_err, -EIO); + +...and then gets back to work. The supervisors eventually poll again +and they each get the error when they next check. Subsequent calls will +return 0, until another error is recorded, at which point it's reported +to each of them once. + +Note that the supervisors can't tell how many mistakes he made, only +whether one was made since they last checked, and the latest value +recorded. + +Occasionally the big boss comes in for a spot check and asks the worker +to do a one-off job for him. He's not really watching the worker +full-time like the supervisors, but he does need to know whether a +mistake occurred while his job was processing. + +He can just sample the current errseq_t in the worker, and then use that +to tell whether an error has occurred later:: + + errseq_t since = errseq_sample(&wd.wd_err); + /* submit some work and wait for it to complete */ + err = errseq_check(&wd.wd_err, since); + +Since he's just going to discard "since" after that point, he doesn't +need to advance it here. He also doesn't need any locking since it's +not usable by anyone else. + +Serializing errseq_t cursor updates +=================================== + +Note that the errseq_t API does not protect the errseq_t cursor during a +check_and_advance_operation. Only the canonical error code is handled +atomically. In a situation where more than one task might be using the +same errseq_t cursor at the same time, it's important to serialize +updates to that cursor. + +If that's not done, then it's possible for the cursor to go backward +in which case the same error could be reported more than once. + +Because of this, it's often advantageous to first do an errseq_check to +see if anything has changed, and only later do an +errseq_check_and_advance after taking the lock. e.g.:: + + if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err)) { + /* su.s_wd_err is protected by s_wd_err_lock */ + spin_lock(&su.s_wd_err_lock); + err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err); + spin_unlock(&su.s_wd_err_lock); + } + +That avoids the spinlock in the common case where nothing has changed +since the last time it was checked. + +Functions +========= + +.. kernel-doc:: lib/errseq.c diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index d55ee6b006ed..1b1fd01990b5 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -22,6 +22,7 @@ Core utilities flexible-arrays librs genalloc + errseq printk-formats Interfaces for kernel debugging diff --git a/Documentation/errseq.rst b/Documentation/errseq.rst deleted file mode 100644 index 4c29bd5afbc5..000000000000 --- a/Documentation/errseq.rst +++ /dev/null @@ -1,149 +0,0 @@ -The errseq_t datatype -===================== -An errseq_t is a way of recording errors in one place, and allowing any -number of "subscribers" to tell whether it has changed since a previous -point where it was sampled. - -The initial use case for this is tracking errors for file -synchronization syscalls (fsync, fdatasync, msync and sync_file_range), -but it may be usable in other situations. - -It's implemented as an unsigned 32-bit value. The low order bits are -designated to hold an error code (between 1 and MAX_ERRNO). The upper bits -are used as a counter. This is done with atomics instead of locking so that -these functions can be called from any context. - -Note that there is a risk of collisions if new errors are being recorded -frequently, since we have so few bits to use as a counter. - -To mitigate this, the bit between the error value and counter is used as -a flag to tell whether the value has been sampled since a new value was -recorded. That allows us to avoid bumping the counter if no one has -sampled it since the last time an error was recorded. - -Thus we end up with a value that looks something like this:: - - bit: 31..13 12 11..0 - +-----------------+----+----------------+ - | counter | SF | errno | - +-----------------+----+----------------+ - -The general idea is for "watchers" to sample an errseq_t value and keep -it as a running cursor. That value can later be used to tell whether -any new errors have occurred since that sampling was done, and atomically -record the state at the time that it was checked. This allows us to -record errors in one place, and then have a number of "watchers" that -can tell whether the value has changed since they last checked it. - -A new errseq_t should always be zeroed out. An errseq_t value of all zeroes -is the special (but common) case where there has never been an error. An all -zero value thus serves as the "epoch" if one wishes to know whether there -has ever been an error set since it was first initialized. - -API usage -========= -Let me tell you a story about a worker drone. Now, he's a good worker -overall, but the company is a little...management heavy. He has to -report to 77 supervisors today, and tomorrow the "big boss" is coming in -from out of town and he's sure to test the poor fellow too. - -They're all handing him work to do -- so much he can't keep track of who -handed him what, but that's not really a big problem. The supervisors -just want to know when he's finished all of the work they've handed him so -far and whether he made any mistakes since they last asked. - -He might have made the mistake on work they didn't actually hand him, -but he can't keep track of things at that level of detail, all he can -remember is the most recent mistake that he made. - -Here's our worker_drone representation:: - - struct worker_drone { - errseq_t wd_err; /* for recording errors */ - }; - -Every day, the worker_drone starts out with a blank slate:: - - struct worker_drone wd; - - wd.wd_err = (errseq_t)0; - -The supervisors come in and get an initial read for the day. They -don't care about anything that happened before their watch begins:: - - struct supervisor { - errseq_t s_wd_err; /* private "cursor" for wd_err */ - spinlock_t s_wd_err_lock; /* protects s_wd_err */ - } - - struct supervisor su; - - su.s_wd_err = errseq_sample(&wd.wd_err); - spin_lock_init(&su.s_wd_err_lock); - -Now they start handing him tasks to do. Every few minutes they ask him to -finish up all of the work they've handed him so far. Then they ask him -whether he made any mistakes on any of it:: - - spin_lock(&su.su_wd_err_lock); - err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err); - spin_unlock(&su.su_wd_err_lock); - -Up to this point, that just keeps returning 0. - -Now, the owners of this company are quite miserly and have given him -substandard equipment with which to do his job. Occasionally it -glitches and he makes a mistake. He sighs a heavy sigh, and marks it -down:: - - errseq_set(&wd.wd_err, -EIO); - -...and then gets back to work. The supervisors eventually poll again -and they each get the error when they next check. Subsequent calls will -return 0, until another error is recorded, at which point it's reported -to each of them once. - -Note that the supervisors can't tell how many mistakes he made, only -whether one was made since they last checked, and the latest value -recorded. - -Occasionally the big boss comes in for a spot check and asks the worker -to do a one-off job for him. He's not really watching the worker -full-time like the supervisors, but he does need to know whether a -mistake occurred while his job was processing. - -He can just sample the current errseq_t in the worker, and then use that -to tell whether an error has occurred later:: - - errseq_t since = errseq_sample(&wd.wd_err); - /* submit some work and wait for it to complete */ - err = errseq_check(&wd.wd_err, since); - -Since he's just going to discard "since" after that point, he doesn't -need to advance it here. He also doesn't need any locking since it's -not usable by anyone else. - -Serializing errseq_t cursor updates -=================================== -Note that the errseq_t API does not protect the errseq_t cursor during a -check_and_advance_operation. Only the canonical error code is handled -atomically. In a situation where more than one task might be using the -same errseq_t cursor at the same time, it's important to serialize -updates to that cursor. - -If that's not done, then it's possible for the cursor to go backward -in which case the same error could be reported more than once. - -Because of this, it's often advantageous to first do an errseq_check to -see if anything has changed, and only later do an -errseq_check_and_advance after taking the lock. e.g.:: - - if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err)) { - /* su.s_wd_err is protected by s_wd_err_lock */ - spin_lock(&su.s_wd_err_lock); - err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err); - spin_unlock(&su.s_wd_err_lock); - } - -That avoids the spinlock in the common case where nothing has changed -since the last time it was checked. -- cgit From 1892ce4cdd9bfb5a6c80fe4fdfd4ffcb59d1b06d Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Sat, 23 Dec 2017 01:41:21 +0900 Subject: doc: md: Fix a file name to md-fault.c in fault-injection.txt drivers/md/faulty.c has been renamed to md-faulty.c after following commit merged int to the main line. 935fe0983e09f4f7331ebf5ea4ae2124f6e9f9e8 . But the file name in fault-injection.txt has not been changed. Now the actual file name and document are in sync. Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/fault-injection/fault-injection.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.txt index 918972babcd8..1c0bfbbf7869 100644 --- a/Documentation/fault-injection/fault-injection.txt +++ b/Documentation/fault-injection/fault-injection.txt @@ -1,7 +1,7 @@ Fault injection capabilities infrastructure =========================================== -See also drivers/md/faulty.c and "every_nth" module option for scsi_debug. +See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug. Available fault injection capabilities -- cgit From 91581e4c60db35268ad67c550f5c551045f592f5 Mon Sep 17 00:00:00 2001 From: Adam Borowski Date: Wed, 20 Dec 2017 14:58:52 +0100 Subject: fs/*/Kconfig: drop links to 404-compliant http://acl.bestbits.at This link is replicated in most filesystems' config stanzas. Referring to an archived version of that site is pointless as it mostly deals with patches; user documentation is available elsewhere. Signed-off-by: Adam Borowski CC: Alexander Viro Reviewed-by: Darrick J. Wong Acked-by: Jan Kara Acked-by: Dave Kleikamp Acked-by: David Sterba Acked-by: "Yan, Zheng" Acked-by: Chao Yu Acked-by: Jaegeuk Kim Acked-by: Steve French Signed-off-by: Jonathan Corbet --- Documentation/filesystems/ext2.txt | 2 -- Documentation/filesystems/ext4.txt | 7 +++---- 2 files changed, 3 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/ext2.txt b/Documentation/filesystems/ext2.txt index 55755395d3dc..81c0becab225 100644 --- a/Documentation/filesystems/ext2.txt +++ b/Documentation/filesystems/ext2.txt @@ -49,12 +49,10 @@ sb=n Use alternate superblock at this location. user_xattr Enable "user." POSIX Extended Attributes (requires CONFIG_EXT2_FS_XATTR). - See also http://acl.bestbits.at nouser_xattr Don't support "user." extended attributes. acl Enable POSIX Access Control Lists support (requires CONFIG_EXT2_FS_POSIX_ACL). - See also http://acl.bestbits.at noacl Don't support POSIX ACLs. nobh Do not attach buffer_heads to file pagecache. diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 75236c0c2ac2..8cd63e16f171 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -202,15 +202,14 @@ inode_readahead_blks=n This tuning parameter controls the maximum the buffer cache. The default value is 32 blocks. nouser_xattr Disables Extended User Attributes. See the - attr(5) manual page and http://acl.bestbits.at/ - for more information about extended attributes. + attr(5) manual page for more information about + extended attributes. noacl This option disables POSIX Access Control List support. If ACL support is enabled in the kernel configuration (CONFIG_EXT4_FS_POSIX_ACL), ACL is enabled by default on mount. See the acl(5) manual - page and http://acl.bestbits.at/ for more information - about acl. + page for more information about acl. bsddf (*) Make 'df' act like BSD. minixdf Make 'df' act like Minix. -- cgit From 2d14a0ee5e73d5224873777892fd86d3a283b059 Mon Sep 17 00:00:00 2001 From: Biju Das Date: Tue, 19 Dec 2017 13:17:28 +0000 Subject: dt-bindings: thermal: rcar: Add device tree support for r8a7743 Add thermal sensor support for r8a7743 SoC. The Renesas RZ/G1M (r8a7743) thermal sensor module is identical to the R-Car Gen2 family. No driver change is needed due to the fallback compatible value "renesas,rcar-gen2-thermal". Signed-off-by: Biju Das Reviewed-by: Fabrizio Castro Reviewed-by: Geert Uytterhoeven Reviewed-by: Rob Herring Reviewed-by: Simon Horman Signed-off-by: Eduardo Valentin --- Documentation/devicetree/bindings/thermal/rcar-thermal.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt index a8e52c8ccfcc..349e635f2d87 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt @@ -6,6 +6,7 @@ Required properties: "renesas,rcar-thermal" (without thermal-zone) as fallback. Examples with soctypes are: - "renesas,thermal-r8a73a4" (R-Mobile APE6) + - "renesas,thermal-r8a7743" (RZ/G1M) - "renesas,thermal-r8a7779" (R-Car H1) - "renesas,thermal-r8a7790" (R-Car H2) - "renesas,thermal-r8a7791" (R-Car M2-W) -- cgit From 7ba03c2599654eeb93912f4c4286df5b83b44044 Mon Sep 17 00:00:00 2001 From: Baruch Siach Date: Fri, 22 Dec 2017 17:14:03 +0100 Subject: dt-bindings: thermal: Describe Armada AP806 and CP110 Add compatible strings for AP806 and CP110 that are part of the Armada 8k/7k line of SoCs. Add a note on the differences in the size of the control area in different bindings. This is an existing difference between the Armada 375 binding and the other boards already supported. The new AP806 and CP110 bindings are similar to the existing Armada 375 in this regard. Signed-off-by: Baruch Siach [: reword, additional details] Signed-off-by: Miquel Raynal Reviewed-by: Rob Herring Signed-off-by: Eduardo Valentin --- .../devicetree/bindings/thermal/armada-thermal.txt | 37 +++++++++++++++------- 1 file changed, 25 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/thermal/armada-thermal.txt b/Documentation/devicetree/bindings/thermal/armada-thermal.txt index 24aacf8948c5..e0d013a2e66d 100644 --- a/Documentation/devicetree/bindings/thermal/armada-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/armada-thermal.txt @@ -2,22 +2,35 @@ Required properties: -- compatible: Should be set to one of the following: - marvell,armada370-thermal - marvell,armada375-thermal - marvell,armada380-thermal - marvell,armadaxp-thermal +- compatible: Should be set to one of the following: + * marvell,armada370-thermal + * marvell,armada375-thermal + * marvell,armada380-thermal + * marvell,armadaxp-thermal + * marvell,armada-ap806-thermal + * marvell,armada-cp110-thermal -- reg: Device's register space. - Two entries are expected, see the examples below. - The first one is required for the sensor register; - the second one is required for the control register - to be used for sensor initialization (a.k.a. calibration). +- reg: Device's register space. + Two entries are expected, see the examples below. The first one points + to the status register (4B). The second one points to the control + registers (8B). + Note: The compatibles marvell,armada370-thermal, + marvell,armada380-thermal, and marvell,armadaxp-thermal must point to + "control MSB/control 1", with size of 4 (deprecated binding), or point + to "control LSB/control 0" with size of 8 (current binding). All other + compatibles must point to "control LSB/control 0" with size of 8. -Example: +Examples: + /* Legacy bindings */ thermal@d0018300 { compatible = "marvell,armada370-thermal"; - reg = <0xd0018300 0x4 + reg = <0xd0018300 0x4 0xd0018304 0x4>; }; + + ap_thermal: thermal@6f8084 { + compatible = "marvell,armada-ap806-thermal"; + reg = <0x6f808C 0x4>, + <0x6f8084 0x8>; + }; -- cgit From 3c8a23c29d30eec7a20fbb3e47e5346d9ada687b Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Mon, 1 Jan 2018 22:49:29 -0800 Subject: Input: gpio_tilt - delete driver This driver was merged in 2011 as a tool for detecting the orientation of a screen. The device driver assumes board file setup using the platform data from . But no boards in the kernel tree defines this platform data. As I am faced with refactoring drivers to use GPIO descriptors and pass decriptor tables from boards, or use the device tree device drivers like these creates a serious problem: I cannot fix them and cannot test them, not even compile-test them with a system actually using it (no in-tree boardfile). I suggest to delete this driver and rewrite it using device tree if it is still in use on actively maintained systems. I can also offer to rewrite it out of the blue using device tree if someone promise to test it and help me iterate it. Signed-off-by: Linus Walleij Acked-by: Heiko Stuebner Patchwork-Id: 10133609 Signed-off-by: Dmitry Torokhov --- Documentation/gpio/drivers-on-gpio.txt | 5 -- Documentation/input/devices/gpio-tilt.rst | 103 ------------------------------ 2 files changed, 108 deletions(-) delete mode 100644 Documentation/input/devices/gpio-tilt.rst (limited to 'Documentation') diff --git a/Documentation/gpio/drivers-on-gpio.txt b/Documentation/gpio/drivers-on-gpio.txt index 9a78d385b92e..a2ccbab12eb7 100644 --- a/Documentation/gpio/drivers-on-gpio.txt +++ b/Documentation/gpio/drivers-on-gpio.txt @@ -28,11 +28,6 @@ hardware descriptions such as device tree or ACPI: - gpio-beeper: drivers/input/misc/gpio-beeper.c is used to provide a beep from an external speaker connected to a GPIO line. -- gpio-tilt-polled: drivers/input/misc/gpio_tilt_polled.c provides tilt - detection switches using GPIO, which is useful for your homebrewn pinball - machine if for nothing else. It can detect different tilt angles of the - monitored object. - - extcon-gpio: drivers/extcon/extcon-gpio.c is used when you need to read an external connector status, such as a headset line for an audio driver or an HDMI connector. It will provide a better userspace sysfs interface than GPIO. diff --git a/Documentation/input/devices/gpio-tilt.rst b/Documentation/input/devices/gpio-tilt.rst deleted file mode 100644 index fa6e64570aa7..000000000000 --- a/Documentation/input/devices/gpio-tilt.rst +++ /dev/null @@ -1,103 +0,0 @@ -Driver for tilt-switches connected via GPIOs -============================================ - -Generic driver to read data from tilt switches connected via gpios. -Orientation can be provided by one or more than one tilt switches, -i.e. each tilt switch providing one axis, and the number of axes -is also not limited. - - -Data structures ---------------- - -The array of struct gpio in the gpios field is used to list the gpios -that represent the current tilt state. - -The array of struct gpio_tilt_axis describes the axes that are reported -to the input system. The values set therein are used for the -input_set_abs_params calls needed to init the axes. - -The array of struct gpio_tilt_state maps gpio states to the corresponding -values to report. The gpio state is represented as a bitfield where the -bit-index corresponds to the index of the gpio in the struct gpio array. -In the same manner the values stored in the axes array correspond to -the elements of the gpio_tilt_axis-array. - - -Example -------- - -Example configuration for a single TS1003 tilt switch that rotates around -one axis in 4 steps and emits the current tilt via two GPIOs:: - - static int sg060_tilt_enable(struct device *dev) { - /* code to enable the sensors */ - }; - - static void sg060_tilt_disable(struct device *dev) { - /* code to disable the sensors */ - }; - - static struct gpio sg060_tilt_gpios[] = { - { SG060_TILT_GPIO_SENSOR1, GPIOF_IN, "tilt_sensor1" }, - { SG060_TILT_GPIO_SENSOR2, GPIOF_IN, "tilt_sensor2" }, - }; - - static struct gpio_tilt_state sg060_tilt_states[] = { - { - .gpios = (0 << 1) | (0 << 0), - .axes = (int[]) { - 0, - }, - }, { - .gpios = (0 << 1) | (1 << 0), - .axes = (int[]) { - 1, /* 90 degrees */ - }, - }, { - .gpios = (1 << 1) | (1 << 0), - .axes = (int[]) { - 2, /* 180 degrees */ - }, - }, { - .gpios = (1 << 1) | (0 << 0), - .axes = (int[]) { - 3, /* 270 degrees */ - }, - }, - }; - - static struct gpio_tilt_axis sg060_tilt_axes[] = { - { - .axis = ABS_RY, - .min = 0, - .max = 3, - .fuzz = 0, - .flat = 0, - }, - }; - - static struct gpio_tilt_platform_data sg060_tilt_pdata= { - .gpios = sg060_tilt_gpios, - .nr_gpios = ARRAY_SIZE(sg060_tilt_gpios), - - .axes = sg060_tilt_axes, - .nr_axes = ARRAY_SIZE(sg060_tilt_axes), - - .states = sg060_tilt_states, - .nr_states = ARRAY_SIZE(sg060_tilt_states), - - .debounce_interval = 100, - - .poll_interval = 1000, - .enable = sg060_tilt_enable, - .disable = sg060_tilt_disable, - }; - - static struct platform_device sg060_device_tilt = { - .name = "gpio-tilt-polled", - .id = -1, - .dev = { - .platform_data = &sg060_tilt_pdata, - }, - }; -- cgit From e5a2cfb492d5f25f96fa06170dba7494355c5969 Mon Sep 17 00:00:00 2001 From: Christoffer Dall Date: Tue, 12 Dec 2017 21:37:21 +0100 Subject: KVM: arm/arm64: Delete outdated forwarded irq documentation The reason I added this documentation originally was that the concept of "never taking the interrupt", but just use the timer to generate an exit from the guest, was confusing to most, and we had to explain it several times over. But as we can clearly see, we've failed to update the documentation as the code has evolved, and people who need to understand these details are probably better off reading the code. Let's lighten our maintenance burden slightly and just get rid of this. Acked-by: Marc Zyngier Signed-off-by: Christoffer Dall --- Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt | 187 --------------------- 1 file changed, 187 deletions(-) delete mode 100644 Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt b/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt deleted file mode 100644 index 38bca2835278..000000000000 --- a/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt +++ /dev/null @@ -1,187 +0,0 @@ -KVM/ARM VGIC Forwarded Physical Interrupts -========================================== - -The KVM/ARM code implements software support for the ARM Generic -Interrupt Controller's (GIC's) hardware support for virtualization by -allowing software to inject virtual interrupts to a VM, which the guest -OS sees as regular interrupts. The code is famously known as the VGIC. - -Some of these virtual interrupts, however, correspond to physical -interrupts from real physical devices. One example could be the -architected timer, which itself supports virtualization, and therefore -lets a guest OS program the hardware device directly to raise an -interrupt at some point in time. When such an interrupt is raised, the -host OS initially handles the interrupt and must somehow signal this -event as a virtual interrupt to the guest. Another example could be a -passthrough device, where the physical interrupts are initially handled -by the host, but the device driver for the device lives in the guest OS -and KVM must therefore somehow inject a virtual interrupt on behalf of -the physical one to the guest OS. - -These virtual interrupts corresponding to a physical interrupt on the -host are called forwarded physical interrupts, but are also sometimes -referred to as 'virtualized physical interrupts' and 'mapped interrupts'. - -Forwarded physical interrupts are handled slightly differently compared -to virtual interrupts generated purely by a software emulated device. - - -The HW bit ----------- -Virtual interrupts are signalled to the guest by programming the List -Registers (LRs) on the GIC before running a VCPU. The LR is programmed -with the virtual IRQ number and the state of the interrupt (Pending, -Active, or Pending+Active). When the guest ACKs and EOIs a virtual -interrupt, the LR state moves from Pending to Active, and finally to -inactive. - -The LRs include an extra bit, called the HW bit. When this bit is set, -KVM must also program an additional field in the LR, the physical IRQ -number, to link the virtual with the physical IRQ. - -When the HW bit is set, KVM must EITHER set the Pending OR the Active -bit, never both at the same time. - -Setting the HW bit causes the hardware to deactivate the physical -interrupt on the physical distributor when the guest deactivates the -corresponding virtual interrupt. - - -Forwarded Physical Interrupts Life Cycle ----------------------------------------- - -The state of forwarded physical interrupts is managed in the following way: - - - The physical interrupt is acked by the host, and becomes active on - the physical distributor (*). - - KVM sets the LR.Pending bit, because this is the only way the GICV - interface is going to present it to the guest. - - LR.Pending will stay set as long as the guest has not acked the interrupt. - - LR.Pending transitions to LR.Active on the guest read of the IAR, as - expected. - - On guest EOI, the *physical distributor* active bit gets cleared, - but the LR.Active is left untouched (set). - - KVM clears the LR on VM exits when the physical distributor - active state has been cleared. - -(*): The host handling is slightly more complicated. For some forwarded -interrupts (shared), KVM directly sets the active state on the physical -distributor before entering the guest, because the interrupt is never actually -handled on the host (see details on the timer as an example below). For other -forwarded interrupts (non-shared) the host does not deactivate the interrupt -when the host ISR completes, but leaves the interrupt active until the guest -deactivates it. Leaving the interrupt active is allowed, because Linux -configures the physical GIC with EOIMode=1, which causes EOI operations to -perform a priority drop allowing the GIC to receive other interrupts of the -default priority. - - -Forwarded Edge and Level Triggered PPIs and SPIs ------------------------------------------------- -Forwarded physical interrupts injected should always be active on the -physical distributor when injected to a guest. - -Level-triggered interrupts will keep the interrupt line to the GIC -asserted, typically until the guest programs the device to deassert the -line. This means that the interrupt will remain pending on the physical -distributor until the guest has reprogrammed the device. Since we -always run the VM with interrupts enabled on the CPU, a pending -interrupt will exit the guest as soon as we switch into the guest, -preventing the guest from ever making progress as the process repeats -over and over. Therefore, the active state on the physical distributor -must be set when entering the guest, preventing the GIC from forwarding -the pending interrupt to the CPU. As soon as the guest deactivates the -interrupt, the physical line is sampled by the hardware again and the host -takes a new interrupt if and only if the physical line is still asserted. - -Edge-triggered interrupts do not exhibit the same problem with -preventing guest execution that level-triggered interrupts do. One -option is to not use HW bit at all, and inject edge-triggered interrupts -from a physical device as pure virtual interrupts. But that would -potentially slow down handling of the interrupt in the guest, because a -physical interrupt occurring in the middle of the guest ISR would -preempt the guest for the host to handle the interrupt. Additionally, -if you configure the system to handle interrupts on a separate physical -core from that running your VCPU, you still have to interrupt the VCPU -to queue the pending state onto the LR, even though the guest won't use -this information until the guest ISR completes. Therefore, the HW -bit should always be set for forwarded edge-triggered interrupts. With -the HW bit set, the virtual interrupt is injected and additional -physical interrupts occurring before the guest deactivates the interrupt -simply mark the state on the physical distributor as Pending+Active. As -soon as the guest deactivates the interrupt, the host takes another -interrupt if and only if there was a physical interrupt between injecting -the forwarded interrupt to the guest and the guest deactivating the -interrupt. - -Consequently, whenever we schedule a VCPU with one or more LRs with the -HW bit set, the interrupt must also be active on the physical -distributor. - - -Forwarded LPIs --------------- -LPIs, introduced in GICv3, are always edge-triggered and do not have an -active state. They become pending when a device signal them, and as -soon as they are acked by the CPU, they are inactive again. - -It therefore doesn't make sense, and is not supported, to set the HW bit -for physical LPIs that are forwarded to a VM as virtual interrupts, -typically virtual SPIs. - -For LPIs, there is no other choice than to preempt the VCPU thread if -necessary, and queue the pending state onto the LR. - - -Putting It Together: The Architected Timer ------------------------------------------- -The architected timer is a device that signals interrupts with level -triggered semantics. The timer hardware is directly accessed by VCPUs -which program the timer to fire at some point in time. Each VCPU on a -system programs the timer to fire at different times, and therefore the -hardware is multiplexed between multiple VCPUs. This is implemented by -context-switching the timer state along with each VCPU thread. - -However, this means that a scenario like the following is entirely -possible, and in fact, typical: - -1. KVM runs the VCPU -2. The guest programs the time to fire in T+100 -3. The guest is idle and calls WFI (wait-for-interrupts) -4. The hardware traps to the host -5. KVM stores the timer state to memory and disables the hardware timer -6. KVM schedules a soft timer to fire in T+(100 - time since step 2) -7. KVM puts the VCPU thread to sleep (on a waitqueue) -8. The soft timer fires, waking up the VCPU thread -9. KVM reprograms the timer hardware with the VCPU's values -10. KVM marks the timer interrupt as active on the physical distributor -11. KVM injects a forwarded physical interrupt to the guest -12. KVM runs the VCPU - -Notice that KVM injects a forwarded physical interrupt in step 11 without -the corresponding interrupt having actually fired on the host. That is -exactly why we mark the timer interrupt as active in step 10, because -the active state on the physical distributor is part of the state -belonging to the timer hardware, which is context-switched along with -the VCPU thread. - -If the guest does not idle because it is busy, the flow looks like this -instead: - -1. KVM runs the VCPU -2. The guest programs the time to fire in T+100 -4. At T+100 the timer fires and a physical IRQ causes the VM to exit - (note that this initially only traps to EL2 and does not run the host ISR - until KVM has returned to the host). -5. With interrupts still disabled on the CPU coming back from the guest, KVM - stores the virtual timer state to memory and disables the virtual hw timer. -6. KVM looks at the timer state (in memory) and injects a forwarded physical - interrupt because it concludes the timer has expired. -7. KVM marks the timer interrupt as active on the physical distributor -7. KVM enables the timer, enables interrupts, and runs the VCPU - -Notice that again the forwarded physical interrupt is injected to the -guest without having actually been handled on the host. In this case it -is because the physical interrupt is never actually seen by the host because the -timer is disabled upon guest return, and the virtual forwarded interrupt is -injected on the KVM guest entry path. -- cgit From d51b9dae2eb3b7b0c90dd0fd9ccd66d6934e9d8f Mon Sep 17 00:00:00 2001 From: Matt Roper Date: Fri, 29 Dec 2017 12:01:59 -0800 Subject: Documentation/cgroup-v1: fix outdated programming details The cgroup-v1 documentation is out of date in a few places: * cgroup controllers can no longer be compiled as modules since commit 3ed80a6 ("cgroup: drop module support"); the functions and fields referenced here no longer exist. * Controllers need to create of a cgroup_subsys object named "_cgrp_subsys" instead of "_subsys" since commit 073219e ("cgroup: clean up cgroup_subsys names and initialization") Cc: Tejun Heo Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Matt Roper Signed-off-by: Tejun Heo --- Documentation/cgroup-v1/cgroups.txt | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cgroup-v1/cgroups.txt b/Documentation/cgroup-v1/cgroups.txt index 308e5ff7207a..059f7063eea6 100644 --- a/Documentation/cgroup-v1/cgroups.txt +++ b/Documentation/cgroup-v1/cgroups.txt @@ -523,12 +523,7 @@ Accessing a task's cgroup pointer may be done in the following ways: Each subsystem should: - add an entry in linux/cgroup_subsys.h -- define a cgroup_subsys object called _subsys - -If a subsystem can be compiled as a module, it should also have in its -module initcall a call to cgroup_load_subsys(), and in its exitcall a -call to cgroup_unload_subsys(). It should also set its_subsys.module = -THIS_MODULE in its .c file. +- define a cgroup_subsys object called _cgrp_subsys Each subsystem may export the following methods. The only mandatory methods are css_alloc/free. Any others that are null are presumed to -- cgit From 83f4f3f63be2b2c4fc94e308a766859df2825f43 Mon Sep 17 00:00:00 2001 From: Jaehoon Chung Date: Wed, 27 Dec 2017 18:43:27 +0900 Subject: PCI: exynos: Remove deprecated PHY initialization code Exynos platforms have a PCI PHY driver in the PHY framework that can be used by the PCI host bridge drivers to initialize and manage the PHY. Remove the deprecated PHY initialization code in the Exynos PCI host bridge driver by updating the driver to use the PHY framework API; modify the DT binding documentation accordingly. Signed-off-by: Jaehoon Chung [lorenzo.pieralisi@arm.com: updated commit log] Signed-off-by: Lorenzo Pieralisi Acked-by: Jingoo Han Reviewed-by: Rob Herring --- .../bindings/pci/samsung,exynos5440-pcie.txt | 58 ++++------------------ 1 file changed, 11 insertions(+), 47 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt b/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt index 34a11bfbfb60..651d957d1051 100644 --- a/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt +++ b/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt @@ -6,9 +6,6 @@ and thus inherits all the common properties defined in designware-pcie.txt. Required properties: - compatible: "samsung,exynos5440-pcie" - reg: base addresses and lengths of the PCIe controller, - the PHY controller, additional register for the PHY controller. - (Registers for the PHY controller are DEPRECATED. - Use the PHY framework.) - reg-names : First name should be set to "elbi". And use the "config" instead of getting the configuration address space from "ranges". @@ -23,49 +20,8 @@ For other common properties, refer to Example: -SoC-specific DT Entry: +SoC-specific DT Entry (with using PHY framework): - pcie@290000 { - compatible = "samsung,exynos5440-pcie", "snps,dw-pcie"; - reg = <0x290000 0x1000 - 0x270000 0x1000 - 0x271000 0x40>; - interrupts = <0 20 0>, <0 21 0>, <0 22 0>; - clocks = <&clock 28>, <&clock 27>; - clock-names = "pcie", "pcie_bus"; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x00000800 0 0x40000000 0x40000000 0 0x00001000 /* configuration space */ - 0x81000000 0 0 0x40001000 0 0x00010000 /* downstream I/O */ - 0x82000000 0 0x40011000 0x40011000 0 0x1ffef000>; /* non-prefetchable memory */ - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; - num-lanes = <4>; - }; - - pcie@2a0000 { - compatible = "samsung,exynos5440-pcie", "snps,dw-pcie"; - reg = <0x2a0000 0x1000 - 0x272000 0x1000 - 0x271040 0x40>; - interrupts = <0 23 0>, <0 24 0>, <0 25 0>; - clocks = <&clock 29>, <&clock 27>; - clock-names = "pcie", "pcie_bus"; - #address-cells = <3>; - #size-cells = <2>; - device_type = "pci"; - ranges = <0x00000800 0 0x60000000 0x60000000 0 0x00001000 /* configuration space */ - 0x81000000 0 0 0x60001000 0 0x00010000 /* downstream I/O */ - 0x82000000 0 0x60011000 0x60011000 0 0x1ffef000>; /* non-prefetchable memory */ - #interrupt-cells = <1>; - interrupt-map-mask = <0 0 0 0>; - interrupt-map = <0 0 0 0 &gic GIC_SPI 24 IRQ_TYPE_LEVEL_HIGH>; - num-lanes = <4>; - }; - -With using PHY framework: pcie_phy0: pcie-phy@270000 { ... reg = <0x270000 0x1000>, <0x271000 0x40>; @@ -74,13 +30,21 @@ With using PHY framework: }; pcie@290000 { - ... + compatible = "samsung,exynos5440-pcie", "snps,dw-pcie"; reg = <0x290000 0x1000>, <0x40000000 0x1000>; reg-names = "elbi", "config"; + clocks = <&clock 28>, <&clock 27>; + clock-names = "pcie", "pcie_bus"; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; phys = <&pcie_phy0>; ranges = <0x81000000 0 0 0x60001000 0 0x00010000 0x82000000 0 0x60011000 0x60011000 0 0x1ffef000>; - ... + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 21 IRQ_TYPE_LEVEL_HIGH>; + num-lanes = <4>; }; Board-specific DT Entry: -- cgit From 2877cbe6501e20dd076c7677f768d50bcc87267b Mon Sep 17 00:00:00 2001 From: Vladimir Rutsky Date: Tue, 2 Jan 2018 17:27:41 +0100 Subject: cgroup-v2.txt: fix typos Signed-off-by: Vladimir Rutsky Signed-off-by: Tejun Heo --- Documentation/cgroup-v2.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index d6efabb487e3..c783bbb9d0fb 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -280,7 +280,7 @@ thread mode, the following conditions must be met. exempt from this requirement. Topology-wise, a cgroup can be in an invalid state. Please consider -the following toplogy:: +the following topology:: A (threaded domain) - B (threaded) - C (domain, just created) @@ -1064,10 +1064,10 @@ PAGE_SIZE multiple when read back. reached the limit and allocation was about to fail. Depending on context result could be invocation of OOM - killer and retrying allocation or failing alloction. + killer and retrying allocation or failing allocation. Failed allocation in its turn could be returned into - userspace as -ENOMEM or siletly ignored in cases like + userspace as -ENOMEM or silently ignored in cases like disk readahead. For now OOM in memory cgroup kills tasks iff shortage has happened inside page fault. @@ -1192,7 +1192,7 @@ PAGE_SIZE multiple when read back. cgroups. The default is "max". Swap usage hard limit. If a cgroup's swap usage reaches this - limit, anonymous meomry of the cgroup will not be swapped out. + limit, anonymous memory of the cgroup will not be swapped out. Usage Guidelines -- cgit From 9249dee611d6624bc9044fdf3877ace67d6143ab Mon Sep 17 00:00:00 2001 From: Suzuki K Poulose Date: Tue, 2 Jan 2018 11:25:32 +0000 Subject: dt-bindings: Document devicetree binding for ARM DSU PMU This patch documents the devicetree bindings for ARM DSU PMU. Cc: Mark Rutland Cc: Will Deacon Cc: devicetree@vger.kernel.org Cc: frowand.list@gmail.com Acked-by: Rob Herring Signed-off-by: Suzuki K Poulose Signed-off-by: Will Deacon --- .../devicetree/bindings/arm/arm-dsu-pmu.txt | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt b/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt new file mode 100644 index 000000000000..6efabba530f1 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/arm-dsu-pmu.txt @@ -0,0 +1,27 @@ +* ARM DynamIQ Shared Unit (DSU) Performance Monitor Unit (PMU) + +ARM DyanmIQ Shared Unit (DSU) integrates one or more CPU cores +with a shared L3 memory system, control logic and external interfaces to +form a multicore cluster. The PMU enables to gather various statistics on +the operations of the DSU. The PMU provides independent 32bit counters that +can count any of the supported events, along with a 64bit cycle counter. +The PMU is accessed via CPU system registers and has no MMIO component. + +** DSU PMU required properties: + +- compatible : should be one of : + + "arm,dsu-pmu" + +- interrupts : Exactly 1 SPI must be listed. + +- cpus : List of phandles for the CPUs connected to this DSU instance. + + +** Example: + +dsu-pmu-0 { + compatible = "arm,dsu-pmu"; + interrupts = ; + cpus = <&cpu_0>, <&cpu_1>; +}; -- cgit From 7520fa99246dade7ab6dde1573a146beed632abd Mon Sep 17 00:00:00 2001 From: Suzuki K Poulose Date: Tue, 2 Jan 2018 11:25:33 +0000 Subject: perf: ARM DynamIQ Shared Unit PMU support Add support for the Cluster PMU part of the ARM DynamIQ Shared Unit (DSU). The DSU integrates one or more cores with an L3 memory system, control logic, and external interfaces to form a multicore cluster. The PMU allows counting the various events related to L3, SCU etc, along with providing a cycle counter. The PMU can be accessed via system registers, which are common to the cores in the same cluster. The PMU registers follow the semantics of the ARMv8 PMU, mostly, with the exception that the counters record the cluster wide events. This driver is mostly based on the ARMv8 and CCI PMU drivers. The driver only supports ARM64 at the moment. It can be extended to support ARM32 by providing register accessors like we do in arch/arm64/include/arm_dsu_pmu.h. Cc: Mark Rutland Cc: Will Deacon Reviewed-by: Jonathan Cameron Reviewed-by: Mark Rutland Signed-off-by: Suzuki K Poulose Signed-off-by: Will Deacon --- Documentation/perf/arm_dsu_pmu.txt | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 Documentation/perf/arm_dsu_pmu.txt (limited to 'Documentation') diff --git a/Documentation/perf/arm_dsu_pmu.txt b/Documentation/perf/arm_dsu_pmu.txt new file mode 100644 index 000000000000..d611e15f5add --- /dev/null +++ b/Documentation/perf/arm_dsu_pmu.txt @@ -0,0 +1,28 @@ +ARM DynamIQ Shared Unit (DSU) PMU +================================== + +ARM DynamIQ Shared Unit integrates one or more cores with an L3 memory system, +control logic and external interfaces to form a multicore cluster. The PMU +allows counting the various events related to the L3 cache, Snoop Control Unit +etc, using 32bit independent counters. It also provides a 64bit cycle counter. + +The PMU can only be accessed via CPU system registers and are common to the +cores connected to the same DSU. Like most of the other uncore PMUs, DSU +PMU doesn't support process specific events and cannot be used in sampling mode. + +The DSU provides a bitmap for a subset of implemented events via hardware +registers. There is no way for the driver to determine if the other events +are available or not. Hence the driver exposes only those events advertised +by the DSU, in "events" directory under : + + /sys/bus/event_sources/devices/arm_dsu_/ + +The user should refer to the TRM of the product to figure out the supported events +and use the raw event code for the unlisted events. + +The driver also exposes the CPUs connected to the DSU instance in "associated_cpus". + + +e.g usage : + + perf stat -a -e arm_dsu_0/cycles/ -- cgit From 6da28acf745fe2537d77b9044f78a2a4e100c773 Mon Sep 17 00:00:00 2001 From: Bartosz Golaszewski Date: Thu, 28 Dec 2017 11:49:10 +0100 Subject: dt-bindings: at24: consistently document the compatible property Current description of the compatible property for at24 is quite vague. State explicitly that any "," pair is accepted as long as a correct fallback is used for non-atmel chips. Signed-off-by: Bartosz Golaszewski Reviewed-by: Rob Herring --- Documentation/devicetree/bindings/eeprom/at24.txt | 58 ++++++++++++++--------- 1 file changed, 36 insertions(+), 22 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index cbc80e194ac6..5ac18ce2e8cd 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -2,28 +2,42 @@ EEPROMs (I2C) Required properties: - - compatible : should be ",", like these: - - "atmel,24c00", "atmel,24c01", "atmel,24c02", "atmel,24c04", - "atmel,24c08", "atmel,24c16", "atmel,24c32", "atmel,24c64", - "atmel,24c128", "atmel,24c256", "atmel,24c512", "atmel,24c1024" - - "catalyst,24c32" - - "microchip,24c128" - - "ramtron,24c64" - - "renesas,r1ex24002" - - The following manufacturers values have been deprecated: - "at", "at24" - - If there is no specific driver for , a generic - device with and manufacturer "atmel" should be used. - Possible types are: - "24c00", "24c01", "24c02", "24c04", "24c08", "24c16", "24c32", "24c64", - "24c128", "24c256", "24c512", "24c1024", "spd" + - compatible: Must be a "," pair. The following + values are supported (assuming "atmel" as manufacturer): + + "atmel,24c00", + "atmel,24c01", + "atmel,24c02", + "atmel,spd", + "atmel,24c04", + "atmel,24c08", + "atmel,24c16", + "atmel,24c32", + "atmel,24c64", + "atmel,24c128", + "atmel,24c256", + "atmel,24c512", + "atmel,24c1024", + + If is not "atmel", then a fallback must be used + with the same and "atmel" as manufacturer. + + Example: + compatible = "microchip,24c128", "atmel,24c128"; + + Supported manufacturers are: + + "catalyst", + "microchip", + "ramtron", + "renesas", + "nxp", + "st", + + Some vendors use different model names for chips which are just + variants of the above. Known such exceptions are listed below: + + "renesas,r1ex24002" - the fallback is "atmel,24c02" - reg : the I2C address of the EEPROM -- cgit From e32a1f30b67521335aa1869263bf9220b5df2b83 Mon Sep 17 00:00:00 2001 From: Bartosz Golaszewski Date: Thu, 28 Dec 2017 11:49:11 +0100 Subject: dt-bindings: at24: fix formatting and style Make formatting and style consistent for the entire document. This patch doesn't change the content of the binding. Signed-off-by: Bartosz Golaszewski Reviewed-by: Javier Martinez Canillas Reviewed-by: Rob Herring --- Documentation/devicetree/bindings/eeprom/at24.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index 5ac18ce2e8cd..07a289ba831d 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -39,23 +39,23 @@ Required properties: "renesas,r1ex24002" - the fallback is "atmel,24c02" - - reg : the I2C address of the EEPROM + - reg: The I2C address of the EEPROM. Optional properties: - - pagesize : the length of the pagesize for writing. Please consult the - manual of your device, that value varies a lot. A wrong value - may result in data loss! If not specified, a safety value of - '1' is used which will be very slow. + - pagesize: The length of the pagesize for writing. Please consult the + manual of your device, that value varies a lot. A wrong value + may result in data loss! If not specified, a safety value of + '1' is used which will be very slow. - - read-only: this parameterless property disables writes to the eeprom + - read-only: This parameterless property disables writes to the eeprom. - - size: total eeprom size in bytes + - size: Total eeprom size in bytes. - - no-read-rollover: - This parameterless property indicates that the multi-address - eeprom does not automatically roll over reads to the next - slave address. Please consult the manual of your device. + - no-read-rollover: This parameterless property indicates that the + multi-address eeprom does not automatically roll over + reads to the next slave address. Please consult the + manual of your device. - wp-gpios: GPIO to which the write-protect pin of the chip is connected. -- cgit From e36820425f699e4a4ebefb583df6308d6749eef3 Mon Sep 17 00:00:00 2001 From: Bartosz Golaszewski Date: Thu, 28 Dec 2017 11:49:12 +0100 Subject: dt-bindings: at24: extend the list of supported chips Add other variants of at24 EEPROMs we support in the driver to the list of allowed compatible fallbacks. Signed-off-by: Bartosz Golaszewski Reviewed-by: Javier Martinez Canillas Reviewed-by: Rob Herring --- Documentation/devicetree/bindings/eeprom/at24.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index 07a289ba831d..1812c848e369 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -7,13 +7,22 @@ Required properties: "atmel,24c00", "atmel,24c01", + "atmel,24cs01", "atmel,24c02", + "atmel,24cs02", + "atmel,24mac402", + "atmel,24mac602", "atmel,spd", "atmel,24c04", + "atmel,24cs04", "atmel,24c08", + "atmel,24cs08", "atmel,24c16", + "atmel,24cs16", "atmel,24c32", + "atmel,24cs32", "atmel,24c64", + "atmel,24cs64", "atmel,24c128", "atmel,24c256", "atmel,24c512", -- cgit From 0c6ab1b8f8940d4ddbfff7ddff080cbfb5f32b02 Mon Sep 17 00:00:00 2001 From: Georgi Djakov Date: Tue, 5 Dec 2017 17:46:58 +0200 Subject: clk: qcom: Add A53 PLL support The CPUs on Qualcomm MSM8916-based platforms are clocked by two PLLs, a primary (A53) CPU PLL and a secondary fixed-rate GPLL0. These sources are connected to a mux and half-integer divider, which is feeding the CPU cores. This patch adds support for the primary CPU PLL which generates the higher range of frequencies above 1GHz. Signed-off-by: Georgi Djakov Acked-by: Bjorn Andersson Tested-by: Amit Kucheria [sboyd@codeaurora.org: Move to devm provider registration, NUL terminate frequency table, made tristate/modular] Signed-off-by: Stephen Boyd --- .../devicetree/bindings/clock/qcom,a53pll.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 Documentation/devicetree/bindings/clock/qcom,a53pll.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/clock/qcom,a53pll.txt b/Documentation/devicetree/bindings/clock/qcom,a53pll.txt new file mode 100644 index 000000000000..e3fa8118eaee --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,a53pll.txt @@ -0,0 +1,22 @@ +Qualcomm MSM8916 A53 PLL Binding +-------------------------------- +The A53 PLL on MSM8916 platforms is the main CPU PLL used used for frequencies +above 1GHz. + +Required properties : +- compatible : Shall contain only one of the following: + + "qcom,msm8916-a53pll" + +- reg : shall contain base register location and length + +- #clock-cells : must be set to <0> + +Example: + + a53pll: clock@b016000 { + compatible = "qcom,msm8916-a53pll"; + reg = <0xb016000 0x40>; + #clock-cells = <0>; + }; + -- cgit From f6df8f234e2502b7d8c6de42e066e01f908318cc Mon Sep 17 00:00:00 2001 From: Sheng Yong Date: Wed, 22 Nov 2017 18:23:38 +0800 Subject: f2fs: introduce sysfs readdir_ra to readahead inode block in readdir This patch introduces a sysfs interface readdir_ra to enable/disable readaheading inode block in f2fs_readdir. When readdir_ra is enabled, it improves the performance of "readdir + stat". For 300,000 files: time find /data/test > /dev/null disable readdir_ra: 1m25.69s real 0m01.94s user 0m50.80s system enable readdir_ra: 0m18.55s real 0m00.44s user 0m15.39s system Signed-off-by: Sheng Yong Reviewed-by: Chao Yu Signed-off-by: Jaegeuk Kim --- Documentation/ABI/testing/sysfs-fs-f2fs | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index a7799c2fca28..d870b5514d15 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -186,3 +186,9 @@ Date: August 2017 Contact: "Jaegeuk Kim" Description: Controls sleep time of GC urgent mode + +What: /sys/fs/f2fs//readdir_ra +Date: November 2017 +Contact: "Sheng Yong" +Description: + Controls readahead inode block in readdir. -- cgit From d3151583b070a6d7f4be13ce7e36e1dc3fa91413 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Thu, 21 Dec 2017 12:33:05 -0600 Subject: dt-bindings: Add "vot" vendor prefix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds a vendor prefix "vot" for Vision Optical Technology Co., Ltd. They make LCD displays. Signed-off-by: David Lechner Reviewed-by: Rob Herring Signed-off-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/1513881187-3197-2-git-send-email-david@lechnology.com --- Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 41cb1ff07150..267d33bd9a77 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -380,6 +380,7 @@ virtio Virtual I/O Device Specification, developed by the OASIS consortium vivante Vivante Corporation vocore VoCore Studio voipac Voipac Technologies s.r.o. +vot Vision Optical Technology Co., Ltd. wd Western Digital Corp. wetek WeTek Electronics, limited. wexler Wexler -- cgit From fe5b66c123ac43c1d7a2f686de8ba04e4723de72 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Thu, 21 Dec 2017 12:33:06 -0600 Subject: dt-bindings: update compatible string for ILI9225 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This updates the compatible string for a no-name LCD panel to "vot,v220hf01a-t", "ilitek,ili9225". The original bindings [1] were the generic "ilitek,ili9225-2.2in-176x220" because I could not find a datasheet. However, after some more research, I finally found one, so the actual vendor and model name are now known. This previous bindings have not made it to the mainline kernel yet, so this is not breaking backwards compatibility. This is also following the precedence of the ILI9322 bindings [2] by using the pattern "vendor,specific-system-config", "vendor,ip-part"; [1]: https://patchwork.ozlabs.org/patch/839352/ [2]: https://patchwork.ozlabs.org/patch/843576/ Signed-off-by: David Lechner Reviewed-by: Rob Herring Signed-off-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/1513881187-3197-3-git-send-email-david@lechnology.com --- Documentation/devicetree/bindings/display/ilitek,ili9225.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/ilitek,ili9225.txt b/Documentation/devicetree/bindings/display/ilitek,ili9225.txt index 21607a541c33..a59feb52015b 100644 --- a/Documentation/devicetree/bindings/display/ilitek,ili9225.txt +++ b/Documentation/devicetree/bindings/display/ilitek,ili9225.txt @@ -4,7 +4,7 @@ This binding is for display panels using an Ilitek ILI9225 controller in SPI mode. Required properties: -- compatible: "ilitek,ili9225-2.2in-176x220" +- compatible: "vot,v220hf01a-t", "ilitek,ili9225" - rs-gpios: Register select signal - reset-gpios: Reset pin @@ -16,7 +16,7 @@ Optional properties: Example: display@0{ - compatible = "ilitek,ili9225-2.2in-176x220"; + compatible = "vot,v220hf01a-t", "ilitek,ili9225"; reg = <0>; spi-max-frequency = <12000000>; rs-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>; -- cgit From 95e2ce7b423bedbf575aca26c5e0a55678a914e6 Mon Sep 17 00:00:00 2001 From: David Lechner Date: Mon, 1 Jan 2018 13:02:14 -0600 Subject: dt-bindings: add jianda vendor prefix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds a vendor prefix "jianda" for Jiandangjing Technology Co., Ltd. Signed-off-by: David Lechner Reviewed-by: Rob Herring Signed-off-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/1514833336-22564-2-git-send-email-david@lechnology.com --- Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 267d33bd9a77..159dc5c075c2 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -173,6 +173,7 @@ itead ITEAD Intelligent Systems Co.Ltd iwave iWave Systems Technologies Pvt. Ltd. jdi Japan Display Inc. jedec JEDEC Solid State Technology Association +jianda Jiandangjing Technology Co., Ltd. karo Ka-Ro electronics GmbH keithkoep Keith & Koep GmbH keymile Keymile GmbH -- cgit From 634ab311fca6f864f5ce5b887ae8a55e238c1dea Mon Sep 17 00:00:00 2001 From: David Lechner Date: Mon, 1 Jan 2018 13:02:15 -0600 Subject: dt-bindings: Add binding for Sitronix ST7735R display panels MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds a new device tree binding for Sitronix ST7735R display panels, such as the Adafruit 1.8" TFT. Signed-off-by: David Lechner Reviewed-by: Rob Herring Reviewed-by: Linus Walleij Signed-off-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/1514833336-22564-3-git-send-email-david@lechnology.com --- .../bindings/display/sitronix,st7735r.txt | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 Documentation/devicetree/bindings/display/sitronix,st7735r.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/sitronix,st7735r.txt b/Documentation/devicetree/bindings/display/sitronix,st7735r.txt new file mode 100644 index 000000000000..f0a5090a3326 --- /dev/null +++ b/Documentation/devicetree/bindings/display/sitronix,st7735r.txt @@ -0,0 +1,35 @@ +Sitronix ST7735R display panels + +This binding is for display panels using a Sitronix ST7735R controller in SPI +mode. + +Required properties: +- compatible: "jianda,jd-t18003-t01", "sitronix,st7735r" +- dc-gpios: Display data/command selection (D/CX) +- reset-gpios: Reset signal (RSTX) + +The node for this driver must be a child node of a SPI controller, hence +all mandatory properties described in ../spi/spi-bus.txt must be specified. + +Optional properties: +- rotation: panel rotation in degrees counter clockwise (0,90,180,270) +- backlight: phandle of the backlight device attached to the panel + +Example: + + backlight: backlight { + compatible = "gpio-backlight"; + gpios = <&gpio 44 GPIO_ACTIVE_HIGH>; + } + + ... + + display@0{ + compatible = "jianda,jd-t18003-t01", "sitronix,st7735r"; + reg = <0>; + spi-max-frequency = <32000000>; + dc-gpios = <&gpio 43 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 80 GPIO_ACTIVE_HIGH>; + rotation = <270>; + backlight = &backlight; + }; -- cgit From 0578c660b7ea620f60e8c2845dbc3ce85cecb5b8 Mon Sep 17 00:00:00 2001 From: Jun Gao Date: Tue, 19 Dec 2017 14:51:01 +0800 Subject: dt-bindings: i2c: Add MediaTek MT2712 i2c binding Add MT2712 i2c binding to binding file. Compare to MT8173 i2c controller, MT2712 has timing adjust registers which can adjust the internal divider of i2c source clock, SCL duty cycle, SCL compare point, start(repeated start) and stop time, SDA change time. Signed-off-by: Jun Gao Reviewed-by: Rob Herring Signed-off-by: Wolfram Sang --- Documentation/devicetree/bindings/i2c/i2c-mtk.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt index ff7bf37deb43..e199695b1c96 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt @@ -5,6 +5,7 @@ The MediaTek's I2C controller is used to interface with I2C devices. Required properties: - compatible: value should be either of the following. "mediatek,mt2701-i2c", "mediatek,mt6577-i2c": for MediaTek MT2701 + "mediatek,mt2712-i2c": for MediaTek MT2712 "mediatek,mt6577-i2c": for MediaTek MT6577 "mediatek,mt6589-i2c": for MediaTek MT6589 "mediatek,mt7622-i2c": for MediaTek MT7622 -- cgit From 563a01e1012dddbe120d1e1e1c466ea0639a098b Mon Sep 17 00:00:00 2001 From: Guennadi Liakhovetski Date: Wed, 8 Nov 2017 11:00:12 -0500 Subject: media: v4l: Add a UVC Metadata format Add a pixel format, used by the UVC driver to stream metadata. Signed-off-by: Guennadi Liakhovetski Signed-off-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/meta-formats.rst | 1 + Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst | 51 ++++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst (limited to 'Documentation') diff --git a/Documentation/media/uapi/v4l/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst index 01e24e3df571..0c4e1ecf5879 100644 --- a/Documentation/media/uapi/v4l/meta-formats.rst +++ b/Documentation/media/uapi/v4l/meta-formats.rst @@ -12,5 +12,6 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 + pixfmt-meta-uvc pixfmt-meta-vsp1-hgo pixfmt-meta-vsp1-hgt diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst b/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst new file mode 100644 index 000000000000..b5165dc090c2 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst @@ -0,0 +1,51 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-meta-fmt-uvc: + +******************************* +V4L2_META_FMT_UVC ('UVCH') +******************************* + +UVC Payload Header Data + + +Description +=========== + +This format describes standard UVC metadata, extracted from UVC packet headers +and provided by the UVC driver through metadata video nodes. That data includes +exact copies of the standard part of UVC Payload Header contents and auxiliary +timing information, required for precise interpretation of timestamps, contained +in those headers. See section "2.4.3.3 Video and Still Image Payload Headers" of +the "UVC 1.5 Class specification" for details. + +Each UVC payload header can be between 2 and 12 bytes large. Buffers can +contain multiple headers, if multiple such headers have been transmitted by the +camera for the respective frame. However, the driver may drop headers when the +buffer is full, when they contain no useful information (e.g. those without the +SCR field or with that field identical to the previous header), or generally to +perform rate limiting when the device sends a large number of headers. + +Each individual block contains the following fields: + +.. flat-table:: UVC Metadata Block + :widths: 1 4 + :header-rows: 1 + :stub-columns: 0 + + * - Field + - Description + * - __u64 ts; + - system timestamp in host byte order, measured by the driver upon + reception of the payload + * - __u16 sof; + - USB Frame Number in host byte order, also obtained by the driver as + close as possible to the above timestamp to enable correlation between + them + * - :cspan:`1` *The rest is an exact copy of the UVC payload header:* + * - __u8 length; + - length of the rest of the block, including this field + * - __u8 flags; + - Flags, indicating presence of other standard UVC fields + * - __u8 buf[]; + - The rest of the header, possibly including UVC PTS and SCR fields -- cgit From cca10d58d25d271f05e1115132b4c2d913bb652e Mon Sep 17 00:00:00 2001 From: Sergey Senozhatsky Date: Thu, 21 Dec 2017 14:41:49 +0900 Subject: printk: add console_msg_format command line option 0day and kernelCI automatically parse kernel log - basically some sort of grepping using the pre-defined text patterns - in order to detect and report regressions/errors. There are several sources they get the kernel logs from: a) dmesg or /proc/ksmg This is the preferred way. Because `dmesg --raw' (see later Note) and /proc/kmsg output contains facility and log level, which greatly simplifies grepping for EMERG/ALERT/CRIT/ERR messages. b) serial consoles This option is harder to maintain, because serial console messages don't contain facility and log level. This patch introduces a `console_msg_format=' command line option, to switch between different message formatting on serial consoles. For the time being we have just two options - default and syslog. The "default" option just keeps the existing format. While the "syslog" option makes serial console messages to appear in syslog format [syslog() syscall], matching the `dmesg -S --raw' and `cat /proc/kmsg' output formats: - facility and log level - time stamp (depends on printk_time/PRINTK_TIME) - message <%u>[time stamp] text\n NOTE: while Kevin and Fengguang talk about "dmesg --raw", it's actually "dmesg -S --raw" that always prints messages in syslog format [per Petr Mladek]. Running "dmesg --raw" may produce output in non-syslog format sometimes. console_msg_format=syslog enables syslog format, thus in documentation we mention "dmesg -S --raw", not "dmesg --raw". Per Kevin Hilman: : Right now we can get this info from a "dmesg --raw" after bootup, : but it would be really nice in certain automation frameworks to : have a kernel command-line option to enable printing of loglevels : in default boot log. : : This is especially useful when ingesting kernel logs into advanced : search/analytics frameworks (I'm playing with and ELK stack: Elastic : Search, Logstash, Kibana). : : The other important reason for having this on the command line is that : for testing linux-next (and other bleeding edge developer branches), : it's common that we never make it to userspace, so can't even run : "dmesg --raw" (or equivalent.) So we really want this on the primary : boot (serial) console. Per Fengguang Wu, 0day scripts should quickly benefit from that feature, because they will be able to switch to a more reliable parsing, based on messages' facility and log levels [1]: `#{grep} -a -E -e '^<[0123]>' -e '^kern :(err |crit |alert |emerg )' instead of doing text pattern matching `#{grep} -a -F -f /lkp/printk-error-messages #{kmsg_file} | grep -a -v -E -f #{LKP_SRC}/etc/oops-pattern | grep -a -v -F -f #{LKP_SRC}/etc/kmsg-blacklist` [1] https://github.com/fengguang/lkp-tests/blob/master/lib/dmesg.rb Link: http://lkml.kernel.org/r/20171221054149.4398-1-sergey.senozhatsky@gmail.com To: Steven Rostedt Cc: Linus Torvalds Cc: Fengguang Wu Cc: Kevin Hilman Cc: Mark Brown Cc: Greg Kroah-Hartman Cc: Andrew Morton Cc: LKML Signed-off-by: Sergey Senozhatsky Reviewed-by: Fengguang Wu Reviewed-by: Kevin Hilman Tested-by: Kevin Hilman Signed-off-by: Petr Mladek --- Documentation/admin-guide/kernel-parameters.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'Documentation') diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 62436bd5f34a..af614995b71d 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -640,6 +640,20 @@ console=brl,ttyS0 For now, only VisioBraille is supported. + console_msg_format= + [KNL] Change console messages format + default + By default we print messages on consoles in + "[time stamp] text\n" format (time stamp may not be + printed, depending on CONFIG_PRINTK_TIME or + `printk_time' param). + syslog + Switch to syslog format: "<%u>[time stamp] text\n" + IOW, each message will have a facility and loglevel + prefix. The format is similar to one used by syslog() + syscall, or to executing "dmesg -S --raw" or to reading + from /proc/kmsg. + consoleblank= [KNL] The console blank (screen saver) timeout in seconds. A value of 0 disables the blank timer. Defaults to 0. -- cgit From 71b03a96ffe24bd295fff3197ff7f5fc230ce2e2 Mon Sep 17 00:00:00 2001 From: Maxime Ripard Date: Thu, 21 Dec 2017 12:02:29 +0100 Subject: dt-bindings: display: sun4i-drm: Add LVDS properties Some clocks and resets supposed to drive the LVDS logic in the display engine have been overlooked when the driver was first introduced. Add those additional resources to the binding, and we'll deal with the ABI stability in the code. Reviewed-by: Chen-Yu Tsai Reviewed-by: Rob Herring Signed-off-by: Maxime Ripard Link: https://patchwork.freedesktop.org/patch/msgid/ddbde28fe2e4f21412974e4c69fbfe1c5ff9383f.1513854122.git-series.maxime.ripard@free-electrons.com --- Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt index 50cc72ee1168..238876cef077 100644 --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt +++ b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt @@ -121,6 +121,14 @@ Required properties: On SoCs other than the A33 and V3s, there is one more clock required: - 'tcon-ch1': The clock driving the TCON channel 1 +On SoCs that support LVDS (all SoCs but the A13, H3, H5 and V3s), you +need one more reset line: + - 'lvds': The reset line driving the LVDS logic + +And on the A23, A31, A31s and A33, you need one more clock line: + - 'lvds-alt': An alternative clock source, separate from the TCON channel 0 + clock, that can be used to drive the LVDS clock + DRC --- -- cgit From 104fe24a5f9361e5a30733a5c127e84879bd362d Mon Sep 17 00:00:00 2001 From: Maxime Ripard Date: Thu, 21 Dec 2017 12:02:30 +0100 Subject: dt-bindings: display: sun4i-drm: Add A83T pipeline The A83T has two video pipelines in parallel that looks quite similar to the other SoCs. The video planes are handled through a controller called the mixer, and the video signal is then passed to the timing controller (TCON). And while there is two instances of the mixers and TCONs, they have a significant number of differences. The TCONs are quite easy to deal with, one is supposed to generate TV (in the broader term, so including things like HDMI) signals, the other one LCD (so RGB, LVDS, DSI) signals. And while they are called TCON0 and TCON1 in the A83t datasheet, newer SoCs call them TCON-TV and TCON-LCD, which seems more appropriate. However, the mixers differ mostly by their capabilities, with some features being available only in the first one, or the number of planes they expose, but also through their register layout. And while the capabilities could be represented as properties, the register layout differences would need to express all the registers offsets as properties, which is usually quite bad. Especially since documentation on that hardware block is close to non-existent and we don't even have the list of all those registers in the first place. So let's call them mixer 0 and 1 in our compatibles, even though the name is pretty bad... At the moment, we only have tested the code on a board that has a single display output, so we're leaving the tcon-tv and mixer1 out. Reviewed-by: Rob Herring Reviewed-by: Chen-Yu Tsai Signed-off-by: Maxime Ripard Link: https://patchwork.freedesktop.org/patch/msgid/2702a5c1d224af1c51743492ad1b917966f2ad43.1513854122.git-series.maxime.ripard@free-electrons.com --- Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt index 238876cef077..cd626ee1147a 100644 --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt +++ b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt @@ -93,6 +93,7 @@ Required properties: * allwinner,sun6i-a31s-tcon * allwinner,sun7i-a20-tcon * allwinner,sun8i-a33-tcon + * allwinner,sun8i-a83t-tcon-lcd * allwinner,sun8i-v3s-tcon - reg: base address and size of memory-mapped region - interrupts: interrupt associated to this IP @@ -224,6 +225,7 @@ supported. Required properties: - compatible: value must be one of: + * allwinner,sun8i-a83t-de2-mixer-0 * allwinner,sun8i-v3s-de2-mixer - reg: base address and size of the memory-mapped region. - clocks: phandles to the clocks feeding the mixer @@ -253,6 +255,7 @@ Required properties: * allwinner,sun6i-a31s-display-engine * allwinner,sun7i-a20-display-engine * allwinner,sun8i-a33-display-engine + * allwinner,sun8i-a83t-display-engine * allwinner,sun8i-v3s-display-engine - allwinner,pipelines: list of phandle to the display engine -- cgit From 2e7e2ebc68979d984c99c29be0e1af390a49b48c Mon Sep 17 00:00:00 2001 From: Maxime Ripard Date: Thu, 21 Dec 2017 12:02:27 +0100 Subject: dt-bindings: panel: lvds: Document power-supply property The power-supply property is used by a vast majority of panels, including panel-simple. Let's document it as a common property Acked-by: Laurent Pinchart Reviewed-by: Rob Herring Signed-off-by: Maxime Ripard Link: https://patchwork.freedesktop.org/patch/msgid/0a6a3abcf1a6b7f0e66a81af8a44c5c0566ce06c.1513854122.git-series.maxime.ripard@free-electrons.com --- .../devicetree/bindings/display/panel/panel-common.txt | 10 ++++++++++ Documentation/devicetree/bindings/display/panel/panel-lvds.txt | 1 + .../devicetree/bindings/display/panel/simple-panel.txt | 2 +- 3 files changed, 12 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.txt b/Documentation/devicetree/bindings/display/panel/panel-common.txt index ec52c472c845..557fa765adcb 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-common.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-common.txt @@ -78,6 +78,16 @@ used for panels that implement compatible control signals. while active. Active high reset signals can be supported by inverting the GPIO specifier polarity flag. +Power +----- + +- power-supply: display panels require power to be supplied. While several + panels need more than one power supply with panel-specific constraints + governing the order and timings of the power supplies, in many cases a single + power supply is sufficient, either because the panel has a single power rail, + or because all its power rails can be driven by the same supply. In that case + the power-supply property specifies the supply powering the panel as a phandle + to a regulator. Backlight --------- diff --git a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt index b938269f841e..250850a2150b 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-lvds.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-lvds.txt @@ -32,6 +32,7 @@ Optional properties: - label: See panel-common.txt. - gpios: See panel-common.txt. - backlight: See panel-common.txt. +- power-supply: See panel-common.txt. - data-mirror: If set, reverse the bit order described in the data mappings below on all data lanes, transmitting bits for slots 6 to 0 instead of 0 to 6. diff --git a/Documentation/devicetree/bindings/display/panel/simple-panel.txt b/Documentation/devicetree/bindings/display/panel/simple-panel.txt index 1341bbf4aa3d..16d8ff088b7d 100644 --- a/Documentation/devicetree/bindings/display/panel/simple-panel.txt +++ b/Documentation/devicetree/bindings/display/panel/simple-panel.txt @@ -1,7 +1,7 @@ Simple display panel Required properties: -- power-supply: regulator to provide the supply voltage +- power-supply: See panel-common.txt Optional properties: - ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing -- cgit From 3b3b681097fae73b7f5dcdd42db6cfdf32943d4c Mon Sep 17 00:00:00 2001 From: Dongjiu Geng Date: Wed, 13 Dec 2017 18:13:56 +0800 Subject: arm64: v8.4: Support for new floating point multiplication instructions ARM v8.4 extensions add new neon instructions for performing a multiplication of each FP16 element of one vector with the corresponding FP16 element of a second vector, and to add or subtract this without an intermediate rounding to the corresponding FP32 element in a third vector. This patch detects this feature and let the userspace know about it via a HWCAP bit and MRS emulation. Cc: Dave Martin Reviewed-by: Suzuki K Poulose Signed-off-by: Dongjiu Geng Reviewed-by: Dave Martin Signed-off-by: Catalin Marinas --- Documentation/arm64/cpu-feature-registers.txt | 4 +++- Documentation/arm64/elf_hwcaps.txt | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.txt index bd9b3faab2c4..a70090b28b07 100644 --- a/Documentation/arm64/cpu-feature-registers.txt +++ b/Documentation/arm64/cpu-feature-registers.txt @@ -110,7 +110,9 @@ infrastructure: x--------------------------------------------------x | Name | bits | visible | |--------------------------------------------------| - | RES0 | [63-48] | n | + | RES0 | [63-52] | n | + |--------------------------------------------------| + | FHM | [51-48] | y | |--------------------------------------------------| | DP | [47-44] | y | |--------------------------------------------------| diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt index 89edba12a9e0..57324ee55ecc 100644 --- a/Documentation/arm64/elf_hwcaps.txt +++ b/Documentation/arm64/elf_hwcaps.txt @@ -158,3 +158,7 @@ HWCAP_SHA512 HWCAP_SVE Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001. + +HWCAP_ASIMDFHM + + Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001. -- cgit From 33314a1387009361e6cfcfaa772abe3b90d11321 Mon Sep 17 00:00:00 2001 From: Simon Horman Date: Tue, 2 Jan 2018 10:56:32 +0100 Subject: dt-bindings: h8300 clocksource: correct spelling of pulse Correct what appears to be a typo in the spelling of pulse. Signed-off-by: Simon Horman Signed-off-by: Rob Herring --- Documentation/devicetree/bindings/timer/renesas,tpu.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/timer/renesas,tpu.txt b/Documentation/devicetree/bindings/timer/renesas,tpu.txt index f8b25897fb31..1d46f9de4feb 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tpu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tpu.txt @@ -1,4 +1,4 @@ -* Renesas H8/300 Timer Pluse Unit +* Renesas H8/300 Timer Pulse Unit The TPU is a 16bit timer/counter with configurable clock inputs and programmable compare match. -- cgit From 24538cc77ca9439991ae6a1a233272578fdfb823 Mon Sep 17 00:00:00 2001 From: Wenyou Yang Date: Sun, 10 Dec 2017 20:31:45 -0500 Subject: media: ov7740: Document device tree bindings Add the device tree binding documentation for the ov7740 sensor driver. Signed-off-by: Wenyou Yang Acked-by: Rob Herring Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- .../devicetree/bindings/media/i2c/ov7740.txt | 47 ++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 Documentation/devicetree/bindings/media/i2c/ov7740.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/ov7740.txt b/Documentation/devicetree/bindings/media/i2c/ov7740.txt new file mode 100644 index 000000000000..af781c3a5f0e --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ov7740.txt @@ -0,0 +1,47 @@ +* Omnivision OV7740 CMOS image sensor + +The Omnivision OV7740 image sensor supports multiple output image +size, such as VGA, and QVGA, CIF and any size smaller. It also +supports the RAW RGB and YUV output formats. + +The common video interfaces bindings (see video-interfaces.txt) should +be used to specify link to the image data receiver. The OV7740 device +node should contain one 'port' child node with an 'endpoint' subnode. + +Required Properties: +- compatible: "ovti,ov7740". +- reg: I2C slave address of the sensor. +- clocks: Reference to the xvclk input clock. +- clock-names: "xvclk". + +Optional Properties: +- reset-gpios: Rreference to the GPIO connected to the reset_b pin, + if any. Active low with pull-ip resistor. +- powerdown-gpios: Reference to the GPIO connected to the pwdn pin, + if any. Active high with pull-down resistor. + +Endpoint node mandatory properties: +- remote-endpoint: A phandle to the bus receiver's endpoint node. + +Example: + + i2c1: i2c@fc028000 { + ov7740: camera@21 { + compatible = "ovti,ov7740"; + reg = <0x21>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_sensor_power &pinctrl_sensor_reset>; + clocks = <&isc>; + clock-names = "xvclk"; + assigned-clocks = <&isc>; + assigned-clock-rates = <24000000>; + reset-gpios = <&pioA 43 GPIO_ACTIVE_LOW>; + powerdown-gpios = <&pioA 44 GPIO_ACTIVE_HIGH>; + + port { + ov7740_0: endpoint { + remote-endpoint = <&isc_0>; + }; + }; + }; + }; -- cgit From 6705d55cfe148ee4fa37ded3417a76f2ae533b2e Mon Sep 17 00:00:00 2001 From: Akinobu Mita Date: Wed, 3 Jan 2018 13:22:46 -0500 Subject: media: mt9m111: document missing required clocks property The mt9m111 driver requires clocks property for the master clock to the sensor, but there is no description for that. This adds it. Cc: Rob Herring Cc: Mauro Carvalho Chehab Signed-off-by: Akinobu Mita Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/media/i2c/mt9m111.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt b/Documentation/devicetree/bindings/media/i2c/mt9m111.txt index ed5a334b1e57..6b910036b57e 100644 --- a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt +++ b/Documentation/devicetree/bindings/media/i2c/mt9m111.txt @@ -6,6 +6,8 @@ interface. Required Properties: - compatible: value should be "micron,mt9m111" +- clocks: reference to the master clock. +- clock-names: shall be "mclk". For further reading on port node refer to Documentation/devicetree/bindings/media/video-interfaces.txt. @@ -16,6 +18,8 @@ Example: mt9m111@5d { compatible = "micron,mt9m111"; reg = <0x5d>; + clocks = <&mclk>; + clock-names = "mclk"; remote = <&pxa_camera>; port { -- cgit From 495f014d313df677015ceedf6cec5feba1ac6570 Mon Sep 17 00:00:00 2001 From: Hugues Fruchet Date: Wed, 3 Jan 2018 04:57:30 -0500 Subject: media: dt-bindings: ov5640: refine CSI-2 and add parallel interface Refine CSI-2 endpoint documentation and add bindings for DVP parallel interface support. Signed-off-by: Hugues Fruchet Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- .../devicetree/bindings/media/i2c/ov5640.txt | 46 +++++++++++++++++++++- 1 file changed, 44 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/i2c/ov5640.txt b/Documentation/devicetree/bindings/media/i2c/ov5640.txt index 540b36c4b1f2..8e36da0d8406 100644 --- a/Documentation/devicetree/bindings/media/i2c/ov5640.txt +++ b/Documentation/devicetree/bindings/media/i2c/ov5640.txt @@ -1,4 +1,4 @@ -* Omnivision OV5640 MIPI CSI-2 sensor +* Omnivision OV5640 MIPI CSI-2 / parallel sensor Required Properties: - compatible: should be "ovti,ov5640" @@ -18,7 +18,25 @@ The device node must contain one 'port' child node for its digital output video port, in accordance with the video interface bindings defined in Documentation/devicetree/bindings/media/video-interfaces.txt. -Example: +OV5640 can be connected to a MIPI CSI-2 bus or a parallel bus endpoint. + +Endpoint node required properties for CSI-2 connection are: +- remote-endpoint: a phandle to the bus receiver's endpoint node. +- clock-lanes: should be set to <0> (clock lane on hardware lane 0) +- data-lanes: should be set to <1> or <1 2> (one or two CSI-2 lanes supported) + +Endpoint node required properties for parallel connection are: +- remote-endpoint: a phandle to the bus receiver's endpoint node. +- bus-width: shall be set to <8> for 8 bits parallel bus + or <10> for 10 bits parallel bus +- data-shift: shall be set to <2> for 8 bits parallel bus + (lines 9:2 are used) or <0> for 10 bits parallel bus +- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. +- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. +- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock + signal. + +Examples: &i2c1 { ov5640: camera@3c { @@ -35,6 +53,7 @@ Example: reset-gpios = <&gpio1 20 GPIO_ACTIVE_LOW>; port { + /* MIPI CSI-2 bus endpoint */ ov5640_to_mipi_csi2: endpoint { remote-endpoint = <&mipi_csi2_from_ov5640>; clock-lanes = <0>; @@ -43,3 +62,26 @@ Example: }; }; }; + +&i2c1 { + ov5640: camera@3c { + compatible = "ovti,ov5640"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_ov5640>; + reg = <0x3c>; + clocks = <&clk_ext_camera>; + clock-names = "xclk"; + + port { + /* Parallel bus endpoint */ + ov5640_to_parallel: endpoint { + remote-endpoint = <¶llel_from_ov5640>; + bus-width = <8>; + data-shift = <2>; /* lines 9:2 are used */ + hsync-active = <0>; + vsync-active = <0>; + pclk-sample = <1>; + }; + }; + }; +}; -- cgit From aa19a176df95d6e49295d6ff77f7967224c71761 Mon Sep 17 00:00:00 2001 From: Thomas Gleixner Date: Thu, 28 Dec 2017 23:17:17 +0100 Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses Add a file to the Documentation directory to describe how file licenses should be described in all kernel files, using the SPDX identifier, as well as where all licenses should be in the kernel source tree for people to refer to (LICENSES/). Thanks to Kate and Greg for review and editing and Jonas for the suggestions concerning the meta tags in the licenses files. Signed-off-by: Thomas Gleixner Reviewed-by: Jonas Oberg Reviewed-by: Jonathan Corbet Reviewed-by: Philippe Ombredanne Reviewed-by: Kate Stewart Reviewed-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 12 ++ Documentation/process/license-rules.rst | 370 ++++++++++++++++++++++++++++++++ 2 files changed, 382 insertions(+) create mode 100644 Documentation/process/license-rules.rst (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index a4fb34dddcf3..ef5080cbf009 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,6 +13,18 @@ documents into a coherent whole. Please note that improvements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. +Licensing documentation +----------------------- + +The following describes the license of the Linux kernel source code +(GPLv2), how to properly mark the license of individual files in the source +tree, as well as links to the full license text. + +.. toctree:: + :maxdepth: 2 + + process/license-rules.rst + User-oriented documentation --------------------------- diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst new file mode 100644 index 000000000000..408f77dc6157 --- /dev/null +++ b/Documentation/process/license-rules.rst @@ -0,0 +1,370 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel licensing rules +============================ + +The Linux Kernel is provided under the terms of the GNU General Public +License version 2 only (GPL-2.0), as published by the Free Software +Foundation, and provided in the COPYING file. This documentation file is +not meant to replace the COPYING file, but provides a description of how +each source file should be annotated to make the licensing it is governed +under clear and unambiguous. + +The license in the COPYING file applies to the kernel source as a whole, +though individual source files can have a different license which is +required to be compatible with the GPL-2.0:: + + GPL-1.0+ : GNU General Public License v1.0 or later + GPL-2.0+ : GNU General Public License v2.0 or later + LGPL-2.0 : GNU Library General Public License v2 only + LGPL-2.0+ : GNU Library General Public License v2 or later + LGPL-2.1 : GNU Lesser General Public License v2.1 only + LGPL-2.1+ : GNU Lesser General Public License v2.1 or later + +Aside from that, individual files can be provided under a dual license, +e.g. one of the compatible GPL variants and alternatively under a +permissive license like BSD, MIT etc. + +The User-space API (UAPI) header files, which describe the interface of +user-space programs to the kernel are a special case. According to the +note in the kernel COPYING file, the syscall interface is a clear boundary, +which does not extend the GPL requirements to any software which uses it to +communicate with the kernel. Because the UAPI headers must be includable +into any source files which create an executable running on the Linux +kernel, the exception must be documented by a special license expression. + +The common way of expressing the license of a source file is to add the +matching boilerplate text into the top comment of the file. Due to +formatting, typos etc. these "boilerplates" are hard to validate for +tools which are used in the context of license compliance. + +An alternative to boilerplate text is the use of Software Package Data +Exchange (SPDX) license identifiers in each source file. SPDX license +identifiers are machine parsable and precise shorthands for the license +under which the content of the file is contributed. SPDX license +identifiers are managed by the SPDX Workgroup at the Linux Foundation and +have been agreed on by partners throughout the industry, tool vendors, and +legal teams. For further information see https://spdx.org/ + +The Linux kernel requires the precise SPDX identifier in all source files. +The valid identifiers used in the kernel are explained in the section +`License identifiers`_ and have been retrieved from the official SPDX +license list at https://spdx.org/licenses/ along with the license texts. + +License identifier syntax +------------------------- + +1. Placement: + + The SPDX license identifier in kernel files shall be added at the first + possible line in a file which can contain a comment. For the majority + or files this is the first line, except for scripts which require the + '#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX + identifier goes into the second line. + +| + +2. Style: + + The SPDX license identifier is added in form of a comment. The comment + style depends on the file type:: + + C source: // SPDX-License-Identifier: + C header: /* SPDX-License-Identifier: */ + ASM: /* SPDX-License-Identifier: */ + scripts: # SPDX-License-Identifier: + .rst: .. SPDX-License-Identifier: + .dts{i}: // SPDX-License-Identifier: + + If a specific tool cannot handle the standard comment style, then the + appropriate comment mechanism which the tool accepts shall be used. This + is the reason for having the "/\* \*/" style comment in C header + files. There was build breakage observed with generated .lds files where + 'ld' failed to parse the C++ comment. This has been fixed by now, but + there are still older assembler tools which cannot handle C++ style + comments. + +| + +3. Syntax: + + A is either an SPDX short form license + identifier found on the SPDX License List, or the combination of two + SPDX short form license identifiers separated by "WITH" when a license + exception applies. When multiple licenses apply, an expression consists + of keywords "AND", "OR" separating sub-expressions and surrounded by + "(", ")" . + + License identifiers for licenses like [L]GPL with the 'or later' option + are constructed by using a "+" for indicating the 'or later' option.:: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + WITH should be used when there is a modifier to a license needed. + For example, the linux kernel UAPI files use the expression:: + + // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note + // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note + + Other examples using WITH exceptions found in the kernel are:: + + // SPDX-License-Identifier: GPL-2.0 WITH mif-exception + // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0 + + Exceptions can only be used with particular License identifiers. The + valid License identifiers are listed in the tags of the exception text + file. For details see the point `Exceptions`_ in the chapter `License + identifiers`_. + + OR should be used if the file is dual licensed and only one license is + to be selected. For example, some dtsi files are available under dual + licenses:: + + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause + + Examples from the kernel for license expressions in dual licensed files:: + + // SPDX-License-Identifier: GPL-2.0 OR MIT + // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause + // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0 + // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1 + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT + // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL + + AND should be used if the file has multiple licenses whose terms all + apply to use the file. For example, if code is inherited from another + project and permission has been given to put it in the kernel, but the + original license terms need to remain in effect:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT + + Another other example where both sets of license terms need to be + adhered to is:: + + // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+ + +License identifiers +------------------- + +The licenses currently used, as well as the licenses for code added to the +kernel, can be broken down into: + +1. _`Preferred licenses`: + + Whenever possible these licenses should be used as they are known to be + fully compatible and widely used. These licenses are available from the + directory:: + + LICENSES/preferred/ + + in the kernel source tree. + + The files in this directory contain the full license text and + `Metatags`_. The file names are identical to the SPDX license + identifier which shall be used for the license in source files. + + Examples:: + + LICENSES/preferred/GPL-2.0 + + Contains the GPL version 2 license text and the required metatags:: + + LICENSES/preferred/MIT + + Contains the MIT license text and the required metatags + + _`Metatags`: + + The following meta tags must be available in a license file: + + - Valid-License-Identifier: + + One or more lines which declare which License Identifiers are valid + inside the project to reference this particular license text. Usually + this is a single valid identifier, but e.g. for licenses with the 'or + later' options two identifiers are valid. + + - SPDX-URL: + + The URL of the SPDX page which contains additional information related + to the license. + + - Usage-Guidance: + + Freeform text for usage advice. The text must include correct examples + for the SPDX license identifiers as they should be put into source + files according to the `License identifier syntax`_ guidelines. + + - License-Text: + + All text after this tag is treated as the original license text + + File format examples:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + To use this license in source code, put one of the following SPDX + tag/value pairs into a comment according to the placement + guidelines in the licensing rules documentation. + For 'GNU General Public License (GPL) version 2 only' use: + SPDX-License-Identifier: GPL-2.0 + For 'GNU General Public License (GPL) version 2 or any later version' use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Full license text + + :: + + SPDX-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: MIT + License-Text: + Full license text + +| + +2. Not recommended licenses: + + These licenses should only be used for existing code or for importing + code from a different project. These licenses are available from the + directory:: + + LICENSES/other/ + + in the kernel source tree. + + The files in this directory contain the full license text and + `Metatags`_. The file names are identical to the SPDX license + identifier which shall be used for the license in source files. + + Examples:: + + LICENSES/other/ISC + + Contains the Internet Systems Consortium license text and the required + metatags:: + + LICENSES/other/ZLib + + Contains the ZLIB license text and the required metatags. + + Metatags: + + The metatag requirements for 'other' licenses are identical to the + requirements of the `Preferred licenses`_. + + File format example:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + Usage of this license in the kernel for new code is discouraged + and it should solely be used for importing code from an already + existing project. + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: ISC + License-Text: + Full license text + +| + +3. _`Exceptions`: + + Some licenses can be amended with exceptions which grant certain rights + which the original license does not. These exceptions are available + from the directory:: + + LICENSES/exceptions/ + + in the kernel source tree. The files in this directory contain the full + exception text and the required `Exception Metatags`_. + + Examples:: + + LICENSES/exceptions/Linux-syscall-note + + Contains the Linux syscall exception as documented in the COPYING + file of the Linux kernel, which is used for UAPI header files. + e.g. /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/:: + + LICENSES/exceptions/GCC-exception-2.0 + + Contains the GCC 'linking exception' which allows to link any binary + independent of its license against the compiled version of a file marked + with this exception. This is required for creating runnable executables + from source code which is not compatible with the GPL. + + _`Exception Metatags`: + + The following meta tags must be available in an exception file: + + - SPDX-Exception-Identifier: + + One exception identifier which can be used with SPDX license + identifiers. + + - SPDX-URL: + + The URL of the SPDX page which contains additional information related + to the exception. + + - SPDX-Licenses: + + A comma separated list of SPDX license identifiers for which the + exception can be used. + + - Usage-Guidance: + + Freeform text for usage advice. The text must be followed by correct + examples for the SPDX license identifiers as they should be put into + source files according to the `License identifier syntax`_ guidelines. + + - Exception-Text: + + All text after this tag is treated as the original exception text + + File format examples:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + This exception is used together with one of the above SPDX-Licenses + to mark user-space API (uapi) header files so they can be included + into non GPL compliant user-space application code. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: WITH Linux-syscall-note + Exception-Text: + Full exception text + + :: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + The "GCC Runtime Library exception 2.0" is used together with one + of the above SPDX-Licenses for code imported from the GCC runtime + library. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: WITH GCC-exception-2.0 + Exception-Text: + Full exception text + + +All SPDX license identifiers and exceptions must have a corresponding file +in the LICENSE subdirectories. This is required to allow tool +verification (e.g. checkpatch.pl) and to have the licenses ready to read +and extract right from the source, which is recommended by various FOSS +organizations, e.g. the `FSFE REUSE initiative `_. -- cgit From a5d332061047301d883f85241fd28cdd45b5ee31 Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Sat, 30 Dec 2017 23:53:06 +0100 Subject: dmaengine: doc: fix bullet list formatting The bullet list documenting the 'struct dma_device' fields has several nesting errors, making it render improperly. It also has incoherent formatting: some fields have a description in the same bullet, some in a sub-bullet. Fix both to have a correct and coherent formatting. Signed-off-by: Luca Ceresoli Signed-off-by: Vinod Koul --- Documentation/driver-api/dmaengine/provider.rst | 28 +++++++++++-------------- 1 file changed, 12 insertions(+), 16 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 814acb4d2294..a257d9d6bd72 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -125,26 +125,22 @@ need to initialize a few fields in there: (i.e. excluding mem2mem transfers) - residue_granularity: + granularity of the transfer residue reported to dma_set_residue. + This can be either: - - Granularity of the transfer residue reported to dma_set_residue. - This can be either: + - Descriptor: + your device doesn't support any kind of residue + reporting. The framework will only know that a particular + transaction descriptor is done. - - Descriptor + - Segment: + your device is able to report which chunks have been transferred - - Your device doesn't support any kind of residue - reporting. The framework will only know that a particular - transaction descriptor is done. + - Burst: + your device is able to report which burst have been transferred - - Segment - - - Your device is able to report which chunks have been transferred - - - Burst - - - Your device is able to report which burst have been transferred - - - dev: should hold the pointer to the ``struct device`` associated - to your current driver instance. +- dev: should hold the pointer to the ``struct device`` associated + to your current driver instance. Supported transaction types --------------------------- -- cgit From 881053f73ffb465a195815e9f0676e34b6c4450f Mon Sep 17 00:00:00 2001 From: Luca Ceresoli Date: Sat, 30 Dec 2017 23:53:07 +0100 Subject: dmaengine: doc: format struct fields using monospace Monospace is more readable and is also used elsewhere in the docs. Signed-off-by: Luca Ceresoli Signed-off-by: Vinod Koul --- Documentation/driver-api/dmaengine/provider.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index a257d9d6bd72..dfc4486b5743 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -111,20 +111,20 @@ The first thing you need to do in your driver is to allocate this structure. Any of the usual memory allocators will do, but you'll also need to initialize a few fields in there: -- channels: should be initialized as a list using the +- ``channels``: should be initialized as a list using the INIT_LIST_HEAD macro for example -- src_addr_widths: +- ``src_addr_widths``: should contain a bitmask of the supported source transfer width -- dst_addr_widths: +- ``dst_addr_widths``: should contain a bitmask of the supported destination transfer width -- directions: +- ``directions``: should contain a bitmask of the supported slave directions (i.e. excluding mem2mem transfers) -- residue_granularity: +- ``residue_granularity``: granularity of the transfer residue reported to dma_set_residue. This can be either: @@ -139,7 +139,7 @@ need to initialize a few fields in there: - Burst: your device is able to report which burst have been transferred -- dev: should hold the pointer to the ``struct device`` associated +- ``dev``: should hold the pointer to the ``struct device`` associated to your current driver instance. Supported transaction types -- cgit From b7511552f920c8c273912353a8c8bf65e8f84fdc Mon Sep 17 00:00:00 2001 From: Dhaval Shah Date: Thu, 21 Dec 2017 10:33:05 -0800 Subject: dt-bindings: soc: xilinx: Add DT bindings to xlnx_vcu driver Add Device Tree binding document for logicoreIP. This logicoreIP provides the isolation between the processing system and programmable logic. Also provides the clock related information. Signed-off-by: Dhaval Shah Reviewed-by: Rob Herring Signed-off-by: Michal Simek --- .../devicetree/bindings/soc/xilinx/xlnx,vcu.txt | 31 ++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt b/Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt new file mode 100644 index 000000000000..6786d6715df0 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/xilinx/xlnx,vcu.txt @@ -0,0 +1,31 @@ +LogicoreIP designed compatible with Xilinx ZYNQ family. +------------------------------------------------------- + +General concept +--------------- + +LogicoreIP design to provide the isolation between processing system +and programmable logic. Also provides the list of register set to configure +the frequency. + +Required properties: +- compatible: shall be one of: + "xlnx,vcu" + "xlnx,vcu-logicoreip-1.0" +- reg, reg-names: There are two sets of registers need to provide. + 1. vcu slcr + 2. Logicore + reg-names should contain name for the each register sequence. +- clocks: phandle for aclk and pll_ref clocksource +- clock-names: The identification string, "aclk", is always required for + the axi clock. "pll_ref" is required for pll. +Example: + + xlnx_vcu: vcu@a0040000 { + compatible = "xlnx,vcu-logicoreip-1.0"; + reg = <0x0 0xa0040000 0x0 0x1000>, + <0x0 0xa0041000 0x0 0x1000>; + reg-names = "vcu_slcr", "logicore"; + clocks = <&si570_1>, <&clkc 71>; + clock-names = "pll_ref", "aclk"; + }; -- cgit From 350f6c75f6933d5d58548d68f9336543c56b4a02 Mon Sep 17 00:00:00 2001 From: Matt Fornero Date: Wed, 6 Dec 2017 14:43:30 -0500 Subject: iio: buffer: Expose data available Add a sysfs attribute that exposes buffer data available to userspace. This attribute can be checked at runtime to determine the overall buffer fill level (across all allocated buffers). Signed-off-by: Matt Fornero Signed-off-by: Jonathan Cameron Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index a478740e2783..9cc0ea1c0273 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -1413,6 +1413,16 @@ Description: the available samples after the timeout expires and thus have a maximum delay guarantee. +What: /sys/bus/iio/devices/iio:deviceX/buffer/data_available +KernelVersion: 4.16 +Contact: linux-iio@vger.kernel.org +Description: + A read-only value indicating the bytes of data available in the + buffer. In the case of an output buffer, this indicates the + amount of empty space available to write data to. In the case of + an input buffer, this indicates the amount of data available for + reading. + What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_enabled KernelVersion: 4.2 Contact: linux-iio@vger.kernel.org -- cgit From b9a3589332c2a25fb7edad25a26fcaada3209126 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Tue, 5 Dec 2017 11:57:27 +0100 Subject: iio: ABI: Fix name of timestamp sysfs file The name of the file is "current_timetamp_clock" not "timestamp_clock". Fixes: bc2b7dab629a ("iio:core: timestamping clock selection support") Cc: Gregor Boirie Signed-off-by: Linus Walleij Signed-off-by: Jonathan Cameron Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-bus-iio | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 9cc0ea1c0273..6a5f34b4d5b9 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -32,7 +32,7 @@ Description: Description of the physical chip / device for device X. Typically a part number. -What: /sys/bus/iio/devices/iio:deviceX/timestamp_clock +What: /sys/bus/iio/devices/iio:deviceX/current_timestamp_clock KernelVersion: 4.5 Contact: linux-iio@vger.kernel.org Description: -- cgit From baf61639b808307bd6e5be27e5cbef9cc3acd80e Mon Sep 17 00:00:00 2001 From: Dong Aisheng Date: Fri, 22 Dec 2017 18:28:59 +0800 Subject: power: reset: remove unused imx-snvs-poweroff driver There's no user of it in kernel now and it basically functions the same as the generic syscon-poweroff.c to which we have already switched. So let's remove it. Cc: Robin Gong Cc: Shawn Guo Signed-off-by: Dong Aisheng Acked-by: Rob Herring Reviewed-by: Fabio Estevam Signed-off-by: Sebastian Reichel --- .../bindings/power/reset/imx-snvs-poweroff.txt | 23 ---------------------- 1 file changed, 23 deletions(-) delete mode 100644 Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt b/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt deleted file mode 100644 index 1b81fcd9fb72..000000000000 --- a/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt +++ /dev/null @@ -1,23 +0,0 @@ -i.mx6 Poweroff Driver - -SNVS_LPCR in SNVS module can power off the whole system by pull -PMIC_ON_REQ low if PMIC_ON_REQ is connected with external PMIC. -If you don't want to use PMIC_ON_REQ as power on/off control, -please set status='disabled' to disable this driver. - -Required Properties: --compatible: "fsl,sec-v4.0-poweroff" --reg: Specifies the physical address of the SNVS_LPCR register - -Example: - snvs@20cc000 { - compatible = "fsl,sec-v4.0-mon", "simple-bus"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x020cc000 0x4000>; - ..... - snvs_poweroff: snvs-poweroff@38 { - compatible = "fsl,sec-v4.0-poweroff"; - reg = <0x38 0x4>; - }; - } -- cgit From 06f502f57d0d7728f9fa0f157ec5e4111ddb98f6 Mon Sep 17 00:00:00 2001 From: Ben Whitten Date: Sun, 10 Dec 2017 21:17:55 +0000 Subject: leds: trigger: Introduce a NETDEV trigger This commit introduces a NETDEV trigger for named device activity. Available triggers are link, rx, and tx. Signed-off-by: Ben Whitten Acked-by: Pavel Machek Signed-off-by: Jacek Anaszewski --- .../ABI/testing/sysfs-class-led-trigger-netdev | 45 ++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-led-trigger-netdev (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev new file mode 100644 index 000000000000..451af6d6768c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev @@ -0,0 +1,45 @@ +What: /sys/class/leds//device_name +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Specifies the network device name to monitor. + +What: /sys/class/leds//interval +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Specifies the duration of the LED blink in milliseconds. + Defaults to 50 ms. + +What: /sys/class/leds//link +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Signal the link state of the named network device. + If set to 0 (default), the LED's normal state is off. + If set to 1, the LED's normal state reflects the link state + of the named network device. + Setting this value also immediately changes the LED state. + +What: /sys/class/leds//tx +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Signal transmission of data on the named network device. + If set to 0 (default), the LED will not blink on transmission. + If set to 1, the LED will blink for the milliseconds specified + in interval to signal transmission. + +What: /sys/class/leds//rx +Date: Dec 2017 +KernelVersion: 4.16 +Contact: linux-leds@vger.kernel.org +Description: + Signal reception of data on the named network device. + If set to 0 (default), the LED will not blink on reception. + If set to 1, the LED will blink for the milliseconds specified + in interval to signal reception. -- cgit From 1d9aa24b65c0084586c0f2fbabb4874754c7fbe5 Mon Sep 17 00:00:00 2001 From: Dan Murphy Date: Tue, 12 Dec 2017 12:15:49 -0600 Subject: dt: bindings: lm3692x: Add bindings for lm3692x LED driver This adds the devicetree bindings for the LM3692x I2C LED string driver. Acked-by: Pavel Machek Signed-off-by: Dan Murphy Signed-off-by: Jacek Anaszewski --- .../devicetree/bindings/leds/leds-lm3692x.txt | 49 ++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 Documentation/devicetree/bindings/leds/leds-lm3692x.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/leds/leds-lm3692x.txt b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt new file mode 100644 index 000000000000..6c9074f84a51 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-lm3692x.txt @@ -0,0 +1,49 @@ +* Texas Instruments - LM3692x Highly Efficient White LED Driver + +The LM3692x is an ultra-compact, highly efficient, +white-LED driver designed for LCD display backlighting. + +The main difference between the LM36922 and LM36923 is the number of +LED strings it supports. The LM36922 supports two strings while the LM36923 +supports three strings. + +Required properties: + - compatible: + "ti,lm36922" + "ti,lm36923" + - reg : I2C slave address + - #address-cells : 1 + - #size-cells : 0 + +Optional properties: + - enable-gpios : gpio pin to enable/disable the device. + - vled-supply : LED supply + +Required child properties: + - reg : 0 + +Optional child properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + - linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt + +Example: + +led-controller@36 { + compatible = "ti,lm3692x"; + reg = <0x36>; + #address-cells = <1>; + #size-cells = <0>; + + enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; + vled-supply = <&vbatt>; + + led@0 { + reg = <0>; + label = "white:backlight_cluster"; + linux,default-trigger = "backlight"; + }; +} + +For more product information please see the link below: +http://www.ti.com/lit/ds/snvsa29/snvsa29.pdf -- cgit From 033336781bcc454e01e8a2e92a78983d467a1059 Mon Sep 17 00:00:00 2001 From: Dan Murphy Date: Mon, 18 Dec 2017 14:23:02 -0600 Subject: dt: bindings: lp8860: Update bindings for lp8860 Update the lp8860 bindings to fix various issues found. Rename enable-gpio to enable-gpios, update the node name to the device name and indent the node example. Signed-off-by: Dan Murphy Reviewed-by: Rob Herring Signed-off-by: Jacek Anaszewski --- Documentation/devicetree/bindings/leds/leds-lp8860.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index aad38dd94d4b..b9d09acbaa73 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -6,22 +6,22 @@ current sinks that can be controlled by a PWM input signal, a SPI/I2C master, or both. Required properties: - - compatible: + - compatible : "ti,lp8860" - - reg - I2C slave address - - label - Used for naming LEDs + - reg : I2C slave address + - label : Used for naming LEDs Optional properties: - - enable-gpio - gpio pin to enable/disable the device. - - supply - "vled" - LED supply + - enable-gpios : gpio pin to enable (active high)/disable the device. + - vled-supply : LED supply Example: -leds: leds@6 { +led-controller@2d { compatible = "ti,lp8860"; reg = <0x2d>; label = "display_cluster"; - enable-gpio = <&gpio1 28 GPIO_ACTIVE_HIGH>; + enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; vled-supply = <&vbatt>; } -- cgit From 915236838988a927e405058a86b7857a984d33d4 Mon Sep 17 00:00:00 2001 From: Dan Murphy Date: Mon, 18 Dec 2017 14:23:03 -0600 Subject: dt: bindings: lp8860: Update DT label binding Update the lp8860 label binding to the LED standard as documented in Documentation/devicetree/bindings/leds/common.txt Signed-off-by: Dan Murphy Reviewed-by: Rob Herring Signed-off-by: Jacek Anaszewski --- Documentation/devicetree/bindings/leds/leds-lp8860.txt | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index b9d09acbaa73..77ddd22c20dc 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -9,20 +9,33 @@ Required properties: - compatible : "ti,lp8860" - reg : I2C slave address - - label : Used for naming LEDs + - #address-cells : 1 + - #size-cells : 0 Optional properties: - enable-gpios : gpio pin to enable (active high)/disable the device. - vled-supply : LED supply +Required child properties: + - reg : 0 + +Optional child properties: + - label : see Documentation/devicetree/bindings/leds/common.txt + Example: led-controller@2d { compatible = "ti,lp8860"; + #address-cells = <1>; + #size-cells = <0>; reg = <0x2d>; - label = "display_cluster"; enable-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; vled-supply = <&vbatt>; + + led@0 { + reg = <0>; + label = "white:backlight"; + }; } For more product information please see the link below: -- cgit From 3829a7e360edff8c19ddfcdd09ef3ab7275fc129 Mon Sep 17 00:00:00 2001 From: Dan Murphy Date: Mon, 18 Dec 2017 14:23:05 -0600 Subject: dt: bindings: lp8860: Add trigger binding to the lp8860 Add a default trigger optional node to the child node. This will allow the driver to set the trigger for a backlight. Signed-off-by: Dan Murphy Reviewed-by: Rob Herring Signed-off-by: Jacek Anaszewski --- Documentation/devicetree/bindings/leds/leds-lp8860.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/leds/leds-lp8860.txt b/Documentation/devicetree/bindings/leds/leds-lp8860.txt index 77ddd22c20dc..5f0e892ad759 100644 --- a/Documentation/devicetree/bindings/leds/leds-lp8860.txt +++ b/Documentation/devicetree/bindings/leds/leds-lp8860.txt @@ -21,6 +21,8 @@ Required child properties: Optional child properties: - label : see Documentation/devicetree/bindings/leds/common.txt + - linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt Example: @@ -35,6 +37,7 @@ led-controller@2d { led@0 { reg = <0>; label = "white:backlight"; + linux,default-trigger = "backlight"; }; } -- cgit From 0b345d722e07d77866edffcf350449a4607026b6 Mon Sep 17 00:00:00 2001 From: NeilBrown Date: Wed, 3 Jan 2018 08:01:15 +1100 Subject: Documentation: security/credentials.rst: explain need to sort group_list This patch updates the documentation with the observations that led to commit bdcf0a423ea1 ("kernel: make groups_sort calling a responsibility group_info allocators") and the new behaviour required. Specifically that groups_sort() should be called on a new group_list before set_groups() or set_current_groups() is called. Signed-off-by: NeilBrown [jc: use proper :c:func: references] Signed-off-by: Jonathan Corbet --- Documentation/security/credentials.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation') diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst index 66a2e24939d8..5bb7125faeee 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -451,6 +451,13 @@ checks and hooks done. Both the current and the proposed sets of credentials are available for this purpose as current_cred() will return the current set still at this point. +When replacing the group list, the new list must be sorted before it +is added to the credential, as a binary search is used to test for +membership. In practice, this means :c:func:`groups_sort` should be +called before :c:func:`set_groups` or :c:func:`set_current_groups`. +:c:func:`groups_sort)` must not be called on a ``struct group_list`` which +is shared as it may permute elements as part of the sorting process +even if the array is already sorted. When the credential set is ready, it should be committed to the current process by calling:: -- cgit From 36bde81e23d234e46d2132057dfb931b4bd74cf4 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sat, 6 Jan 2018 12:30:37 +1100 Subject: docs: add index entry for networking/msg_zerocopy Currently msg_zerocopy is not included in any toctree. Sphinx emits a build warning to this effect. The other three rst files in Documentation/networking are all indexed. We can add msg_zerocopy to the toctree to enable navigation of the document via HTML kernel docs. Add msg_zerocopy to the networking/ toctree. Signed-off-by: Tobin C. Harding Signed-off-by: Jonathan Corbet --- Documentation/networking/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 66e620866245..19e8a927d79b 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -9,6 +9,7 @@ Contents: batman-adv kapi z8530book + msg_zerocopy .. only:: subproject -- cgit From 04b8eb7a4ccd9ef9343e2720ccf2a5db8cfe2f67 Mon Sep 17 00:00:00 2001 From: Sergey Senozhatsky Date: Wed, 6 Dec 2017 13:36:49 +0900 Subject: symbol lookup: introduce dereference_symbol_descriptor() dereference_symbol_descriptor() invokes appropriate ARCH specific function descriptor dereference callbacks: - dereference_kernel_function_descriptor() if the pointer is a kernel symbol; - dereference_module_function_descriptor() if the pointer is a module symbol. This is the last step needed to make '%pS/%ps' smart enough to handle function descriptor dereference on affected ARCHs and to retire '%pF/%pf'. To refresh it: Some architectures (ia64, ppc64, parisc64) use an indirect pointer for C function pointers - the function pointer points to a function descriptor and we need to dereference it to get the actual function pointer. Function descriptors live in .opd elf section and all affected ARCHs (ia64, ppc64, parisc64) handle it properly for kernel and modules. So we, technically, can decide if the dereference is needed by simply looking at the pointer: if it belongs to .opd section then we need to dereference it. The kernel and modules have their own .opd sections, obviously, that's why we need to split dereference_function_descriptor() and use separate kernel and module dereference arch callbacks. Link: http://lkml.kernel.org/r/20171206043649.GB15885@jagdpanzerIV Cc: Fenghua Yu Cc: Benjamin Herrenschmidt Cc: Paul Mackerras Cc: Michael Ellerman Cc: James Bottomley Cc: Andrew Morton Cc: Jessica Yu Cc: Steven Rostedt Cc: linux-ia64@vger.kernel.org Cc: linux-parisc@vger.kernel.org Cc: linuxppc-dev@lists.ozlabs.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Sergey Senozhatsky Tested-by: Tony Luck #ia64 Tested-by: Santosh Sivaraj #powerpc Tested-by: Helge Deller #parisc64 Signed-off-by: Petr Mladek --- Documentation/printk-formats.txt | 35 ++++++++++++----------------------- 1 file changed, 12 insertions(+), 23 deletions(-) (limited to 'Documentation') diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt index 361789df51ec..58c44cce90b6 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.txt @@ -50,42 +50,31 @@ Symbols/Function Pointers :: + %pS versatile_init+0x0/0x110 + %ps versatile_init %pF versatile_init+0x0/0x110 %pf versatile_init - %pS versatile_init+0x0/0x110 %pSR versatile_init+0x9/0x110 (with __builtin_extract_return_addr() translation) - %ps versatile_init %pB prev_fn_of_versatile_init+0x88/0x88 -The ``F`` and ``f`` specifiers are for printing function pointers, -for example, f->func, &gettimeofday. They have the same result as -``S`` and ``s`` specifiers. But they do an extra conversion on -ia64, ppc64 and parisc64 architectures where the function pointers -are actually function descriptors. +The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic +format. They result in the symbol name with (``S``) or without (``s``) +offsets. If KALLSYMS are disabled then the symbol address is printed instead. -The ``S`` and ``s`` specifiers can be used for printing symbols -from direct addresses, for example, __builtin_return_address(0), -(void *)regs->ip. They result in the symbol name with (``S``) or -without (``s``) offsets. If KALLSYMS are disabled then the symbol -address is printed instead. +Note, that the ``F`` and ``f`` specifiers are identical to ``S`` (``s``) +and thus deprecated. We have ``F`` and ``f`` because on ia64, ppc64 and +parisc64 function pointers are indirect and, in fact, are function +descriptors, which require additional dereferencing before we can lookup +the symbol. As of now, ``S`` and ``s`` perform dereferencing on those +platforms (when needed), so ``F`` and ``f`` exist for compatibility +reasons only. The ``B`` specifier results in the symbol name with offsets and should be used when printing stack backtraces. The specifier takes into consideration the effect of compiler optimisations which may occur when tail-call``s are used and marked with the noreturn GCC attribute. -Examples:: - - printk("Going to call: %pF\n", gettimeofday); - printk("Going to call: %pF\n", p->func); - printk("%s: called from %pS\n", __func__, (void *)_RET_IP_); - printk("%s: called from %pS\n", __func__, - (void *)__builtin_return_address(0)); - printk("Faulted at %pS\n", (void *)regs->ip); - printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack); - - Kernel Pointers =============== -- cgit From ba33f4f42e968854d8367fc4e55b07f835c55832 Mon Sep 17 00:00:00 2001 From: Bai Ping Date: Sat, 6 Jan 2018 15:25:53 +0100 Subject: pinctrl: imx6ul: add IOMUXC SNVS pinctrl driver for i.MX 6ULL On i.MX 6ULL, the BOOT_MODEx and TAMPERx pin MUX and CTRL registers are available in a separate IOMUXC_SNVS module. Add support for the IOMUXC_SNVS module to the i.MX 6UL pinctrl driver. Signed-off-by: Bai Ping Signed-off-by: Stefan Agner Reviewed-by: Rob Herring Signed-off-by: Linus Walleij --- Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt index a81bbf37ed66..7ca4f6118d9a 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx6ul-pinctrl.txt @@ -4,7 +4,8 @@ Please refer to fsl,imx-pinctrl.txt in this directory for common binding part and usage. Required properties: -- compatible: "fsl,imx6ul-iomuxc" +- compatible: "fsl,imx6ul-iomuxc" for main IOMUX controller or + "fsl,imx6ull-iomuxc-snvs" for i.MX 6ULL's SNVS IOMUX controller. - fsl,pins: each entry consists of 6 integers and represents the mux and config setting for one pin. The first 5 integers are specified using a PIN_FUNC_ID macro, which can be found in -- cgit From a3a093ae02e2ae81499ad9e78516dccd72906c25 Mon Sep 17 00:00:00 2001 From: "Khan, Imran" Date: Sun, 7 Jan 2018 18:15:30 -0800 Subject: pinctrl: qcom: Add msm8998 pinctrl driver Add initial pinctrl driver to support pin configuration with pinctrl framework for msm8998. Signed-off-by: Imran Khan Acked-by: Rob Herring [bjorn: Consolidated function groups] Signed-off-by: Bjorn Andersson Signed-off-by: Linus Walleij --- .../bindings/pinctrl/qcom,msm8998-pinctrl.txt | 193 +++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt new file mode 100644 index 000000000000..e70c79bbbc5b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8998-pinctrl.txt @@ -0,0 +1,193 @@ +Qualcomm MSM8998 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +MSM8998 platform. + +- compatible: + Usage: required + Value type: + Definition: must be "qcom,msm8998-pinctrl" + +- reg: + Usage: required + Value type: + Definition: the base address and size of the TLMM register space. + +- interrupts: + Usage: required + Value type: + Definition: should specify the TLMM summary IRQ. + +- interrupt-controller: + Usage: required + Value type: + Definition: identifies this node as an interrupt controller + +- #interrupt-cells: + Usage: required + Value type: + Definition: must be 2. Specifying the pin number and flags, as defined + in + +- gpio-controller: + Usage: required + Value type: + Definition: identifies this node as a gpio controller + +- #gpio-cells: + Usage: required + Value type: + Definition: must be 2. Specifying the pin number and flags, as defined + in + +Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for +a general description of GPIO and interrupt bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those pin(s)/group(s), and various pin configuration +parameters, such as pull-up, drive strength, etc. + + +PIN CONFIGURATION NODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +- pins: + Usage: required + Value type: + Definition: List of gpio pins affected by the properties specified in + this subnode. + + Valid pins are: + gpio0-gpio149 + Supports mux, bias and drive-strength + + sdc2_clk, sdc2_cmd, sdc2_data + Supports bias and drive-strength + + ufs_reset + Supports bias and drive-strength + +- function: + Usage: required + Value type: + Definition: Specify the alternative function to be configured for the + specified pins. Functions are only valid for gpio pins. + Valid values are: + + gpio, adsp_ext, agera_pll, atest_char, atest_gpsadc0, + atest_gpsadc1, atest_tsens, atest_tsens2, atest_usb1, + atest_usb10, atest_usb11, atest_usb12, atest_usb13, + audio_ref, bimc_dte0, bimc_dte1, blsp10_spi, blsp10_spi_a, + blsp10_spi_b, blsp11_i2c, blsp1_spi, blsp1_spi_a, + blsp1_spi_b, blsp2_spi, blsp9_spi, blsp_i2c1, blsp_i2c2, + blsp_i2c3, blsp_i2c4, blsp_i2c5, blsp_i2c6, blsp_i2c7, + blsp_i2c8, blsp_i2c9, blsp_i2c10, blsp_i2c11, blsp_i2c12, + blsp_spi1, blsp_spi2, blsp_spi3, blsp_spi4, blsp_spi5, + blsp_spi6, blsp_spi7, blsp_spi8, blsp_spi9, blsp_spi10, + blsp_spi11, blsp_spi12, blsp_uart1_a, blsp_uart1_b, + blsp_uart2_a, blsp_uart2_b, blsp_uart3_a, blsp_uart3_b, + blsp_uart7_a, blsp_uart7_b, blsp_uart8, blsp_uart8_a, + blsp_uart8_b, blsp_uart9_a, blsp_uart9_b, blsp_uim1_a, + blsp_uim1_b, blsp_uim2_a, blsp_uim2_b, blsp_uim3_a, + blsp_uim3_b, blsp_uim7_a, blsp_uim7_b, blsp_uim8_a, + blsp_uim8_b, blsp_uim9_a, blsp_uim9_b, bt_reset, + btfm_slimbus, cam_mclk, cci_async, cci_i2c, cci_timer0, + cci_timer1, cci_timer2, cci_timer3, cci_timer4, cri_trng, + cri_trng0, cri_trng1, dbg_out, ddr_bist, edp_hot, edp_lcd, + gcc_gp1_a, gcc_gp1_b, gcc_gp2_a, gcc_gp2_b, gcc_gp3_a, + gcc_gp3_b, hdmi_cec, hdmi_ddc, hdmi_hot, hdmi_rcv, + isense_dbg, jitter_bist, ldo_en, ldo_update, lpass_slimbus, + m_voc, mdp_vsync, mdp_vsync0, mdp_vsync1, mdp_vsync2, + mdp_vsync3, mdp_vsync_a, mdp_vsync_b, modem_tsync, mss_lte, + nav_dr, nav_pps, pa_indicator, pci_e0, phase_flag, + pll_bypassnl, pll_reset, pri_mi2s, pri_mi2s_ws, prng_rosc, + pwr_crypto, pwr_modem, pwr_nav, qdss_cti0_a, qdss_cti0_b, + qdss_cti1_a, qdss_cti1_b, qdss, qlink_enable, + qlink_request, qua_mi2s, sd_card, sd_write, sdc40, sdc41, + sdc42, sdc43, sdc4_clk, sdc4_cmd, sec_mi2s, sp_cmu, + spkr_i2s, ssbi1, ssc_irq, ter_mi2s, tgu_ch0, tgu_ch1, + tsense_pwm1, tsense_pwm2, tsif1_clk, tsif1_data, tsif1_en, + tsif1_error, tsif1_sync, tsif2_clk, tsif2_data, tsif2_en, + tsif2_error, tsif2_sync, uim1_clk, uim1_data, uim1_present, + uim1_reset, uim2_clk, uim2_data, uim2_present, uim2_reset, + uim_batt, usb_phy, vfr_1, vsense_clkout, vsense_data0, + vsense_data1, vsense_mode, wlan1_adc0, wlan1_adc1, + wlan2_adc0, wlan2_adc1, + +- bias-disable: + Usage: optional + Value type: + Definition: The specified pins should be configued as no pull. + +- bias-pull-down: + Usage: optional + Value type: + Definition: The specified pins should be configued as pull down. + +- bias-pull-up: + Usage: optional + Value type: + Definition: The specified pins should be configued as pull up. + +- output-high: + Usage: optional + Value type: + Definition: The specified pins are configured in output mode, driven + high. + Not valid for sdc pins. + +- output-low: + Usage: optional + Value type: + Definition: The specified pins are configured in output mode, driven + low. + Not valid for sdc pins. + +- drive-strength: + Usage: optional + Value type: + Definition: Selects the drive strength for the specified pins, in mA. + Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16 + +Example: + + tlmm: pinctrl@03400000 { + compatible = "qcom,msm8998-pinctrl"; + reg = <0x03400000 0xc00000>; + interrupts = <0 208 0>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + + uart_console_active: uart_console_active { + mux { + pins = "gpio4", "gpio5"; + function = "blsp_uart8_a"; + }; + + config { + pins = "gpio4", "gpio5"; + drive-strength = <2>; + bias-disable; + }; + }; + }; -- cgit From 9961dbcd228e868224f5f725dfae69de739855dc Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Tue, 9 Jan 2018 12:35:54 +0100 Subject: Documentation: gpio: correct return value of gpiod_get_direction The use of the GPIOF_* flags is deprecated, so don't advertise them here. Document the plain numbers for now until we have a better solution. Signed-off-by: Wolfram Sang Signed-off-by: Linus Walleij --- Documentation/gpio/consumer.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 63e1bd1d88e3..7aac33081510 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -184,7 +184,7 @@ A driver can also query the current direction of a GPIO: int gpiod_get_direction(const struct gpio_desc *desc) -This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT. +This function returns 0 for output, 1 for input, or an error code in case of error. Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO without setting its direction first is illegal and will result in undefined -- cgit From e7053e6c29f6ca116f6378c895805ad3f44c77aa Mon Sep 17 00:00:00 2001 From: Chris Brandt Date: Mon, 8 Jan 2018 07:30:54 -0500 Subject: dt-bindings: usb: renesas_usbhs: Add support for RZ/A1 Document support for RZ/A1 SoCs Signed-off-by: Chris Brandt Reviewed-by: Geert Uytterhoeven Reviewed-by: Simon Horman Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/usb/renesas_usbhs.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index 47394ab788e3..d060172f1529 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -13,8 +13,10 @@ Required properties: - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device - "renesas,usbhs-r8a7796" for r8a7796 (R-Car M3-W) compatible device - "renesas,usbhs-r8a77995" for r8a77995 (R-Car D3) compatible device + - "renesas,usbhs-r7s72100" for r7s72100 (RZ/A1) compatible device - "renesas,rcar-gen2-usbhs" for R-Car Gen2 or RZ/G1 compatible devices - "renesas,rcar-gen3-usbhs" for R-Car Gen3 compatible device + - "renesas,rza1-usbhs" for RZ/A1 compatible device When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first followed -- cgit From 99ca1f6f3be5f2587488514dbaeb1f39a547a9b6 Mon Sep 17 00:00:00 2001 From: Chunfeng Yun Date: Wed, 3 Jan 2018 16:53:19 +0800 Subject: dt-bindings: usb: mtu3: update USB wakeup properties Add two arguments in "mediatek,syscon-wakeup" to support multi wakeup glue layer between SSUSB and SPM, and use standard property "wakeup-source" to replace the private "mediatek,enable-wakeup" Signed-off-by: Chunfeng Yun Reviewed-by: Rob Herring Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/usb/mediatek,mtu3.txt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt index b2271d8e6b50..d589a1ef96a1 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.txt @@ -42,9 +42,14 @@ Optional properties: - enable-manual-drd : supports manual dual-role switch via debugfs; usually used when receptacle is TYPE-A and also wants to support dual-role mode. - - mediatek,enable-wakeup : supports ip sleep wakeup used by host mode - - mediatek,syscon-wakeup : phandle to syscon used to access USB wakeup - control register, it depends on "mediatek,enable-wakeup". + - wakeup-source: enable USB remote wakeup of host mode. + - mediatek,syscon-wakeup : phandle to syscon used to access the register + of the USB wakeup glue layer between SSUSB and SPM; it depends on + "wakeup-source", and has two arguments: + - the first one : register base address of the glue layer in syscon; + - the second one : hardware version of the glue layer + - 1 : used by mt8173 etc + - 2 : used by mt2712 etc - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, bit1 for u3port1, ... etc; @@ -71,8 +76,8 @@ ssusb: usb@11271000 { vbus-supply = <&usb_p0_vbus>; extcon = <&extcon_usb>; dr_mode = "otg"; - mediatek,enable-wakeup; - mediatek,syscon-wakeup = <&pericfg>; + wakeup-source; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; #address-cells = <2>; #size-cells = <2>; ranges; -- cgit From ff17d3286b039d6a4104e55a221b4faef340fe45 Mon Sep 17 00:00:00 2001 From: Chunfeng Yun Date: Wed, 3 Jan 2018 16:53:21 +0800 Subject: dt-bindings: usb: mtk-xhci: update USB wakeup properties Add two arguments in "mediatek,syscon-wakeup" to support multi wakeup glue layer between SSUSB and SPM, and use standard property "wakeup-source" to replace the private "mediatek,wakeup-src" Signed-off-by: Chunfeng Yun Reviewed-by: Rob Herring Signed-off-by: Greg Kroah-Hartman --- .../devicetree/bindings/usb/mediatek,mtk-xhci.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt index 9ff560298498..88d9f4a4b280 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt +++ b/Documentation/devicetree/bindings/usb/mediatek,mtk-xhci.txt @@ -35,10 +35,14 @@ Required properties: - phys : a list of phandle + phy specifier pairs Optional properties: - - mediatek,wakeup-src : 1: ip sleep wakeup mode; 2: line state wakeup - mode; - - mediatek,syscon-wakeup : phandle to syscon used to access USB wakeup - control register, it depends on "mediatek,wakeup-src". + - wakeup-source : enable USB remote wakeup; + - mediatek,syscon-wakeup : phandle to syscon used to access the register + of the USB wakeup glue layer between xHCI and SPM; it depends on + "wakeup-source", and has two arguments: + - the first one : register base address of the glue layer in syscon; + - the second one : hardware version of the glue layer + - 1 : used by mt8173 etc + - 2 : used by mt2712 etc - mediatek,u3p-dis-msk : mask to disable u3ports, bit0 for u3port0, bit1 for u3port1, ... etc; - vbus-supply : reference to the VBUS regulator; @@ -65,8 +69,8 @@ usb30: usb@11270000 { vusb33-supply = <&mt6397_vusb_reg>; vbus-supply = <&usb_p1_vbus>; usb3-lpm-capable; - mediatek,syscon-wakeup = <&pericfg>; - mediatek,wakeup-src = <1>; + mediatek,syscon-wakeup = <&pericfg 0x400 1>; + wakeup-source; imod-interval-ns = <10000>; }; -- cgit From aed3d7012ca79f102bf98cca808c7ff5ceb26c57 Mon Sep 17 00:00:00 2001 From: Paul Cercueil Date: Thu, 28 Dec 2017 14:07:08 +0100 Subject: serial: 8250_ingenic: Add support for the JZ4770 SoC The JZ4770 SoC's UART is no different from the other JZ SoCs, so this commit simply adds the ingenic,jz4770-uart compatible string. Signed-off-by: Paul Cercueil Acked-by: Rob Herring Signed-off-by: Greg Kroah-Hartman --- Documentation/devicetree/bindings/serial/ingenic,uart.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/serial/ingenic,uart.txt b/Documentation/devicetree/bindings/serial/ingenic,uart.txt index 02cb7fe59cb7..c3c6406d5cfe 100644 --- a/Documentation/devicetree/bindings/serial/ingenic,uart.txt +++ b/Documentation/devicetree/bindings/serial/ingenic,uart.txt @@ -1,8 +1,12 @@ * Ingenic SoC UART Required properties: -- compatible : "ingenic,jz4740-uart", "ingenic,jz4760-uart", - "ingenic,jz4775-uart" or "ingenic,jz4780-uart" +- compatible : One of: + - "ingenic,jz4740-uart", + - "ingenic,jz4760-uart", + - "ingenic,jz4770-uart", + - "ingenic,jz4775-uart", + - "ingenic,jz4780-uart". - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. - clocks : phandles to the module & baud clocks. -- cgit From a9afc573dbe64e27c0082f69f242d2bbe13d57f3 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Fri, 5 Jan 2018 21:00:41 +0900 Subject: firmware: Fix a typo in fallback-mechanisms.rst This patch fix a spelling typo found in fallback-mechanisms.rst Signed-off-by: Masanari Iida Acked-by: Luis R. Rodriguez Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/firmware/fallback-mechanisms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst index d19354794e67..4055ac76b288 100644 --- a/Documentation/driver-api/firmware/fallback-mechanisms.rst +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst @@ -71,7 +71,7 @@ via fw_create_instance(). This call creates a new struct device named after the firmware requested, and establishes it in the device hierarchy by associating the device used to make the request as the device's parent. The sysfs directory's file attributes are defined and controlled through -the new device's class (firmare_class) and group (fw_dev_attr_groups). +the new device's class (firmware_class) and group (fw_dev_attr_groups). This is actually where the original firmware_class.c file name comes from, as originally the only firmware loading mechanism available was the mechanism we now use as a fallback mechanism. -- cgit From b4ea81ee4ae807bbaeec22b34f6d790b664e3964 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Tue, 9 Jan 2018 10:29:05 -0800 Subject: vmbus: fix ABI documentation Fixes to vmbus ABI document including: - make it clear that relid is numeric value in sub directory - clarify interrupt mask description - spelling fixes - document regions Signed-off-by: Stephen Hemminger Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/stable/sysfs-bus-vmbus | 39 +++++++++++++++++++------------- 1 file changed, 23 insertions(+), 16 deletions(-) (limited to 'Documentation') diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index d4077cc60d55..b7174a5616d6 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -42,70 +42,77 @@ Contact: K. Y. Srinivasan Description: The 16 bit vendor ID of the device Users: tools/hv/lsvmbus and user level RDMA libraries -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/cpu +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN +Date: September. 2017 +KernelVersion: 4.14 +Contact: Stephen Hemminger +Description: Directory for per-channel information + NN is the VMBUS relid associtated with the channel. + +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/cpu Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger Description: VCPU (sub)channel is affinitized to -Users: tools/hv/lsvmbus and other debuggig tools +Users: tools/hv/lsvmbus and other debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/cpu +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/cpu Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger Description: VCPU (sub)channel is affinitized to -Users: tools/hv/lsvmbus and other debuggig tools +Users: tools/hv/lsvmbus and other debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/in_mask +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/in_mask Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger -Description: Inbound channel signaling state +Description: Host to guest channel interrupt mask Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/latency +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/latency Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger Description: Channel signaling latency Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/out_mask +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/out_mask Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger -Description: Outbound channel signaling state +Description: Guest to host channel interrupt mask Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/pending +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/pending Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger Description: Channel interrupt pending state Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/read_avail +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/read_avail Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger -Description: Bytes availabble to read +Description: Bytes available to read Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/write_avail +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/write_avail Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger -Description: Bytes availabble to write +Description: Bytes available to write Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/events +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/events Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger Description: Number of times we have signaled the host Users: Debugging tools -What: /sys/bus/vmbus/devices/vmbus_*/channels/relid/interrupts +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/interrupts Date: September. 2017 KernelVersion: 4.14 Contact: Stephen Hemminger -- cgit From f0fa297404c3f8ab90f1d89405a72edaff988825 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Tue, 9 Jan 2018 10:29:06 -0800 Subject: vmbus: add monitor_id and subchannel_id to sysfs per channel Useful to identify which network queue is associated with which vmbus channel. Signed-off-by: Stephen Hemminger Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/stable/sysfs-bus-vmbus | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'Documentation') diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index b7174a5616d6..e46be65d0e1d 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -118,3 +118,17 @@ KernelVersion: 4.14 Contact: Stephen Hemminger Description: Number of times we have taken an interrupt (incoming) Users: Debugging tools + +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/subchannel_id +Date: January. 2018 +KernelVersion: 4.16 +Contact: Stephen Hemminger +Description: Subchannel ID associated with VMBUS channel +Users: Debugging tools and userspace drivers + +What: /sys/bus/vmbus/devices/vmbus_*/channels/NN/monitor_id +Date: January. 2018 +KernelVersion: 4.16 +Contact: Stephen Hemminger +Description: Monitor bit associated with channel +Users: Debugging tools and userspace drivers -- cgit From eca3be9b95ac7cf9442654a54962859d74f8e38a Mon Sep 17 00:00:00 2001 From: Hans de Goede Date: Tue, 9 Jan 2018 11:34:15 -0800 Subject: Input: silead - add support for capactive home button found on some x86 tablets On some x86 tablets with a silead touchscreen the windows logo on the front is a capacitive home button. Touching this button results in a touch with bits 12-15 of the Y coordinates set, while normally only the lower 12 are used. Detect this and report a KEY_LEFTMETA press when this happens. Note for now we only respond to the Y coordinate bits 12-15 containing 0x01, on some tablets *without* a capacative button I've noticed these bits containing 0x04 when crossing the edges of the screen. Acked-by: Rob Herring Signed-off-by: Hans de Goede Signed-off-by: Dmitry Torokhov --- Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt index 6aa625e0cb8d..84752de12412 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt @@ -23,6 +23,8 @@ Optional properties: - touchscreen-inverted-y : See touchscreen.txt - touchscreen-swapped-x-y : See touchscreen.txt - silead,max-fingers : maximum number of fingers the touchscreen can detect +- silead,home-button : Boolean, set to true on devices which have a + capacitive home-button build into the touchscreen - vddio-supply : regulator phandle for controller VDDIO - avdd-supply : regulator phandle for controller AVDD -- cgit From 44625605a27f1bd9e9b40dc339a95ff638706bdb Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Tue, 9 Jan 2018 12:57:28 -0800 Subject: doc: fix documentation about uio_hv_generic The vmbus sysfs file names changed in commit f6b2db084b65 ("vmbus: make sysfs names consistent with PCI") and the uio documenatation does not match the current names. Signed-off-by: Stephen Hemminger Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/uio-howto.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index f73d660b2956..3a0d3f5f5c53 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -667,27 +667,28 @@ Making the driver recognize the device Since the driver does not declare any device GUID's, it will not get loaded automatically and will not automatically bind to any devices, you must load it and allocate id to the driver yourself. For example, to use -the network device GUID:: +the network device class GUID:: modprobe uio_hv_generic echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id If there already is a hardware specific kernel driver for the device, the generic driver still won't bind to it, in this case if you want to -use the generic driver (why would you?) you'll have to manually unbind -the hardware specific driver and bind the generic driver, like this:: +use the generic driver for a userspace library you'll have to manually unbind +the hardware specific driver and bind the generic driver, using the device specific GUID +like this:: - echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind - echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind + echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind + echo -n ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind You can verify that the device has been bound to the driver by looking for it in sysfs, for example like the following:: - ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver + ls -l /sys/bus/vmbus/devices/ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver Which if successful should print:: - .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic + .../ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic Things to know about uio_hv_generic ----------------------------------- -- cgit From c5702d1b31085ccda7f46e514a51c6c8db54cdc4 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Tue, 9 Jan 2018 12:57:29 -0800 Subject: uio: document uio_hv_generic regions Describe the regions present with uio_hv_generic in documentation for driver API. Signed-off-by: Stephen Hemminger Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/uio-howto.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index 3a0d3f5f5c53..968f4c21c733 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -698,6 +698,11 @@ prevents the device from generating further interrupts until the bit is cleared. The userspace driver should clear this bit before blocking and waiting for more interrupts. +The vmbus device regions are mapped into uio device resources: + 0) Channel ring buffers: guest to host and host to guest + 1) Guest to host interrupt signalling pages + 2) Guest to host monitor page + Further information =================== -- cgit From e7d214642a19b8e0e7ecda39184c2ab98ba4801f Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Tue, 9 Jan 2018 12:57:30 -0800 Subject: uio_hv_generic: create send and receive buffers Map in receive and send buffers for networking in UIO device. These buffers are special and need to be setup by kernel API's; userspace can not do it. Signed-off-by: Stephen Hemminger Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/uio-howto.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index 968f4c21c733..97e6435b3934 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -702,6 +702,8 @@ The vmbus device regions are mapped into uio device resources: 0) Channel ring buffers: guest to host and host to guest 1) Guest to host interrupt signalling pages 2) Guest to host monitor page + 3) Network receive buffer region + 4) Network send buffer region Further information =================== -- cgit From ca3cda6fcf1e922213a0cc58e708ffb999151db3 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Tue, 9 Jan 2018 12:57:32 -0800 Subject: uio_hv_generic: add rescind support When host rescinds the device, the UIO driver will clear the interrupt state and notify application. The read (or write) on the interrupt FD will then fail with -EIO. This is simpler than adding lots extra uevent stuff inside UIO. Signed-off-by: Stephen Hemminger Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/uio-howto.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index 97e6435b3934..693e3bd84e79 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -698,6 +698,10 @@ prevents the device from generating further interrupts until the bit is cleared. The userspace driver should clear this bit before blocking and waiting for more interrupts. +When host rescinds a device, the interrupt file descriptor is marked down +and any reads of the interrupt file descriptor will return -EIO. Similar +to a closed socket or disconnected serial device. + The vmbus device regions are mapped into uio device resources: 0) Channel ring buffers: guest to host and host to guest 1) Guest to host interrupt signalling pages -- cgit From f78f4107ea94cc23946bc1ec022329ce5755dc19 Mon Sep 17 00:00:00 2001 From: Jassi Brar Date: Sat, 6 Jan 2018 19:44:19 +0530 Subject: dt-bindings: net: Add DT bindings for Socionext Netsec This patch adds documentation for Device-Tree bindings for the Socionext NetSec Controller driver. Reviewed-by: Rob Herring Signed-off-by: Jassi Brar Signed-off-by: Ard Biesheuvel Signed-off-by: David S. Miller --- .../devicetree/bindings/net/socionext-netsec.txt | 53 ++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 Documentation/devicetree/bindings/net/socionext-netsec.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/socionext-netsec.txt b/Documentation/devicetree/bindings/net/socionext-netsec.txt new file mode 100644 index 000000000000..0cff94fb0433 --- /dev/null +++ b/Documentation/devicetree/bindings/net/socionext-netsec.txt @@ -0,0 +1,53 @@ +* Socionext NetSec Ethernet Controller IP + +Required properties: +- compatible: Should be "socionext,synquacer-netsec" +- reg: Address and length of the control register area, followed by the + address and length of the EEPROM holding the MAC address and + microengine firmware +- interrupts: Should contain ethernet controller interrupt +- clocks: phandle to the PHY reference clock +- clock-names: Should be "phy_ref_clk" +- phy-mode: See ethernet.txt file in the same directory +- phy-handle: See ethernet.txt in the same directory. + +- mdio device tree subnode: When the Netsec has a phy connected to its local + mdio, there must be device tree subnode with the following + required properties: + + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. + + For each phy on the mdio bus, there must be a node with the following + fields: + - compatible: Refer to phy.txt + - reg: phy id used to communicate to phy. + +Optional properties: (See ethernet.txt file in the same directory) +- dma-coherent: Boolean property, must only be present if memory + accesses performed by the device are cache coherent. +- local-mac-address: See ethernet.txt in the same directory. +- mac-address: See ethernet.txt in the same directory. +- max-speed: See ethernet.txt in the same directory. +- max-frame-size: See ethernet.txt in the same directory. + +Example: + eth0: ethernet@522d0000 { + compatible = "socionext,synquacer-netsec"; + reg = <0 0x522d0000 0x0 0x10000>, <0 0x10000000 0x0 0x10000>; + interrupts = ; + clocks = <&clk_netsec>; + clock-names = "phy_ref_clk"; + phy-mode = "rgmii"; + max-speed = <1000>; + max-frame-size = <9000>; + phy-handle = <&phy1>; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy1: ethernet-phy@1 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <1>; + }; + }; -- cgit From d0807da78e11d46f18399cbf8c4028c731346766 Mon Sep 17 00:00:00 2001 From: Miroslav Benes Date: Wed, 10 Jan 2018 11:01:28 +0100 Subject: livepatch: Remove immediate feature Immediate flag has been used to disable per-task consistency and patch all tasks immediately. It could be useful if the patch doesn't change any function or data semantics. However, it causes problems on its own. The consistency problem is currently broken with respect to immediate patches. func a patches 1i 2i 3 When the patch 3 is applied, only 2i function is checked (by stack checking facility). There might be a task sleeping in 1i though. Such task is migrated to 3, because we do not check 1i in klp_check_stack_func() at all. Coming atomic replace feature would be easier to implement and more reliable without immediate. Thus, remove immediate feature completely and save us from the problems. Note that force feature has the similar problem. However it is considered as a last resort. If used, administrator should not apply any new live patches and should plan for reboot into an updated kernel. The architectures would now need to provide HAVE_RELIABLE_STACKTRACE to fully support livepatch. Signed-off-by: Miroslav Benes Acked-by: Josh Poimboeuf Signed-off-by: Jiri Kosina --- Documentation/livepatch/livepatch.txt | 89 +++++++++++------------------------ 1 file changed, 27 insertions(+), 62 deletions(-) (limited to 'Documentation') diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index 896ba8941702..1ae2de758c08 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -72,8 +72,7 @@ example, they add a NULL pointer or a boundary check, fix a race by adding a missing memory barrier, or add some locking around a critical section. Most of these changes are self contained and the function presents itself the same way to the rest of the system. In this case, the functions might -be updated independently one by one. (This can be done by setting the -'immediate' flag in the klp_patch struct.) +be updated independently one by one. But there are more complex fixes. For example, a patch might change ordering of locking in multiple functions at the same time. Or a patch @@ -125,12 +124,6 @@ safe to patch tasks: b) Patching CPU-bound user tasks. If the task is highly CPU-bound then it will get patched the next time it gets interrupted by an IRQ. - c) In the future it could be useful for applying patches for - architectures which don't yet have HAVE_RELIABLE_STACKTRACE. In - this case you would have to signal most of the tasks on the - system. However this isn't supported yet because there's - currently no way to patch kthreads without - HAVE_RELIABLE_STACKTRACE. 3. For idle "swapper" tasks, since they don't ever exit the kernel, they instead have a klp_update_patch_state() call in the idle loop which @@ -138,27 +131,16 @@ safe to patch tasks: (Note there's not yet such an approach for kthreads.) -All the above approaches may be skipped by setting the 'immediate' flag -in the 'klp_patch' struct, which will disable per-task consistency and -patch all tasks immediately. This can be useful if the patch doesn't -change any function or data semantics. Note that, even with this flag -set, it's possible that some tasks may still be running with an old -version of the function, until that function returns. +Architectures which don't have HAVE_RELIABLE_STACKTRACE solely rely on +the second approach. It's highly likely that some tasks may still be +running with an old version of the function, until that function +returns. In this case you would have to signal the tasks. This +especially applies to kthreads. They may not be woken up and would need +to be forced. See below for more information. -There's also an 'immediate' flag in the 'klp_func' struct which allows -you to specify that certain functions in the patch can be applied -without per-task consistency. This might be useful if you want to patch -a common function like schedule(), and the function change doesn't need -consistency but the rest of the patch does. - -For architectures which don't have HAVE_RELIABLE_STACKTRACE, the user -must set patch->immediate which causes all tasks to be patched -immediately. This option should be used with care, only when the patch -doesn't change any function or data semantics. - -In the future, architectures which don't have HAVE_RELIABLE_STACKTRACE -may be allowed to use per-task consistency if we can come up with -another way to patch kthreads. +Unless we can come up with another way to patch kthreads, architectures +without HAVE_RELIABLE_STACKTRACE are not considered fully supported by +the kernel livepatching. The /sys/kernel/livepatch//transition file shows whether a patch is in transition. Only a single patch (the topmost patch on the stack) @@ -197,6 +179,11 @@ modules is permanently disabled when the force feature is used. It cannot be guaranteed there is no task sleeping in such module. It implies unbounded reference count if a patch module is disabled and enabled in a loop. +Moreover, the usage of force may also affect future applications of live +patches and cause even more harm to the system. Administrator should first +consider to simply cancel a transition (see above). If force is used, reboot +should be planned and no more live patches applied. + 3.1 Adding consistency model support to new architectures --------------------------------------------------------- @@ -234,13 +221,6 @@ few options: a good backup option for those architectures which don't have reliable stack traces yet. -In the meantime, patches for such architectures can bypass the -consistency model by setting klp_patch.immediate to true. This option -is perfectly fine for patches which don't change the semantics of the -patched functions. In practice, this is usable for ~90% of security -fixes. Use of this option also means the patch can't be unloaded after -it has been disabled. - 4. Livepatch module =================== @@ -296,9 +276,6 @@ into three levels: only for a particular object ( vmlinux or a kernel module ). Note that kallsyms allows for searching symbols according to the object name. - There's also an 'immediate' flag which, when set, patches the - function immediately, bypassing the consistency model safety checks. - + struct klp_object defines an array of patched functions (struct klp_func) in the same object. Where the object is either vmlinux (NULL) or a module name. @@ -317,9 +294,6 @@ into three levels: symbols are found. The only exception are symbols from objects (kernel modules) that have not been loaded yet. - Setting the 'immediate' flag applies the patch to all tasks - immediately, bypassing the consistency model safety checks. - For more details on how the patch is applied on a per-task basis, see the "Consistency model" section. @@ -334,14 +308,12 @@ section "Livepatch life-cycle" below for more details about these two operations. Module removal is only safe when there are no users of the underlying -functions. The immediate consistency model is not able to detect this. The -code just redirects the functions at the very beginning and it does not -check if the functions are in use. In other words, it knows when the -functions get called but it does not know when the functions return. -Therefore it cannot be decided when the livepatch module can be safely -removed. This is solved by a hybrid consistency model. When the system is -transitioned to a new patch state (patched/unpatched) it is guaranteed that -no task sleeps or runs in the old code. +functions. This is the reason why the force feature permanently disables +the removal. The forced tasks entered the functions but we cannot say +that they returned back. Therefore it cannot be decided when the +livepatch module can be safely removed. When the system is successfully +transitioned to a new patch state (patched/unpatched) without being +forced it is guaranteed that no task sleeps or runs in the old code. 5. Livepatch life-cycle @@ -355,19 +327,12 @@ First, the patch is applied only when all patched symbols for already loaded objects are found. The error handling is much easier if this check is done before particular functions get redirected. -Second, the immediate consistency model does not guarantee that anyone is not -sleeping in the new code after the patch is reverted. This means that the new -code needs to stay around "forever". If the code is there, one could apply it -again. Therefore it makes sense to separate the operations that might be done -once and those that need to be repeated when the patch is enabled (applied) -again. - -Third, it might take some time until the entire system is migrated -when a more complex consistency model is used. The patch revert might -block the livepatch module removal for too long. Therefore it is useful -to revert the patch using a separate operation that might be called -explicitly. But it does not make sense to remove all information -until the livepatch module is really removed. +Second, it might take some time until the entire system is migrated with +the hybrid consistency model being used. The patch revert might block +the livepatch module removal for too long. Therefore it is useful to +revert the patch using a separate operation that might be called +explicitly. But it does not make sense to remove all information until +the livepatch module is really removed. 5.1. Registration -- cgit From 9f0372488cc9243018a812e8cfbf27de650b187b Mon Sep 17 00:00:00 2001 From: "Ernesto A. Fernández" Date: Thu, 11 Jan 2018 13:43:33 -0500 Subject: ext4: correct documentation for grpid mount option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The grpid option is currently described as being the same as nogrpid. Signed-off-by: Ernesto A. Fernández Signed-off-by: Theodore Ts'o Cc: stable@vger.kernel.org --- Documentation/filesystems/ext4.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 75236c0c2ac2..d081ce0482cc 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -233,7 +233,7 @@ data_err=ignore(*) Just print an error message if an error occurs data_err=abort Abort the journal if an error occurs in a file data buffer in ordered mode. -grpid Give objects the same group ID as their creator. +grpid New objects have the group ID of their parent. bsdgroups nogrpid (*) New objects have the group ID of their creator. -- cgit From 3394f594de244632c682f9faee054063158f8941 Mon Sep 17 00:00:00 2001 From: Patrick Bruenn Date: Mon, 18 Dec 2017 12:51:30 +0100 Subject: dt-bindings: rtc: add bindings for i.MX53 SRTC Document the binding for i.MX53 SRTC implemented by rtc-mxc_v2 Signed-off-by: Patrick Bruenn Reviewed-by: Rob Herring Signed-off-by: Alexandre Belloni --- Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt b/Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt new file mode 100644 index 000000000000..79d7e87b0d91 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-mxc_v2.txt @@ -0,0 +1,17 @@ +* i.MX53 Secure Real Time Clock (SRTC) + +Required properties: +- compatible: should be: "fsl,imx53-rtc" +- reg: physical base address of the controller and length of memory mapped + region. +- clocks: should contain the phandle for the rtc clock +- interrupts: rtc alarm interrupt + +Example: + +rtc@53fa4000 { + compatible = "fsl,imx53-rtc"; + reg = <0x53fa4000 0x4000>; + interrupts = <24>; + clocks = <&clks IMX5_CLK_SRTC_GATE>; +}; -- cgit From 81fdc7afdd7dbf2fdd5139049b887121472015ef Mon Sep 17 00:00:00 2001 From: Alexandre Belloni Date: Fri, 12 Jan 2018 00:00:21 +0100 Subject: Documentation: rtc: move sysfs documentation to ABI The sysfs documentation should be located under Documentation/ABI. Signed-off-by: Alexandre Belloni --- Documentation/ABI/testing/sysfs-class-rtc | 89 +++++++++++++++++++++++++++++++ Documentation/rtc.txt | 32 ----------- 2 files changed, 89 insertions(+), 32 deletions(-) create mode 100644 Documentation/ABI/testing/sysfs-class-rtc (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-class-rtc b/Documentation/ABI/testing/sysfs-class-rtc new file mode 100644 index 000000000000..a19f5e2def3a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtc @@ -0,0 +1,89 @@ +What: /sys/class/rtc/ +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + The rtc/ class subdirectory belongs to the RTC subsystem. + +What: /sys/class/rtc/rtcX/ +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + The /sys/class/rtc/rtc{0,1,2,3,...} directories correspond + to each RTC device. + +What: /sys/class/rtc/rtcX/date +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + RTC-provided date in YYYY-MM-DD format + +What: /sys/class/rtc/rtcX/hctosys +Date: September 2009 +KernelVersion: 2.6.32 +Contact: linux-rtc@vger.kernel.org +Description: + 1 if the RTC provided the system time at boot via the + CONFIG_RTC_HCTOSYS kernel option, 0 otherwise + +What: /sys/class/rtc/rtcX/max_user_freq +Date: October 2007 +KernelVersion: 2.6.24 +Contact: linux-rtc@vger.kernel.org +Description: + The maximum interrupt rate an unprivileged user may request + from this RTC. + +What: /sys/class/rtc/rtcX/name +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + The name of the RTC corresponding to this sysfs directory + +What: /sys/class/rtc/rtcX/since_epoch +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + RTC-provided time as the number of seconds since the epoch + +What: /sys/class/rtc/rtcX/time +Date: March 2006 +KernelVersion: 2.6.17 +Contact: linux-rtc@vger.kernel.org +Description: + RTC-provided time in 24-hour notation (hh:mm:ss) + +What: /sys/class/rtc/rtcX/*/nvmem +Date: February 2016 +KernelVersion: 4.6 +Contact: linux-rtc@vger.kernel.org +Description: + The non volatile storage exported as a raw file, as described in + Documentation/nvmem/nvmem.txt + +What: /sys/class/rtc/rtcX/offset +Date: February 2016 +KernelVersion: 4.6 +Contact: linux-rtc@vger.kernel.org +Description: + The amount which the rtc clock has been adjusted in firmware. + Visible only if the driver supports clock offset adjustment. + The unit is parts per billion, i.e. The number of clock ticks + which are added to or removed from the rtc's base clock per + billion ticks. A positive value makes a day pass more slowly, + longer, and a negative value makes a day pass more quickly. + +What: /sys/class/rtc/rtcX/wakealarm +Date: February 2007 +KernelVersion: 2.6.20 +Contact: linux-rtc@vger.kernel.org +Description: + The time at which the clock will generate a system wakeup event. + This is a one shot wakeup event, so must be reset after wake if + a daily wakeup is required. Format is seconds since the epoch by + default, or if there's a leading +, seconds in the future, or if + there is a leading +=, seconds ahead of the current alarm. diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index c0c977445fb9..f521262cdc85 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,38 +136,6 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. -SYSFS interface ---------------- - -The sysfs interface under /sys/class/rtc/rtcN provides access to various -rtc attributes without requiring the use of ioctls. All dates and times -are in the RTC's timezone, rather than in system time. - -================ ============================================================== -date RTC-provided date -hctosys 1 if the RTC provided the system time at boot via the - CONFIG_RTC_HCTOSYS kernel option, 0 otherwise -max_user_freq The maximum interrupt rate an unprivileged user may request - from this RTC. -name The name of the RTC corresponding to this sysfs directory -since_epoch The number of seconds since the epoch according to the RTC -time RTC-provided time -wakealarm The time at which the clock will generate a system wakeup - event. This is a one shot wakeup event, so must be reset - after wake if a daily wakeup is required. Format is seconds - since the epoch by default, or if there's a leading +, seconds - in the future, or if there is a leading +=, seconds ahead of - the current alarm. -offset The amount which the rtc clock has been adjusted in firmware. - Visible only if the driver supports clock offset adjustment. - The unit is parts per billion, i.e. The number of clock ticks - which are added to or removed from the rtc's base clock per - billion ticks. A positive value makes a day pass more slowly, - longer, and a negative value makes a day pass more quickly. -*/nvmem The non volatile storage exported as a raw file, as described - in Documentation/nvmem/nvmem.txt -================ ============================================================== - IOCTL interface --------------- -- cgit From d5bc5cde844ebecbc6fac2d65d23610cfd3affc3 Mon Sep 17 00:00:00 2001 From: Aishwarya Pant Date: Mon, 1 Jan 2018 23:00:42 +0530 Subject: Documentation: rtc: add sysfs file permissions Annotate the sysfs interface of rtc with file specific permissions (RO/RW). Signed-off-by: Aishwarya Pant Signed-off-by: Alexandre Belloni --- Documentation/ABI/testing/sysfs-class-rtc | 40 ++++++++++++++++--------------- 1 file changed, 21 insertions(+), 19 deletions(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-class-rtc b/Documentation/ABI/testing/sysfs-class-rtc index a19f5e2def3a..cf60412882f0 100644 --- a/Documentation/ABI/testing/sysfs-class-rtc +++ b/Documentation/ABI/testing/sysfs-class-rtc @@ -18,14 +18,14 @@ Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - RTC-provided date in YYYY-MM-DD format + (RO) RTC-provided date in YYYY-MM-DD format What: /sys/class/rtc/rtcX/hctosys Date: September 2009 KernelVersion: 2.6.32 Contact: linux-rtc@vger.kernel.org Description: - 1 if the RTC provided the system time at boot via the + (RO) 1 if the RTC provided the system time at boot via the CONFIG_RTC_HCTOSYS kernel option, 0 otherwise What: /sys/class/rtc/rtcX/max_user_freq @@ -33,7 +33,7 @@ Date: October 2007 KernelVersion: 2.6.24 Contact: linux-rtc@vger.kernel.org Description: - The maximum interrupt rate an unprivileged user may request + (RW) The maximum interrupt rate an unprivileged user may request from this RTC. What: /sys/class/rtc/rtcX/name @@ -41,49 +41,51 @@ Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - The name of the RTC corresponding to this sysfs directory + (RO) The name of the RTC corresponding to this sysfs directory What: /sys/class/rtc/rtcX/since_epoch Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - RTC-provided time as the number of seconds since the epoch + (RO) RTC-provided time as the number of seconds since the epoch What: /sys/class/rtc/rtcX/time Date: March 2006 KernelVersion: 2.6.17 Contact: linux-rtc@vger.kernel.org Description: - RTC-provided time in 24-hour notation (hh:mm:ss) + (RO) RTC-provided time in 24-hour notation (hh:mm:ss) What: /sys/class/rtc/rtcX/*/nvmem Date: February 2016 KernelVersion: 4.6 Contact: linux-rtc@vger.kernel.org Description: - The non volatile storage exported as a raw file, as described in - Documentation/nvmem/nvmem.txt + (RW) The non volatile storage exported as a raw file, as + described in Documentation/nvmem/nvmem.txt What: /sys/class/rtc/rtcX/offset Date: February 2016 KernelVersion: 4.6 Contact: linux-rtc@vger.kernel.org Description: - The amount which the rtc clock has been adjusted in firmware. - Visible only if the driver supports clock offset adjustment. - The unit is parts per billion, i.e. The number of clock ticks - which are added to or removed from the rtc's base clock per - billion ticks. A positive value makes a day pass more slowly, - longer, and a negative value makes a day pass more quickly. + (RW) The amount which the rtc clock has been adjusted in + firmware. Visible only if the driver supports clock offset + adjustment. The unit is parts per billion, i.e. The number of + clock ticks which are added to or removed from the rtc's base + clock per billion ticks. A positive value makes a day pass more + slowly, longer, and a negative value makes a day pass more + quickly. What: /sys/class/rtc/rtcX/wakealarm Date: February 2007 KernelVersion: 2.6.20 Contact: linux-rtc@vger.kernel.org Description: - The time at which the clock will generate a system wakeup event. - This is a one shot wakeup event, so must be reset after wake if - a daily wakeup is required. Format is seconds since the epoch by - default, or if there's a leading +, seconds in the future, or if - there is a leading +=, seconds ahead of the current alarm. + (RW) The time at which the clock will generate a system wakeup + event. This is a one shot wakeup event, so must be reset after + wake if a daily wakeup is required. Format is seconds since the + epoch by default, or if there's a leading +, seconds in the + future, or if there is a leading +=, seconds ahead of the + current alarm. -- cgit From 796c0ad79ee65abb9c891e44ccd6e347a6be486f Mon Sep 17 00:00:00 2001 From: Aishwarya Pant Date: Mon, 1 Jan 2018 23:01:24 +0530 Subject: Documentation: rtc: move iotcl interface documentation to ABI The ioctl interface should be in Documentation/ABI along with the rest of the interfaces. Signed-off-by: Aishwarya Pant Signed-off-by: Alexandre Belloni --- Documentation/ABI/testing/rtc-cdev | 42 ++++++++++++++++++++++++++++++++ Documentation/rtc.txt | 49 ++------------------------------------ 2 files changed, 44 insertions(+), 47 deletions(-) create mode 100644 Documentation/ABI/testing/rtc-cdev (limited to 'Documentation') diff --git a/Documentation/ABI/testing/rtc-cdev b/Documentation/ABI/testing/rtc-cdev new file mode 100644 index 000000000000..97447283f13b --- /dev/null +++ b/Documentation/ABI/testing/rtc-cdev @@ -0,0 +1,42 @@ +What: /dev/rtcX +Date: April 2005 +KernelVersion: 2.6.12 +Contact: linux-rtc@vger.kernel.org +Description: + The ioctl interface to drivers for real-time clocks (RTCs). + Following actions are supported: + + * RTC_RD_TIME, RTC_SET_TIME: Read or set the RTC time. Time + format is a Gregorian calendar date and 24 hour wall clock + time. + + * RTC_AIE_ON, RTC_AIE_OFF: Enable or disable the alarm interrupt + for RTCs that support alarms + + * RTC_ALM_READ, RTC_ALM_SET: Read or set the alarm time for + RTCs that support alarms. Can be set upto 24 hours in the + future. Requires a separate RTC_AIE_ON call to enable the + alarm interrupt. (Prefer to use RTC_WKALM_*) + + * RTC_WKALM_RD, RTC_WKALM_SET: For RTCs that support a more + powerful interface, which can issue alarms beyond 24 hours and + enable IRQs in the same request. + + * RTC_PIE_ON, RTC_PIE_OFF: Enable or disable the periodic + interrupt for RTCs that support periodic interrupts. + + * RTC_UIE_ON, RTC_UIE_OFF: Enable or disable the update + interrupt for RTCs that support it. + + * RTC_IRQP_READ, RTC_IRQP_SET: Read or set the frequency for + periodic interrupts for RTCs that support periodic interrupts. + Requires a separate RTC_PIE_ON call to enable the periodic + interrupts. + + The ioctl() calls supported by the older /dev/rtc interface are + also supported by the newer RTC class framework. However, + because the chips and systems are not standardized, some PC/AT + functionality might not be provided. And in the same way, some + newer features -- including those enabled by ACPI -- are exposed + by the RTC class framework, but can't be supported by the older + driver. diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index f521262cdc85..a129acf38537 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -136,50 +136,5 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. -IOCTL interface ---------------- - -The ioctl() calls supported by /dev/rtc are also supported by the RTC class -framework. However, because the chips and systems are not standardized, -some PC/AT functionality might not be provided. And in the same way, some -newer features -- including those enabled by ACPI -- are exposed by the -RTC class framework, but can't be supported by the older driver. - - * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading - time, returning the result as a Gregorian calendar date and 24 hour - wall clock time. To be most useful, this time may also be updated. - - * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC - is connected to an IRQ line, it can often issue an alarm IRQ up to - 24 hours in the future. (Use RTC_WKALM_* by preference.) - - * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond - the next 24 hours use a slightly more powerful API, which supports - setting the longer alarm time and enabling its IRQ using a single - request (using the same model as EFI firmware). - - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework - will emulate this mechanism. - - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls - are emulated via a kernel hrtimer. - -In many cases, the RTC alarm can be a system wake event, used to force -Linux out of a low power sleep state (or hibernation) back to a fully -operational state. For example, a system could enter a deep power saving -state until it's time to execute some scheduled tasks. - -Note that many of these ioctls are handled by the common rtc-dev interface. -Some common examples: - - * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be - called with appropriate values. - - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets - the alarm rtc_timer. May call the set_alarm driver function. - - * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - - * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. - -If all else fails, check out the tools/testing/selftests/timers/rtctest.c test! +Check out tools/testing/selftests/timers/rtctest.c for an example usage of the +ioctl interface. -- cgit From cdd10409914184c7eee5ae3e11beb890c9c16c61 Mon Sep 17 00:00:00 2001 From: Viresh Kumar Date: Thu, 11 Jan 2018 11:28:52 +0530 Subject: arm: spear13xx: Fix dmas cells The "dmas" cells for the designware DMA controller need to have only 3 properties apart from the phandle: request line, src master and destination master. But the commit 6e8887f60f60 updated it incorrectly while moving from platform code to DT. Fix it. Cc: stable@vger.kernel.org # v3.10+ Fixes: 6e8887f60f60 ("ARM: SPEAr13xx: Pass generic DW DMAC platform data from DT") Reported-by: Arnd Bergmann Signed-off-by: Viresh Kumar Signed-off-by: Olof Johansson --- Documentation/devicetree/bindings/dma/snps-dma.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/dma/snps-dma.txt b/Documentation/devicetree/bindings/dma/snps-dma.txt index a122723907ac..99acc712f83a 100644 --- a/Documentation/devicetree/bindings/dma/snps-dma.txt +++ b/Documentation/devicetree/bindings/dma/snps-dma.txt @@ -64,6 +64,6 @@ Example: reg = <0xe0000000 0x1000>; interrupts = <0 35 0x4>; dmas = <&dmahost 12 0 1>, - <&dmahost 13 0 1 0>; + <&dmahost 13 1 0>; dma-names = "rx", "rx"; }; -- cgit From 2f46a2bc2694877332f9c1ff47acb7fa117e168a Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Thu, 11 Jan 2018 23:30:09 -0500 Subject: fscrypt: document symlink length restriction Document that encryption reduces the maximum length of a symlink target slightly. Signed-off-by: Eric Biggers Signed-off-by: Theodore Ts'o --- Documentation/filesystems/fscrypt.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 776ddc655f79..cfbc18f0d9c9 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -448,8 +448,14 @@ astute users may notice some differences in behavior: - The st_size of an encrypted symlink will not necessarily give the length of the symlink target as required by POSIX. It will actually - give the length of the ciphertext, which may be slightly longer than - the plaintext due to the NUL-padding. + give the length of the ciphertext, which will be slightly longer + than the plaintext due to NUL-padding and an extra 2-byte overhead. + +- The maximum length of an encrypted symlink is 2 bytes shorter than + the maximum length of an unencrypted symlink. For example, on an + EXT4 filesystem with a 4K block size, unencrypted symlinks can be up + to 4095 bytes long, while encrypted symlinks can only be up to 4093 + bytes long (both lengths excluding the terminating null). Note that mmap *is* supported. This is possible because the pagecache for an encrypted file contains the plaintext, not the ciphertext. -- cgit From 7d9bfdac31d77305a28531033e604264ae3e449c Mon Sep 17 00:00:00 2001 From: Tony Lindgren Date: Wed, 10 Jan 2018 10:14:15 -0800 Subject: ARM: dts: Fix smartreflex compatible for omap3 shared mpu-iva instance The smartreflex instance for mpu and iva is shared. Let's fix this as I've already gotten confused myself few times wondering where the mpu instance is. Note that we are still probing the driver using platform data so this change is safe to do. Signed-off-by: Tony Lindgren --- Documentation/devicetree/bindings/power/ti-smartreflex.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/ti-smartreflex.txt b/Documentation/devicetree/bindings/power/ti-smartreflex.txt index 9780957c9115..21ef14d6af12 100644 --- a/Documentation/devicetree/bindings/power/ti-smartreflex.txt +++ b/Documentation/devicetree/bindings/power/ti-smartreflex.txt @@ -7,7 +7,7 @@ Required properties: compatible: Shall be one of the following: "ti,omap3-smartreflex-core" - "ti,omap3-smartreflex-iva" + "ti,omap3-smartreflex-mpu-iva" "ti,omap4-smartreflex-core" "ti,omap4-smartreflex-mpu" "ti,omap4-smartreflex-iva" -- cgit From 4b1a29a7f5425d32640b34b8a755f34e02f64d0f Mon Sep 17 00:00:00 2001 From: Masami Hiramatsu Date: Sat, 13 Jan 2018 02:56:03 +0900 Subject: error-injection: Support fault injection framework Support in-kernel fault-injection framework via debugfs. This allows you to inject a conditional error to specified function using debugfs interfaces. Here is the result of test script described in Documentation/fault-injection/fault-injection.txt =========== # ./test_fail_function.sh 1+0 records in 1+0 records out 1048576 bytes (1.0 MB, 1.0 MiB) copied, 0.0227404 s, 46.1 MB/s btrfs-progs v4.4 See http://btrfs.wiki.kernel.org for more information. Label: (null) UUID: bfa96010-12e9-4360-aed0-42eec7af5798 Node size: 16384 Sector size: 4096 Filesystem size: 1001.00MiB Block group profiles: Data: single 8.00MiB Metadata: DUP 58.00MiB System: DUP 12.00MiB SSD detected: no Incompat features: extref, skinny-metadata Number of devices: 1 Devices: ID SIZE PATH 1 1001.00MiB /dev/loop2 mount: mount /dev/loop2 on /opt/tmpmnt failed: Cannot allocate memory SUCCESS! =========== Signed-off-by: Masami Hiramatsu Reviewed-by: Josef Bacik Signed-off-by: Alexei Starovoitov --- Documentation/fault-injection/fault-injection.txt | 68 +++++++++++++++++++++++ 1 file changed, 68 insertions(+) (limited to 'Documentation') diff --git a/Documentation/fault-injection/fault-injection.txt b/Documentation/fault-injection/fault-injection.txt index 918972babcd8..f4a32463ca48 100644 --- a/Documentation/fault-injection/fault-injection.txt +++ b/Documentation/fault-injection/fault-injection.txt @@ -30,6 +30,12 @@ o fail_mmc_request injects MMC data errors on devices permitted by setting debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request +o fail_function + + injects error return on specific functions, which are marked by + ALLOW_ERROR_INJECTION() macro, by setting debugfs entries + under /sys/kernel/debug/fail_function. No boot option supported. + Configure fault-injection capabilities behavior ----------------------------------------------- @@ -123,6 +129,29 @@ configuration of fault-injection capabilities. default is 'N', setting it to 'Y' will disable failure injections when dealing with private (address space) futexes. +- /sys/kernel/debug/fail_function/inject: + + Format: { 'function-name' | '!function-name' | '' } + specifies the target function of error injection by name. + If the function name leads '!' prefix, given function is + removed from injection list. If nothing specified ('') + injection list is cleared. + +- /sys/kernel/debug/fail_function/injectable: + + (read only) shows error injectable functions and what type of + error values can be specified. The error type will be one of + below; + - NULL: retval must be 0. + - ERRNO: retval must be -1 to -MAX_ERRNO (-4096). + - ERR_NULL: retval must be 0 or -1 to -MAX_ERRNO (-4096). + +- /sys/kernel/debug/fail_function//retval: + + specifies the "error" return value to inject to the given + function for given function. This will be created when + user specifies new injection entry. + o Boot option In order to inject faults while debugfs is not available (early boot time), @@ -268,6 +297,45 @@ trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT echo "Injecting errors into the module $module... (interrupt to stop)" sleep 1000000 +------------------------------------------------------------------------------ + +o Inject open_ctree error while btrfs mount + +#!/bin/bash + +rm -f testfile.img +dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1 +DEVICE=$(losetup --show -f testfile.img) +mkfs.btrfs -f $DEVICE +mkdir -p tmpmnt + +FAILTYPE=fail_function +FAILFUNC=open_ctree +echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject +echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval +echo N > /sys/kernel/debug/$FAILTYPE/task-filter +echo 100 > /sys/kernel/debug/$FAILTYPE/probability +echo 0 > /sys/kernel/debug/$FAILTYPE/interval +echo -1 > /sys/kernel/debug/$FAILTYPE/times +echo 0 > /sys/kernel/debug/$FAILTYPE/space +echo 1 > /sys/kernel/debug/$FAILTYPE/verbose + +mount -t btrfs $DEVICE tmpmnt +if [ $? -ne 0 ] +then + echo "SUCCESS!" +else + echo "FAILED!" + umount tmpmnt +fi + +echo > /sys/kernel/debug/$FAILTYPE/inject + +rmdir tmpmnt +losetup -d $DEVICE +rm testfile.img + + Tool to run command with failslab or fail_page_alloc ---------------------------------------------------- In order to make it easier to accomplish the tasks mentioned above, we can use -- cgit From 86f04f640058143388f56c048f86e66ea5204ae2 Mon Sep 17 00:00:00 2001 From: James Morse Date: Mon, 8 Jan 2018 15:38:08 +0000 Subject: Docs: dt: add devicetree binding for describing arm64 SDEI firmware The Software Delegated Exception Interface (SDEI) is an ARM standard for registering callbacks from the platform firmware into the OS. This is typically used to implement RAS notifications, or from an IRQ that has been promoted to a firmware-assisted NMI. Add a new devicetree binding to describe the SDE firmware interface. Signed-off-by: James Morse Acked-by: Rob Herring Signed-off-by: Catalin Marinas --- .../devicetree/bindings/arm/firmware/sdei.txt | 42 ++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 Documentation/devicetree/bindings/arm/firmware/sdei.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/arm/firmware/sdei.txt b/Documentation/devicetree/bindings/arm/firmware/sdei.txt new file mode 100644 index 000000000000..ee3f0ff49889 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/firmware/sdei.txt @@ -0,0 +1,42 @@ +* Software Delegated Exception Interface (SDEI) + +Firmware implementing the SDEI functions described in ARM document number +ARM DEN 0054A ("Software Delegated Exception Interface") can be used by +Linux to receive notification of events such as those generated by +firmware-first error handling, or from an IRQ that has been promoted to +a firmware-assisted NMI. + +The interface provides a number of API functions for registering callbacks +and enabling/disabling events. Functions are invoked by trapping to the +privilege level of the SDEI firmware (specified as part of the binding +below) and passing arguments in a manner specified by the "SMC Calling +Convention (ARM DEN 0028B): + + r0 => 32-bit Function ID / return value + {r1 - r3} => Parameters + +Note that the immediate field of the trapping instruction must be set +to #0. + +The SDEI_EVENT_REGISTER function registers a callback in the kernel +text to handle the specified event number. + +The sdei node should be a child node of '/firmware' and have required +properties: + + - compatible : should contain: + * "arm,sdei-1.0" : For implementations complying to SDEI version 1.x. + + - method : The method of calling the SDEI firmware. Permitted + values are: + * "smc" : SMC #0, with the register assignments specified in this + binding. + * "hvc" : HVC #0, with the register assignments specified in this + binding. +Example: + firmware { + sdei { + compatible = "arm,sdei-1.0"; + method = "smc"; + }; + }; -- cgit From 9555003a3373b0cb7ca753779115f1d6f96fcab1 Mon Sep 17 00:00:00 2001 From: Antoine Tenart Date: Thu, 14 Dec 2017 15:26:59 +0100 Subject: Documentation/bindings: crypto: document the SafeXcel EIP97 compatible This patch adds the SafeXcel EIP97 compatible to the Inside Secure device tree bindings documentation. Signed-off-by: Antoine Tenart Signed-off-by: Herbert Xu --- Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt b/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt index fbc07d12322f..30c3ce6b502e 100644 --- a/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt +++ b/Documentation/devicetree/bindings/crypto/inside-secure-safexcel.txt @@ -1,7 +1,8 @@ Inside Secure SafeXcel cryptographic engine Required properties: -- compatible: Should be "inside-secure,safexcel-eip197". +- compatible: Should be "inside-secure,safexcel-eip197" or + "inside-secure,safexcel-eip97". - reg: Base physical address of the engine and length of memory mapped region. - interrupts: Interrupt numbers for the rings and engine. - interrupt-names: Should be "ring0", "ring1", "ring2", "ring3", "eip", "mem". -- cgit From bb48711800e6d7aedbf4dfd3367e0ab1270a6bea Mon Sep 17 00:00:00 2001 From: Stephen Boyd Date: Wed, 13 Dec 2017 14:19:37 -0800 Subject: arm64: cpu_errata: Add Kryo to Falkor 1003 errata The Kryo CPUs are also affected by the Falkor 1003 errata, so we need to do the same workaround on Kryo CPUs. The MIDR is slightly more complicated here, where the PART number is not always the same when looking at all the bits from 15 to 4. Drop the lower 8 bits and just look at the top 4 to see if it's '2' and then consider those as Kryo CPUs. This covers all the combinations without having to list them all out. Fixes: 38fd94b0275c ("arm64: Work around Falkor erratum 1003") Acked-by: Will Deacon Signed-off-by: Stephen Boyd Signed-off-by: Catalin Marinas --- Documentation/arm64/silicon-errata.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index 304bf22bb83c..b9d93e981a05 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -72,6 +72,6 @@ stable kernels. | Hisilicon | Hip0{6,7} | #161010701 | N/A | | Hisilicon | Hip07 | #161600802 | HISILICON_ERRATUM_161600802 | | | | | | -| Qualcomm Tech. | Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 | +| Qualcomm Tech. | Kryo/Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 | | Qualcomm Tech. | Falkor v1 | E1009 | QCOM_FALKOR_ERRATUM_1009 | | Qualcomm Tech. | QDF2400 ITS | E0065 | QCOM_QDF2400_ERRATUM_0065 | -- cgit From 1c2f11466b8b12d2487bd79ac203086c8ce60e1d Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Fri, 12 Jan 2018 22:34:23 +0100 Subject: net: ethernet: Add DT bindings for the Gemini ethernet MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds the device tree bindings for the Gemini ethernet controller. It is pretty straight-forward, using standard bindings and modelling the two child ports as child devices under the parent ethernet controller device. Cc: devicetree@vger.kernel.org Cc: Tobias Waldvogel Cc: Michał Mirosław Reviewed-by: Rob Herring Signed-off-by: Linus Walleij Signed-off-by: David S. Miller --- .../bindings/net/cortina,gemini-ethernet.txt | 92 ++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt b/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt new file mode 100644 index 000000000000..6c559981d110 --- /dev/null +++ b/Documentation/devicetree/bindings/net/cortina,gemini-ethernet.txt @@ -0,0 +1,92 @@ +Cortina Systems Gemini Ethernet Controller +========================================== + +This ethernet controller is found in the Gemini SoC family: +StorLink SL3512 and SL3516, also known as Cortina Systems +CS3512 and CS3516. + +Required properties: +- compatible: must be "cortina,gemini-ethernet" +- reg: must contain the global registers and the V-bit and A-bit + memory areas, in total three register sets. +- syscon: a phandle to the system controller +- #address-cells: must be specified, must be <1> +- #size-cells: must be specified, must be <1> +- ranges: should be state like this giving a 1:1 address translation + for the subnodes + +The subnodes represents the two ethernet ports in this device. +They are not independent of each other since they share resources +in the parent node, and are thus children. + +Required subnodes: +- port0: contains the resources for ethernet port 0 +- port1: contains the resources for ethernet port 1 + +Required subnode properties: +- compatible: must be "cortina,gemini-ethernet-port" +- reg: must contain two register areas: the DMA/TOE memory and + the GMAC memory area of the port +- interrupts: should contain the interrupt line of the port. + this is nominally a level interrupt active high. +- resets: this must provide an SoC-integrated reset line for + the port. +- clocks: this should contain a handle to the PCLK clock for + clocking the silicon in this port +- clock-names: must be "PCLK" + +Optional subnode properties: +- phy-mode: see ethernet.txt +- phy-handle: see ethernet.txt + +Example: + +mdio-bus { + (...) + phy0: ethernet-phy@1 { + reg = <1>; + device_type = "ethernet-phy"; + }; + phy1: ethernet-phy@3 { + reg = <3>; + device_type = "ethernet-phy"; + }; +}; + + +ethernet@60000000 { + compatible = "cortina,gemini-ethernet"; + reg = <0x60000000 0x4000>, /* Global registers, queue */ + <0x60004000 0x2000>, /* V-bit */ + <0x60006000 0x2000>; /* A-bit */ + syscon = <&syscon>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + gmac0: ethernet-port@0 { + compatible = "cortina,gemini-ethernet-port"; + reg = <0x60008000 0x2000>, /* Port 0 DMA/TOE */ + <0x6000a000 0x2000>; /* Port 0 GMAC */ + interrupt-parent = <&intcon>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH>; + resets = <&syscon GEMINI_RESET_GMAC0>; + clocks = <&syscon GEMINI_CLK_GATE_GMAC0>; + clock-names = "PCLK"; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + }; + + gmac1: ethernet-port@1 { + compatible = "cortina,gemini-ethernet-port"; + reg = <0x6000c000 0x2000>, /* Port 1 DMA/TOE */ + <0x6000e000 0x2000>; /* Port 1 GMAC */ + interrupt-parent = <&intcon>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; + resets = <&syscon GEMINI_RESET_GMAC1>; + clocks = <&syscon GEMINI_CLK_GATE_GMAC1>; + clock-names = "PCLK"; + phy-mode = "rgmii"; + phy-handle = <&phy1>; + }; +}; -- cgit From 1532d9e87e8b2377f12929f9e40724d5fbe6ecc5 Mon Sep 17 00:00:00 2001 From: Tomasz Majchrzak Date: Wed, 27 Dec 2017 10:31:40 +0100 Subject: raid5-ppl: PPL support for disks with write-back cache enabled In order to provide data consistency with PPL for disks with write-back cache enabled all data has to be flushed to disks before next PPL entry. The disks to be flushed are marked in the bitmap. It's modified under a mutex and it's only read after PPL io unit is submitted. A limitation of 64 disks in the array has been introduced to keep data structures and implementation simple. RAID5 arrays with so many disks are not likely due to high risk of multiple disks failure. Such restriction should not be a real life limitation. With write-back cache disabled next PPL entry is submitted when data write for current one completes. Data flush defers next log submission so trigger it when there are no stripes for handling found. As PPL assures all data is flushed to disk at request completion, just acknowledge flush request when PPL is enabled. Signed-off-by: Tomasz Majchrzak Signed-off-by: Shaohua Li --- Documentation/md/raid5-ppl.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.txt index 127072b09363..bfa092589e00 100644 --- a/Documentation/md/raid5-ppl.txt +++ b/Documentation/md/raid5-ppl.txt @@ -39,6 +39,7 @@ case the behavior is the same as in plain raid5. PPL is available for md version-1 metadata and external (specifically IMSM) metadata arrays. It can be enabled using mdadm option --consistency-policy=ppl. -Currently, volatile write-back cache should be disabled on all member drives -when using PPL. Otherwise it cannot guarantee consistency in case of power -failure. +There is a limitation of maximum 64 disks in the array for PPL. It allows to +keep data structures and implementation simple. RAID5 arrays with so many disks +are not likely due to high risk of multiple disks failure. Such restriction +should not be a real life limitation. -- cgit From 5855564c8ab2d9cefca7b2933bd19818eb795e40 Mon Sep 17 00:00:00 2001 From: Paul Mackerras Date: Fri, 12 Jan 2018 20:55:20 +1100 Subject: KVM: PPC: Book3S HV: Enable migration of decrementer register This adds a register identifier for use with the one_reg interface to allow the decrementer expiry time to be read and written by userspace. The decrementer expiry time is in guest timebase units and is equal to the sum of the decrementer and the guest timebase. (The expiry time is used rather than the decrementer value itself because the expiry time is not constantly changing, though the decrementer value is, while the guest vcpu is not running.) Without this, a guest vcpu migrated to a new host will see its decrementer set to some random value. On POWER8 and earlier, the decrementer is 32 bits wide and counts down at 512MHz, so the guest vcpu will potentially see no decrementer interrupts for up to about 4 seconds, which will lead to a stall. With POWER9, the decrementer is now 56 bits side, so the stall can be much longer (up to 2.23 years) and more noticeable. To help work around the problem in cases where userspace has not been updated to migrate the decrementer expiry time, we now set the default decrementer expiry at vcpu creation time to the current time rather than the maximum possible value. This should mean an immediate decrementer interrupt when a migrated vcpu starts running. In cases where the decrementer is 32 bits wide and more than 4 seconds elapse between the creation of the vcpu and when it first runs, the decrementer would have wrapped around to positive values and there may still be a stall - but this is no worse than the current situation. In the large-decrementer case, we are sure to get an immediate decrementer interrupt (assuming the time from vcpu creation to first run is less than 2.23 years) and we thus avoid a very long stall. Signed-off-by: Paul Mackerras --- Documentation/virtual/kvm/api.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index f670e4b9e7f3..c6f9eebb79f2 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -1841,6 +1841,7 @@ registers, find a list below: PPC | KVM_REG_PPC_DBSR | 32 PPC | KVM_REG_PPC_TIDR | 64 PPC | KVM_REG_PPC_PSSCR | 64 + PPC | KVM_REG_PPC_DEC_EXPIRY | 64 PPC | KVM_REG_PPC_TM_GPR0 | 64 ... PPC | KVM_REG_PPC_TM_GPR31 | 64 -- cgit From 54a7fbcc17bc2881807ea8e65fa0857ec8a3a863 Mon Sep 17 00:00:00 2001 From: Franklin S Cooper Jr Date: Tue, 16 Jan 2018 17:07:11 +0530 Subject: dt-bindings: can: can-transceiver: Document new binding Add documentation to describe usage of the new can-transceiver binding. This new binding is applicable for any CAN device therefore it exists as its own document. Signed-off-by: Franklin S Cooper Jr Signed-off-by: Sekhar Nori Acked-by: Rob Herring Signed-off-by: Faiz Abbas Signed-off-by: Marc Kleine-Budde --- .../bindings/net/can/can-transceiver.txt | 24 ++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 Documentation/devicetree/bindings/net/can/can-transceiver.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/can/can-transceiver.txt b/Documentation/devicetree/bindings/net/can/can-transceiver.txt new file mode 100644 index 000000000000..0011f53ff159 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/can-transceiver.txt @@ -0,0 +1,24 @@ +Generic CAN transceiver Device Tree binding +------------------------------ + +CAN transceiver typically limits the max speed in standard CAN and CAN FD +modes. Typically these limitations are static and the transceivers themselves +provide no way to detect this limitation at runtime. For this situation, +the "can-transceiver" node can be used. + +Required Properties: + max-bitrate: a positive non 0 value that determines the max + speed that CAN/CAN-FD can run. Any other value + will be ignored. + +Examples: + +Based on Texas Instrument's TCAN1042HGV CAN Transceiver + +m_can0 { + .... + can-transceiver { + max-bitrate = <5000000>; + }; + ... +}; -- cgit From b54f9eea7667b3011e6c7e646051c7a7bfcd8165 Mon Sep 17 00:00:00 2001 From: Franklin S Cooper Jr Date: Tue, 16 Jan 2018 17:07:10 +0530 Subject: dt-bindings: can: m_can: Document new can transceiver binding Add information regarding can-transceiver binding. This is especially important for MCAN since the IP allows CAN FD mode to run significantly faster than what most transceivers are capable of. Signed-off-by: Franklin S Cooper Jr Signed-off-by: Sekhar Nori Acked-by: Rob Herring Signed-off-by: Faiz Abbas Signed-off-by: Marc Kleine-Budde --- Documentation/devicetree/bindings/net/can/m_can.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/can/m_can.txt b/Documentation/devicetree/bindings/net/can/m_can.txt index 63e90421d029..ed614383af9c 100644 --- a/Documentation/devicetree/bindings/net/can/m_can.txt +++ b/Documentation/devicetree/bindings/net/can/m_can.txt @@ -43,6 +43,11 @@ Required properties: Please refer to 2.4.1 Message RAM Configuration in Bosch M_CAN user manual for details. +Optional Subnode: +- can-transceiver : Can-transceiver subnode describing maximum speed + that can be used for CAN/CAN-FD modes. See + Documentation/devicetree/bindings/net/can/can-transceiver.txt + for details. Example: SoC dtsi: m_can1: can@20e8000 { @@ -63,4 +68,8 @@ Board dts: pinctrl-names = "default"; pinctrl-0 = <&pinctrl_m_can1>; status = "enabled"; + + can-transceiver { + max-bitrate = <5000000>; + }; }; -- cgit From 858a43aae23672d46fe802a41f4748f322965182 Mon Sep 17 00:00:00 2001 From: Wanpeng Li Date: Tue, 12 Dec 2017 17:33:02 -0800 Subject: KVM: X86: use paravirtualized TLB Shootdown MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remote TLB flush does a busy wait which is fine in bare-metal scenario. But with-in the guest, the vcpus might have been pre-empted or blocked. In this scenario, the initator vcpu would end up busy-waiting for a long amount of time; it also consumes CPU unnecessarily to wake up the target of the shootdown. This patch set adds support for KVM's new paravirtualized TLB flush; remote TLB flush does not wait for vcpus that are sleeping, instead KVM will flush the TLB as soon as the vCPU starts running again. The improvement is clearly visible when the host is overcommitted; in this case, the PV TLB flush (in addition to avoiding the wait on the main CPU) prevents preempted vCPUs from stealing precious execution time from the running ones. Testing on a Xeon Gold 6142 2.6GHz 2 sockets, 32 cores, 64 threads, so 64 pCPUs, and each VM is 64 vCPUs. ebizzy -M vanilla optimized boost 1VM 46799 48670 4% 2VM 23962 42691 78% 3VM 16152 37539 132% Cc: Paolo Bonzini Cc: Radim Krčmář Cc: Peter Zijlstra Signed-off-by: Wanpeng Li Signed-off-by: Paolo Bonzini Signed-off-by: Radim Krčmář --- Documentation/virtual/kvm/cpuid.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/virtual/kvm/cpuid.txt b/Documentation/virtual/kvm/cpuid.txt index 3c65feb83010..dcab6dc11e3b 100644 --- a/Documentation/virtual/kvm/cpuid.txt +++ b/Documentation/virtual/kvm/cpuid.txt @@ -54,6 +54,10 @@ KVM_FEATURE_PV_UNHALT || 7 || guest checks this feature bit || || before enabling paravirtualized || || spinlock support. ------------------------------------------------------------------------------ +KVM_FEATURE_PV_TLB_FLUSH || 9 || guest checks this feature bit + || || before enabling paravirtualized + || || tlb flush. +------------------------------------------------------------------------------ KVM_FEATURE_CLOCKSOURCE_STABLE_BIT || 24 || host will warn if no guest-side || || per-cpu warps are expected in || || kvmclock. -- cgit From d2279c9d7f7db7f97567368bfc4539b3411adf8d Mon Sep 17 00:00:00 2001 From: Sergey Senozhatsky Date: Fri, 5 Jan 2018 19:25:38 +0900 Subject: kallsyms: remove print_symbol() function No more print_symbol()/__print_symbol() users left, remove these symbols. It was a very old API that encouraged people use continuous lines. It had been obsoleted by %pS format specifier in a normal printk() call. Link: http://lkml.kernel.org/r/20180105102538.GC471@jagdpanzerIV Cc: Andrew Morton Cc: Russell King Cc: Catalin Marinas Cc: Mark Salter Cc: Tony Luck Cc: David Howells Cc: Yoshinori Sato Cc: Guan Xuetao Cc: Borislav Petkov Cc: Greg Kroah-Hartman Cc: Thomas Gleixner Cc: Peter Zijlstra Cc: Vineet Gupta Cc: Fengguang Wu Cc: Steven Rostedt Cc: LKML Cc: linux-arm-kernel@lists.infradead.org Cc: linux-c6x-dev@linux-c6x.org Cc: linux-ia64@vger.kernel.org Cc: linux-am33-list@redhat.com Cc: linux-sh@vger.kernel.org Cc: linux-edac@vger.kernel.org Cc: x86@kernel.org Cc: linux-snps-arc@lists.infradead.org Cc: Sergey Senozhatsky Signed-off-by: Sergey Senozhatsky Suggested-by: Joe Perches [pmladek@suse.com: updated commit message] Signed-off-by: Petr Mladek --- Documentation/filesystems/sysfs.txt | 4 ++-- Documentation/translations/zh_CN/filesystems/sysfs.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 9a3658cc399e..a1426cabcef1 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -154,8 +154,8 @@ static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, if (dev_attr->show) ret = dev_attr->show(dev, dev_attr, buf); if (ret >= (ssize_t)PAGE_SIZE) { - print_symbol("dev_attr_show: %s returned bad count\n", - (unsigned long)dev_attr->show); + printk("dev_attr_show: %pS returned bad count\n", + dev_attr->show); } return ret; } diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index 7d3b05edb8ce..452271dda141 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -167,8 +167,8 @@ static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, if (dev_attr->show) ret = dev_attr->show(dev, dev_attr, buf); if (ret >= (ssize_t)PAGE_SIZE) { - print_symbol("dev_attr_show: %s returned bad count\n", - (unsigned long)dev_attr->show); + printk("dev_attr_show: %pS returned bad count\n", + dev_attr->show); } return ret; } -- cgit From c4e0842bf141178fd5bc0cfe364609ec782fb384 Mon Sep 17 00:00:00 2001 From: "Maciej S. Szmigiero" Date: Wed, 10 Jan 2018 23:33:19 +0100 Subject: cgroup, docs: document the root cgroup behavior of cpu and io controllers Currently, cgroups v2 documentation contains only a generic remark that "How resource consumption in the root cgroup is governed is up to each controller", which isn't really telling users much, who need to dig in the code and / or commit messages to learn the exact behavior. In cgroups v1 at least the blkio controller had its operation with respect to competition between child threads and child cgroups documented in blkio-controller.txt, with references to cfq-iosched.txt. Also, cgroups v2 documentation describes v1 behavior of both cpu and blkio controllers in an "Issues with v1" section. Let's document this behavior also for cgroups v2 to make life easier for users. Signed-off-by: Maciej S. Szmigiero Signed-off-by: Tejun Heo --- Documentation/cgroup-v2.txt | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index c783bbb9d0fb..74cdeaed9f7a 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -58,6 +58,9 @@ v1 is available under Documentation/cgroup-v1/. 5-6-1. RDMA Interface Files 5-7. Misc 5-7-1. perf_event + 5-N. Non-normative information + 5-N-1. CPU controller root cgroup process behaviour + 5-N-2. IO controller root cgroup process behaviour 6. Namespace 6-1. Basics 6-2. The Root and Views @@ -421,7 +424,9 @@ The root cgroup is exempt from this restriction. Root contains processes and anonymous resource consumption which can't be associated with any other cgroups and requires special treatment from most controllers. How resource consumption in the root cgroup is governed -is up to each controller. +is up to each controller (for more information on this topic please +refer to the Non-normative information section in the Controllers +chapter). Note that the restriction doesn't get in the way if there is no enabled controller in the cgroup's "cgroup.subtree_control". This is @@ -1506,6 +1511,35 @@ always be filtered by cgroup v2 path. The controller can still be moved to a legacy hierarchy after v2 hierarchy is populated. +Non-normative information +------------------------- + +This section contains information that isn't considered to be a part of +the stable kernel API and so is subject to change. + + +CPU controller root cgroup process behaviour +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When distributing CPU cycles in the root cgroup each thread in this +cgroup is treated as if it was hosted in a separate child cgroup of the +root cgroup. This child cgroup weight is dependent on its thread nice +level. + +For details of this mapping see sched_prio_to_weight array in +kernel/sched/core.c file (values from this array should be scaled +appropriately so the neutral - nice 0 - value is 100 instead of 1024). + + +IO controller root cgroup process behaviour +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Root cgroup processes are hosted in an implicit leaf child node. +When distributing IO resources this implicit child node is taken into +account as if it was a normal child cgroup of the root cgroup with a +weight value of 200. + + Namespace ========= -- cgit From f261708b92fbc51200fee782845a2a891f67234d Mon Sep 17 00:00:00 2001 From: Arkadi Sharshevsky Date: Mon, 15 Jan 2018 08:59:12 +0100 Subject: mlxsw: documentation: Add resources ABI documentation Add resources ABI documentation. Signed-off-by: Arkadi Sharhsevsky Signed-off-by: Jiri Pirko Signed-off-by: David S. Miller --- Documentation/ABI/testing/devlink-resource-mlxsw | 33 ++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 Documentation/ABI/testing/devlink-resource-mlxsw (limited to 'Documentation') diff --git a/Documentation/ABI/testing/devlink-resource-mlxsw b/Documentation/ABI/testing/devlink-resource-mlxsw new file mode 100644 index 000000000000..259ed2948ec0 --- /dev/null +++ b/Documentation/ABI/testing/devlink-resource-mlxsw @@ -0,0 +1,33 @@ +What: /kvd/ +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The main database in the Spectrum device is a centralized + KVD database used for many of the tables used to configure + the chip including L2 FDB, L3 LPM, ECMP and more. The KVD + is divided into two sections, the first is hash-based table + and the second is a linear access table. The division + between the linear and hash-based sections is static and + require reload before the changes take effect. + +What: /kvd/linear +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The linear section of the KVD is managed by software as a + flat memory accessed using an index. + +What: /kvd/hash_single +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The hash based section of the KVD is managed by the switch + device. Used in case the key size is smaller or equal to + 64bit. + +What: /kvd/hash_double +Date: 08-Jan-2018 +KernelVersion: v4.16 +Contact: mlxsw@mellanox.com +Description: The hash based section of the KVD is managed by the switch + device. Used in case the key is larger than 64 bit. -- cgit From 18a5bf270532312178145b80c8893614367de106 Mon Sep 17 00:00:00 2001 From: Scott Bauer Date: Mon, 18 Dec 2017 10:28:08 -0700 Subject: dm: add unstriped target This device mapper "unstriped" target remaps and unstripes I/O so it is issued solely on a single drive in a HW RAID0 or dm-striped target. In a 4 drive HW RAID0 the striped target exposes 1/4th of the LBA range as a virtual drive. Each I/O to that virtual drive will only be issued to the 1 drive that was selected of the 4 drives in the HW RAID0. This unstriped target is most useful for Intel NVMe drives that have multiple cores but that do not have firmware control to pin separate LBA ranges to each discrete cpu core. Signed-off-by: Scott Bauer Signed-off-by: Heinz Mauelshagen Acked-by: Keith Busch Signed-off-by: Mike Snitzer --- Documentation/device-mapper/unstriped.txt | 124 ++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 Documentation/device-mapper/unstriped.txt (limited to 'Documentation') diff --git a/Documentation/device-mapper/unstriped.txt b/Documentation/device-mapper/unstriped.txt new file mode 100644 index 000000000000..0b2a306c54ee --- /dev/null +++ b/Documentation/device-mapper/unstriped.txt @@ -0,0 +1,124 @@ +Introduction +============ + +The device-mapper "unstriped" target provides a transparent mechanism to +unstripe a device-mapper "striped" target to access the underlying disks +without having to touch the true backing block-device. It can also be +used to unstripe a hardware RAID-0 to access backing disks. + +Parameters: + + + + The number of stripes in the RAID 0. + + + The amount of 512B sectors in the chunk striping. + + + The block device you wish to unstripe. + + + The stripe number within the device that corresponds to physical + drive you wish to unstripe. This must be 0 indexed. + + +Why use this module? +==================== + +An example of undoing an existing dm-stripe +------------------------------------------- + +This small bash script will setup 4 loop devices and use the existing +striped target to combine the 4 devices into one. It then will use +the unstriped target ontop of the striped device to access the +individual backing loop devices. We write data to the newly exposed +unstriped devices and verify the data written matches the correct +underlying device on the striped array. + +#!/bin/bash + +MEMBER_SIZE=$((128 * 1024 * 1024)) +NUM=4 +SEQ_END=$((${NUM}-1)) +CHUNK=256 +BS=4096 + +RAID_SIZE=$((${MEMBER_SIZE}*${NUM}/512)) +DM_PARMS="0 ${RAID_SIZE} striped ${NUM} ${CHUNK}" +COUNT=$((${MEMBER_SIZE} / ${BS})) + +for i in $(seq 0 ${SEQ_END}); do + dd if=/dev/zero of=member-${i} bs=${MEMBER_SIZE} count=1 oflag=direct + losetup /dev/loop${i} member-${i} + DM_PARMS+=" /dev/loop${i} 0" +done + +echo $DM_PARMS | dmsetup create raid0 +for i in $(seq 0 ${SEQ_END}); do + echo "0 1 unstriped ${NUM} ${CHUNK} ${i} /dev/mapper/raid0 0" | dmsetup create set-${i} +done; + +for i in $(seq 0 ${SEQ_END}); do + dd if=/dev/urandom of=/dev/mapper/set-${i} bs=${BS} count=${COUNT} oflag=direct + diff /dev/mapper/set-${i} member-${i} +done; + +for i in $(seq 0 ${SEQ_END}); do + dmsetup remove set-${i} +done + +dmsetup remove raid0 + +for i in $(seq 0 ${SEQ_END}); do + losetup -d /dev/loop${i} + rm -f member-${i} +done + +Another example +--------------- + +Intel NVMe drives contain two cores on the physical device. +Each core of the drive has segregated access to its LBA range. +The current LBA model has a RAID 0 128k chunk on each core, resulting +in a 256k stripe across the two cores: + + Core 0: Core 1: + __________ __________ + | LBA 512| | LBA 768| + | LBA 0 | | LBA 256| + ---------- ---------- + +The purpose of this unstriping is to provide better QoS in noisy +neighbor environments. When two partitions are created on the +aggregate drive without this unstriping, reads on one partition +can affect writes on another partition. This is because the partitions +are striped across the two cores. When we unstripe this hardware RAID 0 +and make partitions on each new exposed device the two partitions are now +physically separated. + +With the dm-unstriped target we're able to segregate an fio script that +has read and write jobs that are independent of each other. Compared to +when we run the test on a combined drive with partitions, we were able +to get a 92% reduction in read latency using this device mapper target. + + +Example dmsetup usage +===================== + +unstriped ontop of Intel NVMe device that has 2 cores +----------------------------------------------------- +dmsetup create nvmset0 --table '0 512 unstriped 2 256 0 /dev/nvme0n1 0' +dmsetup create nvmset1 --table '0 512 unstriped 2 256 1 /dev/nvme0n1 0' + +There will now be two devices that expose Intel NVMe core 0 and 1 +respectively: +/dev/mapper/nvmset0 +/dev/mapper/nvmset1 + +unstriped ontop of striped with 4 drives using 128K chunk size +-------------------------------------------------------------- +dmsetup create raid_disk0 --table '0 512 unstriped 4 256 0 /dev/mapper/striped 0' +dmsetup create raid_disk1 --table '0 512 unstriped 4 256 1 /dev/mapper/striped 0' +dmsetup create raid_disk2 --table '0 512 unstriped 4 256 2 /dev/mapper/striped 0' +dmsetup create raid_disk3 --table '0 512 unstriped 4 256 3 /dev/mapper/striped 0' -- cgit From 424da29c5a85adfcc1eda9412516efd77355d469 Mon Sep 17 00:00:00 2001 From: Mikulas Patocka Date: Wed, 2 Dec 2015 12:32:49 -0500 Subject: dm snapshot: improve documentation relative to origin suspend requirements Add a note to snapshot.txt that the origin target must be suspended when loading or unloading the snapshot target. Signed-off-by: Mikulas Patocka Signed-off-by: Mike Snitzer --- Documentation/device-mapper/snapshot.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/device-mapper/snapshot.txt b/Documentation/device-mapper/snapshot.txt index ad6949bff2e3..b8bbb516f989 100644 --- a/Documentation/device-mapper/snapshot.txt +++ b/Documentation/device-mapper/snapshot.txt @@ -49,6 +49,10 @@ The difference between persistent and transient is with transient snapshots less metadata must be saved on disk - they can be kept in memory by the kernel. +When loading or unloading the snapshot target, the corresponding +snapshot-origin or snapshot-merge target must be suspended. A failure to +suspend the origin target could result in data corruption. + * snapshot-merge -- cgit From 677210462daf48dbf69a5bd2e38deb271d1a41bf Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:40 -0500 Subject: dm cache: fix grammar in cache-policies.txt Use possessive pronoun where appropriate, instead of contraction. Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/cache-policies.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/cache-policies.txt b/Documentation/device-mapper/cache-policies.txt index d3ca8af21a31..86786d87d9a8 100644 --- a/Documentation/device-mapper/cache-policies.txt +++ b/Documentation/device-mapper/cache-policies.txt @@ -60,7 +60,7 @@ Memory usage: The mq policy used a lot of memory; 88 bytes per cache block on a 64 bit machine. -smq uses 28bit indexes to implement it's data structures rather than +smq uses 28bit indexes to implement its data structures rather than pointers. It avoids storing an explicit hit count for each block. It has a 'hotspot' queue, rather than a pre-cache, which uses a quarter of the entries (each hotspot block covers a larger area than a single @@ -84,7 +84,7 @@ resulting in better promotion/demotion decisions. Adaptability: The mq policy maintained a hit count for each cache block. For a -different block to get promoted to the cache it's hit count has to +different block to get promoted to the cache its hit count has to exceed the lowest currently in the cache. This meant it could take a long time for the cache to adapt between varying IO patterns. -- cgit From 3716e20af5b583c3e15661aab657168176baa01e Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:41 -0500 Subject: dm cache: delete obsoleted paragraph in cache.txt The 'mq' policy is no longer the default policy, and the default policy, 'smq', does not store hit counts. Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/cache.txt | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.txt index cdfd0feb294e..043524409221 100644 --- a/Documentation/device-mapper/cache.txt +++ b/Documentation/device-mapper/cache.txt @@ -143,11 +143,6 @@ the policy how big this chunk is, but it should be kept small. Like the dirty flags this data is lost if there's a crash so a safe fallback value should always be possible. -For instance, the 'mq' policy, which is currently the default policy, -uses this facility to store the hit count of the cache blocks. If -there's a crash this information will be lost, which means the cache -may be less efficient until those hit counts are regenerated. - Policy hints affect performance, not correctness. Policy messaging -- cgit From 1346638e5f80588dfafbf07315f72b84c2ab1113 Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:42 -0500 Subject: dm cache: be consistent in specifying sectors and SI units in cache.txt Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/cache.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.txt index 043524409221..79c7b6dc88ae 100644 --- a/Documentation/device-mapper/cache.txt +++ b/Documentation/device-mapper/cache.txt @@ -59,7 +59,7 @@ Fixed block size The origin is divided up into blocks of a fixed size. This block size is configurable when you first create the cache. Typically we've been using block sizes of 256KB - 1024KB. The block size must be between 64 -(32KB) and 2097152 (1GB) and a multiple of 64 (32KB). +sectors (32KB) and 2097152 sectors (1GB) and a multiple of 64 sectors (32KB). Having a fixed block size simplifies the target a lot. But it is something of a compromise. For instance, a small part of a block may be @@ -119,7 +119,7 @@ doing here to avoid migrating during those peak io moments. For the time being, a message "migration_threshold <#sectors>" can be used to set the maximum number of sectors being migrated, -the default being 204800 sectors (or 100MB). +the default being 204800 sectors (100MB). Updating on-disk metadata ------------------------- -- cgit From 9b28a1102efc75d81298198166ead87d643a29ce Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:39 -0500 Subject: dm thin: fix documentation relative to low water mark threshold Fixes: 1. The use of "exceeds" when the opposite of exceeds, falls below, was meant. 2. Properly speaking, a table can not exceed a threshold. It emphasizes the important point, which is that it is the userspace daemon's responsibility to check for low free space when a device is resumed, since it won't get a special event indicating low free space in that situation. Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/thin-provisioning.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.txt index 1699a55b7b70..ef639960b272 100644 --- a/Documentation/device-mapper/thin-provisioning.txt +++ b/Documentation/device-mapper/thin-provisioning.txt @@ -112,9 +112,11 @@ $low_water_mark is expressed in blocks of size $data_block_size. If free space on the data device drops below this level then a dm event will be triggered which a userspace daemon should catch allowing it to extend the pool device. Only one such event will be sent. -Resuming a device with a new table itself triggers an event so the -userspace daemon can use this to detect a situation where a new table -already exceeds the threshold. + +No special event is triggered if a just resumed device's free space is below +the low water mark. However, resuming a device always triggers an +event; a userspace daemon should verify that free space exceeds the low +water mark when handling this event. A low water mark for the metadata device is maintained in the kernel and will trigger a dm event if free space on the metadata device drops below -- cgit From 2bc8a61c696e41eef27ab7ff3bcfe75d2daf573a Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:43 -0500 Subject: dm thin: document representation of when there is none Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/thin-provisioning.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.txt index ef639960b272..3852dade03e4 100644 --- a/Documentation/device-mapper/thin-provisioning.txt +++ b/Documentation/device-mapper/thin-provisioning.txt @@ -396,3 +396,6 @@ ii) Status If the pool has encountered device errors and failed, the status will just contain the string 'Fail'. The userspace recovery tools should then be used. + + In the case where is 0, there is no highest + mapped sector and the value of is unspecified. -- cgit From cc3ff0af19499f0aaa587f42d3091b4dff49208f Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:44 -0500 Subject: dm thin: fixes in thin-provisioning.txt Make the format string for thinpool status more correct. Swap the order of two items to correspond with reality. Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/thin-provisioning.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.txt index 3852dade03e4..fb10d187090e 100644 --- a/Documentation/device-mapper/thin-provisioning.txt +++ b/Documentation/device-mapper/thin-provisioning.txt @@ -276,7 +276,7 @@ ii) Status / / - [no_]discard_passdown ro|rw + ro|rw|out_of_data_space [no_]discard_passdown transaction id: A 64-bit number used by userspace to help synchronise with metadata -- cgit From 7efd5fed6fd713e206ace4b71116d0a5d719fb0a Mon Sep 17 00:00:00 2001 From: mulhern Date: Mon, 27 Nov 2017 10:02:45 -0500 Subject: dm thin: extend thinpool status format string with omitted fields Signed-off-by: mulhern Signed-off-by: Mike Snitzer --- Documentation/device-mapper/thin-provisioning.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/thin-provisioning.txt b/Documentation/device-mapper/thin-provisioning.txt index fb10d187090e..4bcd4b7f79f9 100644 --- a/Documentation/device-mapper/thin-provisioning.txt +++ b/Documentation/device-mapper/thin-provisioning.txt @@ -276,7 +276,8 @@ ii) Status / / - ro|rw|out_of_data_space [no_]discard_passdown + ro|rw|out_of_data_space [no_]discard_passdown [error|queue]_if_no_space + needs_check|- transaction id: A 64-bit number used by userspace to help synchronise with metadata -- cgit From 423860a65ae54fa1fbd3abb224bdc62124dcdb90 Mon Sep 17 00:00:00 2001 From: Matthew Wilcox Date: Tue, 16 Jan 2018 19:40:55 -0800 Subject: Documentation: Fix misconversion of #if At some stage of the conversion pipeline, something thought that the DocBook entity # should be rendered as NUM instead of #. Signed-off-by: Matthew Wilcox Signed-off-by: Jonathan Corbet --- Documentation/kernel-hacking/hacking.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst index 5192d7f78eca..9999c8468293 100644 --- a/Documentation/kernel-hacking/hacking.rst +++ b/Documentation/kernel-hacking/hacking.rst @@ -690,8 +690,8 @@ not provide the necessary runtime environment and the include files are not tested for it. It is still possible, but not recommended. If you really want to do this, forget about exceptions at least. -NUMif ------ +#if +--- It is generally considered cleaner to use macros in header files (or at the top of .c files) to abstract away functions rather than using \`#if' -- cgit From 5d87a33782d36c5f2192c93612262deaaa57ad50 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Thu, 11 Jan 2018 22:28:37 +0900 Subject: linux-next: DOC: HWPOISON: Fix path to debugfs in hwpoison.txt This patch fixes an incorrect path for debugfs in hwpoison.txt Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/vm/hwpoison.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/vm/hwpoison.txt b/Documentation/vm/hwpoison.txt index 6ae89a9edf2a..e912d7eee769 100644 --- a/Documentation/vm/hwpoison.txt +++ b/Documentation/vm/hwpoison.txt @@ -104,7 +104,7 @@ madvise(MADV_HWPOISON, ....) hwpoison-inject module through debugfs -/sys/debug/hwpoison/ +/sys/kernel/debug/hwpoison/ corrupt-pfn -- cgit From ae17a87dd7c79fa742ef5dcf06d1095eec4e1925 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Thu, 11 Jan 2018 20:00:28 +0900 Subject: linux-next: docs-rst: Fix typos in kfigure.py This patch fixes some spelling typos found in kfigure.py Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kfigure.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py index cef4ad19624c..b97228d2cc0e 100644 --- a/Documentation/sphinx/kfigure.py +++ b/Documentation/sphinx/kfigure.py @@ -81,7 +81,7 @@ __version__ = '1.0.0' # ------------- def which(cmd): - """Searches the ``cmd`` in the ``PATH`` enviroment. + """Searches the ``cmd`` in the ``PATH`` environment. This *which* searches the PATH for executable ``cmd`` . First match is returned, if nothing is found, ``None` is returned. @@ -419,7 +419,7 @@ def visit_kernel_render(self, node): tmp_ext = RENDER_MARKUP_EXT.get(srclang, None) if tmp_ext is None: - app.warn('kernel-render: "%s" unknow / include raw.' % (srclang)) + app.warn('kernel-render: "%s" unknown / include raw.' % (srclang)) return if not dot_cmd and tmp_ext == '.dot': @@ -482,7 +482,7 @@ class KernelRender(Figure): srclang = self.arguments[0].strip() if srclang not in RENDER_MARKUP_EXT.keys(): return [self.state_machine.reporter.warning( - 'Unknow source language "%s", use one of: %s.' % ( + 'Unknown source language "%s", use one of: %s.' % ( srclang, ",".join(RENDER_MARKUP_EXT.keys())), line=self.lineno)] -- cgit From 50bd870a9e5cca9fcf5fb4c130c373643d7d9906 Mon Sep 17 00:00:00 2001 From: Yossef Efraim Date: Sun, 14 Jan 2018 11:39:10 +0200 Subject: xfrm: Add ESN support for IPSec HW offload This patch adds ESN support to IPsec device offload. Adding new xfrm device operation to synchronize device ESN. Signed-off-by: Yossef Efraim Signed-off-by: Shannon Nelson Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_device.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation') diff --git a/Documentation/networking/xfrm_device.txt b/Documentation/networking/xfrm_device.txt index 2d9d588cd34b..50c34ca65efe 100644 --- a/Documentation/networking/xfrm_device.txt +++ b/Documentation/networking/xfrm_device.txt @@ -41,6 +41,7 @@ struct xfrmdev_ops { void (*xdo_dev_state_free) (struct xfrm_state *x); bool (*xdo_dev_offload_ok) (struct sk_buff *skb, struct xfrm_state *x); + void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); }; The NIC driver offering ipsec offload will need to implement these @@ -117,6 +118,8 @@ the stack in xfrm_input(). hand the packet to napi_gro_receive() as usual +In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn(). +Driver will check packet seq number and update HW ESN state machine if needed. When the SA is removed by the user, the driver's xdo_dev_state_delete() is asked to disable the offload. Later, xdo_dev_state_free() is called -- cgit From adbf02998b2e21e3f055f72fe2daa86260f03637 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Thu, 18 Jan 2018 10:43:43 +0100 Subject: gpio: Documentation update Update a slew of documentation files with the latest changes in the API/ABI. Again stress that sysfs is deprecated. Add all new flags and clean up and move some text. Signed-off-by: Linus Walleij --- Documentation/gpio/board.txt | 14 ++++-- Documentation/gpio/consumer.txt | 105 ++++++++++++++++++++++++---------------- Documentation/gpio/driver.txt | 4 ++ Documentation/gpio/sysfs.txt | 11 +++++ 4 files changed, 88 insertions(+), 46 deletions(-) (limited to 'Documentation') diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index a0f61898d493..b1d106167baa 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -2,6 +2,7 @@ GPIO Mappings ============= This document explains how GPIOs can be assigned to given devices and functions. + Note that it only applies to the new descriptor-based interface. For a description of the deprecated integer-based GPIO interface please refer to gpio-legacy.txt (actually, there is no real mapping possible with the old @@ -49,7 +50,7 @@ This property will make GPIOs 15, 16 and 17 available to the driver under the power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); -The led GPIOs will be active-high, while the power GPIO will be active-low (i.e. +The led GPIOs will be active high, while the power GPIO will be active low (i.e. gpiod_is_active_low(power) will be true). The second parameter of the gpiod_get() functions, the con_id string, has to be @@ -122,9 +123,14 @@ where can be NULL, in which case it will match any function. - idx is the index of the GPIO within the function. - flags is defined to specify the following properties: - * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low - * GPIOF_OPEN_DRAIN - GPIO pin is open drain type. - * GPIOF_OPEN_SOURCE - GPIO pin is open source type. + * GPIO_ACTIVE_HIGH - GPIO line is active high + * GPIO_ACTIVE_LOW - GPIO line is active low + * GPIO_OPEN_DRAIN - GPIO line ise set up as open drain + * GPIO_OPEN_SOURCE - GPIO line is set up as open source + * GPIO_PERSISTENT - GPIO line is persistent during + suspend/resume and maintains its value + * GPIO_TRANSITORY - GPIO line is transitory and may loose its + electrical state during suspend/resume In the future, these flags might be extended to support more properties. diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 7aac33081510..d53e5b5cfc9c 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -66,6 +66,15 @@ for the GPIO. Values can be: * GPIOD_IN to initialize the GPIO as input. * GPIOD_OUT_LOW to initialize the GPIO as output with a value of 0. * GPIOD_OUT_HIGH to initialize the GPIO as output with a value of 1. +* GPIOD_OUT_LOW_OPEN_DRAIN same as GPIOD_OUT_LOW but also enforce the line + to be electrically used with open drain. +* GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_HIGH but also enforce the line + to be electrically used with open drain. + +The two last flags are used for use cases where open drain is mandatory, such +as I2C: if the line is not already configured as open drain in the mappings +(see board.txt), then open drain will be enforced anyway and a warning will be +printed that the board configuration needs to be updated to match the use case. Both functions return either a valid GPIO descriptor, or an error code checkable with IS_ERR() (they will never return a NULL pointer). -ENOENT will be returned @@ -240,59 +249,71 @@ that can't be accessed from hardIRQ handlers, these calls act the same as the spinlock-safe calls. -Active-low State and Raw GPIO Values ------------------------------------- -Device drivers like to manage the logical state of a GPIO, i.e. the value their -device will actually receive, no matter what lies between it and the GPIO line. -In some cases, it might make sense to control the actual GPIO line value. The -following set of calls ignore the active-low property of a GPIO and work on the -raw line value: - - int gpiod_get_raw_value(const struct gpio_desc *desc) - void gpiod_set_raw_value(struct gpio_desc *desc, int value) - int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) - void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) - int gpiod_direction_output_raw(struct gpio_desc *desc, int value) - -The active-low state of a GPIO can also be queried using the following call: - - int gpiod_is_active_low(const struct gpio_desc *desc) - -Note that these functions should only be used with great moderation ; a driver -should not have to care about the physical line level. - - -The active-low property ------------------------ - -As a driver should not have to care about the physical line level, all of the +The active low and open drain semantics +--------------------------------------- +As a consumer should not have to care about the physical line level, all of the gpiod_set_value_xxx() or gpiod_set_array_value_xxx() functions operate with -the *logical* value. With this they take the active-low property into account. -This means that they check whether the GPIO is configured to be active-low, +the *logical* value. With this they take the active low property into account. +This means that they check whether the GPIO is configured to be active low, and if so, they manipulate the passed value before the physical line level is driven. +The same is applicable for open drain or open source output lines: those do not +actively drive their output high (open drain) or low (open source), they just +switch their output to a high impedance value. The consumer should not need to +care. (For details read about open drain in driver.txt.) + With this, all the gpiod_set_(array)_value_xxx() functions interpret the -parameter "value" as "active" ("1") or "inactive" ("0"). The physical line +parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line level will be driven accordingly. -As an example, if the active-low property for a dedicated GPIO is set, and the -gpiod_set_(array)_value_xxx() passes "active" ("1"), the physical line level +As an example, if the active low property for a dedicated GPIO is set, and the +gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level will be driven low. To summarize: -Function (example) active-low property physical line -gpiod_set_raw_value(desc, 0); don't care low -gpiod_set_raw_value(desc, 1); don't care high -gpiod_set_value(desc, 0); default (active-high) low -gpiod_set_value(desc, 1); default (active-high) high -gpiod_set_value(desc, 0); active-low high -gpiod_set_value(desc, 1); active-low low - -Please note again that the set_raw/get_raw functions should be avoided as much -as possible, especially by drivers which should not care about the actual -physical line level and worry about the logical value instead. +Function (example) line property physical line +gpiod_set_raw_value(desc, 0); don't care low +gpiod_set_raw_value(desc, 1); don't care high +gpiod_set_value(desc, 0); default (active high) low +gpiod_set_value(desc, 1); default (active high) high +gpiod_set_value(desc, 0); active low high +gpiod_set_value(desc, 1); active low low +gpiod_set_value(desc, 0); default (active high) low +gpiod_set_value(desc, 1); default (active high) high +gpiod_set_value(desc, 0); open drain low +gpiod_set_value(desc, 1); open drain high impedance +gpiod_set_value(desc, 0); open source high impedance +gpiod_set_value(desc, 1); open source high + +It is possible to override these semantics using the *set_raw/'get_raw functions +but it should be avoided as much as possible, especially by system-agnostic drivers +which should not need to care about the actual physical line level and worry about +the logical value instead. + + +Accessing raw GPIO values +------------------------- +Consumers exist that need to manage the logical state of a GPIO line, i.e. the value +their device will actually receive, no matter what lies between it and the GPIO +line. + +The following set of calls ignore the active-low or open drain property of a GPIO and +work on the raw line value: + + int gpiod_get_raw_value(const struct gpio_desc *desc) + void gpiod_set_raw_value(struct gpio_desc *desc, int value) + int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc) + void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value) + int gpiod_direction_output_raw(struct gpio_desc *desc, int value) + +The active low state of a GPIO can also be queried using the following call: + + int gpiod_is_active_low(const struct gpio_desc *desc) + +Note that these functions should only be used with great moderation; a driver +should not have to care about the physical line level or open drain semantics. Access multiple GPIOs with a single function call diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index d8de1c7de85a..3392a0fd4c23 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -88,6 +88,10 @@ ending up in the pin control back-end "behind" the GPIO controller, usually closer to the actual pins. This way the pin controller can manage the below listed GPIO configurations. +If a pin controller back-end is used, the GPIO controller or hardware +description needs to provide "GPIO ranges" mapping the GPIO line offsets to pin +numbers on the pin controller so they can properly cross-reference each other. + GPIOs with debounce support --------------------------- diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt index aeab01aa4d00..6cdeab8650cd 100644 --- a/Documentation/gpio/sysfs.txt +++ b/Documentation/gpio/sysfs.txt @@ -1,6 +1,17 @@ GPIO Sysfs Interface for Userspace ================================== +THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO +Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS +ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL +NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. + +Refer to the examples in tools/gpio/* for an introduction to the new +character device ABI. Also see the userspace header in +include/uapi/linux/gpio.h + +The deprecated sysfs ABI +------------------------ Platforms which use the "gpiolib" implementors framework may choose to configure a sysfs user interface to GPIOs. This is different from the debugfs interface, since it provides control over GPIO direction and -- cgit From dec8cd4d9b9fa7dc0b7f253ebb31f2c3ef4213ac Mon Sep 17 00:00:00 2001 From: Paul Cercueil Date: Tue, 16 Jan 2018 16:48:03 +0100 Subject: devicetree/bindings: Add GCW vendor prefix Game Consoles Worldwide, mostly known under the acronym GCW, is the creator of the GCW Zero open-source video game system. Signed-off-by: Paul Cercueil Acked-by: Rob Herring Cc: Ralf Baechle Cc: Maarten ter Huurne Cc: linux-mips@linux-mips.org Patchwork: https://patchwork.linux-mips.org/patch/18489/ Signed-off-by: James Hogan --- Documentation/devicetree/bindings/vendor-prefixes.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 0994bdd82cd3..f40f4da39937 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -123,6 +123,7 @@ focaltech FocalTech Systems Co.,Ltd friendlyarm Guangzhou FriendlyARM Computer Tech Co., Ltd fsl Freescale Semiconductor fujitsu Fujitsu Ltd. +gcw Game Consoles Worldwide ge General Electric Company geekbuying GeekBuying gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. -- cgit From a3f061bc26e07fecc4e3c2ed12d5d6947d996036 Mon Sep 17 00:00:00 2001 From: Jean-François Têtu Date: Thu, 18 Jan 2018 15:58:18 -0800 Subject: Input: fix small typos in force feedback documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix small typos in the Instructions and Uploading sections. Fix a typo in the start/stop effect example usage code. Signed-off-by: Jean-François Têtu Signed-off-by: Dmitry Torokhov --- Documentation/input/ff.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst index 26d461998e08..0c02e87ee86d 100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@ -31,7 +31,7 @@ To enable force feedback, you have to: Before you start, let me WARN you that some devices shake violently during the initialisation phase. This happens for example with my "AVB Top Shot Pegasus". -To stop this annoying behaviour, move you joystick to its limits. Anyway, you +To stop this annoying behaviour, move your joystick to its limits. Anyway, you should keep a hand on your device, in order to avoid it to break down if something goes wrong. @@ -121,7 +121,7 @@ uploaded, but not played. The content of effect may be modified. In particular, its field "id" is set to the unique id assigned by the driver. This data is required for performing some operations (removing an effect, controlling the playback). -This if field must be set to -1 by the user in order to tell the driver to +The "id" field must be set to -1 by the user in order to tell the driver to allocate a new effect. Effects are file descriptor specific. @@ -178,7 +178,7 @@ Control of playing is done with write(). Below is an example: stop.code = effect.id; stop.value = 0; - write(fd, (const void*) &play, sizeof(stop)); + write(fd, (const void*) &stop, sizeof(stop)); Setting the gain ---------------- -- cgit From 2046362cf11d3dcb0c6904f7f3209c568d7858b3 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Sun, 21 Jan 2018 16:52:31 +0100 Subject: gpio: Fix a documentation spelling mistake Simple etraneous letter. Reported-by: Alexander Stein Signed-off-by: Linus Walleij --- Documentation/gpio/board.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index b1d106167baa..659bb19f5b3c 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -125,7 +125,7 @@ where - flags is defined to specify the following properties: * GPIO_ACTIVE_HIGH - GPIO line is active high * GPIO_ACTIVE_LOW - GPIO line is active low - * GPIO_OPEN_DRAIN - GPIO line ise set up as open drain + * GPIO_OPEN_DRAIN - GPIO line is set up as open drain * GPIO_OPEN_SOURCE - GPIO line is set up as open source * GPIO_PERSISTENT - GPIO line is persistent during suspend/resume and maintains its value -- cgit From 4be4119d1fbd93c44d5c639735c3124d0526976c Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Fri, 2 Jun 2017 14:38:46 +0200 Subject: dt: booting-without-of: DT fix s/#interrupt-cell/#interrupt-cells/ Signed-off-by: Geert Uytterhoeven Acked-by: Rob Herring Signed-off-by: Michael Ellerman --- Documentation/devicetree/booting-without-of.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 417f91110010..e86bd2f64117 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -1309,7 +1309,7 @@ number and level/sense information. All interrupt children in an OpenPIC interrupt domain use 2 cells per interrupt in their interrupts property. -The PCI bus binding specifies a #interrupt-cell value of 1 to encode +The PCI bus binding specifies a #interrupt-cells value of 1 to encode which interrupt pin (INTA,INTB,INTC,INTD) is used. 2) interrupt-parent property -- cgit From dd0273284c7474100bcd331887443f0e4b1dcce8 Mon Sep 17 00:00:00 2001 From: Rob Gardner Date: Tue, 5 Dec 2017 19:40:43 -0700 Subject: sparc64: Oracle DAX driver DAX is a coprocessor which resides on the SPARC M7 (DAX1) and M8 (DAX2) processor chips, and has direct access to the CPU's L3 caches as well as physical memory. It can perform several operations on data streams with various input and output formats. This driver provides a transport mechanism and has limited knowledge of the various opcodes and data formats. A user space library provides high level services and translates these into low level commands which are then passed into the driver and subsequently the hypervisor and the coprocessor. The library is the recommended way for applications to use the coprocessor, and the driver interface is not intended for general use. Signed-off-by: Rob Gardner Signed-off-by: Jonathan Helman Signed-off-by: Sanath Kumar Signed-off-by: David S. Miller --- Documentation/sparc/oradax/dax-hv-api.txt | 1433 +++++++++++++++++++++++++++++ Documentation/sparc/oradax/oracle-dax.txt | 429 +++++++++ 2 files changed, 1862 insertions(+) create mode 100644 Documentation/sparc/oradax/dax-hv-api.txt create mode 100644 Documentation/sparc/oradax/oracle-dax.txt (limited to 'Documentation') diff --git a/Documentation/sparc/oradax/dax-hv-api.txt b/Documentation/sparc/oradax/dax-hv-api.txt new file mode 100644 index 000000000000..73e8d506cf64 --- /dev/null +++ b/Documentation/sparc/oradax/dax-hv-api.txt @@ -0,0 +1,1433 @@ +Excerpt from UltraSPARC Virtual Machine Specification +Compiled from version 3.0.20+15 +Publication date 2017-09-25 08:21 +Copyright © 2008, 2015 Oracle and/or its affiliates. All rights reserved. +Extracted via "pdftotext -f 547 -l 572 -layout sun4v_20170925.pdf" +Authors: + Charles Kunzman + Sam Glidden + Mark Cianchetti + + +Chapter 36. Coprocessor services + The following APIs provide access via the Hypervisor to hardware assisted data processing functionality. + These APIs may only be provided by certain platforms, and may not be available to all virtual machines + even on supported platforms. Restrictions on the use of these APIs may be imposed in order to support + live-migration and other system management activities. + +36.1. Data Analytics Accelerator + The Data Analytics Accelerator (DAX) functionality is a collection of hardware coprocessors that provide + high speed processoring of database-centric operations. The coprocessors may support one or more of + the following data query operations: search, extraction, compression, decompression, and translation. The + functionality offered may vary by virtual machine implementation. + + The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device + compatibilty property. Functionality is accessed through the submission of Command Control Blocks + (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status + of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a + separate Completion Area and, unless execution order is specifically restricted through the use of serial- + conditional flags, the execution order of submitted CCBs is arbitrary. Likewise, the time to completion + for a given CCB is never guaranteed. + + Guest software may implement a software timeout on CCB operations, and if the timeout is exceeded, the + operation may be cancelled or killed via the ccb_kill API function. It is recommended for guest software + to implement a software timeout to account for certain RAS errors which may result in lost CCBs. It is + recommended such implementation use the ccb_info API function to check the status of a CCB prior to + killing it in order to determine if the CCB is still in queue, or may have been lost due to a RAS error. + + There is no fixed limit on the number of outstanding CCBs guest software may have queued in the virtual + machine, however, internal resource limitations within the virtual machine can cause CCB submissions + to be temporarily rejected with EWOULDBLOCK. In such cases, guests should continue to attempt + submissions until they succeed; waiting for an outstanding CCB to complete is not necessary, and would + not be a guarantee that a future submission would succeed. + + The availablility of DAX coprocessor command service is indicated by the presence of the DAX virtual + device node in the guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device + node”). + +36.1.1. DAX Compatibility Property + The query functionality may vary based on the compatibility property of the virtual device: + +36.1.1.1. "ORCL,sun4v-dax" Device Compatibility + Available CCB commands: + + • No-op/Sync + + • Extract + + • Scan Value + + • Inverted Scan Value + + • Scan Range + + + 509 + Coprocessor services + + + • Inverted Scan Range + + • Translate + + • Inverted Translate + + • Select + + See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats. + + Only version 0 CCBs are available. + +36.1.1.2. "ORCL,sun4v-dax-fc" Device Compatibility + "ORCL,sun4v-dax-fc" is compatible with the "ORCL,sun4v-dax" interface, and includes additional CCB + bit fields and controls. + +36.1.1.3. "ORCL,sun4v-dax2" Device Compatibility + Available CCB commands: + + • No-op/Sync + + • Extract + + • Scan Value + + • Inverted Scan Value + + • Scan Range + + • Inverted Scan Range + + • Translate + + • Inverted Translate + + • Select + + See Section 36.2.1, “Query CCB Command Formats” for the corresponding CCB input and output formats. + + Version 0 and 1 CCBs are available. Only version 0 CCBs may use Huffman encoded data, whereas only + version 1 CCBs may use OZIP. + +36.1.2. DAX Virtual Device Interrupts + The DAX virtual device has multiple interrupts associated with it which may be used by the guest if + desired. The number of device interrupts available to the guest is indicated in the virtual device node of the + guest MD (Section 8.24.17, “Database Analytics Accelerators (DAX) virtual-device node”). If the device + node indicates N interrupts available, the guest may use any value from 0 to N - 1 (inclusive) in a CCB + interrupt number field. Using values outside this range will result in the CCB being rejected for an invalid + field value. + + The interrupts may be bound and managed using the standard sun4v device interrupts API (Chapter 16, + Device interrupt services). Sysino interrupts are not available for DAX devices. + +36.2. Coprocessor Control Block (CCB) + CCBs are either 64 or 128 bytes long, depending on the operation type. The exact contents of the CCB + are command specific, but all CCBs contain at least one memory buffer address. All memory locations + + + 510 + Coprocessor services + + +referenced by a CCB must be pinned in memory until the CCB either completes execution or is killed +via the ccb_kill API call. Changes in virtual address mappings occurring after CCB submission are not +guaranteed to be visible, and as such all virtual address updates need to be synchronized with CCB +execution. + +All CCBs begin with a common 32-bit header. + +Table 36.1. CCB Header Format +Bits Field Description +[31:28] CCB version. For API version 2.0: set to 1 if CCB uses OZIP encoding; set to 0 if the CCB + uses Huffman encoding; otherwise either 0 or 1. For API version 1.0: always set to 0. +[27] When API version 2.0 is negotiated, this is the Pipeline Flag [512]. It is reserved in + API version 1.0 +[26] Long CCB flag [512] +[25] Conditional synchronization flag [512] +[24] Serial synchronization flag +[23:16] CCB operation code: + 0x00 No Operation (No-op) or Sync + 0x01 Extract + 0x02 Scan Value + 0x12 Inverted Scan Value + 0x03 Scan Range + 0x13 Inverted Scan Range + 0x04 Translate + 0x14 Inverted Translate + 0x05 Select +[15:13] Reserved +[12:11] Table address type + 0b'00 No address + 0b'01 Alternate context virtual address + 0b'10 Real address + 0b'11 Primary context virtual address +[10:8] Output/Destination address type + 0b'000 No address + 0b'001 Alternate context virtual address + 0b'010 Real address + 0b'011 Primary context virtual address + 0b'100 Reserved + 0b'101 Reserved + 0b'110 Reserved + 0b'111 Reserved +[7:5] Secondary source address type + + + 511 + Coprocessor services + + +Bits Field Description + 0b'000 No address + 0b'001 Alternate context virtual address + 0b'010 Real address + 0b'011 Primary context virtual address + 0b'100 Reserved + 0b'101 Reserved + 0b'110 Reserved + 0b'111 Reserved +[4:2] Primary source address type + 0b'000 No address + 0b'001 Alternate context virtual address + 0b'010 Real address + 0b'011 Primary context virtual address + 0b'100 Reserved + 0b'101 Reserved + 0b'110 Reserved + 0b'111 Reserved +[1:0] Completion area address type + 0b'00 No address + 0b'01 Alternate context virtual address + 0b'10 Real address + 0b'11 Primary context virtual address + +The Long CCB flag indicates whether the submitted CCB is 64 or 128 bytes long; value is 0 for 64 bytes +and 1 for 128 bytes. + +The Serial and Conditional flags allow simple relative ordering between CCBs. Any CCB with the Serial +flag set will execute sequentially relative to any previous CCB that is also marked as Serial in the same +CCB submission. CCBs without the Serial flag set execute independently, even if they are between CCBs +with the Serial flag set. CCBs marked solely with the Serial flag will execute upon the completion of the +previous Serial CCB, regardless of the completion status of that CCB. The Conditional flag allows CCBs +to conditionally execute based on the successful execution of the closest CCB marked with the Serial flag. +A CCB may only be conditional on exactly one CCB, however, a CCB may be marked both Conditional +and Serial to allow execution chaining. The flags do NOT allow fan-out chaining, where multiple CCBs +execute in parallel based on the completion of another CCB. + +The Pipeline flag is an optimization that directs the output of one CCB (the "source" CCB) directly to +the input of the next CCB (the "target" CCB). The target CCB thus does not need to read the input from +memory. The Pipeline flag is advisory and may be dropped. + +Both the Pipeline and Serial bits must be set in the source CCB. The Conditional bit must be set in the +target CCB. Exactly one CCB must be made conditional on the source CCB; either 0 or 2 target CCBs +is invalid. However, Pipelines can be extended beyond two CCBs: the sequence would start with a CCB +with both the Pipeline and Serial bits set, proceed through CCBs with the Pipeline, Serial, and Conditional +bits set, and terminate at a CCB that has the Conditional bit set, but not the Pipeline bit. + + + 512 + Coprocessor services + + + The input of the target CCB must start within 64 bytes of the output of the source CCB or the pipeline flag + will be ignored. All CCBs in a pipeline must be submitted in the same call to ccb_submit. + + The various address type fields indicate how the various address values used in the CCB should be + interpreted by the virtual machine. Not all of the types specified are used by every CCB format. Types + which are not applicable to the given CCB command should be indicated as type 0 (No address). Virtual + addresses used in the CCB must have translation entries present in either the TLB or a configured TSB + for the submitting virtual processor. Virtual addresses which cannot be translated by the virtual machine + will result in the CCB submission being rejected, with the causal virtual address indicated. The CCB + may be resubmitted after inserting the translation, or the address may be translated by guest software and + resubmitted using the real address translation. + +36.2.1. Query CCB Command Formats +36.2.1.1. Supported Data Formats, Elements Sizes and Offsets + Data for query commands may be encoded in multiple possible formats. The data query commands use a + common set of values to indicate the encoding formats of the data being processed. Some encoding formats + require multiple data streams for processing, requiring the specification of both primary data formats (the + encoded data) and secondary data streams (meta-data for the encoded data). + +36.2.1.1.1. Primary Input Format + + The primary input format code is a 4-bit field when it is used. There are 10 primary input formats available. + The packed formats are not endian neutral. Code values not listed below are reserved. + + Code Format Description + 0x0 Fixed width byte packed Up to 16 bytes + 0x1 Fixed width bit packed Up to 15 bits (CCB version 0) or 23 bits (CCB version + 1); bits are read most significant bit to least significant bit + within a byte + 0x2 Variable width byte packed Data stream of lengths must be provided as a secondary + input + 0x4 Fixed width byte packed with run Up to 16 bytes; data stream of run lengths must be + length encoding provided as a secondary input + 0x5 Fixed width bit packed with run Up to 15 bits (CCB version 0) or 23 bits (CCB version + length encoding 1); bits are read most significant bit to least significant bit + within a byte; data stream of run lengths must be provided + as a secondary input + 0x8 Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream + Huffman (CCB version 0) or bits are read most significant bit to least significant bit + OZIP (CCB version 1) encoding within a byte; pointer to the encoding table must be + provided + 0x9 Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits (CCB version + Huffman (CCB version 0) or 1); compressed stream bits are read most significant bit to + OZIP (CCB version 1) encoding least significant bit within a byte; pointer to the encoding + table must be provided + 0xA Variable width byte packed with Up to 16 bytes before the encoding; compressed stream + Huffman (CCB version 0) or bits are read most significant bit to least significant bit + OZIP (CCB version 1) encoding within a byte; data stream of lengths must be provided as + a secondary input; pointer to the encoding table must be + provided + + + 513 + Coprocessor services + + + Code Format Description + 0xC Fixed width byte packed with Up to 16 bytes before the encoding; compressed stream + run length encoding, followed by bits are read most significant bit to least significant bit + Huffman (CCB version 0) or within a byte; data stream of run lengths must be provided + OZIP (CCB version 1) encoding as a secondary input; pointer to the encoding table must + be provided + 0xD Fixed width bit packed with Up to 15 bits (CCB version 0) or 23 bits(CCB version 1) + run length encoding, followed by before the encoding; compressed stream bits are read most + Huffman (CCB version 0) or significant bit to least significant bit within a byte; data + OZIP (CCB version 1) encoding stream of run lengths must be provided as a secondary + input; pointer to the encoding table must be provided + + If OZIP encoding is used, there must be no reserved bytes in the table. + +36.2.1.1.2. Primary Input Element Size + + For primary input data streams with fixed size elements, the element size must be indicated in the CCB + command. The size is encoded as the number of bits or bytes, minus one. The valid value range for this + field depends on the input format selected, as listed in the table above. + +36.2.1.1.3. Secondary Input Format + + For primary input data streams which require a secondary input stream, the secondary input stream is + always encoded in a fixed width, bit-packed format. The bits are read from most significant bit to least + significant bit within a byte. There are two encoding options for the secondary input stream data elements, + depending on whether the value of 0 is needed: + + Secondary Input Description + Format Code + 0 Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes + to 2, etc) + 1 Element is stored as value + +36.2.1.1.4. Secondary Input Element Size + + Secondary input element size is encoded as a two bit field: + + Secondary Input Size Description + Code + 0x0 1 bit + 0x1 2 bits + 0x2 4 bits + 0x3 8 bits + +36.2.1.1.5. Input Element Offsets + + Bit-wise input data streams may have any alignment within the base addressed byte. The offset, specified + from most significant bit to least significant bit, is provided as a fixed 3 bit field for each input type. A + value of 0 indicates that the first input element begins at the most significant bit in the first byte, and a + value of 7 indicates it begins with the least significant bit. + + This field should be zero for any byte-wise primary input data streams. + + + 514 + Coprocessor services + + +36.2.1.1.6. Output Format + + Query commands support multiple sizes and encodings for output data streams. There are four possible + output encodings, and up to four supported element sizes per encoding. Not all output encodings are + supported for every command. The format is indicated by a 4-bit field in the CCB: + + Output Format Code Description + 0x0 Byte aligned, 1 byte elements + 0x1 Byte aligned, 2 byte elements + 0x2 Byte aligned, 4 byte elements + 0x3 Byte aligned, 8 byte elements + 0x4 16 byte aligned, 16 byte elements + 0x5 Reserved + 0x6 Reserved + 0x7 Reserved + 0x8 Packed vector of single bit elements + 0x9 Reserved + 0xA Reserved + 0xB Reserved + 0xC Reserved + 0xD 2 byte elements where each element is the index value of a bit, + from an bit vector, which was 1. + 0xE 4 byte elements where each element is the index value of a bit, + from an bit vector, which was 1. + 0xF Reserved + +36.2.1.1.7. Application Data Integrity (ADI) + + On platforms which support ADI, the ADI version number may be specified for each separate memory + access type used in the CCB command. ADI checking only occurs when reading data. When writing data, + the specified ADI version number overwrites any existing ADI value in memory. + + An ADI version value of 0 or 0xF indicates the ADI checking is disabled for that data access, even if it is + enabled in memory. By setting the appropriate flag in CCB_SUBMIT (Section 36.3.1, “ccb_submit”) it is + also an option to disable ADI checking for all inputs accessed via virtual address for all CCBs submitted + during that hypercall invocation. + + The ADI value is only guaranteed to be checked on the first 64 bytes of each data access. Mismatches on + subsequent data chunks may not be detected, so guest software should be careful to use page size checking + to protect against buffer overruns. + +36.2.1.1.8. Page size checking + + All data accesses used in CCB commands must be bounded within a single memory page. When addresses + are provided using a virtual address, the page size for checking is extracted from the TTE for that virtual + address. When using real addresses, the guest must supply the page size in the same field as the address + value. The page size must be one of the sizes supported by the underlying virtual machine. Using a value + that is not supported may result in the CCB submission being rejected or the generation of a CCB parsing + error in the completion area. + + + 515 + Coprocessor services + + +36.2.1.2. Extract command + + Converts an input vector in one format to an output vector in another format. All input format types are + supported. + + The only supported output format is a padded, byte-aligned output stream, using output codes 0x0 - 0x4. + When the specified output element size is larger than the extracted input element size, zeros are padded to + the extracted input element. First, if the decompressed input size is not a whole number of bytes, 0 bits are + padded to the most significant bit side till the next byte boundary. Next, if the output element size is larger + than the byte padded input element, bytes of value 0 are added based on the Padding Direction bit in the + CCB. If the output element size is smaller than the byte-padded input element size, the input element is + truncated by dropped from the least significant byte side until the selected output size is reached. + + The return value of the CCB completion area is invalid. The “number of elements processed” field in the + CCB completion area will be valid. + + The extract CCB is a 64-byte “short format” CCB. + + The extract CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct extract_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t reserved; + uint64_t output; + uint64_t table; + }; + + + The exact field offsets, sizes, and composition are as follows: + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + 4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + + + 516 + Coprocessor services + + +Offset Size Field Description + Bits Field Description + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9] Padding Direction selector: A value of 1 causes padding bytes + to be added to the left side of output elements. A value of 0 + causes padding bytes to be added to the right side of output + elements. + [8:0] Reserved +8 8 Completion + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59] If set to 1, a virtual device interrupt will be generated using + the device interrupt number specified in the lower bits of this + completion word. If 0, the lower bits of this completion word + are ignored. + [58:6] Completion area address bits [58:6]. Address type is + determined by CCB header. + [5:0] Virtual device interrupt number for completion interrupt, if + enabled. +16 8 Primary Input + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59:56] If using real address, these bits should be filled in with the + page size code for the page boundary checking the guest wants + the virtual machine to use when accessing this data stream + (checking is only guaranteed to be performed when using API + version 1.1 and later). If using a virtual address, this field will + be used as as primary input address bits [59:56]. + [55:0] Primary input address bits [55:0]. Address type is determined + by CCB header. +24 8 Data Access Control + Bits Field Description + [63:62] Flow Control + Value Description + 0b'00 Disable flow control + 0b'01 Enable flow control (only valid with "ORCL,sun4v- + dax-fc" compatible virtual device variants) + 0b'10 Reserved + 0b'11 Reserved + [61:60] Reserved (API 1.0) + + + 517 + Coprocessor services + + +Offset Size Field Description + Bits Field Description + Pipeline target (API 2.0) + Value Description + 0b'00 Connect to primary input + 0b'01 Connect to secondary input + 0b'10 Reserved + 0b'11 Reserved + [59:40] Output buffer size given in units of 64 bytes, minus 1. Value of + 0 means 64 bytes, value of 1 means 128 bytes, etc. Buffer size is + only enforced if flow control is enabled in Flow Control field. + [39:32] Reserved + [31:30] Output Data Cache Allocation + Value Description + 0b'00 Do not allocate cache lines for output data stream. + 0b'01 Force cache lines for output data stream to be + allocated in the cache that is local to the submitting + virtual cpu. + 0b'10 Allocate cache lines for output data stream, but allow + existing cache lines associated with the data to remain + in their current cache instance. Any memory not + already in cache will be allocated in the cache local + to the submitting virtual cpu. + 0b'11 Reserved + [29:26] Reserved + [25:24] Primary Input Length Format + Value Description + 0b'00 Number of primary symbols + 0b'01 Number of primary bytes + 0b'10 Number of primary bits + 0b'11 Reserved + [23:0] Primary Input Length + Format Field Value + # of primary symbols Number of input elements to process, + minus 1. Command execution stops + once count is reached. + # of primary bytes Number of input bytes to process, + minus 1. Command execution stops + once count is reached. The count is + done before any decompression or + decoding. + # of primary bits Number of input bits to process, + minus 1. Command execution stops + + + + 518 + Coprocessor services + + + Offset Size Field Description + Bits Field Description + Format Field Value + once count is reached. The count is + done before any decompression or + decoding, and does not include any + bits skipped by the Primary Input + Offset field value of the command + control word. + 32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary + Input. + 40 8 Reserved + 48 8 Output (same fields as Primary Input) + 56 8 Symbol Table (if used by Primary Input) + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59:56] If using real address, these bits should be filled in with the + page size code for the page boundary checking the guest wants + the virtual machine to use when accessing this data stream + (checking is only guaranteed to be performed when using API + version 1.1 and later). If using a virtual address, this field will + be used as as symbol table address bits [59:56]. + [55:4] Symbol table address bits [55:4]. Address type is determined + by CCB header. + [3:0] Symbol table version + Value Description + 0 Huffman encoding. Must use 64 byte aligned table + address. (Only available when using version 0 CCBs) + 1 OZIP encoding. Must use 16 byte aligned table + address. (Only available when using version 1 CCBs) + + +36.2.1.3. Scan commands + + The scan commands search a stream of input data elements for values which match the selection criteria. + All the input format types are supported. There are multiple formats for the scan commands, allowing the + scan to search for exact matches to one value, exact matches to either of two values, or any value within + a specified range. The specific type of scan is indicated by the command code in the CCB header. For the + scan range commands, the boundary conditions can be specified as greater-than-or-equal-to a value, less- + than-or-equal-to a value, or both by using two boundary values. + + There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8, + 0xD, and 0xE). For the standard scan command using the bit vector output, for each input element there + exists one bit in the vector that is set if the input element matched the scan criteria, or clear if not. The + inverted scan command inverts the polarity of the bits in the output. The most significant bit of the first + byte of the output stream corresponds to the first element in the input stream. The standard index array + output format contains one array entry for each input element that matched the scan criteria. Each array + + + + 519 + Coprocessor services + + +entry is the index of an input element that matched the scan criteria. An inverted scan command produces +a similar array, but of all the input elements which did NOT match the scan criteria. + +The return value of the CCB completion area contains the number of input elements found which match +the scan criteria (or number that did not match for the inverted scans). The “number of elements processed” +field in the CCB completion area will be valid, indicating the number of input elements processed. + +These commands are 128-byte “long format” CCBs. + +The scan CCB command format can be specified by the following packed C structure for a big-endian +machine: + + + struct scan_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t match_criteria0; + uint64_t output; + uint64_t table; + uint64_t match_criteria1; + uint64_t match_criteria2; + uint64_t match_criteria3; + uint64_t reserved[5]; + }; + + +The exact field offsets, sizes, and composition are as follows: + +Offset Size Field Description +0 4 CCB header (Table 36.1, “CCB Header Format”) +4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9:5] Operand size for first scan criteria value. In a scan value + operation, this is one of two potential extact match values. + In a scan range operation, this is the size of the upper range + + + 520 + Coprocessor services + + +Offset Size Field Description + Bits Field Description + boundary. The value of this field is the number of bytes in the + operand, minus 1. Values 0xF-0x1E are reserved. A value of + 0x1F indicates this operand is not in use for this scan operation. + [4:0] Operand size for second scan criteria value. In a scan value + operation, this is one of two potential extact match values. + In a scan range operation, this is the size of the lower range + boundary. The value of this field is the number of bytes in the + operand, minus 1. Values 0xF-0x1E are reserved. A value of + 0x1F indicates this operand is not in use for this scan operation. +8 8 Completion (same fields as Section 36.2.1.2, “Extract command”) +16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”) +24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”) +32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary + Input. +40 4 Most significant 4 bytes of first scan criteria operand. If first operand is less + than 4 bytes, the value is left-aligned to the lowest address bytes. +44 4 Most significant 4 bytes of second scan criteria operand. If second operand + is less than 4 bytes, the value is left-aligned to the lowest address bytes. +48 8 Output (same fields as Primary Input) +56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, + “Extract command” +64 4 Next 4 most significant bytes of first scan criteria operand occuring after the + bytes specified at offset 40, if needed by the operand size. If first operand + is less than 8 bytes, the valid bytes are left-aligned to the lowest address. +68 4 Next 4 most significant bytes of second scan criteria operand occuring after + the bytes specified at offset 44, if needed by the operand size. If second + operand is less than 8 bytes, the valid bytes are left-aligned to the lowest + address. +72 4 Next 4 most significant bytes of first scan criteria operand occuring after the + bytes specified at offset 64, if needed by the operand size. If first operand + is less than 12 bytes, the valid bytes are left-aligned to the lowest address. +76 4 Next 4 most significant bytes of second scan criteria operand occuring after + the bytes specified at offset 68, if needed by the operand size. If second + operand is less than 12 bytes, the valid bytes are left-aligned to the lowest + address. +80 4 Next 4 most significant bytes of first scan criteria operand occuring after the + bytes specified at offset 72, if needed by the operand size. If first operand + is less than 16 bytes, the valid bytes are left-aligned to the lowest address. +84 4 Next 4 most significant bytes of second scan criteria operand occuring after + the bytes specified at offset 76, if needed by the operand size. If second + operand is less than 16 bytes, the valid bytes are left-aligned to the lowest + address. + + + + + 521 + Coprocessor services + + +36.2.1.4. Translate commands + + The translate commands takes an input array of indicies, and a table of single bit values indexed by those + indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in + the input array. The output should therefore contain exactly one bit per index in the input data stream, + when outputing as a bit vector. When outputing as an index array, the number of elements depends on the + values read in the bit table, but will always be less than, or equal to, the number of input elements. Only + a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP + encoded input streams are allowed. The primary input data element size must be 3 bytes or less. + + The maximum table index size allowed is 15 bits, however, larger input elements may be used to provide + additional processing of the output values. If 2 or 3 byte values are used, the least significant 15 bits are + used as an index into the bit table. The most significant 9 bits (when using 3-byte input elements) or single + bit (when using 2-byte input elements) are compared against a fixed 9-bit test value provided in the CCB. + If the values match, the value from the bit table is used as the output element value. If the values do not + match, the output data element value is forced to 0. + + In the inverted translate operation, the bit value read from bit table is inverted prior to its use. The additional + additional processing based on any additional non-index bits remains unchanged, and still forces the output + element value to 0 on a mismatch. The specific type of translate command is indicated by the command + code in the CCB header. + + There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8, + 0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the + output format was a bit array. + + The return value of the CCB completion area contains the number of bits set in the output bit vector, + or number of elements in the output index array. The “number of elements processed” field in the CCB + completion area will be valid, indicating the number of input elements processed. + + These commands are 64-byte “short format” CCBs. + + The translate CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct translate_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t reserved; + uint64_t output; + uint64_t table; + }; + + + The exact field offsets, sizes, and composition are as follows: + + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + + + 522 + Coprocessor services + + +Offset Size Field Description +4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9] Reserved + [8:0] Test value used for comparison against the most significant bits + in the input values, when using 2 or 3 byte input elements. +8 8 Completion (same fields as Section 36.2.1.2, “Extract command” +16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command” +24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”, + except Primary Input Length Format may not use the 0x0 value) +32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary + Input. +40 8 Reserved +48 8 Output (same fields as Primary Input) +56 8 Bit Table + Bits Field Description + [63:60] ADI version (see Section 36.2.1.1.7, “Application Data + Integrity (ADI)”) + [59:56] If using real address, these bits should be filled in with the + page size code for the page boundary checking the guest wants + the virtual machine to use when accessing this data stream + (checking is only guaranteed to be performed when using API + version 1.1 and later). If using a virtual address, this field will + be used as as bit table address bits [59:56] + [55:4] Bit table address bits [55:4]. Address type is determined by + CCB header. Address must be 64-byte aligned (CCB version + 0) or 16-byte aligned (CCB version 1). + [3:0] Bit table version + Value Description + 0 4KB table size + 1 8KB table size + + + + 523 + Coprocessor services + + +36.2.1.5. Select command + The select command filters the primary input data stream by using a secondary input bit vector to determine + which input elements to include in the output. For each bit set at a given index N within the bit vector, + the Nth input element is included in the output. If the bit is not set, the element is not included. Only a + restricted subset of the possible input format types are supported. No variable width or run length encoded + input streams are allowed, since the secondary input stream is used for the filtering bit vector. + + The only supported output format is a padded, byte-aligned output stream. The stream follows the same + rules and restrictions as padded output stream described in Section 36.2.1.2, “Extract command”. + + The return value of the CCB completion area contains the number of bits set in the input bit vector. The + "number of elements processed" field in the CCB completion area will be valid, indicating the number + of input elements processed. + + The select CCB is a 64-byte “short format” CCB. + + The select CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct select_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t primary_input; + uint64_t data_access_control; + uint64_t secondary_input; + uint64_t reserved; + uint64_t output; + uint64_t table; + }; + + + The exact field offsets, sizes, and composition are as follows: + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + 4 4 Command control + Bits Field Description + [31:28] Primary Input Format (see Section 36.2.1.1.1, “Primary Input + Format”) + [27:23] Primary Input Element Size (see Section 36.2.1.1.2, “Primary + Input Element Size”) + [22:20] Primary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [19] Secondary Input Format (see Section 36.2.1.1.3, “Secondary + Input Format”) + [18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input + Element Offsets”) + [15:14] Secondary Input Element Size (see Section 36.2.1.1.4, + “Secondary Input Element Size” + + + 524 + Coprocessor services + + + Offset Size Field Description + Bits Field Description + [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) + [9] Padding Direction selector: A value of 1 causes padding bytes + to be added to the left side of output elements. A value of 0 + causes padding bytes to be added to the right side of output + elements. + [8:0] Reserved + 8 8 Completion (same fields as Section 36.2.1.2, “Extract command” + 16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command” + 24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”) + 32 8 Secondary Bit Vector Input. Same fields as Primary Input. + 40 8 Reserved + 48 8 Output (same fields as Primary Input) + 56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, + “Extract command” + +36.2.1.6. No-op and Sync commands + The no-op (no operation) command is a CCB which has no processing effect. The CCB, when processed + by the virtual machine, simply updates the completion area with its execution status. The CCB may have + the serial-conditional flags set in order to restrict when it executes. + + The sync command is a variant of the no-op command which with restricted execution timing. A sync + command CCB will only execute when all previous commands submitted in the same request have + completed. This is stronger than the conditional flag sequencing, which is only dependent on a single + previous serial CCB. While the relative ordering is guaranteed, virtual machine implementations with + shared hardware resources may cause the sync command to wait for longer than the minimum required + time. + + The return value of the CCB completion area is invalid for these CCBs. The “number of elements + processed” field is also invalid for these CCBs. + + These commands are 64-byte “short format” CCBs. + + The no-op CCB command format can be specified by the following packed C structure for a big-endian + machine: + + + struct nop_ccb { + uint32_t header; + uint32_t control; + uint64_t completion; + uint64_t reserved[6]; + }; + + + The exact field offsets, sizes, and composition are as follows: + + Offset Size Field Description + 0 4 CCB header (Table 36.1, “CCB Header Format”) + + + 525 + Coprocessor services + + + Offset Size Field Description + 4 4 Command control + Bits Field Description + [31] If set, this CCB functions as a Sync command. If clear, this + CCB functions as a No-op command. + [30:0] Reserved + 8 8 Completion (same fields as Section 36.2.1.2, “Extract command” + 16 46 Reserved + +36.2.2. CCB Completion Area + All CCB commands use a common 128-byte Completion Area format, which can be specified by the + following packed C structure for a big-endian machine: + + + struct completion_area { + uint8_t status_flag; + uint8_t error_note; + uint8_t rsvd0[2]; + uint32_t error_values; + uint32_t output_size; + uint32_t rsvd1; + uint64_t run_time; + uint64_t run_stats; + uint32_t elements; + uint8_t rsvd2[20]; + uint64_t return_value; + uint64_t extra_return_value[8]; + }; + + + The Completion Area must be a 128-byte aligned memory location. The exact layout can be described + using byte offsets and sizes relative to the memory base: + + Offset Size Field Description + 0 1 CCB execution status + 0x0 Command not yet completed + 0x1 Command ran and succeeded + 0x2 Command ran and failed (partial results may be been + produced) + 0x3 Command ran and was killed (partial execution may + have occurred) + 0x4 Command was not run + 0x5-0xF Reserved + 1 1 Error reason code + 0x0 Reserved + 0x1 Buffer overflow + + + 526 + Coprocessor services + + +Offset Size Field Description + 0x2 CCB decoding error + 0x3 Page overflow + 0x4-0x6 Reserved + 0x7 Command was killed + 0x8 Command execution timeout + 0x9 ADI miscompare error + 0xA Data format error + 0xB-0xD Reserved + 0xE Unexpected hardware error (Do not retry) + 0xF Unexpected hardware error (Retry is ok) + 0x10-0x7F Reserved + 0x80 Partial Symbol Warning + 0x81-0xFF Reserved +2 2 Reserved +4 4 If a partial symbol warning was generated, this field contains the number + of remaining bits which were not decoded. +8 4 Number of bytes of output produced +12 4 Reserved +16 8 Runtime of command (unspecified time units) +24 8 Reserved +32 4 Number of elements processed +36 20 Reserved +56 8 Return value +64 64 Extended return value + +The CCB completion area should be treated as read-only by guest software. The CCB execution status +byte will be cleared by the Hypervisor to reflect the pending execution status when the CCB is submitted +successfully. All other fields are considered invalid upon CCB submission until the CCB execution status +byte becomes non-zero. + +CCBs which complete with status 0x2 or 0x3 may produce partial results and/or side effects due to partial +execution of the CCB command. Some valid data may be accessible depending on the fault type, however, +it is recommended that guest software treat the destination buffer as being in an unknown state. If a CCB +completes with a status byte of 0x2, the error reason code byte can be read to determine what corrective +action should be taken. + +A buffer overflow indicates that the results of the operation exceeded the size of the output buffer indicated +in the CCB. The operation can be retried by resubmitting the CCB with a larger output buffer. + +A CCB decoding error indicates that the CCB contained some invalid field values. It may be also be +triggered if the CCB output is directed at a non-existent secondary input and the pipelining hint is followed. + +A page overflow error indicates that the operation required accessing a memory location beyond the page +size associated with a given address. No data will have been read or written past the page boundary, but +partial results may have been written to the destination buffer. The CCB can be resubmitted with a larger +page size memory allocation to complete the operation. + + + 527 + Coprocessor services + + + In the case of pipelined CCBs, a page overflow error will be triggered if the output from the pipeline source + CCB ends before the input of the pipeline target CCB. Page boundaries are ignored when the pipeline + hint is followed. + + Command kill indicates that the CCB execution was halted or prevented by use of the ccb_kill API call. + + Command timeout indicates that the CCB execution began, but did not complete within a pre-determined + limit set by the virtual machine. The command may have produced some or no output. The CCB may be + resubmitted with no alterations. + + ADI miscompare indicates that the memory buffer version specified in the CCB did not match the value + in memory when accessed by the virtual machine. Guest software should not attempt to resubmit the CCB + without determining the cause of the version mismatch. + + A data format error indicates that the input data stream did not follow the specified data input formatting + selected in the CCB. + + Some CCBs which encounter hardware errors may be resubmitted without change. Persistent hardware + errors may result in multiple failures until RAS software can identify and isolate the faulty component. + + The output size field indicates the number of bytes of valid output in the destination buffer. This field is + not valid for all possible CCB commands. + + The runtime field indicates the execution time of the CCB command once it leaves the internal virtual + machine queue. The time units are fixed, but unspecified, allowing only relative timing comparisons + by guest software. The time units may also vary by hardware platform, and should not be construed to + represent any absolute time value. + + Some data query commands process data in units of elements. If applicable to the command, the number of + elements processed is indicated in the listed field. This field is not valid for all possible CCB commands. + + The return value and extended return value fields are output locations for commands which do not use + a destination output buffer, or have secondary return results. The field is not valid for all possible CCB + commands. + +36.3. Hypervisor API Functions +36.3.1. ccb_submit + trap# FAST_TRAP + function# CCB_SUBMIT + arg0 address + arg1 length + arg2 flags + arg3 reserved + ret0 status + ret1 length + ret2 status data + ret3 reserved + + Submit one or more coprocessor control blocks (CCBs) for evaluation and processing by the virtual + machine. The CCBs are passed in a linear array indicated by address. length indicates the size of + the array in bytes. + + + 528 + Coprocessor services + + +The address should be aligned to the size indicated by length, rounded up to the nearest power of +two. Virtual machines implementations may reject submissions which do not adhere to that alignment. +length must be a multiple of 64 bytes. If length is zero, the maximum supported array length will be +returned as length in ret1. In all other cases, the length value in ret1 will reflect the number of bytes +successfully consumed from the input CCB array. + + Implementation note + Virtual machines should never reject submissions based on the alignment of address if the + entire array is contained within a single memory page of the smallest page size supported by the + virtual machine. + +A guest may choose to submit addresses used in this API function, including the CCB array address, +as either a real or virtual addresses, with the type of each address indicated in flags. Virtual addresses +must be present in either the TLB or an active TSB to be processed. The translation context for virtual +addresses is determined by a combination of CCB contents and the flags argument. + +The flags argument is divided into multiple fields defined as follows: + + +Bits Field Description +[63:16] Reserved +[15] Disable ADI for VA reads (in API 2.0) + Reserved (in API 1.0) +[14] Virtual addresses within CCBs are translated in privileged context +[13:12] Alternate translation context for virtual addresses within CCBs: + 0b'00 CCBs requesting alternate context are rejected + 0b'01 Reserved + 0b'10 CCBs requesting alternate context use secondary context + 0b'11 CCBs requesting alternate context use nucleus context +[11:9] Reserved +[8] Queue info flag +[7] All-or-nothing flag +[6] If address is a virtual address, treat its translation context as privileged +[5:4] Address type of address: + 0b'00 Real address + 0b'01 Virtual address in primary context + 0b'10 Virtual address in secondary context + 0b'11 Virtual address in nucleus context +[3:2] Reserved +[1:0] CCB command type: + 0b'00 Reserved + 0b'01 Reserved + 0b'10 Query command + 0b'11 Reserved + + + + 529 + Coprocessor services + + + The CCB submission type and address type for the CCB array must be provided in the flags argument. + All other fields are optional values which change the default behavior of the CCB processing. + + When set to one, the "Disable ADI for VA reads" bit will turn off ADI checking when using a virtual + address to load data. ADI checking will still be done when loading real-addressed memory. This bit is only + available when using major version 2 of the coprocessor API group; at major version 1 it is reserved. For + more information about using ADI and DAX, see Section 36.2.1.1.7, “Application Data Integrity (ADI)”. + + By default, all virtual addresses are treated as user addresses. If the virtual address translations are + privileged, they must be marked as such in the appropriate flags field. The virtual addresses used within + the submitted CCBs must all be translated with the same privilege level. + + By default, all virtual addresses used within the submitted CCBs are translated using the primary context + active at the time of the submission. The address type field within a CCB allows each address to request + translation in an alternate address context. The address context used when the alternate address context is + requested is selected in the flags argument. + + The all-or-nothing flag specifies whether the virtual machine should allow partial submissions of the + input CCB array. When using CCBs with serial-conditional flags, it is strongly recommended to use + the all-or-nothing flag to avoid broken conditional chains. Using long CCB chains on a machine under + high coprocessor load may make this impractical, however, and require submitting without the flag. + When submitting serial-conditional CCBs without the all-or-nothing flag, guest software must manually + implement the serial-conditional behavior at any point where the chain was not submitted in a single API + call, and resubmission of the remaining CCBs should clear any conditional flag that might be set in the + first remaining CCB. Failure to do so will produce indeterminate CCB execution status and ordering. + + When the all-or-nothing flag is not specified, callers should check the value of length in ret1 to determine + how many CCBs from the array were successfully submitted. Any remaining CCBs can be resubmitted + without modifications. + + The value of length in ret1 is also valid when the API call returns an error, and callers should always + check its value to determine which CCBs in the array were already processed. This will additionally + identify which CCB encountered the processing error, and was not submitted successfully. + + If the queue info flag is used during submission, and at least one CCB was successfully submitted, the + length value in ret1 will be a multi-field value defined as follows: + Bits Field Description + [63:48] DAX unit instance identifier + [47:32] DAX queue instance identifier + [31:16] Reserved + [15:0] Number of CCB bytes successfully submitted + + The value of status data depends on the status value. See error status code descriptions for details. + The value is undefined for status values that do not specifically list a value for the status data. + + The API has a reserved input and output register which will be used in subsequent minor versions of this + API function. Guest software implementations should treat that register as voltile across the function call + in order to maintain forward compatibility. + +36.3.1.1. Errors + EOK One or more CCBs have been accepted and enqueued in the virtual machine + and no errors were been encountered during submission. Some submitted + CCBs may not have been enqueued due to internal virtual machine limitations, + and may be resubmitted without changes. + + + 530 + Coprocessor services + + +EWOULDBLOCK An internal resource conflict within the virtual machine has prevented it from + being able to complete the CCB submissions sufficiently quickly, requiring + it to abandon processing before it was complete. Some CCBs may have been + successfully enqueued prior to the block, and all remaining CCBs may be + resubmitted without changes. +EBADALIGN CCB array is not on a 64-byte boundary, or the array length is not a multiple + of 64 bytes. +ENORADDR A real address used either for the CCB array, or within one of the submitted + CCBs, is not valid for the guest. Some CCBs may have been enqueued prior + to the error being detected. +ENOMAP A virtual address used either for the CCB array, or within one of the submitted + CCBs, could not be translated by the virtual machine using either the TLB + or TSB contents. The submission may be retried after adding the required + mapping, or by converting the virtual address into a real address. Due to the + shared nature of address translation resources, there is no theoretical limit on + the number of times the translation may fail, and it is recommended all guests + implement some real address based backup. The virtual address which failed + translation is returned as status data in ret2. Some CCBs may have been + enqueued prior to the error being detected. +EINVAL The virtual machine detected an invalid CCB during submission, or invalid + input arguments, such as bad flag values. Note that not all invalid CCB values + will be detected during submission, and some may be reported as errors in the + completion area instead. Some CCBs may have been enqueued prior to the + error being detected. This error may be returned if the CCB version is invalid. +ETOOMANY The request was submitted with the all-or-nothing flag set, and the array size is + greater than the virtual machine can support in a single request. The maximum + supported size for the current virtual machine can be queried by submitting a + request with a zero length array, as described above. +ENOACCESS The guest does not have permission to submit CCBs, or an address used in a + CCBs lacks sufficient permissions to perform the required operation (no write + permission on the destination buffer address, for example). A virtual address + which fails permission checking is returned as status data in ret2. Some + CCBs may have been enqueued prior to the error being detected. +EUNAVAILABLE The requested CCB operation could not be performed at this time. The + restricted operation availability may apply only to the first unsuccessfully + submitted CCB, or may apply to a larger scope. The status should not be + interpreted as permanent, and the guest should attempt to submit CCBs in + the future which had previously been unable to be performed. The status + data provides additional information about scope of the retricted availability + as follows: + Value Description + 0 Processing for the exact CCB instance submitted was unavailable, + and it is recommended the guest emulate the operation. The + guest should continue to submit all other CCBs, and assume no + restrictions beyond this exact CCB instance. + 1 Processing is unavailable for all CCBs using the requested opcode, + and it is recommended the guest emulate the operation. The + guest should continue to submit all other CCBs that use different + opcodes, but can expect continued rejections of CCBs using the + same opcode in the near future. + + + 531 + Coprocessor services + + + Value Description + 2 Processing is unavailable for all CCBs using the requested CCB + version, and it is recommended the guest emulate the operation. + The guest should continue to submit all other CCBs that use + different CCB versions, but can expect continued rejections of + CCBs using the same CCB version in the near future. + 3 Processing is unavailable for all CCBs on the submitting vcpu, + and it is recommended the guest emulate the operation or resubmit + the CCB on a different vcpu. The guest should continue to submit + CCBs on all other vcpus but can expect continued rejections of all + CCBs on this vcpu in the near future. + 4 Processing is unavailable for all CCBs, and it is recommended + the guest emulate the operation. The guest should expect all CCB + submissions to be similarly rejected in the near future. + + +36.3.2. ccb_info + + trap# FAST_TRAP + function# CCB_INFO + arg0 address + ret0 status + ret1 CCB state + ret2 position + ret3 dax + ret4 queue + + Requests status information on a previously submitted CCB. The previously submitted CCB is identified + by the 64-byte aligned real address of the CCBs completion area. + + A CCB can be in one of 4 states: + + + State Value Description + COMPLETED 0 The CCB has been fetched and executed, and is no longer active in + the virtual machine. + ENQUEUED 1 The requested CCB is current in a queue awaiting execution. + INPROGRESS 2 The CCB has been fetched and is currently being executed. It may still + be possible to stop the execution using the ccb_kill hypercall. + NOTFOUND 3 The CCB could not be located in the virtual machine, and does not + appear to have been executed. This may occur if the CCB was lost + due to a hardware error, or the CCB may not have been successfully + submitted to the virtual machine in the first place. + + Implementation note + Some platforms may not be able to report CCBs that are currently being processed, and therefore + guest software should invoke the ccb_kill hypercall prior to assuming the request CCB will never + be executed because it was in the NOTFOUND state. + + + 532 + Coprocessor services + + + The position return value is only valid when the state is ENQUEUED. The value returned is the number + of other CCBs ahead of the requested CCB, to provide a relative estimate of when the CCB may execute. + + The dax return value is only valid when the state is ENQUEUED. The value returned is the DAX unit + instance indentifier for the DAX unit processing the queue where the requested CCB is located. The value + matches the value that would have been, or was, returned by ccb_submit using the queue info flag. + + The queue return value is only valid when the state is ENQUEUED. The value returned is the DAX + queue instance indentifier for the DAX unit processing the queue where the requested CCB is located. The + value matches the value that would have been, or was, returned by ccb_submit using the queue info flag. + +36.3.2.1. Errors + + EOK The request was proccessed and the CCB state is valid. + EBADALIGN address is not on a 64-byte aligned. + ENORADDR The real address provided for address is not valid. + EINVAL The CCB completion area contents are not valid. + EWOULDBLOCK Internal resource contraints prevented the CCB state from being queried at this + time. The guest should retry the request. + ENOACCESS The guest does not have permission to access the coprocessor virtual device + functionality. + +36.3.3. ccb_kill + + trap# FAST_TRAP + function# CCB_KILL + arg0 address + ret0 status + ret1 result + + Request to stop execution of a previously submitted CCB. The previously submitted CCB is identified by + the 64-byte aligned real address of the CCBs completion area. + + The kill attempt can produce one of several values in the result return value, reflecting the CCB state + and actions taken by the Hypervisor: + + Result Value Description + COMPLETED 0 The CCB has been fetched and executed, and is no longer active in + the virtual machine. It could not be killed and no action was taken. + DEQUEUED 1 The requested CCB was still enqueued when the kill request was + submitted, and has been removed from the queue. Since the CCB + never began execution, no memory modifications were produced by + it, and the completion area will never be updated. The same CCB may + be submitted again, if desired, with no modifications required. + KILLED 2 The CCB had been fetched and was being executed when the kill + request was submitted. The CCB execution was stopped, and the CCB + is no longer active in the virtual machine. The CCB completion area + will reflect the killed status, with the subsequent implications that + partial results may have been produced. Partial results may include full + + + 533 + Coprocessor services + + + Result Value Description + command execution if the command was stopped just prior to writing + to the completion area. + NOTFOUND 3 The CCB could not be located in the virtual machine, and does not + appear to have been executed. This may occur if the CCB was lost + due to a hardware error, or the CCB may not have been successfully + submitted to the virtual machine in the first place. CCBs in the state + are guaranteed to never execute in the future unless resubmitted. + +36.3.3.1. Interactions with Pipelined CCBs + + If the pipeline target CCB is killed but the pipeline source CCB was skipped, the completion area of the + target CCB may contain status (4,0) "Command was skipped" instead of (3,7) "Command was killed". + + If the pipeline source CCB is killed, the pipeline target CCB's completion status may read (1,0) "Success". + This does not mean the target CCB was processed; since the source CCB was killed, there was no + meaningful output on which the target CCB could operate. + +36.3.3.2. Errors + + EOK The request was proccessed and the result is valid. + EBADALIGN address is not on a 64-byte aligned. + ENORADDR The real address provided for address is not valid. + EINVAL The CCB completion area contents are not valid. + EWOULDBLOCK Internal resource contraints prevented the CCB from being killed at this time. + The guest should retry the request. + ENOACCESS The guest does not have permission to access the coprocessor virtual device + functionality. + +36.3.4. dax_info + trap# FAST_TRAP + function# DAX_INFO + ret0 status + ret1 Number of enabled DAX units + ret2 Number of disabled DAX units + + Returns the number of DAX units that are enabled for the calling guest to submit CCBs. The number of + DAX units that are disabled for the calling guest are also returned. A disabled DAX unit would have been + available for CCB submission to the calling guest had it not been offlined. + +36.3.4.1. Errors + + EOK The request was proccessed and the number of enabled/disabled DAX units + are valid. + + + + + 534 + diff --git a/Documentation/sparc/oradax/oracle-dax.txt b/Documentation/sparc/oradax/oracle-dax.txt new file mode 100644 index 000000000000..9d53ac93286f --- /dev/null +++ b/Documentation/sparc/oradax/oracle-dax.txt @@ -0,0 +1,429 @@ +Oracle Data Analytics Accelerator (DAX) +--------------------------------------- + +DAX is a coprocessor which resides on the SPARC M7 (DAX1) and M8 +(DAX2) processor chips, and has direct access to the CPU's L3 caches +as well as physical memory. It can perform several operations on data +streams with various input and output formats. A driver provides a +transport mechanism and has limited knowledge of the various opcodes +and data formats. A user space library provides high level services +and translates these into low level commands which are then passed +into the driver and subsequently the Hypervisor and the coprocessor. +The library is the recommended way for applications to use the +coprocessor, and the driver interface is not intended for general use. +This document describes the general flow of the driver, its +structures, and its programmatic interface. It also provides example +code sufficient to write user or kernel applications that use DAX +functionality. + +The user library is open source and available at: + https://oss.oracle.com/git/gitweb.cgi?p=libdax.git + +The Hypervisor interface to the coprocessor is described in detail in +the accompanying document, dax-hv-api.txt, which is a plain text +excerpt of the (Oracle internal) "UltraSPARC Virtual Machine +Specification" version 3.0.20+15, dated 2017-09-25. + + +High Level Overview +------------------- + +A coprocessor request is described by a Command Control Block +(CCB). The CCB contains an opcode and various parameters. The opcode +specifies what operation is to be done, and the parameters specify +options, flags, sizes, and addresses. The CCB (or an array of CCBs) +is passed to the Hypervisor, which handles queueing and scheduling of +requests to the available coprocessor execution units. A status code +returned indicates if the request was submitted successfully or if +there was an error. One of the addresses given in each CCB is a +pointer to a "completion area", which is a 128 byte memory block that +is written by the coprocessor to provide execution status. No +interrupt is generated upon completion; the completion area must be +polled by software to find out when a transaction has finished, but +the M7 and later processors provide a mechanism to pause the virtual +processor until the completion status has been updated by the +coprocessor. This is done using the monitored load and mwait +instructions, which are described in more detail later. The DAX +coprocessor was designed so that after a request is submitted, the +kernel is no longer involved in the processing of it. The polling is +done at the user level, which results in almost zero latency between +completion of a request and resumption of execution of the requesting +thread. + + +Addressing Memory +----------------- + +The kernel does not have access to physical memory in the Sun4v +architecture, as there is an additional level of memory virtualization +present. This intermediate level is called "real" memory, and the +kernel treats this as if it were physical. The Hypervisor handles the +translations between real memory and physical so that each logical +domain (LDOM) can have a partition of physical memory that is isolated +from that of other LDOMs. When the kernel sets up a virtual mapping, +it specifies a virtual address and the real address to which it should +be mapped. + +The DAX coprocessor can only operate on physical memory, so before a +request can be fed to the coprocessor, all the addresses in a CCB must +be converted into physical addresses. The kernel cannot do this since +it has no visibility into physical addresses. So a CCB may contain +either the virtual or real addresses of the buffers or a combination +of them. An "address type" field is available for each address that +may be given in the CCB. In all cases, the Hypervisor will translate +all the addresses to physical before dispatching to hardware. Address +translations are performed using the context of the process initiating +the request. + + +The Driver API +-------------- + +An application makes requests to the driver via the write() system +call, and gets results (if any) via read(). The completion areas are +made accessible via mmap(), and are read-only for the application. + +The request may either be an immediate command or an array of CCBs to +be submitted to the hardware. + +Each open instance of the device is exclusive to the thread that +opened it, and must be used by that thread for all subsequent +operations. The driver open function creates a new context for the +thread and initializes it for use. This context contains pointers and +values used internally by the driver to keep track of submitted +requests. The completion area buffer is also allocated, and this is +large enough to contain the completion areas for many concurrent +requests. When the device is closed, any outstanding transactions are +flushed and the context is cleaned up. + +On a DAX1 system (M7), the device will be called "oradax1", while on a +DAX2 system (M8) it will be "oradax2". If an application requires one +or the other, it should simply attempt to open the appropriate +device. Only one of the devices will exist on any given system, so the +name can be used to determine what the platform supports. + +The immediate commands are CCB_DEQUEUE, CCB_KILL, and CCB_INFO. For +all of these, success is indicated by a return value from write() +equal to the number of bytes given in the call. Otherwise -1 is +returned and errno is set. + +CCB_DEQUEUE + +Tells the driver to clean up resources associated with past +requests. Since no interrupt is generated upon the completion of a +request, the driver must be told when it may reclaim resources. No +further status information is returned, so the user should not +subsequently call read(). + +CCB_KILL + +Kills a CCB during execution. The CCB is guaranteed to not continue +executing once this call returns successfully. On success, read() must +be called to retrieve the result of the action. + +CCB_INFO + +Retrieves information about a currently executing CCB. Note that some +Hypervisors might return 'notfound' when the CCB is in 'inprogress' +state. To ensure a CCB in the 'notfound' state will never be executed, +CCB_KILL must be invoked on that CCB. Upon success, read() must be +called to retrieve the details of the action. + +Submission of an array of CCBs for execution + +A write() whose length is a multiple of the CCB size is treated as a +submit operation. The file offset is treated as the index of the +completion area to use, and may be set via lseek() or using the +pwrite() system call. If -1 is returned then errno is set to indicate +the error. Otherwise, the return value is the length of the array that +was actually accepted by the coprocessor. If the accepted length is +equal to the requested length, then the submission was completely +successful and there is no further status needed; hence, the user +should not subsequently call read(). Partial acceptance of the CCB +array is indicated by a return value less than the requested length, +and read() must be called to retrieve further status information. The +status will reflect the error caused by the first CCB that was not +accepted, and status_data will provide additional data in some cases. + +MMAP + +The mmap() function provides access to the completion area allocated +in the driver. Note that the completion area is not writeable by the +user process, and the mmap call must not specify PROT_WRITE. + + +Completion of a Request +----------------------- + +The first byte in each completion area is the command status which is +updated by the coprocessor hardware. Software may take advantage of +new M7/M8 processor capabilities to efficiently poll this status byte. +First, a "monitored load" is achieved via a Load from Alternate Space +(ldxa, lduba, etc.) with ASI 0x84 (ASI_MONITOR_PRIMARY). Second, a +"monitored wait" is achieved via the mwait instruction (a write to +%asr28). This instruction is like pause in that it suspends execution +of the virtual processor for the given number of nanoseconds, but in +addition will terminate early when one of several events occur. If the +block of data containing the monitored location is modified, then the +mwait terminates. This causes software to resume execution immediately +(without a context switch or kernel to user transition) after a +transaction completes. Thus the latency between transaction completion +and resumption of execution may be just a few nanoseconds. + + +Application Life Cycle of a DAX Submission +------------------------------------------ + + - open dax device + - call mmap() to get the completion area address + - allocate a CCB and fill in the opcode, flags, parameters, addresses, etc. + - submit CCB via write() or pwrite() + - go into a loop executing monitored load + monitored wait and + terminate when the command status indicates the request is complete + (CCB_KILL or CCB_INFO may be used any time as necessary) + - perform a CCB_DEQUEUE + - call munmap() for completion area + - close the dax device + + +Memory Constraints +------------------ + +The DAX hardware operates only on physical addresses. Therefore, it is +not aware of virtual memory mappings and the discontiguities that may +exist in the physical memory that a virtual buffer maps to. There is +no I/O TLB or any scatter/gather mechanism. All buffers, whether input +or output, must reside in a physically contiguous region of memory. + +The Hypervisor translates all addresses within a CCB to physical +before handing off the CCB to DAX. The Hypervisor determines the +virtual page size for each virtual address given, and uses this to +program a size limit for each address. This prevents the coprocessor +from reading or writing beyond the bound of the virtual page, even +though it is accessing physical memory directly. A simpler way of +saying this is that a DAX operation will never "cross" a virtual page +boundary. If an 8k virtual page is used, then the data is strictly +limited to 8k. If a user's buffer is larger than 8k, then a larger +page size must be used, or the transaction size will be truncated to +8k. + +Huge pages. A user may allocate huge pages using standard interfaces. +Memory buffers residing on huge pages may be used to achieve much +larger DAX transaction sizes, but the rules must still be followed, +and no transaction will cross a page boundary, even a huge page. A +major caveat is that Linux on Sparc presents 8Mb as one of the huge +page sizes. Sparc does not actually provide a 8Mb hardware page size, +and this size is synthesized by pasting together two 4Mb pages. The +reasons for this are historical, and it creates an issue because only +half of this 8Mb page can actually be used for any given buffer in a +DAX request, and it must be either the first half or the second half; +it cannot be a 4Mb chunk in the middle, since that crosses a +(hardware) page boundary. Note that this entire issue may be hidden by +higher level libraries. + + +CCB Structure +------------- +A CCB is an array of 8 64-bit words. Several of these words provide +command opcodes, parameters, flags, etc., and the rest are addresses +for the completion area, output buffer, and various inputs: + + struct ccb { + u64 control; + u64 completion; + u64 input0; + u64 access; + u64 input1; + u64 op_data; + u64 output; + u64 table; + }; + +See libdax/common/sys/dax1/dax1_ccb.h for a detailed description of +each of these fields, and see dax-hv-api.txt for a complete description +of the Hypervisor API available to the guest OS (ie, Linux kernel). + +The first word (control) is examined by the driver for the following: + - CCB version, which must be consistent with hardware version + - Opcode, which must be one of the documented allowable commands + - Address types, which must be set to "virtual" for all the addresses + given by the user, thereby ensuring that the application can + only access memory that it owns + + +Example Code +------------ + +The DAX is accessible to both user and kernel code. The kernel code +can make hypercalls directly while the user code must use wrappers +provided by the driver. The setup of the CCB is nearly identical for +both; the only difference is in preparation of the completion area. An +example of user code is given now, with kernel code afterwards. + +In order to program using the driver API, the file +arch/sparc/include/uapi/asm/oradax.h must be included. + +First, the proper device must be opened. For M7 it will be +/dev/oradax1 and for M8 it will be /dev/oradax2. The simplest +procedure is to attempt to open both, as only one will succeed: + + fd = open("/dev/oradax1", O_RDWR); + if (fd < 0) + fd = open("/dev/oradax2", O_RDWR); + if (fd < 0) + /* No DAX found */ + +Next, the completion area must be mapped: + + completion_area = mmap(NULL, DAX_MMAP_LEN, PROT_READ, MAP_SHARED, fd, 0); + +All input and output buffers must be fully contained in one hardware +page, since as explained above, the DAX is strictly constrained by +virtual page boundaries. In addition, the output buffer must be +64-byte aligned and its size must be a multiple of 64 bytes because +the coprocessor writes in units of cache lines. + +This example demonstrates the DAX Scan command, which takes as input a +vector and a match value, and produces a bitmap as the output. For +each input element that matches the value, the corresponding bit is +set in the output. + +In this example, the input vector consists of a series of single bits, +and the match value is 0. So each 0 bit in the input will produce a 1 +in the output, and vice versa, which produces an output bitmap which +is the input bitmap inverted. + +For details of all the parameters and bits used in this CCB, please +refer to section 36.2.1.3 of the DAX Hypervisor API document, which +describes the Scan command in detail. + + ccb->control = /* Table 36.1, CCB Header Format */ + (2L << 48) /* command = Scan Value */ + | (3L << 40) /* output address type = primary virtual */ + | (3L << 34) /* primary input address type = primary virtual */ + /* Section 36.2.1, Query CCB Command Formats */ + | (1 << 28) /* 36.2.1.1.1 primary input format = fixed width bit packed */ + | (0 << 23) /* 36.2.1.1.2 primary input element size = 0 (1 bit) */ + | (8 << 10) /* 36.2.1.1.6 output format = bit vector */ + | (0 << 5) /* 36.2.1.3 First scan criteria size = 0 (1 byte) */ + | (31 << 0); /* 36.2.1.3 Disable second scan criteria */ + + ccb->completion = 0; /* Completion area address, to be filled in by driver */ + + ccb->input0 = (unsigned long) input; /* primary input address */ + + ccb->access = /* Section 36.2.1.2, Data Access Control */ + (2 << 24) /* Primary input length format = bits */ + | (nbits - 1); /* number of bits in primary input stream, minus 1 */ + + ccb->input1 = 0; /* secondary input address, unused */ + + ccb->op_data = 0; /* scan criteria (value to be matched) */ + + ccb->output = (unsigned long) output; /* output address */ + + ccb->table = 0; /* table address, unused */ + +The CCB submission is a write() or pwrite() system call to the +driver. If the call fails, then a read() must be used to retrieve the +status: + + if (pwrite(fd, ccb, 64, 0) != 64) { + struct ccb_exec_result status; + read(fd, &status, sizeof(status)); + /* bail out */ + } + +After a successful submission of the CCB, the completion area may be +polled to determine when the DAX is finished. Detailed information on +the contents of the completion area can be found in section 36.2.2 of +the DAX HV API document. + + while (1) { + /* Monitored Load */ + __asm__ __volatile__("lduba [%1] 0x84, %0\n" + : "=r" (status) + : "r" (completion_area)); + + if (status) /* 0 indicates command in progress */ + break; + + /* MWAIT */ + __asm__ __volatile__("wr %%g0, 1000, %%asr28\n" ::); /* 1000 ns */ + } + +A completion area status of 1 indicates successful completion of the +CCB and validity of the output bitmap, which may be used immediately. +All other non-zero values indicate error conditions which are +described in section 36.2.2. + + if (completion_area[0] != 1) { /* section 36.2.2, 1 = command ran and succeeded */ + /* completion_area[0] contains the completion status */ + /* completion_area[1] contains an error code, see 36.2.2 */ + } + +After the completion area has been processed, the driver must be +notified that it can release any resources associated with the +request. This is done via the dequeue operation: + + struct dax_command cmd; + cmd.command = CCB_DEQUEUE; + if (write(fd, &cmd, sizeof(cmd)) != sizeof(cmd)) { + /* bail out */ + } + +Finally, normal program cleanup should be done, i.e., unmapping +completion area, closing the dax device, freeing memory etc. + +[Kernel example] + +The only difference in using the DAX in kernel code is the treatment +of the completion area. Unlike user applications which mmap the +completion area allocated by the driver, kernel code must allocate its +own memory to use for the completion area, and this address and its +type must be given in the CCB: + + ccb->control |= /* Table 36.1, CCB Header Format */ + (3L << 32); /* completion area address type = primary virtual */ + + ccb->completion = (unsigned long) completion_area; /* Completion area address */ + +The dax submit hypercall is made directly. The flags used in the +ccb_submit call are documented in the DAX HV API in section 36.3.1. + +#include + + hv_rv = sun4v_ccb_submit((unsigned long)ccb, 64, + HV_CCB_QUERY_CMD | + HV_CCB_ARG0_PRIVILEGED | HV_CCB_ARG0_TYPE_PRIMARY | + HV_CCB_VA_PRIVILEGED, + 0, &bytes_accepted, &status_data); + + if (hv_rv != HV_EOK) { + /* hv_rv is an error code, status_data contains */ + /* potential additional status, see 36.3.1.1 */ + } + +After the submission, the completion area polling code is identical to +that in user land: + + while (1) { + /* Monitored Load */ + __asm__ __volatile__("lduba [%1] 0x84, %0\n" + : "=r" (status) + : "r" (completion_area)); + + if (status) /* 0 indicates command in progress */ + break; + + /* MWAIT */ + __asm__ __volatile__("wr %%g0, 1000, %%asr28\n" ::); /* 1000 ns */ + } + + if (completion_area[0] != 1) { /* section 36.2.2, 1 = command ran and succeeded */ + /* completion_area[0] contains the completion status */ + /* completion_area[1] contains an error code, see 36.2.2 */ + } + +The output bitmap is ready for consumption immediately after the +completion status indicates success. -- cgit From b2d3bcfa26a7a8de41f358a6cae8b848673b3c6e Mon Sep 17 00:00:00 2001 From: David Decotigny Date: Thu, 18 Jan 2018 09:59:13 -0800 Subject: net: core: Expose number of link up/down transitions Expose the number of times the link has been going UP or DOWN, and update the "carrier_changes" counter to be the sum of these two events. While at it, also update the sysfs-class-net documentation to cover: carrier_changes (3.15), carrier_up_count (4.16) and carrier_down_count (4.16) Signed-off-by: David Decotigny [Florian: * rebase * add documentation * merge carrier_changes with up/down counters] Signed-off-by: Florian Fainelli Signed-off-by: David S. Miller --- Documentation/ABI/testing/sysfs-class-net | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index 6856da99b6f7..2f1788111cd9 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -259,3 +259,27 @@ Contact: netdev@vger.kernel.org Description: Symbolic link to the PHY device this network device is attached to. + +What: /sys/class/net//carrier_changes +Date: Mar 2014 +KernelVersion: 3.15 +Contact: netdev@vger.kernel.org +Description: + 32-bit unsigned integer counting the number of times the link has + seen a change from UP to DOWN and vice versa + +What: /sys/class/net//carrier_up_count +Date: Jan 2018 +KernelVersion: 4.16 +Contact: netdev@vger.kernel.org +Description: + 32-bit unsigned integer counting the number of times the link has + been up + +What: /sys/class/net//carrier_down_count +Date: Jan 2018 +KernelVersion: 4.16 +Contact: netdev@vger.kernel.org +Description: + 32-bit unsigned integer counting the number of times the link has + been down -- cgit From a4d5569eb2169190f9c904cd1a155263735e87a9 Mon Sep 17 00:00:00 2001 From: Andy Shevchenko Date: Mon, 22 Jan 2018 09:27:22 -0800 Subject: Input: docs - use PROPERTY_ENTRY_U32() directly Instead of using PROPERTY_ENTRY_INTEGER() with explicitly supplied type, use PROPERTY_ENTRY_U32() dedicated macro. It will help modify internals of built-in device properties API. No functional change intended. Signed-off-by: Andy Shevchenko Signed-off-by: Dmitry Torokhov --- Documentation/input/devices/rotary-encoder.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/input/devices/rotary-encoder.rst b/Documentation/input/devices/rotary-encoder.rst index b07b20a295ac..810ae02bdaa0 100644 --- a/Documentation/input/devices/rotary-encoder.rst +++ b/Documentation/input/devices/rotary-encoder.rst @@ -108,9 +108,9 @@ example below: }; static const struct property_entry rotary_encoder_properties[] __initconst = { - PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32, 24), - PROPERTY_ENTRY_INTEGER("linux,axis", u32, ABS_X), - PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis", u32, 0), + PROPERTY_ENTRY_U32("rotary-encoder,steps-per-period", 24), + PROPERTY_ENTRY_U32("linux,axis", ABS_X), + PROPERTY_ENTRY_U32("rotary-encoder,relative_axis", 0), { }, }; -- cgit From 56ad7fcd4f058f74db8f4b08dd4e61a52bd8feba Mon Sep 17 00:00:00 2001 From: Xiaofei Tan Date: Thu, 18 Jan 2018 00:46:52 +0800 Subject: scsi: hisi_sas: devicetree: bindings: add LED feature for v2 hw Add directly attached disk LED feature for v2 hw. Signed-off-by: Xiaofei Tan Signed-off-by: John Garry Signed-off-by: Martin K. Petersen --- Documentation/devicetree/bindings/scsi/hisilicon-sas.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt index b6a869f97715..df3bef7998fa 100644 --- a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt +++ b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt @@ -8,7 +8,10 @@ Main node required properties: (b) "hisilicon,hip06-sas-v2" for v2 hw in hip06 chipset (c) "hisilicon,hip07-sas-v2" for v2 hw in hip07 chipset - sas-addr : array of 8 bytes for host SAS address - - reg : Address and length of the SAS register + - reg : Contains two regions. The first is the address and length of the SAS + register. The second is the address and length of CPLD register for + SGPIO control. The second is optional, and should be set only when + we use a CPLD for directly attached disk LED control. - hisilicon,sas-syscon: phandle of syscon used for sas control - ctrl-reset-reg : offset to controller reset register in ctrl reg - ctrl-reset-sts-reg : offset to controller reset status register in ctrl reg -- cgit From 36d1d09af1b97113cd014fd50694000ac3ca2824 Mon Sep 17 00:00:00 2001 From: Arend van Spriel Date: Thu, 11 Jan 2018 09:36:37 +0100 Subject: sysfs: add attribute specification for /sysfs/devices/.../coredump This patch adds the specification for /sysfs/devices/.../coredump which allows user-space to trigger a device coredump obtaining binary data from the device for (fault) analysis. It relies on CONFIG_DEV_COREDUMP being enabled. Signed-off-by: Arend van Spriel Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-devices-coredump | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-devices-coredump (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-devices-coredump b/Documentation/ABI/testing/sysfs-devices-coredump new file mode 100644 index 000000000000..e459368533a4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-coredump @@ -0,0 +1,10 @@ +What: /sys/devices/.../coredump +Date: December 2017 +Contact: Arend van Spriel +Description: + The /sys/devices/.../coredump attribute is only present when the + device is bound to a driver, which provides the .coredump() + callback. The attribute is write only. Anything written to this + file will trigger the .coredump() callback. + + Available when CONFIG_DEV_COREDUMP is enabled. -- cgit From 02d742f4b209057710ed54f14f24861d94c2cd99 Mon Sep 17 00:00:00 2001 From: Sean Young Date: Thu, 28 Dec 2017 14:58:26 -0500 Subject: media: lirc: lirc daemon fails to detect raw IR device Since commit 9b6192589be7 ("media: lirc: implement scancode sending"), and commit de142c324106 ("media: lirc: implement reading scancode") the lirc features ioctl for raw IR devices advertises two modes for sending and receiving. The lirc daemon now fails to detect a raw IR device, both for transmit and receive. To fix this, do not advertise the scancode mode in the lirc features for raw IR devices (however do keep it for scancode devices). The mode can still be used via the LIRC_SET_{REC,SEND}_MODE ioctl. Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/lirc-get-features.rst | 24 +++++++++++------------ 1 file changed, 11 insertions(+), 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst index 3ee44067de63..889a8807037b 100644 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ b/Documentation/media/uapi/rc/lirc-get-features.rst @@ -55,8 +55,11 @@ LIRC features ``LIRC_CAN_REC_MODE2`` - The driver is capable of receiving using - :ref:`LIRC_MODE_MODE2 `. + This is raw IR driver for receiving. This means that + :ref:`LIRC_MODE_MODE2 ` is used. This also implies + that :ref:`LIRC_MODE_SCANCODE ` is also supported, + as long as the kernel is recent enough. Use the + :ref:`lirc_set_rec_mode` to switch modes. .. _LIRC-CAN-REC-LIRCCODE: @@ -68,9 +71,8 @@ LIRC features ``LIRC_CAN_REC_SCANCODE`` - The driver is capable of receiving using - :ref:`LIRC_MODE_SCANCODE `. - + This is a scancode driver for receiving. This means that + :ref:`LIRC_MODE_SCANCODE ` is used. .. _LIRC-CAN-SET-SEND-CARRIER: @@ -164,7 +166,10 @@ LIRC features ``LIRC_CAN_SEND_PULSE`` The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_PULSE `. + :ref:`LIRC_MODE_PULSE `. This implies that + :ref:`LIRC_MODE_SCANCODE ` is also supported for + transmit, as long as the kernel is recent enough. Use the + :ref:`lirc_set_send_mode` to switch modes. .. _LIRC-CAN-SEND-MODE2: @@ -179,13 +184,6 @@ LIRC features Unused. Kept just to avoid breaking uAPI. -.. _LIRC-CAN-SEND-SCANCODE: - -``LIRC_CAN_SEND_SCANCODE`` - - The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_SCANCODE `. - Return Value ============ -- cgit From e3cd973429ff7d05480b3889a9a6f4b658083137 Mon Sep 17 00:00:00 2001 From: Sean Young Date: Thu, 28 Dec 2017 17:03:22 -0500 Subject: media: lirc: lirc mode ioctls deal with current mode The ioctl change the current mode or return the current mode; they do not tell you which modes are possible (use the lirc features ioctl for that). Signed-off-by: Sean Young Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/lirc-get-rec-mode.rst | 42 ++++++++++++++++------ Documentation/media/uapi/rc/lirc-get-send-mode.rst | 38 +++++++++++++++----- 2 files changed, 62 insertions(+), 18 deletions(-) (limited to 'Documentation') diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst index 34919feaf392..2722118484fa 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst @@ -10,15 +10,15 @@ ioctls LIRC_GET_REC_MODE and LIRC_SET_REC_MODE Name ==== -LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set supported receive modes. +LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 rx_modes) +.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) :name: LIRC_GET_REC_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 rx_modes) +.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) :name: LIRC_SET_REC_MODE Arguments @@ -27,19 +27,41 @@ Arguments ``fd`` File descriptor returned by open(). -``rx_modes`` - Bitmask with the supported transmit modes. +``mode`` + Mode used for receive. Description =========== -Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 ` -and :ref:`LIRC_MODE_SCANCODE ` are supported. +Get and set the current receive mode. Only +:ref:`LIRC_MODE_MODE2 ` and +:ref:`LIRC_MODE_SCANCODE ` are supported. Use :ref:`lirc_get_features` to find out which modes the driver supports. Return Value ============ -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``ENODEV`` + + - Device not available. + + - .. row 2 + + - ``ENOTTY`` + + - Device does not support receiving. + + - .. row 3 + + - ``EINVAL`` + + - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst index e39383f08e21..c44e61a79ad1 100644 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst @@ -10,15 +10,15 @@ ioctls LIRC_GET_SEND_MODE and LIRC_SET_SEND_MODE Name ==== -LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set supported transmit mode. +LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. Synopsis ======== -.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *tx_modes ) +.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) :name: LIRC_GET_SEND_MODE -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *tx_modes ) +.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) :name: LIRC_SET_SEND_MODE Arguments @@ -27,8 +27,8 @@ Arguments ``fd`` File descriptor returned by open(). -``tx_modes`` - Bitmask with the supported transmit modes. +``mode`` + The mode used for transmitting. Description @@ -44,6 +44,28 @@ modes the driver supports. Return Value ============ -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``ENODEV`` + + - Device not available. + + - .. row 2 + + - ``ENOTTY`` + + - Device does not support transmitting. + + - .. row 3 + + - ``EINVAL`` + + - Invalid mode or invalid mode for this device. -- cgit From dac15ed62dc9d7898d3695a3c393d6f712d66185 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 16 Dec 2017 05:44:13 -0500 Subject: media: dt-bindings/media/cec-gpio.txt: mention the CEC/HPD max voltages Mention the maximum voltages of the CEC and HPD lines. Since in the example these lines are connected to a Raspberry Pi and the Rpi GPIO lines are 3.3V it is a good idea to warn against directly connecting the HPD to the Raspberry Pi's GPIO line. Signed-off-by: Hans Verkuil Reviewed-by: Rob Herring Cc: # for v4.15 Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/media/cec-gpio.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/media/cec-gpio.txt b/Documentation/devicetree/bindings/media/cec-gpio.txt index 46a0bac8b3b9..12fcd55ed153 100644 --- a/Documentation/devicetree/bindings/media/cec-gpio.txt +++ b/Documentation/devicetree/bindings/media/cec-gpio.txt @@ -4,6 +4,10 @@ The HDMI CEC GPIO module supports CEC implementations where the CEC line is hooked up to a pull-up GPIO line and - optionally - the HPD line is hooked up to another GPIO line. +Please note: the maximum voltage for the CEC line is 3.63V, for the HPD +line it is 5.3V. So you may need some sort of level conversion circuitry +when connecting them to a GPIO line. + Required properties: - compatible: value must be "cec-gpio". - cec-gpios: gpio that the CEC line is connected to. The line should be @@ -21,7 +25,7 @@ the following property is optional: Example for the Raspberry Pi 3 where the CEC line is connected to pin 26 aka BCM7 aka CE1 on the GPIO pin header and the HPD line is -connected to pin 11 aka BCM17: +connected to pin 11 aka BCM17 (some level shifter is needed for this!): #include -- cgit From f13ebc4fbcc7a25fd3ab0cac529ee02c1db4fc7c Mon Sep 17 00:00:00 2001 From: Jian Hu Date: Mon, 20 Nov 2017 22:54:11 +0800 Subject: dt-bindings: i2c: update documentation for the Meson-AXG Update the doc to explicitly add Meson-AXG to support list Signed-off-by: Jian Hu Signed-off-by: Yixun Lan Acked-by: Rob Herring Signed-off-by: Wolfram Sang --- Documentation/devicetree/bindings/i2c/i2c-meson.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt index 611b934c7e10..13d410de077c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-meson.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt @@ -1,7 +1,11 @@ Amlogic Meson I2C controller Required properties: - - compatible: must be "amlogic,meson6-i2c" or "amlogic,meson-gxbb-i2c" + - compatible: must be: + "amlogic,meson6-i2c" for Meson8 and compatible SoCs + "amlogic,meson-gxbb-i2c" for GXBB and compatible SoCs + "amlogic,meson-axg-i2c"for AXG and compatible SoCs + - reg: physical address and length of the device registers - interrupts: a single interrupt specifier - clocks: clock for the device -- cgit From 60b866420ba7ae0b6a8d338f49be21c601d19064 Mon Sep 17 00:00:00 2001 From: Amir Goldstein Date: Wed, 10 Jan 2018 23:15:21 +0200 Subject: ovl: update documentation of inodes index feature Document that inode index feature solves breaking hard links on copy up. Simplify Kconfig backward compatibility disclaimer. Signed-off-by: Amir Goldstein Signed-off-by: Miklos Szeredi --- Documentation/filesystems/overlayfs.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index e6a5f4912b6d..213547cb6d36 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -281,9 +281,9 @@ filesystem, so both st_dev and st_ino of the file may change. Any open files referring to this inode will access the old data. -If a file with multiple hard links is copied up, then this will -"break" the link. Changes will not be propagated to other names -referring to the same inode. +Unless "inode index" feature is enabled, if a file with multiple hard +links is copied up, then this will "break" the link. Changes will not be +propagated to other names referring to the same inode. Unless "redirect_dir" feature is enabled, rename(2) on a lower or merged directory will fail with EXDEV. -- cgit From f168f1098dd9038daaf9f7be5f81cdea4985886a Mon Sep 17 00:00:00 2001 From: Amir Goldstein Date: Fri, 19 Jan 2018 11:26:53 +0200 Subject: ovl: add support for "nfs_export" configuration Introduce the "nfs_export" config, module and mount options. The NFS export feature depends on the "index" feature and enables two implicit overlayfs features: "index_all" and "verify_lower". The "index_all" feature creates an index on copy up of every file and directory. The "verify_lower" feature uses the full index to detect overlay filesystems inconsistencies on lookup, like redirect from multiple upper dirs to the same lower dir. NFS export can be enabled for non-upper mount with no index. However, because lower layer redirects cannot be verified with the index, enabling NFS export support on an overlay with no upper layer requires turning off redirect follow (e.g. "redirect_dir=nofollow"). The full index may incur some overhead on mount time, especially when verifying that lower directory file handles are not stale. NFS export support, full index and consistency verification will be implemented by following patches. Signed-off-by: Amir Goldstein Signed-off-by: Miklos Szeredi --- Documentation/filesystems/overlayfs.txt | 35 +++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'Documentation') diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index 213547cb6d36..7a05329844d2 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -190,6 +190,24 @@ Mount options: Redirects are not created and not followed (equivalent to "redirect_dir=off" if "redirect_always_follow" feature is not enabled). +When the NFS export feature is enabled, every copied up directory is +indexed by the file handle of the lower inode and a file handle of the +upper directory is stored in a "trusted.overlay.upper" extended attribute +on the index entry. On lookup of a merged directory, if the upper +directory does not match the file handle stores in the index, that is an +indication that multiple upper directories may be redirected to the same +lower directory. In that case, lookup returns an error and warns about +a possible inconsistency. + +Because lower layer redirects cannot be verified with the index, enabling +NFS export support on an overlay filesystem with no upper layer requires +turning off redirect follow (e.g. "redirect_dir=nofollow"). + +When the NFS export feature is enabled, all directory index entries are +verified on mount time to check that upper file handles are not stale. +This verification may cause significant overhead in some cases. + + Non-directories --------------- @@ -299,6 +317,23 @@ filesystem are not allowed. If the underlying filesystem is changed, the behavior of the overlay is undefined, though it will not result in a crash or deadlock. +When the overlay NFS export feature is enabled, overlay filesystems +behavior on offline changes of the underlying lower layer is different +than the behavior when NFS export is disabled. + +On every copy_up, an NFS file handle of the lower inode, along with the +UUID of the lower filesystem, are encoded and stored in an extended +attribute "trusted.overlay.origin" on the upper inode. + +When the NFS export feature is enabled, a lookup of a merged directory, +that found a lower directory at the lookup path or at the path pointed +to by the "trusted.overlay.redirect" extended attribute, will verify +that the found lower directory file handle and lower filesystem UUID +match the origin file handle that was stored at copy_up time. If a +found lower directory does not match the stored origin, that directory +will not be merged with the upper directory. + + Testsuite --------- -- cgit From a01f64b5c06ca1130b0b72ceb5e2a25e4d37ab08 Mon Sep 17 00:00:00 2001 From: Amir Goldstein Date: Thu, 25 May 2017 22:39:21 +0300 Subject: ovl: document NFS export Document NFS export design. Followup patches will implement this design. Signed-off-by: Amir Goldstein Signed-off-by: Miklos Szeredi --- Documentation/filesystems/overlayfs.txt | 73 +++++++++++++++++++++++++++++++-- 1 file changed, 69 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index 7a05329844d2..6ea1e64d1464 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -203,10 +203,6 @@ Because lower layer redirects cannot be verified with the index, enabling NFS export support on an overlay filesystem with no upper layer requires turning off redirect follow (e.g. "redirect_dir=nofollow"). -When the NFS export feature is enabled, all directory index entries are -verified on mount time to check that upper file handles are not stale. -This verification may cause significant overhead in some cases. - Non-directories --------------- @@ -334,6 +330,75 @@ found lower directory does not match the stored origin, that directory will not be merged with the upper directory. + +NFS export +---------- + +When the underlying filesystems supports NFS export and the "nfs_export" +feature is enabled, an overlay filesystem may be exported to NFS. + +With the "nfs_export" feature, on copy_up of any lower object, an index +entry is created under the index directory. The index entry name is the +hexadecimal representation of the copy up origin file handle. For a +non-directory object, the index entry is a hard link to the upper inode. +For a directory object, the index entry has an extended attribute +"trusted.overlay.upper" with an encoded file handle of the upper +directory inode. + +When encoding a file handle from an overlay filesystem object, the +following rules apply: + +1. For a non-upper object, encode a lower file handle from lower inode +2. For an indexed object, encode a lower file handle from copy_up origin +3. For a pure-upper object and for an existing non-indexed upper object, + encode an upper file handle from upper inode + +The encoded overlay file handle includes: + - Header including path type information (e.g. lower/upper) + - UUID of the underlying filesystem + - Underlying filesystem encoding of underlying inode + +This encoding format is identical to the encoding format file handles that +are stored in extended attribute "trusted.overlay.origin". + +When decoding an overlay file handle, the following steps are followed: + +1. Find underlying layer by UUID and path type information. +2. Decode the underlying filesystem file handle to underlying dentry. +3. For a lower file handle, lookup the handle in index directory by name. +4. If a whiteout is found in index, return ESTALE. This represents an + overlay object that was deleted after its file handle was encoded. +5. For a non-directory, instantiate a disconnected overlay dentry from the + decoded underlying dentry, the path type and index inode, if found. +6. For a directory, use the connected underlying decoded dentry, path type + and index, to lookup a connected overlay dentry. + +Decoding a non-directory file handle may return a disconnected dentry. +copy_up of that disconnected dentry will create an upper index entry with +no upper alias. + +When overlay filesystem has multiple lower layers, a middle layer +directory may have a "redirect" to lower directory. Because middle layer +"redirects" are not indexed, a lower file handle that was encoded from the +"redirect" origin directory, cannot be used to find the middle or upper +layer directory. Similarly, a lower file handle that was encoded from a +descendant of the "redirect" origin directory, cannot be used to +reconstruct a connected overlay path. To mitigate the cases of +directories that cannot be decoded from a lower file handle, these +directories are copied up on encode and encoded as an upper file handle. +On an overlay filesystem with no upper layer this mitigation cannot be +used NFS export in this setup requires turning off redirect follow (e.g. +"redirect_dir=nofollow"). + +The overlay filesystem does not support non-directory connectable file +handles, so exporting with the 'subtree_check' exportfs configuration will +cause failures to lookup files over NFS. + +When the NFS export feature is enabled, all directory index entries are +verified on mount time to check that upper file handles are not stale. +This verification may cause significant overhead in some cases. + + Testsuite --------- -- cgit From e9dcd80b9d77a92bfae6ce42a451f5c5fd318832 Mon Sep 17 00:00:00 2001 From: Wang YanQing Date: Wed, 24 Jan 2018 15:48:26 +0800 Subject: bpf, doc: Correct one wrong value in "Register value tracking" If we then OR this with 0x40, then the value of 6th bit (0th is first bit) become known, so the right mask is 0xbf instead of 0xcf. Signed-off-by: Wang YanQing Acked-by: Edward Cree Signed-off-by: Daniel Borkmann --- Documentation/networking/filter.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 87814859cfc2..a4508ec1816b 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -1134,7 +1134,7 @@ The verifier's knowledge about the variable offset consists of: mask and value; no bit should ever be 1 in both. For example, if a byte is read into a register from memory, the register's top 56 bits are known zero, while the low 8 are unknown - which is represented as the tnum (0x0; 0xff). If we -then OR this with 0x40, we get (0x40; 0xcf), then if we add 1 we get (0x0; +then OR this with 0x40, we get (0x40; 0xbf), then if we add 1 we get (0x0; 0x1ff), because of potential carries. Besides arithmetic, the register state can also be updated by conditional branches. For instance, if a SCALAR_VALUE is compared > 8, in the 'true' branch -- cgit From d2ee7973c37667425e37dfcf0da3b9f546abfe66 Mon Sep 17 00:00:00 2001 From: Dmitry Safonov Date: Thu, 18 Jan 2018 18:31:33 +0000 Subject: Documentation/pktgen: Clearify how-to use pktgen samples o Change process name in ps output: looks like, these days the process is named kpktgend_, rather than pktgen/. o Use pg_ctrl for start/stop as it can work well with pgset without changes to $(PGDEV) variable. o Clarify a bit needed $(PGDEV) definition for sample scripts and that one needs to `source functions.sh`. o Document how-to unset a behaviour flag, note about history expansion. o Fix pgset spi parameter value. Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Dmitry Safonov Signed-off-by: David S. Miller --- Documentation/networking/pktgen.txt | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/pktgen.txt b/Documentation/networking/pktgen.txt index 2c4e3354e128..d2fd78f85aa4 100644 --- a/Documentation/networking/pktgen.txt +++ b/Documentation/networking/pktgen.txt @@ -12,8 +12,8 @@ suitable sample script and configure that. On a dual CPU: ps aux | grep pkt -root 129 0.3 0.0 0 0 ? SW 2003 523:20 [pktgen/0] -root 130 0.3 0.0 0 0 ? SW 2003 509:50 [pktgen/1] +root 129 0.3 0.0 0 0 ? SW 2003 523:20 [kpktgend_0] +root 130 0.3 0.0 0 0 ? SW 2003 509:50 [kpktgend_1] For monitoring and control pktgen creates: @@ -113,9 +113,16 @@ Configuring devices =================== This is done via the /proc interface, and most easily done via pgset as defined in the sample scripts. +You need to specify PGDEV environment variable to use functions from sample +scripts, i.e.: +export PGDEV=/proc/net/pktgen/eth4@0 +source samples/pktgen/functions.sh Examples: + pg_ctrl start starts injection. + pg_ctrl stop aborts injection. Also, ^C aborts generator. + pgset "clone_skb 1" sets the number of copies of the same packet pgset "clone_skb 0" use single SKB for all transmits pgset "burst 8" uses xmit_more API to queue 8 copies of the same @@ -165,8 +172,12 @@ Examples: IPSEC # IPsec encapsulation (needs CONFIG_XFRM) NODE_ALLOC # node specific memory allocation NO_TIMESTAMP # disable timestamping + pgset 'flag ![name]' Clear a flag to determine behaviour. + Note that you might need to use single quote in + interactive mode, so that your shell wouldn't expand + the specified flag as a history command. - pgset spi SPI_VALUE Set specific SA used to transform packet. + pgset "spi [SPI_VALUE]" Set specific SA used to transform packet. pgset "udp_src_min 9" set UDP source port min, If < udp_src_max, then cycle through the port range. @@ -207,8 +218,6 @@ Examples: pgset "tos XX" set former IPv4 TOS field (e.g. "tos 28" for AF11 no ECN, default 00) pgset "traffic_class XX" set former IPv6 TRAFFIC CLASS (e.g. "traffic_class B8" for EF no ECN, default 00) - pgset stop aborts injection. Also, ^C aborts generator. - pgset "rate 300M" set rate to 300 Mb/s pgset "ratep 1000000" set rate to 1Mpps -- cgit From c508c46e6e3aef7762a214a09cf826711f1e2772 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Tue, 23 Jan 2018 18:06:32 -0800 Subject: firmware: Fix up docs referring to FIRMWARE_IN_KERNEL We've removed the option, so stop talking about it. Signed-off-by: Benjamin Gilbert Acked-by: Ingo Molnar Cc: Borislav Petkov Cc: Thomas Gleixner Cc: H. Peter Anvin Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/firmware/built-in-fw.rst | 7 +------ Documentation/x86/microcode.txt | 5 ++--- 2 files changed, 3 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/firmware/built-in-fw.rst b/Documentation/driver-api/firmware/built-in-fw.rst index 7300e66857f8..396cdf591ac5 100644 --- a/Documentation/driver-api/firmware/built-in-fw.rst +++ b/Documentation/driver-api/firmware/built-in-fw.rst @@ -11,13 +11,8 @@ options: * CONFIG_EXTRA_FIRMWARE * CONFIG_EXTRA_FIRMWARE_DIR -This should not be confused with CONFIG_FIRMWARE_IN_KERNEL, this is for drivers -which enables firmware to be built as part of the kernel build process. This -option, CONFIG_FIRMWARE_IN_KERNEL, will build all firmware for all drivers -enabled which ship its firmware inside the Linux kernel source tree. - There are a few reasons why you might want to consider building your firmware -into the kernel with CONFIG_EXTRA_FIRMWARE though: +into the kernel with CONFIG_EXTRA_FIRMWARE: * Speed * Firmware is needed for accessing the boot device, and the user doesn't diff --git a/Documentation/x86/microcode.txt b/Documentation/x86/microcode.txt index f57e1b45e628..79fdb4a8148a 100644 --- a/Documentation/x86/microcode.txt +++ b/Documentation/x86/microcode.txt @@ -108,12 +108,11 @@ packages already put them there. ==================== The loader supports also loading of a builtin microcode supplied through -the regular firmware builtin method CONFIG_FIRMWARE_IN_KERNEL. Only -64-bit is currently supported. +the regular builtin firmware method CONFIG_EXTRA_FIRMWARE. Only 64-bit is +currently supported. Here's an example: -CONFIG_FIRMWARE_IN_KERNEL=y CONFIG_EXTRA_FIRMWARE="intel-ucode/06-3a-09 amd-ucode/microcode_amd_fam15h.bin" CONFIG_EXTRA_FIRMWARE_DIR="/lib/firmware" -- cgit From cea470729db42a0363c5352e8bd85ef81345eadc Mon Sep 17 00:00:00 2001 From: Marc Kleine-Budde Date: Wed, 24 Jan 2018 12:39:24 +0100 Subject: Documentation/devicetree: mpc5200.txt: fix pointer to location of fsl,mpc5200-mscan node This patch fixes the pointer to the location of the fsl,mpc5200-mscan device tree node binding documentation. Signed-off-by: Marc Kleine-Budde --- Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt b/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt index 4ccb2cd5df94..d096cf461d81 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt @@ -195,4 +195,4 @@ External interrupts: fsl,mpc5200-mscan nodes ----------------------- -See file can.txt in this directory. +See file Documentation/devicetree/bindings/powerpc/fsl/mpc5200.txt -- cgit From 7d5977394515ad3a636361ce23890863be6e0f70 Mon Sep 17 00:00:00 2001 From: Robert Schwebel Date: Wed, 24 Jan 2018 11:19:11 +0100 Subject: can: migrate documentation to restructured text The kernel documentation is now restructured text. Convert the SocketCAN documentation and include it in the toplevel kernel documentation. This patch doesn't do any content change. All references to can.txt in the code are converted to can.rst. Signed-off-by: Robert Schwebel Signed-off-by: Marc Kleine-Budde --- Documentation/networking/00-INDEX | 2 - Documentation/networking/can.rst | 1437 ++++++++++++++++++++++++++++++++++++ Documentation/networking/can.txt | 1308 -------------------------------- Documentation/networking/index.rst | 1 + 4 files changed, 1438 insertions(+), 1310 deletions(-) create mode 100644 Documentation/networking/can.rst delete mode 100644 Documentation/networking/can.txt (limited to 'Documentation') diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index f5d642c01dd3..2b89d91b376f 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -36,8 +36,6 @@ bonding.txt - Linux Ethernet Bonding Driver HOWTO: link aggregation in Linux. bridge.txt - where to get user space programs for ethernet bridging with Linux. -can.txt - - documentation on CAN protocol family. cdc_mbim.txt - 3G/LTE USB modem (Mobile Broadband Interface Model) checksum-offloads.txt diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst new file mode 100644 index 000000000000..d23c51abf8c6 --- /dev/null +++ b/Documentation/networking/can.rst @@ -0,0 +1,1437 @@ +=================================== +SocketCAN - Controller Area Network +=================================== + +Overview / What is SocketCAN +============================ + +The socketcan package is an implementation of CAN protocols +(Controller Area Network) for Linux. CAN is a networking technology +which has widespread use in automation, embedded devices, and +automotive fields. While there have been other CAN implementations +for Linux based on character devices, SocketCAN uses the Berkeley +socket API, the Linux network stack and implements the CAN device +drivers as network interfaces. The CAN socket API has been designed +as similar as possible to the TCP/IP protocols to allow programmers, +familiar with network programming, to easily learn how to use CAN +sockets. + + +.. _socketcan-motivation: + +Motivation / Why Using the Socket API +===================================== + +There have been CAN implementations for Linux before SocketCAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's API. + +SocketCAN was designed to overcome all of these limitations. A new +protocol family has been implemented which provides a socket interface +to user space applications and which builds upon the Linux network +layer, enabling use all of the provided queueing functionality. A device +driver for CAN controller hardware registers itself with the Linux +network layer as a network device, so that CAN frames from the +controller can be passed up to the network layer and on to the CAN +protocol family module and also vice-versa. Also, the protocol family +module provides an API for transport protocol modules to register, so +that any number of transport protocols can be loaded or unloaded +dynamically. In fact, the can core module alone does not provide any +protocol and cannot be used without loading at least one additional +protocol module. Multiple sockets can be opened at the same time, +on different or the same protocol module and they can listen/send +frames on different or the same CAN IDs. Several sockets listening on +the same interface for frames with the same CAN ID are all passed the +same received matching CAN frames. An application wishing to +communicate using a specific transport protocol, e.g. ISO-TP, just +selects that protocol when opening the socket, and then can read and +write application data byte streams, without having to deal with +CAN-IDs, frames, etc. + +Similar functionality visible from user-space could be provided by a +character device, too, but this would lead to a technically inelegant +solution for a couple of reasons: + +* **Intricate usage:** Instead of passing a protocol argument to + socket(2) and using bind(2) to select a CAN interface and CAN ID, an + application would have to do all these operations using ioctl(2)s. + +* **Code duplication:** A character device cannot make use of the Linux + network queueing code, so all that code would have to be duplicated + for CAN networking. + +* **Abstraction:** In most existing character-device implementations, the + hardware-specific device driver for a CAN controller directly + provides the character device for the application to work with. + This is at least very unusual in Unix systems for both, char and + block devices. For example you don't have a character device for a + certain UART of a serial interface, a certain sound chip in your + computer, a SCSI or IDE controller providing access to your hard + disk or tape streamer device. Instead, you have abstraction layers + which provide a unified character or block device interface to the + application on the one hand, and a interface for hardware-specific + device drivers on the other hand. These abstractions are provided + by subsystems like the tty layer, the audio subsystem or the SCSI + and IDE subsystems for the devices mentioned above. + + The easiest way to implement a CAN device driver is as a character + device without such a (complete) abstraction layer, as is done by most + existing drivers. The right way, however, would be to add such a + layer with all the functionality like registering for certain CAN + IDs, supporting several open file descriptors and (de)multiplexing + CAN frames between them, (sophisticated) queueing of CAN frames, and + providing an API for device drivers to register with. However, then + it would be no more difficult, or may be even easier, to use the + networking framework provided by the Linux kernel, and this is what + SocketCAN does. + +The use of the networking framework of the Linux kernel is just the +natural and most appropriate way to implement CAN for Linux. + + +.. _socketcan-concept: + +SocketCAN Concept +================= + +As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to +provide a socket interface to user space applications which builds +upon the Linux network layer. In contrast to the commonly known +TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) +medium that has no MAC-layer addressing like ethernet. The CAN-identifier +(can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs +have to be chosen uniquely on the bus. When designing a CAN-ECU +network the CAN-IDs are mapped to be sent by a specific ECU. +For this reason a CAN-ID can be treated best as a kind of source address. + + +.. _socketcan-receive-lists: + +Receive Lists +------------- + +The network transparent access of multiple applications leads to the +problem that different applications may be interested in the same +CAN-IDs from the same CAN network interface. The SocketCAN core +module - which implements the protocol family CAN - provides several +high efficient receive lists for this reason. If e.g. a user space +application opens a CAN RAW socket, the raw protocol module itself +requests the (range of) CAN-IDs from the SocketCAN core that are +requested by the user. The subscription and unsubscription of +CAN-IDs can be done for specific CAN interfaces or for all(!) known +CAN interfaces with the can_rx_(un)register() functions provided to +CAN protocol modules by the SocketCAN core (see :ref:`socketcan-core-module`). +To optimize the CPU usage at runtime the receive lists are split up +into several specific lists per device that match the requested +filter complexity for a given use-case. + + +.. _socketcan-local-loopback1: + +Local Loopback of Sent Frames +----------------------------- + +As known from other networking concepts the data exchanging +applications may run on the same or different nodes without any +change (except for the according addressing information): + +.. code:: + + ___ ___ ___ _______ ___ + | _ | | _ | | _ | | _ _ | | _ | + ||A|| ||B|| ||C|| ||A| |B|| ||C|| + |___| |___| |___| |_______| |___| + | | | | | + -----------------(1)- CAN bus -(2)--------------- + +To ensure that application A receives the same information in the +example (2) as it would receive in example (1) there is need for +some kind of local loopback of the sent CAN frames on the appropriate +node. + +The Linux network devices (by default) just can handle the +transmission and reception of media dependent frames. Due to the +arbitration on the CAN bus the transmission of a low prio CAN-ID +may be delayed by the reception of a high prio CAN frame. To +reflect the correct [*]_ traffic on the node the loopback of the sent +data has to be performed right after a successful transmission. If +the CAN network interface is not capable of performing the loopback for +some reason the SocketCAN core can do this task as a fallback solution. +See :ref:`socketcan-local-loopback1` for details (recommended). + +The loopback functionality is enabled by default to reflect standard +networking behaviour for CAN applications. Due to some requests from +the RT-SocketCAN group the loopback optionally may be disabled for each +separate socket. See sockopts from the CAN RAW sockets in :ref:`socketcan-raw-sockets`. + +.. [*] you really like to have this when you're running analyser + tools like 'candump' or 'cansniffer' on the (same) node. + + +.. _socketcan-network-problem-notifications: + +Network Problem Notifications +----------------------------- + +The use of the CAN bus may lead to several problems on the physical +and media access control layer. Detecting and logging of these lower +layer problems is a vital requirement for CAN users to identify +hardware issues on the physical transceiver layer as well as +arbitration problems and error frames caused by the different +ECUs. The occurrence of detected errors are important for diagnosis +and have to be logged together with the exact timestamp. For this +reason the CAN interface driver can generate so called Error Message +Frames that can optionally be passed to the user application in the +same way as other CAN frames. Whenever an error on the physical layer +or the MAC layer is detected (e.g. by the CAN controller) the driver +creates an appropriate error message frame. Error messages frames can +be requested by the user application using the common CAN filter +mechanisms. Inside this filter definition the (interested) type of +errors may be selected. The reception of error messages is disabled +by default. The format of the CAN error message frame is briefly +described in the Linux header file "include/uapi/linux/can/error.h". + + +How to use SocketCAN +==================== + +Like TCP/IP, you first need to open a socket for communicating over a +CAN network. Since SocketCAN implements a new protocol family, you +need to pass PF_CAN as the first argument to the socket(2) system +call. Currently, there are two CAN protocols to choose from, the raw +socket protocol and the broadcast manager (BCM). So to open a socket, +you would write:: + + s = socket(PF_CAN, SOCK_RAW, CAN_RAW); + +and:: + + s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); + +respectively. After the successful creation of the socket, you would +normally use the bind(2) system call to bind the socket to a CAN +interface (which is different from TCP/IP due to different addressing +- see :ref:`socketcan-concept`). After binding (CAN_RAW) or connecting (CAN_BCM) +the socket, you can read(2) and write(2) from/to the socket or use +send(2), sendto(2), sendmsg(2) and the recv* counterpart operations +on the socket as usual. There are also CAN specific socket options +described below. + +The basic CAN frame structure and the sockaddr structure are defined +in include/linux/can.h: + +.. code-block:: C + + struct can_frame { + canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ + __u8 can_dlc; /* frame payload length in byte (0 .. 8) */ + __u8 __pad; /* padding */ + __u8 __res0; /* reserved / padding */ + __u8 __res1; /* reserved / padding */ + __u8 data[8] __attribute__((aligned(8))); + }; + +The alignment of the (linear) payload data[] to a 64bit boundary +allows the user to define their own structs and unions to easily access +the CAN payload. There is no given byteorder on the CAN bus by +default. A read(2) system call on a CAN_RAW socket transfers a +struct can_frame to the user space. + +The sockaddr_can structure has an interface index like the +PF_PACKET socket, that also binds to a specific interface: + +.. code-block:: C + + struct sockaddr_can { + sa_family_t can_family; + int can_ifindex; + union { + /* transport protocol class address info (e.g. ISOTP) */ + struct { canid_t rx_id, tx_id; } tp; + + /* reserved for future CAN protocols address information */ + } can_addr; + }; + +To determine the interface index an appropriate ioctl() has to +be used (example for CAN_RAW sockets without error checking): + +.. code-block:: C + + int s; + struct sockaddr_can addr; + struct ifreq ifr; + + s = socket(PF_CAN, SOCK_RAW, CAN_RAW); + + strcpy(ifr.ifr_name, "can0" ); + ioctl(s, SIOCGIFINDEX, &ifr); + + addr.can_family = AF_CAN; + addr.can_ifindex = ifr.ifr_ifindex; + + bind(s, (struct sockaddr *)&addr, sizeof(addr)); + + (..) + +To bind a socket to all(!) CAN interfaces the interface index must +be 0 (zero). In this case the socket receives CAN frames from every +enabled CAN interface. To determine the originating CAN interface +the system call recvfrom(2) may be used instead of read(2). To send +on a socket that is bound to 'any' interface sendto(2) is needed to +specify the outgoing interface. + +Reading CAN frames from a bound CAN_RAW socket (see above) consists +of reading a struct can_frame: + +.. code-block:: C + + struct can_frame frame; + + nbytes = read(s, &frame, sizeof(struct can_frame)); + + if (nbytes < 0) { + perror("can raw socket read"); + return 1; + } + + /* paranoid check ... */ + if (nbytes < sizeof(struct can_frame)) { + fprintf(stderr, "read: incomplete CAN frame\n"); + return 1; + } + + /* do something with the received CAN frame */ + +Writing CAN frames can be done similarly, with the write(2) system call:: + + nbytes = write(s, &frame, sizeof(struct can_frame)); + +When the CAN interface is bound to 'any' existing CAN interface +(addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the +information about the originating CAN interface is needed: + +.. code-block:: C + + struct sockaddr_can addr; + struct ifreq ifr; + socklen_t len = sizeof(addr); + struct can_frame frame; + + nbytes = recvfrom(s, &frame, sizeof(struct can_frame), + 0, (struct sockaddr*)&addr, &len); + + /* get interface name of the received CAN frame */ + ifr.ifr_ifindex = addr.can_ifindex; + ioctl(s, SIOCGIFNAME, &ifr); + printf("Received a CAN frame from interface %s", ifr.ifr_name); + +To write CAN frames on sockets bound to 'any' CAN interface the +outgoing interface has to be defined certainly: + +.. code-block:: C + + strcpy(ifr.ifr_name, "can0"); + ioctl(s, SIOCGIFINDEX, &ifr); + addr.can_ifindex = ifr.ifr_ifindex; + addr.can_family = AF_CAN; + + nbytes = sendto(s, &frame, sizeof(struct can_frame), + 0, (struct sockaddr*)&addr, sizeof(addr)); + +An accurate timestamp can be obtained with an ioctl(2) call after reading +a message from the socket: + +.. code-block:: C + + struct timeval tv; + ioctl(s, SIOCGSTAMP, &tv); + +The timestamp has a resolution of one microsecond and is set automatically +at the reception of a CAN frame. + +Remark about CAN FD (flexible data rate) support: + +Generally the handling of CAN FD is very similar to the formerly described +examples. The new CAN FD capable CAN controllers support two different +bitrates for the arbitration phase and the payload phase of the CAN FD frame +and up to 64 bytes of payload. This extended payload length breaks all the +kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight +bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. +the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that +switches the socket into a mode that allows the handling of CAN FD frames +and (legacy) CAN frames simultaneously (see :ref:`socketcan-rawfd`). + +The struct canfd_frame is defined in include/linux/can.h: + +.. code-block:: C + + struct canfd_frame { + canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ + __u8 len; /* frame payload length in byte (0 .. 64) */ + __u8 flags; /* additional flags for CAN FD */ + __u8 __res0; /* reserved / padding */ + __u8 __res1; /* reserved / padding */ + __u8 data[64] __attribute__((aligned(8))); + }; + +The struct canfd_frame and the existing struct can_frame have the can_id, +the payload length and the payload data at the same offset inside their +structures. This allows to handle the different structures very similar. +When the content of a struct can_frame is copied into a struct canfd_frame +all structure elements can be used as-is - only the data[] becomes extended. + +When introducing the struct canfd_frame it turned out that the data length +code (DLC) of the struct can_frame was used as a length information as the +length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve +the easy handling of the length information the canfd_frame.len element +contains a plain length value from 0 .. 64. So both canfd_frame.len and +can_frame.can_dlc are equal and contain a length information and no DLC. +For details about the distinction of CAN and CAN FD capable devices and +the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`. + +The length of the two CAN(FD) frame structures define the maximum transfer +unit (MTU) of the CAN(FD) network interface and skbuff data length. Two +definitions are specified for CAN specific MTUs in include/linux/can.h: + +.. code-block:: C + + #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame + #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame + + +.. _socketcan-raw-sockets: + +RAW Protocol Sockets with can_filters (SOCK_RAW) +------------------------------------------------ + +Using CAN_RAW sockets is extensively comparable to the commonly +known access to CAN character devices. To meet the new possibilities +provided by the multi user SocketCAN approach, some reasonable +defaults are set at RAW socket binding time: + +- The filters are set to exactly one filter receiving everything +- The socket only receives valid data frames (=> no error message frames) +- The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`) +- The socket does not receive its own sent frames (in loopback mode) + +These default settings may be changed before or after binding the socket. +To use the referenced definitions of the socket options for CAN_RAW +sockets, include . + + +.. _socketcan-rawfilter: + +RAW socket option CAN_RAW_FILTER +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reception of CAN frames using CAN_RAW sockets can be controlled +by defining 0 .. n filters with the CAN_RAW_FILTER socket option. + +The CAN filter structure is defined in include/linux/can.h: + +.. code-block:: C + + struct can_filter { + canid_t can_id; + canid_t can_mask; + }; + +A filter matches, when: + +.. code-block:: C + + & mask == can_id & mask + +which is analogous to known CAN controllers hardware filter semantics. +The filter can be inverted in this semantic, when the CAN_INV_FILTER +bit is set in can_id element of the can_filter structure. In +contrast to CAN controller hardware filters the user may set 0 .. n +receive filters for each open socket separately: + +.. code-block:: C + + struct can_filter rfilter[2]; + + rfilter[0].can_id = 0x123; + rfilter[0].can_mask = CAN_SFF_MASK; + rfilter[1].can_id = 0x200; + rfilter[1].can_mask = 0x700; + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); + +To disable the reception of CAN frames on the selected CAN_RAW socket: + +.. code-block:: C + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); + +To set the filters to zero filters is quite obsolete as to not read +data causes the raw socket to discard the received CAN frames. But +having this 'send only' use-case we may remove the receive list in the +Kernel to save a little (really a very little!) CPU usage. + +CAN Filter Usage Optimisation +............................. + +The CAN filters are processed in per-device filter lists at CAN frame +reception time. To reduce the number of checks that need to be performed +while walking through the filter lists the CAN core provides an optimized +filter handling when the filter subscription focusses on a single CAN ID. + +For the possible 2048 SFF CAN identifiers the identifier is used as an index +to access the corresponding subscription list without any further checks. +For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as +hash function to retrieve the EFF table index. + +To benefit from the optimized filters for single CAN identifiers the +CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together +with set CAN_EFF_FLAG and CAN_RTR_FLAG bits. A set CAN_EFF_FLAG bit in the +can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is +subscribed. E.g. in the example from above: + +.. code-block:: C + + rfilter[0].can_id = 0x123; + rfilter[0].can_mask = CAN_SFF_MASK; + +both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass. + +To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the +filter has to be defined in this way to benefit from the optimized filters: + +.. code-block:: C + + struct can_filter rfilter[2]; + + rfilter[0].can_id = 0x123; + rfilter[0].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_SFF_MASK); + rfilter[1].can_id = 0x12345678 | CAN_EFF_FLAG; + rfilter[1].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_EFF_MASK); + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); + + +RAW Socket Option CAN_RAW_ERR_FILTER +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generate so +called Error Message Frames that can optionally be passed to the user +application in the same way as other CAN frames. The possible +errors are divided into different error classes that may be filtered +using the appropriate error mask. To register for every possible +error condition CAN_ERR_MASK can be used as value for the error mask. +The values for the error mask are defined in linux/can/error.h: + +.. code-block:: C + + can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, + &err_mask, sizeof(err_mask)); + + +RAW Socket Option CAN_RAW_LOOPBACK +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To meet multi user needs the local loopback is enabled by default +(see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases +(e.g. when only one application uses the CAN bus) this loopback +functionality can be disabled (separately for each socket): + +.. code-block:: C + + int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); + + +RAW socket option CAN_RAW_RECV_OWN_MSGS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the local loopback is enabled, all the sent CAN frames are +looped back to the open CAN sockets that registered for the CAN +frames' CAN-ID on this given interface to meet the multi user +needs. The reception of the CAN frames on the same socket that was +sending the CAN frame is assumed to be unwanted and therefore +disabled by default. This default behaviour may be changed on +demand: + +.. code-block:: C + + int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ + + setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, + &recv_own_msgs, sizeof(recv_own_msgs)); + + +.. _socketcan-rawfd: + +RAW Socket Option CAN_RAW_FD_FRAMES +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CAN FD support in CAN_RAW sockets can be enabled with a new socket option +CAN_RAW_FD_FRAMES which is off by default. When the new socket option is +not supported by the CAN_RAW socket (e.g. on older kernels), switching the +CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT. + +Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames +and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames +when reading from the socket: + +.. code-block:: C + + CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed + CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default) + +Example: + +.. code-block:: C + + [ remember: CANFD_MTU == sizeof(struct canfd_frame) ] + + struct canfd_frame cfd; + + nbytes = read(s, &cfd, CANFD_MTU); + + if (nbytes == CANFD_MTU) { + printf("got CAN FD frame with length %d\n", cfd.len); + /* cfd.flags contains valid data */ + } else if (nbytes == CAN_MTU) { + printf("got legacy CAN frame with length %d\n", cfd.len); + /* cfd.flags is undefined */ + } else { + fprintf(stderr, "read: invalid CAN(FD) frame\n"); + return 1; + } + + /* the content can be handled independently from the received MTU size */ + + printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len); + for (i = 0; i < cfd.len; i++) + printf("%02X ", cfd.data[i]); + +When reading with size CANFD_MTU only returns CAN_MTU bytes that have +been received from the socket a legacy CAN frame has been read into the +provided CAN FD structure. Note that the canfd_frame.flags data field is +not specified in the struct can_frame and therefore it is only valid in +CANFD_MTU sized CAN FD frames. + +Implementation hint for new CAN applications: + +To build a CAN FD aware application use struct canfd_frame as basic CAN +data structure for CAN_RAW based applications. When the application is +executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES +socket option returns an error: No problem. You'll get legacy CAN frames +or CAN FD frames and can process them the same way. + +When sending to CAN devices make sure that the device is capable to handle +CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU. +The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. + + +RAW socket option CAN_RAW_JOIN_FILTERS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CAN_RAW socket can set multiple CAN identifier specific filters that +lead to multiple filters in the af_can.c filter processing. These filters +are indenpendent from each other which leads to logical OR'ed filters when +applied (see :ref:`socketcan-rawfilter`). + +This socket option joines the given CAN filters in the way that only CAN +frames are passed to user space that matched *all* given CAN filters. The +semantic for the applied filters is therefore changed to a logical AND. + +This is useful especially when the filterset is a combination of filters +where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or +CAN ID ranges from the incoming traffic. + + +RAW Socket Returned Message Flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using recvmsg() call, the msg->msg_flags may contain following flags: + +MSG_DONTROUTE: + set when the received frame was created on the local host. + +MSG_CONFIRM: + set when the frame was sent via the socket it is received on. + This flag can be interpreted as a 'transmission confirmation' when the + CAN driver supports the echo of frames on driver level, see + :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`. + In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. + + +Broadcast Manager Protocol Sockets (SOCK_DGRAM) +----------------------------------------------- + +The Broadcast Manager protocol provides a command based configuration +interface to filter and send (e.g. cyclic) CAN messages in kernel space. + +Receive filters can be used to down sample frequent messages; detect events +such as message contents changes, packet length changes, and do time-out +monitoring of received messages. + +Periodic transmission tasks of CAN frames or a sequence of CAN frames can be +created and modified at runtime; both the message content and the two +possible transmit intervals can be altered. + +A BCM socket is not intended for sending individual CAN frames using the +struct can_frame as known from the CAN_RAW socket. Instead a special BCM +configuration message is defined. The basic BCM configuration message used +to communicate with the broadcast manager and the available operations are +defined in the linux/can/bcm.h include. The BCM message consists of a +message header with a command ('opcode') followed by zero or more CAN frames. +The broadcast manager sends responses to user space in the same form: + +.. code-block:: C + + struct bcm_msg_head { + __u32 opcode; /* command */ + __u32 flags; /* special flags */ + __u32 count; /* run 'count' times with ival1 */ + struct timeval ival1, ival2; /* count and subsequent interval */ + canid_t can_id; /* unique can_id for task */ + __u32 nframes; /* number of can_frames following */ + struct can_frame frames[0]; + }; + +The aligned payload 'frames' uses the same basic CAN frame structure defined +at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All +messages to the broadcast manager from user space have this structure. + +Note a CAN_BCM socket must be connected instead of bound after socket +creation (example without error checking): + +.. code-block:: C + + int s; + struct sockaddr_can addr; + struct ifreq ifr; + + s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); + + strcpy(ifr.ifr_name, "can0"); + ioctl(s, SIOCGIFINDEX, &ifr); + + addr.can_family = AF_CAN; + addr.can_ifindex = ifr.ifr_ifindex; + + connect(s, (struct sockaddr *)&addr, sizeof(addr)); + + (..) + +The broadcast manager socket is able to handle any number of in flight +transmissions or receive filters concurrently. The different RX/TX jobs are +distinguished by the unique can_id in each BCM message. However additional +CAN_BCM sockets are recommended to communicate on multiple CAN interfaces. +When the broadcast manager socket is bound to 'any' CAN interface (=> the +interface index is set to zero) the configured receive filters apply to any +CAN interface unless the sendto() syscall is used to overrule the 'any' CAN +interface index. When using recvfrom() instead of read() to retrieve BCM +socket messages the originating CAN interface is provided in can_ifindex. + + +Broadcast Manager Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The opcode defines the operation for the broadcast manager to carry out, +or details the broadcast managers response to several events, including +user requests. + +Transmit Operations (user space to broadcast manager): + +TX_SETUP: + Create (cyclic) transmission task. + +TX_DELETE: + Remove (cyclic) transmission task, requires only can_id. + +TX_READ: + Read properties of (cyclic) transmission task for can_id. + +TX_SEND: + Send one CAN frame. + +Transmit Responses (broadcast manager to user space): + +TX_STATUS: + Reply to TX_READ request (transmission task configuration). + +TX_EXPIRED: + Notification when counter finishes sending at initial interval + 'ival1'. Requires the TX_COUNTEVT flag to be set at TX_SETUP. + +Receive Operations (user space to broadcast manager): + +RX_SETUP: + Create RX content filter subscription. + +RX_DELETE: + Remove RX content filter subscription, requires only can_id. + +RX_READ: + Read properties of RX content filter subscription for can_id. + +Receive Responses (broadcast manager to user space): + +RX_STATUS: + Reply to RX_READ request (filter task configuration). + +RX_TIMEOUT: + Cyclic message is detected to be absent (timer ival1 expired). + +RX_CHANGED: + BCM message with updated CAN frame (detected content change). + Sent on first message received or on receipt of revised CAN messages. + + +Broadcast Manager Message Flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When sending a message to the broadcast manager the 'flags' element may +contain the following flag definitions which influence the behaviour: + +SETTIMER: + Set the values of ival1, ival2 and count + +STARTTIMER: + Start the timer with the actual values of ival1, ival2 + and count. Starting the timer leads simultaneously to emit a CAN frame. + +TX_COUNTEVT: + Create the message TX_EXPIRED when count expires + +TX_ANNOUNCE: + A change of data by the process is emitted immediately. + +TX_CP_CAN_ID: + Copies the can_id from the message header to each + subsequent frame in frames. This is intended as usage simplification. For + TX tasks the unique can_id from the message header may differ from the + can_id(s) stored for transmission in the subsequent struct can_frame(s). + +RX_FILTER_ID: + Filter by can_id alone, no frames required (nframes=0). + +RX_CHECK_DLC: + A change of the DLC leads to an RX_CHANGED. + +RX_NO_AUTOTIMER: + Prevent automatically starting the timeout monitor. + +RX_ANNOUNCE_RESUME: + If passed at RX_SETUP and a receive timeout occurred, a + RX_CHANGED message will be generated when the (cyclic) receive restarts. + +TX_RESET_MULTI_IDX: + Reset the index for the multiple frame transmission. + +RX_RTR_FRAME: + Send reply for RTR-request (placed in op->frames[0]). + + +Broadcast Manager Transmission Timers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Periodic transmission configurations may use up to two interval timers. +In this case the BCM sends a number of messages ('count') at an interval +'ival1', then continuing to send at another given interval 'ival2'. When +only one timer is needed 'count' is set to zero and only 'ival2' is used. +When SET_TIMER and START_TIMER flag were set the timers are activated. +The timer values can be altered at runtime when only SET_TIMER is set. + + +Broadcast Manager message sequence transmission +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic +TX task configuration. The number of CAN frames is provided in the 'nframes' +element of the BCM message head. The defined number of CAN frames are added +as array to the TX_SETUP BCM configuration message: + +.. code-block:: C + + /* create a struct to set up a sequence of four CAN frames */ + struct { + struct bcm_msg_head msg_head; + struct can_frame frame[4]; + } mytxmsg; + + (..) + mytxmsg.msg_head.nframes = 4; + (..) + + write(s, &mytxmsg, sizeof(mytxmsg)); + +With every transmission the index in the array of CAN frames is increased +and set to zero at index overflow. + + +Broadcast Manager Receive Filter Timers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP. +When the SET_TIMER flag is set the timers are enabled: + +ival1: + Send RX_TIMEOUT when a received message is not received again within + the given time. When START_TIMER is set at RX_SETUP the timeout detection + is activated directly - even without a former CAN frame reception. + +ival2: + Throttle the received message rate down to the value of ival2. This + is useful to reduce messages for the application when the signal inside the + CAN frame is stateless as state changes within the ival2 periode may get + lost. + +Broadcast Manager Multiplex Message Receive Filter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To filter for content changes in multiplex message sequences an array of more +than one CAN frames can be passed in a RX_SETUP configuration message. The +data bytes of the first CAN frame contain the mask of relevant bits that +have to match in the subsequent CAN frames with the received CAN frame. +If one of the subsequent CAN frames is matching the bits in that frame data +mark the relevant content to be compared with the previous received content. +Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN +filters) can be added as array to the TX_SETUP BCM configuration message: + +.. code-block:: C + + /* usually used to clear CAN frame data[] - beware of endian problems! */ + #define U64_DATA(p) (*(unsigned long long*)(p)->data) + + struct { + struct bcm_msg_head msg_head; + struct can_frame frame[5]; + } msg; + + msg.msg_head.opcode = RX_SETUP; + msg.msg_head.can_id = 0x42; + msg.msg_head.flags = 0; + msg.msg_head.nframes = 5; + U64_DATA(&msg.frame[0]) = 0xFF00000000000000ULL; /* MUX mask */ + U64_DATA(&msg.frame[1]) = 0x01000000000000FFULL; /* data mask (MUX 0x01) */ + U64_DATA(&msg.frame[2]) = 0x0200FFFF000000FFULL; /* data mask (MUX 0x02) */ + U64_DATA(&msg.frame[3]) = 0x330000FFFFFF0003ULL; /* data mask (MUX 0x33) */ + U64_DATA(&msg.frame[4]) = 0x4F07FC0FF0000000ULL; /* data mask (MUX 0x4F) */ + + write(s, &msg, sizeof(msg)); + + +Broadcast Manager CAN FD Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The programming API of the CAN_BCM depends on struct can_frame which is +given as array directly behind the bcm_msg_head structure. To follow this +schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head +flags indicates that the concatenated CAN frame structures behind the +bcm_msg_head are defined as struct canfd_frame: + +.. code-block:: C + + struct { + struct bcm_msg_head msg_head; + struct canfd_frame frame[5]; + } msg; + + msg.msg_head.opcode = RX_SETUP; + msg.msg_head.can_id = 0x42; + msg.msg_head.flags = CAN_FD_FRAME; + msg.msg_head.nframes = 5; + (..) + +When using CAN FD frames for multiplex filtering the MUX mask is still +expected in the first 64 bit of the struct canfd_frame data section. + + +Connected Transport Protocols (SOCK_SEQPACKET) +---------------------------------------------- + +(to be written) + + +Unconnected Transport Protocols (SOCK_DGRAM) +-------------------------------------------- + +(to be written) + + +.. _socketcan-core-module: + +SocketCAN Core Module +===================== + +The SocketCAN core module implements the protocol family +PF_CAN. CAN protocol modules are loaded by the core module at +runtime. The core module provides an interface for CAN protocol +modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`). + + +can.ko Module Params +-------------------- + +- **stats_timer**: + To calculate the SocketCAN core statistics + (e.g. current/maximum frames per second) this 1 second timer is + invoked at can.ko module start time by default. This timer can be + disabled by using stattimer=0 on the module commandline. + +- **debug**: + (removed since SocketCAN SVN r546) + + +procfs content +-------------- + +As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter +lists to deliver received CAN frames to CAN protocol modules. These +receive lists, their filters and the count of filter matches can be +checked in the appropriate receive list. All entries contain the +device and a protocol module identifier:: + + foo@bar:~$ cat /proc/net/can/rcvlist_all + + receive list 'rx_all': + (vcan3: no entry) + (vcan2: no entry) + (vcan1: no entry) + device can_id can_mask function userdata matches ident + vcan0 000 00000000 f88e6370 f6c6f400 0 raw + (any: no entry) + +In this example an application requests any CAN traffic from vcan0:: + + rcvlist_all - list for unfiltered entries (no filter operations) + rcvlist_eff - list for single extended frame (EFF) entries + rcvlist_err - list for error message frames masks + rcvlist_fil - list for mask/value filters + rcvlist_inv - list for mask/value filters (inverse semantic) + rcvlist_sff - list for single standard frame (SFF) entries + +Additional procfs files in /proc/net/can:: + + stats - SocketCAN core statistics (rx/tx frames, match ratios, ...) + reset_stats - manual statistic reset + version - prints the SocketCAN core version and the ABI version + + +Writing Own CAN Protocol Modules +-------------------------------- + +To implement a new protocol in the protocol family PF_CAN a new +protocol has to be defined in include/linux/can.h . +The prototypes and definitions to use the SocketCAN core can be +accessed by including include/linux/can/core.h . +In addition to functions that register the CAN protocol and the +CAN device notifier chain there are functions to subscribe CAN +frames received by CAN interfaces and to send CAN frames:: + + can_rx_register - subscribe CAN frames from a specific interface + can_rx_unregister - unsubscribe CAN frames from a specific interface + can_send - transmit a CAN frame (optional with local loopback) + +For details see the kerneldoc documentation in net/can/af_can.c or +the source code of net/can/raw.c or net/can/bcm.c . + + +CAN Network Drivers +=================== + +Writing a CAN network device driver is much easier than writing a +CAN character device driver. Similar to other known network device +drivers you mainly have to deal with: + +- TX: Put the CAN frame from the socket buffer to the CAN controller. +- RX: Put the CAN frame from the CAN controller to the socket buffer. + +See e.g. at Documentation/networking/netdevices.txt . The differences +for writing CAN network device driver are described below: + + +General Settings +---------------- + +.. code-block:: C + + dev->type = ARPHRD_CAN; /* the netdevice hardware type */ + dev->flags = IFF_NOARP; /* CAN has no arp */ + + dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */ + + or alternative, when the controller supports CAN with flexible data rate: + dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ + +The struct can_frame or struct canfd_frame is the payload of each socket +buffer (skbuff) in the protocol family PF_CAN. + + +.. _socketcan-local-loopback2: + +Local Loopback of Sent Frames +----------------------------- + +As described in :ref:`socketcan-local-loopback1` the CAN network device driver should +support a local loopback functionality similar to the local echo +e.g. of tty devices. In this case the driver flag IFF_ECHO has to be +set to prevent the PF_CAN core from locally echoing sent frames +(aka loopback) as fallback solution:: + + dev->flags = (IFF_NOARP | IFF_ECHO); + + +CAN Controller Hardware Filters +------------------------------- + +To reduce the interrupt load on deep embedded systems some CAN +controllers support the filtering of CAN IDs or ranges of CAN IDs. +These hardware filter capabilities vary from controller to +controller and have to be identified as not feasible in a multi-user +networking approach. The use of the very controller specific +hardware filters could make sense in a very dedicated use-case, as a +filter on driver level would affect all users in the multi-user +system. The high efficient filter sets inside the PF_CAN core allow +to set different multiple filters for each socket separately. +Therefore the use of hardware filters goes to the category 'handmade +tuning on deep embedded systems'. The author is running a MPC603e +@133MHz with four SJA1000 CAN controllers from 2002 under heavy bus +load without any problems ... + + +The Virtual CAN Driver (vcan) +----------------------------- + +Similar to the network loopback devices, vcan offers a virtual local +CAN interface. A full qualified address on CAN consists of + +- a unique CAN Identifier (CAN ID) +- the CAN bus this CAN ID is transmitted on (e.g. can0) + +so in common use cases more than one virtual CAN interface is needed. + +The virtual CAN interfaces allow the transmission and reception of CAN +frames without real CAN controller hardware. Virtual CAN network +devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ... +When compiled as a module the virtual CAN driver module is called vcan.ko + +Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel +netlink interface to create vcan network devices. The creation and +removal of vcan network devices can be managed with the ip(8) tool:: + + - Create a virtual CAN network interface: + $ ip link add type vcan + + - Create a virtual CAN network interface with a specific name 'vcan42': + $ ip link add dev vcan42 type vcan + + - Remove a (virtual CAN) network interface 'vcan42': + $ ip link del vcan42 + + +The CAN Network Device Driver Interface +--------------------------------------- + +The CAN network device driver interface provides a generic interface +to setup, configure and monitor CAN network devices. The user can then +configure the CAN device, like setting the bit-timing parameters, via +the netlink interface using the program "ip" from the "IPROUTE2" +utility suite. The following chapter describes briefly how to use it. +Furthermore, the interface uses a common data structure and exports a +set of common functions, which all real CAN network device drivers +should use. Please have a look to the SJA1000 or MSCAN driver to +understand how to use them. The name of the module is can-dev.ko. + + +Netlink interface to set/get devices properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CAN device must be configured via netlink interface. The supported +netlink message types are defined and briefly described in +"include/linux/can/netlink.h". CAN link support for the program "ip" +of the IPROUTE2 utility suite is available and it can be used as shown +below: + +Setting CAN device properties:: + + $ 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 ] ] + + [ 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:: + + $ ip -details -statistics link show can0 + 2: can0: mtu 16 qdisc pfifo_fast state UP qlen 10 + link/can + can state ERROR-ACTIVE restart-ms 100 + bitrate 125000 sample_point 0.875 + tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 + sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 + clock 8000000 + re-started bus-errors arbit-lost error-warn error-pass bus-off + 41 17457 0 41 42 41 + RX: bytes packets errors dropped overrun mcast + 140859 17608 17457 0 0 0 + TX: bytes packets errors dropped carrier collsns + 861 112 0 41 0 0 + +More info to the above output: + +"" + Shows the list of selected CAN controller modes: LOOPBACK, + LISTEN-ONLY, or TRIPLE-SAMPLING. + +"state ERROR-ACTIVE" + The current state of the CAN controller: "ERROR-ACTIVE", + "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED" + +"restart-ms 100" + Automatic restart delay time. If set to a non-zero value, a + restart of the CAN controller will be triggered automatically + in case of a bus-off condition after the specified delay time + in milliseconds. By default it's off. + +"bitrate 125000 sample-point 0.875" + Shows the real bit-rate in bits/sec and the sample-point in the + range 0.000..0.999. If the calculation of bit-timing parameters + is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the + bit-timing can be defined by setting the "bitrate" argument. + Optionally the "sample-point" can be specified. By default it's + 0.000 assuming CIA-recommended sample-points. + +"tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1" + Shows the time quanta in ns, propagation segment, phase buffer + segment 1 and 2 and the synchronisation jump width in units of + tq. They allow to define the CAN bit-timing in a hardware + independent format as proposed by the Bosch CAN 2.0 spec (see + chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf). + +"sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000" + Shows the bit-timing constants of the CAN controller, here the + "sja1000". The minimum and maximum values of the time segment 1 + and 2, the synchronisation jump width in units of tq, the + bitrate pre-scaler and the CAN system clock frequency in Hz. + These constants could be used for user-defined (non-standard) + bit-timing calculation algorithms in user-space. + +"re-started bus-errors arbit-lost error-warn error-pass bus-off" + Shows the number of restarts, bus and arbitration lost errors, + and the state changes to the error-warning, error-passive and + bus-off state. RX overrun errors are listed in the "overrun" + field of the standard network statistics. + +Setting the CAN Bit-Timing +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CAN bit-timing parameters can always be defined in a hardware +independent format as proposed in the Bosch CAN 2.0 specification +specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2" +and "sjw":: + + $ ip link set canX type can tq 125 prop-seg 6 \ + phase-seg1 7 phase-seg2 2 sjw 1 + +If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA +recommended CAN bit-timing parameters will be calculated if the bit- +rate is specified with the argument "bitrate":: + + $ ip link set canX type can bitrate 125000 + +Note that this works fine for the most common CAN controllers with +standard bit-rates but may *fail* for exotic bit-rates or CAN system +clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some +space and allows user-space tools to solely determine and set the +bit-timing parameters. The CAN controller specific bit-timing +constants can be used for that purpose. They are listed by the +following command:: + + $ ip -details link show can0 + ... + sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 + + +Starting and Stopping the CAN Network Device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A CAN network device is started or stopped as usual with the command +"ifconfig canX up/down" or "ip link set canX up/down". Be aware that +you *must* define proper bit-timing parameters for real CAN devices +before you can start it to avoid error-prone default settings:: + + $ ip link set canX up type can bitrate 125000 + +A device may enter the "bus-off" state if too many errors occurred on +the CAN bus. Then no more messages are received or sent. An automatic +bus-off recovery can be enabled by setting the "restart-ms" to a +non-zero value, e.g.:: + + $ ip link set canX type can restart-ms 100 + +Alternatively, the application may realize the "bus-off" condition +by monitoring CAN error message frames and do a restart when +appropriate with the command:: + + $ ip link set canX type can restart + +Note that a restart will also create a CAN error message frame (see +also :ref:`socketcan-network-problem-notifications`). + + +.. _socketcan-can-fd-driver: + +CAN FD (Flexible Data Rate) Driver Support +------------------------------------------ + +CAN FD capable CAN controllers support two different bitrates for the +arbitration phase and the payload phase of the CAN FD frame. Therefore a +second bit timing has to be specified in order to enable the CAN FD bitrate. + +Additionally CAN FD capable CAN controllers support up to 64 bytes of +payload. The representation of this length in can_frame.can_dlc and +canfd_frame.len for userspace applications and inside the Linux network +layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. +The data length code was a 1:1 mapping to the payload length in the legacy +CAN frames anyway. The payload length to the bus-relevant DLC mapping is +only performed inside the CAN drivers, preferably with the helper +functions can_dlc2len() and can_len2dlc(). + +The CAN netdevice driver capabilities can be distinguished by the network +devices maximum transfer unit (MTU):: + + MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device + MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device + +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. + +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: mtu 72 qdisc pfifo_fast state UNKNOWN \ + mode DEFAULT group default qlen 10 + link/can promiscuity 0 + can 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 state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 + + +Supported CAN Hardware +---------------------- + +Please check the "Kconfig" file in "drivers/net/can" to get an actual +list of the support CAN hardware. On the SocketCAN project website +(see :ref:`socketcan-resources`) there might be further drivers available, also for +older kernel versions. + + +.. _socketcan-resources: + +SocketCAN Resources +=================== + +The Linux CAN / SocketCAN project resources (project site / mailing list) +are referenced in the MAINTAINERS file in the Linux source tree. +Search for CAN NETWORK [LAYERS|DRIVERS]. + +Credits +======= + +- Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver) +- Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) +- Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) +- Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver interface, MSCAN driver) +- Robert Schwebel (design reviews, PTXdist integration) +- Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) +- Benedikt Spranger (reviews) +- Thomas Gleixner (LKML reviews, coding style, posting hints) +- Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver) +- Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) +- Klaus Hitschler (PEAK driver integration) +- Uwe Koppe (CAN netdevices with PF_PACKET approach) +- Michael Schulze (driver layer loopback requirement, RT CAN drivers review) +- Pavel Pisa (Bit-timing calculation) +- Sascha Hauer (SJA1000 platform driver) +- Sebastian Haas (SJA1000 EMS PCI driver) +- Markus Plessing (SJA1000 EMS PCI driver) +- Per Dalen (SJA1000 Kvaser PCI driver) +- Sam Ravnborg (reviews, coding style, kbuild help) diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt deleted file mode 100644 index aa15b9ee2e70..000000000000 --- a/Documentation/networking/can.txt +++ /dev/null @@ -1,1308 +0,0 @@ -============================================================================ - -can.txt - -Readme file for the Controller Area Network Protocol Family (aka SocketCAN) - -This file contains - - 1 Overview / What is SocketCAN - - 2 Motivation / Why using the socket API - - 3 SocketCAN concept - 3.1 receive lists - 3.2 local loopback of sent frames - 3.3 network problem notifications - - 4 How to use SocketCAN - 4.1 RAW protocol sockets with can_filters (SOCK_RAW) - 4.1.1 RAW socket option CAN_RAW_FILTER - 4.1.2 RAW socket option CAN_RAW_ERR_FILTER - 4.1.3 RAW socket option CAN_RAW_LOOPBACK - 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS - 4.1.5 RAW socket option CAN_RAW_FD_FRAMES - 4.1.6 RAW socket option CAN_RAW_JOIN_FILTERS - 4.1.7 RAW socket returned message flags - 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) - 4.2.1 Broadcast Manager operations - 4.2.2 Broadcast Manager message flags - 4.2.3 Broadcast Manager transmission timers - 4.2.4 Broadcast Manager message sequence transmission - 4.2.5 Broadcast Manager receive filter timers - 4.2.6 Broadcast Manager multiplex message receive filter - 4.2.7 Broadcast Manager CAN FD support - 4.3 connected transport protocols (SOCK_SEQPACKET) - 4.4 unconnected transport protocols (SOCK_DGRAM) - - 5 SocketCAN core module - 5.1 can.ko module params - 5.2 procfs content - 5.3 writing own CAN protocol modules - - 6 CAN network drivers - 6.1 general settings - 6.2 local loopback of sent frames - 6.3 CAN controller hardware filters - 6.4 The virtual CAN driver (vcan) - 6.5 The CAN network device driver interface - 6.5.1 Netlink interface to set/get devices properties - 6.5.2 Setting the CAN bit-timing - 6.5.3 Starting and stopping the CAN network device - 6.6 CAN FD (flexible data rate) driver support - 6.7 supported CAN hardware - - 7 SocketCAN resources - - 8 Credits - -============================================================================ - -1. Overview / What is SocketCAN --------------------------------- - -The socketcan package is an implementation of CAN protocols -(Controller Area Network) for Linux. CAN is a networking technology -which has widespread use in automation, embedded devices, and -automotive fields. While there have been other CAN implementations -for Linux based on character devices, SocketCAN uses the Berkeley -socket API, the Linux network stack and implements the CAN device -drivers as network interfaces. The CAN socket API has been designed -as similar as possible to the TCP/IP protocols to allow programmers, -familiar with network programming, to easily learn how to use CAN -sockets. - -2. Motivation / Why using the socket API ----------------------------------------- - -There have been CAN implementations for Linux before SocketCAN so the -question arises, why we have started another project. Most existing -implementations come as a device driver for some CAN hardware, they -are based on character devices and provide comparatively little -functionality. Usually, there is only a hardware-specific device -driver which provides a character device interface to send and -receive raw CAN frames, directly to/from the controller hardware. -Queueing of frames and higher-level transport protocols like ISO-TP -have to be implemented in user space applications. Also, most -character-device implementations support only one single process to -open the device at a time, similar to a serial interface. Exchanging -the CAN controller requires employment of another device driver and -often the need for adaption of large parts of the application to the -new driver's API. - -SocketCAN was designed to overcome all of these limitations. A new -protocol family has been implemented which provides a socket interface -to user space applications and which builds upon the Linux network -layer, enabling use all of the provided queueing functionality. A device -driver for CAN controller hardware registers itself with the Linux -network layer as a network device, so that CAN frames from the -controller can be passed up to the network layer and on to the CAN -protocol family module and also vice-versa. Also, the protocol family -module provides an API for transport protocol modules to register, so -that any number of transport protocols can be loaded or unloaded -dynamically. In fact, the can core module alone does not provide any -protocol and cannot be used without loading at least one additional -protocol module. Multiple sockets can be opened at the same time, -on different or the same protocol module and they can listen/send -frames on different or the same CAN IDs. Several sockets listening on -the same interface for frames with the same CAN ID are all passed the -same received matching CAN frames. An application wishing to -communicate using a specific transport protocol, e.g. ISO-TP, just -selects that protocol when opening the socket, and then can read and -write application data byte streams, without having to deal with -CAN-IDs, frames, etc. - -Similar functionality visible from user-space could be provided by a -character device, too, but this would lead to a technically inelegant -solution for a couple of reasons: - -* Intricate usage. Instead of passing a protocol argument to - socket(2) and using bind(2) to select a CAN interface and CAN ID, an - application would have to do all these operations using ioctl(2)s. - -* Code duplication. A character device cannot make use of the Linux - network queueing code, so all that code would have to be duplicated - for CAN networking. - -* Abstraction. In most existing character-device implementations, the - hardware-specific device driver for a CAN controller directly - provides the character device for the application to work with. - This is at least very unusual in Unix systems for both, char and - block devices. For example you don't have a character device for a - certain UART of a serial interface, a certain sound chip in your - computer, a SCSI or IDE controller providing access to your hard - disk or tape streamer device. Instead, you have abstraction layers - which provide a unified character or block device interface to the - application on the one hand, and a interface for hardware-specific - device drivers on the other hand. These abstractions are provided - by subsystems like the tty layer, the audio subsystem or the SCSI - and IDE subsystems for the devices mentioned above. - - The easiest way to implement a CAN device driver is as a character - device without such a (complete) abstraction layer, as is done by most - existing drivers. The right way, however, would be to add such a - layer with all the functionality like registering for certain CAN - IDs, supporting several open file descriptors and (de)multiplexing - CAN frames between them, (sophisticated) queueing of CAN frames, and - providing an API for device drivers to register with. However, then - it would be no more difficult, or may be even easier, to use the - networking framework provided by the Linux kernel, and this is what - SocketCAN does. - - The use of the networking framework of the Linux kernel is just the - natural and most appropriate way to implement CAN for Linux. - -3. SocketCAN concept ---------------------- - - As described in chapter 2 it is the main goal of SocketCAN to - provide a socket interface to user space applications which builds - upon the Linux network layer. In contrast to the commonly known - TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) - medium that has no MAC-layer addressing like ethernet. The CAN-identifier - (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs - have to be chosen uniquely on the bus. When designing a CAN-ECU - network the CAN-IDs are mapped to be sent by a specific ECU. - For this reason a CAN-ID can be treated best as a kind of source address. - - 3.1 receive lists - - The network transparent access of multiple applications leads to the - problem that different applications may be interested in the same - CAN-IDs from the same CAN network interface. The SocketCAN core - module - which implements the protocol family CAN - provides several - high efficient receive lists for this reason. If e.g. a user space - application opens a CAN RAW socket, the raw protocol module itself - requests the (range of) CAN-IDs from the SocketCAN core that are - requested by the user. The subscription and unsubscription of - CAN-IDs can be done for specific CAN interfaces or for all(!) known - CAN interfaces with the can_rx_(un)register() functions provided to - CAN protocol modules by the SocketCAN core (see chapter 5). - To optimize the CPU usage at runtime the receive lists are split up - into several specific lists per device that match the requested - filter complexity for a given use-case. - - 3.2 local loopback of sent frames - - As known from other networking concepts the data exchanging - applications may run on the same or different nodes without any - change (except for the according addressing information): - - ___ ___ ___ _______ ___ - | _ | | _ | | _ | | _ _ | | _ | - ||A|| ||B|| ||C|| ||A| |B|| ||C|| - |___| |___| |___| |_______| |___| - | | | | | - -----------------(1)- CAN bus -(2)--------------- - - To ensure that application A receives the same information in the - example (2) as it would receive in example (1) there is need for - some kind of local loopback of the sent CAN frames on the appropriate - node. - - The Linux network devices (by default) just can handle the - transmission and reception of media dependent frames. Due to the - arbitration on the CAN bus the transmission of a low prio CAN-ID - may be delayed by the reception of a high prio CAN frame. To - reflect the correct* traffic on the node the loopback of the sent - data has to be performed right after a successful transmission. If - the CAN network interface is not capable of performing the loopback for - some reason the SocketCAN core can do this task as a fallback solution. - See chapter 6.2 for details (recommended). - - The loopback functionality is enabled by default to reflect standard - networking behaviour for CAN applications. Due to some requests from - the RT-SocketCAN group the loopback optionally may be disabled for each - separate socket. See sockopts from the CAN RAW sockets in chapter 4.1. - - * = you really like to have this when you're running analyser tools - like 'candump' or 'cansniffer' on the (same) node. - - 3.3 network problem notifications - - The use of the CAN bus may lead to several problems on the physical - and media access control layer. Detecting and logging of these lower - layer problems is a vital requirement for CAN users to identify - hardware issues on the physical transceiver layer as well as - arbitration problems and error frames caused by the different - ECUs. The occurrence of detected errors are important for diagnosis - and have to be logged together with the exact timestamp. For this - reason the CAN interface driver can generate so called Error Message - Frames that can optionally be passed to the user application in the - same way as other CAN frames. Whenever an error on the physical layer - or the MAC layer is detected (e.g. by the CAN controller) the driver - creates an appropriate error message frame. Error messages frames can - be requested by the user application using the common CAN filter - mechanisms. Inside this filter definition the (interested) type of - errors may be selected. The reception of error messages is disabled - by default. The format of the CAN error message frame is briefly - described in the Linux header file "include/uapi/linux/can/error.h". - -4. How to use SocketCAN ------------------------- - - Like TCP/IP, you first need to open a socket for communicating over a - CAN network. Since SocketCAN implements a new protocol family, you - need to pass PF_CAN as the first argument to the socket(2) system - call. Currently, there are two CAN protocols to choose from, the raw - socket protocol and the broadcast manager (BCM). So to open a socket, - you would write - - s = socket(PF_CAN, SOCK_RAW, CAN_RAW); - - and - - s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); - - respectively. After the successful creation of the socket, you would - normally use the bind(2) system call to bind the socket to a CAN - interface (which is different from TCP/IP due to different addressing - - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM) - the socket, you can read(2) and write(2) from/to the socket or use - send(2), sendto(2), sendmsg(2) and the recv* counterpart operations - on the socket as usual. There are also CAN specific socket options - described below. - - The basic CAN frame structure and the sockaddr structure are defined - in include/linux/can.h: - - struct can_frame { - canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ - __u8 can_dlc; /* frame payload length in byte (0 .. 8) */ - __u8 __pad; /* padding */ - __u8 __res0; /* reserved / padding */ - __u8 __res1; /* reserved / padding */ - __u8 data[8] __attribute__((aligned(8))); - }; - - The alignment of the (linear) payload data[] to a 64bit boundary - allows the user to define their own structs and unions to easily access - the CAN payload. There is no given byteorder on the CAN bus by - default. A read(2) system call on a CAN_RAW socket transfers a - struct can_frame to the user space. - - The sockaddr_can structure has an interface index like the - PF_PACKET socket, that also binds to a specific interface: - - struct sockaddr_can { - sa_family_t can_family; - int can_ifindex; - union { - /* transport protocol class address info (e.g. ISOTP) */ - struct { canid_t rx_id, tx_id; } tp; - - /* reserved for future CAN protocols address information */ - } can_addr; - }; - - To determine the interface index an appropriate ioctl() has to - be used (example for CAN_RAW sockets without error checking): - - int s; - struct sockaddr_can addr; - struct ifreq ifr; - - s = socket(PF_CAN, SOCK_RAW, CAN_RAW); - - strcpy(ifr.ifr_name, "can0" ); - ioctl(s, SIOCGIFINDEX, &ifr); - - addr.can_family = AF_CAN; - addr.can_ifindex = ifr.ifr_ifindex; - - bind(s, (struct sockaddr *)&addr, sizeof(addr)); - - (..) - - To bind a socket to all(!) CAN interfaces the interface index must - be 0 (zero). In this case the socket receives CAN frames from every - enabled CAN interface. To determine the originating CAN interface - the system call recvfrom(2) may be used instead of read(2). To send - on a socket that is bound to 'any' interface sendto(2) is needed to - specify the outgoing interface. - - Reading CAN frames from a bound CAN_RAW socket (see above) consists - of reading a struct can_frame: - - struct can_frame frame; - - nbytes = read(s, &frame, sizeof(struct can_frame)); - - if (nbytes < 0) { - perror("can raw socket read"); - return 1; - } - - /* paranoid check ... */ - if (nbytes < sizeof(struct can_frame)) { - fprintf(stderr, "read: incomplete CAN frame\n"); - return 1; - } - - /* do something with the received CAN frame */ - - Writing CAN frames can be done similarly, with the write(2) system call: - - nbytes = write(s, &frame, sizeof(struct can_frame)); - - When the CAN interface is bound to 'any' existing CAN interface - (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the - information about the originating CAN interface is needed: - - struct sockaddr_can addr; - struct ifreq ifr; - socklen_t len = sizeof(addr); - struct can_frame frame; - - nbytes = recvfrom(s, &frame, sizeof(struct can_frame), - 0, (struct sockaddr*)&addr, &len); - - /* get interface name of the received CAN frame */ - ifr.ifr_ifindex = addr.can_ifindex; - ioctl(s, SIOCGIFNAME, &ifr); - printf("Received a CAN frame from interface %s", ifr.ifr_name); - - To write CAN frames on sockets bound to 'any' CAN interface the - outgoing interface has to be defined certainly. - - strcpy(ifr.ifr_name, "can0"); - ioctl(s, SIOCGIFINDEX, &ifr); - addr.can_ifindex = ifr.ifr_ifindex; - addr.can_family = AF_CAN; - - nbytes = sendto(s, &frame, sizeof(struct can_frame), - 0, (struct sockaddr*)&addr, sizeof(addr)); - - An accurate timestamp can be obtained with an ioctl(2) call after reading - a message from the socket: - - struct timeval tv; - ioctl(s, SIOCGSTAMP, &tv); - - The timestamp has a resolution of one microsecond and is set automatically - at the reception of a CAN frame. - - Remark about CAN FD (flexible data rate) support: - - Generally the handling of CAN FD is very similar to the formerly described - examples. The new CAN FD capable CAN controllers support two different - bitrates for the arbitration phase and the payload phase of the CAN FD frame - and up to 64 bytes of payload. This extended payload length breaks all the - kernel interfaces (ABI) which heavily rely on the CAN frame with fixed eight - bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g. - the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that - switches the socket into a mode that allows the handling of CAN FD frames - and (legacy) CAN frames simultaneously (see section 4.1.5). - - The struct canfd_frame is defined in include/linux/can.h: - - struct canfd_frame { - canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ - __u8 len; /* frame payload length in byte (0 .. 64) */ - __u8 flags; /* additional flags for CAN FD */ - __u8 __res0; /* reserved / padding */ - __u8 __res1; /* reserved / padding */ - __u8 data[64] __attribute__((aligned(8))); - }; - - The struct canfd_frame and the existing struct can_frame have the can_id, - the payload length and the payload data at the same offset inside their - structures. This allows to handle the different structures very similar. - When the content of a struct can_frame is copied into a struct canfd_frame - all structure elements can be used as-is - only the data[] becomes extended. - - When introducing the struct canfd_frame it turned out that the data length - code (DLC) of the struct can_frame was used as a length information as the - length and the DLC has a 1:1 mapping in the range of 0 .. 8. To preserve - the easy handling of the length information the canfd_frame.len element - contains a plain length value from 0 .. 64. So both canfd_frame.len and - can_frame.can_dlc are equal and contain a length information and no DLC. - For details about the distinction of CAN and CAN FD capable devices and - the mapping to the bus-relevant data length code (DLC), see chapter 6.6. - - The length of the two CAN(FD) frame structures define the maximum transfer - unit (MTU) of the CAN(FD) network interface and skbuff data length. Two - definitions are specified for CAN specific MTUs in include/linux/can.h : - - #define CAN_MTU (sizeof(struct can_frame)) == 16 => 'legacy' CAN frame - #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame - - 4.1 RAW protocol sockets with can_filters (SOCK_RAW) - - Using CAN_RAW sockets is extensively comparable to the commonly - known access to CAN character devices. To meet the new possibilities - provided by the multi user SocketCAN approach, some reasonable - defaults are set at RAW socket binding time: - - - The filters are set to exactly one filter receiving everything - - The socket only receives valid data frames (=> no error message frames) - - The loopback of sent CAN frames is enabled (see chapter 3.2) - - The socket does not receive its own sent frames (in loopback mode) - - These default settings may be changed before or after binding the socket. - To use the referenced definitions of the socket options for CAN_RAW - sockets, include . - - 4.1.1 RAW socket option CAN_RAW_FILTER - - The reception of CAN frames using CAN_RAW sockets can be controlled - by defining 0 .. n filters with the CAN_RAW_FILTER socket option. - - The CAN filter structure is defined in include/linux/can.h: - - struct can_filter { - canid_t can_id; - canid_t can_mask; - }; - - A filter matches, when - - & mask == can_id & mask - - which is analogous to known CAN controllers hardware filter semantics. - The filter can be inverted in this semantic, when the CAN_INV_FILTER - bit is set in can_id element of the can_filter structure. In - contrast to CAN controller hardware filters the user may set 0 .. n - receive filters for each open socket separately: - - struct can_filter rfilter[2]; - - rfilter[0].can_id = 0x123; - rfilter[0].can_mask = CAN_SFF_MASK; - rfilter[1].can_id = 0x200; - rfilter[1].can_mask = 0x700; - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); - - To disable the reception of CAN frames on the selected CAN_RAW socket: - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); - - To set the filters to zero filters is quite obsolete as to not read - data causes the raw socket to discard the received CAN frames. But - having this 'send only' use-case we may remove the receive list in the - Kernel to save a little (really a very little!) CPU usage. - - 4.1.1.1 CAN filter usage optimisation - - The CAN filters are processed in per-device filter lists at CAN frame - reception time. To reduce the number of checks that need to be performed - while walking through the filter lists the CAN core provides an optimized - filter handling when the filter subscription focusses on a single CAN ID. - - For the possible 2048 SFF CAN identifiers the identifier is used as an index - to access the corresponding subscription list without any further checks. - For the 2^29 possible EFF CAN identifiers a 10 bit XOR folding is used as - hash function to retrieve the EFF table index. - - To benefit from the optimized filters for single CAN identifiers the - CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together - with set CAN_EFF_FLAG and CAN_RTR_FLAG bits. A set CAN_EFF_FLAG bit in the - can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is - subscribed. E.g. in the example from above - - rfilter[0].can_id = 0x123; - rfilter[0].can_mask = CAN_SFF_MASK; - - both SFF frames with CAN ID 0x123 and EFF frames with 0xXXXXX123 can pass. - - To filter for only 0x123 (SFF) and 0x12345678 (EFF) CAN identifiers the - filter has to be defined in this way to benefit from the optimized filters: - - struct can_filter rfilter[2]; - - rfilter[0].can_id = 0x123; - rfilter[0].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_SFF_MASK); - rfilter[1].can_id = 0x12345678 | CAN_EFF_FLAG; - rfilter[1].can_mask = (CAN_EFF_FLAG | CAN_RTR_FLAG | CAN_EFF_MASK); - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); - - 4.1.2 RAW socket option CAN_RAW_ERR_FILTER - - As described in chapter 3.3 the CAN interface driver can generate so - called Error Message Frames that can optionally be passed to the user - application in the same way as other CAN frames. The possible - errors are divided into different error classes that may be filtered - using the appropriate error mask. To register for every possible - error condition CAN_ERR_MASK can be used as value for the error mask. - The values for the error mask are defined in linux/can/error.h . - - can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, - &err_mask, sizeof(err_mask)); - - 4.1.3 RAW socket option CAN_RAW_LOOPBACK - - To meet multi user needs the local loopback is enabled by default - (see chapter 3.2 for details). But in some embedded use-cases - (e.g. when only one application uses the CAN bus) this loopback - functionality can be disabled (separately for each socket): - - int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); - - 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS - - When the local loopback is enabled, all the sent CAN frames are - looped back to the open CAN sockets that registered for the CAN - frames' CAN-ID on this given interface to meet the multi user - needs. The reception of the CAN frames on the same socket that was - sending the CAN frame is assumed to be unwanted and therefore - disabled by default. This default behaviour may be changed on - demand: - - int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ - - setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, - &recv_own_msgs, sizeof(recv_own_msgs)); - - 4.1.5 RAW socket option CAN_RAW_FD_FRAMES - - CAN FD support in CAN_RAW sockets can be enabled with a new socket option - CAN_RAW_FD_FRAMES which is off by default. When the new socket option is - not supported by the CAN_RAW socket (e.g. on older kernels), switching the - CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT. - - Once CAN_RAW_FD_FRAMES is enabled the application can send both CAN frames - and CAN FD frames. OTOH the application has to handle CAN and CAN FD frames - when reading from the socket. - - CAN_RAW_FD_FRAMES enabled: CAN_MTU and CANFD_MTU are allowed - CAN_RAW_FD_FRAMES disabled: only CAN_MTU is allowed (default) - - Example: - [ remember: CANFD_MTU == sizeof(struct canfd_frame) ] - - struct canfd_frame cfd; - - nbytes = read(s, &cfd, CANFD_MTU); - - if (nbytes == CANFD_MTU) { - printf("got CAN FD frame with length %d\n", cfd.len); - /* cfd.flags contains valid data */ - } else if (nbytes == CAN_MTU) { - printf("got legacy CAN frame with length %d\n", cfd.len); - /* cfd.flags is undefined */ - } else { - fprintf(stderr, "read: invalid CAN(FD) frame\n"); - return 1; - } - - /* the content can be handled independently from the received MTU size */ - - printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len); - for (i = 0; i < cfd.len; i++) - printf("%02X ", cfd.data[i]); - - When reading with size CANFD_MTU only returns CAN_MTU bytes that have - been received from the socket a legacy CAN frame has been read into the - provided CAN FD structure. Note that the canfd_frame.flags data field is - not specified in the struct can_frame and therefore it is only valid in - CANFD_MTU sized CAN FD frames. - - Implementation hint for new CAN applications: - - To build a CAN FD aware application use struct canfd_frame as basic CAN - data structure for CAN_RAW based applications. When the application is - executed on an older Linux kernel and switching the CAN_RAW_FD_FRAMES - socket option returns an error: No problem. You'll get legacy CAN frames - or CAN FD frames and can process them the same way. - - When sending to CAN devices make sure that the device is capable to handle - CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU. - The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. - - 4.1.6 RAW socket option CAN_RAW_JOIN_FILTERS - - The CAN_RAW socket can set multiple CAN identifier specific filters that - lead to multiple filters in the af_can.c filter processing. These filters - are indenpendent from each other which leads to logical OR'ed filters when - applied (see 4.1.1). - - This socket option joines the given CAN filters in the way that only CAN - frames are passed to user space that matched *all* given CAN filters. The - semantic for the applied filters is therefore changed to a logical AND. - - This is useful especially when the filterset is a combination of filters - where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or - CAN ID ranges from the incoming traffic. - - 4.1.7 RAW socket returned message flags - - When using recvmsg() call, the msg->msg_flags may contain following flags: - - MSG_DONTROUTE: set when the received frame was created on the local host. - - MSG_CONFIRM: set when the frame was sent via the socket it is received on. - This flag can be interpreted as a 'transmission confirmation' when the - CAN driver supports the echo of frames on driver level, see 3.2 and 6.2. - In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. - - 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) - - The Broadcast Manager protocol provides a command based configuration - interface to filter and send (e.g. cyclic) CAN messages in kernel space. - - Receive filters can be used to down sample frequent messages; detect events - such as message contents changes, packet length changes, and do time-out - monitoring of received messages. - - Periodic transmission tasks of CAN frames or a sequence of CAN frames can be - created and modified at runtime; both the message content and the two - possible transmit intervals can be altered. - - A BCM socket is not intended for sending individual CAN frames using the - struct can_frame as known from the CAN_RAW socket. Instead a special BCM - configuration message is defined. The basic BCM configuration message used - to communicate with the broadcast manager and the available operations are - defined in the linux/can/bcm.h include. The BCM message consists of a - message header with a command ('opcode') followed by zero or more CAN frames. - The broadcast manager sends responses to user space in the same form: - - struct bcm_msg_head { - __u32 opcode; /* command */ - __u32 flags; /* special flags */ - __u32 count; /* run 'count' times with ival1 */ - struct timeval ival1, ival2; /* count and subsequent interval */ - canid_t can_id; /* unique can_id for task */ - __u32 nframes; /* number of can_frames following */ - struct can_frame frames[0]; - }; - - The aligned payload 'frames' uses the same basic CAN frame structure defined - at the beginning of section 4 and in the include/linux/can.h include. All - messages to the broadcast manager from user space have this structure. - - Note a CAN_BCM socket must be connected instead of bound after socket - creation (example without error checking): - - int s; - struct sockaddr_can addr; - struct ifreq ifr; - - s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); - - strcpy(ifr.ifr_name, "can0"); - ioctl(s, SIOCGIFINDEX, &ifr); - - addr.can_family = AF_CAN; - addr.can_ifindex = ifr.ifr_ifindex; - - connect(s, (struct sockaddr *)&addr, sizeof(addr)); - - (..) - - The broadcast manager socket is able to handle any number of in flight - transmissions or receive filters concurrently. The different RX/TX jobs are - distinguished by the unique can_id in each BCM message. However additional - CAN_BCM sockets are recommended to communicate on multiple CAN interfaces. - When the broadcast manager socket is bound to 'any' CAN interface (=> the - interface index is set to zero) the configured receive filters apply to any - CAN interface unless the sendto() syscall is used to overrule the 'any' CAN - interface index. When using recvfrom() instead of read() to retrieve BCM - socket messages the originating CAN interface is provided in can_ifindex. - - 4.2.1 Broadcast Manager operations - - The opcode defines the operation for the broadcast manager to carry out, - or details the broadcast managers response to several events, including - user requests. - - Transmit Operations (user space to broadcast manager): - - TX_SETUP: Create (cyclic) transmission task. - - TX_DELETE: Remove (cyclic) transmission task, requires only can_id. - - TX_READ: Read properties of (cyclic) transmission task for can_id. - - TX_SEND: Send one CAN frame. - - Transmit Responses (broadcast manager to user space): - - TX_STATUS: Reply to TX_READ request (transmission task configuration). - - TX_EXPIRED: Notification when counter finishes sending at initial interval - 'ival1'. Requires the TX_COUNTEVT flag to be set at TX_SETUP. - - Receive Operations (user space to broadcast manager): - - RX_SETUP: Create RX content filter subscription. - - RX_DELETE: Remove RX content filter subscription, requires only can_id. - - RX_READ: Read properties of RX content filter subscription for can_id. - - Receive Responses (broadcast manager to user space): - - RX_STATUS: Reply to RX_READ request (filter task configuration). - - RX_TIMEOUT: Cyclic message is detected to be absent (timer ival1 expired). - - RX_CHANGED: BCM message with updated CAN frame (detected content change). - Sent on first message received or on receipt of revised CAN messages. - - 4.2.2 Broadcast Manager message flags - - When sending a message to the broadcast manager the 'flags' element may - contain the following flag definitions which influence the behaviour: - - SETTIMER: Set the values of ival1, ival2 and count - - STARTTIMER: Start the timer with the actual values of ival1, ival2 - and count. Starting the timer leads simultaneously to emit a CAN frame. - - TX_COUNTEVT: Create the message TX_EXPIRED when count expires - - TX_ANNOUNCE: A change of data by the process is emitted immediately. - - TX_CP_CAN_ID: Copies the can_id from the message header to each - subsequent frame in frames. This is intended as usage simplification. For - TX tasks the unique can_id from the message header may differ from the - can_id(s) stored for transmission in the subsequent struct can_frame(s). - - RX_FILTER_ID: Filter by can_id alone, no frames required (nframes=0). - - RX_CHECK_DLC: A change of the DLC leads to an RX_CHANGED. - - RX_NO_AUTOTIMER: Prevent automatically starting the timeout monitor. - - RX_ANNOUNCE_RESUME: If passed at RX_SETUP and a receive timeout occurred, a - RX_CHANGED message will be generated when the (cyclic) receive restarts. - - TX_RESET_MULTI_IDX: Reset the index for the multiple frame transmission. - - RX_RTR_FRAME: Send reply for RTR-request (placed in op->frames[0]). - - 4.2.3 Broadcast Manager transmission timers - - Periodic transmission configurations may use up to two interval timers. - In this case the BCM sends a number of messages ('count') at an interval - 'ival1', then continuing to send at another given interval 'ival2'. When - only one timer is needed 'count' is set to zero and only 'ival2' is used. - When SET_TIMER and START_TIMER flag were set the timers are activated. - The timer values can be altered at runtime when only SET_TIMER is set. - - 4.2.4 Broadcast Manager message sequence transmission - - Up to 256 CAN frames can be transmitted in a sequence in the case of a cyclic - TX task configuration. The number of CAN frames is provided in the 'nframes' - element of the BCM message head. The defined number of CAN frames are added - as array to the TX_SETUP BCM configuration message. - - /* create a struct to set up a sequence of four CAN frames */ - struct { - struct bcm_msg_head msg_head; - struct can_frame frame[4]; - } mytxmsg; - - (..) - mytxmsg.msg_head.nframes = 4; - (..) - - write(s, &mytxmsg, sizeof(mytxmsg)); - - With every transmission the index in the array of CAN frames is increased - and set to zero at index overflow. - - 4.2.5 Broadcast Manager receive filter timers - - The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP. - When the SET_TIMER flag is set the timers are enabled: - - ival1: Send RX_TIMEOUT when a received message is not received again within - the given time. When START_TIMER is set at RX_SETUP the timeout detection - is activated directly - even without a former CAN frame reception. - - ival2: Throttle the received message rate down to the value of ival2. This - is useful to reduce messages for the application when the signal inside the - CAN frame is stateless as state changes within the ival2 periode may get - lost. - - 4.2.6 Broadcast Manager multiplex message receive filter - - To filter for content changes in multiplex message sequences an array of more - than one CAN frames can be passed in a RX_SETUP configuration message. The - data bytes of the first CAN frame contain the mask of relevant bits that - have to match in the subsequent CAN frames with the received CAN frame. - If one of the subsequent CAN frames is matching the bits in that frame data - mark the relevant content to be compared with the previous received content. - Up to 257 CAN frames (multiplex filter bit mask CAN frame plus 256 CAN - filters) can be added as array to the TX_SETUP BCM configuration message. - - /* usually used to clear CAN frame data[] - beware of endian problems! */ - #define U64_DATA(p) (*(unsigned long long*)(p)->data) - - struct { - struct bcm_msg_head msg_head; - struct can_frame frame[5]; - } msg; - - msg.msg_head.opcode = RX_SETUP; - msg.msg_head.can_id = 0x42; - msg.msg_head.flags = 0; - msg.msg_head.nframes = 5; - U64_DATA(&msg.frame[0]) = 0xFF00000000000000ULL; /* MUX mask */ - U64_DATA(&msg.frame[1]) = 0x01000000000000FFULL; /* data mask (MUX 0x01) */ - U64_DATA(&msg.frame[2]) = 0x0200FFFF000000FFULL; /* data mask (MUX 0x02) */ - U64_DATA(&msg.frame[3]) = 0x330000FFFFFF0003ULL; /* data mask (MUX 0x33) */ - U64_DATA(&msg.frame[4]) = 0x4F07FC0FF0000000ULL; /* data mask (MUX 0x4F) */ - - write(s, &msg, sizeof(msg)); - - 4.2.7 Broadcast Manager CAN FD support - - The programming API of the CAN_BCM depends on struct can_frame which is - given as array directly behind the bcm_msg_head structure. To follow this - schema for the CAN FD frames a new flag 'CAN_FD_FRAME' in the bcm_msg_head - flags indicates that the concatenated CAN frame structures behind the - bcm_msg_head are defined as struct canfd_frame. - - struct { - struct bcm_msg_head msg_head; - struct canfd_frame frame[5]; - } msg; - - msg.msg_head.opcode = RX_SETUP; - msg.msg_head.can_id = 0x42; - msg.msg_head.flags = CAN_FD_FRAME; - msg.msg_head.nframes = 5; - (..) - - When using CAN FD frames for multiplex filtering the MUX mask is still - expected in the first 64 bit of the struct canfd_frame data section. - - 4.3 connected transport protocols (SOCK_SEQPACKET) - 4.4 unconnected transport protocols (SOCK_DGRAM) - - -5. SocketCAN core module -------------------------- - - The SocketCAN core module implements the protocol family - PF_CAN. CAN protocol modules are loaded by the core module at - runtime. The core module provides an interface for CAN protocol - modules to subscribe needed CAN IDs (see chapter 3.1). - - 5.1 can.ko module params - - - stats_timer: To calculate the SocketCAN core statistics - (e.g. current/maximum frames per second) this 1 second timer is - invoked at can.ko module start time by default. This timer can be - disabled by using stattimer=0 on the module commandline. - - - debug: (removed since SocketCAN SVN r546) - - 5.2 procfs content - - As described in chapter 3.1 the SocketCAN core uses several filter - lists to deliver received CAN frames to CAN protocol modules. These - receive lists, their filters and the count of filter matches can be - checked in the appropriate receive list. All entries contain the - device and a protocol module identifier: - - foo@bar:~$ cat /proc/net/can/rcvlist_all - - receive list 'rx_all': - (vcan3: no entry) - (vcan2: no entry) - (vcan1: no entry) - device can_id can_mask function userdata matches ident - vcan0 000 00000000 f88e6370 f6c6f400 0 raw - (any: no entry) - - In this example an application requests any CAN traffic from vcan0. - - rcvlist_all - list for unfiltered entries (no filter operations) - rcvlist_eff - list for single extended frame (EFF) entries - rcvlist_err - list for error message frames masks - rcvlist_fil - list for mask/value filters - rcvlist_inv - list for mask/value filters (inverse semantic) - rcvlist_sff - list for single standard frame (SFF) entries - - Additional procfs files in /proc/net/can - - stats - SocketCAN core statistics (rx/tx frames, match ratios, ...) - reset_stats - manual statistic reset - version - prints the SocketCAN core version and the ABI version - - 5.3 writing own CAN protocol modules - - To implement a new protocol in the protocol family PF_CAN a new - protocol has to be defined in include/linux/can.h . - The prototypes and definitions to use the SocketCAN core can be - accessed by including include/linux/can/core.h . - In addition to functions that register the CAN protocol and the - CAN device notifier chain there are functions to subscribe CAN - frames received by CAN interfaces and to send CAN frames: - - can_rx_register - subscribe CAN frames from a specific interface - can_rx_unregister - unsubscribe CAN frames from a specific interface - can_send - transmit a CAN frame (optional with local loopback) - - For details see the kerneldoc documentation in net/can/af_can.c or - the source code of net/can/raw.c or net/can/bcm.c . - -6. CAN network drivers ----------------------- - - Writing a CAN network device driver is much easier than writing a - CAN character device driver. Similar to other known network device - drivers you mainly have to deal with: - - - TX: Put the CAN frame from the socket buffer to the CAN controller. - - RX: Put the CAN frame from the CAN controller to the socket buffer. - - See e.g. at Documentation/networking/netdevices.txt . The differences - for writing CAN network device driver are described below: - - 6.1 general settings - - dev->type = ARPHRD_CAN; /* the netdevice hardware type */ - dev->flags = IFF_NOARP; /* CAN has no arp */ - - dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */ - - or alternative, when the controller supports CAN with flexible data rate: - dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */ - - The struct can_frame or struct canfd_frame is the payload of each socket - buffer (skbuff) in the protocol family PF_CAN. - - 6.2 local loopback of sent frames - - As described in chapter 3.2 the CAN network device driver should - support a local loopback functionality similar to the local echo - e.g. of tty devices. In this case the driver flag IFF_ECHO has to be - set to prevent the PF_CAN core from locally echoing sent frames - (aka loopback) as fallback solution: - - dev->flags = (IFF_NOARP | IFF_ECHO); - - 6.3 CAN controller hardware filters - - To reduce the interrupt load on deep embedded systems some CAN - controllers support the filtering of CAN IDs or ranges of CAN IDs. - These hardware filter capabilities vary from controller to - controller and have to be identified as not feasible in a multi-user - networking approach. The use of the very controller specific - hardware filters could make sense in a very dedicated use-case, as a - filter on driver level would affect all users in the multi-user - system. The high efficient filter sets inside the PF_CAN core allow - to set different multiple filters for each socket separately. - Therefore the use of hardware filters goes to the category 'handmade - tuning on deep embedded systems'. The author is running a MPC603e - @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus - load without any problems ... - - 6.4 The virtual CAN driver (vcan) - - Similar to the network loopback devices, vcan offers a virtual local - CAN interface. A full qualified address on CAN consists of - - - a unique CAN Identifier (CAN ID) - - the CAN bus this CAN ID is transmitted on (e.g. can0) - - so in common use cases more than one virtual CAN interface is needed. - - The virtual CAN interfaces allow the transmission and reception of CAN - frames without real CAN controller hardware. Virtual CAN network - devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ... - When compiled as a module the virtual CAN driver module is called vcan.ko - - Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel - netlink interface to create vcan network devices. The creation and - removal of vcan network devices can be managed with the ip(8) tool: - - - Create a virtual CAN network interface: - $ ip link add type vcan - - - Create a virtual CAN network interface with a specific name 'vcan42': - $ ip link add dev vcan42 type vcan - - - Remove a (virtual CAN) network interface 'vcan42': - $ ip link del vcan42 - - 6.5 The CAN network device driver interface - - The CAN network device driver interface provides a generic interface - to setup, configure and monitor CAN network devices. The user can then - configure the CAN device, like setting the bit-timing parameters, via - the netlink interface using the program "ip" from the "IPROUTE2" - utility suite. The following chapter describes briefly how to use it. - Furthermore, the interface uses a common data structure and exports a - set of common functions, which all real CAN network device drivers - should use. Please have a look to the SJA1000 or MSCAN driver to - understand how to use them. The name of the module is can-dev.ko. - - 6.5.1 Netlink interface to set/get devices properties - - The CAN device must be configured via netlink interface. The supported - netlink message types are defined and briefly described in - "include/linux/can/netlink.h". CAN link support for the program "ip" - of the IPROUTE2 utility suite is available and it can be used as shown - below: - - - Setting CAN device properties: - - $ 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 ] ] - - [ 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: - - $ ip -details -statistics link show can0 - 2: can0: mtu 16 qdisc pfifo_fast state UP qlen 10 - link/can - can state ERROR-ACTIVE restart-ms 100 - bitrate 125000 sample_point 0.875 - tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 - sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - clock 8000000 - re-started bus-errors arbit-lost error-warn error-pass bus-off - 41 17457 0 41 42 41 - RX: bytes packets errors dropped overrun mcast - 140859 17608 17457 0 0 0 - TX: bytes packets errors dropped carrier collsns - 861 112 0 41 0 0 - - More info to the above output: - - "" - Shows the list of selected CAN controller modes: LOOPBACK, - LISTEN-ONLY, or TRIPLE-SAMPLING. - - "state ERROR-ACTIVE" - The current state of the CAN controller: "ERROR-ACTIVE", - "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED" - - "restart-ms 100" - Automatic restart delay time. If set to a non-zero value, a - restart of the CAN controller will be triggered automatically - in case of a bus-off condition after the specified delay time - in milliseconds. By default it's off. - - "bitrate 125000 sample-point 0.875" - Shows the real bit-rate in bits/sec and the sample-point in the - range 0.000..0.999. If the calculation of bit-timing parameters - is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the - bit-timing can be defined by setting the "bitrate" argument. - Optionally the "sample-point" can be specified. By default it's - 0.000 assuming CIA-recommended sample-points. - - "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1" - Shows the time quanta in ns, propagation segment, phase buffer - segment 1 and 2 and the synchronisation jump width in units of - tq. They allow to define the CAN bit-timing in a hardware - independent format as proposed by the Bosch CAN 2.0 spec (see - chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf). - - "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - clock 8000000" - Shows the bit-timing constants of the CAN controller, here the - "sja1000". The minimum and maximum values of the time segment 1 - and 2, the synchronisation jump width in units of tq, the - bitrate pre-scaler and the CAN system clock frequency in Hz. - These constants could be used for user-defined (non-standard) - bit-timing calculation algorithms in user-space. - - "re-started bus-errors arbit-lost error-warn error-pass bus-off" - Shows the number of restarts, bus and arbitration lost errors, - and the state changes to the error-warning, error-passive and - bus-off state. RX overrun errors are listed in the "overrun" - field of the standard network statistics. - - 6.5.2 Setting the CAN bit-timing - - The CAN bit-timing parameters can always be defined in a hardware - independent format as proposed in the Bosch CAN 2.0 specification - specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2" - and "sjw": - - $ ip link set canX type can tq 125 prop-seg 6 \ - phase-seg1 7 phase-seg2 2 sjw 1 - - If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA - recommended CAN bit-timing parameters will be calculated if the bit- - rate is specified with the argument "bitrate": - - $ ip link set canX type can bitrate 125000 - - Note that this works fine for the most common CAN controllers with - standard bit-rates but may *fail* for exotic bit-rates or CAN system - clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some - space and allows user-space tools to solely determine and set the - bit-timing parameters. The CAN controller specific bit-timing - constants can be used for that purpose. They are listed by the - following command: - - $ ip -details link show can0 - ... - sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - - 6.5.3 Starting and stopping the CAN network device - - A CAN network device is started or stopped as usual with the command - "ifconfig canX up/down" or "ip link set canX up/down". Be aware that - you *must* define proper bit-timing parameters for real CAN devices - before you can start it to avoid error-prone default settings: - - $ ip link set canX up type can bitrate 125000 - - A device may enter the "bus-off" state if too many errors occurred on - the CAN bus. Then no more messages are received or sent. An automatic - bus-off recovery can be enabled by setting the "restart-ms" to a - non-zero value, e.g.: - - $ ip link set canX type can restart-ms 100 - - Alternatively, the application may realize the "bus-off" condition - by monitoring CAN error message frames and do a restart when - appropriate with the command: - - $ ip link set canX type can restart - - Note that a restart will also create a CAN error message frame (see - also chapter 3.3). - - 6.6 CAN FD (flexible data rate) driver support - - CAN FD capable CAN controllers support two different bitrates for the - arbitration phase and the payload phase of the CAN FD frame. Therefore a - second bit timing has to be specified in order to enable the CAN FD bitrate. - - Additionally CAN FD capable CAN controllers support up to 64 bytes of - payload. The representation of this length in can_frame.can_dlc and - canfd_frame.len for userspace applications and inside the Linux network - layer is a plain value from 0 .. 64 instead of the CAN 'data length code'. - The data length code was a 1:1 mapping to the payload length in the legacy - CAN frames anyway. The payload length to the bus-relevant DLC mapping is - only performed inside the CAN drivers, preferably with the helper - functions can_dlc2len() and can_len2dlc(). - - The CAN netdevice driver capabilities can be distinguished by the network - devices maximum transfer unit (MTU): - - MTU = 16 (CAN_MTU) => sizeof(struct can_frame) => 'legacy' CAN device - MTU = 72 (CANFD_MTU) => sizeof(struct canfd_frame) => CAN FD capable device - - 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. - - 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: mtu 72 qdisc pfifo_fast state UNKNOWN \ - mode DEFAULT group default qlen 10 - link/can promiscuity 0 - can 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 state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 - - 6.7 Supported CAN hardware - - Please check the "Kconfig" file in "drivers/net/can" to get an actual - list of the support CAN hardware. On the SocketCAN project website - (see chapter 7) there might be further drivers available, also for - older kernel versions. - -7. SocketCAN resources ------------------------ - - The Linux CAN / SocketCAN project resources (project site / mailing list) - are referenced in the MAINTAINERS file in the Linux source tree. - Search for CAN NETWORK [LAYERS|DRIVERS]. - -8. Credits ----------- - - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver) - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan) - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation) - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, - CAN device driver interface, MSCAN driver) - Robert Schwebel (design reviews, PTXdist integration) - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers) - Benedikt Spranger (reviews) - Thomas Gleixner (LKML reviews, coding style, posting hints) - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver) - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003) - Klaus Hitschler (PEAK driver integration) - Uwe Koppe (CAN netdevices with PF_PACKET approach) - Michael Schulze (driver layer loopback requirement, RT CAN drivers review) - Pavel Pisa (Bit-timing calculation) - Sascha Hauer (SJA1000 platform driver) - Sebastian Haas (SJA1000 EMS PCI driver) - Markus Plessing (SJA1000 EMS PCI driver) - Per Dalen (SJA1000 Kvaser PCI driver) - Sam Ravnborg (reviews, coding style, kbuild help) diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 7d4b15977d61..90966c2692d8 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -7,6 +7,7 @@ Contents: :maxdepth: 2 batman-adv + can kapi z8530book msg_zerocopy -- cgit From 216bf2f490c214b8a0702b52cc957138ba24bc3f Mon Sep 17 00:00:00 2001 From: Fabrizio Castro Date: Tue, 7 Nov 2017 15:10:42 +0000 Subject: dt-bindings: can: rcar_can: document r8a774[35] can support Document "renesas,can-r8a7743" and "renesas,can-r8a7745" compatible strings. Since the fallback compatible string ("renesas,rcar-gen2-can") activates the right code in the driver, no driver change is needed. Signed-off-by: Fabrizio Castro Reviewed-by: Biju Das Signed-off-by: Marc Kleine-Budde --- Documentation/devicetree/bindings/net/can/rcar_can.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 06bb7cc334c8..94a7f33ac5e9 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -2,7 +2,9 @@ Renesas R-Car CAN controller Device Tree Bindings ------------------------------------------------- Required properties: -- compatible: "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. +- compatible: "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC. + "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. + "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. "renesas,can-r8a7779" if CAN controller is a part of R8A7779 SoC. "renesas,can-r8a7790" if CAN controller is a part of R8A7790 SoC. "renesas,can-r8a7791" if CAN controller is a part of R8A7791 SoC. @@ -12,7 +14,8 @@ Required properties: "renesas,can-r8a7795" if CAN controller is a part of R8A7795 SoC. "renesas,can-r8a7796" if CAN controller is a part of R8A7796 SoC. "renesas,rcar-gen1-can" for a generic R-Car Gen1 compatible device. - "renesas,rcar-gen2-can" for a generic R-Car Gen2 compatible device. + "renesas,rcar-gen2-can" for a generic R-Car Gen2 or RZ/G1 + compatible device. "renesas,rcar-gen3-can" for a generic R-Car Gen3 compatible device. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first -- cgit From 1534156e999735fe0befad958e1447600c0c20e7 Mon Sep 17 00:00:00 2001 From: Gregory CLEMENT Date: Tue, 16 Jan 2018 17:35:39 +0100 Subject: i2c: mv64xxx: Fix clock resource by adding an optional bus clock On Armada 7K/8K we need to explicitly enable the bus clock. The bus clock is optional because not all the SoCs need them but at least for Armada 7K/8K it is actually mandatory. The binding documentation is updating accordingly. Signed-off-by: Gregory CLEMENT Signed-off-by: Wolfram Sang --- .../devicetree/bindings/i2c/i2c-mv64xxx.txt | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt index 5c30026921ae..0ffe65a316ae 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt @@ -25,6 +25,15 @@ default frequency is 100kHz whenever you're using the "allwinner,sun6i-a31-i2c" compatible. + - clocks: : pointers to the reference clocks for this device, the + first one is the one used for the clock on the i2c bus, + the second one is the clock used to acces the registers + of the controller + + - clock-names : names of used clocks, mandatory if the second clock is + used, the name must be "core", and "reg" (the latter is + only for Armada 7K/8K). + Examples: i2c@11000 { @@ -42,3 +51,14 @@ For the Armada XP: interrupts = <29>; clock-frequency = <100000>; }; + +For the Armada 7040: + + i2c@701000 { + compatible = "marvell,mv78230-i2c"; + reg = <0x701000 0x20>; + interrupts = <29>; + clock-frequency = <100000>; + clock-names = "core", "reg"; + clocks = <&core_clock>, <®_clock>; + }; -- cgit From 5b0d0033f3f3a3d09178ef0dcdd0d4e1a08666b8 Mon Sep 17 00:00:00 2001 From: Simon Shields Date: Mon, 22 Jan 2018 17:45:09 -0800 Subject: Input: mms114 - drop platform data and use generic APIs The MMS114 platform data has no in-tree users, so drop it. Switch to using the standard touchscreen properties via touchscreen_parse_properties(), and move the old DT parsing code to use device_property_*() APIs. Finally, use touchscreen_report_pos to report x/y coordinates and drop the custom x/y inversion code. Signed-off-by: Simon Shields Reviewed-by: Rob Herring Reviewed-by: Andi Shyti Tested-by: Andi Shyti Signed-off-by: Dmitry Torokhov --- .../bindings/input/touchscreen/mms114.txt | 29 +++++++++++++--------- 1 file changed, 17 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt index 89d4c56c5671..8f9f9f38eff4 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt @@ -4,14 +4,18 @@ Required properties: - compatible: must be "melfas,mms114" - reg: I2C address of the chip - interrupts: interrupt to which the chip is connected -- x-size: horizontal resolution of touchscreen -- y-size: vertical resolution of touchscreen +- touchscreen-size-x: See [1] +- touchscreen-size-y: See [1] Optional properties: -- contact-threshold: -- moving-threshold: -- x-invert: invert X axis -- y-invert: invert Y axis +- touchscreen-fuzz-x: See [1] +- touchscreen-fuzz-y: See [1] +- touchscreen-fuzz-pressure: See [1] +- touchscreen-inverted-x: See [1] +- touchscreen-inverted-y: See [1] +- touchscreen-swapped-x-y: See [1] + +[1]: Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt Example: @@ -22,12 +26,13 @@ Example: compatible = "melfas,mms114"; reg = <0x48>; interrupts = <39 0>; - x-size = <720>; - y-size = <1280>; - contact-threshold = <10>; - moving-threshold = <10>; - x-invert; - y-invert; + touchscreen-size-x = <720>; + touchscreen-size-y = <1280>; + touchscreen-fuzz-x = <10>; + touchscreen-fuzz-y = <10>; + touchscreen-fuzz-pressure = <10>; + touchscreen-inverted-x; + touchscreen-inverted-y; }; /* ... */ -- cgit From 72b0c0cf9720cd139829610cfcd9ac294451a9f8 Mon Sep 17 00:00:00 2001 From: Simon Shields Date: Tue, 23 Jan 2018 12:02:39 -0800 Subject: Input: mms114 - add support for mms152 MMS152 has no configuration registers, but the packet format used in interrupts is identical to mms114. Signed-off-by: Simon Shields Reviewed-by: Andi Shyti Tested-by: Andi Shyti Signed-off-by: Dmitry Torokhov --- Documentation/devicetree/bindings/input/touchscreen/mms114.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt index 8f9f9f38eff4..2cd954051d29 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/mms114.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/mms114.txt @@ -1,7 +1,9 @@ -* MELFAS MMS114 touchscreen controller +* MELFAS MMS114/MMS152 touchscreen controller Required properties: -- compatible: must be "melfas,mms114" +- compatible: should be one of: + - "melfas,mms114" + - "melfas,mms152" - reg: I2C address of the chip - interrupts: interrupt to which the chip is connected - touchscreen-size-x: See [1] -- cgit From 00b96c0e3c54a1fff9e8b909f46a672e43ef9598 Mon Sep 17 00:00:00 2001 From: Frederic Barrat Date: Tue, 23 Jan 2018 12:31:47 +0100 Subject: ocxl: Documentation ocxl.rst gives a quick, high-level view of opencapi. Update ioctl-number.txt to reflect ioctl numbers being used by the ocxl driver Signed-off-by: Frederic Barrat [mpe: Fix up mixed whitespace as spotted by gregkh] Signed-off-by: Michael Ellerman --- Documentation/ABI/testing/sysfs-class-ocxl | 35 +++++++ Documentation/accelerators/ocxl.rst | 160 +++++++++++++++++++++++++++++ Documentation/ioctl/ioctl-number.txt | 1 + 3 files changed, 196 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-ocxl create mode 100644 Documentation/accelerators/ocxl.rst (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl new file mode 100644 index 000000000000..b5b1fa197592 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-ocxl @@ -0,0 +1,35 @@ +What: /sys/class/ocxl//afu_version +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Version of the AFU, in the format : + Reflects what is read in the configuration space of the AFU + +What: /sys/class/ocxl//contexts +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Number of contexts for the AFU, in the format / + where: + n: number of currently active contexts, for debug + max: maximum number of contexts supported by the AFU + +What: /sys/class/ocxl//pp_mmio_size +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Size of the per-process mmio area, as defined in the + configuration space of the AFU + +What: /sys/class/ocxl//global_mmio_size +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Size of the global mmio area, as defined in the + configuration space of the AFU + +What: /sys/class/ocxl//global_mmio_area +Date: January 2018 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Give access the global mmio area for the AFU diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/accelerators/ocxl.rst new file mode 100644 index 000000000000..4f7af841d935 --- /dev/null +++ b/Documentation/accelerators/ocxl.rst @@ -0,0 +1,160 @@ +======================================================== +OpenCAPI (Open Coherent Accelerator Processor Interface) +======================================================== + +OpenCAPI is an interface between processors and accelerators. It aims +at being low-latency and high-bandwidth. The specification is +developed by the `OpenCAPI Consortium `_. + +It allows an accelerator (which could be a FPGA, ASICs, ...) to access +the host memory coherently, using virtual addresses. An OpenCAPI +device can also host its own memory, that can be accessed from the +host. + +OpenCAPI is known in linux as 'ocxl', as the open, processor-agnostic +evolution of 'cxl' (the driver for the IBM CAPI interface for +powerpc), which was named that way to avoid confusion with the ISDN +CAPI subsystem. + + +High-level view +=============== + +OpenCAPI defines a Data Link Layer (DL) and Transaction Layer (TL), to +be implemented on top of a physical link. Any processor or device +implementing the DL and TL can start sharing memory. + +:: + + +-----------+ +-------------+ + | | | | + | | | Accelerated | + | Processor | | Function | + | | +--------+ | Unit | +--------+ + | |--| Memory | | (AFU) |--| Memory | + | | +--------+ | | +--------+ + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | TL | | TLX | + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | DL | | DLX | + +-----------+ +-------------+ + | | + | PHY | + +---------------------------------------+ + + + +Device discovery +================ + +OpenCAPI relies on a PCI-like configuration space, implemented on the +device. So the host can discover AFUs by querying the config space. + +OpenCAPI devices in Linux are treated like PCI devices (with a few +caveats). The firmware is expected to abstract the hardware as if it +was a PCI link. A lot of the existing PCI infrastructure is reused: +devices are scanned and BARs are assigned during the standard PCI +enumeration. Commands like 'lspci' can therefore be used to see what +devices are available. + +The configuration space defines the AFU(s) that can be found on the +physical adapter, such as its name, how many memory contexts it can +work with, the size of its MMIO areas, ... + + + +MMIO +==== + +OpenCAPI defines two MMIO areas for each AFU: + +* the global MMIO area, with registers pertinent to the whole AFU. +* a per-process MMIO area, which has a fixed size for each context. + + + +AFU interrupts +============== + +OpenCAPI includes the possibility for an AFU to send an interrupt to a +host process. It is done through a 'intrp_req' defined in the +Transaction Layer, specifying a 64-bit object handle which defines the +interrupt. + +The driver allows a process to allocate an interrupt and obtain its +64-bit object handle, that can be passed to the AFU. + + + +char devices +============ + +The driver creates one char device per AFU found on the physical +device. A physical device may have multiple functions and each +function can have multiple AFUs. At the time of this writing though, +it has only been tested with devices exporting only one AFU. + +Char devices can be found in /dev/ocxl/ and are named as: +/dev/ocxl/.. + +where is a max 20-character long name, as found in the +config space of the AFU. + is added by the driver and can help distinguish devices +when a system has more than one instance of the same OpenCAPI device. + is also to help distinguish AFUs in the unlikely case where a +device carries multiple copies of the same AFU. + + + +Sysfs class +=========== + +An ocxl class is added for the devices representing the AFUs. See +/sys/class/ocxl. The layout is described in +Documentation/ABI/testing/sysfs-class-ocxl + + + +User API +======== + +open +---- + +Based on the AFU definition found in the config space, an AFU may +support working with more than one memory context, in which case the +associated char device may be opened multiple times by different +processes. + + +ioctl +----- + +OCXL_IOCTL_ATTACH: + + Attach the memory context of the calling process to the AFU so that + the AFU can access its memory. + +OCXL_IOCTL_IRQ_ALLOC: + + Allocate an AFU interrupt and return an identifier. + +OCXL_IOCTL_IRQ_FREE: + + Free a previously allocated AFU interrupt. + +OCXL_IOCTL_IRQ_SET_FD: + + Associate an event fd to an AFU interrupt so that the user process + can be notified when the AFU sends an interrupt. + + +mmap +---- + +A process can mmap the per-process MMIO area for interactions with the +AFU. diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 3e3fdae5f3ed..6501389d55b9 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -326,6 +326,7 @@ Code Seq#(hex) Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h +0xCA 10-2F uapi/misc/ocxl.h 0xCA 80-BF uapi/scsi/cxlflash_ioctl.h 0xCB 00-1F CBM serial IEC bus in development: -- cgit From cedd55d49dee941d0e4fabb2f2f555d50c53fad7 Mon Sep 17 00:00:00 2001 From: Marc Herbert Date: Fri, 26 Jan 2018 14:59:00 -0800 Subject: kconfig: Remove silentoldconfig from help and docs; fix kconfig/conf's help As explained by Michal Marek at https://lkml.org/lkml/2011/8/31/189 silentoldconfig has become a misnomer. It has become an internal interface so remove it from "make help" and Documentation/ to stop confusing people using it as seen for instance at https://chromium-review.googlesource.com/835632 Don't remove it from kconfig/Makefile yet not to break any (other) tool using it. On the other hand, correct and expand its description in the help of the (internal) scripts/kconfig/conf.c Signed-off-by: Marc Herbert Signed-off-by: Masahiro Yamada --- Documentation/admin-guide/README.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 63066db39910..af5a437198d0 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -170,11 +170,6 @@ Configuring the kernel your existing ./.config file and asking about new config symbols. - "make silentoldconfig" - Like above, but avoids cluttering the screen - with questions already answered. - Additionally updates the dependencies. - "make olddefconfig" Like above, but sets new symbols to their default values without prompting. -- cgit From 1d65b1c886be6111f2347bd1a548bec58da17ccf Mon Sep 17 00:00:00 2001 From: Michael Ellerman Date: Fri, 3 Nov 2017 10:56:32 +1100 Subject: powerpc/cell: Remove axonram driver The QS21/22 IBM Cell blades had a southbridge chip called Axon. This could have DDR DIMMs attached to it, though they were not directly usable as RAM, instead they could be used as some sort of buffer, if applications were written specifically to use the block device provided by the driver. Although the driver supposedly had direct access support, it was apparently never tested (see commit 91117a20245b ("axonram: Fix bug in direct_access")). These machines have not been available for over 5 years, and were never widely in use. It seems highly unlikely anyone is using this driver. In general we're happy to leave old drivers in the tree, but because DAX is involved this driver is caught up in the ongoing work in that area, but none of the DAX folks are able to test it. So remove the driver, if any one *is* using it, we'll be happy to put it back. Signed-off-by: Michael Ellerman --- Documentation/filesystems/dax.txt | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt index 3be3b266be41..70cb68bed2e8 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -46,7 +46,6 @@ stall the CPU for an extended period, you should also not attempt to implement direct_access. These block devices may be used for inspiration: -- axonram: Axon DDR2 device driver - brd: RAM backed block device driver - dcssblk: s390 dcss block device driver - pmem: NVDIMM persistent memory driver -- cgit From 03eac8b22194becd77d253fc546429ebb544aebf Mon Sep 17 00:00:00 2001 From: Florian Schmidt Date: Tue, 30 Jan 2018 17:42:13 +0100 Subject: Documentation: Fix 'file_mapped' -> 'mapped_file' There is no entry file_mapped in the memory.stat file. This looks like a simple word flip that's gone unnoticed since 2010 (dc10e281f5fc, memcg: update documentation). Signed-off-by: Florian Schmidt Acked-by: Michal Hocko Signed-off-by: Tejun Heo --- Documentation/cgroup-v1/memory.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cgroup-v1/memory.txt b/Documentation/cgroup-v1/memory.txt index cefb63639070..a4af2e124e24 100644 --- a/Documentation/cgroup-v1/memory.txt +++ b/Documentation/cgroup-v1/memory.txt @@ -524,9 +524,9 @@ Note: Only anonymous and swap cache memory is listed as part of 'rss' stat. This should not be confused with the true 'resident set size' or the amount of physical memory used by the cgroup. - 'rss + file_mapped" will give you resident set size of cgroup. + 'rss + mapped_file" will give you resident set size of cgroup. (Note: file and shmem may be shared among other cgroups. In that case, - file_mapped is accounted only when the memory cgroup is owner of page + mapped_file is accounted only when the memory cgroup is owner of page cache.) 5.3 swappiness -- cgit From f84a56f73dddaeac1dba8045b007f742f61cd2da Mon Sep 17 00:00:00 2001 From: Mark Rutland Date: Mon, 29 Jan 2018 17:02:16 -0800 Subject: Documentation: Document array_index_nospec Document the rationale and usage of the new array_index_nospec() helper. Signed-off-by: Mark Rutland Signed-off-by: Will Deacon Signed-off-by: Dan Williams Signed-off-by: Thomas Gleixner Reviewed-by: Kees Cook Cc: linux-arch@vger.kernel.org Cc: Jonathan Corbet Cc: Peter Zijlstra Cc: gregkh@linuxfoundation.org Cc: kernel-hardening@lists.openwall.com Cc: torvalds@linux-foundation.org Cc: alan@linux.intel.com Link: https://lkml.kernel.org/r/151727413645.33451.15878817161436755393.stgit@dwillia2-desk3.amr.corp.intel.com --- Documentation/speculation.txt | 90 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 Documentation/speculation.txt (limited to 'Documentation') diff --git a/Documentation/speculation.txt b/Documentation/speculation.txt new file mode 100644 index 000000000000..e9e6cbae2841 --- /dev/null +++ b/Documentation/speculation.txt @@ -0,0 +1,90 @@ +This document explains potential effects of speculation, and how undesirable +effects can be mitigated portably using common APIs. + +=========== +Speculation +=========== + +To improve performance and minimize average latencies, many contemporary CPUs +employ speculative execution techniques such as branch prediction, performing +work which may be discarded at a later stage. + +Typically speculative execution cannot be observed from architectural state, +such as the contents of registers. However, in some cases it is possible to +observe its impact on microarchitectural state, such as the presence or +absence of data in caches. Such state may form side-channels which can be +observed to extract secret information. + +For example, in the presence of branch prediction, it is possible for bounds +checks to be ignored by code which is speculatively executed. Consider the +following code: + + int load_array(int *array, unsigned int index) + { + if (index >= MAX_ARRAY_ELEMS) + return 0; + else + return array[index]; + } + +Which, on arm64, may be compiled to an assembly sequence such as: + + CMP , #MAX_ARRAY_ELEMS + B.LT less + MOV , #0 + RET + less: + LDR , [, ] + RET + +It is possible that a CPU mis-predicts the conditional branch, and +speculatively loads array[index], even if index >= MAX_ARRAY_ELEMS. This +value will subsequently be discarded, but the speculated load may affect +microarchitectural state which can be subsequently measured. + +More complex sequences involving multiple dependent memory accesses may +result in sensitive information being leaked. Consider the following +code, building on the prior example: + + int load_dependent_arrays(int *arr1, int *arr2, int index) + { + int val1, val2, + + val1 = load_array(arr1, index); + val2 = load_array(arr2, val1); + + return val2; + } + +Under speculation, the first call to load_array() may return the value +of an out-of-bounds address, while the second call will influence +microarchitectural state dependent on this value. This may provide an +arbitrary read primitive. + +==================================== +Mitigating speculation side-channels +==================================== + +The kernel provides a generic API to ensure that bounds checks are +respected even under speculation. Architectures which are affected by +speculation-based side-channels are expected to implement these +primitives. + +The array_index_nospec() helper in can be used to +prevent information from being leaked via side-channels. + +A call to array_index_nospec(index, size) returns a sanitized index +value that is bounded to [0, size) even under cpu speculation +conditions. + +This can be used to protect the earlier load_array() example: + + int load_array(int *array, unsigned int index) + { + if (index >= MAX_ARRAY_ELEMS) + return 0; + else { + index = array_index_nospec(index, MAX_ARRAY_ELEMS); + return array[index]; + } + } -- cgit From 9614e2ba9161c7f5419f4212fa6057d2a65f6ae6 Mon Sep 17 00:00:00 2001 From: John Pittman Date: Tue, 30 Jan 2018 16:39:00 -0500 Subject: dm cache: Documentation: update default migration_throttling value In commit f8350daf7af0 ("dm cache: tune migration throttling") the value for DEFAULT_MIGRATION_THRESHOLD was decreased from 204800 to 2048. Edit device-mapper/cache.txt to reflect the correct default value for migration_threshold. Signed-off-by: John Pittman Signed-off-by: Mike Snitzer --- Documentation/device-mapper/cache.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/device-mapper/cache.txt b/Documentation/device-mapper/cache.txt index 79c7b6dc88ae..ff0841711fd5 100644 --- a/Documentation/device-mapper/cache.txt +++ b/Documentation/device-mapper/cache.txt @@ -119,7 +119,7 @@ doing here to avoid migrating during those peak io moments. For the time being, a message "migration_threshold <#sectors>" can be used to set the maximum number of sectors being migrated, -the default being 204800 sectors (100MB). +the default being 2048 sectors (1MB). Updating on-disk metadata ------------------------- -- cgit From 12c69f1e94c89d40696e83804dd2f0965b5250cd Mon Sep 17 00:00:00 2001 From: Josh Poimboeuf Date: Tue, 30 Jan 2018 22:13:33 -0600 Subject: x86/paravirt: Remove 'noreplace-paravirt' cmdline option The 'noreplace-paravirt' option disables paravirt patching, leaving the original pv indirect calls in place. That's highly incompatible with retpolines, unless we want to uglify paravirt even further and convert the paravirt calls to retpolines. As far as I can tell, the option doesn't seem to be useful for much other than introducing surprising corner cases and making the kernel vulnerable to Spectre v2. It was probably a debug option from the early paravirt days. So just remove it. Signed-off-by: Josh Poimboeuf Signed-off-by: Thomas Gleixner Reviewed-by: Juergen Gross Cc: Andrea Arcangeli Cc: Peter Zijlstra Cc: Andi Kleen Cc: Ashok Raj Cc: Greg KH Cc: Jun Nakajima Cc: Tim Chen Cc: Rusty Russell Cc: Dave Hansen Cc: Asit Mallick Cc: Andy Lutomirski Cc: Linus Torvalds Cc: Jason Baron Cc: Paolo Bonzini Cc: Alok Kataria Cc: Arjan Van De Ven Cc: David Woodhouse Cc: Dan Williams Link: https://lkml.kernel.org/r/20180131041333.2x6blhxirc2kclrq@treble --- Documentation/admin-guide/kernel-parameters.txt | 2 -- 1 file changed, 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 46b26bfee27b..1e762c210f1b 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -2742,8 +2742,6 @@ norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space - noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops - noreplace-smp [X86-32,SMP] Don't replace SMP instructions with UP alternatives -- cgit From 2040fae4b22f419ed5cbc40ce8ec4d0fbc798a64 Mon Sep 17 00:00:00 2001 From: Scott Telford Date: Tue, 30 Jan 2018 21:56:54 +0100 Subject: dt-bindings: PCI: cadence: Add DT bindings for Cadence PCIe host controller This patch adds documentation for the DT bindings of the Cadence PCIe controller when configured in host (Root Complex) mode. Signed-off-by: Scott Telford Signed-off-by: Cyrille Pitchen Signed-off-by: Lorenzo Pieralisi Reviewed-by: Rob Herring --- .../bindings/pci/cdns,cdns-pcie-host.txt | 60 ++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt new file mode 100644 index 000000000000..20a33f38f69d --- /dev/null +++ b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-host.txt @@ -0,0 +1,60 @@ +* Cadence PCIe host controller + +This PCIe controller inherits the base properties defined in +host-generic-pci.txt. + +Required properties: +- compatible: Should contain "cdns,cdns-pcie-host" to identify the IP used. +- reg: Should contain the controller register base address, PCIe configuration + window base address, and AXI interface region base address respectively. +- reg-names: Must be "reg", "cfg" and "mem" respectively. +- #address-cells: Set to <3> +- #size-cells: Set to <2> +- device_type: Set to "pci" +- ranges: Ranges for the PCI memory and I/O regions +- #interrupt-cells: Set to <1> +- interrupt-map-mask and interrupt-map: Standard PCI properties to define the + mapping of the PCIe interface to interrupt numbers. + +Optional properties: +- cdns,max-outbound-regions: Set to maximum number of outbound regions + (default 32) +- cdns,no-bar-match-nbits: Set into the no BAR match register to configure the + number of least significant bits kept during inbound (PCIe -> AXI) address + translations (default 32) +- vendor-id: The PCI vendor ID (16 bits, default is design dependent) +- device-id: The PCI device ID (16 bits, default is design dependent) + +Example: + +pcie@fb000000 { + compatible = "cdns,cdns-pcie-host"; + device_type = "pci"; + #address-cells = <3>; + #size-cells = <2>; + bus-range = <0x0 0xff>; + linux,pci-domain = <0>; + cdns,max-outbound-regions = <16>; + cdns,no-bar-match-nbits = <32>; + vendor-id = /bits/ 16 <0x17cd>; + device-id = /bits/ 16 <0x0200>; + + reg = <0x0 0xfb000000 0x0 0x01000000>, + <0x0 0x41000000 0x0 0x00001000>, + <0x0 0x40000000 0x0 0x04000000>; + reg-names = "reg", "cfg", "mem"; + + ranges = <0x02000000 0x0 0x42000000 0x0 0x42000000 0x0 0x1000000>, + <0x01000000 0x0 0x43000000 0x0 0x43000000 0x0 0x0010000>; + + #interrupt-cells = <0x1>; + + interrupt-map = <0x0 0x0 0x0 0x1 &gic 0x0 0x0 0x0 14 0x1 + 0x0 0x0 0x0 0x2 &gic 0x0 0x0 0x0 15 0x1 + 0x0 0x0 0x0 0x3 &gic 0x0 0x0 0x0 16 0x1 + 0x0 0x0 0x0 0x4 &gic 0x0 0x0 0x0 17 0x1>; + + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + + msi-parent = <&its_pci>; +}; -- cgit From 6618f4d3f5d614d5cd4cbc4e81f0fef8e22a36c7 Mon Sep 17 00:00:00 2001 From: Cyrille Pitchen Date: Tue, 30 Jan 2018 21:56:58 +0100 Subject: dt-bindings: PCI: cadence: Add DT bindings for Cadence PCIe endpoint controller This patch documents the DT bindings for the Cadence PCIe controller when configured in endpoint mode. Signed-off-by: Cyrille Pitchen Signed-off-by: Lorenzo Pieralisi Reviewed-by: Rob Herring --- .../devicetree/bindings/pci/cdns,cdns-pcie-ep.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt new file mode 100644 index 000000000000..9a305237fa6e --- /dev/null +++ b/Documentation/devicetree/bindings/pci/cdns,cdns-pcie-ep.txt @@ -0,0 +1,22 @@ +* Cadence PCIe endpoint controller + +Required properties: +- compatible: Should contain "cdns,cdns-pcie-ep" to identify the IP used. +- reg: Should contain the controller register base address and AXI interface + region base address respectively. +- reg-names: Must be "reg" and "mem" respectively. +- cdns,max-outbound-regions: Set to maximum number of outbound regions + +Optional properties: +- max-functions: Maximum number of functions that can be configured (default 1). + +Example: + +pcie@fc000000 { + compatible = "cdns,cdns-pcie-ep"; + reg = <0x0 0xfc000000 0x0 0x01000000>, + <0x0 0x80000000 0x0 0x40000000>; + reg-names = "reg", "mem"; + cdns,max-outbound-regions = <16>; + max-functions = /bits/ 8 <8>; +}; -- cgit From fcb2b0c577f145c7616843c9d4dcb4f9e5d88e29 Mon Sep 17 00:00:00 2001 From: Roman Gushchin Date: Wed, 31 Jan 2018 16:16:22 -0800 Subject: mm: show total hugetlb memory consumption in /proc/meminfo Currently we display some hugepage statistics (total, free, etc) in /proc/meminfo, but only for default hugepage size (e.g. 2Mb). If hugepages of different sizes are used (like 2Mb and 1Gb on x86-64), /proc/meminfo output can be confusing, as non-default sized hugepages are not reflected at all, and there are no signs that they are existing and consuming system memory. To solve this problem, let's display the total amount of memory, consumed by hugetlb pages of all sized (both free and used). Let's call it "Hugetlb", and display size in kB to match generic /proc/meminfo style. For example, (1024 2Mb pages and 2 1Gb pages are pre-allocated): $ cat /proc/meminfo MemTotal: 8168984 kB MemFree: 3789276 kB <...> CmaFree: 0 kB HugePages_Total: 1024 HugePages_Free: 1024 HugePages_Rsvd: 0 HugePages_Surp: 0 Hugepagesize: 2048 kB Hugetlb: 4194304 kB DirectMap4k: 32632 kB DirectMap2M: 4161536 kB DirectMap1G: 6291456 kB Also, this patch updates corresponding docs to reflect Hugetlb entry meaning and difference between Hugetlb and HugePages_Total * Hugepagesize. Link: http://lkml.kernel.org/r/20171115231409.12131-1-guro@fb.com Signed-off-by: Roman Gushchin Acked-by: Michal Hocko Acked-by: Johannes Weiner Acked-by: David Rientjes Cc: Mike Kravetz Cc: "Aneesh Kumar K.V" Cc: Andrea Arcangeli Cc: Dave Hansen Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/vm/hugetlbpage.txt | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index 59cbc803aad6..faf077d50d42 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -20,19 +20,20 @@ options. The /proc/meminfo file provides information about the total number of persistent hugetlb pages in the kernel's huge page pool. It also displays -information about the number of free, reserved and surplus huge pages and the -default huge page size. The huge page size is needed for generating the -proper alignment and size of the arguments to system calls that map huge page -regions. +default huge page size and information about the number of free, reserved +and surplus huge pages in the pool of huge pages of default size. +The huge page size is needed for generating the proper alignment and +size of the arguments to system calls that map huge page regions. The output of "cat /proc/meminfo" will include lines like: ..... -HugePages_Total: vvv -HugePages_Free: www -HugePages_Rsvd: xxx -HugePages_Surp: yyy -Hugepagesize: zzz kB +HugePages_Total: uuu +HugePages_Free: vvv +HugePages_Rsvd: www +HugePages_Surp: xxx +Hugepagesize: yyy kB +Hugetlb: zzz kB where: HugePages_Total is the size of the pool of huge pages. @@ -47,6 +48,14 @@ HugePages_Surp is short for "surplus," and is the number of huge pages in the pool above the value in /proc/sys/vm/nr_hugepages. The maximum number of surplus huge pages is controlled by /proc/sys/vm/nr_overcommit_hugepages. +Hugepagesize is the default hugepage size (in Kb). +Hugetlb is the total amount of memory (in kB), consumed by huge + pages of all sizes. + If huge pages of different sizes are in use, this number + will exceed HugePages_Total * Hugepagesize. To get more + detailed information, please, refer to + /sys/kernel/mm/hugepages (described below). + /proc/filesystems should also show a filesystem of type "hugetlbfs" configured in the kernel. -- cgit From d6cb41cc44c63492702281b1d329955ca767d399 Mon Sep 17 00:00:00 2001 From: Michal Hocko Date: Wed, 31 Jan 2018 16:17:10 -0800 Subject: mm, hugetlb: remove hugepages_treat_as_movable sysctl hugepages_treat_as_movable has been introduced by 396faf0303d2 ("Allow huge page allocations to use GFP_HIGH_MOVABLE") to allow hugetlb allocations from ZONE_MOVABLE even when hugetlb pages were not migrateable. The purpose of the movable zone was different at the time. It aimed at reducing memory fragmentation and hugetlb pages being long lived and large werre not contributing to the fragmentation so it was acceptable to use the zone back then. Things have changed though and the primary purpose of the zone became migratability guarantee. If we allow non migrateable hugetlb pages to be in ZONE_MOVABLE memory hotplug might fail to offline the memory. Remove the knob and only rely on hugepage_migration_supported to allow movable zones. Mel said: : Primarily it was aimed at allowing the hugetlb pool to safely shrink with : the ability to grow it again. The use case was for batched jobs, some of : which needed huge pages and others that did not but didn't want the memory : useless pinned in the huge pages pool. : : I suspect that more users rely on THP than hugetlbfs for flexible use of : huge pages with fallback options so I think that removing the option : should be ok. Link: http://lkml.kernel.org/r/20171003072619.8654-1-mhocko@kernel.org Signed-off-by: Michal Hocko Reported-by: Alexandru Moise <00moses.alexander00@gmail.com> Acked-by: Mel Gorman Cc: Alexandru Moise <00moses.alexander00@gmail.com> Cc: Mike Kravetz Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/sysctl/vm.txt | 25 ------------------------- 1 file changed, 25 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 5025ff9307e6..ff234d229cbb 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -30,7 +30,6 @@ Currently, these files are in /proc/sys/vm: - dirty_writeback_centisecs - drop_caches - extfrag_threshold -- hugepages_treat_as_movable - hugetlb_shm_group - laptop_mode - legacy_va_layout @@ -261,30 +260,6 @@ any throttling. ============================================================== -hugepages_treat_as_movable - -This parameter controls whether we can allocate hugepages from ZONE_MOVABLE -or not. If set to non-zero, hugepages can be allocated from ZONE_MOVABLE. -ZONE_MOVABLE is created when kernel boot parameter kernelcore= is specified, -so this parameter has no effect if used without kernelcore=. - -Hugepage migration is now available in some situations which depend on the -architecture and/or the hugepage size. If a hugepage supports migration, -allocation from ZONE_MOVABLE is always enabled for the hugepage regardless -of the value of this parameter. -IOW, this parameter affects only non-migratable hugepages. - -Assuming that hugepages are not migratable in your system, one usecase of -this parameter is that users can make hugepage pool more extensible by -enabling the allocation from ZONE_MOVABLE. This is because on ZONE_MOVABLE -page reclaim/migration/compaction work more and you can get contiguous -memory more likely. Note that using ZONE_MOVABLE for non-migratable -hugepages can do harm to other features like memory hotremove (because -memory hotremove expects that memory blocks on ZONE_MOVABLE are always -removable,) so it's a trade-off responsible for the users. - -============================================================== - hugetlb_shm_group hugetlb_shm_group contains group id that is allowed to create SysV -- cgit From b72dde3869fbac36aa95e50fbff4ff006a5125dd Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Thu, 1 Feb 2018 09:42:33 -0500 Subject: Documentation/process: kernel maintainer PGP guide This guide is an adapted version of the more general "Protecting Code Integrity" guide written and maintained by The Linux Foundation IT for use with open-source projects. It provides the oft-lacking guidance on the following topics: - how to properly protect one's PGP keys to minimize the risks of them being stolen and used maliciously to impersonate a kernel developer - how to configure Git to properly use GnuPG - when and how to use PGP with Git - how to verify fellow Linux Kernel developer identities I believe this document should live with the rest of the documentation describing proper processes one should follow when participating in kernel development. Placing it in a wiki on some place like kernel.org would be insufficient for a number of reasons -- primarily, because only a relatively small subset of maintainers have accounts on kernel.org, but also because even those who do rarely remember that such wiki exists. Keeping it with the rest of in-kernel docs should hopefully give it more visibility, but also help keep it up-to-date as tools and processes evolve. Signed-off-by: Konstantin Ryabitsev Signed-off-by: Jonathan Corbet --- Documentation/process/index.rst | 1 + Documentation/process/maintainer-pgp-guide.rst | 911 +++++++++++++++++++++++++ 2 files changed, 912 insertions(+) create mode 100644 Documentation/process/maintainer-pgp-guide.rst (limited to 'Documentation') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index a430f6eee756..1c9fe657ed01 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -24,6 +24,7 @@ Below are the essential guides that every developer should read. development-process submitting-patches coding-style + maintainer-pgp-guide email-clients kernel-enforcement-statement kernel-driver-statement diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst new file mode 100644 index 000000000000..28674eb42b95 --- /dev/null +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -0,0 +1,911 @@ +.. _pgpguide: + +=========================== +Kernel Maintainer PGP guide +=========================== + +:Author: Konstantin Ryabitsev + +This document is aimed at Linux kernel developers, and especially at +subsystem maintainers. It contains a subset of information discussed in +the more general "`Protecting Code Integrity`_" guide published by the +Linux Foundation. Please read that document for more in-depth discussion +on some of the topics mentioned in this guide. + +.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md + +The role of PGP in Linux Kernel development +=========================================== + +PGP helps ensure the integrity of the code that is produced by the Linux +Kernel development community and, to a lesser degree, establish trusted +communication channels between developers via PGP-signed email exchange. + +The Linux Kernel source code is available in two main formats: + +- Distributed source repositories (git) +- Periodic release snapshots (tarballs) + +Both git repositories and tarballs carry PGP signatures of the kernel +developers who create official kernel releases. These signatures offer a +cryptographic guarantee that downloadable versions made available via +kernel.org or any other mirrors are identical to what these developers +have on their workstations. To this end: + +- git repositories provide PGP signatures on all tags +- tarballs provide detached PGP signatures with all downloads + +.. _devs_not_infra: + +Trusting the developers, not infrastructure +------------------------------------------- + +Ever since the 2011 compromise of core kernel.org systems, the main +operating principle of the Kernel Archives project has been to assume +that any part of the infrastructure can be compromised at any time. For +this reason, the administrators have taken deliberate steps to emphasize +that trust must always be placed with developers and never with the code +hosting infrastructure, regardless of how good the security practices +for the latter may be. + +The above guiding principle is the reason why this guide is needed. We +want to make sure that by placing trust into developers we do not simply +shift the blame for potential future security incidents to someone else. +The goal is to provide a set of guidelines developers can use to create +a secure working environment and safeguard the PGP keys used to +establish the integrity of the Linux Kernel itself. + +.. _pgp_tools: + +PGP tools +========= + +Use GnuPG v2 +------------ + +Your distro should already have GnuPG installed by default, you just +need to verify that you are using version 2.x and not the legacy 1.4 +release -- many distributions still package both, with the default +``gpg`` command invoking GnuPG v.1. To check, run:: + + $ gpg --version | head -n1 + +If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the +``gpg2`` command (if you don't have it, you may need to install the +gnupg2 package):: + + $ gpg2 --version | head -n1 + +If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide +will assume you have the version 2.2 of GnuPG (or later). If you are +using version 2.0 of GnuPG, then some of the commands in this guide will +not work, and you should consider installing the latest 2.2 version of +GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the +purposes of this guide as well. + +If you have both ``gpg`` and ``gpg2`` commands, you should make sure you +are always using GnuPG v2, not the legacy version. You can enforce this +by setting the appropriate alias:: + + $ alias gpg=gpg2 + +You can put that in your ``.bashrc`` to make sure it's always the case. + +Configure gpg-agent options +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The GnuPG agent is a helper tool that will start automatically whenever +you use the ``gpg`` command and run in the background with the purpose +of caching the private key passphrase. There are two options you should +know in order to tweak when the passphrase should be expired from cache: + +- ``default-cache-ttl`` (seconds): If you use the same key again before + the time-to-live expires, the countdown will reset for another period. + The default is 600 (10 minutes). +- ``max-cache-ttl`` (seconds): Regardless of how recently you've used + the key since initial passphrase entry, if the maximum time-to-live + countdown expires, you'll have to enter the passphrase again. The + default is 30 minutes. + +If you find either of these defaults too short (or too long), you can +edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values:: + + # set to 30 minutes for regular ttl, and 2 hours for max ttl + default-cache-ttl 1800 + max-cache-ttl 7200 + +.. note:: + + It is no longer necessary to start gpg-agent manually at the + beginning of your shell session. You may want to check your rc files + to remove anything you had in place for older versions of GnuPG, as + it may not be doing the right thing any more. + +Set up a refresh cronjob +~~~~~~~~~~~~~~~~~~~~~~~~ + +You will need to regularly refresh your keyring in order to get the +latest changes on other people's public keys, which is best done with a +daily cronjob:: + + @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1 + +Check the full path to your ``gpg`` or ``gpg2`` command and use the +``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1. + +.. _master_key: + +Protect your master PGP key +=========================== + +This guide assumes that you already have a PGP key that you use for Linux +Kernel development purposes. If you do not yet have one, please see the +"`Protecting Code Integrity`_" document mentioned earlier for guidance +on how to create a new one. + +You should also make a new key if your current one is weaker than 2048 bits +(RSA). + +Master key vs. Subkeys +---------------------- + +It is important to understand the following: + +1. There are no technical differences between the "master key" and "subkeys." +2. At creation time, we assign functional limitations to each key by + giving it specific capabilities. +3. A PGP key can have 4 capabilities: + + - **[S]** key can be used for signing + - **[E]** key can be used for encryption + - **[A]** key can be used for authentication + - **[C]** key can be used for certifying other keys + +4. A single key may have multiple capabilities. +5. A subkey is fully independent from the master key. A message + encrypted to a subkey cannot be decrypted with the master key. If you + lose your private subkey, it cannot be recreated from the master key + in any way. + +The key carrying the **[C]** (certify) capability is considered the +"master" key because it is the only key that can be used to indicate +relationship with other keys. Only the **[C]** key can be used to: + +- add or revoke other keys (subkeys) with S/E/A capabilities +- add, change or revoke identities (uids) associated with the key +- add or change the expiration date on itself or any subkey +- sign other people's keys for web of trust purposes + +By default, GnuPG creates the following when generating new keys: + +- A master key carrying both Certify and Sign capabilities (**[SC]**) +- A separate subkey with the Encryption capability (**[E]**) + +If you used the default parameters when generating your key, then that +is what you will have. You can verify by running ``gpg --list-secret-keys``, +for example:: + + sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev + ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] + +Any key carrying the **[C]** capability is your master key, regardless +of any other capabilities it may have assigned to it. + +The long line under the ``sec`` entry is your key fingerprint -- +whenever you see ``[fpr]`` in the examples below, that 40-character +string is what it refers to. + +Ensure your passphrase is strong +-------------------------------- + +GnuPG uses passphrases to encrypt your private keys before storing them on +disk. This way, even if your ``.gnupg`` directory is leaked or stolen in +its entirety, the attackers cannot use your private keys without first +obtaining the passphrase to decrypt them. + +It is absolutely essential that your private keys are protected by a +strong passphrase. To set it or change it, use:: + + $ gpg --change-passphrase [fpr] + +Create a separate Signing subkey +-------------------------------- + +Our goal is to protect your master key by moving it to offline media, so +if you only have a combined **[SC]** key, then you should create a separate +signing subkey:: + + $ gpg --quick-add-key [fpr] ed25519 sign + +Remember to tell the keyservers about this change, so others can pull down +your new subkey:: + + $ gpg --send-key [fpr] + +.. note:: ECC support in GnuPG + + GnuPG 2.1 and later has full support for Elliptic Curve + Cryptography, with ability to combine ECC subkeys with traditional + RSA master keys. The main upside of ECC cryptography is that it is + much faster computationally and creates much smaller signatures when + compared byte for byte with 2048+ bit RSA keys. Unless you plan on + using a smartcard device that does not support ECC operations, we + recommend that you create an ECC signing subkey for your kernel + work. + + If for some reason you prefer to stay with RSA subkeys, just replace + "ed25519" with "rsa2048" in the above command. + + +Back up your master key for disaster recovery +--------------------------------------------- + +The more signatures you have on your PGP key from other developers, the +more reasons you have to create a backup version that lives on something +other than digital media, for disaster recovery reasons. + +The best way to create a printable hardcopy of your private key is by +using the ``paperkey`` software written for this very purpose. See ``man +paperkey`` for more details on the output format and its benefits over +other solutions. Paperkey should already be packaged for most +distributions. + +Run the following command to create a hardcopy backup of your private +key:: + + $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt + +Print out that file (or pipe the output straight to lpr), then take a +pen and write your passphrase on the margin of the paper. **This is +strongly recommended** because the key printout is still encrypted with +that passphrase, and if you ever change it you will not remember what it +used to be when you had created the backup -- *guaranteed*. + +Put the resulting printout and the hand-written passphrase into an envelope +and store in a secure and well-protected place, preferably away from your +home, such as your bank vault. + +.. note:: + + Your printer is probably no longer a simple dumb device connected to + your parallel port, but since the output is still encrypted with + your passphrase, printing out even to "cloud-integrated" modern + printers should remain a relatively safe operation. One option is to + change the passphrase on your master key immediately after you are + done with paperkey. + +Back up your whole GnuPG directory +---------------------------------- + +.. warning:: + + **!!!Do not skip this step!!!** + +It is important to have a readily available backup of your PGP keys +should you need to recover them. This is different from the +disaster-level preparedness we did with ``paperkey``. You will also rely +on these external copies whenever you need to use your Certify key -- +such as when making changes to your own key or signing other people's +keys after conferences and summits. + +Start by getting a small USB "thumb" drive (preferably two!) that you +will use for backup purposes. You will need to encrypt them using LUKS +-- refer to your distro's documentation on how to accomplish this. + +For the encryption passphrase, you can use the same one as on your +master key. + +Once the encryption process is over, re-insert the USB drive and make +sure it gets properly mounted. Copy your entire ``.gnupg`` directory +over to the encrypted storage:: + + $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup + +You should now test to make sure everything still works:: + + $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] + +If you don't get any errors, then you should be good to go. Unmount the +USB drive, distinctly label it so you don't blow it away next time you +need to use a random USB drive, and put in a safe place -- but not too +far away, because you'll need to use it every now and again for things +like editing identities, adding or revoking subkeys, or signing other +people's keys. + +Remove the master key from your homedir +---------------------------------------- + +The files in our home directory are not as well protected as we like to +think. They can be leaked or stolen via many different means: + +- by accident when making quick homedir copies to set up a new workstation +- by systems administrator negligence or malice +- via poorly secured backups +- via malware in desktop apps (browsers, pdf viewers, etc) +- via coercion when crossing international borders + +Protecting your key with a good passphrase greatly helps reduce the risk +of any of the above, but passphrases can be discovered via keyloggers, +shoulder-surfing, or any number of other means. For this reason, the +recommended setup is to remove your master key from your home directory +and store it on offline storage. + +.. warning:: + + Please see the previous section and make sure you have backed up + your GnuPG directory in its entirety. What we are about to do will + render your key useless if you do not have a usable backup! + +First, identify the keygrip of your master key:: + + $ gpg --with-keygrip --list-key [fpr] + +The output will be something like this:: + + pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + Keygrip = 1111000000000000000000000000000000000000 + uid [ultimate] Alice Dev + sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + Keygrip = 2222000000000000000000000000000000000000 + sub ed25519 2018-01-24 [S] + Keygrip = 3333000000000000000000000000000000000000 + +Find the keygrip entry that is beneath the ``pub`` line (right under the +master key fingerprint). This will correspond directly to a file in your +``~/.gnupg`` directory:: + + $ cd ~/.gnupg/private-keys-v1.d + $ ls + 1111000000000000000000000000000000000000.key + 2222000000000000000000000000000000000000.key + 3333000000000000000000000000000000000000.key + +All you have to do is simply remove the .key file that corresponds to +the master keygrip:: + + $ cd ~/.gnupg/private-keys-v1.d + $ rm 1111000000000000000000000000000000000000.key + +Now, if you issue the ``--list-secret-keys`` command, it will show that +the master key is missing (the ``#`` indicates it is not available):: + + $ gpg --list-secret-keys + sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev + ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] + ssb ed25519 2018-01-24 [S] + +You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` +directory, which are left over from earlier versions of GnuPG. + +If you don't have the "private-keys-v1.d" directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your +secret keys are still stored in the legacy ``secring.gpg`` file used by +GnuPG v1. Making any changes to your key, such as changing the +passphrase or adding a subkey, should automatically convert the old +``secring.gpg`` format to use ``private-keys-v1.d`` instead. + +Once you get that done, make sure to delete the obsolete ``secring.gpg`` +file, which still contains your private keys. + +.. _smartcards: + +Move the subkeys to a dedicated crypto device +============================================= + +Even though the master key is now safe from being leaked or stolen, the +subkeys are still in your home directory. Anyone who manages to get +their hands on those will be able to decrypt your communication or fake +your signatures (if they know the passphrase). Furthermore, each time a +GnuPG operation is performed, the keys are loaded into system memory and +can be stolen from there by sufficiently advanced malware (think +Meltdown and Spectre). + +The best way to completely protect your keys is to move them to a +specialized hardware device that is capable of smartcard operations. + +The benefits of smartcards +-------------------------- + +A smartcard contains a cryptographic chip that is capable of storing +private keys and performing crypto operations directly on the card +itself. Because the key contents never leave the smartcard, the +operating system of the computer into which you plug in the hardware +device is not able to retrieve the private keys themselves. This is very +different from the encrypted USB storage device we used earlier for +backup purposes -- while that USB device is plugged in and mounted, the +operating system is able to access the private key contents. + +Using external encrypted USB media is not a substitute to having a +smartcard-capable device. + +Available smartcard devices +--------------------------- + +Unless all your laptops and workstations have smartcard readers, the +easiest is to get a specialized USB device that implements smartcard +functionality. There are several options available: + +- `Nitrokey Start`_: Open hardware and Free Software, based on FSI + Japan's `Gnuk`_. Offers support for ECC keys, but fewest security + features (such as resistance to tampering or some side-channel + attacks). +- `Nitrokey Pro`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features, but no ECC + support. +- `Yubikey 4`_: proprietary hardware and software, but cheaper than + Nitrokey Pro and comes available in the USB-C form that is more useful + with newer laptops. Offers additional security features such as FIDO + U2F, but no ECC. + +`LWN has a good review`_ of some of the above models, as well as several +others. If you want to use ECC keys, your best bet among commercially +available devices is the Nitrokey Start. + +.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 +.. _`Nitrokey Pro`: https://shop.nitrokey.com/shop/product/nitrokey-pro-3 +.. _`Yubikey 4`: https://www.yubico.com/product/yubikey-4-series/ +.. _Gnuk: http://www.fsij.org/doc-gnuk/ +.. _`LWN has a good review`: https://lwn.net/Articles/736231/ + +Configure your smartcard device +------------------------------- + +Your smartcard device should Just Work (TM) the moment you plug it into +any modern Linux workstation. You can verify it by running:: + + $ gpg --card-status + +If you see full smartcard details, then you are good to go. +Unfortunately, troubleshooting all possible reasons why things may not +be working for you is way beyond the scope of this guide. If you are +having trouble getting the card to work with GnuPG, please seek help via +usual support channels. + +To configure your smartcard, you will need to use the GnuPG menu system, as +there are no convenient command-line switches:: + + $ gpg --card-edit + [...omitted...] + gpg/card> admin + Admin commands are allowed + gpg/card> passwd + +You should set the user PIN (1), Admin PIN (3), and the Reset Code (4). +Please make sure to record and store these in a safe place -- especially +the Admin PIN and the Reset Code (which allows you to completely wipe +the smartcard). You so rarely need to use the Admin PIN, that you will +inevitably forget what it is if you do not record it. + +Getting back to the main card menu, you can also set other values (such +as name, sex, login data, etc), but it's not necessary and will +additionally leak information about your smartcard should you lose it. + +.. note:: + + Despite having the name "PIN", neither the user PIN nor the admin + PIN on the card need to be numbers. + +Move the subkeys to your smartcard +---------------------------------- + +Exit the card menu (using "q") and save all changes. Next, let's move +your subkeys onto the smartcard. You will need both your PGP key +passphrase and the admin PIN of the card for most operations:: + + $ gpg --edit-key [fpr] + + Secret subkeys are available. + + pub rsa2048/AAAABBBBCCCCDDDD + created: 2018-01-23 expires: 2020-01-23 usage: SC + trust: ultimate validity: ultimate + ssb rsa2048/1111222233334444 + created: 2018-01-23 expires: never usage: E + ssb ed25519/5555666677778888 + created: 2017-12-07 expires: never usage: S + [ultimate] (1). Alice Dev + + gpg> + +Using ``--edit-key`` puts us into the menu mode again, and you will +notice that the key listing is a little different. From here on, all +commands are done from inside this menu mode, as indicated by ``gpg>``. + +First, let's select the key we'll be putting onto the card -- you do +this by typing ``key 1`` (it's the first one in the listing, the **[E]** +subkey):: + + gpg> key 1 + +In the output, you should now see ``ssb*`` on the **[E]** key. The ``*`` +indicates which key is currently "selected." It works as a *toggle*, +meaning that if you type ``key 1`` again, the ``*`` will disappear and +the key will not be selected any more. + +Now, let's move that key onto the smartcard:: + + gpg> keytocard + Please select where to store the key: + (2) Encryption key + Your selection? 2 + +Since it's our **[E]** key, it makes sense to put it into the Encryption +slot. When you submit your selection, you will be prompted first for +your PGP key passphrase, and then for the admin PIN. If the command +returns without an error, your key has been moved. + +**Important**: Now type ``key 1`` again to unselect the first key, and +``key 2`` to select the **[S]** key:: + + gpg> key 1 + gpg> key 2 + gpg> keytocard + Please select where to store the key: + (1) Signature key + (3) Authentication key + Your selection? 1 + +You can use the **[S]** key both for Signature and Authentication, but +we want to make sure it's in the Signature slot, so choose (1). Once +again, if your command returns without an error, then the operation was +successful:: + + gpg> q + Save changes? (y/N) y + +Saving the changes will delete the keys you moved to the card from your +home directory (but it's okay, because we have them in our backups +should we need to do this again for a replacement smartcard). + +Verifying that the keys were moved +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you perform ``--list-secret-keys`` now, you will see a subtle +difference in the output:: + + $ gpg --list-secret-keys + sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev + ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] + ssb> ed25519 2018-01-24 [S] + +The ``>`` in the ``ssb>`` output indicates that the subkey is only +available on the smartcard. If you go back into your secret keys +directory and look at the contents there, you will notice that the +``.key`` files there have been replaced with stubs:: + + $ cd ~/.gnupg/private-keys-v1.d + $ strings *.key | grep 'private-key' + +The output should contain ``shadowed-private-key`` to indicate that +these files are only stubs and the actual content is on the smartcard. + +Verifying that the smartcard is functioning +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify that the smartcard is working as intended, you can create a +signature:: + + $ echo "Hello world" | gpg --clearsign > /tmp/test.asc + $ gpg --verify /tmp/test.asc + +This should ask for your smartcard PIN on your first command, and then +show "Good signature" after you run ``gpg --verify``. + +Congratulations, you have successfully made it extremely difficult to +steal your digital developer identity! + +Other common GnuPG operations +----------------------------- + +Here is a quick reference for some common operations you'll need to do +with your PGP key. + +Mounting your master key offline storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You will need your master key for any of the operations below, so you +will first need to mount your backup offline storage and tell GnuPG to +use it:: + + $ export GNUPGHOME=/media/disk/foo/gnupg-backup + $ gpg --list-secret-keys + +You want to make sure that you see ``sec`` and not ``sec#`` in the +output (the ``#`` means the key is not available and you're still using +your regular home directory location). + +Extending key expiration date +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The master key has the default expiration date of 2 years from the date +of creation. This is done both for security reasons and to make obsolete +keys eventually disappear from keyservers. + +To extend the expiration on your key by a year from current date, just +run:: + + $ gpg --quick-set-expire [fpr] 1y + +You can also use a specific date if that is easier to remember (e.g. +your birthday, January 1st, or Canada Day):: + + $ gpg --quick-set-expire [fpr] 2020-07-01 + +Remember to send the updated key back to keyservers:: + + $ gpg --send-key [fpr] + +Updating your work directory after any changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you make any changes to your key using the offline storage, you will +want to import these changes back into your regular working directory:: + + $ gpg --export | gpg --homedir ~/.gnupg --import + $ unset GNUPGHOME + + +Using PGP with Git +================== + +One of the core features of Git is its decentralized nature -- once a +repository is cloned to your system, you have full history of the +project, including all of its tags, commits and branches. However, with +hundreds of cloned repositories floating around, how does anyone verify +that their copy of linux.git has not been tampered with by a malicious +third party? + +Or what happens if a backdoor is discovered in the code and the "Author" +line in the commit says it was done by you, while you're pretty sure you +had `nothing to do with it`_? + +To address both of these issues, Git introduced PGP integration. Signed +tags prove the repository integrity by assuring that its contents are +exactly the same as on the workstation of the developer who created the +tag, while signed commits make it nearly impossible for someone to +impersonate you without having access to your PGP keys. + +.. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else + +Configure git to use your PGP key +--------------------------------- + +If you only have one secret key in your keyring, then you don't really +need to do anything extra, as it becomes your default key. However, if +you happen to have multiple secret keys, you can tell git which key +should be used (``[fpr]`` is the fingerprint of your key):: + + $ git config --global user.signingKey [fpr] + +**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should +tell git to always use it instead of the legacy ``gpg`` from version 1:: + + $ git config --global gpg.program gpg2 + +How to work with signed tags +---------------------------- + +To create a signed tag, simply pass the ``-s`` switch to the tag +command:: + + $ git tag -s [tagname] + +Our recommendation is to always sign git tags, as this allows other +developers to ensure that the git repository they are pulling from has +not been maliciously altered. + +How to verify signed tags +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify a signed tag, simply use the ``verify-tag`` command:: + + $ git verify-tag [tagname] + +If you are pulling a tag from another fork of the project repository, +git should automatically verify the signature at the tip you're pulling +and show you the results during the merge operation:: + + $ git pull [url] tags/sometag + +The merge message will contain something like this:: + + Merge tag 'sometag' of [url] + + [Tag message] + + # gpg: Signature made [...] + # gpg: Good signature from [...] + +If you are verifying someone else's git tag, then you will need to +import their PGP key. Please refer to the +":ref:`verify_identities`" section below. + +Configure git to always sign annotated tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Chances are, if you're creating an annotated tag, you'll want to sign +it. To force git to always sign annotated tags, you can set a global +configuration option:: + + $ git config --global tag.forceSignAnnotated true + +How to work with signed commits +------------------------------- + +It is easy to create signed commits, but it is much more difficult to +use them in Linux Kernel development, since it relies on patches sent to +the mailing list, and this workflow does not preserve PGP commit +signatures. + +If you have your working git tree publicly available at some git hosting +service (kernel.org, infradead.org, ozlabs.org, or others), then the +recommendation is that you sign all your git commits even if upstream +developers do not directly benefit from this practice. Should there ever +be a need to perform code forensics or track code provenance, even +externally maintained trees carrying PGP commit signatures will be +extremely valuable for such purposes. + +Creating signed commits +~~~~~~~~~~~~~~~~~~~~~~~ + +To create a signed commit, you just need to pass the ``-S`` flag to the +``git commit`` command (it's capital ``-S`` due to collision with +another flag):: + + $ git commit -S + +Configure git to always sign commits +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can tell git to always sign commits:: + + git config --global commit.gpgSign true + +.. _verify_identities: + +How to verify kernel developer identities +========================================= + +Signing tags and commits is easy, but how does one go about verifying +that the key used to sign something belongs to the actual kernel +developer and not to a malicious imposter? + +Configure auto-key-retrieval using WKD and DANE +----------------------------------------------- + +If you are not already someone with an extensive collection of other +developers' public keys, then you can jumpstart your keyring by relying +on key auto-discovery and auto-retrieval. GnuPG can piggyback on other +delegated trust technologies, namely DNSSEC and TLS, to get you going if +the prospect of starting your own Web of Trust from scratch is too +daunting. + +Add the following to your ``~/.gnupg/gpg.conf``:: + + auto-key-locate wkd,dane,local + auto-key-retrieve + +DNS-Based Authentication of Named Entities ("DANE") is a method for +publishing public keys in DNS and securing them using DNSSEC signed +zones. Web Key Directory ("WKD") is the alternative method that uses +https lookups for the same purpose. When using either DANE or WKD for +looking up public keys, GnuPG will validate DNSSEC or TLS certificates, +respectively, before adding auto-retrieved public keys to your local +keyring. + +Kernel.org publishes the WKD for all developers who have kernel.org +accounts. Once you have the above changes in your ``gpg.conf``, you can +auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you +don't already have them):: + + $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org + +If you have a kernel.org account, then you should `add the kernel.org +UID to your key`_ to make WKD more useful to other kernel developers. + +.. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key + +Web of Trust (WOT) vs. Trust on First Use (TOFU) +------------------------------------------------ + +PGP incorporates a trust delegation mechanism known as the "Web of +Trust." At its core, this is an attempt to replace the need for +centralized Certification Authorities of the HTTPS/TLS world. Instead of +various software makers dictating who should be your trusted certifying +entity, PGP leaves this responsibility to each user. + +Unfortunately, very few people understand how the Web of Trust works. +While it remains an important aspect of the OpenPGP specification, +recent versions of GnuPG (2.2 and above) have implemented an alternative +mechanism called "Trust on First Use" (TOFU). You can think of TOFU as +"the SSH-like approach to trust." With SSH, the first time you connect +to a remote system, its key fingerprint is recorded and remembered. If +the key changes in the future, the SSH client will alert you and refuse +to connect, forcing you to make a decision on whether you choose to +trust the changed key or not. Similarly, the first time you import +someone's PGP key, it is assumed to be valid. If at any point in the +future GnuPG comes across another key with the same identity, both the +previously imported key and the new key will be marked as invalid and +you will need to manually figure out which one to keep. + +We recommend that you use the combined TOFU+PGP trust model (which is +the new default in GnuPG v2). To set it, add (or modify) the +``trust-model`` setting in ``~/.gnupg/gpg.conf``:: + + trust-model tofu+pgp + +How to use keyservers (more) safely +----------------------------------- + +If you get a "No public key" error when trying to validate someone's +tag, then you should attempt to lookup that key using a keyserver. It is +important to keep in mind that there is absolutely no guarantee that the +key you retrieve from PGP keyservers belongs to the actual person -- +that much is by design. You are supposed to use the Web of Trust to +establish key validity. + +How to properly maintain the Web of Trust is beyond the scope of this +document, simply because doing it properly requires both effort and +dedication that tends to be beyond the caring threshold of most human +beings. Here are some shortcuts that will help you reduce the risk of +importing a malicious key. + +First, let's say you've tried to run ``git verify-tag`` but it returned +an error saying the key is not found:: + + $ git verify-tag sunxi-fixes-for-4.15-2 + gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST + gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430 + gpg: issuer "wens@...org" + gpg: Can't check signature: No public key + +Let's query the keyserver for more info about that key fingerprint (the +fingerprint probably belongs to a subkey, so we can't use it directly +without finding out the ID of the master key it is associated with):: + + $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430 + gpg: data source: hkp://keys.gnupg.net + (1) Chen-Yu Tsai + 4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15 + Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430". Enter number(s), N)ext, or Q)uit > q + +Locate the ID of the master key in the output, in our example +``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you +have on your keyring:: + + $ git --list-key torvalds@kernel.org + pub rsa2048 2011-09-20 [SC] + ABAF11C65A2970B130ABE3C479BE3E4300411886 + uid [ unknown] Linus Torvalds + sub rsa2048 2011-09-20 [E] + +Next, open the `PGP pathfinder`_. In the "From" field, paste the key +fingerprint of Linus Torvalds from the output above. In the "To" field, +paste they key-id you found via ``gpg --search`` of the unknown key, and +check the results: + +- `Finding paths to Linus`_ + +If you get a few decent trust paths, then it's a pretty good indication +that it is a valid key. You can add it to your keyring from the +keyserver now:: + + $ gpg --recv-key C94035C21B4F2AEB + +This process is not perfect, and you are obviously trusting the +administrators of the PGP Pathfinder service to not be malicious (in +fact, this goes against :ref:`devs_not_infra`). However, if you +do not carefully maintain your own web of trust, then it is a marked +improvement over blindly trusting keyservers. + +.. _`PGP pathfinder`: https://pgp.cs.uu.nl/ +.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html -- cgit From 5aa55fc2c8db3f6994b19b4bb9a9ec715d94353f Mon Sep 17 00:00:00 2001 From: Grigory Shipunov Date: Tue, 30 Jan 2018 15:58:06 +0300 Subject: Fix broken link in Documentation/process/kernel-docs.rst Kernel Glossary has moved from /Glossary to /KernelGlossary on kernelnewbies.org. This patch corrects this link. Signed-off-by: Grigory Shipunov Signed-off-by: Jonathan Corbet --- Documentation/process/kernel-docs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index b8cac85a4001..3fb28de556e4 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -58,7 +58,7 @@ On-line docs * Title: **Linux Kernel Mailing List Glossary** :Author: various - :URL: http://kernelnewbies.org/glossary/ + :URL: https://kernelnewbies.org/KernelGlossary :Date: rolling version :Keywords: glossary, terms, linux-kernel. :Description: From the introduction: "This glossary is intended as -- cgit From 9124bb8760c16bc7689dd26a5ab98a231765309f Mon Sep 17 00:00:00 2001 From: Corentin Labbe Date: Mon, 29 Jan 2018 12:21:07 +0000 Subject: Documentation: mips: Update AU1xxx_IDE Kconfig dependencies IDEDMA_AUTO IDEDMA_PCI_AUTO was removed in commit 120b9cfddff2 ("ide: remove CONFIG_IDEDMA_{ICS,PCI}_AUTO config") BLK_DEV_IDEDISK was removed in commit 806f80a6fc20 ("ide: add generic ATA/ATAPI disk driver") BLK_DEV_IDE_AU1XXX_BURSTABLE_ON was removed in commit 8f29e650bffc ("ide: AU1200 IDE update") Remove them from documentation Signed-off-by: Corentin Labbe Signed-off-by: Jonathan Corbet --- Documentation/mips/AU1xxx_IDE.README | 7 ------- 1 file changed, 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/AU1xxx_IDE.README index 52844a58cc8a..ff675a1b1422 100644 --- a/Documentation/mips/AU1xxx_IDE.README +++ b/Documentation/mips/AU1xxx_IDE.README @@ -56,8 +56,6 @@ Following extra configs variables are introduced: CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode - CONFIG_BLK_DEV_IDE_AU1XXX_BURSTABLE_ON - set Burstable FIFO in DBDMA - controller SUPPORTED IDE MODES @@ -82,11 +80,9 @@ CONFIG_IDE_GENERIC=y CONFIG_BLK_DEV_IDEPCI=y CONFIG_BLK_DEV_GENERIC=y CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_IDEDMA_PCI_AUTO=y CONFIG_BLK_DEV_IDE_AU1XXX=y CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y CONFIG_BLK_DEV_IDEDMA=y -CONFIG_IDEDMA_AUTO=y Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable the burst support on DBDMA controller. @@ -94,16 +90,13 @@ the burst support on DBDMA controller. If the used system need the USB support enable the following kernel configs for high IDE to USB throughput. -CONFIG_BLK_DEV_IDEDISK=y CONFIG_IDE_GENERIC=y CONFIG_BLK_DEV_IDEPCI=y CONFIG_BLK_DEV_GENERIC=y CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_IDEDMA_PCI_AUTO=y CONFIG_BLK_DEV_IDE_AU1XXX=y CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y CONFIG_BLK_DEV_IDEDMA=y -CONFIG_IDEDMA_AUTO=y Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to disable the burst support on DBDMA controller. -- cgit From 54e36a2dc554685463af54b4ac97a5ec022bd09c Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 27 Jan 2018 18:49:08 -0800 Subject: Documentation/admin-guide: fixes for thunderbolt.rst Edits for grammar, punctuation, and a doubled-up word. Signed-off-by: Randy Dunlap Cc: Andreas Noever Cc: Michael Jamet Cc: Mika Westerberg Cc: Yehezkel Bernat Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/thunderbolt.rst | 66 +++++++++++++++---------------- 1 file changed, 33 insertions(+), 33 deletions(-) (limited to 'Documentation') diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 9b55952039a6..9948ec36a204 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -3,13 +3,13 @@ ============= 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 -database of the authorized devices and prompts user for new connections. +a database of the authorized devices and prompts users for new connections. More details about the sysfs interface for Thunderbolt devices can be found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``. Those users who just want to connect any device without any sort of -manual work, can add following line to +manual work can add following line to ``/etc/udev/rules.d/99-local.rules``:: ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1" @@ -20,7 +20,7 @@ vulnerable to DMA attacks. Security levels and how to use them ----------------------------------- -Starting from Intel Falcon Ridge Thunderbolt controller there are 4 +Starting with Intel Falcon Ridge Thunderbolt controller there are 4 security levels available. The reason for these is the fact that the connected devices can be DMA masters and thus read contents of the host memory without CPU and OS knowing about it. There are ways to prevent @@ -37,14 +37,14 @@ The security levels are as follows: user User is asked whether the device is allowed to be connected. Based on the device identification information available through - ``/sys/bus/thunderbolt/devices``. user then can do the decision. + ``/sys/bus/thunderbolt/devices``, the user then can make the decision. In BIOS settings this is typically called *Unique ID*. secure User is asked whether the device is allowed to be connected. In addition to UUID the device (if it supports secure connect) is sent a challenge that should match the expected one based on a random key - written to ``key`` sysfs attribute. In BIOS settings this is + written to the ``key`` sysfs attribute. In BIOS settings this is typically called *One time saved key*. dponly @@ -78,7 +78,7 @@ When a device is plugged in it will appear in sysfs as follows:: /sys/bus/thunderbolt/devices/0-1/unique_id - e0376f00-0300-0100-ffff-ffffffffffff The ``authorized`` attribute reads 0 which means no PCIe tunnels are -created yet. The user can authorize the device by simply:: +created yet. The user can authorize the device by simply entering:: # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized @@ -86,7 +86,7 @@ This will create the PCIe tunnels and the device is now connected. If the device supports secure connect, and the domain security level is set to ``secure``, it has an additional attribute ``key`` which can hold -a random 32 byte value used for authorization and challenging the device in +a random 32-byte value used for authorization and challenging the device in future connects:: /sys/bus/thunderbolt/devices/0-3/authorized - 0 @@ -99,12 +99,12 @@ future connects:: Notice the key is empty by default. -If the user does not want to use secure connect it can just ``echo 1`` +If the user does not want to use secure connect they can just ``echo 1`` to the ``authorized`` attribute and the PCIe tunnels will be created in -the same way than in ``user`` security level. +the same way as in the ``user`` security level. If the user wants to use secure connect, the first time the device is -plugged a key needs to be created and send to the device:: +plugged a key needs to be created and sent to the device:: # key=$(openssl rand -hex 32) # echo $key > /sys/bus/thunderbolt/devices/0-3/key @@ -121,27 +121,27 @@ device using the same key:: If the challenge the device returns back matches the one we expect based on the key, the device is connected and the PCIe tunnels are created. -However, if the challenge failed no tunnels are created and error is +However, if the challenge fails no tunnels are created and error is returned to the user. -If the user still wants to connect the device it can either approve -the device without a key or write new key and write 1 to the +If the user still wants to connect the device they can either approve +the device without a key or write a new key and write 1 to the ``authorized`` file to get the new key stored on the device NVM. Upgrading NVM on Thunderbolt device or host ------------------------------------------- -Since most of the functionality is handled in a firmware running on a +Since most of the functionality is handled in firmware running on a host controller or a device, it is important that the firmware can be upgraded to the latest where possible bugs in it have been fixed. Typically OEMs provide this firmware from their support site. -There is also a central site which has links where to download firmwares +There is also a central site which has links where to download firmware for some machines: `Thunderbolt Updates `_ -Before you upgrade firmware on a device or host, please make sure it is -the suitable. Failing to do that may render the device (or host) in a +Before you upgrade firmware on a device or host, please make sure it is a +suitable upgrade. Failing to do that may render the device (or host) in a state where it cannot be used properly anymore without special tools! Host NVM upgrade on Apple Macs is not supported. @@ -151,7 +151,7 @@ Thunderbolt device so that the host controller appears. It does not matter which device is connected (unless you are upgrading NVM on a device - then you need to connect that particular device). -Note OEM-specific method to power the controller up ("force power") may +Note an OEM-specific method to power the controller up ("force power") may be available for your system in which case there is no need to plug in a Thunderbolt device. @@ -171,7 +171,7 @@ it comes back the driver notices it and initiates a full power cycle. After a while the host controller appears again and this time it should be fully functional. -We can verify that the new NVM firmware is active by running following +We can verify that the new NVM firmware is active by running the following commands:: # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate @@ -179,38 +179,38 @@ commands:: # cat /sys/bus/thunderbolt/devices/0-0/nvm_version 18.0 -If ``nvm_authenticate`` contains anything else than 0x0 it is the error +If ``nvm_authenticate`` contains anything other than 0x0 it is the error code from the last authentication cycle, which means the authentication of the NVM image failed. Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN`` -depends on the order they are registered in the NVMem subsystem. N in +depend on the order they are registered in the NVMem subsystem. N in the name is the identifier added by the NVMem subsystem. Upgrading NVM when host controller is in safe mode -------------------------------------------------- If the existing NVM is not properly authenticated (or is missing) the -host controller goes into safe mode which means that only available -functionality is flashing new NVM image. When in this mode the reading +host controller goes into safe mode which means that the only available +functionality is flashing a new NVM image. When in this mode, reading ``nvm_version`` fails with ``ENODATA`` and the device identification information is missing. To recover from this mode, one needs to flash a valid NVM image to the -host host controller in the same way it is done in the previous chapter. +host controller in the same way it is done in the previous chapter. Networking over Thunderbolt cable --------------------------------- -Thunderbolt technology allows software communication across two hosts +Thunderbolt technology allows software communication between two hosts connected by a Thunderbolt cable. -It is possible to tunnel any kind of traffic over Thunderbolt link but +It is possible to tunnel any kind of traffic over a Thunderbolt link but currently we only support Apple ThunderboltIP protocol. -If the other host is running Windows or macOS only thing you need to -do is to connect Thunderbolt cable between the two hosts, the -``thunderbolt-net`` is loaded automatically. If the other host is also -Linux you should load ``thunderbolt-net`` manually on one host (it does -not matter which one):: +If the other host is running Windows or macOS, the only thing you need to +do is to connect a Thunderbolt cable between the two hosts; the +``thunderbolt-net`` driver is loaded automatically. If the other host is +also Linux you should load ``thunderbolt-net`` manually on one host (it +does not matter which one):: # modprobe thunderbolt-net @@ -220,12 +220,12 @@ is built-in to the kernel image, there is no need to do anything. The driver will create one virtual ethernet interface per Thunderbolt port which are named like ``thunderbolt0`` and so on. From this point you can either use standard userspace tools like ``ifconfig`` to -configure the interface or let your GUI to handle it automatically. +configure the interface or let your GUI handle it automatically. Forcing power ------------- Many OEMs include a method that can be used to force the power of a -thunderbolt controller to an "On" state even if nothing is connected. +Thunderbolt controller to an "On" state even if nothing is connected. If supported by your machine this will be exposed by the WMI bus with a sysfs attribute called "force_power". -- cgit From 7ddd091341336f8f809efe4049e2d8fbe5366328 Mon Sep 17 00:00:00 2001 From: Cornelia Huck Date: Tue, 11 Jul 2017 15:44:09 +0200 Subject: s390/docs: mention subchannel types Since the original inception of the s390-drivers document, the common I/O layer has grown support for more types of subchannels. Give at least a pointer for the various types. Signed-off-by: Cornelia Huck Signed-off-by: Sebastian Ott Signed-off-by: Martin Schwidefsky --- Documentation/driver-api/s390-drivers.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst index ecf8851d3565..42350f21357d 100644 --- a/Documentation/driver-api/s390-drivers.rst +++ b/Documentation/driver-api/s390-drivers.rst @@ -22,9 +22,28 @@ While most I/O devices on a s390 system are typically driven through the channel I/O mechanism described here, there are various other methods (like the diag interface). These are out of the scope of this document. +The s390 common I/O layer also provides access to some devices that are +not strictly considered I/O devices. They are considered here as well, +although they are not the focus of this document. + Some additional information can also be found in the kernel source under Documentation/s390/driver-model.txt. +The css bus +=========== + +The css bus contains the subchannels available on the system. They fall +into several categories: + +* Standard I/O subchannels, for use by the system. They have a child + device on the ccw bus and are described below. +* I/O subchannels bound to the vfio-ccw driver. See + Documentation/s390/vfio-ccw.txt. +* Message subchannels. No Linux driver currently exists. +* CHSC subchannels (at most one). The chsc subchannel driver can be used + to send asynchronous chsc commands. +* eADM subchannels. Used for talking to storage class memory. + The ccw bus =========== -- cgit From 0f0929bc5ca321ea9bdcf5b9be9246dd0dc3f1bf Mon Sep 17 00:00:00 2001 From: Cornelia Huck Date: Tue, 11 Jul 2017 16:04:45 +0200 Subject: s390/docs: reword airq section Also mention the iv helpers as well. Signed-off-by: Cornelia Huck Signed-off-by: Sebastian Ott Signed-off-by: Martin Schwidefsky --- Documentation/driver-api/s390-drivers.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/s390-drivers.rst b/Documentation/driver-api/s390-drivers.rst index 42350f21357d..30e6aa7e160b 100644 --- a/Documentation/driver-api/s390-drivers.rst +++ b/Documentation/driver-api/s390-drivers.rst @@ -121,10 +121,15 @@ ccw group devices Generic interfaces ================== -Some interfaces are available to other drivers that do not necessarily -have anything to do with the busses described above, but still are -indirectly using basic infrastructure in the common I/O layer. One -example is the support for adapter interrupts. +The following section contains interfaces in use not only by drivers +dealing with ccw devices, but drivers for various other s390 hardware +as well. + +Adapter interrupts +------------------ + +The common I/O layer provides helper functions for dealing with adapter +interrupts and interrupt vectors. .. kernel-doc:: drivers/s390/cio/airq.c :export: -- cgit From 6215ea6b7ee7bdaf308bd72f01dbf62dec70cdad Mon Sep 17 00:00:00 2001 From: Yonghong Song Date: Thu, 1 Feb 2018 23:00:11 -0800 Subject: bpf: add documentation to compare clang "-target bpf" and default target The added documentation explains how generated codes may differ between clang bpf target and default target, and when to use each target. Signed-off-by: Yonghong Song Signed-off-by: Daniel Borkmann --- Documentation/bpf/bpf_devel_QA.txt | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'Documentation') diff --git a/Documentation/bpf/bpf_devel_QA.txt b/Documentation/bpf/bpf_devel_QA.txt index cefef855dea4..84cbb302f2b5 100644 --- a/Documentation/bpf/bpf_devel_QA.txt +++ b/Documentation/bpf/bpf_devel_QA.txt @@ -516,4 +516,35 @@ A: LLVM has a -mcpu selector for the BPF back end in order to allow the By the way, the BPF kernel selftests run with -mcpu=probe for better test coverage. +Q: In some cases clang flag "-target bpf" is used but in other cases the + default clang target, which matches the underlying architecture, is used. + What is the difference and when I should use which? + +A: Although LLVM IR generation and optimization try to stay architecture + independent, "-target " still has some impact on generated code: + + - BPF program may recursively include header file(s) with file scope + inline assembly codes. The default target can handle this well, + while bpf target may fail if bpf backend assembler does not + understand these assembly codes, which is true in most cases. + + - When compiled without -g, additional elf sections, e.g., + .eh_frame and .rela.eh_frame, may be present in the object file + with default target, but not with bpf target. + + - The default target may turn a C switch statement into a switch table + lookup and jump operation. Since the switch table is placed + in the global readonly section, the bpf program will fail to load. + The bpf target does not support switch table optimization. + The clang option "-fno-jump-tables" can be used to disable + switch table generation. + + You should use default target when: + + - Your program includes a header file, e.g., ptrace.h, which eventually + pulls in some header files containing file scope host assembly codes. + - You can add "-fno-jump-tables" to work around the switch table issue. + + Otherwise, you can use bpf target. + Happy BPF hacking! -- cgit From 71ea98ffef522e1526cd8c089eceeea6b7385b89 Mon Sep 17 00:00:00 2001 From: Corentin Labbe Date: Thu, 1 Feb 2018 20:44:10 +0000 Subject: documentation: watchdog: remove documentation of at32ap700x_wdt Since at32ap700x_wdt is gone, no need to keep its documentation Signed-off-by: Corentin Labbe Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- Documentation/watchdog/watchdog-parameters.txt | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index 6f9d7b418917..407d013b8643 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -40,11 +40,6 @@ margin: Watchdog margin in seconds (default=60) nowayout: Disable watchdog shutdown on close (default=kernel config parameter) ------------------------------------------------- -at32ap700x_wdt: -timeout: Timeout value. Limited to be 1 or 2 seconds. (default=2) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- at91rm9200_wdt: wdt_time: Watchdog time in seconds. (default=5) nowayout: Watchdog cannot be stopped once started -- cgit From 7171b137f842d16641185e3c3daa8ebb32f67e1b Mon Sep 17 00:00:00 2001 From: Corentin Labbe Date: Thu, 1 Feb 2018 20:44:11 +0000 Subject: documentation: watchdog: remove documentation for ixp2000 The ixp2000 watchdog driver was removed in commit 065e8238302b ("watchdog: remove ixp2000 driver") No need to keep its documentation, so remove it. Signed-off-by: Corentin Labbe Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- Documentation/watchdog/watchdog-parameters.txt | 5 ----- 1 file changed, 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index 407d013b8643..603140485ac6 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -157,11 +157,6 @@ testmode: Watchdog test mode (1 = no reboot), default=0 nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- -ixp2000_wdt: -heartbeat: Watchdog heartbeat in seconds (default 60s) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- ixp4xx_wdt: heartbeat: Watchdog heartbeat in seconds (default 60s) nowayout: Watchdog cannot be stopped once started -- cgit From 592a547adf686dbec7687e816ecdf9101fe227f5 Mon Sep 17 00:00:00 2001 From: Corentin Labbe Date: Thu, 1 Feb 2018 20:44:12 +0000 Subject: documentation: watchdog: remove documentation of w83697hf_wdt/w83697ug_wdt Since w83697hf_wdt/w83697ug_wdt watchdogs drivers were removed in commit 7285fae9345e ("watchdog: Remove drivers for W83697HF and W83697UG") There are no need to keep their documentation Signed-off-by: Corentin Labbe Reviewed-by: Guenter Roeck Signed-off-by: Guenter Roeck Signed-off-by: Wim Van Sebroeck --- Documentation/watchdog/watchdog-parameters.txt | 13 ------------- 1 file changed, 13 deletions(-) (limited to 'Documentation') diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index 603140485ac6..beea975980f6 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -371,19 +371,6 @@ timeout: Watchdog timeout in seconds. 1 <= timeout <= 255, default=60. nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- -w83697hf_wdt: -wdt_io: w83697hf/hg WDT io port (default 0x2e, 0 = autodetect) -timeout: Watchdog timeout in seconds. 1<= timeout <=255 (default=60) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -early_disable: Watchdog gets disabled at boot time (default=1) -------------------------------------------------- -w83697ug_wdt: -wdt_io: w83697ug/uf WDT io port (default 0x2e) -timeout: Watchdog timeout in seconds. 1<= timeout <=255 (default=60) -nowayout: Watchdog cannot be stopped once started - (default=kernel config parameter) -------------------------------------------------- w83877f_wdt: timeout: Watchdog timeout in seconds. (1<=timeout<=3600, default=30) nowayout: Watchdog cannot be stopped once started -- cgit From 0ae7d327a64b262443b7d3ebee5831e4dde47b89 Mon Sep 17 00:00:00 2001 From: Georgi Djakov Date: Tue, 5 Dec 2017 17:47:00 +0200 Subject: dt-bindings: mailbox: qcom: Document the APCS clock binding Update the binding documentation for APCS to mention that the APCS hardware block also expose a clock controller functionality. The APCS clock controller is a mux and half-integer divider. It has the main CPU PLL as an input and provides the clock for the application CPU. Signed-off-by: Georgi Djakov Reviewed-by: Rob Herring Acked-by: Bjorn Andersson Signed-off-by: Jassi Brar --- .../bindings/mailbox/qcom,apcs-kpss-global.txt | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt index fb961c310f44..16964f0c1773 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt @@ -15,12 +15,21 @@ platforms. Usage: required Value type: Definition: must specify the base address and size of the global block +- clocks: + Usage: required if #clocks-cells property is present + Value type: + Definition: phandle to the input PLL, which feeds the APCS mux/divider - #mbox-cells: Usage: required Value type: Definition: as described in mailbox.txt, must be 1 +- #clock-cells: + Usage: optional + Value type: + Definition: as described in clock.txt, must be 0 + = EXAMPLE The following example describes the APCS HMSS found in MSM8996 and part of the @@ -44,3 +53,12 @@ GLINK RPM referencing the "rpm_hlos" doorbell therein. mbox-names = "rpm_hlos"; }; +Below is another example of the APCS binding on MSM8916 platforms: + + apcs: mailbox@b011000 { + compatible = "qcom,msm8916-apcs-kpss-global"; + reg = <0xb011000 0x1000>; + #mbox-cells = <1>; + clocks = <&a53pll>; + #clock-cells = <0>; + }; -- cgit From 46adb17982fae89aa3d41a0ba5706bc3f9d8f80d Mon Sep 17 00:00:00 2001 From: Jason Gunthorpe Date: Fri, 2 Feb 2018 14:35:29 -0700 Subject: IB: Update references to libibverbs These days the userspace comes from rdma-core, revise references in the kernel to point to the current repository. Signed-off-by: Jason Gunthorpe Reviewed-by: Leon Romanovsky Signed-off-by: Doug Ledford --- Documentation/infiniband/user_verbs.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/infiniband/user_verbs.txt b/Documentation/infiniband/user_verbs.txt index e5092d696da2..df049b9f5b6e 100644 --- a/Documentation/infiniband/user_verbs.txt +++ b/Documentation/infiniband/user_verbs.txt @@ -5,7 +5,7 @@ USERSPACE VERBS ACCESS described in chapter 11 of the InfiniBand Architecture Specification. To use the verbs, the libibverbs library, available from - http://www.openfabrics.org/, is required. libibverbs contains a + https://github.com/linux-rdma/rdma-core, is required. libibverbs contains a device-independent API for using the ib_uverbs interface. libibverbs also requires appropriate device-dependent kernel and userspace driver for your InfiniBand hardware. For example, to use -- cgit From a61a86f8db92923a2a4c857c49a795bcae754497 Mon Sep 17 00:00:00 2001 From: Tonghao Zhang Date: Sun, 4 Feb 2018 18:07:10 -0800 Subject: doc: Change the min default value of tcp_wmem/tcp_rmem. The SK_MEM_QUANTUM was changed from PAGE_SIZE to 4096. And the tcp_wmem/tcp_rmem min default values are 4096. Fixes: bd68a2a854ad ("net: set SK_MEM_QUANTUM to 4096") Cc: Eric Dumazet Signed-off-by: Tonghao Zhang Signed-off-by: David S. Miller --- Documentation/networking/ip-sysctl.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 3f2c40d8e6aa..a553d4e4a0fb 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -508,7 +508,7 @@ tcp_rmem - vector of 3 INTEGERs: min, default, max min: Minimal size of receive buffer used by TCP sockets. It is guaranteed to each TCP socket, even under moderate memory pressure. - Default: 1 page + Default: 4K default: initial size of receive buffer used by TCP sockets. This value overrides net.core.rmem_default used by other protocols. @@ -667,7 +667,7 @@ tcp_window_scaling - BOOLEAN tcp_wmem - vector of 3 INTEGERs: min, default, max min: Amount of memory reserved for send buffers for TCP sockets. Each TCP socket has rights to use it due to fact of its birth. - Default: 1 page + Default: 4K default: initial size of send buffer used by TCP sockets. This value overrides net.core.wmem_default used by other protocols. -- cgit From 4d673da14533b32fe8d3125b5b7be4fea14e39a8 Mon Sep 17 00:00:00 2001 From: David Howells Date: Tue, 6 Feb 2018 06:26:30 +0000 Subject: afs: Support the AFS dynamic root Support the AFS dynamic root which is a pseudo-volume that doesn't connect to any server resource, but rather is just a root directory that dynamically creates mountpoint directories where the name of such a directory is the name of the cell. Such a mount can be created thus: mount -t afs none /afs -o dyn Dynamic root superblocks aren't shared except by bind mounts and propagation. Cell root volumes can then be mounted by referring to them by name, e.g.: ls /afs/grand.central.org/ ls /afs/.grand.central.org/ The kernel will upcall to consult the DNS if the address wasn't supplied directly. Signed-off-by: David Howells --- Documentation/filesystems/afs.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'Documentation') diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt index ba99b5ac4fd8..c5254f6d234d 100644 --- a/Documentation/filesystems/afs.txt +++ b/Documentation/filesystems/afs.txt @@ -7,6 +7,7 @@ Contents: - Overview. - Usage. - Mountpoints. + - Dynamic root. - Proc filesystem. - The cell database. - Security. @@ -127,6 +128,22 @@ mounted on /afs in one go by doing: umount /afs +============ +DYNAMIC ROOT +============ + +A mount option is available to create a serverless mount that is only usable +for dynamic lookup. Creating such a mount can be done by, for example: + + mount -t afs none /afs -o dyn + +This creates a mount that just has an empty directory at the root. Attempting +to look up a name in this directory will cause a mountpoint to be created that +looks up a cell of the same name, for example: + + ls /afs/grand.central.org/ + + =============== PROC FILESYSTEM =============== -- cgit From ac665d9423474e64e64b34b0e2cea43601b50d7d Mon Sep 17 00:00:00 2001 From: Matthew Wilcox Date: Tue, 6 Feb 2018 15:05:49 -0500 Subject: idr: Add documentation Move the idr kernel-doc to its own idr.rst file and add a few paragraphs about how to use it. Also add some more kernel-doc. Signed-off-by: Matthew Wilcox --- Documentation/core-api/idr.rst | 79 +++++++++++++++++++++++++++++++++++ Documentation/core-api/index.rst | 1 + Documentation/core-api/kernel-api.rst | 12 ------ 3 files changed, 80 insertions(+), 12 deletions(-) create mode 100644 Documentation/core-api/idr.rst (limited to 'Documentation') diff --git a/Documentation/core-api/idr.rst b/Documentation/core-api/idr.rst new file mode 100644 index 000000000000..9078a5c3ac95 --- /dev/null +++ b/Documentation/core-api/idr.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +============= +ID Allocation +============= + +:Author: Matthew Wilcox + +Overview +======== + +A common problem to solve is allocating identifiers (IDs); generally +small numbers which identify a thing. Examples include file descriptors, +process IDs, packet identifiers in networking protocols, SCSI tags +and device instance numbers. The IDR and the IDA provide a reasonable +solution to the problem to avoid everybody inventing their own. The IDR +provides the ability to map an ID to a pointer, while the IDA provides +only ID allocation, and as a result is much more memory-efficient. + +IDR usage +========= + +Start by initialising an IDR, either with :c:func:`DEFINE_IDR` +for statically allocated IDRs or :c:func:`idr_init` for dynamically +allocated IDRs. + +You can call :c:func:`idr_alloc` to allocate an unused ID. Look up +the pointer you associated with the ID by calling :c:func:`idr_find` +and free the ID by calling :c:func:`idr_remove`. + +If you need to change the pointer associated with an ID, you can call +:c:func:`idr_replace`. One common reason to do this is to reserve an +ID by passing a ``NULL`` pointer to the allocation function; initialise the +object with the reserved ID and finally insert the initialised object +into the IDR. + +Some users need to allocate IDs larger than ``INT_MAX``. So far all of +these users have been content with a ``UINT_MAX`` limit, and they use +:c:func:`idr_alloc_u32`. If you need IDs that will not fit in a u32, +we will work with you to address your needs. + +If you need to allocate IDs sequentially, you can use +:c:func:`idr_alloc_cyclic`. The IDR becomes less efficient when dealing +with larger IDs, so using this function comes at a slight cost. + +To perform an action on all pointers used by the IDR, you can +either use the callback-based :c:func:`idr_for_each` or the +iterator-style :c:func:`idr_for_each_entry`. You may need to use +:c:func:`idr_for_each_entry_continue` to continue an iteration. You can +also use :c:func:`idr_get_next` if the iterator doesn't fit your needs. + +When you have finished using an IDR, you can call :c:func:`idr_destroy` +to release the memory used by the IDR. This will not free the objects +pointed to from the IDR; if you want to do that, use one of the iterators +to do it. + +You can use :c:func:`idr_is_empty` to find out whether there are any +IDs currently allocated. + +If you need to take a lock while allocating a new ID from the IDR, +you may need to pass a restrictive set of GFP flags, which can lead +to the IDR being unable to allocate memory. To work around this, +you can call :c:func:`idr_preload` before taking the lock, and then +:c:func:`idr_preload_end` after the allocation. + +.. kernel-doc:: include/linux/idr.h + :doc: idr sync + +IDA usage +========= + +.. kernel-doc:: lib/idr.c + :doc: IDA description + +Functions and structures +======================== + +.. kernel-doc:: include/linux/idr.h +.. kernel-doc:: lib/idr.c diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 1b1fd01990b5..c670a8031786 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -16,6 +16,7 @@ Core utilities atomic_ops refcount-vs-atomic cpu_hotplug + idr local_ops workqueue genericirq diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index e7fadf02c511..ff335f8aeb39 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -103,18 +103,6 @@ CRC Functions .. kernel-doc:: lib/crc-itu-t.c :export: -idr/ida Functions ------------------ - -.. kernel-doc:: include/linux/idr.h - :doc: idr sync - -.. kernel-doc:: lib/idr.c - :doc: IDA description - -.. kernel-doc:: lib/idr.c - :export: - Math Functions in Linux ======================= -- cgit From 78ed78451963d1a4282bcda92059fdf2a7821401 Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Tue, 6 Feb 2018 11:51:19 -0500 Subject: Documentation/process: tweak pgp maintainer guide Based on the feedback provided: - Uniformly use lowercase k in "Linux kernel" - Give a one-sentence explanation of what subkeys are - Explain what signed commits might be useful for even if upstream developers do not use them for much of anything - Admonish to set up gpg-agent if signed commits are turned on in git config - Fix a typo reported by Luc Van Oostenryck Signed-off-by: Konstantin Ryabitsev Signed-off-by: Jonathan Corbet --- Documentation/process/maintainer-pgp-guide.rst | 50 +++++++++++++++++--------- 1 file changed, 34 insertions(+), 16 deletions(-) (limited to 'Documentation') diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 28674eb42b95..b453561a7148 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -18,10 +18,10 @@ The role of PGP in Linux Kernel development =========================================== PGP helps ensure the integrity of the code that is produced by the Linux -Kernel development community and, to a lesser degree, establish trusted +kernel development community and, to a lesser degree, establish trusted communication channels between developers via PGP-signed email exchange. -The Linux Kernel source code is available in two main formats: +The Linux kernel source code is available in two main formats: - Distributed source repositories (git) - Periodic release snapshots (tarballs) @@ -53,7 +53,7 @@ want to make sure that by placing trust into developers we do not simply shift the blame for potential future security incidents to someone else. The goal is to provide a set of guidelines developers can use to create a secure working environment and safeguard the PGP keys used to -establish the integrity of the Linux Kernel itself. +establish the integrity of the Linux kernel itself. .. _pgp_tools: @@ -139,7 +139,7 @@ Protect your master PGP key =========================== This guide assumes that you already have a PGP key that you use for Linux -Kernel development purposes. If you do not yet have one, please see the +kernel development purposes. If you do not yet have one, please see the "`Protecting Code Integrity`_" document mentioned earlier for guidance on how to create a new one. @@ -149,7 +149,9 @@ You should also make a new key if your current one is weaker than 2048 bits Master key vs. Subkeys ---------------------- -It is important to understand the following: +Subkeys are fully independent PGP keypairs that are tied to the "master" +key using certifying key signatures (certificates). It is important to +understand the following: 1. There are no technical differences between the "master key" and "subkeys." 2. At creation time, we assign functional limitations to each key by @@ -742,17 +744,29 @@ How to work with signed commits ------------------------------- It is easy to create signed commits, but it is much more difficult to -use them in Linux Kernel development, since it relies on patches sent to +use them in Linux kernel development, since it relies on patches sent to the mailing list, and this workflow does not preserve PGP commit -signatures. - -If you have your working git tree publicly available at some git hosting -service (kernel.org, infradead.org, ozlabs.org, or others), then the -recommendation is that you sign all your git commits even if upstream -developers do not directly benefit from this practice. Should there ever -be a need to perform code forensics or track code provenance, even -externally maintained trees carrying PGP commit signatures will be -extremely valuable for such purposes. +signatures. Furthermore, when rebasing your repository to match +upstream, even your own PGP commit signatures will end up discarded. For +this reason, most kernel developers don't bother signing their commits +and will ignore signed commits in any external repositories that they +rely upon in their work. + +However, if you have your working git tree publicly available at some +git hosting service (kernel.org, infradead.org, ozlabs.org, or others), +then the recommendation is that you sign all your git commits even if +upstream developers do not directly benefit from this practice. + +We recommend this for the following reasons: + +1. Should there ever be a need to perform code forensics or track code + provenance, even externally maintained trees carrying PGP commit + signatures will be valuable for such purposes. +2. If you ever need to re-clone your local repository (for example, + after a disk failure), this lets you easily verify the repository + integrity before resuming your work. +3. If someone needs to cherry-pick your commits, this allows them to + quickly verify their integrity before applying them. Creating signed commits ~~~~~~~~~~~~~~~~~~~~~~~ @@ -770,6 +784,10 @@ You can tell git to always sign commits:: git config --global commit.gpgSign true +.. note:: + + Make sure you configure ``gpg-agent`` before you turn this on. + .. _verify_identities: How to verify kernel developer identities @@ -882,7 +900,7 @@ Locate the ID of the master key in the output, in our example ``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you have on your keyring:: - $ git --list-key torvalds@kernel.org + $ gpg --list-key torvalds@kernel.org pub rsa2048 2011-09-20 [SC] ABAF11C65A2970B130ABE3C479BE3E4300411886 uid [ unknown] Linus Torvalds -- cgit From 60c3e026d73ccabb075fb70ba02f8512ab40cf2c Mon Sep 17 00:00:00 2001 From: Kangmin Park Date: Tue, 6 Feb 2018 15:42:44 -0800 Subject: Documentation/sysctl/user.txt: fix typo Fix 'documetation' to 'documentation' Link: http://lkml.kernel.org/r/CAKW4uUxRPZz59aWAX8ytaCB5=Qh6d_CvAnO7rYq-6NRAnQJbDA@mail.gmail.com Signed-off-by: Kangmin Park Reviewed-by: Andrew Morton Cc: Jiri Kosina Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/sysctl/user.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/sysctl/user.txt b/Documentation/sysctl/user.txt index 1291c498f78f..a5882865836e 100644 --- a/Documentation/sysctl/user.txt +++ b/Documentation/sysctl/user.txt @@ -3,7 +3,7 @@ Documentation for /proc/sys/user/* kernel version 4.9.0 ============================================================== -This file contains the documetation for the sysctl files in +This file contains the documentation for the sysctl files in /proc/sys/user. The files in this directory can be used to override the default -- cgit From 0231d00082f61cfe03f2b7c27e5356f8cdf0312c Mon Sep 17 00:00:00 2001 From: Prarit Bhargava Date: Thu, 18 Jan 2018 10:09:51 -0500 Subject: ACPI: SPCR: Make SPCR available to x86 SPCR is currently only enabled or ARM64 and x86 can use SPCR to setup an early console. General fixes include updating Documentation & Kconfig (for x86), updating comments, and changing parse_spcr() to acpi_parse_spcr(), and earlycon_init_is_deferred to earlycon_acpi_spcr_enable to be more descriptive. On x86, many systems have a valid SPCR table but the table version is not 2 so the table version check must be a warning. On ARM64 when the kernel parameter earlycon is used both the early console and console are enabled. On x86, only the earlycon should be enabled by by default. Modify acpi_parse_spcr() to allow options for initializing the early console and console separately. Signed-off-by: Prarit Bhargava Acked-by: Ingo Molnar Reviewed-by: Mark Salter Tested-by: Mark Salter Signed-off-by: Rafael J. Wysocki --- Documentation/admin-guide/kernel-parameters.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 1bdcf572c2ac..aecb1c8ef675 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -917,9 +917,12 @@ earlycon= [KNL] Output early console device and options. - When used with no options, the early console is - determined by the stdout-path property in device - tree's chosen node. + [ARM64] The early console is determined by the + stdout-path property in device tree's chosen node, + or determined by the ACPI SPCR table. + + [X86] When used with no options the early console is + determined by the ACPI SPCR table. cdns,[,options] Start an early, polled-mode console on a Cadence -- cgit From ffd81dcfef85a33729f90e4acd2f61a68e56b993 Mon Sep 17 00:00:00 2001 From: Dominik Brodowski Date: Tue, 30 Jan 2018 06:42:37 +0100 Subject: cpufreq: Add and use cpufreq_for_each_{valid_,}entry_idx() Pointer subtraction is slow and tedious. Therefore, replace all instances where cpufreq_for_each_{valid_,}entry loops contained such substractions with an iteration macro providing an index to the frequency_table entry. Suggested-by: Al Viro Link: http://lkml.kernel.org/r/20180120020237.GM13338@ZenIV.linux.org.uk Acked-by: Viresh Kumar Signed-off-by: Dominik Brodowski Signed-off-by: Rafael J. Wysocki --- Documentation/cpu-freq/cpu-drivers.txt | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation') diff --git a/Documentation/cpu-freq/cpu-drivers.txt b/Documentation/cpu-freq/cpu-drivers.txt index 434c49cc7330..61546ac578d6 100644 --- a/Documentation/cpu-freq/cpu-drivers.txt +++ b/Documentation/cpu-freq/cpu-drivers.txt @@ -291,3 +291,7 @@ For example: /* Do something with pos */ pos->frequency = ... } + +If you need to work with the position of pos within driver_freq_table, +do not subtract the pointers, as it is quite costly. Instead, use the +macros cpufreq_for_each_entry_idx() and cpufreq_for_each_valid_entry_idx(). -- cgit From aece34cd576c7625181b0488a8129c1e165355f7 Mon Sep 17 00:00:00 2001 From: Paul Burton Date: Fri, 19 Jan 2018 16:40:48 +0100 Subject: dt-bindings: Document mti,mips-cpc binding Document a binding for the MIPS Cluster Power Controller (CPC) that allows the device tree to specify where the CPC registers are located. Signed-off-by: Paul Burton Signed-off-by: Aleksandar Markovic Reviewed-by: Rob Herring Cc: linux-mips@linux-mips.org Cc: devicetree@vger.kernel.org Patchwork: https://patchwork.linux-mips.org/patch/18512/ Signed-off-by: James Hogan --- Documentation/devicetree/bindings/power/mti,mips-cpc.txt | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 Documentation/devicetree/bindings/power/mti,mips-cpc.txt (limited to 'Documentation') diff --git a/Documentation/devicetree/bindings/power/mti,mips-cpc.txt b/Documentation/devicetree/bindings/power/mti,mips-cpc.txt new file mode 100644 index 000000000000..c6b82511ae8a --- /dev/null +++ b/Documentation/devicetree/bindings/power/mti,mips-cpc.txt @@ -0,0 +1,8 @@ +Binding for MIPS Cluster Power Controller (CPC). + +This binding allows a system to specify where the CPC registers are +located. + +Required properties: +compatible : Should be "mti,mips-cpc". +regs: Should describe the address & size of the CPC register region. -- cgit From 6a546c7e69ff0b69581377cc70d7e8a601b98fce Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Fri, 9 Feb 2018 15:30:56 -0500 Subject: membarrier-sync-core: Document architecture support Ensure we gather architecture requirements about each architecture supporting the "sync_core" membarrier command in a single file under Documentation/features. Signed-off-by: Mathieu Desnoyers Cc: Andrea Parri Cc: Andrew Hunter Cc: Andy Lutomirski Cc: Avi Kivity Cc: Benjamin Herrenschmidt Cc: Boqun Feng Cc: Dave Watson Cc: David Sehr Cc: Greg Hackmann Cc: Linus Torvalds Cc: Maged Michael Cc: Michael Ellerman Cc: Paul E. McKenney Cc: Paul Mackerras Cc: Peter Zijlstra (Intel) Cc: Peter Zijlstra Cc: Russell King Cc: Thomas Gleixner Cc: Will Deacon Cc: linux-api@vger.kernel.org Cc: linux-arch@vger.kernel.org Link: http://lkml.kernel.org/r/1518208256-22034-1-git-send-email-mathieu.desnoyers@efficios.com Signed-off-by: Ingo Molnar --- .../sched/membarrier-sync-core/arch-support.txt | 62 ++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 Documentation/features/sched/membarrier-sync-core/arch-support.txt (limited to 'Documentation') diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt new file mode 100644 index 000000000000..2c815a7f1ba7 --- /dev/null +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -0,0 +1,62 @@ +# +# Feature name: membarrier-sync-core +# Kconfig: ARCH_HAS_MEMBARRIER_SYNC_CORE +# description: arch supports core serializing membarrier +# +# Architecture requirements +# +# * arm64 +# +# Rely on eret context synchronization when returning from IPI handler, and +# when returning to user-space. +# +# * x86 +# +# x86-32 uses IRET as return from interrupt, which takes care of the IPI. +# However, it uses both IRET and SYSEXIT to go back to user-space. The IRET +# instruction is core serializing, but not SYSEXIT. +# +# x86-64 uses IRET as return from interrupt, which takes care of the IPI. +# However, it can return to user-space through either SYSRETL (compat code), +# SYSRETQ, or IRET. +# +# Given that neither SYSRET{L,Q}, nor SYSEXIT, are core serializing, we rely +# instead on write_cr3() performed by switch_mm() to provide core serialization +# after changing the current mm, and deal with the special case of kthread -> +# uthread (temporarily keeping current mm into active_mm) by issuing a +# sync_core_before_usermode() in that specific case. +# + ----------------------- + | arch |status| + ----------------------- + | alpha: | TODO | + | arc: | TODO | + | arm: | TODO | + | arm64: | ok | + | blackfin: | TODO | + | c6x: | TODO | + | cris: | TODO | + | frv: | TODO | + | h8300: | TODO | + | hexagon: | TODO | + | ia64: | TODO | + | m32r: | TODO | + | m68k: | TODO | + | metag: | TODO | + | microblaze: | TODO | + | mips: | TODO | + | mn10300: | TODO | + | nios2: | TODO | + | openrisc: | TODO | + | parisc: | TODO | + | powerpc: | TODO | + | s390: | TODO | + | score: | TODO | + | sh: | TODO | + | sparc: | TODO | + | tile: | TODO | + | um: | TODO | + | unicore32: | TODO | + | x86: | ok | + | xtensa: | TODO | + ----------------------- -- cgit From 79e902382637a2f421b7f295dcf9934d80d84d7d Mon Sep 17 00:00:00 2001 From: Juri Lelli Date: Fri, 9 Feb 2018 17:01:14 +0100 Subject: Documentation/locking/mutex-design: Update to reflect latest changes Commit 3ca0ff571b09 ("locking/mutex: Rework mutex::owner") reworked the basic mutex implementation to deal with several problems. Documentation was however left unchanged and became stale. Update mutex-design.txt to reflect changes introduced by the above commit. Signed-off-by: Juri Lelli Cc: Andrew Morton Cc: Davidlohr Bueso Cc: Jonathan Corbet Cc: Linus Torvalds Cc: Paul E. McKenney Cc: Peter Zijlstra Cc: Thomas Gleixner Cc: linux-doc@vger.kernel.org Link: http://lkml.kernel.org/r/20180209160114.19980-1-juri.lelli@redhat.com [ Small readability tweaks to the text. ] Signed-off-by: Ingo Molnar --- Documentation/locking/mutex-design.txt | 49 ++++++++++++---------------------- 1 file changed, 17 insertions(+), 32 deletions(-) (limited to 'Documentation') diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.txt index 60c482df1a38..818aca19612f 100644 --- a/Documentation/locking/mutex-design.txt +++ b/Documentation/locking/mutex-design.txt @@ -21,37 +21,23 @@ Implementation -------------- Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h -and implemented in kernel/locking/mutex.c. These locks use a three -state atomic counter (->count) to represent the different possible -transitions that can occur during the lifetime of a lock: - - 1: unlocked - 0: locked, no waiters - negative: locked, with potential waiters - -In its most basic form it also includes a wait-queue and a spinlock -that serializes access to it. CONFIG_SMP systems can also include -a pointer to the lock task owner (->owner) as well as a spinner MCS -lock (->osq), both described below in (ii). +and implemented in kernel/locking/mutex.c. These locks use an atomic variable +(->owner) to keep track of the lock state during its lifetime. Field owner +actually contains 'struct task_struct *' to the current lock owner and it is +therefore NULL if not currently owned. Since task_struct pointers are aligned +at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., +if waiter list is non-empty). In its most basic form it also includes a +wait-queue and a spinlock that serializes access to it. Furthermore, +CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described +below in (ii). When acquiring a mutex, there are three possible paths that can be taken, depending on the state of the lock: -(i) fastpath: tries to atomically acquire the lock by decrementing the - counter. If it was already taken by another task it goes to the next - possible path. This logic is architecture specific. On x86-64, the - locking fastpath is 2 instructions: - - 0000000000000e10 : - e21: f0 ff 0b lock decl (%rbx) - e24: 79 08 jns e2e - - the unlocking fastpath is equally tight: - - 0000000000000bc0 : - bc8: f0 ff 07 lock incl (%rdi) - bcb: 7f 0a jg bd7 - +(i) fastpath: tries to atomically acquire the lock by cmpxchg()ing the owner with + the current task. This only works in the uncontended case (cmpxchg() checks + against 0UL, so all 3 state bits above have to be 0). If the lock is + contended it goes to the next possible path. (ii) midpath: aka optimistic spinning, tries to spin for acquisition while the lock owner is running and there are no other tasks ready @@ -143,11 +129,10 @@ Test if the mutex is taken: Disadvantages ------------- -Unlike its original design and purpose, 'struct mutex' is larger than -most locks in the kernel. E.g: on x86-64 it is 40 bytes, almost twice -as large as 'struct semaphore' (24 bytes) and tied, along with rwsems, -for the largest lock in the kernel. Larger structure sizes mean more -CPU cache and memory footprint. +Unlike its original design and purpose, 'struct mutex' is among the largest +locks in the kernel. E.g: on x86-64 it is 32 bytes, where 'struct semaphore' +is 24 bytes and rw_semaphore is 40 bytes. Larger structure sizes mean more CPU +cache and memory footprint. When to use mutexes ------------------- -- cgit From b6d8ef86cb7b8b6920b6815ebf1352757d3adb87 Mon Sep 17 00:00:00 2001 From: Aishwarya Pant Date: Wed, 7 Feb 2018 19:04:36 +0530 Subject: Documentation/ABI: update cpuidle sysfs documentation Update cpuidle documentation using git logs and existing documentation in Documentation/cpuidle/sysfs.txt. This might be useful for scripting and tracking changes in the ABI. Signed-off-by: Aishwarya Pant Signed-off-by: Rafael J. Wysocki --- Documentation/ABI/testing/sysfs-devices-system-cpu | 77 +++++++++++++++++++++- 1 file changed, 75 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index bfd29bc8d37a..4ed63b6cfb15 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -108,6 +108,8 @@ Description: CPU topology files that describe a logical CPU's relationship What: /sys/devices/system/cpu/cpuidle/current_driver /sys/devices/system/cpu/cpuidle/current_governer_ro + /sys/devices/system/cpu/cpuidle/available_governors + /sys/devices/system/cpu/cpuidle/current_governor Date: September 2007 Contact: Linux kernel mailing list Description: Discover cpuidle policy and mechanism @@ -119,13 +121,84 @@ Description: Discover cpuidle policy and mechanism Idle policy (governor) is differentiated from idle mechanism (driver) - current_driver: displays current idle mechanism + current_driver: (RO) displays current idle mechanism - current_governor_ro: displays current idle policy + current_governor_ro: (RO) displays current idle policy + + With the cpuidle_sysfs_switch boot option enabled (meant for + developer testing), the following three attributes are visible + instead: + + current_driver: same as described above + + available_governors: (RO) displays a space separated list of + available governors + + current_governor: (RW) displays current idle policy. Users can + switch the governor at runtime by writing to this file. See files in Documentation/cpuidle/ for more information. +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/name + /sys/devices/system/cpu/cpuX/cpuidle/stateN/latency + /sys/devices/system/cpu/cpuX/cpuidle/stateN/power + /sys/devices/system/cpu/cpuX/cpuidle/stateN/time + /sys/devices/system/cpu/cpuX/cpuidle/stateN/usage +Date: September 2007 +KernelVersion: v2.6.24 +Contact: Linux power management list +Description: + The directory /sys/devices/system/cpu/cpuX/cpuidle contains per + logical CPU specific cpuidle information for each online cpu X. + The processor idle states which are available for use have the + following attributes: + + name: (RO) Name of the idle state (string). + + latency: (RO) The latency to exit out of this idle state (in + microseconds). + + power: (RO) The power consumed while in this idle state (in + milliwatts). + + time: (RO) The total time spent in this idle state (in microseconds). + + usage: (RO) Number of times this state was entered (a count). + + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/desc +Date: February 2008 +KernelVersion: v2.6.25 +Contact: Linux power management list +Description: + (RO) A small description about the idle state (string). + + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/disable +Date: March 2012 +KernelVersion: v3.10 +Contact: Linux power management list +Description: + (RW) Option to disable this idle state (bool). The behavior and + the effect of the disable variable depends on the implementation + of a particular governor. In the ladder governor, for example, + it is not coherent, i.e. if one is disabling a light state, then + all deeper states are disabled as well, but the disable variable + does not reflect it. Likewise, if one enables a deep state but a + lighter state still is disabled, then this has no effect. + + +What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/residency +Date: March 2014 +KernelVersion: v3.15 +Contact: Linux power management list +Description: + (RO) Display the target residency i.e. the minimum amount of + time (in microseconds) this cpu should spend in this idle state + to make the transition worth the effort. + + What: /sys/devices/system/cpu/cpu#/cpufreq/* Date: pre-git history Contact: linux-pm@vger.kernel.org -- cgit From 6b4af818c7d7a35a861c94596e05e43596e5fd28 Mon Sep 17 00:00:00 2001 From: Aishwarya Pant Date: Sat, 10 Feb 2018 14:27:19 +0530 Subject: ACPI / DPTF: Document dptf_power sysfs atttributes The descriptions have been collected from git commit logs and reading through code. Signed-off-by: Aishwarya Pant Signed-off-by: Rafael J. Wysocki --- Documentation/ABI/testing/sysfs-platform-dptf | 40 +++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-platform-dptf (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf new file mode 100644 index 000000000000..325dc0667dbb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-dptf @@ -0,0 +1,40 @@ +What: /sys/bus/platform/devices/INT3407:00/dptf_power/charger_type +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) The charger type - Traditional, Hybrid or NVDC. + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/adapter_rating_mw +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Adapter rating in milliwatts (the maximum Adapter power). + Must be 0 if no AC Adaptor is plugged in. + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/max_platform_power_mw +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Maximum platform power that can be supported by the battery + in milliwatts. + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/platform_power_source +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Display the platform power source + 0x00 = DC + 0x01 = AC + 0x02 = USB + 0x03 = Wireless Charger + +What: /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power +Date: Jul, 2016 +KernelVersion: v4.10 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) The maximum sustained power for battery in milliwatts. -- cgit From 22029845ad81033115910cdef35170de6a10a1eb Mon Sep 17 00:00:00 2001 From: Aishwarya Pant Date: Sat, 10 Feb 2018 14:27:38 +0530 Subject: ACPI: dock: document sysfs interface Description has been collected from git commit history and reading through code. Signed-off-by: Aishwarya Pant Signed-off-by: Rafael J. Wysocki --- .../ABI/testing/sysfs-devices-platform-dock | 39 ++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-devices-platform-dock (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-devices-platform-dock b/Documentation/ABI/testing/sysfs-devices-platform-dock new file mode 100644 index 000000000000..1d8c18f905c7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-dock @@ -0,0 +1,39 @@ +What: /sys/devices/platform/dock.N/docked +Date: Dec, 2006 +KernelVersion: 2.6.19 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Value 1 or 0 indicates whether the software believes the + laptop is docked in a docking station. + +What: /sys/devices/platform/dock.N/undock +Date: Dec, 2006 +KernelVersion: 2.6.19 +Contact: linux-acpi@vger.kernel.org +Description: + (WO) Writing to this file causes the software to initiate an + undock request to the firmware. + +What: /sys/devices/platform/dock.N/uid +Date: Feb, 2007 +KernelVersion: v2.6.21 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Displays the docking station the laptop is docked to. + +What: /sys/devices/platform/dock.N/flags +Date: May, 2007 +KernelVersion: v2.6.21 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Show dock station flags, useful for checking if undock + request has been made by the user (from the immediate_undock + option). + +What: /sys/devices/platform/dock.N/type +Date: Aug, 2008 +KernelVersion: v2.6.27 +Contact: linux-acpi@vger.kernel.org +Description: + (RO) Display the dock station type- dock_station, ata_bay or + battery_bay. -- cgit From 61e02392d3c7ecac1f91c0a90a8043d67e081846 Mon Sep 17 00:00:00 2001 From: Will Deacon Date: Tue, 13 Feb 2018 13:30:19 +0000 Subject: locking/atomic/bitops: Document and clarify ordering semantics for failed test_and_{}_bit() A test_and_{}_bit() operation fails if the value of the bit is such that the modification does not take place. For example, if test_and_set_bit() returns 1. In these cases, follow the behaviour of cmpxchg and allow the operation to be unordered. This also applies to test_and_set_bit_lock() if the lock is found to be be taken already. Signed-off-by: Will Deacon Acked-by: Peter Zijlstra (Intel) Cc: Linus Torvalds Cc: Paul E. McKenney Cc: Thomas Gleixner Link: http://lkml.kernel.org/r/1518528619-20049-1-git-send-email-will.deacon@arm.com Signed-off-by: Ingo Molnar --- Documentation/atomic_bitops.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt index 5550bfdcce5f..be70b32c95d9 100644 --- a/Documentation/atomic_bitops.txt +++ b/Documentation/atomic_bitops.txt @@ -58,7 +58,12 @@ Like with atomic_t, the rule of thumb is: - RMW operations that have a return value are fully ordered. -Except for test_and_set_bit_lock() which has ACQUIRE semantics and + - RMW operations that are conditional are unordered on FAILURE, + otherwise the above rules apply. In the case of test_and_{}_bit() operations, + if the bit in memory is unchanged by the operation then it is deemed to have + failed. + +Except for a successful test_and_set_bit_lock() which has ACQUIRE semantics and clear_bit_unlock() which has RELEASE semantics. Since a platform only has a single means of achieving atomic operations -- cgit