diff options
Diffstat (limited to 'Documentation')
1081 files changed, 35073 insertions, 10834 deletions
diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill deleted file mode 100644 index ff60ad9eca4c..000000000000 --- a/Documentation/ABI/obsolete/sysfs-class-rfkill +++ /dev/null @@ -1,29 +0,0 @@ -rfkill - radio frequency (RF) connector kill switch support - -For details to this subsystem look at Documentation/rfkill.txt. - -What: /sys/class/rfkill/rfkill[0-9]+/state -Date: 09-Jul-2007 -KernelVersion v2.6.22 -Contact: linux-wireless@vger.kernel.org -Description: Current state of the transmitter. - This file is deprecated and scheduled to be removed in 2014, - because its not possible to express the 'soft and hard block' - state of the rfkill driver. -Values: A numeric value. - 0: RFKILL_STATE_SOFT_BLOCKED - transmitter is turned off by software - 1: RFKILL_STATE_UNBLOCKED - transmitter is (potentially) active - 2: RFKILL_STATE_HARD_BLOCKED - transmitter is forced off by something outside of - the driver's control. - -What: /sys/class/rfkill/rfkill[0-9]+/claim -Date: 09-Jul-2007 -KernelVersion v2.6.22 -Contact: linux-wireless@vger.kernel.org -Description: This file is deprecated because there no longer is a way to - claim just control over a single rfkill instance. - This file is scheduled to be removed in 2012. -Values: 0: Kernel handles events diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo index 55e281b0071a..55e281b0071a 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-arvo +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku index c601d0f2ac46..c601d0f2ac46 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus index 833fd59926a7..545e69f43229 100644 --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus @@ -1,3 +1,14 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/actual_profile +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the actual + profile. This value is persistent, so its equivalent to the + profile that's active when the mouse is powered on next time. + When written, this file sets the number of the startup profile + and the mouse activates this profile immediately. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/startup_profile Date: October 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -22,6 +33,40 @@ Description: When read, this file returns the raw integer version number of the Please read binary attribute info which contains firmware version. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/info +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 8 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store a macro with max 500 key/button strokes + internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 2082 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 77 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_buttons Date: August 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -34,6 +79,22 @@ Description: The mouse can store 5 profiles which can be switched by the Write control to select profile and read profile_buttons instead. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 43 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_settings Date: August 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -45,4 +106,40 @@ Description: The mouse can store 5 profiles which can be switched by the The returned data is 43 bytes in size. This file is readonly. Write control to select profile and read profile_settings instead. -Users: http://roccat.sourceforge.net
\ No newline at end of file +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a tracking- and a distance-control-unit. These + can be activated/deactivated and the lift-off distance can be + set. The data has to be 6 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/talk +Date: May 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: Used to active some easy* functions of the mouse from outside. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written a calibration process for the tracking control unit + can be initiated/cancelled. Also lets one read/write sensor + registers. + The data has to be 4 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read the mouse returns a 30x30 pixel image of the + sampled underground. This works only in the course of a + calibration process initiated with tcu. + The returned data is 1028 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure index 41a9b7fbfc79..41a9b7fbfc79 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus index 4a98e02b6c6a..ab01631e1e0f 100644 --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus @@ -8,6 +8,17 @@ Description: The integer value of this attribute ranges from 1-4. Has never been used. If bookkeeping is done, it's done in userland tools. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the active + profile. + When written, the mouse activates this profile immediately. + The profile that's active when powered down is the same that's + active when the mouse is powered on. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_x Date: January 2011 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -40,6 +51,29 @@ Description: When read, this file returns the raw integer version number of the Obsoleted by binary sysfs attribute "info". Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/info +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 23 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_buttons Date: January 2011 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -52,6 +86,22 @@ Description: The mouse can store 5 profiles which can be switched by the Write control to select profile and read profile_buttons instead. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 16 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_settings Date: January 2011 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua index 31c6c4c8ba2b..31c6c4c8ba2b 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra index 87ac87e9556d..16020b31ae64 100644 --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra @@ -37,6 +37,29 @@ Description: When read, this file returns the raw integer version number of the Please use binary attribute "info" which provides this information. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 19 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_buttons Date: August 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -49,6 +72,22 @@ Description: The mouse can store 5 profiles which can be switched by the Write control to select profile and read profile_buttons instead. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 13 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_settings Date: August 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -62,6 +101,17 @@ Description: The mouse can store 5 profiles which can be switched by the Write control to select profile and read profile_settings instead. Users: http://roccat.sourceforge.net +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the settings stored in the mouse. + The size of the data is 3 bytes and holds information on the + startup_profile. + When written, this file lets write settings back to the mouse. + The data has to be 3 bytes long. The mouse will reject invalid + data. +Users: http://roccat.sourceforge.net + What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/startup_profile Date: August 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-ryos b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos index 1d6a8cf9dc0a..1d6a8cf9dc0a 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-ryos +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu index f1e02a98bd9d..f1e02a98bd9d 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu diff --git a/Documentation/ABI/testing/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio index 55ffa2df1c10..867c1fab20e2 100644 --- a/Documentation/ABI/testing/sysfs-gpio +++ b/Documentation/ABI/obsolete/sysfs-gpio @@ -1,7 +1,7 @@ What: /sys/class/gpio/ Date: July 2008 KernelVersion: 2.6.27 -Contact: David Brownell <dbrownell@users.sourceforge.net> +Contact: Linus Walleij <linusw@kernel.org> Description: As a Kconfig option, individual GPIO signals may be accessed from @@ -26,3 +26,5 @@ Description: /label ... (r/o) descriptive, not necessarily unique /ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1) + This ABI is deprecated and will be removed after 2020. It is + replaced with the GPIO character device. diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill new file mode 100644 index 000000000000..3ce6231f20b2 --- /dev/null +++ b/Documentation/ABI/removed/sysfs-class-rfkill @@ -0,0 +1,13 @@ +rfkill - radio frequency (RF) connector kill switch support + +For details to this subsystem look at Documentation/rfkill.txt. + +What: /sys/class/rfkill/rfkill[0-9]+/claim +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: This file was deprecated because there no longer was a way to + claim just control over a single rfkill instance. + This file was scheduled to be removed in 2012, and was removed + in 2016. +Values: 0: Kernel handles events diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index 636e938d5e33..5d0125f7bcaf 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -27,3 +27,17 @@ Description: The mapping of which primary/sub channels are bound to which Virtual Processors. Format: <channel's child_relid:the bound cpu's number> Users: tools/hv/lsvmbus + +What: /sys/bus/vmbus/devices/vmbus_*/device +Date: Dec. 2015 +KernelVersion: 4.5 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The 16 bit device ID of the device +Users: tools/hv/lsvmbus and user level RDMA libraries + +What: /sys/bus/vmbus/devices/vmbus_*/vendor +Date: Dec. 2015 +KernelVersion: 4.5 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The 16 bit vendor ID of the device +Users: tools/hv/lsvmbus and user level RDMA libraries diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill index 097f522c33bb..e1ba4a104753 100644 --- a/Documentation/ABI/stable/sysfs-class-rfkill +++ b/Documentation/ABI/stable/sysfs-class-rfkill @@ -2,9 +2,8 @@ rfkill - radio frequency (RF) connector kill switch support For details to this subsystem look at Documentation/rfkill.txt. -For the deprecated /sys/class/rfkill/*/state and -/sys/class/rfkill/*/claim knobs of this interface look in -Documentation/ABI/obsolete/sysfs-class-rfkill. +For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in +Documentation/ABI/removed/sysfs-class-rfkill. What: /sys/class/rfkill Date: 09-Jul-2007 @@ -42,6 +41,28 @@ Values: A numeric value. 1: true +What: /sys/class/rfkill/rfkill[0-9]+/state +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Current state of the transmitter. + This file was scheduled to be removed in 2014, but due to its + large number of users it will be sticking around for a bit + longer. Despite it being marked as stabe, the newer "hard" and + "soft" interfaces should be preffered, since it is not possible + to express the 'soft and hard block' state of the rfkill driver + through this interface. There will likely be another attempt to + remove it in the future. +Values: A numeric value. + 0: RFKILL_STATE_SOFT_BLOCKED + transmitter is turned off by software + 1: RFKILL_STATE_UNBLOCKED + transmitter is (potentially) active + 2: RFKILL_STATE_HARD_BLOCKED + transmitter is forced off by something outside of + the driver's control. + + What: /sys/class/rfkill/rfkill[0-9]+/hard Date: 12-March-2010 KernelVersion v2.6.34 diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm index 9f790eebb5d2..c0e23830f56a 100644 --- a/Documentation/ABI/stable/sysfs-class-tpm +++ b/Documentation/ABI/stable/sysfs-class-tpm @@ -116,7 +116,7 @@ Description: The "pubek" property will return the TPM's public endorsement owner's authorization. Since the TPM driver doesn't store any secrets, it can't authorize its own request for the pubek, making it unaccessible. The public endorsement key is gener- - ated at TPM menufacture time and exists for the life of the + ated at TPM manufacture time and exists for the life of the chip. Example output: @@ -163,7 +163,7 @@ Date: April 2006 KernelVersion: 2.6.17 Contact: tpmdd-devel@lists.sf.net Description: The "temp_deactivated" property returns a '1' if the chip has - been temporarily dectivated, usually until the next power + been temporarily deactivated, usually until the next power cycle. Whether a warm boot (reboot) will clear a TPM chip from a temp_deactivated state is platform specific. diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog index e1f3058f5954..2536434d49d0 100644 --- a/Documentation/ABI/stable/sysfs-firmware-opal-elog +++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog @@ -57,4 +57,4 @@ Description: Shortly after acknowledging it, the log entry will be removed from sysfs. Reading this file will list the supported - operations (curently just acknowledge).
\ No newline at end of file + operations (currently just acknowledge). diff --git a/Documentation/ABI/testing/configfs-iio b/Documentation/ABI/testing/configfs-iio new file mode 100644 index 000000000000..2483756fccf5 --- /dev/null +++ b/Documentation/ABI/testing/configfs-iio @@ -0,0 +1,21 @@ +What: /config/iio +Date: October 2015 +KernelVersion: 4.4 +Contact: linux-iio@vger.kernel.org +Description: + This represents Industrial IO configuration entry point + directory. It contains sub-groups corresponding to IIO + objects. + +What: /config/iio/triggers +Date: October 2015 +KernelVersion: 4.4 +Description: + Industrial IO software triggers directory. + +What: /config/iio/triggers/hrtimers +Date: October 2015 +KernelVersion: 4.4 +Description: + High resolution timers directory. Creating a directory here + will result in creating a hrtimer trigger in the IIO subsystem. diff --git a/Documentation/ABI/testing/configfs-rdma_cm b/Documentation/ABI/testing/configfs-rdma_cm new file mode 100644 index 000000000000..5c389aaf5291 --- /dev/null +++ b/Documentation/ABI/testing/configfs-rdma_cm @@ -0,0 +1,22 @@ +What: /config/rdma_cm +Date: November 29, 2015 +KernelVersion: 4.4.0 +Description: Interface is used to configure RDMA-cable HCAs in respect to + RDMA-CM attributes. + + Attributes are visible only when configfs is mounted. To mount + configfs in /config directory use: + # mount -t configfs none /config/ + + In order to set parameters related to a specific HCA, a directory + for this HCA has to be created: + mkdir -p /config/rdma_cm/<hca> + + +What: /config/rdma_cm/<hca>/ports/<port-num>/default_roce_mode +Date: November 29, 2015 +KernelVersion: 4.4.0 +Description: RDMA-CM based connections from HCA <hca> at port <port-num> + will be initiated with this RoCE type as default. + The possible RoCE types are either "IB/RoCE v1" or "RoCE v2". + This parameter has RW access. diff --git a/Documentation/ABI/testing/configfs-stp-policy b/Documentation/ABI/testing/configfs-stp-policy new file mode 100644 index 000000000000..421ce6825c66 --- /dev/null +++ b/Documentation/ABI/testing/configfs-stp-policy @@ -0,0 +1,48 @@ +What: /config/stp-policy +Date: June 2015 +KernelVersion: 4.3 +Description: + This group contains policies mandating Master/Channel allocation + for software sources wishing to send trace data over an STM + device. + +What: /config/stp-policy/<device>.<policy> +Date: June 2015 +KernelVersion: 4.3 +Description: + This group is the root of a policy; its name is a concatenation + of an stm device name to which this policy applies and an + arbitrary string. If <device> part doesn't match an existing + stm device, mkdir will fail with ENODEV; if that device already + has a policy assigned to it, mkdir will fail with EBUSY. + +What: /config/stp-policy/<device>.<policy>/device +Date: June 2015 +KernelVersion: 4.3 +Description: + STM device to which this policy applies, read only. Same as the + <device> component of its parent directory. + +What: /config/stp-policy/<device>.<policy>/<node> +Date: June 2015 +KernelVersion: 4.3 +Description: + Policy node is a string identifier that software clients will + use to request a master/channel to be allocated and assigned to + them. + +What: /config/stp-policy/<device>.<policy>/<node>/masters +Date: June 2015 +KernelVersion: 4.3 +Description: + Range of masters from which to allocate for users of this node. + Write two numbers: the first master and the last master number. + +What: /config/stp-policy/<device>.<policy>/<node>/channels +Date: June 2015 +KernelVersion: 4.3 +Description: + Range of channels from which to allocate for users of this node. + Write two numbers: the first channel and the last channel + number. + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink index bc7ff731aa0c..f56335af2d88 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink +++ b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink @@ -10,3 +10,5 @@ Description: isoc_mult - 0..2 (hs/ss only) isoc_maxburst - 0..15 (ss only) buflen - buffer length + bulk_qlen - depth of queue for bulk + iso_qlen - depth of queue for iso diff --git a/Documentation/ABI/testing/configfs-usb-gadget-tcm b/Documentation/ABI/testing/configfs-usb-gadget-tcm new file mode 100644 index 000000000000..a29ed2dd6173 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-tcm @@ -0,0 +1,6 @@ +What: /config/usb-gadget/gadget/functions/tcm.name +Date: Dec 2015 +KernelVersion: 4.5 +Description: + There are no attributes because all the configuration + is performed in the "target" subsystem of configfs. diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev new file mode 100644 index 000000000000..7b265fbb47e3 --- /dev/null +++ b/Documentation/ABI/testing/gpio-cdev @@ -0,0 +1,26 @@ +What: /dev/gpiochip[0-9]+ +Date: November 2015 +KernelVersion: 4.4 +Contact: linux-gpio@vger.kernel.org +Description: + The character device files /dev/gpiochip* are the interface + between GPIO chips and userspace. + + The ioctl(2)-based ABI is defined and documented in + [include/uapi]<linux/gpio.h>. + + The following file operations are supported: + + open(2) + Currently the only useful flags are O_RDWR. + + ioctl(2) + Initiate various actions. + See the inline documentation in [include/uapi]<linux/gpio.h> + for descriptions of all ioctls. + + close(2) + Stops and free up the I/O contexts that was associated + with the file descriptor. + +Users: TBD diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 0a378a88217a..bb0f9a135e21 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -27,6 +27,7 @@ Description: base: func:= [BPRM_CHECK][MMAP_CHECK][FILE_CHECK][MODULE_CHECK] [FIRMWARE_CHECK] + [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] [[^]MAY_EXEC] fsmagic:= hex value diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index 8df003963d99..71d184dbb70d 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -60,6 +60,13 @@ Description: Indicates whether a storage device is capable of storing integrity metadata. Set if the device is T10 PI-capable. +What: /sys/block/<disk>/integrity/protection_interval_bytes +Date: July 2015 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Describes the number of data bytes which are protected + by one integrity tuple. Typically the device's logical + block size. What: /sys/block/<disk>/integrity/write_generate Date: June 2008 diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x index d72ca1736ba4..924265a1295d 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x @@ -8,13 +8,6 @@ Description: (RW) Enable/disable tracing on this specific trace entiry. of coresight components linking the source to the sink is configured and managed automatically by the coresight framework. -What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/status -Date: November 2014 -KernelVersion: 3.19 -Contact: Mathieu Poirier <mathieu.poirier@linaro.org> -Description: (R) List various control and status registers. The specific - layout and content is driver specific. - What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_idx Date: November 2014 KernelVersion: 3.19 @@ -251,3 +244,79 @@ Date: November 2014 KernelVersion: 3.19 Contact: Mathieu Poirier <mathieu.poirier@linaro.org> Description: (RW) Define the event that controls the trigger. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cpu +Date: October 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Holds the cpu number this tracer is affined to. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmccr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Configuration Code register + (0x004). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmccer +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Configuration Code Extension + register (0x1e8). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmscr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM System Configuration + register (0x014). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmidr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM ID register (0x1e4). The + value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmcr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Main Control register (0x000). + The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtraceidr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Trace ID register (0x200). + The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmteevr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Trace Enable Event register + (0x020). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtsscr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Trace Start/Stop Conrol + register (0x018). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr1 +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Enable Conrol #1 + register (0x024). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr2 +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Enable Conrol #2 + register (0x01c). The value is read directly from the HW. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 42d360fe66a5..3c6624881375 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -496,8 +496,11 @@ Description: 1kohm_to_gnd: connected to ground via an 1kOhm resistor, 6kohm_to_gnd: connected to ground via a 6kOhm resistor, 20kohm_to_gnd: connected to ground via a 20kOhm resistor, + 90kohm_to_gnd: connected to ground via a 90kOhm resistor, 100kohm_to_gnd: connected to ground via an 100kOhm resistor, + 125kohm_to_gnd: connected to ground via an 125kOhm resistor, 500kohm_to_gnd: connected to ground via a 500kOhm resistor, + 640kohm_to_gnd: connected to ground via a 640kOhm resistor, three_state: left floating. For a list of available output power down options read outX_powerdown_mode_available. If Y is not present the @@ -581,6 +584,7 @@ What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_rising_en What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_falling_en What: /sys/.../iio:deviceX/events/in_voltageY_thresh_rising_en What: /sys/.../iio:deviceX/events/in_voltageY_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_thresh_either_en What: /sys/.../iio:deviceX/events/in_tempY_thresh_rising_en What: /sys/.../iio:deviceX/events/in_tempY_thresh_falling_en KernelVersion: 2.6.37 @@ -1459,3 +1463,41 @@ Description: measurements and return the average value as output data. Each value resulted from <type>[_name]_oversampling_ratio measurements is considered as one sample for <type>[_name]_sampling_frequency. + +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_co2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_voc_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_voc_raw +KernelVersion: 4.3 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) percentage reading of a substance. + +What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw +What: /sys/bus/iio/devices/iio:deviceX/in_resistanceX_raw +What: /sys/bus/iio/devices/iio:deviceX/out_resistance_raw +What: /sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw +KernelVersion: 4.3 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) resistance reading that can be processed + into an ohm value. + +What: /sys/bus/iio/devices/iio:deviceX/heater_enable +KernelVersion: 4.1.0 +Contact: linux-iio@vger.kernel.org +Description: + '1' (enable) or '0' (disable) specifying the enable + of heater function. Same reading values apply + This ABI is especially applicable for humidity sensors + to heatup the device and get rid of any condensation + in some humidity environment + +What: /sys/bus/iio/devices/iio:deviceX/in_ph_raw +KernelVersion: 4.5 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) pH reading of a substance as a negative + base-10 logarithm of hydrodium ions in a litre of water. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 new file mode 100644 index 000000000000..f30b4c424fb6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 @@ -0,0 +1,43 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sensing_mode +Date: August 2015 +KernelVersion: 4.2.0 +Contact: source@cogentembedded.com +Description: + Program sensor type for threshold detector inputs. + Could be either "GND-Open" or "Supply-Open" mode. Y is a + threshold detector input channel. Channels 0..7, 8..15, 16..23 + and 24..31 has common sensor types. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_voltageY_thresh_falling_value +Date: August 2015 +KernelVersion: 4.2.0 +Contact: source@cogentembedded.com +Description: + Channel Y low voltage threshold. If sensor input voltage goes lower then + this value then the threshold falling event is pushed. + Depending on in_voltageY_sensing_mode the low voltage threshold + is separately set for "GND-Open" and "Supply-Open" modes. + Channels 0..31 have common low threshold values, but could have different + sensing_modes. + The low voltage threshold range is between 2..21V. + Hysteresis between low and high thresholds can not be lower then 2 and + can not be odd. + If falling threshold results hysteresis to odd value then rising + threshold is automatically subtracted by one. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_voltageY_thresh_rising_value +Date: August 2015 +KernelVersion: 4.2.0 +Contact: source@cogentembedded.com +Description: + Channel Y high voltage threshold. If sensor input voltage goes higher then + this value then the threshold rising event is pushed. + Depending on in_voltageY_sensing_mode the high voltage threshold + is separately set for "GND-Open" and "Supply-Open" modes. + Channels 0..31 have common high threshold values, but could have different + sensing_modes. + The high voltage threshold range is between 3..22V. + Hysteresis between low and high thresholds can not be lower then 2 and + can not be odd. + If rising threshold results hysteresis to odd value then falling + threshold is automatically appended by one. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x new file mode 100644 index 000000000000..c0c1ea924535 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x @@ -0,0 +1,7 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_VOC_short_raw +Date: September 2015 +KernelVersion: 4.3 +Contact: Matt Ranostay <mranostay@gmail.com> +Description: + Get the raw calibration VOC value from the sensor. + This value has little application outside of calibration. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x new file mode 100644 index 000000000000..3740f253d406 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x @@ -0,0 +1,54 @@ +What: /sys/bus/iio/devices/iio:deviceX/tia_resistanceY + /sys/bus/iio/devices/iio:deviceX/tia_capacitanceY +Date: December 2015 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get and set the resistance and the capacitance settings for the + Transimpedance Amplifier. Y is 1 for Rf1 and Cf1, Y is 2 for + Rf2 and Cf2 values. + +What: /sys/bus/iio/devices/iio:deviceX/tia_separate_en +Date: December 2015 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Enable or disable separate settings for the TransImpedance + Amplifier above, when disabled both values are set by the + first channel. + +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ledY_raw + /sys/bus/iio/devices/iio:deviceX/in_intensity_ledY_ambient_raw +Date: December 2015 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get measured values from the ADC for these stages. Y is the + specific LED number. The values are expressed in 24-bit twos + complement. + +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_ledY-ledY_ambient_raw +Date: December 2015 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get differential values from the ADC for these stages. Y is the + specific LED number. The values are expressed in 24-bit twos + complement for the specified LEDs. + +What: /sys/bus/iio/devices/iio:deviceX/out_current_ledY_offset + /sys/bus/iio/devices/iio:deviceX/out_current_ledY_ambient_offset +Date: December 2015 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get and set the offset cancellation DAC setting for these + stages. The values are expressed in 5-bit sign-magnitude. + +What: /sys/bus/iio/devices/iio:deviceX/out_current_ledY_raw +Date: December 2015 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get and set the LED current for the specified LED. Y is the + specific LED number. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x new file mode 100644 index 000000000000..b72bb62552cf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x @@ -0,0 +1,9 @@ +What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw +What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available +KernelVersion: 4.3 +Contact: linux-iio@vger.kernel.org +Description: + Controls the heater device within the humidity sensor to get + rid of excess condensation. + + Valid control values are 0 = OFF, and 1 = ON. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc b/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc new file mode 100644 index 000000000000..8916f7ec6507 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc @@ -0,0 +1,24 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_allow_async_readout +Date: December 2015 +KernelVersion: 4.4 +Contact: linux-iio@vger.kernel.org +Description: + By default (value '0'), the capture thread checks for the Conversion + Ready Flag to being set prior to committing a new value to the sample + buffer. This synchronizes the in-chip conversion rate with the + in-driver readout rate at the cost of an additional register read. + + Writing '1' will remove the polling for the Conversion Ready Flags to + save the additional i2c transaction, which will improve the bandwidth + available for reading data. However, samples can be occasionally skipped + or repeated, depending on the beat between the capture and conversion + rates. + +What: /sys/bus/iio/devices/iio:deviceX/in_shunt_resistor +Date: December 2015 +KernelVersion: 4.4 +Contact: linux-iio@vger.kernel.org +Description: + The value of the shunt resistor may be known only at runtime fom an + eeprom content read by a client application. This attribute allows to + set its value in ohms. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 new file mode 100644 index 000000000000..6275e9f56e6c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 @@ -0,0 +1,15 @@ +What: /sys/bus/iio/devices/iio:deviceX/meas_conf +What: /sys/bus/iio/devices/iio:deviceX/meas_conf_available +KernelVersion: 4.5 +Contact: linux-iio@vger.kernel.org +Description: + Current configuration and available configurations + for the bias current. + normal - Normal measurement configurations (default) + positivebias - Positive bias configuration + negativebias - Negative bias configuration + disabled - Only available on HMC5983. Disables magnetic + sensor and enables temperature sensor. + Note: The effect of this configuration may vary + according to the device. For exact documentation + check the device's datasheet. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-meas-spec b/Documentation/ABI/testing/sysfs-bus-iio-meas-spec new file mode 100644 index 000000000000..1a6265e92e2f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-meas-spec @@ -0,0 +1,8 @@ +What: /sys/bus/iio/devices/iio:deviceX/battery_low +KernelVersion: 4.1.0 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns either '1' or '0'. '1' means that the + battery level supplied to sensor is below 2.25V. + This ABI is available for tsys02d, htu21, ms8607 + This ABI is available for htu21, ms8607 diff --git a/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs b/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs index bbb039237a25..04ac62305018 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs +++ b/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs @@ -18,3 +18,25 @@ Description: trigger. In order to associate the trigger with an IIO device one should write this name string to /sys/bus/iio/devices/iio:deviceY/trigger/current_trigger. + +What: /sys/bus/iio/devices/iio_sysfs_trigger/add_trigger +KernelVersion: 2.6.39 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is provided by the iio-trig-sysfs stand-alone + driver and it is used to activate the creation of a new trigger. + In order to achieve this, one should write a positive integer + into the associated file, which will serve as the id of the + trigger. If the trigger with the specified id is already present + in the system, an invalid argument message will be returned. + +What: /sys/bus/iio/devices/iio_sysfs_trigger/remove_trigger +KernelVersion: 2.6.39 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to unregister and delete a previously + created trigger from the list of available triggers. In order to + achieve this, one should write a positive integer into the + associated file, representing the id of the trigger that needs + to be removed. If the trigger can't be found, an invalid + argument message will be returned to the user. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-vf610 b/Documentation/ABI/testing/sysfs-bus-iio-vf610 index ecbc1f4af921..308a6756d3bf 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio-vf610 +++ b/Documentation/ABI/testing/sysfs-bus-iio-vf610 @@ -5,3 +5,12 @@ Description: Specifies the hardware conversion mode used. The three available modes are "normal", "high-speed" and "low-power", where the last is the default mode. + + +What: /sys/bus/iio/devices/iio:deviceX/out_conversion_mode +KernelVersion: 4.6 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the hardware conversion mode used within DAC. + The two available modes are "high-power" and "low-power", + where "low-power" mode is the default mode. diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth new file mode 100644 index 000000000000..22d0843849a8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth @@ -0,0 +1,49 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/masters/* +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure output ports for STP masters. Writing -1 + disables a master; any + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_port +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RO) Output port type: + 0: not present, + 1: MSU (Memory Storage Unit) + 2: CTP (Common Trace Port) + 4: PTI (MIPI PTI). + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_drop +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Data retention policy setting: keep (0) or drop (1) + incoming data while output port is in reset. + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_null +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) STP NULL packet generation: enabled (1) or disabled (0). + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_flush +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Force flush data from byte packing buffer for the output + port. + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_reset +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RO) Output port is in reset (1). + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_smcfreq +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) STP sync packet frequency for the port. Specifies the + number of clocks between mainenance packets. diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc new file mode 100644 index 000000000000..b940c5d91cf7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc @@ -0,0 +1,33 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/wrap +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure MSC buffer wrapping. 1 == wrapping enabled. + +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/mode +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure MSC operating mode: + - "single", for contiguous buffer mode (high-order alloc); + - "multi", for multiblock mode; + - "ExI", for DCI handler mode; + - "debug", for debug mode. + If operating mode changes, existing buffer is deallocated, + provided there are no active users and tracing is not enabled, + otherwise the write will fail. + +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/nr_pages +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure MSC buffer size for "single" or "multi" modes. + In single mode, this is a single number of pages, has to be + power of 2. In multiblock mode, this is a comma-separated list + of numbers of pages for each window to be allocated. Number of + windows is not limited. + Writing to this file deallocates existing buffer (provided + there are no active users and tracing is not enabled) and then + allocates a new one. + + diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti new file mode 100644 index 000000000000..df0b24fd0218 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti @@ -0,0 +1,24 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-pti/mode +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure PTI output width. Currently supported values + are 4, 8, 12, 16. + +What: /sys/bus/intel_th/devices/<intel_th_id>-pti/freerunning_clock +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) 0: PTI trace clock acts as a strobe which only toggles + when there is trace data to send. 1: PTI trace clock is a + free-running clock. + +What: /sys/bus/intel_th/devices/<intel_th_id>-pti/clock_divider +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure PTI port clock divider: + - 0: Intel TH clock rate, + - 1: 1/2 Intel TH clock rate, + - 2: 1/4 Intel TH clock rate, + - 3: 1/8 Intel TH clock rate. diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices new file mode 100644 index 000000000000..4d48a9451866 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices @@ -0,0 +1,13 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-<device><id>/active +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Writes of 1 or 0 enable or disable trace output to this + output device. Reads return current status. + +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/port +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RO) Port number, corresponding to this output device on the + switch (GTH). diff --git a/Documentation/ABI/testing/sysfs-bus-mei b/Documentation/ABI/testing/sysfs-bus-mei index 20e4d1638bac..6bd45346ac7e 100644 --- a/Documentation/ABI/testing/sysfs-bus-mei +++ b/Documentation/ABI/testing/sysfs-bus-mei @@ -19,3 +19,10 @@ KernelVersion: 4.2 Contact: Tomas Winkler <tomas.winkler@intel.com> Description: Stores mei client device uuid Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +What: /sys/bus/mei/devices/.../version +Date: Aug 2015 +KernelVersion: 4.3 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Stores mei client protocol version + Format: %d diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 864637f25bee..0bd731cbb50c 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -1,3 +1,23 @@ +What: /sys/bus/usb/devices/INTERFACE/authorized +Date: August 2015 +Description: + This allows to authorize (1) or deauthorize (0) + individual interfaces instead a whole device + in contrast to the device authorization. + If a deauthorized interface will be authorized + so the driver probing must be triggered manually + by writing INTERFACE to /sys/bus/usb/drivers_probe + This allows to avoid side-effects with drivers + that need multiple interfaces. + A deauthorized interface cannot be probed or claimed. + +What: /sys/bus/usb/devices/usbX/interface_authorized_default +Date: August 2015 +Description: + This is used as value that determines if interfaces + would be authorized by default. + The value can be 1 or 0. It's by default 1. + What: /sys/bus/usb/device/.../authorized Date: July 2008 KernelVersion: 2.6.26 @@ -114,19 +134,21 @@ Description: enabled for the device. Developer can write y/Y/1 or n/N/0 to the file to enable/disable the feature. -What: /sys/bus/usb/devices/.../power/usb3_hardware_lpm -Date: June 2015 +What: /sys/bus/usb/devices/.../power/usb3_hardware_lpm_u1 + /sys/bus/usb/devices/.../power/usb3_hardware_lpm_u2 +Date: November 2015 Contact: Kevin Strasser <kevin.strasser@linux.intel.com> + Lu Baolu <baolu.lu@linux.intel.com> Description: If CONFIG_PM is set and a USB 3.0 lpm-capable device is plugged in to a xHCI host which supports link PM, it will check if U1 and U2 exit latencies have been set in the BOS descriptor; if - the check is is passed and the host supports USB3 hardware LPM, + the check is passed and the host supports USB3 hardware LPM, USB3 hardware LPM will be enabled for the device and the USB - device directory will contain a file named - power/usb3_hardware_lpm. The file holds a string value (enable - or disable) indicating whether or not USB3 hardware LPM is - enabled for the device. + device directory will contain two files named + power/usb3_hardware_lpm_u1 and power/usb3_hardware_lpm_u2. These + files hold a string value (enable or disable) indicating whether + or not USB3 hardware LPM U1 or U2 is enabled for the device. What: /sys/bus/usb/devices/.../removable Date: February 2012 @@ -167,6 +189,17 @@ Description: The file will read "hotplug", "wired" and "not used" if the information is available, and "unknown" otherwise. +What: /sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit +Date: November 2015 +Contact: Lu Baolu <baolu.lu@linux.intel.com> +Description: + Some USB3.0 devices are not friendly to USB3 LPM. usb3_lpm_permit + attribute allows enabling/disabling usb3 lpm of a port. It takes + effect both before and after a usb device is enumerated. Supported + values are "0" if both u1 and u2 are NOT permitted, "u1" if only u1 + is permitted, "u2" if only u2 is permitted, "u1_u2" if both u1 and + u2 are permitted. + What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout Date: May 2013 Contact: Mathias Nyman <mathias.nyman@linux.intel.com> diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl index b07e86d4597f..7fd737eed38a 100644 --- a/Documentation/ABI/testing/sysfs-class-cxl +++ b/Documentation/ABI/testing/sysfs-class-cxl @@ -159,7 +159,7 @@ Description: read only Decimal value of the Per Process MMIO space length. Users: https://github.com/ibm-capi/libcxl -What: /sys/class/cxl/<afu>m/pp_mmio_off +What: /sys/class/cxl/<afu>m/pp_mmio_off (not in a guest) Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only @@ -183,7 +183,7 @@ Description: read only Identifies the revision level of the PSL. Users: https://github.com/ibm-capi/libcxl -What: /sys/class/cxl/<card>/base_image +What: /sys/class/cxl/<card>/base_image (not in a guest) Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only @@ -193,7 +193,7 @@ Description: read only during the initial program load. Users: https://github.com/ibm-capi/libcxl -What: /sys/class/cxl/<card>/image_loaded +What: /sys/class/cxl/<card>/image_loaded (not in a guest) Date: September 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read only @@ -201,7 +201,7 @@ Description: read only onto the card. Users: https://github.com/ibm-capi/libcxl -What: /sys/class/cxl/<card>/load_image_on_perst +What: /sys/class/cxl/<card>/load_image_on_perst (not in a guest) Date: December 2014 Contact: linuxppc-dev@lists.ozlabs.org Description: read/write @@ -224,7 +224,7 @@ Description: write only to reload the FPGA depending on load_image_on_perst. Users: https://github.com/ibm-capi/libcxl -What: /sys/class/cxl/<card>/perst_reloads_same_image +What: /sys/class/cxl/<card>/perst_reloads_same_image (not in a guest) Date: July 2015 Contact: linuxppc-dev@lists.ozlabs.org Description: read/write diff --git a/Documentation/ABI/testing/sysfs-class-fpga-manager b/Documentation/ABI/testing/sysfs-class-fpga-manager new file mode 100644 index 000000000000..23056c532fdd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-fpga-manager @@ -0,0 +1,37 @@ +What: /sys/class/fpga_manager/<fpga>/name +Date: August 2015 +KernelVersion: 4.3 +Contact: Alan Tull <atull@opensource.altera.com> +Description: Name of low level fpga manager driver. + +What: /sys/class/fpga_manager/<fpga>/state +Date: August 2015 +KernelVersion: 4.3 +Contact: Alan Tull <atull@opensource.altera.com> +Description: Read fpga manager state as a string. + The intent is to provide enough detail that if something goes + wrong during FPGA programming (something that the driver can't + fix) then userspace can know, i.e. if the firmware request + fails, that could be due to not being able to find the firmware + file. + + This is a superset of FPGA states and fpga manager driver + states. The fpga manager driver is walking through these steps + to get the FPGA into a known operating state. It's a sequence, + though some steps may get skipped. Valid FPGA states will vary + by manufacturer; this is a superset. + + * unknown = can't determine state + * power off = FPGA power is off + * power up = FPGA reports power is up + * reset = FPGA held in reset state + * firmware request = firmware class request in progress + * firmware request error = firmware request failed + * write init = preparing FPGA for programming + * write init error = Error while preparing FPGA for + programming + * write = FPGA ready to receive image data + * write error = Error while programming + * write complete = Doing post programming steps + * write complete error = Error while doing post programming + * operating = FPGA is programmed and operating diff --git a/Documentation/ABI/testing/sysfs-class-infiniband b/Documentation/ABI/testing/sysfs-class-infiniband new file mode 100644 index 000000000000..a86abe66a316 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-infiniband @@ -0,0 +1,16 @@ +What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index> +Date: November 29, 2015 +KernelVersion: 4.4.0 +Contact: linux-rdma@vger.kernel.org +Description: The net-device's name associated with the GID resides + at index <gid-index>. + +What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index> +Date: November 29, 2015 +KernelVersion: 4.4.0 +Contact: linux-rdma@vger.kernel.org +Description: The RoCE type of the associated GID resides at index <gid-index>. + This could either be "IB/RoCE v1" for IB and RoCE v1 based GODs + or "RoCE v2" for RoCE v2 based GIDs. + + diff --git a/Documentation/ABI/testing/sysfs-class-mic.txt b/Documentation/ABI/testing/sysfs-class-mic.txt index 13f48afc534f..d45eed2bf128 100644 --- a/Documentation/ABI/testing/sysfs-class-mic.txt +++ b/Documentation/ABI/testing/sysfs-class-mic.txt @@ -41,18 +41,15 @@ Description: When read, this entry provides the current state of an Intel MIC device in the context of the card OS. Possible values that will be read are: - "offline" - The MIC device is ready to boot the card OS. On + "ready" - The MIC device is ready to boot the card OS. On reading this entry after an OSPM resume, a "boot" has to be written to this entry if the card was previously shutdown during OSPM suspend. - "online" - The MIC device has initiated booting a card OS. + "booting" - The MIC device has initiated booting a card OS. + "online" - The MIC device has completed boot and is online "shutting_down" - The card OS is shutting down. + "resetting" - A reset has been initiated for the MIC device "reset_failed" - The MIC device has failed to reset. - "suspending" - The MIC device is currently being prepared for - suspend. On reading this entry, a "suspend" has to be written - to the state sysfs entry to ensure the card is shutdown during - OSPM suspend. - "suspended" - The MIC device has been suspended. When written, this sysfs entry triggers different state change operations depending upon the current state of the card OS. @@ -62,8 +59,6 @@ Description: sysfs entries. "reset" - Initiates device reset. "shutdown" - Initiates card OS shutdown. - "suspend" - Initiates card OS shutdown and also marks the card - as suspended. What: /sys/class/mic/mic(x)/shutdown_status Date: October 2013 @@ -126,7 +121,7 @@ Description: the card. This sysfs entry can be written with the following valid strings: a) linux - Boot a Linux image. - b) elf - Boot an elf image for flash updates. + b) flash - Boot an image for flash updates. What: /sys/class/mic/mic(x)/log_buf_addr Date: October 2013 @@ -155,3 +150,17 @@ Description: daemon to set the log buffer length address. The correct log buffer length address to be written can be found in the System.map file of the card OS. + +What: /sys/class/mic/mic(x)/heartbeat_enable +Date: March 2015 +KernelVersion: 3.20 +Contact: Ashutosh Dixit <ashutosh.dixit@intel.com> +Description: + The MIC drivers detect and inform user space about card crashes + via a heartbeat mechanism (see the description of + shutdown_status above). User space can turn off this + notification by setting heartbeat_enable to 0 and enable it by + setting this entry to 1. If this notification is disabled it is + the responsibility of user space to detect card crashes via + alternative means such as a network ping. This setting is + enabled by default. diff --git a/Documentation/ABI/testing/sysfs-class-net-batman-adv b/Documentation/ABI/testing/sysfs-class-net-batman-adv index 7f34a95bb963..518f6a1dbc0c 100644 --- a/Documentation/ABI/testing/sysfs-class-net-batman-adv +++ b/Documentation/ABI/testing/sysfs-class-net-batman-adv @@ -1,4 +1,20 @@ +What: /sys/class/net/<iface>/batman-adv/throughput_override +Date: Feb 2014 +Contact: Antonio Quartulli <antonio@meshcoding.com> +description: + Defines the throughput value to be used by B.A.T.M.A.N. V + when estimating the link throughput using this interface. + If the value is set to 0 then batman-adv will try to + estimate the throughput by itself. + +What: /sys/class/net/<iface>/batman-adv/elp_interval +Date: Feb 2014 +Contact: Linus Lüssing <linus.luessing@web.de> +Description: + Defines the interval in milliseconds in which batman + sends its probing packets for link quality measurements. + What: /sys/class/net/<iface>/batman-adv/iface_status Date: May 2010 Contact: Marek Lindner <mareklindner@neomailbox.ch> @@ -12,4 +28,3 @@ Description: The /sys/class/net/<iface>/batman-adv/mesh_iface file displays the batman mesh interface this <iface> currently is associated with. - diff --git a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm index 5cedf72df358..f7be0e88b139 100644 --- a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm +++ b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm @@ -19,6 +19,25 @@ Description: Set to 0 to pad all frames. Set greater than tx_max to disable all padding. +What: /sys/class/net/<iface>/cdc_ncm/ndp_to_end +Date: Dec 2015 +KernelVersion: 4.5 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Boolean attribute showing the status of the "NDP to + end" quirk. Defaults to 'N', except for devices + already known to need it enabled. + + The "NDP to end" quirk makes the driver place the NDP + (the packet index table) after the payload. The NCM + specification does not mandate this, but some devices + are known to be more restrictive. Write 'Y' to this + attribute for temporary testing of a suspect device + failing to work with the default driver settings. + + A device entry should be added to the driver if this + quirk is found to be required. + What: /sys/class/net/<iface>/cdc_ncm/rx_max Date: May 2014 KernelVersion: 3.16 diff --git a/Documentation/ABI/testing/sysfs-class-net-mesh b/Documentation/ABI/testing/sysfs-class-net-mesh index c46406296631..c2b956d44a95 100644 --- a/Documentation/ABI/testing/sysfs-class-net-mesh +++ b/Documentation/ABI/testing/sysfs-class-net-mesh @@ -8,7 +8,7 @@ Description: What: /sys/class/net/<mesh_iface>/mesh/<vlan_subdir>/ap_isolation Date: May 2011 -Contact: Antonio Quartulli <antonio@meshcoding.com> +Contact: Antonio Quartulli <a@unstable.cc> Description: Indicates whether the data traffic going from a wireless client to another wireless client will be @@ -70,7 +70,7 @@ Description: What: /sys/class/net/<mesh_iface>/mesh/isolation_mark Date: Nov 2013 -Contact: Antonio Quartulli <antonio@meshcoding.com> +Contact: Antonio Quartulli <a@unstable.cc> Description: Defines the isolation mark (and its bitmask) which is used to classify clients as "isolated" by the diff --git a/Documentation/ABI/testing/sysfs-class-net-qmi b/Documentation/ABI/testing/sysfs-class-net-qmi new file mode 100644 index 000000000000..fa5a00bb1143 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-qmi @@ -0,0 +1,23 @@ +What: /sys/class/net/<iface>/qmi/raw_ip +Date: Dec 2015 +KernelVersion: 4.4 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Boolean. Default: 'N' + + Set this to 'Y' to change the network device link + framing from '802.3' to 'raw-ip'. + + The netdev will change to reflect the link framing + mode. The netdev is an ordinary ethernet device in + '802.3' mode, and the driver expects to exchange + frames with an ethernet header over the USB link. The + netdev is a headerless p-t-p device in 'raw-ip' mode, + and the driver expects to echange IPv4 or IPv6 packets + without any L2 header over the USB link. + + Userspace is in full control of firmware configuration + through the delegation of the QMI protocol. Userspace + is responsible for coordination of driver and firmware + link framing mode, changing this setting to 'Y' if the + firmware is configured for 'raw-ip' mode. diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index 369d2a2d7d3e..fa05719f9981 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -74,3 +74,61 @@ Description: Valid values: - 0 - 70 (minutes), step by 10 (rounded down) + +What: /sys/class/power_supply/bq24257-charger/ovp_voltage +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry configures the overvoltage protection feature of bq24257- + type charger devices. This feature protects the device and other + components against damage from overvoltage on the input supply. See + device datasheet for details. + + Valid values: + - 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000, + 10500000 (all uV) + +What: /sys/class/power_supply/bq24257-charger/in_dpm_voltage +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry configures the input dynamic power path management voltage of + bq24257-type charger devices. Once the supply drops to the configured + voltage, the input current limit is reduced down to prevent the further + drop of the supply. When the IC enters this mode, the charge current is + lower than the set value. See device datasheet for details. + + Valid values: + - 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000, + 4760000 (all uV) + +What: /sys/class/power_supply/bq24257-charger/high_impedance_enable +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry allows enabling the high-impedance mode of bq24257-type + charger devices. If enabled, it places the charger IC into low power + standby mode with the switch mode controller disabled. When disabled, + the charger operates normally. See device datasheet for details. + + Valid values: + - 1: enabled + - 0: disabled + +What: /sys/class/power_supply/bq24257-charger/sysoff_enable +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry allows enabling the sysoff mode of bq24257-type charger + devices. If enabled and the input is removed, the internal battery FET + is turned off in order to reduce the leakage from the BAT pin to less + than 1uA. Note that on some devices/systems this disconnects the battery + from the system. See device datasheet for details. + + Valid values: + - 1: enabled + - 0: disabled diff --git a/Documentation/ABI/testing/sysfs-class-rc-nuvoton b/Documentation/ABI/testing/sysfs-class-rc-nuvoton new file mode 100644 index 000000000000..905bcdeedef2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rc-nuvoton @@ -0,0 +1,15 @@ +What: /sys/class/rc/rcN/wakeup_data +Date: Mar 2016 +KernelVersion: 4.6 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Reading this file returns the stored CIR wakeup sequence. + It starts with a pulse, followed by a space, pulse etc. + All values are in microseconds. + The same format can be used to store a wakeup sequence + in the Nuvoton chip by writing to this file. + + Note: Some systems reset the stored wakeup sequence to a + factory default on each boot. On such systems store the + wakeup sequence in a file and set it on boot using e.g. + a udev rule. diff --git a/Documentation/ABI/testing/sysfs-class-stm b/Documentation/ABI/testing/sysfs-class-stm new file mode 100644 index 000000000000..c9aa4f3fc9a7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-stm @@ -0,0 +1,14 @@ +What: /sys/class/stm/<stm>/masters +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + Shows first and last available to software master numbers on + this STM device. + +What: /sys/class/stm/<stm>/channels +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + Shows the number of channels per master on this STM device. diff --git a/Documentation/ABI/testing/sysfs-class-stm_source b/Documentation/ABI/testing/sysfs-class-stm_source new file mode 100644 index 000000000000..57b8dd39bbf7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-stm_source @@ -0,0 +1,11 @@ +What: /sys/class/stm_source/<stm_source>/stm_source_link +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + stm_source device linkage to stm device, where its tracing data + is directed. Reads return an existing connection or "<none>" if + this stm_source is not connected to any stm device yet. + Write an existing (registered) stm device's name here to + connect that device. If a device is already connected to this + stm_source, it will first be disconnected. diff --git a/Documentation/ABI/testing/sysfs-class-watchdog b/Documentation/ABI/testing/sysfs-class-watchdog new file mode 100644 index 000000000000..736046b33040 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-watchdog @@ -0,0 +1,51 @@ +What: /sys/class/watchdog/watchdogn/bootstatus +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains status of the watchdog + device at boot. It is equivalent to WDIOC_GETBOOTSTATUS of + ioctl interface. + +What: /sys/class/watchdog/watchdogn/identity +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains identity string of + watchdog device. + +What: /sys/class/watchdog/watchdogn/nowayout +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. While reading, it gives '1' if that + device supports nowayout feature else, it gives '0'. + +What: /sys/class/watchdog/watchdogn/state +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It gives active/inactive status of + watchdog device. + +What: /sys/class/watchdog/watchdogn/status +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains watchdog device's + internal status bits. It is equivalent to WDIOC_GETSTATUS + of ioctl interface. + +What: /sys/class/watchdog/watchdogn/timeleft +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains value of time left for + reset generation. It is equivalent to WDIOC_GETTIMELEFT of + ioctl interface. + +What: /sys/class/watchdog/watchdogn/timeout +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It is read to know about current + value of timeout programmed. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-corsair b/Documentation/ABI/testing/sysfs-driver-hid-corsair new file mode 100644 index 000000000000..b8827f0f12c4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-corsair @@ -0,0 +1,15 @@ +What: /sys/bus/drivers/corsair/<dev>/macro_mode +Date: August 2015 +KernelVersion: 4.2 +Contact: Clement Vuchener <clement.vuchener@gmail.com> +Description: Get/set the current playback mode. "SW" for software mode + where G-keys triggers their regular key codes. "HW" for + hardware playback mode where the G-keys play their macro + from the on-board memory. + + +What: /sys/bus/drivers/corsair/<dev>/current_profile +Date: August 2015 +KernelVersion: 4.2 +Contact: Clement Vuchener <clement.vuchener@gmail.com> +Description: Get/set the current selected profile. Values are from 1 to 3. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus deleted file mode 100644 index 7bd776f9c3c7..000000000000 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus +++ /dev/null @@ -1,96 +0,0 @@ -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/actual_profile -Date: October 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The integer value of this attribute ranges from 0-4. - When read, this attribute returns the number of the actual - profile. This value is persistent, so its equivalent to the - profile that's active when the mouse is powered on next time. - When written, this file sets the number of the startup profile - and the mouse activates this profile immediately. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/info -Date: November 2012 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns general data like firmware version. - When written, the device can be reset. - The data is 8 bytes long. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro -Date: October 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store a macro with max 500 key/button strokes - internally. - When written, this file lets one set the sequence for a specific - button for a specific profile. Button and profile numbers are - included in written data. The data has to be 2082 bytes long. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_buttons -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_buttons holds information about button layout. - When written, this file lets one write the respective profile - buttons back to the mouse. The data has to be 77 bytes long. - The mouse will reject invalid data. - Which profile to write is determined by the profile number - contained in the data. - Before reading this file, control has to be written to select - which profile to read. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings -Date: October 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_settings holds information like resolution, sensitivity - and light effects. - When written, this file lets one write the respective profile - settings back to the mouse. The data has to be 43 bytes long. - The mouse will reject invalid data. - Which profile to write is determined by the profile number - contained in the data. - Before reading this file, control has to be written to select - which profile to read. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor -Date: October 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse has a tracking- and a distance-control-unit. These - can be activated/deactivated and the lift-off distance can be - set. The data has to be 6 bytes long. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/talk -Date: May 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: Used to active some easy* functions of the mouse from outside. - The data has to be 16 bytes long. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu -Date: October 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When written a calibration process for the tracking control unit - can be initiated/cancelled. Also lets one read/write sensor - registers. - The data has to be 4 bytes long. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image -Date: October 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read the mouse returns a 30x30 pixel image of the - sampled underground. This works only in the course of a - calibration process initiated with tcu. - The returned data is 1028 bytes in size. - This file is readonly. -Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus deleted file mode 100644 index a10404f15a54..000000000000 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus +++ /dev/null @@ -1,49 +0,0 @@ -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The integer value of this attribute ranges from 0-4. - When read, this attribute returns the number of the active - profile. - When written, the mouse activates this profile immediately. - The profile that's active when powered down is the same that's - active when the mouse is powered on. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/info -Date: November 2012 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns general data like firmware version. - When written, the device can be reset. - The data is 6 bytes long. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_buttons holds information about button layout. - When written, this file lets one write the respective profile - buttons back to the mouse. The data has to be 23 bytes long. - The mouse will reject invalid data. - Which profile to write is determined by the profile number - contained in the data. - Before reading this file, control has to be written to select - which profile to read. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_settings holds information like resolution, sensitivity - and light effects. - When written, this file lets one write the respective profile - settings back to the mouse. The data has to be 16 bytes long. - The mouse will reject invalid data. - Which profile to write is determined by the profile number - contained in the data. - Before reading this file, control has to be written to select - which profile to read. -Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra deleted file mode 100644 index 9fa9de30d14b..000000000000 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra +++ /dev/null @@ -1,49 +0,0 @@ -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info -Date: November 2012 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns general data like firmware version. - When written, the device can be reset. - The data is 6 bytes long. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_settings holds information like resolution, sensitivity - and light effects. - When written, this file lets one write the respective profile - settings back to the mouse. The data has to be 13 bytes long. - The mouse will reject invalid data. - Which profile to write is determined by the profile number - contained in the data. - Before reading this file, control has to be written to select - which profile to read. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_buttons holds information about button layout. - When written, this file lets one write the respective profile - buttons back to the mouse. The data has to be 19 bytes long. - The mouse will reject invalid data. - Which profile to write is determined by the profile number - contained in the data. - Before reading this file, control has to be written to select - which profile to read. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns the settings stored in the mouse. - The size of the data is 3 bytes and holds information on the - startup_profile. - When written, this file lets write settings back to the mouse. - The data has to be 3 bytes long. The mouse will reject invalid - data. -Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-ppi b/Documentation/ABI/testing/sysfs-driver-ppi index 7d1435bc976c..9921ef285899 100644 --- a/Documentation/ABI/testing/sysfs-driver-ppi +++ b/Documentation/ABI/testing/sysfs-driver-ppi @@ -1,4 +1,4 @@ -What: /sys/devices/pnp0/<bus-num>/ppi/ +What: /sys/class/tpm/tpmX/ppi/ Date: August 2012 Kernel Version: 3.6 Contact: xiaoyan.zhang@intel.com @@ -8,9 +8,14 @@ Description: folder makes sense. The folder path can be got by command 'find /sys/ -name 'pcrs''. For the detail information of PPI, please refer to the PPI specification from + http://www.trustedcomputinggroup.org/ -What: /sys/devices/pnp0/<bus-num>/ppi/version + In Linux 4.2 ppi was moved to the character device directory. + A symlink from tpmX/device/ppi to tpmX/ppi to provide backwards + compatibility. + +What: /sys/class/tpm/tpmX/ppi/version Date: August 2012 Contact: xiaoyan.zhang@intel.com Description: @@ -18,7 +23,7 @@ Description: platform. This file is readonly. -What: /sys/devices/pnp0/<bus-num>/ppi/request +What: /sys/class/tpm/tpmX/ppi/request Date: August 2012 Contact: xiaoyan.zhang@intel.com Description: @@ -28,7 +33,7 @@ Description: integer value range from 1 to 160, and 0 means no request. This file can be read and written. -What: /sys/devices/pnp0/00:<bus-num>/ppi/response +What: /sys/class/tpm/tpmX/ppi/response Date: August 2012 Contact: xiaoyan.zhang@intel.com Description: @@ -37,7 +42,7 @@ Description: : <response description>". This file is readonly. -What: /sys/devices/pnp0/<bus-num>/ppi/transition_action +What: /sys/class/tpm/tpmX/ppi/transition_action Date: August 2012 Contact: xiaoyan.zhang@intel.com Description: @@ -47,7 +52,7 @@ Description: description>". This file is readonly. -What: /sys/devices/pnp0/<bus-num>/ppi/tcg_operations +What: /sys/class/tpm/tpmX/ppi/tcg_operations Date: August 2012 Contact: xiaoyan.zhang@intel.com Description: @@ -58,7 +63,7 @@ Description: This attribute is only supported by PPI version 1.2+. This file is readonly. -What: /sys/devices/pnp0/<bus-num>/ppi/vs_operations +What: /sys/class/tpm/tpmX/ppi/vs_operations Date: August 2012 Contact: xiaoyan.zhang@intel.com Description: diff --git a/Documentation/ABI/testing/sysfs-driver-st b/Documentation/ABI/testing/sysfs-driver-st new file mode 100644 index 000000000000..ba5d77008a85 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-st @@ -0,0 +1,12 @@ +What: /sys/bus/scsi/drivers/st/debug_flag +Date: October 2015 +Kernel Version: ?.? +Contact: shane.seymour@hpe.com +Description: + This file allows you to turn debug output from the st driver + off if you write a '0' to the file or on if you write a '1'. + Note that debug output requires that the module be compiled + with the #define DEBUG set to a non-zero value (this is the + default). If DEBUG is set to 0 then this file will not + appear in sysfs as its presence is conditional upon debug + output support being compiled into the module. diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg new file mode 100644 index 000000000000..011dda4f8e8a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg @@ -0,0 +1,100 @@ +What: /sys/firmware/qemu_fw_cfg/ +Date: August 2015 +Contact: Gabriel Somlo <somlo@cmu.edu> +Description: + Several different architectures supported by QEMU (x86, arm, + sun4*, ppc/mac) are provisioned with a firmware configuration + (fw_cfg) device, originally intended as a way for the host to + provide configuration data to the guest firmware. Starting + with QEMU v2.4, arbitrary fw_cfg file entries may be specified + by the user on the command line, which makes fw_cfg additionally + useful as an out-of-band, asynchronous mechanism for providing + configuration data to the guest userspace. + + The authoritative guest-side hardware interface documentation + to the fw_cfg device can be found in "docs/specs/fw_cfg.txt" + in the QEMU source tree. + + === SysFS fw_cfg Interface === + + The fw_cfg sysfs interface described in this document is only + intended to display discoverable blobs (i.e., those registered + with the file directory), as there is no way to determine the + presence or size of "legacy" blobs (with selector keys between + 0x0002 and 0x0018) programmatically. + + All fw_cfg information is shown under: + + /sys/firmware/qemu_fw_cfg/ + + The only legacy blob displayed is the fw_cfg device revision: + + /sys/firmware/qemu_fw_cfg/rev + + --- Discoverable fw_cfg blobs by selector key --- + + All discoverable blobs listed in the fw_cfg file directory are + displayed as entries named after their unique selector key + value, e.g.: + + /sys/firmware/qemu_fw_cfg/by_key/32 + /sys/firmware/qemu_fw_cfg/by_key/33 + /sys/firmware/qemu_fw_cfg/by_key/34 + ... + + Each such fw_cfg sysfs entry has the following values exported + as attributes: + + name : The 56-byte nul-terminated ASCII string used as the + blob's 'file name' in the fw_cfg directory. + size : The length of the blob, as given in the fw_cfg + directory. + key : The value of the blob's selector key as given in the + fw_cfg directory. This value is the same as used in + the parent directory name. + raw : The raw bytes of the blob, obtained by selecting the + entry via the control register, and reading a number + of bytes equal to the blob size from the data + register. + + --- Listing fw_cfg blobs by file name --- + + While the fw_cfg device does not impose any specific naming + convention on the blobs registered in the file directory, + QEMU developers have traditionally used path name semantics + to give each blob a descriptive name. For example: + + "bootorder" + "genroms/kvmvapic.bin" + "etc/e820" + "etc/boot-fail-wait" + "etc/system-states" + "etc/table-loader" + "etc/acpi/rsdp" + "etc/acpi/tables" + "etc/smbios/smbios-tables" + "etc/smbios/smbios-anchor" + ... + + In addition to the listing by unique selector key described + above, the fw_cfg sysfs driver also attempts to build a tree + of directories matching the path name components of fw_cfg + blob names, ending in symlinks to the by_key entry for each + "basename", as illustrated below (assume current directory is + /sys/firmware): + + qemu_fw_cfg/by_name/bootorder -> ../by_key/38 + qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35 + qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41 + ... + + Construction of the directory tree and symlinks is done on a + "best-effort" basis, as there is no guarantee that components + of fw_cfg blob names are always "well behaved". I.e., there is + the possibility that a symlink (basename) will conflict with + a dirname component of another fw_cfg blob, in which case the + creation of the offending /sys/firmware/qemu_fw_cfg/by_name + entry will be skipped. + + The authoritative list of entries will continue to be found + under the /sys/firmware/qemu_fw_cfg/by_key directory. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 2c4cc42006e8..e5200f354abf 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -80,3 +80,21 @@ Date: February 2015 Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> Description: Controls the trimming rate in batch mode. + +What: /sys/fs/f2fs/<disk>/cp_interval +Date: October 2015 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the checkpoint timing. + +What: /sys/fs/f2fs/<disk>/idle_interval +Date: January 2016 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the idle timing. + +What: /sys/fs/f2fs/<disk>/ra_nid_pages +Date: October 2015 +Contact: "Chao Yu" <chao2.yu@samsung.com> +Description: + Controls the count of nid pages to be readaheaded. diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index 5bf42a840b22..da87f43aec58 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -33,7 +33,7 @@ Description: The object directory contains subdirectories for each function that is patched within the object. -What: /sys/kernel/livepatch/<patch>/<object>/<function> +What: /sys/kernel/livepatch/<patch>/<object>/<function,sympos> Date: Nov 2014 KernelVersion: 3.19.0 Contact: live-patching@vger.kernel.org @@ -41,4 +41,8 @@ Description: The function directory contains attributes regarding the properties and state of the patched function. + The directory name contains the patched function name and a + sympos number corresponding to the nth occurrence of the symbol + name in kallsyms for the patched object. + There are currently no such attributes. diff --git a/Documentation/ABI/testing/sysfs-platform-hidma-mgmt b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt new file mode 100644 index 000000000000..c2fb5d033f0e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt @@ -0,0 +1,97 @@ +What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/priority + /sys/devices/platform/QCOM8060:*/chanops/chan*/priority +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains either 0 or 1 and indicates if the DMA channel is a + low priority (0) or high priority (1) channel. + +What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/weight + /sys/devices/platform/QCOM8060:*/chanops/chan*/weight +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains 0..15 and indicates the weight of the channel among + equal priority channels during round robin scheduling. + +What: /sys/devices/platform/hidma-mgmt*/chreset_timeout_cycles + /sys/devices/platform/QCOM8060:*/chreset_timeout_cycles +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains the platform specific cycle value to wait after a + reset command is issued. If the value is chosen too short, + then the HW will issue a reset failure interrupt. The value + is platform specific and should not be changed without + consultance. + +What: /sys/devices/platform/hidma-mgmt*/dma_channels + /sys/devices/platform/QCOM8060:*/dma_channels +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains the number of dma channels supported by one instance + of HIDMA hardware. The value may change from chip to chip. + +What: /sys/devices/platform/hidma-mgmt*/hw_version_major + /sys/devices/platform/QCOM8060:*/hw_version_major +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Version number major for the hardware. + +What: /sys/devices/platform/hidma-mgmt*/hw_version_minor + /sys/devices/platform/QCOM8060:*/hw_version_minor +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Version number minor for the hardware. + +What: /sys/devices/platform/hidma-mgmt*/max_rd_xactions + /sys/devices/platform/QCOM8060:*/max_rd_xactions +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains a value between 0 and 31. Maximum number of + read transactions that can be issued back to back. + Choosing a higher number gives better performance but + can also cause performance reduction to other peripherals + sharing the same bus. + +What: /sys/devices/platform/hidma-mgmt*/max_read_request + /sys/devices/platform/QCOM8060:*/max_read_request +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Size of each read request. The value needs to be a power + of two and can be between 128 and 1024. + +What: /sys/devices/platform/hidma-mgmt*/max_wr_xactions + /sys/devices/platform/QCOM8060:*/max_wr_xactions +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains a value between 0 and 31. Maximum number of + write transactions that can be issued back to back. + Choosing a higher number gives better performance but + can also cause performance reduction to other peripherals + sharing the same bus. + + +What: /sys/devices/platform/hidma-mgmt*/max_write_request + /sys/devices/platform/QCOM8060:*/max_write_request +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Size of each write request. The value needs to be a power + of two and can be between 128 and 1024. diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index f4551816329e..50b368d490b5 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -256,3 +256,15 @@ Description: Writing a "1" enables this printing while writing a "0" disables it. The default value is "0". Reading from this file will display the current value. + +What: /sys/power/pm_wakeup_irq +Date: April 2015 +Contact: Alexandra Yates <alexandra.yates@linux.intel.org> +Description: + The /sys/power/pm_wakeup_irq file reports to user space the IRQ + number of the first wakeup interrupt (that is, the first + interrupt from an IRQ line armed for system wakeup) seen by the + kernel during the most recent system suspend/resume cycle. + + This output is useful for system wakeup diagnostics of spurious + wakeup interrupts. diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp index 44806a678f12..a17f817a9309 100644 --- a/Documentation/ABI/testing/sysfs-ptp +++ b/Documentation/ABI/testing/sysfs-ptp @@ -74,7 +74,7 @@ Description: assignment may be changed by two writing numbers into the file. -What: /sys/class/ptp/ptpN/pps_avaiable +What: /sys/class/ptp/ptpN/pps_available Date: September 2010 Contact: Richard Cochran <richardcochran@gmail.com> Description: diff --git a/Documentation/Changes b/Documentation/Changes index f447f0516f07..ec97b77c8b00 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -44,6 +44,7 @@ o grub 0.93 # grub --version || grub-insta o mcelog 0.6 # mcelog --version o iptables 1.4.2 # iptables -V o openssl & libcrypto 1.0.0 # openssl version +o bc 1.06.95 # bc --version Kernel compilation diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index c06f817b3091..9a70ddd16584 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -430,7 +430,7 @@ The rationale for using gotos is: return result; } -A common type of bug to be aware of it "one err bugs" which look like this: +A common type of bug to be aware of is "one err bugs" which look like this: err: kfree(foo->bar); @@ -640,7 +640,7 @@ Things to avoid when using macros: do { \ if (blah(x) < 0) \ return -EBUGGERED; \ - } while(0) + } while (0) is a _very_ bad idea. It looks like a function call but exits the "calling" function; don't break the internal parsers of those who will read the code. diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 55b70b903ead..781024ef9050 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -681,6 +681,11 @@ or: as appropriate. +PLEASE NOTE: The 'nents' argument to dma_sync_sg_for_cpu() and + dma_sync_sg_for_device() must be the same passed to + dma_map_sg(). It is _NOT_ the count returned by + dma_map_sg(). + After the last DMA transfer call one of the DMA unmap routines dma_unmap_{single,sg}(). If you don't touch the data from the first dma_map_*() call till dma_unmap_*(), then you don't have to call the @@ -946,16 +951,6 @@ to "Closing". alignment constraints (e.g. the alignment constraints about 64-bit objects). -3) Supporting multiple types of IOMMUs - - If your architecture needs to support multiple types of IOMMUs, you - can use include/linux/asm-generic/dma-mapping-common.h. It's a - library to support the DMA API with multiple types of IOMMUs. Lots - of architectures (x86, powerpc, sh, alpha, ia64, microblaze and - sparc) use it. Choose one to see how it can be used. If you need to - support multiple types of IOMMUs in a single system, the example of - x86 or powerpc helps. - Closing This document, and the API itself, would not be in its current diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index edccacd4f048..45ef3f279c3b 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -142,19 +142,6 @@ Part Ic - DMA addressing limitations ------------------------------------ int -dma_supported(struct device *dev, u64 mask) - -Checks to see if the device can support DMA to the memory described by -mask. - -Returns: 1 if it can and 0 if it can't. - -Notes: This routine merely tests to see if the mask is possible. It -won't change the current mask settings. It is more intended as an -internal API for use by the platform than an external API for use by -driver writers. - -int dma_set_mask_and_coherent(struct device *dev, u64 mask) Checks to see if the mask is possible and updates the device @@ -249,7 +236,7 @@ are guaranteed also to be cache line boundaries). DMA_TO_DEVICE synchronisation must be done after the last modification of the memory region by the software and before it is handed off to -the driver. Once this primitive is used, memory covered by this +the device. Once this primitive is used, memory covered by this primitive should be treated as read-only by the device. If the device may write to it at any point, it should be DMA_BIDIRECTIONAL (see below). @@ -340,7 +327,7 @@ accessed sg->address and sg->length as shown above. void dma_unmap_sg(struct device *dev, struct scatterlist *sg, - int nhwentries, enum dma_data_direction direction) + int nents, enum dma_data_direction direction) Unmap the previously mapped scatter/gather list. All the parameters must be the same as those and passed in to the scatter/gather mapping @@ -356,10 +343,10 @@ void dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size, enum dma_data_direction direction) void -dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nelems, +dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction) void -dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems, +dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction) Synchronise a single contiguous or scatter/gather mapping for the CPU diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt index 18dc52c4f2a0..e8cf9cf873b3 100644 --- a/Documentation/DMA-attributes.txt +++ b/Documentation/DMA-attributes.txt @@ -100,3 +100,29 @@ allocated by dma_alloc_attrs() function from individual pages if it can be mapped as contiguous chunk into device dma address space. By specifying this attribute the allocated buffer is forced to be contiguous also in physical memory. + +DMA_ATTR_ALLOC_SINGLE_PAGES +--------------------------- + +This is a hint to the DMA-mapping subsystem that it's probably not worth +the time to try to allocate memory to in a way that gives better TLB +efficiency (AKA it's not worth trying to build the mapping out of larger +pages). You might want to specify this if: +- You know that the accesses to this memory won't thrash the TLB. + You might know that the accesses are likely to be sequential or + that they aren't sequential but it's unlikely you'll ping-pong + between many addresses that are likely to be in different physical + pages. +- You know that the penalty of TLB misses while accessing the + memory will be small enough to be inconsequential. If you are + doing a heavy operation like decryption or decompression this + might be the case. +- You know that the DMA mapping is fairly transitory. If you expect + the mapping to have a short lifetime then it may be worth it to + optimize allocation (avoid coming up with large pages) instead of + getting the slight performance win of larger pages. +Setting this hint doesn't guarantee that you won't get huge pages, but it +means that we won't try quite as hard to get them. + +NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM, +though ARM64 patches will likely be posted soon. diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore index 7ebd5465d927..e05da3f7aa21 100644 --- a/Documentation/DocBook/.gitignore +++ b/Documentation/DocBook/.gitignore @@ -11,5 +11,7 @@ *.png *.gif *.svg +*.proc +*.db media-indices.tmpl media-entities.tmpl diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl index aac9357d4866..f9b9ad7894f5 100644 --- a/Documentation/DocBook/80211.tmpl +++ b/Documentation/DocBook/80211.tmpl @@ -154,8 +154,9 @@ !Finclude/net/cfg80211.h cfg80211_scan_request !Finclude/net/cfg80211.h cfg80211_scan_done !Finclude/net/cfg80211.h cfg80211_bss -!Finclude/net/cfg80211.h cfg80211_inform_bss_width_frame -!Finclude/net/cfg80211.h cfg80211_inform_bss_width +!Finclude/net/cfg80211.h cfg80211_inform_bss +!Finclude/net/cfg80211.h cfg80211_inform_bss_frame_data +!Finclude/net/cfg80211.h cfg80211_inform_bss_data !Finclude/net/cfg80211.h cfg80211_unlink_bss !Finclude/net/cfg80211.h cfg80211_find_ie !Finclude/net/cfg80211.h ieee80211_bss_get_ie diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 93eff64387cd..d70f9b68174e 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml drm.xml media_api.xml w1.xml \ + tracepoint.xml gpu.xml media_api.xml w1.xml \ writing_musb_glue_layer.xml crypto-API.xml iio.xml include Documentation/DocBook/media/Makefile @@ -50,8 +50,7 @@ pdfdocs: $(PDF) HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) htmldocs: $(HTML) - $(call build_main_index) - $(call build_images) + $(call cmd,build_main_index) $(call install_media_images) MAN := $(patsubst %.xml, %.9, $(BOOKS)) @@ -69,6 +68,12 @@ installmandocs: mandocs KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref KERNELDOC = $(srctree)/scripts/kernel-doc DOCPROC = $(objtree)/scripts/docproc +CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype + +# Use a fixed encoding - UTF-8 if the C library has support built-in +# or ASCII if not +LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C) +export LC_CTYPE XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl XMLTOFLAGS += --skip-validation @@ -133,7 +138,8 @@ quiet_cmd_db2pdf = PDF $@ index = index.html main_idx = $(obj)/$(index) -build_main_index = rm -rf $(main_idx); \ +quiet_cmd_build_main_index = HTML $(main_idx) + cmd_build_main_index = rm -rf $(main_idx); \ echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ cat $(HTML) >> $(main_idx) @@ -221,6 +227,10 @@ dochelp: @echo ' mandocs - man pages' @echo ' installmandocs - install man pages generated by mandocs' @echo ' cleandocs - clean all generated DocBook files' + @echo + @echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' + @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' + ### # Temporary files left by various tools diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl index e94a10bb4a9e..53f439dcc94b 100644 --- a/Documentation/DocBook/alsa-driver-api.tmpl +++ b/Documentation/DocBook/alsa-driver-api.tmpl @@ -112,6 +112,8 @@ !Esound/soc/soc-devres.c !Esound/soc/soc-io.c !Esound/soc/soc-pcm.c +!Esound/soc/soc-ops.c +!Esound/soc/soc-compress.c </sect1> <sect1><title>ASoC DAPM API</title> !Esound/soc/soc-dapm.c diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl index 07df23ea06e4..348619fcafb8 100644 --- a/Documentation/DocBook/crypto-API.tmpl +++ b/Documentation/DocBook/crypto-API.tmpl @@ -348,10 +348,7 @@ <para>type: <itemizedlist> <listitem> - <para>blkcipher for synchronous block ciphers</para> - </listitem> - <listitem> - <para>ablkcipher for asynchronous block ciphers</para> + <para>skcipher for symmetric key ciphers</para> </listitem> <listitem> <para>cipher for single block ciphers that may be used with @@ -485,6 +482,9 @@ <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> </listitem> <listitem> + <para>CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher</para> + </listitem> + <listitem> <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / decompression instead of performing the operation on one @@ -597,7 +597,7 @@ kernel crypto API | IPSEC Layer v v +-----------+ +-----------+ | | | | -| ablkcipher| | ahash | +| skcipher | | ahash | | (ctr) | ---+ | (ghash) | +-----------+ | +-----------+ | @@ -658,7 +658,7 @@ kernel crypto API | IPSEC Layer <listitem> <para> - The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API + The GCM AEAD cipher type implementation now invokes the SKCIPHER API with the instantiated CTR(AES) cipher handle. </para> @@ -669,7 +669,7 @@ kernel crypto API | IPSEC Layer </para> <para> - That means that the ABLKCIPHER implementation of CTR(AES) only + That means that the SKCIPHER implementation of CTR(AES) only implements the CTR block chaining mode. After performing the block chaining operation, the CIPHER implementation of AES is invoked. </para> @@ -677,7 +677,7 @@ kernel crypto API | IPSEC Layer <listitem> <para> - The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES + The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES cipher handle to encrypt one block. </para> </listitem> @@ -706,7 +706,7 @@ kernel crypto API | IPSEC Layer <para> For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The ASCII art picture above applies as well with the difference that only - step (4) is used and the ABLKCIPHER block chaining mode is CBC. + step (4) is used and the SKCIPHER block chaining mode is CBC. </para> </sect2> @@ -904,15 +904,14 @@ kernel crypto API | Caller </sect2> </sect1> - <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> + <sect1><title>Multi-Block Ciphers</title> <para> Example of transformations: cbc(aes), ecb(arc4), ... </para> <para> This section describes the multi-block cipher transformation - implementations for both synchronous [BLKCIPHER] and - asynchronous [ABLKCIPHER] case. The multi-block ciphers are + implementations. The multi-block ciphers are used for transformations which operate on scatterlists of data supplied to the transformation functions. They output the result into a scatterlist of data as well. @@ -921,16 +920,15 @@ kernel crypto API | Caller <sect2><title>Registration Specifics</title> <para> - The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms + The registration of multi-block cipher algorithms is one of the most standard procedures throughout the crypto API. </para> <para> Note, if a cipher implementation requires a proper alignment of data, the caller should use the functions of - crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() - respectively to identify a memory alignment mask. The kernel - crypto API is able to process requests that are unaligned. + crypto_skcipher_alignmask() to identify a memory alignment mask. + The kernel crypto API is able to process requests that are unaligned. This implies, however, additional overhead as the kernel crypto API needs to perform the realignment of the data which may imply moving of data. @@ -945,14 +943,13 @@ kernel crypto API | Caller <para> Please refer to the single block cipher description for schematics - of the block cipher usage. The usage patterns are exactly the same - for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. + of the block cipher usage. </para> </sect2> <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> <para> - There are a couple of specifics to the [ABLKCIPHER] interface. + There are a couple of specifics to the asynchronous interface. </para> <para> @@ -1692,7 +1689,28 @@ read(opfd, out, outlen); !Finclude/linux/crypto.h cipher_alg !Finclude/crypto/rng.h rng_alg </sect1> - <sect1><title>Asynchronous Block Cipher API</title> + <sect1><title>Symmetric Key Cipher API</title> +!Pinclude/crypto/skcipher.h Symmetric Key Cipher API +!Finclude/crypto/skcipher.h crypto_alloc_skcipher +!Finclude/crypto/skcipher.h crypto_free_skcipher +!Finclude/crypto/skcipher.h crypto_has_skcipher +!Finclude/crypto/skcipher.h crypto_skcipher_ivsize +!Finclude/crypto/skcipher.h crypto_skcipher_blocksize +!Finclude/crypto/skcipher.h crypto_skcipher_setkey +!Finclude/crypto/skcipher.h crypto_skcipher_reqtfm +!Finclude/crypto/skcipher.h crypto_skcipher_encrypt +!Finclude/crypto/skcipher.h crypto_skcipher_decrypt + </sect1> + <sect1><title>Symmetric Key Cipher Request Handle</title> +!Pinclude/crypto/skcipher.h Symmetric Key Cipher Request Handle +!Finclude/crypto/skcipher.h crypto_skcipher_reqsize +!Finclude/crypto/skcipher.h skcipher_request_set_tfm +!Finclude/crypto/skcipher.h skcipher_request_alloc +!Finclude/crypto/skcipher.h skcipher_request_free +!Finclude/crypto/skcipher.h skcipher_request_set_callback +!Finclude/crypto/skcipher.h skcipher_request_set_crypt + </sect1> + <sect1><title>Asynchronous Block Cipher API - Deprecated</title> !Pinclude/linux/crypto.h Asynchronous Block Cipher API !Finclude/linux/crypto.h crypto_alloc_ablkcipher !Finclude/linux/crypto.h crypto_free_ablkcipher @@ -1704,7 +1722,7 @@ read(opfd, out, outlen); !Finclude/linux/crypto.h crypto_ablkcipher_encrypt !Finclude/linux/crypto.h crypto_ablkcipher_decrypt </sect1> - <sect1><title>Asynchronous Cipher Request Handle</title> + <sect1><title>Asynchronous Cipher Request Handle - Deprecated</title> !Pinclude/linux/crypto.h Asynchronous Cipher Request Handle !Finclude/linux/crypto.h crypto_ablkcipher_reqsize !Finclude/linux/crypto.h ablkcipher_request_set_tfm @@ -1733,10 +1751,9 @@ read(opfd, out, outlen); !Finclude/crypto/aead.h aead_request_free !Finclude/crypto/aead.h aead_request_set_callback !Finclude/crypto/aead.h aead_request_set_crypt -!Finclude/crypto/aead.h aead_request_set_assoc !Finclude/crypto/aead.h aead_request_set_ad </sect1> - <sect1><title>Synchronous Block Cipher API</title> + <sect1><title>Synchronous Block Cipher API - Deprecated</title> !Pinclude/linux/crypto.h Synchronous Block Cipher API !Finclude/linux/crypto.h crypto_alloc_blkcipher !Finclude/linux/crypto.h crypto_free_blkcipher @@ -1762,19 +1779,6 @@ read(opfd, out, outlen); !Finclude/linux/crypto.h crypto_cipher_encrypt_one !Finclude/linux/crypto.h crypto_cipher_decrypt_one </sect1> - <sect1><title>Synchronous Message Digest API</title> -!Pinclude/linux/crypto.h Synchronous Message Digest API -!Finclude/linux/crypto.h crypto_alloc_hash -!Finclude/linux/crypto.h crypto_free_hash -!Finclude/linux/crypto.h crypto_has_hash -!Finclude/linux/crypto.h crypto_hash_blocksize -!Finclude/linux/crypto.h crypto_hash_digestsize -!Finclude/linux/crypto.h crypto_hash_init -!Finclude/linux/crypto.h crypto_hash_update -!Finclude/linux/crypto.h crypto_hash_final -!Finclude/linux/crypto.h crypto_hash_digest -!Finclude/linux/crypto.h crypto_hash_setkey - </sect1> <sect1><title>Message Digest Algorithm Definitions</title> !Pinclude/crypto/hash.h Message Digest Algorithm Definitions !Finclude/crypto/hash.h hash_alg_common @@ -1825,15 +1829,36 @@ read(opfd, out, outlen); !Finclude/crypto/rng.h crypto_alloc_rng !Finclude/crypto/rng.h crypto_rng_alg !Finclude/crypto/rng.h crypto_free_rng +!Finclude/crypto/rng.h crypto_rng_generate !Finclude/crypto/rng.h crypto_rng_get_bytes !Finclude/crypto/rng.h crypto_rng_reset !Finclude/crypto/rng.h crypto_rng_seedsize !Cinclude/crypto/rng.h </sect1> + <sect1><title>Asymmetric Cipher API</title> +!Pinclude/crypto/akcipher.h Generic Public Key API +!Finclude/crypto/akcipher.h akcipher_alg +!Finclude/crypto/akcipher.h akcipher_request +!Finclude/crypto/akcipher.h crypto_alloc_akcipher +!Finclude/crypto/akcipher.h crypto_free_akcipher +!Finclude/crypto/akcipher.h crypto_akcipher_set_pub_key +!Finclude/crypto/akcipher.h crypto_akcipher_set_priv_key + </sect1> + <sect1><title>Asymmetric Cipher Request Handle</title> +!Finclude/crypto/akcipher.h akcipher_request_alloc +!Finclude/crypto/akcipher.h akcipher_request_free +!Finclude/crypto/akcipher.h akcipher_request_set_callback +!Finclude/crypto/akcipher.h akcipher_request_set_crypt +!Finclude/crypto/akcipher.h crypto_akcipher_maxsize +!Finclude/crypto/akcipher.h crypto_akcipher_encrypt +!Finclude/crypto/akcipher.h crypto_akcipher_decrypt +!Finclude/crypto/akcipher.h crypto_akcipher_sign +!Finclude/crypto/akcipher.h crypto_akcipher_verify + </sect1> </chapter> <chapter id="Code"><title>Code Examples</title> - <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> + <sect1><title>Code Example For Symmetric Key Cipher Operation</title> <programlisting> struct tcrypt_result { @@ -1842,15 +1867,15 @@ struct tcrypt_result { }; /* tie all data structures together */ -struct ablkcipher_def { +struct skcipher_def { struct scatterlist sg; - struct crypto_ablkcipher *tfm; - struct ablkcipher_request *req; + struct crypto_skcipher *tfm; + struct skcipher_request *req; struct tcrypt_result result; }; /* Callback function */ -static void test_ablkcipher_cb(struct crypto_async_request *req, int error) +static void test_skcipher_cb(struct crypto_async_request *req, int error) { struct tcrypt_result *result = req->data; @@ -1862,15 +1887,15 @@ static void test_ablkcipher_cb(struct crypto_async_request *req, int error) } /* Perform cipher operation */ -static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, - int enc) +static unsigned int test_skcipher_encdec(struct skcipher_def *sk, + int enc) { int rc = 0; if (enc) - rc = crypto_ablkcipher_encrypt(ablk->req); + rc = crypto_skcipher_encrypt(sk->req); else - rc = crypto_ablkcipher_decrypt(ablk->req); + rc = crypto_skcipher_decrypt(sk->req); switch (rc) { case 0: @@ -1878,52 +1903,52 @@ static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, case -EINPROGRESS: case -EBUSY: rc = wait_for_completion_interruptible( - &ablk->result.completion); - if (!rc && !ablk->result.err) { - reinit_completion(&ablk->result.completion); + &sk->result.completion); + if (!rc && !sk->result.err) { + reinit_completion(&sk->result.completion); break; } default: - pr_info("ablkcipher encrypt returned with %d result %d\n", - rc, ablk->result.err); + pr_info("skcipher encrypt returned with %d result %d\n", + rc, sk->result.err); break; } - init_completion(&ablk->result.completion); + init_completion(&sk->result.completion); return rc; } /* Initialize and trigger cipher operation */ -static int test_ablkcipher(void) +static int test_skcipher(void) { - struct ablkcipher_def ablk; - struct crypto_ablkcipher *ablkcipher = NULL; - struct ablkcipher_request *req = NULL; + struct skcipher_def sk; + struct crypto_skcipher *skcipher = NULL; + struct skcipher_request *req = NULL; char *scratchpad = NULL; char *ivdata = NULL; unsigned char key[32]; int ret = -EFAULT; - ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); - if (IS_ERR(ablkcipher)) { - pr_info("could not allocate ablkcipher handle\n"); - return PTR_ERR(ablkcipher); + skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0); + if (IS_ERR(skcipher)) { + pr_info("could not allocate skcipher handle\n"); + return PTR_ERR(skcipher); } - req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); + req = skcipher_request_alloc(skcipher, GFP_KERNEL); if (IS_ERR(req)) { pr_info("could not allocate request queue\n"); ret = PTR_ERR(req); goto out; } - ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, - test_ablkcipher_cb, - &ablk.result); + skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, + test_skcipher_cb, + &sk.result); /* AES 256 with random key */ get_random_bytes(&key, 32); - if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { + if (crypto_skcipher_setkey(skcipher, key, 32)) { pr_info("key could not be set\n"); ret = -EAGAIN; goto out; @@ -1945,26 +1970,26 @@ static int test_ablkcipher(void) } get_random_bytes(scratchpad, 16); - ablk.tfm = ablkcipher; - ablk.req = req; + sk.tfm = skcipher; + sk.req = req; /* We encrypt one block */ - sg_init_one(&ablk.sg, scratchpad, 16); - ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); - init_completion(&ablk.result.completion); + sg_init_one(&sk.sg, scratchpad, 16); + skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata); + init_completion(&sk.result.completion); /* encrypt data */ - ret = test_ablkcipher_encdec(&ablk, 1); + ret = test_skcipher_encdec(&sk, 1); if (ret) goto out; pr_info("Encryption triggered successfully\n"); out: - if (ablkcipher) - crypto_free_ablkcipher(ablkcipher); + if (skcipher) + crypto_free_skcipher(skcipher); if (req) - ablkcipher_request_free(req); + skcipher_request_free(req); if (ivdata) kfree(ivdata); if (scratchpad) @@ -1974,77 +1999,6 @@ out: </programlisting> </sect1> - <sect1><title>Code Example For Synchronous Block Cipher Operation</title> - <programlisting> - -static int test_blkcipher(void) -{ - struct crypto_blkcipher *blkcipher = NULL; - char *cipher = "cbc(aes)"; - // AES 128 - charkey = -"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; - chariv = -"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; - unsigned int ivsize = 0; - char *scratchpad = NULL; // holds plaintext and ciphertext - struct scatterlist sg; - struct blkcipher_desc desc; - int ret = -EFAULT; - - blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); - if (IS_ERR(blkcipher)) { - printk("could not allocate blkcipher handle for %s\n", cipher); - return -PTR_ERR(blkcipher); - } - - if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { - printk("key could not be set\n"); - ret = -EAGAIN; - goto out; - } - - ivsize = crypto_blkcipher_ivsize(blkcipher); - if (ivsize) { - if (ivsize != strlen(iv)) - printk("IV length differs from expected length\n"); - crypto_blkcipher_set_iv(blkcipher, iv, ivsize); - } - - scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); - if (!scratchpad) { - printk("could not allocate scratchpad for %s\n", cipher); - goto out; - } - /* get some random data that we want to encrypt */ - get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); - - desc.flags = 0; - desc.tfm = blkcipher; - sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); - - /* encrypt data in place */ - crypto_blkcipher_encrypt(&desc, &sg, &sg, - crypto_blkcipher_blocksize(blkcipher)); - - /* decrypt data in place - * crypto_blkcipher_decrypt(&desc, &sg, &sg, - */ crypto_blkcipher_blocksize(blkcipher)); - - - printk("Cipher operation completed\n"); - return 0; - -out: - if (blkcipher) - crypto_free_blkcipher(blkcipher); - if (scratchpad) - kzfree(scratchpad); - return ret; -} - </programlisting> - </sect1> - <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> <programlisting> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 1d6008d51b55..184f3c7b5145 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -221,33 +221,54 @@ X!Isound/sound_firmware.c <title>Media Devices</title> <sect1><title>Video2Linux devices</title> +!Iinclude/media/tuner.h +!Iinclude/media/tuner-types.h +!Iinclude/media/tveeprom.h !Iinclude/media/v4l2-async.h !Iinclude/media/v4l2-ctrls.h !Iinclude/media/v4l2-dv-timings.h !Iinclude/media/v4l2-event.h !Iinclude/media/v4l2-flash-led-class.h +!Iinclude/media/v4l2-mc.h !Iinclude/media/v4l2-mediabus.h !Iinclude/media/v4l2-mem2mem.h !Iinclude/media/v4l2-of.h !Iinclude/media/v4l2-subdev.h !Iinclude/media/videobuf2-core.h +!Iinclude/media/videobuf2-v4l2.h !Iinclude/media/videobuf2-memops.h </sect1> <sect1><title>Digital TV (DVB) devices</title> -!Idrivers/media/dvb-core/dvb_ca_en50221.h -!Idrivers/media/dvb-core/dvb_frontend.h + <sect1><title>Digital TV Common functions</title> !Idrivers/media/dvb-core/dvb_math.h !Idrivers/media/dvb-core/dvb_ringbuffer.h !Idrivers/media/dvb-core/dvbdev.h + </sect1> + <sect1><title>Digital TV Frontend kABI</title> +!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend +!Idrivers/media/dvb-core/dvb_frontend.h + </sect1> + <sect1><title>Digital TV Demux kABI</title> +!Pdrivers/media/dvb-core/demux.h Digital TV Demux + <sect1><title>Demux Callback API</title> +!Pdrivers/media/dvb-core/demux.h Demux Callback + </sect1> +!Idrivers/media/dvb-core/demux.h + </sect1> + <sect1><title>Digital TV Conditional Access kABI</title> +!Idrivers/media/dvb-core/dvb_ca_en50221.h + </sect1> </sect1> - <sect1><title>Remote Controller devices</title> + <sect1><title>Remote Controller devices</title> !Iinclude/media/rc-core.h - </sect1> - <sect1><title>Media Controller devices</title> +!Iinclude/media/lirc_dev.h + </sect1> + <sect1><title>Media Controller devices</title> +!Pinclude/media/media-device.h Media Controller !Iinclude/media/media-device.h !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h - </sect1> + </sect1> </chapter> @@ -348,7 +369,7 @@ X!Ilib/fonts/fonts.c !Iinclude/linux/input-polldev.h !Edrivers/input/input-polldev.c </sect1> - <sect1><title>Matrix keyboars/keypads</title> + <sect1><title>Matrix keyboards/keypads</title> !Iinclude/linux/input/matrix_keypad.h </sect1> <sect1><title>Sparse keymap support</title> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/gpu.tmpl index 9ddf8c6cb887..a8669330b456 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/gpu.tmpl @@ -2,9 +2,9 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> -<book id="drmDevelopersGuide"> +<book id="gpuDevelopersGuide"> <bookinfo> - <title>Linux DRM Developer's Guide</title> + <title>Linux GPU Driver Developer's Guide</title> <authorgroup> <author> @@ -40,6 +40,16 @@ </address> </affiliation> </author> + <author> + <firstname>Lukas</firstname> + <surname>Wunner</surname> + <contrib>vga_switcheroo documentation</contrib> + <affiliation> + <address> + <email>lukas@wunner.de</email> + </address> + </affiliation> + </author> </authorgroup> <copyright> @@ -51,6 +61,10 @@ <year>2012</year> <holder>Laurent Pinchart</holder> </copyright> + <copyright> + <year>2015</year> + <holder>Lukas Wunner</holder> + </copyright> <legalnotice> <para> @@ -69,6 +83,13 @@ <revremark>Added extensive documentation about driver internals. </revremark> </revision> + <revision> + <revnumber>1.1</revnumber> + <date>2015-10-11</date> + <authorinitials>LW</authorinitials> + <revremark>Added vga_switcheroo documentation. + </revremark> + </revision> </revhistory> </bookinfo> @@ -78,9 +99,9 @@ <title>DRM Core</title> <partintro> <para> - This first part of the DRM Developer's Guide documents core DRM code, - helper libraries for writing drivers and generic userspace interfaces - exposed by DRM drivers. + This first part of the GPU Driver Developer's Guide documents core DRM + code, helper libraries for writing drivers and generic userspace + interfaces exposed by DRM drivers. </para> </partintro> @@ -103,6 +124,43 @@ <para> [Insert diagram of typical DRM stack here] </para> + <sect1> + <title>Style Guidelines</title> + <para> + For consistency this documentation uses American English. Abbreviations + are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so + on. To aid in reading, documentations make full use of the markup + characters kerneldoc provides: @parameter for function parameters, @member + for structure members, &structure to reference structures and + function() for functions. These all get automatically hyperlinked if + kerneldoc for the referenced objects exists. When referencing entries in + function vtables please use ->vfunc(). Note that kerneldoc does + not support referencing struct members directly, so please add a reference + to the vtable struct somewhere in the same paragraph or at least section. + </para> + <para> + Except in special situations (to separate locked from unlocked variants) + locking requirements for functions aren't documented in the kerneldoc. + Instead locking should be check at runtime using e.g. + <code>WARN_ON(!mutex_is_locked(...));</code>. Since it's much easier to + ignore documentation than runtime noise this provides more value. And on + top of that runtime checks do need to be updated when the locking rules + change, increasing the chances that they're correct. Within the + documentation the locking rules should be explained in the relevant + structures: Either in the comment for the lock explaining what it + protects, or data fields need a note about which lock protects them, or + both. + </para> + <para> + Functions which have a non-<code>void</code> return value should have a + section called "Returns" explaining the expected return values in + different cases and their meanings. Currently there's no consensus whether + that section name should be all upper-case or not, and whether it should + end in a colon or not. Go with the file-local style. Other common section + names are "Notes" with information for dangerous or tricky corner cases, + and "FIXME" where the interface could be cleaned up. + </para> + </sect1> </chapter> <!-- Internals --> @@ -138,14 +196,10 @@ <para> At the core of every DRM driver is a <structname>drm_driver</structname> structure. Drivers typically statically initialize a drm_driver structure, - and then pass it to one of the <function>drm_*_init()</function> functions - to register it with the DRM subsystem. - </para> - <para> - Newer drivers that no longer require a <structname>drm_bus</structname> - structure can alternatively use the low-level device initialization and - registration functions such as <function>drm_dev_alloc()</function> and - <function>drm_dev_register()</function> directly. + and then pass it to <function>drm_dev_alloc()</function> to allocate a + device instance. After the device instance is fully initialized it can be + registered (which makes it accessible from userspace) using + <function>drm_dev_register()</function>. </para> <para> The <structname>drm_driver</structname> structure contains static @@ -296,83 +350,12 @@ char *date;</synopsis> </sect3> </sect2> <sect2> - <title>Device Registration</title> - <para> - A number of functions are provided to help with device registration. - The functions deal with PCI and platform devices, respectively. - </para> -!Edrivers/gpu/drm/drm_pci.c -!Edrivers/gpu/drm/drm_platform.c - <para> - New drivers that no longer rely on the services provided by the - <structname>drm_bus</structname> structure can call the low-level - device registration functions directly. The - <function>drm_dev_alloc()</function> function can be used to allocate - and initialize a new <structname>drm_device</structname> structure. - Drivers will typically want to perform some additional setup on this - structure, such as allocating driver-specific data and storing a - pointer to it in the DRM device's <structfield>dev_private</structfield> - field. Drivers should also set the device's unique name using the - <function>drm_dev_set_unique()</function> function. After it has been - set up a device can be registered with the DRM subsystem by calling - <function>drm_dev_register()</function>. This will cause the device to - be exposed to userspace and will call the driver's - <structfield>.load()</structfield> implementation. When a device is - removed, the DRM device can safely be unregistered and freed by calling - <function>drm_dev_unregister()</function> followed by a call to - <function>drm_dev_unref()</function>. - </para> + <title>Device Instance and Driver Handling</title> +!Pdrivers/gpu/drm/drm_drv.c driver instance overview !Edrivers/gpu/drm/drm_drv.c </sect2> <sect2> <title>Driver Load</title> - <para> - The <methodname>load</methodname> method is the driver and device - initialization entry point. The method is responsible for allocating and - initializing driver private data, performing resource allocation and - mapping (e.g. acquiring - clocks, mapping registers or allocating command buffers), initializing - the memory manager (<xref linkend="drm-memory-management"/>), installing - the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up - vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode - setting (<xref linkend="drm-mode-setting"/>) and initial output - configuration (<xref linkend="drm-kms-init"/>). - </para> - <note><para> - If compatibility is a concern (e.g. with drivers converted over from - User Mode Setting to Kernel Mode Setting), care must be taken to prevent - device initialization and control that is incompatible with currently - active userspace drivers. For instance, if user level mode setting - drivers are in use, it would be problematic to perform output discovery - & configuration at load time. Likewise, if user-level drivers - unaware of memory management are in use, memory management and command - buffer setup may need to be omitted. These requirements are - driver-specific, and care needs to be taken to keep both old and new - applications and libraries working. - </para></note> - <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis> - <para> - The method takes two arguments, a pointer to the newly created - <structname>drm_device</structname> and flags. The flags are used to - pass the <structfield>driver_data</structfield> field of the device id - corresponding to the device passed to <function>drm_*_init()</function>. - Only PCI devices currently use this, USB and platform DRM drivers have - their <methodname>load</methodname> method called with flags to 0. - </para> - <sect3> - <title>Driver Private Data</title> - <para> - The driver private hangs off the main - <structname>drm_device</structname> structure and can be used for - tracking various device-specific bits of information, like register - offsets, command buffer status, register state for suspend/resume, etc. - At load time, a driver may simply allocate one and set - <structname>drm_device</structname>.<structfield>dev_priv</structfield> - appropriately; it should be freed and - <structname>drm_device</structname>.<structfield>dev_priv</structfield> - set to NULL when the driver is unloaded. - </para> - </sect3> <sect3 id="drm-irq-registration"> <title>IRQ Registration</title> <para> @@ -465,6 +448,18 @@ char *date;</synopsis> </para> </sect3> </sect2> + <sect2> + <title>Bus-specific Device Registration and PCI Support</title> + <para> + A number of functions are provided to help with device registration. + The functions deal with PCI and platform devices respectively and are + only provided for historical reasons. These are all deprecated and + shouldn't be used in new drivers. Besides that there's a few + helpers for pci drivers. + </para> +!Edrivers/gpu/drm/drm_pci.c +!Edrivers/gpu/drm/drm_platform.c + </sect2> </sect1> <!-- Internals: memory management --> @@ -657,18 +652,6 @@ char *date;</synopsis> <function>drm_gem_object_init</function>. Storage for private GEM objects must be managed by drivers. </para> - <para> - Drivers that do not need to extend GEM objects with private information - can call the <function>drm_gem_object_alloc</function> function to - allocate and initialize a struct <structname>drm_gem_object</structname> - instance. The GEM core will call the optional driver - <methodname>gem_init_object</methodname> operation after initializing - the GEM object with <function>drm_gem_object_init</function>. - <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis> - </para> - <para> - No alloc-and-init function exists for private GEM objects. - </para> </sect3> <sect3> <title>GEM Objects Lifetime</title> @@ -677,10 +660,10 @@ char *date;</synopsis> acquired and release by <function>calling drm_gem_object_reference</function> and <function>drm_gem_object_unreference</function> respectively. The caller must hold the <structname>drm_device</structname> - <structfield>struct_mutex</structfield> lock. As a convenience, GEM - provides the <function>drm_gem_object_reference_unlocked</function> and - <function>drm_gem_object_unreference_unlocked</function> functions that - can be called without holding the lock. + <structfield>struct_mutex</structfield> lock when calling + <function>drm_gem_object_reference</function>. As a convenience, GEM + provides <function>drm_gem_object_unreference_unlocked</function> + functions that can be called without holding the lock. </para> <para> When the last reference to a GEM object is released the GEM core calls @@ -691,15 +674,9 @@ char *date;</synopsis> </para> <para> <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis> - Drivers are responsible for freeing all GEM object resources, including - the resources created by the GEM core. If an mmap offset has been - created for the object (in which case - <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield> - is not NULL) it must be freed by a call to - <function>drm_gem_free_mmap_offset</function>. The shmfs backing store - must be released by calling <function>drm_gem_object_release</function> - (that function can safely be called if no shmfs backing store has been - created). + Drivers are responsible for freeing all GEM object resources. This includes + the resources created by the GEM core, which need to be released with + <function>drm_gem_object_release</function>. </para> </sect3> <sect3> @@ -782,17 +759,10 @@ char *date;</synopsis> DRM identifies the GEM object to be mapped by a fake offset passed through the mmap offset argument. Prior to being mapped, a GEM object must thus be associated with a fake offset. To do so, drivers must call - <function>drm_gem_create_mmap_offset</function> on the object. The - function allocates a fake offset range from a pool and stores the - offset divided by PAGE_SIZE in - <literal>obj->map_list.hash.key</literal>. Care must be taken not to - call <function>drm_gem_create_mmap_offset</function> if a fake offset - has already been allocated for the object. This can be tested by - <literal>obj->map_list.map</literal> being non-NULL. + <function>drm_gem_create_mmap_offset</function> on the object. </para> <para> Once allocated, the fake offset value - (<literal>obj->map_list.hash.key << PAGE_SHIFT</literal>) must be passed to the application in a driver-specific way and can then be used as the mmap offset argument. </para> @@ -878,10 +848,11 @@ char *date;</synopsis> abstracted from the client in libdrm. </para> </sect3> - <sect3> - <title>GEM Function Reference</title> + </sect2> + <sect2> + <title>GEM Function Reference</title> !Edrivers/gpu/drm/drm_gem.c - </sect3> +!Iinclude/drm/drm_gem.h </sect2> <sect2> <title>VMA Offset Manager</title> @@ -1012,12 +983,10 @@ int max_width, max_height;</synopsis> <sect2> <title>Atomic Mode Setting Function Reference</title> !Edrivers/gpu/drm/drm_atomic.c +!Idrivers/gpu/drm/drm_atomic.c </sect2> <sect2> - <title>Frame Buffer Creation</title> - <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, - struct drm_file *file_priv, - struct drm_mode_fb_cmd2 *mode_cmd);</synopsis> + <title>Frame Buffer Abstraction</title> <para> Frame buffers are abstract memory objects that provide a source of pixels to scanout to a CRTC. Applications explicitly request the @@ -1036,73 +1005,6 @@ int max_width, max_height;</synopsis> and so expects TTM handles in the create ioctl and not GEM handles. </para> <para> - Drivers must first validate the requested frame buffer parameters passed - through the mode_cmd argument. In particular this is where invalid - sizes, pixel formats or pitches can be caught. - </para> - <para> - If the parameters are deemed valid, drivers then create, initialize and - return an instance of struct <structname>drm_framebuffer</structname>. - If desired the instance can be embedded in a larger driver-specific - structure. Drivers must fill its <structfield>width</structfield>, - <structfield>height</structfield>, <structfield>pitches</structfield>, - <structfield>offsets</structfield>, <structfield>depth</structfield>, - <structfield>bits_per_pixel</structfield> and - <structfield>pixel_format</structfield> fields from the values passed - through the <parameter>drm_mode_fb_cmd2</parameter> argument. They - should call the <function>drm_helper_mode_fill_fb_struct</function> - helper function to do so. - </para> - - <para> - The initialization of the new framebuffer instance is finalized with a - call to <function>drm_framebuffer_init</function> which takes a pointer - to DRM frame buffer operations (struct - <structname>drm_framebuffer_funcs</structname>). Note that this function - publishes the framebuffer and so from this point on it can be accessed - concurrently from other threads. Hence it must be the last step in the - driver's framebuffer initialization sequence. Frame buffer operations - are - <itemizedlist> - <listitem> - <synopsis>int (*create_handle)(struct drm_framebuffer *fb, - struct drm_file *file_priv, unsigned int *handle);</synopsis> - <para> - Create a handle to the frame buffer underlying memory object. If - the frame buffer uses a multi-plane format, the handle will - reference the memory object associated with the first plane. - </para> - <para> - Drivers call <function>drm_gem_handle_create</function> to create - the handle. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis> - <para> - Destroy the frame buffer object and frees all associated - resources. Drivers must call - <function>drm_framebuffer_cleanup</function> to free resources - allocated by the DRM core for the frame buffer object, and must - make sure to unreference all memory objects associated with the - frame buffer. Handles created by the - <methodname>create_handle</methodname> operation are released by - the DRM core. - </para> - </listitem> - <listitem> - <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer, - struct drm_file *file_priv, unsigned flags, unsigned color, - struct drm_clip_rect *clips, unsigned num_clips);</synopsis> - <para> - This optional operation notifies the driver that a region of the - frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB - ioctl call. - </para> - </listitem> - </itemizedlist> - </para> - <para> The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with <function>drm_framebuffer_reference</function>and drop them @@ -1239,137 +1141,6 @@ int max_width, max_height;</synopsis> pointer to CRTC functions. </para> </sect3> - <sect3 id="drm-kms-crtcops"> - <title>CRTC Operations</title> - <sect4> - <title>Set Configuration</title> - <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis> - <para> - Apply a new CRTC configuration to the device. The configuration - specifies a CRTC, a frame buffer to scan out from, a (x,y) position in - the frame buffer, a display mode and an array of connectors to drive - with the CRTC if possible. - </para> - <para> - If the frame buffer specified in the configuration is NULL, the driver - must detach all encoders connected to the CRTC and all connectors - attached to those encoders and disable them. - </para> - <para> - This operation is called with the mode config lock held. - </para> - <note><para> - Note that the drm core has no notion of restoring the mode setting - state after resume, since all resume handling is in the full - responsibility of the driver. The common mode setting helper library - though provides a helper which can be used for this: - <function>drm_helper_resume_force_mode</function>. - </para></note> - </sect4> - <sect4> - <title>Page Flipping</title> - <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, - struct drm_pending_vblank_event *event);</synopsis> - <para> - Schedule a page flip to the given frame buffer for the CRTC. This - operation is called with the mode config mutex held. - </para> - <para> - Page flipping is a synchronization mechanism that replaces the frame - buffer being scanned out by the CRTC with a new frame buffer during - vertical blanking, avoiding tearing. When an application requests a page - flip the DRM core verifies that the new frame buffer is large enough to - be scanned out by the CRTC in the currently configured mode and then - calls the CRTC <methodname>page_flip</methodname> operation with a - pointer to the new frame buffer. - </para> - <para> - The <methodname>page_flip</methodname> operation schedules a page flip. - Once any pending rendering targeting the new frame buffer has - completed, the CRTC will be reprogrammed to display that frame buffer - after the next vertical refresh. The operation must return immediately - without waiting for rendering or page flip to complete and must block - any new rendering to the frame buffer until the page flip completes. - </para> - <para> - If a page flip can be successfully scheduled the driver must set the - <code>drm_crtc->fb</code> field to the new framebuffer pointed to - by <code>fb</code>. This is important so that the reference counting - on framebuffers stays balanced. - </para> - <para> - If a page flip is already pending, the - <methodname>page_flip</methodname> operation must return - -<errorname>EBUSY</errorname>. - </para> - <para> - To synchronize page flip to vertical blanking the driver will likely - need to enable vertical blanking interrupts. It should call - <function>drm_vblank_get</function> for that purpose, and call - <function>drm_vblank_put</function> after the page flip completes. - </para> - <para> - If the application has requested to be notified when page flip completes - the <methodname>page_flip</methodname> operation will be called with a - non-NULL <parameter>event</parameter> argument pointing to a - <structname>drm_pending_vblank_event</structname> instance. Upon page - flip completion the driver must call <methodname>drm_send_vblank_event</methodname> - to fill in the event and send to wake up any waiting processes. - This can be performed with - <programlisting><![CDATA[ - spin_lock_irqsave(&dev->event_lock, flags); - ... - drm_send_vblank_event(dev, pipe, event); - spin_unlock_irqrestore(&dev->event_lock, flags); - ]]></programlisting> - </para> - <note><para> - FIXME: Could drivers that don't need to wait for rendering to complete - just add the event to <literal>dev->vblank_event_list</literal> and - let the DRM core handle everything, as for "normal" vertical blanking - events? - </para></note> - <para> - While waiting for the page flip to complete, the - <literal>event->base.link</literal> list head can be used freely by - the driver to store the pending event in a driver-specific list. - </para> - <para> - If the file handle is closed before the event is signaled, drivers must - take care to destroy the event in their - <methodname>preclose</methodname> operation (and, if needed, call - <function>drm_vblank_put</function>). - </para> - </sect4> - <sect4> - <title>Miscellaneous</title> - <itemizedlist> - <listitem> - <synopsis>void (*set_property)(struct drm_crtc *crtc, - struct drm_property *property, uint64_t value);</synopsis> - <para> - Set the value of the given CRTC property to - <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> - for more information about properties. - </para> - </listitem> - <listitem> - <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, - uint32_t start, uint32_t size);</synopsis> - <para> - Apply a gamma table to the device. The operation is optional. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis> - <para> - Destroy the CRTC when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - </itemizedlist> - </sect4> - </sect3> </sect2> <sect2> <title>Planes (struct <structname>drm_plane</structname>)</title> @@ -1386,7 +1157,7 @@ int max_width, max_height;</synopsis> <listitem> DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary planes are the planes operated upon by CRTC modesetting and flipping - operations described in <xref linkend="drm-kms-crtcops"/>. + operations described in the page_flip hook in <structname>drm_crtc_funcs</structname>. </listitem> <listitem> DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor @@ -1423,52 +1194,6 @@ int max_width, max_height;</synopsis> primary plane with standard capabilities. </para> </sect3> - <sect3> - <title>Plane Operations</title> - <itemizedlist> - <listitem> - <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, - struct drm_framebuffer *fb, int crtc_x, int crtc_y, - unsigned int crtc_w, unsigned int crtc_h, - uint32_t src_x, uint32_t src_y, - uint32_t src_w, uint32_t src_h);</synopsis> - <para> - Enable and configure the plane to use the given CRTC and frame buffer. - </para> - <para> - The source rectangle in frame buffer memory coordinates is given by - the <parameter>src_x</parameter>, <parameter>src_y</parameter>, - <parameter>src_w</parameter> and <parameter>src_h</parameter> - parameters (as 16.16 fixed point values). Devices that don't support - subpixel plane coordinates can ignore the fractional part. - </para> - <para> - The destination rectangle in CRTC coordinates is given by the - <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>, - <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter> - parameters (as integer values). Devices scale the source rectangle to - the destination rectangle. If scaling is not supported, and the source - rectangle size doesn't match the destination rectangle size, the - driver must return a -<errorname>EINVAL</errorname> error. - </para> - </listitem> - <listitem> - <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis> - <para> - Disable the plane. The DRM core calls this method in response to a - DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. - Disabled planes must not be processed by the CRTC. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis> - <para> - Destroy the plane when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - </itemizedlist> - </sect3> </sect2> <sect2> <title>Encoders (struct <structname>drm_encoder</structname>)</title> @@ -1525,27 +1250,6 @@ int max_width, max_height;</synopsis> encoders they want to use to a CRTC. </para> </sect3> - <sect3> - <title>Encoder Operations</title> - <itemizedlist> - <listitem> - <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis> - <para> - Called to destroy the encoder when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - <listitem> - <synopsis>void (*set_property)(struct drm_plane *plane, - struct drm_property *property, uint64_t value);</synopsis> - <para> - Set the value of the given plane property to - <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> - for more information about properties. - </para> - </listitem> - </itemizedlist> - </sect3> </sect2> <sect2> <title>Connectors (struct <structname>drm_connector</structname>)</title> @@ -1749,27 +1453,6 @@ int max_width, max_height;</synopsis> connector_status_unknown. </para> </sect4> - <sect4> - <title>Miscellaneous</title> - <itemizedlist> - <listitem> - <synopsis>void (*set_property)(struct drm_connector *connector, - struct drm_property *property, uint64_t value);</synopsis> - <para> - Set the value of the given connector property to - <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> - for more information about properties. - </para> - </listitem> - <listitem> - <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis> - <para> - Destroy the connector when not needed anymore. See - <xref linkend="drm-kms-init"/>. - </para> - </listitem> - </itemizedlist> - </sect4> </sect3> </sect2> <sect2> @@ -1896,462 +1579,6 @@ void intel_crt_init(struct drm_device *dev) entities. </para> <sect2> - <title>Helper Functions</title> - <itemizedlist> - <listitem> - <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis> - <para> - The <function>drm_crtc_helper_set_config</function> helper function - is a CRTC <methodname>set_config</methodname> implementation. It - first tries to locate the best encoder for each connector by calling - the connector <methodname>best_encoder</methodname> helper - operation. - </para> - <para> - After locating the appropriate encoders, the helper function will - call the <methodname>mode_fixup</methodname> encoder and CRTC helper - operations to adjust the requested mode, or reject it completely in - which case an error will be returned to the application. If the new - configuration after mode adjustment is identical to the current - configuration the helper function will return without performing any - other operation. - </para> - <para> - If the adjusted mode is identical to the current mode but changes to - the frame buffer need to be applied, the - <function>drm_crtc_helper_set_config</function> function will call - the CRTC <methodname>mode_set_base</methodname> helper operation. If - the adjusted mode differs from the current mode, or if the - <methodname>mode_set_base</methodname> helper operation is not - provided, the helper function performs a full mode set sequence by - calling the <methodname>prepare</methodname>, - <methodname>mode_set</methodname> and - <methodname>commit</methodname> CRTC and encoder helper operations, - in that order. - </para> - </listitem> - <listitem> - <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis> - <para> - The <function>drm_helper_connector_dpms</function> helper function - is a connector <methodname>dpms</methodname> implementation that - tracks power state of connectors. To use the function, drivers must - provide <methodname>dpms</methodname> helper operations for CRTCs - and encoders to apply the DPMS state to the device. - </para> - <para> - The mid-layer doesn't track the power state of CRTCs and encoders. - The <methodname>dpms</methodname> helper operations can thus be - called with a mode identical to the currently active mode. - </para> - </listitem> - <listitem> - <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector, - uint32_t maxX, uint32_t maxY);</synopsis> - <para> - The <function>drm_helper_probe_single_connector_modes</function> helper - function is a connector <methodname>fill_modes</methodname> - implementation that updates the connection status for the connector - and then retrieves a list of modes by calling the connector - <methodname>get_modes</methodname> helper operation. - </para> - <para> - If the helper operation returns no mode, and if the connector status - is connector_status_connected, standard VESA DMT modes up to - 1024x768 are automatically added to the modes list by a call to - <function>drm_add_modes_noedid</function>. - </para> - <para> - The function then filters out modes larger than - <parameter>max_width</parameter> and <parameter>max_height</parameter> - if specified. It finally calls the optional connector - <methodname>mode_valid</methodname> helper operation for each mode in - the probed list to check whether the mode is valid for the connector. - </para> - </listitem> - </itemizedlist> - </sect2> - <sect2> - <title>CRTC Helper Operations</title> - <itemizedlist> - <listitem id="drm-helper-crtc-mode-fixup"> - <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode);</synopsis> - <para> - Let CRTCs adjust the requested mode or reject it completely. This - operation returns true if the mode is accepted (possibly after being - adjusted) or false if it is rejected. - </para> - <para> - The <methodname>mode_fixup</methodname> operation should reject the - mode if it can't reasonably use it. The definition of "reasonable" - is currently fuzzy in this context. One possible behaviour would be - to set the adjusted mode to the panel timings when a fixed-mode - panel is used with hardware capable of scaling. Another behaviour - would be to accept any input mode and adjust it to the closest mode - supported by the hardware (FIXME: This needs to be clarified). - </para> - </listitem> - <listitem> - <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, - struct drm_framebuffer *old_fb)</synopsis> - <para> - Move the CRTC on the current frame buffer (stored in - <literal>crtc->fb</literal>) to position (x,y). Any of the frame - buffer, x position or y position may have been modified. - </para> - <para> - This helper operation is optional. If not provided, the - <function>drm_crtc_helper_set_config</function> function will fall - back to the <methodname>mode_set</methodname> helper operation. - </para> - <note><para> - FIXME: Why are x and y passed as arguments, as they can be accessed - through <literal>crtc->x</literal> and - <literal>crtc->y</literal>? - </para></note> - </listitem> - <listitem> - <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis> - <para> - Prepare the CRTC for mode setting. This operation is called after - validating the requested mode. Drivers use it to perform - device-specific operations required before setting the new mode. - </para> - </listitem> - <listitem> - <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode, int x, int y, - struct drm_framebuffer *old_fb);</synopsis> - <para> - Set a new mode, position and frame buffer. Depending on the device - requirements, the mode can be stored internally by the driver and - applied in the <methodname>commit</methodname> operation, or - programmed to the hardware immediately. - </para> - <para> - The <methodname>mode_set</methodname> operation returns 0 on success - or a negative error code if an error occurs. - </para> - </listitem> - <listitem> - <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis> - <para> - Commit a mode. This operation is called after setting the new mode. - Upon return the device must use the new mode and be fully - operational. - </para> - </listitem> - </itemizedlist> - </sect2> - <sect2> - <title>Encoder Helper Operations</title> - <itemizedlist> - <listitem> - <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder, - const struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode);</synopsis> - <para> - Let encoders adjust the requested mode or reject it completely. This - operation returns true if the mode is accepted (possibly after being - adjusted) or false if it is rejected. See the - <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper - operation</link> for an explanation of the allowed adjustments. - </para> - </listitem> - <listitem> - <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis> - <para> - Prepare the encoder for mode setting. This operation is called after - validating the requested mode. Drivers use it to perform - device-specific operations required before setting the new mode. - </para> - </listitem> - <listitem> - <synopsis>void (*mode_set)(struct drm_encoder *encoder, - struct drm_display_mode *mode, - struct drm_display_mode *adjusted_mode);</synopsis> - <para> - Set a new mode. Depending on the device requirements, the mode can - be stored internally by the driver and applied in the - <methodname>commit</methodname> operation, or programmed to the - hardware immediately. - </para> - </listitem> - <listitem> - <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis> - <para> - Commit a mode. This operation is called after setting the new mode. - Upon return the device must use the new mode and be fully - operational. - </para> - </listitem> - </itemizedlist> - </sect2> - <sect2> - <title>Connector Helper Operations</title> - <itemizedlist> - <listitem> - <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis> - <para> - Return a pointer to the best encoder for the connecter. Device that - map connectors to encoders 1:1 simply return the pointer to the - associated encoder. This operation is mandatory. - </para> - </listitem> - <listitem> - <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis> - <para> - Fill the connector's <structfield>probed_modes</structfield> list - by parsing EDID data with <function>drm_add_edid_modes</function>, - adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>, - or calling <function>drm_mode_probed_add</function> directly for every - supported mode and return the number of modes it has detected. This - operation is mandatory. - </para> - <para> - Note that the caller function will automatically add standard VESA - DMT modes up to 1024x768 if the <methodname>get_modes</methodname> - helper operation returns no mode and if the connector status is - connector_status_connected. There is no need to call - <function>drm_add_edid_modes</function> manually in that case. - </para> - <para> - When adding modes manually the driver creates each mode with a call to - <function>drm_mode_create</function> and must fill the following fields. - <itemizedlist> - <listitem> - <synopsis>__u32 type;</synopsis> - <para> - Mode type bitmask, a combination of - <variablelist> - <varlistentry> - <term>DRM_MODE_TYPE_BUILTIN</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_CLOCK_C</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_CRTC_C</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term> - DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector - </term> - <listitem> - <para>not used?</para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_DEFAULT</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_USERDEF</term> - <listitem><para>not used?</para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_TYPE_DRIVER</term> - <listitem> - <para> - The mode has been created by the driver (as opposed to - to user-created modes). - </para> - </listitem> - </varlistentry> - </variablelist> - Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they - create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred - mode. - </para> - </listitem> - <listitem> - <synopsis>__u32 clock;</synopsis> - <para>Pixel clock frequency in kHz unit</para> - </listitem> - <listitem> - <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal; - __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis> - <para>Horizontal and vertical timing information</para> - <screen><![CDATA[ - Active Front Sync Back - Region Porch Porch - <-----------------------><----------------><-------------><--------------> - - //////////////////////| - ////////////////////// | - ////////////////////// |.................. ................ - _______________ - - <----- [hv]display -----> - <------------- [hv]sync_start ------------> - <--------------------- [hv]sync_end ---------------------> - <-------------------------------- [hv]total -----------------------------> -]]></screen> - </listitem> - <listitem> - <synopsis>__u16 hskew; - __u16 vscan;</synopsis> - <para>Unknown</para> - </listitem> - <listitem> - <synopsis>__u32 flags;</synopsis> - <para> - Mode flags, a combination of - <variablelist> - <varlistentry> - <term>DRM_MODE_FLAG_PHSYNC</term> - <listitem><para> - Horizontal sync is active high - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_NHSYNC</term> - <listitem><para> - Horizontal sync is active low - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_PVSYNC</term> - <listitem><para> - Vertical sync is active high - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_NVSYNC</term> - <listitem><para> - Vertical sync is active low - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_INTERLACE</term> - <listitem><para> - Mode is interlaced - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_DBLSCAN</term> - <listitem><para> - Mode uses doublescan - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_CSYNC</term> - <listitem><para> - Mode uses composite sync - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_PCSYNC</term> - <listitem><para> - Composite sync is active high - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_NCSYNC</term> - <listitem><para> - Composite sync is active low - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_HSKEW</term> - <listitem><para> - hskew provided (not used?) - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_BCAST</term> - <listitem><para> - not used? - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_PIXMUX</term> - <listitem><para> - not used? - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_DBLCLK</term> - <listitem><para> - not used? - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRM_MODE_FLAG_CLKDIV2</term> - <listitem><para> - ? - </para></listitem> - </varlistentry> - </variablelist> - </para> - <para> - Note that modes marked with the INTERLACE or DBLSCAN flags will be - filtered out by - <function>drm_helper_probe_single_connector_modes</function> if - the connector's <structfield>interlace_allowed</structfield> or - <structfield>doublescan_allowed</structfield> field is set to 0. - </para> - </listitem> - <listitem> - <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis> - <para> - Mode name. The driver must call - <function>drm_mode_set_name</function> to fill the mode name from - <structfield>hdisplay</structfield>, - <structfield>vdisplay</structfield> and interlace flag after - filling the corresponding fields. - </para> - </listitem> - </itemizedlist> - </para> - <para> - The <structfield>vrefresh</structfield> value is computed by - <function>drm_helper_probe_single_connector_modes</function>. - </para> - <para> - When parsing EDID data, <function>drm_add_edid_modes</function> fills the - connector <structfield>display_info</structfield> - <structfield>width_mm</structfield> and - <structfield>height_mm</structfield> fields. When creating modes - manually the <methodname>get_modes</methodname> helper operation must - set the <structfield>display_info</structfield> - <structfield>width_mm</structfield> and - <structfield>height_mm</structfield> fields if they haven't been set - already (for instance at initialization time when a fixed-size panel is - attached to the connector). The mode <structfield>width_mm</structfield> - and <structfield>height_mm</structfield> fields are only used internally - during EDID parsing and should not be set when creating modes manually. - </para> - </listitem> - <listitem> - <synopsis>int (*mode_valid)(struct drm_connector *connector, - struct drm_display_mode *mode);</synopsis> - <para> - Verify whether a mode is valid for the connector. Return MODE_OK for - supported modes and one of the enum drm_mode_status values (MODE_*) - for unsupported modes. This operation is optional. - </para> - <para> - As the mode rejection reason is currently not used beside for - immediately removing the unsupported mode, an implementation can - return MODE_BAD regardless of the exact reason why the mode is not - valid. - </para> - <note><para> - Note that the <methodname>mode_valid</methodname> helper operation is - only called for modes detected by the device, and - <emphasis>not</emphasis> for modes set by the user through the CRTC - <methodname>set_config</methodname> operation. - </para></note> - </listitem> - </itemizedlist> - </sect2> - <sect2> <title>Atomic Modeset Helper Functions Reference</title> <sect3> <title>Overview</title> @@ -2369,8 +1596,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_atomic_helper.c </sect2> <sect2> - <title>Modeset Helper Functions Reference</title> -!Iinclude/drm/drm_crtc_helper.h + <title>Modeset Helper Reference for Common Vtables</title> +!Iinclude/drm/drm_modeset_helper_vtables.h +!Pinclude/drm/drm_modeset_helper_vtables.h overview + </sect2> + <sect2> + <title>Legacy CRTC/Modeset Helper Functions Reference</title> !Edrivers/gpu/drm/drm_crtc_helper.c !Pdrivers/gpu/drm/drm_crtc_helper.c overview </sect2> @@ -3646,10 +2877,11 @@ void (*postclose) (struct drm_device *, struct drm_file *);</synopsis> plane properties to default value, so that a subsequent open of the device will not inherit state from the previous user. It can also be used to execute delayed power switching state changes, e.g. in - conjunction with the vga-switcheroo infrastructure. Beyond that KMS - drivers should not do any further cleanup. Only legacy UMS drivers might - need to clean up device state so that the vga console or an independent - fbdev driver could take over. + conjunction with the vga_switcheroo infrastructure (see + <xref linkend="vga_switcheroo"/>). Beyond that KMS drivers should not + do any further cleanup. Only legacy UMS drivers might need to clean up + device state so that the vga console or an independent fbdev driver + could take over. </para> </sect2> <sect2> @@ -3747,11 +2979,14 @@ int num_ioctls;</synopsis> </para></listitem> <listitem><para> DRM_UNLOCKED - The ioctl handler will be called without locking - the DRM global mutex + the DRM global mutex. This is the enforced default for kms drivers + (i.e. using the DRIVER_MODESET flag) and hence shouldn't be used + any more for new drivers. </para></listitem> </itemizedlist> </para> </para> +!Edrivers/gpu/drm/drm_ioctl.c </sect2> </sect1> <sect1> @@ -3949,8 +3184,8 @@ int num_ioctls;</synopsis> <partintro> <para> - This second part of the DRM Developer's Guide documents driver code, - implementation details and also all the driver-specific userspace + This second part of the GPU Driver Developer's Guide documents driver + code, implementation details and also all the driver-specific userspace interfaces. Especially since all hardware-acceleration interfaces to userspace are driver specific for efficiency and other reasons these interfaces can be rather substantial. Hence every driver has its own @@ -4051,6 +3286,7 @@ int num_ioctls;</synopsis> <title>High Definition Audio</title> !Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port !Idrivers/gpu/drm/i915/intel_audio.c +!Iinclude/drm/i915_component.h </sect2> <sect2> <title>Panel Self Refresh PSR (PSR/SRD)</title> @@ -4076,92 +3312,6 @@ int num_ioctls;</synopsis> <sect2> <title>DPIO</title> !Pdrivers/gpu/drm/i915/i915_reg.h DPIO - <table id="dpiox2"> - <title>Dual channel PHY (VLV/CHV/BXT)</title> - <tgroup cols="8"> - <colspec colname="c0" /> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <colspec colname="c4" /> - <colspec colname="c5" /> - <colspec colname="c6" /> - <colspec colname="c7" /> - <spanspec spanname="ch0" namest="c0" nameend="c3" /> - <spanspec spanname="ch1" namest="c4" nameend="c7" /> - <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" /> - <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" /> - <spanspec spanname="ch1pcs01" namest="c4" nameend="c5" /> - <spanspec spanname="ch1pcs23" namest="c6" nameend="c7" /> - <thead> - <row> - <entry spanname="ch0">CH0</entry> - <entry spanname="ch1">CH1</entry> - </row> - </thead> - <tbody valign="top" align="center"> - <row> - <entry spanname="ch0">CMN/PLL/REF</entry> - <entry spanname="ch1">CMN/PLL/REF</entry> - </row> - <row> - <entry spanname="ch0pcs01">PCS01</entry> - <entry spanname="ch0pcs23">PCS23</entry> - <entry spanname="ch1pcs01">PCS01</entry> - <entry spanname="ch1pcs23">PCS23</entry> - </row> - <row> - <entry>TX0</entry> - <entry>TX1</entry> - <entry>TX2</entry> - <entry>TX3</entry> - <entry>TX0</entry> - <entry>TX1</entry> - <entry>TX2</entry> - <entry>TX3</entry> - </row> - <row> - <entry spanname="ch0">DDI0</entry> - <entry spanname="ch1">DDI1</entry> - </row> - </tbody> - </tgroup> - </table> - <table id="dpiox1"> - <title>Single channel PHY (CHV/BXT)</title> - <tgroup cols="4"> - <colspec colname="c0" /> - <colspec colname="c1" /> - <colspec colname="c2" /> - <colspec colname="c3" /> - <spanspec spanname="ch0" namest="c0" nameend="c3" /> - <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" /> - <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" /> - <thead> - <row> - <entry spanname="ch0">CH0</entry> - </row> - </thead> - <tbody valign="top" align="center"> - <row> - <entry spanname="ch0">CMN/PLL/REF</entry> - </row> - <row> - <entry spanname="ch0pcs01">PCS01</entry> - <entry spanname="ch0pcs23">PCS23</entry> - </row> - <row> - <entry>TX0</entry> - <entry>TX1</entry> - <entry>TX2</entry> - <entry>TX3</entry> - </row> - <row> - <entry spanname="ch0">DDI2</entry> - </row> - </tbody> - </tgroup> - </table> </sect2> <sect2> @@ -4238,6 +3388,24 @@ int num_ioctls;</synopsis> </sect2> </sect1> <sect1> + <title>GuC</title> + <sect2> + <title>GuC-specific firmware loader</title> +!Pdrivers/gpu/drm/i915/intel_guc_loader.c GuC-specific firmware loader +!Idrivers/gpu/drm/i915/intel_guc_loader.c + </sect2> + <sect2> + <title>GuC-based command submission</title> +!Pdrivers/gpu/drm/i915/i915_guc_submission.c GuC-based command submission +!Idrivers/gpu/drm/i915/i915_guc_submission.c + </sect2> + <sect2> + <title>GuC Firmware Layout</title> +!Pdrivers/gpu/drm/i915/intel_guc_fwif.h GuC Firmware Layout + </sect2> + </sect1> + + <sect1> <title> Tracing </title> <para> This sections covers all things related to the tracepoints implemented in @@ -4260,4 +3428,72 @@ int num_ioctls;</synopsis> </chapter> !Cdrivers/gpu/drm/i915/i915_irq.c </part> + +<part id="vga_switcheroo"> + <title>vga_switcheroo</title> + <partintro> +!Pdrivers/gpu/vga/vga_switcheroo.c Overview + </partintro> + + <chapter id="modes_of_use"> + <title>Modes of Use</title> + <sect1> + <title>Manual switching and manual power control</title> +!Pdrivers/gpu/vga/vga_switcheroo.c Manual switching and manual power control + </sect1> + <sect1> + <title>Driver power control</title> +!Pdrivers/gpu/vga/vga_switcheroo.c Driver power control + </sect1> + </chapter> + + <chapter id="api"> + <title>API</title> + <sect1> + <title>Public functions</title> +!Edrivers/gpu/vga/vga_switcheroo.c + </sect1> + <sect1> + <title>Public structures</title> +!Finclude/linux/vga_switcheroo.h vga_switcheroo_handler +!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_ops + </sect1> + <sect1> + <title>Public constants</title> +!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_id +!Finclude/linux/vga_switcheroo.h vga_switcheroo_state + </sect1> + <sect1> + <title>Private structures</title> +!Fdrivers/gpu/vga/vga_switcheroo.c vgasr_priv +!Fdrivers/gpu/vga/vga_switcheroo.c vga_switcheroo_client + </sect1> + </chapter> + + <chapter id="handlers"> + <title>Handlers</title> + <sect1> + <title>apple-gmux Handler</title> +!Pdrivers/platform/x86/apple-gmux.c Overview +!Pdrivers/platform/x86/apple-gmux.c Interrupt + <sect2> + <title>Graphics mux</title> +!Pdrivers/platform/x86/apple-gmux.c Graphics mux + </sect2> + <sect2> + <title>Power control</title> +!Pdrivers/platform/x86/apple-gmux.c Power control + </sect2> + <sect2> + <title>Backlight control</title> +!Pdrivers/platform/x86/apple-gmux.c Backlight control + </sect2> + </sect1> + </chapter> + +!Cdrivers/gpu/vga/vga_switcheroo.c +!Cinclude/linux/vga_switcheroo.h +!Cdrivers/platform/x86/apple-gmux.c +</part> + </book> diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl index 06bb53de5a47..f525bf56d1dd 100644 --- a/Documentation/DocBook/iio.tmpl +++ b/Documentation/DocBook/iio.tmpl @@ -458,7 +458,7 @@ .scan_type = { .sign = 's', .realbits = 12, - .storgebits = 16, + .storagebits = 16, .shift = 4, .endianness = IIO_LE, }, @@ -578,7 +578,7 @@ work together. </para> <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer setup</title> -!Edrivers/iio/industrialio-triggered-buffer.c +!Edrivers/iio/buffer/industrialio-triggered-buffer.c !Finclude/linux/iio/iio.h iio_buffer_setup_ops diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 08527e7ea4d0..2840ff483d5a 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -199,8 +199,10 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)-mkdir $(MEDIA_OBJ_DIR)/media_api; \ - cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api + $(Q)if [ "x$(findstring media_api.xml,$(DOCBOOKS))" != "x" ]; then \ + mkdir -p $(MEDIA_OBJ_DIR)/media_api; \ + cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/*.svg $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api; \ + fi $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml index 858fd7d17104..8576481e20ae 100644 --- a/Documentation/DocBook/media/dvb/dvbapi.xml +++ b/Documentation/DocBook/media/dvb/dvbapi.xml @@ -125,9 +125,6 @@ Added ISDB-T test originally written by Patrick Boettcher &sub-audio; </section> </chapter> - <chapter id="dvb_kdapi"> - &sub-kdapi; - </chapter> <chapter id="dvb_examples"> &sub-examples; </chapter> diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 08227d4e9150..e579ae5088ae 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -76,7 +76,7 @@ int main(void) <para>NOTE: While it is possible to directly call the Kernel code like the above example, it is strongly recommended to use - <ulink url="http://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink>, + <ulink url="https://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink>, as it provides abstraction to work with the supported digital TV standards and provides methods for usual operations like program scanning and to read/write channel descriptor files.</para> diff --git a/Documentation/DocBook/media/dvb/examples.xml b/Documentation/DocBook/media/dvb/examples.xml index c9f68c7183cc..837fb3b64b72 100644 --- a/Documentation/DocBook/media/dvb/examples.xml +++ b/Documentation/DocBook/media/dvb/examples.xml @@ -3,7 +3,7 @@ </para> <para>NOTE: This section is out of date, and the code below won't even compile. Please refer to the - <ulink url="http://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink> + <ulink url="https://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink> for updated/recommended examples. </para> diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml index 51db15648099..b5b701f5d8c2 100644 --- a/Documentation/DocBook/media/dvb/intro.xml +++ b/Documentation/DocBook/media/dvb/intro.xml @@ -32,7 +32,7 @@ and filtering several section and PES data streams at the same time. new standard Linux DVB API. As a commitment to the development of terminals based on open standards, Nokia and Convergence made it available to all Linux developers and published it on -<ulink url="http://www.linuxtv.org/" /> in September 2000. +<ulink url="https://linuxtv.org" /> in September 2000. Convergence is the maintainer of the Linux DVB API. Together with the LinuxTV community (i.e. you, the reader of this document), the Linux DVB API will be constantly reviewed and improved. With the Linux driver for diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml deleted file mode 100644 index 68bcd33a82c3..000000000000 --- a/Documentation/DocBook/media/dvb/kdapi.xml +++ /dev/null @@ -1,2309 +0,0 @@ -<title>Kernel Demux API</title> -<para>The kernel demux API defines a driver-internal interface for registering low-level, -hardware specific driver to a hardware independent demux layer. It is only of interest for -DVB device driver writers. The header file for this API is named <constant>demux.h</constant> and located in -<constant>">drivers/media/dvb-core</constant>. -</para> -<para>Maintainer note: This section must be reviewed. It is probably out of date. -</para> - -<section id="kernel_demux_data_types"> -<title>Kernel Demux Data Types</title> - - -<section id="dmx_success_t"> -<title>dmx_success_t</title> - <programlisting> - typedef enum { - DMX_OK = 0, /⋆ Received Ok ⋆/ - DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ - DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ - DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ - DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ - DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ - DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ - } dmx_success_t; -</programlisting> - -</section> -<section id="ts_filter_types"> -<title>TS filter types</title> - <programlisting> - /⋆--------------------------------------------------------------------------⋆/ - /⋆ TS packet reception ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - /⋆ TS filter type for set_type() ⋆/ - - #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ - #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS - payload (<=184 bytes per packet) to callback ⋆/ - #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ -</programlisting> - -</section> -<section id="dmx_ts_pes_t"> -<title>dmx_ts_pes_t</title> -<para>The structure -</para> -<programlisting> - typedef enum - { - DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ - DMX_TS_PES_VIDEO, /⋆ ... ⋆/ - DMX_TS_PES_TELETEXT, - DMX_TS_PES_SUBTITLE, - DMX_TS_PES_PCR, - DMX_TS_PES_OTHER, - } dmx_ts_pes_t; -</programlisting> -<para>describes the PES type for filters which write to a built-in decoder. The correspond (and -should be kept identical) to the types in the demux device. -</para> -<programlisting> - struct dmx_ts_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_ts_feed_s⋆ feed, - __u16 pid, - size_t callback_length, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); - int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, - int type, - dmx_ts_pes_t pes_type); - }; - - typedef struct dmx_ts_feed_s dmx_ts_feed_t; -</programlisting> - <programlisting> - /⋆--------------------------------------------------------------------------⋆/ - /⋆ PES packet reception (not supported yet) ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef struct dmx_pes_filter_s { - struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - } dmx_pes_filter_t; -</programlisting> - <programlisting> - typedef struct dmx_pes_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_pes_feed_s⋆ feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); - int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, - dmx_pes_filter_t⋆⋆ filter); - int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, - dmx_pes_filter_t⋆ filter); - } dmx_pes_feed_t; -</programlisting> - <programlisting> - typedef struct { - __u8 filter_value [DMX_MAX_FILTER_SIZE]; - __u8 filter_mask [DMX_MAX_FILTER_SIZE]; - struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - } dmx_section_filter_t; -</programlisting> - <programlisting> - struct dmx_section_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_section_feed_s⋆ feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - int check_crc); - int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, - dmx_section_filter_t⋆⋆ filter); - int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, - dmx_section_filter_t⋆ filter); - int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); - }; - typedef struct dmx_section_feed_s dmx_section_feed_t; - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ Callback functions ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1, - size_t buffer1_length, - __u8 ⋆ buffer2, - size_t buffer2_length, - dmx_ts_feed_t⋆ source, - dmx_success_t success); - - typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, - size_t buffer1_len, - __u8 ⋆ buffer2, - size_t buffer2_len, - dmx_section_filter_t ⋆ source, - dmx_success_t success); - - typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, - size_t buffer1_len, - __u8 ⋆ buffer2, - size_t buffer2_len, - dmx_pes_filter_t⋆ source, - dmx_success_t success); - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ DVB Front-End ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef enum { - DMX_OTHER_FE = 0, - DMX_SATELLITE_FE, - DMX_CABLE_FE, - DMX_TERRESTRIAL_FE, - DMX_LVDS_FE, - DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ - DMX_MEMORY_FE - } dmx_frontend_source_t; - - typedef struct { - /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ - char⋆ id; /⋆ Unique front-end identifier ⋆/ - char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ - char⋆ model; /⋆ Name of the front-end model ⋆/ - struct list_head connectivity_list; /⋆ List of front-ends that can - be connected to a particular - demux ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - dmx_frontend_source_t source; - } dmx_frontend_t; - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ MPEG-2 TS Demux ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - /⋆ - ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. - ⋆/ - - #define DMX_TS_FILTERING 1 - #define DMX_PES_FILTERING 2 - #define DMX_SECTION_FILTERING 4 - #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ - #define DMX_CRC_CHECKING 16 - #define DMX_TS_DESCRAMBLING 32 - #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 - #define DMX_MAC_ADDRESS_DESCRAMBLING 128 -</programlisting> - -</section> -<section id="demux_demux_t"> -<title>demux_demux_t</title> - <programlisting> - /⋆ - ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered - ⋆ front-ends from the generic type struct list_head - ⋆ to the type ⋆ dmx_frontend_t - ⋆. - ⋆/ - - #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) - - struct dmx_demux_s { - /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ - char⋆ id; /⋆ Unique demux identifier ⋆/ - char⋆ vendor; /⋆ Name of the demux vendor ⋆/ - char⋆ model; /⋆ Name of the demux model ⋆/ - __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ - dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ - struct list_head reg_list; /⋆ List of registered demuxes ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int users; /⋆ Number of users ⋆/ - int (⋆open) (struct dmx_demux_s⋆ demux); - int (⋆close) (struct dmx_demux_s⋆ demux); - int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); - int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, - dmx_ts_feed_t⋆⋆ feed, - dmx_ts_cb callback); - int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, - dmx_ts_feed_t⋆ feed); - int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, - dmx_pes_feed_t⋆⋆ feed, - dmx_pes_cb callback); - int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, - dmx_pes_feed_t⋆ feed); - int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, - dmx_section_feed_t⋆⋆ feed, - dmx_section_cb callback); - int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, - dmx_section_feed_t⋆ feed); - int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, - __u8⋆ buffer1, - size_t buffer1_length, - __u8⋆ buffer2, - size_t buffer2_length, - __u16 pid); - int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, - __u8⋆ buffer1, - size_t buffer1_length, - __u8⋆ buffer2, size_t buffer2_length, - __u16 pid); - int (⋆add_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); - int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); - - - /⋆ added because js cannot keep track of these himself ⋆/ - int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); - }; - typedef struct dmx_demux_s dmx_demux_t; -</programlisting> - -</section> -<section id="demux_directory"> -<title>Demux directory</title> - <programlisting> - /⋆ - ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered - ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t - ⋆. - ⋆/ - - #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) - - int dmx_register_demux (dmx_demux_t⋆ demux); - int dmx_unregister_demux (dmx_demux_t⋆ demux); - struct list_head⋆ dmx_get_demuxes (void); -</programlisting> - </section></section> -<section id="demux_directory_api"> -<title>Demux Directory API</title> -<para>The demux directory is a Linux kernel-wide facility for registering and accessing the -MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers -is possible using this API. -</para> -<para>All demux drivers in the directory implement the abstract interface dmx_demux_t. -</para> - -<section -role="subsection"><title>dmx_register_demux()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function makes a demux driver interface available to the Linux kernel. It is - usually called by the init_module() function of the kernel module that contains - the demux driver. The caller of this function is responsible for allocating - dynamic or static memory for the demux structure and for initializing its fields - before calling this function. The memory allocated for the demux structure - must not be freed before calling dmx_unregister_demux(),</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux structure.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EEXIST</para> -</entry><entry - align="char"> -<para>A demux with the same value of the id field already stored - in the directory.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSPC</para> -</entry><entry - align="char"> -<para>No space left in the directory.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>dmx_unregister_demux()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function is called to indicate that the given demux interface is no - longer available. The caller of this function is responsible for freeing the - memory of the demux structure, if it was dynamically allocated before calling - dmx_register_demux(). The cleanup_module() function of the kernel module - that contains the demux driver should call this function. Note that this function - fails if the demux is currently in use, i.e., release_demux() has not been called - for the interface.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux structure which is to be - unregistered.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>The specified demux is not registered in the demux - directory.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>The specified demux is currently in use.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>dmx_get_demuxes()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Provides the caller with the list of registered demux interfaces, using the - standard list structure defined in the include file linux/list.h. The include file - demux.h defines the macro DMX_DIR_ENTRY() for converting an element of - the generic type struct list_head* to the type dmx_demux_t*. The caller must - not free the memory of any of the elements obtained via this function call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>struct list_head ⋆dmx_get_demuxes ()</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>none</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>struct list_head *</para> -</entry><entry - align="char"> -<para>A list of demux interfaces, or NULL in the case of an - empty list.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section> -<section id="demux_api"> -<title>Demux API</title> -<para>The demux API 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. When the demux -client allocates a resource via the demux API, it receives a pointer to the API of that -resource. -</para> -<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the -demux API. In a system with more than one front-end, the API can be used to select one of -the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The -demux API only controls front-ends regarding their connections with demuxes; the APIs -used to set the other front-end parameters, such as tuning, are not defined in this -document. -</para> -<para>The functions that implement the abstract interface demux should be defined static or -module private and registered to the Demux Directory for external access. It is not necessary -to implement every function in the demux_t struct, however (for example, a demux interface -might support Section filtering, but not TS or PES filtering). The API client is expected to -check the value of any function pointer before calling the function: the value of NULL means -“function not available”. -</para> -<para>Whenever the functions of the demux API modify shared data, the possibilities of lost -update and race condition problems should be addressed, e.g. by protecting parts of code with -mutexes. This is especially important on multi-processor hosts. -</para> -<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x -kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if -swapping is needed. For example, the Linux kernel calls the functions of a network device -interface from a bottom half context. Thus, if a demux API function is called from network -device code, the function must not sleep. -</para> - - -<section id="kdapi_fopen"> -<title>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function reserves the demux for use by the caller and, if necessary, - initializes the demux. When the demux is no longer needed, the function close() - should be called. It should be possible for multiple clients to access the demux - at the same time. Thus, the function implementation should increment the - demux usage count when open() is called and decrement it when close() is - called.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open ( demux_t⋆ demux );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EUSERS</para> -</entry><entry - align="char"> -<para>Maximum usage count reached.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="kdapi_fclose"> -<title>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function reserves the demux for use by the caller and, if necessary, - initializes the demux. When the demux is no longer needed, the function close() - should be called. It should be possible for multiple clients to access the demux - at the same time. Thus, the function implementation should increment the - demux usage count when open() is called and decrement it when close() is - called.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(demux_t⋆ demux);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENODEV</para> -</entry><entry - align="char"> -<para>The demux was not in use.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> -<section id="kdapi_fwrite"> -<title>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function provides the demux driver with a memory buffer containing TS - packets. Instead of receiving TS packets from the DVB front-end, the demux - driver software will read packets from memory. Any clients of this demux - with active TS, PES or Section filters will receive filtered data via the Demux - callback API (see 0). The function returns when all the data in the buffer has - been consumed by the demux. Demux hardware typically cannot read TS from - memory. If this is the case, memory-based filtering has to be implemented - entirely in software.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int write(demux_t⋆ demux, const char⋆ buf, size_t - count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>const char* buf</para> -</entry><entry - align="char"> -<para>Pointer to the TS data in kernel-space memory.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t length</para> -</entry><entry - align="char"> -<para>Length of the TS data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>The command is not implemented.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>allocate_ts_feed()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Allocates a new TS feed, which is used to filter the TS packets carrying a - certain PID. The TS feed normally corresponds to a hardware PID filter on the - demux chip.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int allocate_ts_feed(dmx_demux_t⋆ demux, - dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_feed_t** - feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_cb callback</para> -</entry><entry - align="char"> -<para>Pointer to the callback function for passing received TS - packet</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>No more TS feeds available.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>The command is not implemented.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>release_ts_feed()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in - progress on the TS feed should be stopped before calling this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int release_ts_feed(dmx_demux_t⋆ demux, - dmx_ts_feed_t⋆ feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>allocate_section_feed()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving - sections. On platforms with hardware support for section filtering, a section - feed is directly mapped to the demux HW. On other platforms, TS packets are - first PID filtered in hardware and a hardware section filter then emulated in - software. The caller obtains an API pointer of type dmx_section_feed_t as an - out parameter. Using this API the caller can set filtering parameters and start - receiving sections.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int allocate_section_feed(dmx_demux_t⋆ demux, - dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_feed_t - **feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_cb - callback</para> -</entry><entry - align="char"> -<para>Pointer to the callback function for passing received - sections.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>No more section feeds available.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>The command is not implemented.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>release_section_feed()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Releases the resources allocated with allocate_section_feed(), including - allocated filters. Any filtering in progress on the section feed should be stopped - before calling this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int release_section_feed(dmx_demux_t⋆ demux, - dmx_section_feed_t ⋆feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_feed_t - *feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>descramble_mac_address()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function runs a descrambling algorithm on the destination MAC - address field of a DVB Datagram Section, replacing the original address - with its un-encrypted version. Otherwise, the description on the function - descramble_section_payload() applies also to this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int descramble_mac_address(dmx_demux_t⋆ demux, __u8 - ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, - size_t buffer2_length, __u16 pid);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t - *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8 *buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the first byte of the section.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer1.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8* buffer2</para> -</entry><entry - align="char"> -<para>Pointer to the tail of the section data, or NULL. The - pointer has a non-NULL value if the section wraps past - the end of a circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer2.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>The PID on which the section was received. Useful - for obtaining the descrambling key, e.g. from a DVB - Common Access facility.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>descramble_section_payload()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function runs a descrambling algorithm on the payload of a DVB - Datagram Section, replacing the original payload with its un-encrypted - version. The function will be called from the demux API implementation; - the API client need not call this function directly. Section-level scrambling - algorithms are currently standardized only for DVB-RCC (return channel - over 2-directional cable TV network) systems. For all other DVB networks, - encryption schemes are likely to be proprietary to each data broadcaster. Thus, - it is expected that this function pointer will have the value of NULL (i.e., - function not available) in most demux API implementations. Nevertheless, it - should be possible to use the function pointer as a hook for dynamically adding - a “plug-in” descrambling facility to a demux driver.</para> -</entry> - </row><row><entry - align="char"> -<para>While this function is not needed with hardware-based section descrambling, - the descramble_section_payload function pointer can be used to override the - default hardware-based descrambling algorithm: if the function pointer has a - non-NULL value, the corresponding function should be used instead of any - descrambling hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int descramble_section_payload(dmx_demux_t⋆ demux, - __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, - size_t buffer2_length, __u16 pid);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t - *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8 *buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the first byte of the section.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer1.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8 *buffer2</para> -</entry><entry - align="char"> -<para>Pointer to the tail of the section data, or NULL. The - pointer has a non-NULL value if the section wraps past - the end of a circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer2.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>The PID on which the section was received. Useful - for obtaining the descrambling key, e.g. from a DVB - Common Access facility.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>add_frontend()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Registers a connectivity between a demux and a front-end, i.e., indicates that - the demux can be connected via a call to connect_frontend() to use the given - front-end as a TS source. The client of this function has to allocate dynamic or - static memory for the frontend structure and initialize its fields before calling - this function. This function is normally called during the driver initialization. - The caller must not free the memory of the frontend struct before successfully - calling remove_frontend().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t - ⋆frontend);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_frontend_t* - frontend</para> -</entry><entry - align="char"> -<para>Pointer to the front-end instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EEXIST</para> -</entry><entry - align="char"> -<para>A front-end with the same value of the id field already - registered.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINUSE</para> -</entry><entry - align="char"> -<para>The demux is in use.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOMEM</para> -</entry><entry - align="char"> -<para>No more front-ends can be added.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>remove_frontend()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Indicates that the given front-end, registered by a call to add_frontend(), can - no longer be connected as a TS source by this demux. The function should be - called when a front-end driver or a demux driver is removed from the system. - If the front-end is in use, the function fails with the return value of -EBUSY. - After successfully calling this function, the caller can free the memory of - the frontend struct if it was dynamically allocated before the add_frontend() - operation.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int remove_frontend(dmx_demux_t⋆ demux, - dmx_frontend_t⋆ frontend);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_frontend_t* - frontend</para> -</entry><entry - align="char"> -<para>Pointer to the front-end instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>The front-end is in use, i.e. a call to connect_frontend() - has not been followed by a call to disconnect_frontend().</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>get_frontends()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Provides the APIs of the front-ends that have been registered for this demux. - Any of the front-ends obtained with this call can be used as a parameter for - connect_frontend().</para> -</entry> - </row><row><entry - align="char"> -<para>The include file demux.h contains the macro DMX_FE_ENTRY() for - converting an element of the generic type struct list_head* to the type - dmx_frontend_t*. The caller must not free the memory of any of the elements - obtained via this function call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t*</para> -</entry><entry - align="char"> -<para>A list of front-end interfaces, or NULL in the case of an - empty list.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>connect_frontend()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Connects the TS output of the front-end to the input of the demux. A demux - can only be connected to a front-end registered to the demux with the function - add_frontend().</para> -</entry> - </row><row><entry - align="char"> -<para>It may or may not be possible to connect multiple demuxes to the same - front-end, depending on the capabilities of the HW platform. When not used, - the front-end should be released by calling disconnect_frontend().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int connect_frontend(dmx_demux_t⋆ demux, - dmx_frontend_t⋆ frontend);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_frontend_t* - frontend</para> -</entry><entry - align="char"> -<para>Pointer to the front-end instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>The front-end is in use.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>disconnect_frontend()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Disconnects the demux and a front-end previously connected by a - connect_frontend() call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int disconnect_frontend(dmx_demux_t⋆ demux);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section> -<section id="demux_callback_api"> -<title>Demux Callback API</title> -<para>This kernel-space API comprises the callback functions that deliver filtered data to the -demux client. Unlike the other APIs, these API functions are provided by the client and called -from the demux code. -</para> -<para>The function pointers of this abstract interface are not packed into a structure as in the -other demux APIs, because the callback functions are registered and used independent -of each other. As an example, it is possible for the API client to provide several -callback functions for receiving TS packets and no callbacks for PES packets or -sections. -</para> -<para>The functions that implement the callback API need not be re-entrant: when a demux -driver calls one of these functions, the driver is not allowed to call the function again before -the original call returns. If a callback is triggered by a hardware interrupt, it is recommended -to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback -function call directly from a hardware interrupt. -</para> - -<section -role="subsection"><title>dmx_ts_cb()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function, provided by the client of the demux API, is called from the - demux code. The function is only called when filtering on this TS feed has - been enabled using the start_filtering() function.</para> -</entry> - </row><row><entry - align="char"> -<para>Any TS packets that match the filter settings are copied to a circular buffer. The - filtered TS packets are delivered to the client using this callback function. The - size of the circular buffer is controlled by the circular_buffer_size parameter - of the set() function in the TS Feed API. It is expected that the buffer1 and - buffer2 callback parameters point to addresses within the circular buffer, but - other implementations are also possible. Note that the called party should not - try to free the memory the buffer1 and buffer2 parameters point to.</para> -</entry> - </row><row><entry - align="char"> -<para>When this function is called, the buffer1 parameter typically points to the - start of the first undelivered TS packet within a circular buffer. The buffer2 - buffer parameter is normally NULL, except when the received TS packets have - crossed the last address of the circular buffer and ”wrapped” to the beginning - of the buffer. In the latter case the buffer1 parameter would contain an address - within the circular buffer, while the buffer2 parameter would contain the first - address of the circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>The number of bytes delivered with this function (i.e. buffer1_length + - buffer2_length) is usually equal to the value of callback_length parameter - given in the set() function, with one exception: if a timeout occurs before - receiving callback_length bytes of TS data, any undelivered packets are - immediately delivered to the client by calling this function. The timeout - duration is controlled by the set() function in the TS Feed API.</para> -</entry> - </row><row><entry - align="char"> -<para>If a TS packet is received with errors that could not be fixed by the TS-level - forward error correction (FEC), the Transport_error_indicator flag of the TS - packet header should be set. The TS packet should not be discarded, as - the error can possibly be corrected by a higher layer protocol. If the called - party is slow in processing the callback, it is possible that the circular buffer - eventually fills up. If this happens, the demux driver should discard any TS - packets received while the buffer is full. The error should be indicated to the - client on the next callback by setting the success parameter to the value of - DMX_OVERRUN_ERROR.</para> -</entry> - </row><row><entry - align="char"> -<para>The type of data returned to the callback can be selected by the new - function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t - pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the - include file ost/demux.h) The type parameter decides if the raw TS packet - (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY) - should be returned. If additionally the TS_DECODER bit is set the stream - will also be sent to the hardware MPEG decoder. In this case, the second - flag decides as what kind of data the stream should be interpreted. The - possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, - DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, - DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, - __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ - source, dmx_success_t success);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>__u8* buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the start of the filtered TS packets.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the TS data in buffer1.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8* buffer2</para> -</entry><entry - align="char"> -<para>Pointer to the tail of the filtered TS packets, or NULL.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the TS data in buffer2.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_feed_t* - source</para> -</entry><entry - align="char"> -<para>Indicates which TS feed is the source of the callback.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_success_t - success</para> -</entry><entry - align="char"> -<para>Indicates if there was an error in TS reception.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>Continue filtering.</para> -</entry> - </row><row><entry - align="char"> -<para>-1</para> -</entry><entry - align="char"> -<para>Stop filtering - has the same effect as a call to - stop_filtering() on the TS Feed API.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>dmx_section_cb()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function, provided by the client of the demux API, is called from the - demux code. The function is only called when filtering of sections has been - enabled using the function start_filtering() of the section feed API. When the - demux driver has received a complete section that matches at least one section - filter, the client is notified via this callback function. Normally this function is - called for each received section; however, it is also possible to deliver multiple - sections with one callback, for example when the system load is high. If an - error occurs while receiving a section, this function should be called with - the corresponding error type set in the success field, whether or not there is - data to deliver. The Section Feed implementation should maintain a circular - buffer for received sections. However, this is not necessary if the Section Feed - API is implemented as a client of the TS Feed API, because the TS Feed - implementation then buffers the received data. The size of the circular buffer - can be configured using the set() function in the Section Feed API. If there - is no room in the circular buffer when a new section is received, the section - must be discarded. If this happens, the value of the success parameter should - be DMX_OVERRUN_ERROR on the next callback.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int dmx_section_cb(__u8⋆ buffer1, size_t - buffer1_length, __u8⋆ buffer2, size_t - buffer2_length, dmx_section_filter_t⋆ source, - dmx_success_t success);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>__u8* buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the start of the filtered section, e.g. within the - circular buffer of the demux driver.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the filtered section data in buffer1, including - headers and CRC.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8* buffer2</para> -</entry><entry - align="char"> -<para>Pointer to the tail of the filtered section data, or NULL. - Useful to handle the wrapping of a circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the filtered section data in buffer2, including - headers and CRC.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_filter_t* - filter</para> -</entry><entry - align="char"> -<para>Indicates the filter that triggered the callback.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_success_t - success</para> -</entry><entry - align="char"> -<para>Indicates if there was an error in section reception.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>Continue filtering.</para> -</entry> - </row><row><entry - align="char"> -<para>-1</para> -</entry><entry - align="char"> -<para>Stop filtering - has the same effect as a call to - stop_filtering() on the Section Feed API.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section> -<section id="ts_feed_api"> -<title>TS Feed API</title> -<para>A TS feed is typically mapped to a hardware PID filter on the demux chip. -Using this API, the client can set the filtering properties to start/stop filtering TS -packets on a particular TS feed. The API is defined as an abstract interface of the type -dmx_ts_feed_t. -</para> -<para>The functions that implement the interface should be defined static or module private. The -client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the -demux API. -</para> - -<section -role="subsection"><title>set()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function sets the parameters of a TS feed. Any filtering in progress on the - TS feed must be stopped before calling this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t - callback_length, size_t circular_buffer_size, int - descramble, struct timespec timeout);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>PID value to filter. Only the TS packets carrying the - specified PID will be passed to the API client.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t - callback_length</para> -</entry><entry - align="char"> -<para>Number of bytes to deliver with each call to the - dmx_ts_cb() callback function. The value of this - parameter should be a multiple of 188.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t - circular_buffer_size</para> -</entry><entry - align="char"> -<para>Size of the circular buffer for the filtered TS packets.</para> -</entry> - </row><row><entry - align="char"> -<para>int descramble</para> -</entry><entry - align="char"> -<para>If non-zero, descramble the filtered TS packets.</para> -</entry> - </row><row><entry - align="char"> -<para>struct timespec - timeout</para> -</entry><entry - align="char"> -<para>Maximum time to wait before delivering received TS - packets to the client.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOMEM</para> -</entry><entry - align="char"> -<para>Not enough memory for the requested buffer size.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available for TS.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>start_filtering()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Starts filtering TS packets on this TS feed, according to its settings. The PID - value to filter can be set by the API client. All matching TS packets are - delivered asynchronously to the client, using the callback function registered - with allocate_ts_feed().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int start_filtering(dmx_ts_feed_t⋆ feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>stop_filtering()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Stops filtering TS packets on this TS feed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section> -<section id="section_feed_api"> -<title>Section Feed API</title> -<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this -API, the client can set the properties of a section feed and to start/stop filtering. The API is -defined as an abstract interface of the type dmx_section_feed_t. The functions that implement -the interface should be defined static or module private. The client can get the handle of -a section feed API by calling the function allocate_section_feed() in the demux -API. -</para> -<para>On demux platforms that provide section filtering in hardware, the Section Feed API -implementation provides a software wrapper for the demux hardware. Other platforms may -support only PID filtering in hardware, requiring that TS packets are converted to sections in -software. In the latter case the Section Feed API implementation can be a client of the TS -Feed API. -</para> - -</section> -<section id="kdapi_set"> -<title>set()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function sets the parameters of a section feed. Any filtering in progress on - the section feed must be stopped before calling this function. If descrambling - is enabled, the payload_scrambling_control and address_scrambling_control - fields of received DVB datagram sections should be observed. If either one is - non-zero, the section should be descrambled either in hardware or using the - functions descramble_mac_address() and descramble_section_payload() of the - demux API. Note that according to the MPEG-2 Systems specification, only - the payloads of private sections can be scrambled while the rest of the section - data must be sent in the clear.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t - circular_buffer_size, int descramble, int - check_crc);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>PID value to filter; only the TS packets carrying the - specified PID will be accepted.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t - circular_buffer_size</para> -</entry><entry - align="char"> -<para>Size of the circular buffer for filtered sections.</para> -</entry> - </row><row><entry - align="char"> -<para>int descramble</para> -</entry><entry - align="char"> -<para>If non-zero, descramble any sections that are scrambled.</para> -</entry> - </row><row><entry - align="char"> -<para>int check_crc</para> -</entry><entry - align="char"> -<para>If non-zero, check the CRC values of filtered sections.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOMEM</para> -</entry><entry - align="char"> -<para>Not enough memory for the requested buffer size.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available for sections.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>allocate_filter()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function is used to allocate a section filter on the demux. It should only be - called when no filtering is in progress on this section feed. If a filter cannot be - allocated, the function fails with -ENOSPC. See in section ?? for the format of - the section filter.</para> -</entry> - </row><row><entry - align="char"> -<para>The bitfields filter_mask and filter_value should only be modified when no - filtering is in progress on this section feed. filter_mask controls which bits of - filter_value are compared with the section headers/payload. On a binary value - of 1 in filter_mask, the corresponding bits are compared. The filter only accepts - sections that are equal to filter_value in all the tested bit positions. Any changes - to the values of filter_mask and filter_value are guaranteed to take effect only - when the start_filtering() function is called next time. The parent pointer in - the struct is initialized by the API implementation to the value of the feed - parameter. The priv pointer is not used by the API implementation, and can - thus be freely utilized by the caller of this function. Any data pointed to by the - priv pointer is available to the recipient of the dmx_section_cb() function call.</para> -</entry> - </row><row><entry - align="char"> -<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is - currently set at 16 bytes, hardware filters of that size are not available on all - platforms. Therefore, section filtering will often take place first in hardware, - followed by filtering in software for the header bytes that were not covered - by a hardware filter. The filter_mask field can be checked to determine how - many bytes of the section filter are actually used, and if the hardware filter will - suffice. Additionally, software-only section filters can optionally be allocated - to clients when all hardware section filters are in use. Note that on most demux - hardware it is not possible to filter on the section_length field of the section - header – thus this field is ignored, even though it is included in filter_value and - filter_mask fields.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int allocate_filter(dmx_section_feed_t⋆ feed, - dmx_section_filter_t⋆⋆ filter);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_filter_t** - filter</para> -</entry><entry - align="char"> -<para>Pointer to the allocated filter.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSPC</para> -</entry><entry - align="char"> -<para>No filters of given type and length available.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>release_filter()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function releases all the resources of a previously allocated section filter. - The function should not be called while filtering is in progress on this section - feed. After calling this function, the caller should not try to dereference the - filter pointer.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int release_filter ( dmx_section_feed_t⋆ feed, - dmx_section_filter_t⋆ filter);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_filter_t* - filter</para> -</entry><entry - align="char"> -<para>I/O Pointer to the instance data of a section filter.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENODEV</para> -</entry><entry - align="char"> -<para>No such filter allocated.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>start_filtering()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Starts filtering sections on this section feed, according to its settings. Sections - are first filtered based on their PID and then matched with the section - filters allocated for this feed. If the section matches the PID filter and - at least one section filter, it is delivered to the API client. The section - is delivered asynchronously using the callback function registered with - allocate_section_feed().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int start_filtering ( dmx_section_feed_t⋆ feed );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title>stop_filtering()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Stops filtering sections on this section feed. Note that any changes to the - filtering parameters (filter_value, filter_mask, etc.) should only be made when - filtering is stopped.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index fdee6b3f3eca..9beb30f0071b 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -177,6 +177,24 @@ Signal - NTSC for Studio Applications"</title> 1125-Line High-Definition Production"</title> </biblioentry> + <biblioentry id="smpte431"> + <abbrev>SMPTE RP 431-2</abbrev> + <authorgroup> + <corpauthor>Society of Motion Picture and Television Engineers +(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> + </authorgroup> + <title>SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment"</title> + </biblioentry> + + <biblioentry id="smpte2084"> + <abbrev>SMPTE ST 2084</abbrev> + <authorgroup> + <corpauthor>Society of Motion Picture and Television Engineers +(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor> + </authorgroup> + <title>SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays"</title> + </biblioentry> + <biblioentry id="srgb"> <abbrev>sRGB</abbrev> <authorgroup> diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml index 1c5c49a2de59..22126a991b34 100644 --- a/Documentation/DocBook/media/v4l/capture.c.xml +++ b/Documentation/DocBook/media/v4l/capture.c.xml @@ -5,7 +5,7 @@ * This program can be used and distributed without restrictions. * * This program is provided with the V4L2 API - * see http://linuxtv.org/docs.php for more information + * see https://linuxtv.org/docs.php for more information */ #include <stdio.h> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index a0aef85d33c1..5399e8904715 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2591,6 +2591,26 @@ and &v4l2-mbus-framefmt;. </orderedlist> </section> + <section> + <title>V4L2 in Linux 4.4</title> + <orderedlist> + <listitem> + <para>Renamed <constant>V4L2_TUNER_ADC</constant> to +<constant>V4L2_TUNER_SDR</constant>. The use of +<constant>V4L2_TUNER_ADC</constant> is deprecated now. + </para> + </listitem> + <listitem> + <para>Added <constant>V4L2_CID_RF_TUNER_RF_GAIN</constant> +RF Tuner control.</para> + </listitem> + <listitem> + <para>Added transmitter support for Software Defined Radio (SDR) +Interface.</para> + </listitem> + </orderedlist> + </section> + <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> @@ -2646,7 +2666,7 @@ is useful to display images captured with V4L2 devices.</para> <para>V4L2 does not support digital terrestrial, cable or satellite broadcast. A separate project aiming at digital receivers exists. You can find its homepage at <ulink -url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API +url="https://linuxtv.org">https://linuxtv.org</ulink>. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both.</para> </section> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 33aece541880..361040e6b0f4 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -2330,6 +2330,14 @@ vertical search range for motion estimation module in video encoder.</entry> </row> <row><entry></entry></row> + <row id="v4l2-mpeg-video-force-key-frame"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME</constant> </entry> + <entry>button</entry> + </row><row><entry spanname="descr">Force a key frame for the next queued buffer. Applicable to encoders. +This is a general, codec-agnostic keyframe control.</entry> + </row> + + <row><entry></entry></row> <row> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant> </entry> <entry>integer</entry> @@ -5070,6 +5078,46 @@ interface and may change in the future.</para> </entry> </row> <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_IT_CONTENT_TYPE</constant></entry> + <entry id="v4l2-dv-content-type">enum v4l2_dv_it_content_type</entry> + </row> + <row><entry spanname="descr">Configures the IT Content Type + of the transmitted video. This information is sent over HDMI and DisplayPort connectors + as part of the AVI InfoFrame. The term 'IT Content' is used for content that originates + from a computer as opposed to content from a TV broadcast or an analog source. The + enum v4l2_dv_it_content_type defines the possible content types:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_DV_IT_CONTENT_TYPE_GRAPHICS</constant> </entry> + <entry>Graphics content. Pixel data should be passed unfiltered and without + analog reconstruction.</entry> + </row> + <row> + <entry><constant>V4L2_DV_IT_CONTENT_TYPE_PHOTO</constant> </entry> + <entry>Photo content. The content is derived from digital still pictures. + The content should be passed through with minimal scaling and picture + enhancements.</entry> + </row> + <row> + <entry><constant>V4L2_DV_IT_CONTENT_TYPE_CINEMA</constant> </entry> + <entry>Cinema content.</entry> + </row> + <row> + <entry><constant>V4L2_DV_IT_CONTENT_TYPE_GAME</constant> </entry> + <entry>Game content. Audio and video latency should be minimized.</entry> + </row> + <row> + <entry><constant>V4L2_DV_IT_CONTENT_TYPE_NO_ITC</constant> </entry> + <entry>No IT Content information is available and the ITC bit in the AVI + InfoFrame is set to 0.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row> <entry spanname="id"><constant>V4L2_CID_DV_RX_POWER_PRESENT</constant></entry> <entry>bitmask</entry> </row> @@ -5098,6 +5146,16 @@ interface and may change in the future.</para> This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. </entry> </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_RX_IT_CONTENT_TYPE</constant></entry> + <entry>enum v4l2_dv_it_content_type</entry> + </row> + <row><entry spanname="descr">Reads the IT Content Type + of the received video. This information is sent over HDMI and DisplayPort connectors + as part of the AVI InfoFrame. The term 'IT Content' is used for content that originates + from a computer as opposed to content from a TV broadcast or an analog source. See + <constant>V4L2_CID_DV_TX_IT_CONTENT_TYPE</constant> for the available content types.</entry> + </row> <row><entry></entry></row> </tbody> </tgroup> @@ -5418,6 +5476,18 @@ set. Unit is in Hz. The range and step are driver-specific.</entry> <entry spanname="descr">Enables/disables IF automatic gain control (AGC)</entry> </row> <row> + <entry spanname="id"><constant>V4L2_CID_RF_TUNER_RF_GAIN</constant> </entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">The RF amplifier is the very first +amplifier on the receiver signal path, just right after the antenna input. +The difference between the LNA gain and the RF gain in this document is that +the LNA gain is integrated in the tuner chip while the RF gain is a separate +chip. There may be both RF and LNA gain controls in the same device. +The range and step are driver-specific.</entry> + </row> + <row> <entry spanname="id"><constant>V4L2_CID_RF_TUNER_LNA_GAIN</constant> </entry> <entry>integer</entry> </row> @@ -5425,6 +5495,8 @@ set. Unit is in Hz. The range and step are driver-specific.</entry> <entry spanname="descr">LNA (low noise amplifier) gain is first gain stage on the RF tuner signal path. It is located very close to tuner antenna input. Used when <constant>V4L2_CID_RF_TUNER_LNA_GAIN_AUTO</constant> is not set. +See <constant>V4L2_CID_RF_TUNER_RF_GAIN</constant> to understand how RF gain +and LNA gain differs from the each others. The range and step are driver-specific.</entry> </row> <row> diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml index f8903568a243..a659771f7b7c 100644 --- a/Documentation/DocBook/media/v4l/dev-sdr.xml +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -28,6 +28,16 @@ Devices supporting the SDR receiver interface set the <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver. + </para> + <para> +Devices supporting the SDR transmitter interface set the +<constant>V4L2_CAP_SDR_OUTPUT</constant> and +<constant>V4L2_CAP_MODULATOR</constant> flag in the +<structfield>capabilities</structfield> field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an +Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. + </para> + <para> At least one of the read/write, streaming or asynchronous I/O methods must be supported. </para> @@ -39,15 +49,16 @@ be supported. <para> SDR devices can support <link linkend="control">controls</link>, and must support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used -for setting the ADC sampling rate (sampling frequency) and the possible RF tuner -frequency. +for setting the ADC/DAC sampling rate (sampling frequency) and the possible +radio frequency (RF). </para> <para> -The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and -the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The -tuner index of the RF tuner (if any) must always follow the ADC tuner index. -Normally the ADC tuner is #0 and the RF tuner is #1. +The <constant>V4L2_TUNER_SDR</constant> tuner type is used for setting SDR +device ADC/DAC frequency, and the <constant>V4L2_TUNER_RF</constant> +tuner type is used for setting radio frequency. +The tuner index of the RF tuner (if any) must always follow the SDR tuner index. +Normally the SDR tuner is #0 and the RF tuner is #1. </para> <para> @@ -59,9 +70,9 @@ The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. <title>Data Format Negotiation</title> <para> -The SDR capture device uses the <link linkend="format">format</link> ioctls to -select the capture format. Both the sampling resolution and the data streaming -format are bound to that selectable format. In addition to the basic +The SDR device uses the <link linkend="format">format</link> ioctls to +select the capture and output format. Both the sampling resolution and the data +streaming format are bound to that selectable format. In addition to the basic <link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl must be supported as well. </para> @@ -69,7 +80,8 @@ must be supported as well. <para> To use the <link linkend="format">format</link> ioctls applications set the <structfield>type</structfield> field of a &v4l2-format; to -<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format; +<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> or +<constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant> and use the &v4l2-sdr-format; <structfield>sdr</structfield> member of the <structfield>fmt</structfield> union as needed per the desired operation. Currently there is two fields, <structfield>pixelformat</structfield> and diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 7bbc2a48911e..144158b3a5ac 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -699,7 +699,7 @@ linkend="v4l2-buf-type" /></entry> buffer. It depends on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when <structfield>type</structfield> -refers to an input stream, applications when it refers to an output stream. +refers to a capture stream, applications when it refers to an output stream. If the application sets this to 0 for an output stream, then <structfield>bytesused</structfield> will be set to the size of the buffer (see the <structfield>length</structfield> field of this struct) by @@ -720,14 +720,14 @@ linkend="buffer-flags" />.</entry> <entry>Indicates the field order of the image in the buffer, see <xref linkend="v4l2-field" />. This field is not used when the buffer contains VBI data. Drivers must set it when -<structfield>type</structfield> refers to an input stream, +<structfield>type</structfield> refers to a capture stream, applications when it refers to an output stream.</entry> </row> <row> <entry>struct timeval</entry> <entry><structfield>timestamp</structfield></entry> <entry></entry> - <entry><para>For input streams this is time when the first data + <entry><para>For capture streams this is time when the first data byte was captured, as returned by the <function>clock_gettime()</function> function for the relevant clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in @@ -866,7 +866,7 @@ must set this to 0.</entry> <entry></entry> <entry>The number of bytes occupied by data in the plane (its payload). Drivers must set this field when <structfield>type</structfield> - refers to an input stream, applications when it refers to an output stream. + refers to a capture stream, applications when it refers to an output stream. If the application sets this to 0 for an output stream, then <structfield>bytesused</structfield> will be set to the size of the plane (see the <structfield>length</structfield> field of this struct) @@ -919,7 +919,7 @@ must set this to 0.</entry> <entry></entry> <entry>Offset in bytes to video data in the plane. Drivers must set this field when <structfield>type</structfield> - refers to an input stream, applications when it refers to an output stream. + refers to a capture stream, applications when it refers to an output stream. Note that data_offset is included in <structfield>bytesused</structfield>. So the size of the image in the plane is <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at @@ -1006,8 +1006,14 @@ must set this to 0.</entry> <row> <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry> <entry>11</entry> - <entry>Buffer for Software Defined Radio (SDR), see <xref - linkend="sdr" />.</entry> + <entry>Buffer for Software Defined Radio (SDR) capture stream, see + <xref linkend="sdr" />.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant></entry> + <entry>12</entry> + <entry>Buffer for Software Defined Radio (SDR) output stream, see + <xref linkend="sdr" />.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml index 873ac3a621f0..5f2fc07a93d7 100644 --- a/Documentation/DocBook/media/v4l/media-controller.xml +++ b/Documentation/DocBook/media/v4l/media-controller.xml @@ -58,21 +58,36 @@ <title>Media device model</title> <para>Discovering a device internal topology, and configuring it at runtime, is one of the goals of the media controller API. To achieve this, hardware - devices are modelled as an oriented graph of building blocks called entities - connected through pads.</para> - <para>An entity is a basic media hardware or software building block. It can - correspond to a large variety of logical blocks such as physical hardware - devices (CMOS sensor for instance), logical hardware devices (a building - block in a System-on-Chip image processing pipeline), DMA channels or - physical connectors.</para> - <para>A pad is a connection endpoint through which an entity can interact - with other entities. Data (not restricted to video) produced by an entity - flows from the entity's output to one or more entity inputs. Pads should not - be confused with physical pins at chip boundaries.</para> - <para>A link is a point-to-point oriented connection between two pads, - either on the same entity or on different entities. Data flows from a source - pad to a sink pad.</para> + devices and Linux Kernel interfaces are modelled as graph objects on + an oriented graph. The object types that constitute the graph are:</para> + <itemizedlist> + <listitem><para>An <emphasis role="bold">entity</emphasis> + is a basic media hardware or software building block. It can correspond to + a large variety of logical blocks such as physical hardware devices + (CMOS sensor for instance), logical hardware devices (a building block in + a System-on-Chip image processing pipeline), DMA channels or physical + connectors.</para></listitem> + <listitem><para>An <emphasis role="bold">interface</emphasis> + is a graph representation of a Linux Kernel userspace API interface, + like a device node or a sysfs file that controls one or more entities + in the graph.</para></listitem> + <listitem><para>A <emphasis role="bold">pad</emphasis> + is a data connection endpoint through which an entity can interact with + other entities. Data (not restricted to video) produced by an entity + flows from the entity's output to one or more entity inputs. Pads should + not be confused with physical pins at chip boundaries.</para></listitem> + <listitem><para>A <emphasis role="bold">data link</emphasis> + is a point-to-point oriented connection between two pads, either on the + same entity or on different entities. Data flows from a source pad to a + sink pad.</para></listitem> + <listitem><para>An <emphasis role="bold">interface link</emphasis> + is a point-to-point bidirectional control connection between a Linux + Kernel interface and an entity.m</para></listitem> + </itemizedlist> </section> + + <!-- All non-ioctl specific data types go here. --> + &sub-media-types; </chapter> <appendix id="media-user-func"> @@ -83,6 +98,7 @@ &sub-media-func-ioctl; <!-- All ioctls go here. --> &sub-media-ioc-device-info; + &sub-media-ioc-g-topology; &sub-media-ioc-enum-entities; &sub-media-ioc-enum-links; &sub-media-ioc-setup-link; diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml index 5872f8bbf774..0c4f96bfc2de 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml @@ -59,15 +59,6 @@ <para>Entity IDs can be non-contiguous. Applications must <emphasis>not</emphasis> try to enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para> - <para>Two or more entities that share a common non-zero - <structfield>group_id</structfield> value are considered as logically - grouped. Groups are used to report - <itemizedlist> - <listitem><para>ALSA, VBI and video nodes that carry the same media - stream</para></listitem> - <listitem><para>lens and flash controllers associated with a sensor</para></listitem> - </itemizedlist> - </para> <table pgwide="1" frame="none" id="media-entity-desc"> <title>struct <structname>media_entity_desc</structname></title> @@ -106,7 +97,7 @@ <entry><structfield>revision</structfield></entry> <entry></entry> <entry></entry> - <entry>Entity revision in a driver/hardware specific format.</entry> + <entry>Entity revision. Always zero (obsolete)</entry> </row> <row> <entry>__u32</entry> @@ -120,7 +111,7 @@ <entry><structfield>group_id</structfield></entry> <entry></entry> <entry></entry> - <entry>Entity group ID</entry> + <entry>Entity group ID. Always zero (obsolete)</entry> </row> <row> <entry>__u16</entry> @@ -171,97 +162,6 @@ </tbody> </tgroup> </table> - - <table frame="none" pgwide="1" id="media-entity-type"> - <title>Media entity types</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry> - <entry>Unknown device node</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry> - <entry>V4L video, radio or vbi device node</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry> - <entry>Frame buffer device node</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry> - <entry>ALSA card</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_FE</constant></entry> - <entry>DVB frontend devnode</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_DEMUX</constant></entry> - <entry>DVB demux devnode</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_DVR</constant></entry> - <entry>DVB DVR devnode</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_CA</constant></entry> - <entry>DVB CAM devnode</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_DEVNODE_DVB_NET</constant></entry> - <entry>DVB network devnode</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry> - <entry>Unknown V4L sub-device</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry> - <entry>Video sensor</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry> - <entry>Flash controller</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry> - <entry>Lens controller</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_DECODER</constant></entry> - <entry>Video decoder, the basic function of the video decoder is to - accept analogue video from a wide variety of sources such as - broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL or HD format and still occasionally SECAM, separate - it into its component parts, luminance and chrominance, and output - it in some digital video standard, with appropriate embedded timing - signals.</entry> - </row> - <row> - <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_TUNER</constant></entry> - <entry>TV and/or radio tuner</entry> - </row> - </tbody> - </tgroup> - </table> - - <table frame="none" pgwide="1" id="media-entity-flag"> - <title>Media entity flags</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry> - <entry>Default entity for its type. Used to discover the default - audio, VBI and video devices, the default camera sensor, ...</entry> - </row> - </tbody> - </tgroup> - </table> </refsect1> <refsect1> diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml index 74fb394ec667..2bbeea9f3e18 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml @@ -118,35 +118,6 @@ </tgroup> </table> - <table frame="none" pgwide="1" id="media-pad-flag"> - <title>Media pad flags</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_PAD_FL_SINK</constant></entry> - <entry>Input pad, relative to the entity. Input pads sink data and - are targets of links.</entry> - </row> - <row> - <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry> - <entry>Output pad, relative to the entity. Output pads source data - and are origins of links.</entry> - </row> - <row> - <entry><constant>MEDIA_PAD_FL_MUST_CONNECT</constant></entry> - <entry>If this flag is set and the pad is linked to any other - pad, then at least one of those links must be enabled for the - entity to be able to stream. There could be temporary reasons - (e.g. device configuration dependent) for the pad to need - enabled links even when this flag isn't set; the absence of the - flag doesn't imply there is none.</entry> - </row> - </tbody> - </tgroup> - </table> - <table pgwide="1" frame="none" id="media-link-desc"> <title>struct <structname>media_link_desc</structname></title> <tgroup cols="3"> @@ -171,33 +142,6 @@ </tgroup> </table> - <table frame="none" pgwide="1" id="media-link-flag"> - <title>Media link flags</title> - <tgroup cols="2"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <tbody valign="top"> - <row> - <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry> - <entry>The link is enabled and can be used to transfer media data. - When two or more links target a sink pad, only one of them can be - enabled at a time.</entry> - </row> - <row> - <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry> - <entry>The link enabled state can't be modified at runtime. An - immutable link is always enabled.</entry> - </row> - <row> - <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry> - <entry>The link enabled state can be modified during streaming. This - flag is set by drivers and is read-only for applications.</entry> - </row> - </tbody> - </tgroup> - </table> - <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and - <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para> </refsect1> <refsect1> diff --git a/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml new file mode 100644 index 000000000000..e0d49fa329f0 --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-ioc-g-topology.xml @@ -0,0 +1,391 @@ +<refentry id="media-g-topology"> + <refmeta> + <refentrytitle>ioctl MEDIA_IOC_G_TOPOLOGY</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>MEDIA_IOC_G_TOPOLOGY</refname> + <refpurpose>Enumerate the graph topology and graph element properties</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct media_v2_topology *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='media-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>MEDIA_IOC_G_TOPOLOGY</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para>The typical usage of this ioctl is to call it twice. + On the first call, the structure defined at &media-v2-topology; should + be zeroed. At return, if no errors happen, this ioctl will return the + <constant>topology_version</constant> and the total number of entities, + interfaces, pads and links.</para> + <para>Before the second call, the userspace should allocate arrays to + store the graph elements that are desired, putting the pointers to them + at the ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping + the other values untouched.</para> + <para>If the <constant>topology_version</constant> remains the same, the + ioctl should fill the desired arrays with the media graph elements.</para> + + <table pgwide="1" frame="none" id="media-v2-topology"> + <title>struct <structname>media_v2_topology</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u64</entry> + <entry><structfield>topology_version</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Version of the media graph topology. When the graph is + created, this field starts with zero. Every time a graph + element is added or removed, this field is + incremented.</entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>num_entities</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Number of entities in the graph</entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>ptr_entities</structfield></entry> + <entry></entry> + <entry></entry> + <entry>A pointer to a memory area where the entities array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + entities. It will just update + <constant>num_entities</constant></entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>num_interfaces</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Number of interfaces in the graph</entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>ptr_interfaces</structfield></entry> + <entry></entry> + <entry></entry> + <entry>A pointer to a memory area where the interfaces array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + interfaces. It will just update + <constant>num_interfaces</constant></entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>num_pads</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Total number of pads in the graph</entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>ptr_pads</structfield></entry> + <entry></entry> + <entry></entry> + <entry>A pointer to a memory area where the pads array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + pads. It will just update + <constant>num_pads</constant></entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>num_links</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Total number of data and interface links in the graph</entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>ptr_links</structfield></entry> + <entry></entry> + <entry></entry> + <entry>A pointer to a memory area where the links array + will be stored, converted to a 64-bits integer. + It can be zero. if zero, the ioctl won't store the + links. It will just update + <constant>num_links</constant></entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-v2-entity"> + <title>struct <structname>media_v2_entity</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Unique ID for the entity.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>name</structfield>[64]</entry> + <entry></entry> + <entry></entry> + <entry>Entity name as an UTF-8 NULL-terminated string.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>function</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Entity main function, see <xref linkend="media-entity-type" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[12]</entry> + <entry>Reserved for future extensions. Drivers and applications must + set this array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-v2-interface"> + <title>struct <structname>media_v2_interface</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Unique ID for the interface.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>intf_type</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Interface type, see <xref linkend="media-intf-type" /> for details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Interface flags. Currently unused.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[9]</entry> + <entry></entry> + <entry></entry> + <entry>Reserved for future extensions. Drivers and applications must + set this array to zero.</entry> + </row> + <row> + <entry>struct media_v2_intf_devnode</entry> + <entry><structfield>devnode</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Used only for device node interfaces. See <xref linkend="media-v2-intf-devnode" /> for details..</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-v2-intf-devnode"> + <title>struct <structname>media_v2_interface</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>major</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Device node major number.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>minor</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Device node minor number.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-v2-pad"> + <title>struct <structname>media_v2_pad</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Unique ID for the pad.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>entity_id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Unique ID for the entity where this pad belongs.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[9]</entry> + <entry></entry> + <entry></entry> + <entry>Reserved for future extensions. Drivers and applications must + set this array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="media-v2-link"> + <title>struct <structname>media_v2_pad</structname></title> + <tgroup cols="5"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Unique ID for the pad.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>source_id</structfield></entry> + <entry></entry> + <entry></entry> + <entry> + <para>On pad to pad links: unique ID for the source pad.</para> + <para>On interface to entity links: unique ID for the interface.</para> + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>sink_id</structfield></entry> + <entry></entry> + <entry></entry> + <entry> + <para>On pad to pad links: unique ID for the sink pad.</para> + <para>On interface to entity links: unique ID for the entity.</para> + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry></entry> + <entry></entry> + <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[5]</entry> + <entry></entry> + <entry></entry> + <entry>Reserved for future extensions. Drivers and applications must + set this array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>ENOSPC</errorcode></term> + <listitem> + <para>This is returned when either one or more of the num_entities, + num_interfaces, num_links or num_pads are non-zero and are smaller + than the actual number of elements inside the graph. This may happen + if the <constant>topology_version</constant> changed when compared + to the last time this ioctl was called. Userspace should usually + free the area for the pointers, zero the struct elements and call + this ioctl again.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml new file mode 100644 index 000000000000..5e3f20fdcf17 --- /dev/null +++ b/Documentation/DocBook/media/v4l/media-types.xml @@ -0,0 +1,315 @@ +<section id="media-controller-types"> +<title>Types and flags used to represent the media graph elements</title> + + <table frame="none" pgwide="1" id="media-entity-type"> + <title>Media entity types</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_ENT_F_UNKNOWN</constant> and <constant>MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN</constant></entry> + <entry>Unknown entity. That generally indicates that + a driver didn't initialize properly the entity, with is a Kernel bug</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_IO_V4L</constant></entry> + <entry>Data streaming input and/or output entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_IO_VBI</constant></entry> + <entry>V4L VBI streaming input or output entity</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_IO_SWRADIO</constant></entry> + <entry>V4L Software Digital Radio (SDR) streaming input or output entity</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_IO_DTV</constant></entry> + <entry>DVB Digital TV streaming input or output entity</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_DTV_DEMOD</constant></entry> + <entry>Digital TV demodulator entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_TS_DEMUX</constant></entry> + <entry>MPEG Transport stream demux entity. Could be implemented on hardware or in Kernelspace by the Linux DVB subsystem.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_DTV_CA</constant></entry> + <entry>Digital TV Conditional Access module (CAM) entity</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_DTV_NET_DECAP</constant></entry> + <entry>Digital TV network ULE/MLE desencapsulation entity. Could be implemented on hardware or in Kernelspace</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_CONN_RF</constant></entry> + <entry>Connector for a Radio Frequency (RF) signal.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_CONN_SVIDEO</constant></entry> + <entry>Connector for a S-Video signal.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_CONN_COMPOSITE</constant></entry> + <entry>Connector for a RGB composite signal.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_CAM_SENSOR</constant></entry> + <entry>Camera video sensor entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_FLASH</constant></entry> + <entry>Flash controller entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_LENS</constant></entry> + <entry>Lens controller entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_ATV_DECODER</constant></entry> + <entry>Analog video decoder, the basic function of the video decoder + is to accept analogue video from a wide variety of sources such as + broadcast, DVD players, cameras and video cassette recorders, in + either NTSC, PAL, SECAM or HD format, separating the stream + into its component parts, luminance and chrominance, and output + it in some digital video standard, with appropriate timing + signals.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_TUNER</constant></entry> + <entry>Digital TV, analog TV, radio and/or software radio tuner, + with consists on a PLL tuning stage that converts radio + frequency (RF) signal into an Intermediate Frequency (IF). + Modern tuners have internally IF-PLL decoders for audio + and video, but older models have those stages implemented + on separate entities. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_IF_VID_DECODER</constant></entry> + <entry>IF-PLL video decoder. It receives the IF from a PLL + and decodes the analog TV video signal. This is commonly + found on some very old analog tuners, like Philips MK3 + designs. They all contain a tda9887 (or some software + compatible similar chip, like tda9885). Those devices + use a different I2C address than the tuner PLL. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_IF_AUD_DECODER</constant></entry> + <entry>IF-PLL sound decoder. It receives the IF from a PLL + and decodes the analog TV audio signal. This is commonly + found on some very old analog hardware, like Micronas + msp3400, Philips tda9840, tda985x, etc. Those devices + use a different I2C address than the tuner PLL and + should be controlled together with the IF-PLL video + decoder. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_AUDIO_CAPTURE</constant></entry> + <entry>Audio Capture Function Entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_AUDIO_PLAYBACK</constant></entry> + <entry>Audio Playback Function Entity.</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_AUDIO_MIXER</constant></entry> + <entry>Audio Mixer Function Entity.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-entity-flag"> + <title>Media entity flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry> + <entry>Default entity for its type. Used to discover the default + audio, VBI and video devices, the default camera sensor, ...</entry> + </row> + <row> + <entry><constant>MEDIA_ENT_FL_CONNECTOR</constant></entry> + <entry>The entity represents a data conector</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-intf-type"> + <title>Media interface types</title> + <tgroup cols="3"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <colspec colname="c3"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_INTF_T_DVB_FE</constant></entry> + <entry>Device node interface for the Digital TV frontend</entry> + <entry>typically, /dev/dvb/adapter?/frontend?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_DEMUX</constant></entry> + <entry>Device node interface for the Digital TV demux</entry> + <entry>typically, /dev/dvb/adapter?/demux?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_DVR</constant></entry> + <entry>Device node interface for the Digital TV DVR</entry> + <entry>typically, /dev/dvb/adapter?/dvr?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_CA</constant></entry> + <entry>Device node interface for the Digital TV Conditional Access</entry> + <entry>typically, /dev/dvb/adapter?/ca?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_DVB_FE</constant></entry> + <entry>Device node interface for the Digital TV network control</entry> + <entry>typically, /dev/dvb/adapter?/net?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_VIDEO</constant></entry> + <entry>Device node interface for video (V4L)</entry> + <entry>typically, /dev/video?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_VBI</constant></entry> + <entry>Device node interface for VBI (V4L)</entry> + <entry>typically, /dev/vbi?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_RADIO</constant></entry> + <entry>Device node interface for radio (V4L)</entry> + <entry>typically, /dev/vbi?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_SUBDEV</constant></entry> + <entry>Device node interface for a V4L subdevice</entry> + <entry>typically, /dev/v4l-subdev?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_V4L_SWRADIO</constant></entry> + <entry>Device node interface for Software Defined Radio (V4L)</entry> + <entry>typically, /dev/swradio?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_PCM_CAPTURE</constant></entry> + <entry>Device node interface for ALSA PCM Capture</entry> + <entry>typically, /dev/snd/pcmC?D?c</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_PCM_PLAYBACK</constant></entry> + <entry>Device node interface for ALSA PCM Playback</entry> + <entry>typically, /dev/snd/pcmC?D?p</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_CONTROL</constant></entry> + <entry>Device node interface for ALSA Control</entry> + <entry>typically, /dev/snd/controlC?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_COMPRESS</constant></entry> + <entry>Device node interface for ALSA Compress</entry> + <entry>typically, /dev/snd/compr?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_RAWMIDI</constant></entry> + <entry>Device node interface for ALSA Raw MIDI</entry> + <entry>typically, /dev/snd/midi?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_HWDEP</constant></entry> + <entry>Device node interface for ALSA Hardware Dependent</entry> + <entry>typically, /dev/snd/hwC?D?</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_SEQUENCER</constant></entry> + <entry>Device node interface for ALSA Sequencer</entry> + <entry>typically, /dev/snd/seq</entry> + </row> + <row> + <entry><constant>MEDIA_INTF_T_ALSA_TIMER</constant></entry> + <entry>Device node interface for ALSA Timer</entry> + <entry>typically, /dev/snd/timer</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="media-pad-flag"> + <title>Media pad flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_PAD_FL_SINK</constant></entry> + <entry>Input pad, relative to the entity. Input pads sink data and + are targets of links.</entry> + </row> + <row> + <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry> + <entry>Output pad, relative to the entity. Output pads source data + and are origins of links.</entry> + </row> + <row> + <entry><constant>MEDIA_PAD_FL_MUST_CONNECT</constant></entry> + <entry>If this flag is set and the pad is linked to any other + pad, then at least one of those links must be enabled for the + entity to be able to stream. There could be temporary reasons + (e.g. device configuration dependent) for the pad to need + enabled links even when this flag isn't set; the absence of the + flag doesn't imply there is none.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and + <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para> + + <table frame="none" pgwide="1" id="media-link-flag"> + <title>Media link flags</title> + <tgroup cols="2"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry> + <entry>The link is enabled and can be used to transfer media data. + When two or more links target a sink pad, only one of them can be + enabled at a time.</entry> + </row> + <row> + <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry> + <entry>The link enabled state can't be modified at runtime. An + immutable link is always enabled.</entry> + </row> + <row> + <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry> + <entry>The link enabled state can be modified during streaming. This + flag is set by drivers and is read-only for applications.</entry> + </row> + <row> + <entry><constant>MEDIA_LNK_FL_LINK_TYPE</constant></entry> + <entry><para>This is a bitmask that defines the type of the link. + Currently, two types of links are supported:</para> + <para><constant>MEDIA_LNK_FL_DATA_LINK</constant> + if the link is between two pads</para> + <para><constant>MEDIA_LNK_FL_INTERFACE_LINK</constant> + if the link is between an interface and an entity</para></entry> + </row> + </tbody> + </tgroup> + </table> + +</section> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y12i.xml b/Documentation/DocBook/media/v4l/pixfmt-y12i.xml new file mode 100644 index 000000000000..4a2d1e5f67e4 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-y12i.xml @@ -0,0 +1,49 @@ +<refentry id="V4L2-PIX-FMT-Y12I"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_Y12I ('Y12I')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname><constant>V4L2_PIX_FMT_Y12I</constant></refname> + <refpurpose>Interleaved grey-scale image, e.g. from a stereo-pair</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is a grey-scale image with a depth of 12 bits per pixel, but with +pixels from 2 sources interleaved and bit-packed. Each pixel is stored in a +24-bit word in the little-endian order. On a little-endian machine these pixels +can be deinterlaced using</para> + +<para> +<programlisting> +__u8 *buf; +left0 = 0xfff & *(__u16 *)buf; +right0 = *(__u16 *)(buf + 1) >> 4; +</programlisting> +</para> + + <example> + <title><constant>V4L2_PIX_FMT_Y12I</constant> 2 pixel data stream taking 3 bytes</title> + + <formalpara> + <title>Bit-packed representation</title> + <para>pixels cross the byte boundary and have a ratio of 3 bytes for each + interleaved pixel. + <informaltable frame="all"> + <tgroup cols="3" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>Y'<subscript>0left[7:0]</subscript></entry> + <entry>Y'<subscript>0right[3:0]</subscript>Y'<subscript>0left[11:8]</subscript></entry> + <entry>Y'<subscript>0right[11:4]</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-y8i.xml b/Documentation/DocBook/media/v4l/pixfmt-y8i.xml new file mode 100644 index 000000000000..99f389d4c6c8 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-y8i.xml @@ -0,0 +1,80 @@ +<refentry id="V4L2-PIX-FMT-Y8I"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_Y8I ('Y8I ')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname><constant>V4L2_PIX_FMT_Y8I</constant></refname> + <refpurpose>Interleaved grey-scale image, e.g. from a stereo-pair</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is a grey-scale image with a depth of 8 bits per pixel, but with +pixels from 2 sources interleaved. Each pixel is stored in a 16-bit word. E.g. +the R200 RealSense camera stores pixel from the left sensor in lower and from +the right sensor in the higher 8 bits.</para> + + <example> + <title><constant>V4L2_PIX_FMT_Y8I</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="9" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>Y'<subscript>00left</subscript></entry> + <entry>Y'<subscript>00right</subscript></entry> + <entry>Y'<subscript>01left</subscript></entry> + <entry>Y'<subscript>01right</subscript></entry> + <entry>Y'<subscript>02left</subscript></entry> + <entry>Y'<subscript>02right</subscript></entry> + <entry>Y'<subscript>03left</subscript></entry> + <entry>Y'<subscript>03right</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>Y'<subscript>10left</subscript></entry> + <entry>Y'<subscript>10right</subscript></entry> + <entry>Y'<subscript>11left</subscript></entry> + <entry>Y'<subscript>11right</subscript></entry> + <entry>Y'<subscript>12left</subscript></entry> + <entry>Y'<subscript>12right</subscript></entry> + <entry>Y'<subscript>13left</subscript></entry> + <entry>Y'<subscript>13right</subscript></entry> + </row> + <row> + <entry>start + 16:</entry> + <entry>Y'<subscript>20left</subscript></entry> + <entry>Y'<subscript>20right</subscript></entry> + <entry>Y'<subscript>21left</subscript></entry> + <entry>Y'<subscript>21right</subscript></entry> + <entry>Y'<subscript>22left</subscript></entry> + <entry>Y'<subscript>22right</subscript></entry> + <entry>Y'<subscript>23left</subscript></entry> + <entry>Y'<subscript>23right</subscript></entry> + </row> + <row> + <entry>start + 24:</entry> + <entry>Y'<subscript>30left</subscript></entry> + <entry>Y'<subscript>30right</subscript></entry> + <entry>Y'<subscript>31left</subscript></entry> + <entry>Y'<subscript>31right</subscript></entry> + <entry>Y'<subscript>32left</subscript></entry> + <entry>Y'<subscript>32right</subscript></entry> + <entry>Y'<subscript>33left</subscript></entry> + <entry>Y'<subscript>33right</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml index e781cc61786c..7d13fe96657d 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml @@ -1,35 +1,43 @@ - <refentry id="V4L2-PIX-FMT-YUV420M"> + <refentry> <refmeta> - <refentrytitle>V4L2_PIX_FMT_YUV420M ('YM12')</refentrytitle> + <refentrytitle>V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21')</refentrytitle> &manvol; </refmeta> <refnamediv> - <refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant> - with planes non contiguous in memory. </refpurpose> + <refname id="V4L2-PIX-FMT-YUV420M"><constant>V4L2_PIX_FMT_YUV420M</constant></refname> + <refname id="V4L2-PIX-FMT-YVU420M"><constant>V4L2_PIX_FMT_YVU420M</constant></refname> + <refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant> and + <constant>V4L2_PIX_FMT_YVU420</constant> with planes non contiguous + in memory.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <para>This is a multi-planar format, as opposed to a packed format. -The three components are separated into three sub- images or planes. +The three components are separated into three sub-images or planes.</para> -The Y plane is first. The Y plane has one byte per pixel. The Cb data + <para>The Y plane is first. The Y plane has one byte per pixel. +For <constant>V4L2_PIX_FMT_YUV420M</constant> the Cb data constitutes the second plane which is half the width and half the height of the Y plane (and of the image). Each Cb belongs to four pixels, a two-by-two square of the image. For example, Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is -in the third plane. </para> +in the third plane.</para> + + <para><constant>V4L2_PIX_FMT_YVU420M</constant> is the same except +the Cr data is stored in the second plane and the Cb data in the third plane. +</para> <para>If the Y plane has pad bytes after each row, then the Cb and Cr planes have half as many pad bytes after their rows. In other words, two Cx rows (including padding) is exactly as long as one Y row (including padding).</para> - <para><constant>V4L2_PIX_FMT_YUV420M</constant> is intended to be + <para><constant>V4L2_PIX_FMT_YUV420M</constant> and +<constant>V4L2_PIX_FMT_YVU420M</constant> are intended to be used only in drivers and applications that support the multi-planar API, described in <xref linkend="planar-apis"/>. </para> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv422m.xml index 2330667907c7..dd502802cb75 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv422m.xml @@ -1,40 +1,45 @@ - <refentry id="V4L2-PIX-FMT-YVU420M"> + <refentry> <refmeta> - <refentrytitle>V4L2_PIX_FMT_YVU420M ('YM21')</refentrytitle> + <refentrytitle>V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61')</refentrytitle> &manvol; </refmeta> <refnamediv> - <refname> <constant>V4L2_PIX_FMT_YVU420M</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_YVU420</constant> - with planes non contiguous in memory. </refpurpose> + <refname id="V4L2-PIX-FMT-YUV422M"><constant>V4L2_PIX_FMT_YUV422M</constant></refname> + <refname id="V4L2-PIX-FMT-YVU422M"><constant>V4L2_PIX_FMT_YVU422M</constant></refname> + <refpurpose>Planar formats with ½ horizontal resolution, also + known as YUV and YVU 4:2:2</refpurpose> </refnamediv> <refsect1> <title>Description</title> <para>This is a multi-planar format, as opposed to a packed format. -The three components are separated into three sub-images or planes. +The three components are separated into three sub-images or planes.</para> -The Y plane is first. The Y plane has one byte per pixel. The Cr data -constitutes the second plane which is half the width and half -the height of the Y plane (and of the image). Each Cr belongs to four -pixels, a two-by-two square of the image. For example, -Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, -Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and -Y'<subscript>11</subscript>. The Cb data, just like the Cr plane, constitutes -the third plane. </para> + <para>The Y plane is first. The Y plane has one byte per pixel. +For <constant>V4L2_PIX_FMT_YUV422M</constant> the Cb data +constitutes the second plane which is half the width of the Y plane (and of the +image). Each Cb belongs to two pixels. For example, +Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, +Y'<subscript>01</subscript>. The Cr data, just like the Cb plane, is +in the third plane. </para> - <para>If the Y plane has pad bytes after each row, then the Cr -and Cb planes have half as many pad bytes after their rows. In other + <para><constant>V4L2_PIX_FMT_YVU422M</constant> is the same except +the Cr data is stored in the second plane and the Cb data in the third plane. +</para> + + <para>If the Y plane has pad bytes after each row, then the Cb +and Cr planes have half as many pad bytes after their rows. In other words, two Cx rows (including padding) is exactly as long as one Y row (including padding).</para> - <para><constant>V4L2_PIX_FMT_YVU420M</constant> is intended to be + <para><constant>V4L2_PIX_FMT_YUV422M</constant> and +<constant>V4L2_PIX_FMT_YVU422M</constant> are intended to be used only in drivers and applications that support the multi-planar API, described in <xref linkend="planar-apis"/>. </para> <example> - <title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 × 4 + <title><constant>V4L2_PIX_FMT_YUV422M</constant> 4 × 4 pixel image</title> <formalpara> @@ -75,24 +80,44 @@ pixel image</title> <row><entry></entry></row> <row> <entry>start1 + 0:</entry> - <entry>Cr<subscript>00</subscript></entry> - <entry>Cr<subscript>01</subscript></entry> + <entry>Cb<subscript>00</subscript></entry> + <entry>Cb<subscript>01</subscript></entry> </row> <row> <entry>start1 + 2:</entry> - <entry>Cr<subscript>10</subscript></entry> - <entry>Cr<subscript>11</subscript></entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cb<subscript>11</subscript></entry> + </row> + <row> + <entry>start1 + 4:</entry> + <entry>Cb<subscript>20</subscript></entry> + <entry>Cb<subscript>21</subscript></entry> + </row> + <row> + <entry>start1 + 6:</entry> + <entry>Cb<subscript>30</subscript></entry> + <entry>Cb<subscript>31</subscript></entry> </row> <row><entry></entry></row> <row> <entry>start2 + 0:</entry> - <entry>Cb<subscript>00</subscript></entry> - <entry>Cb<subscript>01</subscript></entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cr<subscript>01</subscript></entry> </row> <row> <entry>start2 + 2:</entry> - <entry>Cb<subscript>10</subscript></entry> - <entry>Cb<subscript>11</subscript></entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cr<subscript>11</subscript></entry> + </row> + <row> + <entry>start2 + 4:</entry> + <entry>Cr<subscript>20</subscript></entry> + <entry>Cr<subscript>21</subscript></entry> + </row> + <row> + <entry>start2 + 6:</entry> + <entry>Cr<subscript>30</subscript></entry> + <entry>Cr<subscript>31</subscript></entry> </row> </tbody> </tgroup> @@ -113,36 +138,23 @@ pixel image</title> </row> <row> <entry>0</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry> </row> <row> <entry>1</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry> </row> <row> <entry>2</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> - </row> - <row> - <entry></entry> - <entry></entry><entry>C</entry><entry></entry><entry></entry> - <entry></entry><entry>C</entry><entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry> </row> <row> <entry>3</entry> - <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> - <entry>Y</entry><entry></entry><entry>Y</entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry>C</entry><entry>Y</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv444m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv444m.xml new file mode 100644 index 000000000000..1b7335940bc7 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-yuv444m.xml @@ -0,0 +1,177 @@ + <refentry> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-YUV444M"><constant>V4L2_PIX_FMT_YUV444M</constant></refname> + <refname id="V4L2-PIX-FMT-YVU444M"><constant>V4L2_PIX_FMT_YVU444M</constant></refname> + <refpurpose>Planar formats with full horizontal resolution, also + known as YUV and YVU 4:4:4</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>This is a multi-planar format, as opposed to a packed format. +The three components are separated into three sub-images or planes.</para> + + <para>The Y plane is first. The Y plane has one byte per pixel. +For <constant>V4L2_PIX_FMT_YUV444M</constant> the Cb data +constitutes the second plane which is the same width and height as the Y plane +(and as the image). The Cr data, just like the Cb plane, is in the third plane. +</para> + + <para><constant>V4L2_PIX_FMT_YVU444M</constant> is the same except +the Cr data is stored in the second plane and the Cb data in the third plane. +</para> + <para>If the Y plane has pad bytes after each row, then the Cb +and Cr planes have the same number of pad bytes after their rows.</para> + + <para><constant>V4L2_PIX_FMT_YUV444M</constant> and +<constant>V4L2_PIX_FMT_YUV444M</constant> are intended to be +used only in drivers and applications that support the multi-planar API, +described in <xref linkend="planar-apis"/>. </para> + + <example> + <title><constant>V4L2_PIX_FMT_YUV444M</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="5" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start0 + 0:</entry> + <entry>Y'<subscript>00</subscript></entry> + <entry>Y'<subscript>01</subscript></entry> + <entry>Y'<subscript>02</subscript></entry> + <entry>Y'<subscript>03</subscript></entry> + </row> + <row> + <entry>start0 + 4:</entry> + <entry>Y'<subscript>10</subscript></entry> + <entry>Y'<subscript>11</subscript></entry> + <entry>Y'<subscript>12</subscript></entry> + <entry>Y'<subscript>13</subscript></entry> + </row> + <row> + <entry>start0 + 8:</entry> + <entry>Y'<subscript>20</subscript></entry> + <entry>Y'<subscript>21</subscript></entry> + <entry>Y'<subscript>22</subscript></entry> + <entry>Y'<subscript>23</subscript></entry> + </row> + <row> + <entry>start0 + 12:</entry> + <entry>Y'<subscript>30</subscript></entry> + <entry>Y'<subscript>31</subscript></entry> + <entry>Y'<subscript>32</subscript></entry> + <entry>Y'<subscript>33</subscript></entry> + </row> + <row><entry></entry></row> + <row> + <entry>start1 + 0:</entry> + <entry>Cb<subscript>00</subscript></entry> + <entry>Cb<subscript>01</subscript></entry> + <entry>Cb<subscript>02</subscript></entry> + <entry>Cb<subscript>03</subscript></entry> + </row> + <row> + <entry>start1 + 4:</entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cb<subscript>11</subscript></entry> + <entry>Cb<subscript>12</subscript></entry> + <entry>Cb<subscript>13</subscript></entry> + </row> + <row> + <entry>start1 + 8:</entry> + <entry>Cb<subscript>20</subscript></entry> + <entry>Cb<subscript>21</subscript></entry> + <entry>Cb<subscript>22</subscript></entry> + <entry>Cb<subscript>23</subscript></entry> + </row> + <row> + <entry>start1 + 12:</entry> + <entry>Cb<subscript>20</subscript></entry> + <entry>Cb<subscript>21</subscript></entry> + <entry>Cb<subscript>32</subscript></entry> + <entry>Cb<subscript>33</subscript></entry> + </row> + <row><entry></entry></row> + <row> + <entry>start2 + 0:</entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cr<subscript>01</subscript></entry> + <entry>Cr<subscript>02</subscript></entry> + <entry>Cr<subscript>03</subscript></entry> + </row> + <row> + <entry>start2 + 4:</entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cr<subscript>11</subscript></entry> + <entry>Cr<subscript>12</subscript></entry> + <entry>Cr<subscript>13</subscript></entry> + </row> + <row> + <entry>start2 + 8:</entry> + <entry>Cr<subscript>20</subscript></entry> + <entry>Cr<subscript>21</subscript></entry> + <entry>Cr<subscript>22</subscript></entry> + <entry>Cr<subscript>23</subscript></entry> + </row> + <row> + <entry>start2 + 12:</entry> + <entry>Cr<subscript>30</subscript></entry> + <entry>Cr<subscript>31</subscript></entry> + <entry>Cr<subscript>32</subscript></entry> + <entry>Cr<subscript>33</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + + <formalpara> + <title>Color Sample Location.</title> + <para> + <informaltable frame="none"> + <tgroup cols="7" align="center"> + <tbody valign="top"> + <row> + <entry></entry> + <entry>0</entry><entry></entry><entry>1</entry><entry></entry> + <entry>2</entry><entry></entry><entry>3</entry> + </row> + <row> + <entry>0</entry> + <entry>YC</entry><entry></entry><entry>YC</entry><entry></entry> + <entry>YC</entry><entry></entry><entry>YC</entry> + </row> + <row> + <entry>1</entry> + <entry>YC</entry><entry></entry><entry>YC</entry><entry></entry> + <entry>YC</entry><entry></entry><entry>YC</entry> + </row> + <row> + <entry>2</entry> + <entry>YC</entry><entry></entry><entry>YC</entry><entry></entry> + <entry>YC</entry><entry></entry><entry>YC</entry> + </row> + <row> + <entry>3</entry> + <entry>YC</entry><entry></entry><entry>YC</entry><entry></entry> + <entry>YC</entry><entry></entry><entry>YC</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-z16.xml b/Documentation/DocBook/media/v4l/pixfmt-z16.xml new file mode 100644 index 000000000000..3d87e4bf87b8 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-z16.xml @@ -0,0 +1,81 @@ +<refentry id="V4L2-PIX-FMT-Z16"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_Z16 ('Z16 ')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname><constant>V4L2_PIX_FMT_Z16</constant></refname> + <refpurpose>Interleaved grey-scale image, e.g. from a stereo-pair</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is a 16-bit format, representing depth data. Each pixel is a +distance to the respective point in the image coordinates. Distance unit can +vary and has to be negotiated with the device separately. Each pixel is stored +in a 16-bit word in the little endian byte order. +</para> + + <example> + <title><constant>V4L2_PIX_FMT_Z16</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="9" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>Z<subscript>00low</subscript></entry> + <entry>Z<subscript>00high</subscript></entry> + <entry>Z<subscript>01low</subscript></entry> + <entry>Z<subscript>01high</subscript></entry> + <entry>Z<subscript>02low</subscript></entry> + <entry>Z<subscript>02high</subscript></entry> + <entry>Z<subscript>03low</subscript></entry> + <entry>Z<subscript>03high</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>Z<subscript>10low</subscript></entry> + <entry>Z<subscript>10high</subscript></entry> + <entry>Z<subscript>11low</subscript></entry> + <entry>Z<subscript>11high</subscript></entry> + <entry>Z<subscript>12low</subscript></entry> + <entry>Z<subscript>12high</subscript></entry> + <entry>Z<subscript>13low</subscript></entry> + <entry>Z<subscript>13high</subscript></entry> + </row> + <row> + <entry>start + 16:</entry> + <entry>Z<subscript>20low</subscript></entry> + <entry>Z<subscript>20high</subscript></entry> + <entry>Z<subscript>21low</subscript></entry> + <entry>Z<subscript>21high</subscript></entry> + <entry>Z<subscript>22low</subscript></entry> + <entry>Z<subscript>22high</subscript></entry> + <entry>Z<subscript>23low</subscript></entry> + <entry>Z<subscript>23high</subscript></entry> + </row> + <row> + <entry>start + 24:</entry> + <entry>Z<subscript>30low</subscript></entry> + <entry>Z<subscript>30high</subscript></entry> + <entry>Z<subscript>31low</subscript></entry> + <entry>Z<subscript>31high</subscript></entry> + <entry>Z<subscript>32low</subscript></entry> + <entry>Z<subscript>32high</subscript></entry> + <entry>Z<subscript>33low</subscript></entry> + <entry>Z<subscript>33high</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 965ea916784a..5a08aeea4360 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -540,6 +540,10 @@ colorspaces except for BT.2020 which uses limited range R'G'B' quantization.</pa <entry>See <xref linkend="col-bt2020" />.</entry> </row> <row> + <entry><constant>V4L2_COLORSPACE_DCI_P3</constant></entry> + <entry>See <xref linkend="col-dcip3" />.</entry> + </row> + <row> <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> <entry>See <xref linkend="col-smpte-240m" />.</entry> </row> @@ -601,6 +605,14 @@ colorspaces except for BT.2020 which uses limited range R'G'B' quantization.</pa <entry><constant>V4L2_XFER_FUNC_NONE</constant></entry> <entry>Do not use a transfer function (i.e. use linear RGB values).</entry> </row> + <row> + <entry><constant>V4L2_XFER_FUNC_DCI_P3</constant></entry> + <entry>Use the DCI-P3 transfer function.</entry> + </row> + <row> + <entry><constant>V4L2_XFER_FUNC_SMPTE2084</constant></entry> + <entry>Use the SMPTE 2084 transfer function.</entry> + </row> </tbody> </tgroup> </table> @@ -1154,6 +1166,68 @@ clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> </section> + <section id="col-dcip3"> + <title>Colorspace DCI-P3 (<constant>V4L2_COLORSPACE_DCI_P3</constant>)</title> + <para>The <xref linkend="smpte431" /> standard defines the colorspace used by cinema +projectors that use the DCI-P3 colorspace. +The default transfer function is <constant>V4L2_XFER_FUNC_DCI_P3</constant>. +The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. Note that this +colorspace does not specify a Y'CbCr encoding since it is not meant to be encoded +to Y'CbCr. So this default Y'CbCr encoding was picked because it is the HDTV +encoding. The default Y'CbCr quantization is limited range. The chromaticities of +the primary colors and the white reference are:</para> + <table frame="none"> + <title>DCI-P3 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.6800</entry> + <entry>0.3200</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.2650</entry> + <entry>0.6900</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.1500</entry> + <entry>0.0600</entry> + </row> + <row> + <entry>White Reference</entry> + <entry>0.3140</entry> + <entry>0.3510</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = L<superscript>1/2.6</superscript></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L'<superscript>2.6</superscript></para> + </listitem> + </varlistentry> + </variablelist> + <para>Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.</para> + </section> + <section id="col-smpte-240m"> <title>Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> <para>The <xref linkend="smpte240m" /> standard was an interim standard used during @@ -1402,6 +1476,41 @@ and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> </section> + <section> + <title>Detailed Transfer Function Descriptions</title> + <section id="xf-smpte-2084"> + <title>Transfer Function SMPTE 2084 (<constant>V4L2_XFER_FUNC_SMPTE2084</constant>)</title> + <para>The <xref linkend="smpte2084" /> standard defines the transfer function used by +High Dynamic Range content.</para> + <variablelist> + <varlistentry> + <term>Constants:</term> + <listitem> + <para>m1 = (2610 / 4096) / 4</para> + <para>m2 = (2523 / 4096) * 128</para> + <para>c1 = 3424 / 4096</para> + <para>c2 = (2413 / 4096) * 32</para> + <para>c3 = (2392 / 4096) * 32</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = ((c1 + c2 * L<superscript>m1</superscript>) / (1 + c3 * L<superscript>m1</superscript>))<superscript>m2</superscript></para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = (max(L'<superscript>1/m2</superscript> - c1, 0) / (c2 - c3 * L'<superscript>1/m2</superscript>))<superscript>1/m1</superscript></para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + <section id="pixfmt-indexed"> <title>Indexed Format</title> @@ -1511,6 +1620,8 @@ information.</para> &sub-y10b; &sub-y16; &sub-y16-be; + &sub-y8i; + &sub-y12i; &sub-uv8; &sub-yuyv; &sub-uyvy; @@ -1519,7 +1630,8 @@ information.</para> &sub-y41p; &sub-yuv420; &sub-yuv420m; - &sub-yvu420m; + &sub-yuv422m; + &sub-yuv444m; &sub-yuv410; &sub-yuv422p; &sub-yuv411p; @@ -1532,6 +1644,14 @@ information.</para> &sub-m420; </section> + <section id="depth-formats"> + <title>Depth Formats</title> + <para>Depth data provides distance to points, mapped onto the image plane + </para> + + &sub-z16; + </section> + <section> <title>Compressed Formats</title> @@ -1623,7 +1743,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see <section id="sdr-formats"> <title>SDR Formats</title> - <para>These formats are used for <link linkend="sdr">SDR Capture</link> + <para>These formats are used for <link linkend="sdr">SDR</link> interface only.</para> &sub-sdr-cu08; diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index e98caa1c39bd..42e626d6c936 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -151,9 +151,28 @@ Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, structs, ioctls) must be noted in more detail in the history chapter (compat.xml), along with the possible impact on existing drivers and applications. --> + <revision> + <revnumber>4.5</revnumber> + <date>2015-10-29</date> + <authorinitials>rr</authorinitials> + <revremark>Extend vidioc-g-ext-ctrls;. Replace ctrl_class with a new +union with ctrl_class and which. Which is used to select the current value of +the control or the default value. + </revremark> + </revision> + + <revision> + <revnumber>4.4</revnumber> + <date>2015-05-26</date> + <authorinitials>ap</authorinitials> + <revremark>Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. +Added V4L2_CID_RF_TUNER_RF_GAIN control. +Added transmitter support for Software Defined Radio (SDR) Interface. + </revremark> + </revision> <revision> - <revnumber>3.21</revnumber> + <revnumber>4.1</revnumber> <date>2015-02-13</date> <authorinitials>mcc</authorinitials> <revremark>Fix documentation for media controller device nodes and add support for DVB device nodes. @@ -557,7 +576,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.19</subtitle> + <subtitle>Revision 4.4</subtitle> <chapter id="common"> &sub-common; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 8ffe74f84af1..d81fa0d4016b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -58,7 +58,7 @@ <para>This ioctl is used to create buffers for <link linkend="mmap">memory mapped</link> or <link linkend="userp">user pointer</link> or <link linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in -addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter +addition to the &VIDIOC-REQBUFS; ioctl, when a tighter control over buffers is required. This ioctl can be called multiple times to create buffers of different sizes.</para> @@ -71,30 +71,28 @@ zeroed.</para> <para>The <structfield>format</structfield> field specifies the image format that the buffers must be able to handle. The application has to fill in this -&v4l2-format;. Usually this will be done using the -<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl() -to ensure that the requested format is supported by the driver. Unsupported -formats will result in an error.</para> +&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls +to ensure that the requested format is supported by the driver. +Based on the format's <structfield>type</structfield> field the requested buffer +size (for single-planar) or plane sizes (for multi-planar formats) will be +used for the allocated buffers. The driver may return an error if the size(s) +are not supported by the hardware (usually because they are too small).</para> <para>The buffers created by this ioctl will have as minimum size the size -defined by the <structfield>format.pix.sizeimage</structfield> field. If the +defined by the <structfield>format.pix.sizeimage</structfield> field (or the +corresponding fields for other format types). Usually if the <structfield>format.pix.sizeimage</structfield> field is less than the minimum -required for the given format, then <structfield>sizeimage</structfield> will be -increased by the driver to that minimum to allocate the buffers. If it is -larger, then the value will be used as-is. The same applies to the -<structfield>sizeimage</structfield> field of the -<structname>v4l2_plane_pix_format</structname> structure in the case of -multiplanar formats.</para> +required for the given format, then an error will be returned since drivers will +typically not allow this. If it is larger, then the value will be used as-is. +In other words, the driver may reject the requested size, but if it is accepted +the driver will use it unchanged.</para> <para>When the ioctl is called with a pointer to this structure the driver will attempt to allocate up to the requested number of buffers and store the actual number allocated and the starting index in the <structfield>count</structfield> and the <structfield>index</structfield> fields respectively. On return <structfield>count</structfield> can be smaller than -the number requested. The driver may also increase buffer sizes if required, -however, it will not update <structfield>sizeimage</structfield> field values. -The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that -information.</para> +the number requested.</para> <table pgwide="1" frame="none" id="v4l2-create-buffers"> <title>struct <structname>v4l2_create_buffers</structname></title> diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml index 4c4603c135fe..f14a3bb1afaa 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml @@ -99,7 +99,7 @@ if the driver supports writing registers to the device.</para> <para>We recommended the <application>v4l2-dbg</application> utility over calling this ioctl directly. It is available from the LinuxTV v4l-dvb repository; see <ulink -url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for +url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for access instructions.</para> <!-- Note for convenience vidioc-dbg-g-register.sgml diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml index 3d038e75d12b..5877f68a5820 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml @@ -117,7 +117,7 @@ However when a driver supports these ioctls it must also support <para>We recommended the <application>v4l2-dbg</application> utility over calling these ioctls directly. It is available from the LinuxTV v4l-dvb repository; see <ulink -url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for +url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for access instructions.</para> <!-- Note for convenience vidioc-dbg-g-chip-info.sgml diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml index fc1d4625a78c..70a4a08e9404 100644 --- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml @@ -130,7 +130,7 @@ encoding will continue until the end of the current <wordasword>Group Of Pictures</wordasword>, otherwise encoding will stop immediately. When the encoder is already stopped, this command does nothing. mem2mem encoders will send a <constant>V4L2_EVENT_EOS</constant> event -when the last frame has been decoded and all frames are ready to be dequeued and +when the last frame has been encoded and all frames are ready to be dequeued and will set the <constant>V4L2_BUF_FLAG_LAST</constant> buffer flag on the last buffer of the capture queue to indicate there will be no new buffers produced to dequeue. This buffer may be empty, indicated by the driver setting the diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml index 8065099401d1..f18454e91752 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml @@ -198,7 +198,7 @@ video4linux-list@redhat.com on 17 Oct 2002 <constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital TV standards. Presently the V4L2 API does not support digital TV. See also the Linux DVB API at <ulink -url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> +url="https://linuxtv.org">https://linuxtv.org</ulink>.</para> <para><programlisting> #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ V4L2_STD_PAL_B1 |\ diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index c5bdbfcc42b3..eb82f7e7d06b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -61,7 +61,7 @@ must belong to the same control class.</para> <para>Applications must always fill in the <structfield>count</structfield>, -<structfield>ctrl_class</structfield>, +<structfield>which</structfield>, <structfield>controls</structfield> and <structfield>reserved</structfield> fields of &v4l2-ext-controls;, and initialize the &v4l2-ext-control; array pointed to by the @@ -109,7 +109,7 @@ the driver whether wrong values are automatically adjusted to a valid value or if an error is returned.</para> <para>When the <structfield>id</structfield> or -<structfield>ctrl_class</structfield> is invalid drivers return an +<structfield>which</structfield> is invalid drivers return an &EINVAL;. When the value is out of bounds drivers can choose to take the closest valid value or return an &ERANGE;, whatever seems more appropriate. In the first case the new value is set in @@ -200,6 +200,13 @@ Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry </row> <row> <entry></entry> + <entry>__u32 *</entry> + <entry><structfield>p_u32</structfield></entry> + <entry>A pointer to a matrix control of unsigned 32-bit values. +Valid if this control is of type <constant>V4L2_CTRL_TYPE_U32</constant>.</entry> + </row> + <row> + <entry></entry> <entry>void *</entry> <entry><structfield>ptr</structfield></entry> <entry>A pointer to a compound type which can be an N-dimensional array and/or a @@ -216,7 +223,12 @@ Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control <tgroup cols="3"> &cs-str; <tbody valign="top"> + <row> + <entry>union</entry> + <entry>(anonymous)</entry> + </row> <row> + <entry></entry> <entry>__u32</entry> <entry><structfield>ctrl_class</structfield></entry> <entry>The control class to which all controls belong, see @@ -228,6 +240,23 @@ with a <structfield>count</structfield> of 0. If that succeeds, then the driver supports this feature.</entry> </row> <row> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>which</structfield></entry> + <entry><para>Which value of the control to get/set/try. <constant>V4L2_CTRL_WHICH_CUR_VAL</constant> +will return the current value of the control and <constant>V4L2_CTRL_WHICH_DEF_VAL</constant> will +return the default value of the control. Please note that you can only get the default value of the +control, you cannot set or try it.</para> +<para>For backwards compatibility you can also use a control class here (see +<xref linkend="ctrl-class" />). In that case all controls have to belong to that +control class. This usage is deprecated, instead just use <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>. +There are some very old drivers that do not yet support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant> +and that require a control class here. You can test for such drivers by setting ctrl_class to +<constant>V4L2_CTRL_WHICH_CUR_VAL</constant> and calling VIDIOC_TRY_EXT_CTRLS with a count of 0. +If that fails, then the driver does not support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.</para> +</entry> + </row> + <row> <entry>__u32</entry> <entry><structfield>count</structfield></entry> <entry>The number of controls in the controls array. May @@ -383,7 +412,7 @@ These controls are described in <xref linkend="rf-tuner-controls" />.</entry> <listitem> <para>The &v4l2-ext-control; <structfield>id</structfield> is invalid, the &v4l2-ext-controls; -<structfield>ctrl_class</structfield> is invalid, or the &v4l2-ext-control; +<structfield>which</structfield> is invalid, or the &v4l2-ext-control; <structfield>value</structfield> was inappropriate (e.g. the given menu index is not supported by the driver). This error code is also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index 4fe19a7a9a31..ffcb448251f0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml @@ -175,7 +175,7 @@ capture and output devices.</entry> <entry>&v4l2-sdr-format;</entry> <entry><structfield>sdr</structfield></entry> <entry>Definition of a data format, see -<xref linkend="pixfmt" />, used by SDR capture devices.</entry> +<xref linkend="pixfmt" />, used by SDR capture and output devices.</entry> </row> <row> <entry></entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml index 7068b599a00d..96e17b344c5d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml @@ -78,6 +78,12 @@ different audio modulation if the request cannot be satisfied. However this is a write-only ioctl, it does not return the actual audio modulation selected.</para> + <para><link linkend="sdr">SDR</link> specific modulator types are +<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>. +For SDR devices <structfield>txsubchans</structfield> field must be +initialized to zero. +The term 'modulator' means SDR transmitter in this context.</para> + <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl is available.</para> @@ -140,7 +146,13 @@ indicator, for example a stereo pilot tone.</entry> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[4]</entry> + <entry><structfield>type</structfield></entry> + <entry spanname="hspan">Type of the modulator, see <xref + linkend="v4l2-tuner-type" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[3]</entry> <entry>Reserved for future extensions. Drivers and applications must set the array to zero.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index b0d865933da6..459b7e561f3c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -80,6 +80,12 @@ if the requested mode is invalid or unsupported. Since this is a <!-- FIXME -->write-only ioctl, it does not return the actually selected audio mode.</para> + <para><link linkend="sdr">SDR</link> specific tuner types are +<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>. +For SDR devices <structfield>audmode</structfield> field must be +initialized to zero. +The term 'tuner' means SDR receiver in this context.</para> + <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl is available.</para> @@ -261,6 +267,16 @@ applications must set the array to zero.</entry> <entry>2</entry> <entry></entry> </row> + <row> + <entry><constant>V4L2_TUNER_SDR</constant></entry> + <entry>4</entry> + <entry></entry> + </row> + <row> + <entry><constant>V4L2_TUNER_RF</constant></entry> + <entry>5</entry> + <entry></entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml index e9c70a8f3476..0c93677d16b4 100644 --- a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml @@ -60,9 +60,19 @@ input</refpurpose> automatically, similar to sensing the video standard. To do so, applications call <constant>VIDIOC_QUERY_DV_TIMINGS</constant> with a pointer to a &v4l2-dv-timings;. Once the hardware detects the timings, it will fill in the -timings structure. +timings structure.</para> -If the timings could not be detected because there was no signal, then +<para>Please note that drivers shall <emphasis>not</emphasis> switch timings automatically +if new timings are detected. Instead, drivers should send the +<constant>V4L2_EVENT_SOURCE_CHANGE</constant> event (if they support this) and expect +that userspace will take action by calling <constant>VIDIOC_QUERY_DV_TIMINGS</constant>. +The reason is that new timings usually mean different buffer sizes as well, and you +cannot change buffer sizes on the fly. In general, applications that receive the +Source Change event will have to call <constant>VIDIOC_QUERY_DV_TIMINGS</constant>, +and if the detected timings are valid they will have to stop streaming, set the new +timings, allocate new buffers and start streaming again.</para> + +<para>If the timings could not be detected because there was no signal, then <errorcode>ENOLINK</errorcode> is returned. If a signal was detected, but it was unstable and the receiver could not lock to the signal, then <errorcode>ENOLCK</errorcode> is returned. If the receiver could lock to the signal, diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index 20fda75a012d..cd82148dedd7 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -308,6 +308,12 @@ modulator programming see fields.</entry> </row> <row> + <entry><constant>V4L2_CAP_SDR_OUTPUT</constant></entry> + <entry>0x00400000</entry> + <entry>The device supports the +<link linkend="sdr">SDR Output</link> interface.</entry> + </row> + <row> <entry><constant>V4L2_CAP_READWRITE</constant></entry> <entry>0x01000000</entry> <entry>The device supports the <link diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index 6ec39c698baf..55b7582cf314 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -101,8 +101,9 @@ prematurely end the enumeration).</para></footnote></para> next supported non-compound control, or <errorcode>EINVAL</errorcode> if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> flag can be specified to enumerate all compound controls (i.e. controls -with type ≥ <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). Specify both -<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and +with type ≥ <constant>V4L2_CTRL_COMPOUND_TYPES</constant> and/or array +control, in other words controls that contain more than one value). +Specify both <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate all controls, compound or not. Drivers which do not support these flags yet always return <errorcode>EINVAL</errorcode>.</para> @@ -422,7 +423,7 @@ the array to zero.</entry> <entry>any</entry> <entry>An integer-valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware.</entry> +values.</entry> </row> <row> <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry> @@ -518,7 +519,7 @@ Older drivers which do not support this feature return an <entry>any</entry> <entry>An unsigned 8-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware. +values. </entry> </row> <row> @@ -528,7 +529,17 @@ values which are actually different on the hardware. <entry>any</entry> <entry>An unsigned 16-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware. +values. +</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_TYPE_U32</constant></entry> + <entry>any</entry> + <entry>any</entry> + <entry>any</entry> + <entry>An unsigned 32-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values. </entry> </row> </tbody> diff --git a/Documentation/DocBook/media/v4l/vidioc-querystd.xml b/Documentation/DocBook/media/v4l/vidioc-querystd.xml index 222348542182..3ceae35fab03 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querystd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querystd.xml @@ -59,6 +59,16 @@ then the driver will return V4L2_STD_UNKNOWN. When detection is not possible or fails, the set must contain all standards supported by the current video input or output.</para> +<para>Please note that drivers shall <emphasis>not</emphasis> switch the video standard +automatically if a new video standard is detected. Instead, drivers should send the +<constant>V4L2_EVENT_SOURCE_CHANGE</constant> event (if they support this) and expect +that userspace will take action by calling <constant>VIDIOC_QUERYSTD</constant>. +The reason is that a new video standard can mean different buffer sizes as well, and you +cannot change buffer sizes on the fly. In general, applications that receive the +Source Change event will have to call <constant>VIDIOC_QUERYSTD</constant>, +and if the detected video standard is valid they will have to stop streaming, set the new +standard, allocate new buffers and start streaming again.</para> + </refsect1> <refsect1> diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index f3f5fe5b64c9..7b77e0f7b87d 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -19,10 +19,10 @@ <!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> <!-- Video for Linux mailing list address. --> -<!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>"> +<!ENTITY v4l-ml "<ulink url='https://linuxtv.org/lists.php'>https://linuxtv.org/lists.php</ulink>"> <!-- LinuxTV v4l-dvb repository. --> -<!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>"> +<!ENTITY v4l-dvb "<ulink url='https://linuxtv.org/repo/'>https://linuxtv.org/repo/</ulink>"> <!ENTITY dash-ent-8 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> <!ENTITY dash-ent-10 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> <!ENTITY dash-ent-12 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> @@ -38,7 +38,7 @@ <title>LINUX MEDIA INFRASTRUCTURE API</title> <copyright> - <year>2009-2014</year> + <year>2009-2015</year> <holder>LinuxTV Developers</holder> </copyright> @@ -91,7 +91,7 @@ components, like mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API.</para> <para>For additional information and for the latest development code, - see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> + see: <ulink url="https://linuxtv.org">https://linuxtv.org</ulink>.</para> <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> </preface> diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 7da8f0402af5..b442921bca54 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -162,12 +162,15 @@ <sect1 id="Basic_defines"> <title>Basic defines</title> <para> - At least you have to provide a mtd structure and - a storage for the ioremap'ed chip address. - You can allocate the mtd structure using kmalloc - or you can allocate it statically. - In case of static allocation you have to allocate - a nand_chip structure too. + At least you have to provide a nand_chip structure + and a storage for the ioremap'ed chip address. + You can allocate the nand_chip structure using + kmalloc or you can allocate it statically. + The NAND chip structure embeds an mtd structure + which will be registered to the MTD subsystem. + You can extract a pointer to the mtd structure + from a nand_chip pointer using the nand_to_mtd() + helper. </para> <para> Kmalloc based example @@ -180,7 +183,6 @@ static void __iomem *baseaddr; Static example </para> <programlisting> -static struct mtd_info board_mtd; static struct nand_chip board_chip; static void __iomem *baseaddr; </programlisting> @@ -235,7 +237,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) <programlisting> static void board_hwcontrol(struct mtd_info *mtd, int cmd) { - struct nand_chip *this = (struct nand_chip *) mtd->priv; + struct nand_chip *this = mtd_to_nand(mtd); switch(cmd){ case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break; case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; @@ -274,13 +276,15 @@ static int __init board_init (void) int err = 0; /* Allocate memory for MTD device structure and private data */ - board_mtd = kzalloc(sizeof(struct mtd_info) + sizeof(struct nand_chip), GFP_KERNEL); - if (!board_mtd) { + this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL); + if (!this) { printk ("Unable to allocate NAND MTD device structure.\n"); err = -ENOMEM; goto out; } + board_mtd = nand_to_mtd(this); + /* map physical address */ baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024); if (!baseaddr) { @@ -289,11 +293,6 @@ static int __init board_init (void) goto out_mtd; } - /* Get pointer to private data */ - this = (struct nand_chip *) (); - /* Link the private data with the MTD structure */ - board_mtd->priv = this; - /* Set address of NAND IO lines */ this->IO_ADDR_R = baseaddr; this->IO_ADDR_W = baseaddr; @@ -317,7 +316,7 @@ static int __init board_init (void) out_ior: iounmap(baseaddr); out_mtd: - kfree (board_mtd); + kfree (this); out: return err; } @@ -343,7 +342,7 @@ static void __exit board_cleanup (void) iounmap(baseaddr); /* Free the MTD device structure */ - kfree (board_mtd); + kfree (mtd_to_nand(board_mtd)); } module_exit(board_cleanup); #endif @@ -399,7 +398,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) <programlisting> static void board_select_chip (struct mtd_info *mtd, int chip) { - struct nand_chip *this = (struct nand_chip *) mtd->priv; + struct nand_chip *this = mtd_to_nand(mtd); /* Deselect all chips */ this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 4cd5b2cd0f3d..bc776be0f19c 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -732,6 +732,18 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param) or SET_INTERFACE. </para></warning></listitem></varlistentry> + <varlistentry><term>USBDEVFS_DROP_PRIVILEGES</term> + <listitem><para>This is used to relinquish the ability + to do certain operations which are considered to be + privileged on a usbfs file descriptor. + This includes claiming arbitrary interfaces, resetting + a device on which there are currently claimed interfaces + from other users, and issuing USBDEVFS_IOCTL calls. + The ioctl parameter is a 32 bit mask of interfaces + the user is allowed to claim on this file descriptor. + You may issue this ioctl more than one time to narrow + said mask. + </para></listitem></varlistentry> </variablelist> </sect2> diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 84ef6a90131c..a27ab9f53fb6 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -2181,10 +2181,6 @@ struct _snd_pcm_runtime { struct snd_pcm_hardware hw; struct snd_pcm_hw_constraints hw_constraints; - /* -- interrupt callbacks -- */ - void (*transfer_ack_begin)(struct snd_pcm_substream *substream); - void (*transfer_ack_end)(struct snd_pcm_substream *substream); - /* -- timer -- */ unsigned int timer_resolution; /* timer resolution */ @@ -2209,9 +2205,8 @@ struct _snd_pcm_runtime { For the operators (callbacks) of each sound driver, most of these records are supposed to be read-only. Only the PCM middle-layer changes / updates them. The exceptions are - the hardware description (hw), interrupt callbacks - (transfer_ack_xxx), DMA buffer information, and the private - data. Besides, if you use the standard buffer allocation + the hardware description (hw) DMA buffer information and the + private data. Besides, if you use the standard buffer allocation method via <function>snd_pcm_lib_malloc_pages()</function>, you don't need to set the DMA buffer information by yourself. </para> @@ -2538,16 +2533,6 @@ struct _snd_pcm_runtime { </para> </section> - <section id="pcm-interface-runtime-intr"> - <title>Interrupt Callbacks</title> - <para> - The field <structfield>transfer_ack_begin</structfield> and - <structfield>transfer_ack_end</structfield> are called at - the beginning and at the end of - <function>snd_pcm_period_elapsed()</function>, respectively. - </para> - </section> - </section> <section id="pcm-interface-operators"> diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 21152d397b88..1f345da28ec5 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -68,7 +68,7 @@ For common questions and answers about the GPL, please see: Documentation ------------- +------------- The Linux kernel source tree has a large range of documents that are invaluable for learning how to interact with the kernel community. When @@ -187,7 +187,7 @@ apply a patch. If you do not know where you want to start, but you want to look for some task to start doing to join into the kernel development community, go to the Linux Kernel Janitor's project: - http://kernelnewbies.org/KernelJanitors + http://kernelnewbies.org/KernelJanitors It is a great place to start. It describes a list of relatively simple problems that need to be cleaned up and fixed within the Linux kernel source tree. Working with the developers in charge of this project, you @@ -209,7 +209,7 @@ tools. One such tool that is particularly recommended is the Linux Cross-Reference project, which is able to present source code in a self-referential, indexed webpage format. An excellent up-to-date repository of the kernel code may be found at: - http://lxr.linux.no/+trees + http://lxr.free-electrons.com/ The development process @@ -250,11 +250,6 @@ process is as follows: release a new -rc kernel every week. - Process continues until the kernel is considered "ready", the process should last around 6 weeks. - - Known regressions in each release are periodically posted to the - linux-kernel mailing list. The goal is to reduce the length of - that list to zero before declaring the kernel to be "ready," but, in - the real world, a small number of regressions often remain at - release time. It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases: @@ -263,7 +258,7 @@ mailing list about kernel releases: preconceived timeline." 4.x.y -stable kernel tree ---------------------------- +------------------------- Kernels with 3-part versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant regressions discovered in a given 4.x kernel. @@ -286,7 +281,7 @@ documents what kinds of changes are acceptable for the -stable tree, and how the release process works. 4.x -git patches ------------------- +---------------- These are daily snapshots of Linus' kernel tree which are managed in a git repository (hence the name.) These patches are usually released daily and represent the current state of Linus' tree. They are more @@ -318,7 +313,7 @@ accepted, or rejected. Most of these patchwork sites are listed at http://patchwork.kernel.org/. 4.x -next kernel tree for integration tests ---------------------------------------------- +------------------------------------------- Before updates from subsystem trees are merged into the mainline 4.x tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index 31d1d658827f..c0d8788e75d3 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -587,7 +587,7 @@ used to control it: modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type> preaction=<preaction type> preop=<preop type> start_now=x - nowayout=x ifnum_to_use=n + nowayout=x ifnum_to_use=n panic_wdt_timeout=<t> ifnum_to_use specifies which interface the watchdog timer should use. The default is -1, which means to pick the first one registered. @@ -597,7 +597,9 @@ is the amount of seconds before the reset that the pre-timeout panic will occur (if pretimeout is zero, then pretimeout will not be enabled). Note that the pretimeout is the time before the final timeout. So if the timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout -will occur in 40 second (10 seconds before the timeout). +will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout +is the value of timeout which is set on kernel panic, in order to let actions +such as kdump to occur during panic. The action may be "reset", "power_cycle", or "power_off", and specifies what to do when the timer times out, and defaults to @@ -634,6 +636,7 @@ for configuring the watchdog: ipmi_watchdog.preop=<preop type> ipmi_watchdog.start_now=x ipmi_watchdog.nowayout=x + ipmi_watchdog.panic_wdt_timeout=<t> The options are the same as the module parameter options. diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt index 3a8e15cba816..8d990bde8693 100644 --- a/Documentation/IRQ-domain.txt +++ b/Documentation/IRQ-domain.txt @@ -32,9 +32,9 @@ top of the irq_alloc_desc*() API. An irq_domain to manage mapping is preferred over interrupt controller drivers open coding their own reverse mapping scheme. -irq_domain also implements translation from Device Tree interrupt -specifiers to hwirq numbers, and can be easily extended to support -other IRQ topology data sources. +irq_domain also implements translation from an abstract irq_fwspec +structure to hwirq numbers (Device Tree and ACPI GSI so far), and can +be easily extended to support other IRQ topology data sources. === irq_domain usage === An interrupt controller driver creates and registers an irq_domain by @@ -184,7 +184,7 @@ There are four major interfaces to use hierarchy irq_domain: related resources associated with these interrupts. 3) irq_domain_activate_irq(): activate interrupt controller hardware to deliver the interrupt. -3) irq_domain_deactivate_irq(): deactivate interrupt controller hardware +4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware to stop delivering the interrupt. Following changes are needed to support hierarchy irq_domain. diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt index 7b57fc087088..49585b6e1ea2 100644 --- a/Documentation/Intel-IOMMU.txt +++ b/Documentation/Intel-IOMMU.txt @@ -3,7 +3,7 @@ Linux IOMMU Support The architecture spec can be obtained from the below location. -http://www.intel.com/technology/virtualization/ +http://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/vt-directed-io-spec.pdf This guide gives a quick cheat sheet for some basic understanding. diff --git a/Documentation/Makefile b/Documentation/Makefile index bc0548201755..1207d7907650 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,4 +1,4 @@ subdir-y := accounting auxdisplay blackfin connector \ filesystems filesystems ia64 laptops mic misc-devices \ - networking pcmcia prctl ptp spi timers vDSO video4linux \ + networking pcmcia prctl ptp timers vDSO video4linux \ watchdog diff --git a/Documentation/RCU/Design/Requirements/2013-08-is-it-dead.png b/Documentation/RCU/Design/Requirements/2013-08-is-it-dead.png Binary files differnew file mode 100644 index 000000000000..7496a55e4e7b --- /dev/null +++ b/Documentation/RCU/Design/Requirements/2013-08-is-it-dead.png diff --git a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg new file mode 100644 index 000000000000..4b4014fda770 --- /dev/null +++ b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg @@ -0,0 +1,374 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="447.99197" + height="428.19299" + id="svg2" + version="1.1" + inkscape:version="0.48.3.1 r9886" + sodipodi:docname="GPpartitionReaders1.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3792" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lstart" + style="overflow:visible"> + <path + id="path3789" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(1.1,0,0,1.1,1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.6184291" + inkscape:cx="223.99599" + inkscape:cy="214.0965" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="979" + inkscape:window-height="836" + inkscape:window-x="571" + inkscape:window-y="335" + inkscape:window-maximized="0" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-28.441125,-185.60612)"> + <flowRoot + xml:space="preserve" + id="flowRoot2985" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + id="flowRegion2987"><rect + id="rect2989" + width="82.85714" + height="11.428572" + x="240" + y="492.36218" /></flowRegion><flowPara + id="flowPara2991"></flowPara></flowRoot> <g + id="g4433" + transform="translate(2,0)"> + <text + sodipodi:linespacing="125%" + id="text2993" + y="-261.66608" + x="412.12299" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + xml:space="preserve" + transform="matrix(0,1,-1,0,0,0)"><tspan + y="-261.66608" + x="412.12299" + id="tspan2995" + sodipodi:role="line">synchronize_rcu()</tspan></text> + <g + id="g4417" + transform="matrix(0,1,-1,0,730.90257,222.4928)"> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)" + d="m 97.580736,477.4048 183.140664,0" + id="path2997" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 96.752718,465.38398 0,22.62742" + id="path4397" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 281.54942,465.38397 0,22.62742" + id="path4397-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + </g> + </g> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="268.18076" + id="text4429" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431" + x="112.04738" + y="268.18076">WRITE_ONCE(a, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="439.13766" + id="text4441" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4443" + x="112.04738" + y="439.13766">WRITE_ONCE(b, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.60869" + y="309.29346" + id="text4445" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4447" + x="255.60869" + y="309.29346">r1 = READ_ONCE(a);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.14423" + y="520.61786" + id="text4449" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4451" + x="255.14423" + y="520.61786">WRITE_ONCE(c, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="384.71124" + id="text4453" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4455" + x="396.10254" + y="384.71124">r2 = READ_ONCE(b);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="582.13617" + id="text4457" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4459" + x="396.10254" + y="582.13617">r3 = READ_ONCE(c);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.08231" + y="213.91006" + id="text4461" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463" + x="112.08231" + y="213.91006">thread0()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="252.34512" + y="213.91006" + id="text4461-6" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-0" + x="252.34512" + y="213.91006">thread1()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.42557" + y="213.91006" + id="text4461-2" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-2" + x="396.42557" + y="213.91006">thread2()</tspan></text> + <rect + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="rect4495" + width="436.28488" + height="416.4859" + x="34.648232" + y="191.10612" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 183.14066,191.10612 0,417.193 -0.70711,0" + id="path4497" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 325.13867,191.10612 0,417.193 -0.70711,0" + id="path4497-5" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="111.75929" + y="251.53981" + id="text4429-8" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9" + x="111.75929" + y="251.53981">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="367.91556" + id="text4429-8-9" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4" + x="396.10254" + y="367.91556">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="597.40289" + id="text4429-8-9-3" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4" + x="396.10254" + y="597.40289">rcu_read_unlock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="111.75929" + y="453.15311" + id="text4429-8-9-3-1" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4-6" + x="111.75929" + y="453.15311">rcu_read_unlock();</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 33.941125,227.87568 436.284885,0 0,0.7071" + id="path4608" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="394.94427" + y="345.66351" + id="text4648" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650" + x="394.94427" + y="345.66351">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(36.441125,199.60612)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.11968" + y="475.77856" + id="text4648-4" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4" + x="112.11968" + y="475.77856">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-246.38346,329.72117)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <path + sodipodi:type="arc" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7-7" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-103.65246,202.90878)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="254.85066" + y="348.96619" + id="text4648-4-3" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4-5" + x="254.85066" + y="348.96619">QS</tspan></text> + </g> +</svg> diff --git a/Documentation/RCU/Design/Requirements/RCUApplicability.svg b/Documentation/RCU/Design/Requirements/RCUApplicability.svg new file mode 100644 index 000000000000..ebcbeee391ed --- /dev/null +++ b/Documentation/RCU/Design/Requirements/RCUApplicability.svg @@ -0,0 +1,237 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5d --> + +<!-- CreationDate: Tue Mar 4 18:34:25 2014 --> + +<!-- Magnification: 3.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="1089.1382" + height="668.21368" + viewBox="-2121 -36 14554.634 8876.4061" + id="svg2" + version="1.1" + inkscape:version="0.48.3.1 r9886" + sodipodi:docname="RCUApplicability.svg"> + <metadata + id="metadata40"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs38" /> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="849" + inkscape:window-height="639" + id="namedview36" + showgrid="false" + inkscape:zoom="0.51326165" + inkscape:cx="544.56912" + inkscape:cy="334.10686" + inkscape:window-x="149" + inkscape:window-y="448" + inkscape:window-maximized="0" + inkscape:current-layer="g4" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" /> + <g + style="fill:none;stroke-width:0.025in" + id="g4" + transform="translate(-2043.6828,14.791398)"> + <!-- Line: box --> + <rect + x="0" + y="0" + width="14400" + height="8775" + rx="0" + style="fill:#ffa1a1;stroke:#000000;stroke-width:21;stroke-linecap:butt;stroke-linejoin:miter" + id="rect6" /> + <!-- Line: box --> + <rect + x="1350" + y="0" + width="11700" + height="6075" + rx="0" + style="fill:#ffff00;stroke:#000000;stroke-width:21;stroke-linecap:butt;stroke-linejoin:miter" + id="rect8" /> + <!-- Line: box --> + <rect + x="2700" + y="0" + width="9000" + height="4275" + rx="0" + style="fill:#00ff00;stroke:#000000;stroke-width:21;stroke-linecap:butt;stroke-linejoin:miter" + id="rect10" /> + <!-- Line: box --> + <rect + x="4050" + y="0" + width="6300" + height="2475" + rx="0" + style="fill:#87cfff;stroke:#000000;stroke-width:21;stroke-linecap:butt;stroke-linejoin:miter" + id="rect12" /> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="900" + font-style="normal" + font-weight="normal" + font-size="324" + id="text14" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3017">Read-Mostly, Stale &</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="1350" + font-style="normal" + font-weight="normal" + font-size="324" + id="text16" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3019">Inconsistent Data OK</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="1800" + font-style="normal" + font-weight="normal" + font-size="324" + id="text18" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3021">(RCU Works Great!!!)</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="3825" + font-style="normal" + font-weight="normal" + font-size="324" + id="text20" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3023">(RCU Works Well)</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="3375" + font-style="normal" + font-weight="normal" + font-size="324" + id="text22" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3025">Read-Mostly, Need Consistent Data</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="5175" + font-style="normal" + font-weight="normal" + font-size="324" + id="text24" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3027">Read-Write, Need Consistent Data</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="6975" + font-style="normal" + font-weight="normal" + font-size="324" + id="text26" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + sodipodi:linespacing="125%">Update-Mostly, Need Consistent Data</text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="5625" + font-style="normal" + font-weight="normal" + font-size="324" + id="text28" + sodipodi:linespacing="125%" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L"><tspan + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + id="tspan3029">(RCU Might Be OK...)</tspan></text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="7875" + font-style="normal" + font-weight="normal" + font-size="324" + id="text30" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + sodipodi:linespacing="125%">(1) Provide Existence Guarantees For Update-Friendly Mechanisms</text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="8325" + font-style="normal" + font-weight="normal" + font-size="324" + id="text32" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + sodipodi:linespacing="125%">(2) Provide Wait-Free Read-Side Primitives for Real-Time Use)</text> + <!-- Text --> + <text + xml:space="preserve" + x="7200" + y="7425" + font-style="normal" + font-weight="normal" + font-size="324" + id="text34" + style="font-size:427.63009644px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;font-family:Nimbus Sans L;-inkscape-font-specification:Nimbus Sans L" + sodipodi:linespacing="125%">(RCU is Very Unlikely to be the Right Tool For The Job, But it Can:</text> + </g> +</svg> diff --git a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg new file mode 100644 index 000000000000..48cd1623d4d4 --- /dev/null +++ b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg @@ -0,0 +1,639 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="735.25" + height="516.21875" + id="svg2" + version="1.1" + inkscape:version="0.48.3.1 r9886" + sodipodi:docname="ReadersPartitionGP1.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3792" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lstart" + style="overflow:visible"> + <path + id="path3789" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(1.1,0,0,1.1,1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lstart-4" + style="overflow:visible"> + <path + id="path3789-9" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(1.1,0,0,1.1,1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend-4" + style="overflow:visible"> + <path + id="path3792-4" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.3670394" + inkscape:cx="367.26465" + inkscape:cy="258.46182" + inkscape:document-units="px" + inkscape:current-layer="g4433-6" + showgrid="false" + inkscape:window-width="1351" + inkscape:window-height="836" + inkscape:window-x="438" + inkscape:window-y="335" + inkscape:window-maximized="0" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-29.15625,-185.59375)"> + <flowRoot + xml:space="preserve" + id="flowRoot2985" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + id="flowRegion2987"><rect + id="rect2989" + width="82.85714" + height="11.428572" + x="240" + y="492.36218" /></flowRegion><flowPara + id="flowPara2991" /></flowRoot> <g + id="g4433" + transform="translate(2,-12)"> + <text + sodipodi:linespacing="125%" + id="text2993" + y="-261.66608" + x="436.12299" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + xml:space="preserve" + transform="matrix(0,1,-1,0,0,0)"><tspan + y="-261.66608" + x="436.12299" + id="tspan2995" + sodipodi:role="line">synchronize_rcu()</tspan></text> + <g + id="g4417" + transform="matrix(0,1,-1,0,730.90257,222.4928)"> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)" + d="M 97.580736,477.4048 327.57913,476.09759" + id="path2997" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 96.752718,465.38398 0,22.62742" + id="path4397" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 328.40703,465.38397 0,22.62742" + id="path4397-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + </g> + </g> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="268.18076" + id="text4429" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431" + x="112.04738" + y="268.18076">WRITE_ONCE(a, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="487.13766" + id="text4441" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4443" + x="112.04738" + y="487.13766">WRITE_ONCE(b, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.60869" + y="297.29346" + id="text4445" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4447" + x="255.60869" + y="297.29346">r1 = READ_ONCE(a);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.14423" + y="554.61786" + id="text4449" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4451" + x="255.14423" + y="554.61786">WRITE_ONCE(c, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="370.71124" + id="text4453" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4455" + x="396.10254" + y="370.71124">WRITE_ONCE(d, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="572.13617" + id="text4457" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4459" + x="396.10254" + y="572.13617">r2 = READ_ONCE(c);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.08231" + y="213.91006" + id="text4461" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463" + x="112.08231" + y="213.91006">thread0()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="252.34512" + y="213.91006" + id="text4461-6" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-0" + x="252.34512" + y="213.91006">thread1()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.42557" + y="213.91006" + id="text4461-2" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-2" + x="396.42557" + y="213.91006">thread2()</tspan></text> + <rect + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="rect4495" + width="724.25244" + height="505.21201" + x="34.648232" + y="191.10612" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 183.14066,191.10612 0,504.24243" + id="path4497" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 325.13867,191.10612 0,504.24243" + id="path4497-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="111.75929" + y="251.53981" + id="text4429-8" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9" + x="111.75929" + y="251.53981">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="353.91556" + id="text4429-8-9" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4" + x="396.10254" + y="353.91556">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="587.40289" + id="text4429-8-9-3" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4" + x="396.10254" + y="587.40289">rcu_read_unlock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="111.75929" + y="501.15311" + id="text4429-8-9-3-1" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4-6" + x="111.75929" + y="501.15311">rcu_read_unlock();</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 33.941125,227.87568 724.941765,0" + id="path4608" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="394.94427" + y="331.66351" + id="text4648" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650" + x="394.94427" + y="331.66351">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(36.441125,185.60612)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.11968" + y="523.77856" + id="text4648-4" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4" + x="112.11968" + y="523.77856">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-246.38346,377.72117)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <path + sodipodi:type="arc" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7-7" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-103.65246,190.90878)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="254.85066" + y="336.96619" + id="text4648-4-3" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4-5" + x="254.85066" + y="336.96619">QS</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 470.93311,190.39903 0,504.24243" + id="path4497-5-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 616.22755,190.38323 0,504.24243" + id="path4497-5-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <g + id="g4433-6" + transform="translate(288.0964,78.32827)"> + <text + sodipodi:linespacing="125%" + id="text2993-7" + y="-261.66608" + x="440.12299" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + xml:space="preserve" + transform="matrix(0,1,-1,0,0,0)"><tspan + y="-261.66608" + x="440.12299" + id="tspan2995-1" + sodipodi:role="line">synchronize_rcu()</tspan></text> + <g + id="g4417-1" + transform="matrix(0,1,-1,0,730.90257,222.4928)"> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)" + d="M 97.580736,477.4048 328.5624,477.07246" + id="path2997-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 96.752718,465.38398 0,22.62742" + id="path4397-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 329.39039,465.38397 0,22.62742" + id="path4397-5-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + </g> + </g> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="541.70508" + y="387.6217" + id="text4445-0" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4447-5" + x="541.70508" + y="387.6217">r3 = READ_ONCE(d);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="541.2406" + y="646.94611" + id="text4449-6" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4451-6" + x="541.2406" + y="646.94611">WRITE_ONCE(e, 1);</tspan></text> + <path + sodipodi:type="arc" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7-7-5" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(182.44393,281.23704)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="540.94702" + y="427.29443" + id="text4648-4-3-1" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4-5-7" + x="540.94702" + y="427.29443">QS</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="686.27747" + y="461.83929" + id="text4453-7" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4455-1" + x="686.27747" + y="461.83929">r4 = READ_ONCE(b);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="686.27747" + y="669.26422" + id="text4457-9" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4459-2" + x="686.27747" + y="669.26422">r5 = READ_ONCE(e);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="686.27747" + y="445.04358" + id="text4429-8-9-33" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-2" + x="686.27747" + y="445.04358">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="686.27747" + y="684.53094" + id="text4429-8-9-3-8" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4-5" + x="686.27747" + y="684.53094">rcu_read_unlock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="685.11914" + y="422.79153" + id="text4648-9" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-7" + x="685.11914" + y="422.79153">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-8" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(326.61602,276.73415)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="397.85934" + y="609.59003" + id="text4648-5" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-77" + x="397.85934" + y="609.59003">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-80" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(39.356201,463.53264)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="256.75986" + y="586.99133" + id="text4648-5-2" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-77-7" + x="256.75986" + y="586.99133">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-80-5" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-101.74328,440.93395)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="546.22791" + y="213.91006" + id="text4461-2-5" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-2-6" + x="546.22791" + y="213.91006">thread3()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="684.00067" + y="213.91006" + id="text4461-2-1" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-2-0" + x="684.00067" + y="213.91006">thread4()</tspan></text> + </g> +</svg> diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html new file mode 100644 index 000000000000..a725f9900ec8 --- /dev/null +++ b/Documentation/RCU/Design/Requirements/Requirements.html @@ -0,0 +1,2897 @@ +<!-- DO NOT HAND EDIT. --> +<!-- Instead, edit Documentation/RCU/Design/Requirements/Requirements.htmlx and run 'sh htmlqqz.sh Documentation/RCU/Design/Requirements/Requirements' --> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + <html> + <head><title>A Tour Through RCU's Requirements [LWN.net]</title> + <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8"> + +<h1>A Tour Through RCU's Requirements</h1> + +<p>Copyright IBM Corporation, 2015</p> +<p>Author: Paul E. McKenney</p> +<p><i>The initial version of this document appeared in the +<a href="https://lwn.net/">LWN</a> articles +<a href="https://lwn.net/Articles/652156/">here</a>, +<a href="https://lwn.net/Articles/652677/">here</a>, and +<a href="https://lwn.net/Articles/653326/">here</a>.</i></p> + +<h2>Introduction</h2> + +<p> +Read-copy update (RCU) is a synchronization mechanism that is often +used as a replacement for reader-writer locking. +RCU is unusual in that updaters do not block readers, +which means that RCU's read-side primitives can be exceedingly fast +and scalable. +In addition, updaters can make useful forward progress concurrently +with readers. +However, all this concurrency between RCU readers and updaters does raise +the question of exactly what RCU readers are doing, which in turn +raises the question of exactly what RCU's requirements are. + +<p> +This document therefore summarizes RCU's requirements, and can be thought +of as an informal, high-level specification for RCU. +It is important to understand that RCU's specification is primarily +empirical in nature; +in fact, I learned about many of these requirements the hard way. +This situation might cause some consternation, however, not only +has this learning process been a lot of fun, but it has also been +a great privilege to work with so many people willing to apply +technologies in interesting new ways. + +<p> +All that aside, here are the categories of currently known RCU requirements: +</p> + +<ol> +<li> <a href="#Fundamental Requirements"> + Fundamental Requirements</a> +<li> <a href="#Fundamental Non-Requirements">Fundamental Non-Requirements</a> +<li> <a href="#Parallelism Facts of Life"> + Parallelism Facts of Life</a> +<li> <a href="#Quality-of-Implementation Requirements"> + Quality-of-Implementation Requirements</a> +<li> <a href="#Linux Kernel Complications"> + Linux Kernel Complications</a> +<li> <a href="#Software-Engineering Requirements"> + Software-Engineering Requirements</a> +<li> <a href="#Other RCU Flavors"> + Other RCU Flavors</a> +<li> <a href="#Possible Future Changes"> + Possible Future Changes</a> +</ol> + +<p> +This is followed by a <a href="#Summary">summary</a>, +which is in turn followed by the inevitable +<a href="#Answers to Quick Quizzes">answers to the quick quizzes</a>. + +<h2><a name="Fundamental Requirements">Fundamental Requirements</a></h2> + +<p> +RCU's fundamental requirements are the closest thing RCU has to hard +mathematical requirements. +These are: + +<ol> +<li> <a href="#Grace-Period Guarantee"> + Grace-Period Guarantee</a> +<li> <a href="#Publish-Subscribe Guarantee"> + Publish-Subscribe Guarantee</a> +<li> <a href="#Memory-Barrier Guarantees"> + Memory-Barrier Guarantees</a> +<li> <a href="#RCU Primitives Guaranteed to Execute Unconditionally"> + RCU Primitives Guaranteed to Execute Unconditionally</a> +<li> <a href="#Guaranteed Read-to-Write Upgrade"> + Guaranteed Read-to-Write Upgrade</a> +</ol> + +<h3><a name="Grace-Period Guarantee">Grace-Period Guarantee</a></h3> + +<p> +RCU's grace-period guarantee is unusual in being premeditated: +Jack Slingwine and I had this guarantee firmly in mind when we started +work on RCU (then called “rclock”) in the early 1990s. +That said, the past two decades of experience with RCU have produced +a much more detailed understanding of this guarantee. + +<p> +RCU's grace-period guarantee allows updaters to wait for the completion +of all pre-existing RCU read-side critical sections. +An RCU read-side critical section +begins with the marker <tt>rcu_read_lock()</tt> and ends with +the marker <tt>rcu_read_unlock()</tt>. +These markers may be nested, and RCU treats a nested set as one +big RCU read-side critical section. +Production-quality implementations of <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> are extremely lightweight, and in +fact have exactly zero overhead in Linux kernels built for production +use with <tt>CONFIG_PREEMPT=n</tt>. + +<p> +This guarantee allows ordering to be enforced with extremely low +overhead to readers, for example: + +<blockquote> +<pre> + 1 int x, y; + 2 + 3 void thread0(void) + 4 { + 5 rcu_read_lock(); + 6 r1 = READ_ONCE(x); + 7 r2 = READ_ONCE(y); + 8 rcu_read_unlock(); + 9 } +10 +11 void thread1(void) +12 { +13 WRITE_ONCE(x, 1); +14 synchronize_rcu(); +15 WRITE_ONCE(y, 1); +16 } +</pre> +</blockquote> + +<p> +Because the <tt>synchronize_rcu()</tt> on line 14 waits for +all pre-existing readers, any instance of <tt>thread0()</tt> that +loads a value of zero from <tt>x</tt> must complete before +<tt>thread1()</tt> stores to <tt>y</tt>, so that instance must +also load a value of zero from <tt>y</tt>. +Similarly, any instance of <tt>thread0()</tt> that loads a value of +one from <tt>y</tt> must have started after the +<tt>synchronize_rcu()</tt> started, and must therefore also load +a value of one from <tt>x</tt>. +Therefore, the outcome: +<blockquote> +<pre> +(r1 == 0 && r2 == 1) +</pre> +</blockquote> +cannot happen. + +<p><a name="Quick Quiz 1"><b>Quick Quiz 1</b>:</a> +Wait a minute! +You said that updaters can make useful forward progress concurrently +with readers, but pre-existing readers will block +<tt>synchronize_rcu()</tt>!!! +Just who are you trying to fool??? +<br><a href="#qq1answer">Answer</a> + +<p> +This scenario resembles one of the first uses of RCU in +<a href="https://en.wikipedia.org/wiki/DYNIX">DYNIX/ptx</a>, +which managed a distributed lock manager's transition into +a state suitable for handling recovery from node failure, +more or less as follows: + +<blockquote> +<pre> + 1 #define STATE_NORMAL 0 + 2 #define STATE_WANT_RECOVERY 1 + 3 #define STATE_RECOVERING 2 + 4 #define STATE_WANT_NORMAL 3 + 5 + 6 int state = STATE_NORMAL; + 7 + 8 void do_something_dlm(void) + 9 { +10 int state_snap; +11 +12 rcu_read_lock(); +13 state_snap = READ_ONCE(state); +14 if (state_snap == STATE_NORMAL) +15 do_something(); +16 else +17 do_something_carefully(); +18 rcu_read_unlock(); +19 } +20 +21 void start_recovery(void) +22 { +23 WRITE_ONCE(state, STATE_WANT_RECOVERY); +24 synchronize_rcu(); +25 WRITE_ONCE(state, STATE_RECOVERING); +26 recovery(); +27 WRITE_ONCE(state, STATE_WANT_NORMAL); +28 synchronize_rcu(); +29 WRITE_ONCE(state, STATE_NORMAL); +30 } +</pre> +</blockquote> + +<p> +The RCU read-side critical section in <tt>do_something_dlm()</tt> +works with the <tt>synchronize_rcu()</tt> in <tt>start_recovery()</tt> +to guarantee that <tt>do_something()</tt> never runs concurrently +with <tt>recovery()</tt>, but with little or no synchronization +overhead in <tt>do_something_dlm()</tt>. + +<p><a name="Quick Quiz 2"><b>Quick Quiz 2</b>:</a> +Why is the <tt>synchronize_rcu()</tt> on line 28 needed? +<br><a href="#qq2answer">Answer</a> + +<p> +In order to avoid fatal problems such as deadlocks, +an RCU read-side critical section must not contain calls to +<tt>synchronize_rcu()</tt>. +Similarly, an RCU read-side critical section must not +contain anything that waits, directly or indirectly, on completion of +an invocation of <tt>synchronize_rcu()</tt>. + +<p> +Although RCU's grace-period guarantee is useful in and of itself, with +<a href="https://lwn.net/Articles/573497/">quite a few use cases</a>, +it would be good to be able to use RCU to coordinate read-side +access to linked data structures. +For this, the grace-period guarantee is not sufficient, as can +be seen in function <tt>add_gp_buggy()</tt> below. +We will look at the reader's code later, but in the meantime, just think of +the reader as locklessly picking up the <tt>gp</tt> pointer, +and, if the value loaded is non-<tt>NULL</tt>, locklessly accessing the +<tt>->a</tt> and <tt>->b</tt> fields. + +<blockquote> +<pre> + 1 bool add_gp_buggy(int a, int b) + 2 { + 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 4 if (!p) + 5 return -ENOMEM; + 6 spin_lock(&gp_lock); + 7 if (rcu_access_pointer(gp)) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +11 p->a = a; +12 p->b = a; +13 gp = p; /* ORDERING BUG */ +14 spin_unlock(&gp_lock); +15 return true; +16 } +</pre> +</blockquote> + +<p> +The problem is that both the compiler and weakly ordered CPUs are within +their rights to reorder this code as follows: + +<blockquote> +<pre> + 1 bool add_gp_buggy_optimized(int a, int b) + 2 { + 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 4 if (!p) + 5 return -ENOMEM; + 6 spin_lock(&gp_lock); + 7 if (rcu_access_pointer(gp)) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +<b>11 gp = p; /* ORDERING BUG */ +12 p->a = a; +13 p->b = a;</b> +14 spin_unlock(&gp_lock); +15 return true; +16 } +</pre> +</blockquote> + +<p> +If an RCU reader fetches <tt>gp</tt> just after +<tt>add_gp_buggy_optimized</tt> executes line 11, +it will see garbage in the <tt>->a</tt> and <tt>->b</tt> +fields. +And this is but one of many ways in which compiler and hardware optimizations +could cause trouble. +Therefore, we clearly need some way to prevent the compiler and the CPU from +reordering in this manner, which brings us to the publish-subscribe +guarantee discussed in the next section. + +<h3><a name="Publish-Subscribe Guarantee">Publish/Subscribe Guarantee</a></h3> + +<p> +RCU's publish-subscribe guarantee allows data to be inserted +into a linked data structure without disrupting RCU readers. +The updater uses <tt>rcu_assign_pointer()</tt> to insert the +new data, and readers use <tt>rcu_dereference()</tt> to +access data, whether new or old. +The following shows an example of insertion: + +<blockquote> +<pre> + 1 bool add_gp(int a, int b) + 2 { + 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 4 if (!p) + 5 return -ENOMEM; + 6 spin_lock(&gp_lock); + 7 if (rcu_access_pointer(gp)) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +11 p->a = a; +12 p->b = a; +13 rcu_assign_pointer(gp, p); +14 spin_unlock(&gp_lock); +15 return true; +16 } +</pre> +</blockquote> + +<p> +The <tt>rcu_assign_pointer()</tt> on line 13 is conceptually +equivalent to a simple assignment statement, but also guarantees +that its assignment will +happen after the two assignments in lines 11 and 12, +similar to the C11 <tt>memory_order_release</tt> store operation. +It also prevents any number of “interesting” compiler +optimizations, for example, the use of <tt>gp</tt> as a scratch +location immediately preceding the assignment. + +<p><a name="Quick Quiz 3"><b>Quick Quiz 3</b>:</a> +But <tt>rcu_assign_pointer()</tt> does nothing to prevent the +two assignments to <tt>p->a</tt> and <tt>p->b</tt> +from being reordered. +Can't that also cause problems? +<br><a href="#qq3answer">Answer</a> + +<p> +It is tempting to assume that the reader need not do anything special +to control its accesses to the RCU-protected data, +as shown in <tt>do_something_gp_buggy()</tt> below: + +<blockquote> +<pre> + 1 bool do_something_gp_buggy(void) + 2 { + 3 rcu_read_lock(); + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */ + 5 if (p) { + 6 do_something(p->a, p->b); + 7 rcu_read_unlock(); + 8 return true; + 9 } +10 rcu_read_unlock(); +11 return false; +12 } +</pre> +</blockquote> + +<p> +However, this temptation must be resisted because there are a +surprisingly large number of ways that the compiler +(to say nothing of +<a href="https://h71000.www7.hp.com/wizard/wiz_2637.html">DEC Alpha CPUs</a>) +can trip this code up. +For but one example, if the compiler were short of registers, it +might choose to refetch from <tt>gp</tt> rather than keeping +a separate copy in <tt>p</tt> as follows: + +<blockquote> +<pre> + 1 bool do_something_gp_buggy_optimized(void) + 2 { + 3 rcu_read_lock(); + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */ +<b> 5 do_something(gp->a, gp->b);</b> + 6 rcu_read_unlock(); + 7 return true; + 8 } + 9 rcu_read_unlock(); +10 return false; +11 } +</pre> +</blockquote> + +<p> +If this function ran concurrently with a series of updates that +replaced the current structure with a new one, +the fetches of <tt>gp->a</tt> +and <tt>gp->b</tt> might well come from two different structures, +which could cause serious confusion. +To prevent this (and much else besides), <tt>do_something_gp()</tt> uses +<tt>rcu_dereference()</tt> to fetch from <tt>gp</tt>: + +<blockquote> +<pre> + 1 bool do_something_gp(void) + 2 { + 3 rcu_read_lock(); + 4 p = rcu_dereference(gp); + 5 if (p) { + 6 do_something(p->a, p->b); + 7 rcu_read_unlock(); + 8 return true; + 9 } +10 rcu_read_unlock(); +11 return false; +12 } +</pre> +</blockquote> + +<p> +The <tt>rcu_dereference()</tt> uses volatile casts and (for DEC Alpha) +memory barriers in the Linux kernel. +Should a +<a href="http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf">high-quality implementation of C11 <tt>memory_order_consume</tt> [PDF]</a> +ever appear, then <tt>rcu_dereference()</tt> could be implemented +as a <tt>memory_order_consume</tt> load. +Regardless of the exact implementation, a pointer fetched by +<tt>rcu_dereference()</tt> may not be used outside of the +outermost RCU read-side critical section containing that +<tt>rcu_dereference()</tt>, unless protection of +the corresponding data element has been passed from RCU to some +other synchronization mechanism, most commonly locking or +<a href="https://www.kernel.org/doc/Documentation/RCU/rcuref.txt">reference counting</a>. + +<p> +In short, updaters use <tt>rcu_assign_pointer()</tt> and readers +use <tt>rcu_dereference()</tt>, and these two RCU API elements +work together to ensure that readers have a consistent view of +newly added data elements. + +<p> +Of course, it is also necessary to remove elements from RCU-protected +data structures, for example, using the following process: + +<ol> +<li> Remove the data element from the enclosing structure. +<li> Wait for all pre-existing RCU read-side critical sections + to complete (because only pre-existing readers can possibly have + a reference to the newly removed data element). +<li> At this point, only the updater has a reference to the + newly removed data element, so it can safely reclaim + the data element, for example, by passing it to <tt>kfree()</tt>. +</ol> + +This process is implemented by <tt>remove_gp_synchronous()</tt>: + +<blockquote> +<pre> + 1 bool remove_gp_synchronous(void) + 2 { + 3 struct foo *p; + 4 + 5 spin_lock(&gp_lock); + 6 p = rcu_access_pointer(gp); + 7 if (!p) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +11 rcu_assign_pointer(gp, NULL); +12 spin_unlock(&gp_lock); +13 synchronize_rcu(); +14 kfree(p); +15 return true; +16 } +</pre> +</blockquote> + +<p> +This function is straightforward, with line 13 waiting for a grace +period before line 14 frees the old data element. +This waiting ensures that readers will reach line 7 of +<tt>do_something_gp()</tt> before the data element referenced by +<tt>p</tt> is freed. +The <tt>rcu_access_pointer()</tt> on line 6 is similar to +<tt>rcu_dereference()</tt>, except that: + +<ol> +<li> The value returned by <tt>rcu_access_pointer()</tt> + cannot be dereferenced. + If you want to access the value pointed to as well as + the pointer itself, use <tt>rcu_dereference()</tt> + instead of <tt>rcu_access_pointer()</tt>. +<li> The call to <tt>rcu_access_pointer()</tt> need not be + protected. + In contrast, <tt>rcu_dereference()</tt> must either be + within an RCU read-side critical section or in a code + segment where the pointer cannot change, for example, in + code protected by the corresponding update-side lock. +</ol> + +<p><a name="Quick Quiz 4"><b>Quick Quiz 4</b>:</a> +Without the <tt>rcu_dereference()</tt> or the +<tt>rcu_access_pointer()</tt>, what destructive optimizations +might the compiler make use of? +<br><a href="#qq4answer">Answer</a> + +<p> +In short, RCU's publish-subscribe guarantee is provided by the combination +of <tt>rcu_assign_pointer()</tt> and <tt>rcu_dereference()</tt>. +This guarantee allows data elements to be safely added to RCU-protected +linked data structures without disrupting RCU readers. +This guarantee can be used in combination with the grace-period +guarantee to also allow data elements to be removed from RCU-protected +linked data structures, again without disrupting RCU readers. + +<p> +This guarantee was only partially premeditated. +DYNIX/ptx used an explicit memory barrier for publication, but had nothing +resembling <tt>rcu_dereference()</tt> for subscription, nor did it +have anything resembling the <tt>smp_read_barrier_depends()</tt> +that was later subsumed into <tt>rcu_dereference()</tt>. +The need for these operations made itself known quite suddenly at a +late-1990s meeting with the DEC Alpha architects, back in the days when +DEC was still a free-standing company. +It took the Alpha architects a good hour to convince me that any sort +of barrier would ever be needed, and it then took me a good <i>two</i> hours +to convince them that their documentation did not make this point clear. +More recent work with the C and C++ standards committees have provided +much education on tricks and traps from the compiler. +In short, compilers were much less tricky in the early 1990s, but in +2015, don't even think about omitting <tt>rcu_dereference()</tt>! + +<h3><a name="Memory-Barrier Guarantees">Memory-Barrier Guarantees</a></h3> + +<p> +The previous section's simple linked-data-structure scenario clearly +demonstrates the need for RCU's stringent memory-ordering guarantees on +systems with more than one CPU: + +<ol> +<li> Each CPU that has an RCU read-side critical section that + begins before <tt>synchronize_rcu()</tt> starts is + guaranteed to execute a full memory barrier between the time + that the RCU read-side critical section ends and the time that + <tt>synchronize_rcu()</tt> returns. + Without this guarantee, a pre-existing RCU read-side critical section + might hold a reference to the newly removed <tt>struct foo</tt> + after the <tt>kfree()</tt> on line 14 of + <tt>remove_gp_synchronous()</tt>. +<li> Each CPU that has an RCU read-side critical section that ends + after <tt>synchronize_rcu()</tt> returns is guaranteed + to execute a full memory barrier between the time that + <tt>synchronize_rcu()</tt> begins and the time that the RCU + read-side critical section begins. + Without this guarantee, a later RCU read-side critical section + running after the <tt>kfree()</tt> on line 14 of + <tt>remove_gp_synchronous()</tt> might + later run <tt>do_something_gp()</tt> and find the + newly deleted <tt>struct foo</tt>. +<li> If the task invoking <tt>synchronize_rcu()</tt> remains + on a given CPU, then that CPU is guaranteed to execute a full + memory barrier sometime during the execution of + <tt>synchronize_rcu()</tt>. + This guarantee ensures that the <tt>kfree()</tt> on + line 14 of <tt>remove_gp_synchronous()</tt> really does + execute after the removal on line 11. +<li> If the task invoking <tt>synchronize_rcu()</tt> migrates + among a group of CPUs during that invocation, then each of the + CPUs in that group is guaranteed to execute a full memory barrier + sometime during the execution of <tt>synchronize_rcu()</tt>. + This guarantee also ensures that the <tt>kfree()</tt> on + line 14 of <tt>remove_gp_synchronous()</tt> really does + execute after the removal on + line 11, but also in the case where the thread executing the + <tt>synchronize_rcu()</tt> migrates in the meantime. +</ol> + +<p><a name="Quick Quiz 5"><b>Quick Quiz 5</b>:</a> +Given that multiple CPUs can start RCU read-side critical sections +at any time without any ordering whatsoever, how can RCU possibly tell whether +or not a given RCU read-side critical section starts before a +given instance of <tt>synchronize_rcu()</tt>? +<br><a href="#qq5answer">Answer</a> + +<p><a name="Quick Quiz 6"><b>Quick Quiz 6</b>:</a> +The first and second guarantees require unbelievably strict ordering! +Are all these memory barriers <i> really</i> required? +<br><a href="#qq6answer">Answer</a> + +<p> +Note that these memory-barrier requirements do not replace the fundamental +RCU requirement that a grace period wait for all pre-existing readers. +On the contrary, the memory barriers called out in this section must operate in +such a way as to <i>enforce</i> this fundamental requirement. +Of course, different implementations enforce this requirement in different +ways, but enforce it they must. + +<h3><a name="RCU Primitives Guaranteed to Execute Unconditionally">RCU Primitives Guaranteed to Execute Unconditionally</a></h3> + +<p> +The common-case RCU primitives are unconditional. +They are invoked, they do their job, and they return, with no possibility +of error, and no need to retry. +This is a key RCU design philosophy. + +<p> +However, this philosophy is pragmatic rather than pigheaded. +If someone comes up with a good justification for a particular conditional +RCU primitive, it might well be implemented and added. +After all, this guarantee was reverse-engineered, not premeditated. +The unconditional nature of the RCU primitives was initially an +accident of implementation, and later experience with synchronization +primitives with conditional primitives caused me to elevate this +accident to a guarantee. +Therefore, the justification for adding a conditional primitive to +RCU would need to be based on detailed and compelling use cases. + +<h3><a name="Guaranteed Read-to-Write Upgrade">Guaranteed Read-to-Write Upgrade</a></h3> + +<p> +As far as RCU is concerned, it is always possible to carry out an +update within an RCU read-side critical section. +For example, that RCU read-side critical section might search for +a given data element, and then might acquire the update-side +spinlock in order to update that element, all while remaining +in that RCU read-side critical section. +Of course, it is necessary to exit the RCU read-side critical section +before invoking <tt>synchronize_rcu()</tt>, however, this +inconvenience can be avoided through use of the +<tt>call_rcu()</tt> and <tt>kfree_rcu()</tt> API members +described later in this document. + +<p><a name="Quick Quiz 7"><b>Quick Quiz 7</b>:</a> +But how does the upgrade-to-write operation exclude other readers? +<br><a href="#qq7answer">Answer</a> + +<p> +This guarantee allows lookup code to be shared between read-side +and update-side code, and was premeditated, appearing in the earliest +DYNIX/ptx RCU documentation. + +<h2><a name="Fundamental Non-Requirements">Fundamental Non-Requirements</a></h2> + +<p> +RCU provides extremely lightweight readers, and its read-side guarantees, +though quite useful, are correspondingly lightweight. +It is therefore all too easy to assume that RCU is guaranteeing more +than it really is. +Of course, the list of things that RCU does not guarantee is infinitely +long, however, the following sections list a few non-guarantees that +have caused confusion. +Except where otherwise noted, these non-guarantees were premeditated. + +<ol> +<li> <a href="#Readers Impose Minimal Ordering"> + Readers Impose Minimal Ordering</a> +<li> <a href="#Readers Do Not Exclude Updaters"> + Readers Do Not Exclude Updaters</a> +<li> <a href="#Updaters Only Wait For Old Readers"> + Updaters Only Wait For Old Readers</a> +<li> <a href="#Grace Periods Don't Partition Read-Side Critical Sections"> + Grace Periods Don't Partition Read-Side Critical Sections</a> +<li> <a href="#Read-Side Critical Sections Don't Partition Grace Periods"> + Read-Side Critical Sections Don't Partition Grace Periods</a> +<li> <a href="#Disabling Preemption Does Not Block Grace Periods"> + Disabling Preemption Does Not Block Grace Periods</a> +</ol> + +<h3><a name="Readers Impose Minimal Ordering">Readers Impose Minimal Ordering</a></h3> + +<p> +Reader-side markers such as <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> provide absolutely no ordering guarantees +except through their interaction with the grace-period APIs such as +<tt>synchronize_rcu()</tt>. +To see this, consider the following pair of threads: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(x, 1); + 5 rcu_read_unlock(); + 6 rcu_read_lock(); + 7 WRITE_ONCE(y, 1); + 8 rcu_read_unlock(); + 9 } +10 +11 void thread1(void) +12 { +13 rcu_read_lock(); +14 r1 = READ_ONCE(y); +15 rcu_read_unlock(); +16 rcu_read_lock(); +17 r2 = READ_ONCE(x); +18 rcu_read_unlock(); +19 } +</pre> +</blockquote> + +<p> +After <tt>thread0()</tt> and <tt>thread1()</tt> execute +concurrently, it is quite possible to have + +<blockquote> +<pre> +(r1 == 1 && r2 == 0) +</pre> +</blockquote> + +(that is, <tt>y</tt> appears to have been assigned before <tt>x</tt>), +which would not be possible if <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> had much in the way of ordering +properties. +But they do not, so the CPU is within its rights +to do significant reordering. +This is by design: Any significant ordering constraints would slow down +these fast-path APIs. + +<p><a name="Quick Quiz 8"><b>Quick Quiz 8</b>:</a> +Can't the compiler also reorder this code? +<br><a href="#qq8answer">Answer</a> + +<h3><a name="Readers Do Not Exclude Updaters">Readers Do Not Exclude Updaters</a></h3> + +<p> +Neither <tt>rcu_read_lock()</tt> nor <tt>rcu_read_unlock()</tt> +exclude updates. +All they do is to prevent grace periods from ending. +The following example illustrates this: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 r1 = READ_ONCE(y); + 5 if (r1) { + 6 do_something_with_nonzero_x(); + 7 r2 = READ_ONCE(x); + 8 WARN_ON(!r2); /* BUG!!! */ + 9 } +10 rcu_read_unlock(); +11 } +12 +13 void thread1(void) +14 { +15 spin_lock(&my_lock); +16 WRITE_ONCE(x, 1); +17 WRITE_ONCE(y, 1); +18 spin_unlock(&my_lock); +19 } +</pre> +</blockquote> + +<p> +If the <tt>thread0()</tt> function's <tt>rcu_read_lock()</tt> +excluded the <tt>thread1()</tt> function's update, +the <tt>WARN_ON()</tt> could never fire. +But the fact is that <tt>rcu_read_lock()</tt> does not exclude +much of anything aside from subsequent grace periods, of which +<tt>thread1()</tt> has none, so the +<tt>WARN_ON()</tt> can and does fire. + +<h3><a name="Updaters Only Wait For Old Readers">Updaters Only Wait For Old Readers</a></h3> + +<p> +It might be tempting to assume that after <tt>synchronize_rcu()</tt> +completes, there are no readers executing. +This temptation must be avoided because +new readers can start immediately after <tt>synchronize_rcu()</tt> +starts, and <tt>synchronize_rcu()</tt> is under no +obligation to wait for these new readers. + +<p><a name="Quick Quiz 9"><b>Quick Quiz 9</b>:</a> +Suppose that synchronize_rcu() did wait until all readers had completed. +Would the updater be able to rely on this? +<br><a href="#qq9answer">Answer</a> + +<h3><a name="Grace Periods Don't Partition Read-Side Critical Sections"> +Grace Periods Don't Partition Read-Side Critical Sections</a></h3> + +<p> +It is tempting to assume that if any part of one RCU read-side critical +section precedes a given grace period, and if any part of another RCU +read-side critical section follows that same grace period, then all of +the first RCU read-side critical section must precede all of the second. +However, this just isn't the case: A single grace period does not +partition the set of RCU read-side critical sections. +An example of this situation can be illustrated as follows, where +<tt>x</tt>, <tt>y</tt>, and <tt>z</tt> are initially all zero: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(a, 1); + 5 WRITE_ONCE(b, 1); + 6 rcu_read_unlock(); + 7 } + 8 + 9 void thread1(void) +10 { +11 r1 = READ_ONCE(a); +12 synchronize_rcu(); +13 WRITE_ONCE(c, 1); +14 } +15 +16 void thread2(void) +17 { +18 rcu_read_lock(); +19 r2 = READ_ONCE(b); +20 r3 = READ_ONCE(c); +21 rcu_read_unlock(); +22 } +</pre> +</blockquote> + +<p> +It turns out that the outcome: + +<blockquote> +<pre> +(r1 == 1 && r2 == 0 && r3 == 1) +</pre> +</blockquote> + +is entirely possible. +The following figure show how this can happen, with each circled +<tt>QS</tt> indicating the point at which RCU recorded a +<i>quiescent state</i> for each thread, that is, a state in which +RCU knows that the thread cannot be in the midst of an RCU read-side +critical section that started before the current grace period: + +<p><img src="GPpartitionReaders1.svg" alt="GPpartitionReaders1.svg" width="60%"></p> + +<p> +If it is necessary to partition RCU read-side critical sections in this +manner, it is necessary to use two grace periods, where the first +grace period is known to end before the second grace period starts: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(a, 1); + 5 WRITE_ONCE(b, 1); + 6 rcu_read_unlock(); + 7 } + 8 + 9 void thread1(void) +10 { +11 r1 = READ_ONCE(a); +12 synchronize_rcu(); +13 WRITE_ONCE(c, 1); +14 } +15 +16 void thread2(void) +17 { +18 r2 = READ_ONCE(c); +19 synchronize_rcu(); +20 WRITE_ONCE(d, 1); +21 } +22 +23 void thread3(void) +24 { +25 rcu_read_lock(); +26 r3 = READ_ONCE(b); +27 r4 = READ_ONCE(d); +28 rcu_read_unlock(); +29 } +</pre> +</blockquote> + +<p> +Here, if <tt>(r1 == 1)</tt>, then +<tt>thread0()</tt>'s write to <tt>b</tt> must happen +before the end of <tt>thread1()</tt>'s grace period. +If in addition <tt>(r4 == 1)</tt>, then +<tt>thread3()</tt>'s read from <tt>b</tt> must happen +after the beginning of <tt>thread2()</tt>'s grace period. +If it is also the case that <tt>(r2 == 1)</tt>, then the +end of <tt>thread1()</tt>'s grace period must precede the +beginning of <tt>thread2()</tt>'s grace period. +This mean that the two RCU read-side critical sections cannot overlap, +guaranteeing that <tt>(r3 == 1)</tt>. +As a result, the outcome: + +<blockquote> +<pre> +(r1 == 1 && r2 == 1 && r3 == 0 && r4 == 1) +</pre> +</blockquote> + +cannot happen. + +<p> +This non-requirement was also non-premeditated, but became apparent +when studying RCU's interaction with memory ordering. + +<h3><a name="Read-Side Critical Sections Don't Partition Grace Periods"> +Read-Side Critical Sections Don't Partition Grace Periods</a></h3> + +<p> +It is also tempting to assume that if an RCU read-side critical section +happens between a pair of grace periods, then those grace periods cannot +overlap. +However, this temptation leads nowhere good, as can be illustrated by +the following, with all variables initially zero: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(a, 1); + 5 WRITE_ONCE(b, 1); + 6 rcu_read_unlock(); + 7 } + 8 + 9 void thread1(void) +10 { +11 r1 = READ_ONCE(a); +12 synchronize_rcu(); +13 WRITE_ONCE(c, 1); +14 } +15 +16 void thread2(void) +17 { +18 rcu_read_lock(); +19 WRITE_ONCE(d, 1); +20 r2 = READ_ONCE(c); +21 rcu_read_unlock(); +22 } +23 +24 void thread3(void) +25 { +26 r3 = READ_ONCE(d); +27 synchronize_rcu(); +28 WRITE_ONCE(e, 1); +29 } +30 +31 void thread4(void) +32 { +33 rcu_read_lock(); +34 r4 = READ_ONCE(b); +35 r5 = READ_ONCE(e); +36 rcu_read_unlock(); +37 } +</pre> +</blockquote> + +<p> +In this case, the outcome: + +<blockquote> +<pre> +(r1 == 1 && r2 == 1 && r3 == 1 && r4 == 0 && r5 == 1) +</pre> +</blockquote> + +is entirely possible, as illustrated below: + +<p><img src="ReadersPartitionGP1.svg" alt="ReadersPartitionGP1.svg" width="100%"></p> + +<p> +Again, an RCU read-side critical section can overlap almost all of a +given grace period, just so long as it does not overlap the entire +grace period. +As a result, an RCU read-side critical section cannot partition a pair +of RCU grace periods. + +<p><a name="Quick Quiz 10"><b>Quick Quiz 10</b>:</a> +How long a sequence of grace periods, each separated by an RCU read-side +critical section, would be required to partition the RCU read-side +critical sections at the beginning and end of the chain? +<br><a href="#qq10answer">Answer</a> + +<h3><a name="Disabling Preemption Does Not Block Grace Periods"> +Disabling Preemption Does Not Block Grace Periods</a></h3> + +<p> +There was a time when disabling preemption on any given CPU would block +subsequent grace periods. +However, this was an accident of implementation and is not a requirement. +And in the current Linux-kernel implementation, disabling preemption +on a given CPU in fact does not block grace periods, as Oleg Nesterov +<a href="https://lkml.kernel.org/g/20150614193825.GA19582@redhat.com">demonstrated</a>. + +<p> +If you need a preempt-disable region to block grace periods, you need to add +<tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>, for example +as follows: + +<blockquote> +<pre> + 1 preempt_disable(); + 2 rcu_read_lock(); + 3 do_something(); + 4 rcu_read_unlock(); + 5 preempt_enable(); + 6 + 7 /* Spinlocks implicitly disable preemption. */ + 8 spin_lock(&mylock); + 9 rcu_read_lock(); +10 do_something(); +11 rcu_read_unlock(); +12 spin_unlock(&mylock); +</pre> +</blockquote> + +<p> +In theory, you could enter the RCU read-side critical section first, +but it is more efficient to keep the entire RCU read-side critical +section contained in the preempt-disable region as shown above. +Of course, RCU read-side critical sections that extend outside of +preempt-disable regions will work correctly, but such critical sections +can be preempted, which forces <tt>rcu_read_unlock()</tt> to do +more work. +And no, this is <i>not</i> an invitation to enclose all of your RCU +read-side critical sections within preempt-disable regions, because +doing so would degrade real-time response. + +<p> +This non-requirement appeared with preemptible RCU. +If you need a grace period that waits on non-preemptible code regions, use +<a href="#Sched Flavor">RCU-sched</a>. + +<h2><a name="Parallelism Facts of Life">Parallelism Facts of Life</a></h2> + +<p> +These parallelism facts of life are by no means specific to RCU, but +the RCU implementation must abide by them. +They therefore bear repeating: + +<ol> +<li> Any CPU or task may be delayed at any time, + and any attempts to avoid these delays by disabling + preemption, interrupts, or whatever are completely futile. + This is most obvious in preemptible user-level + environments and in virtualized environments (where + a given guest OS's VCPUs can be preempted at any time by + the underlying hypervisor), but can also happen in bare-metal + environments due to ECC errors, NMIs, and other hardware + events. + Although a delay of more than about 20 seconds can result + in splats, the RCU implementation is obligated to use + algorithms that can tolerate extremely long delays, but where + “extremely long” is not long enough to allow + wrap-around when incrementing a 64-bit counter. +<li> Both the compiler and the CPU can reorder memory accesses. + Where it matters, RCU must use compiler directives and + memory-barrier instructions to preserve ordering. +<li> Conflicting writes to memory locations in any given cache line + will result in expensive cache misses. + Greater numbers of concurrent writes and more-frequent + concurrent writes will result in more dramatic slowdowns. + RCU is therefore obligated to use algorithms that have + sufficient locality to avoid significant performance and + scalability problems. +<li> As a rough rule of thumb, only one CPU's worth of processing + may be carried out under the protection of any given exclusive + lock. + RCU must therefore use scalable locking designs. +<li> Counters are finite, especially on 32-bit systems. + RCU's use of counters must therefore tolerate counter wrap, + or be designed such that counter wrap would take way more + time than a single system is likely to run. + An uptime of ten years is quite possible, a runtime + of a century much less so. + As an example of the latter, RCU's dyntick-idle nesting counter + allows 54 bits for interrupt nesting level (this counter + is 64 bits even on a 32-bit system). + Overflowing this counter requires 2<sup>54</sup> + half-interrupts on a given CPU without that CPU ever going idle. + If a half-interrupt happened every microsecond, it would take + 570 years of runtime to overflow this counter, which is currently + believed to be an acceptably long time. +<li> Linux systems can have thousands of CPUs running a single + Linux kernel in a single shared-memory environment. + RCU must therefore pay close attention to high-end scalability. +</ol> + +<p> +This last parallelism fact of life means that RCU must pay special +attention to the preceding facts of life. +The idea that Linux might scale to systems with thousands of CPUs would +have been met with some skepticism in the 1990s, but these requirements +would have otherwise have been unsurprising, even in the early 1990s. + +<h2><a name="Quality-of-Implementation Requirements">Quality-of-Implementation Requirements</a></h2> + +<p> +These sections list quality-of-implementation requirements. +Although an RCU implementation that ignores these requirements could +still be used, it would likely be subject to limitations that would +make it inappropriate for industrial-strength production use. +Classes of quality-of-implementation requirements are as follows: + +<ol> +<li> <a href="#Specialization">Specialization</a> +<li> <a href="#Performance and Scalability">Performance and Scalability</a> +<li> <a href="#Composability">Composability</a> +<li> <a href="#Corner Cases">Corner Cases</a> +</ol> + +<p> +These classes is covered in the following sections. + +<h3><a name="Specialization">Specialization</a></h3> + +<p> +RCU is and always has been intended primarily for read-mostly situations, as +illustrated by the following figure. +This means that RCU's read-side primitives are optimized, often at the +expense of its update-side primitives. + +<p><img src="RCUApplicability.svg" alt="RCUApplicability.svg" width="70%"></p> + +<p> +This focus on read-mostly situations means that RCU must interoperate +with other synchronization primitives. +For example, the <tt>add_gp()</tt> and <tt>remove_gp_synchronous()</tt> +examples discussed earlier use RCU to protect readers and locking to +coordinate updaters. +However, the need extends much farther, requiring that a variety of +synchronization primitives be legal within RCU read-side critical sections, +including spinlocks, sequence locks, atomic operations, reference +counters, and memory barriers. + +<p><a name="Quick Quiz 11"><b>Quick Quiz 11</b>:</a> +What about sleeping locks? +<br><a href="#qq11answer">Answer</a> + +<p> +It often comes as a surprise that many algorithms do not require a +consistent view of data, but many can function in that mode, +with network routing being the poster child. +Internet routing algorithms take significant time to propagate +updates, so that by the time an update arrives at a given system, +that system has been sending network traffic the wrong way for +a considerable length of time. +Having a few threads continue to send traffic the wrong way for a +few more milliseconds is clearly not a problem: In the worst case, +TCP retransmissions will eventually get the data where it needs to go. +In general, when tracking the state of the universe outside of the +computer, some level of inconsistency must be tolerated due to +speed-of-light delays if nothing else. + +<p> +Furthermore, uncertainty about external state is inherent in many cases. +For example, a pair of veternarians might use heartbeat to determine +whether or not a given cat was alive. +But how long should they wait after the last heartbeat to decide that +the cat is in fact dead? +Waiting less than 400 milliseconds makes no sense because this would +mean that a relaxed cat would be considered to cycle between death +and life more than 100 times per minute. +Moreover, just as with human beings, a cat's heart might stop for +some period of time, so the exact wait period is a judgment call. +One of our pair of veternarians might wait 30 seconds before pronouncing +the cat dead, while the other might insist on waiting a full minute. +The two veternarians would then disagree on the state of the cat during +the final 30 seconds of the minute following the last heartbeat, as +fancifully illustrated below: + +<p><img src="2013-08-is-it-dead.png" alt="2013-08-is-it-dead.png" width="431"></p> + +<p> +Interestingly enough, this same situation applies to hardware. +When push comes to shove, how do we tell whether or not some +external server has failed? +We send messages to it periodically, and declare it failed if we +don't receive a response within a given period of time. +Policy decisions can usually tolerate short +periods of inconsistency. +The policy was decided some time ago, and is only now being put into +effect, so a few milliseconds of delay is normally inconsequential. + +<p> +However, there are algorithms that absolutely must see consistent data. +For example, the translation between a user-level SystemV semaphore +ID to the corresponding in-kernel data structure is protected by RCU, +but it is absolutely forbidden to update a semaphore that has just been +removed. +In the Linux kernel, this need for consistency is accommodated by acquiring +spinlocks located in the in-kernel data structure from within +the RCU read-side critical section, and this is indicated by the +green box in the figure above. +Many other techniques may be used, and are in fact used within the +Linux kernel. + +<p> +In short, RCU is not required to maintain consistency, and other +mechanisms may be used in concert with RCU when consistency is required. +RCU's specialization allows it to do its job extremely well, and its +ability to interoperate with other synchronization mechanisms allows +the right mix of synchronization tools to be used for a given job. + +<h3><a name="Performance and Scalability">Performance and Scalability</a></h3> + +<p> +Energy efficiency is a critical component of performance today, +and Linux-kernel RCU implementations must therefore avoid unnecessarily +awakening idle CPUs. +I cannot claim that this requirement was premeditated. +In fact, I learned of it during a telephone conversation in which I +was given “frank and open” feedback on the importance +of energy efficiency in battery-powered systems and on specific +energy-efficiency shortcomings of the Linux-kernel RCU implementation. +In my experience, the battery-powered embedded community will consider +any unnecessary wakeups to be extremely unfriendly acts. +So much so that mere Linux-kernel-mailing-list posts are +insufficient to vent their ire. + +<p> +Memory consumption is not particularly important for in most +situations, and has become decreasingly +so as memory sizes have expanded and memory +costs have plummeted. +However, as I learned from Matt Mackall's +<a href="http://elinux.org/Linux_Tiny-FAQ">bloatwatch</a> +efforts, memory footprint is critically important on single-CPU systems with +non-preemptible (<tt>CONFIG_PREEMPT=n</tt>) kernels, and thus +<a href="https://lkml.kernel.org/g/20090113221724.GA15307@linux.vnet.ibm.com">tiny RCU</a> +was born. +Josh Triplett has since taken over the small-memory banner with his +<a href="https://tiny.wiki.kernel.org/">Linux kernel tinification</a> +project, which resulted in +<a href="#Sleepable RCU">SRCU</a> +becoming optional for those kernels not needing it. + +<p> +The remaining performance requirements are, for the most part, +unsurprising. +For example, in keeping with RCU's read-side specialization, +<tt>rcu_dereference()</tt> should have negligible overhead (for +example, suppression of a few minor compiler optimizations). +Similarly, in non-preemptible environments, <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> should have exactly zero overhead. + +<p> +In preemptible environments, in the case where the RCU read-side +critical section was not preempted (as will be the case for the +highest-priority real-time process), <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> should have minimal overhead. +In particular, they should not contain atomic read-modify-write +operations, memory-barrier instructions, preemption disabling, +interrupt disabling, or backwards branches. +However, in the case where the RCU read-side critical section was preempted, +<tt>rcu_read_unlock()</tt> may acquire spinlocks and disable interrupts. +This is why it is better to nest an RCU read-side critical section +within a preempt-disable region than vice versa, at least in cases +where that critical section is short enough to avoid unduly degrading +real-time latencies. + +<p> +The <tt>synchronize_rcu()</tt> grace-period-wait primitive is +optimized for throughput. +It may therefore incur several milliseconds of latency in addition to +the duration of the longest RCU read-side critical section. +On the other hand, multiple concurrent invocations of +<tt>synchronize_rcu()</tt> are required to use batching optimizations +so that they can be satisfied by a single underlying grace-period-wait +operation. +For example, in the Linux kernel, it is not unusual for a single +grace-period-wait operation to serve more than +<a href="https://www.usenix.org/conference/2004-usenix-annual-technical-conference/making-rcu-safe-deep-sub-millisecond-response">1,000 separate invocations</a> +of <tt>synchronize_rcu()</tt>, thus amortizing the per-invocation +overhead down to nearly zero. +However, the grace-period optimization is also required to avoid +measurable degradation of real-time scheduling and interrupt latencies. + +<p> +In some cases, the multi-millisecond <tt>synchronize_rcu()</tt> +latencies are unacceptable. +In these cases, <tt>synchronize_rcu_expedited()</tt> may be used +instead, reducing the grace-period latency down to a few tens of +microseconds on small systems, at least in cases where the RCU read-side +critical sections are short. +There are currently no special latency requirements for +<tt>synchronize_rcu_expedited()</tt> on large systems, but, +consistent with the empirical nature of the RCU specification, +that is subject to change. +However, there most definitely are scalability requirements: +A storm of <tt>synchronize_rcu_expedited()</tt> invocations on 4096 +CPUs should at least make reasonable forward progress. +In return for its shorter latencies, <tt>synchronize_rcu_expedited()</tt> +is permitted to impose modest degradation of real-time latency +on non-idle online CPUs. +That said, it will likely be necessary to take further steps to reduce this +degradation, hopefully to roughly that of a scheduling-clock interrupt. + +<p> +There are a number of situations where even +<tt>synchronize_rcu_expedited()</tt>'s reduced grace-period +latency is unacceptable. +In these situations, the asynchronous <tt>call_rcu()</tt> can be +used in place of <tt>synchronize_rcu()</tt> as follows: + +<blockquote> +<pre> + 1 struct foo { + 2 int a; + 3 int b; + 4 struct rcu_head rh; + 5 }; + 6 + 7 static void remove_gp_cb(struct rcu_head *rhp) + 8 { + 9 struct foo *p = container_of(rhp, struct foo, rh); +10 +11 kfree(p); +12 } +13 +14 bool remove_gp_asynchronous(void) +15 { +16 struct foo *p; +17 +18 spin_lock(&gp_lock); +19 p = rcu_dereference(gp); +20 if (!p) { +21 spin_unlock(&gp_lock); +22 return false; +23 } +24 rcu_assign_pointer(gp, NULL); +25 call_rcu(&p->rh, remove_gp_cb); +26 spin_unlock(&gp_lock); +27 return true; +28 } +</pre> +</blockquote> + +<p> +A definition of <tt>struct foo</tt> is finally needed, and appears +on lines 1-5. +The function <tt>remove_gp_cb()</tt> is passed to <tt>call_rcu()</tt> +on line 25, and will be invoked after the end of a subsequent +grace period. +This gets the same effect as <tt>remove_gp_synchronous()</tt>, +but without forcing the updater to wait for a grace period to elapse. +The <tt>call_rcu()</tt> function may be used in a number of +situations where neither <tt>synchronize_rcu()</tt> nor +<tt>synchronize_rcu_expedited()</tt> would be legal, +including within preempt-disable code, <tt>local_bh_disable()</tt> code, +interrupt-disable code, and interrupt handlers. +However, even <tt>call_rcu()</tt> is illegal within NMI handlers. +The callback function (<tt>remove_gp_cb()</tt> in this case) will be +executed within softirq (software interrupt) environment within the +Linux kernel, +either within a real softirq handler or under the protection +of <tt>local_bh_disable()</tt>. +In both the Linux kernel and in userspace, it is bad practice to +write an RCU callback function that takes too long. +Long-running operations should be relegated to separate threads or +(in the Linux kernel) workqueues. + +<p><a name="Quick Quiz 12"><b>Quick Quiz 12</b>:</a> +Why does line 19 use <tt>rcu_access_pointer()</tt>? +After all, <tt>call_rcu()</tt> on line 25 stores into the +structure, which would interact badly with concurrent insertions. +Doesn't this mean that <tt>rcu_dereference()</tt> is required? +<br><a href="#qq12answer">Answer</a> + +<p> +However, all that <tt>remove_gp_cb()</tt> is doing is +invoking <tt>kfree()</tt> on the data element. +This is a common idiom, and is supported by <tt>kfree_rcu()</tt>, +which allows “fire and forget” operation as shown below: + +<blockquote> +<pre> + 1 struct foo { + 2 int a; + 3 int b; + 4 struct rcu_head rh; + 5 }; + 6 + 7 bool remove_gp_faf(void) + 8 { + 9 struct foo *p; +10 +11 spin_lock(&gp_lock); +12 p = rcu_dereference(gp); +13 if (!p) { +14 spin_unlock(&gp_lock); +15 return false; +16 } +17 rcu_assign_pointer(gp, NULL); +18 kfree_rcu(p, rh); +19 spin_unlock(&gp_lock); +20 return true; +21 } +</pre> +</blockquote> + +<p> +Note that <tt>remove_gp_faf()</tt> simply invokes +<tt>kfree_rcu()</tt> and proceeds, without any need to pay any +further attention to the subsequent grace period and <tt>kfree()</tt>. +It is permissible to invoke <tt>kfree_rcu()</tt> from the same +environments as for <tt>call_rcu()</tt>. +Interestingly enough, DYNIX/ptx had the equivalents of +<tt>call_rcu()</tt> and <tt>kfree_rcu()</tt>, but not +<tt>synchronize_rcu()</tt>. +This was due to the fact that RCU was not heavily used within DYNIX/ptx, +so the very few places that needed something like +<tt>synchronize_rcu()</tt> simply open-coded it. + +<p><a name="Quick Quiz 13"><b>Quick Quiz 13</b>:</a> +Earlier it was claimed that <tt>call_rcu()</tt> and +<tt>kfree_rcu()</tt> allowed updaters to avoid being blocked +by readers. +But how can that be correct, given that the invocation of the callback +and the freeing of the memory (respectively) must still wait for +a grace period to elapse? +<br><a href="#qq13answer">Answer</a> + +<p> +But what if the updater must wait for the completion of code to be +executed after the end of the grace period, but has other tasks +that can be carried out in the meantime? +The polling-style <tt>get_state_synchronize_rcu()</tt> and +<tt>cond_synchronize_rcu()</tt> functions may be used for this +purpose, as shown below: + +<blockquote> +<pre> + 1 bool remove_gp_poll(void) + 2 { + 3 struct foo *p; + 4 unsigned long s; + 5 + 6 spin_lock(&gp_lock); + 7 p = rcu_access_pointer(gp); + 8 if (!p) { + 9 spin_unlock(&gp_lock); +10 return false; +11 } +12 rcu_assign_pointer(gp, NULL); +13 spin_unlock(&gp_lock); +14 s = get_state_synchronize_rcu(); +15 do_something_while_waiting(); +16 cond_synchronize_rcu(s); +17 kfree(p); +18 return true; +19 } +</pre> +</blockquote> + +<p> +On line 14, <tt>get_state_synchronize_rcu()</tt> obtains a +“cookie” from RCU, +then line 15 carries out other tasks, +and finally, line 16 returns immediately if a grace period has +elapsed in the meantime, but otherwise waits as required. +The need for <tt>get_state_synchronize_rcu</tt> and +<tt>cond_synchronize_rcu()</tt> has appeared quite recently, +so it is too early to tell whether they will stand the test of time. + +<p> +RCU thus provides a range of tools to allow updaters to strike the +required tradeoff between latency, flexibility and CPU overhead. + +<h3><a name="Composability">Composability</a></h3> + +<p> +Composability has received much attention in recent years, perhaps in part +due to the collision of multicore hardware with object-oriented techniques +designed in single-threaded environments for single-threaded use. +And in theory, RCU read-side critical sections may be composed, and in +fact may be nested arbitrarily deeply. +In practice, as with all real-world implementations of composable +constructs, there are limitations. + +<p> +Implementations of RCU for which <tt>rcu_read_lock()</tt> +and <tt>rcu_read_unlock()</tt> generate no code, such as +Linux-kernel RCU when <tt>CONFIG_PREEMPT=n</tt>, can be +nested arbitrarily deeply. +After all, there is no overhead. +Except that if all these instances of <tt>rcu_read_lock()</tt> +and <tt>rcu_read_unlock()</tt> are visible to the compiler, +compilation will eventually fail due to exhausting memory, +mass storage, or user patience, whichever comes first. +If the nesting is not visible to the compiler, as is the case with +mutually recursive functions each in its own translation unit, +stack overflow will result. +If the nesting takes the form of loops, either the control variable +will overflow or (in the Linux kernel) you will get an RCU CPU stall warning. +Nevertheless, this class of RCU implementations is one +of the most composable constructs in existence. + +<p> +RCU implementations that explicitly track nesting depth +are limited by the nesting-depth counter. +For example, the Linux kernel's preemptible RCU limits nesting to +<tt>INT_MAX</tt>. +This should suffice for almost all practical purposes. +That said, a consecutive pair of RCU read-side critical sections +between which there is an operation that waits for a grace period +cannot be enclosed in another RCU read-side critical section. +This is because it is not legal to wait for a grace period within +an RCU read-side critical section: To do so would result either +in deadlock or +in RCU implicitly splitting the enclosing RCU read-side critical +section, neither of which is conducive to a long-lived and prosperous +kernel. + +<p> +It is worth noting that RCU is not alone in limiting composability. +For example, many transactional-memory implementations prohibit +composing a pair of transactions separated by an irrevocable +operation (for example, a network receive operation). +For another example, lock-based critical sections can be composed +surprisingly freely, but only if deadlock is avoided. + +<p> +In short, although RCU read-side critical sections are highly composable, +care is required in some situations, just as is the case for any other +composable synchronization mechanism. + +<h3><a name="Corner Cases">Corner Cases</a></h3> + +<p> +A given RCU workload might have an endless and intense stream of +RCU read-side critical sections, perhaps even so intense that there +was never a point in time during which there was not at least one +RCU read-side critical section in flight. +RCU cannot allow this situation to block grace periods: As long as +all the RCU read-side critical sections are finite, grace periods +must also be finite. + +<p> +That said, preemptible RCU implementations could potentially result +in RCU read-side critical sections being preempted for long durations, +which has the effect of creating a long-duration RCU read-side +critical section. +This situation can arise only in heavily loaded systems, but systems using +real-time priorities are of course more vulnerable. +Therefore, RCU priority boosting is provided to help deal with this +case. +That said, the exact requirements on RCU priority boosting will likely +evolve as more experience accumulates. + +<p> +Other workloads might have very high update rates. +Although one can argue that such workloads should instead use +something other than RCU, the fact remains that RCU must +handle such workloads gracefully. +This requirement is another factor driving batching of grace periods, +but it is also the driving force behind the checks for large numbers +of queued RCU callbacks in the <tt>call_rcu()</tt> code path. +Finally, high update rates should not delay RCU read-side critical +sections, although some read-side delays can occur when using +<tt>synchronize_rcu_expedited()</tt>, courtesy of this function's use +of <tt>try_stop_cpus()</tt>. +(In the future, <tt>synchronize_rcu_expedited()</tt> will be +converted to use lighter-weight inter-processor interrupts (IPIs), +but this will still disturb readers, though to a much smaller degree.) + +<p> +Although all three of these corner cases were understood in the early +1990s, a simple user-level test consisting of <tt>close(open(path))</tt> +in a tight loop +in the early 2000s suddenly provided a much deeper appreciation of the +high-update-rate corner case. +This test also motivated addition of some RCU code to react to high update +rates, for example, if a given CPU finds itself with more than 10,000 +RCU callbacks queued, it will cause RCU to take evasive action by +more aggressively starting grace periods and more aggressively forcing +completion of grace-period processing. +This evasive action causes the grace period to complete more quickly, +but at the cost of restricting RCU's batching optimizations, thus +increasing the CPU overhead incurred by that grace period. + +<h2><a name="Software-Engineering Requirements"> +Software-Engineering Requirements</a></h2> + +<p> +Between Murphy's Law and “To err is human”, it is necessary to +guard against mishaps and misuse: + +<ol> +<li> It is all too easy to forget to use <tt>rcu_read_lock()</tt> + everywhere that it is needed, so kernels built with + <tt>CONFIG_PROVE_RCU=y</tt> will spat if + <tt>rcu_dereference()</tt> is used outside of an + RCU read-side critical section. + Update-side code can use <tt>rcu_dereference_protected()</tt>, + which takes a + <a href="https://lwn.net/Articles/371986/">lockdep expression</a> + to indicate what is providing the protection. + If the indicated protection is not provided, a lockdep splat + is emitted. + + <p> + Code shared between readers and updaters can use + <tt>rcu_dereference_check()</tt>, which also takes a + lockdep expression, and emits a lockdep splat if neither + <tt>rcu_read_lock()</tt> nor the indicated protection + is in place. + In addition, <tt>rcu_dereference_raw()</tt> is used in those + (hopefully rare) cases where the required protection cannot + be easily described. + Finally, <tt>rcu_read_lock_held()</tt> is provided to + allow a function to verify that it has been invoked within + an RCU read-side critical section. + I was made aware of this set of requirements shortly after Thomas + Gleixner audited a number of RCU uses. +<li> A given function might wish to check for RCU-related preconditions + upon entry, before using any other RCU API. + The <tt>rcu_lockdep_assert()</tt> does this job, + asserting the expression in kernels having lockdep enabled + and doing nothing otherwise. +<li> It is also easy to forget to use <tt>rcu_assign_pointer()</tt> + and <tt>rcu_dereference()</tt>, perhaps (incorrectly) + substituting a simple assignment. + To catch this sort of error, a given RCU-protected pointer may be + tagged with <tt>__rcu</tt>, after which running sparse + with <tt>CONFIG_SPARSE_RCU_POINTER=y</tt> will complain + about simple-assignment accesses to that pointer. + Arnd Bergmann made me aware of this requirement, and also + supplied the needed + <a href="https://lwn.net/Articles/376011/">patch series</a>. +<li> Kernels built with <tt>CONFIG_DEBUG_OBJECTS_RCU_HEAD=y</tt> + will splat if a data element is passed to <tt>call_rcu()</tt> + twice in a row, without a grace period in between. + (This error is similar to a double free.) + The corresponding <tt>rcu_head</tt> structures that are + dynamically allocated are automatically tracked, but + <tt>rcu_head</tt> structures allocated on the stack + must be initialized with <tt>init_rcu_head_on_stack()</tt> + and cleaned up with <tt>destroy_rcu_head_on_stack()</tt>. + Similarly, statically allocated non-stack <tt>rcu_head</tt> + structures must be initialized with <tt>init_rcu_head()</tt> + and cleaned up with <tt>destroy_rcu_head()</tt>. + Mathieu Desnoyers made me aware of this requirement, and also + supplied the needed + <a href="https://lkml.kernel.org/g/20100319013024.GA28456@Krystal">patch</a>. +<li> An infinite loop in an RCU read-side critical section will + eventually trigger an RCU CPU stall warning splat, with + the duration of “eventually” being controlled by the + <tt>RCU_CPU_STALL_TIMEOUT</tt> <tt>Kconfig</tt> option, or, + alternatively, by the + <tt>rcupdate.rcu_cpu_stall_timeout</tt> boot/sysfs + parameter. + However, RCU is not obligated to produce this splat + unless there is a grace period waiting on that particular + RCU read-side critical section. + <p> + Some extreme workloads might intentionally delay + RCU grace periods, and systems running those workloads can + be booted with <tt>rcupdate.rcu_cpu_stall_suppress</tt> + to suppress the splats. + This kernel parameter may also be set via <tt>sysfs</tt>. + Furthermore, RCU CPU stall warnings are counter-productive + during sysrq dumps and during panics. + RCU therefore supplies the <tt>rcu_sysrq_start()</tt> and + <tt>rcu_sysrq_end()</tt> API members to be called before + and after long sysrq dumps. + RCU also supplies the <tt>rcu_panic()</tt> notifier that is + automatically invoked at the beginning of a panic to suppress + further RCU CPU stall warnings. + + <p> + This requirement made itself known in the early 1990s, pretty + much the first time that it was necessary to debug a CPU stall. + That said, the initial implementation in DYNIX/ptx was quite + generic in comparison with that of Linux. +<li> Although it would be very good to detect pointers leaking out + of RCU read-side critical sections, there is currently no + good way of doing this. + One complication is the need to distinguish between pointers + leaking and pointers that have been handed off from RCU to + some other synchronization mechanism, for example, reference + counting. +<li> In kernels built with <tt>CONFIG_RCU_TRACE=y</tt>, RCU-related + information is provided via both debugfs and event tracing. +<li> Open-coded use of <tt>rcu_assign_pointer()</tt> and + <tt>rcu_dereference()</tt> to create typical linked + data structures can be surprisingly error-prone. + Therefore, RCU-protected + <a href="https://lwn.net/Articles/609973/#RCU List APIs">linked lists</a> + and, more recently, RCU-protected + <a href="https://lwn.net/Articles/612100/">hash tables</a> + are available. + Many other special-purpose RCU-protected data structures are + available in the Linux kernel and the userspace RCU library. +<li> Some linked structures are created at compile time, but still + require <tt>__rcu</tt> checking. + The <tt>RCU_POINTER_INITIALIZER()</tt> macro serves this + purpose. +<li> It is not necessary to use <tt>rcu_assign_pointer()</tt> + when creating linked structures that are to be published via + a single external pointer. + The <tt>RCU_INIT_POINTER()</tt> macro is provided for + this task and also for assigning <tt>NULL</tt> pointers + at runtime. +</ol> + +<p> +This not a hard-and-fast list: RCU's diagnostic capabilities will +continue to be guided by the number and type of usage bugs found +in real-world RCU usage. + +<h2><a name="Linux Kernel Complications">Linux Kernel Complications</a></h2> + +<p> +The Linux kernel provides an interesting environment for all kinds of +software, including RCU. +Some of the relevant points of interest are as follows: + +<ol> +<li> <a href="#Configuration">Configuration</a>. +<li> <a href="#Firmware Interface">Firmware Interface</a>. +<li> <a href="#Early Boot">Early Boot</a>. +<li> <a href="#Interrupts and NMIs"> + Interrupts and non-maskable interrupts (NMIs)</a>. +<li> <a href="#Loadable Modules">Loadable Modules</a>. +<li> <a href="#Hotplug CPU">Hotplug CPU</a>. +<li> <a href="#Scheduler and RCU">Scheduler and RCU</a>. +<li> <a href="#Tracing and RCU">Tracing and RCU</a>. +<li> <a href="#Energy Efficiency">Energy Efficiency</a>. +<li> <a href="#Memory Efficiency">Memory Efficiency</a>. +<li> <a href="#Performance, Scalability, Response Time, and Reliability"> + Performance, Scalability, Response Time, and Reliability</a>. +</ol> + +<p> +This list is probably incomplete, but it does give a feel for the +most notable Linux-kernel complications. +Each of the following sections covers one of the above topics. + +<h3><a name="Configuration">Configuration</a></h3> + +<p> +RCU's goal is automatic configuration, so that almost nobody +needs to worry about RCU's <tt>Kconfig</tt> options. +And for almost all users, RCU does in fact work well +“out of the box.” + +<p> +However, there are specialized use cases that are handled by +kernel boot parameters and <tt>Kconfig</tt> options. +Unfortunately, the <tt>Kconfig</tt> system will explicitly ask users +about new <tt>Kconfig</tt> options, which requires almost all of them +be hidden behind a <tt>CONFIG_RCU_EXPERT</tt> <tt>Kconfig</tt> option. + +<p> +This all should be quite obvious, but the fact remains that +Linus Torvalds recently had to +<a href="https://lkml.kernel.org/g/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com">remind</a> +me of this requirement. + +<h3><a name="Firmware Interface">Firmware Interface</a></h3> + +<p> +In many cases, kernel obtains information about the system from the +firmware, and sometimes things are lost in translation. +Or the translation is accurate, but the original message is bogus. + +<p> +For example, some systems' firmware overreports the number of CPUs, +sometimes by a large factor. +If RCU naively believed the firmware, as it used to do, +it would create too many per-CPU kthreads. +Although the resulting system will still run correctly, the extra +kthreads needlessly consume memory and can cause confusion +when they show up in <tt>ps</tt> listings. + +<p> +RCU must therefore wait for a given CPU to actually come online before +it can allow itself to believe that the CPU actually exists. +The resulting “ghost CPUs” (which are never going to +come online) cause a number of +<a href="https://paulmck.livejournal.com/37494.html">interesting complications</a>. + +<h3><a name="Early Boot">Early Boot</a></h3> + +<p> +The Linux kernel's boot sequence is an interesting process, +and RCU is used early, even before <tt>rcu_init()</tt> +is invoked. +In fact, a number of RCU's primitives can be used as soon as the +initial task's <tt>task_struct</tt> is available and the +boot CPU's per-CPU variables are set up. +The read-side primitives (<tt>rcu_read_lock()</tt>, +<tt>rcu_read_unlock()</tt>, <tt>rcu_dereference()</tt>, +and <tt>rcu_access_pointer()</tt>) will operate normally very early on, +as will <tt>rcu_assign_pointer()</tt>. + +<p> +Although <tt>call_rcu()</tt> may be invoked at any +time during boot, callbacks are not guaranteed to be invoked until after +the scheduler is fully up and running. +This delay in callback invocation is due to the fact that RCU does not +invoke callbacks until it is fully initialized, and this full initialization +cannot occur until after the scheduler has initialized itself to the +point where RCU can spawn and run its kthreads. +In theory, it would be possible to invoke callbacks earlier, +however, this is not a panacea because there would be severe restrictions +on what operations those callbacks could invoke. + +<p> +Perhaps surprisingly, <tt>synchronize_rcu()</tt>, +<a href="#Bottom-Half Flavor"><tt>synchronize_rcu_bh()</tt></a> +(<a href="#Bottom-Half Flavor">discussed below</a>), +and +<a href="#Sched Flavor"><tt>synchronize_sched()</tt></a> +will all operate normally +during very early boot, the reason being that there is only one CPU +and preemption is disabled. +This means that the call <tt>synchronize_rcu()</tt> (or friends) +itself is a quiescent +state and thus a grace period, so the early-boot implementation can +be a no-op. + +<p> +Both <tt>synchronize_rcu_bh()</tt> and <tt>synchronize_sched()</tt> +continue to operate normally through the remainder of boot, courtesy +of the fact that preemption is disabled across their RCU read-side +critical sections and also courtesy of the fact that there is still +only one CPU. +However, once the scheduler starts initializing, preemption is enabled. +There is still only a single CPU, but the fact that preemption is enabled +means that the no-op implementation of <tt>synchronize_rcu()</tt> no +longer works in <tt>CONFIG_PREEMPT=y</tt> kernels. +Therefore, as soon as the scheduler starts initializing, the early-boot +fastpath is disabled. +This means that <tt>synchronize_rcu()</tt> switches to its runtime +mode of operation where it posts callbacks, which in turn means that +any call to <tt>synchronize_rcu()</tt> will block until the corresponding +callback is invoked. +Unfortunately, the callback cannot be invoked until RCU's runtime +grace-period machinery is up and running, which cannot happen until +the scheduler has initialized itself sufficiently to allow RCU's +kthreads to be spawned. +Therefore, invoking <tt>synchronize_rcu()</tt> during scheduler +initialization can result in deadlock. + +<p><a name="Quick Quiz 14"><b>Quick Quiz 14</b>:</a> +So what happens with <tt>synchronize_rcu()</tt> during +scheduler initialization for <tt>CONFIG_PREEMPT=n</tt> +kernels? +<br><a href="#qq14answer">Answer</a> + +<p> +I learned of these boot-time requirements as a result of a series of +system hangs. + +<h3><a name="Interrupts and NMIs">Interrupts and NMIs</a></h3> + +<p> +The Linux kernel has interrupts, and RCU read-side critical sections are +legal within interrupt handlers and within interrupt-disabled regions +of code, as are invocations of <tt>call_rcu()</tt>. + +<p> +Some Linux-kernel architectures can enter an interrupt handler from +non-idle process context, and then just never leave it, instead stealthily +transitioning back to process context. +This trick is sometimes used to invoke system calls from inside the kernel. +These “half-interrupts” mean that RCU has to be very careful +about how it counts interrupt nesting levels. +I learned of this requirement the hard way during a rewrite +of RCU's dyntick-idle code. + +<p> +The Linux kernel has non-maskable interrupts (NMIs), and +RCU read-side critical sections are legal within NMI handlers. +Thankfully, RCU update-side primitives, including +<tt>call_rcu()</tt>, are prohibited within NMI handlers. + +<p> +The name notwithstanding, some Linux-kernel architectures +can have nested NMIs, which RCU must handle correctly. +Andy Lutomirski +<a href="https://lkml.kernel.org/g/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com">surprised me</a> +with this requirement; +he also kindly surprised me with +<a href="https://lkml.kernel.org/g/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com">an algorithm</a> +that meets this requirement. + +<h3><a name="Loadable Modules">Loadable Modules</a></h3> + +<p> +The Linux kernel has loadable modules, and these modules can +also be unloaded. +After a given module has been unloaded, any attempt to call +one of its functions results in a segmentation fault. +The module-unload functions must therefore cancel any +delayed calls to loadable-module functions, for example, +any outstanding <tt>mod_timer()</tt> must be dealt with +via <tt>del_timer_sync()</tt> or similar. + +<p> +Unfortunately, there is no way to cancel an RCU callback; +once you invoke <tt>call_rcu()</tt>, the callback function is +going to eventually be invoked, unless the system goes down first. +Because it is normally considered socially irresponsible to crash the system +in response to a module unload request, we need some other way +to deal with in-flight RCU callbacks. + +<p> +RCU therefore provides +<tt><a href="https://lwn.net/Articles/217484/">rcu_barrier()</a></tt>, +which waits until all in-flight RCU callbacks have been invoked. +If a module uses <tt>call_rcu()</tt>, its exit function should therefore +prevent any future invocation of <tt>call_rcu()</tt>, then invoke +<tt>rcu_barrier()</tt>. +In theory, the underlying module-unload code could invoke +<tt>rcu_barrier()</tt> unconditionally, but in practice this would +incur unacceptable latencies. + +<p> +Nikita Danilov noted this requirement for an analogous filesystem-unmount +situation, and Dipankar Sarma incorporated <tt>rcu_barrier()</tt> into RCU. +The need for <tt>rcu_barrier()</tt> for module unloading became +apparent later. + +<h3><a name="Hotplug CPU">Hotplug CPU</a></h3> + +<p> +The Linux kernel supports CPU hotplug, which means that CPUs +can come and go. +It is of course illegal to use any RCU API member from an offline CPU. +This requirement was present from day one in DYNIX/ptx, but +on the other hand, the Linux kernel's CPU-hotplug implementation +is “interesting.” + +<p> +The Linux-kernel CPU-hotplug implementation has notifiers that +are used to allow the various kernel subsystems (including RCU) +to respond appropriately to a given CPU-hotplug operation. +Most RCU operations may be invoked from CPU-hotplug notifiers, +including even normal synchronous grace-period operations +such as <tt>synchronize_rcu()</tt>. +However, expedited grace-period operations such as +<tt>synchronize_rcu_expedited()</tt> are not supported, +due to the fact that current implementations block CPU-hotplug +operations, which could result in deadlock. + +<p> +In addition, all-callback-wait operations such as +<tt>rcu_barrier()</tt> are also not supported, due to the +fact that there are phases of CPU-hotplug operations where +the outgoing CPU's callbacks will not be invoked until after +the CPU-hotplug operation ends, which could also result in deadlock. + +<h3><a name="Scheduler and RCU">Scheduler and RCU</a></h3> + +<p> +RCU depends on the scheduler, and the scheduler uses RCU to +protect some of its data structures. +This means the scheduler is forbidden from acquiring +the runqueue locks and the priority-inheritance locks +in the middle of an outermost RCU read-side critical section unless either +(1) it releases them before exiting that same +RCU read-side critical section, or +(2) interrupts are disabled across +that entire RCU read-side critical section. +This same prohibition also applies (recursively!) to any lock that is acquired +while holding any lock to which this prohibition applies. +Adhering to this rule prevents preemptible RCU from invoking +<tt>rcu_read_unlock_special()</tt> while either runqueue or +priority-inheritance locks are held, thus avoiding deadlock. + +<p> +Prior to v4.4, it was only necessary to disable preemption across +RCU read-side critical sections that acquired scheduler locks. +In v4.4, expedited grace periods started using IPIs, and these +IPIs could force a <tt>rcu_read_unlock()</tt> to take the slowpath. +Therefore, this expedited-grace-period change required disabling of +interrupts, not just preemption. + +<p> +For RCU's part, the preemptible-RCU <tt>rcu_read_unlock()</tt> +implementation must be written carefully to avoid similar deadlocks. +In particular, <tt>rcu_read_unlock()</tt> must tolerate an +interrupt where the interrupt handler invokes both +<tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>. +This possibility requires <tt>rcu_read_unlock()</tt> to use +negative nesting levels to avoid destructive recursion via +interrupt handler's use of RCU. + +<p> +This pair of mutual scheduler-RCU requirements came as a +<a href="https://lwn.net/Articles/453002/">complete surprise</a>. + +<p> +As noted above, RCU makes use of kthreads, and it is necessary to +avoid excessive CPU-time accumulation by these kthreads. +This requirement was no surprise, but RCU's violation of it +when running context-switch-heavy workloads when built with +<tt>CONFIG_NO_HZ_FULL=y</tt> +<a href="http://www.rdrop.com/users/paulmck/scalability/paper/BareMetal.2015.01.15b.pdf">did come as a surprise [PDF]</a>. +RCU has made good progress towards meeting this requirement, even +for context-switch-have <tt>CONFIG_NO_HZ_FULL=y</tt> workloads, +but there is room for further improvement. + +<h3><a name="Tracing and RCU">Tracing and RCU</a></h3> + +<p> +It is possible to use tracing on RCU code, but tracing itself +uses RCU. +For this reason, <tt>rcu_dereference_raw_notrace()</tt> +is provided for use by tracing, which avoids the destructive +recursion that could otherwise ensue. +This API is also used by virtualization in some architectures, +where RCU readers execute in environments in which tracing +cannot be used. +The tracing folks both located the requirement and provided the +needed fix, so this surprise requirement was relatively painless. + +<h3><a name="Energy Efficiency">Energy Efficiency</a></h3> + +<p> +Interrupting idle CPUs is considered socially unacceptable, +especially by people with battery-powered embedded systems. +RCU therefore conserves energy by detecting which CPUs are +idle, including tracking CPUs that have been interrupted from idle. +This is a large part of the energy-efficiency requirement, +so I learned of this via an irate phone call. + +<p> +Because RCU avoids interrupting idle CPUs, it is illegal to +execute an RCU read-side critical section on an idle CPU. +(Kernels built with <tt>CONFIG_PROVE_RCU=y</tt> will splat +if you try it.) +The <tt>RCU_NONIDLE()</tt> macro and <tt>_rcuidle</tt> +event tracing is provided to work around this restriction. +In addition, <tt>rcu_is_watching()</tt> may be used to +test whether or not it is currently legal to run RCU read-side +critical sections on this CPU. +I learned of the need for diagnostics on the one hand +and <tt>RCU_NONIDLE()</tt> on the other while inspecting +idle-loop code. +Steven Rostedt supplied <tt>_rcuidle</tt> event tracing, +which is used quite heavily in the idle loop. + +<p> +It is similarly socially unacceptable to interrupt an +<tt>nohz_full</tt> CPU running in userspace. +RCU must therefore track <tt>nohz_full</tt> userspace +execution. +And in +<a href="https://lwn.net/Articles/558284/"><tt>CONFIG_NO_HZ_FULL_SYSIDLE=y</tt></a> +kernels, RCU must separately track idle CPUs on the one hand and +CPUs that are either idle or executing in userspace on the other. +In both cases, RCU must be able to sample state at two points in +time, and be able to determine whether or not some other CPU spent +any time idle and/or executing in userspace. + +<p> +These energy-efficiency requirements have proven quite difficult to +understand and to meet, for example, there have been more than five +clean-sheet rewrites of RCU's energy-efficiency code, the last of +which was finally able to demonstrate +<a href="http://www.rdrop.com/users/paulmck/realtime/paper/AMPenergy.2013.04.19a.pdf">real energy savings running on real hardware [PDF]</a>. +As noted earlier, +I learned of many of these requirements via angry phone calls: +Flaming me on the Linux-kernel mailing list was apparently not +sufficient to fully vent their ire at RCU's energy-efficiency bugs! + +<h3><a name="Memory Efficiency">Memory Efficiency</a></h3> + +<p> +Although small-memory non-realtime systems can simply use Tiny RCU, +code size is only one aspect of memory efficiency. +Another aspect is the size of the <tt>rcu_head</tt> structure +used by <tt>call_rcu()</tt> and <tt>kfree_rcu()</tt>. +Although this structure contains nothing more than a pair of pointers, +it does appear in many RCU-protected data structures, including +some that are size critical. +The <tt>page</tt> structure is a case in point, as evidenced by +the many occurrences of the <tt>union</tt> keyword within that structure. + +<p> +This need for memory efficiency is one reason that RCU uses hand-crafted +singly linked lists to track the <tt>rcu_head</tt> structures that +are waiting for a grace period to elapse. +It is also the reason why <tt>rcu_head</tt> structures do not contain +debug information, such as fields tracking the file and line of the +<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt> that posted them. +Although this information might appear in debug-only kernel builds at some +point, in the meantime, the <tt>->func</tt> field will often provide +the needed debug information. + +<p> +However, in some cases, the need for memory efficiency leads to even +more extreme measures. +Returning to the <tt>page</tt> structure, the <tt>rcu_head</tt> field +shares storage with a great many other structures that are used at +various points in the corresponding page's lifetime. +In order to correctly resolve certain +<a href="https://lkml.kernel.org/g/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com">race conditions</a>, +the Linux kernel's memory-management subsystem needs a particular bit +to remain zero during all phases of grace-period processing, +and that bit happens to map to the bottom bit of the +<tt>rcu_head</tt> structure's <tt>->next</tt> field. +RCU makes this guarantee as long as <tt>call_rcu()</tt> +is used to post the callback, as opposed to <tt>kfree_rcu()</tt> +or some future “lazy” +variant of <tt>call_rcu()</tt> that might one day be created for +energy-efficiency purposes. + +<h3><a name="Performance, Scalability, Response Time, and Reliability"> +Performance, Scalability, Response Time, and Reliability</a></h3> + +<p> +Expanding on the +<a href="#Performance and Scalability">earlier discussion</a>, +RCU is used heavily by hot code paths in performance-critical +portions of the Linux kernel's networking, security, virtualization, +and scheduling code paths. +RCU must therefore use efficient implementations, especially in its +read-side primitives. +To that end, it would be good if preemptible RCU's implementation +of <tt>rcu_read_lock()</tt> could be inlined, however, doing +this requires resolving <tt>#include</tt> issues with the +<tt>task_struct</tt> structure. + +<p> +The Linux kernel supports hardware configurations with up to +4096 CPUs, which means that RCU must be extremely scalable. +Algorithms that involve frequent acquisitions of global locks or +frequent atomic operations on global variables simply cannot be +tolerated within the RCU implementation. +RCU therefore makes heavy use of a combining tree based on the +<tt>rcu_node</tt> structure. +RCU is required to tolerate all CPUs continuously invoking any +combination of RCU's runtime primitives with minimal per-operation +overhead. +In fact, in many cases, increasing load must <i>decrease</i> the +per-operation overhead, witness the batching optimizations for +<tt>synchronize_rcu()</tt>, <tt>call_rcu()</tt>, +<tt>synchronize_rcu_expedited()</tt>, and <tt>rcu_barrier()</tt>. +As a general rule, RCU must cheerfully accept whatever the +rest of the Linux kernel decides to throw at it. + +<p> +The Linux kernel is used for real-time workloads, especially +in conjunction with the +<a href="https://rt.wiki.kernel.org/index.php/Main_Page">-rt patchset</a>. +The real-time-latency response requirements are such that the +traditional approach of disabling preemption across RCU +read-side critical sections is inappropriate. +Kernels built with <tt>CONFIG_PREEMPT=y</tt> therefore +use an RCU implementation that allows RCU read-side critical +sections to be preempted. +This requirement made its presence known after users made it +clear that an earlier +<a href="https://lwn.net/Articles/107930/">real-time patch</a> +did not meet their needs, in conjunction with some +<a href="https://lkml.kernel.org/g/20050318002026.GA2693@us.ibm.com">RCU issues</a> +encountered by a very early version of the -rt patchset. + +<p> +In addition, RCU must make do with a sub-100-microsecond real-time latency +budget. +In fact, on smaller systems with the -rt patchset, the Linux kernel +provides sub-20-microsecond real-time latencies for the whole kernel, +including RCU. +RCU's scalability and latency must therefore be sufficient for +these sorts of configurations. +To my surprise, the sub-100-microsecond real-time latency budget +<a href="http://www.rdrop.com/users/paulmck/realtime/paper/bigrt.2013.01.31a.LCA.pdf"> +applies to even the largest systems [PDF]</a>, +up to and including systems with 4096 CPUs. +This real-time requirement motivated the grace-period kthread, which +also simplified handling of a number of race conditions. + +<p> +Finally, RCU's status as a synchronization primitive means that +any RCU failure can result in arbitrary memory corruption that can be +extremely difficult to debug. +This means that RCU must be extremely reliable, which in +practice also means that RCU must have an aggressive stress-test +suite. +This stress-test suite is called <tt>rcutorture</tt>. + +<p> +Although the need for <tt>rcutorture</tt> was no surprise, +the current immense popularity of the Linux kernel is posing +interesting—and perhaps unprecedented—validation +challenges. +To see this, keep in mind that there are well over one billion +instances of the Linux kernel running today, given Android +smartphones, Linux-powered televisions, and servers. +This number can be expected to increase sharply with the advent of +the celebrated Internet of Things. + +<p> +Suppose that RCU contains a race condition that manifests on average +once per million years of runtime. +This bug will be occurring about three times per <i>day</i> across +the installed base. +RCU could simply hide behind hardware error rates, given that no one +should really expect their smartphone to last for a million years. +However, anyone taking too much comfort from this thought should +consider the fact that in most jurisdictions, a successful multi-year +test of a given mechanism, which might include a Linux kernel, +suffices for a number of types of safety-critical certifications. +In fact, rumor has it that the Linux kernel is already being used +in production for safety-critical applications. +I don't know about you, but I would feel quite bad if a bug in RCU +killed someone. +Which might explain my recent focus on validation and verification. + +<h2><a name="Other RCU Flavors">Other RCU Flavors</a></h2> + +<p> +One of the more surprising things about RCU is that there are now +no fewer than five <i>flavors</i>, or API families. +In addition, the primary flavor that has been the sole focus up to +this point has two different implementations, non-preemptible and +preemptible. +The other four flavors are listed below, with requirements for each +described in a separate section. + +<ol> +<li> <a href="#Bottom-Half Flavor">Bottom-Half Flavor</a> +<li> <a href="#Sched Flavor">Sched Flavor</a> +<li> <a href="#Sleepable RCU">Sleepable RCU</a> +<li> <a href="#Tasks RCU">Tasks RCU</a> +</ol> + +<h3><a name="Bottom-Half Flavor">Bottom-Half Flavor</a></h3> + +<p> +The softirq-disable (AKA “bottom-half”, +hence the “_bh” abbreviations) +flavor of RCU, or <i>RCU-bh</i>, was developed by +Dipankar Sarma to provide a flavor of RCU that could withstand the +network-based denial-of-service attacks researched by Robert +Olsson. +These attacks placed so much networking load on the system +that some of the CPUs never exited softirq execution, +which in turn prevented those CPUs from ever executing a context switch, +which, in the RCU implementation of that time, prevented grace periods +from ever ending. +The result was an out-of-memory condition and a system hang. + +<p> +The solution was the creation of RCU-bh, which does +<tt>local_bh_disable()</tt> +across its read-side critical sections, and which uses the transition +from one type of softirq processing to another as a quiescent state +in addition to context switch, idle, user mode, and offline. +This means that RCU-bh grace periods can complete even when some of +the CPUs execute in softirq indefinitely, thus allowing algorithms +based on RCU-bh to withstand network-based denial-of-service attacks. + +<p> +Because +<tt>rcu_read_lock_bh()</tt> and <tt>rcu_read_unlock_bh()</tt> +disable and re-enable softirq handlers, any attempt to start a softirq +handlers during the +RCU-bh read-side critical section will be deferred. +In this case, <tt>rcu_read_unlock_bh()</tt> +will invoke softirq processing, which can take considerable time. +One can of course argue that this softirq overhead should be associated +with the code following the RCU-bh read-side critical section rather +than <tt>rcu_read_unlock_bh()</tt>, but the fact +is that most profiling tools cannot be expected to make this sort +of fine distinction. +For example, suppose that a three-millisecond-long RCU-bh read-side +critical section executes during a time of heavy networking load. +There will very likely be an attempt to invoke at least one softirq +handler during that three milliseconds, but any such invocation will +be delayed until the time of the <tt>rcu_read_unlock_bh()</tt>. +This can of course make it appear at first glance as if +<tt>rcu_read_unlock_bh()</tt> was executing very slowly. + +<p> +The +<a href="https://lwn.net/Articles/609973/#RCU Per-Flavor API Table">RCU-bh API</a> +includes +<tt>rcu_read_lock_bh()</tt>, +<tt>rcu_read_unlock_bh()</tt>, +<tt>rcu_dereference_bh()</tt>, +<tt>rcu_dereference_bh_check()</tt>, +<tt>synchronize_rcu_bh()</tt>, +<tt>synchronize_rcu_bh_expedited()</tt>, +<tt>call_rcu_bh()</tt>, +<tt>rcu_barrier_bh()</tt>, and +<tt>rcu_read_lock_bh_held()</tt>. + +<h3><a name="Sched Flavor">Sched Flavor</a></h3> + +<p> +Before preemptible RCU, waiting for an RCU grace period had the +side effect of also waiting for all pre-existing interrupt +and NMI handlers. +However, there are legitimate preemptible-RCU implementations that +do not have this property, given that any point in the code outside +of an RCU read-side critical section can be a quiescent state. +Therefore, <i>RCU-sched</i> was created, which follows “classic” +RCU in that an RCU-sched grace period waits for for pre-existing +interrupt and NMI handlers. +In kernels built with <tt>CONFIG_PREEMPT=n</tt>, the RCU and RCU-sched +APIs have identical implementations, while kernels built with +<tt>CONFIG_PREEMPT=y</tt> provide a separate implementation for each. + +<p> +Note well that in <tt>CONFIG_PREEMPT=y</tt> kernels, +<tt>rcu_read_lock_sched()</tt> and <tt>rcu_read_unlock_sched()</tt> +disable and re-enable preemption, respectively. +This means that if there was a preemption attempt during the +RCU-sched read-side critical section, <tt>rcu_read_unlock_sched()</tt> +will enter the scheduler, with all the latency and overhead entailed. +Just as with <tt>rcu_read_unlock_bh()</tt>, this can make it look +as if <tt>rcu_read_unlock_sched()</tt> was executing very slowly. +However, the highest-priority task won't be preempted, so that task +will enjoy low-overhead <tt>rcu_read_unlock_sched()</tt> invocations. + +<p> +The +<a href="https://lwn.net/Articles/609973/#RCU Per-Flavor API Table">RCU-sched API</a> +includes +<tt>rcu_read_lock_sched()</tt>, +<tt>rcu_read_unlock_sched()</tt>, +<tt>rcu_read_lock_sched_notrace()</tt>, +<tt>rcu_read_unlock_sched_notrace()</tt>, +<tt>rcu_dereference_sched()</tt>, +<tt>rcu_dereference_sched_check()</tt>, +<tt>synchronize_sched()</tt>, +<tt>synchronize_rcu_sched_expedited()</tt>, +<tt>call_rcu_sched()</tt>, +<tt>rcu_barrier_sched()</tt>, and +<tt>rcu_read_lock_sched_held()</tt>. +However, anything that disables preemption also marks an RCU-sched +read-side critical section, including +<tt>preempt_disable()</tt> and <tt>preempt_enable()</tt>, +<tt>local_irq_save()</tt> and <tt>local_irq_restore()</tt>, +and so on. + +<h3><a name="Sleepable RCU">Sleepable RCU</a></h3> + +<p> +For well over a decade, someone saying “I need to block within +an RCU read-side critical section” was a reliable indication +that this someone did not understand RCU. +After all, if you are always blocking in an RCU read-side critical +section, you can probably afford to use a higher-overhead synchronization +mechanism. +However, that changed with the advent of the Linux kernel's notifiers, +whose RCU read-side critical +sections almost never sleep, but sometimes need to. +This resulted in the introduction of +<a href="https://lwn.net/Articles/202847/">sleepable RCU</a>, +or <i>SRCU</i>. + +<p> +SRCU allows different domains to be defined, with each such domain +defined by an instance of an <tt>srcu_struct</tt> structure. +A pointer to this structure must be passed in to each SRCU function, +for example, <tt>synchronize_srcu(&ss)</tt>, where +<tt>ss</tt> is the <tt>srcu_struct</tt> structure. +The key benefit of these domains is that a slow SRCU reader in one +domain does not delay an SRCU grace period in some other domain. +That said, one consequence of these domains is that read-side code +must pass a “cookie” from <tt>srcu_read_lock()</tt> +to <tt>srcu_read_unlock()</tt>, for example, as follows: + +<blockquote> +<pre> + 1 int idx; + 2 + 3 idx = srcu_read_lock(&ss); + 4 do_something(); + 5 srcu_read_unlock(&ss, idx); +</pre> +</blockquote> + +<p> +As noted above, it is legal to block within SRCU read-side critical sections, +however, with great power comes great responsibility. +If you block forever in one of a given domain's SRCU read-side critical +sections, then that domain's grace periods will also be blocked forever. +Of course, one good way to block forever is to deadlock, which can +happen if any operation in a given domain's SRCU read-side critical +section can block waiting, either directly or indirectly, for that domain's +grace period to elapse. +For example, this results in a self-deadlock: + +<blockquote> +<pre> + 1 int idx; + 2 + 3 idx = srcu_read_lock(&ss); + 4 do_something(); + 5 synchronize_srcu(&ss); + 6 srcu_read_unlock(&ss, idx); +</pre> +</blockquote> + +<p> +However, if line 5 acquired a mutex that was held across +a <tt>synchronize_srcu()</tt> for domain <tt>ss</tt>, +deadlock would still be possible. +Furthermore, if line 5 acquired a mutex that was held across +a <tt>synchronize_srcu()</tt> for some other domain <tt>ss1</tt>, +and if an <tt>ss1</tt>-domain SRCU read-side critical section +acquired another mutex that was held across as <tt>ss</tt>-domain +<tt>synchronize_srcu()</tt>, +deadlock would again be possible. +Such a deadlock cycle could extend across an arbitrarily large number +of different SRCU domains. +Again, with great power comes great responsibility. + +<p> +Unlike the other RCU flavors, SRCU read-side critical sections can +run on idle and even offline CPUs. +This ability requires that <tt>srcu_read_lock()</tt> and +<tt>srcu_read_unlock()</tt> contain memory barriers, which means +that SRCU readers will run a bit slower than would RCU readers. +It also motivates the <tt>smp_mb__after_srcu_read_unlock()</tt> +API, which, in combination with <tt>srcu_read_unlock()</tt>, +guarantees a full memory barrier. + +<p> +The +<a href="https://lwn.net/Articles/609973/#RCU Per-Flavor API Table">SRCU API</a> +includes +<tt>srcu_read_lock()</tt>, +<tt>srcu_read_unlock()</tt>, +<tt>srcu_dereference()</tt>, +<tt>srcu_dereference_check()</tt>, +<tt>synchronize_srcu()</tt>, +<tt>synchronize_srcu_expedited()</tt>, +<tt>call_srcu()</tt>, +<tt>srcu_barrier()</tt>, and +<tt>srcu_read_lock_held()</tt>. +It also includes +<tt>DEFINE_SRCU()</tt>, +<tt>DEFINE_STATIC_SRCU()</tt>, and +<tt>init_srcu_struct()</tt> +APIs for defining and initializing <tt>srcu_struct</tt> structures. + +<h3><a name="Tasks RCU">Tasks RCU</a></h3> + +<p> +Some forms of tracing use “tramopolines” to handle the +binary rewriting required to install different types of probes. +It would be good to be able to free old trampolines, which sounds +like a job for some form of RCU. +However, because it is necessary to be able to install a trace +anywhere in the code, it is not possible to use read-side markers +such as <tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>. +In addition, it does not work to have these markers in the trampoline +itself, because there would need to be instructions following +<tt>rcu_read_unlock()</tt>. +Although <tt>synchronize_rcu()</tt> would guarantee that execution +reached the <tt>rcu_read_unlock()</tt>, it would not be able to +guarantee that execution had completely left the trampoline. + +<p> +The solution, in the form of +<a href="https://lwn.net/Articles/607117/"><i>Tasks RCU</i></a>, +is to have implicit +read-side critical sections that are delimited by voluntary context +switches, that is, calls to <tt>schedule()</tt>, +<tt>cond_resched_rcu_qs()</tt>, and +<tt>synchronize_rcu_tasks()</tt>. +In addition, transitions to and from userspace execution also delimit +tasks-RCU read-side critical sections. + +<p> +The tasks-RCU API is quite compact, consisting only of +<tt>call_rcu_tasks()</tt>, +<tt>synchronize_rcu_tasks()</tt>, and +<tt>rcu_barrier_tasks()</tt>. + +<h2><a name="Possible Future Changes">Possible Future Changes</a></h2> + +<p> +One of the tricks that RCU uses to attain update-side scalability is +to increase grace-period latency with increasing numbers of CPUs. +If this becomes a serious problem, it will be necessary to rework the +grace-period state machine so as to avoid the need for the additional +latency. + +<p> +Expedited grace periods scan the CPUs, so their latency and overhead +increases with increasing numbers of CPUs. +If this becomes a serious problem on large systems, it will be necessary +to do some redesign to avoid this scalability problem. + +<p> +RCU disables CPU hotplug in a few places, perhaps most notably in the +expedited grace-period and <tt>rcu_barrier()</tt> operations. +If there is a strong reason to use expedited grace periods in CPU-hotplug +notifiers, it will be necessary to avoid disabling CPU hotplug. +This would introduce some complexity, so there had better be a <i>very</i> +good reason. + +<p> +The tradeoff between grace-period latency on the one hand and interruptions +of other CPUs on the other hand may need to be re-examined. +The desire is of course for zero grace-period latency as well as zero +interprocessor interrupts undertaken during an expedited grace period +operation. +While this ideal is unlikely to be achievable, it is quite possible that +further improvements can be made. + +<p> +The multiprocessor implementations of RCU use a combining tree that +groups CPUs so as to reduce lock contention and increase cache locality. +However, this combining tree does not spread its memory across NUMA +nodes nor does it align the CPU groups with hardware features such +as sockets or cores. +Such spreading and alignment is currently believed to be unnecessary +because the hotpath read-side primitives do not access the combining +tree, nor does <tt>call_rcu()</tt> in the common case. +If you believe that your architecture needs such spreading and alignment, +then your architecture should also benefit from the +<tt>rcutree.rcu_fanout_leaf</tt> boot parameter, which can be set +to the number of CPUs in a socket, NUMA node, or whatever. +If the number of CPUs is too large, use a fraction of the number of +CPUs. +If the number of CPUs is a large prime number, well, that certainly +is an “interesting” architectural choice! +More flexible arrangements might be considered, but only if +<tt>rcutree.rcu_fanout_leaf</tt> has proven inadequate, and only +if the inadequacy has been demonstrated by a carefully run and +realistic system-level workload. + +<p> +Please note that arrangements that require RCU to remap CPU numbers will +require extremely good demonstration of need and full exploration of +alternatives. + +<p> +There is an embarrassingly large number of flavors of RCU, and this +number has been increasing over time. +Perhaps it will be possible to combine some at some future date. + +<p> +RCU's various kthreads are reasonably recent additions. +It is quite likely that adjustments will be required to more gracefully +handle extreme loads. +It might also be necessary to be able to relate CPU utilization by +RCU's kthreads and softirq handlers to the code that instigated this +CPU utilization. +For example, RCU callback overhead might be charged back to the +originating <tt>call_rcu()</tt> instance, though probably not +in production kernels. + +<h2><a name="Summary">Summary</a></h2> + +<p> +This document has presented more than two decade's worth of RCU +requirements. +Given that the requirements keep changing, this will not be the last +word on this subject, but at least it serves to get an important +subset of the requirements set forth. + +<h2><a name="Acknowledgments">Acknowledgments</a></h2> + +I am grateful to Steven Rostedt, Lai Jiangshan, Ingo Molnar, +Oleg Nesterov, Borislav Petkov, Peter Zijlstra, Boqun Feng, and +Andy Lutomirski for their help in rendering +this article human readable, and to Michelle Rankin for her support +of this effort. +Other contributions are acknowledged in the Linux kernel's git archive. +The cartoon is copyright (c) 2013 by Melissa Broussard, +and is provided +under the terms of the Creative Commons Attribution-Share Alike 3.0 +United States license. + +<h3><a name="Answers to Quick Quizzes"> +Answers to Quick Quizzes</a></h3> + +<a name="qq1answer"></a> +<p><b>Quick Quiz 1</b>: +Wait a minute! +You said that updaters can make useful forward progress concurrently +with readers, but pre-existing readers will block +<tt>synchronize_rcu()</tt>!!! +Just who are you trying to fool??? + + +</p><p><b>Answer</b>: +First, if updaters do not wish to be blocked by readers, they can use +<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt>, which will +be discussed later. +Second, even when using <tt>synchronize_rcu()</tt>, the other +update-side code does run concurrently with readers, whether pre-existing +or not. + + +</p><p><a href="#Quick%20Quiz%201"><b>Back to Quick Quiz 1</b>.</a> + +<a name="qq2answer"></a> +<p><b>Quick Quiz 2</b>: +Why is the <tt>synchronize_rcu()</tt> on line 28 needed? + + +</p><p><b>Answer</b>: +Without that extra grace period, memory reordering could result in +<tt>do_something_dlm()</tt> executing <tt>do_something()</tt> +concurrently with the last bits of <tt>recovery()</tt>. + + +</p><p><a href="#Quick%20Quiz%202"><b>Back to Quick Quiz 2</b>.</a> + +<a name="qq3answer"></a> +<p><b>Quick Quiz 3</b>: +But <tt>rcu_assign_pointer()</tt> does nothing to prevent the +two assignments to <tt>p->a</tt> and <tt>p->b</tt> +from being reordered. +Can't that also cause problems? + + +</p><p><b>Answer</b>: +No, it cannot. +The readers cannot see either of these two fields until +the assignment to <tt>gp</tt>, by which time both fields are +fully initialized. +So reordering the assignments +to <tt>p->a</tt> and <tt>p->b</tt> cannot possibly +cause any problems. + + +</p><p><a href="#Quick%20Quiz%203"><b>Back to Quick Quiz 3</b>.</a> + +<a name="qq4answer"></a> +<p><b>Quick Quiz 4</b>: +Without the <tt>rcu_dereference()</tt> or the +<tt>rcu_access_pointer()</tt>, what destructive optimizations +might the compiler make use of? + + +</p><p><b>Answer</b>: +Let's start with what happens to <tt>do_something_gp()</tt> +if it fails to use <tt>rcu_dereference()</tt>. +It could reuse a value formerly fetched from this same pointer. +It could also fetch the pointer from <tt>gp</tt> in a byte-at-a-time +manner, resulting in <i>load tearing</i>, in turn resulting a bytewise +mash-up of two distince pointer values. +It might even use value-speculation optimizations, where it makes a wrong +guess, but by the time it gets around to checking the value, an update +has changed the pointer to match the wrong guess. +Too bad about any dereferences that returned pre-initialization garbage +in the meantime! + +<p> +For <tt>remove_gp_synchronous()</tt>, as long as all modifications +to <tt>gp</tt> are carried out while holding <tt>gp_lock</tt>, +the above optimizations are harmless. +However, +with <tt>CONFIG_SPARSE_RCU_POINTER=y</tt>, +<tt>sparse</tt> will complain if you +define <tt>gp</tt> with <tt>__rcu</tt> and then +access it without using +either <tt>rcu_access_pointer()</tt> or <tt>rcu_dereference()</tt>. + + +</p><p><a href="#Quick%20Quiz%204"><b>Back to Quick Quiz 4</b>.</a> + +<a name="qq5answer"></a> +<p><b>Quick Quiz 5</b>: +Given that multiple CPUs can start RCU read-side critical sections +at any time without any ordering whatsoever, how can RCU possibly tell whether +or not a given RCU read-side critical section starts before a +given instance of <tt>synchronize_rcu()</tt>? + + +</p><p><b>Answer</b>: +If RCU cannot tell whether or not a given +RCU read-side critical section starts before a +given instance of <tt>synchronize_rcu()</tt>, +then it must assume that the RCU read-side critical section +started first. +In other words, a given instance of <tt>synchronize_rcu()</tt> +can avoid waiting on a given RCU read-side critical section only +if it can prove that <tt>synchronize_rcu()</tt> started first. + + +</p><p><a href="#Quick%20Quiz%205"><b>Back to Quick Quiz 5</b>.</a> + +<a name="qq6answer"></a> +<p><b>Quick Quiz 6</b>: +The first and second guarantees require unbelievably strict ordering! +Are all these memory barriers <i> really</i> required? + + +</p><p><b>Answer</b>: +Yes, they really are required. +To see why the first guarantee is required, consider the following +sequence of events: + +<ol> +<li> CPU 1: <tt>rcu_read_lock()</tt> +<li> CPU 1: <tt>q = rcu_dereference(gp); + /* Very likely to return p. */</tt> +<li> CPU 0: <tt>list_del_rcu(p);</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> starts. +<li> CPU 1: <tt>do_something_with(q->a); + /* No smp_mb(), so might happen after kfree(). */</tt> +<li> CPU 1: <tt>rcu_read_unlock()</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> returns. +<li> CPU 0: <tt>kfree(p);</tt> +</ol> + +<p> +Therefore, there absolutely must be a full memory barrier between the +end of the RCU read-side critical section and the end of the +grace period. + +<p> +The sequence of events demonstrating the necessity of the second rule +is roughly similar: + +<ol> +<li> CPU 0: <tt>list_del_rcu(p);</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> starts. +<li> CPU 1: <tt>rcu_read_lock()</tt> +<li> CPU 1: <tt>q = rcu_dereference(gp); + /* Might return p if no memory barrier. */</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> returns. +<li> CPU 0: <tt>kfree(p);</tt> +<li> CPU 1: <tt>do_something_with(q->a); /* Boom!!! */</tt> +<li> CPU 1: <tt>rcu_read_unlock()</tt> +</ol> + +<p> +And similarly, without a memory barrier between the beginning of the +grace period and the beginning of the RCU read-side critical section, +CPU 1 might end up accessing the freelist. + +<p> +The “as if” rule of course applies, so that any implementation +that acts as if the appropriate memory barriers were in place is a +correct implementation. +That said, it is much easier to fool yourself into believing that you have +adhered to the as-if rule than it is to actually adhere to it! + + +</p><p><a href="#Quick%20Quiz%206"><b>Back to Quick Quiz 6</b>.</a> + +<a name="qq7answer"></a> +<p><b>Quick Quiz 7</b>: +But how does the upgrade-to-write operation exclude other readers? + + +</p><p><b>Answer</b>: +It doesn't, just like normal RCU updates, which also do not exclude +RCU readers. + + +</p><p><a href="#Quick%20Quiz%207"><b>Back to Quick Quiz 7</b>.</a> + +<a name="qq8answer"></a> +<p><b>Quick Quiz 8</b>: +Can't the compiler also reorder this code? + + +</p><p><b>Answer</b>: +No, the volatile casts in <tt>READ_ONCE()</tt> and +<tt>WRITE_ONCE()</tt> prevent the compiler from reordering in +this particular case. + + +</p><p><a href="#Quick%20Quiz%208"><b>Back to Quick Quiz 8</b>.</a> + +<a name="qq9answer"></a> +<p><b>Quick Quiz 9</b>: +Suppose that synchronize_rcu() did wait until all readers had completed. +Would the updater be able to rely on this? + + +</p><p><b>Answer</b>: +No. +Even if <tt>synchronize_rcu()</tt> were to wait until +all readers had completed, a new reader might start immediately after +<tt>synchronize_rcu()</tt> completed. +Therefore, the code following +<tt>synchronize_rcu()</tt> cannot rely on there being no readers +in any case. + + +</p><p><a href="#Quick%20Quiz%209"><b>Back to Quick Quiz 9</b>.</a> + +<a name="qq10answer"></a> +<p><b>Quick Quiz 10</b>: +How long a sequence of grace periods, each separated by an RCU read-side +critical section, would be required to partition the RCU read-side +critical sections at the beginning and end of the chain? + + +</p><p><b>Answer</b>: +In theory, an infinite number. +In practice, an unknown number that is sensitive to both implementation +details and timing considerations. +Therefore, even in practice, RCU users must abide by the theoretical rather +than the practical answer. + + +</p><p><a href="#Quick%20Quiz%2010"><b>Back to Quick Quiz 10</b>.</a> + +<a name="qq11answer"></a> +<p><b>Quick Quiz 11</b>: +What about sleeping locks? + + +</p><p><b>Answer</b>: +These are forbidden within Linux-kernel RCU read-side critical sections +because it is not legal to place a quiescent state (in this case, +voluntary context switch) within an RCU read-side critical section. +However, sleeping locks may be used within userspace RCU read-side critical +sections, and also within Linux-kernel sleepable RCU +<a href="#Sleepable RCU">(SRCU)</a> +read-side critical sections. +In addition, the -rt patchset turns spinlocks into a sleeping locks so +that the corresponding critical sections can be preempted, which +also means that these sleeplockified spinlocks (but not other sleeping locks!) +may be acquire within -rt-Linux-kernel RCU read-side critical sections. + +<p> +Note that it <i>is</i> legal for a normal RCU read-side critical section +to conditionally acquire a sleeping locks (as in <tt>mutex_trylock()</tt>), +but only as long as it does not loop indefinitely attempting to +conditionally acquire that sleeping locks. +The key point is that things like <tt>mutex_trylock()</tt> +either return with the mutex held, or return an error indication if +the mutex was not immediately available. +Either way, <tt>mutex_trylock()</tt> returns immediately without sleeping. + + +</p><p><a href="#Quick%20Quiz%2011"><b>Back to Quick Quiz 11</b>.</a> + +<a name="qq12answer"></a> +<p><b>Quick Quiz 12</b>: +Why does line 19 use <tt>rcu_access_pointer()</tt>? +After all, <tt>call_rcu()</tt> on line 25 stores into the +structure, which would interact badly with concurrent insertions. +Doesn't this mean that <tt>rcu_dereference()</tt> is required? + + +</p><p><b>Answer</b>: +Presumably the <tt>->gp_lock</tt> acquired on line 18 excludes +any changes, including any insertions that <tt>rcu_dereference()</tt> +would protect against. +Therefore, any insertions will be delayed until after <tt>->gp_lock</tt> +is released on line 25, which in turn means that +<tt>rcu_access_pointer()</tt> suffices. + + +</p><p><a href="#Quick%20Quiz%2012"><b>Back to Quick Quiz 12</b>.</a> + +<a name="qq13answer"></a> +<p><b>Quick Quiz 13</b>: +Earlier it was claimed that <tt>call_rcu()</tt> and +<tt>kfree_rcu()</tt> allowed updaters to avoid being blocked +by readers. +But how can that be correct, given that the invocation of the callback +and the freeing of the memory (respectively) must still wait for +a grace period to elapse? + + +</p><p><b>Answer</b>: +We could define things this way, but keep in mind that this sort of +definition would say that updates in garbage-collected languages +cannot complete until the next time the garbage collector runs, +which does not seem at all reasonable. +The key point is that in most cases, an updater using either +<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt> can proceed to the +next update as soon as it has invoked <tt>call_rcu()</tt> or +<tt>kfree_rcu()</tt>, without having to wait for a subsequent +grace period. + + +</p><p><a href="#Quick%20Quiz%2013"><b>Back to Quick Quiz 13</b>.</a> + +<a name="qq14answer"></a> +<p><b>Quick Quiz 14</b>: +So what happens with <tt>synchronize_rcu()</tt> during +scheduler initialization for <tt>CONFIG_PREEMPT=n</tt> +kernels? + + +</p><p><b>Answer</b>: +In <tt>CONFIG_PREEMPT=n</tt> kernel, <tt>synchronize_rcu()</tt> +maps directly to <tt>synchronize_sched()</tt>. +Therefore, <tt>synchronize_rcu()</tt> works normally throughout +boot in <tt>CONFIG_PREEMPT=n</tt> kernels. +However, your code must also work in <tt>CONFIG_PREEMPT=y</tt> kernels, +so it is still necessary to avoid invoking <tt>synchronize_rcu()</tt> +during scheduler initialization. + + +</p><p><a href="#Quick%20Quiz%2014"><b>Back to Quick Quiz 14</b>.</a> + + +</body></html> diff --git a/Documentation/RCU/Design/Requirements/Requirements.htmlx b/Documentation/RCU/Design/Requirements/Requirements.htmlx new file mode 100644 index 000000000000..3a97ba490c42 --- /dev/null +++ b/Documentation/RCU/Design/Requirements/Requirements.htmlx @@ -0,0 +1,2741 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + <html> + <head><title>A Tour Through RCU's Requirements [LWN.net]</title> + <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8"> + +<h1>A Tour Through RCU's Requirements</h1> + +<p>Copyright IBM Corporation, 2015</p> +<p>Author: Paul E. McKenney</p> +<p><i>The initial version of this document appeared in the +<a href="https://lwn.net/">LWN</a> articles +<a href="https://lwn.net/Articles/652156/">here</a>, +<a href="https://lwn.net/Articles/652677/">here</a>, and +<a href="https://lwn.net/Articles/653326/">here</a>.</i></p> + +<h2>Introduction</h2> + +<p> +Read-copy update (RCU) is a synchronization mechanism that is often +used as a replacement for reader-writer locking. +RCU is unusual in that updaters do not block readers, +which means that RCU's read-side primitives can be exceedingly fast +and scalable. +In addition, updaters can make useful forward progress concurrently +with readers. +However, all this concurrency between RCU readers and updaters does raise +the question of exactly what RCU readers are doing, which in turn +raises the question of exactly what RCU's requirements are. + +<p> +This document therefore summarizes RCU's requirements, and can be thought +of as an informal, high-level specification for RCU. +It is important to understand that RCU's specification is primarily +empirical in nature; +in fact, I learned about many of these requirements the hard way. +This situation might cause some consternation, however, not only +has this learning process been a lot of fun, but it has also been +a great privilege to work with so many people willing to apply +technologies in interesting new ways. + +<p> +All that aside, here are the categories of currently known RCU requirements: +</p> + +<ol> +<li> <a href="#Fundamental Requirements"> + Fundamental Requirements</a> +<li> <a href="#Fundamental Non-Requirements">Fundamental Non-Requirements</a> +<li> <a href="#Parallelism Facts of Life"> + Parallelism Facts of Life</a> +<li> <a href="#Quality-of-Implementation Requirements"> + Quality-of-Implementation Requirements</a> +<li> <a href="#Linux Kernel Complications"> + Linux Kernel Complications</a> +<li> <a href="#Software-Engineering Requirements"> + Software-Engineering Requirements</a> +<li> <a href="#Other RCU Flavors"> + Other RCU Flavors</a> +<li> <a href="#Possible Future Changes"> + Possible Future Changes</a> +</ol> + +<p> +This is followed by a <a href="#Summary">summary</a>, +which is in turn followed by the inevitable +<a href="#Answers to Quick Quizzes">answers to the quick quizzes</a>. + +<h2><a name="Fundamental Requirements">Fundamental Requirements</a></h2> + +<p> +RCU's fundamental requirements are the closest thing RCU has to hard +mathematical requirements. +These are: + +<ol> +<li> <a href="#Grace-Period Guarantee"> + Grace-Period Guarantee</a> +<li> <a href="#Publish-Subscribe Guarantee"> + Publish-Subscribe Guarantee</a> +<li> <a href="#Memory-Barrier Guarantees"> + Memory-Barrier Guarantees</a> +<li> <a href="#RCU Primitives Guaranteed to Execute Unconditionally"> + RCU Primitives Guaranteed to Execute Unconditionally</a> +<li> <a href="#Guaranteed Read-to-Write Upgrade"> + Guaranteed Read-to-Write Upgrade</a> +</ol> + +<h3><a name="Grace-Period Guarantee">Grace-Period Guarantee</a></h3> + +<p> +RCU's grace-period guarantee is unusual in being premeditated: +Jack Slingwine and I had this guarantee firmly in mind when we started +work on RCU (then called “rclock”) in the early 1990s. +That said, the past two decades of experience with RCU have produced +a much more detailed understanding of this guarantee. + +<p> +RCU's grace-period guarantee allows updaters to wait for the completion +of all pre-existing RCU read-side critical sections. +An RCU read-side critical section +begins with the marker <tt>rcu_read_lock()</tt> and ends with +the marker <tt>rcu_read_unlock()</tt>. +These markers may be nested, and RCU treats a nested set as one +big RCU read-side critical section. +Production-quality implementations of <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> are extremely lightweight, and in +fact have exactly zero overhead in Linux kernels built for production +use with <tt>CONFIG_PREEMPT=n</tt>. + +<p> +This guarantee allows ordering to be enforced with extremely low +overhead to readers, for example: + +<blockquote> +<pre> + 1 int x, y; + 2 + 3 void thread0(void) + 4 { + 5 rcu_read_lock(); + 6 r1 = READ_ONCE(x); + 7 r2 = READ_ONCE(y); + 8 rcu_read_unlock(); + 9 } +10 +11 void thread1(void) +12 { +13 WRITE_ONCE(x, 1); +14 synchronize_rcu(); +15 WRITE_ONCE(y, 1); +16 } +</pre> +</blockquote> + +<p> +Because the <tt>synchronize_rcu()</tt> on line 14 waits for +all pre-existing readers, any instance of <tt>thread0()</tt> that +loads a value of zero from <tt>x</tt> must complete before +<tt>thread1()</tt> stores to <tt>y</tt>, so that instance must +also load a value of zero from <tt>y</tt>. +Similarly, any instance of <tt>thread0()</tt> that loads a value of +one from <tt>y</tt> must have started after the +<tt>synchronize_rcu()</tt> started, and must therefore also load +a value of one from <tt>x</tt>. +Therefore, the outcome: +<blockquote> +<pre> +(r1 == 0 && r2 == 1) +</pre> +</blockquote> +cannot happen. + +<p>@@QQ@@ +Wait a minute! +You said that updaters can make useful forward progress concurrently +with readers, but pre-existing readers will block +<tt>synchronize_rcu()</tt>!!! +Just who are you trying to fool??? +<p>@@QQA@@ +First, if updaters do not wish to be blocked by readers, they can use +<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt>, which will +be discussed later. +Second, even when using <tt>synchronize_rcu()</tt>, the other +update-side code does run concurrently with readers, whether pre-existing +or not. +<p>@@QQE@@ + +<p> +This scenario resembles one of the first uses of RCU in +<a href="https://en.wikipedia.org/wiki/DYNIX">DYNIX/ptx</a>, +which managed a distributed lock manager's transition into +a state suitable for handling recovery from node failure, +more or less as follows: + +<blockquote> +<pre> + 1 #define STATE_NORMAL 0 + 2 #define STATE_WANT_RECOVERY 1 + 3 #define STATE_RECOVERING 2 + 4 #define STATE_WANT_NORMAL 3 + 5 + 6 int state = STATE_NORMAL; + 7 + 8 void do_something_dlm(void) + 9 { +10 int state_snap; +11 +12 rcu_read_lock(); +13 state_snap = READ_ONCE(state); +14 if (state_snap == STATE_NORMAL) +15 do_something(); +16 else +17 do_something_carefully(); +18 rcu_read_unlock(); +19 } +20 +21 void start_recovery(void) +22 { +23 WRITE_ONCE(state, STATE_WANT_RECOVERY); +24 synchronize_rcu(); +25 WRITE_ONCE(state, STATE_RECOVERING); +26 recovery(); +27 WRITE_ONCE(state, STATE_WANT_NORMAL); +28 synchronize_rcu(); +29 WRITE_ONCE(state, STATE_NORMAL); +30 } +</pre> +</blockquote> + +<p> +The RCU read-side critical section in <tt>do_something_dlm()</tt> +works with the <tt>synchronize_rcu()</tt> in <tt>start_recovery()</tt> +to guarantee that <tt>do_something()</tt> never runs concurrently +with <tt>recovery()</tt>, but with little or no synchronization +overhead in <tt>do_something_dlm()</tt>. + +<p>@@QQ@@ +Why is the <tt>synchronize_rcu()</tt> on line 28 needed? +<p>@@QQA@@ +Without that extra grace period, memory reordering could result in +<tt>do_something_dlm()</tt> executing <tt>do_something()</tt> +concurrently with the last bits of <tt>recovery()</tt>. +<p>@@QQE@@ + +<p> +In order to avoid fatal problems such as deadlocks, +an RCU read-side critical section must not contain calls to +<tt>synchronize_rcu()</tt>. +Similarly, an RCU read-side critical section must not +contain anything that waits, directly or indirectly, on completion of +an invocation of <tt>synchronize_rcu()</tt>. + +<p> +Although RCU's grace-period guarantee is useful in and of itself, with +<a href="https://lwn.net/Articles/573497/">quite a few use cases</a>, +it would be good to be able to use RCU to coordinate read-side +access to linked data structures. +For this, the grace-period guarantee is not sufficient, as can +be seen in function <tt>add_gp_buggy()</tt> below. +We will look at the reader's code later, but in the meantime, just think of +the reader as locklessly picking up the <tt>gp</tt> pointer, +and, if the value loaded is non-<tt>NULL</tt>, locklessly accessing the +<tt>->a</tt> and <tt>->b</tt> fields. + +<blockquote> +<pre> + 1 bool add_gp_buggy(int a, int b) + 2 { + 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 4 if (!p) + 5 return -ENOMEM; + 6 spin_lock(&gp_lock); + 7 if (rcu_access_pointer(gp)) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +11 p->a = a; +12 p->b = a; +13 gp = p; /* ORDERING BUG */ +14 spin_unlock(&gp_lock); +15 return true; +16 } +</pre> +</blockquote> + +<p> +The problem is that both the compiler and weakly ordered CPUs are within +their rights to reorder this code as follows: + +<blockquote> +<pre> + 1 bool add_gp_buggy_optimized(int a, int b) + 2 { + 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 4 if (!p) + 5 return -ENOMEM; + 6 spin_lock(&gp_lock); + 7 if (rcu_access_pointer(gp)) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +<b>11 gp = p; /* ORDERING BUG */ +12 p->a = a; +13 p->b = a;</b> +14 spin_unlock(&gp_lock); +15 return true; +16 } +</pre> +</blockquote> + +<p> +If an RCU reader fetches <tt>gp</tt> just after +<tt>add_gp_buggy_optimized</tt> executes line 11, +it will see garbage in the <tt>->a</tt> and <tt>->b</tt> +fields. +And this is but one of many ways in which compiler and hardware optimizations +could cause trouble. +Therefore, we clearly need some way to prevent the compiler and the CPU from +reordering in this manner, which brings us to the publish-subscribe +guarantee discussed in the next section. + +<h3><a name="Publish-Subscribe Guarantee">Publish/Subscribe Guarantee</a></h3> + +<p> +RCU's publish-subscribe guarantee allows data to be inserted +into a linked data structure without disrupting RCU readers. +The updater uses <tt>rcu_assign_pointer()</tt> to insert the +new data, and readers use <tt>rcu_dereference()</tt> to +access data, whether new or old. +The following shows an example of insertion: + +<blockquote> +<pre> + 1 bool add_gp(int a, int b) + 2 { + 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 4 if (!p) + 5 return -ENOMEM; + 6 spin_lock(&gp_lock); + 7 if (rcu_access_pointer(gp)) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +11 p->a = a; +12 p->b = a; +13 rcu_assign_pointer(gp, p); +14 spin_unlock(&gp_lock); +15 return true; +16 } +</pre> +</blockquote> + +<p> +The <tt>rcu_assign_pointer()</tt> on line 13 is conceptually +equivalent to a simple assignment statement, but also guarantees +that its assignment will +happen after the two assignments in lines 11 and 12, +similar to the C11 <tt>memory_order_release</tt> store operation. +It also prevents any number of “interesting” compiler +optimizations, for example, the use of <tt>gp</tt> as a scratch +location immediately preceding the assignment. + +<p>@@QQ@@ +But <tt>rcu_assign_pointer()</tt> does nothing to prevent the +two assignments to <tt>p->a</tt> and <tt>p->b</tt> +from being reordered. +Can't that also cause problems? +<p>@@QQA@@ +No, it cannot. +The readers cannot see either of these two fields until +the assignment to <tt>gp</tt>, by which time both fields are +fully initialized. +So reordering the assignments +to <tt>p->a</tt> and <tt>p->b</tt> cannot possibly +cause any problems. +<p>@@QQE@@ + +<p> +It is tempting to assume that the reader need not do anything special +to control its accesses to the RCU-protected data, +as shown in <tt>do_something_gp_buggy()</tt> below: + +<blockquote> +<pre> + 1 bool do_something_gp_buggy(void) + 2 { + 3 rcu_read_lock(); + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */ + 5 if (p) { + 6 do_something(p->a, p->b); + 7 rcu_read_unlock(); + 8 return true; + 9 } +10 rcu_read_unlock(); +11 return false; +12 } +</pre> +</blockquote> + +<p> +However, this temptation must be resisted because there are a +surprisingly large number of ways that the compiler +(to say nothing of +<a href="https://h71000.www7.hp.com/wizard/wiz_2637.html">DEC Alpha CPUs</a>) +can trip this code up. +For but one example, if the compiler were short of registers, it +might choose to refetch from <tt>gp</tt> rather than keeping +a separate copy in <tt>p</tt> as follows: + +<blockquote> +<pre> + 1 bool do_something_gp_buggy_optimized(void) + 2 { + 3 rcu_read_lock(); + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */ +<b> 5 do_something(gp->a, gp->b);</b> + 6 rcu_read_unlock(); + 7 return true; + 8 } + 9 rcu_read_unlock(); +10 return false; +11 } +</pre> +</blockquote> + +<p> +If this function ran concurrently with a series of updates that +replaced the current structure with a new one, +the fetches of <tt>gp->a</tt> +and <tt>gp->b</tt> might well come from two different structures, +which could cause serious confusion. +To prevent this (and much else besides), <tt>do_something_gp()</tt> uses +<tt>rcu_dereference()</tt> to fetch from <tt>gp</tt>: + +<blockquote> +<pre> + 1 bool do_something_gp(void) + 2 { + 3 rcu_read_lock(); + 4 p = rcu_dereference(gp); + 5 if (p) { + 6 do_something(p->a, p->b); + 7 rcu_read_unlock(); + 8 return true; + 9 } +10 rcu_read_unlock(); +11 return false; +12 } +</pre> +</blockquote> + +<p> +The <tt>rcu_dereference()</tt> uses volatile casts and (for DEC Alpha) +memory barriers in the Linux kernel. +Should a +<a href="http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf">high-quality implementation of C11 <tt>memory_order_consume</tt> [PDF]</a> +ever appear, then <tt>rcu_dereference()</tt> could be implemented +as a <tt>memory_order_consume</tt> load. +Regardless of the exact implementation, a pointer fetched by +<tt>rcu_dereference()</tt> may not be used outside of the +outermost RCU read-side critical section containing that +<tt>rcu_dereference()</tt>, unless protection of +the corresponding data element has been passed from RCU to some +other synchronization mechanism, most commonly locking or +<a href="https://www.kernel.org/doc/Documentation/RCU/rcuref.txt">reference counting</a>. + +<p> +In short, updaters use <tt>rcu_assign_pointer()</tt> and readers +use <tt>rcu_dereference()</tt>, and these two RCU API elements +work together to ensure that readers have a consistent view of +newly added data elements. + +<p> +Of course, it is also necessary to remove elements from RCU-protected +data structures, for example, using the following process: + +<ol> +<li> Remove the data element from the enclosing structure. +<li> Wait for all pre-existing RCU read-side critical sections + to complete (because only pre-existing readers can possibly have + a reference to the newly removed data element). +<li> At this point, only the updater has a reference to the + newly removed data element, so it can safely reclaim + the data element, for example, by passing it to <tt>kfree()</tt>. +</ol> + +This process is implemented by <tt>remove_gp_synchronous()</tt>: + +<blockquote> +<pre> + 1 bool remove_gp_synchronous(void) + 2 { + 3 struct foo *p; + 4 + 5 spin_lock(&gp_lock); + 6 p = rcu_access_pointer(gp); + 7 if (!p) { + 8 spin_unlock(&gp_lock); + 9 return false; +10 } +11 rcu_assign_pointer(gp, NULL); +12 spin_unlock(&gp_lock); +13 synchronize_rcu(); +14 kfree(p); +15 return true; +16 } +</pre> +</blockquote> + +<p> +This function is straightforward, with line 13 waiting for a grace +period before line 14 frees the old data element. +This waiting ensures that readers will reach line 7 of +<tt>do_something_gp()</tt> before the data element referenced by +<tt>p</tt> is freed. +The <tt>rcu_access_pointer()</tt> on line 6 is similar to +<tt>rcu_dereference()</tt>, except that: + +<ol> +<li> The value returned by <tt>rcu_access_pointer()</tt> + cannot be dereferenced. + If you want to access the value pointed to as well as + the pointer itself, use <tt>rcu_dereference()</tt> + instead of <tt>rcu_access_pointer()</tt>. +<li> The call to <tt>rcu_access_pointer()</tt> need not be + protected. + In contrast, <tt>rcu_dereference()</tt> must either be + within an RCU read-side critical section or in a code + segment where the pointer cannot change, for example, in + code protected by the corresponding update-side lock. +</ol> + +<p>@@QQ@@ +Without the <tt>rcu_dereference()</tt> or the +<tt>rcu_access_pointer()</tt>, what destructive optimizations +might the compiler make use of? +<p>@@QQA@@ +Let's start with what happens to <tt>do_something_gp()</tt> +if it fails to use <tt>rcu_dereference()</tt>. +It could reuse a value formerly fetched from this same pointer. +It could also fetch the pointer from <tt>gp</tt> in a byte-at-a-time +manner, resulting in <i>load tearing</i>, in turn resulting a bytewise +mash-up of two distince pointer values. +It might even use value-speculation optimizations, where it makes a wrong +guess, but by the time it gets around to checking the value, an update +has changed the pointer to match the wrong guess. +Too bad about any dereferences that returned pre-initialization garbage +in the meantime! + +<p> +For <tt>remove_gp_synchronous()</tt>, as long as all modifications +to <tt>gp</tt> are carried out while holding <tt>gp_lock</tt>, +the above optimizations are harmless. +However, +with <tt>CONFIG_SPARSE_RCU_POINTER=y</tt>, +<tt>sparse</tt> will complain if you +define <tt>gp</tt> with <tt>__rcu</tt> and then +access it without using +either <tt>rcu_access_pointer()</tt> or <tt>rcu_dereference()</tt>. +<p>@@QQE@@ + +<p> +In short, RCU's publish-subscribe guarantee is provided by the combination +of <tt>rcu_assign_pointer()</tt> and <tt>rcu_dereference()</tt>. +This guarantee allows data elements to be safely added to RCU-protected +linked data structures without disrupting RCU readers. +This guarantee can be used in combination with the grace-period +guarantee to also allow data elements to be removed from RCU-protected +linked data structures, again without disrupting RCU readers. + +<p> +This guarantee was only partially premeditated. +DYNIX/ptx used an explicit memory barrier for publication, but had nothing +resembling <tt>rcu_dereference()</tt> for subscription, nor did it +have anything resembling the <tt>smp_read_barrier_depends()</tt> +that was later subsumed into <tt>rcu_dereference()</tt>. +The need for these operations made itself known quite suddenly at a +late-1990s meeting with the DEC Alpha architects, back in the days when +DEC was still a free-standing company. +It took the Alpha architects a good hour to convince me that any sort +of barrier would ever be needed, and it then took me a good <i>two</i> hours +to convince them that their documentation did not make this point clear. +More recent work with the C and C++ standards committees have provided +much education on tricks and traps from the compiler. +In short, compilers were much less tricky in the early 1990s, but in +2015, don't even think about omitting <tt>rcu_dereference()</tt>! + +<h3><a name="Memory-Barrier Guarantees">Memory-Barrier Guarantees</a></h3> + +<p> +The previous section's simple linked-data-structure scenario clearly +demonstrates the need for RCU's stringent memory-ordering guarantees on +systems with more than one CPU: + +<ol> +<li> Each CPU that has an RCU read-side critical section that + begins before <tt>synchronize_rcu()</tt> starts is + guaranteed to execute a full memory barrier between the time + that the RCU read-side critical section ends and the time that + <tt>synchronize_rcu()</tt> returns. + Without this guarantee, a pre-existing RCU read-side critical section + might hold a reference to the newly removed <tt>struct foo</tt> + after the <tt>kfree()</tt> on line 14 of + <tt>remove_gp_synchronous()</tt>. +<li> Each CPU that has an RCU read-side critical section that ends + after <tt>synchronize_rcu()</tt> returns is guaranteed + to execute a full memory barrier between the time that + <tt>synchronize_rcu()</tt> begins and the time that the RCU + read-side critical section begins. + Without this guarantee, a later RCU read-side critical section + running after the <tt>kfree()</tt> on line 14 of + <tt>remove_gp_synchronous()</tt> might + later run <tt>do_something_gp()</tt> and find the + newly deleted <tt>struct foo</tt>. +<li> If the task invoking <tt>synchronize_rcu()</tt> remains + on a given CPU, then that CPU is guaranteed to execute a full + memory barrier sometime during the execution of + <tt>synchronize_rcu()</tt>. + This guarantee ensures that the <tt>kfree()</tt> on + line 14 of <tt>remove_gp_synchronous()</tt> really does + execute after the removal on line 11. +<li> If the task invoking <tt>synchronize_rcu()</tt> migrates + among a group of CPUs during that invocation, then each of the + CPUs in that group is guaranteed to execute a full memory barrier + sometime during the execution of <tt>synchronize_rcu()</tt>. + This guarantee also ensures that the <tt>kfree()</tt> on + line 14 of <tt>remove_gp_synchronous()</tt> really does + execute after the removal on + line 11, but also in the case where the thread executing the + <tt>synchronize_rcu()</tt> migrates in the meantime. +</ol> + +<p>@@QQ@@ +Given that multiple CPUs can start RCU read-side critical sections +at any time without any ordering whatsoever, how can RCU possibly tell whether +or not a given RCU read-side critical section starts before a +given instance of <tt>synchronize_rcu()</tt>? +<p>@@QQA@@ +If RCU cannot tell whether or not a given +RCU read-side critical section starts before a +given instance of <tt>synchronize_rcu()</tt>, +then it must assume that the RCU read-side critical section +started first. +In other words, a given instance of <tt>synchronize_rcu()</tt> +can avoid waiting on a given RCU read-side critical section only +if it can prove that <tt>synchronize_rcu()</tt> started first. +<p>@@QQE@@ + +<p>@@QQ@@ +The first and second guarantees require unbelievably strict ordering! +Are all these memory barriers <i> really</i> required? +<p>@@QQA@@ +Yes, they really are required. +To see why the first guarantee is required, consider the following +sequence of events: + +<ol> +<li> CPU 1: <tt>rcu_read_lock()</tt> +<li> CPU 1: <tt>q = rcu_dereference(gp); + /* Very likely to return p. */</tt> +<li> CPU 0: <tt>list_del_rcu(p);</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> starts. +<li> CPU 1: <tt>do_something_with(q->a); + /* No smp_mb(), so might happen after kfree(). */</tt> +<li> CPU 1: <tt>rcu_read_unlock()</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> returns. +<li> CPU 0: <tt>kfree(p);</tt> +</ol> + +<p> +Therefore, there absolutely must be a full memory barrier between the +end of the RCU read-side critical section and the end of the +grace period. + +<p> +The sequence of events demonstrating the necessity of the second rule +is roughly similar: + +<ol> +<li> CPU 0: <tt>list_del_rcu(p);</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> starts. +<li> CPU 1: <tt>rcu_read_lock()</tt> +<li> CPU 1: <tt>q = rcu_dereference(gp); + /* Might return p if no memory barrier. */</tt> +<li> CPU 0: <tt>synchronize_rcu()</tt> returns. +<li> CPU 0: <tt>kfree(p);</tt> +<li> CPU 1: <tt>do_something_with(q->a); /* Boom!!! */</tt> +<li> CPU 1: <tt>rcu_read_unlock()</tt> +</ol> + +<p> +And similarly, without a memory barrier between the beginning of the +grace period and the beginning of the RCU read-side critical section, +CPU 1 might end up accessing the freelist. + +<p> +The “as if” rule of course applies, so that any implementation +that acts as if the appropriate memory barriers were in place is a +correct implementation. +That said, it is much easier to fool yourself into believing that you have +adhered to the as-if rule than it is to actually adhere to it! +<p>@@QQE@@ + +<p> +Note that these memory-barrier requirements do not replace the fundamental +RCU requirement that a grace period wait for all pre-existing readers. +On the contrary, the memory barriers called out in this section must operate in +such a way as to <i>enforce</i> this fundamental requirement. +Of course, different implementations enforce this requirement in different +ways, but enforce it they must. + +<h3><a name="RCU Primitives Guaranteed to Execute Unconditionally">RCU Primitives Guaranteed to Execute Unconditionally</a></h3> + +<p> +The common-case RCU primitives are unconditional. +They are invoked, they do their job, and they return, with no possibility +of error, and no need to retry. +This is a key RCU design philosophy. + +<p> +However, this philosophy is pragmatic rather than pigheaded. +If someone comes up with a good justification for a particular conditional +RCU primitive, it might well be implemented and added. +After all, this guarantee was reverse-engineered, not premeditated. +The unconditional nature of the RCU primitives was initially an +accident of implementation, and later experience with synchronization +primitives with conditional primitives caused me to elevate this +accident to a guarantee. +Therefore, the justification for adding a conditional primitive to +RCU would need to be based on detailed and compelling use cases. + +<h3><a name="Guaranteed Read-to-Write Upgrade">Guaranteed Read-to-Write Upgrade</a></h3> + +<p> +As far as RCU is concerned, it is always possible to carry out an +update within an RCU read-side critical section. +For example, that RCU read-side critical section might search for +a given data element, and then might acquire the update-side +spinlock in order to update that element, all while remaining +in that RCU read-side critical section. +Of course, it is necessary to exit the RCU read-side critical section +before invoking <tt>synchronize_rcu()</tt>, however, this +inconvenience can be avoided through use of the +<tt>call_rcu()</tt> and <tt>kfree_rcu()</tt> API members +described later in this document. + +<p>@@QQ@@ +But how does the upgrade-to-write operation exclude other readers? +<p>@@QQA@@ +It doesn't, just like normal RCU updates, which also do not exclude +RCU readers. +<p>@@QQE@@ + +<p> +This guarantee allows lookup code to be shared between read-side +and update-side code, and was premeditated, appearing in the earliest +DYNIX/ptx RCU documentation. + +<h2><a name="Fundamental Non-Requirements">Fundamental Non-Requirements</a></h2> + +<p> +RCU provides extremely lightweight readers, and its read-side guarantees, +though quite useful, are correspondingly lightweight. +It is therefore all too easy to assume that RCU is guaranteeing more +than it really is. +Of course, the list of things that RCU does not guarantee is infinitely +long, however, the following sections list a few non-guarantees that +have caused confusion. +Except where otherwise noted, these non-guarantees were premeditated. + +<ol> +<li> <a href="#Readers Impose Minimal Ordering"> + Readers Impose Minimal Ordering</a> +<li> <a href="#Readers Do Not Exclude Updaters"> + Readers Do Not Exclude Updaters</a> +<li> <a href="#Updaters Only Wait For Old Readers"> + Updaters Only Wait For Old Readers</a> +<li> <a href="#Grace Periods Don't Partition Read-Side Critical Sections"> + Grace Periods Don't Partition Read-Side Critical Sections</a> +<li> <a href="#Read-Side Critical Sections Don't Partition Grace Periods"> + Read-Side Critical Sections Don't Partition Grace Periods</a> +<li> <a href="#Disabling Preemption Does Not Block Grace Periods"> + Disabling Preemption Does Not Block Grace Periods</a> +</ol> + +<h3><a name="Readers Impose Minimal Ordering">Readers Impose Minimal Ordering</a></h3> + +<p> +Reader-side markers such as <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> provide absolutely no ordering guarantees +except through their interaction with the grace-period APIs such as +<tt>synchronize_rcu()</tt>. +To see this, consider the following pair of threads: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(x, 1); + 5 rcu_read_unlock(); + 6 rcu_read_lock(); + 7 WRITE_ONCE(y, 1); + 8 rcu_read_unlock(); + 9 } +10 +11 void thread1(void) +12 { +13 rcu_read_lock(); +14 r1 = READ_ONCE(y); +15 rcu_read_unlock(); +16 rcu_read_lock(); +17 r2 = READ_ONCE(x); +18 rcu_read_unlock(); +19 } +</pre> +</blockquote> + +<p> +After <tt>thread0()</tt> and <tt>thread1()</tt> execute +concurrently, it is quite possible to have + +<blockquote> +<pre> +(r1 == 1 && r2 == 0) +</pre> +</blockquote> + +(that is, <tt>y</tt> appears to have been assigned before <tt>x</tt>), +which would not be possible if <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> had much in the way of ordering +properties. +But they do not, so the CPU is within its rights +to do significant reordering. +This is by design: Any significant ordering constraints would slow down +these fast-path APIs. + +<p>@@QQ@@ +Can't the compiler also reorder this code? +<p>@@QQA@@ +No, the volatile casts in <tt>READ_ONCE()</tt> and +<tt>WRITE_ONCE()</tt> prevent the compiler from reordering in +this particular case. +<p>@@QQE@@ + +<h3><a name="Readers Do Not Exclude Updaters">Readers Do Not Exclude Updaters</a></h3> + +<p> +Neither <tt>rcu_read_lock()</tt> nor <tt>rcu_read_unlock()</tt> +exclude updates. +All they do is to prevent grace periods from ending. +The following example illustrates this: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 r1 = READ_ONCE(y); + 5 if (r1) { + 6 do_something_with_nonzero_x(); + 7 r2 = READ_ONCE(x); + 8 WARN_ON(!r2); /* BUG!!! */ + 9 } +10 rcu_read_unlock(); +11 } +12 +13 void thread1(void) +14 { +15 spin_lock(&my_lock); +16 WRITE_ONCE(x, 1); +17 WRITE_ONCE(y, 1); +18 spin_unlock(&my_lock); +19 } +</pre> +</blockquote> + +<p> +If the <tt>thread0()</tt> function's <tt>rcu_read_lock()</tt> +excluded the <tt>thread1()</tt> function's update, +the <tt>WARN_ON()</tt> could never fire. +But the fact is that <tt>rcu_read_lock()</tt> does not exclude +much of anything aside from subsequent grace periods, of which +<tt>thread1()</tt> has none, so the +<tt>WARN_ON()</tt> can and does fire. + +<h3><a name="Updaters Only Wait For Old Readers">Updaters Only Wait For Old Readers</a></h3> + +<p> +It might be tempting to assume that after <tt>synchronize_rcu()</tt> +completes, there are no readers executing. +This temptation must be avoided because +new readers can start immediately after <tt>synchronize_rcu()</tt> +starts, and <tt>synchronize_rcu()</tt> is under no +obligation to wait for these new readers. + +<p>@@QQ@@ +Suppose that synchronize_rcu() did wait until all readers had completed. +Would the updater be able to rely on this? +<p>@@QQA@@ +No. +Even if <tt>synchronize_rcu()</tt> were to wait until +all readers had completed, a new reader might start immediately after +<tt>synchronize_rcu()</tt> completed. +Therefore, the code following +<tt>synchronize_rcu()</tt> cannot rely on there being no readers +in any case. +<p>@@QQE@@ + +<h3><a name="Grace Periods Don't Partition Read-Side Critical Sections"> +Grace Periods Don't Partition Read-Side Critical Sections</a></h3> + +<p> +It is tempting to assume that if any part of one RCU read-side critical +section precedes a given grace period, and if any part of another RCU +read-side critical section follows that same grace period, then all of +the first RCU read-side critical section must precede all of the second. +However, this just isn't the case: A single grace period does not +partition the set of RCU read-side critical sections. +An example of this situation can be illustrated as follows, where +<tt>x</tt>, <tt>y</tt>, and <tt>z</tt> are initially all zero: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(a, 1); + 5 WRITE_ONCE(b, 1); + 6 rcu_read_unlock(); + 7 } + 8 + 9 void thread1(void) +10 { +11 r1 = READ_ONCE(a); +12 synchronize_rcu(); +13 WRITE_ONCE(c, 1); +14 } +15 +16 void thread2(void) +17 { +18 rcu_read_lock(); +19 r2 = READ_ONCE(b); +20 r3 = READ_ONCE(c); +21 rcu_read_unlock(); +22 } +</pre> +</blockquote> + +<p> +It turns out that the outcome: + +<blockquote> +<pre> +(r1 == 1 && r2 == 0 && r3 == 1) +</pre> +</blockquote> + +is entirely possible. +The following figure show how this can happen, with each circled +<tt>QS</tt> indicating the point at which RCU recorded a +<i>quiescent state</i> for each thread, that is, a state in which +RCU knows that the thread cannot be in the midst of an RCU read-side +critical section that started before the current grace period: + +<p><img src="GPpartitionReaders1.svg" alt="GPpartitionReaders1.svg" width="60%"></p> + +<p> +If it is necessary to partition RCU read-side critical sections in this +manner, it is necessary to use two grace periods, where the first +grace period is known to end before the second grace period starts: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(a, 1); + 5 WRITE_ONCE(b, 1); + 6 rcu_read_unlock(); + 7 } + 8 + 9 void thread1(void) +10 { +11 r1 = READ_ONCE(a); +12 synchronize_rcu(); +13 WRITE_ONCE(c, 1); +14 } +15 +16 void thread2(void) +17 { +18 r2 = READ_ONCE(c); +19 synchronize_rcu(); +20 WRITE_ONCE(d, 1); +21 } +22 +23 void thread3(void) +24 { +25 rcu_read_lock(); +26 r3 = READ_ONCE(b); +27 r4 = READ_ONCE(d); +28 rcu_read_unlock(); +29 } +</pre> +</blockquote> + +<p> +Here, if <tt>(r1 == 1)</tt>, then +<tt>thread0()</tt>'s write to <tt>b</tt> must happen +before the end of <tt>thread1()</tt>'s grace period. +If in addition <tt>(r4 == 1)</tt>, then +<tt>thread3()</tt>'s read from <tt>b</tt> must happen +after the beginning of <tt>thread2()</tt>'s grace period. +If it is also the case that <tt>(r2 == 1)</tt>, then the +end of <tt>thread1()</tt>'s grace period must precede the +beginning of <tt>thread2()</tt>'s grace period. +This mean that the two RCU read-side critical sections cannot overlap, +guaranteeing that <tt>(r3 == 1)</tt>. +As a result, the outcome: + +<blockquote> +<pre> +(r1 == 1 && r2 == 1 && r3 == 0 && r4 == 1) +</pre> +</blockquote> + +cannot happen. + +<p> +This non-requirement was also non-premeditated, but became apparent +when studying RCU's interaction with memory ordering. + +<h3><a name="Read-Side Critical Sections Don't Partition Grace Periods"> +Read-Side Critical Sections Don't Partition Grace Periods</a></h3> + +<p> +It is also tempting to assume that if an RCU read-side critical section +happens between a pair of grace periods, then those grace periods cannot +overlap. +However, this temptation leads nowhere good, as can be illustrated by +the following, with all variables initially zero: + +<blockquote> +<pre> + 1 void thread0(void) + 2 { + 3 rcu_read_lock(); + 4 WRITE_ONCE(a, 1); + 5 WRITE_ONCE(b, 1); + 6 rcu_read_unlock(); + 7 } + 8 + 9 void thread1(void) +10 { +11 r1 = READ_ONCE(a); +12 synchronize_rcu(); +13 WRITE_ONCE(c, 1); +14 } +15 +16 void thread2(void) +17 { +18 rcu_read_lock(); +19 WRITE_ONCE(d, 1); +20 r2 = READ_ONCE(c); +21 rcu_read_unlock(); +22 } +23 +24 void thread3(void) +25 { +26 r3 = READ_ONCE(d); +27 synchronize_rcu(); +28 WRITE_ONCE(e, 1); +29 } +30 +31 void thread4(void) +32 { +33 rcu_read_lock(); +34 r4 = READ_ONCE(b); +35 r5 = READ_ONCE(e); +36 rcu_read_unlock(); +37 } +</pre> +</blockquote> + +<p> +In this case, the outcome: + +<blockquote> +<pre> +(r1 == 1 && r2 == 1 && r3 == 1 && r4 == 0 && r5 == 1) +</pre> +</blockquote> + +is entirely possible, as illustrated below: + +<p><img src="ReadersPartitionGP1.svg" alt="ReadersPartitionGP1.svg" width="100%"></p> + +<p> +Again, an RCU read-side critical section can overlap almost all of a +given grace period, just so long as it does not overlap the entire +grace period. +As a result, an RCU read-side critical section cannot partition a pair +of RCU grace periods. + +<p>@@QQ@@ +How long a sequence of grace periods, each separated by an RCU read-side +critical section, would be required to partition the RCU read-side +critical sections at the beginning and end of the chain? +<p>@@QQA@@ +In theory, an infinite number. +In practice, an unknown number that is sensitive to both implementation +details and timing considerations. +Therefore, even in practice, RCU users must abide by the theoretical rather +than the practical answer. +<p>@@QQE@@ + +<h3><a name="Disabling Preemption Does Not Block Grace Periods"> +Disabling Preemption Does Not Block Grace Periods</a></h3> + +<p> +There was a time when disabling preemption on any given CPU would block +subsequent grace periods. +However, this was an accident of implementation and is not a requirement. +And in the current Linux-kernel implementation, disabling preemption +on a given CPU in fact does not block grace periods, as Oleg Nesterov +<a href="https://lkml.kernel.org/g/20150614193825.GA19582@redhat.com">demonstrated</a>. + +<p> +If you need a preempt-disable region to block grace periods, you need to add +<tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>, for example +as follows: + +<blockquote> +<pre> + 1 preempt_disable(); + 2 rcu_read_lock(); + 3 do_something(); + 4 rcu_read_unlock(); + 5 preempt_enable(); + 6 + 7 /* Spinlocks implicitly disable preemption. */ + 8 spin_lock(&mylock); + 9 rcu_read_lock(); +10 do_something(); +11 rcu_read_unlock(); +12 spin_unlock(&mylock); +</pre> +</blockquote> + +<p> +In theory, you could enter the RCU read-side critical section first, +but it is more efficient to keep the entire RCU read-side critical +section contained in the preempt-disable region as shown above. +Of course, RCU read-side critical sections that extend outside of +preempt-disable regions will work correctly, but such critical sections +can be preempted, which forces <tt>rcu_read_unlock()</tt> to do +more work. +And no, this is <i>not</i> an invitation to enclose all of your RCU +read-side critical sections within preempt-disable regions, because +doing so would degrade real-time response. + +<p> +This non-requirement appeared with preemptible RCU. +If you need a grace period that waits on non-preemptible code regions, use +<a href="#Sched Flavor">RCU-sched</a>. + +<h2><a name="Parallelism Facts of Life">Parallelism Facts of Life</a></h2> + +<p> +These parallelism facts of life are by no means specific to RCU, but +the RCU implementation must abide by them. +They therefore bear repeating: + +<ol> +<li> Any CPU or task may be delayed at any time, + and any attempts to avoid these delays by disabling + preemption, interrupts, or whatever are completely futile. + This is most obvious in preemptible user-level + environments and in virtualized environments (where + a given guest OS's VCPUs can be preempted at any time by + the underlying hypervisor), but can also happen in bare-metal + environments due to ECC errors, NMIs, and other hardware + events. + Although a delay of more than about 20 seconds can result + in splats, the RCU implementation is obligated to use + algorithms that can tolerate extremely long delays, but where + “extremely long” is not long enough to allow + wrap-around when incrementing a 64-bit counter. +<li> Both the compiler and the CPU can reorder memory accesses. + Where it matters, RCU must use compiler directives and + memory-barrier instructions to preserve ordering. +<li> Conflicting writes to memory locations in any given cache line + will result in expensive cache misses. + Greater numbers of concurrent writes and more-frequent + concurrent writes will result in more dramatic slowdowns. + RCU is therefore obligated to use algorithms that have + sufficient locality to avoid significant performance and + scalability problems. +<li> As a rough rule of thumb, only one CPU's worth of processing + may be carried out under the protection of any given exclusive + lock. + RCU must therefore use scalable locking designs. +<li> Counters are finite, especially on 32-bit systems. + RCU's use of counters must therefore tolerate counter wrap, + or be designed such that counter wrap would take way more + time than a single system is likely to run. + An uptime of ten years is quite possible, a runtime + of a century much less so. + As an example of the latter, RCU's dyntick-idle nesting counter + allows 54 bits for interrupt nesting level (this counter + is 64 bits even on a 32-bit system). + Overflowing this counter requires 2<sup>54</sup> + half-interrupts on a given CPU without that CPU ever going idle. + If a half-interrupt happened every microsecond, it would take + 570 years of runtime to overflow this counter, which is currently + believed to be an acceptably long time. +<li> Linux systems can have thousands of CPUs running a single + Linux kernel in a single shared-memory environment. + RCU must therefore pay close attention to high-end scalability. +</ol> + +<p> +This last parallelism fact of life means that RCU must pay special +attention to the preceding facts of life. +The idea that Linux might scale to systems with thousands of CPUs would +have been met with some skepticism in the 1990s, but these requirements +would have otherwise have been unsurprising, even in the early 1990s. + +<h2><a name="Quality-of-Implementation Requirements">Quality-of-Implementation Requirements</a></h2> + +<p> +These sections list quality-of-implementation requirements. +Although an RCU implementation that ignores these requirements could +still be used, it would likely be subject to limitations that would +make it inappropriate for industrial-strength production use. +Classes of quality-of-implementation requirements are as follows: + +<ol> +<li> <a href="#Specialization">Specialization</a> +<li> <a href="#Performance and Scalability">Performance and Scalability</a> +<li> <a href="#Composability">Composability</a> +<li> <a href="#Corner Cases">Corner Cases</a> +</ol> + +<p> +These classes is covered in the following sections. + +<h3><a name="Specialization">Specialization</a></h3> + +<p> +RCU is and always has been intended primarily for read-mostly situations, as +illustrated by the following figure. +This means that RCU's read-side primitives are optimized, often at the +expense of its update-side primitives. + +<p><img src="RCUApplicability.svg" alt="RCUApplicability.svg" width="70%"></p> + +<p> +This focus on read-mostly situations means that RCU must interoperate +with other synchronization primitives. +For example, the <tt>add_gp()</tt> and <tt>remove_gp_synchronous()</tt> +examples discussed earlier use RCU to protect readers and locking to +coordinate updaters. +However, the need extends much farther, requiring that a variety of +synchronization primitives be legal within RCU read-side critical sections, +including spinlocks, sequence locks, atomic operations, reference +counters, and memory barriers. + +<p>@@QQ@@ +What about sleeping locks? +<p>@@QQA@@ +These are forbidden within Linux-kernel RCU read-side critical sections +because it is not legal to place a quiescent state (in this case, +voluntary context switch) within an RCU read-side critical section. +However, sleeping locks may be used within userspace RCU read-side critical +sections, and also within Linux-kernel sleepable RCU +<a href="#Sleepable RCU">(SRCU)</a> +read-side critical sections. +In addition, the -rt patchset turns spinlocks into a sleeping locks so +that the corresponding critical sections can be preempted, which +also means that these sleeplockified spinlocks (but not other sleeping locks!) +may be acquire within -rt-Linux-kernel RCU read-side critical sections. + +<p> +Note that it <i>is</i> legal for a normal RCU read-side critical section +to conditionally acquire a sleeping locks (as in <tt>mutex_trylock()</tt>), +but only as long as it does not loop indefinitely attempting to +conditionally acquire that sleeping locks. +The key point is that things like <tt>mutex_trylock()</tt> +either return with the mutex held, or return an error indication if +the mutex was not immediately available. +Either way, <tt>mutex_trylock()</tt> returns immediately without sleeping. +<p>@@QQE@@ + +<p> +It often comes as a surprise that many algorithms do not require a +consistent view of data, but many can function in that mode, +with network routing being the poster child. +Internet routing algorithms take significant time to propagate +updates, so that by the time an update arrives at a given system, +that system has been sending network traffic the wrong way for +a considerable length of time. +Having a few threads continue to send traffic the wrong way for a +few more milliseconds is clearly not a problem: In the worst case, +TCP retransmissions will eventually get the data where it needs to go. +In general, when tracking the state of the universe outside of the +computer, some level of inconsistency must be tolerated due to +speed-of-light delays if nothing else. + +<p> +Furthermore, uncertainty about external state is inherent in many cases. +For example, a pair of veternarians might use heartbeat to determine +whether or not a given cat was alive. +But how long should they wait after the last heartbeat to decide that +the cat is in fact dead? +Waiting less than 400 milliseconds makes no sense because this would +mean that a relaxed cat would be considered to cycle between death +and life more than 100 times per minute. +Moreover, just as with human beings, a cat's heart might stop for +some period of time, so the exact wait period is a judgment call. +One of our pair of veternarians might wait 30 seconds before pronouncing +the cat dead, while the other might insist on waiting a full minute. +The two veternarians would then disagree on the state of the cat during +the final 30 seconds of the minute following the last heartbeat, as +fancifully illustrated below: + +<p><img src="2013-08-is-it-dead.png" alt="2013-08-is-it-dead.png" width="431"></p> + +<p> +Interestingly enough, this same situation applies to hardware. +When push comes to shove, how do we tell whether or not some +external server has failed? +We send messages to it periodically, and declare it failed if we +don't receive a response within a given period of time. +Policy decisions can usually tolerate short +periods of inconsistency. +The policy was decided some time ago, and is only now being put into +effect, so a few milliseconds of delay is normally inconsequential. + +<p> +However, there are algorithms that absolutely must see consistent data. +For example, the translation between a user-level SystemV semaphore +ID to the corresponding in-kernel data structure is protected by RCU, +but it is absolutely forbidden to update a semaphore that has just been +removed. +In the Linux kernel, this need for consistency is accommodated by acquiring +spinlocks located in the in-kernel data structure from within +the RCU read-side critical section, and this is indicated by the +green box in the figure above. +Many other techniques may be used, and are in fact used within the +Linux kernel. + +<p> +In short, RCU is not required to maintain consistency, and other +mechanisms may be used in concert with RCU when consistency is required. +RCU's specialization allows it to do its job extremely well, and its +ability to interoperate with other synchronization mechanisms allows +the right mix of synchronization tools to be used for a given job. + +<h3><a name="Performance and Scalability">Performance and Scalability</a></h3> + +<p> +Energy efficiency is a critical component of performance today, +and Linux-kernel RCU implementations must therefore avoid unnecessarily +awakening idle CPUs. +I cannot claim that this requirement was premeditated. +In fact, I learned of it during a telephone conversation in which I +was given “frank and open” feedback on the importance +of energy efficiency in battery-powered systems and on specific +energy-efficiency shortcomings of the Linux-kernel RCU implementation. +In my experience, the battery-powered embedded community will consider +any unnecessary wakeups to be extremely unfriendly acts. +So much so that mere Linux-kernel-mailing-list posts are +insufficient to vent their ire. + +<p> +Memory consumption is not particularly important for in most +situations, and has become decreasingly +so as memory sizes have expanded and memory +costs have plummeted. +However, as I learned from Matt Mackall's +<a href="http://elinux.org/Linux_Tiny-FAQ">bloatwatch</a> +efforts, memory footprint is critically important on single-CPU systems with +non-preemptible (<tt>CONFIG_PREEMPT=n</tt>) kernels, and thus +<a href="https://lkml.kernel.org/g/20090113221724.GA15307@linux.vnet.ibm.com">tiny RCU</a> +was born. +Josh Triplett has since taken over the small-memory banner with his +<a href="https://tiny.wiki.kernel.org/">Linux kernel tinification</a> +project, which resulted in +<a href="#Sleepable RCU">SRCU</a> +becoming optional for those kernels not needing it. + +<p> +The remaining performance requirements are, for the most part, +unsurprising. +For example, in keeping with RCU's read-side specialization, +<tt>rcu_dereference()</tt> should have negligible overhead (for +example, suppression of a few minor compiler optimizations). +Similarly, in non-preemptible environments, <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> should have exactly zero overhead. + +<p> +In preemptible environments, in the case where the RCU read-side +critical section was not preempted (as will be the case for the +highest-priority real-time process), <tt>rcu_read_lock()</tt> and +<tt>rcu_read_unlock()</tt> should have minimal overhead. +In particular, they should not contain atomic read-modify-write +operations, memory-barrier instructions, preemption disabling, +interrupt disabling, or backwards branches. +However, in the case where the RCU read-side critical section was preempted, +<tt>rcu_read_unlock()</tt> may acquire spinlocks and disable interrupts. +This is why it is better to nest an RCU read-side critical section +within a preempt-disable region than vice versa, at least in cases +where that critical section is short enough to avoid unduly degrading +real-time latencies. + +<p> +The <tt>synchronize_rcu()</tt> grace-period-wait primitive is +optimized for throughput. +It may therefore incur several milliseconds of latency in addition to +the duration of the longest RCU read-side critical section. +On the other hand, multiple concurrent invocations of +<tt>synchronize_rcu()</tt> are required to use batching optimizations +so that they can be satisfied by a single underlying grace-period-wait +operation. +For example, in the Linux kernel, it is not unusual for a single +grace-period-wait operation to serve more than +<a href="https://www.usenix.org/conference/2004-usenix-annual-technical-conference/making-rcu-safe-deep-sub-millisecond-response">1,000 separate invocations</a> +of <tt>synchronize_rcu()</tt>, thus amortizing the per-invocation +overhead down to nearly zero. +However, the grace-period optimization is also required to avoid +measurable degradation of real-time scheduling and interrupt latencies. + +<p> +In some cases, the multi-millisecond <tt>synchronize_rcu()</tt> +latencies are unacceptable. +In these cases, <tt>synchronize_rcu_expedited()</tt> may be used +instead, reducing the grace-period latency down to a few tens of +microseconds on small systems, at least in cases where the RCU read-side +critical sections are short. +There are currently no special latency requirements for +<tt>synchronize_rcu_expedited()</tt> on large systems, but, +consistent with the empirical nature of the RCU specification, +that is subject to change. +However, there most definitely are scalability requirements: +A storm of <tt>synchronize_rcu_expedited()</tt> invocations on 4096 +CPUs should at least make reasonable forward progress. +In return for its shorter latencies, <tt>synchronize_rcu_expedited()</tt> +is permitted to impose modest degradation of real-time latency +on non-idle online CPUs. +That said, it will likely be necessary to take further steps to reduce this +degradation, hopefully to roughly that of a scheduling-clock interrupt. + +<p> +There are a number of situations where even +<tt>synchronize_rcu_expedited()</tt>'s reduced grace-period +latency is unacceptable. +In these situations, the asynchronous <tt>call_rcu()</tt> can be +used in place of <tt>synchronize_rcu()</tt> as follows: + +<blockquote> +<pre> + 1 struct foo { + 2 int a; + 3 int b; + 4 struct rcu_head rh; + 5 }; + 6 + 7 static void remove_gp_cb(struct rcu_head *rhp) + 8 { + 9 struct foo *p = container_of(rhp, struct foo, rh); +10 +11 kfree(p); +12 } +13 +14 bool remove_gp_asynchronous(void) +15 { +16 struct foo *p; +17 +18 spin_lock(&gp_lock); +19 p = rcu_dereference(gp); +20 if (!p) { +21 spin_unlock(&gp_lock); +22 return false; +23 } +24 rcu_assign_pointer(gp, NULL); +25 call_rcu(&p->rh, remove_gp_cb); +26 spin_unlock(&gp_lock); +27 return true; +28 } +</pre> +</blockquote> + +<p> +A definition of <tt>struct foo</tt> is finally needed, and appears +on lines 1-5. +The function <tt>remove_gp_cb()</tt> is passed to <tt>call_rcu()</tt> +on line 25, and will be invoked after the end of a subsequent +grace period. +This gets the same effect as <tt>remove_gp_synchronous()</tt>, +but without forcing the updater to wait for a grace period to elapse. +The <tt>call_rcu()</tt> function may be used in a number of +situations where neither <tt>synchronize_rcu()</tt> nor +<tt>synchronize_rcu_expedited()</tt> would be legal, +including within preempt-disable code, <tt>local_bh_disable()</tt> code, +interrupt-disable code, and interrupt handlers. +However, even <tt>call_rcu()</tt> is illegal within NMI handlers. +The callback function (<tt>remove_gp_cb()</tt> in this case) will be +executed within softirq (software interrupt) environment within the +Linux kernel, +either within a real softirq handler or under the protection +of <tt>local_bh_disable()</tt>. +In both the Linux kernel and in userspace, it is bad practice to +write an RCU callback function that takes too long. +Long-running operations should be relegated to separate threads or +(in the Linux kernel) workqueues. + +<p>@@QQ@@ +Why does line 19 use <tt>rcu_access_pointer()</tt>? +After all, <tt>call_rcu()</tt> on line 25 stores into the +structure, which would interact badly with concurrent insertions. +Doesn't this mean that <tt>rcu_dereference()</tt> is required? +<p>@@QQA@@ +Presumably the <tt>->gp_lock</tt> acquired on line 18 excludes +any changes, including any insertions that <tt>rcu_dereference()</tt> +would protect against. +Therefore, any insertions will be delayed until after <tt>->gp_lock</tt> +is released on line 25, which in turn means that +<tt>rcu_access_pointer()</tt> suffices. +<p>@@QQE@@ + +<p> +However, all that <tt>remove_gp_cb()</tt> is doing is +invoking <tt>kfree()</tt> on the data element. +This is a common idiom, and is supported by <tt>kfree_rcu()</tt>, +which allows “fire and forget” operation as shown below: + +<blockquote> +<pre> + 1 struct foo { + 2 int a; + 3 int b; + 4 struct rcu_head rh; + 5 }; + 6 + 7 bool remove_gp_faf(void) + 8 { + 9 struct foo *p; +10 +11 spin_lock(&gp_lock); +12 p = rcu_dereference(gp); +13 if (!p) { +14 spin_unlock(&gp_lock); +15 return false; +16 } +17 rcu_assign_pointer(gp, NULL); +18 kfree_rcu(p, rh); +19 spin_unlock(&gp_lock); +20 return true; +21 } +</pre> +</blockquote> + +<p> +Note that <tt>remove_gp_faf()</tt> simply invokes +<tt>kfree_rcu()</tt> and proceeds, without any need to pay any +further attention to the subsequent grace period and <tt>kfree()</tt>. +It is permissible to invoke <tt>kfree_rcu()</tt> from the same +environments as for <tt>call_rcu()</tt>. +Interestingly enough, DYNIX/ptx had the equivalents of +<tt>call_rcu()</tt> and <tt>kfree_rcu()</tt>, but not +<tt>synchronize_rcu()</tt>. +This was due to the fact that RCU was not heavily used within DYNIX/ptx, +so the very few places that needed something like +<tt>synchronize_rcu()</tt> simply open-coded it. + +<p>@@QQ@@ +Earlier it was claimed that <tt>call_rcu()</tt> and +<tt>kfree_rcu()</tt> allowed updaters to avoid being blocked +by readers. +But how can that be correct, given that the invocation of the callback +and the freeing of the memory (respectively) must still wait for +a grace period to elapse? +<p>@@QQA@@ +We could define things this way, but keep in mind that this sort of +definition would say that updates in garbage-collected languages +cannot complete until the next time the garbage collector runs, +which does not seem at all reasonable. +The key point is that in most cases, an updater using either +<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt> can proceed to the +next update as soon as it has invoked <tt>call_rcu()</tt> or +<tt>kfree_rcu()</tt>, without having to wait for a subsequent +grace period. +<p>@@QQE@@ + +<p> +But what if the updater must wait for the completion of code to be +executed after the end of the grace period, but has other tasks +that can be carried out in the meantime? +The polling-style <tt>get_state_synchronize_rcu()</tt> and +<tt>cond_synchronize_rcu()</tt> functions may be used for this +purpose, as shown below: + +<blockquote> +<pre> + 1 bool remove_gp_poll(void) + 2 { + 3 struct foo *p; + 4 unsigned long s; + 5 + 6 spin_lock(&gp_lock); + 7 p = rcu_access_pointer(gp); + 8 if (!p) { + 9 spin_unlock(&gp_lock); +10 return false; +11 } +12 rcu_assign_pointer(gp, NULL); +13 spin_unlock(&gp_lock); +14 s = get_state_synchronize_rcu(); +15 do_something_while_waiting(); +16 cond_synchronize_rcu(s); +17 kfree(p); +18 return true; +19 } +</pre> +</blockquote> + +<p> +On line 14, <tt>get_state_synchronize_rcu()</tt> obtains a +“cookie” from RCU, +then line 15 carries out other tasks, +and finally, line 16 returns immediately if a grace period has +elapsed in the meantime, but otherwise waits as required. +The need for <tt>get_state_synchronize_rcu</tt> and +<tt>cond_synchronize_rcu()</tt> has appeared quite recently, +so it is too early to tell whether they will stand the test of time. + +<p> +RCU thus provides a range of tools to allow updaters to strike the +required tradeoff between latency, flexibility and CPU overhead. + +<h3><a name="Composability">Composability</a></h3> + +<p> +Composability has received much attention in recent years, perhaps in part +due to the collision of multicore hardware with object-oriented techniques +designed in single-threaded environments for single-threaded use. +And in theory, RCU read-side critical sections may be composed, and in +fact may be nested arbitrarily deeply. +In practice, as with all real-world implementations of composable +constructs, there are limitations. + +<p> +Implementations of RCU for which <tt>rcu_read_lock()</tt> +and <tt>rcu_read_unlock()</tt> generate no code, such as +Linux-kernel RCU when <tt>CONFIG_PREEMPT=n</tt>, can be +nested arbitrarily deeply. +After all, there is no overhead. +Except that if all these instances of <tt>rcu_read_lock()</tt> +and <tt>rcu_read_unlock()</tt> are visible to the compiler, +compilation will eventually fail due to exhausting memory, +mass storage, or user patience, whichever comes first. +If the nesting is not visible to the compiler, as is the case with +mutually recursive functions each in its own translation unit, +stack overflow will result. +If the nesting takes the form of loops, either the control variable +will overflow or (in the Linux kernel) you will get an RCU CPU stall warning. +Nevertheless, this class of RCU implementations is one +of the most composable constructs in existence. + +<p> +RCU implementations that explicitly track nesting depth +are limited by the nesting-depth counter. +For example, the Linux kernel's preemptible RCU limits nesting to +<tt>INT_MAX</tt>. +This should suffice for almost all practical purposes. +That said, a consecutive pair of RCU read-side critical sections +between which there is an operation that waits for a grace period +cannot be enclosed in another RCU read-side critical section. +This is because it is not legal to wait for a grace period within +an RCU read-side critical section: To do so would result either +in deadlock or +in RCU implicitly splitting the enclosing RCU read-side critical +section, neither of which is conducive to a long-lived and prosperous +kernel. + +<p> +It is worth noting that RCU is not alone in limiting composability. +For example, many transactional-memory implementations prohibit +composing a pair of transactions separated by an irrevocable +operation (for example, a network receive operation). +For another example, lock-based critical sections can be composed +surprisingly freely, but only if deadlock is avoided. + +<p> +In short, although RCU read-side critical sections are highly composable, +care is required in some situations, just as is the case for any other +composable synchronization mechanism. + +<h3><a name="Corner Cases">Corner Cases</a></h3> + +<p> +A given RCU workload might have an endless and intense stream of +RCU read-side critical sections, perhaps even so intense that there +was never a point in time during which there was not at least one +RCU read-side critical section in flight. +RCU cannot allow this situation to block grace periods: As long as +all the RCU read-side critical sections are finite, grace periods +must also be finite. + +<p> +That said, preemptible RCU implementations could potentially result +in RCU read-side critical sections being preempted for long durations, +which has the effect of creating a long-duration RCU read-side +critical section. +This situation can arise only in heavily loaded systems, but systems using +real-time priorities are of course more vulnerable. +Therefore, RCU priority boosting is provided to help deal with this +case. +That said, the exact requirements on RCU priority boosting will likely +evolve as more experience accumulates. + +<p> +Other workloads might have very high update rates. +Although one can argue that such workloads should instead use +something other than RCU, the fact remains that RCU must +handle such workloads gracefully. +This requirement is another factor driving batching of grace periods, +but it is also the driving force behind the checks for large numbers +of queued RCU callbacks in the <tt>call_rcu()</tt> code path. +Finally, high update rates should not delay RCU read-side critical +sections, although some read-side delays can occur when using +<tt>synchronize_rcu_expedited()</tt>, courtesy of this function's use +of <tt>try_stop_cpus()</tt>. +(In the future, <tt>synchronize_rcu_expedited()</tt> will be +converted to use lighter-weight inter-processor interrupts (IPIs), +but this will still disturb readers, though to a much smaller degree.) + +<p> +Although all three of these corner cases were understood in the early +1990s, a simple user-level test consisting of <tt>close(open(path))</tt> +in a tight loop +in the early 2000s suddenly provided a much deeper appreciation of the +high-update-rate corner case. +This test also motivated addition of some RCU code to react to high update +rates, for example, if a given CPU finds itself with more than 10,000 +RCU callbacks queued, it will cause RCU to take evasive action by +more aggressively starting grace periods and more aggressively forcing +completion of grace-period processing. +This evasive action causes the grace period to complete more quickly, +but at the cost of restricting RCU's batching optimizations, thus +increasing the CPU overhead incurred by that grace period. + +<h2><a name="Software-Engineering Requirements"> +Software-Engineering Requirements</a></h2> + +<p> +Between Murphy's Law and “To err is human”, it is necessary to +guard against mishaps and misuse: + +<ol> +<li> It is all too easy to forget to use <tt>rcu_read_lock()</tt> + everywhere that it is needed, so kernels built with + <tt>CONFIG_PROVE_RCU=y</tt> will spat if + <tt>rcu_dereference()</tt> is used outside of an + RCU read-side critical section. + Update-side code can use <tt>rcu_dereference_protected()</tt>, + which takes a + <a href="https://lwn.net/Articles/371986/">lockdep expression</a> + to indicate what is providing the protection. + If the indicated protection is not provided, a lockdep splat + is emitted. + + <p> + Code shared between readers and updaters can use + <tt>rcu_dereference_check()</tt>, which also takes a + lockdep expression, and emits a lockdep splat if neither + <tt>rcu_read_lock()</tt> nor the indicated protection + is in place. + In addition, <tt>rcu_dereference_raw()</tt> is used in those + (hopefully rare) cases where the required protection cannot + be easily described. + Finally, <tt>rcu_read_lock_held()</tt> is provided to + allow a function to verify that it has been invoked within + an RCU read-side critical section. + I was made aware of this set of requirements shortly after Thomas + Gleixner audited a number of RCU uses. +<li> A given function might wish to check for RCU-related preconditions + upon entry, before using any other RCU API. + The <tt>rcu_lockdep_assert()</tt> does this job, + asserting the expression in kernels having lockdep enabled + and doing nothing otherwise. +<li> It is also easy to forget to use <tt>rcu_assign_pointer()</tt> + and <tt>rcu_dereference()</tt>, perhaps (incorrectly) + substituting a simple assignment. + To catch this sort of error, a given RCU-protected pointer may be + tagged with <tt>__rcu</tt>, after which running sparse + with <tt>CONFIG_SPARSE_RCU_POINTER=y</tt> will complain + about simple-assignment accesses to that pointer. + Arnd Bergmann made me aware of this requirement, and also + supplied the needed + <a href="https://lwn.net/Articles/376011/">patch series</a>. +<li> Kernels built with <tt>CONFIG_DEBUG_OBJECTS_RCU_HEAD=y</tt> + will splat if a data element is passed to <tt>call_rcu()</tt> + twice in a row, without a grace period in between. + (This error is similar to a double free.) + The corresponding <tt>rcu_head</tt> structures that are + dynamically allocated are automatically tracked, but + <tt>rcu_head</tt> structures allocated on the stack + must be initialized with <tt>init_rcu_head_on_stack()</tt> + and cleaned up with <tt>destroy_rcu_head_on_stack()</tt>. + Similarly, statically allocated non-stack <tt>rcu_head</tt> + structures must be initialized with <tt>init_rcu_head()</tt> + and cleaned up with <tt>destroy_rcu_head()</tt>. + Mathieu Desnoyers made me aware of this requirement, and also + supplied the needed + <a href="https://lkml.kernel.org/g/20100319013024.GA28456@Krystal">patch</a>. +<li> An infinite loop in an RCU read-side critical section will + eventually trigger an RCU CPU stall warning splat, with + the duration of “eventually” being controlled by the + <tt>RCU_CPU_STALL_TIMEOUT</tt> <tt>Kconfig</tt> option, or, + alternatively, by the + <tt>rcupdate.rcu_cpu_stall_timeout</tt> boot/sysfs + parameter. + However, RCU is not obligated to produce this splat + unless there is a grace period waiting on that particular + RCU read-side critical section. + <p> + Some extreme workloads might intentionally delay + RCU grace periods, and systems running those workloads can + be booted with <tt>rcupdate.rcu_cpu_stall_suppress</tt> + to suppress the splats. + This kernel parameter may also be set via <tt>sysfs</tt>. + Furthermore, RCU CPU stall warnings are counter-productive + during sysrq dumps and during panics. + RCU therefore supplies the <tt>rcu_sysrq_start()</tt> and + <tt>rcu_sysrq_end()</tt> API members to be called before + and after long sysrq dumps. + RCU also supplies the <tt>rcu_panic()</tt> notifier that is + automatically invoked at the beginning of a panic to suppress + further RCU CPU stall warnings. + + <p> + This requirement made itself known in the early 1990s, pretty + much the first time that it was necessary to debug a CPU stall. + That said, the initial implementation in DYNIX/ptx was quite + generic in comparison with that of Linux. +<li> Although it would be very good to detect pointers leaking out + of RCU read-side critical sections, there is currently no + good way of doing this. + One complication is the need to distinguish between pointers + leaking and pointers that have been handed off from RCU to + some other synchronization mechanism, for example, reference + counting. +<li> In kernels built with <tt>CONFIG_RCU_TRACE=y</tt>, RCU-related + information is provided via both debugfs and event tracing. +<li> Open-coded use of <tt>rcu_assign_pointer()</tt> and + <tt>rcu_dereference()</tt> to create typical linked + data structures can be surprisingly error-prone. + Therefore, RCU-protected + <a href="https://lwn.net/Articles/609973/#RCU List APIs">linked lists</a> + and, more recently, RCU-protected + <a href="https://lwn.net/Articles/612100/">hash tables</a> + are available. + Many other special-purpose RCU-protected data structures are + available in the Linux kernel and the userspace RCU library. +<li> Some linked structures are created at compile time, but still + require <tt>__rcu</tt> checking. + The <tt>RCU_POINTER_INITIALIZER()</tt> macro serves this + purpose. +<li> It is not necessary to use <tt>rcu_assign_pointer()</tt> + when creating linked structures that are to be published via + a single external pointer. + The <tt>RCU_INIT_POINTER()</tt> macro is provided for + this task and also for assigning <tt>NULL</tt> pointers + at runtime. +</ol> + +<p> +This not a hard-and-fast list: RCU's diagnostic capabilities will +continue to be guided by the number and type of usage bugs found +in real-world RCU usage. + +<h2><a name="Linux Kernel Complications">Linux Kernel Complications</a></h2> + +<p> +The Linux kernel provides an interesting environment for all kinds of +software, including RCU. +Some of the relevant points of interest are as follows: + +<ol> +<li> <a href="#Configuration">Configuration</a>. +<li> <a href="#Firmware Interface">Firmware Interface</a>. +<li> <a href="#Early Boot">Early Boot</a>. +<li> <a href="#Interrupts and NMIs"> + Interrupts and non-maskable interrupts (NMIs)</a>. +<li> <a href="#Loadable Modules">Loadable Modules</a>. +<li> <a href="#Hotplug CPU">Hotplug CPU</a>. +<li> <a href="#Scheduler and RCU">Scheduler and RCU</a>. +<li> <a href="#Tracing and RCU">Tracing and RCU</a>. +<li> <a href="#Energy Efficiency">Energy Efficiency</a>. +<li> <a href="#Memory Efficiency">Memory Efficiency</a>. +<li> <a href="#Performance, Scalability, Response Time, and Reliability"> + Performance, Scalability, Response Time, and Reliability</a>. +</ol> + +<p> +This list is probably incomplete, but it does give a feel for the +most notable Linux-kernel complications. +Each of the following sections covers one of the above topics. + +<h3><a name="Configuration">Configuration</a></h3> + +<p> +RCU's goal is automatic configuration, so that almost nobody +needs to worry about RCU's <tt>Kconfig</tt> options. +And for almost all users, RCU does in fact work well +“out of the box.” + +<p> +However, there are specialized use cases that are handled by +kernel boot parameters and <tt>Kconfig</tt> options. +Unfortunately, the <tt>Kconfig</tt> system will explicitly ask users +about new <tt>Kconfig</tt> options, which requires almost all of them +be hidden behind a <tt>CONFIG_RCU_EXPERT</tt> <tt>Kconfig</tt> option. + +<p> +This all should be quite obvious, but the fact remains that +Linus Torvalds recently had to +<a href="https://lkml.kernel.org/g/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com">remind</a> +me of this requirement. + +<h3><a name="Firmware Interface">Firmware Interface</a></h3> + +<p> +In many cases, kernel obtains information about the system from the +firmware, and sometimes things are lost in translation. +Or the translation is accurate, but the original message is bogus. + +<p> +For example, some systems' firmware overreports the number of CPUs, +sometimes by a large factor. +If RCU naively believed the firmware, as it used to do, +it would create too many per-CPU kthreads. +Although the resulting system will still run correctly, the extra +kthreads needlessly consume memory and can cause confusion +when they show up in <tt>ps</tt> listings. + +<p> +RCU must therefore wait for a given CPU to actually come online before +it can allow itself to believe that the CPU actually exists. +The resulting “ghost CPUs” (which are never going to +come online) cause a number of +<a href="https://paulmck.livejournal.com/37494.html">interesting complications</a>. + +<h3><a name="Early Boot">Early Boot</a></h3> + +<p> +The Linux kernel's boot sequence is an interesting process, +and RCU is used early, even before <tt>rcu_init()</tt> +is invoked. +In fact, a number of RCU's primitives can be used as soon as the +initial task's <tt>task_struct</tt> is available and the +boot CPU's per-CPU variables are set up. +The read-side primitives (<tt>rcu_read_lock()</tt>, +<tt>rcu_read_unlock()</tt>, <tt>rcu_dereference()</tt>, +and <tt>rcu_access_pointer()</tt>) will operate normally very early on, +as will <tt>rcu_assign_pointer()</tt>. + +<p> +Although <tt>call_rcu()</tt> may be invoked at any +time during boot, callbacks are not guaranteed to be invoked until after +the scheduler is fully up and running. +This delay in callback invocation is due to the fact that RCU does not +invoke callbacks until it is fully initialized, and this full initialization +cannot occur until after the scheduler has initialized itself to the +point where RCU can spawn and run its kthreads. +In theory, it would be possible to invoke callbacks earlier, +however, this is not a panacea because there would be severe restrictions +on what operations those callbacks could invoke. + +<p> +Perhaps surprisingly, <tt>synchronize_rcu()</tt>, +<a href="#Bottom-Half Flavor"><tt>synchronize_rcu_bh()</tt></a> +(<a href="#Bottom-Half Flavor">discussed below</a>), +and +<a href="#Sched Flavor"><tt>synchronize_sched()</tt></a> +will all operate normally +during very early boot, the reason being that there is only one CPU +and preemption is disabled. +This means that the call <tt>synchronize_rcu()</tt> (or friends) +itself is a quiescent +state and thus a grace period, so the early-boot implementation can +be a no-op. + +<p> +Both <tt>synchronize_rcu_bh()</tt> and <tt>synchronize_sched()</tt> +continue to operate normally through the remainder of boot, courtesy +of the fact that preemption is disabled across their RCU read-side +critical sections and also courtesy of the fact that there is still +only one CPU. +However, once the scheduler starts initializing, preemption is enabled. +There is still only a single CPU, but the fact that preemption is enabled +means that the no-op implementation of <tt>synchronize_rcu()</tt> no +longer works in <tt>CONFIG_PREEMPT=y</tt> kernels. +Therefore, as soon as the scheduler starts initializing, the early-boot +fastpath is disabled. +This means that <tt>synchronize_rcu()</tt> switches to its runtime +mode of operation where it posts callbacks, which in turn means that +any call to <tt>synchronize_rcu()</tt> will block until the corresponding +callback is invoked. +Unfortunately, the callback cannot be invoked until RCU's runtime +grace-period machinery is up and running, which cannot happen until +the scheduler has initialized itself sufficiently to allow RCU's +kthreads to be spawned. +Therefore, invoking <tt>synchronize_rcu()</tt> during scheduler +initialization can result in deadlock. + +<p>@@QQ@@ +So what happens with <tt>synchronize_rcu()</tt> during +scheduler initialization for <tt>CONFIG_PREEMPT=n</tt> +kernels? +<p>@@QQA@@ +In <tt>CONFIG_PREEMPT=n</tt> kernel, <tt>synchronize_rcu()</tt> +maps directly to <tt>synchronize_sched()</tt>. +Therefore, <tt>synchronize_rcu()</tt> works normally throughout +boot in <tt>CONFIG_PREEMPT=n</tt> kernels. +However, your code must also work in <tt>CONFIG_PREEMPT=y</tt> kernels, +so it is still necessary to avoid invoking <tt>synchronize_rcu()</tt> +during scheduler initialization. +<p>@@QQE@@ + +<p> +I learned of these boot-time requirements as a result of a series of +system hangs. + +<h3><a name="Interrupts and NMIs">Interrupts and NMIs</a></h3> + +<p> +The Linux kernel has interrupts, and RCU read-side critical sections are +legal within interrupt handlers and within interrupt-disabled regions +of code, as are invocations of <tt>call_rcu()</tt>. + +<p> +Some Linux-kernel architectures can enter an interrupt handler from +non-idle process context, and then just never leave it, instead stealthily +transitioning back to process context. +This trick is sometimes used to invoke system calls from inside the kernel. +These “half-interrupts” mean that RCU has to be very careful +about how it counts interrupt nesting levels. +I learned of this requirement the hard way during a rewrite +of RCU's dyntick-idle code. + +<p> +The Linux kernel has non-maskable interrupts (NMIs), and +RCU read-side critical sections are legal within NMI handlers. +Thankfully, RCU update-side primitives, including +<tt>call_rcu()</tt>, are prohibited within NMI handlers. + +<p> +The name notwithstanding, some Linux-kernel architectures +can have nested NMIs, which RCU must handle correctly. +Andy Lutomirski +<a href="https://lkml.kernel.org/g/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com">surprised me</a> +with this requirement; +he also kindly surprised me with +<a href="https://lkml.kernel.org/g/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com">an algorithm</a> +that meets this requirement. + +<h3><a name="Loadable Modules">Loadable Modules</a></h3> + +<p> +The Linux kernel has loadable modules, and these modules can +also be unloaded. +After a given module has been unloaded, any attempt to call +one of its functions results in a segmentation fault. +The module-unload functions must therefore cancel any +delayed calls to loadable-module functions, for example, +any outstanding <tt>mod_timer()</tt> must be dealt with +via <tt>del_timer_sync()</tt> or similar. + +<p> +Unfortunately, there is no way to cancel an RCU callback; +once you invoke <tt>call_rcu()</tt>, the callback function is +going to eventually be invoked, unless the system goes down first. +Because it is normally considered socially irresponsible to crash the system +in response to a module unload request, we need some other way +to deal with in-flight RCU callbacks. + +<p> +RCU therefore provides +<tt><a href="https://lwn.net/Articles/217484/">rcu_barrier()</a></tt>, +which waits until all in-flight RCU callbacks have been invoked. +If a module uses <tt>call_rcu()</tt>, its exit function should therefore +prevent any future invocation of <tt>call_rcu()</tt>, then invoke +<tt>rcu_barrier()</tt>. +In theory, the underlying module-unload code could invoke +<tt>rcu_barrier()</tt> unconditionally, but in practice this would +incur unacceptable latencies. + +<p> +Nikita Danilov noted this requirement for an analogous filesystem-unmount +situation, and Dipankar Sarma incorporated <tt>rcu_barrier()</tt> into RCU. +The need for <tt>rcu_barrier()</tt> for module unloading became +apparent later. + +<h3><a name="Hotplug CPU">Hotplug CPU</a></h3> + +<p> +The Linux kernel supports CPU hotplug, which means that CPUs +can come and go. +It is of course illegal to use any RCU API member from an offline CPU. +This requirement was present from day one in DYNIX/ptx, but +on the other hand, the Linux kernel's CPU-hotplug implementation +is “interesting.” + +<p> +The Linux-kernel CPU-hotplug implementation has notifiers that +are used to allow the various kernel subsystems (including RCU) +to respond appropriately to a given CPU-hotplug operation. +Most RCU operations may be invoked from CPU-hotplug notifiers, +including even normal synchronous grace-period operations +such as <tt>synchronize_rcu()</tt>. +However, expedited grace-period operations such as +<tt>synchronize_rcu_expedited()</tt> are not supported, +due to the fact that current implementations block CPU-hotplug +operations, which could result in deadlock. + +<p> +In addition, all-callback-wait operations such as +<tt>rcu_barrier()</tt> are also not supported, due to the +fact that there are phases of CPU-hotplug operations where +the outgoing CPU's callbacks will not be invoked until after +the CPU-hotplug operation ends, which could also result in deadlock. + +<h3><a name="Scheduler and RCU">Scheduler and RCU</a></h3> + +<p> +RCU depends on the scheduler, and the scheduler uses RCU to +protect some of its data structures. +This means the scheduler is forbidden from acquiring +the runqueue locks and the priority-inheritance locks +in the middle of an outermost RCU read-side critical section unless either +(1) it releases them before exiting that same +RCU read-side critical section, or +(2) interrupts are disabled across +that entire RCU read-side critical section. +This same prohibition also applies (recursively!) to any lock that is acquired +while holding any lock to which this prohibition applies. +Adhering to this rule prevents preemptible RCU from invoking +<tt>rcu_read_unlock_special()</tt> while either runqueue or +priority-inheritance locks are held, thus avoiding deadlock. + +<p> +Prior to v4.4, it was only necessary to disable preemption across +RCU read-side critical sections that acquired scheduler locks. +In v4.4, expedited grace periods started using IPIs, and these +IPIs could force a <tt>rcu_read_unlock()</tt> to take the slowpath. +Therefore, this expedited-grace-period change required disabling of +interrupts, not just preemption. + +<p> +For RCU's part, the preemptible-RCU <tt>rcu_read_unlock()</tt> +implementation must be written carefully to avoid similar deadlocks. +In particular, <tt>rcu_read_unlock()</tt> must tolerate an +interrupt where the interrupt handler invokes both +<tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>. +This possibility requires <tt>rcu_read_unlock()</tt> to use +negative nesting levels to avoid destructive recursion via +interrupt handler's use of RCU. + +<p> +This pair of mutual scheduler-RCU requirements came as a +<a href="https://lwn.net/Articles/453002/">complete surprise</a>. + +<p> +As noted above, RCU makes use of kthreads, and it is necessary to +avoid excessive CPU-time accumulation by these kthreads. +This requirement was no surprise, but RCU's violation of it +when running context-switch-heavy workloads when built with +<tt>CONFIG_NO_HZ_FULL=y</tt> +<a href="http://www.rdrop.com/users/paulmck/scalability/paper/BareMetal.2015.01.15b.pdf">did come as a surprise [PDF]</a>. +RCU has made good progress towards meeting this requirement, even +for context-switch-have <tt>CONFIG_NO_HZ_FULL=y</tt> workloads, +but there is room for further improvement. + +<h3><a name="Tracing and RCU">Tracing and RCU</a></h3> + +<p> +It is possible to use tracing on RCU code, but tracing itself +uses RCU. +For this reason, <tt>rcu_dereference_raw_notrace()</tt> +is provided for use by tracing, which avoids the destructive +recursion that could otherwise ensue. +This API is also used by virtualization in some architectures, +where RCU readers execute in environments in which tracing +cannot be used. +The tracing folks both located the requirement and provided the +needed fix, so this surprise requirement was relatively painless. + +<h3><a name="Energy Efficiency">Energy Efficiency</a></h3> + +<p> +Interrupting idle CPUs is considered socially unacceptable, +especially by people with battery-powered embedded systems. +RCU therefore conserves energy by detecting which CPUs are +idle, including tracking CPUs that have been interrupted from idle. +This is a large part of the energy-efficiency requirement, +so I learned of this via an irate phone call. + +<p> +Because RCU avoids interrupting idle CPUs, it is illegal to +execute an RCU read-side critical section on an idle CPU. +(Kernels built with <tt>CONFIG_PROVE_RCU=y</tt> will splat +if you try it.) +The <tt>RCU_NONIDLE()</tt> macro and <tt>_rcuidle</tt> +event tracing is provided to work around this restriction. +In addition, <tt>rcu_is_watching()</tt> may be used to +test whether or not it is currently legal to run RCU read-side +critical sections on this CPU. +I learned of the need for diagnostics on the one hand +and <tt>RCU_NONIDLE()</tt> on the other while inspecting +idle-loop code. +Steven Rostedt supplied <tt>_rcuidle</tt> event tracing, +which is used quite heavily in the idle loop. + +<p> +It is similarly socially unacceptable to interrupt an +<tt>nohz_full</tt> CPU running in userspace. +RCU must therefore track <tt>nohz_full</tt> userspace +execution. +And in +<a href="https://lwn.net/Articles/558284/"><tt>CONFIG_NO_HZ_FULL_SYSIDLE=y</tt></a> +kernels, RCU must separately track idle CPUs on the one hand and +CPUs that are either idle or executing in userspace on the other. +In both cases, RCU must be able to sample state at two points in +time, and be able to determine whether or not some other CPU spent +any time idle and/or executing in userspace. + +<p> +These energy-efficiency requirements have proven quite difficult to +understand and to meet, for example, there have been more than five +clean-sheet rewrites of RCU's energy-efficiency code, the last of +which was finally able to demonstrate +<a href="http://www.rdrop.com/users/paulmck/realtime/paper/AMPenergy.2013.04.19a.pdf">real energy savings running on real hardware [PDF]</a>. +As noted earlier, +I learned of many of these requirements via angry phone calls: +Flaming me on the Linux-kernel mailing list was apparently not +sufficient to fully vent their ire at RCU's energy-efficiency bugs! + +<h3><a name="Memory Efficiency">Memory Efficiency</a></h3> + +<p> +Although small-memory non-realtime systems can simply use Tiny RCU, +code size is only one aspect of memory efficiency. +Another aspect is the size of the <tt>rcu_head</tt> structure +used by <tt>call_rcu()</tt> and <tt>kfree_rcu()</tt>. +Although this structure contains nothing more than a pair of pointers, +it does appear in many RCU-protected data structures, including +some that are size critical. +The <tt>page</tt> structure is a case in point, as evidenced by +the many occurrences of the <tt>union</tt> keyword within that structure. + +<p> +This need for memory efficiency is one reason that RCU uses hand-crafted +singly linked lists to track the <tt>rcu_head</tt> structures that +are waiting for a grace period to elapse. +It is also the reason why <tt>rcu_head</tt> structures do not contain +debug information, such as fields tracking the file and line of the +<tt>call_rcu()</tt> or <tt>kfree_rcu()</tt> that posted them. +Although this information might appear in debug-only kernel builds at some +point, in the meantime, the <tt>->func</tt> field will often provide +the needed debug information. + +<p> +However, in some cases, the need for memory efficiency leads to even +more extreme measures. +Returning to the <tt>page</tt> structure, the <tt>rcu_head</tt> field +shares storage with a great many other structures that are used at +various points in the corresponding page's lifetime. +In order to correctly resolve certain +<a href="https://lkml.kernel.org/g/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com">race conditions</a>, +the Linux kernel's memory-management subsystem needs a particular bit +to remain zero during all phases of grace-period processing, +and that bit happens to map to the bottom bit of the +<tt>rcu_head</tt> structure's <tt>->next</tt> field. +RCU makes this guarantee as long as <tt>call_rcu()</tt> +is used to post the callback, as opposed to <tt>kfree_rcu()</tt> +or some future “lazy” +variant of <tt>call_rcu()</tt> that might one day be created for +energy-efficiency purposes. + +<h3><a name="Performance, Scalability, Response Time, and Reliability"> +Performance, Scalability, Response Time, and Reliability</a></h3> + +<p> +Expanding on the +<a href="#Performance and Scalability">earlier discussion</a>, +RCU is used heavily by hot code paths in performance-critical +portions of the Linux kernel's networking, security, virtualization, +and scheduling code paths. +RCU must therefore use efficient implementations, especially in its +read-side primitives. +To that end, it would be good if preemptible RCU's implementation +of <tt>rcu_read_lock()</tt> could be inlined, however, doing +this requires resolving <tt>#include</tt> issues with the +<tt>task_struct</tt> structure. + +<p> +The Linux kernel supports hardware configurations with up to +4096 CPUs, which means that RCU must be extremely scalable. +Algorithms that involve frequent acquisitions of global locks or +frequent atomic operations on global variables simply cannot be +tolerated within the RCU implementation. +RCU therefore makes heavy use of a combining tree based on the +<tt>rcu_node</tt> structure. +RCU is required to tolerate all CPUs continuously invoking any +combination of RCU's runtime primitives with minimal per-operation +overhead. +In fact, in many cases, increasing load must <i>decrease</i> the +per-operation overhead, witness the batching optimizations for +<tt>synchronize_rcu()</tt>, <tt>call_rcu()</tt>, +<tt>synchronize_rcu_expedited()</tt>, and <tt>rcu_barrier()</tt>. +As a general rule, RCU must cheerfully accept whatever the +rest of the Linux kernel decides to throw at it. + +<p> +The Linux kernel is used for real-time workloads, especially +in conjunction with the +<a href="https://rt.wiki.kernel.org/index.php/Main_Page">-rt patchset</a>. +The real-time-latency response requirements are such that the +traditional approach of disabling preemption across RCU +read-side critical sections is inappropriate. +Kernels built with <tt>CONFIG_PREEMPT=y</tt> therefore +use an RCU implementation that allows RCU read-side critical +sections to be preempted. +This requirement made its presence known after users made it +clear that an earlier +<a href="https://lwn.net/Articles/107930/">real-time patch</a> +did not meet their needs, in conjunction with some +<a href="https://lkml.kernel.org/g/20050318002026.GA2693@us.ibm.com">RCU issues</a> +encountered by a very early version of the -rt patchset. + +<p> +In addition, RCU must make do with a sub-100-microsecond real-time latency +budget. +In fact, on smaller systems with the -rt patchset, the Linux kernel +provides sub-20-microsecond real-time latencies for the whole kernel, +including RCU. +RCU's scalability and latency must therefore be sufficient for +these sorts of configurations. +To my surprise, the sub-100-microsecond real-time latency budget +<a href="http://www.rdrop.com/users/paulmck/realtime/paper/bigrt.2013.01.31a.LCA.pdf"> +applies to even the largest systems [PDF]</a>, +up to and including systems with 4096 CPUs. +This real-time requirement motivated the grace-period kthread, which +also simplified handling of a number of race conditions. + +<p> +Finally, RCU's status as a synchronization primitive means that +any RCU failure can result in arbitrary memory corruption that can be +extremely difficult to debug. +This means that RCU must be extremely reliable, which in +practice also means that RCU must have an aggressive stress-test +suite. +This stress-test suite is called <tt>rcutorture</tt>. + +<p> +Although the need for <tt>rcutorture</tt> was no surprise, +the current immense popularity of the Linux kernel is posing +interesting—and perhaps unprecedented—validation +challenges. +To see this, keep in mind that there are well over one billion +instances of the Linux kernel running today, given Android +smartphones, Linux-powered televisions, and servers. +This number can be expected to increase sharply with the advent of +the celebrated Internet of Things. + +<p> +Suppose that RCU contains a race condition that manifests on average +once per million years of runtime. +This bug will be occurring about three times per <i>day</i> across +the installed base. +RCU could simply hide behind hardware error rates, given that no one +should really expect their smartphone to last for a million years. +However, anyone taking too much comfort from this thought should +consider the fact that in most jurisdictions, a successful multi-year +test of a given mechanism, which might include a Linux kernel, +suffices for a number of types of safety-critical certifications. +In fact, rumor has it that the Linux kernel is already being used +in production for safety-critical applications. +I don't know about you, but I would feel quite bad if a bug in RCU +killed someone. +Which might explain my recent focus on validation and verification. + +<h2><a name="Other RCU Flavors">Other RCU Flavors</a></h2> + +<p> +One of the more surprising things about RCU is that there are now +no fewer than five <i>flavors</i>, or API families. +In addition, the primary flavor that has been the sole focus up to +this point has two different implementations, non-preemptible and +preemptible. +The other four flavors are listed below, with requirements for each +described in a separate section. + +<ol> +<li> <a href="#Bottom-Half Flavor">Bottom-Half Flavor</a> +<li> <a href="#Sched Flavor">Sched Flavor</a> +<li> <a href="#Sleepable RCU">Sleepable RCU</a> +<li> <a href="#Tasks RCU">Tasks RCU</a> +</ol> + +<h3><a name="Bottom-Half Flavor">Bottom-Half Flavor</a></h3> + +<p> +The softirq-disable (AKA “bottom-half”, +hence the “_bh” abbreviations) +flavor of RCU, or <i>RCU-bh</i>, was developed by +Dipankar Sarma to provide a flavor of RCU that could withstand the +network-based denial-of-service attacks researched by Robert +Olsson. +These attacks placed so much networking load on the system +that some of the CPUs never exited softirq execution, +which in turn prevented those CPUs from ever executing a context switch, +which, in the RCU implementation of that time, prevented grace periods +from ever ending. +The result was an out-of-memory condition and a system hang. + +<p> +The solution was the creation of RCU-bh, which does +<tt>local_bh_disable()</tt> +across its read-side critical sections, and which uses the transition +from one type of softirq processing to another as a quiescent state +in addition to context switch, idle, user mode, and offline. +This means that RCU-bh grace periods can complete even when some of +the CPUs execute in softirq indefinitely, thus allowing algorithms +based on RCU-bh to withstand network-based denial-of-service attacks. + +<p> +Because +<tt>rcu_read_lock_bh()</tt> and <tt>rcu_read_unlock_bh()</tt> +disable and re-enable softirq handlers, any attempt to start a softirq +handlers during the +RCU-bh read-side critical section will be deferred. +In this case, <tt>rcu_read_unlock_bh()</tt> +will invoke softirq processing, which can take considerable time. +One can of course argue that this softirq overhead should be associated +with the code following the RCU-bh read-side critical section rather +than <tt>rcu_read_unlock_bh()</tt>, but the fact +is that most profiling tools cannot be expected to make this sort +of fine distinction. +For example, suppose that a three-millisecond-long RCU-bh read-side +critical section executes during a time of heavy networking load. +There will very likely be an attempt to invoke at least one softirq +handler during that three milliseconds, but any such invocation will +be delayed until the time of the <tt>rcu_read_unlock_bh()</tt>. +This can of course make it appear at first glance as if +<tt>rcu_read_unlock_bh()</tt> was executing very slowly. + +<p> +The +<a href="https://lwn.net/Articles/609973/#RCU Per-Flavor API Table">RCU-bh API</a> +includes +<tt>rcu_read_lock_bh()</tt>, +<tt>rcu_read_unlock_bh()</tt>, +<tt>rcu_dereference_bh()</tt>, +<tt>rcu_dereference_bh_check()</tt>, +<tt>synchronize_rcu_bh()</tt>, +<tt>synchronize_rcu_bh_expedited()</tt>, +<tt>call_rcu_bh()</tt>, +<tt>rcu_barrier_bh()</tt>, and +<tt>rcu_read_lock_bh_held()</tt>. + +<h3><a name="Sched Flavor">Sched Flavor</a></h3> + +<p> +Before preemptible RCU, waiting for an RCU grace period had the +side effect of also waiting for all pre-existing interrupt +and NMI handlers. +However, there are legitimate preemptible-RCU implementations that +do not have this property, given that any point in the code outside +of an RCU read-side critical section can be a quiescent state. +Therefore, <i>RCU-sched</i> was created, which follows “classic” +RCU in that an RCU-sched grace period waits for for pre-existing +interrupt and NMI handlers. +In kernels built with <tt>CONFIG_PREEMPT=n</tt>, the RCU and RCU-sched +APIs have identical implementations, while kernels built with +<tt>CONFIG_PREEMPT=y</tt> provide a separate implementation for each. + +<p> +Note well that in <tt>CONFIG_PREEMPT=y</tt> kernels, +<tt>rcu_read_lock_sched()</tt> and <tt>rcu_read_unlock_sched()</tt> +disable and re-enable preemption, respectively. +This means that if there was a preemption attempt during the +RCU-sched read-side critical section, <tt>rcu_read_unlock_sched()</tt> +will enter the scheduler, with all the latency and overhead entailed. +Just as with <tt>rcu_read_unlock_bh()</tt>, this can make it look +as if <tt>rcu_read_unlock_sched()</tt> was executing very slowly. +However, the highest-priority task won't be preempted, so that task +will enjoy low-overhead <tt>rcu_read_unlock_sched()</tt> invocations. + +<p> +The +<a href="https://lwn.net/Articles/609973/#RCU Per-Flavor API Table">RCU-sched API</a> +includes +<tt>rcu_read_lock_sched()</tt>, +<tt>rcu_read_unlock_sched()</tt>, +<tt>rcu_read_lock_sched_notrace()</tt>, +<tt>rcu_read_unlock_sched_notrace()</tt>, +<tt>rcu_dereference_sched()</tt>, +<tt>rcu_dereference_sched_check()</tt>, +<tt>synchronize_sched()</tt>, +<tt>synchronize_rcu_sched_expedited()</tt>, +<tt>call_rcu_sched()</tt>, +<tt>rcu_barrier_sched()</tt>, and +<tt>rcu_read_lock_sched_held()</tt>. +However, anything that disables preemption also marks an RCU-sched +read-side critical section, including +<tt>preempt_disable()</tt> and <tt>preempt_enable()</tt>, +<tt>local_irq_save()</tt> and <tt>local_irq_restore()</tt>, +and so on. + +<h3><a name="Sleepable RCU">Sleepable RCU</a></h3> + +<p> +For well over a decade, someone saying “I need to block within +an RCU read-side critical section” was a reliable indication +that this someone did not understand RCU. +After all, if you are always blocking in an RCU read-side critical +section, you can probably afford to use a higher-overhead synchronization +mechanism. +However, that changed with the advent of the Linux kernel's notifiers, +whose RCU read-side critical +sections almost never sleep, but sometimes need to. +This resulted in the introduction of +<a href="https://lwn.net/Articles/202847/">sleepable RCU</a>, +or <i>SRCU</i>. + +<p> +SRCU allows different domains to be defined, with each such domain +defined by an instance of an <tt>srcu_struct</tt> structure. +A pointer to this structure must be passed in to each SRCU function, +for example, <tt>synchronize_srcu(&ss)</tt>, where +<tt>ss</tt> is the <tt>srcu_struct</tt> structure. +The key benefit of these domains is that a slow SRCU reader in one +domain does not delay an SRCU grace period in some other domain. +That said, one consequence of these domains is that read-side code +must pass a “cookie” from <tt>srcu_read_lock()</tt> +to <tt>srcu_read_unlock()</tt>, for example, as follows: + +<blockquote> +<pre> + 1 int idx; + 2 + 3 idx = srcu_read_lock(&ss); + 4 do_something(); + 5 srcu_read_unlock(&ss, idx); +</pre> +</blockquote> + +<p> +As noted above, it is legal to block within SRCU read-side critical sections, +however, with great power comes great responsibility. +If you block forever in one of a given domain's SRCU read-side critical +sections, then that domain's grace periods will also be blocked forever. +Of course, one good way to block forever is to deadlock, which can +happen if any operation in a given domain's SRCU read-side critical +section can block waiting, either directly or indirectly, for that domain's +grace period to elapse. +For example, this results in a self-deadlock: + +<blockquote> +<pre> + 1 int idx; + 2 + 3 idx = srcu_read_lock(&ss); + 4 do_something(); + 5 synchronize_srcu(&ss); + 6 srcu_read_unlock(&ss, idx); +</pre> +</blockquote> + +<p> +However, if line 5 acquired a mutex that was held across +a <tt>synchronize_srcu()</tt> for domain <tt>ss</tt>, +deadlock would still be possible. +Furthermore, if line 5 acquired a mutex that was held across +a <tt>synchronize_srcu()</tt> for some other domain <tt>ss1</tt>, +and if an <tt>ss1</tt>-domain SRCU read-side critical section +acquired another mutex that was held across as <tt>ss</tt>-domain +<tt>synchronize_srcu()</tt>, +deadlock would again be possible. +Such a deadlock cycle could extend across an arbitrarily large number +of different SRCU domains. +Again, with great power comes great responsibility. + +<p> +Unlike the other RCU flavors, SRCU read-side critical sections can +run on idle and even offline CPUs. +This ability requires that <tt>srcu_read_lock()</tt> and +<tt>srcu_read_unlock()</tt> contain memory barriers, which means +that SRCU readers will run a bit slower than would RCU readers. +It also motivates the <tt>smp_mb__after_srcu_read_unlock()</tt> +API, which, in combination with <tt>srcu_read_unlock()</tt>, +guarantees a full memory barrier. + +<p> +The +<a href="https://lwn.net/Articles/609973/#RCU Per-Flavor API Table">SRCU API</a> +includes +<tt>srcu_read_lock()</tt>, +<tt>srcu_read_unlock()</tt>, +<tt>srcu_dereference()</tt>, +<tt>srcu_dereference_check()</tt>, +<tt>synchronize_srcu()</tt>, +<tt>synchronize_srcu_expedited()</tt>, +<tt>call_srcu()</tt>, +<tt>srcu_barrier()</tt>, and +<tt>srcu_read_lock_held()</tt>. +It also includes +<tt>DEFINE_SRCU()</tt>, +<tt>DEFINE_STATIC_SRCU()</tt>, and +<tt>init_srcu_struct()</tt> +APIs for defining and initializing <tt>srcu_struct</tt> structures. + +<h3><a name="Tasks RCU">Tasks RCU</a></h3> + +<p> +Some forms of tracing use “tramopolines” to handle the +binary rewriting required to install different types of probes. +It would be good to be able to free old trampolines, which sounds +like a job for some form of RCU. +However, because it is necessary to be able to install a trace +anywhere in the code, it is not possible to use read-side markers +such as <tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>. +In addition, it does not work to have these markers in the trampoline +itself, because there would need to be instructions following +<tt>rcu_read_unlock()</tt>. +Although <tt>synchronize_rcu()</tt> would guarantee that execution +reached the <tt>rcu_read_unlock()</tt>, it would not be able to +guarantee that execution had completely left the trampoline. + +<p> +The solution, in the form of +<a href="https://lwn.net/Articles/607117/"><i>Tasks RCU</i></a>, +is to have implicit +read-side critical sections that are delimited by voluntary context +switches, that is, calls to <tt>schedule()</tt>, +<tt>cond_resched_rcu_qs()</tt>, and +<tt>synchronize_rcu_tasks()</tt>. +In addition, transitions to and from userspace execution also delimit +tasks-RCU read-side critical sections. + +<p> +The tasks-RCU API is quite compact, consisting only of +<tt>call_rcu_tasks()</tt>, +<tt>synchronize_rcu_tasks()</tt>, and +<tt>rcu_barrier_tasks()</tt>. + +<h2><a name="Possible Future Changes">Possible Future Changes</a></h2> + +<p> +One of the tricks that RCU uses to attain update-side scalability is +to increase grace-period latency with increasing numbers of CPUs. +If this becomes a serious problem, it will be necessary to rework the +grace-period state machine so as to avoid the need for the additional +latency. + +<p> +Expedited grace periods scan the CPUs, so their latency and overhead +increases with increasing numbers of CPUs. +If this becomes a serious problem on large systems, it will be necessary +to do some redesign to avoid this scalability problem. + +<p> +RCU disables CPU hotplug in a few places, perhaps most notably in the +expedited grace-period and <tt>rcu_barrier()</tt> operations. +If there is a strong reason to use expedited grace periods in CPU-hotplug +notifiers, it will be necessary to avoid disabling CPU hotplug. +This would introduce some complexity, so there had better be a <i>very</i> +good reason. + +<p> +The tradeoff between grace-period latency on the one hand and interruptions +of other CPUs on the other hand may need to be re-examined. +The desire is of course for zero grace-period latency as well as zero +interprocessor interrupts undertaken during an expedited grace period +operation. +While this ideal is unlikely to be achievable, it is quite possible that +further improvements can be made. + +<p> +The multiprocessor implementations of RCU use a combining tree that +groups CPUs so as to reduce lock contention and increase cache locality. +However, this combining tree does not spread its memory across NUMA +nodes nor does it align the CPU groups with hardware features such +as sockets or cores. +Such spreading and alignment is currently believed to be unnecessary +because the hotpath read-side primitives do not access the combining +tree, nor does <tt>call_rcu()</tt> in the common case. +If you believe that your architecture needs such spreading and alignment, +then your architecture should also benefit from the +<tt>rcutree.rcu_fanout_leaf</tt> boot parameter, which can be set +to the number of CPUs in a socket, NUMA node, or whatever. +If the number of CPUs is too large, use a fraction of the number of +CPUs. +If the number of CPUs is a large prime number, well, that certainly +is an “interesting” architectural choice! +More flexible arrangements might be considered, but only if +<tt>rcutree.rcu_fanout_leaf</tt> has proven inadequate, and only +if the inadequacy has been demonstrated by a carefully run and +realistic system-level workload. + +<p> +Please note that arrangements that require RCU to remap CPU numbers will +require extremely good demonstration of need and full exploration of +alternatives. + +<p> +There is an embarrassingly large number of flavors of RCU, and this +number has been increasing over time. +Perhaps it will be possible to combine some at some future date. + +<p> +RCU's various kthreads are reasonably recent additions. +It is quite likely that adjustments will be required to more gracefully +handle extreme loads. +It might also be necessary to be able to relate CPU utilization by +RCU's kthreads and softirq handlers to the code that instigated this +CPU utilization. +For example, RCU callback overhead might be charged back to the +originating <tt>call_rcu()</tt> instance, though probably not +in production kernels. + +<h2><a name="Summary">Summary</a></h2> + +<p> +This document has presented more than two decade's worth of RCU +requirements. +Given that the requirements keep changing, this will not be the last +word on this subject, but at least it serves to get an important +subset of the requirements set forth. + +<h2><a name="Acknowledgments">Acknowledgments</a></h2> + +I am grateful to Steven Rostedt, Lai Jiangshan, Ingo Molnar, +Oleg Nesterov, Borislav Petkov, Peter Zijlstra, Boqun Feng, and +Andy Lutomirski for their help in rendering +this article human readable, and to Michelle Rankin for her support +of this effort. +Other contributions are acknowledged in the Linux kernel's git archive. +The cartoon is copyright (c) 2013 by Melissa Broussard, +and is provided +under the terms of the Creative Commons Attribution-Share Alike 3.0 +United States license. + +<p>@@QQAL@@ + +</body></html> diff --git a/Documentation/RCU/Design/htmlqqz.sh b/Documentation/RCU/Design/htmlqqz.sh new file mode 100755 index 000000000000..d354f069559b --- /dev/null +++ b/Documentation/RCU/Design/htmlqqz.sh @@ -0,0 +1,108 @@ +#!/bin/sh +# +# Usage: sh htmlqqz.sh file +# +# Extracts and converts quick quizzes in a proto-HTML document file.htmlx. +# Commands, all of which must be on a line by themselves: +# +# "<p>@@QQ@@": Start of a quick quiz. +# "<p>@@QQA@@": Start of a quick-quiz answer. +# "<p>@@QQE@@": End of a quick-quiz answer, and thus of the quick quiz. +# "<p>@@QQAL@@": Place to put quick-quiz answer list. +# +# Places the result in file.html. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, you can access it online at +# http://www.gnu.org/licenses/gpl-2.0.html. +# +# Copyright (c) 2013 Paul E. McKenney, IBM Corporation. + +fn=$1 +if test ! -r $fn.htmlx +then + echo "Error: $fn.htmlx unreadable." + exit 1 +fi + +echo "<!-- DO NOT HAND EDIT. -->" > $fn.html +echo "<!-- Instead, edit $fn.htmlx and run 'sh htmlqqz.sh $fn' -->" >> $fn.html +awk < $fn.htmlx >> $fn.html ' + +state == "" && $1 != "<p>@@QQ@@" && $1 != "<p>@@QQAL@@" { + print $0; + if ($0 ~ /^<p>@@QQ/) + print "Bad Quick Quiz command: " NR " (expected <p>@@QQ@@ or <p>@@QQAL@@)." > "/dev/stderr" + next; +} + +state == "" && $1 == "<p>@@QQ@@" { + qqn++; + qqlineno = NR; + haveqq = 1; + state = "qq"; + print "<p><a name=\"Quick Quiz " qqn "\"><b>Quick Quiz " qqn "</b>:</a>" + next; +} + +state == "qq" && $1 != "<p>@@QQA@@" { + qq[qqn] = qq[qqn] $0 "\n"; + print $0 + if ($0 ~ /^<p>@@QQ/) + print "Bad Quick Quiz command: " NR ". (expected <p>@@QQA@@)" > "/dev/stderr" + next; +} + +state == "qq" && $1 == "<p>@@QQA@@" { + state = "qqa"; + print "<br><a href=\"#qq" qqn "answer\">Answer</a>" + next; +} + +state == "qqa" && $1 != "<p>@@QQE@@" { + qqa[qqn] = qqa[qqn] $0 "\n"; + if ($0 ~ /^<p>@@QQ/) + print "Bad Quick Quiz command: " NR " (expected <p>@@QQE@@)." > "/dev/stderr" + next; +} + +state == "qqa" && $1 == "<p>@@QQE@@" { + state = ""; + next; +} + +state == "" && $1 == "<p>@@QQAL@@" { + haveqq = ""; + print "<h3><a name=\"Answers to Quick Quizzes\">" + print "Answers to Quick Quizzes</a></h3>" + print ""; + for (i = 1; i <= qqn; i++) { + print "<a name=\"qq" i "answer\"></a>" + print "<p><b>Quick Quiz " i "</b>:" + print qq[i]; + print ""; + print "</p><p><b>Answer</b>:" + print qqa[i]; + print ""; + print "</p><p><a href=\"#Quick%20Quiz%20" i "\"><b>Back to Quick Quiz " i "</b>.</a>" + print ""; + } + next; +} + +END { + if (state != "") + print "Unterminated Quick Quiz: " qqlineno "." > "/dev/stderr" + else if (haveqq) + print "Missing \"<p>@@QQAL@@\", no Quick Quiz." > "/dev/stderr" +}' diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index efb9454875ab..0f7fb4298e7e 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -205,6 +205,13 @@ o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the behavior, you might need to replace some of the cond_resched() calls with calls to cond_resched_rcu_qs(). +o Booting Linux using a console connection that is too slow to + keep up with the boot-time console-message rate. For example, + a 115Kbaud serial console can be -way- too slow to keep up + with boot-time message rates, and will frequently result in + RCU CPU stall warning messages. Especially if you have added + debug printk()s. + o Anything that prevents RCU's grace-period kthreads from running. This can result in the "All QSes seen" console-log message. This message will include information on when the kthread last diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt index dac02a6219b1..118e7c176ce7 100644 --- a/Documentation/RCU/torture.txt +++ b/Documentation/RCU/torture.txt @@ -166,40 +166,27 @@ test_no_idle_hz Whether or not to test the ability of RCU to operate in torture_type The type of RCU to test, with string values as follows: - "rcu": rcu_read_lock(), rcu_read_unlock() and call_rcu(). - - "rcu_sync": rcu_read_lock(), rcu_read_unlock(), and - synchronize_rcu(). - - "rcu_expedited": rcu_read_lock(), rcu_read_unlock(), and - synchronize_rcu_expedited(). + "rcu": rcu_read_lock(), rcu_read_unlock() and call_rcu(), + along with expedited, synchronous, and polling + variants. "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and - call_rcu_bh(). - - "rcu_bh_sync": rcu_read_lock_bh(), rcu_read_unlock_bh(), - and synchronize_rcu_bh(). + call_rcu_bh(), along with expedited and synchronous + variants. - "rcu_bh_expedited": rcu_read_lock_bh(), rcu_read_unlock_bh(), - and synchronize_rcu_bh_expedited(). + "rcu_busted": This tests an intentionally incorrect version + of RCU in order to help test rcutorture itself. "srcu": srcu_read_lock(), srcu_read_unlock() and - call_srcu(). - - "srcu_sync": srcu_read_lock(), srcu_read_unlock() and - synchronize_srcu(). - - "srcu_expedited": srcu_read_lock(), srcu_read_unlock() and - synchronize_srcu_expedited(). + call_srcu(), along with expedited and + synchronous variants. "sched": preempt_disable(), preempt_enable(), and - call_rcu_sched(). - - "sched_sync": preempt_disable(), preempt_enable(), and - synchronize_sched(). + call_rcu_sched(), along with expedited, + synchronous, and polling variants. - "sched_expedited": preempt_disable(), preempt_enable(), and - synchronize_sched_expedited(). + "tasks": voluntary context switch and call_rcu_tasks(), + along with expedited and synchronous variants. Defaults to "rcu". diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt index 97f17e9decda..ec6998b1b6d0 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt @@ -56,14 +56,14 @@ rcuboost: The output of "cat rcu/rcu_preempt/rcudata" looks as follows: - 0!c=30455 g=30456 pq=1/0 qp=1 dt=126535/140000000000000/0 df=2002 of=4 ql=0/0 qs=N... b=10 ci=74572 nci=0 co=1131 ca=716 - 1!c=30719 g=30720 pq=1/0 qp=0 dt=132007/140000000000000/0 df=1874 of=10 ql=0/0 qs=N... b=10 ci=123209 nci=0 co=685 ca=982 - 2!c=30150 g=30151 pq=1/1 qp=1 dt=138537/140000000000000/0 df=1707 of=8 ql=0/0 qs=N... b=10 ci=80132 nci=0 co=1328 ca=1458 - 3 c=31249 g=31250 pq=1/1 qp=0 dt=107255/140000000000000/0 df=1749 of=6 ql=0/450 qs=NRW. b=10 ci=151700 nci=0 co=509 ca=622 - 4!c=29502 g=29503 pq=1/0 qp=1 dt=83647/140000000000000/0 df=965 of=5 ql=0/0 qs=N... b=10 ci=65643 nci=0 co=1373 ca=1521 - 5 c=31201 g=31202 pq=1/0 qp=1 dt=70422/0/0 df=535 of=7 ql=0/0 qs=.... b=10 ci=58500 nci=0 co=764 ca=698 - 6!c=30253 g=30254 pq=1/0 qp=1 dt=95363/140000000000000/0 df=780 of=5 ql=0/0 qs=N... b=10 ci=100607 nci=0 co=1414 ca=1353 - 7 c=31178 g=31178 pq=1/0 qp=0 dt=91536/0/0 df=547 of=4 ql=0/0 qs=.... b=10 ci=109819 nci=0 co=1115 ca=969 + 0!c=30455 g=30456 cnq=1/0:1 dt=126535/140000000000000/0 df=2002 of=4 ql=0/0 qs=N... b=10 ci=74572 nci=0 co=1131 ca=716 + 1!c=30719 g=30720 cnq=1/0:0 dt=132007/140000000000000/0 df=1874 of=10 ql=0/0 qs=N... b=10 ci=123209 nci=0 co=685 ca=982 + 2!c=30150 g=30151 cnq=1/1:1 dt=138537/140000000000000/0 df=1707 of=8 ql=0/0 qs=N... b=10 ci=80132 nci=0 co=1328 ca=1458 + 3 c=31249 g=31250 cnq=1/1:0 dt=107255/140000000000000/0 df=1749 of=6 ql=0/450 qs=NRW. b=10 ci=151700 nci=0 co=509 ca=622 + 4!c=29502 g=29503 cnq=1/0:1 dt=83647/140000000000000/0 df=965 of=5 ql=0/0 qs=N... b=10 ci=65643 nci=0 co=1373 ca=1521 + 5 c=31201 g=31202 cnq=1/0:1 dt=70422/0/0 df=535 of=7 ql=0/0 qs=.... b=10 ci=58500 nci=0 co=764 ca=698 + 6!c=30253 g=30254 cnq=1/0:1 dt=95363/140000000000000/0 df=780 of=5 ql=0/0 qs=N... b=10 ci=100607 nci=0 co=1414 ca=1353 + 7 c=31178 g=31178 cnq=1/0:0 dt=91536/0/0 df=547 of=4 ql=0/0 qs=.... b=10 ci=109819 nci=0 co=1115 ca=969 This file has one line per CPU, or eight for this 8-CPU system. The fields are as follows: @@ -188,14 +188,14 @@ o "ca" is the number of RCU callbacks that have been adopted by this Kernels compiled with CONFIG_RCU_BOOST=y display the following from /debug/rcu/rcu_preempt/rcudata: - 0!c=12865 g=12866 pq=1/0 qp=1 dt=83113/140000000000000/0 df=288 of=11 ql=0/0 qs=N... kt=0/O ktl=944 b=10 ci=60709 nci=0 co=748 ca=871 - 1 c=14407 g=14408 pq=1/0 qp=0 dt=100679/140000000000000/0 df=378 of=7 ql=0/119 qs=NRW. kt=0/W ktl=9b6 b=10 ci=109740 nci=0 co=589 ca=485 - 2 c=14407 g=14408 pq=1/0 qp=0 dt=105486/0/0 df=90 of=9 ql=0/89 qs=NRW. kt=0/W ktl=c0c b=10 ci=83113 nci=0 co=533 ca=490 - 3 c=14407 g=14408 pq=1/0 qp=0 dt=107138/0/0 df=142 of=8 ql=0/188 qs=NRW. kt=0/W ktl=b96 b=10 ci=121114 nci=0 co=426 ca=290 - 4 c=14405 g=14406 pq=1/0 qp=1 dt=50238/0/0 df=706 of=7 ql=0/0 qs=.... kt=0/W ktl=812 b=10 ci=34929 nci=0 co=643 ca=114 - 5!c=14168 g=14169 pq=1/0 qp=0 dt=45465/140000000000000/0 df=161 of=11 ql=0/0 qs=N... kt=0/O ktl=b4d b=10 ci=47712 nci=0 co=677 ca=722 - 6 c=14404 g=14405 pq=1/0 qp=0 dt=59454/0/0 df=94 of=6 ql=0/0 qs=.... kt=0/W ktl=e57 b=10 ci=55597 nci=0 co=701 ca=811 - 7 c=14407 g=14408 pq=1/0 qp=1 dt=68850/0/0 df=31 of=8 ql=0/0 qs=.... kt=0/W ktl=14bd b=10 ci=77475 nci=0 co=508 ca=1042 + 0!c=12865 g=12866 cnq=1/0:1 dt=83113/140000000000000/0 df=288 of=11 ql=0/0 qs=N... kt=0/O ktl=944 b=10 ci=60709 nci=0 co=748 ca=871 + 1 c=14407 g=14408 cnq=1/0:0 dt=100679/140000000000000/0 df=378 of=7 ql=0/119 qs=NRW. kt=0/W ktl=9b6 b=10 ci=109740 nci=0 co=589 ca=485 + 2 c=14407 g=14408 cnq=1/0:0 dt=105486/0/0 df=90 of=9 ql=0/89 qs=NRW. kt=0/W ktl=c0c b=10 ci=83113 nci=0 co=533 ca=490 + 3 c=14407 g=14408 cnq=1/0:0 dt=107138/0/0 df=142 of=8 ql=0/188 qs=NRW. kt=0/W ktl=b96 b=10 ci=121114 nci=0 co=426 ca=290 + 4 c=14405 g=14406 cnq=1/0:1 dt=50238/0/0 df=706 of=7 ql=0/0 qs=.... kt=0/W ktl=812 b=10 ci=34929 nci=0 co=643 ca=114 + 5!c=14168 g=14169 cnq=1/0:0 dt=45465/140000000000000/0 df=161 of=11 ql=0/0 qs=N... kt=0/O ktl=b4d b=10 ci=47712 nci=0 co=677 ca=722 + 6 c=14404 g=14405 cnq=1/0:0 dt=59454/0/0 df=94 of=6 ql=0/0 qs=.... kt=0/W ktl=e57 b=10 ci=55597 nci=0 co=701 ca=811 + 7 c=14407 g=14408 cnq=1/0:1 dt=68850/0/0 df=31 of=8 ql=0/0 qs=.... kt=0/W ktl=14bd b=10 ci=77475 nci=0 co=508 ca=1042 This is similar to the output discussed above, but contains the following additional fields: diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index adc2184009c5..dc49c6712b17 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -364,7 +364,7 @@ uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt. }; DEFINE_SPINLOCK(foo_mutex); - struct foo *gbl_foo; + struct foo __rcu *gbl_foo; /* * Create a new struct foo that is the same as the one currently @@ -386,7 +386,7 @@ uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt. new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL); spin_lock(&foo_mutex); - old_fp = gbl_foo; + old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex)); *new_fp = *old_fp; new_fp->a = new_a; rcu_assign_pointer(gbl_foo, new_fp); @@ -487,7 +487,7 @@ The foo_update_a() function might then be written as follows: new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL); spin_lock(&foo_mutex); - old_fp = gbl_foo; + old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex)); *new_fp = *old_fp; new_fp->a = new_a; rcu_assign_pointer(gbl_foo, new_fp); diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index fd89b04d34f0..8c79f1d53731 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -659,8 +659,8 @@ succinct and descriptive, but that is what a well-written summary should do. The "summary phrase" may be prefixed by tags enclosed in square -brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not -considered part of the summary phrase, but describe how the patch +brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are +not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if the multiple versions of the patch have been sent out in response to comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for @@ -672,8 +672,8 @@ the patch series. A couple of example Subjects: - Subject: [patch 2/5] ext2: improve scalability of bitmap searching - Subject: [PATCHv2 001/207] x86: fix eflags tracking + Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCH v2 01/27] x86: fix eflags tracking The "from" line must be the very first line in the message body, and has the form: @@ -718,8 +718,21 @@ generates appropriate diffstats by default.) See more details on the proper patch format in the following references. +15) Explicit In-Reply-To headers +-------------------------------- + +It can be helpful to manually add In-Reply-To: headers to a patch +(e.g., when using "git send-email") to associate the patch with +previous relevant discussion, e.g. to link a bug fix to the email with +the bug report. However, for a multi-patch series, it is generally +best to avoid using In-Reply-To: to link to older versions of the +series. This way multiple versions of the patch don't become an +unmanageable forest of references in email clients. If a link is +helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in +the cover email text) to link to an earlier version of the patch series. + -15) Sending "git pull" requests +16) Sending "git pull" requests ------------------------------- If you have a series of patches, it may be most convenient to have the diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index f40578026a04..7785fb5eb93f 100644 --- a/Documentation/accounting/getdelays.c +++ b/Documentation/accounting/getdelays.c @@ -375,7 +375,8 @@ int main(int argc, char *argv[]) } } - if ((nl_sd = create_nl_socket(NETLINK_GENERIC)) < 0) + nl_sd = create_nl_socket(NETLINK_GENERIC); + if (nl_sd < 0) err(1, "error creating Netlink socket\n"); diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt index b731b292e812..a91ec5af52df 100644 --- a/Documentation/acpi/enumeration.txt +++ b/Documentation/acpi/enumeration.txt @@ -347,13 +347,18 @@ For the first case, the MFD drivers do not need to do anything. The resulting child platform device will have its ACPI_COMPANION() set to point to the parent device. -If the ACPI namespace has a device that we can match using an ACPI id, -the id should be set like: +If the ACPI namespace has a device that we can match using an ACPI id or ACPI +adr, the cell should be set like: + + static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = { + .pnpid = "XYZ0001", + .adr = 0, + }; static struct mfd_cell my_subdevice_cell = { .name = "my_subdevice", /* set the resources relative to the parent */ - .acpi_pnpid = "XYZ0001", + .acpi_match = &my_subdevice_cell_acpi_match, }; The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under diff --git a/Documentation/acpi/i2c-muxes.txt b/Documentation/acpi/i2c-muxes.txt new file mode 100644 index 000000000000..9fcc4f0b885e --- /dev/null +++ b/Documentation/acpi/i2c-muxes.txt @@ -0,0 +1,58 @@ +ACPI I2C Muxes +-------------- + +Describing an I2C device hierarchy that includes I2C muxes requires an ACPI +Device () scope per mux channel. + +Consider this topology: + ++------+ +------+ +| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50) +| | | 0x70 |--CH01--> i2c client B (0x50) ++------+ +------+ + +which corresponds to the following ASL: + +Device (SMB1) +{ + Name (_HID, ...) + Device (MUX0) + { + Name (_HID, ...) + Name (_CRS, ResourceTemplate () { + I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED, + AddressingMode7Bit, "^SMB1", 0x00, + ResourceConsumer,,) + } + + Device (CH00) + { + Name (_ADR, 0) + + Device (CLIA) + { + Name (_HID, ...) + Name (_CRS, ResourceTemplate () { + I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED, + AddressingMode7Bit, "^CH00", 0x00, + ResourceConsumer,,) + } + } + } + + Device (CH01) + { + Name (_ADR, 1) + + Device (CLIB) + { + Name (_HID, ...) + Name (_CRS, ResourceTemplate () { + I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED, + AddressingMode7Bit, "^CH01", 0x00, + ResourceConsumer,,) + } + } + } + } +} diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README index 18a775d10172..ae89b67d8e23 100644 --- a/Documentation/arm/Marvell/README +++ b/Documentation/arm/Marvell/README @@ -233,29 +233,30 @@ MMP/MMP2 family (communication processor) Linux kernel mach directory: arch/arm/mach-mmp Linux kernel plat directory: arch/arm/plat-pxa -Berlin family (Digital Entertainment) +Berlin family (Multimedia Solutions) ------------------------------------- Flavors: - 88DE3005, Armada 1500-mini + 88DE3005, Armada 1500 Mini Design name: BG2CD Core: ARM Cortex-A9, PL310 L2CC - Homepage: http://www.marvell.com/digital-entertainment/armada-1500-mini/ + Homepage: http://www.marvell.com/multimedia-solutions/armada-1500-mini/ + 88DE3006, Armada 1500 Mini Plus + Design name: BG2CDP + Core: Dual Core ARM Cortex-A7 + Homepage: http://www.marvell.com/multimedia-solutions/armada-1500-mini-plus/ 88DE3100, Armada 1500 Design name: BG2 Core: Marvell PJ4B (ARMv7), Tauros3 L2CC - Homepage: http://www.marvell.com/digital-entertainment/armada-1500/ - Product Brief: http://www.marvell.com/digital-entertainment/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf + Product Brief: http://www.marvell.com/multimedia-solutions/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf 88DE3114, Armada 1500 Pro - Design name: BG2-Q + Design name: BG2Q Core: Quad Core ARM Cortex-A9, PL310 L2CC - Homepage: http://www.marvell.com/digital-entertainment/armada-1500-pro/ - Product Brief: http://www.marvell.com/digital-entertainment/armada-1500-pro/assets/Marvell_ARMADA_1500_PRO-01_product_brief.pdf 88DE???? Design name: BG3 Core: ARM Cortex-A15, CA15 integrated L2CC - Homepage: http://www.marvell.com/digital-entertainment/ + Homepage: http://www.marvell.com/multimedia-solutions/ Directory: arch/arm/mach-berlin Comments: diff --git a/Documentation/arm/SA1100/Victor b/Documentation/arm/SA1100/Victor deleted file mode 100644 index 9cff415da5a7..000000000000 --- a/Documentation/arm/SA1100/Victor +++ /dev/null @@ -1,16 +0,0 @@ -Victor is known as a "digital talking book player" manufactured by -VisuAide, Inc. to be used by blind people. - -For more information related to Victor, see: - - http://www.humanware.com/en-usa/products - -Of course Victor is using Linux as its main operating system. -The Victor implementation for Linux is maintained by Nicolas Pitre: - - nico@visuaide.com - nico@fluxnic.net - -For any comments, please feel free to contact me through the above -addresses. - diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/Samsung/Bootloader-interface.txt index df8d4fb85939..ed494ac0beb2 100644 --- a/Documentation/arm/Samsung/Bootloader-interface.txt +++ b/Documentation/arm/Samsung/Bootloader-interface.txt @@ -19,7 +19,7 @@ executing kernel. Address: sysram_ns_base_addr Offset Value Purpose ============================================================================= -0x08 exynos_cpu_resume_ns System suspend +0x08 exynos_cpu_resume_ns, mcpm_entry_point System suspend 0x0c 0x00000bad (Magic cookie) System suspend 0x1c exynos4_secondary_startup Secondary CPU boot 0x1c + 4*cpu exynos4_secondary_startup (Exynos4412) Secondary CPU boot @@ -56,7 +56,8 @@ Offset Value Purpose Address: pmu_base_addr Offset Value Purpose ============================================================================= -0x0908 Non-zero (only Exynos3250) Secondary CPU boot up indicator +0x0908 Non-zero Secondary CPU boot up indicator + on Exynos3250 and Exynos542x 4. Glossary diff --git a/Documentation/arm/Samsung/clksrc-change-registers.awk b/Documentation/arm/Samsung/clksrc-change-registers.awk index d9174fabe37e..7be1b8aa7cd9 100755 --- a/Documentation/arm/Samsung/clksrc-change-registers.awk +++ b/Documentation/arm/Samsung/clksrc-change-registers.awk @@ -41,7 +41,7 @@ function find_length(f) else if (f ~ /0xf/) return 4 - printf "unknown legnth " f "\n" > "/dev/stderr" + printf "unknown length " f "\n" > "/dev/stderr" exit } diff --git a/Documentation/arm/keystone/Overview.txt b/Documentation/arm/keystone/Overview.txt index f17bc4c9dff9..400c0c270d2e 100644 --- a/Documentation/arm/keystone/Overview.txt +++ b/Documentation/arm/keystone/Overview.txt @@ -49,24 +49,6 @@ specified through DTS. Following are the DTS used:- The device tree documentation for the keystone machines are located at Documentation/devicetree/bindings/arm/keystone/keystone.txt -Known issues & workaround -------------------------- - -Some of the device drivers used on keystone are re-used from that from -DaVinci and other TI SoCs. These device drivers may use clock APIs directly. -Some of the keystone specific drivers such as netcp uses run time power -management API instead to enable clock. As this API has limitations on -keystone, following workaround is needed to boot Linux. - - Add 'clk_ignore_unused' to the bootargs env variable in u-boot. Otherwise - clock frameworks will try to disable clocks that are unused and disable - the hardware. This is because netcp related power domain and clock - domains are enabled in u-boot as run time power management API currently - doesn't enable clocks for netcp due to a limitation. This workaround is - expected to be removed in the future when proper API support becomes - available. Until then, this work around is needed. - - Document Author --------------- Murali Karicheri <m-karicheri2@ti.com> diff --git a/Documentation/arm/keystone/knav-qmss.txt b/Documentation/arm/keystone/knav-qmss.txt new file mode 100644 index 000000000000..fcdb9fd5f53a --- /dev/null +++ b/Documentation/arm/keystone/knav-qmss.txt @@ -0,0 +1,56 @@ +* Texas Instruments Keystone Navigator Queue Management SubSystem driver + +Driver source code path + drivers/soc/ti/knav_qmss.c + drivers/soc/ti/knav_qmss_acc.c + +The QMSS (Queue Manager Sub System) found on Keystone SOCs is one of +the main hardware sub system which forms the backbone of the Keystone +multi-core Navigator. QMSS consist of queue managers, packed-data structure +processors(PDSP), linking RAM, descriptor pools and infrastructure +Packet DMA. +The Queue Manager is a hardware module that is responsible for accelerating +management of the packet queues. Packets are queued/de-queued by writing or +reading descriptor address to a particular memory mapped location. The PDSPs +perform QMSS related functions like accumulation, QoS, or event management. +Linking RAM registers are used to link the descriptors which are stored in +descriptor RAM. Descriptor RAM is configurable as internal or external memory. +The QMSS driver manages the PDSP setups, linking RAM regions, +queue pool management (allocation, push, pop and notify) and descriptor +pool management. + +knav qmss driver provides a set of APIs to drivers to open/close qmss queues, +allocate descriptor pools, map the descriptors, push/pop to queues etc. For +details of the available APIs, please refers to include/linux/soc/ti/knav_qmss.h + +DT documentation is available at +Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt + +Accumulator QMSS queues using PDSP firmware +============================================ +The QMSS PDSP firmware support accumulator channel that can monitor a single +queue or multiple contiguous queues. drivers/soc/ti/knav_qmss_acc.c is the +driver that interface with the accumulator PDSP. This configures +accumulator channels defined in DTS (example in DT documentation) to monitor +1 or 32 queues per channel. More description on the firmware is available in +CPPI/QMSS Low Level Driver document (docs/CPPI_QMSS_LLD_SDS.pdf) at + git://git.ti.com/keystone-rtos/qmss-lld.git + +k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin firmware supports upto 48 accumulator +channels. This firmware is available under ti-keystone folder of +firmware.git at + git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git + +To use copy the firmware image to lib/firmware folder of the initramfs or +ubifs file system and provide a sym link to k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin +in the file system and boot up the kernel. User would see + + "firmware file ks2_qmss_pdsp_acc48.bin downloaded for PDSP" + +in the boot up log if loading of firmware to PDSP is successful. + +Use of accumulated queues requires the firmware image to be present in the +file system. The driver doesn't acc queues to the supported queue range if +PDSP is not running in the SoC. The API call fails if there is a queue open +request to an acc queue and PDSP is not running. So make sure to copy firmware +to file system before using these queue types. diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt index 4178ebda6e66..546a39048eb0 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.txt @@ -54,7 +54,7 @@ VMALLOC_START VMALLOC_END-1 vmalloc() / ioremap() space. located here through iotable_init(). VMALLOC_START is based upon the value of the high_memory variable, and VMALLOC_END - is equal to 0xff000000. + is equal to 0xff800000. PAGE_OFFSET high_memory-1 Kernel direct-mapped RAM region. This maps the platforms RAM, and typically diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.txt index a179e5bc02c9..0b7cab978c02 100644 --- a/Documentation/arm/pxa/mfp.txt +++ b/Documentation/arm/pxa/mfp.txt @@ -49,7 +49,7 @@ to this new MFP mechanism, here are several key points: internal controllers like PWM, SSP and UART, with 128 internal signals which can be routed to external through one or more MFPs (e.g. GPIO<0> can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2, - see arch/arm/mach-pxa/mach/include/mfp-pxa300.h) + see arch/arm/mach-pxa/mfp-pxa300.h) 2. Alternate function configuration is removed from this GPIO controller, the remaining functions are pure GPIO-specific, i.e. @@ -76,11 +76,11 @@ For board code writers, here are some guidelines: 1. include ONE of the following header files in your <board>.c: - - #include <mach/mfp-pxa25x.h> - - #include <mach/mfp-pxa27x.h> - - #include <mach/mfp-pxa300.h> - - #include <mach/mfp-pxa320.h> - - #include <mach/mfp-pxa930.h> + - #include "mfp-pxa25x.h" + - #include "mfp-pxa27x.h" + - #include "mfp-pxa300.h" + - #include "mfp-pxa320.h" + - #include "mfp-pxa930.h" NOTE: only one file in your <board>.c, depending on the processors used, because pin configuration definitions may conflict in these file (i.e. @@ -203,20 +203,20 @@ make them effective there-after. 1. Unified pin definitions - enum constants for all configurable pins 2. processor-neutral bit definitions for a possible MFP configuration - - arch/arm/mach-pxa/include/mach/mfp-pxa3xx.h + - arch/arm/mach-pxa/mfp-pxa3xx.h for PXA3xx specific MFPR register bit definitions and PXA3xx common pin configurations - - arch/arm/mach-pxa/include/mach/mfp-pxa2xx.h + - arch/arm/mach-pxa/mfp-pxa2xx.h for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations - - arch/arm/mach-pxa/include/mach/mfp-pxa25x.h - arch/arm/mach-pxa/include/mach/mfp-pxa27x.h - arch/arm/mach-pxa/include/mach/mfp-pxa300.h - arch/arm/mach-pxa/include/mach/mfp-pxa320.h - arch/arm/mach-pxa/include/mach/mfp-pxa930.h + - arch/arm/mach-pxa/mfp-pxa25x.h + arch/arm/mach-pxa/mfp-pxa27x.h + arch/arm/mach-pxa/mfp-pxa300.h + arch/arm/mach-pxa/mfp-pxa320.h + arch/arm/mach-pxa/mfp-pxa930.h for processor specific definitions diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README index 5e38e1582f95..430d279a8df3 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi/README @@ -25,7 +25,7 @@ SunXi family + Datasheet http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf - - Allwinner A13 (sun5i) + - Allwinner A13 / R8 (sun5i) + Datasheet http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf + User Manual diff --git a/Documentation/arm/uefi.txt b/Documentation/arm/uefi.txt index d60030a1b909..6543a0adea8a 100644 --- a/Documentation/arm/uefi.txt +++ b/Documentation/arm/uefi.txt @@ -58,7 +58,3 @@ linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI -------------------------------------------------------------------------------- linux,uefi-mmap-desc-ver | 32-bit | Version of the mmap descriptor format. -------------------------------------------------------------------------------- -linux,uefi-stub-kern-ver | string | Copy of linux_banner from build. --------------------------------------------------------------------------------- - -For verbose debug messages, specify 'uefi_debug' on the kernel command line. diff --git a/Documentation/arm64/booting.txt b/Documentation/arm64/booting.txt index 7d9d3c2286b2..56d6d8b796db 100644 --- a/Documentation/arm64/booting.txt +++ b/Documentation/arm64/booting.txt @@ -104,7 +104,18 @@ Header notes: - The flags field (introduced in v3.17) is a little-endian 64-bit field composed as follows: Bit 0: Kernel endianness. 1 if BE, 0 if LE. - Bits 1-63: Reserved. + Bit 1-2: Kernel Page size. + 0 - Unspecified. + 1 - 4K + 2 - 16K + 3 - 64K + Bit 3: Kernel physical placement + 0 - 2MB aligned base should be as close as possible + to the base of DRAM, since memory below it is not + accessible via the linear mapping + 1 - 2MB aligned base may be anywhere in physical + memory + Bits 4-63: Reserved. - When image_size is zero, a bootloader should attempt to keep as much memory as possible free for use by the kernel immediately after the @@ -112,14 +123,14 @@ Header notes: depending on selected features, and is effectively unbound. The Image must be placed text_offset bytes from a 2MB aligned base -address near the start of usable system RAM and called there. Memory -below that base address is currently unusable by Linux, and therefore it -is strongly recommended that this location is the start of system RAM. -The region between the 2 MB aligned base address and the start of the -image has no special significance to the kernel, and may be used for -other purposes. +address anywhere in usable system RAM and called there. The region +between the 2 MB aligned base address and the start of the image has no +special significance to the kernel, and may be used for other purposes. At least image_size bytes from the start of the image must be free for use by the kernel. +NOTE: versions prior to v4.6 cannot make use of memory below the +physical offset of the Image so it is recommended that the Image be +placed as close as possible to the start of system RAM. Any memory described to the kernel (even that below the start of the image) which is not marked as reserved from the kernel (e.g., with a @@ -173,13 +184,22 @@ Before jumping into the kernel, the following conditions must be met: the kernel image will be entered must be initialised by software at a higher exception level to prevent execution in an UNKNOWN state. - For systems with a GICv3 interrupt controller: + For systems with a GICv3 interrupt controller to be used in v3 mode: - If EL3 is present: ICC_SRE_EL3.Enable (bit 3) must be initialiased to 0b1. ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b1. - If the kernel is entered at EL1: ICC.SRE_EL2.Enable (bit 3) must be initialised to 0b1 ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b1. + - The DT or ACPI tables must describe a GICv3 interrupt controller. + + For systems with a GICv3 interrupt controller to be used in + compatibility (v2) mode: + - If EL3 is present: + ICC_SRE_EL3.SRE (bit 0) must be initialised to 0b0. + - If the kernel is entered at EL1: + ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0. + - The DT or ACPI tables must describe a GICv2 interrupt controller. The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt new file mode 100644 index 000000000000..ba4b6acfc545 --- /dev/null +++ b/Documentation/arm64/silicon-errata.txt @@ -0,0 +1,59 @@ + Silicon Errata and Software Workarounds + ======================================= + +Author: Will Deacon <will.deacon@arm.com> +Date : 27 November 2015 + +It is an unfortunate fact of life that hardware is often produced with +so-called "errata", which can cause it to deviate from the architecture +under specific circumstances. For hardware produced by ARM, these +errata are broadly classified into the following categories: + + Category A: A critical error without a viable workaround. + Category B: A significant or critical error with an acceptable + workaround. + Category C: A minor error that is not expected to occur under normal + operation. + +For more information, consult one of the "Software Developers Errata +Notice" documents available on infocenter.arm.com (registration +required). + +As far as Linux is concerned, Category B errata may require some special +treatment in the operating system. For example, avoiding a particular +sequence of code, or configuring the processor in a particular way. A +less common situation may require similar actions in order to declassify +a Category A erratum into a Category C erratum. These are collectively +known as "software workarounds" and are only required in the minority of +cases (e.g. those cases that both require a non-secure workaround *and* +can be triggered by Linux). + +For software workarounds that may adversely impact systems unaffected by +the erratum in question, a Kconfig entry is added under "Kernel +Features" -> "ARM errata workarounds via the alternatives framework". +These are enabled by default and patched in at runtime when an affected +CPU is detected. For less-intrusive workarounds, a Kconfig option is not +available and the code is structured (preferably with a comment) in such +a way that the erratum will not be hit. + +This approach can make it slightly onerous to determine exactly which +errata are worked around in an arbitrary kernel source tree, so this +file acts as a registry of software workarounds in the Linux Kernel and +will be updated when new workarounds are committed and backported to +stable kernels. + +| Implementor | Component | Erratum ID | Kconfig | ++----------------+-----------------+-----------------+-------------------------+ +| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | +| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | +| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | +| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | +| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | +| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | +| ARM | Cortex-A57 | #852523 | N/A | +| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | +| | | | | +| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | +| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | +| Cavium | ThunderX Core | #27456 | CAVIUM_ERRATUM_27456 | diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt index b19fc34efdb1..c9d1cacb4395 100644 --- a/Documentation/atomic_ops.txt +++ b/Documentation/atomic_ops.txt @@ -542,6 +542,10 @@ The routines xchg() and cmpxchg() must provide the same exact memory-barrier semantics as the atomic and bit operations returning values. +Note: If someone wants to use xchg(), cmpxchg() and their variants, +linux/atomic.h should be included rather than asm/cmpxchg.h, unless +the code is in arch/* and can take care of itself. + Spinlocks and rwlocks have memory barrier expectations as well. The rule to follow is simple: diff --git a/Documentation/block/cfq-iosched.txt b/Documentation/block/cfq-iosched.txt index f3bc72945cbd..1e4f835a659d 100644 --- a/Documentation/block/cfq-iosched.txt +++ b/Documentation/block/cfq-iosched.txt @@ -81,14 +81,13 @@ on higher end storage. Default value for this parameter is 8ms. -latency -------- -This parameter is used to enable/disable the latency mode of the CFQ -scheduler. If latency mode (called low_latency) is enabled, CFQ tries -to recompute the slice time for each process based on the target_latency set -for the system. This favors fairness over throughput. Disabling low -latency (setting it to 0) ignores target latency, allowing each process in the -system to get a full time slice. +low_latency +----------- +This parameter is used to enable/disable the low latency mode of the CFQ +scheduler. If enabled, CFQ tries to recompute the slice time for each process +based on the target_latency set for the system. This favors fairness over +throughput. Disabling low latency (setting it to 0) ignores target latency, +allowing each process in the system to get a full time slice. By default low latency mode is enabled. diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.txt index 2f6c6ff7161d..d8880ca30af4 100644 --- a/Documentation/block/null_blk.txt +++ b/Documentation/block/null_blk.txt @@ -70,3 +70,6 @@ use_per_node_hctx=[0/1]: Default: 0 parameter. 1: The multi-queue block layer is instantiated with a hardware dispatch queue for each CPU node in the system. + +use_lightnvm=[0/1]: Default: 0 + Register device with LightNVM. Requires blk-mq to be used. diff --git a/Documentation/block/pr.txt b/Documentation/block/pr.txt new file mode 100644 index 000000000000..d3eb1ca65051 --- /dev/null +++ b/Documentation/block/pr.txt @@ -0,0 +1,119 @@ + +Block layer support for Persistent Reservations +=============================================== + +The Linux kernel supports a user space interface for simplified +Persistent Reservations which map to block devices that support +these (like SCSI). Persistent Reservations allow restricting +access to block devices to specific initiators in a shared storage +setup. + +This document gives a general overview of the support ioctl commands. +For a more detailed reference please refer the the SCSI Primary +Commands standard, specifically the section on Reservations and the +"PERSISTENT RESERVE IN" and "PERSISTENT RESERVE OUT" commands. + +All implementations are expected to ensure the reservations survive +a power loss and cover all connections in a multi path environment. +These behaviors are optional in SPC but will be automatically applied +by Linux. + + +The following types of reservations are supported: +-------------------------------------------------- + + - PR_WRITE_EXCLUSIVE + + Only the initiator that owns the reservation can write to the + device. Any initiator can read from the device. + + - PR_EXCLUSIVE_ACCESS + + Only the initiator that owns the reservation can access the + device. + + - PR_WRITE_EXCLUSIVE_REG_ONLY + + Only initiators with a registered key can write to the device, + Any initiator can read from the device. + + - PR_EXCLUSIVE_ACCESS_REG_ONLY + + Only initiators with a registered key can access the device. + + - PR_WRITE_EXCLUSIVE_ALL_REGS + + Only initiators with a registered key can write to the device, + Any initiator can read from the device. + All initiators with a registered key are considered reservation + holders. + Please reference the SPC spec on the meaning of a reservation + holder if you want to use this type. + + - PR_EXCLUSIVE_ACCESS_ALL_REGS + + Only initiators with a registered key can access the device. + All initiators with a registered key are considered reservation + holders. + Please reference the SPC spec on the meaning of a reservation + holder if you want to use this type. + + +The following ioctl are supported: +---------------------------------- + +1. IOC_PR_REGISTER + +This ioctl command registers a new reservation if the new_key argument +is non-null. If no existing reservation exists old_key must be zero, +if an existing reservation should be replaced old_key must contain +the old reservation key. + +If the new_key argument is 0 it unregisters the existing reservation passed +in old_key. + + +2. IOC_PR_RESERVE + +This ioctl command reserves the device and thus restricts access for other +devices based on the type argument. The key argument must be the existing +reservation key for the device as acquired by the IOC_PR_REGISTER, +IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands. + + +3. IOC_PR_RELEASE + +This ioctl command releases the reservation specified by key and flags +and thus removes any access restriction implied by it. + + +4. IOC_PR_PREEMPT + +This ioctl command releases the existing reservation referred to by +old_key and replaces it with a a new reservation of type for the +reservation key new_key. + + +5. IOC_PR_PREEMPT_ABORT + +This ioctl command works like IOC_PR_PREEMPT except that it also aborts +any outstanding command sent over a connection identified by old_key. + +6. IOC_PR_CLEAR + +This ioctl command unregisters both key and any other reservation key +registered with the device and drops any existing reservation. + + +Flags +----- + +All the ioctls have a flag field. Currently only one flag is supported: + + - PR_FL_IGNORE_KEY + + Ignore the existing reservation key. This is commonly supported for + IOC_PR_REGISTER, and some implementation may support the flag for + IOC_PR_RESERVE. + +For all unknown flags the kernel will return -EOPNOTSUPP. diff --git a/Documentation/blockdev/cpqarray.txt b/Documentation/blockdev/cpqarray.txt deleted file mode 100644 index c7154e20ef5e..000000000000 --- a/Documentation/blockdev/cpqarray.txt +++ /dev/null @@ -1,93 +0,0 @@ -This driver is for Compaq's SMART2 Intelligent Disk Array Controllers. - -Supported Cards: ----------------- - -This driver is known to work with the following cards: - - * SMART (EISA) - * SMART-2/E (EISA) - * SMART-2/P - * SMART-2DH - * SMART-2SL - * SMART-221 - * SMART-3100ES - * SMART-3200 - * Integrated Smart Array Controller - * SA 4200 - * SA 4250ES - * SA 431 - * RAID LC2 Controller - -It should also work with some really old Disk array adapters, but I am -unable to test against these cards: - - * IDA - * IDA-2 - * IAES - - -EISA Controllers: ------------------ - -If you want to use an EISA controller you'll have to supply some -modprobe/lilo parameters. If the driver is compiled into the kernel, must -give it the controller's IO port address at boot time (it is not -necessary to specify the IRQ). For example, if you had two SMART-2/E -controllers, in EISA slots 1 and 2 you'd give it a boot argument like -this: - - smart2=0x1000,0x2000 - -If you were loading the driver as a module, you'd give load it like this: - - modprobe cpqarray eisa=0x1000,0x2000 - -You can use EISA and PCI adapters at the same time. - - -Device Naming: --------------- - -You need some entries in /dev for the ida device. MAKEDEV in the /dev -directory can make device nodes for you automatically. The device setup is -as follows: - -Major numbers: - 72 ida0 - 73 ida1 - 74 ida2 - 75 ida3 - 76 ida4 - 77 ida5 - 78 ida6 - 79 ida7 - -Minor numbers: - b7 b6 b5 b4 b3 b2 b1 b0 - |----+----| |----+----| - | | - | +-------- Partition ID (0=wholedev, 1-15 partition) - | - +-------------------- Logical Volume number - -The device naming scheme is: -/dev/ida/c0d0 Controller 0, disk 0, whole device -/dev/ida/c0d0p1 Controller 0, disk 0, partition 1 -/dev/ida/c0d0p2 Controller 0, disk 0, partition 2 -/dev/ida/c0d0p3 Controller 0, disk 0, partition 3 - -/dev/ida/c1d1 Controller 1, disk 1, whole device -/dev/ida/c1d1p1 Controller 1, disk 1, partition 1 -/dev/ida/c1d1p2 Controller 1, disk 1, partition 2 -/dev/ida/c1d1p3 Controller 1, disk 1, partition 3 - - -Changelog: -========== - -10-28-2004 : General cleanup, syntax fixes for in-kernel driver version. - James Nelson <james4765@gmail.com> - - -1999 : Original Document diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.txt index 62435bb25266..5bda5031c83d 100644 --- a/Documentation/blockdev/zram.txt +++ b/Documentation/blockdev/zram.txt @@ -14,8 +14,43 @@ Statistics for individual zram devices are exported through sysfs nodes at * Usage +There are several ways to configure and manage zram device(-s): +a) using zram and zram_control sysfs attributes +b) using zramctl utility, provided by util-linux (util-linux@vger.kernel.org). + +In this document we will describe only 'manual' zram configuration steps, +IOW, zram and zram_control sysfs attributes. + +In order to get a better idea about zramctl please consult util-linux +documentation, zramctl man-page or `zramctl --help'. Please be informed +that zram maintainers do not develop/maintain util-linux or zramctl, should +you have any questions please contact util-linux@vger.kernel.org + Following shows a typical sequence of steps for using zram. +WARNING +======= +For the sake of simplicity we skip error checking parts in most of the +examples below. However, it is your sole responsibility to handle errors. + +zram sysfs attributes always return negative values in case of errors. +The list of possible return codes: +-EBUSY -- an attempt to modify an attribute that cannot be changed once +the device has been initialised. Please reset device first; +-ENOMEM -- zram was not able to allocate enough memory to fulfil your +needs; +-EINVAL -- invalid input has been provided. + +If you use 'echo', the returned value that is changed by 'echo' utility, +and, in general case, something like: + + echo 3 > /sys/block/zram0/max_comp_streams + if [ $? -ne 0 ]; + handle_error + fi + +should suffice. + 1) Load Module: modprobe zram num_devices=4 This creates 4 devices: /dev/zram{0,1,2,3} @@ -47,7 +82,7 @@ max_comp_streams adjustment. 3) Select compression algorithm Using comp_algorithm device attribute one can see available and - currently selected (shown in square brackets) compression algortithms, + currently selected (shown in square brackets) compression algorithms, change selected compression algorithm (once the device is initialised there is no way to change compression algorithm). @@ -119,7 +154,7 @@ execute 8) Stats: Per-device statistics are exported as various nodes under /sys/block/zram<id>/ -A brief description of exported device attritbutes. For more details please +A brief description of exported device attributes. For more details please read Documentation/ABI/testing/sysfs-block-zram. Name access description @@ -140,8 +175,9 @@ zero_pages RO the number of zero filled pages written to this disk orig_data_size RO uncompressed size of data stored in this disk compr_data_size RO compressed size of data stored in this disk mem_used_total RO the amount of memory allocated for this disk -mem_used_max RW the maximum amount memory zram have consumed to - store compressed data +mem_used_max RW the maximum amount of memory zram have consumed to + store the data (to reset this counter to the actual + current value, write 1 to this attribute) mem_limit RW the maximum amount of memory ZRAM can use to store the compressed data pages_compacted RO the number of pages freed during compaction diff --git a/Documentation/cgroups/00-INDEX b/Documentation/cgroup-v1/00-INDEX index 3f5a40f57d4a..106885ad670d 100644 --- a/Documentation/cgroups/00-INDEX +++ b/Documentation/cgroup-v1/00-INDEX @@ -24,7 +24,3 @@ net_prio.txt - Network priority cgroups details and usages. pids.txt - Process number cgroups details and usages. -resource_counter.txt - - Resource Counter API. -unified-hierarchy.txt - - Description the new/next cgroup interface. diff --git a/Documentation/cgroups/blkio-controller.txt b/Documentation/cgroup-v1/blkio-controller.txt index 12686bec37b9..673dc34d3f78 100644 --- a/Documentation/cgroups/blkio-controller.txt +++ b/Documentation/cgroup-v1/blkio-controller.txt @@ -59,7 +59,7 @@ cgroups. Here is what you can do. - At macro level, first dd should finish first. To get more precise data, keep on looking at (with the help of script), at blkio.disk_time and blkio.disk_sectors files of both test1 and test2 groups. This will tell how - much disk time (in milli seconds), each group got and how many secotors each + much disk time (in milliseconds), each group got and how many sectors each group dispatched to the disk. We provide fairness in terms of disk time, so ideally io.disk_time of cgroups should be in proportion to the weight. @@ -84,8 +84,7 @@ Throttling/Upper Limit policy - Run dd to read a file and see if rate is throttled to 1MB/s or not. - # dd if=/mnt/common/zerofile of=/dev/null bs=4K count=1024 - # iflag=direct + # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024 1024+0 records in 1024+0 records out 4194304 bytes (4.2 MB) copied, 4.0001 s, 1.0 MB/s @@ -374,82 +373,3 @@ One can experience an overall throughput drop if you have created multiple groups and put applications in that group which are not driving enough IO to keep disk busy. In that case set group_idle=0, and CFQ will not idle on individual groups and throughput should improve. - -Writeback -========= - -Page cache is dirtied through buffered writes and shared mmaps and -written asynchronously to the backing filesystem by the writeback -mechanism. Writeback sits between the memory and IO domains and -regulates the proportion of dirty memory by balancing dirtying and -write IOs. - -On traditional cgroup hierarchies, relationships between different -controllers cannot be established making it impossible for writeback -to operate accounting for cgroup resource restrictions and all -writeback IOs are attributed to the root cgroup. - -If both the blkio and memory controllers are used on the v2 hierarchy -and the filesystem supports cgroup writeback, writeback operations -correctly follow the resource restrictions imposed by both memory and -blkio controllers. - -Writeback examines both system-wide and per-cgroup dirty memory status -and enforces the more restrictive of the two. Also, writeback control -parameters which are absolute values - vm.dirty_bytes and -vm.dirty_background_bytes - are distributed across cgroups according -to their current writeback bandwidth. - -There's a peculiarity stemming from the discrepancy in ownership -granularity between memory controller and writeback. While memory -controller tracks ownership per page, writeback operates on inode -basis. cgroup writeback bridges the gap by tracking ownership by -inode but migrating ownership if too many foreign pages, pages which -don't match the current inode ownership, have been encountered while -writing back the inode. - -This is a conscious design choice as writeback operations are -inherently tied to inodes making strictly following page ownership -complicated and inefficient. The only use case which suffers from -this compromise is multiple cgroups concurrently dirtying disjoint -regions of the same inode, which is an unlikely use case and decided -to be unsupported. Note that as memory controller assigns page -ownership on the first use and doesn't update it until the page is -released, even if cgroup writeback strictly follows page ownership, -multiple cgroups dirtying overlapping areas wouldn't work as expected. -In general, write-sharing an inode across multiple cgroups is not well -supported. - -Filesystem support for cgroup writeback ---------------------------------------- - -A filesystem can make writeback IOs cgroup-aware by updating -address_space_operations->writepage[s]() to annotate bio's using the -following two functions. - -* wbc_init_bio(@wbc, @bio) - - Should be called for each bio carrying writeback data and associates - the bio with the inode's owner cgroup. Can be called anytime - between bio allocation and submission. - -* wbc_account_io(@wbc, @page, @bytes) - - Should be called for each data segment being written out. While - this function doesn't care exactly when it's called during the - writeback session, it's the easiest and most natural to call it as - data segments are added to a bio. - -With writeback bio's annotated, cgroup support can be enabled per -super_block by setting MS_CGROUPWB in ->s_flags. This allows for -selective disabling of cgroup writeback support which is helpful when -certain filesystem features, e.g. journaled data mode, are -incompatible. - -wbc_init_bio() binds the specified bio to its cgroup. Depending on -the configuration, the bio may be executed at a lower priority and if -the writeback session is holding shared resources, e.g. a journal -entry, may lead to priority inversion. There is no one easy solution -for the problem. Filesystems can try to work around specific problem -cases by skipping wbc_init_bio() or using bio_associate_blkcg() -directly. diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroup-v1/cgroups.txt index f935fac1e73b..947e6fe31ef9 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroup-v1/cgroups.txt @@ -8,7 +8,7 @@ Original copyright statements from cpusets.txt: Portions Copyright (C) 2004 BULL SA. Portions Copyright (c) 2004-2006 Silicon Graphics, Inc. Modified by Paul Jackson <pj@sgi.com> -Modified by Christoph Lameter <clameter@sgi.com> +Modified by Christoph Lameter <cl@linux.com> CONTENTS: ========= @@ -637,6 +637,10 @@ void exit(struct task_struct *task) Called during task exit. +void free(struct task_struct *task) + +Called when the task_struct is freed. + void bind(struct cgroup *root) (cgroup_mutex held by caller) diff --git a/Documentation/cgroups/cpuacct.txt b/Documentation/cgroup-v1/cpuacct.txt index 9d73cc0cadb9..9d73cc0cadb9 100644 --- a/Documentation/cgroups/cpuacct.txt +++ b/Documentation/cgroup-v1/cpuacct.txt diff --git a/Documentation/cgroups/cpusets.txt b/Documentation/cgroup-v1/cpusets.txt index fdf7dff3f607..e5cdcd445615 100644 --- a/Documentation/cgroups/cpusets.txt +++ b/Documentation/cgroup-v1/cpusets.txt @@ -6,7 +6,7 @@ Written by Simon.Derr@bull.net Portions Copyright (c) 2004-2006 Silicon Graphics, Inc. Modified by Paul Jackson <pj@sgi.com> -Modified by Christoph Lameter <clameter@sgi.com> +Modified by Christoph Lameter <cl@linux.com> Modified by Paul Menage <menage@google.com> Modified by Hidetoshi Seto <seto.hidetoshi@jp.fujitsu.com> diff --git a/Documentation/cgroups/devices.txt b/Documentation/cgroup-v1/devices.txt index 3c1095ca02ea..3c1095ca02ea 100644 --- a/Documentation/cgroups/devices.txt +++ b/Documentation/cgroup-v1/devices.txt diff --git a/Documentation/cgroups/freezer-subsystem.txt b/Documentation/cgroup-v1/freezer-subsystem.txt index c96a72cbb30a..e831cb2b8394 100644 --- a/Documentation/cgroups/freezer-subsystem.txt +++ b/Documentation/cgroup-v1/freezer-subsystem.txt @@ -50,7 +50,7 @@ being frozen. This allows the bash example above and gdb to run as expected. The cgroup freezer is hierarchical. Freezing a cgroup freezes all -tasks beloning to the cgroup and all its descendant cgroups. Each +tasks belonging to the cgroup and all its descendant cgroups. Each cgroup has its own state (self-state) and the state inherited from the parent (parent-state). Iff both states are THAWED, the cgroup is THAWED. diff --git a/Documentation/cgroups/hugetlb.txt b/Documentation/cgroup-v1/hugetlb.txt index 106245c3aecc..106245c3aecc 100644 --- a/Documentation/cgroups/hugetlb.txt +++ b/Documentation/cgroup-v1/hugetlb.txt diff --git a/Documentation/cgroups/memcg_test.txt b/Documentation/cgroup-v1/memcg_test.txt index 8870b0212150..8870b0212150 100644 --- a/Documentation/cgroups/memcg_test.txt +++ b/Documentation/cgroup-v1/memcg_test.txt diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroup-v1/memory.txt index ff71e16cc752..ff71e16cc752 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroup-v1/memory.txt diff --git a/Documentation/cgroups/net_cls.txt b/Documentation/cgroup-v1/net_cls.txt index ec182346dea2..ec182346dea2 100644 --- a/Documentation/cgroups/net_cls.txt +++ b/Documentation/cgroup-v1/net_cls.txt diff --git a/Documentation/cgroups/net_prio.txt b/Documentation/cgroup-v1/net_prio.txt index a82cbd28ea8a..a82cbd28ea8a 100644 --- a/Documentation/cgroups/net_prio.txt +++ b/Documentation/cgroup-v1/net_prio.txt diff --git a/Documentation/cgroups/pids.txt b/Documentation/cgroup-v1/pids.txt index 1a078b5d281a..1a078b5d281a 100644 --- a/Documentation/cgroups/pids.txt +++ b/Documentation/cgroup-v1/pids.txt diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt new file mode 100644 index 000000000000..bdc6773277be --- /dev/null +++ b/Documentation/cgroup-v2.txt @@ -0,0 +1,1417 @@ + +Control Group v2 + +October, 2015 Tejun Heo <tj@kernel.org> + +This is the authoritative documentation on the design, interface and +conventions of cgroup v2. It describes all userland-visible aspects +of cgroup including core and specific controller behaviors. All +future changes must be reflected in this document. Documentation for +v1 is available under Documentation/cgroup-v1/. + +CONTENTS + +1. Introduction + 1-1. Terminology + 1-2. What is cgroup? +2. Basic Operations + 2-1. Mounting + 2-2. Organizing Processes + 2-3. [Un]populated Notification + 2-4. Controlling Controllers + 2-4-1. Enabling and Disabling + 2-4-2. Top-down Constraint + 2-4-3. No Internal Process Constraint + 2-5. Delegation + 2-5-1. Model of Delegation + 2-5-2. Delegation Containment + 2-6. Guidelines + 2-6-1. Organize Once and Control + 2-6-2. Avoid Name Collisions +3. Resource Distribution Models + 3-1. Weights + 3-2. Limits + 3-3. Protections + 3-4. Allocations +4. Interface Files + 4-1. Format + 4-2. Conventions + 4-3. Core Interface Files +5. Controllers + 5-1. CPU + 5-1-1. CPU Interface Files + 5-2. Memory + 5-2-1. Memory Interface Files + 5-2-2. Usage Guidelines + 5-2-3. Memory Ownership + 5-3. IO + 5-3-1. IO Interface Files + 5-3-2. Writeback +P. Information on Kernel Programming + P-1. Filesystem Support for Writeback +D. Deprecated v1 Core Features +R. Issues with v1 and Rationales for v2 + R-1. Multiple Hierarchies + R-2. Thread Granularity + R-3. Competition Between Inner Nodes and Threads + R-4. Other Interface Issues + R-5. Controller Issues and Remedies + R-5-1. Memory + + +1. Introduction + +1-1. Terminology + +"cgroup" stands for "control group" and is never capitalized. The +singular form is used to designate the whole feature and also as a +qualifier as in "cgroup controllers". When explicitly referring to +multiple individual control groups, the plural form "cgroups" is used. + + +1-2. What is cgroup? + +cgroup is a mechanism to organize processes hierarchically and +distribute system resources along the hierarchy in a controlled and +configurable manner. + +cgroup is largely composed of two parts - the core and controllers. +cgroup core is primarily responsible for hierarchically organizing +processes. A cgroup controller is usually responsible for +distributing a specific type of system resource along the hierarchy +although there are utility controllers which serve purposes other than +resource distribution. + +cgroups form a tree structure and every process in the system belongs +to one and only one cgroup. All threads of a process belong to the +same cgroup. On creation, all processes are put in the cgroup that +the parent process belongs to at the time. A process can be migrated +to another cgroup. Migration of a process doesn't affect already +existing descendant processes. + +Following certain structural constraints, controllers may be enabled or +disabled selectively on a cgroup. All controller behaviors are +hierarchical - if a controller is enabled on a cgroup, it affects all +processes which belong to the cgroups consisting the inclusive +sub-hierarchy of the cgroup. When a controller is enabled on a nested +cgroup, it always restricts the resource distribution further. The +restrictions set closer to the root in the hierarchy can not be +overridden from further away. + + +2. Basic Operations + +2-1. Mounting + +Unlike v1, cgroup v2 has only single hierarchy. The cgroup v2 +hierarchy can be mounted with the following mount command. + + # mount -t cgroup2 none $MOUNT_POINT + +cgroup2 filesystem has the magic number 0x63677270 ("cgrp"). All +controllers which support v2 and are not bound to a v1 hierarchy are +automatically bound to the v2 hierarchy and show up at the root. +Controllers which are not in active use in the v2 hierarchy can be +bound to other hierarchies. This allows mixing v2 hierarchy with the +legacy v1 multiple hierarchies in a fully backward compatible way. + +A controller can be moved across hierarchies only after the controller +is no longer referenced in its current hierarchy. Because per-cgroup +controller states are destroyed asynchronously and controllers may +have lingering references, a controller may not show up immediately on +the v2 hierarchy after the final umount of the previous hierarchy. +Similarly, a controller should be fully disabled to be moved out of +the unified hierarchy and it may take some time for the disabled +controller to become available for other hierarchies; furthermore, due +to inter-controller dependencies, other controllers may need to be +disabled too. + +While useful for development and manual configurations, moving +controllers dynamically between the v2 and other hierarchies is +strongly discouraged for production use. It is recommended to decide +the hierarchies and controller associations before starting using the +controllers after system boot. + +During transition to v2, system management software might still +automount the v1 cgroup filesystem and so hijack all controllers +during boot, before manual intervention is possible. To make testing +and experimenting easier, the kernel parameter cgroup_no_v1= allows +disabling controllers in v1 and make them always available in v2. + + +2-2. Organizing Processes + +Initially, only the root cgroup exists to which all processes belong. +A child cgroup can be created by creating a sub-directory. + + # mkdir $CGROUP_NAME + +A given cgroup may have multiple child cgroups forming a tree +structure. Each cgroup has a read-writable interface file +"cgroup.procs". When read, it lists the PIDs of all processes which +belong to the cgroup one-per-line. The PIDs are not ordered and the +same PID may show up more than once if the process got moved to +another cgroup and then back or the PID got recycled while reading. + +A process can be migrated into a cgroup by writing its PID to the +target cgroup's "cgroup.procs" file. Only one process can be migrated +on a single write(2) call. If a process is composed of multiple +threads, writing the PID of any thread migrates all threads of the +process. + +When a process forks a child process, the new process is born into the +cgroup that the forking process belongs to at the time of the +operation. After exit, a process stays associated with the cgroup +that it belonged to at the time of exit until it's reaped; however, a +zombie process does not appear in "cgroup.procs" and thus can't be +moved to another cgroup. + +A cgroup which doesn't have any children or live processes can be +destroyed by removing the directory. Note that a cgroup which doesn't +have any children and is associated only with zombie processes is +considered empty and can be removed. + + # rmdir $CGROUP_NAME + +"/proc/$PID/cgroup" lists a process's cgroup membership. If legacy +cgroup is in use in the system, this file may contain multiple lines, +one for each hierarchy. The entry for cgroup v2 is always in the +format "0::$PATH". + + # cat /proc/842/cgroup + ... + 0::/test-cgroup/test-cgroup-nested + +If the process becomes a zombie and the cgroup it was associated with +is removed subsequently, " (deleted)" is appended to the path. + + # cat /proc/842/cgroup + ... + 0::/test-cgroup/test-cgroup-nested (deleted) + + +2-3. [Un]populated Notification + +Each non-root cgroup has a "cgroup.events" file which contains +"populated" field indicating whether the cgroup's sub-hierarchy has +live processes in it. Its value is 0 if there is no live process in +the cgroup and its descendants; otherwise, 1. poll and [id]notify +events are triggered when the value changes. This can be used, for +example, to start a clean-up operation after all processes of a given +sub-hierarchy have exited. The populated state updates and +notifications are recursive. Consider the following sub-hierarchy +where the numbers in the parentheses represent the numbers of processes +in each cgroup. + + A(4) - B(0) - C(1) + \ D(0) + +A, B and C's "populated" fields would be 1 while D's 0. After the one +process in C exits, B and C's "populated" fields would flip to "0" and +file modified events will be generated on the "cgroup.events" files of +both cgroups. + + +2-4. Controlling Controllers + +2-4-1. Enabling and Disabling + +Each cgroup has a "cgroup.controllers" file which lists all +controllers available for the cgroup to enable. + + # cat cgroup.controllers + cpu io memory + +No controller is enabled by default. Controllers can be enabled and +disabled by writing to the "cgroup.subtree_control" file. + + # echo "+cpu +memory -io" > cgroup.subtree_control + +Only controllers which are listed in "cgroup.controllers" can be +enabled. When multiple operations are specified as above, either they +all succeed or fail. If multiple operations on the same controller +are specified, the last one is effective. + +Enabling a controller in a cgroup indicates that the distribution of +the target resource across its immediate children will be controlled. +Consider the following sub-hierarchy. The enabled controllers are +listed in parentheses. + + A(cpu,memory) - B(memory) - C() + \ D() + +As A has "cpu" and "memory" enabled, A will control the distribution +of CPU cycles and memory to its children, in this case, B. As B has +"memory" enabled but not "CPU", C and D will compete freely on CPU +cycles but their division of memory available to B will be controlled. + +As a controller regulates the distribution of the target resource to +the cgroup's children, enabling it creates the controller's interface +files in the child cgroups. In the above example, enabling "cpu" on B +would create the "cpu." prefixed controller interface files in C and +D. Likewise, disabling "memory" from B would remove the "memory." +prefixed controller interface files from C and D. This means that the +controller interface files - anything which doesn't start with +"cgroup." are owned by the parent rather than the cgroup itself. + + +2-4-2. Top-down Constraint + +Resources are distributed top-down and a cgroup can further distribute +a resource only if the resource has been distributed to it from the +parent. This means that all non-root "cgroup.subtree_control" files +can only contain controllers which are enabled in the parent's +"cgroup.subtree_control" file. A controller can be enabled only if +the parent has the controller enabled and a controller can't be +disabled if one or more children have it enabled. + + +2-4-3. No Internal Process Constraint + +Non-root cgroups can only distribute resources to their children when +they don't have any processes of their own. In other words, only +cgroups which don't contain any processes can have controllers enabled +in their "cgroup.subtree_control" files. + +This guarantees that, when a controller is looking at the part of the +hierarchy which has it enabled, processes are always only on the +leaves. This rules out situations where child cgroups compete against +internal processes of the parent. + +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. + +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 +important as otherwise it wouldn't be possible to create children of a +populated cgroup. To control resource distribution of a cgroup, the +cgroup must create children and transfer all its processes to the +children before enabling controllers in its "cgroup.subtree_control" +file. + + +2-5. Delegation + +2-5-1. Model of Delegation + +A cgroup can be delegated to a less privileged user by granting write +access of the directory and its "cgroup.procs" file to the user. Note +that resource control interface files in a given directory control the +distribution of the parent's resources and thus must not be delegated +along with the directory. + +Once delegated, the user can build sub-hierarchy under the directory, +organize processes as it sees fit and further distribute the resources +it received from the parent. The limits and other settings of all +resource controllers are hierarchical and regardless of what happens +in the delegated sub-hierarchy, nothing can escape the resource +restrictions imposed by the parent. + +Currently, cgroup doesn't impose any restrictions on the number of +cgroups in or nesting depth of a delegated sub-hierarchy; however, +this may be limited explicitly in the future. + + +2-5-2. Delegation Containment + +A delegated sub-hierarchy is contained in the sense that processes +can't be moved into or out of the sub-hierarchy by the delegatee. For +a process with a non-root euid to migrate a target process into a +cgroup by writing its PID to the "cgroup.procs" file, the following +conditions must be met. + +- The writer's euid must match either uid or suid of the target process. + +- The writer must have write access to the "cgroup.procs" file. + +- The writer must have write access to the "cgroup.procs" file of the + common ancestor of the source and destination cgroups. + +The above three constraints ensure that while a delegatee may migrate +processes around freely in the delegated sub-hierarchy it can't pull +in from or push out to outside the sub-hierarchy. + +For an example, let's assume cgroups C0 and C1 have been delegated to +user U0 who created C00, C01 under C0 and C10 under C1 as follows and +all processes under C0 and C1 belong to U0. + + ~~~~~~~~~~~~~ - C0 - C00 + ~ cgroup ~ \ C01 + ~ hierarchy ~ + ~~~~~~~~~~~~~ - C1 - C10 + +Let's also say U0 wants to write the PID of a process which is +currently in C10 into "C00/cgroup.procs". U0 has write access to the +file and uid match on the process; however, the common ancestor of the +source cgroup C10 and the destination cgroup C00 is above the points +of delegation and U0 would not have write access to its "cgroup.procs" +files and thus the write will be denied with -EACCES. + + +2-6. Guidelines + +2-6-1. Organize Once and Control + +Migrating a process across cgroups is a relatively expensive operation +and stateful resources such as memory are not moved together with the +process. This is an explicit design decision as there often exist +inherent trade-offs between migration and various hot paths in terms +of synchronization cost. + +As such, migrating processes across cgroups frequently as a means to +apply different resource restrictions is discouraged. A workload +should be assigned to a cgroup according to the system's logical and +resource structure once on start-up. Dynamic adjustments to resource +distribution can be made by changing controller configuration through +the interface files. + + +2-6-2. Avoid Name Collisions + +Interface files for a cgroup and its children cgroups occupy the same +directory and it is possible to create children cgroups which collide +with interface files. + +All cgroup core interface files are prefixed with "cgroup." and each +controller's interface files are prefixed with the controller name and +a dot. A controller's name is composed of lower case alphabets and +'_'s but never begins with an '_' so it can be used as the prefix +character for collision avoidance. Also, interface file names won't +start or end with terms which are often used in categorizing workloads +such as job, service, slice, unit or workload. + +cgroup doesn't do anything to prevent name collisions and it's the +user's responsibility to avoid them. + + +3. Resource Distribution Models + +cgroup controllers implement several resource distribution schemes +depending on the resource type and expected use cases. This section +describes major schemes in use along with their expected behaviors. + + +3-1. Weights + +A parent's resource is distributed by adding up the weights of all +active children and giving each the fraction matching the ratio of its +weight against the sum. As only children which can make use of the +resource at the moment participate in the distribution, this is +work-conserving. Due to the dynamic nature, this model is usually +used for stateless resources. + +All weights are in the range [1, 10000] with the default at 100. This +allows symmetric multiplicative biases in both directions at fine +enough granularity while staying in the intuitive range. + +As long as the weight is in range, all configuration combinations are +valid and there is no reason to reject configuration changes or +process migrations. + +"cpu.weight" proportionally distributes CPU cycles to active children +and is an example of this type. + + +3-2. Limits + +A child can only consume upto the configured amount of the resource. +Limits can be over-committed - the sum of the limits of children can +exceed the amount of resource available to the parent. + +Limits are in the range [0, max] and defaults to "max", which is noop. + +As limits can be over-committed, all configuration combinations are +valid and there is no reason to reject configuration changes or +process migrations. + +"io.max" limits the maximum BPS and/or IOPS that a cgroup can consume +on an IO device and is an example of this type. + + +3-3. Protections + +A cgroup is protected to be allocated upto the configured amount of +the resource if the usages of all its ancestors are under their +protected levels. Protections can be hard guarantees or best effort +soft boundaries. Protections can also be over-committed in which case +only upto the amount available to the parent is protected among +children. + +Protections are in the range [0, max] and defaults to 0, which is +noop. + +As protections can be over-committed, all configuration combinations +are valid and there is no reason to reject configuration changes or +process migrations. + +"memory.low" implements best-effort memory protection and is an +example of this type. + + +3-4. Allocations + +A cgroup is exclusively allocated a certain amount of a finite +resource. Allocations can't be over-committed - the sum of the +allocations of children can not exceed the amount of resource +available to the parent. + +Allocations are in the range [0, max] and defaults to 0, which is no +resource. + +As allocations can't be over-committed, some configuration +combinations are invalid and should be rejected. Also, if the +resource is mandatory for execution of processes, process migrations +may be rejected. + +"cpu.rt.max" hard-allocates realtime slices and is an example of this +type. + + +4. Interface Files + +4-1. Format + +All interface files should be in one of the following formats whenever +possible. + + New-line separated values + (when only one value can be written at once) + + VAL0\n + VAL1\n + ... + + Space separated values + (when read-only or multiple values can be written at once) + + VAL0 VAL1 ...\n + + Flat keyed + + KEY0 VAL0\n + KEY1 VAL1\n + ... + + Nested keyed + + KEY0 SUB_KEY0=VAL00 SUB_KEY1=VAL01... + KEY1 SUB_KEY0=VAL10 SUB_KEY1=VAL11... + ... + +For a writable file, the format for writing should generally match +reading; however, controllers may allow omitting later fields or +implement restricted shortcuts for most common use cases. + +For both flat and nested keyed files, only the values for a single key +can be written at a time. For nested keyed files, the sub key pairs +may be specified in any order and not all pairs have to be specified. + + +4-2. Conventions + +- Settings for a single feature should be contained in a single file. + +- The root cgroup should be exempt from resource control and thus + shouldn't have resource control interface files. Also, + informational files on the root cgroup which end up showing global + information available elsewhere shouldn't exist. + +- If a controller implements weight based resource distribution, its + interface file should be named "weight" and have the range [1, + 10000] with 100 as the default. The values are chosen to allow + enough and symmetric bias in both directions while keeping it + intuitive (the default is 100%). + +- If a controller implements an absolute resource guarantee and/or + limit, the interface files should be named "min" and "max" + respectively. If a controller implements best effort resource + guarantee and/or limit, the interface files should be named "low" + and "high" respectively. + + In the above four control files, the special token "max" should be + used to represent upward infinity for both reading and writing. + +- If a setting has a configurable default value and keyed specific + overrides, the default entry should be keyed with "default" and + appear as the first entry in the file. + + The default value can be updated by writing either "default $VAL" or + "$VAL". + + When writing to update a specific override, "default" can be used as + the value to indicate removal of the override. Override entries + with "default" as the value must not appear when read. + + For example, a setting which is keyed by major:minor device numbers + with integer values may look like the following. + + # cat cgroup-example-interface-file + default 150 + 8:0 300 + + The default value can be updated by + + # echo 125 > cgroup-example-interface-file + + or + + # echo "default 125" > cgroup-example-interface-file + + An override can be set by + + # echo "8:16 170" > cgroup-example-interface-file + + and cleared by + + # echo "8:0 default" > cgroup-example-interface-file + # cat cgroup-example-interface-file + default 125 + 8:16 170 + +- For events which are not very high frequency, an interface file + "events" should be created which lists event key value pairs. + Whenever a notifiable event happens, file modified event should be + generated on the file. + + +4-3. Core Interface Files + +All cgroup core files are prefixed with "cgroup." + + cgroup.procs + + A read-write new-line separated values file which exists on + all cgroups. + + When read, it lists the PIDs of all processes which belong to + the cgroup one-per-line. The PIDs are not ordered and the + same PID may show up more than once if the process got moved + to another cgroup and then back or the PID got recycled while + reading. + + A PID can be written to migrate the process associated with + the PID to the cgroup. The writer should match all of the + following conditions. + + - Its euid is either root or must match either uid or suid of + the target process. + + - It must have write access to the "cgroup.procs" file. + + - It must have write access to the "cgroup.procs" file of the + common ancestor of the source and destination cgroups. + + When delegating a sub-hierarchy, write access to this file + should be granted along with the containing directory. + + cgroup.controllers + + A read-only space separated values file which exists on all + cgroups. + + It shows space separated list of all controllers available to + the cgroup. The controllers are not ordered. + + cgroup.subtree_control + + A read-write space separated values file which exists on all + cgroups. Starts out empty. + + When read, it shows space separated list of the controllers + which are enabled to control resource distribution from the + cgroup to its children. + + Space separated list of controllers prefixed with '+' or '-' + can be written to enable or disable controllers. A controller + name prefixed with '+' enables the controller and '-' + disables. If a controller appears more than once on the list, + the last one is effective. When multiple enable and disable + operations are specified, either all succeed or all fail. + + cgroup.events + + A read-only flat-keyed file which exists on non-root cgroups. + The following entries are defined. Unless specified + otherwise, a value change in this file generates a file + modified event. + + populated + + 1 if the cgroup or its descendants contains any live + processes; otherwise, 0. + + +5. Controllers + +5-1. CPU + +[NOTE: The interface for the cpu controller hasn't been merged yet] + +The "cpu" controllers regulates distribution of CPU cycles. This +controller implements weight and absolute bandwidth limit models for +normal scheduling policy and absolute bandwidth allocation model for +realtime scheduling policy. + + +5-1-1. CPU Interface Files + +All time durations are in microseconds. + + cpu.stat + + A read-only flat-keyed file which exists on non-root cgroups. + + It reports the following six stats. + + usage_usec + user_usec + system_usec + nr_periods + nr_throttled + throttled_usec + + cpu.weight + + A read-write single value file which exists on non-root + cgroups. The default is "100". + + The weight in the range [1, 10000]. + + cpu.max + + A read-write two value file which exists on non-root cgroups. + The default is "max 100000". + + The maximum bandwidth limit. It's in the following format. + + $MAX $PERIOD + + which indicates that the group may consume upto $MAX in each + $PERIOD duration. "max" for $MAX indicates no limit. If only + one number is written, $MAX is updated. + + cpu.rt.max + + [NOTE: The semantics of this file is still under discussion and the + interface hasn't been merged yet] + + A read-write two value file which exists on all cgroups. + The default is "0 100000". + + The maximum realtime runtime allocation. Over-committing + configurations are disallowed and process migrations are + rejected if not enough bandwidth is available. It's in the + following format. + + $MAX $PERIOD + + which indicates that the group may consume upto $MAX in each + $PERIOD duration. If only one number is written, $MAX is + updated. + + +5-2. Memory + +The "memory" controller regulates distribution of memory. Memory is +stateful and implements both limit and protection models. Due to the +intertwining between memory usage and reclaim pressure and the +stateful nature of memory, the distribution model is relatively +complex. + +While not completely water-tight, all major memory usages by a given +cgroup are tracked so that the total memory consumption can be +accounted and controlled to a reasonable extent. Currently, the +following types of memory usages are tracked. + +- Userland memory - page cache and anonymous memory. + +- Kernel data structures such as dentries and inodes. + +- TCP socket buffers. + +The above list may expand in the future for better coverage. + + +5-2-1. Memory Interface Files + +All memory amounts are in bytes. If a value which is not aligned to +PAGE_SIZE is written, the value may be rounded up to the closest +PAGE_SIZE multiple when read back. + + memory.current + + A read-only single value file which exists on non-root + cgroups. + + The total amount of memory currently being used by the cgroup + and its descendants. + + memory.low + + A read-write single value file which exists on non-root + cgroups. The default is "0". + + Best-effort memory protection. If the memory usages of a + cgroup and all its ancestors are below their low boundaries, + the cgroup's memory won't be reclaimed unless memory can be + reclaimed from unprotected cgroups. + + Putting more memory than generally available under this + protection is discouraged. + + memory.high + + A read-write single value file which exists on non-root + cgroups. The default is "max". + + Memory usage throttle limit. This is the main mechanism to + control memory usage of a cgroup. If a cgroup's usage goes + over the high boundary, the processes of the cgroup are + throttled and put under heavy reclaim pressure. + + Going over the high limit never invokes the OOM killer and + under extreme conditions the limit may be breached. + + memory.max + + A read-write single value file which exists on non-root + cgroups. The default is "max". + + Memory usage hard limit. This is the final protection + mechanism. If a cgroup's memory usage reaches this limit and + can't be reduced, the OOM killer is invoked in the cgroup. + Under certain circumstances, the usage may go over the limit + temporarily. + + This is the ultimate protection mechanism. As long as the + high limit is used and monitored properly, this limit's + utility is limited to providing the final safety net. + + memory.events + + A read-only flat-keyed file which exists on non-root cgroups. + The following entries are defined. Unless specified + otherwise, a value change in this file generates a file + modified event. + + low + + The number of times the cgroup is reclaimed due to + high memory pressure even though its usage is under + the low boundary. This usually indicates that the low + boundary is over-committed. + + high + + The number of times processes of the cgroup are + throttled and routed to perform direct memory reclaim + because the high memory boundary was exceeded. For a + cgroup whose memory usage is capped by the high limit + rather than global memory pressure, this event's + occurrences are expected. + + max + + The number of times the cgroup's memory usage was + about to go over the max boundary. If direct reclaim + fails to bring it down, the OOM killer is invoked. + + oom + + The number of times the OOM killer has been invoked in + the cgroup. This may not exactly match the number of + processes killed but should generally be close. + + memory.stat + + A read-only flat-keyed file which exists on non-root cgroups. + + This breaks down the cgroup's memory footprint into different + types of memory, type-specific details, and other information + on the state and past events of the memory management system. + + All memory amounts are in bytes. + + The entries are ordered to be human readable, and new entries + can show up in the middle. Don't rely on items remaining in a + fixed position; use the keys to look up specific values! + + anon + + Amount of memory used in anonymous mappings such as + brk(), sbrk(), and mmap(MAP_ANONYMOUS) + + file + + Amount of memory used to cache filesystem data, + including tmpfs and shared memory. + + kernel_stack + + Amount of memory allocated to kernel stacks. + + slab + + Amount of memory used for storing in-kernel data + structures. + + sock + + Amount of memory used in network transmission buffers + + file_mapped + + Amount of cached filesystem data mapped with mmap() + + file_dirty + + Amount of cached filesystem data that was modified but + not yet written back to disk + + file_writeback + + Amount of cached filesystem data that was modified and + is currently being written back to disk + + inactive_anon + active_anon + inactive_file + active_file + unevictable + + Amount of memory, swap-backed and filesystem-backed, + on the internal memory management lists used by the + page reclaim algorithm + + slab_reclaimable + + Part of "slab" that might be reclaimed, such as + dentries and inodes. + + slab_unreclaimable + + Part of "slab" that cannot be reclaimed on memory + pressure. + + pgfault + + Total number of page faults incurred + + pgmajfault + + Number of major page faults incurred + + memory.swap.current + + A read-only single value file which exists on non-root + cgroups. + + The total amount of swap currently being used by the cgroup + and its descendants. + + memory.swap.max + + A read-write single value file which exists on non-root + 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. + + +5-2-2. Usage Guidelines + +"memory.high" is the main mechanism to control memory usage. +Over-committing on high limit (sum of high limits > available memory) +and letting global memory pressure to distribute memory according to +usage is a viable strategy. + +Because breach of the high limit doesn't trigger the OOM killer but +throttles the offending cgroup, a management agent has ample +opportunities to monitor and take appropriate actions such as granting +more memory or terminating the workload. + +Determining whether a cgroup has enough memory is not trivial as +memory usage doesn't indicate whether the workload can benefit from +more memory. For example, a workload which writes data received from +network to a file can use all available memory but can also operate as +performant with a small amount of memory. A measure of memory +pressure - how much the workload is being impacted due to lack of +memory - is necessary to determine whether a workload needs more +memory; unfortunately, memory pressure monitoring mechanism isn't +implemented yet. + + +5-2-3. Memory Ownership + +A memory area is charged to the cgroup which instantiated it and stays +charged to the cgroup until the area is released. Migrating a process +to a different cgroup doesn't move the memory usages that it +instantiated while in the previous cgroup to the new cgroup. + +A memory area may be used by processes belonging to different cgroups. +To which cgroup the area will be charged is in-deterministic; however, +over time, the memory area is likely to end up in a cgroup which has +enough memory allowance to avoid high reclaim pressure. + +If a cgroup sweeps a considerable amount of memory which is expected +to be accessed repeatedly by other cgroups, it may make sense to use +POSIX_FADV_DONTNEED to relinquish the ownership of memory areas +belonging to the affected files to ensure correct memory ownership. + + +5-3. IO + +The "io" controller regulates the distribution of IO resources. This +controller implements both weight based and absolute bandwidth or IOPS +limit distribution; however, weight based distribution is available +only if cfq-iosched is in use and neither scheme is available for +blk-mq devices. + + +5-3-1. IO Interface Files + + io.stat + + A read-only nested-keyed file which exists on non-root + cgroups. + + Lines are keyed by $MAJ:$MIN device numbers and not ordered. + The following nested keys are defined. + + rbytes Bytes read + wbytes Bytes written + rios Number of read IOs + wios Number of write IOs + + An example read output follows. + + 8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353 + 8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252 + + io.weight + + A read-write flat-keyed file which exists on non-root cgroups. + The default is "default 100". + + The first line is the default weight applied to devices + without specific override. The rest are overrides keyed by + $MAJ:$MIN device numbers and not ordered. The weights are in + the range [1, 10000] and specifies the relative amount IO time + the cgroup can use in relation to its siblings. + + The default weight can be updated by writing either "default + $WEIGHT" or simply "$WEIGHT". Overrides can be set by writing + "$MAJ:$MIN $WEIGHT" and unset by writing "$MAJ:$MIN default". + + An example read output follows. + + default 100 + 8:16 200 + 8:0 50 + + io.max + + A read-write nested-keyed file which exists on non-root + cgroups. + + BPS and IOPS based IO limit. Lines are keyed by $MAJ:$MIN + device numbers and not ordered. The following nested keys are + defined. + + rbps Max read bytes per second + wbps Max write bytes per second + riops Max read IO operations per second + wiops Max write IO operations per second + + When writing, any number of nested key-value pairs can be + specified in any order. "max" can be specified as the value + to remove a specific limit. If the same key is specified + multiple times, the outcome is undefined. + + BPS and IOPS are measured in each IO direction and IOs are + delayed if limit is reached. Temporary bursts are allowed. + + Setting read limit at 2M BPS and write at 120 IOPS for 8:16. + + echo "8:16 rbps=2097152 wiops=120" > io.max + + Reading returns the following. + + 8:16 rbps=2097152 wbps=max riops=max wiops=120 + + Write IOPS limit can be removed by writing the following. + + echo "8:16 wiops=max" > io.max + + Reading now returns the following. + + 8:16 rbps=2097152 wbps=max riops=max wiops=max + + +5-3-2. Writeback + +Page cache is dirtied through buffered writes and shared mmaps and +written asynchronously to the backing filesystem by the writeback +mechanism. Writeback sits between the memory and IO domains and +regulates the proportion of dirty memory by balancing dirtying and +write IOs. + +The io controller, in conjunction with the memory controller, +implements control of page cache writeback IOs. The memory controller +defines the memory domain that dirty memory ratio is calculated and +maintained for and the io controller defines the io domain which +writes out dirty pages for the memory domain. Both system-wide and +per-cgroup dirty memory states are examined and the more restrictive +of the two is enforced. + +cgroup writeback requires explicit support from the underlying +filesystem. Currently, cgroup writeback is implemented on ext2, ext4 +and btrfs. On other filesystems, all writeback IOs are attributed to +the root cgroup. + +There are inherent differences in memory and writeback management +which affects how cgroup ownership is tracked. Memory is tracked per +page while writeback per inode. For the purpose of writeback, an +inode is assigned to a cgroup and all IO requests to write dirty pages +from the inode are attributed to that cgroup. + +As cgroup ownership for memory is tracked per page, there can be pages +which are associated with different cgroups than the one the inode is +associated with. These are called foreign pages. The writeback +constantly keeps track of foreign pages and, if a particular foreign +cgroup becomes the majority over a certain period of time, switches +the ownership of the inode to that cgroup. + +While this model is enough for most use cases where a given inode is +mostly dirtied by a single cgroup even when the main writing cgroup +changes over time, use cases where multiple cgroups write to a single +inode simultaneously are not supported well. In such circumstances, a +significant portion of IOs are likely to be attributed incorrectly. +As memory controller assigns page ownership on the first use and +doesn't update it until the page is released, even if writeback +strictly follows page ownership, multiple cgroups dirtying overlapping +areas wouldn't work as expected. It's recommended to avoid such usage +patterns. + +The sysctl knobs which affect writeback behavior are applied to cgroup +writeback as follows. + + vm.dirty_background_ratio + vm.dirty_ratio + + These ratios apply the same to cgroup writeback with the + amount of available memory capped by limits imposed by the + memory controller and system-wide clean memory. + + vm.dirty_background_bytes + vm.dirty_bytes + + For cgroup writeback, this is calculated into ratio against + total available memory and applied the same way as + vm.dirty[_background]_ratio. + + +P. Information on Kernel Programming + +This section contains kernel programming information in the areas +where interacting with cgroup is necessary. cgroup core and +controllers are not covered. + + +P-1. Filesystem Support for Writeback + +A filesystem can support cgroup writeback by updating +address_space_operations->writepage[s]() to annotate bio's using the +following two functions. + + wbc_init_bio(@wbc, @bio) + + Should be called for each bio carrying writeback data and + associates the bio with the inode's owner cgroup. Can be + called anytime between bio allocation and submission. + + wbc_account_io(@wbc, @page, @bytes) + + Should be called for each data segment being written out. + While this function doesn't care exactly when it's called + during the writeback session, it's the easiest and most + natural to call it as data segments are added to a bio. + +With writeback bio's annotated, cgroup support can be enabled per +super_block by setting SB_I_CGROUPWB in ->s_iflags. This allows for +selective disabling of cgroup writeback support which is helpful when +certain filesystem features, e.g. journaled data mode, are +incompatible. + +wbc_init_bio() binds the specified bio to its cgroup. Depending on +the configuration, the bio may be executed at a lower priority and if +the writeback session is holding shared resources, e.g. a journal +entry, may lead to priority inversion. There is no one easy solution +for the problem. Filesystems can try to work around specific problem +cases by skipping wbc_init_bio() or using bio_associate_blkcg() +directly. + + +D. Deprecated v1 Core Features + +- Multiple hierarchies including named ones are not supported. + +- All mount options and remounting are not supported. + +- The "tasks" file is removed and "cgroup.procs" is not sorted. + +- "cgroup.clone_children" is removed. + +- /proc/cgroups is meaningless for v2. Use "cgroup.controllers" file + at the root instead. + + +R. Issues with v1 and Rationales for v2 + +R-1. Multiple Hierarchies + +cgroup v1 allowed an arbitrary number of hierarchies and each +hierarchy could host any number of controllers. While this seemed to +provide a high level of flexibility, it wasn't useful in practice. + +For example, as there is only one instance of each controller, utility +type controllers such as freezer which can be useful in all +hierarchies could only be used in one. The issue is exacerbated by +the fact that controllers couldn't be moved to another hierarchy once +hierarchies were populated. Another issue was that all controllers +bound to a hierarchy were forced to have exactly the same view of the +hierarchy. It wasn't possible to vary the granularity depending on +the specific controller. + +In practice, these issues heavily limited which controllers could be +put on the same hierarchy and most configurations resorted to putting +each controller on its own hierarchy. Only closely related ones, such +as the cpu and cpuacct controllers, made sense to be put on the same +hierarchy. This often meant that userland ended up managing multiple +similar hierarchies repeating the same steps on each hierarchy +whenever a hierarchy management operation was necessary. + +Furthermore, support for multiple hierarchies came at a steep cost. +It greatly complicated cgroup core implementation but more importantly +the support for multiple hierarchies restricted how cgroup could be +used in general and what controllers was able to do. + +There was no limit on how many hierarchies there might be, which meant +that a thread's cgroup membership couldn't be described in finite +length. The key might contain any number of entries and was unlimited +in length, which made it highly awkward to manipulate and led to +addition of controllers which existed only to identify membership, +which in turn exacerbated the original problem of proliferating number +of hierarchies. + +Also, as a controller couldn't have any expectation regarding the +topologies of hierarchies other controllers might be on, each +controller had to assume that all other controllers were attached to +completely orthogonal hierarchies. This made it impossible, or at +least very cumbersome, for controllers to cooperate with each other. + +In most use cases, putting controllers on hierarchies which are +completely orthogonal to each other isn't necessary. What usually is +called for is the ability to have differing levels of granularity +depending on the specific controller. In other words, hierarchy may +be collapsed from leaf towards root when viewed from specific +controllers. For example, a given configuration might not care about +how memory is distributed beyond a certain level while still wanting +to control how CPU cycles are distributed. + + +R-2. Thread Granularity + +cgroup v1 allowed threads of a process to belong to different cgroups. +This didn't make sense for some controllers and those controllers +ended up implementing different ways to ignore such situations but +much more importantly it blurred the line between API exposed to +individual applications and system management interface. + +Generally, in-process knowledge is available only to the process +itself; thus, unlike service-level organization of processes, +categorizing threads of a process requires active participation from +the application which owns the target process. + +cgroup v1 had an ambiguously defined delegation model which got abused +in combination with thread granularity. cgroups were delegated to +individual applications so that they can create and manage their own +sub-hierarchies and control resource distributions along them. This +effectively raised cgroup to the status of a syscall-like API exposed +to lay programs. + +First of all, cgroup has a fundamentally inadequate interface to be +exposed this way. For a process to access its own knobs, it has to +extract the path on the target hierarchy from /proc/self/cgroup, +construct the path by appending the name of the knob to the path, open +and then read and/or write to it. This is not only extremely clunky +and unusual but also inherently racy. There is no conventional way to +define transaction across the required steps and nothing can guarantee +that the process would actually be operating on its own sub-hierarchy. + +cgroup controllers implemented a number of knobs which would never be +accepted as public APIs because they were just adding control knobs to +system-management pseudo filesystem. cgroup ended up with interface +knobs which were not properly abstracted or refined and directly +revealed kernel internal details. These knobs got exposed to +individual applications through the ill-defined delegation mechanism +effectively abusing cgroup as a shortcut to implementing public APIs +without going through the required scrutiny. + +This was painful for both userland and kernel. Userland ended up with +misbehaving and poorly abstracted interfaces and kernel exposing and +locked into constructs inadvertently. + + +R-3. Competition Between Inner Nodes and Threads + +cgroup v1 allowed threads to be in any cgroups which created an +interesting problem where threads belonging to a parent cgroup and its +children cgroups competed for resources. This was nasty as two +different types of entities competed and there was no obvious way to +settle it. Different controllers did different things. + +The cpu controller considered threads and cgroups as equivalents and +mapped nice levels to cgroup weights. This worked for some cases but +fell flat when children wanted to be allocated specific ratios of CPU +cycles and the number of internal threads fluctuated - the ratios +constantly changed as the number of competing entities fluctuated. +There also were other issues. The mapping from nice level to weight +wasn't obvious or universal, and there were various other knobs which +simply weren't available for threads. + +The io controller implicitly created a hidden leaf node for each +cgroup to host the threads. The hidden leaf had its own copies of all +the knobs with "leaf_" prefixed. While this allowed equivalent +control over internal threads, it was with serious drawbacks. It +always added an extra layer of nesting which wouldn't be necessary +otherwise, made the interface messy and significantly complicated the +implementation. + +The memory controller didn't have a way to control what happened +between internal tasks and child cgroups and the behavior was not +clearly defined. There were attempts to add ad-hoc behaviors and +knobs to tailor the behavior to specific workloads which would have +led to problems extremely difficult to resolve in the long term. + +Multiple controllers struggled with internal tasks and came up with +different ways to deal with it; unfortunately, all the approaches were +severely flawed and, furthermore, the widely different behaviors +made cgroup as a whole highly inconsistent. + +This clearly is a problem which needs to be addressed from cgroup core +in a uniform way. + + +R-4. Other Interface Issues + +cgroup v1 grew without oversight and developed a large number of +idiosyncrasies and inconsistencies. One issue on the cgroup core side +was how an empty cgroup was notified - a userland helper binary was +forked and executed for each event. The event delivery wasn't +recursive or delegatable. The limitations of the mechanism also led +to in-kernel event delivery filtering mechanism further complicating +the interface. + +Controller interfaces were problematic too. An extreme example is +controllers completely ignoring hierarchical organization and treating +all cgroups as if they were all located directly under the root +cgroup. Some controllers exposed a large amount of inconsistent +implementation details to userland. + +There also was no consistency across controllers. When a new cgroup +was created, some controllers defaulted to not imposing extra +restrictions while others disallowed any resource usage until +explicitly configured. Configuration knobs for the same type of +control used widely differing naming schemes and formats. Statistics +and information knobs were named arbitrarily and used different +formats and units even in the same controller. + +cgroup v2 establishes common conventions where appropriate and updates +controllers so that they expose minimal and consistent interfaces. + + +R-5. Controller Issues and Remedies + +R-5-1. Memory + +The original lower boundary, the soft limit, is defined as a limit +that is per default unset. As a result, the set of cgroups that +global reclaim prefers is opt-in, rather than opt-out. The costs for +optimizing these mostly negative lookups are so high that the +implementation, despite its enormous size, does not even provide the +basic desirable behavior. First off, the soft limit has no +hierarchical meaning. All configured groups are organized in a global +rbtree and treated like equal peers, regardless where they are located +in the hierarchy. This makes subtree delegation impossible. Second, +the soft limit reclaim pass is so aggressive that it not just +introduces high allocation latencies into the system, but also impacts +system performance due to overreclaim, to the point where the feature +becomes self-defeating. + +The memory.low boundary on the other hand is a top-down allocated +reserve. A cgroup enjoys reclaim protection when it and all its +ancestors are below their low boundaries, which makes delegation of +subtrees possible. Secondly, new cgroups have no reserve per default +and in the common case most cgroups are eligible for the preferred +reclaim pass. This allows the new low boundary to be efficiently +implemented with just a minor addition to the generic reclaim code, +without the need for out-of-band data structures and reclaim passes. +Because the generic reclaim code considers all cgroups except for the +ones running low in the preferred first reclaim pass, overreclaim of +individual groups is eliminated as well, resulting in much better +overall workload performance. + +The original high boundary, the hard limit, is defined as a strict +limit that can not budge, even if the OOM killer has to be called. +But this generally goes against the goal of making the most out of the +available memory. The memory consumption of workloads varies during +runtime, and that requires users to overcommit. But doing that with a +strict upper limit requires either a fairly accurate prediction of the +working set size or adding slack to the limit. Since working set size +estimation is hard and error prone, and getting it wrong results in +OOM kills, most users tend to err on the side of a looser limit and +end up wasting precious resources. + +The memory.high boundary on the other hand can be set much more +conservatively. When hit, it throttles allocations by forcing them +into direct reclaim to work off the excess, but it never invokes the +OOM killer. As a result, a high boundary that is chosen too +aggressively will not terminate the processes, but instead it will +lead to gradual performance degradation. The user can monitor this +and make corrections until the minimal memory footprint that still +gives acceptable performance is found. + +In extreme cases, with many concurrent allocations and a complete +breakdown of reclaim progress within the group, the high boundary can +be exceeded. But even then it's mostly better to satisfy the +allocation from the slack available in other groups or the rest of the +system than killing the group. Otherwise, memory.max is there to +limit this type of spillover and ultimately contain buggy or even +malicious applications. + +Setting the original memory.limit_in_bytes below the current usage was +subject to a race condition, where concurrent charges could cause the +limit setting to fail. memory.max on the other hand will first set the +limit to prevent new charges, and then reclaim and OOM kill until the +new limit is met - or the task writing to memory.max is killed. + +The combined memory+swap accounting and limiting is replaced by real +control over swap space. + +The main argument for a combined memory+swap facility in the original +cgroup design was that global or parental pressure would always be +able to swap all anonymous memory of a child group, regardless of the +child's own (possibly untrusted) configuration. However, untrusted +groups can sabotage swapping by other means - such as referencing its +anonymous memory in a tight loop - and an admin can not assume full +swappability when overcommitting untrusted jobs. + +For trusted jobs, on the other hand, a combined counter is not an +intuitive userspace interface, and it flies in the face of the idea +that cgroup controllers should account and limit specific physical +resources. Swap space is a resource like all others in the system, +and that's why unified hierarchy allows distributing it separately. diff --git a/Documentation/cgroups/unified-hierarchy.txt b/Documentation/cgroups/unified-hierarchy.txt deleted file mode 100644 index e0975c2cf03d..000000000000 --- a/Documentation/cgroups/unified-hierarchy.txt +++ /dev/null @@ -1,644 +0,0 @@ - -Cgroup unified hierarchy - -April, 2014 Tejun Heo <tj@kernel.org> - -This document describes the changes made by unified hierarchy and -their rationales. It will eventually be merged into the main cgroup -documentation. - -CONTENTS - -1. Background -2. Basic Operation - 2-1. Mounting - 2-2. cgroup.subtree_control - 2-3. cgroup.controllers -3. Structural Constraints - 3-1. Top-down - 3-2. No internal tasks -4. Delegation - 4-1. Model of delegation - 4-2. Common ancestor rule -5. Other Changes - 5-1. [Un]populated Notification - 5-2. Other Core Changes - 5-3. Controller File Conventions - 5-3-1. Format - 5-3-2. Control Knobs - 5-4. Per-Controller Changes - 5-4-1. io - 5-4-2. cpuset - 5-4-3. memory -6. Planned Changes - 6-1. CAP for resource control - - -1. Background - -cgroup allows an arbitrary number of hierarchies and each hierarchy -can host any number of controllers. While this seems to provide a -high level of flexibility, it isn't quite useful in practice. - -For example, as there is only one instance of each controller, utility -type controllers such as freezer which can be useful in all -hierarchies can only be used in one. The issue is exacerbated by the -fact that controllers can't be moved around once hierarchies are -populated. Another issue is that all controllers bound to a hierarchy -are forced to have exactly the same view of the hierarchy. It isn't -possible to vary the granularity depending on the specific controller. - -In practice, these issues heavily limit which controllers can be put -on the same hierarchy and most configurations resort to putting each -controller on its own hierarchy. Only closely related ones, such as -the cpu and cpuacct controllers, make sense to put on the same -hierarchy. This often means that userland ends up managing multiple -similar hierarchies repeating the same steps on each hierarchy -whenever a hierarchy management operation is necessary. - -Unfortunately, support for multiple hierarchies comes at a steep cost. -Internal implementation in cgroup core proper is dazzlingly -complicated but more importantly the support for multiple hierarchies -restricts how cgroup is used in general and what controllers can do. - -There's no limit on how many hierarchies there may be, which means -that a task's cgroup membership can't be described in finite length. -The key may contain any varying number of entries and is unlimited in -length, which makes it highly awkward to handle and leads to addition -of controllers which exist only to identify membership, which in turn -exacerbates the original problem. - -Also, as a controller can't have any expectation regarding what shape -of hierarchies other controllers would be on, each controller has to -assume that all other controllers are operating on completely -orthogonal hierarchies. This makes it impossible, or at least very -cumbersome, for controllers to cooperate with each other. - -In most use cases, putting controllers on hierarchies which are -completely orthogonal to each other isn't necessary. What usually is -called for is the ability to have differing levels of granularity -depending on the specific controller. In other words, hierarchy may -be collapsed from leaf towards root when viewed from specific -controllers. For example, a given configuration might not care about -how memory is distributed beyond a certain level while still wanting -to control how CPU cycles are distributed. - -Unified hierarchy is the next version of cgroup interface. It aims to -address the aforementioned issues by having more structure while -retaining enough flexibility for most use cases. Various other -general and controller-specific interface issues are also addressed in -the process. - - -2. Basic Operation - -2-1. Mounting - -Currently, unified hierarchy can be mounted with the following mount -command. Note that this is still under development and scheduled to -change soon. - - mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT - -All controllers which support the unified hierarchy and are not bound -to other hierarchies are automatically bound to unified hierarchy and -show up at the root of it. Controllers which are enabled only in the -root of unified hierarchy can be bound to other hierarchies. This -allows mixing unified hierarchy with the traditional multiple -hierarchies in a fully backward compatible way. - -For development purposes, the following boot parameter makes all -controllers to appear on the unified hierarchy whether supported or -not. - - cgroup__DEVEL__legacy_files_on_dfl - -A controller can be moved across hierarchies only after the controller -is no longer referenced in its current hierarchy. Because per-cgroup -controller states are destroyed asynchronously and controllers may -have lingering references, a controller may not show up immediately on -the unified hierarchy after the final umount of the previous -hierarchy. Similarly, a controller should be fully disabled to be -moved out of the unified hierarchy and it may take some time for the -disabled controller to become available for other hierarchies; -furthermore, due to dependencies among controllers, other controllers -may need to be disabled too. - -While useful for development and manual configurations, dynamically -moving controllers between the unified and other hierarchies is -strongly discouraged for production use. It is recommended to decide -the hierarchies and controller associations before starting using the -controllers. - - -2-2. cgroup.subtree_control - -All cgroups on unified hierarchy have a "cgroup.subtree_control" file -which governs which controllers are enabled on the children of the -cgroup. Let's assume a hierarchy like the following. - - root - A - B - C - \ D - -root's "cgroup.subtree_control" file determines which controllers are -enabled on A. A's on B. B's on C and D. This coincides with the -fact that controllers on the immediate sub-level are used to -distribute the resources of the parent. In fact, it's natural to -assume that resource control knobs of a child belong to its parent. -Enabling a controller in a "cgroup.subtree_control" file declares that -distribution of the respective resources of the cgroup will be -controlled. Note that this means that controller enable states are -shared among siblings. - -When read, the file contains a space-separated list of currently -enabled controllers. A write to the file should contain a -space-separated list of controllers with '+' or '-' prefixed (without -the quotes). Controllers prefixed with '+' are enabled and '-' -disabled. If a controller is listed multiple times, the last entry -wins. The specific operations are executed atomically - either all -succeed or fail. - - -2-3. cgroup.controllers - -Read-only "cgroup.controllers" file contains a space-separated list of -controllers which can be enabled in the cgroup's -"cgroup.subtree_control" file. - -In the root cgroup, this lists controllers which are not bound to -other hierarchies and the content changes as controllers are bound to -and unbound from other hierarchies. - -In non-root cgroups, the content of this file equals that of the -parent's "cgroup.subtree_control" file as only controllers enabled -from the parent can be used in its children. - - -3. Structural Constraints - -3-1. Top-down - -As it doesn't make sense to nest control of an uncontrolled resource, -all non-root "cgroup.subtree_control" files can only contain -controllers which are enabled in the parent's "cgroup.subtree_control" -file. A controller can be enabled only if the parent has the -controller enabled and a controller can't be disabled if one or more -children have it enabled. - - -3-2. No internal tasks - -One long-standing issue that cgroup faces is the competition between -tasks belonging to the parent cgroup and its children cgroups. This -is inherently nasty as two different types of entities compete and -there is no agreed-upon obvious way to handle it. Different -controllers are doing different things. - -The cpu controller considers tasks and cgroups as equivalents and maps -nice levels to cgroup weights. This works for some cases but falls -flat when children should be allocated specific ratios of CPU cycles -and the number of internal tasks fluctuates - the ratios constantly -change as the number of competing entities fluctuates. There also are -other issues. The mapping from nice level to weight isn't obvious or -universal, and there are various other knobs which simply aren't -available for tasks. - -The io controller implicitly creates a hidden leaf node for each -cgroup to host the tasks. The hidden leaf has its own copies of all -the knobs with "leaf_" prefixed. While this allows equivalent control -over internal tasks, it's with serious drawbacks. It always adds an -extra layer of nesting which may not be necessary, makes the interface -messy and significantly complicates the implementation. - -The memory controller currently doesn't have a way to control what -happens between internal tasks and child cgroups and the behavior is -not clearly defined. There have been attempts to add ad-hoc behaviors -and knobs to tailor the behavior to specific workloads. Continuing -this direction will lead to problems which will be extremely difficult -to resolve in the long term. - -Multiple controllers struggle with internal tasks and came up with -different ways to deal with it; unfortunately, all the approaches in -use now are severely flawed and, furthermore, the widely different -behaviors make cgroup as whole highly inconsistent. - -It is clear that this is something which needs to be addressed from -cgroup core proper in a uniform way so that controllers don't need to -worry about it and cgroup as a whole shows a consistent and logical -behavior. To achieve that, unified hierarchy enforces the following -structural constraint: - - Except for the root, only cgroups which don't contain any task may - have controllers enabled in their "cgroup.subtree_control" files. - -Combined with other properties, this guarantees that, when a -controller is looking at the part of the hierarchy which has it -enabled, tasks are always only on the leaves. This rules out -situations where child cgroups compete against internal tasks of the -parent. - -There are two things to note. Firstly, the root cgroup is exempt from -the restriction. Root contains tasks and anonymous resource -consumption which can't be associated with any other cgroup and -requires special treatment from most controllers. How resource -consumption in the root cgroup is governed is up to each controller. - -Secondly, the restriction doesn't take effect if there is no enabled -controller in the cgroup's "cgroup.subtree_control" file. This is -important as otherwise it wouldn't be possible to create children of a -populated cgroup. To control resource distribution of a cgroup, the -cgroup must create children and transfer all its tasks to the children -before enabling controllers in its "cgroup.subtree_control" file. - - -4. Delegation - -4-1. Model of delegation - -A cgroup can be delegated to a less privileged user by granting write -access of the directory and its "cgroup.procs" file to the user. Note -that the resource control knobs in a given directory concern the -resources of the parent and thus must not be delegated along with the -directory. - -Once delegated, the user can build sub-hierarchy under the directory, -organize processes as it sees fit and further distribute the resources -it got from the parent. The limits and other settings of all resource -controllers are hierarchical and regardless of what happens in the -delegated sub-hierarchy, nothing can escape the resource restrictions -imposed by the parent. - -Currently, cgroup doesn't impose any restrictions on the number of -cgroups in or nesting depth of a delegated sub-hierarchy; however, -this may in the future be limited explicitly. - - -4-2. Common ancestor rule - -On the unified hierarchy, to write to a "cgroup.procs" file, in -addition to the usual write permission to the file and uid match, the -writer must also have write access to the "cgroup.procs" file of the -common ancestor of the source and destination cgroups. This prevents -delegatees from smuggling processes across disjoint sub-hierarchies. - -Let's say cgroups C0 and C1 have been delegated to user U0 who created -C00, C01 under C0 and C10 under C1 as follows. - - ~~~~~~~~~~~~~ - C0 - C00 - ~ cgroup ~ \ C01 - ~ hierarchy ~ - ~~~~~~~~~~~~~ - C1 - C10 - -C0 and C1 are separate entities in terms of resource distribution -regardless of their relative positions in the hierarchy. The -resources the processes under C0 are entitled to are controlled by -C0's ancestors and may be completely different from C1. It's clear -that the intention of delegating C0 to U0 is allowing U0 to organize -the processes under C0 and further control the distribution of C0's -resources. - -On traditional hierarchies, if a task has write access to "tasks" or -"cgroup.procs" file of a cgroup and its uid agrees with the target, it -can move the target to the cgroup. In the above example, U0 will not -only be able to move processes in each sub-hierarchy but also across -the two sub-hierarchies, effectively allowing it to violate the -organizational and resource restrictions implied by the hierarchical -structure above C0 and C1. - -On the unified hierarchy, let's say U0 wants to write the pid of a -process which has a matching uid and is currently in C10 into -"C00/cgroup.procs". U0 obviously has write access to the file and -migration permission on the process; however, the common ancestor of -the source cgroup C10 and the destination cgroup C00 is above the -points of delegation and U0 would not have write access to its -"cgroup.procs" and thus be denied with -EACCES. - - -5. Other Changes - -5-1. [Un]populated Notification - -cgroup users often need a way to determine when a cgroup's -subhierarchy becomes empty so that it can be cleaned up. cgroup -currently provides release_agent for it; unfortunately, this mechanism -is riddled with issues. - -- It delivers events by forking and execing a userland binary - specified as the release_agent. This is a long deprecated method of - notification delivery. It's extremely heavy, slow and cumbersome to - integrate with larger infrastructure. - -- There is single monitoring point at the root. There's no way to - delegate management of a subtree. - -- The event isn't recursive. It triggers when a cgroup doesn't have - any tasks or child cgroups. Events for internal nodes trigger only - after all children are removed. This again makes it impossible to - delegate management of a subtree. - -- Events are filtered from the kernel side. A "notify_on_release" - file is used to subscribe to or suppress release events. This is - unnecessarily complicated and probably done this way because event - delivery itself was expensive. - -Unified hierarchy implements an interface file "cgroup.populated" -which can be used to monitor whether the cgroup's subhierarchy has -tasks in it or not. Its value is 0 if there is no task in the cgroup -and its descendants; otherwise, 1. poll and [id]notify events are -triggered when the value changes. - -This is significantly lighter and simpler and trivially allows -delegating management of subhierarchy - subhierarchy monitoring can -block further propagation simply by putting itself or another process -in the subhierarchy and monitor events that it's interested in from -there without interfering with monitoring higher in the tree. - -In unified hierarchy, the release_agent mechanism is no longer -supported and the interface files "release_agent" and -"notify_on_release" do not exist. - - -5-2. Other Core Changes - -- None of the mount options is allowed. - -- remount is disallowed. - -- rename(2) is disallowed. - -- The "tasks" file is removed. Everything should at process - granularity. Use the "cgroup.procs" file instead. - -- The "cgroup.procs" file is not sorted. pids will be unique unless - they got recycled in-between reads. - -- The "cgroup.clone_children" file is removed. - - -5-3. Controller File Conventions - -5-3-1. Format - -In general, all controller files should be in one of the following -formats whenever possible. - -- Values only files - - VAL0 VAL1...\n - -- Flat keyed files - - KEY0 VAL0\n - KEY1 VAL1\n - ... - -- Nested keyed files - - KEY0 SUB_KEY0=VAL00 SUB_KEY1=VAL01... - KEY1 SUB_KEY0=VAL10 SUB_KEY1=VAL11... - ... - -For a writeable file, the format for writing should generally match -reading; however, controllers may allow omitting later fields or -implement restricted shortcuts for most common use cases. - -For both flat and nested keyed files, only the values for a single key -can be written at a time. For nested keyed files, the sub key pairs -may be specified in any order and not all pairs have to be specified. - - -5-3-2. Control Knobs - -- Settings for a single feature should generally be implemented in a - single file. - -- In general, the root cgroup should be exempt from resource control - and thus shouldn't have resource control knobs. - -- If a controller implements ratio based resource distribution, the - control knob should be named "weight" and have the range [1, 10000] - and 100 should be the default value. The values are chosen to allow - enough and symmetric bias in both directions while keeping it - intuitive (the default is 100%). - -- If a controller implements an absolute resource guarantee and/or - limit, the control knobs should be named "min" and "max" - respectively. If a controller implements best effort resource - gurantee and/or limit, the control knobs should be named "low" and - "high" respectively. - - In the above four control files, the special token "max" should be - used to represent upward infinity for both reading and writing. - -- If a setting has configurable default value and specific overrides, - the default settings should be keyed with "default" and appear as - the first entry in the file. Specific entries can use "default" as - its value to indicate inheritance of the default value. - - -5-4. Per-Controller Changes - -5-4-1. io - -- blkio is renamed to io. The interface is overhauled anyway. The - new name is more in line with the other two major controllers, cpu - and memory, and better suited given that it may be used for cgroup - writeback without involving block layer. - -- Everything including stat is always hierarchical making separate - recursive stat files pointless and, as no internal node can have - tasks, leaf weights are meaningless. The operation model is - simplified and the interface is overhauled accordingly. - - io.stat - - The stat file. The reported stats are from the point where - bio's are issued to request_queue. The stats are counted - independent of which policies are enabled. Each line in the - file follows the following format. More fields may later be - added at the end. - - $MAJ:$MIN rbytes=$RBYTES wbytes=$WBYTES rios=$RIOS wrios=$WIOS - - io.weight - - The weight setting, currently only available and effective if - cfq-iosched is in use for the target device. The weight is - between 1 and 10000 and defaults to 100. The first line - always contains the default weight in the following format to - use when per-device setting is missing. - - default $WEIGHT - - Subsequent lines list per-device weights of the following - format. - - $MAJ:$MIN $WEIGHT - - Writing "$WEIGHT" or "default $WEIGHT" changes the default - setting. Writing "$MAJ:$MIN $WEIGHT" sets per-device weight - while "$MAJ:$MIN default" clears it. - - This file is available only on non-root cgroups. - - io.max - - The maximum bandwidth and/or iops setting, only available if - blk-throttle is enabled. The file is of the following format. - - $MAJ:$MIN rbps=$RBPS wbps=$WBPS riops=$RIOPS wiops=$WIOPS - - ${R|W}BPS are read/write bytes per second and ${R|W}IOPS are - read/write IOs per second. "max" indicates no limit. Writing - to the file follows the same format but the individual - settings may be ommitted or specified in any order. - - This file is available only on non-root cgroups. - - -5-4-2. cpuset - -- Tasks are kept in empty cpusets after hotplug and take on the masks - of the nearest non-empty ancestor, instead of being moved to it. - -- A task can be moved into an empty cpuset, and again it takes on the - masks of the nearest non-empty ancestor. - - -5-4-3. memory - -- use_hierarchy is on by default and the cgroup file for the flag is - not created. - -- The original lower boundary, the soft limit, is defined as a limit - that is per default unset. As a result, the set of cgroups that - global reclaim prefers is opt-in, rather than opt-out. The costs - for optimizing these mostly negative lookups are so high that the - implementation, despite its enormous size, does not even provide the - basic desirable behavior. First off, the soft limit has no - hierarchical meaning. All configured groups are organized in a - global rbtree and treated like equal peers, regardless where they - are located in the hierarchy. This makes subtree delegation - impossible. Second, the soft limit reclaim pass is so aggressive - that it not just introduces high allocation latencies into the - system, but also impacts system performance due to overreclaim, to - the point where the feature becomes self-defeating. - - The memory.low boundary on the other hand is a top-down allocated - reserve. A cgroup enjoys reclaim protection when it and all its - ancestors are below their low boundaries, which makes delegation of - subtrees possible. Secondly, new cgroups have no reserve per - default and in the common case most cgroups are eligible for the - preferred reclaim pass. This allows the new low boundary to be - efficiently implemented with just a minor addition to the generic - reclaim code, without the need for out-of-band data structures and - reclaim passes. Because the generic reclaim code considers all - cgroups except for the ones running low in the preferred first - reclaim pass, overreclaim of individual groups is eliminated as - well, resulting in much better overall workload performance. - -- The original high boundary, the hard limit, is defined as a strict - limit that can not budge, even if the OOM killer has to be called. - But this generally goes against the goal of making the most out of - the available memory. The memory consumption of workloads varies - during runtime, and that requires users to overcommit. But doing - that with a strict upper limit requires either a fairly accurate - prediction of the working set size or adding slack to the limit. - Since working set size estimation is hard and error prone, and - getting it wrong results in OOM kills, most users tend to err on the - side of a looser limit and end up wasting precious resources. - - The memory.high boundary on the other hand can be set much more - conservatively. When hit, it throttles allocations by forcing them - into direct reclaim to work off the excess, but it never invokes the - OOM killer. As a result, a high boundary that is chosen too - aggressively will not terminate the processes, but instead it will - lead to gradual performance degradation. The user can monitor this - and make corrections until the minimal memory footprint that still - gives acceptable performance is found. - - In extreme cases, with many concurrent allocations and a complete - breakdown of reclaim progress within the group, the high boundary - can be exceeded. But even then it's mostly better to satisfy the - allocation from the slack available in other groups or the rest of - the system than killing the group. Otherwise, memory.max is there - to limit this type of spillover and ultimately contain buggy or even - malicious applications. - -- The original control file names are unwieldy and inconsistent in - many different ways. For example, the upper boundary hit count is - exported in the memory.failcnt file, but an OOM event count has to - be manually counted by listening to memory.oom_control events, and - lower boundary / soft limit events have to be counted by first - setting a threshold for that value and then counting those events. - Also, usage and limit files encode their units in the filename. - That makes the filenames very long, even though this is not - information that a user needs to be reminded of every time they type - out those names. - - To address these naming issues, as well as to signal clearly that - the new interface carries a new configuration model, the naming - conventions in it necessarily differ from the old interface. - -- The original limit files indicate the state of an unset limit with a - Very High Number, and a configured limit can be unset by echoing -1 - into those files. But that very high number is implementation and - architecture dependent and not very descriptive. And while -1 can - be understood as an underflow into the highest possible value, -2 or - -10M etc. do not work, so it's not consistent. - - memory.low, memory.high, and memory.max will use the string "max" to - indicate and set the highest possible value. - -6. Planned Changes - -6-1. CAP for resource control - -Unified hierarchy will require one of the capabilities(7), which is -yet to be decided, for all resource control related knobs. Process -organization operations - creation of sub-cgroups and migration of -processes in sub-hierarchies may be delegated by changing the -ownership and/or permissions on the cgroup directory and -"cgroup.procs" interface file; however, all operations which affect -resource control - writes to a "cgroup.subtree_control" file or any -controller-specific knobs - will require an explicit CAP privilege. - -This, in part, is to prevent the cgroup interface from being -inadvertently promoted to programmable API used by non-privileged -binaries. cgroup exposes various aspects of the system in ways which -aren't properly abstracted for direct consumption by regular programs. -This is an administration interface much closer to sysctl knobs than -system calls. Even the basic access model, being filesystem path -based, isn't suitable for direct consumption. There's no way to -access "my cgroup" in a race-free way or make multiple operations -atomic against migration to another cgroup. - -Another aspect is that, for better or for worse, the cgroup interface -goes through far less scrutiny than regular interfaces for -unprivileged userland. The upside is that cgroup is able to expose -useful features which may not be suitable for general consumption in a -reasonable time frame. It provides a relatively short path between -internal details and userland-visible interface. Of course, this -shortcut comes with high risk. We go through what we go through for -general kernel APIs for good reasons. It may end up leaking internal -details in a way which can exert significant pain by locking the -kernel into a contract that can't be maintained in a reasonable -manner. - -Also, due to the specific nature, cgroup and its controllers don't -tend to attract attention from a wide scope of developers. cgroup's -short history is already fraught with severely mis-designed -interfaces, unnecessary commitments to and exposing of internal -details, broken and dangerous implementations of various features. - -Keeping cgroup as an administration interface is both advantageous for -its role and imperative given its nature. Some of the cgroup features -may make sense for unprivileged access. If deemed justified, those -must be further abstracted and implemented as a different interface, -be it a system call or process-private filesystem, and survive through -the scrutiny that any interface for general consumption is required to -go through. - -Requiring CAP is not a complete solution but should serve as a -significant deterrent against spraying cgroup usages in non-privileged -programs. diff --git a/Documentation/cpu-freq/intel-pstate.txt b/Documentation/cpu-freq/intel-pstate.txt index be8d4006bf76..e6bd1e6512a5 100644 --- a/Documentation/cpu-freq/intel-pstate.txt +++ b/Documentation/cpu-freq/intel-pstate.txt @@ -1,61 +1,131 @@ -Intel P-state driver +Intel P-State driver -------------------- -This driver provides an interface to control the P state selection for -SandyBridge+ Intel processors. The driver can operate two different -modes based on the processor model, legacy mode and Hardware P state (HWP) -mode. - -In legacy mode, the Intel P-state implements two internal governors, -performance and powersave, that differ from the general cpufreq governors of -the same name (the general cpufreq governors implement target(), whereas the -internal Intel P-state governors implement setpolicy()). The internal -performance governor sets the max_perf_pct and min_perf_pct to 100; that is, -the governor selects the highest available P state to maximize the performance -of the core. The internal powersave governor selects the appropriate P state -based on the current load on the CPU. - -In HWP mode P state selection is implemented in the processor -itself. The driver provides the interfaces between the cpufreq core and -the processor to control P state selection based on user preferences -and reporting frequency to the cpufreq core. In this mode the -internal Intel P-state governor code is disabled. - -In addition to the interfaces provided by the cpufreq core for -controlling frequency the driver provides sysfs files for -controlling P state selection. These files have been added to -/sys/devices/system/cpu/intel_pstate/ - - max_perf_pct: limits the maximum P state that will be requested by - the driver stated as a percentage of the available performance. The - available (P states) performance may be reduced by the no_turbo +This driver provides an interface to control the P-State selection for the +SandyBridge+ Intel processors. + +The following document explains P-States: +http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf +As stated in the document, P-State doesn’t exactly mean a frequency. However, for +the sake of the relationship with cpufreq, P-State and frequency are used +interchangeably. + +Understanding the cpufreq core governors and policies are important before +discussing more details about the Intel P-State driver. Based on what callbacks +a cpufreq driver provides to the cpufreq core, it can support two types of +drivers: +- with target_index() callback: In this mode, the drivers using cpufreq core +simply provide the minimum and maximum frequency limits and an additional +interface target_index() to set the current frequency. The cpufreq subsystem +has a number of scaling governors ("performance", "powersave", "ondemand", +etc.). Depending on which governor is in use, cpufreq core will call for +transitions to a specific frequency using target_index() callback. +- setpolicy() callback: In this mode, drivers do not provide target_index() +callback, so cpufreq core can't request a transition to a specific frequency. +The driver provides minimum and maximum frequency limits and callbacks to set a +policy. The policy in cpufreq sysfs is referred to as the "scaling governor". +The cpufreq core can request the driver to operate in any of the two policies: +"performance" and "powersave". The driver decides which frequency to use based +on the above policy selection considering minimum and maximum frequency limits. + +The Intel P-State driver falls under the latter category, which implements the +setpolicy() callback. This driver decides what P-State to use based on the +requested policy from the cpufreq core. If the processor is capable of +selecting its next P-State internally, then the driver will offload this +responsibility to the processor (aka HWP: Hardware P-States). If not, the +driver implements algorithms to select the next P-State. + +Since these policies are implemented in the driver, they are not same as the +cpufreq scaling governors implementation, even if they have the same name in +the cpufreq sysfs (scaling_governors). For example the "performance" policy is +similar to cpufreq’s "performance" governor, but "powersave" is completely +different than the cpufreq "powersave" governor. The strategy here is similar +to cpufreq "ondemand", where the requested P-State is related to the system load. + +Sysfs Interface + +In addition to the frequency-controlling interfaces provided by the cpufreq +core, the driver provides its own sysfs files to control the P-State selection. +These files have been added to /sys/devices/system/cpu/intel_pstate/. +Any changes made to these files are applicable to all CPUs (even in a +multi-package system). + + max_perf_pct: Limits the maximum P-State that will be requested by + the driver. It states it as a percentage of the available performance. The + available (P-State) performance may be reduced by the no_turbo setting described below. - min_perf_pct: limits the minimum P state that will be requested by - the driver stated as a percentage of the max (non-turbo) + min_perf_pct: Limits the minimum P-State that will be requested by + the driver. It states it as a percentage of the max (non-turbo) performance level. - no_turbo: limits the driver to selecting P states below the turbo + no_turbo: Limits the driver to selecting P-State below the turbo frequency range. - turbo_pct: displays the percentage of the total performance that - is supported by hardware that is in the turbo range. This number + turbo_pct: Displays the percentage of the total performance that + is supported by hardware that is in the turbo range. This number is independent of whether turbo has been disabled or not. - num_pstates: displays the number of pstates that are supported - by hardware. This number is independent of whether turbo has + num_pstates: Displays the number of P-States that are supported + by hardware. This number is independent of whether turbo has been disabled or not. +For example, if a system has these parameters: + Max 1 core turbo ratio: 0x21 (Max 1 core ratio is the maximum P-State) + Max non turbo ratio: 0x17 + Minimum ratio : 0x08 (Here the ratio is called max efficiency ratio) + +Sysfs will show : + max_perf_pct:100, which corresponds to 1 core ratio + min_perf_pct:24, max_efficiency_ratio / max 1 Core ratio + no_turbo:0, turbo is not disabled + num_pstates:26 = (max 1 Core ratio - Max Efficiency Ratio + 1) + turbo_pct:39 = (max 1 core ratio - max non turbo ratio) / num_pstates + +Refer to "Intel® 64 and IA-32 Architectures Software Developer’s Manual +Volume 3: System Programming Guide" to understand ratios. + +cpufreq sysfs for Intel P-State + +Since this driver registers with cpufreq, cpufreq sysfs is also presented. +There are some important differences, which need to be considered. + +scaling_cur_freq: This displays the real frequency which was used during +the last sample period instead of what is requested. Some other cpufreq driver, +like acpi-cpufreq, displays what is requested (Some changes are on the +way to fix this for acpi-cpufreq driver). The same is true for frequencies +displayed at /proc/cpuinfo. + +scaling_governor: This displays current active policy. Since each CPU has a +cpufreq sysfs, it is possible to set a scaling governor to each CPU. But this +is not possible with Intel P-States, as there is one common policy for all +CPUs. Here, the last requested policy will be applicable to all CPUs. It is +suggested that one use the cpupower utility to change policy to all CPUs at the +same time. + +scaling_setspeed: This attribute can never be used with Intel P-State. + +scaling_max_freq/scaling_min_freq: This interface can be used similarly to +the max_perf_pct/min_perf_pct of Intel P-State sysfs. However since frequencies +are converted to nearest possible P-State, this is prone to rounding errors. +This method is not preferred to limit performance. + +affected_cpus: Not used +related_cpus: Not used + For contemporary Intel processors, the frequency is controlled by the -processor itself and the P-states exposed to software are related to +processor itself and the P-State exposed to software is related to performance levels. The idea that frequency can be set to a single -frequency is fiction for Intel Core processors. Even if the scaling -driver selects a single P state the actual frequency the processor +frequency is fictional for Intel Core processors. Even if the scaling +driver selects a single P-State, the actual frequency the processor will run at is selected by the processor itself. -For legacy mode debugfs files have also been added to allow tuning of -the internal governor algorythm. These files are located at -/sys/kernel/debug/pstate_snb/ These files are NOT present in HWP mode. +Tuning Intel P-State driver + +When HWP mode is not used, debugfs files have also been added to allow the +tuning of the internal governor algorithm. These files are located at +/sys/kernel/debug/pstate_snb/. The algorithm uses a PID (Proportional +Integral Derivative) controller. The PID tunable parameters are: deadband d_gain_pct @@ -63,3 +133,90 @@ the internal governor algorythm. These files are located at p_gain_pct sample_rate_ms setpoint + +To adjust these parameters, some understanding of driver implementation is +necessary. There are some tweeks described here, but be very careful. Adjusting +them requires expert level understanding of power and performance relationship. +These limits are only useful when the "powersave" policy is active. + +-To make the system more responsive to load changes, sample_rate_ms can +be adjusted (current default is 10ms). +-To make the system use higher performance, even if the load is lower, setpoint +can be adjusted to a lower number. This will also lead to faster ramp up time +to reach the maximum P-State. +If there are no derivative and integral coefficients, The next P-State will be +equal to: + current P-State - ((setpoint - current cpu load) * p_gain_pct) + +For example, if the current PID parameters are (Which are defaults for the core +processors like SandyBridge): + deadband = 0 + d_gain_pct = 0 + i_gain_pct = 0 + p_gain_pct = 20 + sample_rate_ms = 10 + setpoint = 97 + +If the current P-State = 0x08 and current load = 100, this will result in the +next P-State = 0x08 - ((97 - 100) * 0.2) = 8.6 (rounded to 9). Here the P-State +goes up by only 1. If during next sample interval the current load doesn't +change and still 100, then P-State goes up by one again. This process will +continue as long as the load is more than the setpoint until the maximum P-State +is reached. + +For the same load at setpoint = 60, this will result in the next P-State += 0x08 - ((60 - 100) * 0.2) = 16 +So by changing the setpoint from 97 to 60, there is an increase of the +next P-State from 9 to 16. So this will make processor execute at higher +P-State for the same CPU load. If the load continues to be more than the +setpoint during next sample intervals, then P-State will go up again till the +maximum P-State is reached. But the ramp up time to reach the maximum P-State +will be much faster when the setpoint is 60 compared to 97. + +Debugging Intel P-State driver + +Event tracing +To debug P-State transition, the Linux event tracing interface can be used. +There are two specific events, which can be enabled (Provided the kernel +configs related to event tracing are enabled). + +# cd /sys/kernel/debug/tracing/ +# echo 1 > events/power/pstate_sample/enable +# echo 1 > events/power/cpu_frequency/enable +# cat trace +gnome-terminal--4510 [001] ..s. 1177.680733: pstate_sample: core_busy=107 + scaled=94 from=26 to=26 mperf=1143818 aperf=1230607 tsc=29838618 + freq=2474476 +cat-5235 [002] ..s. 1177.681723: cpu_frequency: state=2900000 cpu_id=2 + + +Using ftrace + +If function level tracing is required, the Linux ftrace interface can be used. +For example if we want to check how often a function to set a P-State is +called, we can set ftrace filter to intel_pstate_set_pstate. + +# cd /sys/kernel/debug/tracing/ +# cat available_filter_functions | grep -i pstate +intel_pstate_set_pstate +intel_pstate_cpu_init +... + +# echo intel_pstate_set_pstate > set_ftrace_filter +# echo function > current_tracer +# cat trace | head -15 +# tracer: function +# +# entries-in-buffer/entries-written: 80/80 #P:4 +# +# _-----=> irqs-off +# / _----=> need-resched +# | / _---=> hardirq/softirq +# || / _--=> preempt-depth +# ||| / delay +# TASK-PID CPU# |||| TIMESTAMP FUNCTION +# | | | |||| | | + Xorg-3129 [000] ..s. 2537.644844: intel_pstate_set_pstate <-intel_pstate_timer_func + gnome-terminal--4510 [002] ..s. 2537.649844: intel_pstate_set_pstate <-intel_pstate_timer_func + gnome-shell-3409 [001] ..s. 2537.650850: intel_pstate_set_pstate <-intel_pstate_timer_func + <idle>-0 [000] ..s. 2537.654843: intel_pstate_set_pstate <-intel_pstate_timer_func diff --git a/Documentation/cpu-freq/pcc-cpufreq.txt b/Documentation/cpu-freq/pcc-cpufreq.txt index 9e3c3b33514c..0a94224ad296 100644 --- a/Documentation/cpu-freq/pcc-cpufreq.txt +++ b/Documentation/cpu-freq/pcc-cpufreq.txt @@ -159,8 +159,8 @@ to be strictly associated with a P-state. 2.2 cpuinfo_transition_latency: ------------------------------- -The cpuinfo_transition_latency field is 0. The PCC specification does -not include a field to expose this value currently. +The cpuinfo_transition_latency field is CPUFREQ_ETERNAL. The PCC specification +does not include a field to expose this value currently. 2.3 cpuinfo_cur_freq: --------------------- diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt index f9ad5e048b11..dd68821c22d4 100644 --- a/Documentation/cpu-hotplug.txt +++ b/Documentation/cpu-hotplug.txt @@ -150,7 +150,7 @@ an entry as shown below in the output. If this is not mounted, do the following. - #mkdir /sysfs + #mkdir /sys #mount -t sysfs sys /sys Now you should see entries for all present cpu, the following is an example diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt index 8b49302712a8..beda682e8d77 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.txt @@ -49,28 +49,33 @@ under development. Here's an example of how to use the API: - #include <linux/crypto.h> + #include <crypto/ahash.h> #include <linux/err.h> #include <linux/scatterlist.h> struct scatterlist sg[2]; char result[128]; - struct crypto_hash *tfm; - struct hash_desc desc; + struct crypto_ahash *tfm; + struct ahash_request *req; - tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC); + tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC); if (IS_ERR(tfm)) fail(); /* ... set up the scatterlists ... */ - desc.tfm = tfm; - desc.flags = 0; - - if (crypto_hash_digest(&desc, sg, 2, result)) + req = ahash_request_alloc(tfm, GFP_ATOMIC); + if (!req) fail(); + + ahash_request_set_callback(req, 0, NULL, NULL); + ahash_request_set_crypt(req, sg, result, 2); - crypto_free_hash(tfm); + if (crypto_ahash_digest(req)) + fail(); + + ahash_request_free(req); + crypto_free_ahash(tfm); Many real examples are available in the regression test module (tcrypt.c). diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt index b7675904a747..8c07e0ea6bc0 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.txt @@ -186,7 +186,7 @@ and looks like the following: const struct public_key_signature *sig); }; -Asymmetric keys point to this with their type_data[0] member. +Asymmetric keys point to this with their payload[asym_subtype] member. The owner and name fields should be set to the owning module and the name of the subtype. Currently, the name is only used for print statements. @@ -269,8 +269,7 @@ mandatory: struct key_preparsed_payload { char *description; - void *type_data[2]; - void *payload; + void *payload[4]; const void *data; size_t datalen; size_t quotalen; @@ -283,16 +282,18 @@ mandatory: not theirs. If the parser is happy with the blob, it should propose a description for - the key and attach it to ->description, ->type_data[0] should be set to - point to the subtype to be used, ->payload should be set to point to the - initialised data for that subtype, ->type_data[1] should point to a hex - fingerprint and quotalen should be updated to indicate how much quota this - key should account for. - - When clearing up, the data attached to ->type_data[1] and ->description - will be kfree()'d and the data attached to ->payload will be passed to the - subtype's ->destroy() method to be disposed of. A module reference for - the subtype pointed to by ->type_data[0] will be put. + the key and attach it to ->description, ->payload[asym_subtype] should be + set to point to the subtype to be used, ->payload[asym_crypto] should be + set to point to the initialised data for that subtype, + ->payload[asym_key_ids] should point to one or more hex fingerprints and + quotalen should be updated to indicate how much quota this key should + account for. + + When clearing up, the data attached to ->payload[asym_key_ids] and + ->description will be kfree()'d and the data attached to + ->payload[asm_crypto] will be passed to the subtype's ->destroy() method + to be disposed of. A module reference for the subtype pointed to by + ->payload[asym_subtype] will be put. If the data format is not recognised, -EBADMSG should be returned. If it diff --git a/Documentation/device-mapper/cache-policies.txt b/Documentation/device-mapper/cache-policies.txt index d9246a32e673..e5062ad18717 100644 --- a/Documentation/device-mapper/cache-policies.txt +++ b/Documentation/device-mapper/cache-policies.txt @@ -28,51 +28,16 @@ Overview of supplied cache replacement policies multiqueue (mq) --------------- -This policy has been deprecated in favor of the smq policy (see below). +This policy is now an alias for smq (see below). -The multiqueue policy has three sets of 16 queues: one set for entries -waiting for the cache and another two for those in the cache (a set for -clean entries and a set for dirty entries). +The following tunables are accepted, but have no effect: -Cache entries in the queues are aged based on logical time. Entry into -the cache is based on variable thresholds and queue selection is based -on hit count on entry. The policy aims to take different cache miss -costs into account and to adjust to varying load patterns automatically. - -Message and constructor argument pairs are: 'sequential_threshold <#nr_sequential_ios>' 'random_threshold <#nr_random_ios>' 'read_promote_adjustment <value>' 'write_promote_adjustment <value>' 'discard_promote_adjustment <value>' -The sequential threshold indicates the number of contiguous I/Os -required before a stream is treated as sequential. Once a stream is -considered sequential it will bypass the cache. The random threshold -is the number of intervening non-contiguous I/Os that must be seen -before the stream is treated as random again. - -The sequential and random thresholds default to 512 and 4 respectively. - -Large, sequential I/Os are probably better left on the origin device -since spindles tend to have good sequential I/O bandwidth. The -io_tracker counts contiguous I/Os to try to spot when the I/O is in one -of these sequential modes. But there are use-cases for wanting to -promote sequential blocks to the cache (e.g. fast application startup). -If sequential threshold is set to 0 the sequential I/O detection is -disabled and sequential I/O will no longer implicitly bypass the cache. -Setting the random threshold to 0 does _not_ disable the random I/O -stream detection. - -Internally the mq policy determines a promotion threshold. If the hit -count of a block not in the cache goes above this threshold it gets -promoted to the cache. The read, write and discard promote adjustment -tunables allow you to tweak the promotion threshold by adding a small -value based on the io type. They default to 4, 8 and 1 respectively. -If you're trying to quickly warm a new cache device you may wish to -reduce these to encourage promotion. Remember to switch them back to -their defaults after the cache fills though. - Stochastic multiqueue (smq) --------------------------- diff --git a/Documentation/device-mapper/delay.txt b/Documentation/device-mapper/delay.txt index 15adc55359e5..a07b5927f4a8 100644 --- a/Documentation/device-mapper/delay.txt +++ b/Documentation/device-mapper/delay.txt @@ -8,6 +8,7 @@ Parameters: <device> <offset> <delay> [<write_device> <write_offset> <write_delay>] With separate write parameters, the first set is only used for reads. +Offsets are specified in sectors. Delays are specified in milliseconds. Example scripts diff --git a/Documentation/device-mapper/verity.txt b/Documentation/device-mapper/verity.txt index e15bc1a0fb98..89fd8f9a259f 100644 --- a/Documentation/device-mapper/verity.txt +++ b/Documentation/device-mapper/verity.txt @@ -18,11 +18,11 @@ Construction Parameters 0 is the original format used in the Chromium OS. The salt is appended when hashing, digests are stored continuously and - the rest of the block is padded with zeros. + the rest of the block is padded with zeroes. 1 is the current format that should be used for new devices. The salt is prepended when hashing and each digest is - padded with zeros to the power of two. + padded with zeroes to the power of two. <dev> This is the device containing data, the integrity of which needs to be @@ -79,6 +79,37 @@ restart_on_corruption not compatible with ignore_corruption and requires user space support to avoid restart loops. +ignore_zero_blocks + Do not verify blocks that are expected to contain zeroes and always return + zeroes instead. This may be useful if the partition contains unused blocks + that are not guaranteed to contain zeroes. + +use_fec_from_device <fec_dev> + Use forward error correction (FEC) to recover from corruption if hash + verification fails. Use encoding data from the specified device. This + may be the same device where data and hash blocks reside, in which case + fec_start must be outside data and hash areas. + + If the encoding data covers additional metadata, it must be accessible + on the hash device after the hash blocks. + + Note: block sizes for data and hash devices must match. Also, if the + verity <dev> is encrypted the <fec_dev> should be too. + +fec_roots <num> + Number of generator roots. This equals to the number of parity bytes in + the encoding data. For example, in RS(M, N) encoding, the number of roots + is M-N. + +fec_blocks <num> + The number of encoding data blocks on the FEC device. The block size for + the FEC device is <data_block_size>. + +fec_start <offset> + This is the offset, in <data_block_size> blocks, from the start of the + FEC device to the beginning of the encoding data. + + Theory of operation =================== @@ -98,6 +129,11 @@ per-block basis. This allows for a lightweight hash computation on first read into the page cache. Block hashes are stored linearly, aligned to the nearest block size. +If forward error correction (FEC) support is enabled any recovery of +corrupted data will be verified using the cryptographic hash of the +corresponding data. This is why combining error correction with +integrity checking is essential. + Hash Tree --------- diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt b/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt new file mode 100644 index 000000000000..885f93d14ef9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt @@ -0,0 +1,49 @@ +Altera SoCFPGA ECC Manager +This driver uses the EDAC framework to implement the SOCFPGA ECC Manager. +The ECC Manager counts and corrects single bit errors and counts/handles +double bit errors which are uncorrectable. + +Required Properties: +- compatible : Should be "altr,socfpga-ecc-manager" +- #address-cells: must be 1 +- #size-cells: must be 1 +- ranges : standard definition, should translate from local addresses + +Subcomponents: + +L2 Cache ECC +Required Properties: +- compatible : Should be "altr,socfpga-l2-ecc" +- reg : Address and size for ECC error interrupt clear registers. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt. Note the rising edge type. + +On Chip RAM ECC +Required Properties: +- compatible : Should be "altr,socfpga-ocram-ecc" +- reg : Address and size for ECC error interrupt clear registers. +- iram : phandle to On-Chip RAM definition. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt. Note the rising edge type. + +Example: + + eccmgr: eccmgr@ffd08140 { + compatible = "altr,socfpga-ecc-manager"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + l2-ecc@ffd08140 { + compatible = "altr,socfpga-l2-ecc"; + reg = <0xffd08140 0x4>; + interrupts = <0 36 1>, <0 37 1>; + }; + + ocram-ecc@ffd08144 { + compatible = "altr,socfpga-ocram-ecc"; + reg = <0xffd08144 0x4>; + iram = <&ocram>; + interrupts = <0 178 1>, <0 179 1>; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/amlogic.txt b/Documentation/devicetree/bindings/arm/amlogic.txt index 973884a1bacf..1dfee20eee74 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.txt +++ b/Documentation/devicetree/bindings/arm/amlogic.txt @@ -9,6 +9,12 @@ Boards with the Amlogic Meson8 SoC shall have the following properties: Required root node property: compatible: "amlogic,meson8"; +Boards with the Amlogic Meson8b SoC shall have the following properties: + Required root node property: + compatible: "amlogic,meson8b"; + Board compatible values: - - "geniatech,atv1200" - - "minix,neo-x8" + - "geniatech,atv1200" (Meson6) + - "minix,neo-x8" (Meson8) + - "tronfy,mxq" (Meson8b) + - "hardkernel,odroid-c1" (Meson8b) diff --git a/Documentation/devicetree/bindings/arm/apm/scu.txt b/Documentation/devicetree/bindings/arm/apm/scu.txt new file mode 100644 index 000000000000..b45be06625fd --- /dev/null +++ b/Documentation/devicetree/bindings/arm/apm/scu.txt @@ -0,0 +1,17 @@ +APM X-GENE SoC series SCU Registers + +This system clock unit contain various register that control block resets, +clock enable/disables, clock divisors and other deepsleep registers. + +Properties: + - compatible : should contain two values. First value must be: + - "apm,xgene-scu" + second value must be always "syscon". + + - reg : offset and length of the register set. + +Example : + scu: system-clk-controller@17000000 { + compatible = "apm,xgene-scu","syscon"; + reg = <0x0 0x17000000 0x0 0x400>; + }; diff --git a/Documentation/devicetree/bindings/arm/arm,scpi.txt b/Documentation/devicetree/bindings/arm/arm,scpi.txt new file mode 100644 index 000000000000..313dabdc14f9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/arm,scpi.txt @@ -0,0 +1,188 @@ +System Control and Power Interface (SCPI) Message Protocol +---------------------------------------------------------- + +Firmware implementing the SCPI described in ARM document number ARM DUI 0922B +("ARM Compute Subsystem SCP: Message Interface Protocols")[0] can be used +by Linux to initiate various system control and power operations. + +Required properties: + +- compatible : should be "arm,scpi" +- mboxes: List of phandle and mailbox channel specifiers + All the channels reserved by remote SCP firmware for use by + SCPI message protocol should be specified in any order +- shmem : List of phandle pointing to the shared memory(SHM) area between the + processors using these mailboxes for IPC, one for each mailbox + SHM can be any memory reserved for the purpose of this communication + between the processors. + +See Documentation/devicetree/bindings/mailbox/mailbox.txt +for more details about the generic mailbox controller and +client driver bindings. + +Clock bindings for the clocks based on SCPI Message Protocol +------------------------------------------------------------ + +This binding uses the common clock binding[1]. + +Container Node +============== +Required properties: +- compatible : should be "arm,scpi-clocks" + All the clocks provided by SCP firmware via SCPI message + protocol much be listed as sub-nodes under this node. + +Sub-nodes +========= +Required properties: +- compatible : shall include one of the following + "arm,scpi-dvfs-clocks" - all the clocks that are variable and index based. + These clocks don't provide an entire range of values between the + limits but only discrete points within the range. The firmware + provides the mapping for each such operating frequency and the + index associated with it. The firmware also manages the + voltage scaling appropriately with the clock scaling. + "arm,scpi-variable-clocks" - all the clocks that are variable and provide full + range within the specified range. The firmware provides the + range of values within a specified range. + +Other required properties for all clocks(all from common clock binding): +- #clock-cells : Should be 1. Contains the Clock ID value used by SCPI commands. +- clock-output-names : shall be the corresponding names of the outputs. +- clock-indices: The identifying number for the clocks(i.e.clock_id) in the + node. It can be non linear and hence provide the mapping of identifiers + into the clock-output-names array. + +SRAM and Shared Memory for SCPI +------------------------------- + +A small area of SRAM is reserved for SCPI communication between application +processors and SCP. + +Required properties: +- compatible : should be "arm,juno-sram-ns" for Non-secure SRAM on Juno + +The rest of the properties should follow the generic mmio-sram description +found in ../../sram/sram.txt + +Each sub-node represents the reserved area for SCPI. + +Required sub-node properties: +- reg : The base offset and size of the reserved area with the SRAM +- compatible : should be "arm,juno-scp-shmem" for Non-secure SRAM based + shared memory on Juno platforms + +Sensor bindings for the sensors based on SCPI Message Protocol +-------------------------------------------------------------- +SCPI provides an API to access the various sensors on the SoC. + +Required properties: +- compatible : should be "arm,scpi-sensors". +- #thermal-sensor-cells: should be set to 1. This property follows the + thermal device tree bindings[2]. + + Valid cell values are raw identifiers (Sensor + ID) as used by the firmware. Refer to + platform documentation for your + implementation for the IDs to use. For Juno + R0 and Juno R1 refer to [3]. + +[0] http://infocenter.arm.com/help/topic/com.arm.doc.dui0922b/index.html +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Documentation/devicetree/bindings/thermal/thermal.txt +[3] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0922b/apas03s22.html + +Example: + +sram: sram@50000000 { + compatible = "arm,juno-sram-ns", "mmio-sram"; + reg = <0x0 0x50000000 0x0 0x10000>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x0 0x50000000 0x10000>; + + cpu_scp_lpri: scp-shmem@0 { + compatible = "arm,juno-scp-shmem"; + reg = <0x0 0x200>; + }; + + cpu_scp_hpri: scp-shmem@200 { + compatible = "arm,juno-scp-shmem"; + reg = <0x200 0x200>; + }; +}; + +mailbox: mailbox0@40000000 { + .... + #mbox-cells = <1>; +}; + +scpi_protocol: scpi@2e000000 { + compatible = "arm,scpi"; + mboxes = <&mailbox 0 &mailbox 1>; + shmem = <&cpu_scp_lpri &cpu_scp_hpri>; + + clocks { + compatible = "arm,scpi-clocks"; + + scpi_dvfs: scpi_clocks@0 { + compatible = "arm,scpi-dvfs-clocks"; + #clock-cells = <1>; + clock-indices = <0>, <1>, <2>; + clock-output-names = "atlclk", "aplclk","gpuclk"; + }; + scpi_clk: scpi_clocks@3 { + compatible = "arm,scpi-variable-clocks"; + #clock-cells = <1>; + clock-indices = <3>, <4>; + clock-output-names = "pxlclk0", "pxlclk1"; + }; + }; + + scpi_sensors0: sensors { + compatible = "arm,scpi-sensors"; + #thermal-sensor-cells = <1>; + }; +}; + +cpu@0 { + ... + reg = <0 0>; + clocks = <&scpi_dvfs 0>; +}; + +hdlcd@7ff60000 { + ... + reg = <0 0x7ff60000 0 0x1000>; + clocks = <&scpi_clk 4>; +}; + +thermal-zones { + soc_thermal { + polling-delay-passive = <100>; + polling-delay = <1000>; + + /* sensor ID */ + thermal-sensors = <&scpi_sensors0 3>; + ... + }; +}; + +In the above example, the #clock-cells is set to 1 as required. +scpi_dvfs has 3 output clocks namely: atlclk, aplclk, and gpuclk with 0, +1 and 2 as clock-indices. scpi_clk has 2 output clocks namely: pxlclk0 +and pxlclk1 with 3 and 4 as clock-indices. + +The first consumer in the example is cpu@0 and it has '0' as the clock +specifier which points to the first entry in the output clocks of +scpi_dvfs i.e. "atlclk". + +Similarly the second example is hdlcd@7ff60000 and it has pxlclk1 as input +clock. '4' in the clock specifier here points to the second entry +in the output clocks of scpi_clocks i.e. "pxlclk1" + +The thermal-sensors property in the soc_thermal node uses the +temperature sensor provided by SCP firmware to setup a thermal +zone. The ID "3" is the sensor identifier for the temperature sensor +as used by the firmware. diff --git a/Documentation/devicetree/bindings/arm/arm-boards b/Documentation/devicetree/bindings/arm/arm-boards index 1a709970e7f7..100db7347747 100644 --- a/Documentation/devicetree/bindings/arm/arm-boards +++ b/Documentation/devicetree/bindings/arm/arm-boards @@ -123,7 +123,9 @@ Required nodes: - syscon: some subnode of the RealView SoC node must be a system controller node pointing to the control registers, - with the compatible string set to one of these tuples: + with the compatible string set to one of these: + "arm,realview-eb11mp-revb-syscon", "arm,realview-eb-syscon", "syscon" + "arm,realview-eb11mp-revc-syscon", "arm,realview-eb-syscon", "syscon" "arm,realview-eb-syscon", "syscon" "arm,realview-pb1176-syscon", "syscon" "arm,realview-pb11mp-syscon", "syscon" diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt index c78576bb7729..11d3056dc2bd 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt @@ -26,6 +26,10 @@ Raspberry Pi Model B+ Required root node properties: compatible = "raspberrypi,model-b-plus", "brcm,bcm2835"; +Raspberry Pi 2 Model B +Required root node properties: +compatible = "raspberrypi,2-model-b", "brcm,bcm2836"; + Raspberry Pi Compute Module Required root node properties: compatible = "raspberrypi,compute-module", "brcm,bcm2835"; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.txt index 6b0f49f6f499..8608a776caa7 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm4708.txt @@ -5,4 +5,11 @@ Boards with the BCM4708 SoC shall have the following properties: Required root node property: +bcm4708 compatible = "brcm,bcm4708"; + +bcm4709 +compatible = "brcm,bcm4709"; + +bcm53012 +compatible = "brcm,bcm53012"; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt index 430608ec09f0..0d0c1ae81bed 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,brcmstb.txt @@ -20,6 +20,25 @@ system control is required: - compatible: "brcm,bcm<chip_id>-hif-cpubiuctrl", "syscon" - compatible: "brcm,bcm<chip_id>-hif-continuation", "syscon" +hif-cpubiuctrl 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. + +Required properties: + + - compatible: must be "brcm,bcm7445-hif-cpubiuctrl", "syscon" + +Optional properties: + + - brcm,write-pairing: + Boolean property, which when present indicates that the chip + supports write-pairing. + example: rdb { #address-cells = <1>; @@ -35,6 +54,7 @@ example: hif_cpubiuctrl: syscon@3e2400 { compatible = "brcm,bcm7445-hif-cpubiuctrl", "syscon"; reg = <0x3e2400 0x5b4>; + brcm,write-pairing; }; hif_continuation: syscon@452000 { @@ -43,8 +63,7 @@ example: }; }; -Lastly, nodes that allow for support of SMP initialization and reboot are -required: +Nodes that allow for support of SMP initialization and reboot are required: smpboot ------- @@ -95,3 +114,142 @@ example: compatible = "brcm,brcmstb-reboot"; syscon = <&sun_top_ctrl 0x304 0x308>; }; + + + +Power management +---------------- + +For power management (particularly, S2/S3/S5 system suspend), the following SoC +components are needed: + += Always-On control block (AON CTRL) + +This hardware provides control registers for the "always-on" (even in low-power +modes) hardware, such as the Power Management State Machine (PMSM). + +Required properties: +- compatible : should contain "brcm,brcmstb-aon-ctrl" +- reg : the register start and length for the AON CTRL block + +Example: + +aon-ctrl@410000 { + compatible = "brcm,brcmstb-aon-ctrl"; + reg = <0x410000 0x400>; +}; + += Memory controllers + +A Broadcom STB SoC typically has a number of independent memory controllers, +each of which may have several associated hardware blocks, which are versioned +independently (control registers, DDR PHYs, etc.). One might consider +describing these controllers as a parent "memory controllers" block, which +contains N sub-nodes (one for each controller in the system), each of which is +associated with a number of hardware register resources (e.g., its PHY). See +the example device tree snippet below. + +== MEMC (MEMory Controller) + +Represents a single memory controller instance. + +Required properties: +- compatible : should contain "brcm,brcmstb-memc" and "simple-bus" + +Should contain subnodes for any of the following relevant hardware resources: + +== DDR PHY control + +Control registers for this memory controller's DDR PHY. + +Required properties: +- compatible : should contain one of these + "brcm,brcmstb-ddr-phy-v225.1" + "brcm,brcmstb-ddr-phy-v240.1" + "brcm,brcmstb-ddr-phy-v240.2" + +- reg : the DDR PHY register range + +== DDR SHIMPHY + +Control registers for this memory controller's DDR SHIMPHY. + +Required properties: +- compatible : should contain "brcm,brcmstb-ddr-shimphy-v1.0" +- reg : the DDR SHIMPHY register range + +== MEMC DDR control + +Sequencer DRAM parameters and control registers. Used for Self-Refresh +Power-Down (SRPD), among other things. + +Required properties: +- compatible : should contain "brcm,brcmstb-memc-ddr" +- reg : the MEMC DDR register range + +Example: + +memory_controllers { + ranges; + compatible = "simple-bus"; + + memc@0 { + compatible = "brcm,brcmstb-memc", "simple-bus"; + ranges; + + ddr-phy@f1106000 { + compatible = "brcm,brcmstb-ddr-phy-v240.1"; + reg = <0xf1106000 0x21c>; + }; + + shimphy@f1108000 { + compatible = "brcm,brcmstb-ddr-shimphy-v1.0"; + reg = <0xf1108000 0xe4>; + }; + + memc-ddr@f1102000 { + reg = <0xf1102000 0x800>; + compatible = "brcm,brcmstb-memc-ddr"; + }; + }; + + memc@1 { + compatible = "brcm,brcmstb-memc", "simple-bus"; + ranges; + + ddr-phy@f1186000 { + compatible = "brcm,brcmstb-ddr-phy-v240.1"; + reg = <0xf1186000 0x21c>; + }; + + shimphy@f1188000 { + compatible = "brcm,brcmstb-ddr-shimphy-v1.0"; + reg = <0xf1188000 0xe4>; + }; + + memc-ddr@f1182000 { + reg = <0xf1182000 0x800>; + compatible = "brcm,brcmstb-memc-ddr"; + }; + }; + + memc@2 { + compatible = "brcm,brcmstb-memc", "simple-bus"; + ranges; + + ddr-phy@f1206000 { + compatible = "brcm,brcmstb-ddr-phy-v240.1"; + reg = <0xf1206000 0x21c>; + }; + + shimphy@f1208000 { + compatible = "brcm,brcmstb-ddr-shimphy-v1.0"; + reg = <0xf1208000 0xe4>; + }; + + memc-ddr@f1202000 { + reg = <0xf1202000 0x800>; + compatible = "brcm,brcmstb-memc-ddr"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,nsp-cpu-method.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp-cpu-method.txt new file mode 100644 index 000000000000..677ef9d9f445 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp-cpu-method.txt @@ -0,0 +1,39 @@ +Broadcom Northstar Plus SoC CPU Enable Method +--------------------------------------------- +This binding defines the enable method used for starting secondary +CPU in the following Broadcom SoCs: + BCM58522, BCM58525, BCM58535, BCM58622, BCM58623, BCM58625, BCM88312 + +The enable method is specified by defining the following required +properties in the corresponding secondary "cpu" device tree node: + - enable-method = "brcm,bcm-nsp-smp"; + - secondary-boot-reg = <...>; + +The secondary-boot-reg property is a u32 value that specifies the +physical address of the register which should hold the common +entry point for a secondary CPU. This entry is cpu node specific +and should be added per cpu. E.g., in case of NSP (BCM58625) which +is a dual core CPU SoC, this entry should be added to cpu1 node. + + +Example: + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu0: cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a9"; + next-level-cache = <&L2>; + reg = <0>; + }; + + cpu1: cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a9"; + next-level-cache = <&L2>; + enable-method = "brcm,bcm-nsp-smp"; + secondary-boot-reg = <0xffff042c>; + reg = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.txt new file mode 100644 index 000000000000..eae53e4556be --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,nsp.txt @@ -0,0 +1,34 @@ +Broadcom Northstar Plus device tree bindings +-------------------------------------------- + +Broadcom Northstar Plus family of SoCs are used for switching control +and management applications as well as residential router/gateway +applications. The SoC features dual core Cortex A9 ARM CPUs, integrating +several peripheral interfaces including multiple Gigabit Ethernet PHYs, +DDR3 memory, PCIE Gen-2, USB 2.0 and USB 3.0, serial and NAND flash, +SATA and several other IO controllers. + +Boards with Northstar Plus SoCs shall have the following properties: + +Required root node property: + +BCM58522 +compatible = "brcm,bcm58522", "brcm,nsp"; + +BCM58525 +compatible = "brcm,bcm58525", "brcm,nsp"; + +BCM58535 +compatible = "brcm,bcm58535", "brcm,nsp"; + +BCM58622 +compatible = "brcm,bcm58622", "brcm,nsp"; + +BCM58623 +compatible = "brcm,bcm58623", "brcm,nsp"; + +BCM58625 +compatible = "brcm,bcm58625", "brcm,nsp"; + +BCM88312 +compatible = "brcm,bcm88312", "brcm,nsp"; diff --git a/Documentation/devicetree/bindings/arm/coherency-fabric.txt b/Documentation/devicetree/bindings/arm/coherency-fabric.txt index 8dd46617c889..9b5c3f620e65 100644 --- a/Documentation/devicetree/bindings/arm/coherency-fabric.txt +++ b/Documentation/devicetree/bindings/arm/coherency-fabric.txt @@ -27,6 +27,11 @@ Required properties: * For "marvell,armada-380-coherency-fabric", only one pair is needed for the per-CPU fabric registers. +Optional properties: + +- broken-idle: boolean to set when the Idle mode is not supported by the + hardware. + Examples: coherency-fabric@d0020200 { diff --git a/Documentation/devicetree/bindings/arm/compulab-boards.txt b/Documentation/devicetree/bindings/arm/compulab-boards.txt new file mode 100644 index 000000000000..42a10285af9c --- /dev/null +++ b/Documentation/devicetree/bindings/arm/compulab-boards.txt @@ -0,0 +1,25 @@ +CompuLab SB-SOM is a multi-module baseboard capable of carrying: + - CM-T43 + - CM-T54 + - CM-QS600 + - CL-SOM-AM57x + - CL-SOM-iMX7 +modules with minor modifications to the SB-SOM assembly. + +Required root node properties: + - compatible = should be "compulab,sb-som" + +Compulab CL-SOM-iMX7 is a miniature System-on-Module (SoM) based on +Freescale i.MX7 ARM Cortex-A7 System-on-Chip. + +Required root node properties: + - compatible = "compulab,cl-som-imx7", "fsl,imx7d"; + +Compulab SBC-iMX7 is a single board computer based on the +Freescale i.MX7 system-on-chip. SBC-iMX7 is implemented with +the CL-SOM-iMX7 System-on-Module providing most of the functions, +and SB-SOM-iMX7 carrier board providing additional peripheral +functions and connectors. + +Required root node properties: + - compatible = "compulab,sbc-imx7", "compulab,cl-som-imx7", "fsl,imx7d"; diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index 91e6e5c478d0..afcf50f050ad 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -157,6 +157,7 @@ nodes to be present and contain the properties described below. "arm,cortex-a17" "arm,cortex-a53" "arm,cortex-a57" + "arm,cortex-a72" "arm,cortex-m0" "arm,cortex-m0+" "arm,cortex-m1" @@ -190,14 +191,19 @@ nodes to be present and contain the properties described below. "allwinner,sun6i-a31" "allwinner,sun8i-a23" "arm,psci" + "arm,realview-smp" + "brcm,bcm-nsp-smp" "brcm,brahma-b15" "marvell,armada-375-smp" "marvell,armada-380-smp" "marvell,armada-390-smp" "marvell,armada-xp-smp" + "mediatek,mt6589-smp" + "mediatek,mt81xx-tz-smp" "qcom,gcc-msm8660" "qcom,kpss-acc-v1" "qcom,kpss-acc-v2" + "rockchip,rk3036-smp" "rockchip,rk3066-smp" "ste,dbx500-smp" @@ -240,6 +246,23 @@ nodes to be present and contain the properties described below. Definition: Specifies the syscon node controlling the cpu core power domains. + - dynamic-power-coefficient + Usage: optional + Value type: <prop-encoded-array> + Definition: A u32 value that represents the running time dynamic + power coefficient in units of mW/MHz/uV^2. The + coefficient can either be calculated from power + measurements or derived by analysis. + + The dynamic power consumption of the CPU is + proportional to the square of the Voltage (V) and + the clock frequency (f). The coefficient is used to + calculate the dynamic power as below - + + Pdyn = dynamic-power-coefficient * V^2 * f + + where voltage is in uV, frequency is in MHz. + Example 1 (dual-cluster big.LITTLE system 32-bit): cpus { diff --git a/Documentation/devicetree/bindings/arm/fsl.txt b/Documentation/devicetree/bindings/arm/fsl.txt index 2a3ba73f0c5c..752a685d926f 100644 --- a/Documentation/devicetree/bindings/arm/fsl.txt +++ b/Documentation/devicetree/bindings/arm/fsl.txt @@ -128,10 +128,22 @@ Example: reg = <0x0 0x1ee0000 0x0 0x10000>; }; -Freescale LS2085A SoC Device Tree Bindings ------------------------------------------- +Freescale ARMv8 based Layerscape SoC family Device Tree Bindings +---------------------------------------------------------------- -LS2085A ARMv8 based Simulator model +LS1043A ARMv8 based RDB Board Required root node properties: - - compatible = "fsl,ls2085a-simu", "fsl,ls2085a"; + - compatible = "fsl,ls1043a-rdb", "fsl,ls1043a"; + +LS2080A ARMv8 based Simulator model +Required root node properties: + - compatible = "fsl,ls2080a-simu", "fsl,ls2080a"; + +LS2080A ARMv8 based QDS Board +Required root node properties: + - compatible = "fsl,ls2080a-qds", "fsl,ls2080a"; + +LS2080A ARMv8 based RDB Board +Required root node properties: + - compatible = "fsl,ls2080a-rdb", "fsl,ls2080a"; diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt index 953fb640d9c4..fd54e1db2156 100644 --- a/Documentation/devicetree/bindings/arm/fw-cfg.txt +++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt @@ -11,43 +11,9 @@ QEMU exposes the control and data register to ARM guests as memory mapped registers; their location is communicated to the guest's UEFI firmware in the DTB that QEMU places at the bottom of the guest's DRAM. -The guest writes a selector value (a key) to the selector register, and then -can read the corresponding data (produced by QEMU) via the data register. If -the selected entry is writable, the guest can rewrite it through the data -register. +The authoritative guest-side hardware interface documentation to the fw_cfg +device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree. -The selector register takes keys in big endian byte order. - -The data register allows accesses with 8, 16, 32 and 64-bit width (only at -offset 0 of the register). Accesses larger than a byte are interpreted as -arrays, bundled together only for better performance. The bytes constituting -such a word, in increasing address order, correspond to the bytes that would -have been transferred by byte-wide accesses in chronological order. - -The interface allows guest firmware to download various parameters and blobs -that affect how the firmware works and what tables it installs for the guest -OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and -initrd images for direct kernel booting, virtual machine UUID, SMP information, -virtual NUMA topology, and so on. - -The authoritative registry of the valid selector values and their meanings is -the QEMU source code; the structure of the data blobs corresponding to the -individual key values is also defined in the QEMU source code. - -The presence of the registers can be verified by selecting the "signature" blob -with key 0x0000, and reading four bytes from the data register. The returned -signature is "QEMU". - -The outermost protocol (involving the write / read sequences of the control and -data registers) is expected to be versioned, and/or described by feature bits. -The interface revision / feature bitmap can be retrieved with key 0x0001. The -blob to be read from the data register has size 4, and it is to be interpreted -as a uint32_t value in little endian byte order. The current value -(corresponding to the above outer protocol) is zero. - -The guest kernel is not expected to use these registers (although it is -certainly allowed to); the device tree bindings are documented here because -this is where device tree bindings reside in general. Required properties: diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index c733e28e18e5..e3ccab114006 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -20,6 +20,10 @@ HiKey Board Required root node properties: - compatible = "hisilicon,hi6220-hikey", "hisilicon,hi6220"; +HiP05 D02 Board +Required root node properties: + - compatible = "hisilicon,hip05-d02"; + Hisilicon system controller Required properties: @@ -167,6 +171,39 @@ Example: }; ----------------------------------------------------------------------- +Hisilicon HiP05 PCIe-SAS system controller + +Required properties: +- compatible : "hisilicon,pcie-sas-subctrl", "syscon"; +- reg : Register address and size + +The HiP05 PCIe-SAS system controller is shared by PCIe and SAS controllers in +HiP05 Soc to implement some basic configurations. + +Example: + /* for HiP05 PCIe-SAS system */ + pcie_sas: system_controller@0xb0000000 { + compatible = "hisilicon,pcie-sas-subctrl", "syscon"; + reg = <0xb0000000 0x10000>; + }; + +Hisilicon HiP05 PERISUB system controller + +Required properties: +- compatible : "hisilicon,hip05-perisubc", "syscon"; +- reg : Register address and size + +The HiP05 PERISUB system controller is shared by peripheral controllers in +HiP05 Soc to implement some basic configurations. The peripheral +controllers include mdio, ddr, iic, uart, timer and so on. + +Example: + /* for HiP05 perisub-ctrl-c system */ + peri_c_subctrl: syscon@80000000 { + compatible = "hisilicon,hip05-perisubc", "syscon"; + reg = <0x0 0x80000000 0x0 0x10000>; + }; +----------------------------------------------------------------------- Hisilicon CPU controller Required properties: diff --git a/Documentation/devicetree/bindings/arm/keystone/keystone.txt b/Documentation/devicetree/bindings/arm/keystone/keystone.txt index 59d7a46f85eb..3090a8a008c0 100644 --- a/Documentation/devicetree/bindings/arm/keystone/keystone.txt +++ b/Documentation/devicetree/bindings/arm/keystone/keystone.txt @@ -9,12 +9,26 @@ Required properties: the form "ti,keystone-*". Generic devices like gic, arch_timers, ns16550 type UART should use the specified compatible for those devices. +SoC families: + +- Keystone 2 generic SoC: + compatible = "ti,keystone" + +SoCs: + +- Keystone 2 Hawking/Kepler + compatible = "ti,k2hk", "ti,keystone" +- Keystone 2 Lamarr + compatible = "ti,k2l", "ti,keystone" +- Keystone 2 Edison + compatible = "ti,k2e", "ti,keystone" + Boards: - Keystone 2 Hawking/Kepler EVM - compatible = "ti,k2hk-evm","ti,keystone" + compatible = "ti,k2hk-evm", "ti,k2hk", "ti,keystone" - Keystone 2 Lamarr EVM - compatible = "ti,k2l-evm","ti,keystone" + compatible = "ti,k2l-evm", "ti, k2l", "ti,keystone" - Keystone 2 Edison EVM - compatible = "ti,k2e-evm","ti,keystone" + compatible = "ti,k2e-evm", "ti,k2e", "ti,keystone" diff --git a/Documentation/devicetree/bindings/arm/l2cc.txt b/Documentation/devicetree/bindings/arm/l2c2x0.txt index 06c88a4d28ac..fe0398c5c77b 100644 --- a/Documentation/devicetree/bindings/arm/l2cc.txt +++ b/Documentation/devicetree/bindings/arm/l2c2x0.txt @@ -1,7 +1,8 @@ * ARM L2 Cache Controller -ARM cores often have a separate level 2 cache controller. There are various -implementations of the L2 cache controller with compatible programming models. +ARM cores often have a separate L2C210/L2C220/L2C310 (also known as PL210/PL220/ +PL310 and variants) based level 2 cache controller. All these various implementations +of the L2 cache controller have compatible programming models (Note 1). Some of the properties that are just prefixed "cache-*" are taken from section 3.7.3 of the ePAPR v1.1 specification which can be found at: https://www.power.org/wp-content/uploads/2012/06/Power_ePAPR_APPROVED_v1.1.pdf @@ -67,12 +68,17 @@ Optional properties: disable if zero. - arm,prefetch-offset : Override prefetch offset value. Valid values are 0-7, 15, 23, and 31. -- arm,shared-override : The default behavior of the pl310 cache controller with - respect to the shareable attribute is to transform "normal memory - non-cacheable transactions" into "cacheable no allocate" (for reads) or - "write through no write allocate" (for writes). +- arm,shared-override : The default behavior of the L220 or PL310 cache + controllers with respect to the shareable attribute is to transform "normal + memory non-cacheable transactions" into "cacheable no allocate" (for reads) + or "write through no write allocate" (for writes). On systems where this may cause DMA buffer corruption, this property must be specified to indicate that such transforms are precluded. +- arm,parity-enable : enable parity checking on the L2 cache (L220 or PL310). +- arm,parity-disable : disable parity checking on the L2 cache (L220 or PL310). +- arm,outer-sync-disable : disable the outer sync operation on the L2 cache. + Some core tiles, especially ARM PB11MPCore have a faulty L220 cache that + will randomly hang unless outer sync operations are disabled. - prefetch-data : Data prefetch. Value: <0> (forcibly disable), <1> (forcibly enable), property absent (retain settings set by firmware) - prefetch-instr : Instruction prefetch. Value: <0> (forcibly disable), @@ -91,3 +97,9 @@ L2: cache-controller { cache-level = <2>; interrupts = <45>; }; + +Note 1: The description in this document doesn't apply to integrated L2 + cache controllers as found in e.g. Cortex-A15/A7/A57/A53. These + integrated L2 controllers are assumed to be all preconfigured by + early secure boot code. Thus no need to deal with their configuration + in the kernel at all. diff --git a/Documentation/devicetree/bindings/arm/marvell,kirkwood.txt b/Documentation/devicetree/bindings/arm/marvell,kirkwood.txt index 5171ad8f48ff..ab0c9cdf388e 100644 --- a/Documentation/devicetree/bindings/arm/marvell,kirkwood.txt +++ b/Documentation/devicetree/bindings/arm/marvell,kirkwood.txt @@ -24,6 +24,8 @@ board. Currently known boards are: "buffalo,lswxl" "buffalo,lsxhl" "buffalo,lsxl" +"cloudengines,pogo02" +"cloudengines,pogoplugv4" "dlink,dns-320" "dlink,dns-320-a1" "dlink,dns-325" diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt index 618a91994a18..54f43bc2df44 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ b/Documentation/devicetree/bindings/arm/mediatek.txt @@ -6,6 +6,7 @@ following property: Required root node property: compatible: Must contain one of + "mediatek,mt2701" "mediatek,mt6580" "mediatek,mt6589" "mediatek,mt6592" @@ -17,6 +18,9 @@ compatible: Must contain one of Supported boards: +- Evaluation board for MT2701: + Required root node properties: + - compatible = "mediatek,mt2701-evb", "mediatek,mt2701"; - Evaluation board for MT6580: Required root node properties: - compatible = "mediatek,mt6580-evbp1", "mediatek,mt6580"; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt new file mode 100644 index 000000000000..b1f2ce17dff8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt @@ -0,0 +1,22 @@ +Mediatek imgsys controller +============================ + +The Mediatek imgsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt8173-imgsys", "syscon" +- #clock-cells: Must be 1 + +The imgsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +imgsys: clock-controller@15000000 { + compatible = "mediatek,mt8173-imgsys", "syscon"; + reg = <0 0x15000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index f6cd3e4192ff..aaf8d1460c4d 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -18,7 +18,7 @@ The available clocks are defined in dt-bindings/clock/mt*-clk.h. Also it uses the common reset controller binding from Documentation/devicetree/bindings/reset/reset.txt. The available reset outputs are defined in -dt-bindings/reset-controller/mt*-resets.h +dt-bindings/reset/mt*-resets.h Example: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt new file mode 100644 index 000000000000..4385946eadef --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -0,0 +1,22 @@ +Mediatek mmsys controller +============================ + +The Mediatek mmsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt8173-mmsys", "syscon" +- #clock-cells: Must be 1 + +The mmsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +mmsys: clock-controller@14000000 { + compatible = "mediatek,mt8173-mmsys", "syscon"; + reg = <0 0x14000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt index f25b85499a6f..2f6ff86df49f 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt @@ -18,7 +18,7 @@ The available clocks are defined in dt-bindings/clock/mt*-clk.h. Also it uses the common reset controller binding from Documentation/devicetree/bindings/reset/reset.txt. The available reset outputs are defined in -dt-bindings/reset-controller/mt*-resets.h +dt-bindings/reset/mt*-resets.h Example: diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt new file mode 100644 index 000000000000..1faacf1c1b25 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt @@ -0,0 +1,22 @@ +Mediatek vdecsys controller +============================ + +The Mediatek vdecsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt8173-vdecsys", "syscon" +- #clock-cells: Must be 1 + +The vdecsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +vdecsys: clock-controller@16000000 { + compatible = "mediatek,mt8173-vdecsys", "syscon"; + reg = <0 0x16000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencltsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencltsys.txt new file mode 100644 index 000000000000..3cc299fd7857 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencltsys.txt @@ -0,0 +1,22 @@ +Mediatek vencltsys controller +============================ + +The Mediatek vencltsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt8173-vencltsys", "syscon" +- #clock-cells: Must be 1 + +The vencltsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +vencltsys: clock-controller@19000000 { + compatible = "mediatek,mt8173-vencltsys", "syscon"; + reg = <0 0x19000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt new file mode 100644 index 000000000000..5bb2866a2b50 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vencsys.txt @@ -0,0 +1,22 @@ +Mediatek vencsys controller +============================ + +The Mediatek vencsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt8173-vencsys", "syscon" +- #clock-cells: Must be 1 + +The vencsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +vencsys: clock-controller@18000000 { + compatible = "mediatek,mt8173-vencsys", "syscon"; + reg = <0 0x18000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mvebu-cpu-config.txt b/Documentation/devicetree/bindings/arm/mvebu-cpu-config.txt new file mode 100644 index 000000000000..2cdcd716da40 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mvebu-cpu-config.txt @@ -0,0 +1,20 @@ +MVEBU CPU Config registers +-------------------------- + +MVEBU (Marvell SOCs: Armada 370/XP) + +Required properties: + +- compatible: one of: + - "marvell,armada-370-cpu-config" + - "marvell,armada-xp-cpu-config" + +- reg: Should contain CPU config registers location and length, in + their per-CPU variant + +Example: + + cpu-config@21000 { + compatible = "marvell,armada-xp-cpu-config"; + reg = <0x21000 0x8>; + }; diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index 9f4e5136e568..66422d663184 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -23,6 +23,7 @@ Optional properties: during suspend. - ti,no-reset-on-init: When present, the module should not be reset at init - ti,no-idle-on-init: When present, the module should not be idled at init +- ti,no-idle: When present, the module is never allowed to idle. Example: @@ -138,9 +139,21 @@ Boards: - AM335X phyBOARD-WEGA: Single Board Computer dev kit compatible = "phytec,am335x-wega", "phytec,am335x-phycore-som", "ti,am33xx" +- AM335X CM-T335 : System On Module, built around the Sitara AM3352/4 + compatible = "compulab,cm-t335", "ti,am33xx" + +- AM335X SBC-T335 : single board computer, built around the Sitara AM3352/4 + compatible = "compulab,sbc-t335", "compulab,cm-t335", "ti,am33xx" + - OMAP5 EVM : Evaluation Module compatible = "ti,omap5-evm", "ti,omap5" +- AM437x CM-T43 + compatible = "compulab,am437x-cm-t43", "ti,am4372", "ti,am43" + +- AM437x SBC-T43 + compatible = "compulab,am437x-sbc-t43", "compulab,am437x-cm-t43", "ti,am4372", "ti,am43" + - AM43x EPOS EVM compatible = "ti,am43x-epos-evm", "ti,am4372", "ti,am43" @@ -150,6 +163,12 @@ Boards: - AM437x SK EVM: AM437x StarterKit Evaluation Module compatible = "ti,am437x-sk-evm", "ti,am4372", "ti,am43" +- AM57XX CL-SOM-AM57x + compatible = "compulab,cl-som-am57x", "ti,am5728", "ti,dra742", "ti,dra74", "ti,dra7" + +- AM57XX SBC-AM57x + compatible = "compulab,sbc-am57x", "compulab,cl-som-am57x", "ti,am5728", "ti,dra742", "ti,dra74", "ti,dra7" + - DRA742 EVM: Software Development Board for DRA742 compatible = "ti,dra7-evm", "ti,dra742", "ti,dra74", "ti,dra7" diff --git a/Documentation/devicetree/bindings/arm/pmu.txt b/Documentation/devicetree/bindings/arm/pmu.txt index 435251fa9ce0..56518839f52a 100644 --- a/Documentation/devicetree/bindings/arm/pmu.txt +++ b/Documentation/devicetree/bindings/arm/pmu.txt @@ -7,7 +7,11 @@ representation in the device tree should be done as under:- Required properties: - compatible : should be one of + "apm,potenza-pmu" "arm,armv8-pmuv3" + "arm,cortex-a72-pmu" + "arm,cortex-a57-pmu" + "arm,cortex-a53-pmu" "arm,cortex-a17-pmu" "arm,cortex-a15-pmu" "arm,cortex-a12-pmu" diff --git a/Documentation/devicetree/bindings/arm/psci.txt b/Documentation/devicetree/bindings/arm/psci.txt index 5aa40ede0e99..a2c4f1d52492 100644 --- a/Documentation/devicetree/bindings/arm/psci.txt +++ b/Documentation/devicetree/bindings/arm/psci.txt @@ -23,13 +23,20 @@ Main node required properties: - compatible : should contain at least one of: - * "arm,psci" : for implementations complying to PSCI versions prior to - 0.2. For these cases function IDs must be provided. + * "arm,psci" : For implementations complying to PSCI versions prior + to 0.2. + For these cases function IDs must be provided. - * "arm,psci-0.2" : for implementations complying to PSCI 0.2. Function - IDs are not required and should be ignored by an OS with PSCI 0.2 - support, but are permitted to be present for compatibility with - existing software when "arm,psci" is later in the compatible list. + * "arm,psci-0.2" : For implementations complying to PSCI 0.2. + Function IDs are not required and should be ignored by + an OS with PSCI 0.2 support, but are permitted to be + present for compatibility with existing software when + "arm,psci" is later in the compatible list. + + * "arm,psci-1.0" : For implementations complying to PSCI 1.0. + PSCI 1.0 is backward compatible with PSCI 0.2 with + minor specification updates, as defined in the PSCI + specification[2]. - method : The method of calling the PSCI firmware. Permitted values are: @@ -100,3 +107,5 @@ Case 3: PSCI v0.2 and PSCI v0.1. [1] Kernel documentation - ARM idle states bindings Documentation/devicetree/bindings/arm/idle-states.txt +[2] Power State Coordination Interface (PSCI) specification + http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf diff --git a/Documentation/devicetree/bindings/arm/rockchip.txt b/Documentation/devicetree/bindings/arm/rockchip.txt index af58cd74aeff..078c14fcdaaa 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.txt +++ b/Documentation/devicetree/bindings/arm/rockchip.txt @@ -1,6 +1,10 @@ Rockchip platforms device tree bindings --------------------------------------- +- Kylin RK3036 board: + Required root node properties: + - compatible = "rockchip,kylin-rk3036", "rockchip,rk3036"; + - MarsBoard RK3066 board: Required root node properties: - compatible = "haoyu,marsboard-rk3066", "rockchip,rk3066a"; @@ -17,6 +21,10 @@ Rockchip platforms device tree bindings Required root node properties: - compatible = "radxa,rock", "rockchip,rk3188"; +- Radxa Rock2 Square board: + Required root node properties: + - compatible = "radxa,rock2-square", "rockchip,rk3288"; + - Firefly Firefly-RK3288 board: Required root node properties: - compatible = "firefly,firefly-rk3288", "rockchip,rk3288"; @@ -31,6 +39,18 @@ Rockchip platforms device tree bindings Required root node properties: - compatible = "netxeon,r89", "rockchip,rk3288"; +- Google Brain (dev-board): + Required root node properties: + - compatible = "google,veyron-brain-rev0", "google,veyron-brain", + "google,veyron", "rockchip,rk3288"; + +- Google Jaq (Haier Chromebook 11 and more): + Required root node properties: + - compatible = "google,veyron-jaq-rev5", "google,veyron-jaq-rev4", + "google,veyron-jaq-rev3", "google,veyron-jaq-rev2", + "google,veyron-jaq-rev1", "google,veyron-jaq", + "google,veyron", "rockchip,rk3288"; + - Google Jerry (Hisense Chromebook C11 and more): Required root node properties: - compatible = "google,veyron-jerry-rev7", "google,veyron-jerry-rev6", @@ -38,6 +58,15 @@ Rockchip platforms device tree bindings "google,veyron-jerry-rev3", "google,veyron-jerry", "google,veyron", "rockchip,rk3288"; +- Google Mickey (Asus Chromebit CS10): + Required root node properties: + - compatible = "google,veyron-mickey-rev8", "google,veyron-mickey-rev7", + "google,veyron-mickey-rev6", "google,veyron-mickey-rev5", + "google,veyron-mickey-rev4", "google,veyron-mickey-rev3", + "google,veyron-mickey-rev2", "google,veyron-mickey-rev1", + "google,veyron-mickey-rev0", "google,veyron-mickey", + "google,veyron", "rockchip,rk3288"; + - Google Minnie (Asus Chromebook Flip C100P): Required root node properties: - compatible = "google,veyron-minnie-rev4", "google,veyron-minnie-rev3", @@ -58,6 +87,14 @@ Rockchip platforms device tree bindings "google,veyron-speedy-rev3", "google,veyron-speedy-rev2", "google,veyron-speedy", "google,veyron", "rockchip,rk3288"; +- Rockchip RK3368 evb: + Required root node properties: + - compatible = "rockchip,rk3368-evb-act8846", "rockchip,rk3368"; + - Rockchip R88 board: Required root node properties: - compatible = "rockchip,r88", "rockchip,rk3368"; + +- Rockchip RK3228 Evaluation board: + Required root node properties: + - compatible = "rockchip,rk3228-evb", "rockchip,rk3228"; diff --git a/Documentation/devicetree/bindings/arm/samsung-boards.txt b/Documentation/devicetree/bindings/arm/samsung-boards.txt deleted file mode 100644 index 43589d2466a7..000000000000 --- a/Documentation/devicetree/bindings/arm/samsung-boards.txt +++ /dev/null @@ -1,27 +0,0 @@ -* Samsung's Exynos SoC based boards - -Required root node properties: - - compatible = should be one or more of the following. - - "samsung,monk" - for Exynos3250-based Samsung Simband board. - - "samsung,rinato" - for Exynos3250-based Samsung Gear2 board. - - "samsung,smdkv310" - for Exynos4210-based Samsung SMDKV310 eval board. - - "samsung,trats" - for Exynos4210-based Tizen Reference board. - - "samsung,universal_c210" - for Exynos4210-based Samsung board. - - "samsung,smdk4412", - for Exynos4412-based Samsung SMDK4412 eval board. - - "samsung,trats2" - for Exynos4412-based Tizen Reference board. - - "samsung,smdk5250" - for Exynos5250-based Samsung SMDK5250 eval board. - - "samsung,xyref5260" - for Exynos5260-based Samsung board. - - "samsung,smdk5410" - for Exynos5410-based Samsung SMDK5410 eval board. - - "samsung,smdk5420" - for Exynos5420-based Samsung SMDK5420 eval board. - - "samsung,sd5v1" - for Exynos5440-based Samsung board. - - "samsung,ssdk5440" - for Exynos5440-based Samsung board. - -Optional: - - firmware node, specifying presence and type of secure firmware: - - compatible: only "samsung,secure-firmware" is currently supported - - reg: address of non-secure SYSRAM used for communication with firmware - - firmware@0203F000 { - compatible = "samsung,secure-firmware"; - reg = <0x0203F000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt index f46ca9a316a2..ccaaec6014bd 100644 --- a/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt +++ b/Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt @@ -47,6 +47,9 @@ Required properties: - samsung,syscon-phandle Contains the PMU system controller node (To access the ADC_PHY register on Exynos5250/5420/5800/3250) +Optional properties: +- has-touchscreen: If present, indicates that a touchscreen is + connected an usable. Note: child nodes can be added for auto probing from device tree. diff --git a/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt new file mode 100644 index 000000000000..12129c011c8f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/samsung/samsung-boards.txt @@ -0,0 +1,69 @@ +* Samsung's Exynos SoC based boards + +Required root node properties: + - compatible = should be one or more of the following. + - "samsung,monk" - for Exynos3250-based Samsung Simband board. + - "samsung,rinato" - for Exynos3250-based Samsung Gear2 board. + - "samsung,smdkv310" - for Exynos4210-based Samsung SMDKV310 eval board. + - "samsung,trats" - for Exynos4210-based Tizen Reference board. + - "samsung,universal_c210" - for Exynos4210-based Samsung board. + - "samsung,smdk4412", - for Exynos4412-based Samsung SMDK4412 eval board. + - "samsung,trats2" - for Exynos4412-based Tizen Reference board. + - "samsung,smdk5250" - for Exynos5250-based Samsung SMDK5250 eval board. + - "samsung,xyref5260" - for Exynos5260-based Samsung board. + - "samsung,smdk5410" - for Exynos5410-based Samsung SMDK5410 eval board. + - "samsung,smdk5420" - for Exynos5420-based Samsung SMDK5420 eval board. + - "samsung,sd5v1" - for Exynos5440-based Samsung board. + - "samsung,ssdk5440" - for Exynos5440-based Samsung board. + +* Other companies Exynos SoC based + * FriendlyARM + - "friendlyarm,tiny4412" - for Exynos4412-based FriendlyARM + TINY4412 board. + + * Google + - "google,pi" - for Exynos5800-based Google Peach Pi + Rev 10+ board, + also: "google,pi-rev16", "google,pi-rev15", "google,pi-rev14", + "google,pi-rev13", "google,pi-rev12", "google,pi-rev11", + "google,pi-rev10", "google,peach". + + - "google,pit" - for Exynos5420-based Google Peach Pit + Rev 6+ (Exynos5420), + also: "google,pit-rev16", "google,pit-rev15", "google,pit-rev14", + "google,pit-rev13", "google,pit-rev12", "google,pit-rev11", + "google,pit-rev10", "google,pit-rev9", "google,pit-rev8", + "google,pit-rev7", "google,pit-rev6", "google,peach". + + - "google,snow-rev4" - for Exynos5250-based Google Snow board, + also: "google,snow" + - "google,snow-rev5" - for Exynos5250-based Google Snow + Rev 5+ board. + - "google,spring" - for Exynos5250-based Google Spring board. + + * Hardkernel + - "hardkernel,odroid-u3" - for Exynos4412-based Hardkernel Odroid U3. + - "hardkernel,odroid-x" - for Exynos4412-based Hardkernel Odroid X. + - "hardkernel,odroid-x2" - for Exynos4412-based Hardkernel Odroid X2. + - "hardkernel,odroid-xu3" - for Exynos5422-based Hardkernel Odroid XU3. + - "hardkernel,odroid-xu3-lite" - for Exynos5422-based Hardkernel + Odroid XU3 Lite board. + - "hardkernel,odroid-xu4" - for Exynos5422-based Hardkernel Odroid XU4. + + * Insignal + - "insignal,arndale" - for Exynos5250-based Insignal Arndale board. + - "insignal,arndale-octa" - for Exynos5420-based Insignal Arndale + Octa board. + - "insignal,origen" - for Exynos4210-based Insignal Origen board. + - "insignal,origen4412 - for Exynos4412-based Insignal Origen board. + + +Optional nodes: + - firmware node, specifying presence and type of secure firmware: + - compatible: only "samsung,secure-firmware" is currently supported + - reg: address of non-secure SYSRAM used for communication with firmware + + firmware@0203F000 { + compatible = "samsung,secure-firmware"; + reg = <0x0203F000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/arm/scu.txt b/Documentation/devicetree/bindings/arm/scu.txt index c447680519bb..08a587875996 100644 --- a/Documentation/devicetree/bindings/arm/scu.txt +++ b/Documentation/devicetree/bindings/arm/scu.txt @@ -10,10 +10,13 @@ References: Revision r2p0 - Cortex-A5: see DDI0434B Cortex-A5 MPCore Technical Reference Manual Revision r0p1 +- ARM11 MPCore: see DDI0360F ARM 11 MPCore Processor Technical Reference + Manial Revision r2p0 - compatible : Should be: "arm,cortex-a9-scu" "arm,cortex-a5-scu" + "arm,arm11mp-scu" - reg : Specify the base address and the size of the SCU register window. diff --git a/Documentation/devicetree/bindings/arm/secure.txt b/Documentation/devicetree/bindings/arm/secure.txt new file mode 100644 index 000000000000..e31303fb233a --- /dev/null +++ b/Documentation/devicetree/bindings/arm/secure.txt @@ -0,0 +1,53 @@ +* ARM Secure world bindings + +ARM CPUs with TrustZone support have two distinct address spaces, +"Normal" and "Secure". Most devicetree consumers (including the Linux +kernel) are not TrustZone aware and run entirely in either the Normal +world or the Secure world. However some devicetree consumers are +TrustZone aware and need to be able to determine whether devices are +visible only in the Secure address space, only in the Normal address +space, or visible in both. (One example of that situation would be a +virtual machine which boots Secure firmware and wants to tell the +firmware about the layout of the machine via devicetree.) + +The general principle of the naming scheme for Secure world bindings +is that any property that needs a different value in the Secure world +can be supported by prefixing the property name with "secure-". So for +instance "secure-foo" would override "foo". For property names with +a vendor prefix, the Secure variant of "vendor,foo" would be +"vendor,secure-foo". If there is no "secure-" property then the Secure +world value is the same as specified for the Normal world by the +non-prefixed property. However, only the properties listed below may +validly have "secure-" versions; this list will be enlarged on a +case-by-case basis. + +Defining the bindings in this way means that a device tree which has +been annotated to indicate the presence of Secure-only devices can +still be processed unmodified by existing Non-secure software (and in +particular by the kernel). + +Note that it is still valid for bindings intended for purely Secure +world consumers (like kernels that run entirely in Secure) to simply +describe the view of Secure world using the standard bindings. These +secure- bindings only need to be used where both the Secure and Normal +world views need to be described in a single device tree. + +Valid Secure world properties: + +- secure-status : specifies whether the device is present and usable + in the secure world. The combination of this with "status" allows + the various possible combinations of device visibility to be + specified. If "secure-status" is not specified it defaults to the + same value as "status"; if "status" is not specified either then + both default to "okay". This means the following combinations are + possible: + + /* Neither specified: default to visible in both S and NS */ + secure-status = "okay"; /* visible in both */ + status = "okay"; /* visible in both */ + status = "okay"; secure-status = "okay"; /* visible in both */ + secure-status = "disabled"; /* NS-only */ + status = "okay"; secure-status = "disabled"; /* NS-only */ + status = "disabled"; secure-status = "okay"; /* S-only */ + status = "disabled"; /* disabled in both */ + status = "disabled"; secure-status = "disabled"; /* disabled in both */ diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index c4f19b2e7dd9..9cf67e48f222 100644 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -27,6 +27,8 @@ SoCs: compatible = "renesas,r8a7793" - R-Car E2 (R8A77940) compatible = "renesas,r8a7794" + - R-Car H3 (R8A77950) + compatible = "renesas,r8a7795" Boards: @@ -39,8 +41,6 @@ Boards: compatible = "renesas,armadillo800eva" - BOCK-W compatible = "renesas,bockw", "renesas,r8a7778" - - BOCK-W - Reference Device Tree Implementation - compatible = "renesas,bockw-reference", "renesas,r8a7778" - Genmai (RTK772100BC00000BR) compatible = "renesas,genmai", "renesas,r7s72100" - Gose @@ -57,7 +57,9 @@ Boards: compatible = "renesas,lager", "renesas,r8a7790" - Marzen compatible = "renesas,marzen", "renesas,r8a7779" - -Note: Reference Device Tree Implementations are temporary implementations - to ease the migration from platform devices to Device Tree, and are - intended to be removed in the future. + - Porter (M2-LCDP) + compatible = "renesas,porter", "renesas,r8a7791" + - Salvator-X (RTP0RC7795SIPB0010S) + compatible = "renesas,salvator-x", "renesas,r8a7795"; + - SILK (RTP0RC7794LCB00011S) + compatible = "renesas,silk", "renesas,r8a7794" diff --git a/Documentation/devicetree/bindings/arm/sunxi.txt b/Documentation/devicetree/bindings/arm/sunxi.txt index 67da20539540..bb9b0faa919d 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.txt +++ b/Documentation/devicetree/bindings/arm/sunxi.txt @@ -6,6 +6,7 @@ using one of the following compatible strings: allwinner,sun4i-a10 allwinner,sun5i-a10s allwinner,sun5i-a13 + allwinner,sun5i-r8 allwinner,sun6i-a31 allwinner,sun7i-a20 allwinner,sun8i-a23 diff --git a/Documentation/devicetree/bindings/arm/technologic.txt b/Documentation/devicetree/bindings/arm/technologic.txt new file mode 100644 index 000000000000..842298894cf0 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/technologic.txt @@ -0,0 +1,6 @@ +Technologic Systems Platforms Device Tree Bindings +-------------------------------------------------- + +TS-4800 board +Required root node properties: + - compatible = "technologic,imx51-ts4800", "fsl,imx51"; diff --git a/Documentation/devicetree/bindings/nvec/nvidia,nvec.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,nvec.txt index 5ae601e7f51f..5ae601e7f51f 100644 --- a/Documentation/devicetree/bindings/nvec/nvidia,nvec.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,nvec.txt diff --git a/Documentation/devicetree/bindings/arm/twd.txt b/Documentation/devicetree/bindings/arm/twd.txt index 75b8610939fa..383ea19c2bf0 100644 --- a/Documentation/devicetree/bindings/arm/twd.txt +++ b/Documentation/devicetree/bindings/arm/twd.txt @@ -19,6 +19,11 @@ interrupts. - reg : Specify the base address and the size of the TWD timer register window. +Optional + +- always-on : a boolean property. If present, the timer is powered through + an always-on power domain, therefore it never loses context. + Example: twd-timer@2c000600 { diff --git a/Documentation/devicetree/bindings/arm/uniphier/cache-uniphier.txt b/Documentation/devicetree/bindings/arm/uniphier/cache-uniphier.txt new file mode 100644 index 000000000000..d27a646f48a9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/uniphier/cache-uniphier.txt @@ -0,0 +1,60 @@ +UniPhier outer cache controller + +UniPhier SoCs are integrated with a full-custom outer cache controller system. +All of them have a level 2 cache controller, and some have a level 3 cache +controller as well. + +Required properties: +- compatible: should be "socionext,uniphier-system-cache" +- reg: offsets and lengths of the register sets for the device. It should + contain 3 regions: control register, revision register, operation register, + in this order. +- cache-unified: specifies the cache is a unified cache. +- cache-size: specifies the size in bytes of the cache +- cache-sets: specifies the number of associativity sets of the cache +- cache-line-size: specifies the line size in bytes +- cache-level: specifies the level in the cache hierarchy. The value should + be 2 for L2 cache, 3 for L3 cache, etc. + +Optional properties: +- next-level-cache: phandle to the next level cache if present. The next level + cache should be also compatible with "socionext,uniphier-system-cache". + +The L2 cache must exist to use the L3 cache; the cache hierarchy must be +indicated correctly with "next-level-cache" properties. + +Example 1 (system with L2): + l2: l2-cache@500c0000 { + compatible = "socionext,uniphier-system-cache"; + reg = <0x500c0000 0x2000>, <0x503c0100 0x4>, + <0x506c0000 0x400>; + cache-unified; + cache-size = <0x80000>; + cache-sets = <256>; + cache-line-size = <128>; + cache-level = <2>; + }; + +Example 2 (system with L2 and L3): + l2: l2-cache@500c0000 { + compatible = "socionext,uniphier-system-cache"; + reg = <0x500c0000 0x2000>, <0x503c0100 0x8>, + <0x506c0000 0x400>; + cache-unified; + cache-size = <0x200000>; + cache-sets = <512>; + cache-line-size = <128>; + cache-level = <2>; + next-level-cache = <&l3>; + }; + + l3: l3-cache@500c8000 { + compatible = "socionext,uniphier-system-cache"; + reg = <0x500c8000 0x2000>, <0x503c8100 0x8>, + <0x506c8000 0x400>; + cache-unified; + cache-size = <0x400000>; + cache-sets = <512>; + cache-line-size = <256>; + cache-level = <3>; + }; diff --git a/Documentation/devicetree/bindings/ata/ahci-fsl-qoriq.txt b/Documentation/devicetree/bindings/ata/ahci-fsl-qoriq.txt new file mode 100644 index 000000000000..032a7606b862 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/ahci-fsl-qoriq.txt @@ -0,0 +1,21 @@ +Binding for Freescale QorIQ AHCI SATA Controller + +Required properties: + - reg: Physical base address and size of the controller's register area. + - compatible: Compatibility string. Must be 'fsl,<chip>-ahci', where + chip could be ls1021a, ls2080a, ls1043a etc. + - clocks: Input clock specifier. Refer to common clock bindings. + - interrupts: Interrupt specifier. Refer to interrupt binding. + +Optional properties: + - dma-coherent: Enable AHCI coherent DMA operation. + - reg-names: register area names when there are more than 1 register area. + +Examples: + sata@3200000 { + compatible = "fsl,ls1021a-ahci"; + reg = <0x0 0x3200000 0x0 0x10000>; + interrupts = <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&platform_clk 1>; + dma-coherent; + }; diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt index a2321819e7f5..3d84dcae8475 100644 --- a/Documentation/devicetree/bindings/ata/ahci-platform.txt +++ b/Documentation/devicetree/bindings/ata/ahci-platform.txt @@ -11,13 +11,12 @@ Required properties: - compatible : compatible string, one of: - "allwinner,sun4i-a10-ahci" - "hisilicon,hisi-ahci" + - "cavium,octeon-7130-ahci" - "ibm,476gtr-ahci" - "marvell,armada-380-ahci" - "snps,dwc-ahci" - "snps,exynos5440-ahci" - "snps,spear-ahci" - - "fsl,qoriq-ahci" : for qoriq series socs which include ls1021, ls2085, etc. - - "fsl,<chip>-ahci" : chip could be ls1021, ls2085 etc. - "generic-ahci" - interrupts : <interrupt mapping for SATA IRQ> - reg : <registers mapping> diff --git a/Documentation/devicetree/bindings/ata/brcm,sata-brcmstb.txt b/Documentation/devicetree/bindings/ata/brcm,sata-brcmstb.txt index 20ac9bbfa1fd..60872838f1ad 100644 --- a/Documentation/devicetree/bindings/ata/brcm,sata-brcmstb.txt +++ b/Documentation/devicetree/bindings/ata/brcm,sata-brcmstb.txt @@ -4,7 +4,9 @@ SATA nodes are defined to describe on-chip Serial ATA controllers. Each SATA controller should have its own node. Required properties: -- compatible : compatible list, may contain "brcm,bcm7445-ahci" and/or +- compatible : should be one or more of + "brcm,bcm7425-ahci" + "brcm,bcm7445-ahci" "brcm,sata3-ahci" - reg : register mappings for AHCI and SATA_TOP_CTRL - reg-names : "ahci" and "top-ctrl" diff --git a/Documentation/devicetree/bindings/ata/sata_rcar.txt b/Documentation/devicetree/bindings/ata/sata_rcar.txt index 2493a5a31655..0764f9ab63dc 100644 --- a/Documentation/devicetree/bindings/ata/sata_rcar.txt +++ b/Documentation/devicetree/bindings/ata/sata_rcar.txt @@ -8,6 +8,7 @@ Required properties: - "renesas,sata-r8a7790" for R-Car H2 other than ES1 - "renesas,sata-r8a7791" for R-Car M2-W - "renesas,sata-r8a7793" for R-Car M2-N + - "renesas,sata-r8a7795" for R-Car H3 - reg : address and length of the SATA registers; - interrupts : must consist of one interrupt specifier. - clocks : must contain a reference to the functional clock. diff --git a/Documentation/devicetree/bindings/powerpc/fsl/board.txt b/Documentation/devicetree/bindings/board/fsl-board.txt index cff38bdbc0e4..fb7b03ec2071 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/board.txt +++ b/Documentation/devicetree/bindings/board/fsl-board.txt @@ -21,11 +21,14 @@ Example: This is the memory-mapped registers for on board FPGA. -Required properities: +Required properties: - compatible: should be a board-specific string followed by a string indicating the type of FPGA. Example: - "fsl,<board>-fpga", "fsl,fpga-pixis" + "fsl,<board>-fpga", "fsl,fpga-pixis", or + "fsl,<board>-fpga", "fsl,fpga-qixis" - reg: should contain the address and the length of the FPGA register set. + +Optional properties: - interrupt-parent: should specify phandle for the interrupt controller. - interrupts: should specify event (wakeup) IRQ. @@ -38,6 +41,13 @@ Example (P1022DS): interrupts = <8 8 0 0>; }; +Example (LS2080A-RDB): + + cpld@3,0 { + compatible = "fsl,ls2080ardb-fpga", "fsl,fpga-qixis"; + reg = <0x3 0 0x10000>; + }; + * Freescale BCSR GPIO banks Some BCSR registers act as simple GPIO controllers, each such diff --git a/Documentation/devicetree/bindings/bus/sunxi-rsb.txt b/Documentation/devicetree/bindings/bus/sunxi-rsb.txt new file mode 100644 index 000000000000..3dd28343b6ce --- /dev/null +++ b/Documentation/devicetree/bindings/bus/sunxi-rsb.txt @@ -0,0 +1,47 @@ +Allwinner Reduced Serial Bus (RSB) controller + +The RSB controller found on later Allwinner SoCs is an SMBus like 2 wire +serial bus with 1 master and up to 15 slaves. It is represented by a node +for the controller itself, and child nodes representing the slave devices. + +Required properties : + + - reg : Offset and length of the register set for the controller. + - compatible : Shall be "allwinner,sun8i-a23-rsb". + - interrupts : The interrupt line associated to the RSB controller. + - clocks : The gate clk associated to the RSB controller. + - resets : The reset line associated to the RSB controller. + - #address-cells : shall be 1 + - #size-cells : shall be 0 + +Optional properties : + + - clock-frequency : Desired RSB bus clock frequency in Hz. Maximum is 20MHz. + If not set this defaults to 3MHz. + +Child nodes: + +An RSB controller node can contain zero or more child nodes representing +slave devices on the bus. Child 'reg' properties should contain the slave +device's hardware address. The hardware address is hardwired in the device, +which can normally be found in the datasheet. + +Example: + + rsb@01f03400 { + compatible = "allwinner,sun8i-a23-rsb"; + reg = <0x01f03400 0x400>; + interrupts = <0 39 4>; + clocks = <&apb0_gates 3>; + clock-frequency = <3000000>; + resets = <&apb0_rst 3>; + #address-cells = <1>; + #size-cells = <0>; + + pmic@3e3 { + compatible = "..."; + reg = <0x3e3>; + + /* ... */ + }; + }; diff --git a/Documentation/devicetree/bindings/bus/uniphier-system-bus.txt b/Documentation/devicetree/bindings/bus/uniphier-system-bus.txt new file mode 100644 index 000000000000..68ef80afff16 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/uniphier-system-bus.txt @@ -0,0 +1,66 @@ +UniPhier System Bus + +The UniPhier System Bus is an external bus that connects on-board devices to +the UniPhier SoC. It is a simple (semi-)parallel bus with address, data, and +some control signals. It supports up to 8 banks (chip selects). + +Before any access to the bus, the bus controller must be configured; the bus +controller registers provide the control for the translation from the offset +within each bank to the CPU-viewed address. The needed setup includes the base +address, the size of each bank. Optionally, some timing parameters can be +optimized for faster bus access. + +Required properties: +- compatible: should be "socionext,uniphier-system-bus". +- reg: offset and length of the register set for the bus controller device. +- #address-cells: should be 2. The first cell is the bank number (chip select). + The second cell is the address offset within the bank. +- #size-cells: should be 1. +- ranges: should provide a proper address translation from the System Bus to + the parent bus. + +Note: +The address region(s) that can be assigned for the System Bus is implementation +defined. Some SoCs can use 0x00000000-0x0fffffff and 0x40000000-0x4fffffff, +while other SoCs can only use 0x40000000-0x4fffffff. There might be additional +limitations depending on SoCs and the boot mode. The address translation is +arbitrary as long as the banks are assigned in the supported address space with +the required alignment and they do not overlap one another. +For example, it is possible to map: + bank 0 to 0x42000000-0x43ffffff, bank 5 to 0x46000000-0x46ffffff +It is also possible to map: + bank 0 to 0x48000000-0x49ffffff, bank 5 to 0x44000000-0x44ffffff +There is no reason to stick to a particular translation mapping, but the +"ranges" property should provide a "reasonable" default that is known to work. +The software should initialize the bus controller according to it. + +Example: + + system-bus { + compatible = "socionext,uniphier-system-bus"; + reg = <0x58c00000 0x400>; + #address-cells = <2>; + #size-cells = <1>; + ranges = <1 0x00000000 0x42000000 0x02000000 + 5 0x00000000 0x46000000 0x01000000>; + + ethernet@1,01f00000 { + compatible = "smsc,lan9115"; + reg = <1 0x01f00000 0x1000>; + interrupts = <0 48 4> + phy-mode = "mii"; + }; + + uart@5,00200000 { + compatible = "ns16550a"; + reg = <5 0x00200000 0x20>; + interrupts = <0 49 4> + clock-frequency = <12288000>; + }; + }; + +In this example, + - the Ethernet device is connected at the offset 0x01f00000 of CS1 and + mapped to 0x43f00000 of the parent bus. + - the UART device is connected at the offset 0x00200000 of CS5 and + mapped to 0x46200000 of the parent bus. diff --git a/Documentation/devicetree/bindings/chosen.txt b/Documentation/devicetree/bindings/chosen.txt index ed838f453f7a..6ae9d82d4c37 100644 --- a/Documentation/devicetree/bindings/chosen.txt +++ b/Documentation/devicetree/bindings/chosen.txt @@ -44,3 +44,11 @@ Implementation note: Linux will look for the property "linux,stdout-path" or on PowerPC "stdout" if "stdout-path" is not found. However, the "linux,stdout-path" and "stdout" properties are deprecated. New platforms should only use the "stdout-path" property. + +linux,booted-from-kexec +----------------------- + +This property is set (currently only on PowerPC, and only needed on +book3e) by some versions of kexec-tools to tell the new kernel that it +is being booted by kexec, as the booting environment may differ (e.g. +a different secondary CPU release mechanism) diff --git a/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt b/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt new file mode 100644 index 000000000000..8b7177cecb36 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt @@ -0,0 +1,40 @@ +ARM System Controller ICST clocks + +The ICS525 and ICS307 oscillators are produced by Integrated Devices +Technology (IDT). ARM integrated these oscillators deeply into their +reference designs by adding special control registers that manage such +oscillators to their system controllers. + +The ARM system controller contains logic to serialize and initialize +an ICST clock request after a write to the 32 bit register at an offset +into the system controller. Furthermore, to even be able to alter one of +these frequencies, the system controller must first be unlocked by +writing a special token to another offset in the system controller. + +The ICST oscillator must be provided inside a system controller node. + +Required properties: +- lock-offset: the offset address into the system controller where the + unlocking register is located +- vco-offset: the offset address into the system controller where the + ICST control register is located (even 32 bit address) +- compatible: must be one of "arm,syscon-icst525" or "arm,syscon-icst307" +- #clock-cells: must be <0> +- clocks: parent clock, since the ICST needs a parent clock to derive its + frequency from, this attribute is compulsory. + +Example: + +syscon: syscon@10000000 { + compatible = "syscon"; + reg = <0x10000000 0x1000>; + + oscclk0: osc0@0c { + compatible = "arm,syscon-icst307"; + #clock-cells = <0>; + lock-offset = <0x20>; + vco-offset = <0x0c>; + clocks = <&xtal24mhz>; + }; + (...) +}; diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt b/Documentation/devicetree/bindings/clock/at91-clock.txt index 5ba6450693b9..181bc8ac4e3a 100644 --- a/Documentation/devicetree/bindings/clock/at91-clock.txt +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt @@ -77,6 +77,9 @@ Required properties: "atmel,sama5d4-clk-h32mx": at91 h32mx clock + "atmel,sama5d2-clk-generated": + at91 generated clock + Required properties for SCKC node: - reg : defines the IO memory reserved for the SCKC. - #size-cells : shall be 0 (reg is used to encode clk id). @@ -461,3 +464,35 @@ For example: compatible = "atmel,sama5d4-clk-h32mx"; clocks = <&mck>; }; + +Required properties for generated clocks: +- #size-cells : shall be 0 (reg is used to encode clk id). +- #address-cells : shall be 1 (reg is used to encode clk id). +- clocks : shall be the generated clock source phandles. + e.g. clocks = <&clk32k>, <&main>, <&plladiv>, <&utmi>, <&mck>, <&audio_pll_pmc>; +- name: device tree node describing a specific generated clock. + * #clock-cells : from common clock binding; shall be set to 0. + * reg: peripheral id. See Atmel's datasheets to get a full + list of peripheral ids. + * atmel,clk-output-range : minimum and maximum clock frequency + (two u32 fields). + +For example: + gck { + compatible = "atmel,sama5d2-clk-generated"; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&clk32k>, <&main>, <&plladiv>, <&utmi>, <&mck>, <&audio_pll_pmc>; + + tcb0_gclk: tcb0_gclk { + #clock-cells = <0>; + reg = <35>; + atmel,clk-output-range = <0 83000000>; + }; + + pwm_gclk: pwm_gclk { + #clock-cells = <0>; + reg = <38>; + atmel,clk-output-range = <0 83000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt b/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt new file mode 100644 index 000000000000..7a837d2182ac --- /dev/null +++ b/Documentation/devicetree/bindings/clock/brcm,bcm2835-aux-clock.txt @@ -0,0 +1,31 @@ +Broadcom BCM2835 auxiliary peripheral support + +This binding uses the common clock binding: + Documentation/devicetree/bindings/clock/clock-bindings.txt + +The auxiliary peripherals (UART, SPI1, and SPI2) have a small register +area controlling clock gating to the peripherals, and providing an IRQ +status register. + +Required properties: +- compatible: Should be "brcm,bcm2835-aux" +- #clock-cells: Should be <1>. The permitted clock-specifier values can be + found in include/dt-bindings/clock/bcm2835-aux.h +- reg: Specifies base physical address and size of the registers +- clocks: The parent clock phandle + +Example: + + clocks: cprman@7e101000 { + compatible = "brcm,bcm2835-cprman"; + #clock-cells = <1>; + reg = <0x7e101000 0x2000>; + clocks = <&clk_osc>; + }; + + aux: aux@0x7e215004 { + compatible = "brcm,bcm2835-aux"; + #clock-cells = <1>; + reg = <0x7e215000 0x8>; + clocks = <&clocks BCM2835_CLOCK_VPU>; + }; diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt b/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt new file mode 100644 index 000000000000..e56a1df3a9d3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt @@ -0,0 +1,45 @@ +Broadcom BCM2835 CPRMAN clocks + +This binding uses the common clock binding: + Documentation/devicetree/bindings/clock/clock-bindings.txt + +The CPRMAN clock controller generates clocks in the audio power domain +of the BCM2835. There is a level of PLLs deriving from an external +oscillator, a level of PLL dividers that produce channels off of the +few PLLs, and a level of mostly-generic clock generators sourcing from +the PLL channels. Most other hardware components source from the +clock generators, but a few (like the ARM or HDMI) will source from +the PLL dividers directly. + +Required properties: +- compatible: Should be "brcm,bcm2835-cprman" +- #clock-cells: Should be <1>. The permitted clock-specifier values can be + found in include/dt-bindings/clock/bcm2835.h +- reg: Specifies base physical address and size of the registers +- clocks: The external oscillator clock phandle + +Example: + + clk_osc: clock@3 { + compatible = "fixed-clock"; + reg = <3>; + #clock-cells = <0>; + clock-output-names = "osc"; + clock-frequency = <19200000>; + }; + + clocks: cprman@7e101000 { + compatible = "brcm,bcm2835-cprman"; + #clock-cells = <1>; + reg = <0x7e101000 0x2000>; + clocks = <&clk_osc>; + }; + + i2c0: i2c@7e205000 { + compatible = "brcm,bcm2835-i2c"; + reg = <0x7e205000 0x1000>; + interrupts = <2 21>; + clocks = <&clocks BCM2835_CLOCK_VPU>; + #address-cells = <1>; + #size-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.txt b/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.txt index da8d9bb5751c..0b35e71b39e8 100644 --- a/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.txt +++ b/Documentation/devicetree/bindings/clock/brcm,iproc-clocks.txt @@ -130,3 +130,86 @@ These clock IDs are defined in: ch3_unused mipipll 4 BCM_CYGNUS_MIPIPLL_CH3_UNUSED ch4_unused mipipll 5 BCM_CYGNUS_MIPIPLL_CH4_UNUSED ch5_unused mipipll 6 BCM_CYGNUS_MIPIPLL_CH5_UNUSED + +Northstar and Northstar Plus +------ +PLL and leaf clock compatible strings for Northstar and Northstar Plus are: + "brcm,nsp-armpll" + "brcm,nsp-genpll" + "brcm,nsp-lcpll0" + +The following table defines the set of PLL/clock index and ID for Northstar and +Northstar Plus. These clock IDs are defined in: + "include/dt-bindings/clock/bcm-nsp.h" + + Clock Source Index ID + --- ----- ----- --------- + crystal N/A N/A N/A + + armpll crystal N/A N/A + + genpll crystal 0 BCM_NSP_GENPLL + phy genpll 1 BCM_NSP_GENPLL_PHY_CLK + ethernetclk genpll 2 BCM_NSP_GENPLL_ENET_SW_CLK + usbclk genpll 3 BCM_NSP_GENPLL_USB_PHY_REF_CLK + iprocfast genpll 4 BCM_NSP_GENPLL_IPROCFAST_CLK + sata1 genpll 5 BCM_NSP_GENPLL_SATA1_CLK + sata2 genpll 6 BCM_NSP_GENPLL_SATA2_CLK + + lcpll0 crystal 0 BCM_NSP_LCPLL0 + pcie_phy lcpll0 1 BCM_NSP_LCPLL0_PCIE_PHY_REF_CLK + sdio lcpll0 2 BCM_NSP_LCPLL0_SDIO_CLK + ddr_phy lcpll0 3 BCM_NSP_LCPLL0_DDR_PHY_CLK + +Northstar 2 +----------- +PLL and leaf clock compatible strings for Northstar 2 are: + "brcm,ns2-genpll-scr" + "brcm,ns2-genpll-sw" + "brcm,ns2-lcpll-ddr" + "brcm,ns2-lcpll-ports" + +The following table defines the set of PLL/clock index and ID for Northstar 2. +These clock IDs are defined in: + "include/dt-bindings/clock/bcm-ns2.h" + + Clock Source Index ID + --- ----- ----- --------- + crystal N/A N/A N/A + + genpll_scr crystal 0 BCM_NS2_GENPLL_SCR + scr genpll_scr 1 BCM_NS2_GENPLL_SCR_SCR_CLK + fs genpll_scr 2 BCM_NS2_GENPLL_SCR_FS_CLK + audio_ref genpll_scr 3 BCM_NS2_GENPLL_SCR_AUDIO_CLK + ch3_unused genpll_scr 4 BCM_NS2_GENPLL_SCR_CH3_UNUSED + ch4_unused genpll_scr 5 BCM_NS2_GENPLL_SCR_CH4_UNUSED + ch5_unused genpll_scr 6 BCM_NS2_GENPLL_SCR_CH5_UNUSED + + genpll_sw crystal 0 BCM_NS2_GENPLL_SW + rpe genpll_sw 1 BCM_NS2_GENPLL_SW_RPE_CLK + 250 genpll_sw 2 BCM_NS2_GENPLL_SW_250_CLK + nic genpll_sw 3 BCM_NS2_GENPLL_SW_NIC_CLK + chimp genpll_sw 4 BCM_NS2_GENPLL_SW_CHIMP_CLK + port genpll_sw 5 BCM_NS2_GENPLL_SW_PORT_CLK + sdio genpll_sw 6 BCM_NS2_GENPLL_SW_SDIO_CLK + + lcpll_ddr crystal 0 BCM_NS2_LCPLL_DDR + pcie_sata_usb lcpll_ddr 1 BCM_NS2_LCPLL_DDR_PCIE_SATA_USB_CLK + ddr lcpll_ddr 2 BCM_NS2_LCPLL_DDR_DDR_CLK + ch2_unused lcpll_ddr 3 BCM_NS2_LCPLL_DDR_CH2_UNUSED + ch3_unused lcpll_ddr 4 BCM_NS2_LCPLL_DDR_CH3_UNUSED + ch4_unused lcpll_ddr 5 BCM_NS2_LCPLL_DDR_CH4_UNUSED + ch5_unused lcpll_ddr 6 BCM_NS2_LCPLL_DDR_CH5_UNUSED + + lcpll_ports crystal 0 BCM_NS2_LCPLL_PORTS + wan lcpll_ports 1 BCM_NS2_LCPLL_PORTS_WAN_CLK + rgmii lcpll_ports 2 BCM_NS2_LCPLL_PORTS_RGMII_CLK + ch2_unused lcpll_ports 3 BCM_NS2_LCPLL_PORTS_CH2_UNUSED + ch3_unused lcpll_ports 4 BCM_NS2_LCPLL_PORTS_CH3_UNUSED + ch4_unused lcpll_ports 5 BCM_NS2_LCPLL_PORTS_CH4_UNUSED + ch5_unused lcpll_ports 6 BCM_NS2_LCPLL_PORTS_CH5_UNUSED + +BCM63138 +-------- +PLL and leaf clock compatible strings for BCM63138 are: + "brcm,bcm63138-armpll" diff --git a/Documentation/devicetree/bindings/clock/cs2000-cp.txt b/Documentation/devicetree/bindings/clock/cs2000-cp.txt new file mode 100644 index 000000000000..54e6df0bee8a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/cs2000-cp.txt @@ -0,0 +1,22 @@ +CIRRUS LOGIC Fractional-N Clock Synthesizer & Clock Multiplier + +Required properties: + +- compatible: "cirrus,cs2000-cp" +- reg: The chip select number on the I2C bus +- clocks: common clock binding for CLK_IN, XTI/REF_CLK +- clock-names: CLK_IN : clk_in, XTI/REF_CLK : ref_clk +- #clock-cells: must be <0> + +Example: + +&i2c2 { + ... + cs2000: clk_multiplier@4f { + #clock-cells = <0>; + compatible = "cirrus,cs2000-cp"; + reg = <0x4f>; + clocks = <&rcar_sound 0>, <&x12_clk>; + clock-names = "clk_in", "ref_clk"; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/dove-divider-clock.txt b/Documentation/devicetree/bindings/clock/dove-divider-clock.txt new file mode 100644 index 000000000000..e3eb0f657c5e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/dove-divider-clock.txt @@ -0,0 +1,28 @@ +PLL divider based Dove clocks + +Marvell Dove has a 2GHz PLL, which feeds into a set of dividers to provide +high speed clocks for a number of peripherals. These dividers are part of +the PMU, and thus this node should be a child of the PMU node. + +The following clocks are provided: + +ID Clock +------------- +0 AXI bus clock +1 GPU clock +2 VMeta clock +3 LCD clock + +Required properties: +- compatible : shall be "marvell,dove-divider-clock" +- reg : shall be the register address of the Core PLL and Clock Divider + Control 0 register. This will cover that register, as well as the + Core PLL and Clock Divider Control 1 register. Thus, it will have + a size of 8. +- #clock-cells : from common clock binding; shall be set to 1 + +divider_clk: core-clock@0064 { + compatible = "marvell,dove-divider-clock"; + reg = <0x0064 0x8>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra210-car.txt b/Documentation/devicetree/bindings/clock/nvidia,tegra210-car.txt new file mode 100644 index 000000000000..26f237f641b7 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra210-car.txt @@ -0,0 +1,56 @@ +NVIDIA Tegra210 Clock And Reset Controller + +This binding uses the common clock binding: +Documentation/devicetree/bindings/clock/clock-bindings.txt + +The CAR (Clock And Reset) Controller on Tegra is the HW module responsible +for muxing and gating Tegra's clocks, and setting their rates. + +Required properties : +- compatible : Should be "nvidia,tegra210-car" +- reg : Should contain CAR registers location and length +- clocks : Should contain phandle and clock specifiers for two clocks: + the 32 KHz "32k_in". +- #clock-cells : Should be 1. + In clock consumers, this cell represents the clock ID exposed by the + CAR. The assignments may be found in header file + <dt-bindings/clock/tegra210-car.h>. +- #reset-cells : Should be 1. + In clock consumers, this cell represents the bit number in the CAR's + array of CLK_RST_CONTROLLER_RST_DEVICES_* registers. + +Example SoC include file: + +/ { + tegra_car: clock { + compatible = "nvidia,tegra210-car"; + reg = <0x60006000 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + + usb@c5004000 { + clocks = <&tegra_car TEGRA210_CLK_USB2>; + }; +}; + +Example board file: + +/ { + clocks { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <0>; + + clk_32k: clock@1 { + compatible = "fixed-clock"; + reg = <1>; + #clock-cells = <0>; + clock-frequency = <32768>; + }; + }; + + &tegra_car { + clocks = <&clk_32k>; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/nxp,lpc3220-clk.txt b/Documentation/devicetree/bindings/clock/nxp,lpc3220-clk.txt new file mode 100644 index 000000000000..20cbca3f41d8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/nxp,lpc3220-clk.txt @@ -0,0 +1,30 @@ +NXP LPC32xx Clock Controller + +Required properties: +- compatible: should be "nxp,lpc3220-clk" +- reg: should contain clock controller registers location and length +- #clock-cells: must be 1, the cell holds id of a clock provided by the + clock controller +- clocks: phandles of external oscillators, the list must contain one + 32768 Hz oscillator and may have one optional high frequency oscillator +- clock-names: list of external oscillator clock names, must contain + "xtal_32k" and may have optional "xtal" + +Examples: + + /* System Control Block */ + scb { + compatible = "simple-bus"; + ranges = <0x0 0x040004000 0x00001000>; + #address-cells = <1>; + #size-cells = <1>; + + clk: clock-controller@0 { + compatible = "nxp,lpc3220-clk"; + reg = <0x00 0x114>; + #clock-cells = <1>; + + clocks = <&xtal_32k>, <&xtal>; + clock-names = "xtal_32k", "xtal"; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/nxp,lpc3220-usb-clk.txt b/Documentation/devicetree/bindings/clock/nxp,lpc3220-usb-clk.txt new file mode 100644 index 000000000000..0aa249409b51 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/nxp,lpc3220-usb-clk.txt @@ -0,0 +1,22 @@ +NXP LPC32xx USB Clock Controller + +Required properties: +- compatible: should be "nxp,lpc3220-usb-clk" +- reg: should contain clock controller registers location and length +- #clock-cells: must be 1, the cell holds id of a clock provided by the + USB clock controller + +Examples: + + usb { + #address-cells = <1>; + #size-cells = <1>; + compatible = "simple-bus"; + ranges = <0x0 0x31020000 0x00001000>; + + usbclk: clock-controller@f00 { + compatible = "nxp,lpc3220-usb-clk"; + reg = <0xf00 0x100>; + #clock-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.txt b/Documentation/devicetree/bindings/clock/qcom,gcc.txt index 54c23f34f194..72f82f444091 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.txt @@ -13,15 +13,20 @@ Required properties : "qcom,gcc-msm8974" "qcom,gcc-msm8974pro" "qcom,gcc-msm8974pro-ac" + "qcom,gcc-msm8996" - reg : shall contain base register location and length - #clock-cells : shall contain 1 - #reset-cells : shall contain 1 +Optional properties : +- #power-domain-cells : shall contain 1 + Example: clock-controller@900000 { compatible = "qcom,gcc-msm8960"; reg = <0x900000 0x4000>; #clock-cells = <1>; #reset-cells = <1>; + #power-domain-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/qcom,mmcc.txt b/Documentation/devicetree/bindings/clock/qcom,mmcc.txt index 29ebf84d25af..8b0f7841af8d 100644 --- a/Documentation/devicetree/bindings/clock/qcom,mmcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,mmcc.txt @@ -9,15 +9,20 @@ Required properties : "qcom,mmcc-msm8660" "qcom,mmcc-msm8960" "qcom,mmcc-msm8974" + "qcom,mmcc-msm8996" - reg : shall contain base register location and length - #clock-cells : shall contain 1 - #reset-cells : shall contain 1 +Optional properties : +- #power-domain-cells : shall contain 1 + Example: clock-controller@4000000 { compatible = "qcom,mmcc-msm8960"; reg = <0x4000000 0x1000>; #clock-cells = <1>; #reset-cells = <1>; + #power-domain-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index df4a259a6898..16a3ec433119 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -1,6 +1,6 @@ * Clock Block on Freescale QorIQ Platforms -Freescale qoriq chips take primary clocking input from the external +Freescale QorIQ chips take primary clocking input from the external SYSCLK signal. The SYSCLK input (frequency) is multiplied using multiple phase locked loops (PLL) to create a variety of frequencies which can then be passed to a variety of internal logic, including @@ -13,14 +13,16 @@ which the chip complies. Chassis Version Example Chips --------------- ------------- 1.0 p4080, p5020, p5040 -2.0 t4240, b4860, t1040 +2.0 t4240, b4860 1. Clock Block Binding Required properties: -- compatible: Should contain a specific clock block compatible string - and a single chassis clock compatible string. - Clock block strings include, but not limited to, one of the: +- compatible: Should contain a chip-specific clock block compatible + string and (if applicable) may contain a chassis-version clock + compatible string. + + Chip-specific strings are of the form "fsl,<chip>-clockgen", such as: * "fsl,p2041-clockgen" * "fsl,p3041-clockgen" * "fsl,p4080-clockgen" @@ -30,15 +32,14 @@ Required properties: * "fsl,b4420-clockgen" * "fsl,b4860-clockgen" * "fsl,ls1021a-clockgen" - Chassis clock strings include: + Chassis-version clock strings include: * "fsl,qoriq-clockgen-1.0": for chassis 1.0 clocks * "fsl,qoriq-clockgen-2.0": for chassis 2.0 clocks - reg: Describes the address of the device's resources within the address space defined by its parent bus, and resource zero represents the clock register set -- clock-frequency: Input system clock frequency -Recommended properties: +Optional properties: - ranges: Allows valid translation between child's address space and parent's. Must be present if the device has sub-nodes. - #address-cells: Specifies the number of cells used to represent @@ -47,8 +48,46 @@ Recommended properties: - #size-cells: Specifies the number of cells used to represent the size of an address. Must be present if the device has sub-nodes and set to 1 if present +- clock-frequency: Input system clock frequency (SYSCLK) +- clocks: If clock-frequency is not specified, sysclk may be provided + as an input clock. Either clock-frequency or clocks must be + provided. + +2. Clock Provider + +The clockgen node should act as a clock provider, though in older device +trees the children of the clockgen node are the clock providers. + +When the clockgen node is a clock provider, #clock-cells = <2>. +The first cell of the clock specifier is the clock type, and the +second cell is the clock index for the specified type. + + Type# Name Index Cell + 0 sysclk must be 0 + 1 cmux index (n in CLKCnCSR) + 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 + +3. Example + + clockgen: global-utilities@e1000 { + compatible = "fsl,p5020-clockgen", "fsl,qoriq-clockgen-1.0"; + clock-frequency = <133333333>; + reg = <0xe1000 0x1000>; + #clock-cells = <2>; + }; + + fman@400000 { + ... + clocks = <&clockgen 3 0>; + ... + }; +} +4. Legacy Child Nodes -2. Clock Provider/Consumer Binding +NOTE: These nodes are deprecated. Kernels should continue to support +device trees with these nodes, but new device trees should not use them. Most of the bindings are from the common clock binding[1]. [1] Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -82,7 +121,7 @@ Recommended properties: - reg: Should be the offset and length of clock block base address. The length should be 4. -Example for clock block and clock provider: +Legacy Example: / { clockgen: global-utilities@e1000 { compatible = "fsl,p5020-clockgen", "fsl,qoriq-clockgen-1.0"; @@ -142,7 +181,7 @@ Example for clock block and clock provider: }; }; -Example for clock consumer: +Example for legacy clock consumer: / { cpu0: PowerPC,e5500@0 { diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt index 5ddb68418655..ae36ab842919 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-div6-clocks.txt @@ -1,7 +1,7 @@ * Renesas CPG DIV6 Clock The CPG DIV6 clocks are variable factor clocks provided by the Clock Pulse -Generator (CPG). They clock input is divided by a configurable factor from 1 +Generator (CPG). Their clock input is divided by a configurable factor from 1 to 64. Required Properties: @@ -20,6 +20,10 @@ Required Properties: clocks must be specified. For clocks with multiple parents, invalid settings must be specified as "<0>". - #clock-cells: Must be 0 + + +Optional Properties: + - clock-output-names: The name of the clock as a free-form string diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt new file mode 100644 index 000000000000..59297d34b208 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt @@ -0,0 +1,69 @@ +* Renesas Clock Pulse Generator / Module Standby and Software Reset + +On Renesas ARM SoCs (SH/R-Mobile, R-Car, RZ), the CPG (Clock Pulse Generator) +and MSSR (Module Standby and Software Reset) blocks are intimately connected, +and share the same register block. + +They provide the following functionalities: + - The CPG block generates various core clocks, + - The MSSR block provides two functions: + 1. Module Standby, providing a Clock Domain to control the clock supply + to individual SoC devices, + 2. Reset Control, to perform a software reset of individual SoC devices. + +Required Properties: + - compatible: Must be one of: + - "renesas,r8a7795-cpg-mssr" for the r8a7795 SoC + + - reg: Base address and length of the memory resource used by the CPG/MSSR + block + + - clocks: References to external parent clocks, one entry for each entry in + clock-names + - clock-names: List of external parent clock names. Valid names are: + - "extal" (r8a7795) + - "extalr" (r8a7795) + + - #clock-cells: Must be 2 + - For CPG core clocks, the two clock specifier cells must be "CPG_CORE" + and a core clock reference, as defined in + <dt-bindings/clock/*-cpg-mssr.h>. + - For module clocks, the two clock specifier cells must be "CPG_MOD" and + a module number, as defined in the datasheet. + + - #power-domain-cells: Must be 0 + - SoC devices that are part of the CPG/MSSR Clock Domain and can be + power-managed through Module Standby should refer to the CPG device + node in their "power-domains" property, as documented by the generic PM + Domain bindings in + Documentation/devicetree/bindings/power/power_domain.txt. + + +Examples +-------- + + - CPG device node: + + cpg: clock-controller@e6150000 { + compatible = "renesas,r8a7795-cpg-mssr"; + reg = <0 0xe6150000 0 0x1000>; + clocks = <&extal_clk>, <&extalr_clk>; + clock-names = "extal", "extalr"; + #clock-cells = <2>; + #power-domain-cells = <0>; + }; + + + - CPG/MSSR Clock Domain member device node: + + scif2: serial@e6e88000 { + compatible = "renesas,scif-r8a7795", "renesas,scif"; + reg = <0 0xe6e88000 0 64>; + interrupts = <GIC_SPI 164 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 310>; + clock-names = "sci_ick"; + dmas = <&dmac1 0x13>, <&dmac1 0x12>; + dma-names = "tx", "rx"; + power-domains = <&cpg>; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/clock/renesas,h8300-div-clock.txt b/Documentation/devicetree/bindings/clock/renesas,h8300-div-clock.txt index 36c2b528245c..399e0da22348 100644 --- a/Documentation/devicetree/bindings/clock/renesas,h8300-div-clock.txt +++ b/Documentation/devicetree/bindings/clock/renesas,h8300-div-clock.txt @@ -2,7 +2,7 @@ Required Properties: - - compatible: Must be "renesas,sh73a0-h8300-div-clock" + - compatible: Must be "renesas,h8300-div-clock" - clocks: Reference to the parent clocks ("extal1" and "extal2") diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3036-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3036-cru.txt new file mode 100644 index 000000000000..20df350b9ef3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3036-cru.txt @@ -0,0 +1,56 @@ +* Rockchip RK3036 Clock and Reset Unit + +The RK3036 clock controller generates and supplies clock to various +controllers within the SoC and also implements a reset controller for SoC +peripherals. + +Required Properties: + +- compatible: should be "rockchip,rk3036-cru" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files" + If missing pll rates are not changeable, due to the missing pll lock status. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. All available clocks are defined as +preprocessor macros in the dt-bindings/clock/rk3036-cru.h headers and can be +used in device tree sources. Similar macros exist for the reset sources in +these files. + +External clocks: + +There are several clocks that are generated outside the SoC. It is expected +that they are defined using standard clock bindings with following +clock-output-names: + - "xin24m" - crystal input - required, + - "ext_i2s" - external I2S clock - optional, + - "rmii_clkin" - external EMAC clock - optional + +Example: Clock controller node: + + cru: cru@20000000 { + compatible = "rockchip,rk3036-cru"; + reg = <0x20000000 0x1000>; + rockchip,grf = <&grf>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock + controller: + + uart0: serial@20060000 { + compatible = "snps,dw-apb-uart"; + reg = <0x20060000 0x100>; + interrupts = <GIC_SPI 20 IRQ_TYPE_LEVEL_HIGH>; + reg-shift = <2>; + reg-io-width = <4>; + clocks = <&cru SCLK_UART0>; + }; diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3228-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3228-cru.txt new file mode 100644 index 000000000000..f323048127eb --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3228-cru.txt @@ -0,0 +1,58 @@ +* Rockchip RK3228 Clock and Reset Unit + +The RK3228 clock controller generates and supplies clock to various +controllers within the SoC and also implements a reset controller for SoC +peripherals. + +Required Properties: + +- compatible: should be "rockchip,rk3228-cru" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files" + If missing pll rates are not changeable, due to the missing pll lock status. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. All available clocks are defined as +preprocessor macros in the dt-bindings/clock/rk3228-cru.h headers and can be +used in device tree sources. Similar macros exist for the reset sources in +these files. + +External clocks: + +There are several clocks that are generated outside the SoC. It is expected +that they are defined using standard clock bindings with following +clock-output-names: + - "xin24m" - crystal input - required, + - "ext_i2s" - external I2S clock - optional, + - "ext_gmac" - external GMAC clock - optional + - "ext_hsadc" - external HSADC clock - optional + - "phy_50m_out" - output clock of the pll in the mac phy + +Example: Clock controller node: + + cru: cru@20000000 { + compatible = "rockchip,rk3228-cru"; + reg = <0x20000000 0x1000>; + rockchip,grf = <&grf>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock + controller: + + uart0: serial@10110000 { + compatible = "snps,dw-apb-uart"; + reg = <0x10110000 0x100>; + interrupts = <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>; + reg-shift = <2>; + reg-io-width = <4>; + clocks = <&cru SCLK_UART0>; + }; diff --git a/Documentation/devicetree/bindings/clock/samsung,s2mps11.txt b/Documentation/devicetree/bindings/clock/samsung,s2mps11.txt new file mode 100644 index 000000000000..2726c1d58a79 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/samsung,s2mps11.txt @@ -0,0 +1,49 @@ +Binding for Samsung S2M and S5M family clock generator block +============================================================ + +This is a part of device tree bindings for S2M and S5M family multi-function +devices. +More information can be found in bindings/mfd/sec-core.txt file. + +The S2MPS11/13/15 and S5M8767 provide three(AP/CP/BT) buffered 32.768 kHz +outputs. The S2MPS14 provides two (AP/BT) buffered 32.768 KHz outputs. + +To register these as clocks with common clock framework instantiate under +main device node a sub-node named "clocks". + +It uses the common clock binding documented in: + - Documentation/devicetree/bindings/clock/clock-bindings.txt + + +Required properties of the "clocks" sub-node: + - #clock-cells: should be 1. + - compatible: Should be one of: "samsung,s2mps11-clk", "samsung,s2mps13-clk", + "samsung,s2mps14-clk", "samsung,s5m8767-clk" + The S2MPS15 uses the same compatible as S2MPS13, as both provides similar + clocks. + + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + Clock ID Devices + ---------------------------------------------------------- + 32KhzAP 0 S2MPS11/13/14/15, S5M8767 + 32KhzCP 1 S2MPS11/13/15, S5M8767 + 32KhzBT 2 S2MPS11/13/14/15, S5M8767 + +Include dt-bindings/clock/samsung,s2mps11.h file to use preprocessor defines +in device tree sources. + + +Example: + + s2mps11_pmic@66 { + compatible = "samsung,s2mps11-pmic"; + reg = <0x66>; + + s2m_osc: clocks { + compatible = "samsung,s2mps11-clk"; + #clock-cells = <1>; + clock-output-names = "xx", "yy", "zz"; + }; + }; diff --git a/Documentation/devicetree/bindings/clock/silabs,si514.txt b/Documentation/devicetree/bindings/clock/silabs,si514.txt new file mode 100644 index 000000000000..ea1a9dbc63b6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/silabs,si514.txt @@ -0,0 +1,24 @@ +Binding for Silicon Labs 514 programmable I2C clock generator. + +Reference +This binding uses the common clock binding[1]. Details about the device can be +found in the datasheet[2]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Si514 datasheet + http://www.silabs.com/Support%20Documents/TechnicalDocs/si514.pdf + +Required properties: + - compatible: Shall be "silabs,si514" + - reg: I2C device address. + - #clock-cells: From common clock bindings: Shall be 0. + +Optional properties: + - clock-output-names: From common clock bindings. Recommended to be "si514". + +Example: + si514: clock-generator@55 { + reg = <0x55>; + #clock-cells = <0>; + compatible = "silabs,si514"; + }; diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt index d8b168ebd5f1..844b3a0976bf 100644 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt +++ b/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt @@ -23,6 +23,7 @@ Required properties: "st,stih407-plls-c32-a9", "st,clkgen-plls-c32" "sst,plls-c32-cx_0", "st,clkgen-plls-c32" "sst,plls-c32-cx_1", "st,clkgen-plls-c32" + "st,stih418-plls-c28-a9", "st,clkgen-plls-c32" "st,stih415-gpu-pll-c32", "st,clkgengpu-pll-c32" "st,stih416-gpu-pll-c32", "st,clkgengpu-pll-c32" diff --git a/Documentation/devicetree/bindings/clock/sunxi.txt b/Documentation/devicetree/bindings/clock/sunxi.txt index 8a47b77abfca..e59f57b24777 100644 --- a/Documentation/devicetree/bindings/clock/sunxi.txt +++ b/Documentation/devicetree/bindings/clock/sunxi.txt @@ -27,7 +27,9 @@ Required properties: "allwinner,sun5i-a10s-ahb-gates-clk" - for the AHB gates on A10s "allwinner,sun7i-a20-ahb-gates-clk" - for the AHB gates on A20 "allwinner,sun6i-a31-ar100-clk" - for the AR100 on A31 + "allwinner,sun9i-a80-cpus-clk" - for the CPUS on A80 "allwinner,sun6i-a31-ahb1-clk" - for the AHB1 clock on A31 + "allwinner,sun8i-h3-ahb2-clk" - for the AHB2 clock on H3 "allwinner,sun6i-a31-ahb1-gates-clk" - for the AHB1 gates on A31 "allwinner,sun8i-a23-ahb1-gates-clk" - for the AHB1 gates on A23 "allwinner,sun9i-a80-ahb0-gates-clk" - for the AHB0 gates on A80 @@ -55,6 +57,9 @@ Required properties: "allwinner,sun9i-a80-apb1-gates-clk" - for the APB1 gates on A80 "allwinner,sun6i-a31-apb2-gates-clk" - for the APB2 gates on A31 "allwinner,sun8i-a23-apb2-gates-clk" - for the APB2 gates on A23 + "allwinner,sun8i-h3-bus-gates-clk" - for the bus gates on H3 + "allwinner,sun9i-a80-apbs-gates-clk" - for the APBS gates on A80 + "allwinner,sun4i-a10-dram-gates-clk" - for the DRAM gates on A10 "allwinner,sun5i-a13-mbus-clk" - for the MBUS clock on A13 "allwinner,sun4i-a10-mmc-clk" - for the MMC clock "allwinner,sun9i-a80-mmc-clk" - for mmc module clocks on A80 @@ -68,8 +73,10 @@ Required properties: "allwinner,sun5i-a13-usb-clk" - for usb gates + resets on A13 "allwinner,sun6i-a31-usb-clk" - for usb gates + resets on A31 "allwinner,sun8i-a23-usb-clk" - for usb gates + resets on A23 + "allwinner,sun8i-h3-usb-clk" - for usb gates + resets on H3 "allwinner,sun9i-a80-usb-mod-clk" - for usb gates + resets on A80 "allwinner,sun9i-a80-usb-phy-clk" - for usb phy gates + resets on A80 + "allwinner,sun4i-a10-ve-clk" - for the Video Engine clock Required properties for all clocks: - reg : shall be the control register address for the clock. @@ -89,6 +96,9 @@ Required properties for all clocks: And "allwinner,*-usb-clk" clocks also require: - reset-cells : shall be set to 1 +The "allwinner,sun4i-a10-ve-clk" clock also requires: +- reset-cells : shall be set to 0 + The "allwinner,sun9i-a80-mmc-config-clk" clock also requires: - #reset-cells : shall be set to 1 - resets : shall be the reset control phandle for the mmc block. diff --git a/Documentation/devicetree/bindings/clock/tango4-clock.txt b/Documentation/devicetree/bindings/clock/tango4-clock.txt new file mode 100644 index 000000000000..19c580a7bda2 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/tango4-clock.txt @@ -0,0 +1,23 @@ +* Sigma Designs Tango4 Clock Generator + +The Tango4 clock generator outputs cpu_clk and sys_clk (the latter is used +for RAM and various peripheral devices). The clock binding described here +is applicable to all Tango4 SoCs. + +Required Properties: + +- compatible: should be "sigma,tango4-clkgen". +- reg: physical base address of the device and length of memory mapped region. +- clocks: phandle of the input clock (crystal oscillator). +- clock-output-names: should be "cpuclk" and "sysclk". +- #clock-cells: should be set to 1. + +Example: + + clkgen: clkgen@10000 { + compatible = "sigma,tango4-clkgen"; + reg = <0x10000 0x40>; + clocks = <&xtal>; + clock-output-names = "cpuclk", "sysclk"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt b/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt index 0715695e94a9..2aa06ac0fac5 100644 --- a/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt +++ b/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt @@ -12,7 +12,7 @@ must be present contiguously. Generic DT driver will check only node 'x' for cpu:x. Required properties: -- operating-points: Refer to Documentation/devicetree/bindings/power/opp.txt +- operating-points: Refer to Documentation/devicetree/bindings/opp/opp.txt for details Optional properties: diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt index e41c98ffbccb..dd3929e85dec 100644 --- a/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-dt.txt @@ -11,7 +11,7 @@ Required properties: - None Optional properties: -- operating-points: Refer to Documentation/devicetree/bindings/power/opp.txt for +- operating-points: Refer to Documentation/devicetree/bindings/opp/opp.txt for details. OPPs *must* be supplied either via DT, i.e. this property, or populated at runtime. - clock-latency: Specify the possible maximum transition latency for clock, diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt new file mode 100644 index 000000000000..d91a02a3b6b0 --- /dev/null +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-st.txt @@ -0,0 +1,91 @@ +Binding for ST's CPUFreq driver +=============================== + +ST's CPUFreq driver attempts to read 'process' and 'version' attributes +from the SoC, then supplies the OPP framework with 'prop' and 'supported +hardware' information respectively. The framework is then able to read +the DT and operate in the usual way. + +For more information about the expected DT format [See: ../opp/opp.txt]. + +Frequency Scaling only +---------------------- + +No vendor specific driver required for this. + +Located in CPU's node: + +- operating-points : [See: ../power/opp.txt] + +Example [safe] +-------------- + +cpus { + cpu@0 { + /* kHz uV */ + operating-points = <1500000 0 + 1200000 0 + 800000 0 + 500000 0>; + }; +}; + +Dynamic Voltage and Frequency Scaling (DVFS) +-------------------------------------------- + +This requires the ST CPUFreq driver to supply 'process' and 'version' info. + +Located in CPU's node: + +- operating-points-v2 : [See ../power/opp.txt] + +Example [unsafe] +---------------- + +cpus { + cpu@0 { + operating-points-v2 = <&cpu0_opp_table>; + }; +}; + +cpu0_opp_table: opp_table { + compatible = "operating-points-v2"; + + /* ############################################################### */ + /* # WARNING: Do not attempt to copy/replicate these nodes, # */ + /* # they are only to be supplied by the bootloader !!! # */ + /* ############################################################### */ + opp0 { + /* Major Minor Substrate */ + /* 2 all all */ + opp-supported-hw = <0x00000004 0xffffffff 0xffffffff>; + opp-hz = /bits/ 64 <1500000000>; + clock-latency-ns = <10000000>; + + opp-microvolt-pcode0 = <1200000>; + opp-microvolt-pcode1 = <1200000>; + opp-microvolt-pcode2 = <1200000>; + opp-microvolt-pcode3 = <1200000>; + opp-microvolt-pcode4 = <1170000>; + opp-microvolt-pcode5 = <1140000>; + opp-microvolt-pcode6 = <1100000>; + opp-microvolt-pcode7 = <1070000>; + }; + + opp1 { + /* Major Minor Substrate */ + /* all all all */ + opp-supported-hw = <0xffffffff 0xffffffff 0xffffffff>; + opp-hz = /bits/ 64 <1200000000>; + clock-latency-ns = <10000000>; + + opp-microvolt-pcode0 = <1110000>; + opp-microvolt-pcode1 = <1150000>; + opp-microvolt-pcode2 = <1100000>; + opp-microvolt-pcode3 = <1080000>; + opp-microvolt-pcode4 = <1040000>; + opp-microvolt-pcode5 = <1020000>; + opp-microvolt-pcode6 = <980000>; + opp-microvolt-pcode7 = <930000>; + }; +}; diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt index 6831d025ec24..adeca34c5a33 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt @@ -441,7 +441,7 @@ EXAMPLE: regmap = <&snvs>; interrupts = <0 4 0x4> linux,keycode = <116>; /* KEY_POWER */ - wakeup; + wakeup-source; }; ===================================================================== @@ -530,7 +530,7 @@ FULL EXAMPLE regmap = <&sec_mon>; interrupts = <0 4 0x4>; linux,keycode = <116>; /* KEY_POWER */ - wakeup; + wakeup-source; }; }; diff --git a/Documentation/devicetree/bindings/crypto/rockchip-crypto.txt b/Documentation/devicetree/bindings/crypto/rockchip-crypto.txt new file mode 100644 index 000000000000..096df34b11c1 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/rockchip-crypto.txt @@ -0,0 +1,29 @@ +Rockchip Electronics And Security Accelerator + +Required properties: +- compatible: Should be "rockchip,rk3288-crypto" +- reg: Base physical address of the engine and length of memory mapped + region +- interrupts: Interrupt number +- clocks: Reference to the clocks about crypto +- clock-names: "aclk" used to clock data + "hclk" used to clock data + "sclk" used to clock crypto accelerator + "apb_pclk" used to clock dma +- resets: Must contain an entry for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include the name "crypto-rst". + +Examples: + + crypto: cypto-controller@ff8a0000 { + compatible = "rockchip,rk3288-crypto"; + reg = <0xff8a0000 0x4000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru ACLK_CRYPTO>, <&cru HCLK_CRYPTO>, + <&cru SCLK_CRYPTO>, <&cru ACLK_DMAC1>; + clock-names = "aclk", "hclk", "sclk", "apb_pclk"; + resets = <&cru SRST_CRYPTO>; + reset-names = "crypto-rst"; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/video/arm,pl11x.txt b/Documentation/devicetree/bindings/display/arm,pl11x.txt index 3e3039a8a253..3e3039a8a253 100644 --- a/Documentation/devicetree/bindings/video/arm,pl11x.txt +++ b/Documentation/devicetree/bindings/display/arm,pl11x.txt diff --git a/Documentation/devicetree/bindings/drm/armada/marvell,dove-lcd.txt b/Documentation/devicetree/bindings/display/armada/marvell,dove-lcd.txt index 46525ea3e646..46525ea3e646 100644 --- a/Documentation/devicetree/bindings/drm/armada/marvell,dove-lcd.txt +++ b/Documentation/devicetree/bindings/display/armada/marvell,dove-lcd.txt diff --git a/Documentation/devicetree/bindings/video/atmel,lcdc.txt b/Documentation/devicetree/bindings/display/atmel,lcdc.txt index ecb8da063d07..ecb8da063d07 100644 --- a/Documentation/devicetree/bindings/video/atmel,lcdc.txt +++ b/Documentation/devicetree/bindings/display/atmel,lcdc.txt diff --git a/Documentation/devicetree/bindings/drm/atmel/hlcdc-dc.txt b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt index ebc1a914bda3..ebc1a914bda3 100644 --- a/Documentation/devicetree/bindings/drm/atmel/hlcdc-dc.txt +++ b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt diff --git a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt new file mode 100644 index 000000000000..56a961aa5061 --- /dev/null +++ b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt @@ -0,0 +1,65 @@ +Broadcom VC4 (VideoCore4) GPU + +The VC4 device present on the Raspberry Pi includes a display system +with HDMI output and the HVS (Hardware Video Scaler) for compositing +display planes. + +Required properties for VC4: +- compatible: Should be "brcm,bcm2835-vc4" + +Required properties for Pixel Valve: +- compatible: Should be one of "brcm,bcm2835-pixelvalve0", + "brcm,bcm2835-pixelvalve1", or "brcm,bcm2835-pixelvalve2" +- reg: Physical base address and length of the PV's registers +- interrupts: The interrupt number + See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt + +Required properties for HVS: +- compatible: Should be "brcm,bcm2835-hvs" +- reg: Physical base address and length of the HVS's registers +- interrupts: The interrupt number + See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt + +Required properties for HDMI +- compatible: Should be "brcm,bcm2835-hdmi" +- reg: Physical base address and length of the two register ranges + ("HDMI" and "HD", in that order) +- interrupts: The interrupt numbers + See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt +- ddc: phandle of the I2C controller used for DDC EDID probing +- clocks: a) hdmi: The HDMI state machine clock + b) pixel: The pixel clock. + +Optional properties for HDMI: +- hpd-gpios: The GPIO pin for HDMI hotplug detect (if it doesn't appear + as an interrupt/status bit in the HDMI controller + itself). See bindings/pinctrl/brcm,bcm2835-gpio.txt + +Example: +pixelvalve@7e807000 { + compatible = "brcm,bcm2835-pixelvalve2"; + reg = <0x7e807000 0x100>; + interrupts = <2 10>; /* pixelvalve */ +}; + +hvs@7e400000 { + compatible = "brcm,bcm2835-hvs"; + reg = <0x7e400000 0x6000>; + interrupts = <2 1>; +}; + +hdmi: hdmi@7e902000 { + compatible = "brcm,bcm2835-hdmi"; + reg = <0x7e902000 0x600>, + <0x7e808000 0x100>; + interrupts = <2 8>, <2 9>; + ddc = <&i2c2>; + hpd-gpios = <&gpio 46 GPIO_ACTIVE_HIGH>; + clocks = <&clocks BCM2835_PLLH_PIX>, + <&clocks BCM2835_CLOCK_HSM>; + clock-names = "pixel", "hdmi"; +}; + +vc4: gpu { + compatible = "brcm,bcm2835-vc4"; +}; diff --git a/Documentation/devicetree/bindings/video/adi,adv7123.txt b/Documentation/devicetree/bindings/display/bridge/adi,adv7123.txt index a6b2b2b8f3d9..a6b2b2b8f3d9 100644 --- a/Documentation/devicetree/bindings/video/adi,adv7123.txt +++ b/Documentation/devicetree/bindings/display/bridge/adi,adv7123.txt diff --git a/Documentation/devicetree/bindings/video/adi,adv7511.txt b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt index 96c25ee01501..96c25ee01501 100644 --- a/Documentation/devicetree/bindings/video/adi,adv7511.txt +++ b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt diff --git a/Documentation/devicetree/bindings/drm/bridge/dw_hdmi.txt b/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt index a905c1413558..dc1452f0d5d8 100644 --- a/Documentation/devicetree/bindings/drm/bridge/dw_hdmi.txt +++ b/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt @@ -14,8 +14,8 @@ Required properties: -port@[X]: SoC specific port nodes with endpoint definitions as defined in Documentation/devicetree/bindings/media/video-interfaces.txt, please refer to the SoC specific binding document: - * Documentation/devicetree/bindings/drm/imx/hdmi.txt - * Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt + * Documentation/devicetree/bindings/display/imx/hdmi.txt + * Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt Optional properties - reg-io-width: the width of the reg:1,4, default set to 1 if not present diff --git a/Documentation/devicetree/bindings/video/bridge/ps8622.txt b/Documentation/devicetree/bindings/display/bridge/ps8622.txt index c989c3807f2b..c989c3807f2b 100644 --- a/Documentation/devicetree/bindings/video/bridge/ps8622.txt +++ b/Documentation/devicetree/bindings/display/bridge/ps8622.txt diff --git a/Documentation/devicetree/bindings/video/bridge/ptn3460.txt b/Documentation/devicetree/bindings/display/bridge/ptn3460.txt index 361971ba104d..361971ba104d 100644 --- a/Documentation/devicetree/bindings/video/bridge/ptn3460.txt +++ b/Documentation/devicetree/bindings/display/bridge/ptn3460.txt diff --git a/Documentation/devicetree/bindings/drm/i2c/tda998x.txt b/Documentation/devicetree/bindings/display/bridge/tda998x.txt index e9e4bce40760..e178e6b9f9ee 100644 --- a/Documentation/devicetree/bindings/drm/i2c/tda998x.txt +++ b/Documentation/devicetree/bindings/display/bridge/tda998x.txt @@ -5,6 +5,10 @@ Required properties; - reg: I2C address +Required node: + - port: Input port node with endpoint definition, as described + in Documentation/devicetree/bindings/graph.txt + Optional properties: - interrupts: interrupt number and trigger type default: polling diff --git a/Documentation/devicetree/bindings/video/thine,thc63lvdm83d b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt index 527e236e9a2a..527e236e9a2a 100644 --- a/Documentation/devicetree/bindings/video/thine,thc63lvdm83d +++ b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt diff --git a/Documentation/devicetree/bindings/video/cirrus,clps711x-fb.txt b/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt index 6fc3c6adeefa..d685be898d0c 100644 --- a/Documentation/devicetree/bindings/video/cirrus,clps711x-fb.txt +++ b/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt @@ -6,7 +6,7 @@ Required properties: location and size of the framebuffer memory. - clocks : phandle + clock specifier pair of the FB reference clock. - display : phandle to a display node as described in - Documentation/devicetree/bindings/video/display-timing.txt. + Documentation/devicetree/bindings/display/display-timing.txt. Additionally, the display node has to define properties: - bits-per-pixel: Bits per pixel. - ac-prescale : LCD AC bias frequency. This frequency is the required diff --git a/Documentation/devicetree/bindings/video/analog-tv-connector.txt b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt index 0c0970c210ab..0c0970c210ab 100644 --- a/Documentation/devicetree/bindings/video/analog-tv-connector.txt +++ b/Documentation/devicetree/bindings/display/connector/analog-tv-connector.txt diff --git a/Documentation/devicetree/bindings/video/dvi-connector.txt b/Documentation/devicetree/bindings/display/connector/dvi-connector.txt index fc53f7c60bc6..fc53f7c60bc6 100644 --- a/Documentation/devicetree/bindings/video/dvi-connector.txt +++ b/Documentation/devicetree/bindings/display/connector/dvi-connector.txt diff --git a/Documentation/devicetree/bindings/video/hdmi-connector.txt b/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt index acd5668b1ce1..acd5668b1ce1 100644 --- a/Documentation/devicetree/bindings/video/hdmi-connector.txt +++ b/Documentation/devicetree/bindings/display/connector/hdmi-connector.txt diff --git a/Documentation/devicetree/bindings/video/vga-connector.txt b/Documentation/devicetree/bindings/display/connector/vga-connector.txt index c727f298e7ad..c727f298e7ad 100644 --- a/Documentation/devicetree/bindings/video/vga-connector.txt +++ b/Documentation/devicetree/bindings/display/connector/vga-connector.txt diff --git a/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt b/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt new file mode 100644 index 000000000000..ed5e0a7894ad --- /dev/null +++ b/Documentation/devicetree/bindings/display/etnaviv/etnaviv-drm.txt @@ -0,0 +1,54 @@ +Etnaviv DRM master device +========================= + +The Etnaviv DRM master device is a virtual device needed to list all +Vivante GPU cores that comprise the GPU subsystem. + +Required properties: +- compatible: Should be one of + "fsl,imx-gpu-subsystem" + "marvell,dove-gpu-subsystem" +- cores: Should contain a list of phandles pointing to Vivante GPU devices + +example: + +gpu-subsystem { + compatible = "fsl,imx-gpu-subsystem"; + cores = <&gpu_2d>, <&gpu_3d>; +}; + + +Vivante GPU core devices +======================== + +Required properties: +- compatible: Should be "vivante,gc" + A more specific compatible is not needed, as the cores contain chip + identification registers at fixed locations, which provide all the + necessary information to the driver. +- reg: should be register base and length as documented in the + datasheet +- interrupts: Should contain the cores interrupt line +- clocks: should contain one clock for entry in clock-names + see Documentation/devicetree/bindings/clock/clock-bindings.txt +- clock-names: + - "bus": AXI/register clock + - "core": GPU core clock + - "shader": Shader clock (only required if GPU has feature PIPE_3D) + +Optional properties: +- power-domains: a power domain consumer specifier according to + Documentation/devicetree/bindings/power/power_domain.txt + +example: + +gpu_3d: gpu@00130000 { + compatible = "vivante,gc"; + reg = <0x00130000 0x4000>; + interrupts = <0 9 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6QDL_CLK_GPU3D_AXI>, + <&clks IMX6QDL_CLK_GPU3D_CORE>, + <&clks IMX6QDL_CLK_GPU3D_SHADER>; + clock-names = "bus", "core", "shader"; + power-domains = <&gpc 1>; +}; diff --git a/Documentation/devicetree/bindings/video/exynos-mic.txt b/Documentation/devicetree/bindings/display/exynos/exynos-mic.txt index 0fba2ee6440a..0fba2ee6440a 100644 --- a/Documentation/devicetree/bindings/video/exynos-mic.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos-mic.txt diff --git a/Documentation/devicetree/bindings/video/exynos5433-decon.txt b/Documentation/devicetree/bindings/display/exynos/exynos5433-decon.txt index 377afbf5122a..377afbf5122a 100644 --- a/Documentation/devicetree/bindings/video/exynos5433-decon.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos5433-decon.txt diff --git a/Documentation/devicetree/bindings/video/exynos7-decon.txt b/Documentation/devicetree/bindings/display/exynos/exynos7-decon.txt index f5f9c8d4a55a..3938caacf11c 100644 --- a/Documentation/devicetree/bindings/video/exynos7-decon.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos7-decon.txt @@ -38,7 +38,7 @@ Optional Properties: Can be used in case timings cannot be provided otherwise or to override timings provided by the panel. -[1]: Documentation/devicetree/bindings/video/display-timing.txt +[1]: Documentation/devicetree/bindings/display/display-timing.txt Example: diff --git a/Documentation/devicetree/bindings/video/exynos_dp.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dp.txt index 7a3a9cdb86ab..fe4a7a2dea9c 100644 --- a/Documentation/devicetree/bindings/video/exynos_dp.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_dp.txt @@ -1,3 +1,20 @@ +Device-Tree bindings for Samsung Exynos Embedded DisplayPort Transmitter(eDP) + +DisplayPort is industry standard to accommodate the growing board adoption +of digital display technology within the PC and CE industries. +It consolidates the internal and external connection methods to reduce device +complexity and cost. It also supports necessary features for important cross +industry applications and provides performance scalability to enable the next +generation of displays that feature higher color depths, refresh rates, and +display resolutions. + +eDP (embedded display port) device is compliant with Embedded DisplayPort +standard as follows, +- DisplayPort standard 1.1a for Exynos5250 and Exynos5260. +- DisplayPort standard 1.3 for Exynos5422s and Exynos5800. + +eDP resides between FIMD and panel or FIMD and bridge such as LVDS. + The Exynos display port interface should be configured based on the type of panel connected to it. @@ -50,7 +67,7 @@ Required properties for dp-controller: number of lanes supported by the panel. LANE_COUNT1 = 1, LANE_COUNT2 = 2, LANE_COUNT4 = 4 - display-timings: timings for the connected panel as described by - Documentation/devicetree/bindings/video/display-timing.txt + Documentation/devicetree/bindings/display/display-timing.txt Optional properties for dp-controller: -interlaced: @@ -66,8 +83,15 @@ Optional properties for dp-controller: Hotplug detect GPIO. Indicates which GPIO should be used for hotplug detection - -video interfaces: Device node can contain video interface port - nodes according to [1]. +Video interfaces: + Device node can contain video interface port nodes according to [1]. + The following are properties specific to those nodes: + + endpoint node connected to bridge or panel node: + - remote-endpoint: specifies the endpoint in panel or bridge node. + This node is required in all kinds of exynos dp + to represent the connection between dp and bridge + or dp and panel. [1]: Documentation/devicetree/bindings/media/video-interfaces.txt @@ -111,9 +135,18 @@ Board Specific portion: }; ports { - port@0 { + port { dp_out: endpoint { - remote-endpoint = <&bridge_in>; + remote-endpoint = <&dp_in>; + }; + }; + }; + + panel { + ... + port { + dp_in: endpoint { + remote-endpoint = <&dp_out>; }; }; }; diff --git a/Documentation/devicetree/bindings/video/exynos_dsim.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt index 0be036270661..0e6f0c024858 100644 --- a/Documentation/devicetree/bindings/video/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt @@ -49,7 +49,7 @@ Video interfaces: mode - samsung,esc-clock-frequency: specifies DSI frequency in escape mode -[1]: Documentation/devicetree/bindings/mipi/dsi/mipi-dsi-bus.txt +[1]: Documentation/devicetree/bindings/display/mipi-dsi-bus.txt [2]: Documentation/devicetree/bindings/media/video-interfaces.txt Example: diff --git a/Documentation/devicetree/bindings/video/exynos_hdmi.txt b/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt index 1fd8cf9cbfac..d474f59be6d6 100644 --- a/Documentation/devicetree/bindings/video/exynos_hdmi.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt @@ -2,10 +2,9 @@ Device-Tree bindings for drm hdmi driver Required properties: - compatible: value should be one among the following: - 1) "samsung,exynos5-hdmi" <DEPRECATED> - 2) "samsung,exynos4210-hdmi" - 3) "samsung,exynos4212-hdmi" - 4) "samsung,exynos5420-hdmi" + 1) "samsung,exynos4210-hdmi" + 2) "samsung,exynos4212-hdmi" + 3) "samsung,exynos5420-hdmi" - reg: physical base address of the hdmi and length of memory mapped region. - interrupts: interrupt number to the cpu. diff --git a/Documentation/devicetree/bindings/video/exynos_hdmiddc.txt b/Documentation/devicetree/bindings/display/exynos/exynos_hdmiddc.txt index 41eee971562b..41eee971562b 100644 --- a/Documentation/devicetree/bindings/video/exynos_hdmiddc.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_hdmiddc.txt diff --git a/Documentation/devicetree/bindings/video/exynos_hdmiphy.txt b/Documentation/devicetree/bindings/display/exynos/exynos_hdmiphy.txt index 162f641f7639..162f641f7639 100644 --- a/Documentation/devicetree/bindings/video/exynos_hdmiphy.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_hdmiphy.txt diff --git a/Documentation/devicetree/bindings/video/exynos_mixer.txt b/Documentation/devicetree/bindings/display/exynos/exynos_mixer.txt index 3e38128f866b..3e38128f866b 100644 --- a/Documentation/devicetree/bindings/video/exynos_mixer.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_mixer.txt diff --git a/Documentation/devicetree/bindings/video/samsung-fimd.txt b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt index a8bbbde03e79..27c3ce0db16a 100644 --- a/Documentation/devicetree/bindings/video/samsung-fimd.txt +++ b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt @@ -82,7 +82,7 @@ in [2]. The following are properties specific to those nodes: 3 - for parallel output, 4 - for write-back interface -[1]: Documentation/devicetree/bindings/video/display-timing.txt +[1]: Documentation/devicetree/bindings/display/display-timing.txt [2]: Documentation/devicetree/bindings/media/video-interfaces.txt Example: diff --git a/Documentation/devicetree/bindings/video/fsl,dcu.txt b/Documentation/devicetree/bindings/display/fsl,dcu.txt index ebf1be9ae393..ebf1be9ae393 100644 --- a/Documentation/devicetree/bindings/video/fsl,dcu.txt +++ b/Documentation/devicetree/bindings/display/fsl,dcu.txt diff --git a/Documentation/devicetree/bindings/video/fsl,imx-fb.txt b/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt index 8c8c2f4e4c3f..00d5f8ea7ec6 100644 --- a/Documentation/devicetree/bindings/video/fsl,imx-fb.txt +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt @@ -9,7 +9,7 @@ Required properties: Required nodes: - display: Phandle to a display node as described in - Documentation/devicetree/bindings/video/display-timing.txt + Documentation/devicetree/bindings/display/display-timing.txt Additional, the display node has to define properties: - bits-per-pixel: Bits per pixel - fsl,pcr: LCDC PCR value diff --git a/Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt index 971c3eedb1c7..971c3eedb1c7 100644 --- a/Documentation/devicetree/bindings/drm/imx/fsl-imx-drm.txt +++ b/Documentation/devicetree/bindings/display/imx/fsl-imx-drm.txt diff --git a/Documentation/devicetree/bindings/drm/imx/hdmi.txt b/Documentation/devicetree/bindings/display/imx/hdmi.txt index 1b756cf9afb0..1b756cf9afb0 100644 --- a/Documentation/devicetree/bindings/drm/imx/hdmi.txt +++ b/Documentation/devicetree/bindings/display/imx/hdmi.txt diff --git a/Documentation/devicetree/bindings/drm/imx/ldb.txt b/Documentation/devicetree/bindings/display/imx/ldb.txt index 9a21366436f6..0a175d991b52 100644 --- a/Documentation/devicetree/bindings/drm/imx/ldb.txt +++ b/Documentation/devicetree/bindings/display/imx/ldb.txt @@ -63,7 +63,7 @@ Required properties: Optional properties (required if display-timings are used): - display-timings : A node that describes the display timings as defined in - Documentation/devicetree/bindings/video/display-timing.txt. + Documentation/devicetree/bindings/display/display-timing.txt. - fsl,data-mapping : should be "spwg" or "jeida" This describes how the color bits are laid out in the serialized LVDS signal. diff --git a/Documentation/devicetree/bindings/display/marvell,pxa2xx-lcdc.txt b/Documentation/devicetree/bindings/display/marvell,pxa2xx-lcdc.txt new file mode 100644 index 000000000000..309c47f25b87 --- /dev/null +++ b/Documentation/devicetree/bindings/display/marvell,pxa2xx-lcdc.txt @@ -0,0 +1,34 @@ +PXA LCD Controller +------------------ + +Required properties: + - compatible : one of these + "marvell,pxa2xx-lcdc", + "marvell,pxa270-lcdc", + "marvell,pxa300-lcdc" + - reg : should contain 1 register range (address and length). + - interrupts : framebuffer controller interrupt. + - clocks: phandle to input clocks + +Required nodes: + - port: connection to the LCD panel (see video-interfaces.txt) + This node must have its properties bus-width and remote-endpoint set. + If the panel is not a TFT color panel, then a "lcd-type" property in + the panel should specify the panel type. + This panel node should be in the board dts. + +Example: + lcd-controller@40500000 { + compatible = "marvell,pxa2xx-lcdc"; + reg = <0x44000000 0x10000>; + interrupts = <17>; + clocks = <&clks CLK_LCD>; + status = "okay"; + + port { + lcdc_out: endpoint { + remote-endpoint = <&panel_in>; + bus-width = <16>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mipi/dsi/mipi-dsi-bus.txt b/Documentation/devicetree/bindings/display/mipi-dsi-bus.txt index 973c27273772..973c27273772 100644 --- a/Documentation/devicetree/bindings/mipi/dsi/mipi-dsi-bus.txt +++ b/Documentation/devicetree/bindings/display/mipi-dsi-bus.txt diff --git a/Documentation/devicetree/bindings/drm/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt index d56923cd5590..e7423bea1424 100644 --- a/Documentation/devicetree/bindings/drm/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -14,21 +14,24 @@ Required properties: - clocks: device clocks See Documentation/devicetree/bindings/clocks/clock-bindings.txt for details. - clock-names: the following clocks are required: + * "mdp_core_clk" + * "iface_clk" * "bus_clk" - * "byte_clk" - * "core_clk" * "core_mmss_clk" - * "iface_clk" - * "mdp_core_clk" + * "byte_clk" * "pixel_clk" + * "core_clk" + For DSIv2, we need an additional clock: + * "src_clk" - vdd-supply: phandle to vdd regulator device node - vddio-supply: phandle to vdd-io regulator device node - vdda-supply: phandle to vdda regulator device node - qcom,dsi-phy: phandle to DSI PHY device node +- syscon-sfpb: A phandle to mmss_sfpb syscon node (only for DSIv2) Optional properties: - panel@0: Node of panel connected to this DSI controller. - See files in Documentation/devicetree/bindings/panel/ for each supported + See files in Documentation/devicetree/bindings/display/panel/ for each supported panel. - qcom,dual-dsi-mode: Boolean value indicating if the DSI controller is driving a panel which needs 2 DSI links. @@ -51,6 +54,7 @@ Required properties: * "qcom,dsi-phy-28nm-hpm" * "qcom,dsi-phy-28nm-lp" * "qcom,dsi-phy-20nm" + * "qcom,dsi-phy-28nm-8960" - reg: Physical base address and length of the registers of PLL, PHY and PHY regulator - reg-names: The names of register regions. The following regions are required: diff --git a/Documentation/devicetree/bindings/drm/msm/edp.txt b/Documentation/devicetree/bindings/display/msm/edp.txt index 3a20f6ea5898..3a20f6ea5898 100644 --- a/Documentation/devicetree/bindings/drm/msm/edp.txt +++ b/Documentation/devicetree/bindings/display/msm/edp.txt diff --git a/Documentation/devicetree/bindings/drm/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index 67d0a58dbb77..67d0a58dbb77 100644 --- a/Documentation/devicetree/bindings/drm/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt diff --git a/Documentation/devicetree/bindings/drm/msm/hdmi.txt b/Documentation/devicetree/bindings/display/msm/hdmi.txt index e926239e1101..379ee2ea9a3d 100644 --- a/Documentation/devicetree/bindings/drm/msm/hdmi.txt +++ b/Documentation/devicetree/bindings/display/msm/hdmi.txt @@ -2,6 +2,7 @@ Qualcomm adreno/snapdragon hdmi output Required properties: - compatible: one of the following + * "qcom,hdmi-tx-8996" * "qcom,hdmi-tx-8994" * "qcom,hdmi-tx-8084" * "qcom,hdmi-tx-8974" @@ -21,6 +22,7 @@ Required properties: Optional properties: - qcom,hdmi-tx-mux-en-gpio: hdmi mux enable pin - qcom,hdmi-tx-mux-sel-gpio: hdmi mux select pin +- power-domains: reference to the power domain(s), if available. - pinctrl-names: the pin control state names; should contain "default" - pinctrl-0: the default pinctrl state (active) - pinctrl-1: the "sleep" pinctrl state @@ -35,6 +37,7 @@ Example: reg-names = "core_physical"; reg = <0x04a00000 0x1000>; interrupts = <GIC_SPI 79 0>; + power-domains = <&mmcc MDSS_GDSC>; clock-names = "core_clk", "master_iface_clk", diff --git a/Documentation/devicetree/bindings/drm/msm/mdp.txt b/Documentation/devicetree/bindings/display/msm/mdp.txt index 1a0598e5279d..a214f6cd0363 100644 --- a/Documentation/devicetree/bindings/drm/msm/mdp.txt +++ b/Documentation/devicetree/bindings/display/msm/mdp.txt @@ -2,22 +2,33 @@ Qualcomm adreno/snapdragon display controller Required properties: - compatible: - * "qcom,mdp" - mdp4 + * "qcom,mdp4" - mdp4 + * "qcom,mdp5" - mdp5 - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt signal from the display controller. - connectors: array of phandles for output device(s) - clocks: device clocks See ../clocks/clock-bindings.txt for details. -- clock-names: the following clocks are required: - * "core_clk" - * "iface_clk" - * "lut_clk" - * "src_clk" - * "hdmi_clk" - * "mpd_clk" +- clock-names: the following clocks are required. + For MDP4: + * "core_clk" + * "iface_clk" + * "lut_clk" + * "src_clk" + * "hdmi_clk" + * "mdp_clk" + For MDP5: + * "bus_clk" + * "iface_clk" + * "core_clk_src" + * "core_clk" + * "lut_clk" (some MDP5 versions may not need this) + * "vsync_clk" Optional properties: - gpus: phandle for gpu device +- clock-names: the following clocks are optional: + * "lut_clk" Example: @@ -25,7 +36,7 @@ Example: ... mdp: qcom,mdp@5100000 { - compatible = "qcom,mdp"; + compatible = "qcom,mdp4"; reg = <0x05100000 0xf0000>; interrupts = <GIC_SPI 75 0>; connectors = <&hdmi>; diff --git a/Documentation/devicetree/bindings/fb/mxsfb.txt b/Documentation/devicetree/bindings/display/mxsfb.txt index 96ec5179c8a0..96ec5179c8a0 100644 --- a/Documentation/devicetree/bindings/fb/mxsfb.txt +++ b/Documentation/devicetree/bindings/display/mxsfb.txt diff --git a/Documentation/devicetree/bindings/panel/ampire,am800480r3tmqwa1h.txt b/Documentation/devicetree/bindings/display/panel/ampire,am800480r3tmqwa1h.txt index 83e2cae1cc1b..83e2cae1cc1b 100644 --- a/Documentation/devicetree/bindings/panel/ampire,am800480r3tmqwa1h.txt +++ b/Documentation/devicetree/bindings/display/panel/ampire,am800480r3tmqwa1h.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b080uan01.txt b/Documentation/devicetree/bindings/display/panel/auo,b080uan01.txt index bae0e2b51467..bae0e2b51467 100644 --- a/Documentation/devicetree/bindings/panel/auo,b080uan01.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b080uan01.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b101aw03.txt b/Documentation/devicetree/bindings/display/panel/auo,b101aw03.txt index 72e088a4fb3a..72e088a4fb3a 100644 --- a/Documentation/devicetree/bindings/panel/auo,b101aw03.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b101aw03.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b101ean01.txt b/Documentation/devicetree/bindings/display/panel/auo,b101ean01.txt index 3590b0741619..3590b0741619 100644 --- a/Documentation/devicetree/bindings/panel/auo,b101ean01.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b101ean01.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b101xtn01.txt b/Documentation/devicetree/bindings/display/panel/auo,b101xtn01.txt index 889d511d66c9..889d511d66c9 100644 --- a/Documentation/devicetree/bindings/panel/auo,b101xtn01.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b101xtn01.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b116xw03.txt b/Documentation/devicetree/bindings/display/panel/auo,b116xw03.txt index 690d0a568ef3..690d0a568ef3 100644 --- a/Documentation/devicetree/bindings/panel/auo,b116xw03.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b116xw03.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b133htn01.txt b/Documentation/devicetree/bindings/display/panel/auo,b133htn01.txt index 302226b5bb55..302226b5bb55 100644 --- a/Documentation/devicetree/bindings/panel/auo,b133htn01.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b133htn01.txt diff --git a/Documentation/devicetree/bindings/panel/auo,b133xtn01.txt b/Documentation/devicetree/bindings/display/panel/auo,b133xtn01.txt index 7443b7c76769..7443b7c76769 100644 --- a/Documentation/devicetree/bindings/panel/auo,b133xtn01.txt +++ b/Documentation/devicetree/bindings/display/panel/auo,b133xtn01.txt diff --git a/Documentation/devicetree/bindings/panel/avic,tm070ddh03.txt b/Documentation/devicetree/bindings/display/panel/avic,tm070ddh03.txt index b6f2f3e8f44e..b6f2f3e8f44e 100644 --- a/Documentation/devicetree/bindings/panel/avic,tm070ddh03.txt +++ b/Documentation/devicetree/bindings/display/panel/avic,tm070ddh03.txt diff --git a/Documentation/devicetree/bindings/display/panel/boe,tv080wum-nl0.txt b/Documentation/devicetree/bindings/display/panel/boe,tv080wum-nl0.txt new file mode 100644 index 000000000000..50be5e2438b2 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/boe,tv080wum-nl0.txt @@ -0,0 +1,7 @@ +Boe Corporation 8.0" WUXGA TFT LCD panel + +Required properties: +- compatible: should be "boe,tv080wum-nl0" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/chunghwa,claa101wa01a.txt b/Documentation/devicetree/bindings/display/panel/chunghwa,claa101wa01a.txt index f24614e4d5ec..f24614e4d5ec 100644 --- a/Documentation/devicetree/bindings/panel/chunghwa,claa101wa01a.txt +++ b/Documentation/devicetree/bindings/display/panel/chunghwa,claa101wa01a.txt diff --git a/Documentation/devicetree/bindings/panel/chunghwa,claa101wb03.txt b/Documentation/devicetree/bindings/display/panel/chunghwa,claa101wb03.txt index 0ab2c05a4c22..0ab2c05a4c22 100644 --- a/Documentation/devicetree/bindings/panel/chunghwa,claa101wb03.txt +++ b/Documentation/devicetree/bindings/display/panel/chunghwa,claa101wb03.txt diff --git a/Documentation/devicetree/bindings/video/display-timing.txt b/Documentation/devicetree/bindings/display/panel/display-timing.txt index e1d4a0b59612..e1d4a0b59612 100644 --- a/Documentation/devicetree/bindings/video/display-timing.txt +++ b/Documentation/devicetree/bindings/display/panel/display-timing.txt diff --git a/Documentation/devicetree/bindings/panel/edt,et057090dhu.txt b/Documentation/devicetree/bindings/display/panel/edt,et057090dhu.txt index 4903d7b1d947..4903d7b1d947 100644 --- a/Documentation/devicetree/bindings/panel/edt,et057090dhu.txt +++ b/Documentation/devicetree/bindings/display/panel/edt,et057090dhu.txt diff --git a/Documentation/devicetree/bindings/panel/edt,et070080dh6.txt b/Documentation/devicetree/bindings/display/panel/edt,et070080dh6.txt index 20cb38e836e4..20cb38e836e4 100644 --- a/Documentation/devicetree/bindings/panel/edt,et070080dh6.txt +++ b/Documentation/devicetree/bindings/display/panel/edt,et070080dh6.txt diff --git a/Documentation/devicetree/bindings/panel/edt,etm0700g0dh6.txt b/Documentation/devicetree/bindings/display/panel/edt,etm0700g0dh6.txt index ee4b18053e40..ee4b18053e40 100644 --- a/Documentation/devicetree/bindings/panel/edt,etm0700g0dh6.txt +++ b/Documentation/devicetree/bindings/display/panel/edt,etm0700g0dh6.txt diff --git a/Documentation/devicetree/bindings/panel/foxlink,fl500wvr00-a0t.txt b/Documentation/devicetree/bindings/display/panel/foxlink,fl500wvr00-a0t.txt index b47f9d87bc19..b47f9d87bc19 100644 --- a/Documentation/devicetree/bindings/panel/foxlink,fl500wvr00-a0t.txt +++ b/Documentation/devicetree/bindings/display/panel/foxlink,fl500wvr00-a0t.txt diff --git a/Documentation/devicetree/bindings/panel/giantplus,gpg482739qs5.txt b/Documentation/devicetree/bindings/display/panel/giantplus,gpg482739qs5.txt index 24b0b624434b..24b0b624434b 100644 --- a/Documentation/devicetree/bindings/panel/giantplus,gpg482739qs5.txt +++ b/Documentation/devicetree/bindings/display/panel/giantplus,gpg482739qs5.txt diff --git a/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt b/Documentation/devicetree/bindings/display/panel/hannstar,hsd070pww1.txt index 7da1d5c038ff..7da1d5c038ff 100644 --- a/Documentation/devicetree/bindings/panel/hannstar,hsd070pww1.txt +++ b/Documentation/devicetree/bindings/display/panel/hannstar,hsd070pww1.txt diff --git a/Documentation/devicetree/bindings/panel/hannstar,hsd100pxn1.txt b/Documentation/devicetree/bindings/display/panel/hannstar,hsd100pxn1.txt index 8270319a99de..8270319a99de 100644 --- a/Documentation/devicetree/bindings/panel/hannstar,hsd100pxn1.txt +++ b/Documentation/devicetree/bindings/display/panel/hannstar,hsd100pxn1.txt diff --git a/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt b/Documentation/devicetree/bindings/display/panel/hit,tx23d38vm0caa.txt index 04caaae19af6..04caaae19af6 100644 --- a/Documentation/devicetree/bindings/panel/hit,tx23d38vm0caa.txt +++ b/Documentation/devicetree/bindings/display/panel/hit,tx23d38vm0caa.txt diff --git a/Documentation/devicetree/bindings/panel/innolux,at043tn24.txt b/Documentation/devicetree/bindings/display/panel/innolux,at043tn24.txt index 4104226b61bc..4104226b61bc 100644 --- a/Documentation/devicetree/bindings/panel/innolux,at043tn24.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,at043tn24.txt diff --git a/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt b/Documentation/devicetree/bindings/display/panel/innolux,g121i1-l01.txt index 2743b07cd2f2..2743b07cd2f2 100644 --- a/Documentation/devicetree/bindings/panel/innolux,g121i1-l01.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,g121i1-l01.txt diff --git a/Documentation/devicetree/bindings/display/panel/innolux,g121x1-l03.txt b/Documentation/devicetree/bindings/display/panel/innolux,g121x1-l03.txt new file mode 100644 index 000000000000..649744620ae1 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/innolux,g121x1-l03.txt @@ -0,0 +1,7 @@ +Innolux Corporation 12.1" G121X1-L03 XGA (1024x768) TFT LCD panel + +Required properties: +- compatible: should be "innolux,g121x1-l03" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/innolux,n116bge.txt b/Documentation/devicetree/bindings/display/panel/innolux,n116bge.txt index 081bb939ed31..081bb939ed31 100644 --- a/Documentation/devicetree/bindings/panel/innolux,n116bge.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,n116bge.txt diff --git a/Documentation/devicetree/bindings/panel/innolux,n156bge-l21.txt b/Documentation/devicetree/bindings/display/panel/innolux,n156bge-l21.txt index 7825844aafdf..7825844aafdf 100644 --- a/Documentation/devicetree/bindings/panel/innolux,n156bge-l21.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,n156bge-l21.txt diff --git a/Documentation/devicetree/bindings/panel/innolux,zj070na-01p.txt b/Documentation/devicetree/bindings/display/panel/innolux,zj070na-01p.txt index 824f87f1526d..824f87f1526d 100644 --- a/Documentation/devicetree/bindings/panel/innolux,zj070na-01p.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,zj070na-01p.txt diff --git a/Documentation/devicetree/bindings/display/panel/kyo,tcg121xglp.txt b/Documentation/devicetree/bindings/display/panel/kyo,tcg121xglp.txt new file mode 100644 index 000000000000..a8e940fe731e --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/kyo,tcg121xglp.txt @@ -0,0 +1,7 @@ +Kyocera Corporation 12.1" XGA (1024x768) TFT LCD panel + +Required properties: +- compatible: should be "kyo,tcg121xglp" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/lg,lb070wv8.txt b/Documentation/devicetree/bindings/display/panel/lg,lb070wv8.txt index a7588e5259cf..a7588e5259cf 100644 --- a/Documentation/devicetree/bindings/panel/lg,lb070wv8.txt +++ b/Documentation/devicetree/bindings/display/panel/lg,lb070wv8.txt diff --git a/Documentation/devicetree/bindings/panel/lg,ld070wx3-sl01.txt b/Documentation/devicetree/bindings/display/panel/lg,ld070wx3-sl01.txt index 5e649cb9aa1a..5e649cb9aa1a 100644 --- a/Documentation/devicetree/bindings/panel/lg,ld070wx3-sl01.txt +++ b/Documentation/devicetree/bindings/display/panel/lg,ld070wx3-sl01.txt diff --git a/Documentation/devicetree/bindings/panel/lg,lg4573.txt b/Documentation/devicetree/bindings/display/panel/lg,lg4573.txt index 824441f4e95a..824441f4e95a 100644 --- a/Documentation/devicetree/bindings/panel/lg,lg4573.txt +++ b/Documentation/devicetree/bindings/display/panel/lg,lg4573.txt diff --git a/Documentation/devicetree/bindings/panel/lg,lh500wx1-sd03.txt b/Documentation/devicetree/bindings/display/panel/lg,lh500wx1-sd03.txt index a04fd2b2e73d..a04fd2b2e73d 100644 --- a/Documentation/devicetree/bindings/panel/lg,lh500wx1-sd03.txt +++ b/Documentation/devicetree/bindings/display/panel/lg,lh500wx1-sd03.txt diff --git a/Documentation/devicetree/bindings/panel/lg,lp129qe.txt b/Documentation/devicetree/bindings/display/panel/lg,lp129qe.txt index 9f262e0c5a2e..9f262e0c5a2e 100644 --- a/Documentation/devicetree/bindings/panel/lg,lp129qe.txt +++ b/Documentation/devicetree/bindings/display/panel/lg,lp129qe.txt diff --git a/Documentation/devicetree/bindings/video/lgphilips,lb035q02.txt b/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.txt index 1a1e653e5407..1a1e653e5407 100644 --- a/Documentation/devicetree/bindings/video/lgphilips,lb035q02.txt +++ b/Documentation/devicetree/bindings/display/panel/lgphilips,lb035q02.txt diff --git a/Documentation/devicetree/bindings/panel/nec,nl4827hc19-05b.txt b/Documentation/devicetree/bindings/display/panel/nec,nl4827hc19-05b.txt index 8e1914d1edb8..8e1914d1edb8 100644 --- a/Documentation/devicetree/bindings/panel/nec,nl4827hc19-05b.txt +++ b/Documentation/devicetree/bindings/display/panel/nec,nl4827hc19-05b.txt diff --git a/Documentation/devicetree/bindings/panel/okaya,rs800480t-7x0gp.txt b/Documentation/devicetree/bindings/display/panel/okaya,rs800480t-7x0gp.txt index ddf8e211d382..ddf8e211d382 100644 --- a/Documentation/devicetree/bindings/panel/okaya,rs800480t-7x0gp.txt +++ b/Documentation/devicetree/bindings/display/panel/okaya,rs800480t-7x0gp.txt diff --git a/Documentation/devicetree/bindings/panel/ortustech,com43h4m85ulc.txt b/Documentation/devicetree/bindings/display/panel/ortustech,com43h4m85ulc.txt index de19e9398618..de19e9398618 100644 --- a/Documentation/devicetree/bindings/panel/ortustech,com43h4m85ulc.txt +++ b/Documentation/devicetree/bindings/display/panel/ortustech,com43h4m85ulc.txt diff --git a/Documentation/devicetree/bindings/panel/panasonic,vvx10f004b00.txt b/Documentation/devicetree/bindings/display/panel/panasonic,vvx10f004b00.txt index d328b0341bf4..d328b0341bf4 100644 --- a/Documentation/devicetree/bindings/panel/panasonic,vvx10f004b00.txt +++ b/Documentation/devicetree/bindings/display/panel/panasonic,vvx10f004b00.txt diff --git a/Documentation/devicetree/bindings/display/panel/panasonic,vvx10f034n00.txt b/Documentation/devicetree/bindings/display/panel/panasonic,vvx10f034n00.txt new file mode 100644 index 000000000000..37dedf6a6702 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panasonic,vvx10f034n00.txt @@ -0,0 +1,20 @@ +Panasonic 10" WUXGA TFT LCD panel + +Required properties: +- compatible: should be "panasonic,vvx10f034n00" +- reg: DSI virtual channel of the peripheral +- power-supply: phandle of the regulator that provides the supply voltage + +Optional properties: +- backlight: phandle of the backlight device attached to the panel + +Example: + + mdss_dsi@fd922800 { + panel@0 { + compatible = "panasonic,vvx10f034n00"; + reg = <0>; + power-supply = <&vreg_vsp>; + backlight = <&lp8566_wled>; + }; + }; diff --git a/Documentation/devicetree/bindings/video/panel-dpi.txt b/Documentation/devicetree/bindings/display/panel/panel-dpi.txt index a40180b05bab..216c894d4f99 100644 --- a/Documentation/devicetree/bindings/video/panel-dpi.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-dpi.txt @@ -10,7 +10,7 @@ Optional properties: Required nodes: - "panel-timing" containing video timings - (Documentation/devicetree/bindings/video/display-timing.txt) + (Documentation/devicetree/bindings/display/display-timing.txt) - Video port for DPI input Example diff --git a/Documentation/devicetree/bindings/video/panel-dsi-cm.txt b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt index dce48eb9db57..dce48eb9db57 100644 --- a/Documentation/devicetree/bindings/video/panel-dsi-cm.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-dsi-cm.txt diff --git a/Documentation/devicetree/bindings/display/panel/qiaodian,qd43003c0-40.txt b/Documentation/devicetree/bindings/display/panel/qiaodian,qd43003c0-40.txt new file mode 100644 index 000000000000..0fbdab89ac3d --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/qiaodian,qd43003c0-40.txt @@ -0,0 +1,7 @@ +QiaoDian XianShi Corporation 4"3 TFT LCD panel + +Required properties: +- compatible: should be "qiaodian,qd43003c0-40" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/panel/samsung,ld9040.txt b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.txt index 07c36c3f7b52..fc595d9b985b 100644 --- a/Documentation/devicetree/bindings/panel/samsung,ld9040.txt +++ b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.txt @@ -20,7 +20,7 @@ The device node can contain one 'port' child node with one child 'endpoint' node, according to the bindings defined in [3]. This node should describe panel's video bus. -[1]: Documentation/devicetree/bindings/video/display-timing.txt +[1]: Documentation/devicetree/bindings/display/display-timing.txt [2]: Documentation/devicetree/bindings/spi/spi-bus.txt [3]: Documentation/devicetree/bindings/media/video-interfaces.txt diff --git a/Documentation/devicetree/bindings/panel/samsung,ltn101nt05.txt b/Documentation/devicetree/bindings/display/panel/samsung,ltn101nt05.txt index ef522c6bb85f..ef522c6bb85f 100644 --- a/Documentation/devicetree/bindings/panel/samsung,ltn101nt05.txt +++ b/Documentation/devicetree/bindings/display/panel/samsung,ltn101nt05.txt diff --git a/Documentation/devicetree/bindings/panel/samsung,ltn140at29-301.txt b/Documentation/devicetree/bindings/display/panel/samsung,ltn140at29-301.txt index e7f969d891cc..e7f969d891cc 100644 --- a/Documentation/devicetree/bindings/panel/samsung,ltn140at29-301.txt +++ b/Documentation/devicetree/bindings/display/panel/samsung,ltn140at29-301.txt diff --git a/Documentation/devicetree/bindings/panel/samsung,s6e8aa0.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt index e7ee988e3156..25701c81b5e0 100644 --- a/Documentation/devicetree/bindings/panel/samsung,s6e8aa0.txt +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt @@ -21,7 +21,7 @@ The device node can contain one 'port' child node with one child 'endpoint' node, according to the bindings defined in [2]. This node should describe panel's video bus. -[1]: Documentation/devicetree/bindings/video/display-timing.txt +[1]: Documentation/devicetree/bindings/display/display-timing.txt [2]: Documentation/devicetree/bindings/media/video-interfaces.txt Example: diff --git a/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt index f522bb8e47e1..f522bb8e47e1 100644 --- a/Documentation/devicetree/bindings/panel/sharp,lq101r1sx01.txt +++ b/Documentation/devicetree/bindings/display/panel/sharp,lq101r1sx01.txt diff --git a/Documentation/devicetree/bindings/video/sharp,ls037v7dw01.txt b/Documentation/devicetree/bindings/display/panel/sharp,ls037v7dw01.txt index 0cc8981e9d49..0cc8981e9d49 100644 --- a/Documentation/devicetree/bindings/video/sharp,ls037v7dw01.txt +++ b/Documentation/devicetree/bindings/display/panel/sharp,ls037v7dw01.txt diff --git a/Documentation/devicetree/bindings/display/panel/sharp,ls043t1le01.txt b/Documentation/devicetree/bindings/display/panel/sharp,ls043t1le01.txt new file mode 100644 index 000000000000..3770a111968b --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sharp,ls043t1le01.txt @@ -0,0 +1,22 @@ +Sharp Microelectronics 4.3" qHD TFT LCD panel + +Required properties: +- compatible: should be "sharp,ls043t1le01-qhd" +- reg: DSI virtual channel of the peripheral +- power-supply: phandle of the regulator that provides the supply voltage + +Optional properties: +- backlight: phandle of the backlight device attached to the panel +- reset-gpios: a GPIO spec for the reset pin + +Example: + + mdss_dsi@fd922800 { + panel@0 { + compatible = "sharp,ls043t1le01-qhd"; + reg = <0>; + avdd-supply = <&pm8941_l22>; + backlight = <&pm8941_wled>; + reset-gpios = <&pm8941_gpios 19 GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/panel/shelly,sca07010-bfn-lnn.txt b/Documentation/devicetree/bindings/display/panel/shelly,sca07010-bfn-lnn.txt index fc1ea9e26c94..fc1ea9e26c94 100644 --- a/Documentation/devicetree/bindings/panel/shelly,sca07010-bfn-lnn.txt +++ b/Documentation/devicetree/bindings/display/panel/shelly,sca07010-bfn-lnn.txt diff --git a/Documentation/devicetree/bindings/panel/simple-panel.txt b/Documentation/devicetree/bindings/display/panel/simple-panel.txt index 1341bbf4aa3d..1341bbf4aa3d 100644 --- a/Documentation/devicetree/bindings/panel/simple-panel.txt +++ b/Documentation/devicetree/bindings/display/panel/simple-panel.txt diff --git a/Documentation/devicetree/bindings/video/sony,acx565akm.txt b/Documentation/devicetree/bindings/display/panel/sony,acx565akm.txt index e12333280749..e12333280749 100644 --- a/Documentation/devicetree/bindings/video/sony,acx565akm.txt +++ b/Documentation/devicetree/bindings/display/panel/sony,acx565akm.txt diff --git a/Documentation/devicetree/bindings/display/panel/startek,startek-kd050c.txt b/Documentation/devicetree/bindings/display/panel/startek,startek-kd050c.txt new file mode 100644 index 000000000000..70cd8d18d841 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/startek,startek-kd050c.txt @@ -0,0 +1,4 @@ +Startek Electronic Technology Co. KD050C 5.0" WVGA TFT LCD panel + +Required properties: +- compatible: should be "startek,startek-kd050c" diff --git a/Documentation/devicetree/bindings/video/toppoly,td028ttec1.txt b/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt index 7175dc3740ac..7175dc3740ac 100644 --- a/Documentation/devicetree/bindings/video/toppoly,td028ttec1.txt +++ b/Documentation/devicetree/bindings/display/panel/toppoly,td028ttec1.txt diff --git a/Documentation/devicetree/bindings/video/tpo,td043mtea1.txt b/Documentation/devicetree/bindings/display/panel/tpo,td043mtea1.txt index ec6d62975162..ec6d62975162 100644 --- a/Documentation/devicetree/bindings/video/tpo,td043mtea1.txt +++ b/Documentation/devicetree/bindings/display/panel/tpo,td043mtea1.txt diff --git a/Documentation/devicetree/bindings/video/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index c902323928f7..eccd4f4867b2 100644 --- a/Documentation/devicetree/bindings/video/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -5,7 +5,9 @@ Required Properties: - compatible: must be one of the following. - "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) compatible DU + - "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU + - "renesas,du-r8a7793" for R8A7793 (R-Car M2-N) compatible DU + - "renesas,du-r8a7794" for R8A7794 (R-Car E2) compatible DU - reg: A list of base address and length of each memory resource, one for each entry in the reg-names property. @@ -22,9 +24,9 @@ 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. - - R8A7790 and R8A7791 use one functional clock per channel and one clock - per LVDS encoder. The functional clocks must be named "du.x" with "x" - being the channel numerical index. The LVDS clocks must be named + - R8A779[0134] 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. @@ -43,7 +45,9 @@ corresponding to each DU output. ----------------------------------------------------------------------------- R8A7779 (H1) DPAD 0 DPAD 1 - R8A7790 (H2) DPAD LVDS 0 LVDS 1 - R8A7791 (M2) DPAD LVDS 0 - + R8A7791 (M2-W) DPAD LVDS 0 - + R8A7793 (M2-N) DPAD LVDS 0 - + R8A7794 (E2) DPAD 0 DPAD 1 - Example: R8A7790 (R-Car H2) DU diff --git a/Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt index 668091f27674..668091f27674 100644 --- a/Documentation/devicetree/bindings/video/dw_hdmi-rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt new file mode 100644 index 000000000000..1753f0cc6fad --- /dev/null +++ b/Documentation/devicetree/bindings/display/rockchip/dw_mipi_dsi_rockchip.txt @@ -0,0 +1,60 @@ +Rockchip specific extensions to the Synopsys Designware MIPI DSI +================================ + +Required properties: +- #address-cells: Should be <1>. +- #size-cells: Should be <0>. +- compatible: "rockchip,rk3288-mipi-dsi", "snps,dw-mipi-dsi". +- reg: Represent the physical address range of the controller. +- interrupts: Represent the controller's interrupt to the CPU(s). +- clocks, clock-names: Phandles to the controller's pll reference + clock(ref) and APB clock(pclk), as described in [1]. +- rockchip,grf: this soc should set GRF regs to mux vopl/vopb. +- ports: contain a port node with endpoint definitions as defined in [2]. + For vopb,set the reg = <0> and set the reg = <1> for vopl. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Documentation/devicetree/bindings/media/video-interfaces.txt + +Example: + mipi_dsi: mipi@ff960000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "rockchip,rk3288-mipi-dsi", "snps,dw-mipi-dsi"; + reg = <0xff960000 0x4000>; + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cru SCLK_MIPI_24M>, <&cru PCLK_MIPI_DSI0>; + clock-names = "ref", "pclk"; + rockchip,grf = <&grf>; + status = "okay"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + reg = <1>; + + mipi_in: port { + #address-cells = <1>; + #size-cells = <0>; + mipi_in_vopb: endpoint@0 { + reg = <0>; + remote-endpoint = <&vopb_out_mipi>; + }; + mipi_in_vopl: endpoint@1 { + reg = <1>; + remote-endpoint = <&vopl_out_mipi>; + }; + }; + }; + + panel { + compatible ="boe,tv080wum-nl0"; + reg = <0>; + + enable-gpios = <&gpio7 3 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&lcd_en>; + backlight = <&backlight>; + status = "okay"; + }; + }; diff --git a/Documentation/devicetree/bindings/video/rockchip-drm.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.txt index 7fff582495a2..5707af89319d 100644 --- a/Documentation/devicetree/bindings/video/rockchip-drm.txt +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-drm.txt @@ -9,7 +9,7 @@ Required properties: - compatible: Should be "rockchip,display-subsystem" - ports: Should contain a list of phandles pointing to display interface port of vop devices. vop definitions as defined in - Documentation/devicetree/bindings/video/rockchip-vop.txt + Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt example: diff --git a/Documentation/devicetree/bindings/video/rockchip-vop.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt index d15351f2313d..5489b59e3d41 100644 --- a/Documentation/devicetree/bindings/video/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,rk3288-vop"; + "rockchip,rk3036-vop"; - interrupts: should contain a list of all VOP IP block interrupts in the order: VSYNC, LCD_SYSTEM. The interrupt specifier diff --git a/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt index c46ba641a1df..c46ba641a1df 100644 --- a/Documentation/devicetree/bindings/video/simple-framebuffer-sunxi.txt +++ b/Documentation/devicetree/bindings/display/simple-framebuffer-sunxi.txt diff --git a/Documentation/devicetree/bindings/video/simple-framebuffer.txt b/Documentation/devicetree/bindings/display/simple-framebuffer.txt index 4474ef6e0b95..8c9e9f515c87 100644 --- a/Documentation/devicetree/bindings/video/simple-framebuffer.txt +++ b/Documentation/devicetree/bindings/display/simple-framebuffer.txt @@ -47,10 +47,14 @@ Required properties: - a8b8g8r8 (32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r). Optional properties: -- clocks : List of clocks used by the framebuffer. Clocks listed here - are expected to already be configured correctly. The OS must - ensure these clocks are not modified or disabled while the - simple framebuffer remains active. +- clocks : List of clocks used by the framebuffer. +- *-supply : Any number of regulators used by the framebuffer. These should + be named according to the names in the device's design. + + The above resources are expected to already be configured correctly. + The OS must ensure they are not modified or disabled while the simple + framebuffer remains active. + - display : phandle pointing to the primary display hardware node Example: @@ -68,6 +72,7 @@ chosen { stride = <(1600 * 2)>; format = "r5g6b5"; clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>; + lcd-supply = <®_dc1sw>; display = <&lcdc0>; }; stdout-path = "display0"; diff --git a/Documentation/devicetree/bindings/fb/sm501fb.txt b/Documentation/devicetree/bindings/display/sm501fb.txt index 9d9f0098092b..9d9f0098092b 100644 --- a/Documentation/devicetree/bindings/fb/sm501fb.txt +++ b/Documentation/devicetree/bindings/display/sm501fb.txt diff --git a/Documentation/devicetree/bindings/video/ssd1289fb.txt b/Documentation/devicetree/bindings/display/ssd1289fb.txt index 4fcd5e68cb6e..4fcd5e68cb6e 100644 --- a/Documentation/devicetree/bindings/video/ssd1289fb.txt +++ b/Documentation/devicetree/bindings/display/ssd1289fb.txt diff --git a/Documentation/devicetree/bindings/video/ssd1307fb.txt b/Documentation/devicetree/bindings/display/ssd1307fb.txt index d1be78db63f5..eb31ed47a283 100644 --- a/Documentation/devicetree/bindings/video/ssd1307fb.txt +++ b/Documentation/devicetree/bindings/display/ssd1307fb.txt @@ -2,7 +2,8 @@ Required properties: - compatible: Should be "solomon,<chip>fb-<bus>". The only supported bus for - now is i2c, and the supported chips are ssd1305, ssd1306 and ssd1307. + now is i2c, and the supported chips are ssd1305, ssd1306, ssd1307 and + ssd1309. - reg: Should contain address of the controller on the I2C bus. Most likely 0x3c or 0x3d - pwm: Should contain the pwm to use according to the OF device tree PWM diff --git a/Documentation/devicetree/bindings/gpu/st,stih4xx.txt b/Documentation/devicetree/bindings/display/st,stih4xx.txt index a36dfce0032e..a352ed30cd70 100644 --- a/Documentation/devicetree/bindings/gpu/st,stih4xx.txt +++ b/Documentation/devicetree/bindings/display/st,stih4xx.txt @@ -61,7 +61,7 @@ STMicroelectronics stih4xx platforms - reg-names: names of the mapped memory regions listed in regs property in the same order. - interrupts : HDMI interrupt number to the CPU. - - interrupt-names: name of the interrupts listed in interrupts property in + - interrupt-names: names of the interrupts listed in interrupts property in the same order - clocks: from common clock binding: handle hardware IP needed clocks, the number of clocks may depend of the SoC type. @@ -95,7 +95,7 @@ sti-dvo: - clock-names: names of the clocks listed in clocks property in the same order. - pinctrl-0: pin control handle - - pinctrl-name: names of the pin control to use + - pinctrl-names: names of the pin control states to use - sti,panel: phandle of the panel connected to the DVO output sti-hqvdp: diff --git a/Documentation/devicetree/bindings/mipi/nvidia,tegra114-mipi.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra114-mipi.txt index e4a25cedc5cf..e4a25cedc5cf 100644 --- a/Documentation/devicetree/bindings/mipi/nvidia,tegra114-mipi.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra114-mipi.txt diff --git a/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index e685610d38e2..a3bd8c050c4e 100644 --- a/Documentation/devicetree/bindings/gpu/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -184,7 +184,7 @@ of the following host1x client modules: - avdd-dsi-supply: phandle of a supply that powers the DSI controller - nvidia,mipi-calibrate: Should contain a phandle and a specifier specifying which pads are used by this DSI output and need to be calibrated. See also - ../mipi/nvidia,tegra114-mipi.txt. + ../display/tegra/nvidia,tegra114-mipi.txt. Optional properties: - nvidia,ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing diff --git a/Documentation/devicetree/bindings/video/ti,dra7-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt index f33a05137b0e..c30f9ec189ed 100644 --- a/Documentation/devicetree/bindings/video/ti,dra7-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,dra7-dss.txt @@ -1,7 +1,7 @@ Texas Instruments DRA7x Display Subsystem ========================================= -See Documentation/devicetree/bindings/video/ti,omap-dss.txt for generic +See Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt for generic description about OMAP Display Subsystem bindings. DSS Core diff --git a/Documentation/devicetree/bindings/video/ti,omap-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt index e1ef29569338..e1ef29569338 100644 --- a/Documentation/devicetree/bindings/video/ti,omap-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt diff --git a/Documentation/devicetree/bindings/video/ti,omap2-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt index fa8bb2ed1170..afcd5a86c6a4 100644 --- a/Documentation/devicetree/bindings/video/ti,omap2-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap2-dss.txt @@ -1,7 +1,7 @@ Texas Instruments OMAP2 Display Subsystem ========================================= -See Documentation/devicetree/bindings/video/ti,omap-dss.txt for generic +See Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt for generic description about OMAP Display Subsystem bindings. DSS Core diff --git a/Documentation/devicetree/bindings/video/ti,omap3-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt index 0023fa4b1328..dc66e1447c31 100644 --- a/Documentation/devicetree/bindings/video/ti,omap3-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap3-dss.txt @@ -1,7 +1,7 @@ Texas Instruments OMAP3 Display Subsystem ========================================= -See Documentation/devicetree/bindings/video/ti,omap-dss.txt for generic +See Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt for generic description about OMAP Display Subsystem bindings. DSS Core diff --git a/Documentation/devicetree/bindings/video/ti,omap4-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt index b8c29fbd1fbb..bc624db8888d 100644 --- a/Documentation/devicetree/bindings/video/ti,omap4-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap4-dss.txt @@ -1,7 +1,7 @@ Texas Instruments OMAP4 Display Subsystem ========================================= -See Documentation/devicetree/bindings/video/ti,omap-dss.txt for generic +See Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt for generic description about OMAP Display Subsystem bindings. DSS Core diff --git a/Documentation/devicetree/bindings/video/ti,omap5-dss.txt b/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt index 38ffc8fcd816..118a486c47bb 100644 --- a/Documentation/devicetree/bindings/video/ti,omap5-dss.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,omap5-dss.txt @@ -1,7 +1,7 @@ Texas Instruments OMAP5 Display Subsystem ========================================= -See Documentation/devicetree/bindings/video/ti,omap-dss.txt for generic +See Documentation/devicetree/bindings/display/ti/ti,omap-dss.txt for generic description about OMAP Display Subsystem bindings. DSS Core diff --git a/Documentation/devicetree/bindings/video/ti,opa362.txt b/Documentation/devicetree/bindings/display/ti/ti,opa362.txt index f96083c0bd17..f96083c0bd17 100644 --- a/Documentation/devicetree/bindings/video/ti,opa362.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,opa362.txt diff --git a/Documentation/devicetree/bindings/video/ti,tfp410.txt b/Documentation/devicetree/bindings/display/ti/ti,tfp410.txt index 2cbe32a3d0bb..2cbe32a3d0bb 100644 --- a/Documentation/devicetree/bindings/video/ti,tfp410.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,tfp410.txt diff --git a/Documentation/devicetree/bindings/video/ti,tpd12s015.txt b/Documentation/devicetree/bindings/display/ti/ti,tpd12s015.txt index 26e6d32e3f20..26e6d32e3f20 100644 --- a/Documentation/devicetree/bindings/video/ti,tpd12s015.txt +++ b/Documentation/devicetree/bindings/display/ti/ti,tpd12s015.txt diff --git a/Documentation/devicetree/bindings/drm/tilcdc/panel.txt b/Documentation/devicetree/bindings/display/tilcdc/panel.txt index 4ab9e2300907..f20b31cdc59a 100644 --- a/Documentation/devicetree/bindings/drm/tilcdc/panel.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/panel.txt @@ -15,7 +15,7 @@ Required properties: - display-timings: typical videomode of lcd panel. Multiple video modes can be listed if the panel supports multiple timings, but the 'native-mode' should be the preferred/default resolution. Refer to - Documentation/devicetree/bindings/video/display-timing.txt for display + Documentation/devicetree/bindings/display/display-timing.txt for display timing binding details. Optional properties: diff --git a/Documentation/devicetree/bindings/drm/tilcdc/tfp410.txt b/Documentation/devicetree/bindings/display/tilcdc/tfp410.txt index a58ae7756fc6..a58ae7756fc6 100644 --- a/Documentation/devicetree/bindings/drm/tilcdc/tfp410.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/tfp410.txt diff --git a/Documentation/devicetree/bindings/drm/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt index 2136ee81e061..2136ee81e061 100644 --- a/Documentation/devicetree/bindings/drm/tilcdc/tilcdc.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt diff --git a/Documentation/devicetree/bindings/video/via,vt8500-fb.txt b/Documentation/devicetree/bindings/display/via,vt8500-fb.txt index 2871e218a0fb..2871e218a0fb 100644 --- a/Documentation/devicetree/bindings/video/via,vt8500-fb.txt +++ b/Documentation/devicetree/bindings/display/via,vt8500-fb.txt diff --git a/Documentation/devicetree/bindings/video/wm,prizm-ge-rops.txt b/Documentation/devicetree/bindings/display/wm,prizm-ge-rops.txt index a850fa011f02..a850fa011f02 100644 --- a/Documentation/devicetree/bindings/video/wm,prizm-ge-rops.txt +++ b/Documentation/devicetree/bindings/display/wm,prizm-ge-rops.txt diff --git a/Documentation/devicetree/bindings/video/wm,wm8505-fb.txt b/Documentation/devicetree/bindings/display/wm,wm8505-fb.txt index 0bcadb2840a5..0bcadb2840a5 100644 --- a/Documentation/devicetree/bindings/video/wm,wm8505-fb.txt +++ b/Documentation/devicetree/bindings/display/wm,wm8505-fb.txt diff --git a/Documentation/devicetree/bindings/dma/arm-pl330.txt b/Documentation/devicetree/bindings/dma/arm-pl330.txt index 267565894db9..db7e2260f9c5 100644 --- a/Documentation/devicetree/bindings/dma/arm-pl330.txt +++ b/Documentation/devicetree/bindings/dma/arm-pl330.txt @@ -15,6 +15,7 @@ Optional properties: cells in the dmas property of client device. - dma-channels: contains the total number of DMA channels supported by the DMAC - dma-requests: contains the total number of DMA requests supported by the DMAC + - arm,pl330-broken-no-flushp: quirk for avoiding to execute DMAFLUSHP Example: diff --git a/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt new file mode 100644 index 000000000000..fd5618bd8fbc --- /dev/null +++ b/Documentation/devicetree/bindings/dma/qcom_hidma_mgmt.txt @@ -0,0 +1,89 @@ +Qualcomm Technologies HIDMA Management interface + +Qualcomm Technologies HIDMA is a high speed DMA device. It only supports +memcpy and memset capabilities. It has been designed for virtualized +environments. + +Each HIDMA HW instance consists of multiple DMA channels. These channels +share the same bandwidth. The bandwidth utilization can be parititioned +among channels based on the priority and weight assignments. + +There are only two priority levels and 15 weigh assignments possible. + +Other parameters here determine how much of the system bus this HIDMA +instance can use like maximum read/write request and and number of bytes to +read/write in a single burst. + +Main node required properties: +- compatible: "qcom,hidma-mgmt-1.0"; +- reg: Address range for DMA device +- dma-channels: Number of channels supported by this DMA controller. +- max-write-burst-bytes: Maximum write burst in bytes that HIDMA can + occupy the bus for in a single transaction. A memcpy requested is + fragmented to multiples of this amount. This parameter is used while + writing into destination memory. Setting this value incorrectly can + starve other peripherals in the system. +- max-read-burst-bytes: Maximum read burst in bytes that HIDMA can + occupy the bus for in a single transaction. A memcpy request is + fragmented to multiples of this amount. This parameter is used while + reading the source memory. Setting this value incorrectly can starve + other peripherals in the system. +- max-write-transactions: This value is how many times a write burst is + applied back to back while writing to the destination before yielding + the bus. +- max-read-transactions: This value is how many times a read burst is + applied back to back while reading the source before yielding the bus. +- channel-reset-timeout-cycles: Channel reset timeout in cycles for this SOC. + Once a reset is applied to the HW, HW starts a timer for reset operation + to confirm. If reset is not completed within this time, HW reports reset + failure. + +Sub-nodes: + +HIDMA has one or more DMA channels that are used to move data from one +memory location to another. + +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" +- reg: Addresses for the transfer and event channel +- interrupts: Should contain the event interrupt +- desc-count: Number of asynchronous requests this channel can handle +- iommus: required a iommu node + +Example: + +Hypervisor OS configuration: + + hidma-mgmt@f9984000 = { + compatible = "qcom,hidma-mgmt-1.0"; + reg = <0xf9984000 0x15000>; + dma-channels = <6>; + max-write-burst-bytes = <1024>; + max-read-burst-bytes = <1024>; + max-write-transactions = <31>; + max-read-transactions = <31>; + channel-reset-timeout-cycles = <0x500>; + + hidma_24: dma-controller@0x5c050000 { + compatible = "qcom,hidma-1.0"; + reg = <0 0x5c050000 0x0 0x1000>, + <0 0x5c0b0000 0x0 0x1000>; + interrupts = <0 389 0>; + desc-count = <10>; + iommus = <&system_mmu>; + }; + }; + +Guest OS configuration: + + hidma_24: dma-controller@0x5c050000 { + compatible = "qcom,hidma-1.0"; + reg = <0 0x5c050000 0x0 0x1000>, + <0 0x5c0b0000 0x0 0x1000>; + interrupts = <0 389 0>; + desc-count = <10>; + iommus = <&system_mmu>; + }; diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index 09daeef1ff22..5b902ac8d97e 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt @@ -14,7 +14,14 @@ not described in these device tree bindings. Required Properties: -- compatible: must contain "renesas,rcar-dmac" +- compatible: "renesas,dmac-<soctype>", "renesas,rcar-dmac" as fallback. + Examples with soctypes are: + - "renesas,dmac-r8a7790" (R-Car H2) + - "renesas,dmac-r8a7791" (R-Car M2-W) + - "renesas,dmac-r8a7792" (R-Car V2H) + - "renesas,dmac-r8a7793" (R-Car M2-N) + - "renesas,dmac-r8a7794" (R-Car E2) + - "renesas,dmac-r8a7795" (R-Car H3) - reg: base address and length of the registers block for the DMAC @@ -35,7 +42,7 @@ Required Properties: Example: R8A7790 (R-Car H2) SYS-DMACs dmac0: dma-controller@e6700000 { - compatible = "renesas,rcar-dmac"; + compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac"; reg = <0 0xe6700000 0 0x20000>; interrupts = <0 197 IRQ_TYPE_LEVEL_HIGH 0 200 IRQ_TYPE_LEVEL_HIGH @@ -65,7 +72,7 @@ Example: R8A7790 (R-Car H2) SYS-DMACs }; dmac1: dma-controller@e6720000 { - compatible = "renesas,rcar-dmac"; + compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac"; reg = <0 0xe6720000 0 0x20000>; interrupts = <0 220 IRQ_TYPE_LEVEL_HIGH 0 216 IRQ_TYPE_LEVEL_HIGH diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt index 040f365954cc..e7780a186a36 100644 --- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt @@ -1,7 +1,13 @@ * Renesas USB DMA Controller Device Tree bindings Required Properties: -- compatible: must contain "renesas,usb-dmac" +-compatible: "renesas,<soctype>-usb-dmac", "renesas,usb-dmac" as fallback. + Examples with soctypes are: + - "renesas,r8a7790-usb-dmac" (R-Car H2) + - "renesas,r8a7791-usb-dmac" (R-Car M2-W) + - "renesas,r8a7793-usb-dmac" (R-Car M2-N) + - "renesas,r8a7794-usb-dmac" (R-Car E2) + - "renesas,r8a7795-usb-dmac" (R-Car H3) - reg: base address and length of the registers block for the DMAC - interrupts: interrupt specifiers for the DMAC, one for each entry in interrupt-names. @@ -15,7 +21,7 @@ Required Properties: Example: R8A7790 (R-Car H2) USB-DMACs usb_dmac0: dma-controller@e65a0000 { - compatible = "renesas,usb-dmac"; + compatible = "renesas,r8a7790-usb-dmac", "renesas,usb-dmac"; reg = <0 0xe65a0000 0 0x100>; interrupts = <0 109 IRQ_TYPE_LEVEL_HIGH 0 109 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/dma/stm32-dma.txt b/Documentation/devicetree/bindings/dma/stm32-dma.txt new file mode 100644 index 000000000000..70cd13f1588a --- /dev/null +++ b/Documentation/devicetree/bindings/dma/stm32-dma.txt @@ -0,0 +1,82 @@ +* STMicroelectronics STM32 DMA controller + +The STM32 DMA is a general-purpose direct memory access controller capable of +supporting 8 independent DMA channels. Each channel can have up to 8 requests. + +Required properties: +- compatible: Should be "st,stm32-dma" +- reg: Should contain DMA registers location and length. This should include + all of the per-channel registers. +- interrupts: Should contain all of the per-channel DMA interrupts in + ascending order with respect to the DMA channel index. +- clocks: Should contain the input clock of the DMA instance. +- #dma-cells : Must be <4>. See DMA client paragraph for more details. + +Optional properties: +- resets: Reference to a reset controller asserting the DMA controller +- st,mem2mem: boolean; if defined, it indicates that the controller supports + memory-to-memory transfer + +Example: + + dma2: dma-controller@40026400 { + compatible = "st,stm32-dma"; + reg = <0x40026400 0x400>; + interrupts = <56>, + <57>, + <58>, + <59>, + <60>, + <68>, + <69>, + <70>; + clocks = <&clk_hclk>; + #dma-cells = <4>; + st,mem2mem; + resets = <&rcc 150>; + }; + +* DMA client + +DMA clients connected to the STM32 DMA controller must use the format +described in the dma.txt file, using a five-cell specifier for each +channel: a phandle plus four integer cells. +The four cells in order are: + +1. The channel id +2. The request line number +3. A 32bit mask specifying the DMA channel configuration which are device + dependent: + -bit 9: Peripheral Increment Address + 0x0: no address increment between transfers + 0x1: increment address between transfers + -bit 10: Memory Increment Address + 0x0: no address increment between transfers + 0x1: increment address between transfers + -bit 15: Peripheral Increment Offset Size + 0x0: offset size is linked to the peripheral bus width + 0x1: offset size is fixed to 4 (32-bit alignment) + -bit 16-17: Priority level + 0x0: low + 0x1: medium + 0x2: high + 0x3: very high +5. A 32bit mask specifying the DMA FIFO threshold configuration which are device + dependent: + -bit 0-1: Fifo threshold + 0x0: 1/4 full FIFO + 0x1: 1/2 full FIFO + 0x2: 3/4 full FIFO + 0x3: full FIFO + +Example: + + usart1: serial@40011000 { + compatible = "st,stm32-usart", "st,stm32-uart"; + reg = <0x40011000 0x400>; + interrupts = <37>; + clocks = <&clk_pclk2>; + dmas = <&dma2 2 4 0x10400 0x3>, + <&dma2 7 5 0x10200 0x3>; + dma-names = "rx", "tx"; + }; diff --git a/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt b/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt index 63a48928f3a8..aead5869a28d 100644 --- a/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt +++ b/Documentation/devicetree/bindings/dma/ti-dma-crossbar.txt @@ -2,9 +2,10 @@ Texas Instruments DMA Crossbar (DMA request router) Required properties: - compatible: "ti,dra7-dma-crossbar" for DRA7xx DMA crossbar + "ti,am335x-edma-crossbar" for AM335x and AM437x - reg: Memory map for accessing module -- #dma-cells: Should be set to <1>. - Clients should use the crossbar request number (input) +- #dma-cells: Should be set to to match with the DMA controller's dma-cells + for ti,dra7-dma-crossbar and <3> for ti,am335x-edma-crossbar. - dma-requests: Number of DMA requests the crossbar can receive - dma-masters: phandle pointing to the DMA controller @@ -13,6 +14,19 @@ The DMA controller node need to have the following poroperties: Optional properties: - ti,dma-safe-map: Safe routing value for unused request lines +- ti,reserved-dma-request-ranges: DMA request ranges which should not be used + when mapping xbar input to DMA request, they are either + allocated to be used by for example the DSP or they are used as + memcpy channels in eDMA. + +Notes: +When requesting channel via ti,dra7-dma-crossbar, the DMA clinet must request +the DMA event number as crossbar ID (input to the DMA crossbar). + +For ti,am335x-edma-crossbar: the meaning of parameters of dmas for clients: +dmas = <&edma_xbar 12 0 1>; where <12> is the DMA request number, <0> is the TC +the event should be assigned and <1> is the mux selection for in the crossbar. +When mux 0 is used the DMA channel can be requested directly from edma node. Example: @@ -36,6 +50,8 @@ sdma_xbar: dma-router@4a002b78 { #dma-cells = <1>; dma-requests = <205>; ti,dma-safe-map = <0>; + /* Protect the sDMA request ranges: 10-14 and 100-126 */ + ti,reserved-dma-request-ranges = <10 5>, <100 27>; dma-masters = <&sdma>; }; @@ -47,6 +63,7 @@ uart1: serial@4806a000 { ti,hwmods = "uart1"; clock-frequency = <48000000>; status = "disabled"; + /* Requesting crossbar input 49 and 50 */ dmas = <&sdma_xbar 49>, <&sdma_xbar 50>; dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/dma/ti-edma.txt b/Documentation/devicetree/bindings/dma/ti-edma.txt index 5ba525a10035..079b42a81d7c 100644 --- a/Documentation/devicetree/bindings/dma/ti-edma.txt +++ b/Documentation/devicetree/bindings/dma/ti-edma.txt @@ -1,4 +1,117 @@ -TI EDMA +Texas Instruments eDMA + +The eDMA3 consists of two components: Channel controller (CC) and Transfer +Controller(s) (TC). The CC is the main entry for DMA users since it is +responsible for the DMA channel handling, while the TCs are responsible to +execute the actual DMA tansfer. + +------------------------------------------------------------------------------ +eDMA3 Channel Controller + +Required properties: +- compatible: "ti,edma3-tpcc" for the channel controller(s) +- #dma-cells: Should be set to <2>. The first number is the DMA request + number and the second is the TC the channel is serviced on. +- reg: Memory map of eDMA CC +- reg-names: "edma3_cc" +- interrupts: Interrupt lines for CCINT, MPERR and CCERRINT. +- interrupt-names: "edma3_ccint", "emda3_mperr" and "edma3_ccerrint" +- ti,tptcs: List of TPTCs associated with the eDMA in the following form: + <&tptc_phandle TC_priority_number>. The highest priority is 0. + +Optional properties: +- ti,hwmods: Name of the hwmods associated to the eDMA CC +- ti,edma-memcpy-channels: List of channels allocated to be used for memcpy, iow + these channels will be SW triggered channels. See example. +- ti,edma-reserved-slot-ranges: PaRAM slot ranges which should not be used by + the driver, they are allocated to be used by for example the + DSP. See example. + +------------------------------------------------------------------------------ +eDMA3 Transfer Controller + +Required properties: +- compatible: "ti,edma3-tptc" for the transfer controller(s) +- reg: Memory map of eDMA TC +- interrupts: Interrupt number for TCerrint. + +Optional properties: +- ti,hwmods: Name of the hwmods associated to the given eDMA TC +- interrupt-names: "edma3_tcerrint" + +------------------------------------------------------------------------------ +Example: + +edma: edma@49000000 { + compatible = "ti,edma3-tpcc"; + ti,hwmods = "tpcc"; + reg = <0x49000000 0x10000>; + reg-names = "edma3_cc"; + interrupts = <12 13 14>; + interrupt-names = "edma3_ccint", "emda3_mperr", "edma3_ccerrint"; + dma-requests = <64>; + #dma-cells = <2>; + + ti,tptcs = <&edma_tptc0 7>, <&edma_tptc1 7>, <&edma_tptc2 0>; + + /* Channel 20 and 21 is allocated for memcpy */ + ti,edma-memcpy-channels = <20 21>; + /* The following PaRAM slots are reserved: 35-44 and 100-109 */ + ti,edma-reserved-slot-ranges = <35 10>, <100 10>; +}; + +edma_tptc0: tptc@49800000 { + compatible = "ti,edma3-tptc"; + ti,hwmods = "tptc0"; + reg = <0x49800000 0x100000>; + interrupts = <112>; + interrupt-names = "edm3_tcerrint"; +}; + +edma_tptc1: tptc@49900000 { + compatible = "ti,edma3-tptc"; + ti,hwmods = "tptc1"; + reg = <0x49900000 0x100000>; + interrupts = <113>; + interrupt-names = "edm3_tcerrint"; +}; + +edma_tptc2: tptc@49a00000 { + compatible = "ti,edma3-tptc"; + ti,hwmods = "tptc2"; + reg = <0x49a00000 0x100000>; + interrupts = <114>; + interrupt-names = "edm3_tcerrint"; +}; + +sham: sham@53100000 { + compatible = "ti,omap4-sham"; + ti,hwmods = "sham"; + reg = <0x53100000 0x200>; + interrupts = <109>; + /* DMA channel 36 executed on eDMA TC0 - low priority queue */ + dmas = <&edma 36 0>; + dma-names = "rx"; +}; + +mcasp0: mcasp@48038000 { + compatible = "ti,am33xx-mcasp-audio"; + ti,hwmods = "mcasp0"; + reg = <0x48038000 0x2000>, + <0x46000000 0x400000>; + reg-names = "mpu", "dat"; + interrupts = <80>, <81>; + interrupt-names = "tx", "rx"; + status = "disabled"; + /* DMA channels 8 and 9 executed on eDMA TC2 - high priority queue */ + dmas = <&edma 8 2>, + <&edma 9 2>; + dma-names = "tx", "rx"; +}; + +------------------------------------------------------------------------------ +DEPRECATED binding, new DTS files must use the ti,edma3-tpcc/ti,edma3-tptc +binding. Required properties: - compatible : "ti,edma3" diff --git a/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt b/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt index 78edb80002c8..1006b0489464 100644 --- a/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt +++ b/Documentation/devicetree/bindings/edac/apm-xgene-edac.txt @@ -5,6 +5,8 @@ The follow error types are supported: memory controller - Memory controller PMD (L1/L2) - Processor module unit (PMD) L1/L2 cache + L3 - L3 cache controller + SoC - SoC IP's such as Ethernet, SATA, and etc The following section describes the EDAC DT node binding. @@ -14,6 +16,10 @@ Required properties: - regmap-mcba : Regmap of the MCB-A (memory bridge) resource. - regmap-mcbb : Regmap of the MCB-B (memory bridge) resource. - regmap-efuse : Regmap of the PMD efuse resource. +- regmap-rb : Regmap of the register bus resource. This property + is optional only for compatibility. If the RB + error conditions are not cleared, it will + continuously generate interrupt. - reg : First resource shall be the CPU bus (PCP) resource. - interrupts : Interrupt-specifier for MCU, PMD, L3, or SoC error IRQ(s). @@ -30,6 +36,17 @@ Required properties for PMD subnode: - reg : First resource shall be the PMD resource. - pmd-controller : Instance number of the PMD controller. +Required properties for L3 subnode: +- compatible : Shall be "apm,xgene-edac-l3" or + "apm,xgene-edac-l3-v2". +- reg : First resource shall be the L3 EDAC resource. + +Required properties for SoC subnode: +- compatible : Shall be "apm,xgene-edac-soc-v1" for revision 1 or + "apm,xgene-edac-l3-soc" for general value reporting + only. +- reg : First resource shall be the SoC EDAC resource. + Example: csw: csw@7e200000 { compatible = "apm,xgene-csw", "syscon"; @@ -51,6 +68,11 @@ Example: reg = <0x0 0x1054a000 0x0 0x20>; }; + rb: rb@7e000000 { + compatible = "apm,xgene-rb", "syscon"; + reg = <0x0 0x7e000000 0x0 0x10>; + }; + edac@78800000 { compatible = "apm,xgene-edac"; #address-cells = <2>; @@ -60,6 +82,7 @@ Example: regmap-mcba = <&mcba>; regmap-mcbb = <&mcbb>; regmap-efuse = <&efuse>; + regmap-rb = <&rb>; reg = <0x0 0x78800000 0x0 0x100>; interrupts = <0x0 0x20 0x4>, <0x0 0x21 0x4>, @@ -76,4 +99,14 @@ Example: reg = <0x0 0x7c000000 0x0 0x200000>; pmd-controller = <0>; }; + + edacl3@7e600000 { + compatible = "apm,xgene-edac-l3"; + reg = <0x0 0x7e600000 0x0 0x1000>; + }; + + edacsoc@7e930000 { + compatible = "apm,xgene-edac-soc-v1"; + reg = <0x0 0x7e930000 0x0 0x1000>; + }; }; diff --git a/Documentation/devicetree/bindings/eeprom.txt b/Documentation/devicetree/bindings/eeprom.txt deleted file mode 100644 index 4342c10de1bf..000000000000 --- a/Documentation/devicetree/bindings/eeprom.txt +++ /dev/null @@ -1,28 +0,0 @@ -EEPROMs (I2C) - -Required properties: - - - compatible : should be "<manufacturer>,<type>" - If there is no specific driver for <manufacturer>, a generic - driver based on <type> is selected. 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 - -Example: - -eeprom@52 { - compatible = "atmel,24c32"; - reg = <0x52>; - pagesize = <32>; -}; diff --git a/Documentation/devicetree/bindings/misc/at25.txt b/Documentation/devicetree/bindings/eeprom/at25.txt index 1d3447165c37..1d3447165c37 100644 --- a/Documentation/devicetree/bindings/misc/at25.txt +++ b/Documentation/devicetree/bindings/eeprom/at25.txt diff --git a/Documentation/devicetree/bindings/eeprom/eeprom.txt b/Documentation/devicetree/bindings/eeprom/eeprom.txt new file mode 100644 index 000000000000..735bc94444bb --- /dev/null +++ b/Documentation/devicetree/bindings/eeprom/eeprom.txt @@ -0,0 +1,39 @@ +EEPROMs (I2C) + +Required properties: + + - compatible : should be "<manufacturer>,<type>", 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" + + "ramtron,24c64" + + "renesas,r1ex24002" + + If there is no specific driver for <manufacturer>, a generic + driver based on <type> is selected. 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 + +Example: + +eeprom@52 { + compatible = "atmel,24c32"; + reg = <0x52>; + pagesize = <32>; +}; diff --git a/Documentation/devicetree/bindings/extcon/extcon-arizona.txt b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt new file mode 100644 index 000000000000..e27341f8a4c7 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/extcon-arizona.txt @@ -0,0 +1,75 @@ +Cirrus Logic Arizona class audio SoCs + +These devices are audio SoCs with extensive digital capabilities and a range +of analogue I/O. + +This document lists Extcon specific bindings, see the primary binding document: + ../mfd/arizona.txt + +Optional properties: + + - wlf,hpdet-channel : Headphone detection channel. + ARIZONA_ACCDET_MODE_HPL or 1 - Headphone detect mode is set to HPDETL + ARIZONA_ACCDET_MODE_HPR or 2 - Headphone detect mode is set to HPDETR + If this node is not mentioned or if the value is unknown, then + headphone detection mode is set to HPDETL. + + - wlf,use-jd2 : Use the additional JD input along with JD1 for dual pin jack + detection. + - wlf,use-jd2-nopull : Internal pull on JD2 is disabled when used for + jack detection. + - wlf,jd-invert : Invert the polarity of the jack detection switch + + - wlf,micd-software-compare : Use a software comparison to determine mic + presence + - wlf,micd-detect-debounce : Additional software microphone detection + debounce specified in milliseconds. + - wlf,micd-pol-gpio : GPIO specifier for the GPIO controlling the headset + polarity if one exists. + - wlf,micd-bias-start-time : Time allowed for MICBIAS to startup prior to + performing microphone detection, specified as per the ARIZONA_MICD_TIME_XXX + defines. + - wlf,micd-rate : Delay between successive microphone detection measurements, + specified as per the ARIZONA_MICD_TIME_XXX defines. + - wlf,micd-dbtime : Microphone detection hardware debounces specified as the + number of measurements to take, valid values being 2 and 4. + - wlf,micd-timeout-ms : Timeout for microphone detection, specified in + milliseconds. + - wlf,micd-force-micbias : Force MICBIAS continuously on during microphone + detection. + - wlf,micd-configs : Headset polarity configurations (generally used for + detection of CTIA / OMTP headsets), the field can be of variable length + but should always be a multiple of 3 cells long, each three cell group + represents one polarity configuration. + The first cell defines the accessory detection pin, zero will use MICDET1 + and all other values will use MICDET2. + The second cell represents the MICBIAS to be used. + The third cell represents the value of the micd-pol-gpio pin. + + - wlf,gpsw : Settings for the general purpose switch + +Example: + +codec: wm8280@0 { + compatible = "wlf,wm8280"; + reg = <0>; + ... + + wlf,use-jd2; + wlf,use-jd2-nopull; + wlf,jd-invert; + + wlf,micd-software-compare; + wlf,micd-detect-debounce = <0>; + wlf,micd-pol-gpio = <&codec 2 0>; + wlf,micd-rate = <ARIZONA_MICD_TIME_8MS>; + wlf,micd-dbtime = <4>; + wlf,micd-timeout-ms = <100>; + wlf,micd-force-micbias; + wlf,micd-configs = < + 0 1 0 /* MICDET1 MICBIAS1 GPIO=low */ + 1 2 1 /* MICDET2 MICBIAS2 GPIO=high */ + >; + + wlf,gpsw = <0>; +}; diff --git a/Documentation/devicetree/bindings/extcon/extcon-max3355.txt b/Documentation/devicetree/bindings/extcon/extcon-max3355.txt new file mode 100644 index 000000000000..f2288ea9eb82 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/extcon-max3355.txt @@ -0,0 +1,21 @@ +Maxim Integrated MAX3355 USB OTG chip +------------------------------------- + +MAX3355 integrates a charge pump and comparators to enable a system with an +integrated USB OTG dual-role transceiver to function as a USB OTG dual-role +device. + +Required properties: +- compatible: should be "maxim,max3355"; +- maxim,shdn-gpios: should contain a phandle and GPIO specifier for the GPIO pin + connected to the MAX3355's SHDN# pin; +- id-gpios: should contain a phandle and GPIO specifier for the GPIO pin + connected to the MAX3355's ID_OUT pin. + +Example: + + usb-otg { + compatible = "maxim,max3355"; + maxim,shdn-gpios = <&gpio2 4 GPIO_ACTIVE_LOW>; + id-gpios = <&gpio5 31 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt index 9b027a615486..d52f3340414d 100644 --- a/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt +++ b/Documentation/devicetree/bindings/fpga/altera-socfpga-fpga-mgr.txt @@ -9,7 +9,7 @@ Required properties: Example: - hps_0_fpgamgr: fpgamgr@0xff706000 { + hps_0_fpgamgr: fpgamgr@ff706000 { compatible = "altr,socfpga-fpga-mgr"; reg = <0xFF706000 0x1000 0xFFB90000 0x1000>; diff --git a/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.txt new file mode 100644 index 000000000000..7018aa896835 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/xilinx-zynq-fpga-mgr.txt @@ -0,0 +1,19 @@ +Xilinx Zynq FPGA Manager + +Required properties: +- compatible: should contain "xlnx,zynq-devcfg-1.0" +- reg: base address and size for memory mapped io +- interrupts: interrupt for the FPGA manager device +- clocks: phandle for clocks required operation +- clock-names: name for the clock, should be "ref_clk" +- syscon: phandle for access to SLCR registers + +Example: + devcfg: devcfg@f8007000 { + compatible = "xlnx,zynq-devcfg-1.0"; + reg = <0xf8007000 0x100>; + interrupts = <0 8 4>; + clocks = <&clkc 12>; + clock-names = "ref_clk"; + syscon = <&slcr>; + }; diff --git a/Documentation/devicetree/bindings/goldfish/audio.txt b/Documentation/devicetree/bindings/goldfish/audio.txt new file mode 100644 index 000000000000..d043fda433ba --- /dev/null +++ b/Documentation/devicetree/bindings/goldfish/audio.txt @@ -0,0 +1,17 @@ +Android Goldfish Audio + +Android goldfish audio device generated by android emulator. + +Required properties: + +- compatible : should contain "google,goldfish-audio" to match emulator +- reg : <registers mapping> +- interrupts : <interrupt mapping> + +Example: + + goldfish_audio@9030000 { + compatible = "google,goldfish-audio"; + reg = <0x9030000 0x100>; + interrupts = <0x4>; + }; diff --git a/Documentation/devicetree/bindings/goldfish/battery.txt b/Documentation/devicetree/bindings/goldfish/battery.txt new file mode 100644 index 000000000000..4fb613933214 --- /dev/null +++ b/Documentation/devicetree/bindings/goldfish/battery.txt @@ -0,0 +1,17 @@ +Android Goldfish Battery + +Android goldfish battery device generated by android emulator. + +Required properties: + +- compatible : should contain "google,goldfish-battery" to match emulator +- reg : <registers mapping> +- interrupts : <interrupt mapping> + +Example: + + goldfish_battery@9020000 { + compatible = "google,goldfish-battery"; + reg = <0x9020000 0x1000>; + interrupts = <0x3>; + }; diff --git a/Documentation/devicetree/bindings/goldfish/events.txt b/Documentation/devicetree/bindings/goldfish/events.txt new file mode 100644 index 000000000000..5babf46317a4 --- /dev/null +++ b/Documentation/devicetree/bindings/goldfish/events.txt @@ -0,0 +1,17 @@ +Android Goldfish Events Keypad + +Android goldfish events keypad device generated by android emulator. + +Required properties: + +- compatible : should contain "google,goldfish-events-keypad" to match emulator +- reg : <registers mapping> +- interrupts : <interrupt mapping> + +Example: + + goldfish-events@9040000 { + compatible = "google,goldfish-events-keypad"; + reg = <0x9040000 0x1000>; + interrupts = <0x5>; + }; diff --git a/Documentation/devicetree/bindings/goldfish/pipe.txt b/Documentation/devicetree/bindings/goldfish/pipe.txt new file mode 100644 index 000000000000..e417a31a1ee3 --- /dev/null +++ b/Documentation/devicetree/bindings/goldfish/pipe.txt @@ -0,0 +1,17 @@ +Android Goldfish QEMU Pipe + +Andorid pipe virtual device generated by android emulator. + +Required properties: + +- compatible : should contain "google,android-pipe" to match emulator +- reg : <registers mapping> +- interrupts : <interrupt mapping> + +Example: + + android_pipe@a010000 { + compatible = "google,android-pipe"; + reg = <ff018000 0x2000>; + interrupts = <0x12>; + }; diff --git a/Documentation/devicetree/bindings/goldfish/tty.txt b/Documentation/devicetree/bindings/goldfish/tty.txt new file mode 100644 index 000000000000..82648278da77 --- /dev/null +++ b/Documentation/devicetree/bindings/goldfish/tty.txt @@ -0,0 +1,17 @@ +Android Goldfish TTY + +Android goldfish tty device generated by android emulator. + +Required properties: + +- compatible : should contain "google,goldfish-tty" to match emulator +- reg : <registers mapping> +- interrupts : <interrupt mapping> + +Example: + + goldfish_tty@1f004000 { + compatible = "google,goldfish-tty"; + reg = <0x1f004000 0x1000>; + interrupts = <0xc>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-altera.txt b/Documentation/devicetree/bindings/gpio/gpio-altera.txt index 12f50149e1ed..826a7208ca93 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-altera.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-altera.txt @@ -12,7 +12,7 @@ Required properties: - #interrupt-cells : Should be 1. The interrupt type is fixed in the hardware. - The first cell is the GPIO offset number within the GPIO controller. - interrupts: Specify the interrupt. -- altr,interrupt-trigger: Specifies the interrupt trigger type the GPIO +- altr,interrupt-type: Specifies the interrupt trigger type the GPIO hardware is synthesized. This field is required if the Altera GPIO controller used has IRQ enabled as the interrupt type is not software controlled, but hardware synthesized. Required if GPIO is used as an interrupt @@ -35,7 +35,7 @@ gpio_altr: gpio@0xff200000 { reg = <0xff200000 0x10>; interrupts = <0 45 4>; altr,ngpio = <32>; - altr,interrupt-trigger = <IRQ_TYPE_EDGE_RISING>; + altr,interrupt-type = <IRQ_TYPE_EDGE_RISING>; #gpio-cells = <2>; gpio-controller; #interrupt-cells = <1>; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt b/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt index f3332b9a8ed4..c934106b10aa 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt @@ -10,6 +10,7 @@ Required properties: - "microchip,mcp23s08" for 8 GPIO SPI version - "microchip,mcp23s17" for 16 GPIO SPI version + - "microchip,mcp23s18" for 16 GPIO SPI version - "microchip,mcp23008" for 8 GPIO I2C version or - "microchip,mcp23017" for 16 GPIO I2C version of the chip NOTE: Do not use the old mcp prefix any more. It is deprecated and will be @@ -43,9 +44,6 @@ Optional properties: - first cell is the pin number - second cell is used to specify flags. - interrupt-controller: Marks the device node as a interrupt controller. -NOTE: The interrupt functionality is only supported for i2c versions of the -chips. The spi chips can also do the interrupts, but this is not supported by -the linux driver yet. Optional device specific properties: - microchip,irq-mirror: Sets the mirror flag in the IOCON register. Devices diff --git a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt index 805ddcd79a57..120bc4971cf3 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mpc8xxx.txt @@ -1,9 +1,9 @@ -* Freescale MPC512x/MPC8xxx GPIO controller +* Freescale MPC512x/MPC8xxx/Layerscape GPIO controller Required properties: - compatible : Should be "fsl,<soc>-gpio" The following <soc>s are known to be supported: - mpc5121, mpc5125, mpc8349, mpc8572, mpc8610, pq3, qoriq + mpc5121, mpc5125, mpc8349, mpc8572, mpc8610, pq3, qoriq. - reg : Address and length of the register set for the device - interrupts : Should be the port interrupt shared by all 32 pins. - #gpio-cells : Should be two. The first cell is the pin number and @@ -11,6 +11,10 @@ Required properties: 0 = active high 1 = active low +Optional properties: +- little-endian : GPIO registers are used as little endian. If not + present registers are used as big endian by default. + Example: gpio0: gpio@1100 { diff --git a/Documentation/devicetree/bindings/gpio/gpio-msm.txt b/Documentation/devicetree/bindings/gpio/gpio-msm.txt deleted file mode 100644 index ac20e68a004e..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-msm.txt +++ /dev/null @@ -1,26 +0,0 @@ -MSM GPIO controller bindings - -Required properties: -- compatible: - - "qcom,msm-gpio" for MSM controllers -- #gpio-cells : Should be two. - - first cell is the pin number - - second cell is used to specify optional parameters (unused) -- gpio-controller : Marks the device node as a GPIO controller. -- #interrupt-cells : Should be 2. -- interrupt-controller: Mark the device node as an interrupt controller -- interrupts : Specify the TLMM summary interrupt number -- ngpio : Specify the number of MSM GPIOs - -Example: - - msmgpio: gpio@fd510000 { - compatible = "qcom,msm-gpio"; - gpio-controller; - #gpio-cells = <2>; - interrupt-controller; - #interrupt-cells = <2>; - reg = <0xfd510000 0x4000>; - interrupts = <0 208 0>; - ngpio = <150>; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index b9a42f294dd0..6b4a98f74be3 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -24,6 +24,8 @@ Required properties: ti,tca6408 ti,tca6416 ti,tca6424 + ti,tca9539 + onsemi,pca9654 exar,xra1202 Example: diff --git a/Documentation/devicetree/bindings/gpio/gpio-pisosr.txt b/Documentation/devicetree/bindings/gpio/gpio-pisosr.txt new file mode 100644 index 000000000000..414a01cdf715 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-pisosr.txt @@ -0,0 +1,34 @@ +Generic Parallel-in/Serial-out Shift Register GPIO Driver + +This binding describes generic parallel-in/serial-out shift register +devices that can be used for GPI (General Purpose Input). This includes +SN74165 serial-out shift registers and the SN65HVS88x series of +industrial serializers. + +Required properties: + - compatible : Should be "pisosr-gpio". + - gpio-controller : Marks the device node as a GPIO controller. + - #gpio-cells : Should be two. For consumer use see gpio.txt. + +Optional properties: + - ngpios : Number of used GPIO lines (0..n-1), default is 8. + - load-gpios : GPIO pin specifier attached to load enable, this + pin is pulsed before reading from the device to + load input pin values into the the device. + +For other required and optional properties of SPI slave +nodes please refer to ../spi/spi-bus.txt. + +Example: + + gpio@0 { + compatible = "ti,sn65hvs882", "pisosr-gpio"; + gpio-controller; + #gpio-cells = <2>; + + load-gpios = <&gpio2 23 GPIO_ACTIVE_LOW>; + + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt b/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt index ba2bb84eeac3..c809acb9c71b 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-sx150x.txt @@ -5,7 +5,8 @@ Required properties: - compatible: should be "semtech,sx1506q", "semtech,sx1508q", - "semtech,sx1509q". + "semtech,sx1509q", + "semtech,sx1502q". - reg: The I2C slave address for this device. diff --git a/Documentation/devicetree/bindings/gpio/gpio-tps65086.txt b/Documentation/devicetree/bindings/gpio/gpio-tps65086.txt new file mode 100644 index 000000000000..ba051074bedc --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-tps65086.txt @@ -0,0 +1,16 @@ +* TPS65086 GPO Controller bindings + +Required properties: + - compatible : Should be "ti,tps65086-gpio". + - 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 cell is used to specify flags. + See ../gpio/gpio.txt for possible values. + +Example: + + gpio4: gpio { + compatible = "ti,tps65086-gpio"; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-ts4800.txt b/Documentation/devicetree/bindings/gpio/gpio-ts4800.txt new file mode 100644 index 000000000000..92ea9c8f6399 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-ts4800.txt @@ -0,0 +1,20 @@ +* TS-4800 FPGA's GPIO controller bindings + +Required properties: +- compatible: Must be "technologic,ts4800-gpio". +- #gpio-cells: Should be two. The first cell is the pin number. +- reg: Physical base address of the controller and length + of memory mapped region. + +Optional property: +- ngpios: See "gpio.txt" + +Example: + +gpio1: gpio { + compatible = "technologic,ts4800-gpio"; + reg = <0x10020 0x6>; + ngpios = <8>; + gpio-controller; + #gpio-cells = <2>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt index dae130060537..5490c1d68981 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-xgene-sb.txt @@ -1,10 +1,20 @@ APM X-Gene Standby GPIO controller bindings -This is a gpio controller in the standby domain. - -There are 20 GPIO pins from 0..21. There is no GPIO_DS14 or GPIO_DS15, -only GPIO_DS8..GPIO_DS13 support interrupts. The IRQ mapping -is currently 1-to-1 on interrupts 0x28 thru 0x2d. +This is a gpio controller in the standby domain. It also supports interrupt in +some particular pins which are sourced to its parent interrupt controller +as diagram below: + +-----------------+ + | X-Gene standby | + | GPIO controller +------ GPIO_0 ++------------+ | | ... +| Parent IRQ | EXT_INT_0 | +------ GPIO_8/EXT_INT_0 +| controller | (SPI40) | | ... +| (GICv2) +--------------+ +------ GPIO_[N+8]/EXT_INT_N +| | ... | | +| | EXT_INT_N | +------ GPIO_[N+9] +| | (SPI[40 + N])| | ... +| +--------------+ +------ GPIO_MAX ++------------+ +-----------------+ Required properties: - compatible: "apm,xgene-gpio-sb" for the X-Gene Standby GPIO controller @@ -15,10 +25,18 @@ Required properties: 0 = active high 1 = active low - gpio-controller: Marks the device node as a GPIO controller. -- interrupts: Shall contain exactly 6 interrupts. +- interrupts: The EXT_INT_0 parent interrupt resource must be listed first. +- interrupt-parent: Phandle of the parent interrupt controller. +- interrupt-cells: Should be two. + - first cell is 0-N coresponding for EXT_INT_0 to EXT_INT_N. + - second cell is used to specify flags. +- interrupt-controller: Marks the device node as an interrupt controller. +- apm,nr-gpios: Optional, specify number of gpios pin. +- apm,nr-irqs: Optional, specify number of interrupt pins. +- apm,irq-start: Optional, specify lowest gpio pin support interrupt. Example: - sbgpio: sbgpio@17001000 { + sbgpio: gpio@17001000{ compatible = "apm,xgene-gpio-sb"; reg = <0x0 0x17001000 0x0 0x400>; #gpio-cells = <2>; @@ -29,4 +47,19 @@ Example: <0x0 0x2b 0x1>, <0x0 0x2c 0x1>, <0x0 0x2d 0x1>; + interrupt-parent = <&gic>; + #interrupt-cells = <2>; + interrupt-controller; + apm,nr-gpios = <22>; + apm,nr-irqs = <6>; + apm,irq-start = <8>; + }; + + testuser { + compatible = "example,testuser"; + /* Use the GPIO_13/EXT_INT_5 line as an active high triggered + * level interrupt + */ + interrupts = <5 4>; + interrupt-parent = <&sbgpio>; }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt index db4c6a663c03..7b542657f259 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt @@ -12,6 +12,13 @@ Required properties: - interrupts : Interrupt specifier (see interrupt bindings for details) - interrupt-parent : Must be core interrupt controller +- interrupt-controller : Marks the device node as an interrupt controller. +- #interrupt-cells : Should be 2. The first cell is the GPIO number. + The second cell bits[3:0] is used to specify trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. - reg : Address and length of the register set for the device Example: @@ -22,5 +29,7 @@ Example: gpio-controller; interrupt-parent = <&intc>; interrupts = <0 20 4>; + interrupt-controller; + #interrupt-cells = <2>; reg = <0xe000a000 0x1000>; }; diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 82d40e2505f6..069cdf6f9dac 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -54,9 +54,13 @@ only uses one. gpio-specifier may encode: bank, pin position inside the bank, whether pin is open-drain and whether pin is logically inverted. + Exact meaning of each specifier cell is controller specific, and must -be documented in the device tree binding for the device. Use the macros -defined in include/dt-bindings/gpio/gpio.h whenever possible: +be documented in the device tree binding for the device. + +Most controllers are however specifying a generic flag bitfield +in the last cell, so for these, use the macros defined in +include/dt-bindings/gpio/gpio.h whenever possible: Example of a node using GPIOs: @@ -67,6 +71,15 @@ Example of a node using GPIOs: GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. +Optional standard bitfield specifiers for the last cell: + +- Bit 0: 0 means active high, 1 means active low +- Bit 1: 1 means single-ended wiring, see: + https://en.wikipedia.org/wiki/Single-ended_triode + When used with active-low, this means open drain/collector, see: + https://en.wikipedia.org/wiki/Open_collector + When used with active-high, this means open source/emitter + 1.1) GPIO specifier best practices ---------------------------------- @@ -118,6 +131,30 @@ Every GPIO controller node must contain both an empty "gpio-controller" property, and a #gpio-cells integer property, which indicates the number of cells in a gpio-specifier. +Optionally, a GPIO controller may have a "ngpios" property. This property +indicates the number of in-use slots of available slots for GPIOs. The +typical example is something like this: the hardware register is 32 bits +wide, but only 18 of the bits have a physical counterpart. The driver is +generally written so that all 32 bits can be used, but the IP block is reused +in a lot of designs, some using all 32 bits, some using 18 and some using +12. In this case, setting "ngpios = <18>;" informs the driver that only the +first 18 GPIOs, at local offset 0 .. 17, are in use. + +If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an +additional bitmask is needed to specify which GPIOs are actually in use, +and which are dummies. The bindings for this case has not yet been +specified, but should be specified if/when such hardware appears. + +Example: + +gpio-controller@00000000 { + compatible = "foo"; + reg = <0x00000000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + ngpios = <18>; +} + The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism providing automatic GPIO request and configuration as part of the gpio-controller's driver probe function. diff --git a/Documentation/devicetree/bindings/gpio/microchip,pic32-gpio.txt b/Documentation/devicetree/bindings/gpio/microchip,pic32-gpio.txt new file mode 100644 index 000000000000..ef3752889496 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/microchip,pic32-gpio.txt @@ -0,0 +1,49 @@ +* Microchip PIC32 GPIO devices (PIO). + +Required properties: + - compatible: "microchip,pic32mzda-gpio" + - reg: Base address and length for the device. + - interrupts: The port interrupt shared by all pins. + - gpio-controller: Marks the port as GPIO controller. + - #gpio-cells: Two. The first cell is the pin number and + the second cell is used to specify the gpio polarity as defined in + defined in <dt-bindings/gpio/gpio.h>: + 0 = GPIO_ACTIVE_HIGH + 1 = GPIO_ACTIVE_LOW + 2 = GPIO_OPEN_DRAIN + - interrupt-controller: Marks the device node as an interrupt controller. + - #interrupt-cells: Two. The first cell is the GPIO number and second cell + is used to specify the trigger type as defined in + <dt-bindings/interrupt-controller/irq.h>: + IRQ_TYPE_EDGE_RISING + IRQ_TYPE_EDGE_FALLING + IRQ_TYPE_EDGE_BOTH + - clocks: Clock specifier (see clock bindings for details). + - microchip,gpio-bank: Specifies which bank a controller owns. + - gpio-ranges: Interaction with the PINCTRL subsystem. + +Example: + +/* PORTA */ +gpio0: gpio0@1f860000 { + compatible = "microchip,pic32mzda-gpio"; + reg = <0x1f860000 0x100>; + interrupts = <118 IRQ_TYPE_LEVEL_HIGH>; + #gpio-cells = <2>; + gpio-controller; + interrupt-controller; + #interrupt-cells = <2>; + clocks = <&PBCLK4>; + microchip,gpio-bank = <0>; + gpio-ranges = <&pic32_pinctrl 0 0 16>; +}; + +keys { + ... + + button@sw1 { + label = "ESC"; + linux,code = <1>; + gpios = <&gpio0 12 0>; + }; +}; diff --git a/Documentation/devicetree/bindings/gpio/netxbig-gpio-ext.txt b/Documentation/devicetree/bindings/gpio/netxbig-gpio-ext.txt new file mode 100644 index 000000000000..50ec2e690701 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/netxbig-gpio-ext.txt @@ -0,0 +1,22 @@ +Binding for the GPIO extension bus found on some LaCie/Seagate boards +(Example: 2Big/5Big Network v2, 2Big NAS). + +Required properties: +- compatible: "lacie,netxbig-gpio-ext". +- addr-gpios: GPIOs representing the address register (LSB -> MSB). +- data-gpios: GPIOs representing the data register (LSB -> MSB). +- enable-gpio: latches the new configuration (address, data) on raising edge. + +Example: + +netxbig_gpio_ext: netxbig-gpio-ext { + compatible = "lacie,netxbig-gpio-ext"; + + addr-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH + &gpio1 16 GPIO_ACTIVE_HIGH + &gpio1 17 GPIO_ACTIVE_HIGH>; + data-gpios = <&gpio1 12 GPIO_ACTIVE_HIGH + &gpio1 13 GPIO_ACTIVE_HIGH + &gpio1 14 GPIO_ACTIVE_HIGH>; + enable-gpio = <&gpio0 29 GPIO_ACTIVE_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt index dd5d2c0394b1..4d6c8cdc8586 100644 --- a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt @@ -24,7 +24,7 @@ controller. - #interrupt-cells : Specifies the number of cells needed to encode an interrupt. Shall be set to 2. The first cell defines the interrupt number, the second encodes the triger flags encoded as described in - Documentation/devicetree/bindings/interrupts.txt + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - interrupt-parent : The parent interrupt controller. - interrupts : The interrupt to the parent controller raised when GPIOs generate the interrupts. diff --git a/Documentation/devicetree/bindings/hsi/nokia-modem.txt b/Documentation/devicetree/bindings/hsi/nokia-modem.txt index 8a979780452b..53de1d9d0b95 100644 --- a/Documentation/devicetree/bindings/hsi/nokia-modem.txt +++ b/Documentation/devicetree/bindings/hsi/nokia-modem.txt @@ -7,6 +7,8 @@ properties are needed by the Nokia modem HSI client: Required properties: - compatible: Should be one of "nokia,n900-modem" + "nokia,n950-modem" + "nokia,n9-modem" - hsi-channel-names: Should contain the following strings "mcsaab-control" "speech-control" @@ -15,11 +17,11 @@ Required properties: - gpios: Should provide a GPIO handler for each GPIO listed in gpio-names - gpio-names: Should contain the following strings - "cmt_apeslpx" - "cmt_rst_rq" - "cmt_en" - "cmt_rst" - "cmt_bsi" + "cmt_apeslpx" (for n900, n950, n9) + "cmt_rst_rq" (for n900, n950, n9) + "cmt_en" (for n900, n950, n9) + "cmt_rst" (for n900) + "cmt_bsi" (for n900) - interrupts: Should be IRQ handle for modem's reset indication Example: diff --git a/Documentation/devicetree/bindings/hwmon/ina209.txt b/Documentation/devicetree/bindings/hwmon/ina209.txt deleted file mode 100644 index 9dd2bee80840..000000000000 --- a/Documentation/devicetree/bindings/hwmon/ina209.txt +++ /dev/null @@ -1,18 +0,0 @@ -ina209 properties - -Required properties: -- compatible: Must be "ti,ina209" -- reg: I2C address - -Optional properties: - -- shunt-resistor - Shunt resistor value in micro-Ohm - -Example: - -temp-sensor@4c { - compatible = "ti,ina209"; - reg = <0x4c>; - shunt-resistor = <5000>; -}; diff --git a/Documentation/devicetree/bindings/hwmon/ina2xx.txt b/Documentation/devicetree/bindings/hwmon/ina2xx.txt index a2ad85d7e747..9bcd5e87830d 100644 --- a/Documentation/devicetree/bindings/hwmon/ina2xx.txt +++ b/Documentation/devicetree/bindings/hwmon/ina2xx.txt @@ -2,6 +2,7 @@ ina2xx properties Required properties: - compatible: Must be one of the following: + - "ti,ina209" for ina209 - "ti,ina219" for ina219 - "ti,ina220" for ina220 - "ti,ina226" for ina226 diff --git a/Documentation/devicetree/bindings/hwmon/nsa320-mcu.txt b/Documentation/devicetree/bindings/hwmon/nsa320-mcu.txt new file mode 100644 index 000000000000..0863e067c85b --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/nsa320-mcu.txt @@ -0,0 +1,20 @@ +Bindings for the fan / temperature monitor microcontroller used on +the Zyxel NSA 320 and several subsequent models. + +Required properties: +- compatible : "zyxel,nsa320-mcu" +- data-gpios : The GPIO pin connected to the data line on the MCU +- clk-gpios : The GPIO pin connected to the clock line on the MCU +- act-gpios : The GPIO pin connected to the active line on the MCU + +Example: + + hwmon { + compatible = "zyxel,nsa320-mcu"; + pinctrl-0 = <&pmx_mcu_data &pmx_mcu_clk &pmx_mcu_act>; + pinctrl-names = "default"; + + data-gpios = <&gpio0 14 GPIO_ACTIVE_HIGH>; + clk-gpios = <&gpio0 16 GPIO_ACTIVE_HIGH>; + act-gpios = <&gpio0 17 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt index a04a80f9cc70..c3b9c4cfe8df 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt +++ b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt @@ -10,6 +10,7 @@ Requires node properties: "murata,ncp03wb473" "murata,ncp15wl333" "murata,ncp03wf104" + "murata,ncp15xh103" /* Usage of vendor name "ntc" is deprecated */ <DEPRECATED> "ntc,ncp15wb473" diff --git a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt index 610757ce4492..c6d533202d3e 100644 --- a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt @@ -3,10 +3,35 @@ Bindings for a fan connected to the PWM lines Required properties: - compatible : "pwm-fan" - pwms : the PWM that is used to control the PWM fan +- cooling-levels : PWM duty cycle values in a range from 0 to 255 + which correspond to thermal cooling states Example: - pwm-fan { + fan0: pwm-fan { compatible = "pwm-fan"; - status = "okay"; + cooling-min-state = <0>; + cooling-max-state = <3>; + #cooling-cells = <2>; pwms = <&pwm 0 10000 0>; + cooling-levels = <0 102 170 230>; }; + + thermal-zones { + cpu_thermal: cpu-thermal { + thermal-sensors = <&tmu 0>; + polling-delay-passive = <0>; + polling-delay = <0>; + trips { + cpu_alert1: cpu-alert1 { + temperature = <100000>; /* millicelsius */ + hysteresis = <2000>; /* millicelsius */ + type = "passive"; + }; + }; + cooling-maps { + map0 { + trip = <&cpu_alert1>; + cooling-device = <&fan0 0 1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-at91.txt b/Documentation/devicetree/bindings/i2c/i2c-at91.txt index 6e81dc153f3b..ef973a0343c7 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-at91.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-at91.txt @@ -3,7 +3,7 @@ I2C for Atmel platforms Required properties : - compatible : Must be "atmel,at91rm9200-i2c", "atmel,at91sam9261-i2c", "atmel,at91sam9260-i2c", "atmel,at91sam9g20-i2c", "atmel,at91sam9g10-i2c", - "atmel,at91sam9x5-i2c" or "atmel,sama5d2-i2c" + "atmel,at91sam9x5-i2c", "atmel,sama5d4-i2c" or "atmel,sama5d2-i2c" - reg: physical base address of the controller and length of memory mapped region. - interrupts: interrupt number to the cpu. @@ -17,6 +17,8 @@ Optional properties: - dma-names: should contain "tx" and "rx". - atmel,fifo-size: maximum number of data the RX and TX FIFOs can store for FIFO capable I2C controllers. +- i2c-sda-hold-time-ns: TWD hold time, only available for "atmel,sama5d4-i2c" + and "atmel,sama5d2-i2c". - Child nodes conforming to i2c bus binding Examples : @@ -52,6 +54,7 @@ i2c0: i2c@f8034600 { #size-cells = <0>; clocks = <&flx0>; atmel,fifo-size = <16>; + i2c-sda-hold-time-ns = <336>; wm8731: wm8731@1a { compatible = "wm8731"; diff --git a/Documentation/devicetree/bindings/i2c/i2c-brcmstb.txt b/Documentation/devicetree/bindings/i2c/i2c-brcmstb.txt index d6f724efdcf2..aeceaceba3c5 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-brcmstb.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-brcmstb.txt @@ -2,7 +2,7 @@ Broadcom stb bsc iic master controller Required properties: -- compatible: should be "brcm,brcmstb-i2c" +- compatible: should be "brcm,brcmstb-i2c" or "brcm,brcmper-i2c" - clock-frequency: 32-bit decimal value of iic master clock freqency in Hz valid values are 375000, 390000, 187500, 200000 93750, 97500, 46875 and 50000 diff --git a/Documentation/devicetree/bindings/i2c/i2c-davinci.txt b/Documentation/devicetree/bindings/i2c/i2c-davinci.txt index a4e1cbc810c1..5b123e0e4cc2 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-davinci.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-davinci.txt @@ -1,10 +1,10 @@ -* Texas Instruments Davinci I2C +* Texas Instruments Davinci/Keystone I2C This file provides information, what the device node for the -davinci i2c interface contain. +davinci/keystone i2c interface contains. Required properties: -- compatible: "ti,davinci-i2c"; +- compatible: "ti,davinci-i2c" or "ti,keystone-i2c"; - reg : Offset and length of the register set for the device Recommended properties : diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx.txt b/Documentation/devicetree/bindings/i2c/i2c-imx.txt index ce4311d726ae..eab5836ba7f9 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx.txt @@ -14,6 +14,10 @@ Optional properties: The absence of the propoerty indicates the default frequency 100 kHz. - dmas: A list of two dma specifiers, one for each entry in dma-names. - dma-names: should contain "tx" and "rx". +- scl-gpios: specify the gpio related to SCL pin +- sda-gpios: specify the gpio related to SDA pin +- pinctrl: add extra pinctrl to configure i2c pins to gpio function for i2c + bus recovery, call it "gpio" state Examples: @@ -37,4 +41,9 @@ i2c0: i2c@40066000 { /* i2c0 on vf610 */ dmas = <&edma0 0 50>, <&edma0 0 51>; dma-names = "rx","tx"; + pinctrl-names = "default", "gpio"; + pinctrl-0 = <&pinctrl_i2c1>; + pinctrl-1 = <&pinctrl_i2c1_gpio>; + scl-gpios = <&gpio5 26 GPIO_ACTIVE_HIGH>; + sda-gpios = <&gpio5 27 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt index 16b3e07aa98f..95e97223a71c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt @@ -10,6 +10,7 @@ Required properties: "renesas,i2c-r8a7792" "renesas,i2c-r8a7793" "renesas,i2c-r8a7794" + "renesas,i2c-r8a7795" - reg: physical base address of the controller and length of memory mapped region. - interrupts: interrupt specifier. @@ -19,6 +20,10 @@ Optional properties: propoerty indicates the default frequency 100 kHz. - clocks: clock specifier. +- i2c-scl-falling-time-ns: see i2c.txt +- i2c-scl-internal-delay-ns: see i2c.txt +- i2c-scl-rising-time-ns: see i2c.txt + Examples : i2c0: i2c@e6508000 { diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt index 2bfc6e7ed094..214f94c25d37 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt @@ -10,6 +10,7 @@ Required properties: - "renesas,iic-r8a7792" (R-Car V2H) - "renesas,iic-r8a7793" (R-Car M2-N) - "renesas,iic-r8a7794" (R-Car E2) + - "renesas,iic-r8a7795" (R-Car H3) - "renesas,iic-sh73a0" (SH-Mobile AG5) - reg : address start and address range size of device - interrupts : interrupt of device diff --git a/Documentation/devicetree/bindings/i2c/i2c-uniphier-f.txt b/Documentation/devicetree/bindings/i2c/i2c-uniphier-f.txt new file mode 100644 index 000000000000..27fc6f8c798b --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-uniphier-f.txt @@ -0,0 +1,25 @@ +UniPhier I2C controller (FIFO-builtin) + +Required properties: +- compatible: should be "socionext,uniphier-fi2c". +- #address-cells: should be 1. +- #size-cells: should be 0. +- reg: offset and length of the register set for the device. +- interrupts: a single interrupt specifier. +- clocks: phandle to the input clock. + +Optional properties: +- clock-frequency: desired I2C bus frequency in Hz. The maximum supported + value is 400000. Defaults to 100000 if not specified. + +Examples: + + i2c0: i2c@58780000 { + compatible = "socionext,uniphier-fi2c"; + reg = <0x58780000 0x80>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <0 41 4>; + clocks = <&i2c_clk>; + clock-frequency = <100000>; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-uniphier.txt b/Documentation/devicetree/bindings/i2c/i2c-uniphier.txt new file mode 100644 index 000000000000..26f9d95b3436 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-uniphier.txt @@ -0,0 +1,25 @@ +UniPhier I2C controller (FIFO-less) + +Required properties: +- compatible: should be "socionext,uniphier-i2c". +- #address-cells: should be 1. +- #size-cells: should be 0. +- reg: offset and length of the register set for the device. +- interrupts: a single interrupt specifier. +- clocks: phandle to the input clock. + +Optional properties: +- clock-frequency: desired I2C bus frequency in Hz. The maximum supported + value is 400000. Defaults to 100000 if not specified. + +Examples: + + i2c0: i2c@58400000 { + compatible = "socionext,uniphier-i2c"; + reg = <0x58400000 0x40>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <0 41 1>; + clocks = <&i2c_clk>; + clock-frequency = <100000>; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt index 8a99150ac3a7..c8d977ed847f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c.txt @@ -29,12 +29,38 @@ Optional properties These properties may not be supported by all drivers. However, if a driver wants to support one of the below features, it should adapt the bindings below. -- clock-frequency - frequency of bus clock in Hz. -- wakeup-source - device can be used as a wakeup source. +- clock-frequency + frequency of bus clock in Hz. -- interrupts - interrupts used by the device. -- interrupt-names - "irq" and "wakeup" names are recognized by I2C core, - other names are left to individual drivers. +- i2c-scl-falling-time-ns + Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C + specification. + +- i2c-scl-internal-delay-ns + Number of nanoseconds the IP core additionally needs to setup SCL. + +- i2c-scl-rising-time-ns + Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C + specification. + +- i2c-sda-falling-time-ns + Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C + specification. + +- interrupts + interrupts used by the device. + +- interrupt-names + "irq" and "wakeup" names are recognized by I2C core, other names are + left to individual drivers. + +- multi-master + states that there is another master active on this bus. The OS can use + this information to adapt power management to keep the arbitration awake + all the time, for example. + +- wakeup-source + device can be used as a wakeup source. Binding may contain optional "interrupts" property, describing interrupts used by the device. I2C core will assign "irq" interrupt (or the very first diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index d77d412cbc68..539874490492 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -20,22 +20,11 @@ adi,adt7476 +/-1C TDM Extended Temp Range I.C adi,adt7490 +/-1C TDM Extended Temp Range I.C adi,adxl345 Three-Axis Digital Accelerometer adi,adxl346 Three-Axis Digital Accelerometer (backward-compatibility value "adi,adxl345" must be listed too) +ams,iaq-core AMS iAQ-Core VOC Sensor at,24c08 i2c serial eeprom (24cxx) -atmel,24c00 i2c serial eeprom (24cxx) -atmel,24c01 i2c serial eeprom (24cxx) -atmel,24c02 i2c serial eeprom (24cxx) -atmel,24c04 i2c serial eeprom (24cxx) -atmel,24c16 i2c serial eeprom (24cxx) -atmel,24c32 i2c serial eeprom (24cxx) -atmel,24c64 i2c serial eeprom (24cxx) -atmel,24c128 i2c serial eeprom (24cxx) -atmel,24c256 i2c serial eeprom (24cxx) -atmel,24c512 i2c serial eeprom (24cxx) -atmel,24c1024 i2c serial eeprom (24cxx) atmel,at97sc3204t i2c trusted platform module (TPM) capella,cm32181 CM32181: Ambient Light Sensor capella,cm3232 CM3232: Ambient Light Sensor -catalyst,24c32 i2c serial eeprom cirrus,cs42l51 Cirrus Logic CS42L51 audio codec dallas,ds1307 64 x 8, Serial, I2C Real-Time Clock dallas,ds1338 I2C RTC with 56-Byte NV RAM @@ -49,12 +38,13 @@ dallas,ds4510 CPU Supervisor with Nonvolatile Memory and Programmable I/O dallas,ds75 Digital Thermometer and Thermostat dlg,da9053 DA9053: flexible system level PMIC with multicore support dlg,da9063 DA9063: system PMIC for quad-core application processors +epson,rx8010 I2C-BUS INTERFACE REAL TIME CLOCK MODULE epson,rx8025 High-Stability. I2C-Bus INTERFACE REAL TIME CLOCK MODULE epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE fsl,mag3110 MAG3110: Xtrinsic High Accuracy, 3D Magnetometer fsl,mc13892 MC13892: Power Management Integrated Circuit (PMIC) for i.MX35/51 fsl,mma8450 MMA8450Q: Xtrinsic Low-power, 3-axis Xtrinsic Accelerometer -fsl,mma8452 MMA8452Q: 3-axis 12-bit / 8-bit Digital Accelerometer +fsl,mpl3115 MPL3115: Absolute Digital Pressure Sensor fsl,mpr121 MPR121: Proximity Capacitive Touch Sensor Controller fsl,sgtl5000 SGTL5000: Ultra Low-Power Audio Codec gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface @@ -80,7 +70,7 @@ oki,ml86v7667 OKI ML86V7667 video decoder ovti,ov5642 OV5642: Color CMOS QSXGA (5-megapixel) Image Sensor with OmniBSI and Embedded TrueFocus pericom,pt7c4338 Real-time Clock Module plx,pex8648 48-Lane, 12-Port PCI Express Gen 2 (5.0 GT/s) Switch -ramtron,24c64 i2c serial eeprom (24cxx) +pulsedlight,lidar-lite-v2 Pulsedlight LIDAR range-finding sensor ricoh,r2025sd I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,r2221tl I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,rs5c372a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC @@ -88,6 +78,7 @@ ricoh,rs5c372b I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,rv5c386 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC ricoh,rv5c387a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC samsung,24ad0xd1 S524AD0XF1 (128K/256K-bit Serial EEPROM for Low Power) +sgx,vz89x SGX Sensortech VZ89X Sensors sii,s35390a 2-wire CMOS real-time clock skyworks,sky81452 Skyworks SKY81452: Six-Channel White LED Driver with Touch Panel Bias Supply st-micro,24c256 i2c serial eeprom (24cxx) diff --git a/Documentation/devicetree/bindings/misc/lis302.txt b/Documentation/devicetree/bindings/iio/accel/lis302.txt index 2a19bff9693f..2a19bff9693f 100644 --- a/Documentation/devicetree/bindings/misc/lis302.txt +++ b/Documentation/devicetree/bindings/iio/accel/lis302.txt diff --git a/Documentation/devicetree/bindings/iio/accel/mma8452.txt b/Documentation/devicetree/bindings/iio/accel/mma8452.txt new file mode 100644 index 000000000000..165937e1ac1c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/mma8452.txt @@ -0,0 +1,32 @@ +Freescale MMA8451Q, MMA8452Q, MMA8453Q, MMA8652FC or MMA8653FC +triaxial accelerometer + +Required properties: + + - compatible: should contain one of + * "fsl,mma8451" + * "fsl,mma8452" + * "fsl,mma8453" + * "fsl,mma8652" + * "fsl,mma8653" + + - reg: the I2C address of the chip + +Optional properties: + + - interrupt-parent: should be the phandle for the interrupt controller + + - interrupts: interrupt mapping for GPIO IRQ + + - interrupt-names: should contain "INT1" and/or "INT2", the accelerometer's + interrupt line in use. + +Example: + + mma8453fc@1d { + compatible = "fsl,mma8453"; + reg = <0x1d>; + interrupt-parent = <&gpio1>; + interrupts = <5 0>; + interrupt-names = "INT2"; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt new file mode 100644 index 000000000000..3223684a643b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/at91-sama5d2_adc.txt @@ -0,0 +1,28 @@ +* AT91 SAMA5D2 Analog to Digital Converter (ADC) + +Required properties: + - compatible: Should be "atmel,sama5d2-adc". + - reg: Should contain ADC registers location and length. + - interrupts: Should contain the IRQ line for the ADC. + - clocks: phandle to device clock. + - clock-names: Must be "adc_clk". + - vref-supply: Supply used as reference for conversions. + - vddana-supply: Supply for the adc device. + - atmel,min-sample-rate-hz: Minimum sampling rate, it depends on SoC. + - atmel,max-sample-rate-hz: Maximum sampling rate, it depends on SoC. + - atmel,startup-time-ms: Startup time expressed in ms, it depends on SoC. + +Example: + +adc: adc@fc030000 { + compatible = "atmel,sama5d2-adc"; + reg = <0xfc030000 0x100>; + interrupts = <40 IRQ_TYPE_LEVEL_HIGH 7>; + clocks = <&adc_clk>; + clock-names = "adc_clk"; + atmel,min-sample-rate-hz = <200000>; + atmel,max-sample-rate-hz = <20000000>; + atmel,startup-time-ms = <4>; + vddana-supply = <&vdd_3v3_lp_reg>; + vref-supply = <&vdd_3v3_lp_reg>; +} diff --git a/Documentation/devicetree/bindings/iio/adc/fsl,imx25-gcq.txt b/Documentation/devicetree/bindings/iio/adc/fsl,imx25-gcq.txt new file mode 100644 index 000000000000..b0866d36a307 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/fsl,imx25-gcq.txt @@ -0,0 +1,58 @@ +Freescale i.MX25 ADC GCQ device + +This is a generic conversion queue device that can convert any of the +analog inputs using the ADC unit of the i.MX25. + +Required properties: + - compatible: Should be "fsl,imx25-gcq". + - reg: Should be the register range of the module. + - interrupts: Should be the interrupt number of the module. + Typically this is <1>. + - interrupt-parent: phandle to the tsadc module of the i.MX25. + - #address-cells: Should be <1> (setting for the subnodes) + - #size-cells: Should be <0> (setting for the subnodes) + +Optional properties: + - vref-ext-supply: The regulator supplying the ADC reference voltage. + Required when at least one subnode uses the this reference. + - vref-xp-supply: The regulator supplying the ADC reference voltage on pin XP. + Required when at least one subnode uses this reference. + - vref-yp-supply: The regulator supplying the ADC reference voltage on pin YP. + Required when at least one subnode uses this reference. + +Sub-nodes: +Optionally you can define subnodes which define the reference voltage +for the analog inputs. + +Required properties for subnodes: + - reg: Should be the number of the analog input. + 0: xp + 1: yp + 2: xn + 3: yn + 4: wiper + 5: inaux0 + 6: inaux1 + 7: inaux2 +Optional properties for subnodes: + - fsl,adc-refp: specifies the positive reference input as defined in + <dt-bindings/iio/adc/fsl-imx25-gcq.h> + - fsl,adc-refn: specifies the negative reference input as defined in + <dt-bindings/iio/adc/fsl-imx25-gcq.h> + +Example: + + adc: adc@50030800 { + compatible = "fsl,imx25-gcq"; + reg = <0x50030800 0x60>; + interrupt-parent = <&tscadc>; + interrupts = <1>; + #address-cells = <1>; + #size-cells = <0>; + + inaux@5 { + reg = <5>; + fsl,adc-refp = <MX25_ADC_REFP_INT>; + fsl,adc-refn = <MX25_ADC_REFN_NGND>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/hi8435.txt b/Documentation/devicetree/bindings/iio/adc/hi8435.txt new file mode 100644 index 000000000000..3b0348c5e516 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/hi8435.txt @@ -0,0 +1,21 @@ +Holt Integrated Circuits HI-8435 threshold detector bindings + +Required properties: + - compatible: should be "holt,hi8435" + - reg: spi chip select number for the device + +Recommended properties: + - spi-max-frequency: definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional properties: + - gpios: GPIO used for controlling the reset pin + +Example: +sensor@0 { + compatible = "holt,hi8435"; + reg = <0>; + gpios = <&gpio6 1 0>; + + spi-max-frequency = <1000000>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/imx7d-adc.txt b/Documentation/devicetree/bindings/iio/adc/imx7d-adc.txt new file mode 100644 index 000000000000..5c184b940669 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/imx7d-adc.txt @@ -0,0 +1,22 @@ +Freescale imx7d ADC bindings + +The devicetree bindings are for the ADC driver written for +imx7d SoC. + +Required properties: +- compatible: Should be "fsl,imx7d-adc" +- reg: Offset and length of the register set for the ADC device +- interrupts: The interrupt number for the ADC device +- clocks: The root clock of the ADC controller +- clock-names: Must contain "adc", matching entry in the clocks property +- vref-supply: The regulator supply ADC reference voltage + +Example: +adc1: adc@30610000 { + compatible = "fsl,imx7d-adc"; + reg = <0x30610000 0x10000>; + interrupts = <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX7D_ADC_ROOT_CLK>; + clock-names = "adc"; + vref-supply = <®_vcc_3v3_mcu>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/mcp320x.txt b/Documentation/devicetree/bindings/iio/adc/mcp320x.txt index 2a1f3af30155..bcd3ac8e6e0c 100644 --- a/Documentation/devicetree/bindings/iio/adc/mcp320x.txt +++ b/Documentation/devicetree/bindings/iio/adc/mcp320x.txt @@ -10,16 +10,28 @@ must be specified. Required properties: - compatible: Must be one of the following, depending on the model: - "mcp3001" - "mcp3002" - "mcp3004" - "mcp3008" - "mcp3201" - "mcp3202" - "mcp3204" - "mcp3208" - "mcp3301" + "mcp3001" (DEPRECATED) + "mcp3002" (DEPRECATED) + "mcp3004" (DEPRECATED) + "mcp3008" (DEPRECATED) + "mcp3201" (DEPRECATED) + "mcp3202" (DEPRECATED) + "mcp3204" (DEPRECATED) + "mcp3208" (DEPRECATED) + "mcp3301" (DEPRECATED) + "microchip,mcp3001" + "microchip,mcp3002" + "microchip,mcp3004" + "microchip,mcp3008" + "microchip,mcp3201" + "microchip,mcp3202" + "microchip,mcp3204" + "microchip,mcp3208" + "microchip,mcp3301" + + NOTE: The use of the compatibles with no vendor prefix + is deprecated and only listed because old DT use them. Examples: spi_controller { diff --git a/Documentation/devicetree/bindings/iio/adc/mcp3422.txt b/Documentation/devicetree/bindings/iio/adc/mcp3422.txt index 333139cc0bfb..82bcce07255d 100644 --- a/Documentation/devicetree/bindings/iio/adc/mcp3422.txt +++ b/Documentation/devicetree/bindings/iio/adc/mcp3422.txt @@ -1,10 +1,12 @@ -* Microchip mcp3422/3/4/6/7/8 chip family (ADC) +* Microchip mcp3421/2/3/4/6/7/8 chip family (ADC) Required properties: - compatible: Should be + "microchip,mcp3421" or "microchip,mcp3422" or "microchip,mcp3423" or "microchip,mcp3424" or + "microchip,mcp3425" or "microchip,mcp3426" or "microchip,mcp3427" or "microchip,mcp3428" diff --git a/Documentation/devicetree/bindings/iio/adc/palmas-gpadc.txt b/Documentation/devicetree/bindings/iio/adc/palmas-gpadc.txt new file mode 100644 index 000000000000..4bb9a86065d1 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/palmas-gpadc.txt @@ -0,0 +1,48 @@ +* Palmas general purpose ADC IP block devicetree bindings + +Channels list: + 0 battery type + 1 battery temp NTC (optional current source) + 2 GP + 3 temp (with ext. diode, optional current source) + 4 GP + 5 GP + 6 VBAT_SENSE + 7 VCC_SENSE + 8 Backup Battery voltage + 9 external charger (VCHG) + 10 VBUS + 11 DC-DC current probe (how does this work?) + 12 internal die temp + 13 internal die temp + 14 USB ID pin voltage + 15 test network + +Required properties: +- compatible : Must be "ti,palmas-gpadc". +- #io-channel-cells: Should be set to <1>. + +Optional sub-nodes: +ti,channel0-current-microamp: Channel 0 current in uA. + Values are rounded to derive 0uA, 5uA, 15uA, 20uA. +ti,channel3-current-microamp: Channel 3 current in uA. + Values are rounded to derive 0uA, 10uA, 400uA, 800uA. +ti,enable-extended-delay: Enable extended delay. + +Example: + +pmic { + compatible = "ti,twl6035-pmic", "ti,palmas-pmic"; + ... + gpadc { + compatible = "ti,palmas-gpadc"; + interrupts = <18 0 + 16 0 + 17 0>; + #io-channel-cells = <1>; + ti,channel0-current-microamp = <5>; + ti,channel3-current-microamp = <10>; + }; + }; + ... +}; diff --git a/Documentation/devicetree/bindings/iio/adc/ti-adc0832.txt b/Documentation/devicetree/bindings/iio/adc/ti-adc0832.txt new file mode 100644 index 000000000000..d91130587d01 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-adc0832.txt @@ -0,0 +1,19 @@ +* Texas Instruments' ADC0831/ADC0832/ADC0832/ADC0838 + +Required properties: + - compatible: Should be one of + * "ti,adc0831" + * "ti,adc0832" + * "ti,adc0834" + * "ti,adc0838" + - reg: spi chip select number for the device + - vref-supply: The regulator supply for ADC reference voltage + - spi-max-frequency: Max SPI frequency to use (< 400000) + +Example: +adc@0 { + compatible = "ti,adc0832"; + reg = <0>; + vref-supply = <&vdd_supply>; + spi-max-frequency = <200000>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt b/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt index 15ca6b47958e..daa2b2c29428 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt +++ b/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt @@ -1,7 +1,7 @@ -* Texas Instruments' ADC128S052 and ADC122S021 ADC chip +* Texas Instruments' ADC128S052, ADC122S021 and ADC124S021 ADC chip Required properties: - - compatible: Should be "ti,adc128s052" or "ti,adc122s021" + - compatible: Should be "ti,adc128s052", "ti,adc122s021" or "ti,adc124s021" - reg: spi chip select number for the device - vref-supply: The regulator supply for ADC reference voltage diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt new file mode 100644 index 000000000000..a02337d7efa4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-ads8688.txt @@ -0,0 +1,20 @@ +* Texas Instruments' ADS8684 and ADS8688 ADC chip + +Required properties: + - compatible: Should be "ti,ads8684" or "ti,ads8688" + - reg: spi chip select number for the device + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional properties: + - vref-supply: The regulator supply for ADC reference voltage + +Example: +adc@0 { + compatible = "ti,ads8688"; + reg = <0>; + vref-supply = <&vdd_supply>; + spi-max-frequency = <1000000>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/atlas,ph-sm.txt b/Documentation/devicetree/bindings/iio/chemical/atlas,ph-sm.txt new file mode 100644 index 000000000000..cffa1907463a --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/atlas,ph-sm.txt @@ -0,0 +1,22 @@ +* Atlas Scientific pH-SM OEM sensor + +http://www.atlas-scientific.com/_files/_datasheets/_oem/pH_oem_datasheet.pdf + +Required properties: + + - compatible: must be "atlas,ph-sm" + - 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 + + Refer to interrupt-controller/interrupts.txt for generic interrupt client + node bindings. + +Example: + +atlas@65 { + compatible = "atlas,ph-sm"; + reg = <0x65>; + interrupt-parent = <&gpio1>; + interrupts = <16 2>; +}; diff --git a/Documentation/devicetree/bindings/misc/ti,dac7512.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7512.txt index 1db45939dac9..1db45939dac9 100644 --- a/Documentation/devicetree/bindings/misc/ti,dac7512.txt +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7512.txt diff --git a/Documentation/devicetree/bindings/iio/dac/vf610-dac.txt b/Documentation/devicetree/bindings/iio/dac/vf610-dac.txt new file mode 100644 index 000000000000..20c6c7ae9687 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/vf610-dac.txt @@ -0,0 +1,20 @@ +Freescale vf610 Digital to Analog Converter bindings + +The devicetree bindings are for the new DAC driver written for +vf610 SoCs from Freescale. + +Required properties: +- compatible: Should contain "fsl,vf610-dac" +- reg: Offset and length of the register set for the device +- interrupts: Should contain the interrupt for the device +- clocks: The clock is needed by the DAC controller +- clock-names: Must contain "dac" matching entry in the clocks property. + +Example: +dac0: dac@400cc000 { + compatible = "fsl,vf610-dac"; + reg = <0x400cc000 0x1000>; + interrupts = <55 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "dac"; + clocks = <&clks VF610_CLK_DAC0>; +}; diff --git a/Documentation/devicetree/bindings/iio/health/afe4403.txt b/Documentation/devicetree/bindings/iio/health/afe4403.txt new file mode 100644 index 000000000000..2fffd70336ba --- /dev/null +++ b/Documentation/devicetree/bindings/iio/health/afe4403.txt @@ -0,0 +1,34 @@ +Texas Instruments AFE4403 Heart rate and Pulse Oximeter + +Required properties: + - compatible : Should be "ti,afe4403". + - reg : SPI chip select address of device. + - tx-supply : Regulator supply to transmitting LEDs. + - interrupt-parent : Phandle to he parent interrupt controller. + - interrupts : The interrupt line the device ADC_RDY pin is + connected to. For details refer to, + ../../interrupt-controller/interrupts.txt. + +Optional properties: + - reset-gpios : GPIO used to reset the device. + For details refer to, ../../gpio/gpio.txt. + +For other required and optional properties of SPI slave nodes +please refer to ../../spi/spi-bus.txt. + +Example: + +&spi0 { + heart_mon@0 { + compatible = "ti,afe4403"; + reg = <0>; + spi-max-frequency = <10000000>; + + tx-supply = <&vbat>; + + interrupt-parent = <&gpio1>; + interrupts = <28 IRQ_TYPE_EDGE_RISING>; + + reset-gpios = <&gpio1 16 GPIO_ACTIVE_LOW>; + }; +}; diff --git a/Documentation/devicetree/bindings/iio/health/afe4404.txt b/Documentation/devicetree/bindings/iio/health/afe4404.txt new file mode 100644 index 000000000000..de69f203edfa --- /dev/null +++ b/Documentation/devicetree/bindings/iio/health/afe4404.txt @@ -0,0 +1,30 @@ +Texas Instruments AFE4404 Heart rate and Pulse Oximeter + +Required properties: + - compatible : Should be "ti,afe4404". + - reg : I2C address of the device. + - tx-supply : Regulator supply to transmitting LEDs. + - interrupt-parent : Phandle to he parent interrupt controller. + - interrupts : The interrupt line the device ADC_RDY pin is + connected to. For details refer to, + ../interrupt-controller/interrupts.txt. + +Optional properties: + - reset-gpios : GPIO used to reset the device. + For details refer to, ../gpio/gpio.txt. + +Example: + +&i2c2 { + heart_mon@58 { + compatible = "ti,afe4404"; + reg = <0x58>; + + tx-supply = <&vbat>; + + interrupt-parent = <&gpio1>; + interrupts = <28 IRQ_TYPE_EDGE_RISING>; + + reset-gpios = <&gpio1 16 GPIO_ACTIVE_LOW>; + }; +}; diff --git a/Documentation/devicetree/bindings/iio/health/max30100.txt b/Documentation/devicetree/bindings/iio/health/max30100.txt new file mode 100644 index 000000000000..295a9edfa4fd --- /dev/null +++ b/Documentation/devicetree/bindings/iio/health/max30100.txt @@ -0,0 +1,29 @@ +Maxim MAX30100 heart rate and pulse oximeter sensor + +* https://datasheets.maximintegrated.com/en/ds/MAX30100.pdf + +Required properties: + - compatible: must be "maxim,max30100" + - 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 + + Refer to interrupt-controller/interrupts.txt for generic + interrupt client node bindings. + +Optional properties: + - maxim,led-current-microamp: configuration for LED current in microamperes + while the engine is running. First indexed value is the configuration for + the RED LED, and second value is for the IR LED. + + Refer to the datasheet for the allowed current values. + +Example: + +max30100@057 { + compatible = "maxim,max30100"; + reg = <57>; + maxim,led-current-microamp = <24000 50000>; + interrupt-parent = <&gpio1>; + interrupts = <16 2>; +}; diff --git a/Documentation/devicetree/bindings/iio/iio-bindings.txt b/Documentation/devicetree/bindings/iio/iio-bindings.txt index 0b447d9ad196..68d6f8ce063b 100644 --- a/Documentation/devicetree/bindings/iio/iio-bindings.txt +++ b/Documentation/devicetree/bindings/iio/iio-bindings.txt @@ -82,7 +82,7 @@ vdd channel is connected to output 0 of the &ref device. ... - iio_hwmon { + iio-hwmon { compatible = "iio-hwmon"; io-channels = <&adc 0>, <&adc 1>, <&adc 2>, <&adc 3>, <&adc 4>, <&adc 5>, diff --git a/Documentation/devicetree/bindings/iio/light/apds9960.txt b/Documentation/devicetree/bindings/iio/light/apds9960.txt new file mode 100644 index 000000000000..174b709f16db --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/apds9960.txt @@ -0,0 +1,22 @@ +* Avago APDS9960 gesture/RGB/ALS/proximity sensor + +http://www.avagotech.com/docs/AV02-4191EN + +Required properties: + + - compatible: must be "avago,apds9960" + - 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 + + Refer to interrupt-controller/interrupts.txt for generic interrupt client + node bindings. + +Example: + +apds9960@39 { + compatible = "avago,apds9960"; + reg = <0x39>; + interrupt-parent = <&gpio1>; + interrupts = <16 1>; +}; diff --git a/Documentation/devicetree/bindings/iio/light/opt3001.txt b/Documentation/devicetree/bindings/iio/light/opt3001.txt new file mode 100644 index 000000000000..eac30d508849 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/opt3001.txt @@ -0,0 +1,26 @@ +* Texas Instruments OPT3001 Ambient Light Sensor + +The driver supports interrupt-driven and interrupt-less operation, depending +on whether an interrupt property has been populated into the DT. Note that +the optional generation of IIO events on rising/falling light threshold changes +requires the use of interrupts. Without interrupts, only the simple reading +of the current light value is supported through the IIO API. + +http://www.ti.com/product/opt3001 + +Required properties: + - compatible: should be "ti,opt3001" + - reg: the I2C address of the sensor + +Optional properties: + - interrupt-parent: should be the phandle for the interrupt controller + - interrupts: interrupt mapping for GPIO IRQ (configure for falling edge) + +Example: + +opt3001@44 { + compatible = "ti,opt3001"; + reg = <0x44>; + interrupt-parent = <&gpio1>; + interrupts = <28 IRQ_TYPE_EDGE_FALLING>; +}; diff --git a/Documentation/devicetree/bindings/iio/light/us5182d.txt b/Documentation/devicetree/bindings/iio/light/us5182d.txt new file mode 100644 index 000000000000..a61979997f37 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/us5182d.txt @@ -0,0 +1,45 @@ +* UPISEMI us5182d I2C ALS and Proximity sensor + +Required properties: +- compatible: must be "upisemi,usd5182" +- reg: the I2C address of the device + +Optional properties: +- upisemi,glass-coef: glass attenuation factor - compensation factor of + resolution 1000 for material transmittance. + +- upisemi,dark-ths: array of 8 elements containing 16-bit thresholds (adc + counts) corresponding to every scale. + +- upisemi,upper-dark-gain: 8-bit dark gain compensation factor(4 int and 4 + fractional bits - Q4.4) applied when light > threshold + +- upisemi,lower-dark-gain: 8-bit dark gain compensation factor(4 int and 4 + fractional bits - Q4.4) applied when light < threshold + +- upisemi,continuous: This chip has two power modes: one-shot (chip takes one + measurement and then shuts itself down) and continuous ( + chip takes continuous measurements). The one-shot mode is + more power-friendly but the continuous mode may be more + reliable. If this property is specified the continuous + mode will be used instead of the default one-shot one for + raw reads. + +If the optional properties are not specified these factors will default to the +values in the below example. +The glass-coef defaults to no compensation for the covering material. +The threshold array defaults to experimental values that work with US5182D +sensor on evaluation board - roughly between 12-32 lux. +There will be no dark-gain compensation by default when ALS > thresh +(0 * dark-gain), and a 1.35 compensation factor when ALS < thresh. + +Example: + + usd5182@39 { + compatible = "upisemi,usd5182"; + reg = <0x39>; + upisemi,glass-coef = < 1000 >; + upisemi,dark-ths = /bits/ 16 <170 200 512 512 800 2000 4000 8000>; + upisemi,upper-dark-gain = /bits/ 8 <0x00>; + upisemi,lower-dark-gain = /bits/ 8 <0x16>; + }; diff --git a/Documentation/devicetree/bindings/misc/bmp085.txt b/Documentation/devicetree/bindings/iio/pressure/bmp085.txt index d7a6deb6b21e..d7a6deb6b21e 100644 --- a/Documentation/devicetree/bindings/misc/bmp085.txt +++ b/Documentation/devicetree/bindings/iio/pressure/bmp085.txt diff --git a/Documentation/devicetree/bindings/iio/st-sensors.txt b/Documentation/devicetree/bindings/iio/st-sensors.txt index d3ccdb190c53..d4b87cc1e446 100644 --- a/Documentation/devicetree/bindings/iio/st-sensors.txt +++ b/Documentation/devicetree/bindings/iio/st-sensors.txt @@ -36,6 +36,7 @@ Accelerometers: - st,lsm303dlm-accel - st,lsm330-accel - st,lsm303agr-accel +- st,lis2dh12-accel Gyroscopes: - st,l3g4200d-gyro diff --git a/Documentation/devicetree/bindings/input/ads7846.txt b/Documentation/devicetree/bindings/input/ads7846.txt index df8b1279491d..c6cfe2e3ed41 100644 --- a/Documentation/devicetree/bindings/input/ads7846.txt +++ b/Documentation/devicetree/bindings/input/ads7846.txt @@ -29,6 +29,8 @@ Optional properties: ti,vref-delay-usecs vref supply delay in usecs, 0 for external vref (u16). ti,vref-mv The VREF voltage, in millivolts (u16). + Set to 0 to use internal refernce + (ADS7846). ti,keep-vref-on set to keep vref on for differential measurements as well ti,swap-xy swap x and y axis @@ -65,6 +67,7 @@ Optional properties: pendown-gpio GPIO handle describing the pin the !PENIRQ line is connected to. wakeup-source use any event on touchscreen as wakeup event. + (Legacy property support: "linux,wakeup") Example for a TSC2046 chip connected to an McSPI controller of an OMAP SoC:: @@ -86,6 +89,6 @@ Example for a TSC2046 chip connected to an McSPI controller of an OMAP SoC:: ti,x-plate-ohms = /bits/ 16 <40>; ti,pressure-max = /bits/ 16 <255>; - linux,wakeup; + wakeup-source; }; }; diff --git a/Documentation/devicetree/bindings/input/da9062-onkey.txt b/Documentation/devicetree/bindings/input/da9062-onkey.txt new file mode 100644 index 000000000000..ab0e0488fe92 --- /dev/null +++ b/Documentation/devicetree/bindings/input/da9062-onkey.txt @@ -0,0 +1,32 @@ +* Dialog DA9062/63 OnKey Module + +This module is part of the DA9062/DA9063. For more details about entire +chips see Documentation/devicetree/bindings/mfd/da9062.txt and +Documentation/devicetree/bindings/mfd/da9063.txt + +This module provides KEY_POWER, KEY_SLEEP and events. + +Required properties: + +- compatible: should be one of: + dlg,da9062-onkey + dlg,da9063-onkey + +Optional properties: + + - dlg,disable-key-power : Disable power-down using a long key-press. If this + entry exists the OnKey driver will remove support for the KEY_POWER key + press. If this entry does not exist then by default the key-press + triggered power down is enabled and the OnKey will support both KEY_POWER + and KEY_SLEEP. + +Example: + + pmic0: da9062@58 { + + onkey { + compatible = "dlg,da9063-onkey"; + dlg,disable-key-power; + }; + + }; diff --git a/Documentation/devicetree/bindings/input/gpio-keys-polled.txt b/Documentation/devicetree/bindings/input/gpio-keys-polled.txt index 5b91f5a3bd5c..95d0fb11a787 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys-polled.txt +++ b/Documentation/devicetree/bindings/input/gpio-keys-polled.txt @@ -13,14 +13,22 @@ Subnode properties: - gpios: OF device-tree gpio specification. - label: Descriptive name of the key. - - linux,code: Keycode to emit. + - linux,code: Key / Axis code to emit. Optional subnode-properties: - linux,input-type: Specify event type this button/key generates. If not specified defaults to <1> == EV_KEY. + - linux,input-value: If linux,input-type is EV_ABS or EV_REL then this + value is sent for events this button generates when pressed. + EV_ABS/EV_REL axis will generate an event with a value of 0 when + all buttons with linux,input-type == type and linux,code == axis + are released. This value is interpreted as a signed 32 bit value, + e.g. to make a button generate a value of -1 use: + linux,input-value = <0xffffffff>; /* -1 */ - debounce-interval: Debouncing interval time in milliseconds. If not specified defaults to 5. - wakeup-source: Boolean, button can wake-up the system. + (Legacy property supported: "gpio-key,wakeup") Example nodes: diff --git a/Documentation/devicetree/bindings/input/gpio-keys.txt b/Documentation/devicetree/bindings/input/gpio-keys.txt index 072bf7573c37..21641236c095 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys.txt +++ b/Documentation/devicetree/bindings/input/gpio-keys.txt @@ -6,6 +6,7 @@ Required properties: Optional properties: - autorepeat: Boolean, Enable auto repeat feature of Linux input subsystem. + - label: String, name of the input device. Each button (key) is represented as a sub-node of "gpio-keys": Subnode properties: @@ -24,6 +25,7 @@ Optional subnode-properties: - debounce-interval: Debouncing interval time in milliseconds. If not specified defaults to 5. - wakeup-source: Boolean, button can wake-up the system. + (Legacy property supported: "gpio-key,wakeup") - linux,can-disable: Boolean, indicates that button is connected to dedicated (not shared) interrupt which can be disabled to suppress events from the button. diff --git a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt index 4d86059c370c..d0ea09ba249f 100644 --- a/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt +++ b/Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt @@ -20,6 +20,7 @@ Required Properties: Optional Properties: - linux,no-autorepeat: do no enable autorepeat feature. - wakeup-source: use any event on keypad as wakeup event. + (Legacy property supported: "linux,wakeup") - debounce-delay-ms: debounce interval in milliseconds - col-scan-delay-us: delay, measured in microseconds, that is needed before we can scan keypad after activating column gpio diff --git a/Documentation/devicetree/bindings/hid/hid-over-i2c.txt b/Documentation/devicetree/bindings/input/hid-over-i2c.txt index 488edcb264c4..488edcb264c4 100644 --- a/Documentation/devicetree/bindings/hid/hid-over-i2c.txt +++ b/Documentation/devicetree/bindings/input/hid-over-i2c.txt diff --git a/Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt b/Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt index 0382b8bd69c6..1faa7292e21f 100644 --- a/Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt +++ b/Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt @@ -29,7 +29,8 @@ matrix-keyboard bindings: - nvidia,debounce-delay-ms: delay in milliseconds per row scan for debouncing - nvidia,repeat-delay-ms: delay in milliseconds before repeat starts - nvidia,ghost-filter: enable ghost filtering for this device -- nvidia,wakeup-source: configure keyboard as a wakeup source for suspend/resume +- wakeup-source: configure keyboard as a wakeup source for suspend/resume + (Legacy property supported: "nvidia,wakeup-source") Example: diff --git a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt b/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt index ee6215681182..4a9dc6ba96b1 100644 --- a/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt +++ b/Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt @@ -37,6 +37,7 @@ PROPERTIES Usage: optional Value type: <bool> Definition: use any event on keypad as wakeup event. + (Legacy property supported: "linux,keypad-wakeup") - keypad,num-rows: Usage: required diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt new file mode 100644 index 000000000000..f2c30c8b725d --- /dev/null +++ b/Documentation/devicetree/bindings/input/rmi4/rmi_2d_sensor.txt @@ -0,0 +1,56 @@ +Synaptics RMI4 2D Sensor Device Binding + +The Synaptics RMI4 core is able to support RMI4 devices using different +transports and different functions. This file describes the device tree +bindings for devices which contain 2D sensors using Function 11 or +Function 12. Complete documentation for transports and other functions +can be found in: +Documentation/devicetree/bindings/input/rmi4. + +RMI4 Function 11 and Function 12 are for 2D touch position sensing. +Additional documentation for F11 can be found at: +http://www.synaptics.com/sites/default/files/511-000136-01-Rev-E-RMI4-Interfacing-Guide.pdf + +Optional Touch Properties: +Description in Documentation/devicetree/bindings/input/touch +- touchscreen-inverted-x +- touchscreen-inverted-y +- touchscreen-swapped-x-y +- touchscreen-x-mm +- touchscreen-y-mm + +Optional Properties: +- syna,clip-x-low: Sets a minimum value for X. +- syna,clip-y-low: Sets a minimum value for Y. +- syna,clip-x-high: Sets a maximum value for X. +- syna,clip-y-high: Sets a maximum value for Y. +- syna,offset-x: Add an offset to X. +- syna,offset-y: Add an offset to Y. +- syna,delta-x-threshold: Set the minimum distance on the X axis required + to generate an interrupt in reduced reporting + mode. +- syna,delta-y-threshold: Set the minimum distance on the Y axis required + to generate an interrupt in reduced reporting + mode. +- syna,sensor-type: Set the sensor type. 1 for touchscreen 2 for touchpad. +- syna,disable-report-mask: Mask for disabling posiiton reporting. Used to + disable reporing absolute position data. +- syna,rezero-wait-ms: Time in miliseconds to wait after issuing a rezero + command. + + +Example of a RMI4 I2C device with F11: +Example: + &i2c1 { + rmi4-i2c-dev@2c { + compatible = "syna,rmi4-i2c"; + + ... + + rmi4-f11@11 { + reg = <0x11>; + touchscreen-inverted-y; + syna,sensor-type = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt new file mode 100644 index 000000000000..079cad2b6843 --- /dev/null +++ b/Documentation/devicetree/bindings/input/rmi4/rmi_f01.txt @@ -0,0 +1,39 @@ +Synaptics RMI4 F01 Device Binding + +The Synaptics RMI4 core is able to support RMI4 devices using different +transports and different functions. This file describes the device tree +bindings for devices which contain Function 1. Complete documentation +for transports and other functions can be found in: +Documentation/devicetree/bindings/input/rmi4. + +Additional documentation for F01 can be found at: +http://www.synaptics.com/sites/default/files/511-000136-01-Rev-E-RMI4-Interfacing-Guide.pdf + +Optional Properties: +- syna,nosleep-mode: If set the device will run at full power without sleeping. + nosleep has 3 modes, 0 will not change the default + setting, 1 will disable nosleep (allow sleeping), + and 2 will enable nosleep (disabling sleep). +- syna,wakeup-threshold: Defines the amplitude of the disturbance to the + background capacitance that will cause the + device to wake from dozing. +- syna,doze-holdoff-ms: The delay to wait after the last finger lift and the + first doze cycle. +- syna,doze-interval-ms: The time period that the device sleeps between finger + activity. + + +Example of a RMI4 I2C device with F01: + Example: + &i2c1 { + rmi4-i2c-dev@2c { + compatible = "syna,rmi4-i2c"; + + ... + + rmi4-f01@1 { + reg = <0x1>; + syna,nosleep-mode = <1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt new file mode 100644 index 000000000000..95fa715c6046 --- /dev/null +++ b/Documentation/devicetree/bindings/input/rmi4/rmi_i2c.txt @@ -0,0 +1,53 @@ +Synaptics RMI4 I2C Device Binding + +The Synaptics RMI4 core is able to support RMI4 devices using different +transports and different functions. This file describes the device tree +bindings for devices using the I2C transport driver. Complete documentation +for other transports and functions can be found in +Documentation/devicetree/bindings/input/rmi4. + +Required Properties: +- compatible: syna,rmi4-i2c +- reg: I2C address +- #address-cells: Set to 1 to indicate that the function child nodes + consist of only on uint32 value. +- #size-cells: Set to 0 to indicate that the function child nodes do not + have a size property. + +Optional Properties: +- interrupts: interrupt which the rmi device is connected to. +- interrupt-parent: The interrupt controller. +See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +- syna,reset-delay-ms: The number of milliseconds to wait after resetting the + device. + +Function Parameters: +Parameters specific to RMI functions are contained in child nodes of the rmi device + node. Documentation for the parameters of each function can be found in: +Documentation/devicetree/bindings/input/rmi4/rmi_f*.txt. + + + +Example: + &i2c1 { + rmi4-i2c-dev@2c { + compatible = "syna,rmi4-i2c"; + reg = <0x2c>; + #address-cells = <1>; + #size-cells = <0>; + interrupt-parent = <&gpio>; + interrupts = <4 2>; + + rmi4-f01@1 { + reg = <0x1>; + syna,nosleep-mode = <1>; + }; + + rmi4-f11@11 { + reg = <0x11>; + touchscreen-inverted-y; + syna,sensor-type = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt b/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt new file mode 100644 index 000000000000..a4ca7828f21d --- /dev/null +++ b/Documentation/devicetree/bindings/input/rmi4/rmi_spi.txt @@ -0,0 +1,57 @@ +Synaptics RMI4 SPI Device Binding + +The Synaptics RMI4 core is able to support RMI4 devices using different +transports and different functions. This file describes the device tree +bindings for devices using the SPI transport driver. Complete documentation +for other transports and functions can be found in +Documentation/devicetree/bindings/input/rmi4. + +Required Properties: +- compatible: syna,rmi4-spi +- reg: Chip select address for the device +- #address-cells: Set to 1 to indicate that the function child nodes + consist of only on uint32 value. +- #size-cells: Set to 0 to indicate that the function child nodes do not + have a size property. + +Optional Properties: +- interrupts: interrupt which the rmi device is connected to. +- interrupt-parent: The interrupt controller. +See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +- spi-rx-delay-us: microsecond delay after a read transfer. +- spi-tx-delay-us: microsecond delay after a write transfer. + +Function Parameters: +Parameters specific to RMI functions are contained in child nodes of the rmi device + node. Documentation for the parameters of each function can be found in: +Documentation/devicetree/bindings/input/rmi4/rmi_f*.txt. + + + +Example: + spi@7000d800 { + rmi4-spi-dev@0 { + compatible = "syna,rmi4-spi"; + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + spi-max-frequency = <4000000>; + spi-cpha; + spi-cpol; + interrupt-parent = <&gpio>; + interrupts = <TEGRA_GPIO(K, 2) 0x2>; + spi-rx-delay-us = <30>; + + rmi4-f01@1 { + reg = <0x1>; + syna,nosleep-mode = <1>; + }; + + rmi4-f11@11 { + reg = <0x11>; + touchscreen-inverted-y; + syna,sensor-type = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/input/rotary-encoder.txt b/Documentation/devicetree/bindings/input/rotary-encoder.txt index 331549593ed5..6c9f0c8a846c 100644 --- a/Documentation/devicetree/bindings/input/rotary-encoder.txt +++ b/Documentation/devicetree/bindings/input/rotary-encoder.txt @@ -1,7 +1,7 @@ Rotary encoder DT bindings Required properties: -- gpios: a spec for two GPIOs to be used +- gpios: a spec for at least two GPIOs to be used, most significant first Optional properties: - linux,axis: the input subsystem axis to map to this rotary encoder. @@ -14,7 +14,17 @@ Optional properties: device, hence no steps need to be passed. - rotary-encoder,rollover: Automatic rollove when the rotary value becomes greater than the specified steps or smaller than 0. For absolute axis only. +- rotary-encoder,steps-per-period: Number of steps (stable states) per period. + The values have the following meaning: + 1: Full-period mode (default) + 2: Half-period mode + 4: Quarter-period mode +- wakeup-source: Boolean, rotary encoder can wake up the system. + +Deprecated properties: - rotary-encoder,half-period: Makes the driver work on half-period mode. + This property is deprecated. Instead, a 'steps-per-period ' value should + be used, such as "rotary-encoder,steps-per-period = <2>". See Documentation/input/rotary-encoder.txt for more information. diff --git a/Documentation/devicetree/bindings/input/samsung-keypad.txt b/Documentation/devicetree/bindings/input/samsung-keypad.txt index 863e77f619dc..5305e74e5742 100644 --- a/Documentation/devicetree/bindings/input/samsung-keypad.txt +++ b/Documentation/devicetree/bindings/input/samsung-keypad.txt @@ -38,6 +38,7 @@ Required Board Specific Properties: Optional Properties: - wakeup-source: use any event on keypad as wakeup event. + (Legacy property supported: "linux,input-wakeup") Optional Properties specific to linux: - linux,keypad-no-autorepeat: do no enable autorepeat feature. @@ -51,7 +52,7 @@ Example: samsung,keypad-num-rows = <2>; samsung,keypad-num-columns = <8>; linux,input-no-autorepeat; - linux,input-wakeup; + wakeup-source; pinctrl-names = "default"; pinctrl-0 = <&keypad_rows &keypad_columns>; diff --git a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt index b9c32f6fd687..4357e498ef04 100644 --- a/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt +++ b/Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt @@ -12,7 +12,7 @@ Each key is represented as a sub-node of "allwinner,sun4i-a10-lradc-keys": Required subnode-properties: - label: Descriptive name of the key. - linux,code: Keycode to emit. - - channel: Channel this key is attached to, mut be 0 or 1. + - channel: Channel this key is attached to, must be 0 or 1. - voltage: Voltage in µV at lradc input when this key is pressed. Example: diff --git a/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt b/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt new file mode 100644 index 000000000000..e3f22d23fc8f --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/ad7879.txt @@ -0,0 +1,53 @@ +* Analog Devices AD7879(-1)/AD7889(-1) touchscreen interface (SPI/I2C) + +Required properties: +- compatible : for SPI slave, use "adi,ad7879" + for I2C slave, use "adi,ad7879-1" +- reg : SPI chipselect/I2C slave address + See spi-bus.txt for more SPI slave properties +- interrupt-parent : the phandle for the interrupt controller +- interrupts : touch controller interrupt +- touchscreen-max-pressure : maximum reported pressure +- adi,resistance-plate-x : total resistance of X-plate (for pressure + calculation) +Optional properties: +- touchscreen-swapped-x-y : X and Y axis are swapped (boolean) +- adi,first-conversion-delay : 0-12: In 128us steps (starting with 128us) + 13 : 2.560ms + 14 : 3.584ms + 15 : 4.096ms + This property has to be a '/bits/ 8' value +- adi,acquisition-time : 0: 2us + 1: 4us + 2: 8us + 3: 16us + This property has to be a '/bits/ 8' value +- adi,median-filter-size : 0: disabled + 1: 4 measurements + 2: 8 measurements + 3: 16 measurements + This property has to be a '/bits/ 8' value +- adi,averaging : 0: 2 middle values (1 if median disabled) + 1: 4 middle values + 2: 8 middle values + 3: 16 values + This property has to be a '/bits/ 8' value +- adi,conversion-interval: : 0 : convert one time only + 1-255: 515us + val * 35us (up to 9.440ms) + This property has to be a '/bits/ 8' value + +Example: + + ad7879@2c { + compatible = "adi,ad7879-1"; + reg = <0x2c>; + interrupt-parent = <&gpio1>; + interrupts = <13 IRQ_TYPE_EDGE_FALLING>; + touchscreen-max-pressure = <4096>; + adi,resistance-plate-x = <120>; + adi,first-conversion-delay = /bits/ 8 <3>; + adi,acquisition-time = /bits/ 8 <1>; + adi,median-filter-size = /bits/ 8 <2>; + adi,averaging = /bits/ 8 <1>; + adi,conversion-interval = /bits/ 8 <255>; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/cyttsp.txt b/Documentation/devicetree/bindings/input/touchscreen/cyttsp.txt new file mode 100644 index 000000000000..b75d4cfd2c36 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/cyttsp.txt @@ -0,0 +1,95 @@ +* Cypress cyttsp touchscreen controller + +Required properties: + - compatible : must be "cypress,cyttsp-i2c" or "cypress,cyttsp-spi" + - reg : Device I2C address or SPI chip select number + - spi-max-frequency : Maximum SPI clocking speed of the device (for cyttsp-spi) + - interrupt-parent : the phandle for the gpio controller + (see interrupt binding[0]). + - interrupts : (gpio) interrupt to which the chip is connected + (see interrupt binding[0]). + - bootloader-key : the 8-byte bootloader key that is required to switch + the chip from bootloader mode (default mode) to + application mode. + This property has to be specified as an array of 8 + '/bits/ 8' values. + +Optional properties: + - reset-gpios : the reset gpio the chip is connected to + (see GPIO binding[1] for more details). + - touchscreen-size-x : horizontal resolution of touchscreen (in pixels) + - touchscreen-size-y : vertical resolution of touchscreen (in pixels) + - touchscreen-fuzz-x : horizontal noise value of the absolute input device + (in pixels) + - touchscreen-fuzz-y : vertical noise value of the absolute input device + (in pixels) + - active-distance : the distance in pixels beyond which a touch must move + before movement is detected and reported by the device. + Valid values: 0-15. + - active-interval-ms : the minimum period in ms between consecutive + scanning/processing cycles when the chip is in active mode. + Valid values: 0-255. + - lowpower-interval-ms : the minimum period in ms between consecutive + scanning/processing cycles when the chip is in low-power mode. + Valid values: 0-2550 + - touch-timeout-ms : minimum time in ms spent in the active power state while no + touches are detected before entering low-power mode. + Valid values: 0-2550 + - use-handshake : enable register-based handshake (boolean). This should + only be used if the chip is configured to use 'blocking + communication with timeout' (in this case the device + generates an interrupt at the end of every + scanning/processing cycle). + +[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +[1]: Documentation/devicetree/bindings/gpio/gpio.txt + +Example: + &i2c1 { + /* ... */ + cyttsp@a { + compatible = "cypress,cyttsp-i2c"; + reg = <0xa>; + interrupt-parent = <&gpio0>; + interrupts = <28 0>; + reset-gpios = <&gpio3 4 GPIO_ACTIVE_LOW>; + + touchscreen-size-x = <800>; + touchscreen-size-y = <480>; + touchscreen-fuzz-x = <4>; + touchscreen-fuzz-y = <7>; + + bootloader-key = /bits/ 8 <0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08>; + active-distance = <8>; + active-interval-ms = <0>; + lowpower-interval-ms = <200>; + touch-timeout-ms = <100>; + }; + + /* ... */ + }; + + &mcspi1 { + /* ... */ + cyttsp@0 { + compatible = "cypress,cyttsp-spi"; + spi-max-frequency = <6000000>; + reg = <0>; + interrupt-parent = <&gpio0>; + interrupts = <28 0>; + reset-gpios = <&gpio3 4 GPIO_ACTIVE_LOW>; + + touchscreen-size-x = <800>; + touchscreen-size-y = <480>; + touchscreen-fuzz-x = <4>; + touchscreen-fuzz-y = <7>; + + bootloader-key = /bits/ 8 <0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08>; + active-distance = <8>; + active-interval-ms = <0>; + lowpower-interval-ms = <200>; + touch-timeout-ms = <100>; + }; + + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt index 76db96704a60..f99528da1b1d 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt @@ -5,6 +5,7 @@ There are 3 variants of the chip for various touch panel sizes FT5206GE1 2.8" .. 3.8" FT5306DE4 4.3" .. 7" FT5406EE8 7" .. 8.9" +FT5506EEG 7" .. 8.9" The software interface is identical for all those chips, so that currently there is no need for the driver to distinguish between the @@ -17,6 +18,7 @@ Required properties: - compatible: "edt,edt-ft5206" or: "edt,edt-ft5306" or: "edt,edt-ft5406" + or: "edt,edt-ft5506" - reg: I2C slave address of the chip (0x38) - interrupt-parent: a phandle pointing to the interrupt controller @@ -49,7 +51,7 @@ Example: pinctrl-names = "default"; pinctrl-0 = <&edt_ft5x06_pins>; interrupt-parent = <&gpio2>; - interrupts = <5 0>; - reset-gpios = <&gpio2 6 1>; - wake-gpios = <&gpio4 9 0>; + interrupts = <5 IRQ_TYPE_EDGE_FALLING>; + reset-gpios = <&gpio2 6 GPIO_ACTIVE_LOW>; + wake-gpios = <&gpio4 9 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/focaltech-ft6236.txt b/Documentation/devicetree/bindings/input/touchscreen/focaltech-ft6236.txt new file mode 100644 index 000000000000..777521da3da5 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/focaltech-ft6236.txt @@ -0,0 +1,35 @@ +* FocalTech FT6236 I2C touchscreen controller + +Required properties: + - compatible : "focaltech,ft6236" + - reg : I2C slave address of the chip (0x38) + - interrupt-parent : a phandle pointing to the interrupt controller + serving the interrupt for this chip + - interrupts : interrupt specification for the touch controller + interrupt + - reset-gpios : GPIO specification for the RSTN input + - touchscreen-size-x : horizontal resolution of touchscreen (in pixels) + - touchscreen-size-y : vertical resolution of touchscreen (in pixels) + +Optional properties: + - touchscreen-fuzz-x : horizontal noise value of the absolute input + device (in pixels) + - touchscreen-fuzz-y : vertical noise value of the absolute input + device (in pixels) + - touchscreen-inverted-x : X axis is inverted (boolean) + - touchscreen-inverted-y : Y axis is inverted (boolean) + - touchscreen-swapped-x-y: X and Y axis are swapped (boolean) + Swapping is done after inverting the axis + +Example: + + ft6x06@38 { + compatible = "focaltech,ft6236"; + reg = <0x38>; + interrupt-parent = <&gpio>; + interrupts = <23 2>; + touchscreen-size-x = <320>; + touchscreen-size-y = <480>; + touchscreen-inverted-x; + touchscreen-swapped-x-y; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/fsl-mx25-tcq.txt b/Documentation/devicetree/bindings/input/touchscreen/fsl-mx25-tcq.txt new file mode 100644 index 000000000000..cdf05f9b2329 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/fsl-mx25-tcq.txt @@ -0,0 +1,35 @@ +Freescale mx25 TS conversion queue module + +mx25 touchscreen conversion queue module which controls the ADC unit of the +mx25 for attached touchscreens. + +Required properties: + - compatible: Should be "fsl,imx25-tcq". + - reg: Memory range of the device. + - interrupts: Should be the interrupt number associated with this module within + the tscadc unit (<0>). + - interrupt-parent: Should be a phandle to the tscadc unit. + - fsl,wires: Should be '<4>' or '<5>' + +Optional properties: + - fsl,pen-debounce-ns: Pen debounce time in nanoseconds. + - fsl,pen-threshold: Pen-down threshold for the touchscreen. This is a value + between 1 and 4096. It is the ratio between the internal reference voltage + and the measured voltage after the plate was precharged. Resistence between + plates and therefore the voltage decreases with pressure so that a smaller + value is equivalent to a higher pressure. + - fsl,settling-time-ns: Settling time in nanoseconds. The settling time is before + the actual touch detection to wait for an even charge distribution in the + plate. + +This device includes two conversion queues which can be added as subnodes. +The first queue is for the touchscreen, the second for general purpose ADC. + +Example: + tsc: tcq@50030400 { + compatible = "fsl,imx25-tcq"; + reg = <0x50030400 0x60>; + interrupt-parent = <&tscadc>; + interrupts = <0>; + fsl,wires = <4>; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.txt b/Documentation/devicetree/bindings/input/touchscreen/goodix.txt index 8ba98eec765b..c98757a69110 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.txt @@ -13,6 +13,17 @@ Required properties: - interrupt-parent : Interrupt controller to which the chip is connected - interrupts : Interrupt to which the chip is connected +Optional properties: + + - irq-gpios : GPIO pin used for IRQ. The driver uses the + interrupt gpio pin as output to reset the device. + - reset-gpios : GPIO pin used for reset + + - touchscreen-inverted-x : X axis is inverted (boolean) + - touchscreen-inverted-y : Y axis is inverted (boolean) + - touchscreen-swapped-x-y : X and Y axis are swapped (boolean) + (swapping is done after inverting the axis) + Example: i2c@00000000 { @@ -23,6 +34,9 @@ Example: reg = <0x5d>; interrupt-parent = <&gpio>; interrupts = <0 0>; + + irq-gpios = <&gpio1 0 0>; + reset-gpios = <&gpio1 1 0>; }; /* ... */ diff --git a/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt b/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt index 8eb240a287c8..697a3e7831e7 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/pixcir_i2c_ts.txt @@ -9,7 +9,9 @@ Required properties: - touchscreen-size-y: vertical resolution of touchscreen (in pixels) Optional properties: -- reset-gpio: GPIO connected to the RESET line of the chip +- reset-gpios: GPIO connected to the RESET line of the chip +- enable-gpios: GPIO connected to the ENABLE line of the chip +- wake-gpios: GPIO connected to the WAKE line of the chip Example: diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt index ac23caf518ad..bccaa4e73045 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt @@ -18,6 +18,8 @@ Optional properties for Touchscreens: - touchscreen-inverted-y : Y axis is inverted (boolean) - touchscreen-swapped-x-y : X and Y axis are swapped (boolean) Swapping is done after inverting the axis + - touchscreen-x-mm : horizontal length in mm of the touchscreen + - touchscreen-y-mm : vertical length in mm of the touchscreen Deprecated properties for Touchscreens: - x-size : deprecated name for touchscreen-size-x diff --git a/Documentation/devicetree/bindings/input/touchscreen/ts4800-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/ts4800-ts.txt new file mode 100644 index 000000000000..4c1c092c276b --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/ts4800-ts.txt @@ -0,0 +1,11 @@ +* TS-4800 Touchscreen bindings + +Required properties: +- compatible: must be "technologic,ts4800-ts" +- reg: physical base address of the controller and length of memory mapped + region. +- syscon: phandle / integers array that points to the syscon node which + describes the FPGA's syscon registers. + - phandle to FPGA's syscon + - offset to the touchscreen register + - offset to the touchscreen enable bit diff --git a/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt b/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt index 09089a6d69ed..b80c04b0e5c0 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/tsc2005.txt @@ -1,14 +1,15 @@ -* Texas Instruments tsc2005 touchscreen controller +* Texas Instruments tsc2004 and tsc2005 touchscreen controllers Required properties: - - compatible : "ti,tsc2005" - - reg : SPI device address - - spi-max-frequency : Maximal SPI speed + - compatible : "ti,tsc2004" or "ti,tsc2005" + - reg : Device address - interrupts : IRQ specifier - - reset-gpios : GPIO specifier - - vio-supply : Regulator specifier + - spi-max-frequency : Maximum SPI clocking speed of the device + (for tsc2005) Optional properties: + - vio-supply : Regulator specifier + - reset-gpios : GPIO specifier for the controller reset line - ti,x-plate-ohms : integer, resistance of the touchscreen's X plates in ohm (defaults to 280) - ti,esd-recovery-timeout-ms : integer, if the touchscreen does not respond after @@ -18,6 +19,27 @@ Optional properties: Example: +&i2c3 { + tsc2004@48 { + compatible = "ti,tsc2004"; + reg = <0x48>; + vio-supply = <&vio>; + + reset-gpios = <&gpio4 8 GPIO_ACTIVE_HIGH>; + interrupts-extended = <&gpio1 27 IRQ_TYPE_EDGE_RISING>; + + touchscreen-fuzz-x = <4>; + touchscreen-fuzz-y = <7>; + touchscreen-fuzz-pressure = <2>; + touchscreen-size-x = <4096>; + touchscreen-size-y = <4096>; + touchscreen-max-pressure = <2048>; + + ti,x-plate-ohms = <280>; + ti,esd-recovery-timeout-ms = <8000>; + }; +} + &mcspi1 { tsc2005@0 { compatible = "ti,tsc2005"; diff --git a/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.txt b/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.txt new file mode 100644 index 000000000000..f6f1c14bf99b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/al,alpine-msix.txt @@ -0,0 +1,26 @@ +Alpine MSIX controller + +See arm,gic-v3.txt for SPI and MSI definitions. + +Required properties: + +- compatible: should be "al,alpine-msix" +- reg: physical base address and size of the registers +- interrupt-parent: specifies the parent interrupt controller. +- interrupt-controller: identifies the node as an interrupt controller +- msi-controller: identifies the node as an PCI Message Signaled Interrupt + controller +- al,msi-base-spi: SPI base of the MSI frame +- al,msi-num-spis: number of SPIs assigned to the MSI frame, relative to SPI0 + +Example: + +msix: msix { + compatible = "al,alpine-msix"; + reg = <0x0 0xfbe00000 0x0 0x100000>; + interrupt-parent = <&gic>; + interrupt-controller; + msi-controller; + al,msi-base-spi = <160>; + al,msi-num-spis = <160>; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun67i-sc-nmi.txt b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sunxi-nmi.txt index d1c5cdabc3e0..81cd3692405e 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun67i-sc-nmi.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sunxi-nmi.txt @@ -4,7 +4,7 @@ Allwinner Sunxi NMI Controller Required properties: - compatible : should be "allwinner,sun7i-a20-sc-nmi" or - "allwinner,sun6i-a31-sc-nmi" + "allwinner,sun6i-a31-sc-nmi" or "allwinner,sun9i-a80-nmi" - reg : Specifies base physical address and size of the registers. - interrupt-controller : Identifies the node as an interrupt controller - #interrupt-cells : Specifies the number of cells needed to encode an diff --git a/Documentation/devicetree/bindings/arm/gic-v3.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt index 7803e77d85cb..007a5b46256a 100644 --- a/Documentation/devicetree/bindings/arm/gic-v3.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt @@ -24,9 +24,8 @@ Main node required properties: 1 = edge triggered 4 = level triggered - Cells 4 and beyond are reserved for future use. When the 1st cell - has a value of 0 or 1, cells 4 and beyond act as padding, and may be - ignored. It is recommended that padding cells have a value of 0. + Cells 4 and beyond are reserved for future use and must have a value + of 0 if present. - reg : Specifies base physical address(s) and size of the GIC registers, in the following order: diff --git a/Documentation/devicetree/bindings/arm/gic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt index 2da059a4790c..793c20ff8fcc 100644 --- a/Documentation/devicetree/bindings/arm/gic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt @@ -11,13 +11,16 @@ have PPIs or SGIs. Main node required properties: - compatible : should be one of: - "arm,gic-400" + "arm,arm1176jzf-devchip-gic" + "arm,arm11mp-gic" "arm,cortex-a15-gic" - "arm,cortex-a9-gic" "arm,cortex-a7-gic" - "arm,arm11mp-gic" + "arm,cortex-a9-gic" + "arm,eb11mp-gic" + "arm,gic-400" + "arm,pl390" + "arm,tc11mp-gic" "brcm,brahma-b15-gic" - "arm,arm1176jzf-devchip-gic" "qcom,msm-8660-qgic" "qcom,msm-qgic2" - interrupt-controller : Identifies the node as an interrupt controller @@ -58,6 +61,21 @@ Optional regions, used when the GIC doesn't have banked registers. The offset is cpu-offset * cpu-nr. +- clocks : List of phandle and clock-specific pairs, one for each entry + in clock-names. +- clock-names : List of names for the GIC clock input(s). Valid clock names + depend on the GIC variant: + "ic_clk" (for "arm,arm11mp-gic") + "PERIPHCLKEN" (for "arm,cortex-a15-gic") + "PERIPHCLK", "PERIPHCLKEN" (for "arm,cortex-a9-gic") + "clk" (for "arm,gic-400") + "gclk" (for "arm,pl390") + +- power-domains : A phandle and PM domain specifier as defined by bindings of + the power controller specified by phandle, used when the GIC + is part of a Power or Clock Domain. + + Example: intc: interrupt-controller@fff11000 { diff --git a/Documentation/devicetree/bindings/arm/versatile-fpga-irq.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt index c9cf605bb995..c9cf605bb995 100644 --- a/Documentation/devicetree/bindings/arm/versatile-fpga-irq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,versatile-fpga-irq.txt diff --git a/Documentation/devicetree/bindings/arm/vic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,vic.txt index dd527216c5fb..dd527216c5fb 100644 --- a/Documentation/devicetree/bindings/arm/vic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,vic.txt diff --git a/Documentation/devicetree/bindings/cris/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/axis,crisv32-intc.txt index e8b123b0a5e6..e8b123b0a5e6 100644 --- a/Documentation/devicetree/bindings/cris/interrupts.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/axis,crisv32-intc.txt diff --git a/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.txt b/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.txt new file mode 100644 index 000000000000..720f7c92e9a1 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/hisilicon,mbigen-v2.txt @@ -0,0 +1,74 @@ +Hisilicon mbigen device tree bindings. +======================================= + +Mbigen means: message based interrupt generator. + +MBI is kind of msi interrupt only used on Non-PCI devices. + +To reduce the wired interrupt number connected to GIC, +Hisilicon designed mbigen to collect and generate interrupt. + + +Non-pci devices can connect to mbigen and generate the +interrupt by writing ITS register. + +The mbigen chip and devices connect to mbigen have the following properties: + +Mbigen main node required properties: +------------------------------------------- +- compatible: Should be "hisilicon,mbigen-v2" + +- reg: Specifies the base physical address and size of the Mbigen + registers. + +- interrupt controller: Identifies the node as an interrupt controller + +- msi-parent: Specifies the MSI controller this mbigen use. + For more detail information,please refer to the generic msi-parent binding in + Documentation/devicetree/bindings/interrupt-controller/msi.txt. + +- num-pins: the total number of pins implemented in this Mbigen + instance. + +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The value must be 2. + + The 1st cell is hardware pin number of the interrupt.This number is local to + each mbigen chip and in the range from 0 to the maximum interrupts number + of the mbigen. + + The 2nd cell is the interrupt trigger type. + The value of this cell should be: + 1: rising edge triggered + or + 4: high level triggered + +Examples: + + mbigen_device_gmac:intc { + compatible = "hisilicon,mbigen-v2"; + reg = <0x0 0xc0080000 0x0 0x10000>; + interrupt-controller; + msi-parent = <&its_dsa 0x40b1c>; + num-pins = <9>; + #interrupt-cells = <2>; + }; + +Devices connect to mbigen required properties: +---------------------------------------------------- +-interrupt-parent: Specifies the mbigen device node which device connected. + +-interrupts:Specifies the interrupt source. + For the specific information of each cell in this property,please refer to + the "interrupt-cells" description mentioned above. + +Examples: + gmac0: ethernet@c2080000 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0 0xc2080000 0 0x20000>, + <0 0xc0000000 0 0x1000>; + interrupt-parent = <&mbigen_device_gmac>; + interrupts = <656 1>, + <657 1>; + }; diff --git a/Documentation/devicetree/bindings/metag/meta-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/img,meta-intc.txt index 80994adab392..80994adab392 100644 --- a/Documentation/devicetree/bindings/metag/meta-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/img,meta-intc.txt diff --git a/Documentation/devicetree/bindings/metag/pdc-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt index a69118550344..a69118550344 100644 --- a/Documentation/devicetree/bindings/metag/pdc-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/img,pdc-intc.txt diff --git a/Documentation/devicetree/bindings/x86/interrupt.txt b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt index 7d19f494f19a..7d19f494f19a 100644 --- a/Documentation/devicetree/bindings/x86/interrupt.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/intel,ce4100-ioapic.txt diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt new file mode 100644 index 000000000000..8af0a8e613ab --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt @@ -0,0 +1,44 @@ + +* Marvell ODMI for MSI support + +Some Marvell SoCs have an On-Die Message Interrupt (ODMI) controller +which can be used by on-board peripheral for MSI interrupts. + +Required properties: + +- compatible : The value here should contain: + + "marvell,ap806-odmi-controller", "marvell,odmi-controller". + +- interrupt,controller : Identifies the node as an interrupt controller. + +- msi-controller : Identifies the node as an MSI controller. + +- marvell,odmi-frames : Number of ODMI frames available. Each frame + provides a number of events. + +- reg : List of register definitions, one for each + ODMI frame. + +- marvell,spi-base : List of GIC base SPI interrupts, one for each + ODMI frame. Those SPI interrupts are 0-based, + i.e marvell,spi-base = <128> will use SPI #96. + See Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt + for details about the GIC Device Tree binding. + +- interrupt-parent : Reference to the parent interrupt controller. + +Example: + + odmi: odmi@300000 { + compatible = "marvell,ap806-odm-controller", + "marvell,odmi-controller"; + interrupt-controller; + msi-controller; + marvell,odmi-frames = <4>; + reg = <0x300000 0x4000>, + <0x304000 0x4000>, + <0x308000 0x4000>, + <0x30C000 0x4000>; + marvell,spi-base = <128>, <136>, <144>, <152>; + }; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt index afef6a85ac51..b8e1674c7837 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sysirq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt @@ -14,6 +14,7 @@ Required properties: "mediatek,mt6582-sysirq" "mediatek,mt6580-sysirq" "mediatek,mt6577-sysirq" + "mediatek,mt2701-sysirq" - interrupt-controller : Identifies the node as an interrupt controller - #interrupt-cells : Use the same format as specified by GIC in Documentation/devicetree/bindings/arm/gic.txt diff --git a/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32-evic.txt b/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32-evic.txt new file mode 100644 index 000000000000..c3a1b37c4c35 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/microchip,pic32-evic.txt @@ -0,0 +1,67 @@ +Microchip PIC32 Interrupt Controller +==================================== + +The Microchip PIC32 contains an Enhanced Vectored Interrupt Controller (EVIC). +It handles all internal and external interrupts. This controller exists outside +of the CPU and is the arbitrator of all interrupts (including interrupts from +the CPU itself) before they are presented to the CPU. + +External interrupts have a software configurable edge polarity. Non external +interrupts have a type and polarity that is determined by the source of the +interrupt. + +Required properties +------------------- + +- compatible: Should be "microchip,pic32mzda-evic" +- reg: Specifies physical base address and size of register range. +- interrupt-controller: Identifies the node as an interrupt controller. +- #interrupt cells: Specifies the number of cells used to encode an interrupt + source connected to this controller. The value shall be 2 and interrupt + descriptor shall have the following format: + + <hw_irq irq_type> + + hw_irq - represents the hardware interrupt number as in the data sheet. + irq_type - is used to describe the type and polarity of an interrupt. For + internal interrupts use IRQ_TYPE_EDGE_RISING for non persistent interrupts and + IRQ_TYPE_LEVEL_HIGH for persistent interrupts. For external interrupts use + IRQ_TYPE_EDGE_RISING or IRQ_TYPE_EDGE_FALLING to select the desired polarity. + +Optional properties +------------------- +- microchip,external-irqs: u32 array of external interrupts with software + polarity configuration. This array corresponds to the bits in the INTCON + SFR. + +Example +------- + +evic: interrupt-controller@1f810000 { + compatible = "microchip,pic32mzda-evic"; + interrupt-controller; + #interrupt-cells = <2>; + reg = <0x1f810000 0x1000>; + microchip,external-irqs = <3 8 13 18 23>; +}; + +Each device/peripheral must request its interrupt line with the associated type +and polarity. + +Internal interrupt DTS snippet +------------------------------ + +device@1f800000 { + ... + interrupts = <113 IRQ_TYPE_LEVEL_HIGH>; + ... +}; + +External interrupt DTS snippet +------------------------------ + +device@1f800000 { + ... + interrupts = <3 IRQ_TYPE_EDGE_RISING>; + ... +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt index aae4c384ee1f..173595305e26 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mips-gic.txt @@ -23,6 +23,12 @@ Optional properties: - mti,reserved-cpu-vectors : Specifies the list of CPU interrupt vectors to which the GIC may not route interrupts. Valid values are 2 - 7. This property is ignored if the CPU is started in EIC mode. +- mti,reserved-ipi-vectors : Specifies the range of GIC interrupts that are + reserved for IPIs. + It accepts 2 values, the 1st is the starting interrupt and the 2nd is the size + of the reserved range. + If not specified, the driver will allocate the last 2 * number of VPEs in the + system. Required properties for timer sub-node: - compatible : Should be "mti,gic-timer". @@ -44,6 +50,7 @@ Example: #interrupt-cells = <3>; mti,reserved-cpu-vectors = <7>; + mti,reserved-ipi-vectors = <40 8>; timer { compatible = "mti,gic-timer"; diff --git a/Documentation/devicetree/bindings/arm/mrvl/intc.txt b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt index 8b53273cb22f..8b53273cb22f 100644 --- a/Documentation/devicetree/bindings/arm/mrvl/intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt diff --git a/Documentation/devicetree/bindings/arm/lpc32xx-mic.txt b/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.txt index 539adca19e8f..539adca19e8f 100644 --- a/Documentation/devicetree/bindings/arm/lpc32xx-mic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/nxp,lpc3220-mic.txt diff --git a/Documentation/devicetree/bindings/open-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt index 909a902dff85..909a902dff85 100644 --- a/Documentation/devicetree/bindings/open-pic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/open-pic.txt diff --git a/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt index ec96b1f01478..475ae9bd562b 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/qca,ath79-misc-intc.txt @@ -22,7 +22,7 @@ Interrupt Controllers bindings used by client devices. Example: interrupt-controller@18060010 { - compatible = "qca,ar9132-misc-intc", qca,ar7100-misc-intc"; + compatible = "qca,ar9132-misc-intc", "qca,ar7100-misc-intc"; reg = <0x18060010 0x4>; interrupt-parent = <&cpuintc>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt index 63633bdea7e4..ae5054c27c99 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt @@ -10,6 +10,7 @@ Required properties: - "renesas,irqc-r8a7792" (R-Car V2H) - "renesas,irqc-r8a7793" (R-Car M2-N) - "renesas,irqc-r8a7794" (R-Car E2) + - "renesas,intc-ex-r8a7795" (R-Car H3) - #interrupt-cells: has to be <2>: an interrupt index and flags, as defined in interrupts.txt in this directory - clocks: Must contain a reference to the functional clock. diff --git a/Documentation/devicetree/bindings/arm/samsung/interrupt-combiner.txt b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt index 9e5f73412cd7..9e5f73412cd7 100644 --- a/Documentation/devicetree/bindings/arm/samsung/interrupt-combiner.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/samsung,exynos4210-combiner.txt diff --git a/Documentation/devicetree/bindings/interrupt-controller/sigma,smp8642-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/sigma,smp8642-intc.txt new file mode 100644 index 000000000000..1f441fa0ad40 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/sigma,smp8642-intc.txt @@ -0,0 +1,49 @@ +Sigma Designs SMP86xx/SMP87xx secondary interrupt controller + +Required properties: +- compatible: should be "sigma,smp8642-intc" +- reg: physical address of MMIO region +- ranges: address space mapping of child nodes +- interrupt-parent: phandle of parent interrupt controller +- interrupt-controller: boolean +- #address-cells: should be <1> +- #size-cells: should be <1> + +One child node per control block with properties: +- reg: address of registers for this control block +- interrupt-controller: boolean +- #interrupt-cells: should be <2>, interrupt index and flags per interrupts.txt +- interrupts: interrupt spec of primary interrupt controller + +Example: + +interrupt-controller@6e000 { + compatible = "sigma,smp8642-intc"; + reg = <0x6e000 0x400>; + ranges = <0x0 0x6e000 0x400>; + interrupt-parent = <&gic>; + interrupt-controller; + #address-cells = <1>; + #size-cells = <1>; + + irq0: interrupt-controller@0 { + reg = <0x000 0x100>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 2 IRQ_TYPE_LEVEL_HIGH>; + }; + + irq1: interrupt-controller@100 { + reg = <0x100 0x100>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 3 IRQ_TYPE_LEVEL_HIGH>; + }; + + irq2: interrupt-controller@300 { + reg = <0x300 0x100>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>; + }; +}; diff --git a/Documentation/devicetree/bindings/arc/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.txt index 9a5d562435ea..9a5d562435ea 100644 --- a/Documentation/devicetree/bindings/arc/interrupts.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/snps,arc700-intc.txt diff --git a/Documentation/devicetree/bindings/arc/archs-idu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt index 0dcb7c7d3e40..0dcb7c7d3e40 100644 --- a/Documentation/devicetree/bindings/arc/archs-idu-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt diff --git a/Documentation/devicetree/bindings/arc/archs-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.txt index 69f326d6a5ad..69f326d6a5ad 100644 --- a/Documentation/devicetree/bindings/arc/archs-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-intc.txt diff --git a/Documentation/devicetree/bindings/arm/spear/shirq.txt b/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt index 715a013ed4bd..715a013ed4bd 100644 --- a/Documentation/devicetree/bindings/arm/spear/shirq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/st,spear3xx-shirq.txt diff --git a/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800.txt b/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800.txt new file mode 100644 index 000000000000..7f15f1b0325b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/technologic,ts4800.txt @@ -0,0 +1,16 @@ +TS-4800 FPGA interrupt controller + +TS-4800 FPGA has an internal interrupt controller. When one of the +interrupts is triggered, the SoC is notified, usually using a GPIO as +parent interrupt source. + +Required properties: +- compatible: should be "technologic,ts4800-irqc" +- interrupt-controller: identifies the node as an interrupt controller +- reg: physical base address of the controller and length of memory mapped + region +- #interrupt-cells: specifies the number of cells needed to encode an interrupt + source, should be 1. +- interrupt-parent: phandle to the parent interrupt controller this one is + cascaded from +- interrupts: specifies the interrupt line in the interrupt-parent controller diff --git a/Documentation/devicetree/bindings/c6x/interrupt.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,c64x+megamod-pic.txt index 42bb796cc4ad..42bb796cc4ad 100644 --- a/Documentation/devicetree/bindings/c6x/interrupt.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,c64x+megamod-pic.txt diff --git a/Documentation/devicetree/bindings/arm/davinci/cp-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.txt index 597e8a089fe4..597e8a089fe4 100644 --- a/Documentation/devicetree/bindings/arm/davinci/cp-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,cp-intc.txt diff --git a/Documentation/devicetree/bindings/arm/omap/intc.txt b/Documentation/devicetree/bindings/interrupt-controller/ti,omap2-intc.txt index f2583e6ec060..f2583e6ec060 100644 --- a/Documentation/devicetree/bindings/arm/omap/intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/ti,omap2-intc.txt diff --git a/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.txt index 0a4ce1051b02..0a4ce1051b02 100644 --- a/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/via,vt8500-intc.txt diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt b/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt index 3443e0f838df..947863acc2d4 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt +++ b/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt @@ -36,5 +36,24 @@ the PCIe specification. NOTE: this only applies to the SMMU itself, not masters connected upstream of the SMMU. +- msi-parent : See the generic MSI binding described in + devicetree/bindings/interrupt-controller/msi.txt + for a description of the msi-parent property. + - hisilicon,broken-prefetch-cmd : Avoid sending CMD_PREFETCH_* commands to the SMMU. + +** Example + + smmu@2b400000 { + compatible = "arm,smmu-v3"; + reg = <0x0 0x2b400000 0x0 0x20000>; + interrupts = <GIC_SPI 74 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 75 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 77 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 79 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "eventq", "priq", "cmdq-sync", "gerror"; + dma-coherent; + #iommu-cells = <0>; + msi-parent = <&its 0xff0000>; + }; diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt index cd29083e16ec..48ffb38f699e 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -7,7 +7,15 @@ connected to the IPMMU through a port called micro-TLB. Required Properties: - - compatible: Must contain "renesas,ipmmu-vmsa". + - compatible: Must contain SoC-specific and generic entries from below. + + - "renesas,ipmmu-r8a73a4" for the R8A73A4 (R-Mobile APE6) IPMMU. + - "renesas,ipmmu-r8a7790" for the R8A7790 (R-Car H2) IPMMU. + - "renesas,ipmmu-r8a7791" for the R8A7791 (R-Car M2-W) IPMMU. + - "renesas,ipmmu-r8a7793" for the R8A7793 (R-Car M2-N) IPMMU. + - "renesas,ipmmu-r8a7794" for the R8A7794 (R-Car E2) IPMMU. + - "renesas,ipmmu-vmsa" for generic R-Car Gen2 VMSA-compatible IPMMU. + - reg: Base address and size of the IPMMU registers. - interrupts: Specifiers for the MMU fault interrupts. For instances that support secure mode two interrupts must be specified, for non-secure and @@ -27,7 +35,7 @@ node with the following property: Example: R8A7791 IPMMU-MX and VSP1-D0 bus master ipmmu_mx: mmu@fe951000 { - compatible = "renasas,ipmmu-vmsa"; + compatible = "renasas,ipmmu-r8a7791", "renasas,ipmmu-vmsa"; reg = <0 0xfe951000 0 0x1000>; interrupts = <0 222 IRQ_TYPE_LEVEL_HIGH>, <0 221 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt index 729543c47046..bc620fe32a70 100644 --- a/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt +++ b/Documentation/devicetree/bindings/iommu/samsung,sysmmu.txt @@ -47,7 +47,7 @@ Required properties: - clocks: Required if the System MMU is needed to gate its clock. - power-domains: Required if the System MMU is needed to gate its power. Please refer to the following document: - Documentation/devicetree/bindings/arm/exynos/power_domain.txt + Documentation/devicetree/bindings/power/pd-samsung.txt Examples: gsc_0: gsc@13e00000 { diff --git a/Documentation/devicetree/bindings/iommu/ti,omap-iommu.txt b/Documentation/devicetree/bindings/iommu/ti,omap-iommu.txt index 869699925fd5..4bd10dd881b8 100644 --- a/Documentation/devicetree/bindings/iommu/ti,omap-iommu.txt +++ b/Documentation/devicetree/bindings/iommu/ti,omap-iommu.txt @@ -4,6 +4,7 @@ Required properties: - compatible : Should be one of, "ti,omap2-iommu" for OMAP2/OMAP3 IOMMU instances "ti,omap4-iommu" for OMAP4/OMAP5 IOMMU instances + "ti,dra7-dsp-iommu" for DRA7xx DSP IOMMU instances "ti,dra7-iommu" for DRA7xx IOMMU instances - ti,hwmods : Name of the hwmod associated with the IOMMU instance - reg : Address space for the configuration registers @@ -19,6 +20,13 @@ Optional properties: Should be either 8 or 32 (default: 32) - ti,iommu-bus-err-back : Indicates the IOMMU instance supports throwing back a bus error response on MMU faults. +- ti,syscon-mmuconfig : Should be a pair of the phandle to the DSP_SYSTEM + syscon node that contains the additional control + register for enabling the MMU, and the MMU instance + number (0-indexed) within the sub-system. This property + is required for DSP IOMMU instances on DRA7xx SoCs. The + instance number should be 0 for DSP MDMA MMUs and 1 for + DSP EDMA MMUs. Example: /* OMAP3 ISP MMU */ @@ -30,3 +38,22 @@ Example: ti,hwmods = "mmu_isp"; ti,#tlb-entries = <8>; }; + + /* DRA74x DSP2 MMUs */ + mmu0_dsp2: mmu@41501000 { + compatible = "ti,dra7-dsp-iommu"; + reg = <0x41501000 0x100>; + interrupts = <GIC_SPI 146 IRQ_TYPE_LEVEL_HIGH>; + ti,hwmods = "mmu0_dsp2"; + #iommu-cells = <0>; + ti,syscon-mmuconfig = <&dsp2_system 0x0>; + }; + + mmu1_dsp2: mmu@41502000 { + compatible = "ti,dra7-dsp-iommu"; + reg = <0x41502000 0x100>; + interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>; + ti,hwmods = "mmu1_dsp2"; + #iommu-cells = <0>; + ti,syscon-mmuconfig = <&dsp2_system 0x1>; + }; diff --git a/Documentation/devicetree/bindings/video/backlight/88pm860x.txt b/Documentation/devicetree/bindings/leds/backlight/88pm860x.txt index 261df2799315..261df2799315 100644 --- a/Documentation/devicetree/bindings/video/backlight/88pm860x.txt +++ b/Documentation/devicetree/bindings/leds/backlight/88pm860x.txt diff --git a/Documentation/devicetree/bindings/video/backlight/gpio-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt index 321be6640533..321be6640533 100644 --- a/Documentation/devicetree/bindings/video/backlight/gpio-backlight.txt +++ b/Documentation/devicetree/bindings/leds/backlight/gpio-backlight.txt diff --git a/Documentation/devicetree/bindings/video/backlight/lp855x.txt b/Documentation/devicetree/bindings/leds/backlight/lp855x.txt index 0a3ecbc3a1b9..0a3ecbc3a1b9 100644 --- a/Documentation/devicetree/bindings/video/backlight/lp855x.txt +++ b/Documentation/devicetree/bindings/leds/backlight/lp855x.txt diff --git a/Documentation/devicetree/bindings/video/backlight/max8925-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt index b4cffdaa4137..b4cffdaa4137 100644 --- a/Documentation/devicetree/bindings/video/backlight/max8925-backlight.txt +++ b/Documentation/devicetree/bindings/leds/backlight/max8925-backlight.txt diff --git a/Documentation/devicetree/bindings/video/backlight/pm8941-wled.txt b/Documentation/devicetree/bindings/leds/backlight/pm8941-wled.txt index 424f8444a6cd..e5b294dafc58 100644 --- a/Documentation/devicetree/bindings/video/backlight/pm8941-wled.txt +++ b/Documentation/devicetree/bindings/leds/backlight/pm8941-wled.txt @@ -5,6 +5,8 @@ Required properties: - reg: slave address Optional properties: +- default-brightness: brightness value on boot, value from: 0-4095 + default: 2048 - label: The name of the backlight device - qcom,cs-out: bool; enable current sink output - qcom,cabc: bool; enable content adaptive backlight control diff --git a/Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt index 764db86d441a..764db86d441a 100644 --- a/Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt +++ b/Documentation/devicetree/bindings/leds/backlight/pwm-backlight.txt diff --git a/Documentation/devicetree/bindings/video/backlight/sky81452-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/sky81452-backlight.txt index 8bf2940f54bc..8bf2940f54bc 100644 --- a/Documentation/devicetree/bindings/video/backlight/sky81452-backlight.txt +++ b/Documentation/devicetree/bindings/leds/backlight/sky81452-backlight.txt diff --git a/Documentation/devicetree/bindings/video/backlight/tps65217-backlight.txt b/Documentation/devicetree/bindings/leds/backlight/tps65217-backlight.txt index 5fb9279ac287..5fb9279ac287 100644 --- a/Documentation/devicetree/bindings/video/backlight/tps65217-backlight.txt +++ b/Documentation/devicetree/bindings/leds/backlight/tps65217-backlight.txt diff --git a/Documentation/devicetree/bindings/leds/leds-aat1290.txt b/Documentation/devicetree/bindings/leds/leds-aat1290.txt index c05ed91a4e42..85c0c58617f6 100644 --- a/Documentation/devicetree/bindings/leds/leds-aat1290.txt +++ b/Documentation/devicetree/bindings/leds/leds-aat1290.txt @@ -27,9 +27,9 @@ Required properties of the LED child node: - flash-max-microamp : see Documentation/devicetree/bindings/leds/common.txt Maximum flash LED supply current can be calculated using following formula: I = 1A * 162kohm / Rset. -- flash-timeout-us : see Documentation/devicetree/bindings/leds/common.txt - Maximum flash timeout can be calculated using following - formula: T = 8.82 * 10^9 * Ct. +- flash-max-timeout-us : see Documentation/devicetree/bindings/leds/common.txt + Maximum flash timeout can be calculated using following + formula: T = 8.82 * 10^9 * Ct. Optional properties of the LED child node: - label : see Documentation/devicetree/bindings/leds/common.txt @@ -54,7 +54,7 @@ aat1290 { label = "aat1290-flash"; led-max-microamp = <520833>; flash-max-microamp = <1012500>; - flash-timeout-us = <1940000>; + flash-max-timeout-us = <1940000>; }; }; diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt index f9e36adc0ebf..3f48c1eaf085 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt +++ b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt @@ -29,6 +29,14 @@ Required properties: Optional properties: - brcm,serial-leds : Boolean, enables Serial LEDs. Default : false + - brcm,serial-mux : Boolean, enables Serial LEDs multiplexing. + Default : false + - brcm,serial-clk-low : Boolean, makes clock signal active low. + Default : false + - brcm,serial-dat-low : Boolean, makes data signal active low. + Default : false + - brcm,serial-shift-inv : Boolean, inverts Serial LEDs shift direction. + Default : false Each LED is represented as a sub-node of the brcm,bcm6328-leds device. @@ -110,6 +118,8 @@ Scenario 2 : BCM63268 with Serial/GPHY0 LEDs #size-cells = <0>; reg = <0x10001900 0x24>; brcm,serial-leds; + brcm,serial-dat-low; + brcm,serial-shift-inv; gphy0_spd0@0 { reg = <0>; diff --git a/Documentation/devicetree/bindings/leds/leds-is31fl32xx.txt b/Documentation/devicetree/bindings/leds/leds-is31fl32xx.txt new file mode 100644 index 000000000000..926c2117942c --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-is31fl32xx.txt @@ -0,0 +1,52 @@ +Binding for ISSI IS31FL32xx and Si-En SN32xx LED Drivers + +The IS31FL32xx/SN32xx family of LED drivers are I2C devices with multiple +constant-current channels, each with independent 256-level PWM control. +Each LED is represented as a sub-node of the device. + +Required properties: +- compatible: one of + issi,is31fl3236 + issi,is31fl3235 + issi,is31fl3218 + issi,is31fl3216 + si-en,sn3218 + si-en,sn3216 +- reg: I2C slave address +- address-cells : must be 1 +- size-cells : must be 0 + +LED sub-node properties: +- reg : LED channel number (1..N) +- label : (optional) + see Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger : (optional) + see Documentation/devicetree/bindings/leds/common.txt + + +Example: + +is31fl3236: led-controller@3c { + compatible = "issi,is31fl3236"; + reg = <0x3c>; + #address-cells = <1>; + #size-cells = <0>; + + led@1 { + reg = <1>; + label = "EB:blue:usr0"; + }; + led@2 { + reg = <2>; + label = "EB:blue:usr1"; + }; + ... + led@36 { + reg = <36>; + label = "EB:blue:usr35"; + }; +}; + +For more product information please see the links below: +http://www.issi.com/US/product-analog-fxled-driver.shtml +http://www.si-en.com/product.asp?parentid=890 diff --git a/Documentation/devicetree/bindings/leds/leds-netxbig.txt b/Documentation/devicetree/bindings/leds/leds-netxbig.txt new file mode 100644 index 000000000000..5ef92a26d768 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-netxbig.txt @@ -0,0 +1,92 @@ +Binding for the CPLD LEDs (GPIO extension bus) found on some LaCie/Seagate +boards (Example: 2Big/5Big Network v2, 2Big NAS). + +Required properties: +- compatible: "lacie,netxbig-leds". +- gpio-ext: Phandle for the gpio-ext bus. + +Optional properties: +- timers: Timer array. Each timer entry is represented by three integers: + Mode (gpio-ext bus), delay_on and delay_off. + +Each LED is represented as a sub-node of the netxbig-leds device. + +Required sub-node properties: +- mode-addr: Mode register address on gpio-ext bus. +- mode-val: Mode to value mapping. Each entry is represented by two integers: + A mode and the corresponding value on the gpio-ext bus. +- bright-addr: Brightness register address on gpio-ext bus. +- max-brightness: Maximum brightness value. + +Optional sub-node properties: +- label: Name for this LED. If omitted, the label is taken from the node name. +- linux,default-trigger: Trigger assigned to the LED. + +Example: + +netxbig-leds { + compatible = "lacie,netxbig-leds"; + + gpio-ext = &gpio_ext; + + timers = <NETXBIG_LED_TIMER1 500 500 + NETXBIG_LED_TIMER2 500 1000>; + + blue-power { + label = "netxbig:blue:power"; + mode-addr = <0>; + mode-val = <NETXBIG_LED_OFF 0 + NETXBIG_LED_ON 1 + NETXBIG_LED_TIMER1 3 + NETXBIG_LED_TIMER2 7>; + bright-addr = <1>; + max-brightness = <7>; + }; + red-power { + label = "netxbig:red:power"; + mode-addr = <0>; + mode-val = <NETXBIG_LED_OFF 0 + NETXBIG_LED_ON 2 + NETXBIG_LED_TIMER1 4>; + bright-addr = <1>; + max-brightness = <7>; + }; + blue-sata0 { + label = "netxbig:blue:sata0"; + mode-addr = <3>; + mode-val = <NETXBIG_LED_OFF 0 + NETXBIG_LED_ON 7 + NETXBIG_LED_SATA 1 + NETXBIG_LED_TIMER1 3>; + bright-addr = <2>; + max-brightness = <7>; + }; + red-sata0 { + label = "netxbig:red:sata0"; + mode-addr = <3>; + mode-val = <NETXBIG_LED_OFF 0 + NETXBIG_LED_ON 2 + NETXBIG_LED_TIMER1 4>; + bright-addr = <2>; + max-brightness = <7>; + }; + blue-sata1 { + label = "netxbig:blue:sata1"; + mode-addr = <4>; + mode-val = <NETXBIG_LED_OFF 0 + NETXBIG_LED_ON 7 + NETXBIG_LED_SATA 1 + NETXBIG_LED_TIMER1 3>; + bright-addr = <2>; + max-brightness = <7>; + }; + red-sata1 { + label = "netxbig:red:sata1"; + mode-addr = <4>; + mode-val = <NETXBIG_LED_OFF 0 + NETXBIG_LED_ON 2 + NETXBIG_LED_TIMER1 4>; + bright-addr = <2>; + max-brightness = <7>; + }; +}; diff --git a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt index d1a043339c11..9b40c4925aa9 100644 --- a/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt +++ b/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt @@ -75,6 +75,14 @@ data that represent the following: Cell #3 (usr_id) - mailbox user id for identifying the interrupt line associated with generating a tx/rx fifo interrupt. +Optional Properties: +-------------------- +- ti,mbox-send-noirq: Quirk flag to allow the client user of this sub-mailbox + to send messages without triggering a Tx ready interrupt, + and to control the Tx ticker. Should be used only on + sub-mailboxes used to communicate with WkupM3 remote + processor on AM33xx/AM43xx SoCs. + Mailbox Users: ============== A device needing to communicate with a target processor device should specify diff --git a/Documentation/devicetree/bindings/mailbox/sti-mailbox.txt b/Documentation/devicetree/bindings/mailbox/sti-mailbox.txt new file mode 100644 index 000000000000..b61eec920359 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/sti-mailbox.txt @@ -0,0 +1,51 @@ +ST Microelectronics Mailbox Driver + +Each ST Mailbox IP currently consists of 4 instances of 32 channels. Messages +are passed between Application and Remote processors using shared memory. + +Controller +---------- + +Required properties: +- compatible : Should be "st,stih407-mailbox" +- reg : Offset and length of the device's register set +- mbox-name : Name of the mailbox +- #mbox-cells: : Must be 2 + <&phandle instance channel direction> + phandle : Label name of controller + instance : Instance number + channel : Channel number + +Optional properties +- interrupts : Contains the IRQ line for a Rx mailbox + +Example: + +mailbox0: mailbox@0 { + compatible = "st,stih407-mailbox"; + reg = <0x08f00000 0x1000>; + interrupts = <GIC_SPI 1 IRQ_TYPE_NONE>; + #mbox-cells = <2>; + mbox-name = "a9"; +}; + +Client +------ + +Required properties: +- compatible : Many (See the client docs) +- reg : Shared (between Application and Remote) memory address +- mboxes : Standard property to specify a Mailbox (See ./mailbox.txt) + Cells must match 'mbox-cells' (See Controller docs above) + +Optional properties +- mbox-names : Name given to channels seen in the 'mboxes' property. + +Example: + +mailbox_test { + compatible = "mailbox_test"; + reg = <0x[shared_memory_address], [shared_memory_size]>; + mboxes = <&mailbox2 0 1>, <&mailbox0 2 1>; + mbox-names = "tx", "rx"; +}; diff --git a/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt b/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt index 4ef45636ebde..38941db23dd2 100644 --- a/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt +++ b/Documentation/devicetree/bindings/media/exynos-jpeg-codec.txt @@ -4,7 +4,8 @@ Required properties: - compatible : should be one of: "samsung,s5pv210-jpeg", "samsung,exynos4210-jpeg", - "samsung,exynos3250-jpeg", "samsung,exynos5420-jpeg"; + "samsung,exynos3250-jpeg", "samsung,exynos5420-jpeg", + "samsung,exynos5433-jpeg"; - reg : address and length of the JPEG codec IP register set; - interrupts : specifies the JPEG codec IP interrupt; - clock-names : should contain: diff --git a/Documentation/devicetree/bindings/media/exynos5-gsc.txt b/Documentation/devicetree/bindings/media/exynos5-gsc.txt index 0604d42f38d1..5fe9372abb37 100644 --- a/Documentation/devicetree/bindings/media/exynos5-gsc.txt +++ b/Documentation/devicetree/bindings/media/exynos5-gsc.txt @@ -7,6 +7,10 @@ Required properties: - reg: should contain G-Scaler physical address location and length. - interrupts: should contain G-Scaler interrupt number +Optional properties: +- samsung,sysreg: handle to syscon used to control the system registers to + set writeback input and destination + Example: gsc_0: gsc@0x13e00000 { diff --git a/Documentation/devicetree/bindings/media/i2c/adp1653.txt b/Documentation/devicetree/bindings/media/i2c/adp1653.txt index 5ce66f2104e3..4cce0de40ee9 100644 --- a/Documentation/devicetree/bindings/media/i2c/adp1653.txt +++ b/Documentation/devicetree/bindings/media/i2c/adp1653.txt @@ -12,12 +12,13 @@ There are two LED outputs available - flash and indicator. One LED is represented by one child node, nodes need to be named "flash" and "indicator". Required properties of the LED child node: -- max-microamp : see Documentation/devicetree/bindings/leds/common.txt +- led-max-microamp : see Documentation/devicetree/bindings/leds/common.txt Required properties of the flash LED child node: - flash-max-microamp : see Documentation/devicetree/bindings/leds/common.txt - flash-timeout-us : see Documentation/devicetree/bindings/leds/common.txt +- led-max-microamp : see Documentation/devicetree/bindings/leds/common.txt Example: @@ -29,9 +30,9 @@ Example: flash { flash-timeout-us = <500000>; flash-max-microamp = <320000>; - max-microamp = <50000>; + led-max-microamp = <50000>; }; indicator { - max-microamp = <17500>; + led-max-microamp = <17500>; }; }; diff --git a/Documentation/devicetree/bindings/media/i2c/mt9v032.txt b/Documentation/devicetree/bindings/media/i2c/mt9v032.txt index 202565313e82..100f0ae43269 100644 --- a/Documentation/devicetree/bindings/media/i2c/mt9v032.txt +++ b/Documentation/devicetree/bindings/media/i2c/mt9v032.txt @@ -20,6 +20,8 @@ Optional Properties: - link-frequencies: List of allowed link frequencies in Hz. Each frequency is expressed as a 64-bit big-endian integer. +- reset-gpios: GPIO handle which is connected to the reset pin of the chip. +- standby-gpios: GPIO handle which is connected to the standby pin of the chip. For further reading on port node refer to Documentation/devicetree/bindings/media/video-interfaces.txt. diff --git a/Documentation/devicetree/bindings/media/i2c/tvp5150.txt b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt new file mode 100644 index 000000000000..8c0fc1a26bf0 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/tvp5150.txt @@ -0,0 +1,45 @@ +* Texas Instruments TVP5150 and TVP5151 video decoders + +The TVP5150 and TVP5151 are video decoders that convert baseband NTSC and PAL +(and also SECAM in the TVP5151 case) video signals to either 8-bit 4:2:2 YUV +with discrete syncs or 8-bit ITU-R BT.656 with embedded syncs output formats. + +Required Properties: +- compatible: value must be "ti,tvp5150" +- reg: I2C slave address + +Optional Properties: +- pdn-gpios: phandle for the GPIO connected to the PDN pin, if any. +- reset-gpios: phandle for the GPIO connected to the RESETB pin, if any. + +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. + +Required Endpoint Properties for parallel synchronization: + +- hsync-active: active state of the HSYNC signal. Must be <1> (HIGH). +- vsync-active: active state of the VSYNC signal. Must be <1> (HIGH). +- field-even-active: field signal level during the even field data + transmission. Must be <0>. + +If none of hsync-active, vsync-active and field-even-active is specified, +the endpoint is assumed to use embedded BT.656 synchronization. + +Example: + +&i2c2 { + ... + tvp5150@5c { + compatible = "ti,tvp5150"; + reg = <0x5c>; + pdn-gpios = <&gpio4 30 GPIO_ACTIVE_LOW>; + reset-gpios = <&gpio6 7 GPIO_ACTIVE_LOW>; + + port { + tvp5150_1: endpoint { + remote-endpoint = <&ccdc_ep>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 9dafe6b06cd2..619193ccf7ff 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -6,6 +6,7 @@ family of devices. The current blocks are always slaves and suppot one input channel which can be either RGB, YUYV or BT656. - compatible: Must be one of the following + - "renesas,vin-r8a7795" for the R8A7795 device - "renesas,vin-r8a7794" for the R8A7794 device - "renesas,vin-r8a7793" for the R8A7793 device - "renesas,vin-r8a7791" for the R8A7791 device diff --git a/Documentation/devicetree/bindings/media/renesas,jpu.txt b/Documentation/devicetree/bindings/media/renesas,jpu.txt index 0cb94201bf92..d3436e5190f9 100644 --- a/Documentation/devicetree/bindings/media/renesas,jpu.txt +++ b/Documentation/devicetree/bindings/media/renesas,jpu.txt @@ -5,11 +5,12 @@ and decoding function conforming to the JPEG baseline process, so that the JPU can encode image data and decode JPEG data quickly. Required properties: - - compatible: should containg one of the following: - - "renesas,jpu-r8a7790" for R-Car H2 - - "renesas,jpu-r8a7791" for R-Car M2-W - - "renesas,jpu-r8a7792" for R-Car V2H - - "renesas,jpu-r8a7793" for R-Car M2-N +- compatible: "renesas,jpu-<soctype>", "renesas,rcar-gen2-jpu" as fallback. + Examples with soctypes are: + - "renesas,jpu-r8a7790" for R-Car H2 + - "renesas,jpu-r8a7791" for R-Car M2-W + - "renesas,jpu-r8a7792" for R-Car V2H + - "renesas,jpu-r8a7793" for R-Car M2-N - reg: Base address and length of the registers block for the JPU. - interrupts: JPU interrupt specifier. @@ -17,7 +18,7 @@ Required properties: Example: R8A7790 (R-Car H2) JPU node jpeg-codec@fe980000 { - compatible = "renesas,jpu-r8a7790"; + compatible = "renesas,jpu-r8a7790", "renesas,rcar-gen2-jpu"; reg = <0 0xfe980000 0 0x10300>; interrupts = <0 272 IRQ_TYPE_LEVEL_HIGH>; clocks = <&mstp1_clks R8A7790_CLK_JPU>; diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt index 87fe08abf36d..627405abd144 100644 --- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt +++ b/Documentation/devicetree/bindings/media/renesas,vsp1.txt @@ -1,30 +1,18 @@ -* Renesas VSP1 Video Processing Engine +* Renesas VSP Video Processing Engine -The VSP1 is a video processing engine that supports up-/down-scaling, alpha +The VSP is a video processing engine that supports up-/down-scaling, alpha blending, color space conversion and various other image processing features. It can be found in the Renesas R-Car second generation SoCs. Required properties: - - compatible: Must contain "renesas,vsp1" + - compatible: Must contain one of the following values + - "renesas,vsp1" for the R-Car Gen2 VSP1 + - "renesas,vsp2" for the R-Car Gen3 VSP2 - - reg: Base address and length of the registers block for the VSP1. - - interrupts: VSP1 interrupt specifier. - - clocks: A phandle + clock-specifier pair for the VSP1 functional clock. - - - renesas,#rpf: Number of Read Pixel Formatter (RPF) modules in the VSP1. - - renesas,#uds: Number of Up Down Scaler (UDS) modules in the VSP1. - - renesas,#wpf: Number of Write Pixel Formatter (WPF) modules in the VSP1. - - -Optional properties: - - - renesas,has-lif: Boolean, indicates that the LCD Interface (LIF) module is - available. - - renesas,has-lut: Boolean, indicates that the Look Up Table (LUT) module is - available. - - renesas,has-sru: Boolean, indicates that the Super Resolution Unit (SRU) - module is available. + - reg: Base address and length of the registers block for the VSP. + - interrupts: VSP interrupt specifier. + - clocks: A phandle + clock-specifier pair for the VSP functional clock. Example: R8A7790 (R-Car H2) VSP1-S node @@ -34,10 +22,4 @@ Example: R8A7790 (R-Car H2) VSP1-S node reg = <0 0xfe928000 0 0x8000>; interrupts = <0 267 IRQ_TYPE_LEVEL_HIGH>; clocks = <&mstp1_clks R8A7790_CLK_VSP1_S>; - - renesas,has-lut; - renesas,has-sru; - renesas,#rpf = <5>; - renesas,#uds = <3>; - renesas,#wpf = <4>; }; diff --git a/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt b/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt index d4def767bdfe..cc51b1fd6e0c 100644 --- a/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt +++ b/Documentation/devicetree/bindings/media/stih407-c8sectpfe.txt @@ -35,7 +35,7 @@ Required properties (tsin (child) node): - tsin-num : tsin id of the InputBlock (must be between 0 to 6) - i2c-bus : phandle to the I2C bus DT node which the demodulators & tuners on this tsin channel are connected. -- rst-gpio : reset gpio for this tsin channel. +- reset-gpios : reset gpio for this tsin channel. Optional properties (tsin (child) node): @@ -55,27 +55,27 @@ Example: status = "okay"; reg = <0x08a20000 0x10000>, <0x08a00000 0x4000>; reg-names = "stfe", "stfe-ram"; - interrupts = <0 34 0>, <0 35 0>; + interrupts = <GIC_SPI 34 IRQ_TYPE_NONE>, <GIC_SPI 35 IRQ_TYPE_NONE>; interrupt-names = "stfe-error-irq", "stfe-idle-irq"; - - pinctrl-names = "tsin0-serial", "tsin0-parallel", "tsin3-serial", - "tsin4-serial", "tsin5-serial"; - pinctrl-0 = <&pinctrl_tsin0_serial>; pinctrl-1 = <&pinctrl_tsin0_parallel>; pinctrl-2 = <&pinctrl_tsin3_serial>; pinctrl-3 = <&pinctrl_tsin4_serial_alt3>; pinctrl-4 = <&pinctrl_tsin5_serial_alt1>; - + pinctrl-names = "tsin0-serial", + "tsin0-parallel", + "tsin3-serial", + "tsin4-serial", + "tsin5-serial"; clocks = <&clk_s_c0_flexgen CLK_PROC_STFE>; - clock-names = "stfe"; + clock-names = "c8sectpfe"; /* tsin0 is TSA on NIMA */ tsin0: port@0 { tsin-num = <0>; serial-not-parallel; i2c-bus = <&ssc2>; - rst-gpio = <&pio15 4 0>; + reset-gpios = <&pio15 4 GPIO_ACTIVE_HIGH>; dvb-card = <STV0367_TDA18212_NIMA_1>; }; @@ -83,7 +83,7 @@ Example: tsin-num = <3>; serial-not-parallel; i2c-bus = <&ssc3>; - rst-gpio = <&pio15 7 0>; + reset-gpios = <&pio15 7 GPIO_ACTIVE_HIGH>; dvb-card = <STV0367_TDA18212_NIMB_1>; }; }; diff --git a/Documentation/devicetree/bindings/media/ti-cal.txt b/Documentation/devicetree/bindings/media/ti-cal.txt new file mode 100644 index 000000000000..ae9b52f37576 --- /dev/null +++ b/Documentation/devicetree/bindings/media/ti-cal.txt @@ -0,0 +1,72 @@ +Texas Instruments DRA72x CAMERA ADAPTATION LAYER (CAL) +------------------------------------------------------ + +The Camera Adaptation Layer (CAL) is a key component for image capture +applications. The capture module provides the system interface and the +processing capability to connect CSI2 image-sensor modules to the +DRA72x device. + +Required properties: +- compatible: must be "ti,dra72-cal" +- reg: CAL Top level, Receiver Core #0, Receiver Core #1 and Camera RX + control address space +- reg-names: cal_top, cal_rx_core0, cal_rx_core1, and camerrx_control + registers +- interrupts: should contain IRQ line for the CAL; + +CAL supports 2 camera port nodes on MIPI bus. Each CSI2 camera port nodes +should contain a 'port' child node with child 'endpoint' node. Please +refer to the bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: + cal: cal@4845b000 { + compatible = "ti,dra72-cal"; + ti,hwmods = "cal"; + reg = <0x4845B000 0x400>, + <0x4845B800 0x40>, + <0x4845B900 0x40>, + <0x4A002e94 0x4>; + reg-names = "cal_top", + "cal_rx_core0", + "cal_rx_core1", + "camerrx_control"; + interrupts = <GIC_SPI 119 IRQ_TYPE_LEVEL_HIGH>; + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + csi2_0: port@0 { + reg = <0>; + endpoint { + slave-mode; + remote-endpoint = <&ar0330_1>; + }; + }; + csi2_1: port@1 { + reg = <1>; + }; + }; + }; + + i2c5: i2c@4807c000 { + ar0330@10 { + compatible = "ti,ar0330"; + reg = <0x10>; + + port { + #address-cells = <1>; + #size-cells = <0>; + + ar0330_1: endpoint { + reg = <0>; + clock-lanes = <1>; + data-lanes = <0 2 3 4>; + remote-endpoint = <&csi2_0>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt b/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt index e6df32f9986d..22b77ee02f58 100644 --- a/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt +++ b/Documentation/devicetree/bindings/memory-controllers/arm,pl172.txt @@ -1,8 +1,9 @@ -* Device tree bindings for ARM PL172 MultiPort Memory Controller +* Device tree bindings for ARM PL172/PL175/PL176 MultiPort Memory Controller Required properties: -- compatible: "arm,pl172", "arm,primecell" +- compatible: Must be "arm,primecell" and exactly one from + "arm,pl172", "arm,pl175" or "arm,pl176". - reg: Must contains offset/length value for controller. @@ -56,7 +57,8 @@ Optional child cs node config properties: - mpmc,extended-wait: Enable extended wait. -- mpmc,buffer-enable: Enable write buffer. +- mpmc,buffer-enable: Enable write buffer, option is not supported by + PL175 and PL176 controllers. - mpmc,write-protect: Enable write protect. diff --git a/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt b/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt index efe35a065714..c81af75bcd88 100644 --- a/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt +++ b/Documentation/devicetree/bindings/memory-controllers/ath79-ddr-controller.txt @@ -1,6 +1,6 @@ Binding for Qualcomm Atheros AR7xxx/AR9xxx DDR controller -The DDR controller of the ARxxx and AR9xxx families provides an interface +The DDR controller of the AR7xxx and AR9xxx families provides an interface to flush the FIFO between various devices and the DDR. This is mainly used by the IRQ controller to flush the FIFO before running the interrupt handler of such devices. @@ -11,9 +11,9 @@ Required properties: "qca,[ar7100|ar7240]-ddr-controller" as fallback. On SoC with PCI support "qca,ar7100-ddr-controller" should be used as fallback, otherwise "qca,ar7240-ddr-controller" should be used. -- reg: Base address and size of the controllers memory area -- #qca,ddr-wb-channel-cells: has to be 1, the index of the write buffer - channel +- reg: Base address and size of the controller's memory area +- #qca,ddr-wb-channel-cells: Specifies the number of cells needed to encode + the write buffer channel index, should be 1. Example: diff --git a/Documentation/devicetree/bindings/arm/calxeda/mem-ctrlr.txt b/Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.txt index 049675944b78..049675944b78 100644 --- a/Documentation/devicetree/bindings/arm/calxeda/mem-ctrlr.txt +++ b/Documentation/devicetree/bindings/memory-controllers/calxeda-ddr-ctrlr.txt diff --git a/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt b/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt index c64b7925cd09..9f78e6c82740 100644 --- a/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt +++ b/Documentation/devicetree/bindings/memory-controllers/renesas-memory-controllers.txt @@ -24,9 +24,9 @@ Required properties: Optional properties: - interrupts: Must contain a list of interrupt specifiers for memory controller interrupts, if available. - - interrupts-names: Must contain a list of interrupt names corresponding to - the interrupts in the interrupts property, if available. - Valid interrupt names are: + - interrupt-names: Must contain a list of interrupt names corresponding to + the interrupts in the interrupts property, if available. + Valid interrupt names are: - "sec" (secure interrupt) - "temp" (normal (temperature) interrupt) - power-domains: Must contain a reference to the PM domain that the memory diff --git a/Documentation/devicetree/bindings/mfd/act8945a.txt b/Documentation/devicetree/bindings/mfd/act8945a.txt new file mode 100644 index 000000000000..f71283055685 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/act8945a.txt @@ -0,0 +1,76 @@ +Device-Tree bindings for Active-semi ACT8945A MFD driver + +Required properties: + - compatible: "active-semi,act8945a". + - reg: the I2C slave address for the ACT8945A chip + +The chip exposes two subdevices: + - a regulators: see ../regulator/act8945a-regulator.txt + - a charger: see ../power/act8945a-charger.txt + +Example: + pmic@5b { + compatible = "active-semi,act8945a"; + reg = <0x5b>; + status = "okay"; + + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_charger_chglev>; + active-semi,chglev-gpio = <&pioA 12 GPIO_ACTIVE_HIGH>; + active-semi,input-voltage-threshold-microvolt = <6600>; + active-semi,precondition-timeout = <40>; + active-semi,total-timeout = <3>; + + active-semi,vsel-high; + + regulators { + vdd_1v35_reg: REG_DCDC1 { + regulator-name = "VDD_1V35"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + }; + + vdd_1v2_reg: REG_DCDC2 { + regulator-name = "VDD_1V2"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1300000>; + regulator-always-on; + }; + + vdd_3v3_reg: REG_DCDC3 { + regulator-name = "VDD_3V3"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vdd_fuse_reg: REG_LDO1 { + regulator-name = "VDD_FUSE"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <2500000>; + regulator-always-on; + }; + + vdd_3v3_lp_reg: REG_LDO2 { + regulator-name = "VDD_3V3_LP"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vdd_led_reg: REG_LDO3 { + regulator-name = "VDD_LED"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vdd_sdhc_1v8_reg: REG_LDO4 { + regulator-name = "VDD_SDHC_1V8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/arizona.txt b/Documentation/devicetree/bindings/mfd/arizona.txt index a8fee60dc20d..9b30011ecabe 100644 --- a/Documentation/devicetree/bindings/mfd/arizona.txt +++ b/Documentation/devicetree/bindings/mfd/arizona.txt @@ -1,4 +1,4 @@ -Wolfson Arizona class audio SoCs +Cirrus Logic/Wolfson Microelectronics Arizona class audio SoCs These devices are audio SoCs with extensive digital capabilites and a range of analogue I/O. @@ -6,12 +6,14 @@ of analogue I/O. Required properties: - compatible : One of the following chip-specific strings: + "cirrus,cs47l24" "wlf,wm5102" "wlf,wm5110" "wlf,wm8280" "wlf,wm8997" "wlf,wm8998" "wlf,wm1814" + "wlf,wm1831" - reg : I2C slave address when connected using I2C, chip select number when using SPI. @@ -24,7 +26,7 @@ Required properties: - #interrupt-cells: the number of cells to describe an IRQ, this should be 2. The first cell is the IRQ number. The second cell is the flags, encoded as the trigger masks from - Documentation/devicetree/bindings/interrupts.txt + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - gpio-controller : Indicates this device is a GPIO controller. - #gpio-cells : Must be 2. The first cell is the pin number and the @@ -41,10 +43,20 @@ Required properties: - SPKVDD-supply : Speaker driver power supply (wm8997) + - DCVDD-supply : Main power supply (cs47l24, wm1831) + + - MICVDD-supply : Microphone power supply (cs47l24, wm1831) + Optional properties: - wlf,reset : GPIO specifier for the GPIO controlling /RESET - - wlf,ldoena : GPIO specifier for the GPIO controlling LDOENA + + - clocks: Should reference the clocks supplied on MCLK1 and MCLK2 + - clock-names: Should contains two strings: + "mclk1" for the clock supplied on MCLK1, recommended to be a high + quality audio reference clock + "mclk2" for the clock supplied on MCLK2, recommended to be an always on + 32k clock - wlf,gpio-defaults : A list of GPIO configuration register values. Defines for the appropriate values can found in <dt-bindings/mfd/arizona.txt>. If @@ -60,6 +72,12 @@ Optional properties: that have not been specified are set to 0 by default. Entries are: <IN1, IN2, IN3, IN4> (wm5102, wm5110, wm8280, wm8997) <IN1A, IN2A, IN1B, IN2B> (wm8998, wm1814) + - wlf,out-mono : A list of boolean values indicating whether each output is + mono or stereo. Position within the list indicates the output affected + (eg. First entry in the list corresponds to output 1). A non-zero value + indicates a mono output. If present, the number of values should be less + than or equal to the number of outputs, if less values are supplied the + additional outputs will be treated as stereo. - wlf,dmic-ref : DMIC reference voltage source for each input, can be selected from either MICVDD or one of the MICBIAS's, defines @@ -67,21 +85,14 @@ Optional properties: present, the number of values should be less than or equal to the number of inputs, unspecified inputs will use the chip default. - - wlf,hpdet-channel : Headphone detection channel. - ARIZONA_ACCDET_MODE_HPL or 1 - Headphone detect mode is set to HPDETL - ARIZONA_ACCDET_MODE_HPR or 2 - Headphone detect mode is set to HPDETR - If this node is not mentioned or if the value is unknown, then - headphone detection mode is set to HPDETL. - - DCVDD-supply, MICVDD-supply : Power supplies, only need to be specified if they are being externally supplied. As covered in Documentation/devicetree/bindings/regulator/regulator.txt + (wm5102, wm5110, wm8280, wm8997, wm8998, wm1814) -Optional subnodes: - - ldo1 : Initial data for the LDO1 regulator, as covered in - Documentation/devicetree/bindings/regulator/regulator.txt - - micvdd : Initial data for the MICVDD regulator, as covered in - Documentation/devicetree/bindings/regulator/regulator.txt +Also see child specific device properties: + Regulator - ../regulator/arizona-regulator.txt + Extcon - ../extcon/extcon-arizona.txt Example: diff --git a/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt b/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt new file mode 100644 index 000000000000..692300117c64 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel-flexcom.txt @@ -0,0 +1,63 @@ +* Device tree bindings for Atmel Flexcom (Flexible Serial Communication Unit) + +The Atmel Flexcom is just a wrapper which embeds a SPI controller, an I2C +controller and an USART. Only one function can be used at a time and is chosen +at boot time according to the device tree. + +Required properties: +- compatible: Should be "atmel,sama5d2-flexcom" +- reg: Should be the offset/length value for Flexcom dedicated + I/O registers (without USART, TWI or SPI registers). +- clocks: Should be the Flexcom peripheral clock from PMC. +- #address-cells: Should be <1> +- #size-cells: Should be <1> +- ranges: Should be one range for the full I/O register region + (including USART, TWI and SPI registers). +- atmel,flexcom-mode: Should be one of the following values: + - <1> for USART + - <2> for SPI + - <3> for I2C + +Required child: +A single available child device of type matching the "atmel,flexcom-mode" +property. + +The phandle provided by the clocks property of the child is the same as one for +the Flexcom parent. + +For other properties, please refer to the documentations of the respective +device: +- ../serial/atmel-usart.txt +- ../spi/spi_atmel.txt +- ../i2c/i2c-at91.txt + +Example: + +flexcom@f8034000 { + compatible = "atmel,sama5d2-flexcom"; + reg = <0xf8034000 0x200>; + clocks = <&flx0_clk>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0xf8034000 0x800>; + atmel,flexcom-mode = <2>; + + spi@400 { + compatible = "atmel,at91rm9200-spi"; + reg = <0x400 0x200>; + interrupts = <19 IRQ_TYPE_LEVEL_HIGH 7>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_flx0_default>; + #address-cells = <1>; + #size-cells = <0>; + clocks = <&flx0_clk>; + clock-names = "spi_clk"; + atmel,fifo-size = <32>; + + mtd_dataflash@0 { + compatible = "atmel,at25f512b"; + reg = <0>; + spi-max-frequency = <20000000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt index ad5d90482a0e..670831b29565 100644 --- a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt +++ b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt @@ -15,7 +15,7 @@ Required properties: The HLCDC IP exposes two subdevices: - a PWM chip: see ../pwm/atmel-hlcdc-pwm.txt - - a Display Controller: see ../drm/atmel-hlcdc-dc.txt + - a Display Controller: see ../display/atmel-hlcdc-dc.txt Example: diff --git a/Documentation/devicetree/bindings/mfd/axp20x.txt b/Documentation/devicetree/bindings/mfd/axp20x.txt index 41811223e5be..fd39fa54571b 100644 --- a/Documentation/devicetree/bindings/mfd/axp20x.txt +++ b/Documentation/devicetree/bindings/mfd/axp20x.txt @@ -5,11 +5,12 @@ axp152 (X-Powers) axp202 (X-Powers) axp209 (X-Powers) axp221 (X-Powers) +axp223 (X-Powers) Required properties: - compatible: "x-powers,axp152", "x-powers,axp202", "x-powers,axp209", - "x-powers,axp221" -- reg: The I2C slave address for the AXP chip + "x-powers,axp221", "x-powers,axp223" +- reg: The I2C slave address or RSB hardware address for the AXP chip - interrupt-parent: The parent interrupt controller - interrupts: SoC NMI / GPIO interrupt connected to the PMIC's IRQ pin - interrupt-controller: The PMIC has its own internal IRQs @@ -51,7 +52,7 @@ LDO3 : LDO : ldo3in-supply LDO4 : LDO : ldo24in-supply : shared supply LDO5 : LDO : ldo5in-supply -AXP221 regulators, type, and corresponding input supply names: +AXP221/AXP223 regulators, type, and corresponding input supply names: Regulator Type Supply Name Notes --------- ---- ----------- ----- @@ -60,8 +61,8 @@ DCDC2 : DC-DC buck : vin2-supply DCDC3 : DC-DC buck : vin3-supply DCDC4 : DC-DC buck : vin4-supply DCDC5 : DC-DC buck : vin5-supply -DC1SW : On/Off Switch : dcdc1-supply : DCDC1 secondary output -DC5LDO : LDO : dcdc5-supply : input from DCDC5 +DC1SW : On/Off Switch : : DCDC1 secondary output +DC5LDO : LDO : : input from DCDC5 ALDO1 : LDO : aldoin-supply : shared supply ALDO2 : LDO : aldoin-supply : shared supply ALDO3 : LDO : aldoin-supply : shared supply diff --git a/Documentation/devicetree/bindings/mfd/cros-ec.txt b/Documentation/devicetree/bindings/mfd/cros-ec.txt index 1777916e9e28..136e0c2da44d 100644 --- a/Documentation/devicetree/bindings/mfd/cros-ec.txt +++ b/Documentation/devicetree/bindings/mfd/cros-ec.txt @@ -34,6 +34,10 @@ Required properties (LPC): - compatible: "google,cros-ec-lpc" - reg: List of (IO address, size) pairs defining the interface uses +Optional properties (all): +- google,has-vbc-nvram: Some implementations of the EC include a small + nvram space used to store verified boot context data. This boolean flag + is used to specify whether this nvram is present or not. Example for I2C: diff --git a/Documentation/devicetree/bindings/mfd/da9150.txt b/Documentation/devicetree/bindings/mfd/da9150.txt index d0588eaa0d71..fd4dca7f4aba 100644 --- a/Documentation/devicetree/bindings/mfd/da9150.txt +++ b/Documentation/devicetree/bindings/mfd/da9150.txt @@ -6,6 +6,7 @@ Device Description ------ ----------- da9150-gpadc : General Purpose ADC da9150-charger : Battery Charger +da9150-fg : Battery Fuel-Gauge ====== @@ -16,13 +17,13 @@ Required properties: the IRQs from da9150 are delivered to. - interrupts: IRQ line info for da9150 chip. - interrupt-controller: da9150 has internal IRQs (own IRQ domain). - (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for + (See ../interrupt-controller/interrupts.txt for further information relating to interrupt properties) Sub-devices: -- da9150-gpadc: See Documentation/devicetree/bindings/iio/adc/da9150-gpadc.txt -- da9150-charger: See Documentation/devicetree/bindings/power/da9150-charger.txt - +- da9150-gpadc: See ../iio/adc/da9150-gpadc.txt +- da9150-charger: See ../power/da9150-charger.txt +- da9150-fg: See ../power/da9150-fg.txt Example: @@ -34,10 +35,28 @@ Example: interrupt-controller; gpadc: da9150-gpadc { - ... + compatible = "dlg,da9150-gpadc"; + #io-channel-cells = <1>; + }; + + charger { + compatible = "dlg,da9150-charger"; + + io-channels = <&gpadc 0>, + <&gpadc 2>, + <&gpadc 8>, + <&gpadc 5>; + io-channel-names = "CHAN_IBUS", + "CHAN_VBUS", + "CHAN_TJUNC", + "CHAN_VBAT"; }; - da9150-charger { - ... + fuel-gauge { + compatible = "dlg,da9150-fuel-gauge"; + + dlg,update-interval = <10000>; + dlg,warn-soc-level = /bits/ 8 <15>; + dlg,crit-soc-level = /bits/ 8 <5> }; }; diff --git a/Documentation/devicetree/bindings/mfd/fsl-imx25-tsadc.txt b/Documentation/devicetree/bindings/mfd/fsl-imx25-tsadc.txt new file mode 100644 index 000000000000..b03505286997 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/fsl-imx25-tsadc.txt @@ -0,0 +1,47 @@ +Freescale MX25 ADC/TSC MultiFunction Device (MFD) + +This device combines two general purpose conversion queues one used for general +ADC and the other used for touchscreens. + +Required properties: + - compatible: Should be "fsl,imx25-tsadc". + - reg: Start address and size of the memory area of + the device + - interrupts: Interrupt for this device + (See: ../interrupt-controller/interrupts.txt) + - clocks: An 'ipg' clock (See: ../clock/clock-bindings.txt) + - interrupt-controller: This device is an interrupt controller. It + controls the interrupts of both + conversion queues. + - #interrupt-cells: Should be '<1>'. + - #address-cells: Should be '<1>'. + - #size-cells: Should be '<1>'. + +This device includes two conversion queues which can be added as subnodes. +The first queue is for the touchscreen, the second for general purpose ADC. + +Example: + tscadc: tscadc@50030000 { + compatible = "fsl,imx25-tsadc"; + reg = <0x50030000 0xc>; + interrupts = <46>; + clocks = <&clks 119>; + clock-names = "ipg"; + interrupt-controller; + #interrupt-cells = <1>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + tsc: tcq@50030400 { + compatible = "fsl,imx25-tcq"; + reg = <0x50030400 0x60>; + ... + }; + + adc: gcq@50030800 { + compatible = "fsl,imx25-gcq"; + reg = <0x50030800 0x60>; + ... + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/mt6397.txt b/Documentation/devicetree/bindings/mfd/mt6397.txt index 15043e652699..949c85f8d02c 100644 --- a/Documentation/devicetree/bindings/mfd/mt6397.txt +++ b/Documentation/devicetree/bindings/mfd/mt6397.txt @@ -1,6 +1,6 @@ -MediaTek MT6397 Multifunction Device Driver +MediaTek MT6397/MT6323 Multifunction Device Driver -MT6397 is a multifunction device with the following sub modules: +MT6397/MT6323 is a multifunction device with the following sub modules: - Regulator - RTC - Audio codec @@ -8,14 +8,14 @@ MT6397 is a multifunction device with the following sub modules: - Clock It is interfaced to host controller using SPI interface by a proprietary hardware -called PMIC wrapper or pwrap. MT6397 MFD is a child device of pwrap. +called PMIC wrapper or pwrap. MT6397/MT6323 MFD is a child device of pwrap. See the following for pwarp node definitions: Documentation/devicetree/bindings/soc/pwrap.txt This document describes the binding for MFD device and its sub module. Required properties: -compatible: "mediatek,mt6397" +compatible: "mediatek,mt6397" or "mediatek,mt6323" Optional subnodes: @@ -26,6 +26,8 @@ Optional subnodes: Required properties: - compatible: "mediatek,mt6397-regulator" see Documentation/devicetree/bindings/regulator/mt6397-regulator.txt + - compatible: "mediatek,mt6323-regulator" + see Documentation/devicetree/bindings/regulator/mt6323-regulator.txt - codec Required properties: - compatible: "mediatek,mt6397-codec" diff --git a/Documentation/devicetree/bindings/mfd/palmas.txt b/Documentation/devicetree/bindings/mfd/palmas.txt index eda898978d33..8ae1a32bfb7e 100644 --- a/Documentation/devicetree/bindings/mfd/palmas.txt +++ b/Documentation/devicetree/bindings/mfd/palmas.txt @@ -24,7 +24,7 @@ and also the generic series names - #interrupt-cells : should be set to 2 for IRQ number and flags The first cell is the IRQ number. The second cell is the flags, encoded as the trigger masks from - Documentation/devicetree/bindings/interrupts.txt + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - interrupt-parent : The parent interrupt controller. Optional properties: diff --git a/Documentation/devicetree/bindings/mfd/s2mpa01.txt b/Documentation/devicetree/bindings/mfd/s2mpa01.txt deleted file mode 100644 index c13d3d8c3947..000000000000 --- a/Documentation/devicetree/bindings/mfd/s2mpa01.txt +++ /dev/null @@ -1,90 +0,0 @@ - -* Samsung S2MPA01 Voltage and Current Regulator - -The Samsung S2MPA01 is a multi-function device which includes high -efficiency buck converters including Dual-Phase buck converter, various LDOs, -and an RTC. It is interfaced to the host controller using an I2C interface. -Each sub-block is addressed by the host system using different I2C slave -addresses. - -Required properties: -- compatible: Should be "samsung,s2mpa01-pmic". -- reg: Specifies the I2C slave address of the PMIC block. It should be 0x66. - -Optional properties: -- interrupt-parent: Specifies the phandle of the interrupt controller to which - the interrupts from s2mpa01 are delivered to. -- interrupts: An interrupt specifier for the sole interrupt generated by the - device. - -Optional nodes: -- regulators: The regulators of s2mpa01 that have to be instantiated should be - included in a sub-node named 'regulators'. Regulator nodes and constraints - included in this sub-node use the standard regulator bindings which are - documented elsewhere. - -Properties for BUCK regulator nodes: -- regulator-ramp-delay: ramp delay in uV/us. May be 6250, 12500 - (default), 25000, or 50000. May be 0 for disabling the ramp delay on - BUCK{1,2,3,4}. - - In the absence of the regulator-ramp-delay property, the default ramp - delay will be used. - - NOTE: Some BUCKs share the ramp rate setting i.e. same ramp value will be set - for a particular group of BUCKs. So provide same regulator-ramp-delay=<value>. - - The following BUCKs share ramp settings: - * 1 and 6 - * 2 and 4 - * 8, 9, and 10 - -The following are the names of the regulators that the s2mpa01 PMIC block -supports. Note: The 'n' in LDOn and BUCKn represents the LDO or BUCK number -as per the datasheet of s2mpa01. - - - LDOn - - valid values for n are 1 to 26 - - Example: LDO1, LD02, LDO26 - - BUCKn - - valid values for n are 1 to 10. - - Example: BUCK1, BUCK2, BUCK9 - -Example: - - s2mpa01_pmic@66 { - compatible = "samsung,s2mpa01-pmic"; - reg = <0x66>; - - regulators { - ldo1_reg: LDO1 { - regulator-name = "VDD_ALIVE"; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1000000>; - }; - - ldo2_reg: LDO2 { - regulator-name = "VDDQ_MMC2"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "vdd_mif"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - }; - - buck2_reg: BUCK2 { - regulator-name = "vdd_arm"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - regulator-ramp-delay = <50000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/s2mps11.txt b/Documentation/devicetree/bindings/mfd/s2mps11.txt deleted file mode 100644 index 57a045016fca..000000000000 --- a/Documentation/devicetree/bindings/mfd/s2mps11.txt +++ /dev/null @@ -1,139 +0,0 @@ - -* Samsung S2MPS11, S2MPS13, S2MPS14 and S2MPU02 Voltage and Current Regulator - -The Samsung S2MPS11 is a multi-function device which includes voltage and -current regulators, RTC, charger controller and other sub-blocks. It is -interfaced to the host controller using an I2C interface. Each sub-block is -addressed by the host system using different I2C slave addresses. - -Required properties: -- compatible: Should be "samsung,s2mps11-pmic" or "samsung,s2mps13-pmic" - or "samsung,s2mps14-pmic" or "samsung,s2mpu02-pmic". -- reg: Specifies the I2C slave address of the pmic block. It should be 0x66. - -Optional properties: -- interrupt-parent: Specifies the phandle of the interrupt controller to which - the interrupts from s2mps11 are delivered to. -- interrupts: Interrupt specifiers for interrupt sources. - -Optional nodes: -- clocks: s2mps11, s2mps13 and s5m8767 provide three(AP/CP/BT) buffered 32.768 - KHz outputs, so to register these as clocks with common clock framework - instantiate a sub-node named "clocks". It uses the common clock binding - documented in : - [Documentation/devicetree/bindings/clock/clock-bindings.txt] - The s2mps14 provides two (AP/BT) buffered 32.768 KHz outputs. - - #clock-cells: should be 1. - - - The following is the list of clocks generated by the controller. Each clock - is assigned an identifier and client nodes use this identifier to specify - the clock which they consume. - Clock ID Devices - ---------------------------------------------------------- - 32KhzAP 0 S2MPS11, S2MPS13, S2MPS14, S5M8767 - 32KhzCP 1 S2MPS11, S2MPS13, S5M8767 - 32KhzBT 2 S2MPS11, S2MPS13, S2MPS14, S5M8767 - - - compatible: Should be one of: "samsung,s2mps11-clk", "samsung,s2mps13-clk", - "samsung,s2mps14-clk", "samsung,s5m8767-clk" - -- regulators: The regulators of s2mps11 that have to be instantiated should be -included in a sub-node named 'regulators'. Regulator nodes included in this -sub-node should be of the format as listed below. - - regulator_name { - [standard regulator constraints....]; - }; - - regulator-ramp-delay for BUCKs = [6250/12500/25000(default)/50000] uV/us - - BUCK[2/3/4/6] supports disabling ramp delay on hardware, so explicitly - regulator-ramp-delay = <0> can be used for them to disable ramp delay. - In the absence of the regulator-ramp-delay property, the default ramp - delay will be used. - -NOTE: Some BUCKs share the ramp rate setting i.e. same ramp value will be set -for a particular group of BUCKs. So provide same regulator-ramp-delay<value>. -Grouping of BUCKs sharing ramp rate setting is as follow : BUCK[1, 6], -BUCK[3, 4], and BUCK[7, 8, 10] - -On S2MPS14 the LDO10, LDO11 and LDO12 can be configured to external control -over GPIO. To turn this feature on this property must be added to the regulator -sub-node: - - samsung,ext-control-gpios: GPIO specifier for one GPIO - controlling this regulator (enable/disable); -Example: - LDO12 { - regulator-name = "V_EMMC_2.8V"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - samsung,ext-control-gpios = <&gpk0 2 0>; - }; - - -The regulator constraints inside the regulator nodes use the standard regulator -bindings which are documented elsewhere. - -The following are the names of the regulators that the s2mps11 pmic block -supports. Note: The 'n' in LDOn and BUCKn represents the LDO or BUCK number -as per the datasheet of s2mps11. - - - LDOn - - valid values for n are: - - S2MPS11: 1 to 38 - - S2MPS13: 1 to 40 - - S2MPS14: 1 to 25 - - S2MPU02: 1 to 28 - - Example: LDO1, LDO2, LDO28 - - BUCKn - - valid values for n are: - - S2MPS11: 1 to 10 - - S2MPS13: 1 to 10 - - S2MPS14: 1 to 5 - - S2MPU02: 1 to 7 - - Example: BUCK1, BUCK2, BUCK9 - -Example: - - s2mps11_pmic@66 { - compatible = "samsung,s2mps11-pmic"; - reg = <0x66>; - - s2m_osc: clocks { - compatible = "samsung,s2mps11-clk"; - #clock-cells = <1>; - clock-output-names = "xx", "yy", "zz"; - }; - - regulators { - ldo1_reg: LDO1 { - regulator-name = "VDD_ABB_3.3V"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - }; - - ldo2_reg: LDO2 { - regulator-name = "VDD_ALIVE_1.1V"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "vdd_mif"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - }; - - buck2_reg: BUCK2 { - regulator-name = "vdd_arm"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - regulator-ramp-delay = <50000>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/samsung,sec-core.txt b/Documentation/devicetree/bindings/mfd/samsung,sec-core.txt new file mode 100644 index 000000000000..cdd079bfc287 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/samsung,sec-core.txt @@ -0,0 +1,88 @@ +Binding for Samsung S2M and S5M family multi-function device +============================================================ + +This is a part of device tree bindings for S2M and S5M family multi-function +devices. + +The Samsung S2MPA01, S2MPS11/13/14/15, S2MPU02 and S5M8767 is a family +of multi-function devices which include voltage and current regulators, RTC, +charger controller, clock outputs and other sub-blocks. It is interfaced +to the host controller using an I2C interface. Each sub-block is usually +addressed by the host system using different I2C slave addresses. + + +This document describes bindings for main device node. Optional sub-blocks +must be a sub-nodes to it. Bindings for them can be found in: + - bindings/regulator/samsung,s2mpa01.txt + - bindings/regulator/samsung,s2mps11.txt + - bindings/regulator/samsung,s5m8767.txt + - bindings/clock/samsung,s2mps11.txt + + +Required properties: + - compatible: Should be one of the following + - "samsung,s2mpa01-pmic", + - "samsung,s2mps11-pmic", + - "samsung,s2mps13-pmic", + - "samsung,s2mps14-pmic", + - "samsung,s2mps15-pmic", + - "samsung,s2mpu02-pmic", + - "samsung,s5m8767-pmic". + - reg: Specifies the I2C slave address of the pmic block. It should be 0x66. + +Optional properties: + - interrupt-parent: Specifies the phandle of the interrupt controller to which + the interrupts from s2mps11 are delivered to. + - interrupts: Interrupt specifiers for interrupt sources. + - samsung,s2mps11-wrstbi-ground: Indicates that WRSTBI pin of PMIC is pulled + down. When the system is suspended it will always go down thus triggerring + unwanted buck warm reset (setting buck voltages to default values). + - samsung,s2mps11-acokb-ground: Indicates that ACOKB pin of S2MPS11 PMIC is + connected to the ground so the PMIC must manually set PWRHOLD bit in CTRL1 + register to turn off the power. Usually the ACOKB is pulled up to VBATT so + when PWRHOLD pin goes low, the rising ACOKB will trigger power off. + +Example: + + s2mps11_pmic@66 { + compatible = "samsung,s2mps11-pmic"; + reg = <0x66>; + + s2m_osc: clocks { + compatible = "samsung,s2mps11-clk"; + #clock-cells = <1>; + clock-output-names = "xx", "yy", "zz"; + }; + + regulators { + ldo1_reg: LDO1 { + regulator-name = "VDD_ABB_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + ldo2_reg: LDO2 { + regulator-name = "VDD_ALIVE_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + }; + + buck1_reg: BUCK1 { + regulator-name = "vdd_mif"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + }; + + buck2_reg: BUCK2 { + regulator-name = "vdd_arm"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + regulator-ramp-delay = <50000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/sky81452.txt b/Documentation/devicetree/bindings/mfd/sky81452.txt index 35181794aa24..511764acd4d5 100644 --- a/Documentation/devicetree/bindings/mfd/sky81452.txt +++ b/Documentation/devicetree/bindings/mfd/sky81452.txt @@ -6,7 +6,7 @@ Required properties: Required child nodes: - backlight : container node for backlight following the binding - in video/backlight/sky81452-backlight.txt + in leds/backlight/sky81452-backlight.txt - regulator : container node for regulators following the binding in regulator/sky81452-regulator.txt diff --git a/Documentation/devicetree/bindings/mfd/syscon.txt b/Documentation/devicetree/bindings/mfd/syscon.txt index fe8150bb3248..408f768686f1 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.txt +++ b/Documentation/devicetree/bindings/mfd/syscon.txt @@ -13,6 +13,10 @@ Required properties: - compatible: Should contain "syscon". - reg: the register region can be accessed from syscon +Optional property: +- reg-io-width: the size (in bytes) of the IO accesses that should be + performed on the device. + Examples: gpr: iomuxc-gpr@020e0000 { compatible = "fsl,imx6q-iomuxc-gpr", "syscon"; diff --git a/Documentation/devicetree/bindings/mfd/tc3589x.txt b/Documentation/devicetree/bindings/mfd/tc3589x.txt index 37bf7f1aa70a..23fc2f21f5a4 100644 --- a/Documentation/devicetree/bindings/mfd/tc3589x.txt +++ b/Documentation/devicetree/bindings/mfd/tc3589x.txt @@ -56,6 +56,7 @@ Optional nodes: bindings/input/matrix-keymap.txt - linux,no-autorepeat: do no enable autorepeat feature. - wakeup-source: use any event on keypad as wakeup event. + (Legacy property supported: "linux,wakeup") Example: diff --git a/Documentation/devicetree/bindings/mfd/tps65086.txt b/Documentation/devicetree/bindings/mfd/tps65086.txt new file mode 100644 index 000000000000..d3705612a846 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/tps65086.txt @@ -0,0 +1,55 @@ +* TPS65086 Power Management Integrated Circuit (PMIC) bindings + +Required properties: + - compatible : Should be "ti,tps65086". + - reg : I2C slave address. + - interrupt-parent : Phandle to the parent interrupt controller. + - interrupts : The interrupt line the device is connected to. + - interrupt-controller : Marks the device node as an interrupt controller. + - #interrupt-cells : The number of cells to describe an IRQ, should be 2. + The first cell is the IRQ number. + The second cell is the flags, encoded as trigger + masks from ../interrupt-controller/interrupts.txt. + - 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 cell is used to specify flags. + See ../gpio/gpio.txt for more information. + - regulators: : List of child nodes that specify the regulator + initialization data. Child nodes must be named + after their hardware counterparts: buck[1-6], + ldoa[1-3], swa1, swb[1-2], and vtt. Each child + node is defined using the standard binding for + regulators and the optional regulator properties + defined below. + +Optional regulator properties: + - ti,regulator-step-size-25mv : This is applicable for buck[1,2,6], set this + if the regulator is factory set with a 25mv + step voltage mapping. + - ti,regulator-decay : This is applicable for buck[1-6], set this if + the output needs to decay, default is for + the output to slew down. + +Example: + + pmic: tps65086@5e { + compatible = "ti,tps65086"; + reg = <0x5e>; + interrupt-parent = <&gpio1>; + interrupts = <28 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + + regulators { + buck1 { + regulator-name = "vcc1"; + regulator-min-microvolt = <1600000>; + regulator-max-microvolt = <1600000>; + regulator-boot-on; + ti,regulator-decay; + ti,regulator-step-size-25mv; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/tps65912.txt b/Documentation/devicetree/bindings/mfd/tps65912.txt new file mode 100644 index 000000000000..717e66d23142 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/tps65912.txt @@ -0,0 +1,50 @@ +* TPS65912 Power Management Integrated Circuit bindings + +Required properties: + - compatible : Should be "ti,tps65912". + - reg : Slave address or chip select number (I2C / SPI). + - interrupt-parent : The parent interrupt controller. + - interrupts : The interrupt line the device is connected to. + - interrupt-controller : Marks the device node as an interrupt controller. + - #interrupt-cells : The number of cells to describe an IRQ, should be 2. + The first cell is the IRQ number. + The second cell is the flags, encoded as trigger + masks from ../interrupt-controller/interrupts.txt. + - 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 cell is used to specify flags. + See ../gpio/gpio.txt for more information. + - regulators: : List of child nodes that specify the regulator + initialization data. Child nodes must be named + after their hardware counterparts: dcdc[1-4] and + ldo[1-10]. Each child nodes is defined using the + standard binding for regulators. + +Example: + + pmic: tps65912@2d { + compatible = "ti,tps65912"; + reg = <0x2d>; + interrupt-parent = <&gpio1>; + interrupts = <28 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + + regulators { + dcdc1 { + regulator-name = "vdd_core"; + regulator-min-microvolt = <912000>; + regulator-max-microvolt = <1144000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <1900000>; + regulator-max-microvolt = <1900000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mips/cavium/sata-uctl.txt b/Documentation/devicetree/bindings/mips/cavium/sata-uctl.txt new file mode 100644 index 000000000000..3bd3c2f0b9b1 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/cavium/sata-uctl.txt @@ -0,0 +1,42 @@ +* UCTL SATA controller glue + +UCTL is the bridge unit between the I/O interconnect (an internal bus) +and the SATA AHCI host controller (UAHC). It performs the following functions: + - provides interfaces for the applications to access the UAHC AHCI + registers on the CN71XX I/O space. + - provides a bridge for UAHC to fetch AHCI command table entries and data + buffers from Level 2 Cache. + - posts interrupts to the CIU. + - contains registers that: + - control the behavior of the UAHC + - control the clock/reset generation to UAHC + - control endian swapping for all UAHC registers and DMA accesses + +Properties: + +- compatible: "cavium,octeon-7130-sata-uctl" + + Compatibility with the cn7130 SOC. + +- reg: The base address of the UCTL register bank. + +- #address-cells, #size-cells, ranges and dma-ranges must be present and hold + suitable values to map all child nodes. + +Example: + + uctl@118006c000000 { + compatible = "cavium,octeon-7130-sata-uctl"; + reg = <0x11800 0x6c000000 0x0 0x100>; + ranges; /* Direct mapping */ + dma-ranges; + #address-cells = <2>; + #size-cells = <2>; + + sata: sata@16c0000000000 { + compatible = "cavium,octeon-7130-ahci"; + reg = <0x16c00 0x00000000 0x0 0x200>; + interrupt-parent = <&cibsata>; + interrupts = <2 4>; /* Bit: 2, level */ + }; + }; diff --git a/Documentation/devicetree/bindings/mips/img/xilfpga.txt b/Documentation/devicetree/bindings/mips/img/xilfpga.txt new file mode 100644 index 000000000000..57e7ee942166 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/img/xilfpga.txt @@ -0,0 +1,83 @@ +Imagination University Program MIPSfpga +======================================= + +Under the Imagination University Program, a microAptiv UP core has been +released for academic usage. + +As we are dealing with a MIPS core instantiated on an FPGA, specifications +are fluid and can be varied in RTL. + +This binding document is provided as baseline guidance for the example +project provided by IMG. + +The example project runs on the Nexys4DDR board by Digilent powered by +the ARTIX-7 FPGA by Xilinx. + +Relevant details about the example project and the Nexys4DDR board: + +- microAptiv UP core m14Kc +- 50MHz clock speed +- 128Mbyte DDR RAM at 0x0000_0000 +- 8Kbyte RAM at 0x1000_0000 +- axi_intc at 0x1020_0000 +- axi_uart16550 at 0x1040_0000 +- axi_gpio at 0x1060_0000 +- axi_i2c at 0x10A0_0000 +- custom_gpio at 0x10C0_0000 +- axi_ethernetlite at 0x10E0_0000 +- 8Kbyte BootRAM at 0x1FC0_0000 + +Required properties: +-------------------- + - compatible: Must include "digilent,nexys4ddr","img,xilfpga". + +CPU nodes: +---------- +A "cpus" node is required. Required properties: + - #address-cells: Must be 1. + - #size-cells: Must be 0. +A CPU sub-node is also required for at least CPU 0. Required properties: + - device_type: Must be "cpu". + - compatible: Must be "mips,m14Kc". + - reg: Must be <0>. + - clocks: phandle to ext clock for fixed-clock received by MIPS core. + +Example: + + compatible = "img,xilfpga","digilent,nexys4ddr"; + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu0: cpu@0 { + device_type = "cpu"; + compatible = "mips,m14Kc"; + reg = <0>; + clocks = <&ext>; + }; + }; + + ext: ext { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <50000000>; + }; + +Boot protocol: +-------------- + +The BootRAM is a writeable "RAM" in FPGA at 0x1FC0_0000. +This is for easy reprogrammibility via JTAG. + +The BootRAM initializes the cache and the axi_uart peripheral. + +DDR initialization is already handled by a HW IP block. + +When the example project bitstream is loaded, the cpu_reset button +needs to be pressed. + +The bootram initializes the cache and axi_uart. +Then outputs MIPSFPGA\n\r on the serial port on the Nexys4DDR board. + +At this point, the board is ready to load the Linux kernel +vmlinux file via JTAG. diff --git a/Documentation/devicetree/bindings/mips/pic32/microchip,pic32mzda.txt b/Documentation/devicetree/bindings/mips/pic32/microchip,pic32mzda.txt new file mode 100644 index 000000000000..1c8dbc45feec --- /dev/null +++ b/Documentation/devicetree/bindings/mips/pic32/microchip,pic32mzda.txt @@ -0,0 +1,31 @@ +* Microchip PIC32MZDA Platforms + +PIC32MZDA Starter Kit +Required root node properties: + - compatible = "microchip,pic32mzda-sk", "microchip,pic32mzda" + +CPU nodes: +---------- +A "cpus" node is required. Required properties: + - #address-cells: Must be 1. + - #size-cells: Must be 0. +A CPU sub-node is also required. Required properties: + - device_type: Must be "cpu". + - compatible: Must be "mti,mips14KEc". +Example: + cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu0: cpu@0 { + device_type = "cpu"; + compatible = "mti,mips14KEc"; + }; + }; + +Boot protocol +-------------- +In accordance with Unified Hosting Interface Reference Manual (MD01069), the +bootloader must pass the following arguments to the kernel: + - $a0: -2. + - $a1: KSEG0 address of the flattened device-tree blob. diff --git a/Documentation/devicetree/bindings/misc/eeprom-93xx46.txt b/Documentation/devicetree/bindings/misc/eeprom-93xx46.txt new file mode 100644 index 000000000000..a8ebb4621f79 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/eeprom-93xx46.txt @@ -0,0 +1,25 @@ +EEPROMs (SPI) compatible with Microchip Technology 93xx46 family. + +Required properties: +- compatible : shall be one of: + "atmel,at93c46d" + "eeprom-93xx46" +- data-size : number of data bits per word (either 8 or 16) + +Optional properties: +- read-only : parameter-less property which disables writes to the EEPROM +- select-gpios : if present, specifies the GPIO that will be asserted prior to + each access to the EEPROM (e.g. for SPI bus multiplexing) + +Property rules described in Documentation/devicetree/bindings/spi/spi-bus.txt +apply. In particular, "reg" and "spi-max-frequency" properties must be given. + +Example: + eeprom@0 { + compatible = "eeprom-93xx46"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cs-high; + data-size = <8>; + select-gpios = <&gpio4 4 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt index b7943f3f9995..dedfb02c744a 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt +++ b/Documentation/devicetree/bindings/mmc/fsl-esdhc.txt @@ -22,6 +22,8 @@ Optional properties: - voltage-ranges : two cells are required, first cell specifies minimum slot voltage (mV), second cell specifies maximum slot voltage (mV). Several ranges could be specified. + - little-endian : If the host controller is little-endian mode, specify + this property. The default endian mode is big-endian. Example: diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index 0384fc3f64e8..ed23b9bedfdc 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -37,6 +37,7 @@ Optional properties: - sd-uhs-sdr104: SD UHS SDR104 speed is supported - sd-uhs-ddr50: SD UHS DDR50 speed is supported - cap-power-off-card: powering off the card is safe +- cap-mmc-hw-reset: eMMC hardware reset is supported - cap-sdio-irq: enable SDIO IRQ signalling on this interface - full-pwr-cycle: full power cycle of the card is supported - mmc-ddr-1_8v: eMMC high-speed DDR mode(1.8V I/O) is supported @@ -67,7 +68,8 @@ polarity is in effect. Optional SDIO properties: - keep-power-in-suspend: Preserves card power during a suspend/resume cycle -- enable-sdio-wakeup: Enables wake up of host system on SDIO IRQ assertion +- wakeup-source: Enables wake up of host system on SDIO IRQ assertion + (Legacy property supported: "enable-sdio-wakeup") MMC power sequences: @@ -117,7 +119,7 @@ sdhci@ab000000 { wp-gpios = <&gpio 70 0>; max-frequency = <50000000>; keep-power-in-suspend; - enable-sdio-wakeup; + wakeup-source; mmc-pwrseq = <&sdhci0_pwrseq> } diff --git a/Documentation/devicetree/bindings/mmc/mtk-sd.txt b/Documentation/devicetree/bindings/mmc/mtk-sd.txt index a1adfa495ad3..0120c7f1109c 100644 --- a/Documentation/devicetree/bindings/mmc/mtk-sd.txt +++ b/Documentation/devicetree/bindings/mmc/mtk-sd.txt @@ -17,6 +17,11 @@ Required properties: - vmmc-supply: power to the Core - vqmmc-supply: power to the IO +Optional properties: +- assigned-clocks: PLL of the source clock +- assigned-clock-parents: parent of source clock, used for HS400 mode to get 400Mhz source clock +- hs400-ds-delay: HS400 DS delay setting + Examples: mmc0: mmc@11230000 { compatible = "mediatek,mt8173-mmc", "mediatek,mt8135-mmc"; @@ -24,9 +29,13 @@ mmc0: mmc@11230000 { interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_LOW>; vmmc-supply = <&mt6397_vemc_3v3_reg>; vqmmc-supply = <&mt6397_vio18_reg>; - clocks = <&pericfg CLK_PERI_MSDC30_0>, <&topckgen CLK_TOP_MSDC50_0_H_SEL>; + clocks = <&pericfg CLK_PERI_MSDC30_0>, + <&topckgen CLK_TOP_MSDC50_0_H_SEL>; clock-names = "source", "hclk"; pinctrl-names = "default", "state_uhs"; pinctrl-0 = <&mmc0_pins_default>; pinctrl-1 = <&mmc0_pins_uhs>; + assigned-clocks = <&topckgen CLK_TOP_MSDC50_0_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_MSDCPLL_D2>; + hs400-ds-delay = <0x14015>; }; diff --git a/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt b/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt index d38942f6c5ae..ff611fa66871 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt +++ b/Documentation/devicetree/bindings/mmc/renesas,mmcif.txt @@ -6,11 +6,13 @@ and the properties used by the MMCIF device. Required properties: -- compatible: must contain one of the following +- compatible: should be "renesas,mmcif-<soctype>", "renesas,sh-mmcif" as a + fallback. Examples with <soctype> are: - "renesas,mmcif-r8a7740" for the MMCIF found in r8a7740 SoCs - "renesas,mmcif-r8a7790" for the MMCIF found in r8a7790 SoCs - "renesas,mmcif-r8a7791" for the MMCIF found in r8a7791 SoCs - - "renesas,sh-mmcif" for the generic MMCIF + - "renesas,mmcif-r8a7793" for the MMCIF found in r8a7793 SoCs + - "renesas,mmcif-r8a7794" for the MMCIF found in r8a7794 SoCs - clocks: reference to the functional clock diff --git a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt index c327c2d6f23d..3dc13b68fc3f 100644 --- a/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.txt @@ -14,6 +14,19 @@ Required Properties: before RK3288 - "rockchip,rk3288-dw-mshc": for Rockchip RK3288 +Optional Properties: +* clocks: from common clock binding: if ciu_drive and ciu_sample are + specified in clock-names, should contain handles to these clocks. + +* clock-names: Apart from the clock-names described in synopsys-dw-mshc.txt + two more clocks "ciu-drive" and "ciu-sample" are supported. They are used + to control the clock phases, "ciu-sample" is required for tuning high- + speed modes. + +* rockchip,default-sample-phase: The default phase to set ciu_sample at + probing, low speeds or in case where all phases work at tuning time. + If not specified 0 deg will be used. + Example: rkdwmmc0@12200000 { diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt index 346c6095a615..8636f5ae97e5 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt @@ -75,6 +75,12 @@ Optional properties: * vmmc-supply: The phandle to the regulator to use for vmmc. If this is specified we'll defer probe until we can find this regulator. +* dmas: List of DMA specifiers with the controller specific format as described + in the generic DMA client binding. Refer to dma.txt for details. + +* dma-names: request names for generic DMA client binding. Must be "rx-tx". + Refer to dma.txt for details. + Aliases: - All the MSHC controller nodes should be represented in the aliases node using @@ -95,6 +101,23 @@ board specific portions as listed below. #size-cells = <0>; }; +[board specific internal DMA resources] + + dwmmc0@12200000 { + clock-frequency = <400000000>; + clock-freq-min-max = <400000 200000000>; + num-slots = <1>; + broken-cd; + fifo-depth = <0x80>; + card-detect-delay = <200>; + vmmc-supply = <&buck8>; + bus-width = <8>; + cap-mmc-highspeed; + cap-sd-highspeed; + }; + +[board specific generic DMA request binding] + dwmmc0@12200000 { clock-frequency = <400000000>; clock-freq-min-max = <400000 200000000>; @@ -106,4 +129,6 @@ board specific portions as listed below. bus-width = <8>; cap-mmc-highspeed; cap-sd-highspeed; + dmas = <&pdma 12>; + dma-names = "rx-tx"; }; diff --git a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt index 4ff7128ee3b2..c2546ced9c02 100644 --- a/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt +++ b/Documentation/devicetree/bindings/mtd/brcm,brcmnand.txt @@ -45,6 +45,8 @@ Required properties: - #size-cells : <0> Optional properties: +- clock : reference to the clock for the NAND controller +- clock-names : "nand" (required for the above clock) - brcm,nand-has-wp : Some versions of this IP include a write-protect (WP) control bit. It is always available on >= v7.0. Use this property to describe the rare @@ -72,6 +74,12 @@ we define additional 'compatible' properties and associated register resources w and enable registers - reg-names: (required) "nand-int-base" + * "brcm,nand-bcm6368" + - compatible: should contain "brcm,nand-bcm<soc>", "brcm,nand-bcm6368" + - reg: (required) the 'NAND_INTR_BASE' register range, with combined status + and enable registers, and boot address registers + - reg-names: (required) "nand-int-base" + * "brcm,nand-iproc" - reg: (required) the "IDM" register range, for interrupt enable and APB bus access endianness configuration, and the "EXT" register range, @@ -148,3 +156,27 @@ nand@f0442800 { }; }; }; + +nand@10000200 { + compatible = "brcm,nand-bcm63168", "brcm,nand-bcm6368", + "brcm,brcmnand-v4.0", "brcm,brcmnand"; + reg = <0x10000200 0x180>, + <0x10000600 0x200>, + <0x100000b0 0x10>; + reg-names = "nand", "nand-cache", "nand-int-base"; + interrupt-parent = <&periph_intc>; + interrupts = <50>; + clocks = <&periph_clk 20>; + clock-names = "nand"; + + #address-cells = <1>; + #size-cells = <0>; + + nand0: nandcs@0 { + compatible = "brcm,nandcs"; + reg = <0>; + nand-on-flash-bbt; + nand-ecc-strength = <1>; + nand-ecc-step-size = <512>; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt index 862aa2f8837a..00c587b3d3ae 100644 --- a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt +++ b/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt @@ -2,7 +2,8 @@ Required properties: - compatible : Should be "fsl,vf610-qspi", "fsl,imx6sx-qspi", - "fsl,imx7d-qspi", "fsl,imx6ul-qspi" + "fsl,imx7d-qspi", "fsl,imx6ul-qspi", + "fsl,ls1021-qspi" - reg : the first contains the register location and length, the second contains the memory mapping address and length - reg-names: Should contain the reg names "QuadSPI" and "QuadSPI-memory" diff --git a/Documentation/devicetree/bindings/mtd/fsmc-nand.txt b/Documentation/devicetree/bindings/mtd/fsmc-nand.txt index 5235cbc551b0..32636eb77304 100644 --- a/Documentation/devicetree/bindings/mtd/fsmc-nand.txt +++ b/Documentation/devicetree/bindings/mtd/fsmc-nand.txt @@ -30,6 +30,12 @@ Optional properties: command is asserted. Zero means one cycle, 255 means 256 cycles. - bank: default NAND bank to use (0-3 are valid, 0 is the default). +- nand-ecc-mode : see nand.txt +- nand-ecc-strength : see nand.txt +- nand-ecc-step-size : see nand.txt + +Can support 1-bit HW ECC (default) or if stronger correction is required, +software-based BCH. Example: diff --git a/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt b/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt new file mode 100644 index 000000000000..29ea5853ca91 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/ingenic,jz4780-nand.txt @@ -0,0 +1,86 @@ +* Ingenic JZ4780 NAND/BCH + +This file documents the device tree bindings for NAND flash devices on the +JZ4780. NAND devices are connected to the NEMC controller (described in +memory-controllers/ingenic,jz4780-nemc.txt), and thus NAND device nodes must +be children of the NEMC node. + +Required NAND controller device properties: +- compatible: Should be set to "ingenic,jz4780-nand". +- reg: For each bank with a NAND chip attached, should specify a bank number, + an offset of 0 and a size of 0x1000000 (i.e. the whole NEMC bank). + +Optional NAND controller device properties: +- ingenic,bch-controller: To make use of the hardware BCH controller, this + property must contain a phandle for the BCH controller node. The required + properties for this node are described below. If this is not specified, + software BCH will be used instead. + +Optional children nodes: +- Individual NAND chips are children of the NAND controller node. + +Required children node properties: +- reg: An integer ranging from 1 to 6 representing the CS line to use. + +Optional children node properties: +- nand-ecc-step-size: ECC block size in bytes. +- nand-ecc-strength: ECC strength (max number of correctable bits). +- nand-ecc-mode: String, operation mode of the NAND ecc mode. "hw" by default +- nand-on-flash-bbt: boolean to enable on flash bbt option, if not present false +- rb-gpios: GPIO specifier for the busy pin. +- wp-gpios: GPIO specifier for the write protect pin. + +Optional child node of NAND chip nodes: +- partitions: see Documentation/devicetree/bindings/mtd/partition.txt + +Example: + +nemc: nemc@13410000 { + ... + + nandc: nand-controller@1 { + compatible = "ingenic,jz4780-nand"; + reg = <1 0 0x1000000>; /* Bank 1 */ + + #address-cells = <1>; + #size-cells = <0>; + + ingenic,bch-controller = <&bch>; + + nand@1 { + reg = <1>; + + nand-ecc-step-size = <1024>; + nand-ecc-strength = <24>; + nand-ecc-mode = "hw"; + nand-on-flash-bbt; + + rb-gpios = <&gpa 20 GPIO_ACTIVE_LOW>; + wp-gpios = <&gpf 22 GPIO_ACTIVE_LOW>; + + partitions { + #address-cells = <2>; + #size-cells = <2>; + ... + } + }; + }; +}; + +The BCH controller is a separate SoC component used for error correction on +NAND devices. The following is a description of the device properties for a +BCH controller. + +Required BCH properties: +- compatible: Should be set to "ingenic,jz4780-bch". +- reg: Should specify the BCH controller registers location and length. +- clocks: Clock for the BCH controller. + +Example: + +bch: bch@134d0000 { + compatible = "ingenic,jz4780-bch"; + reg = <0x134d0000 0x10000>; + + clocks = <&cgu JZ4780_CLK_BCH>; +}; diff --git a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.txt b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.txt index 2bee68103b01..2c91c03e7eb0 100644 --- a/Documentation/devicetree/bindings/mtd/jedec,spi-nor.txt +++ b/Documentation/devicetree/bindings/mtd/jedec,spi-nor.txt @@ -1,15 +1,61 @@ -* MTD SPI driver for ST M25Pxx (and similar) serial flash chips +* SPI NOR flash: ST M25Pxx (and similar) serial flash chips Required properties: - #address-cells, #size-cells : Must be present if the device has sub-nodes representing partitions. - compatible : May include a device-specific string consisting of the - manufacturer and name of the chip. Bear in mind the DT binding - is not Linux-only, but in case of Linux, see the "m25p_ids" - table in drivers/mtd/devices/m25p80.c for the list of supported - chips. + manufacturer and name of the chip. A list of supported chip + names follows. Must also include "jedec,spi-nor" for any SPI NOR flash that can be identified by the JEDEC READ ID opcode (0x9F). + + Supported chip names: + at25df321a + at25df641 + at26df081a + mr25h256 + mx25l4005a + mx25l1606e + mx25l6405d + mx25l12805d + mx25l25635e + n25q064 + n25q128a11 + n25q128a13 + n25q512a + s25fl256s1 + s25fl512s + s25sl12801 + s25fl008k + s25fl064k + sst25vf040b + m25p40 + m25p80 + m25p16 + m25p32 + m25p64 + m25p128 + w25x80 + w25x32 + w25q32 + w25q32dw + w25q80bl + w25q128 + w25q256 + + The following chip names have been used historically to + designate quirky versions of flash chips that do not support the + JEDEC READ ID opcode (0x9F): + m25p05-nonjedec + m25p10-nonjedec + m25p20-nonjedec + m25p40-nonjedec + m25p80-nonjedec + m25p16-nonjedec + m25p32-nonjedec + m25p64-nonjedec + m25p128-nonjedec + - reg : Chip-Select number - spi-max-frequency : Maximum frequency of the SPI bus the chip can operate at diff --git a/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt b/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt new file mode 100644 index 000000000000..fb314f09861b --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt @@ -0,0 +1,41 @@ +* Serial NOR flash controller for MTK MT81xx (and similar) + +Required properties: +- compatible: should be "mediatek,mt8173-nor"; +- reg: physical base address and length of the controller's register +- clocks: the phandle of the clocks needed by the nor controller +- clock-names: the names of the clocks + the clocks should be named "spi" and "sf". "spi" is used for spi bus, + and "sf" is used for controller, these are the clocks witch + hardware needs to enabling nor flash and nor flash controller. + See Documentation/devicetree/bindings/clock/clock-bindings.txt for details. +- #address-cells: should be <1> +- #size-cells: should be <0> + +The SPI flash must be a child of the nor_flash node and must have a +compatible property. Also see jedec,spi-nor.txt. + +Required properties: +- compatible: May include a device-specific string consisting of the manufacturer + and name of the chip. Must also include "jedec,spi-nor" for any + SPI NOR flash that can be identified by the JEDEC READ ID opcode (0x9F). +- reg : Chip-Select number + +Example: + +nor_flash: spi@1100d000 { + compatible = "mediatek,mt8173-nor"; + reg = <0 0x1100d000 0 0xe0>; + clocks = <&pericfg CLK_PERI_SPI>, + <&topckgen CLK_TOP_SPINFI_IFR_SEL>; + clock-names = "spi", "sf"; + #address-cells = <1>; + #size-cells = <0>; + status = "disabled"; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + }; +}; + diff --git a/Documentation/devicetree/bindings/mtd/partition.txt b/Documentation/devicetree/bindings/mtd/partition.txt index 8e5557da1955..81a224da63be 100644 --- a/Documentation/devicetree/bindings/mtd/partition.txt +++ b/Documentation/devicetree/bindings/mtd/partition.txt @@ -4,10 +4,19 @@ Partitions can be represented by sub-nodes of an mtd device. This can be used on platforms which have strong conventions about which portions of a flash are used for what purposes, but which don't use an on-flash partition table such as RedBoot. -NOTE: if the sub-node has a compatible string, then it is not a partition. -#address-cells & #size-cells must both be present in the mtd device. There are -two valid values for both: +The partition table should be a subnode of the mtd node and should be named +'partitions'. This node should have the following property: +- compatible : (required) must be "fixed-partitions" +Partitions are then defined in subnodes of the partitions node. + +For backwards compatibility partitions as direct subnodes of the mtd device are +supported. This use is discouraged. +NOTE: also for backwards compatibility, direct subnodes that have a compatible +string are not considered partitions, as they may be used for other bindings. + +#address-cells & #size-cells must both be present in the partitions subnode of the +mtd device. There are two valid values for both: <1>: for partitions that require a single 32-bit cell to represent their size/address (aka the value is below 4 GiB) <2>: for partitions that require two 32-bit cells to represent their @@ -23,49 +32,60 @@ Optional properties: partition should only be mounted read-only. This is usually used for flash partitions containing early-boot firmware images or data which should not be clobbered. +- lock : Do not unlock the partition at initialization time (not supported on + all devices) Examples: flash@0 { - #address-cells = <1>; - #size-cells = <1>; + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <1>; - partition@0 { - label = "u-boot"; - reg = <0x0000000 0x100000>; - read-only; - }; + partition@0 { + label = "u-boot"; + reg = <0x0000000 0x100000>; + read-only; + }; - uimage@100000 { - reg = <0x0100000 0x200000>; + uimage@100000 { + reg = <0x0100000 0x200000>; + }; }; }; flash@1 { - #address-cells = <1>; - #size-cells = <2>; + partitions { + compatible = "fixed-partitions"; + #address-cells = <1>; + #size-cells = <2>; - /* a 4 GiB partition */ - partition@0 { - label = "filesystem"; - reg = <0x00000000 0x1 0x00000000>; + /* a 4 GiB partition */ + partition@0 { + label = "filesystem"; + reg = <0x00000000 0x1 0x00000000>; + }; }; }; flash@2 { - #address-cells = <2>; - #size-cells = <2>; + partitions { + compatible = "fixed-partitions"; + #address-cells = <2>; + #size-cells = <2>; - /* an 8 GiB partition */ - partition@0 { - label = "filesystem #1"; - reg = <0x0 0x00000000 0x2 0x00000000>; - }; + /* an 8 GiB partition */ + partition@0 { + label = "filesystem #1"; + reg = <0x0 0x00000000 0x2 0x00000000>; + }; - /* a 4 GiB partition */ - partition@200000000 { - label = "filesystem #2"; - reg = <0x2 0x00000000 0x1 0x00000000>; + /* a 4 GiB partition */ + partition@200000000 { + label = "filesystem #2"; + reg = <0x2 0x00000000 0x1 0x00000000>; + }; }; }; diff --git a/Documentation/devicetree/bindings/mtd/vf610-nfc.txt b/Documentation/devicetree/bindings/mtd/vf610-nfc.txt new file mode 100644 index 000000000000..c96eeb65f450 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/vf610-nfc.txt @@ -0,0 +1,59 @@ +Freescale's NAND flash controller (NFC) + +This variant of the Freescale NAND flash controller (NFC) can be found on +Vybrid (vf610), MPC5125, MCF54418 and Kinetis K70. + +Required properties: +- compatible: Should be set to "fsl,vf610-nfc". +- reg: address range of the NFC. +- interrupts: interrupt of the NFC. +- #address-cells: shall be set to 1. Encode the nand CS. +- #size-cells : shall be set to 0. +- assigned-clocks: main clock from the SoC, for Vybrid <&clks VF610_CLK_NFC>; +- assigned-clock-rates: The NAND bus timing is derived from this clock + rate and should not exceed maximum timing for any NAND memory chip + in a board stuffing. Typical NAND memory timings derived from this + clock are found in the SoC hardware reference manual. Furthermore, + there might be restrictions on maximum rates when using hardware ECC. + +- #address-cells, #size-cells : Must be present if the device has sub-nodes + representing partitions. + +Required children nodes: +Children nodes represent the available nand chips. Currently the driver can +only handle one NAND chip. + +Required properties: +- compatible: Should be set to "fsl,vf610-nfc-cs". +- nand-bus-width: see nand.txt +- nand-ecc-mode: see nand.txt + +Required properties for hardware ECC: +- nand-ecc-strength: supported strengths are 24 and 32 bit (see nand.txt) +- nand-ecc-step-size: step size equals page size, currently only 2k pages are + supported +- nand-on-flash-bbt: see nand.txt + +Example: + + nfc: nand@400e0000 { + compatible = "fsl,vf610-nfc"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x400e0000 0x4000>; + interrupts = <GIC_SPI 83 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks VF610_CLK_NFC>; + clock-names = "nfc"; + assigned-clocks = <&clks VF610_CLK_NFC>; + assigned-clock-rates = <33000000>; + + nand@0 { + compatible = "fsl,vf610-nfc-nandcs"; + reg = <0>; + nand-bus-width = <8>; + nand-ecc-mode = "hw"; + nand-ecc-strength = <32>; + nand-ecc-step-size = <2048>; + nand-on-flash-bbt; + }; + }; diff --git a/Documentation/devicetree/bindings/net/apm-xgene-enet.txt b/Documentation/devicetree/bindings/net/apm-xgene-enet.txt index f55aa280d34f..078060a97f95 100644 --- a/Documentation/devicetree/bindings/net/apm-xgene-enet.txt +++ b/Documentation/devicetree/bindings/net/apm-xgene-enet.txt @@ -37,6 +37,14 @@ Required properties for ethernet interfaces that have external PHY: Optional properties: - status: Should be "ok" or "disabled" for enabled/disabled. Default is "ok". +- tx-delay: Delay value for RGMII bridge TX clock. + Valid values are between 0 to 7, that maps to + 417, 717, 1020, 1321, 1611, 1913, 2215, 2514 ps + Default value is 4, which corresponds to 1611 ps +- rx-delay: Delay value for RGMII bridge RX clock. + Valid values are between 0 to 7, that maps to + 273, 589, 899, 1222, 1480, 1806, 2147, 2464 ps + Default value is 2, which corresponds to 899 ps Example: menetclk: menetclk { @@ -72,5 +80,7 @@ Example: /* Board-specific peripheral configurations */ &menet { + tx-delay = <4>; + rx-delay = <2>; status = "ok"; }; diff --git a/Documentation/devicetree/bindings/net/arc_emac.txt b/Documentation/devicetree/bindings/net/arc_emac.txt index a1d71eb43b20..c73a0e9c625e 100644 --- a/Documentation/devicetree/bindings/net/arc_emac.txt +++ b/Documentation/devicetree/bindings/net/arc_emac.txt @@ -7,6 +7,13 @@ Required properties: - max-speed: see ethernet.txt file in the same directory. - phy: see ethernet.txt file in the same directory. +Optional properties: +- phy-reset-gpios : Should specify the gpio for phy reset +- phy-reset-duration : Reset duration in milliseconds. Should present + only if property "phy-reset-gpios" is available. Missing the property + will have the duration be 1 millisecond. Numbers greater than 1000 are + invalid and 1 millisecond will be used instead. + Clock handling: The clock frequency is needed to calculate and set polling period of EMAC. It must be provided by one of: diff --git a/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt b/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt index 451fef26b4df..10587bdadbbe 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcmgenet.txt @@ -68,7 +68,7 @@ ethernet@f0b60000 { phy1: ethernet-phy@1 { max-speed = <1000>; reg = <0x1>; - compatible = "brcm,28nm-gphy", "ethernet-phy-ieee802.3-c22"; + compatible = "ethernet-phy-ieee802.3-c22"; }; }; }; @@ -115,7 +115,7 @@ ethernet@f0ba0000 { phy0: ethernet-phy@0 { max-speed = <1000>; reg = <0x0>; - compatible = "brcm,bcm53125", "ethernet-phy-ieee802.3-c22"; + compatible = "ethernet-phy-ieee802.3-c22"; }; }; }; diff --git a/Documentation/devicetree/bindings/net/brcm,iproc-mdio.txt b/Documentation/devicetree/bindings/net/brcm,iproc-mdio.txt new file mode 100644 index 000000000000..8ba9ed11d716 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,iproc-mdio.txt @@ -0,0 +1,23 @@ +* Broadcom iProc MDIO bus controller + +Required properties: +- compatible: should be "brcm,iproc-mdio" +- reg: address and length of the register set for the MDIO interface +- #size-cells: must be 1 +- #address-cells: must be 0 + +Child nodes of this MDIO bus controller node are standard Ethernet PHY device +nodes as described in Documentation/devicetree/bindings/net/phy.txt + +Example: + +mdio@18002000 { + compatible = "brcm,iproc-mdio"; + reg = <0x18002000 0x8>; + #size-cells = <1>; + #address-cells = <0>; + + enet-gphy@0 { + reg = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/can/ifi_canfd.txt b/Documentation/devicetree/bindings/net/can/ifi_canfd.txt new file mode 100644 index 000000000000..20ea5c70ab82 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/ifi_canfd.txt @@ -0,0 +1,15 @@ +IFI CANFD controller +-------------------- + +Required properties: + - compatible: Should be "ifi,canfd-1.0" + - reg: Should contain CAN controller registers location and length + - interrupts: Should contain IRQ line for the CAN controller + +Example: + + canfd0: canfd@ff220000 { + compatible = "ifi,canfd-1.0"; + reg = <0xff220000 0x00001000>; + interrupts = <0 43 0>; + }; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 002d8440bf66..8d40ab27bc8c 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -6,6 +6,17 @@ Required properties: "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. + "renesas,can-r8a7792" if CAN controller is a part of R8A7792 SoC. + "renesas,can-r8a7793" if CAN controller is a part of R8A7793 SoC. + "renesas,can-r8a7794" if CAN controller is a part of R8A7794 SoC. + "renesas,can-r8a7795" if CAN controller is a part of R8A7795 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-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 + followed by the generic version. + - reg: physical base address and size of the R-Car CAN register map. - interrupts: interrupt specifier for the sole interrupt. - clocks: phandles and clock specifiers for 3 CAN clock inputs. @@ -13,6 +24,15 @@ Required properties: - pinctrl-0: pin control group to be used for this controller. - pinctrl-names: must be "default". +Required properties for "renesas,can-r8a7795" compatible: +In R8A7795 SoC, "clkp2" can be CANFD clock. This is a div6 clock and can be +used by both CAN and CAN FD controller at the same time. It needs to be scaled +to maximum frequency if any of these controllers use it. This is done using +the below properties. + +- assigned-clocks: phandle of clkp2(CANFD) clock. +- assigned-clock-rates: maximum frequency of this clock. + Optional properties: - renesas,can-clock-select: R-Car CAN Clock Source Select. Valid values are: <0x0> (default) : Peripheral clock (clkp1) @@ -25,7 +45,7 @@ Example SoC common .dtsi file: can0: can@e6e80000 { - compatible = "renesas,can-r8a7791"; + compatible = "renesas,can-r8a7791", "renesas,rcar-gen2-can"; reg = <0 0xe6e80000 0 0x1000>; interrupts = <0 186 IRQ_TYPE_LEVEL_HIGH>; clocks = <&mstp9_clks R8A7791_CLK_RCAN0>, diff --git a/Documentation/devicetree/bindings/net/can/sja1000.txt b/Documentation/devicetree/bindings/net/can/sja1000.txt index b4a6d53fb01a..ac3160eca96a 100644 --- a/Documentation/devicetree/bindings/net/can/sja1000.txt +++ b/Documentation/devicetree/bindings/net/can/sja1000.txt @@ -2,7 +2,7 @@ Memory mapped SJA1000 CAN controller from NXP (formerly Philips) Required properties: -- compatible : should be "nxp,sja1000". +- compatible : should be one of "nxp,sja1000", "technologic,sja1000". - reg : should specify the chip select, address offset and size required to map the registers of the SJA1000. The size is usually 0x80. @@ -14,6 +14,7 @@ Optional properties: - reg-io-width : Specify the size (in bytes) of the IO accesses that should be performed on the device. Valid value is 1, 2 or 4. + This property is ignored for technologic version. Default to 1 (8 bits). - nxp,external-clock-frequency : Frequency of the external oscillator diff --git a/Documentation/devicetree/bindings/net/can/sun4i_can.txt b/Documentation/devicetree/bindings/net/can/sun4i_can.txt new file mode 100644 index 000000000000..84ed1909df76 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/sun4i_can.txt @@ -0,0 +1,36 @@ +Allwinner A10/A20 CAN controller Device Tree Bindings +----------------------------------------------------- + +Required properties: +- compatible: "allwinner,sun4i-a10-can" +- reg: physical base address and size of the Allwinner A10/A20 CAN register map. +- interrupts: interrupt specifier for the sole interrupt. +- clock: phandle and clock specifier. + +Example +------- + +SoC common .dtsi file: + + can0_pins_a: can0@0 { + allwinner,pins = "PH20","PH21"; + allwinner,function = "can"; + allwinner,drive = <0>; + allwinner,pull = <0>; + }; +... + can0: can@01c2bc00 { + compatible = "allwinner,sun4i-a10-can"; + reg = <0x01c2bc00 0x400>; + interrupts = <0 26 4>; + clocks = <&apb1_gates 4>; + status = "disabled"; + }; + +Board specific .dts file: + + can0: can@01c2bc00 { + pinctrl-names = "default"; + pinctrl-0 = <&can0_pins_a>; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/net/cavium-mdio.txt b/Documentation/devicetree/bindings/net/cavium-mdio.txt index 04cb7491d232..020df08b8a30 100644 --- a/Documentation/devicetree/bindings/net/cavium-mdio.txt +++ b/Documentation/devicetree/bindings/net/cavium-mdio.txt @@ -1,9 +1,12 @@ * System Management Interface (SMI) / MDIO Properties: -- compatible: "cavium,octeon-3860-mdio" +- compatible: One of: - Compatibility with all cn3XXX, cn5XXX and cn6XXX SOCs. + "cavium,octeon-3860-mdio": Compatibility with all cn3XXX, cn5XXX + and cn6XXX SOCs. + + "cavium,thunder-8890-mdio": Compatibility with all cn8XXX SOCs. - reg: The base address of the MDIO bus controller register bank. @@ -25,3 +28,57 @@ Example: reg = <0>; }; }; + + +* System Management Interface (SMI) / MDIO Nexus + + Several mdio buses may be gathered as children of a single PCI + device, this PCI device is the nexus of the buses. + +Properties: + +- compatible: "cavium,thunder-8890-mdio-nexus"; + +- reg: The PCI device and function numbers of the nexus device. + +- #address-cells: Must be <2>. + +- #size-cells: Must be <2>. + +- ranges: As needed for mapping of the MDIO bus device registers. + +- assigned-addresses: As needed for mapping of the MDIO bus device registers. + +Example: + + mdio-nexus@1,3 { + compatible = "cavium,thunder-8890-mdio-nexus"; + #address-cells = <2>; + #size-cells = <2>; + reg = <0x0b00 0 0 0 0>; /* DEVFN = 0x0b (1:3) */ + assigned-addresses = <0x03000000 0x87e0 0x05000000 0x0 0x800000>; + ranges = <0x87e0 0x05000000 0x03000000 0x87e0 0x05000000 0x0 0x800000>; + + mdio0@87e0,05003800 { + compatible = "cavium,thunder-8890-mdio"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x87e0 0x05003800 0x0 0x30>; + + ethernet-phy@0 { + ... + reg = <0>; + }; + }; + mdio0@87e0,05003880 { + compatible = "cavium,thunder-8890-mdio"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x87e0 0x05003880 0x0 0x30>; + + ethernet-phy@0 { + ... + reg = <0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/cdns-emac.txt b/Documentation/devicetree/bindings/net/cdns-emac.txt deleted file mode 100644 index 4451ee973223..000000000000 --- a/Documentation/devicetree/bindings/net/cdns-emac.txt +++ /dev/null @@ -1,20 +0,0 @@ -* Cadence EMAC Ethernet controller - -Required properties: -- compatible: Should be "cdns,[<chip>-]{emac}" - Use "cdns,at91rm9200-emac" Atmel at91rm9200 SoC. - Use "cdns,zynq-gem" Xilinx Zynq-7xxx SoC. - Or the generic form: "cdns,emac". -- reg: Address and length of the register set for the device -- interrupts: Should contain macb interrupt -- phy-mode: see ethernet.txt file in the same directory. - -Examples: - - macb0: ethernet@fffc4000 { - compatible = "cdns,at91rm9200-emac"; - reg = <0xfffc4000 0x4000>; - interrupts = <21>; - phy-mode = "rmii"; - local-mac-address = [3a 0e 03 04 05 06]; - }; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index a2cae4eb4a60..28a4781ab6d7 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -30,17 +30,29 @@ Optional properties: - dual_emac : Specifies Switch to act as Dual EMAC - syscon : Phandle to the system control device node, which is the control module device of the am33x +- mode-gpios : Should be added if one/multiple gpio lines are + required to be driven so that cpsw data lines + can be connected to the phy via selective mux. + For example in dra72x-evm, pcf gpio has to be + driven low so that cpsw slave 0 and phy data + lines are connected via mux. + Slave Properties: Required properties: -- phy_id : Specifies slave phy id - phy-mode : See ethernet.txt file in the same directory Optional properties: - dual_emac_res_vlan : Specifies VID to be used to segregate the ports - mac-address : See ethernet.txt file in the same directory +- phy_id : Specifies slave phy id - phy-handle : See ethernet.txt file in the same directory +Slave sub-nodes: +- fixed-link : See fixed-link.txt file in the same directory + Either the property phy_id, or the sub-node + fixed-link can be specified + Note: "ti,hwmods" field is used to fetch the base address and irq resources from TI, omap hwmod data base during device registration. Future plan is to migrate hwmod data base contents into device tree diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index 04e6bef3ac3f..5fdbbcdf8c4b 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -31,6 +31,8 @@ A switch child node has the following optional property: switch. Must be set if the switch can not detect the presence and/or size of a connected EEPROM, otherwise optional. +- reset-gpios : phandle and specifier to a gpio line connected to + reset pin of the switch chip. A switch may have multiple "port" children nodes @@ -114,6 +116,7 @@ Example: #size-cells = <0>; reg = <17 1>; /* MDIO address 17, switch 1 in tree */ mii-bus = <&mii_bus1>; + reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; switch1port0: port@0 { reg = <0>; diff --git a/Documentation/devicetree/bindings/net/emac_rockchip.txt b/Documentation/devicetree/bindings/net/emac_rockchip.txt index 8dc1c79fef7f..05bd7dafce17 100644 --- a/Documentation/devicetree/bindings/net/emac_rockchip.txt +++ b/Documentation/devicetree/bindings/net/emac_rockchip.txt @@ -1,8 +1,10 @@ -* ARC EMAC 10/100 Ethernet platform driver for Rockchip Rk3066/RK3188 SoCs +* ARC EMAC 10/100 Ethernet platform driver for Rockchip RK3036/RK3066/RK3188 SoCs Required properties: -- compatible: Should be "rockchip,rk3066-emac" or "rockchip,rk3188-emac" - according to the target SoC. +- compatible: should be "rockchip,<name>-emac" + "rockchip,rk3036-emac": found on RK3036 SoCs + "rockchip,rk3066-emac": found on RK3066 SoCs + "rockchip,rk3188-emac": found on RK3188 SoCs - reg: Address and length of the register set for the device - interrupts: Should contain the EMAC interrupts - rockchip,grf: phandle to the syscon grf used to control speed and mode diff --git a/Documentation/devicetree/bindings/net/fsl-fec.txt b/Documentation/devicetree/bindings/net/fsl-fec.txt index a9eb611bee68..b037a9d78d93 100644 --- a/Documentation/devicetree/bindings/net/fsl-fec.txt +++ b/Documentation/devicetree/bindings/net/fsl-fec.txt @@ -12,6 +12,9 @@ Optional properties: only if property "phy-reset-gpios" is available. Missing the property will have the duration be 1 millisecond. Numbers greater than 1000 are invalid and 1 millisecond will be used instead. +- phy-reset-active-high : If present then the reset sequence using the GPIO + specified in the "phy-reset-gpios" property is reversed (H=reset state, + L=operation state). - phy-supply : regulator that powers the Ethernet PHY. - phy-handle : phandle to the PHY device connected to this device. - fixed-link : Assume a fixed link. See fixed-link.txt in the same directory. diff --git a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt index 1e97532a0b79..db74f0dc290c 100644 --- a/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt +++ b/Documentation/devicetree/bindings/net/fsl-tsec-phy.txt @@ -57,6 +57,10 @@ Properties: "rgmii-id", as all other connection types are detected by hardware. - fsl,magic-packet : If present, indicates that the hardware supports waking up via magic packet. + - fsl,wake-on-filer : If present, indicates that the hardware supports + waking up by Filer General Purpose Interrupt (FGPI) asserted on the + Rx int line. This is an advanced power management capability allowing + certain packet types (user) defined by filer rules to wake up the system. - bd-stash : If present, indicates that the hardware supports stashing buffer descriptors in the L2. - rx-stash-len : Denotes the number of bytes of a received buffer to stash diff --git a/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt b/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt index 988fc694b663..d1df8a00e1f3 100644 --- a/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt +++ b/Documentation/devicetree/bindings/net/hisilicon-hip04-net.txt @@ -32,13 +32,13 @@ Required properties: Required properties: -- compatible: should be "hisilicon,hip04-mdio". +- compatible: should be "hisilicon,mdio". - Inherits from MDIO bus node binding [2] [2] Documentation/devicetree/bindings/net/phy.txt Example: mdio { - compatible = "hisilicon,hip04-mdio"; + compatible = "hisilicon,mdio"; reg = <0x28f1000 0x1000>; #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/net/hisilicon-hns-dsaf.txt b/Documentation/devicetree/bindings/net/hisilicon-hns-dsaf.txt new file mode 100644 index 000000000000..ecacfa44b1eb --- /dev/null +++ b/Documentation/devicetree/bindings/net/hisilicon-hns-dsaf.txt @@ -0,0 +1,46 @@ +Hisilicon DSA Fabric device controller + +Required properties: +- compatible: should be "hisilicon,hns-dsaf-v1" or "hisilicon,hns-dsaf-v2". + "hisilicon,hns-dsaf-v1" is for hip05. + "hisilicon,hns-dsaf-v2" is for Hi1610 and Hi1612. +- mode: dsa fabric mode string. only support one of dsaf modes like these: + "2port-64vf", + "6port-16rss", + "6port-16vf". +- interrupt-parent: the interrupt parent of this device. +- interrupts: should contain the DSA Fabric and rcb interrupt. +- reg: specifies base physical address(es) and size of the device registers. + The first region is external interface control register base and size. + The second region is SerDes base register and size. + The third region is the PPE register base and size. + The fourth region is dsa fabric base register and size. + The fifth region is cpld base register and size, it is not required if do not use cpld. +- phy-handle: phy handle of physicl port, 0 if not any phy device. see ethernet.txt [1]. +- buf-size: rx buffer size, should be 16-1024. +- desc-num: number of description in TX and RX queue, should be 512, 1024, 2048 or 4096. + +[1] Documentation/devicetree/bindings/net/phy.txt + +Example: + +dsaf0: dsa@c7000000 { + compatible = "hisilicon,hns-dsaf-v1"; + mode = "6port-16rss"; + interrupt-parent = <&mbigen_dsa>; + reg = <0x0 0xC0000000 0x0 0x420000 + 0x0 0xC2000000 0x0 0x300000 + 0x0 0xc5000000 0x0 0x890000 + 0x0 0xc7000000 0x0 0x60000>; + phy-handle = <0 0 0 0 &soc0_phy4 &soc0_phy5 0 0>; + interrupts = <131 4>,<132 4>, <133 4>,<134 4>, + <135 4>,<136 4>, <137 4>,<138 4>, + <139 4>,<140 4>, <141 4>,<142 4>, + <143 4>,<144 4>, <145 4>,<146 4>, + <147 4>,<148 4>, <384 1>,<385 1>, + <386 1>,<387 1>, <388 1>,<389 1>, + <390 1>,<391 1>, + buf-size = <4096>; + desc-num = <1024>; + dma-coherent; +}; diff --git a/Documentation/devicetree/bindings/net/hisilicon-hns-mdio.txt b/Documentation/devicetree/bindings/net/hisilicon-hns-mdio.txt new file mode 100644 index 000000000000..4a7ede9657b0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/hisilicon-hns-mdio.txt @@ -0,0 +1,27 @@ +Hisilicon MDIO bus controller + +Properties: +- compatible: can be one of: + "hisilicon,hns-mdio" + "hisilicon,mdio" + "hisilicon,hns-mdio" is recommended to be used for hip05 and later SOCs, + while "hisilicon,mdio" is optional for backwards compatibility only on + hip04 Soc. +- reg: The base address of the MDIO bus controller register bank. +- #address-cells: Must be <1>. +- #size-cells: Must be <0>. MDIO addresses have no size component. + +Typically an MDIO bus might have several children. + +Example: + mdio@803c0000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "hisilicon,hns-mdio","hisilicon,mdio"; + reg = <0x0 0x803c0000 0x0 0x10000>; + + ethernet-phy@0 { + ... + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/hisilicon-hns-nic.txt b/Documentation/devicetree/bindings/net/hisilicon-hns-nic.txt new file mode 100644 index 000000000000..e6a9d1c30878 --- /dev/null +++ b/Documentation/devicetree/bindings/net/hisilicon-hns-nic.txt @@ -0,0 +1,48 @@ +Hisilicon Network Subsystem NIC controller + +Required properties: +- compatible: "hisilicon,hns-nic-v1" or "hisilicon,hns-nic-v2". + "hisilicon,hns-nic-v1" is for hip05. + "hisilicon,hns-nic-v2" is for Hi1610 and Hi1612. +- ae-handle: accelerator engine handle for hns, + specifies a reference to the associating hardware driver node. + see Documentation/devicetree/bindings/net/hisilicon-hns-dsaf.txt +- port-id: is the index of port provided by DSAF (the accelerator). DSAF can + connect to 8 PHYs. Port 0 to 1 are both used for adminstration purpose. They + are called debug ports. + + The remaining 6 PHYs are taken according to the mode of DSAF. + + In NIC mode of DSAF, all 6 PHYs are taken as ethernet ports to the CPU. The + port-id can be 2 to 7. Here is the diagram: + +-----+---------------+ + | CPU | + +-+-+-+---+-+-+-+-+-+-+ + | | | | | | | | + debug service + port port + (0,1) (2-7) + + In Switch mode of DSAF, all 6 PHYs are taken as physical ports connect to a + LAN Switch while the CPU side assume itself have one single NIC connect to + this switch. In this case, the port-id will be 2 only. + +-----+---------------+ + | CPU | + +-+-+-+---+-+-+-+-+-+-+ + | | service| port(2) + debug +------------+ + port | switch | + (0,1) +-+-+-+-+-+-++ + | | | | | | + external port + +- local-mac-address: mac addr of the ethernet interface + +Example: + + ethernet@0{ + compatible = "hisilicon,hns-nic-v1"; + ae-handle = <&dsaf0>; + port-id = <0>; + local-mac-address = [a2 14 e4 4b 56 76]; + }; diff --git a/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt b/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt new file mode 100644 index 000000000000..dea5124cdc52 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ieee802154/adf7242.txt @@ -0,0 +1,18 @@ +* ADF7242 IEEE 802.15.4 * + +Required properties: + - compatible: should be "adi,adf7242" + - spi-max-frequency: maximal bus speed (12.5 MHz) + - reg: the chipselect index + - interrupts: the interrupt generated by the device via pin IRQ1. + IRQ_TYPE_LEVEL_HIGH (4) or IRQ_TYPE_EDGE_FALLING (1) + +Example: + + adf7242@0 { + compatible = "adi,adf7242"; + spi-max-frequency = <10000000>; + reg = <0>; + interrupts = <98 IRQ_TYPE_LEVEL_HIGH>; + interrupt-parent = <&gpio3>; + }; diff --git a/Documentation/devicetree/bindings/net/ieee802154/mrf24j40.txt b/Documentation/devicetree/bindings/net/ieee802154/mrf24j40.txt new file mode 100644 index 000000000000..a4ed2efb5b73 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ieee802154/mrf24j40.txt @@ -0,0 +1,20 @@ +* MRF24J40 IEEE 802.15.4 * + +Required properties: + - compatible: should be "microchip,mrf24j40", "microchip,mrf24j40ma", + or "microchip,mrf24j40mc" depends on your transceiver + board + - spi-max-frequency: maximal bus speed, should be set something under or equal + 10000000 + - reg: the chipselect index + - interrupts: the interrupt generated by the device. + +Example: + + mrf24j40ma@0 { + compatible = "microchip,mrf24j40ma"; + spi-max-frequency = <8500000>; + reg = <0>; + interrupts = <19 8>; + interrupt-parent = <&gpio3>; + }; diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index b5d79761ac97..b5a42df4c928 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -2,15 +2,19 @@ Required properties: - compatible: Should be "cdns,[<chip>-]{macb|gem}" + Use "cdns,at91rm9200-emac" Atmel at91rm9200 SoC. Use "cdns,at91sam9260-macb" for Atmel at91sam9 SoCs or the 10/100Mbit IP available on sama5d3 SoCs. + Use "cdns,np4-macb" for NP4 SoC devices. Use "cdns,at32ap7000-macb" for other 10/100 usage or use the generic form: "cdns,macb". Use "cdns,pc302-gem" for Picochip picoXcell pc302 and later devices based on the Cadence GEM, or the generic form: "cdns,gem". Use "atmel,sama5d2-gem" for the GEM IP (10/100) available on Atmel sama5d2 SoCs. Use "atmel,sama5d3-gem" for the Gigabit IP available on Atmel sama5d3 SoCs. Use "atmel,sama5d4-gem" for the GEM IP (10/100) available on Atmel sama5d4 SoCs. + Use "cdns,zynq-gem" Xilinx Zynq-7xxx SoC. Use "cdns,zynqmp-gem" for Zynq Ultrascale+ MPSoC. + Or the generic form: "cdns,emac". - reg: Address and length of the register set for the device - interrupts: Should contain macb interrupt - phy-mode: See ethernet.txt file in the same directory. @@ -19,6 +23,11 @@ Required properties: Optional elements: 'tx_clk' - clocks: Phandles to input clocks. +Optional properties for PHY child node: +- reset-gpios : Should specify the gpio for phy reset +- magic-packet : If present, indicates that the hardware supports waking + up via magic packet. + Examples: macb0: ethernet@fffc4000 { @@ -29,4 +38,8 @@ Examples: local-mac-address = [3a 0e 03 04 05 06]; clock-names = "pclk", "hclk", "tx_clk"; clocks = <&clkc 30>, <&clkc 30>, <&clkc 13>; + ethernet-phy@1 { + reg = <0x1>; + reset-gpios = <&pioE 6 1>; + }; }; diff --git a/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt b/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt index f5a8ca29aff0..73be8970815e 100644 --- a/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt +++ b/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt @@ -6,16 +6,42 @@ Required properties: - interrupts: interrupt for the device - phy: See ethernet.txt file in the same directory. - phy-mode: See ethernet.txt file in the same directory -- clocks: a pointer to the reference clock for this device. +- clocks: List of clocks for this device. At least one clock is + mandatory for the core clock. If several clocks are given, then the + clock-names property must be used to identify them. + +Optional properties: +- tx-csum-limit: maximum mtu supported by port that allow TX checksum. + Value is presented in bytes. If not used, by default 1600B is set for + "marvell,armada-370-neta" and 9800B for others. +- clock-names: List of names corresponding to clocks property; shall be + "core" for core clock and "bus" for the optional bus clock. + + +Optional properties (valid only for Armada XP/38x): + +- buffer-manager: a phandle to a buffer manager node. Please refer to + Documentation/devicetree/bindings/net/marvell-neta-bm.txt +- bm,pool-long: ID of a pool, that will accept all packets of a size + higher than 'short' pool's threshold (if set) and up to MTU value. + Obligatory, when the port is supposed to use hardware + buffer management. +- bm,pool-short: ID of a pool, that will be used for accepting + packets of a size lower than given threshold. If not set, the port + will use a single 'long' pool for all packets, as defined above. Example: -ethernet@d0070000 { +ethernet@70000 { compatible = "marvell,armada-370-neta"; - reg = <0xd0070000 0x2500>; + reg = <0x70000 0x2500>; interrupts = <8>; clocks = <&gate_clk 4>; + tx-csum-limit = <9800> status = "okay"; phy = <&phy0>; phy-mode = "rgmii-id"; + buffer-manager = <&bm>; + bm,pool-long = <0>; + bm,pool-short = <1>; }; diff --git a/Documentation/devicetree/bindings/net/marvell-neta-bm.txt b/Documentation/devicetree/bindings/net/marvell-neta-bm.txt new file mode 100644 index 000000000000..c1b1d7c3bde1 --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell-neta-bm.txt @@ -0,0 +1,49 @@ +* Marvell Armada 380/XP Buffer Manager driver (BM) + +Required properties: + +- compatible: should be "marvell,armada-380-neta-bm". +- reg: address and length of the register set for the device. +- clocks: a pointer to the reference clock for this device. +- internal-mem: a phandle to BM internal SRAM definition. + +Optional properties (port): + +- pool<0 : 3>,capacity: size of external buffer pointers' ring maintained + in DRAM. Can be set for each pool (id 0 : 3) separately. The value has + to be chosen between 128 and 16352 and it also has to be aligned to 32. + Otherwise the driver would adjust a given number or choose default if + not set. +- pool<0 : 3>,pkt-size: maximum size of a packet accepted by a given buffer + pointers' pool (id 0 : 3). It will be taken into consideration only when pool + type is 'short'. For 'long' ones it would be overridden by port's MTU. + If not set a driver will choose a default value. + +In order to see how to hook the BM to a given ethernet port, please +refer to Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt. + +Example: + +- main node: + +bm: bm@c8000 { + compatible = "marvell,armada-380-neta-bm"; + reg = <0xc8000 0xac>; + clocks = <&gateclk 13>; + internal-mem = <&bm_bppi>; + status = "okay"; + pool2,capacity = <4096>; + pool1,pkt-size = <512>; +}; + +- internal SRAM node: + +bm_bppi: bm-bppi { + compatible = "mmio-sram"; + reg = <MBUS_ID(0x0c, 0x04) 0 0x100000>; + ranges = <0 MBUS_ID(0x0c, 0x04) 0 0x100000>; + #address-cells = <1>; + #size-cells = <1>; + clocks = <&gateclk 13>; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/net/maxim,ds26522.txt b/Documentation/devicetree/bindings/net/maxim,ds26522.txt new file mode 100644 index 000000000000..ee8bb725f245 --- /dev/null +++ b/Documentation/devicetree/bindings/net/maxim,ds26522.txt @@ -0,0 +1,13 @@ +* Maxim (Dallas) DS26522 Dual T1/E1/J1 Transceiver + +Required properties: +- compatible: Should contain "maxim,ds26522". +- reg: SPI CS. +- spi-max-frequency: SPI clock. + +Example: + slic@1 { + compatible = "maxim,ds26522"; + reg = <1>; + spi-max-frequency = <2000000>; /* input clock */ + }; diff --git a/Documentation/devicetree/bindings/net/mdio-mux-gpio.txt b/Documentation/devicetree/bindings/net/mdio-mux-gpio.txt index 79384113c2b0..694987d3c17a 100644 --- a/Documentation/devicetree/bindings/net/mdio-mux-gpio.txt +++ b/Documentation/devicetree/bindings/net/mdio-mux-gpio.txt @@ -38,7 +38,6 @@ Example : phy11: ethernet-phy@1 { reg = <1>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -48,7 +47,6 @@ Example : }; phy12: ethernet-phy@2 { reg = <2>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -58,7 +56,6 @@ Example : }; phy13: ethernet-phy@3 { reg = <3>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -68,7 +65,6 @@ Example : }; phy14: ethernet-phy@4 { reg = <4>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -85,7 +81,6 @@ Example : phy21: ethernet-phy@1 { reg = <1>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -95,7 +90,6 @@ Example : }; phy22: ethernet-phy@2 { reg = <2>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -105,7 +99,6 @@ Example : }; phy23: ethernet-phy@3 { reg = <3>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -115,7 +108,6 @@ Example : }; phy24: ethernet-phy@4 { reg = <4>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, diff --git a/Documentation/devicetree/bindings/net/mdio-mux.txt b/Documentation/devicetree/bindings/net/mdio-mux.txt index f65606f8d632..491f5bd55203 100644 --- a/Documentation/devicetree/bindings/net/mdio-mux.txt +++ b/Documentation/devicetree/bindings/net/mdio-mux.txt @@ -47,7 +47,6 @@ Example : phy11: ethernet-phy@1 { reg = <1>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -57,7 +56,6 @@ Example : }; phy12: ethernet-phy@2 { reg = <2>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -67,7 +65,6 @@ Example : }; phy13: ethernet-phy@3 { reg = <3>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -77,7 +74,6 @@ Example : }; phy14: ethernet-phy@4 { reg = <4>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -94,7 +90,6 @@ Example : phy21: ethernet-phy@1 { reg = <1>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -104,7 +99,6 @@ Example : }; phy22: ethernet-phy@2 { reg = <2>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -114,7 +108,6 @@ Example : }; phy23: ethernet-phy@3 { reg = <3>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, @@ -124,7 +117,6 @@ Example : }; phy24: ethernet-phy@4 { reg = <4>; - compatible = "marvell,88e1149r"; marvell,reg-init = <3 0x10 0 0x5777>, <3 0x11 0 0x00aa>, <3 0x12 0 0x4105>, diff --git a/Documentation/devicetree/bindings/net/mediatek,mt7620-gsw.txt b/Documentation/devicetree/bindings/net/mediatek,mt7620-gsw.txt new file mode 100644 index 000000000000..aa6313024176 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mediatek,mt7620-gsw.txt @@ -0,0 +1,26 @@ +Mediatek Gigabit Switch +======================= + +The mediatek gigabit switch can be found on Mediatek SoCs (mt7620, mt7621). + +Required properties: +- compatible: Should be "mediatek,mt7620-gsw" or "mediatek,mt7621-gsw" +- reg: Address and length of the register set for the device +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the gigabit switches interrupt +- resets: Should contain the gigabit switches resets +- reset-names: Should contain the reset names "gsw" + +Example: + +gsw@10110000 { + compatible = "ralink,mt7620-gsw"; + reg = <0x10110000 8000>; + + resets = <&rstctrl 23>; + reset-names = "gsw"; + + interrupt-parent = <&intc>; + interrupts = <17>; +}; diff --git a/Documentation/devicetree/bindings/net/mediatek-net.txt b/Documentation/devicetree/bindings/net/mediatek-net.txt new file mode 100644 index 000000000000..5ca79290eabf --- /dev/null +++ b/Documentation/devicetree/bindings/net/mediatek-net.txt @@ -0,0 +1,77 @@ +MediaTek Frame Engine Ethernet controller +========================================= + +The frame engine ethernet controller can be found on MediaTek SoCs. These SoCs +have dual GMAC each represented by a child node.. + +* Ethernet controller node + +Required properties: +- compatible: Should be "mediatek,mt7623-eth" +- reg: Address and length of the register set for the device +- interrupts: Should contain the frame engines interrupt +- clocks: the clock used by the core +- clock-names: the names of the clock listed in the clocks property. These are + "ethif", "esw", "gp2", "gp1" +- power-domains: phandle to the power domain that the ethernet is part of +- resets: Should contain a phandle to the ethsys reset signal +- reset-names: Should contain the reset signal name "eth" +- mediatek,ethsys: phandle to the syscon node that handles the port setup +- mediatek,pctl: phandle to the syscon node that handles the ports slew rate + and driver current + +Optional properties: +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device + + +* Ethernet MAC node + +Required properties: +- compatible: Should be "mediatek,eth-mac" +- reg: The number of the MAC +- phy-handle: see ethernet.txt file in the same directory. + +Example: + +eth: ethernet@1b100000 { + compatible = "mediatek,mt7623-eth"; + reg = <0 0x1b100000 0 0x20000>; + clocks = <&topckgen CLK_TOP_ETHIF_SEL>, + <ðsys CLK_ETHSYS_ESW>, + <ðsys CLK_ETHSYS_GP2>, + <ðsys CLK_ETHSYS_GP1>; + clock-names = "ethif", "esw", "gp2", "gp1"; + interrupts = <GIC_SPI 200 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT2701_POWER_DOMAIN_ETH>; + resets = <ðsys MT2701_ETHSYS_ETH_RST>; + reset-names = "eth"; + mediatek,ethsys = <ðsys>; + mediatek,pctl = <&syscfg_pctl_a>; + #address-cells = <1>; + #size-cells = <0>; + + gmac1: mac@0 { + compatible = "mediatek,eth-mac"; + reg = <0>; + phy-handle = <&phy0>; + }; + + gmac2: mac@1 { + compatible = "mediatek,eth-mac"; + reg = <1>; + phy-handle = <&phy1>; + }; + + mdio-bus { + phy0: ethernet-phy@0 { + reg = <0>; + phy-mode = "rgmii"; + }; + + phy1: ethernet-phy@1 { + reg = <1>; + phy-mode = "rgmii"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/net/micrel-ks8995.txt b/Documentation/devicetree/bindings/net/micrel-ks8995.txt new file mode 100644 index 000000000000..281bc2498d12 --- /dev/null +++ b/Documentation/devicetree/bindings/net/micrel-ks8995.txt @@ -0,0 +1,20 @@ +Micrel KS8995 SPI controlled Ethernet Switch families + +Required properties (according to spi-bus.txt): +- compatible: either "micrel,ks8995", "micrel,ksz8864" or "micrel,ksz8795" + +Optional properties: +- reset-gpios : phandle of gpio that will be used to reset chip during probe + +Example: + +spi-master { + ... + switch@0 { + compatible = "micrel,ksz8795"; + + reg = <0>; + spi-max-frequency = <50000000>; + reset-gpios = <&gpio0 46 GPIO_ACTIVE_LOW>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt index 692076fda0e5..f9c32adab5c6 100644 --- a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt +++ b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt @@ -1,8 +1,9 @@ Micrel KSZ9021/KSZ9031 Gigabit Ethernet PHY -Some boards require special tuning values, particularly when it comes to -clock delays. You can specify clock delay values by adding -micrel-specific properties to an Ethernet OF device node. +Some boards require special tuning values, particularly when it comes +to clock delays. You can specify clock delay values in the PHY OF +device node. Deprecated, but still supported, these properties can +also be added to an Ethernet OF device node. Note that these settings are applied after any phy-specific fixup from phy_fixup_list (see phy_init_hw() from drivers/net/phy/phy_device.c), @@ -57,16 +58,6 @@ KSZ9031: Examples: - /* Attach to an Ethernet device with autodetected PHY */ - &enet { - rxc-skew-ps = <3000>; - rxdv-skew-ps = <0>; - txc-skew-ps = <3000>; - txen-skew-ps = <0>; - status = "okay"; - }; - - /* Attach to an explicitly-specified PHY */ mdio { phy0: ethernet-phy@0 { rxc-skew-ps = <3000>; diff --git a/Documentation/devicetree/bindings/net/nfc/nfcmrvl.txt b/Documentation/devicetree/bindings/net/nfc/nfcmrvl.txt index 7c4a0cc370cf..76df9173825a 100644 --- a/Documentation/devicetree/bindings/net/nfc/nfcmrvl.txt +++ b/Documentation/devicetree/bindings/net/nfc/nfcmrvl.txt @@ -1,7 +1,10 @@ * Marvell International Ltd. NCI NFC Controller Required properties: -- compatible: Should be "mrvl,nfc-uart". +- compatible: Should be: + - "marvell,nfc-uart" or "mrvl,nfc-uart" for UART devices + - "marvell,nfc-i2c" for I2C devices + - "marvell,nfc-spi" for SPI devices Optional SoC specific properties: - pinctrl-names: Contains only one value - "default". @@ -13,13 +16,19 @@ Optional UART-based chip specific properties: - flow-control: Specifies that the chip is using RTS/CTS. - break-control: Specifies that the chip needs specific break management. +Optional I2C-based chip specific properties: +- i2c-int-falling: Specifies that the chip read event shall be trigged on + falling edge. +- i2c-int-rising: Specifies that the chip read event shall be trigged on + rising edge. + Example (for ARM-based BeagleBoard Black with 88W8887 on UART5): &uart5 { status = "okay"; nfcmrvluart: nfcmrvluart@5 { - compatible = "mrvl,nfc-uart"; + compatible = "marvell,nfc-uart"; reset-n-io = <&gpio3 16 0>; @@ -27,3 +36,51 @@ Example (for ARM-based BeagleBoard Black with 88W8887 on UART5): flow-control; } }; + + +Example (for ARM-based BeagleBoard Black with 88W8887 on I2C1): + +&i2c1 { + status = "okay"; + clock-frequency = <400000>; + + nfcmrvli2c0: i2c@1 { + compatible = "marvell,nfc-i2c"; + + reg = <0x8>; + + /* I2C INT configuration */ + interrupt-parent = <&gpio3>; + interrupts = <21 0>; + + /* I2C INT trigger configuration */ + i2c-int-rising; + + /* Reset IO */ + reset-n-io = <&gpio3 19 0>; + }; +}; + + +Example (for ARM-based BeagleBoard Black on SPI0): + +&spi0 { + + mrvlnfcspi0: spi@0 { + compatible = "marvell,nfc-spi"; + + reg = <0>; + + /* SPI Bus configuration */ + spi-max-frequency = <3000000>; + spi-cpha; + spi-cpol; + + /* SPI INT configuration */ + interrupt-parent = <&gpio1>; + interrupts = <17 0>; + + /* Reset IO */ + reset-n-io = <&gpio3 19 0>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/nfc/st-nci-i2c.txt b/Documentation/devicetree/bindings/net/nfc/st-nci-i2c.txt index d707588ed734..263732e8879f 100644 --- a/Documentation/devicetree/bindings/net/nfc/st-nci-i2c.txt +++ b/Documentation/devicetree/bindings/net/nfc/st-nci-i2c.txt @@ -11,6 +11,10 @@ Required properties: Optional SoC Specific Properties: - pinctrl-names: Contains only one value - "default". - pintctrl-0: Specifies the pin control groups used for this controller. +- ese-present: Specifies that an ese is physically connected to the nfc +controller. +- uicc-present: Specifies that the uicc swp signal can be physically +connected to the nfc controller. Example (for ARM-based BeagleBoard xM with ST21NFCB on I2C2): @@ -29,5 +33,8 @@ Example (for ARM-based BeagleBoard xM with ST21NFCB on I2C2): interrupts = <2 IRQ_TYPE_LEVEL_HIGH>; reset-gpios = <&gpio5 29 GPIO_ACTIVE_HIGH>; + + ese-present; + uicc-present; }; }; diff --git a/Documentation/devicetree/bindings/net/nfc/st-nci-spi.txt b/Documentation/devicetree/bindings/net/nfc/st-nci-spi.txt index 525681b6dc39..711ca85a363d 100644 --- a/Documentation/devicetree/bindings/net/nfc/st-nci-spi.txt +++ b/Documentation/devicetree/bindings/net/nfc/st-nci-spi.txt @@ -2,7 +2,7 @@ Required properties: - compatible: Should be "st,st21nfcb-spi" -- spi-max-frequency: Maximum SPI frequency (<= 10000000). +- spi-max-frequency: Maximum SPI frequency (<= 4000000). - interrupt-parent: phandle for the interrupt gpio controller - interrupts: GPIO interrupt to which the chip is connected - reset-gpios: Output GPIO pin used to reset the ST21NFCB @@ -10,6 +10,10 @@ Required properties: Optional SoC Specific Properties: - pinctrl-names: Contains only one value - "default". - pintctrl-0: Specifies the pin control groups used for this controller. +- ese-present: Specifies that an ese is physically connected to the nfc +controller. +- uicc-present: Specifies that the uicc swp signal can be physically +connected to the nfc controller. Example (for ARM-based BeagleBoard xM with ST21NFCB on SPI4): @@ -27,5 +31,8 @@ Example (for ARM-based BeagleBoard xM with ST21NFCB on SPI4): interrupts = <2 IRQ_TYPE_EDGE_RISING>; reset-gpios = <&gpio5 29 GPIO_ACTIVE_HIGH>; + + ese-present; + uicc-present; }; }; diff --git a/Documentation/devicetree/bindings/net/nfc/st95hf.txt b/Documentation/devicetree/bindings/net/nfc/st95hf.txt new file mode 100644 index 000000000000..ea3178bc9ddd --- /dev/null +++ b/Documentation/devicetree/bindings/net/nfc/st95hf.txt @@ -0,0 +1,50 @@ +* STMicroelectronics : NFC Transceiver ST95HF + +ST NFC Transceiver is required to attach with SPI bus. +ST95HF node should be defined in DT as SPI slave device of SPI +master with which ST95HF transceiver is physically connected. +The properties defined below are required to be the part of DT +to include ST95HF transceiver into the platform. + +Required properties: +=================== +- reg: Address of SPI slave "ST95HF transceiver" on SPI master bus. + +- compatible: should be "st,st95hf" for ST95HF NFC transceiver + +- spi-max-frequency: Max. operating SPI frequency for ST95HF + transceiver. + +- enable-gpio: GPIO line to enable ST95HF transceiver. + +- interrupt-parent : Standard way to specify the controller to which + ST95HF transceiver's interrupt is routed. + +- interrupts : Standard way to define ST95HF transceiver's out + interrupt. + +Optional property: +================= +- st95hfvin-supply : This is an optional property. It contains a + phandle to ST95HF transceiver's regulator supply node in DT. + +Example: +======= +spi@9840000 { + reg = <0x9840000 0x110>; + #address-cells = <1>; + #size-cells = <0>; + cs-gpios = <&pio0 4>; + status = "okay"; + + st95hf@0{ + reg = <0>; + compatible = "st,st95hf"; + status = "okay"; + spi-max-frequency = <1000000>; + enable-gpio = <&pio4 0>; + interrupt-parent = <&pio0>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + }; + +}; diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index 525e1658f2da..bc1c3c8bf8fa 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -17,8 +17,7 @@ Optional Properties: "ethernet-phy-ieee802.3-c22" or "ethernet-phy-ieee802.3-c45" for PHYs that implement IEEE802.3 clause 22 or IEEE802.3 clause 45 specifications. If neither of these are specified, the default is to - assume clause 22. The compatible list may also contain other - elements. + assume clause 22. If the phy's identifier is known then the list may contain an entry of the form: "ethernet-phy-idAAAA.BBBB" where @@ -28,6 +27,9 @@ Optional Properties: 4 hex digits. This is the chip vendor OUI bits 19:24, followed by 10 bits of a vendor specific ID. + The compatible list should not contain other values than those + listed here. + - max-speed: Maximum PHY supported speed (10, 100, 1000...) - broken-turn-around: If set, indicates the PHY device does not correctly diff --git a/Documentation/devicetree/bindings/net/ralink,rt2880-net.txt b/Documentation/devicetree/bindings/net/ralink,rt2880-net.txt new file mode 100644 index 000000000000..88b095d1f13b --- /dev/null +++ b/Documentation/devicetree/bindings/net/ralink,rt2880-net.txt @@ -0,0 +1,61 @@ +Ralink Frame Engine Ethernet controller +======================================= + +The Ralink frame engine ethernet controller can be found on Ralink and +Mediatek SoCs (RT288x, RT3x5x, RT366x, RT388x, rt5350, mt7620, mt7621, mt76x8). + +Depending on the SoC, there is a number of ports connected to the CPU port +directly and/or via a (gigabit-)switch. + +* Ethernet controller node + +Required properties: +- compatible: Should be one of "ralink,rt2880-eth", "ralink,rt3050-eth", + "ralink,rt3050-eth", "ralink,rt3883-eth", "ralink,rt5350-eth", + "mediatek,mt7620-eth", "mediatek,mt7621-eth" +- reg: Address and length of the register set for the device +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the frame engines interrupt +- resets: Should contain the frame engines resets +- reset-names: Should contain the reset names "fe". If a switch is present + "esw" is also required. + + +* Ethernet port node + +Required properties: +- compatible: Should be "ralink,eth-port" +- reg: The number of the physical port +- phy-handle: reference to the node describing the phy + +Example: + +mdio-bus { + ... + phy0: ethernet-phy@0 { + phy-mode = "mii"; + reg = <0>; + }; +}; + +ethernet@400000 { + compatible = "ralink,rt2880-eth"; + reg = <0x00400000 10000>; + + #address-cells = <1>; + #size-cells = <0>; + + resets = <&rstctrl 18>; + reset-names = "fe"; + + interrupt-parent = <&cpuintc>; + interrupts = <5>; + + port@0 { + compatible = "ralink,eth-port"; + reg = <0>; + phy-handle = <&phy0>; + }; + +}; diff --git a/Documentation/devicetree/bindings/net/ralink,rt3050-esw.txt b/Documentation/devicetree/bindings/net/ralink,rt3050-esw.txt new file mode 100644 index 000000000000..2e79bd376c56 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ralink,rt3050-esw.txt @@ -0,0 +1,32 @@ +Ralink Fast Ethernet Embedded Switch +==================================== + +The ralink fast ethernet embedded switch can be found on Ralink and Mediatek +SoCs (RT3x5x, RT5350, MT76x8). + +Required properties: +- compatible: Should be "ralink,rt3050-esw" +- reg: Address and length of the register set for the device +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupts: Should contain the embedded switches interrupt +- resets: Should contain the embedded switches resets +- reset-names: Should contain the reset names "esw" + +Optional properties: +- ralink,portmap: can be used to choose if the default switch setup is + llllw or wllll +- ralink,led_polarity: override the active high/low settings of the leds + +Example: + +esw@10110000 { + compatible = "ralink,rt3050-esw"; + reg = <0x10110000 8000>; + + resets = <&rstctrl 23>; + reset-names = "esw"; + + interrupt-parent = <&intc>; + interrupts = <17>; +}; diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt index 1fd8831437bf..c8ac222eac67 100644 --- a/Documentation/devicetree/bindings/net/renesas,ravb.txt +++ b/Documentation/devicetree/bindings/net/renesas,ravb.txt @@ -5,9 +5,23 @@ interface contains. Required properties: - compatible: "renesas,etheravb-r8a7790" if the device is a part of R8A7790 SoC. + "renesas,etheravb-r8a7791" if the device is a part of R8A7791 SoC. + "renesas,etheravb-r8a7792" if the device is a part of R8A7792 SoC. + "renesas,etheravb-r8a7793" if the device is a part of R8A7793 SoC. "renesas,etheravb-r8a7794" if the device is a part of R8A7794 SoC. + "renesas,etheravb-r8a7795" if the device is a part of R8A7795 SoC. + "renesas,etheravb-rcar-gen2" for generic R-Car Gen 2 compatible interface. + "renesas,etheravb-rcar-gen3" for generic R-Car Gen 3 compatible interface. + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first + followed by the generic version. + - reg: offset and length of (1) the register block and (2) the stream buffer. -- interrupts: interrupt specifier for the sole interrupt. +- interrupts: A list of interrupt-specifiers, one for each entry in + interrupt-names. + If interrupt-names is not present, an interrupt specifier + for a single muxed interrupt. - phy-mode: see ethernet.txt file in the same directory. - phy-handle: see ethernet.txt file in the same directory. - #address-cells: number of address cells for the MDIO bus, must be equal to 1. @@ -18,6 +32,12 @@ Required properties: Optional properties: - interrupt-parent: the phandle for the interrupt controller that services interrupts for this device. +- interrupt-names: A list of interrupt names. + For the R8A7795 SoC this property is mandatory; + it should include one entry per channel, named "ch%u", + where %u is the channel number ranging from 0 to 24. + For other SoCs this property is optional; if present + it should contain "mux" for a single muxed interrupt. - pinctrl-names: pin configuration state name ("default"). - renesas,no-ether-link: boolean, specify when a board does not provide a proper AVB_LINK signal. @@ -27,13 +47,46 @@ Optional properties: Example: ethernet@e6800000 { - compatible = "renesas,etheravb-r8a7790"; - reg = <0 0xe6800000 0 0x800>, <0 0xee0e8000 0 0x4000>; + compatible = "renesas,etheravb-r8a7795", "renesas,etheravb-rcar-gen3"; + reg = <0 0xe6800000 0 0x800>, <0 0xe6a00000 0 0x10000>; interrupt-parent = <&gic>; - interrupts = <0 163 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&mstp8_clks R8A7790_CLK_ETHERAVB>; - phy-mode = "rmii"; + interrupts = <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 44 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 45 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 46 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 47 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 49 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 53 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 54 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 57 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 58 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 59 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 60 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 61 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 62 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 63 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "ch0", "ch1", "ch2", "ch3", + "ch4", "ch5", "ch6", "ch7", + "ch8", "ch9", "ch10", "ch11", + "ch12", "ch13", "ch14", "ch15", + "ch16", "ch17", "ch18", "ch19", + "ch20", "ch21", "ch22", "ch23", + "ch24"; + clocks = <&cpg CPG_MOD 812>; + power-domains = <&cpg>; + phy-mode = "rgmii-id"; phy-handle = <&phy0>; + pinctrl-0 = <ðer_pins>; pinctrl-names = "default"; renesas,no-ether-link; @@ -41,8 +94,20 @@ Example: #size-cells = <0>; phy0: ethernet-phy@0 { + rxc-skew-ps = <900>; + rxdv-skew-ps = <0>; + rxd0-skew-ps = <0>; + rxd1-skew-ps = <0>; + rxd2-skew-ps = <0>; + rxd3-skew-ps = <0>; + txc-skew-ps = <900>; + txen-skew-ps = <0>; + txd0-skew-ps = <0>; + txd1-skew-ps = <0>; + txd2-skew-ps = <0>; + txd3-skew-ps = <0>; reg = <0>; interrupt-parent = <&gpio2>; - interrupts = <15 IRQ_TYPE_LEVEL_LOW>; + interrupts = <11 IRQ_TYPE_LEVEL_LOW>; }; }; diff --git a/Documentation/devicetree/bindings/net/socfpga-dwmac.txt b/Documentation/devicetree/bindings/net/socfpga-dwmac.txt index 3a9d67951606..72d82d684342 100644 --- a/Documentation/devicetree/bindings/net/socfpga-dwmac.txt +++ b/Documentation/devicetree/bindings/net/socfpga-dwmac.txt @@ -11,6 +11,8 @@ Required properties: designware version numbers documented in stmmac.txt - altr,sysmgr-syscon : Should be the phandle to the system manager node that encompasses the glue register, the register offset, and the register shift. + - altr,f2h_ptp_ref_clk use f2h_ptp_ref_clk instead of default eosc1 clock + for ptp ref clk. This affects all emacs as the clock is common. Optional properties: altr,emac-splitter: Should be the phandle to the emac splitter soft IP node if diff --git a/Documentation/devicetree/bindings/net/stmmac.txt b/Documentation/devicetree/bindings/net/stmmac.txt index f34fc3c81a75..6605d19601c2 100644 --- a/Documentation/devicetree/bindings/net/stmmac.txt +++ b/Documentation/devicetree/bindings/net/stmmac.txt @@ -17,18 +17,6 @@ Required properties: The 1st cell is reset pre-delay in micro seconds. The 2nd cell is reset pulse in micro seconds. The 3rd cell is reset post-delay in micro seconds. -- snps,pbl Programmable Burst Length -- snps,fixed-burst Program the DMA to use the fixed burst mode -- snps,mixed-burst Program the DMA to use the mixed burst mode -- snps,force_thresh_dma_mode Force DMA to use the threshold mode for - both tx and rx -- snps,force_sf_dma_mode Force DMA to use the Store and Forward - mode for both tx and rx. This flag is - ignored if force_thresh_dma_mode is set. -- snps,multicast-filter-bins: Number of multicast filter hash bins - supported by this device instance -- snps,perfect-filter-entries: Number of perfect filter entries supported - by this device instance Optional properties: - resets: Should contain a phandle to the STMMAC reset signal, if any @@ -44,12 +32,43 @@ Optional properties: available this clock is used for programming the Timestamp Addend Register. If not passed then the system clock will be used and this is fine on some platforms. -- snps,burst_len: The AXI burst lenth value of the AXI BUS MODE register. - tx-fifo-depth: See ethernet.txt file in the same directory - rx-fifo-depth: See ethernet.txt file in the same directory +- snps,pbl Programmable Burst Length +- snps,aal Address-Aligned Beats +- snps,fixed-burst Program the DMA to use the fixed burst mode +- snps,mixed-burst Program the DMA to use the mixed burst mode +- snps,force_thresh_dma_mode Force DMA to use the threshold mode for + both tx and rx +- snps,force_sf_dma_mode Force DMA to use the Store and Forward + mode for both tx and rx. This flag is + ignored if force_thresh_dma_mode is set. +- snps,multicast-filter-bins: Number of multicast filter hash bins + supported by this device instance +- snps,perfect-filter-entries: Number of perfect filter entries supported + by this device instance +- AXI BUS Mode parameters: below the list of all the parameters to program the + AXI register inside the DMA module: + - snps,lpi_en: enable Low Power Interface + - snps,xit_frm: unlock on WoL + - snps,wr_osr_lmt: max write oustanding req. limit + - snps,rd_osr_lmt: max read oustanding req. limit + - snps,kbbe: do not cross 1KiB boundary. + - snps,axi_all: align address + - snps,blen: this is a vector of supported burst length. + - snps,fb: fixed-burst + - snps,mb: mixed-burst + - snps,rb: rebuild INCRx Burst +- mdio: with compatible = "snps,dwmac-mdio", create and register mdio bus. Examples: + stmmac_axi_setup: stmmac-axi-config { + snps,wr_osr_lmt = <0xf>; + snps,rd_osr_lmt = <0xf>; + snps,blen = <256 128 64 32 0 0 0>; + }; + gmac0: ethernet@e0800000 { compatible = "st,spear600-gmac"; reg = <0xe0800000 0x8000>; @@ -65,4 +84,12 @@ Examples: tx-fifo-depth = <16384>; clocks = <&clock>; clock-names = "stmmaceth"; + snps,axi-config = <&stmmac_axi_setup>; + mdio0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "snps,dwmac-mdio"; + phy1: ethernet-phy@0 { + }; + }; }; diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index edefc26c6204..96aae6b4f736 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -1,17 +1,46 @@ * Qualcomm Atheros ath10k wireless devices -For ath10k devices the calibration data can be provided through Device -Tree. The node is a child node of the PCI controller. - Required properties: --compatible : Should be "qcom,ath10k" +- compatible: Should be one of the following: + * "qcom,ath10k" + * "qcom,ipq4019-wifi" + +PCI based devices uses compatible string "qcom,ath10k" and takes only +calibration data via "qcom,ath10k-calibration-data". Rest of the properties +are not applicable for PCI based devices. + +AHB based devices (i.e. ipq4019) uses compatible string "qcom,ipq4019-wifi" +and also uses most of the properties defined in this doc. Optional properties: +- reg: Address and length of the register set for the device. +- resets: Must contain an entry for each entry in reset-names. + See ../reset/reseti.txt for details. +- reset-names: Must include the list of following reset names, + "wifi_cpu_init" + "wifi_radio_srif" + "wifi_radio_warm" + "wifi_radio_cold" + "wifi_core_warm" + "wifi_core_cold" +- clocks: List of clock specifiers, must contain an entry for each required + entry in clock-names. +- clock-names: Should contain the clock names "wifi_wcss_cmd", "wifi_wcss_ref", + "wifi_wcss_rtc". +- interrupts: List of interrupt lines. Must contain an entry + for each entry in the interrupt-names property. +- interrupt-names: Must include the entries for MSI interrupt + names ("msi0" to "msi15") and legacy interrupt + name ("legacy"), +- qcom,msi_addr: MSI interrupt address. +- qcom,msi_base: Base value to add before writing MSI data into + MSI address register. - qcom,ath10k-calibration-data : calibration data as an array, the length can vary between hw versions +Example (to supply the calibration data alone): -Example: +In this example, the node is defined as child node of the PCI controller. pci { pcie@0 { @@ -28,3 +57,53 @@ pci { }; }; }; + +Example (to supply ipq4019 SoC wifi block details): + +wifi0: wifi@a000000 { + compatible = "qcom,ipq4019-wifi"; + reg = <0xa000000 0x200000>; + resets = <&gcc WIFI0_CPU_INIT_RESET>, + <&gcc WIFI0_RADIO_SRIF_RESET>, + <&gcc WIFI0_RADIO_WARM_RESET>, + <&gcc WIFI0_RADIO_COLD_RESET>, + <&gcc WIFI0_CORE_WARM_RESET>, + <&gcc WIFI0_CORE_COLD_RESET>; + reset-names = "wifi_cpu_init", + "wifi_radio_srif", + "wifi_radio_warm", + "wifi_radio_cold", + "wifi_core_warm", + "wifi_core_cold"; + clocks = <&gcc GCC_WCSS2G_CLK>, + <&gcc GCC_WCSS2G_REF_CLK>, + <&gcc GCC_WCSS2G_RTC_CLK>; + clock-names = "wifi_wcss_cmd", + "wifi_wcss_ref", + "wifi_wcss_rtc"; + interrupts = <0 0x20 0x1>, + <0 0x21 0x1>, + <0 0x22 0x1>, + <0 0x23 0x1>, + <0 0x24 0x1>, + <0 0x25 0x1>, + <0 0x26 0x1>, + <0 0x27 0x1>, + <0 0x28 0x1>, + <0 0x29 0x1>, + <0 0x2a 0x1>, + <0 0x2b 0x1>, + <0 0x2c 0x1>, + <0 0x2d 0x1>, + <0 0x2e 0x1>, + <0 0x2f 0x1>, + <0 0xa8 0x0>; + interrupt-names = "msi0", "msi1", "msi2", "msi3", + "msi4", "msi5", "msi6", "msi7", + "msi8", "msi9", "msi10", "msi11", + "msi12", "msi13", "msi14", "msi15", + "legacy"; + qcom,msi_addr = <0x0b006040>; + qcom,msi_base = <0x40>; + qcom,ath10k-calibration-data = [ 01 02 03 ... ]; +}; diff --git a/Documentation/devicetree/bindings/net/wireless/ti,wlcore,spi.txt b/Documentation/devicetree/bindings/net/wireless/ti,wlcore,spi.txt new file mode 100644 index 000000000000..9180724e182c --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/ti,wlcore,spi.txt @@ -0,0 +1,36 @@ +* Texas Instruments wl1271 wireless lan controller + +The wl1271 chip can be connected via SPI or via SDIO. This +document describes the binding for the SPI connected chip. + +Required properties: +- compatible : Should be "ti,wl1271" +- reg : Chip select address of device +- spi-max-frequency : Maximum SPI clocking speed of device in Hz +- ref-clock-frequency : Reference clock frequency +- interrupt-parent, interrupts : + Should contain parameters for 1 interrupt line. + Interrupt parameters: parent, line number, type. +- vwlan-supply : Point the node of the regulator that powers/enable the wl1271 chip + +Optional properties: +- clock-xtal : boolean, clock is generated from XTAL + +- Please consult Documentation/devicetree/bindings/spi/spi-bus.txt + for optional SPI connection related properties, + +Examples: + +&spi1 { + wl1271@1 { + compatible = "ti,wl1271"; + + reg = <1>; + spi-max-frequency = <48000000>; + clock-xtal; + ref-clock-frequency = <38400000>; + interrupt-parent = <&gpio3>; + interrupts = <8 IRQ_TYPE_LEVEL_HIGH>; + vwlan-supply = <&vwlan_fixed>; + }; +}; diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt new file mode 100644 index 000000000000..383d5889e95a --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -0,0 +1,20 @@ +Freescale i.MX6 On-Chip OTP Controller (OCOTP) device tree bindings + +This binding represents the on-chip eFuse OTP controller found on +i.MX6Q/D, i.MX6DL/S, i.MX6SL, and i.MX6SX SoCs. + +Required properties: +- compatible: should be one of + "fsl,imx6q-ocotp" (i.MX6Q/D/DL/S), + "fsl,imx6sl-ocotp" (i.MX6SL), or + "fsl,imx6sx-ocotp" (i.MX6SX), followed by "syscon". +- reg: Should contain the register base and length. +- clocks: Should contain a phandle pointing to the gated peripheral clock. + +Example: + + ocotp: ocotp@021bc000 { + compatible = "fsl,imx6q-ocotp", "syscon"; + reg = <0x021bc000 0x4000>; + clocks = <&clks IMX6QDL_CLK_IIM>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/lpc1857-eeprom.txt b/Documentation/devicetree/bindings/nvmem/lpc1857-eeprom.txt new file mode 100644 index 000000000000..809df68f6e14 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/lpc1857-eeprom.txt @@ -0,0 +1,28 @@ +* NXP LPC18xx EEPROM memory NVMEM driver + +Required properties: + - compatible: Should be "nxp,lpc1857-eeprom" + - reg: Must contain an entry with the physical base address and length + for each entry in reg-names. + - reg-names: Must include the following entries. + - reg: EEPROM registers. + - mem: EEPROM address space. + - clocks: Must contain an entry for each entry in clock-names. + - clock-names: Must include the following entries. + - eeprom: EEPROM operating clock. + - resets: Should contain a reference to the reset controller asserting + the EEPROM in reset. + - interrupts: Should contain EEPROM interrupt. + +Example: + + eeprom: eeprom@4000e000 { + compatible = "nxp,lpc1857-eeprom"; + reg = <0x4000e000 0x1000>, + <0x20040000 0x4000>; + reg-names = "reg", "mem"; + clocks = <&ccu1 CLK_CPU_EEPROM>; + clock-names = "eeprom"; + resets = <&rgu 27>; + interrupts = <4>; + }; diff --git a/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt new file mode 100644 index 000000000000..74cf52908a6c --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/mtk-efuse.txt @@ -0,0 +1,36 @@ += Mediatek MTK-EFUSE device tree bindings = + +This binding is intended to represent MTK-EFUSE which is found in most Mediatek SOCs. + +Required properties: +- compatible: should be "mediatek,mt8173-efuse" or "mediatek,efuse" +- reg: Should contain registers location and length + += Data cells = +Are child nodes of MTK-EFUSE, bindings of which as described in +bindings/nvmem/nvmem.txt + +Example: + + efuse: efuse@10206000 { + compatible = "mediatek,mt8173-efuse"; + reg = <0 0x10206000 0 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + + /* Data cells */ + thermal_calibration: calib@528 { + reg = <0x528 0xc>; + }; + }; + += Data consumers = +Are device nodes which consume nvmem data cells. + +For example: + + thermal { + ... + nvmem-cells = <&thermal_calibration>; + nvmem-cell-names = "calibration"; + }; diff --git a/Documentation/devicetree/bindings/nvmem/mxs-ocotp.txt b/Documentation/devicetree/bindings/nvmem/mxs-ocotp.txt new file mode 100644 index 000000000000..daebce9e6b07 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/mxs-ocotp.txt @@ -0,0 +1,25 @@ +On-Chip OTP Memory for Freescale i.MX23/i.MX28 + +Required properties : +- compatible : + - "fsl,imx23-ocotp" for i.MX23 + - "fsl,imx28-ocotp" for i.MX28 +- #address-cells : Should be 1 +- #size-cells : Should be 1 +- reg : Address and length of OTP controller registers +- clocks : Should contain a reference to the hbus clock + += Data cells = +Are child nodes of mxs-ocotp, bindings of which as described in +bindings/nvmem/nvmem.txt + +Example for i.MX28: + + ocotp: ocotp@8002c000 { + compatible = "fsl,imx28-ocotp", "fsl,ocotp"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x8002c000 0x2000>; + clocks = <&clks 25>; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt new file mode 100644 index 000000000000..8f86ab3b1046 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt @@ -0,0 +1,38 @@ += Rockchip eFuse device tree bindings = + +Required properties: +- compatible: Should be "rockchip,rockchip-efuse" +- reg: Should contain the registers location and exact eFuse size +- clocks: Should be the clock id of eFuse +- clock-names: Should be "pclk_efuse" + += Data cells = +Are child nodes of eFuse, bindings of which as described in +bindings/nvmem/nvmem.txt + +Example: + + efuse: efuse@ffb40000 { + compatible = "rockchip,rockchip-efuse"; + reg = <0xffb40000 0x20>; + #address-cells = <1>; + #size-cells = <1>; + clocks = <&cru PCLK_EFUSE256>; + clock-names = "pclk_efuse"; + + /* Data cells */ + cpu_leakage: cpu_leakage { + reg = <0x17 0x1>; + }; + }; + += Data consumers = +Are device nodes which consume nvmem data cells. + +Example: + + cpu_leakage { + ... + nvmem-cells = <&cpu_leakage>; + nvmem-cell-names = "cpu_leakage"; + }; diff --git a/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt b/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt new file mode 100644 index 000000000000..56ed481c3e26 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/vf610-ocotp.txt @@ -0,0 +1,19 @@ +On-Chip OTP Memory for Freescale Vybrid + +Required Properties: + compatible: + - "fsl,vf610-ocotp" for VF5xx/VF6xx + #address-cells : Should be 1 + #size-cells : Should be 1 + reg : Address and length of OTP controller and fuse map registers + clocks : ipg clock we associate with the OCOTP peripheral + +Example for Vybrid VF5xx/VF6xx: + + ocotp: ocotp@400a5000 { + compatible = "fsl,vf610-ocotp"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0x400a5000 0xCF0>; + clocks = <&clks VF610_CLK_OCOTP>; + }; diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index 0cb44dc21f97..601256fe8c0d 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -45,21 +45,10 @@ Devices supporting OPPs must set their "operating-points-v2" property with phandle to a OPP table in their DT node. The OPP core will use this phandle to find the operating points for the device. -Devices may want to choose OPP tables at runtime and so can provide a list of -phandles here. But only *one* of them should be chosen at runtime. This must be -accompanied by a corresponding "operating-points-names" property, to uniquely -identify the OPP tables. - If required, this can be extended for SoC vendor specfic bindings. Such bindings should be documented as Documentation/devicetree/bindings/power/<vendor>-opp.txt and should have a compatible description like: "operating-points-v2-<vendor>". -Optional properties: -- operating-points-names: Names of OPP tables (required if multiple OPP - tables are present), to uniquely identify them. The same list must be present - for all the CPUs which are sharing clock/voltage rails and hence the OPP - tables. - * OPP Table Node This describes the OPPs belonging to a device. This node can have following @@ -100,6 +89,14 @@ Optional properties: Entries for multiple regulators must be present in the same order as regulators are specified in device's DT node. +- opp-microvolt-<name>: Named opp-microvolt property. This is exactly similar to + the above opp-microvolt property, but allows multiple voltage ranges to be + provided for the same OPP. At runtime, the platform can pick a <name> and + matching opp-microvolt-<name> property will be enabled for all OPPs. If the + platform doesn't pick a specific <name> or the <name> doesn't match with any + opp-microvolt-<name> properties, then opp-microvolt property shall be used, if + present. + - opp-microamp: The maximum current drawn by the device in microamperes considering system specific parameters (such as transients, process, aging, maximum operating temperature range etc.) as necessary. This may be used to @@ -112,6 +109,9 @@ Optional properties: for few regulators, then this should be marked as zero for them. If it isn't required for any regulator, then this property need not be present. +- opp-microamp-<name>: Named opp-microamp property. Similar to + opp-microvolt-<name> property, but for microamp instead. + - clock-latency-ns: Specifies the maximum possible transition latency (in nanoseconds) for switching to this OPP from any other OPP. @@ -123,6 +123,26 @@ Optional properties: - opp-suspend: Marks the OPP to be used during device suspend. Only one OPP in the table should have this. +- opp-supported-hw: This enables us to select only a subset of OPPs from the + larger OPP table, based on what version of the hardware we are running on. We + still can't have multiple nodes with the same opp-hz value in OPP table. + + It's an user defined array containing a hierarchy of hardware version numbers, + supported by the OPP. For example: a platform with hierarchy of three levels + of versions (A, B and C), this field should be like <X Y Z>, where X + corresponds to Version hierarchy A, Y corresponds to version hierarchy B and Z + corresponds to version hierarchy C. + + Each level of hierarchy is represented by a 32 bit value, and so there can be + only 32 different supported version per hierarchy. i.e. 1 bit per version. A + value of 0xFFFFFFFF will enable the OPP for all versions for that hierarchy + level. And a value of 0x00000000 will disable the OPP completely, and so we + never want that to happen. + + If 32 values aren't sufficient for a version hierarchy, than that version + hierarchy can be contained in multiple 32 bit values. i.e. <X Y Z1 Z2> in the + above example, Z1 & Z2 refer to the version hierarchy Z. + - status: Marks the node enabled/disabled. Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together. @@ -157,20 +177,20 @@ Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together. compatible = "operating-points-v2"; opp-shared; - opp00 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; opp-microvolt = <970000 975000 985000>; opp-microamp = <70000>; clock-latency-ns = <300000>; opp-suspend; }; - opp01 { + opp@1100000000 { opp-hz = /bits/ 64 <1100000000>; opp-microvolt = <980000 1000000 1010000>; opp-microamp = <80000>; clock-latency-ns = <310000>; }; - opp02 { + opp@1200000000 { opp-hz = /bits/ 64 <1200000000>; opp-microvolt = <1025000>; clock-latency-ns = <290000>; @@ -236,20 +256,20 @@ independently. * independently. */ - opp00 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; opp-microvolt = <970000 975000 985000>; opp-microamp = <70000>; clock-latency-ns = <300000>; opp-suspend; }; - opp01 { + opp@1100000000 { opp-hz = /bits/ 64 <1100000000>; opp-microvolt = <980000 1000000 1010000>; opp-microamp = <80000>; clock-latency-ns = <310000>; }; - opp02 { + opp@1200000000 { opp-hz = /bits/ 64 <1200000000>; opp-microvolt = <1025000>; opp-microamp = <90000; @@ -312,20 +332,20 @@ DVFS state together. compatible = "operating-points-v2"; opp-shared; - opp00 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; opp-microvolt = <970000 975000 985000>; opp-microamp = <70000>; clock-latency-ns = <300000>; opp-suspend; }; - opp01 { + opp@1100000000 { opp-hz = /bits/ 64 <1100000000>; opp-microvolt = <980000 1000000 1010000>; opp-microamp = <80000>; clock-latency-ns = <310000>; }; - opp02 { + opp@1200000000 { opp-hz = /bits/ 64 <1200000000>; opp-microvolt = <1025000>; opp-microamp = <90000>; @@ -338,20 +358,20 @@ DVFS state together. compatible = "operating-points-v2"; opp-shared; - opp10 { + opp@1300000000 { opp-hz = /bits/ 64 <1300000000>; opp-microvolt = <1045000 1050000 1055000>; opp-microamp = <95000>; clock-latency-ns = <400000>; opp-suspend; }; - opp11 { + opp@1400000000 { opp-hz = /bits/ 64 <1400000000>; opp-microvolt = <1075000>; opp-microamp = <100000>; clock-latency-ns = <400000>; }; - opp12 { + opp@1500000000 { opp-hz = /bits/ 64 <1500000000>; opp-microvolt = <1010000 1100000 1110000>; opp-microamp = <95000>; @@ -378,7 +398,7 @@ Example 4: Handling multiple regulators compatible = "operating-points-v2"; opp-shared; - opp00 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; opp-microvolt = <970000>, /* Supply 0 */ <960000>, /* Supply 1 */ @@ -391,7 +411,7 @@ Example 4: Handling multiple regulators /* OR */ - opp00 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; opp-microvolt = <970000 975000 985000>, /* Supply 0 */ <960000 965000 975000>, /* Supply 1 */ @@ -404,7 +424,7 @@ Example 4: Handling multiple regulators /* OR */ - opp00 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; opp-microvolt = <970000 975000 985000>, /* Supply 0 */ <960000 965000 975000>, /* Supply 1 */ @@ -417,7 +437,8 @@ Example 4: Handling multiple regulators }; }; -Example 5: Multiple OPP tables +Example 5: opp-supported-hw +(example: three level hierarchy of versions: cuts, substrate and process) / { cpus { @@ -426,40 +447,73 @@ Example 5: Multiple OPP tables ... cpu-supply = <&cpu_supply> - operating-points-v2 = <&cpu0_opp_table_slow>, <&cpu0_opp_table_fast>; - operating-points-names = "slow", "fast"; + operating-points-v2 = <&cpu0_opp_table_slow>; }; }; - cpu0_opp_table_slow: opp_table_slow { + opp_table { compatible = "operating-points-v2"; status = "okay"; opp-shared; - opp00 { + opp@600000000 { + /* + * Supports all substrate and process versions for 0xF + * cuts, i.e. only first four cuts. + */ + opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF> opp-hz = /bits/ 64 <600000000>; + opp-microvolt = <900000 915000 925000>; ... }; - opp01 { + opp@800000000 { + /* + * Supports: + * - cuts: only one, 6th cut (represented by 6th bit). + * - substrate: supports 16 different substrate versions + * - process: supports 9 different process versions + */ + opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0> opp-hz = /bits/ 64 <800000000>; + opp-microvolt = <900000 915000 925000>; ... }; }; +}; + +Example 6: opp-microvolt-<name>, opp-microamp-<name>: +(example: device with two possible microvolt ranges: slow and fast) - cpu0_opp_table_fast: opp_table_fast { +/ { + cpus { + cpu@0 { + compatible = "arm,cortex-a7"; + ... + + operating-points-v2 = <&cpu0_opp_table>; + }; + }; + + cpu0_opp_table: opp_table0 { compatible = "operating-points-v2"; - status = "okay"; opp-shared; - opp10 { + opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - ... + opp-microvolt-slow = <900000 915000 925000>; + opp-microvolt-fast = <970000 975000 985000>; + opp-microamp-slow = <70000>; + opp-microamp-fast = <71000>; }; - opp11 { - opp-hz = /bits/ 64 <1100000000>; - ... + opp@1200000000 { + opp-hz = /bits/ 64 <1200000000>; + opp-microvolt-slow = <900000 915000 925000>, /* Supply vcc0 */ + <910000 925000 935000>; /* Supply vcc1 */ + opp-microvolt-fast = <970000 975000 985000>, /* Supply vcc0 */ + <960000 965000 975000>; /* Supply vcc1 */ + opp-microamp = <70000>; /* Will be used for both slow/fast */ }; }; }; diff --git a/Documentation/devicetree/bindings/pci/altera-pcie-msi.txt b/Documentation/devicetree/bindings/pci/altera-pcie-msi.txt new file mode 100644 index 000000000000..09cd3bc4d038 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/altera-pcie-msi.txt @@ -0,0 +1,28 @@ +* Altera PCIe MSI controller + +Required properties: +- compatible: should contain "altr,msi-1.0" +- reg: specifies the physical base address of the controller and + the length of the memory mapped region. +- reg-names: must include the following entries: + "csr": CSR registers + "vector_slave": vectors slave port region +- interrupt-parent: interrupt source phandle. +- interrupts: specifies the interrupt source of the parent interrupt + controller. The format of the interrupt specifier depends on the + parent interrupt controller. +- num-vectors: number of vectors, range 1 to 32. +- msi-controller: indicates that this is MSI controller node + + +Example +msi0: msi@0xFF200000 { + compatible = "altr,msi-1.0"; + reg = <0xFF200000 0x00000010 + 0xFF200010 0x00000080>; + reg-names = "csr", "vector_slave"; + interrupt-parent = <&hps_0_arm_gic_0>; + interrupts = <0 42 4>; + msi-controller; + num-vectors = <32>; +}; diff --git a/Documentation/devicetree/bindings/pci/altera-pcie.txt b/Documentation/devicetree/bindings/pci/altera-pcie.txt new file mode 100644 index 000000000000..2951a6a50704 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/altera-pcie.txt @@ -0,0 +1,49 @@ +* Altera PCIe controller + +Required properties: +- compatible : should contain "altr,pcie-root-port-1.0" +- reg: a list of physical base address and length for TXS and CRA. +- reg-names: must include the following entries: + "Txs": TX slave port region + "Cra": Control register access region +- interrupt-parent: interrupt source phandle. +- interrupts: specifies the interrupt source of the parent interrupt controller. + The format of the interrupt specifier depends on the parent interrupt + controller. +- device_type: must be "pci" +- #address-cells: set to <3> +- #size-cells: set to <2> +- #interrupt-cells: set to <1> +- ranges: describes the translation of addresses for root ports and standard + PCI regions. +- interrupt-map-mask and interrupt-map: standard PCI properties to define the + mapping of the PCIe interface to interrupt numbers. + +Optional properties: +- msi-parent: Link to the hardware entity that serves as the MSI controller for this PCIe + controller. +- bus-range: PCI bus numbers covered + +Example + pcie_0: pcie@0xc00000000 { + compatible = "altr,pcie-root-port-1.0"; + reg = <0xc0000000 0x20000000>, + <0xff220000 0x00004000>; + reg-names = "Txs", "Cra"; + interrupt-parent = <&hps_0_arm_gic_0>; + interrupts = <0 40 4>; + interrupt-controller; + #interrupt-cells = <1>; + bus-range = <0x0 0xFF>; + device_type = "pci"; + msi-parent = <&msi_to_gic_gen_0>; + #address-cells = <3>; + #size-cells = <2>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_0 1>, + <0 0 0 2 &pcie_0 2>, + <0 0 0 3 &pcie_0 3>, + <0 0 0 4 &pcie_0 4>; + ranges = <0x82000000 0x00000000 0x00000000 0xc0000000 0x00000000 0x10000000 + 0x82000000 0x00000000 0x10000000 0xd0000000 0x00000000 0x10000000>; + }; diff --git a/Documentation/devicetree/bindings/pci/arm,juno-r1-pcie.txt b/Documentation/devicetree/bindings/pci/arm,juno-r1-pcie.txt new file mode 100644 index 000000000000..f7514c170a32 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/arm,juno-r1-pcie.txt @@ -0,0 +1,10 @@ +* ARM Juno R1 PCIe interface + +This PCIe host controller is based on PLDA XpressRICH3-AXI IP +and thus inherits all the common properties defined in plda,xpressrich3-axi.txt +as well as the base properties defined in host-generic-pci.txt. + +Required properties: + - compatible: "arm,juno-r1-pcie" + - dma-coherent: The host controller bridges the AXI transactions into PCIe bus + in a manner that makes the DMA operations to appear coherent to the CPUs. diff --git a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt index f7ce50e38ed4..01b88f4e0d5b 100644 --- a/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt +++ b/Documentation/devicetree/bindings/pci/brcm,iproc-pcie.txt @@ -1,7 +1,10 @@ * Broadcom iProc PCIe controller with the platform bus interface Required properties: -- compatible: Must be "brcm,iproc-pcie" +- compatible: Must be "brcm,iproc-pcie" for PAXB, or "brcm,iproc-pcie-paxc" + for PAXC. PAXB-based root complex is used for external endpoint devices. + PAXC-based root complex is connected to emulated endpoint devices + internal to the ASIC - reg: base address and length of the PCIe controller I/O register space - #interrupt-cells: set to <1> - interrupt-map-mask and interrupt-map, standard PCI properties to define the @@ -17,6 +20,43 @@ Optional properties: - phys: phandle of the PCIe PHY device - phy-names: must be "pcie-phy" +- brcm,pcie-ob: Some iProc SoCs do not have the outbound address mapping done +by the ASIC after power on reset. In this case, SW needs to configure it + +If the brcm,pcie-ob property is present, the following properties become +effective: + +Required: +- brcm,pcie-ob-axi-offset: The offset from the AXI address to the internal +address used by the iProc PCIe core (not the PCIe address) +- brcm,pcie-ob-window-size: The outbound address mapping window size (in MB) + +Optional: +- brcm,pcie-ob-oarr-size: Some iProc SoCs need the OARR size bit to be set to +increase the outbound window size + +MSI support (optional): + +For older platforms without MSI integrated in the GIC, iProc PCIe core provides +an event queue based MSI support. The iProc MSI uses host memories to store +MSI posted writes in the event queues + +- msi-parent: Link to the device node of the MSI controller. On newer iProc +platforms, the MSI controller may be gicv2m or gicv3-its. On older iProc +platforms without MSI support in its interrupt controller, one may use the +event queue based MSI support integrated within the iProc PCIe core. + +When the iProc event queue based MSI is used, one needs to define the +following properties in the MSI device node: +- compatible: Must be "brcm,iproc-msi" +- msi-controller: claims itself as an MSI controller +- interrupt-parent: Link to its parent interrupt device +- interrupts: List of interrupt IDs from its parent interrupt device + +Optional properties: +- brcm,pcie-msi-inten: Needs to be present for some older iProc platforms that +require the interrupt enable registers to be set explicitly to enable MSI + Example: pcie0: pcie@18012000 { compatible = "brcm,iproc-pcie"; @@ -38,6 +78,24 @@ Example: phys = <&phy 0 5>; phy-names = "pcie-phy"; + + brcm,pcie-ob; + brcm,pcie-ob-oarr-size; + brcm,pcie-ob-axi-offset = <0x00000000>; + brcm,pcie-ob-window-size = <256>; + + msi-parent = <&msi0>; + + /* iProc event queue based MSI */ + msi0: msi@18012000 { + compatible = "brcm,iproc-msi"; + msi-controller; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 96 IRQ_TYPE_NONE>, + <GIC_SPI 97 IRQ_TYPE_NONE>, + <GIC_SPI 98 IRQ_TYPE_NONE>, + <GIC_SPI 99 IRQ_TYPE_NONE>, + }; }; pcie1: pcie@18013000 { diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt index 9f4faa8e8d00..64f2fff12128 100644 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt @@ -15,14 +15,33 @@ Required properties: to define the mapping of the PCIe interface to interrupt numbers. - num-lanes: number of lanes to use -- 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: - - "pcie" - - "pcie_bus" Optional properties: +- num-lanes: number of lanes to use (this property should be specified unless + the link is brought already up in BIOS) - reset-gpio: gpio pin number of power good signal - bus-range: PCI bus numbers covered (it is recommended for new devicetrees to specify this property, to keep backwards compatibility a range of 0x00-0xff is assumed if not present) +- 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: + - "pcie" + - "pcie_bus" + +Example configuration: + + pcie: pcie@0xdffff000 { + compatible = "snps,dw-pcie"; + reg = <0xdffff000 0x1000>, /* Controller registers */ + <0xd0000000 0x2000>; /* PCI config space */ + reg-names = "ctrlreg", "config"; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x81000000 0 0x00000000 0xde000000 0 0x00010000 + 0x82000000 0 0xd0400000 0xd0400000 0 0x0d000000>; + interrupts = <25>, <24>; + #interrupt-cells = <1>; + num-lanes = <1>; + }; diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index 6fbba53a309b..3be80c68941a 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -13,6 +13,13 @@ Required properties: - clock-names: Must include the following additional entries: - "pcie_phy" +Optional properties: +- fsl,tx-deemph-gen1: Gen1 De-emphasis value. Default: 0 +- fsl,tx-deemph-gen2-3p5db: Gen2 (3.5db) De-emphasis value. Default: 0 +- fsl,tx-deemph-gen2-6db: Gen2 (6db) De-emphasis value. Default: 20 +- fsl,tx-swing-full: Gen2 TX SWING FULL value. Default: 127 +- fsl,tx-swing-low: TX launch amplitude swing_low value. Default: 127 + Example: pcie@0x01000000 { diff --git a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt new file mode 100644 index 000000000000..b721beacfe4d --- /dev/null +++ b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt @@ -0,0 +1,44 @@ +HiSilicon Hip05 and Hip06 PCIe host bridge DT description + +HiSilicon PCIe host controller is based on Designware PCI core. +It shares common functions with PCIe Designware core driver and inherits +common properties defined in +Documentation/devicetree/bindings/pci/designware-pci.txt. + +Additional properties are described here: + +Required properties +- compatible: Should contain "hisilicon,hip05-pcie" or "hisilicon,hip06-pcie". +- reg: Should contain rc_dbi, config registers location and length. +- reg-names: Must include the following entries: + "rc_dbi": controller configuration registers; + "config": PCIe configuration space registers. +- msi-parent: Should be its_pcie which is an ITS receiving MSI interrupts. +- port-id: Should be 0, 1, 2 or 3. + +Optional properties: +- status: Either "ok" or "disabled". +- dma-coherent: Present if DMA operations are coherent. + +Hip05 Example (note that Hip06 is the same except compatible): + pcie@0xb0080000 { + compatible = "hisilicon,hip05-pcie", "snps,dw-pcie"; + reg = <0 0xb0080000 0 0x10000>, <0x220 0x00000000 0 0x2000>; + reg-names = "rc_dbi", "config"; + bus-range = <0 15>; + msi-parent = <&its_pcie>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + dma-coherent; + ranges = <0x82000000 0 0x00000000 0x220 0x00000000 0 0x10000000>; + num-lanes = <8>; + port-id = <1>; + #interrupts-cells = <1>; + interrupts-map-mask = <0xf800 0 0 7>; + interrupts-map = <0x0 0 0 1 &mbigen_pcie 1 10 + 0x0 0 0 2 &mbigen_pcie 2 11 + 0x0 0 0 3 &mbigen_pcie 3 12 + 0x0 0 0 4 &mbigen_pcie 4 13>; + status = "ok"; + }; diff --git a/Documentation/devicetree/bindings/pci/host-generic-pci.txt b/Documentation/devicetree/bindings/pci/host-generic-pci.txt index cf3e205e0b7e..3f1d3fca62bb 100644 --- a/Documentation/devicetree/bindings/pci/host-generic-pci.txt +++ b/Documentation/devicetree/bindings/pci/host-generic-pci.txt @@ -34,8 +34,9 @@ Properties of the host controller node: - #size-cells : Must be 2. - reg : The Configuration Space base address and size, as accessed - from the parent bus. - + from the parent bus. The base address corresponds to + the first bus in the "bus-range" property. If no + "bus-range" is specified, this will be bus 0 (the default). Properties of the /chosen node: diff --git a/Documentation/devicetree/bindings/pci/layerscape-pci.txt b/Documentation/devicetree/bindings/pci/layerscape-pci.txt index 6286f049bf18..e3767857d30d 100644 --- a/Documentation/devicetree/bindings/pci/layerscape-pci.txt +++ b/Documentation/devicetree/bindings/pci/layerscape-pci.txt @@ -1,10 +1,20 @@ Freescale Layerscape PCIe controller -This PCIe host controller is based on the Synopsis Designware PCIe IP +This PCIe host controller is based on the Synopsys DesignWare PCIe IP and thus inherits all the common properties defined in designware-pcie.txt. +This controller derives its clocks from the Reset Configuration Word (RCW) +which is used to describe the PLL settings at the time of chip-reset. + +Also as per the available Reference Manuals, there is no specific 'version' +register available in the Freescale PCIe controller register set, +which can allow determining the underlying DesignWare PCIe controller version +information. + Required properties: -- compatible: should contain the platform identifier such as "fsl,ls1021a-pcie" +- compatible: should contain the platform identifier such as: + "fsl,ls1021a-pcie", "snps,dw-pcie" + "fsl,ls2080a-pcie", "snps,dw-pcie" - reg: base addresses and lengths of the PCIe controller - interrupts: A list of interrupt outputs of the controller. Must contain an entry for each entry in the interrupt-names property. diff --git a/Documentation/devicetree/bindings/pci/pci-msi.txt b/Documentation/devicetree/bindings/pci/pci-msi.txt new file mode 100644 index 000000000000..9b3cc817d181 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/pci-msi.txt @@ -0,0 +1,220 @@ +This document describes the generic device tree binding for describing the +relationship between PCI devices and MSI controllers. + +Each PCI device under a root complex is uniquely identified by its Requester ID +(AKA RID). A Requester ID is a triplet of a Bus number, Device number, and +Function number. + +For the purpose of this document, when treated as a numeric value, a RID is +formatted such that: + +* Bits [15:8] are the Bus number. +* Bits [7:3] are the Device number. +* Bits [2:0] are the Function number. +* Any other bits required for padding must be zero. + +MSIs may be distinguished in part through the use of sideband data accompanying +writes. In the case of PCI devices, this sideband data may be derived from the +Requester ID. A mechanism is required to associate a device with both the MSI +controllers it can address, and the sideband data that will be associated with +its writes to those controllers. + +For generic MSI bindings, see +Documentation/devicetree/bindings/interrupt-controller/msi.txt. + + +PCI root complex +================ + +Optional properties +------------------- + +- msi-map: Maps a Requester ID to an MSI controller and associated + msi-specifier data. The property is an arbitrary number of tuples of + (rid-base,msi-controller,msi-base,length), where: + + * rid-base is a single cell describing the first RID matched by the entry. + + * msi-controller is a single phandle to an MSI controller + + * msi-base is an msi-specifier describing the msi-specifier produced for the + first RID matched by the entry. + + * length is a single cell describing how many consecutive RIDs are matched + following the rid-base. + + Any RID r in the interval [rid-base, rid-base + length) is associated with + the listed msi-controller, with the msi-specifier (r - rid-base + msi-base). + +- msi-map-mask: A mask to be applied to each Requester ID prior to being mapped + to an msi-specifier per the msi-map property. + +- msi-parent: Describes the MSI parent of the root complex itself. Where + the root complex and MSI controller do not pass sideband data with MSI + writes, this property may be used to describe the MSI controller(s) + used by PCI devices under the root complex, if defined as such in the + binding for the root complex. + + +Example (1) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + msi: msi-controller@a { + reg = <0xa 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the MSI controller is + * the RID, identity-mapped. + */ + msi-map = <0x0 &msi_a 0x0 0x10000>, + }; +}; + + +Example (2) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + msi: msi-controller@a { + reg = <0xa 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the MSI controller is + * the RID, masked to only the device and function bits. + */ + msi-map = <0x0 &msi_a 0x0 0x100>, + msi-map-mask = <0xff> + }; +}; + + +Example (3) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + msi: msi-controller@a { + reg = <0xa 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the MSI controller is + * the RID, but the high bit of the bus number is + * ignored. + */ + msi-map = <0x0000 &msi 0x0000 0x8000>, + <0x8000 &msi 0x0000 0x8000>; + }; +}; + + +Example (4) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + msi: msi-controller@a { + reg = <0xa 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the MSI controller is + * the RID, but the high bit of the bus number is + * negated. + */ + msi-map = <0x0000 &msi 0x8000 0x8000>, + <0x8000 &msi 0x0000 0x8000>; + }; +}; + + +Example (5) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + msi_a: msi-controller@a { + reg = <0xa 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + msi_b: msi-controller@b { + reg = <0xb 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + msi_c: msi-controller@c { + reg = <0xc 0x1>; + compatible = "vendor,some-controller"; + msi-controller; + #msi-cells = <1>; + }; + + pci: pci@c { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to MSI controller a is the + * RID, but the high bit of the bus number is negated. + * The sideband data provided to MSI controller b is the + * RID, identity-mapped. + * MSI controller c is not addressable. + */ + msi-map = <0x0000 &msi_a 0x8000 0x08000>, + <0x8000 &msi_a 0x0000 0x08000>, + <0x0000 &msi_b 0x0000 0x10000>; + }; +}; diff --git a/Documentation/devicetree/bindings/pci/pci-rcar-gen2.txt b/Documentation/devicetree/bindings/pci/pci-rcar-gen2.txt index 7fab84b33531..07a75094c5a8 100644 --- a/Documentation/devicetree/bindings/pci/pci-rcar-gen2.txt +++ b/Documentation/devicetree/bindings/pci/pci-rcar-gen2.txt @@ -8,7 +8,15 @@ OHCI and EHCI controllers. Required properties: - compatible: "renesas,pci-r8a7790" for the R8A7790 SoC; "renesas,pci-r8a7791" for the R8A7791 SoC; - "renesas,pci-r8a7794" for the R8A7794 SoC. + "renesas,pci-r8a7793" for the R8A7793 SoC; + "renesas,pci-r8a7794" for the R8A7794 SoC; + "renesas,pci-rcar-gen2" for a generic R-Car Gen2 compatible device + + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first + followed by the generic version. + - reg: A list of physical regions to access the device: the first is the operational registers for the OHCI/EHCI controllers and the second is for the bridge configuration and control registers. @@ -24,10 +32,15 @@ Required properties: - interrupt-map-mask: standard property that helps to define the interrupt mapping. +Optional properties: +- dma-ranges: a single range for the inbound memory region. If not supplied, + defaults to 1GiB at 0x40000000. Note there are hardware restrictions on the + allowed combinations of address and size. + Example SoC configuration: pci0: pci@ee090000 { - compatible = "renesas,pci-r8a7790"; + compatible = "renesas,pci-r8a7790", "renesas,pci-rcar-gen2"; clocks = <&mstp7_clks R8A7790_CLK_EHCI>; reg = <0x0 0xee090000 0x0 0xc00>, <0x0 0xee080000 0x0 0x1100>; @@ -38,6 +51,7 @@ Example SoC configuration: #address-cells = <3>; #size-cells = <2>; #interrupt-cells = <1>; + dma-ranges = <0x42000000 0 0x40000000 0 0x40000000 0 0x40000000>; interrupt-map-mask = <0xff00 0 0 0x7>; interrupt-map = <0x0000 0 0 1 &gic 0 108 IRQ_TYPE_LEVEL_HIGH 0x0800 0 0 1 &gic 0 108 IRQ_TYPE_LEVEL_HIGH diff --git a/Documentation/devicetree/bindings/pci/pci-thunder-ecam.txt b/Documentation/devicetree/bindings/pci/pci-thunder-ecam.txt new file mode 100644 index 000000000000..f478874b79ce --- /dev/null +++ b/Documentation/devicetree/bindings/pci/pci-thunder-ecam.txt @@ -0,0 +1,30 @@ +* ThunderX PCI host controller for pass-1.x silicon + +Firmware-initialized PCI host controller to on-chip devices found on +some Cavium ThunderX processors. These devices have ECAM-based config +access, but the BARs are all at fixed addresses. We handle the fixed +addresses by synthesizing Enhanced Allocation (EA) capabilities for +these devices. + +The properties and their meanings are identical to those described in +host-generic-pci.txt except as listed below. + +Properties of the host controller node that differ from +host-generic-pci.txt: + +- compatible : Must be "cavium,pci-host-thunder-ecam" + +Example: + + pcie@84b000000000 { + compatible = "cavium,pci-host-thunder-ecam"; + device_type = "pci"; + msi-parent = <&its>; + msi-map = <0 &its 0x30000 0x10000>; + bus-range = <0 31>; + #size-cells = <2>; + #address-cells = <3>; + #stream-id-cells = <1>; + reg = <0x84b0 0x00000000 0 0x02000000>; /* Configuration space */ + ranges = <0x03000000 0x8180 0x00000000 0x8180 0x00000000 0x80 0x00000000>; /* mem ranges */ + }; diff --git a/Documentation/devicetree/bindings/pci/pci-thunder-pem.txt b/Documentation/devicetree/bindings/pci/pci-thunder-pem.txt new file mode 100644 index 000000000000..f131faea3b7c --- /dev/null +++ b/Documentation/devicetree/bindings/pci/pci-thunder-pem.txt @@ -0,0 +1,43 @@ +* ThunderX PEM PCIe host controller + +Firmware-initialized PCI host controller found on some Cavium +ThunderX processors. + +The properties and their meanings are identical to those described in +host-generic-pci.txt except as listed below. + +Properties of the host controller node that differ from +host-generic-pci.txt: + +- compatible : Must be "cavium,pci-host-thunder-pem" + +- reg : Two entries: First the configuration space for down + stream devices base address and size, as accessed + from the parent bus. Second, the register bank of + the PEM device PCIe bridge. + +Example: + + pci@87e0,c2000000 { + compatible = "cavium,pci-host-thunder-pem"; + device_type = "pci"; + msi-parent = <&its>; + msi-map = <0 &its 0x10000 0x10000>; + bus-range = <0x8f 0xc7>; + #size-cells = <2>; + #address-cells = <3>; + + reg = <0x8880 0x8f000000 0x0 0x39000000>, /* Configuration space */ + <0x87e0 0xc2000000 0x0 0x00010000>; /* PEM space */ + ranges = <0x01000000 0x00 0x00020000 0x88b0 0x00020000 0x00 0x00010000>, /* I/O */ + <0x03000000 0x00 0x10000000 0x8890 0x10000000 0x0f 0xf0000000>, /* mem64 */ + <0x43000000 0x10 0x00000000 0x88a0 0x00000000 0x10 0x00000000>, /* mem64-pref */ + <0x03000000 0x87e0 0xc2f00000 0x87e0 0xc2000000 0x00 0x00100000>; /* mem64 PEM BAR4 */ + + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &gic0 0 0 0 24 4>, /* INTA */ + <0 0 0 2 &gic0 0 0 0 25 4>, /* INTB */ + <0 0 0 3 &gic0 0 0 0 26 4>, /* INTC */ + <0 0 0 4 &gic0 0 0 0 27 4>; /* INTD */ + }; diff --git a/Documentation/devicetree/bindings/pci/pci.txt b/Documentation/devicetree/bindings/pci/pci.txt index f8fbe9af7b2f..08dcfad09f8d 100644 --- a/Documentation/devicetree/bindings/pci/pci.txt +++ b/Documentation/devicetree/bindings/pci/pci.txt @@ -1,12 +1,12 @@ PCI bus bridges have standardized Device Tree bindings: PCI Bus Binding to: IEEE Std 1275-1994 -http://www.openfirmware.org/ofwg/bindings/pci/pci2_1.pdf +http://www.firmware.org/1275/bindings/pci/pci2_1.pdf And for the interrupt mapping part: Open Firmware Recommended Practice: Interrupt Mapping -http://www.openfirmware.org/1275/practice/imap/imap0_9d.pdf +http://www.firmware.org/1275/practice/imap/imap0_9d.pdf Additionally to the properties specified in the above standards a host bridge driver implementation may support the following properties: diff --git a/Documentation/devicetree/bindings/pci/plda,xpressrich3-axi.txt b/Documentation/devicetree/bindings/pci/plda,xpressrich3-axi.txt new file mode 100644 index 000000000000..f3f75bfb42bc --- /dev/null +++ b/Documentation/devicetree/bindings/pci/plda,xpressrich3-axi.txt @@ -0,0 +1,12 @@ +* PLDA XpressRICH3-AXI host controller + +The PLDA XpressRICH3-AXI host controller can be configured in a manner that +makes it compliant with the SBSA[1] standard published by ARM Ltd. For those +scenarios, the host-generic-pci.txt bindings apply with the following additions +to the compatible property: + +Required properties: + - compatible: should contain "plda,xpressrich3-axi" to identify the IP used. + + +[1] http://infocenter.arm.com/help/topic/com.arm.doc.den0029a/ diff --git a/Documentation/devicetree/bindings/pci/qcom,pcie.txt b/Documentation/devicetree/bindings/pci/qcom,pcie.txt new file mode 100644 index 000000000000..4059a6f89bc1 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/qcom,pcie.txt @@ -0,0 +1,233 @@ +* Qualcomm PCI express root complex + +- compatible: + Usage: required + Value type: <stringlist> + Definition: Value should contain + - "qcom,pcie-ipq8064" for ipq8064 + - "qcom,pcie-apq8064" for apq8064 + - "qcom,pcie-apq8084" for apq8084 + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: Register ranges as listed in the reg-names property + +- reg-names: + Usage: required + Value type: <stringlist> + Definition: Must include the following entries + - "parf" Qualcomm specific registers + - "dbi" Designware PCIe registers + - "elbi" External local bus interface registers + - "config" PCIe configuration space + +- device_type: + Usage: required + Value type: <string> + Definition: Should be "pci". As specified in designware-pcie.txt + +- #address-cells: + Usage: required + Value type: <u32> + Definition: Should be 3. As specified in designware-pcie.txt + +- #size-cells: + Usage: required + Value type: <u32> + Definition: Should be 2. As specified in designware-pcie.txt + +- ranges: + Usage: required + Value type: <prop-encoded-array> + Definition: As specified in designware-pcie.txt + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: MSI interrupt + +- interrupt-names: + Usage: required + Value type: <stringlist> + Definition: Should contain "msi" + +- #interrupt-cells: + Usage: required + Value type: <u32> + Definition: Should be 1. As specified in designware-pcie.txt + +- interrupt-map-mask: + Usage: required + Value type: <prop-encoded-array> + Definition: As specified in designware-pcie.txt + +- interrupt-map: + Usage: required + Value type: <prop-encoded-array> + Definition: As specified in designware-pcie.txt + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: List of phandle and clock specifier pairs as listed + in clock-names property + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: Should contain the following entries + - "iface" Configuration AHB clock + +- clock-names: + Usage: required for ipq/apq8064 + Value type: <stringlist> + Definition: Should contain the following entries + - "core" Clocks the pcie hw block + - "phy" Clocks the pcie PHY block +- clock-names: + Usage: required for apq8084 + Value type: <stringlist> + Definition: Should contain the following entries + - "aux" Auxiliary (AUX) clock + - "bus_master" Master AXI clock + - "bus_slave" Slave AXI clock +- resets: + Usage: required + Value type: <prop-encoded-array> + Definition: List of phandle and reset specifier pairs as listed + in reset-names property + +- reset-names: + Usage: required for ipq/apq8064 + Value type: <stringlist> + Definition: Should contain the following entries + - "axi" AXI reset + - "ahb" AHB reset + - "por" POR reset + - "pci" PCI reset + - "phy" PHY reset + +- reset-names: + Usage: required for apq8084 + Value type: <stringlist> + Definition: Should contain the following entries + - "core" Core reset + +- power-domains: + Usage: required for apq8084 + Value type: <prop-encoded-array> + Definition: A phandle and power domain specifier pair to the + power domain which is responsible for collapsing + and restoring power to the peripheral + +- vdda-supply: + Usage: required + Value type: <phandle> + Definition: A phandle to the core analog power supply + +- vdda_phy-supply: + Usage: required for ipq/apq8064 + Value type: <phandle> + Definition: A phandle to the analog power supply for PHY + +- vdda_refclk-supply: + Usage: required for ipq/apq8064 + Value type: <phandle> + Definition: A phandle to the analog power supply for IC which generates + reference clock + +- phys: + Usage: required for apq8084 + Value type: <phandle> + Definition: List of phandle(s) as listed in phy-names property + +- phy-names: + Usage: required for apq8084 + Value type: <stringlist> + Definition: Should contain "pciephy" + +- <name>-gpios: + Usage: optional + Value type: <prop-encoded-array> + Definition: List of phandle and gpio specifier pairs. Should contain + - "perst-gpios" PCIe endpoint reset signal line + - "wake-gpios" PCIe endpoint wake signal line + +* Example for ipq/apq8064 + pcie@1b500000 { + compatible = "qcom,pcie-apq8064", "qcom,pcie-ipq8064", "snps,dw-pcie"; + reg = <0x1b500000 0x1000 + 0x1b502000 0x80 + 0x1b600000 0x100 + 0x0ff00000 0x100000>; + reg-names = "dbi", "elbi", "parf", "config"; + device_type = "pci"; + linux,pci-domain = <0>; + bus-range = <0x00 0xff>; + num-lanes = <1>; + #address-cells = <3>; + #size-cells = <2>; + ranges = <0x81000000 0 0 0x0fe00000 0 0x00100000 /* I/O */ + 0x82000000 0 0 0x08000000 0 0x07e00000>; /* memory */ + interrupts = <GIC_SPI 238 IRQ_TYPE_NONE>; + interrupt-names = "msi"; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0x7>; + interrupt-map = <0 0 0 1 &intc 0 36 IRQ_TYPE_LEVEL_HIGH>, /* int_a */ + <0 0 0 2 &intc 0 37 IRQ_TYPE_LEVEL_HIGH>, /* int_b */ + <0 0 0 3 &intc 0 38 IRQ_TYPE_LEVEL_HIGH>, /* int_c */ + <0 0 0 4 &intc 0 39 IRQ_TYPE_LEVEL_HIGH>; /* int_d */ + clocks = <&gcc PCIE_A_CLK>, + <&gcc PCIE_H_CLK>, + <&gcc PCIE_PHY_CLK>; + clock-names = "core", "iface", "phy"; + resets = <&gcc PCIE_ACLK_RESET>, + <&gcc PCIE_HCLK_RESET>, + <&gcc PCIE_POR_RESET>, + <&gcc PCIE_PCI_RESET>, + <&gcc PCIE_PHY_RESET>; + reset-names = "axi", "ahb", "por", "pci", "phy"; + pinctrl-0 = <&pcie_pins_default>; + pinctrl-names = "default"; + }; + +* Example for apq8084 + pcie0@fc520000 { + compatible = "qcom,pcie-apq8084", "snps,dw-pcie"; + reg = <0xfc520000 0x2000>, + <0xff000000 0x1000>, + <0xff001000 0x1000>, + <0xff002000 0x2000>; + reg-names = "parf", "dbi", "elbi", "config"; + device_type = "pci"; + linux,pci-domain = <0>; + bus-range = <0x00 0xff>; + num-lanes = <1>; + #address-cells = <3>; + #size-cells = <2>; + ranges = <0x81000000 0 0 0xff200000 0 0x00100000 /* I/O */ + 0x82000000 0 0x00300000 0xff300000 0 0x00d00000>; /* memory */ + interrupts = <GIC_SPI 243 IRQ_TYPE_NONE>; + interrupt-names = "msi"; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0x7>; + interrupt-map = <0 0 0 1 &intc 0 244 IRQ_TYPE_LEVEL_HIGH>, /* int_a */ + <0 0 0 2 &intc 0 245 IRQ_TYPE_LEVEL_HIGH>, /* int_b */ + <0 0 0 3 &intc 0 247 IRQ_TYPE_LEVEL_HIGH>, /* int_c */ + <0 0 0 4 &intc 0 248 IRQ_TYPE_LEVEL_HIGH>; /* int_d */ + clocks = <&gcc GCC_PCIE_0_CFG_AHB_CLK>, + <&gcc GCC_PCIE_0_MSTR_AXI_CLK>, + <&gcc GCC_PCIE_0_SLV_AXI_CLK>, + <&gcc GCC_PCIE_0_AUX_CLK>; + clock-names = "iface", "master_bus", "slave_bus", "aux"; + resets = <&gcc GCC_PCIE_0_BCR>; + reset-names = "core"; + power-domains = <&gcc PCIE0_GDSC>; + vdda-supply = <&pma8084_l3>; + phys = <&pciephy0>; + phy-names = "pciephy"; + perst-gpio = <&tlmm 70 GPIO_ACTIVE_LOW>; + pinctrl-0 = <&pcie0_pins_default>; + pinctrl-names = "default"; + }; diff --git a/Documentation/devicetree/bindings/pci/rcar-pci.txt b/Documentation/devicetree/bindings/pci/rcar-pci.txt index 29d3b989d3b0..6cf99690eef9 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci.txt +++ b/Documentation/devicetree/bindings/pci/rcar-pci.txt @@ -1,8 +1,17 @@ * Renesas RCar PCIe interface Required properties: -- compatible: should contain one of the following - "renesas,pcie-r8a7779", "renesas,pcie-r8a7790", "renesas,pcie-r8a7791" +compatible: "renesas,pcie-r8a7779" for the R8A7779 SoC; + "renesas,pcie-r8a7790" for the R8A7790 SoC; + "renesas,pcie-r8a7791" for the R8A7791 SoC; + "renesas,pcie-r8a7793" for the R8A7793 SoC; + "renesas,pcie-r8a7795" for the R8A7795 SoC; + "renesas,pcie-rcar-gen2" for a generic R-Car Gen2 compatible device. + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first + followed by the generic version. + - reg: base address and length of the pcie controller registers. - #address-cells: set to <3> - #size-cells: set to <2> @@ -25,7 +34,7 @@ Example: SoC specific DT Entry: pcie: pcie@fe000000 { - compatible = "renesas,pcie-r8a7791"; + compatible = "renesas,pcie-r8a7791", "renesas,pcie-rcar-gen2"; reg = <0 0xfe000000 0 0x80000>; #address-cells = <3>; #size-cells = <2>; diff --git a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt new file mode 100644 index 000000000000..337fc97d18c9 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt @@ -0,0 +1,68 @@ +* Xilinx NWL PCIe Root Port Bridge DT description + +Required properties: +- compatible: Should contain "xlnx,nwl-pcie-2.11" +- #address-cells: Address representation for root ports, set to <3> +- #size-cells: Size representation for root ports, set to <2> +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- reg: Should contain Bridge, PCIe Controller registers location, + configuration space, and length +- reg-names: Must include the following entries: + "breg": bridge registers + "pcireg": PCIe controller registers + "cfg": configuration space region +- device_type: must be "pci" +- interrupts: Should contain NWL PCIe interrupt +- interrupt-names: Must include the following entries: + "msi1, msi0": interrupt asserted when MSI is received + "intx": interrupt asserted when a legacy interrupt is received + "misc": interrupt asserted when miscellaneous is received +- interrupt-map-mask and interrupt-map: standard PCI properties to define the + mapping of the PCI interface to interrupt numbers. +- ranges: ranges for the PCI memory regions (I/O space region is not + supported by hardware) + Please refer to the standard PCI bus binding document for a more + detailed explanation +- msi-controller: indicates that this is MSI controller node +- msi-parent: MSI parent of the root complex itself +- legacy-interrupt-controller: Interrupt controller device node for Legacy interrupts + - interrupt-controller: identifies the node as an interrupt controller + - #interrupt-cells: should be set to 1 + - #address-cells: specifies the number of cells needed to encode an + address. The value must be 0. + + +Example: +++++++++ + +nwl_pcie: pcie@fd0e0000 { + #address-cells = <3>; + #size-cells = <2>; + compatible = "xlnx,nwl-pcie-2.11"; + #interrupt-cells = <1>; + msi-controller; + device_type = "pci"; + interrupt-parent = <&gic>; + interrupts = <0 114 4>, <0 115 4>, <0 116 4>, <0 117 4>, <0 118 4>; + interrupt-names = "msi0", "msi1", "intx", "dummy", "misc"; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + interrupt-map = <0x0 0x0 0x0 0x1 &pcie_intc 0x1>, + <0x0 0x0 0x0 0x2 &pcie_intc 0x2>, + <0x0 0x0 0x0 0x3 &pcie_intc 0x3>, + <0x0 0x0 0x0 0x4 &pcie_intc 0x4>; + + msi-parent = <&nwl_pcie>; + reg = <0x0 0xfd0e0000 0x0 0x1000>, + <0x0 0xfd480000 0x0 0x1000>, + <0x0 0xe0000000 0x0 0x1000000>; + reg-names = "breg", "pcireg", "cfg"; + ranges = <0x02000000 0x00000000 0xe1000000 0x00000000 0xe1000000 0 0x0f000000>; + + pcie_intc: legacy-interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; + +}; diff --git a/Documentation/devicetree/bindings/pci/xilinx-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-pcie.txt index 02f979a48aeb..fd57a81180a4 100644 --- a/Documentation/devicetree/bindings/pci/xilinx-pcie.txt +++ b/Documentation/devicetree/bindings/pci/xilinx-pcie.txt @@ -17,7 +17,7 @@ Required properties: Please refer to the standard PCI bus binding document for a more detailed explanation -Optional properties: +Optional properties for Zynq/Microblaze: - bus-range: PCI bus numbers covered Interrupt controller child node @@ -38,13 +38,13 @@ the four INTx interrupts in ISR and route them to this domain. Example: ++++++++ - +Zynq: pci_express: axi-pcie@50000000 { #address-cells = <3>; #size-cells = <2>; #interrupt-cells = <1>; compatible = "xlnx,axi-pcie-host-1.00.a"; - reg = < 0x50000000 0x10000000 >; + reg = < 0x50000000 0x1000000 >; device_type = "pci"; interrupts = < 0 52 4 >; interrupt-map-mask = <0 0 0 7>; @@ -60,3 +60,29 @@ Example: #interrupt-cells = <1>; }; }; + + +Microblaze: + pci_express: axi-pcie@10000000 { + #address-cells = <3>; + #size-cells = <2>; + #interrupt-cells = <1>; + compatible = "xlnx,axi-pcie-host-1.00.a"; + reg = <0x10000000 0x4000000>; + device_type = "pci"; + interrupt-parent = <µblaze_0_intc>; + interrupts = <1 2>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc 1>, + <0 0 0 2 &pcie_intc 2>, + <0 0 0 3 &pcie_intc 3>, + <0 0 0 4 &pcie_intc 4>; + ranges = <0x02000000 0x00000000 0x80000000 0x80000000 0x00000000 0x10000000>; + + pcie_intc: interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; + + }; diff --git a/Documentation/devicetree/bindings/phy/brcm,brcmstb-sata-phy.txt b/Documentation/devicetree/bindings/phy/brcm,brcmstb-sata-phy.txt index 7f81ef90146a..d87ab7c127b8 100644 --- a/Documentation/devicetree/bindings/phy/brcm,brcmstb-sata-phy.txt +++ b/Documentation/devicetree/bindings/phy/brcm,brcmstb-sata-phy.txt @@ -2,6 +2,7 @@ Required properties: - compatible: should be one or more of + "brcm,bcm7425-sata-phy" "brcm,bcm7445-sata-phy" "brcm,phy-sata3" - address-cells: should be 1 diff --git a/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.txt b/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.txt new file mode 100644 index 000000000000..761c4bc24a9b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/brcm,cygnus-pcie-phy.txt @@ -0,0 +1,47 @@ +Broadcom Cygnus PCIe PHY + +Required properties: +- compatible: must be "brcm,cygnus-pcie-phy" +- reg: base address and length of the PCIe PHY block +- #address-cells: must be 1 +- #size-cells: must be 0 + +Each PCIe PHY should be represented by a child node + +Required properties For the child node: +- reg: the PHY ID +0 - PCIe RC 0 +1 - PCIe RC 1 +- #phy-cells: must be 0 + +Example: + pcie_phy: phy@0301d0a0 { + compatible = "brcm,cygnus-pcie-phy"; + reg = <0x0301d0a0 0x14>; + + pcie0_phy: phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + + pcie1_phy: phy@1 { + reg = <1>; + #phy-cells = <0>; + }; + }; + + /* users of the PCIe phy */ + + pcie0: pcie@18012000 { + ... + ... + phys = <&pcie0_phy>; + phy-names = "pcie-phy"; + }; + + pcie1: pcie@18013000 { + ... + ... + phys = <pcie1_phy>; + phy-names = "pcie-phy"; + }; diff --git a/Documentation/devicetree/bindings/arm/calxeda/combophy.txt b/Documentation/devicetree/bindings/phy/calxeda-combophy.txt index 6622bdb2e8bc..6622bdb2e8bc 100644 --- a/Documentation/devicetree/bindings/arm/calxeda/combophy.txt +++ b/Documentation/devicetree/bindings/phy/calxeda-combophy.txt diff --git a/Documentation/devicetree/bindings/usb/keystone-phy.txt b/Documentation/devicetree/bindings/phy/keystone-usb-phy.txt index f37b3a86341d..f37b3a86341d 100644 --- a/Documentation/devicetree/bindings/usb/keystone-phy.txt +++ b/Documentation/devicetree/bindings/phy/keystone-usb-phy.txt diff --git a/Documentation/devicetree/bindings/usb/mxs-phy.txt b/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt index 379b84a567cc..379b84a567cc 100644 --- a/Documentation/devicetree/bindings/usb/mxs-phy.txt +++ b/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt b/Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.txt index a9aa79fb90ed..a9aa79fb90ed 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra20-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra20-usb-phy.txt diff --git a/Documentation/devicetree/bindings/phy/phy-ath79-usb.txt b/Documentation/devicetree/bindings/phy/phy-ath79-usb.txt new file mode 100644 index 000000000000..cafe2197dad9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-ath79-usb.txt @@ -0,0 +1,18 @@ +* Atheros AR71XX/9XXX USB PHY + +Required properties: +- compatible: "qca,ar7100-usb-phy" +- #phys-cells: should be 0 +- reset-names: "usb-phy"[, "usb-suspend-override"] +- resets: references to the reset controllers + +Example: + + usb-phy { + compatible = "qca,ar7100-usb-phy"; + + reset-names = "usb-phy", "usb-suspend-override"; + resets = <&rst 4>, <&rst 3>; + + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-hi6220-usb.txt b/Documentation/devicetree/bindings/phy/phy-hi6220-usb.txt new file mode 100644 index 000000000000..f17a56e2152f --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-hi6220-usb.txt @@ -0,0 +1,16 @@ +Hisilicon hi6220 usb PHY +----------------------- + +Required properties: +- compatible: should be "hisilicon,hi6220-usb-phy" +- #phy-cells: must be 0 +- hisilicon,peripheral-syscon: phandle of syscon used to control phy. +Refer to phy/phy-bindings.txt for the generic PHY binding properties + +Example: + usb_phy: usbphy { + compatible = "hisilicon,hi6220-usb-phy"; + #phy-cells = <0>; + phy-supply = <&fixed_5v_hub>; + hisilicon,peripheral-syscon = <&sys_ctrl>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt b/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt new file mode 100644 index 000000000000..00100cf3e037 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mt65xx-usb.txt @@ -0,0 +1,68 @@ +mt65xx USB3.0 PHY binding +-------------------------- + +This binding describes a usb3.0 phy for mt65xx platforms of Medaitek SoC. + +Required properties (controller (parent) node): + - compatible : should be "mediatek,mt8173-u3phy" + - reg : offset and length of register for phy, exclude port's + register. + - clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names + - clock-names : must contain + "u3phya_ref": for reference clock of usb3.0 analog phy. + +Required nodes : a sub-node is required for each port the controller + provides. Address range information including the usual + 'reg' property is used inside these nodes to describe + the controller's topology. + +Required properties (port (child) node): +- reg : address and length of the register set for the port. +- #phy-cells : should be 1 (See second example) + cell after port phandle is phy type from: + - PHY_TYPE_USB2 + - PHY_TYPE_USB3 + +Example: + +u3phy: usb-phy@11290000 { + compatible = "mediatek,mt8173-u3phy"; + reg = <0 0x11290000 0 0x800>; + clocks = <&apmixedsys CLK_APMIXED_REF2USB_TX>; + clock-names = "u3phya_ref"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + status = "okay"; + + phy_port0: port@11290800 { + reg = <0 0x11290800 0 0x800>; + #phy-cells = <1>; + status = "okay"; + }; + + phy_port1: port@11291000 { + reg = <0 0x11291000 0 0x800>; + #phy-cells = <1>; + status = "okay"; + }; +}; + +Specifying phy control of devices +--------------------------------- + +Device nodes should specify the configuration required in their "phys" +property, containing a phandle to the phy port node and a device type; +phy-names for each port are optional. + +Example: + +#include <dt-bindings/phy/phy.h> + +usb30: usb@11270000 { + ... + phys = <&phy_port0 PHY_TYPE_USB3>; + phy-names = "usb3-0"; + ... +}; diff --git a/Documentation/devicetree/bindings/usb/qcom,usb-8x16-phy.txt b/Documentation/devicetree/bindings/phy/qcom,usb-8x16-phy.txt index 2cb2168cef41..2cb2168cef41 100644 --- a/Documentation/devicetree/bindings/usb/qcom,usb-8x16-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom,usb-8x16-phy.txt diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt new file mode 100644 index 000000000000..eaf7e9b7ce6b --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -0,0 +1,32 @@ +* Renesas R-Car generation 3 USB 2.0 PHY + +This file provides information on what the device node for the R-Car generation +3 USB 2.0 PHY contains. + +Required properties: +- compatible: "renesas,usb2-phy-r8a7795" if the device is a part of an R8A7795 + SoC. +- reg: offset and length of the partial USB 2.0 Host register block. +- clocks: clock phandle and specifier pair(s). +- #phy-cells: see phy-bindings.txt in the same directory, must be <0>. + +Optional properties: +To use a USB channel where USB 2.0 Host and HSUSB (USB 2.0 Peripheral) are +combined, the device tree node should set interrupt properties to use the +channel as USB OTG: +- interrupts: interrupt specifier for the PHY. + +Example (R-Car H3): + + usb-phy@ee080200 { + compatible = "renesas,usb2-phy-r8a7795"; + reg = <0 0xee080200 0 0x700>; + interrupts = <GIC_SPI 108 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp7_clks R8A7795_CLK_EHCI0>; + }; + + usb-phy@ee0a0200 { + compatible = "renesas,usb2-phy-r8a7795"; + reg = <0 0xee0a0200 0 0x700>; + clocks = <&mstp7_clks R8A7795_CLK_EHCI0>; + }; diff --git a/Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt new file mode 100644 index 000000000000..50c4f9b00adf --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rockchip-dp-phy.txt @@ -0,0 +1,22 @@ +Rockchip specific extensions to the Analogix Display Port PHY +------------------------------------ + +Required properties: +- compatible : should be one of the following supported values: + - "rockchip.rk3288-dp-phy" +- clocks: from common clock binding: handle to dp clock. + of memory mapped region. +- clock-names: from common clock binding: + Required elements: "24m" +- rockchip,grf: phandle to the syscon managing the "general register files" +- #phy-cells : from the generic PHY bindings, must be 0; + +Example: + +edp_phy: edp-phy { + compatible = "rockchip,rk3288-dp-phy"; + rockchip,grf = <&grf>; + clocks = <&cru SCLK_EDP_24M>; + clock-names = "24m"; + #phy-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt new file mode 100644 index 000000000000..61916f15a949 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rockchip-emmc-phy.txt @@ -0,0 +1,19 @@ +Rockchip EMMC PHY +----------------------- + +Required properties: + - compatible: rockchip,rk3399-emmc-phy + - rockchip,grf : phandle to the syscon managing the "general + register files" + - #phy-cells: must be 0 + - reg: PHY configure reg address offset in "general + register files" + +Example: + +emmcphy: phy { + compatible = "rockchip,rk3399-emmc-phy"; + rockchip,grf = <&grf>; + reg = <0xf780>; + #phy-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt index 826454ac43bb..68498d560354 100644 --- a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt @@ -1,7 +1,10 @@ ROCKCHIP USB2 PHY Required properties: - - compatible: rockchip,rk3288-usb-phy + - compatible: matching the soc type, one of + "rockchip,rk3066a-usb-phy" + "rockchip,rk3188-usb-phy" + "rockchip,rk3288-usb-phy" - rockchip,grf : phandle to the syscon managing the "general register files" - #address-cells: should be 1 @@ -21,6 +24,7 @@ required properties: Optional Properties: - clocks : phandle + clock specifier for the phy clocks - clock-names: string, clock name, must be "phyclk" +- #clock-cells: for users of the phy-pll, should be 0 Example: diff --git a/Documentation/devicetree/bindings/phy/samsung-phy.txt b/Documentation/devicetree/bindings/phy/samsung-phy.txt index 60c6f2a633e0..0289d3b07853 100644 --- a/Documentation/devicetree/bindings/phy/samsung-phy.txt +++ b/Documentation/devicetree/bindings/phy/samsung-phy.txt @@ -44,6 +44,9 @@ Required properties: - the "ref" clock is used to get the rate of the clock provided to the PHY module +Optional properties: +- vbus-supply: power-supply phandle for vbus power source + The first phandle argument in the PHY specifier identifies the PHY, its meaning is compatible dependent. For the currently supported SoCs (Exynos 4210 and Exynos 4212) it is as follows: diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index 0cebf7454517..95736d77fbb7 100644 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt @@ -9,6 +9,7 @@ Required properties: * allwinner,sun7i-a20-usb-phy * allwinner,sun8i-a23-usb-phy * allwinner,sun8i-a33-usb-phy + * allwinner,sun8i-h3-usb-phy - reg : a list of offset + length pairs - reg-names : * "phy_ctrl" diff --git a/Documentation/devicetree/bindings/phy/ti-phy.txt b/Documentation/devicetree/bindings/phy/ti-phy.txt index 9cf9446eaf2e..a3b394587874 100644 --- a/Documentation/devicetree/bindings/phy/ti-phy.txt +++ b/Documentation/devicetree/bindings/phy/ti-phy.txt @@ -31,6 +31,8 @@ OMAP USB2 PHY Required properties: - compatible: Should be "ti,omap-usb2" + Should be "ti,dra7x-usb2-phy2" for the 2nd instance of USB2 PHY + in DRA7x - reg : Address and length of the register set for the device. - #phy-cells: determine the number of cells that should be given in the phandle while referencing this phy. @@ -40,10 +42,14 @@ Required properties: * "wkupclk" - wakeup clock. * "refclk" - reference clock (optional). -Optional properties: +Deprecated properties: - ctrl-module : phandle of the control module used by PHY driver to power on the PHY. +Recommended properies: +- syscon-phy-power : phandle/offset pair. Phandle to the system control + module and the register offset to power on/off the PHY. + This is usually a subnode of ocp2scp to which it is connected. usb2phy@4a0ad080 { @@ -77,14 +83,22 @@ Required properties: * "div-clk" - apll clock Optional properties: - - ctrl-module : phandle of the control module used by PHY driver to power on - the PHY. - id: If there are multiple instance of the same type, in order to differentiate between each instance "id" can be used (e.g., multi-lane PCIe PHY). If "id" is not provided, it is set to default value of '1'. - syscon-pllreset: Handle to system control region that contains the CTRL_CORE_SMA_SW_0 register and register offset to the CTRL_CORE_SMA_SW_0 register that contains the SATA_PLL_SOFT_RESET bit. Only valid for sata_phy. + - syscon-pcs : phandle/offset pair. Phandle to the system control module and the + register offset to write the PCS delay value. + +Deprecated properties: + - ctrl-module : phandle of the control module used by PHY driver to power on + the PHY. + +Recommended properies: + - syscon-phy-power : phandle/offset pair. Phandle to the system control + module and the register offset to power on/off the PHY. This is usually a subnode of ocp2scp to which it is connected. diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 3c821cda1ad0..69617220c5d6 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -17,6 +17,12 @@ Required properties: "allwinner,sun8i-a23-pinctrl" "allwinner,sun8i-a23-r-pinctrl" "allwinner,sun8i-a33-pinctrl" + "allwinner,sun9i-a80-pinctrl" + "allwinner,sun9i-a80-r-pinctrl" + "allwinner,sun8i-a83t-pinctrl" + "allwinner,sun8i-h3-pinctrl" + "allwinner,sun8i-h3-r-pinctrl" + "allwinner,sun50i-a64-pinctrl" - reg: Should contain the register physical address and length for the pin controller. diff --git a/Documentation/devicetree/bindings/pinctrl/atmel,at91-pio4-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/atmel,at91-pio4-pinctrl.txt new file mode 100644 index 000000000000..61ac75706cc9 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/atmel,at91-pio4-pinctrl.txt @@ -0,0 +1,90 @@ +* Atmel PIO4 Controller + +The Atmel PIO4 controller is used to select the function of a pin and to +configure it. + +Required properties: +- compatible: "atmel,sama5d2-pinctrl". +- reg: base address and length of the PIO controller. +- interrupts: interrupt outputs from the controller, one for each bank. +- interrupt-controller: mark the device node as an interrupt controller. +- #interrupt-cells: should be two. +- gpio-controller: mark the device node as a gpio controller. +- #gpio-cells: should be two. + +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. + +Subnode format +Each node (or subnode) will list the pins it needs and how to configured these +pins. + + node { + pinmux = <PIN_NUMBER_PINMUX>; + GENERIC_PINCONFIG; + }; + +Required properties: +- pinmux: integer array. Each integer represents a pin number plus mux and +ioset settings. Use the macros from boot/dts/<soc>-pinfunc.h file to get the +right representation of the pin. + +Optional properties: +- GENERIC_PINCONFIG: generic pinconfig options to use, bias-disable, +bias-pull-down, bias-pull-up, drive-open-drain, input-schmitt-enable, +input-debounce, output-low, output-high. + +Example: + +#include <sama5d2-pinfunc.h> + +... +{ + pioA: pinctrl@fc038000 { + compatible = "atmel,sama5d2-pinctrl"; + reg = <0xfc038000 0x600>; + interrupts = <18 IRQ_TYPE_LEVEL_HIGH 7>, + <68 IRQ_TYPE_LEVEL_HIGH 7>, + <69 IRQ_TYPE_LEVEL_HIGH 7>, + <70 IRQ_TYPE_LEVEL_HIGH 7>; + interrupt-controller; + #interrupt-cells = <2>; + gpio-controller; + #gpio-cells = <2>; + clocks = <&pioA_clk>; + + pinctrl_i2c0_default: i2c0_default { + pinmux = <PIN_PD21__TWD0>, + <PIN_PD22__TWCK0>; + bias-disable; + }; + + pinctrl_led_gpio_default: led_gpio_default { + pinmux = <PIN_PB0>, + <PIN_PB5>; + bias-pull-up; + }; + + pinctrl_sdmmc1_default: sdmmc1_default { + cmd_data { + pinmux = <PIN_PA28__SDMMC1_CMD>, + <PIN_PA18__SDMMC1_DAT0>, + <PIN_PA19__SDMMC1_DAT1>, + <PIN_PA20__SDMMC1_DAT2>, + <PIN_PA21__SDMMC1_DAT3>; + bias-pull-up; + }; + + ck_cd { + pinmux = <PIN_PA22__SDMMC1_CK>, + <PIN_PA30__SDMMC1_CD>; + bias-disable; + }; + }; + ... + }; +}; +... diff --git a/Documentation/devicetree/bindings/pinctrl/berlin,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/berlin,pinctrl.txt index a8bb5e26019c..f8fa28ce163e 100644 --- a/Documentation/devicetree/bindings/pinctrl/berlin,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/berlin,pinctrl.txt @@ -20,7 +20,10 @@ Required properties: "marvell,berlin2cd-soc-pinctrl", "marvell,berlin2cd-system-pinctrl", "marvell,berlin2q-soc-pinctrl", - "marvell,berlin2q-system-pinctrl" + "marvell,berlin2q-system-pinctrl", + "marvell,berlin4ct-avio-pinctrl", + "marvell,berlin4ct-soc-pinctrl", + "marvell,berlin4ct-system-pinctrl" Required subnode-properties: - groups: a list of strings describing the group names. diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,cygnus-gpio.txt b/Documentation/devicetree/bindings/pinctrl/brcm,iproc-gpio.txt index 6540ca56be5e..e4277921f3e3 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,cygnus-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/brcm,iproc-gpio.txt @@ -1,15 +1,18 @@ -Broadcom Cygnus GPIO/PINCONF Controller +Broadcom iProc GPIO/PINCONF Controller Required properties: - compatible: - Must be "brcm,cygnus-ccm-gpio", "brcm,cygnus-asiu-gpio", or - "brcm,cygnus-crmu-gpio" + Must be "brcm,cygnus-ccm-gpio", "brcm,cygnus-asiu-gpio", + "brcm,cygnus-crmu-gpio" or "brcm,iproc-gpio" - reg: - Define the base and range of the I/O address space that contains the Cygnus + Define the base and range of the I/O address space that contains SoC GPIO/PINCONF controller registers +- ngpios: + Total number of in-use slots in GPIO controller + - #gpio-cells: Must be two. The first cell is the GPIO pin number (within the controller's pin space) and the second cell is used for the following: @@ -26,9 +29,13 @@ Optional properties: - interrupt-controller: Specifies that the node is an interrupt controller -- pinmux: - Specifies the phandle to the IOMUX device, where pins can be individually -muxed to GPIO +- gpio-ranges: + Specifies the mapping between gpio controller and pin-controllers pins. + This requires 4 fields in cells defined as - + 1. Phandle of pin-controller. + 2. GPIO base pin offset. + 3 Pin-control base pin offset. + 4. number of gpio pins which are linearly mapped from pin base. Supported generic PINCONF properties in child nodes: @@ -53,6 +60,7 @@ Example: compatible = "brcm,cygnus-ccm-gpio"; reg = <0x1800a000 0x50>, <0x0301d164 0x20>; + ngpios = <24>; #gpio-cells = <2>; gpio-controller; interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; @@ -74,10 +82,13 @@ Example: gpio_asiu: gpio@180a5000 { compatible = "brcm,cygnus-asiu-gpio"; reg = <0x180a5000 0x668>; + ngpios = <146>; #gpio-cells = <2>; gpio-controller; interrupts = <GIC_SPI 174 IRQ_TYPE_LEVEL_HIGH>; interrupt-controller; + gpio-ranges = <&pinctrl 0 42 1>, + <&pinctrl 1 44 3>; }; /* diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,ns2-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/brcm,ns2-pinmux.txt new file mode 100644 index 000000000000..e295dda4bbba --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,ns2-pinmux.txt @@ -0,0 +1,102 @@ +Broadcom Northstar2 IOMUX Controller + +The Northstar2 IOMUX controller supports group based mux configuration. There +are some individual pins that support modifying the pinconf parameters. + +Required properties: + +- compatible: + Must be "brcm,ns2-pinmux" + +- reg: + Define the base and range of the I/O address space that contains the + Northstar2 IOMUX and pin configuration registers. + +Properties in sub nodes: + +- function: + The mux function to select + +- groups: + The list of groups to select with a given function + +- pins: + List of pin names to change configuration + +The generic properties bias-disable, bias-pull-down, bias-pull-up, +drive-strength, slew-rate, input-enable, input-disable are supported +for some individual pins listed at the end. + +For more details, refer to +Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt + +For example: + + pinctrl: pinctrl@6501d130 { + compatible = "brcm,ns2-pinmux"; + reg = <0x6501d130 0x08>, + <0x660a0028 0x04>, + <0x660009b0 0x40>; + + pinctrl-names = "default"; + pinctrl-0 = <&nand_sel &uart3_rx &sdio0_d4>; + + /* Select nand function */ + nand_sel: nand_sel { + function = "nand"; + groups = "nand_grp"; + }; + + /* Pull up the uart3 rx pin */ + uart3_rx: uart3_rx { + pins = "uart3_sin"; + bias-pull-up; + }; + + /* Set the drive strength of sdio d4 pin */ + sdio0_d4: sdio0_d4 { + pins = "sdio0_data4"; + drive-strength = <8>; + }; + }; + +List of supported functions and groups in Northstar2: + +"nand": "nand_grp" + +"nor": "nor_data_grp", "nor_adv_grp", "nor_addr_0_3_grp", "nor_addr_4_5_grp", + "nor_addr_6_7_grp", "nor_addr_8_9_grp", "nor_addr_10_11_grp", + "nor_addr_12_15_grp" + +"gpio": "gpio_0_1_grp", "gpio_2_5_grp", "gpio_6_7_grp", "gpio_8_9_grp", + "gpio_10_11_grp", "gpio_12_13_grp", "gpio_14_17_grp", "gpio_18_19_grp", + "gpio_20_21_grp", "gpio_22_23_grp", "gpio_24_25_grp", "gpio_26_27_grp", + "gpio_28_29_grp", "gpio_30_31_grp" + +"pcie": "pcie_ab1_clk_wak_grp", "pcie_a3_clk_wak_grp", "pcie_b3_clk_wak_grp", + "pcie_b2_clk_wak_grp", "pcie_a2_clk_wak_grp" + +"uart0": "uart0_modem_grp", "uart0_rts_cts_grp", "uart0_in_out_grp" + +"uart1": "uart1_ext_clk_grp", "uart1_dcd_dsr_grp", "uart1_ri_dtr_grp", + "uart1_rts_cts_grp", "uart1_in_out_grp" + +"uart2": "uart2_rts_cts_grp" + +"pwm": "pwm_0_grp", "pwm_1_grp", "pwm_2_grp", "pwm_3_grp" + + +List of pins that support pinconf parameters: + +"qspi_wp", "qspi_hold", "qspi_cs", "qspi_sck", "uart3_sin", "uart3_sout", +"qspi_mosi", "qspi_miso", "spi0_fss", "spi0_rxd", "spi0_txd", "spi0_sck", +"spi1_fss", "spi1_rxd", "spi1_txd", "spi1_sck", "sdio0_data7", +"sdio0_emmc_rst", "sdio0_led_on", "sdio0_wp", "sdio0_data3", "sdio0_data4", +"sdio0_data5", "sdio0_data6", "sdio0_cmd", "sdio0_data0", "sdio0_data1", +"sdio0_data2", "sdio1_led_on", "sdio1_wp", "sdio0_cd_l", "sdio0_clk", +"sdio1_data5", "sdio1_data6", "sdio1_data7", "sdio1_emmc_rst", "sdio1_data1", +"sdio1_data2", "sdio1_data3", "sdio1_data4", "sdio1_cd_l", "sdio1_clk", +"sdio1_cmd", "sdio1_data0", "ext_mdio_0", "ext_mdc_0", "usb3_p1_vbus_ppc", +"usb3_p1_overcurrent", "usb3_p0_vbus_ppc", "usb3_p0_overcurrent", +"usb2_presence_indication", "usb2_vbus_present", "usb2_vbus_ppc", +"usb2_overcurrent", "sata_led1", "sata_led0" diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,nsp-gpio.txt b/Documentation/devicetree/bindings/pinctrl/brcm,nsp-gpio.txt new file mode 100644 index 000000000000..0844168a6dd4 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,nsp-gpio.txt @@ -0,0 +1,80 @@ +Broadcom Northstar plus (NSP) GPIO/PINCONF Controller + +Required properties: +- compatible: + Must be "brcm,nsp-gpio-a" + +- reg: + Should contain the register physical address and length for each of + GPIO base, IO control registers + +- #gpio-cells: + Must be two. The first cell is the GPIO pin number (within the + controller's pin space) and the second cell is used for the following: + bit[0]: polarity (0 for active high and 1 for active low) + +- gpio-controller: + Specifies that the node is a GPIO controller + +- ngpios: + Number of gpios supported (58x25 supports 32 and 58x23 supports 24) + +Optional properties: +- interrupts: + Interrupt ID + +- interrupt-controller: + Specifies that the node is an interrupt controller + +- gpio-ranges: + Specifies the mapping between gpio controller and pin-controllers pins. + This requires 4 fields in cells defined as - + 1. Phandle of pin-controller. + 2. GPIO base pin offset. + 3 Pin-control base pin offset. + 4. number of gpio pins which are linearly mapped from pin base. + +Supported generic PINCONF properties in child nodes: +- pins: + The list of pins (within the controller's own pin space) that properties + in the node apply to. Pin names are "gpio-<pin>" + +- bias-disable: + Disable pin bias + +- bias-pull-up: + Enable internal pull up resistor + +- bias-pull-down: + Enable internal pull down resistor + +- drive-strength: + Valid drive strength values include 2, 4, 6, 8, 10, 12, 14, 16 (mA) + +Example: + + gpioa: gpio@18000020 { + compatible = "brcm,nsp-gpio-a"; + reg = <0x18000020 0x100>, + <0x1803f1c4 0x1c>; + #gpio-cells = <2>; + gpio-controller; + ngpios = <32>; + gpio-ranges = <&pinctrl 0 0 31>; + interrupt-controller; + interrupts = <GIC_SPI 85 IRQ_TYPE_LEVEL_HIGH>; + + /* Hog a few default settings */ + pinctrl-names = "default"; + pinctrl-0 = <&led>; + led: led { + pins = "gpio-1"; + bias-pull-up; + }; + + pwr: pwr { + gpio-hog; + gpios = <3 1>; + output-high; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt index 8bbf25d58656..457b2c68d47b 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx7d-pinctrl.txt @@ -1,16 +1,42 @@ * Freescale i.MX7 Dual IOMUX Controller +iMX7D supports two iomuxc controllers, fsl,imx7d-iomuxc controller is similar +as previous iMX SoC generation and fsl,imx7d-iomuxc-lpsr which provides low +power state retention capabilities on gpios that are part of iomuxc-lpsr +(GPIO1_IO7..GPIO1_IO0). While iomuxc-lpsr provides its own set of registers for +mux and pad control settings, it shares the input select register from main +iomuxc controller for daisy chain settings, the fsl,input-sel property extends +fsl,imx-pinctrl driver to support iomuxc-lpsr controller. + +iomuxc_lpsr: iomuxc-lpsr@302c0000 { + compatible = "fsl,imx7d-iomuxc-lpsr"; + reg = <0x302c0000 0x10000>; + fsl,input-sel = <&iomuxc>; +}; + +iomuxc: iomuxc@30330000 { + compatible = "fsl,imx7d-iomuxc"; + reg = <0x30330000 0x10000>; +}; + +Pheriparials using pads from iomuxc-lpsr support low state retention power +state, under LPSR mode GPIO's state of pads are retain. + Please refer to fsl,imx-pinctrl.txt in this directory for common binding part and usage. Required properties: -- compatible: "fsl,imx7d-iomuxc" +- compatible: "fsl,imx7d-iomuxc" for main IOMUXC controller, or + "fsl,imx7d-iomuxc-lpsr" for Low Power State Retention IOMUXC controller. - fsl,pins: each entry consists of 6 integers and represents the mux and config setting for one pin. The first 5 integers <mux_reg conf_reg input_reg mux_val input_val> are specified using a PIN_FUNC_ID macro, which can be found in imx7d-pinfunc.h under device tree source folder. The last integer CONFIG is the pad setting value like pull-up on this pin. Please refer to i.MX7 Dual Reference Manual for detailed CONFIG settings. +- fsl,input-sel: required property for iomuxc-lpsr controller, this property is + a phandle for main iomuxc controller which shares the input select register for + daisy chain settings. CONFIG bits definition: PAD_CTL_PUS_100K_DOWN (0 << 5) @@ -25,3 +51,38 @@ PAD_CTL_DSE_X1 (0 << 0) PAD_CTL_DSE_X2 (1 << 0) PAD_CTL_DSE_X3 (2 << 0) PAD_CTL_DSE_X4 (3 << 0) + +Examples: +While iomuxc-lpsr is intended to be used by dedicated peripherals to take +advantages of LPSR power mode, is also possible that an IP to use pads from +any of the iomux controllers. For example the I2C1 IP can use SCL pad from +iomuxc-lpsr controller and SDA pad from iomuxc controller as: + +i2c1: i2c@30a20000 { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2c1_1 &pinctrl_i2c1_2>; + status = "okay"; +}; + +iomuxc-lpsr@302c0000 { + compatible = "fsl,imx7d-iomuxc-lpsr"; + reg = <0x302c0000 0x10000>; + fsl,input-sel = <&iomuxc>; + + pinctrl_i2c1_1: i2c1grp-1 { + fsl,pins = < + MX7D_PAD_GPIO1_IO04__I2C1_SCL 0x4000007f + >; + }; +}; + +iomuxc@30330000 { + compatible = "fsl,imx7d-iomuxc"; + reg = <0x30330000 0x10000>; + + pinctrl_i2c1_2: i2c1grp-2 { + fsl,pins = < + MX7D_PAD_I2C1_SDA__I2C1_SDA 0x4000007f + >; + }; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt index e89b4677567d..8e5216bcd748 100644 --- a/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,pinctrl-xway.txt @@ -1,7 +1,16 @@ Lantiq XWAY pinmux controller Required properties: -- compatible: "lantiq,pinctrl-xway" or "lantiq,pinctrl-xr9" +- compatible: "lantiq,pinctrl-xway", (DEPRECATED: Use "lantiq,pinctrl-danube") + "lantiq,pinctrl-xr9", (DEPRECATED: Use "lantiq,xrx100-pinctrl" or + "lantiq,xrx200-pinctrl") + "lantiq,pinctrl-ase", (DEPRECATED: Use "lantiq,ase-pinctrl") + "lantiq,<chip>-pinctrl", where <chip> is: + "ase" (XWAY AMAZON Family) + "danube" (XWAY DANUBE Family) + "xrx100" (XWAY xRX100 Family) + "xrx200" (XWAY xRX200 Family) + "xrx300" (XWAY xRX300 Family) - reg: Should contain the physical address and length of the gpio/pinmux register range @@ -36,19 +45,87 @@ Required subnode-properties: Valid values for group and function names: +XWAY: (DEPRECATED: Use DANUBE) mux groups: exin0, exin1, exin2, jtag, ebu a23, ebu a24, ebu a25, ebu clk, ebu cs1, ebu wait, nand ale, nand cs1, nand cle, spi, spi_cs1, spi_cs2, spi_cs3, - spi_cs4, spi_cs5, spi_cs6, asc0, asc0 cts rts, stp, nmi , gpt1, gpt2, + spi_cs4, spi_cs5, spi_cs6, asc0, asc0 cts rts, stp, nmi, gpt1, gpt2, gpt3, clkout0, clkout1, clkout2, clkout3, gnt1, gnt2, gnt3, req1, req2, req3 - additional mux groups (XR9 only): - mdio, nand rdy, nand rd, exin3, exin4, gnt4, req4 + functions: + spi, asc, cgu, jtag, exin, stp, gpt, nmi, pci, ebu + +XR9: ( DEPRECATED: Use xRX100/xRX200) + mux groups: + exin0, exin1, exin2, exin3, exin4, jtag, ebu a23, ebu a24, ebu a25, + ebu clk, ebu cs1, ebu wait, nand ale, nand cs1, nand cle, nand rdy, + nand rd, spi, spi_cs1, spi_cs2, spi_cs3, spi_cs4, spi_cs5, spi_cs6, + asc0, asc0 cts rts, stp, nmi, gpt1, gpt2, gpt3, clkout0, clkout1, + clkout2, clkout3, gnt1, gnt2, gnt3, gnt4, req1, req2, req3, req4, mdio, + gphy0 led0, gphy0 led1, gphy0 led2, gphy1 led0, gphy1 led1, gphy1 led2 + + functions: + spi, asc, cgu, jtag, exin, stp, gpt, nmi, pci, ebu, mdio, gphy + +AMAZON: + mux groups: + exin0, exin1, exin2, jtag, spi_di, spi_do, spi_clk, spi_cs1, spi_cs2, + spi_cs3, spi_cs4, spi_cs5, spi_cs6, asc, stp, gpt1, gpt2, gpt3, clkout0, + clkout1, clkout2, mdio, dfe led0, dfe led1, ephy led0, ephy led1, ephy led2 + + functions: + spi, asc, cgu, jtag, exin, stp, gpt, mdio, ephy, dfe + +DANUBE: + mux groups: + exin0, exin1, exin2, jtag, ebu a23, ebu a24, ebu a25, ebu clk, ebu cs1, + ebu wait, nand ale, nand cs1, nand cle, spi_di, spi_do, spi_clk, spi_cs1, + spi_cs2, spi_cs3, spi_cs4, spi_cs5, spi_cs6, asc0, asc0 cts rts, stp, nmi, + gpt1, gpt2, gpt3, clkout0, clkout1, clkout2, clkout3, gnt1, gnt2, gnt3, + req1, req2, req3, dfe led0, dfe led1 functions: - spi, asc, cgu, jtag, exin, stp, gpt, nmi, pci, ebu, mdio + spi, asc, cgu, jtag, exin, stp, gpt, nmi, pci, ebu, dfe +xRX100: + mux groups: + exin0, exin1, exin2, exin3, exin4, ebu a23, ebu a24, ebu a25, ebu clk, + ebu cs1, ebu wait, nand ale, nand cs1, nand cle, nand rdy, nand rd, + spi_di, spi_do, spi_clk, spi_cs1, spi_cs2, spi_cs3, spi_cs4, spi_cs5, + spi_cs6, asc0, asc0 cts rts, stp, nmi, gpt1, gpt2, gpt3, clkout0, clkout1, + clkout2, clkout3, gnt1, gnt2, gnt3, gnt4, req1, req2, req3, req4, mdio, + dfe led0, dfe led1 + + functions: + spi, asc, cgu, exin, stp, gpt, nmi, pci, ebu, mdio, dfe + +xRX200: + mux groups: + exin0, exin1, exin2, exin3, exin4, ebu a23, ebu a24, ebu a25, ebu clk, + ebu cs1, ebu wait, nand ale, nand cs1, nand cle, nand rdy, nand rd, + spi_di, spi_do, spi_clk, spi_cs1, spi_cs2, spi_cs3, spi_cs4, spi_cs5, + spi_cs6, usif uart_rx, usif uart_tx, usif uart_rts, usif uart_cts, + usif uart_dtr, usif uart_dsr, usif uart_dcd, usif uart_ri, usif spi_di, + usif spi_do, usif spi_clk, usif spi_cs0, usif spi_cs1, usif spi_cs2, + stp, nmi, gpt1, gpt2, gpt3, clkout0, clkout1, clkout2, clkout3, gnt1, + gnt2, gnt3, gnt4, req1, req2, req3, req4, mdio, dfe led0, dfe led1, + gphy0 led0, gphy0 led1, gphy0 led2, gphy1 led0, gphy1 led1, gphy1 led2 + + functions: + spi, usif, cgu, exin, stp, gpt, nmi, pci, ebu, mdio, dfe, gphy + +xRX300: + mux groups: + exin0, exin1, exin2, exin4, nand ale, nand cs0, nand cs1, nand cle, + nand rdy, nand rd, nand_d0, nand_d1, nand_d2, nand_d3, nand_d4, nand_d5, + nand_d6, nand_d7, nand_d1, nand wr, nand wp, nand se, spi_di, spi_do, + spi_clk, spi_cs1, spi_cs4, spi_cs6, usif uart_rx, usif uart_tx, + usif spi_di, usif spi_do, usif spi_clk, usif spi_cs0, stp, clkout2, + mdio, dfe led0, dfe led1, ephy0 led0, ephy0 led1, ephy1 led0, ephy1 led1 + + functions: + spi, usif, cgu, exin, stp, ebu, mdio, dfe, ephy Definition of pin configurations: @@ -62,15 +139,32 @@ Optional subnode-properties: 0: none, 1: down, 2: up. - lantiq,open-drain: Boolean, enables open-drain on the defined pin. -Valid values for XWAY pin names: +Valid values for XWAY pin names: (DEPRECATED: Use DANUBE) Pinconf pins can be referenced via the names io0-io31. -Valid values for XR9 pin names: +Valid values for XR9 pin names: (DEPRECATED: Use xrX100/xRX200) Pinconf pins can be referenced via the names io0-io55. +Valid values for AMAZON pin names: + Pinconf pins can be referenced via the names io0-io31. + +Valid values for DANUBE pin names: + Pinconf pins can be referenced via the names io0-io31. + +Valid values for xRX100 pin names: + Pinconf pins can be referenced via the names io0-io55. + +Valid values for xRX200 pin names: + Pinconf pins can be referenced via the names io0-io49. + +Valid values for xRX300 pin names: + Pinconf pins can be referenced via the names io0-io1,io3-io6,io8-io11, + io13-io19,io23-io27,io34-io36, + io42-io43,io48-io61. + Example: gpio: pinmux@E100B10 { - compatible = "lantiq,pinctrl-xway"; + compatible = "lantiq,danube-pinctrl"; pinctrl-names = "default"; pinctrl-0 = <&state_default>; diff --git a/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt new file mode 100644 index 000000000000..4b5efa51bec7 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/microchip,pic32-pinctrl.txt @@ -0,0 +1,60 @@ +* Microchip PIC32 Pin Controller + +Please refer to pinctrl-bindings.txt, ../gpio/gpio.txt, and +../interrupt-controller/interrupts.txt for generic information regarding +pin controller, GPIO, and interrupt bindings. + +PIC32 'pin configuration node' is a node of a group of pins which can be +used for a specific device or function. This node represents configuraions of +pins, optional function, and optional mux related configuration. + +Required properties for pin controller node: + - compatible: "microchip,pic32mada-pinctrl" + - reg: Address range of the pinctrl registers. + - clocks: Clock specifier (see clock bindings for details) + +Required properties for pin configuration sub-nodes: + - pins: List of pins to which the configuration applies. + +Optional properties for pin configuration sub-nodes: +---------------------------------------------------- + - function: Mux function for the specified pins. + - bias-pull-up: Enable weak pull-up. + - bias-pull-down: Enable weak pull-down. + - input-enable: Set the pin as an input. + - output-low: Set the pin as an output level low. + - output-high: Set the pin as an output level high. + - microchip,digital: Enable digital I/O. + - microchip,analog: Enable analog I/O. + +Example: + +pic32_pinctrl: pinctrl@1f801400{ + #address-cells = <1>; + #size-cells = <1>; + compatible = "microchip,pic32mzda-pinctrl"; + reg = <0x1f801400 0x400>; + clocks = <&PBCLK1>; + + pinctrl_uart2: pinctrl_uart2 { + uart2-tx { + pins = "G9"; + function = "U2TX"; + microchip,digital; + output-low; + }; + uart2-rx { + pins = "B0"; + function = "U2RX"; + microchip,digital; + input-enable; + }; + }; +}; + +uart2: serial@1f822200 { + compatible = "microchip,pic32mzda-uart"; + reg = <0x1f822200 0x50>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_uart2>; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/nxp,lpc1850-scu.txt b/Documentation/devicetree/bindings/pinctrl/nxp,lpc1850-scu.txt index df0309c57505..bd8b0c69fa44 100644 --- a/Documentation/devicetree/bindings/pinctrl/nxp,lpc1850-scu.txt +++ b/Documentation/devicetree/bindings/pinctrl/nxp,lpc1850-scu.txt @@ -22,6 +22,10 @@ The following generic nodes are supported: - input-schmitt-disable - slew-rate +NXP specific properties: + - nxp,gpio-pin-interrupt : Assign pin to gpio pin interrupt controller + irq number 0 to 7. See example below. + Not all pins support all properties so either refer to the NXP 1850/4350 user manual or the pin table in the pinctrl-lpc18xx driver for supported pin properties. @@ -54,4 +58,14 @@ pinctrl: pinctrl@40086000 { bias-disable; }; }; + + gpio_joystick_pins: gpio-joystick-pins { + gpio_joystick_1_cfg { + pins = "p9_0"; + function = "gpio"; + nxp,gpio-pin-interrupt = <0>; + input-enable; + bias-disable; + }; + }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt index 0480bc31bfd7..17631d0a9af7 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt65xx.txt @@ -4,10 +4,12 @@ The Mediatek's Pin controller is used to control SoC pins. Required properties: - compatible: value should be one of the following. - (a) "mediatek,mt8135-pinctrl", compatible with mt8135 pinctrl. - (b) "mediatek,mt8173-pinctrl", compatible with mt8173 pinctrl. - (c) "mediatek,mt6397-pinctrl", compatible with mt6397 pinctrl. - (d) "mediatek,mt8127-pinctrl", compatible with mt8127 pinctrl. + "mediatek,mt2701-pinctrl", compatible with mt2701 pinctrl. + "mediatek,mt6397-pinctrl", compatible with mt6397 pinctrl. + "mediatek,mt7623-pinctrl", compatible with mt7623 pinctrl. + "mediatek,mt8127-pinctrl", compatible with mt8127 pinctrl. + "mediatek,mt8135-pinctrl", compatible with mt8135 pinctrl. + "mediatek,mt8173-pinctrl", compatible with mt8173 pinctrl. - pins-are-numbered: Specify the subnodes are using numbered pinmux to specify pins. - gpio-controller : Marks the device node as a gpio controller. diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt new file mode 100644 index 000000000000..cfb8500dd56b --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq4019-pinctrl.txt @@ -0,0 +1,74 @@ +Qualcomm Atheros IPQ4019 TLMM block + +This is the Top Level Mode Multiplexor block found on the Qualcomm IPQ8019 +platform, it provides pinctrl, pinmux, pinconf, and gpiolib facilities. + +Required properties: +- compatible: "qcom,ipq4019-pinctrl" +- reg: Should be the base address and length of the TLMM block. +- interrupts: Should be the parent IRQ of the TLMM block. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Should be two. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells : Should be two. + The first cell is the gpio pin number and the + second cell is used for optional parameters. + +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 abitrary 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. + +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, function, bias-disable, bias-pull-down, bias-pull,up, drive-strength. + +Non-empty subnodes must specify the 'pins' property. +Note that not all properties are valid for all pins. + + +Valid values for qcom,pins are: + gpio0-gpio99 + Supports mux, bias and drive-strength + +Valid values for qcom,function are: +gpio, blsp_uart1, blsp_i2c0, blsp_i2c1, blsp_uart0, blsp_spi1, blsp_spi0 + +Example: + + tlmm: pinctrl@1000000 { + compatible = "qcom,ipq4019-pinctrl"; + reg = <0x1000000 0x300000>; + + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <0 208 0>; + + serial_pins: serial_pinmux { + mux { + pins = "gpio60", "gpio61"; + function = "blsp_uart0"; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt new file mode 100644 index 000000000000..e312a71b2f94 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/qcom,msm8996-pinctrl.txt @@ -0,0 +1,199 @@ +Qualcomm MSM8996 TLMM block + +This binding describes the Top Level Mode Multiplexer block found in the +MSM8996 platform. + +- compatible: + Usage: required + Value type: <string> + Definition: must be "qcom,msm8996-pinctrl" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: the base address and size of the TLMM register space. + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: should specify the TLMM summary IRQ. + +- interrupt-controller: + Usage: required + Value type: <none> + Definition: identifies this node as an interrupt controller + +- #interrupt-cells: + Usage: required + Value type: <u32> + Definition: must be 2. Specifying the pin number and flags, as defined + in <dt-bindings/interrupt-controller/irq.h> + +- gpio-controller: + Usage: required + Value type: <none> + Definition: identifies this node as a gpio controller + +- #gpio-cells: + Usage: required + Value type: <u32> + Definition: must be 2. Specifying the pin number and flags, as defined + in <dt-bindings/gpio/gpio.h> + +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: <string-array> + Definition: List of gpio pins affected by the properties specified in + this subnode. + + Valid pins are: + gpio0-gpio149 + Supports mux, bias and drive-strength + + sdc1_clk, sdc1_cmd, sdc1_data sdc2_clk, sdc2_cmd, + sdc2_data sdc1_rclk + Supports bias and drive-strength + +- function: + Usage: required + Value type: <string> + Definition: Specify the alternative function to be configured for the + specified pins. Functions are only valid for gpio pins. + Valid values are: + + blsp_uart1, blsp_spi1, blsp_i2c1, blsp_uim1, atest_tsens, + bimc_dte1, dac_calib0, blsp_spi8, blsp_uart8, blsp_uim8, + qdss_cti_trig_out_b, bimc_dte0, dac_calib1, qdss_cti_trig_in_b, + dac_calib2, atest_tsens2, atest_usb1, blsp_spi10, blsp_uart10, + blsp_uim10, atest_bbrx1, atest_usb13, atest_bbrx0, atest_usb12, + mdp_vsync, edp_lcd, blsp_i2c10, atest_gpsadc1, atest_usb11, + atest_gpsadc0, edp_hot, atest_usb10, m_voc, dac_gpio, atest_char, + cam_mclk, pll_bypassnl, qdss_stm7, blsp_i2c8, qdss_tracedata_b, + pll_reset, qdss_stm6, qdss_stm5, qdss_stm4, atest_usb2, cci_i2c, + qdss_stm3, dac_calib3, atest_usb23, atest_char3, dac_calib4, + qdss_stm2, atest_usb22, atest_char2, qdss_stm1, dac_calib5, + atest_usb21, atest_char1, dbg_out, qdss_stm0, dac_calib6, + atest_usb20, atest_char0, dac_calib10, qdss_stm10, + qdss_cti_trig_in_a, cci_timer4, blsp_spi6, blsp_uart6, blsp_uim6, + blsp2_spi, qdss_stm9, qdss_cti_trig_out_a, dac_calib11, + qdss_stm8, cci_timer0, qdss_stm13, dac_calib7, cci_timer1, + qdss_stm12, dac_calib8, cci_timer2, blsp1_spi, qdss_stm11, + dac_calib9, cci_timer3, cci_async, dac_calib12, blsp_i2c6, + qdss_tracectl_a, dac_calib13, qdss_traceclk_a, dac_calib14, + dac_calib15, hdmi_rcv, dac_calib16, hdmi_cec, pwr_modem, + dac_calib17, hdmi_ddc, pwr_nav, dac_calib18, pwr_crypto, + dac_calib19, hdmi_hot, dac_calib20, dac_calib21, pci_e0, + dac_calib22, dac_calib23, dac_calib24, tsif1_sync, dac_calib25, + sd_write, tsif1_error, blsp_spi2, blsp_uart2, blsp_uim2, + qdss_cti, blsp_i2c2, blsp_spi3, blsp_uart3, blsp_uim3, blsp_i2c3, + uim3, blsp_spi9, blsp_uart9, blsp_uim9, blsp10_spi, blsp_i2c9, + blsp_spi7, blsp_uart7, blsp_uim7, qdss_tracedata_a, blsp_i2c7, + qua_mi2s, gcc_gp1_clk_a, ssc_irq, uim4, blsp_spi11, blsp_uart11, + blsp_uim11, gcc_gp2_clk_a, gcc_gp3_clk_a, blsp_i2c11, cri_trng0, + cri_trng1, cri_trng, qdss_stm18, pri_mi2s, qdss_stm17, blsp_spi4, + blsp_uart4, blsp_uim4, qdss_stm16, qdss_stm15, blsp_i2c4, + qdss_stm14, dac_calib26, spkr_i2s, audio_ref, lpass_slimbus, + isense_dbg, tsense_pwm1, tsense_pwm2, btfm_slimbus, ter_mi2s, + qdss_stm22, qdss_stm21, qdss_stm20, qdss_stm19, gcc_gp1_clk_b, + sec_mi2s, blsp_spi5, blsp_uart5, blsp_uim5, gcc_gp2_clk_b, + gcc_gp3_clk_b, blsp_i2c5, blsp_spi12, blsp_uart12, blsp_uim12, + qdss_stm25, qdss_stm31, blsp_i2c12, qdss_stm30, qdss_stm29, + tsif1_clk, qdss_stm28, tsif1_en, tsif1_data, sdc4_cmd, qdss_stm27, + qdss_traceclk_b, tsif2_error, sdc43, vfr_1, qdss_stm26, tsif2_clk, + sdc4_clk, qdss_stm24, tsif2_en, sdc42, qdss_stm23, qdss_tracectl_b, + sd_card, tsif2_data, sdc41, tsif2_sync, sdc40, mdp_vsync_p_b, + ldo_en, mdp_vsync_s_b, ldo_update, blsp11_uart_tx_b, blsp11_uart_rx_b, + blsp11_i2c_sda_b, prng_rosc, blsp11_i2c_scl_b, uim2, uim1, uim_batt, + pci_e2, pa_indicator, adsp_ext, ddr_bist, qdss_tracedata_11, + qdss_tracedata_12, modem_tsync, nav_dr, nav_pps, pci_e1, gsm_tx, + qspi_cs, ssbi2, ssbi1, mss_lte, qspi_clk, qspi0, qspi1, qspi2, qspi3, + gpio + +- bias-disable: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as no pull. + +- bias-pull-down: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as pull down. + +- bias-pull-up: + Usage: optional + Value type: <none> + Definition: The specified pins should be configued as pull up. + +- output-high: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + high. + Not valid for sdc pins. + +- output-low: + Usage: optional + Value type: <none> + Definition: The specified pins are configured in output mode, driven + low. + Not valid for sdc pins. + +- drive-strength: + Usage: optional + Value type: <u32> + 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@01010000 { + compatible = "qcom,msm8996-pinctrl"; + reg = <0x01010000 0x300000>; + 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"; + }; + + config { + pins = "gpio4", "gpio5"; + drive-strength = <2>; + bias-disable; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt index 1ae63c0acd40..a90c812ad642 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt @@ -14,6 +14,7 @@ PMIC's from Qualcomm. "qcom,pm8917-gpio" "qcom,pm8921-gpio" "qcom,pm8941-gpio" + "qcom,pm8994-gpio" "qcom,pma8084-gpio" - reg: @@ -79,6 +80,7 @@ to specify in a pin configuration subnode: gpio1-gpio38 for pm8917 gpio1-gpio44 for pm8921 gpio1-gpio36 for pm8941 + gpio1-gpio22 for pm8994 gpio1-gpio22 for pma8084 - function: diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt index d7803a2a94e9..d74e631e10da 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt @@ -15,6 +15,7 @@ of PMIC's from Qualcomm. "qcom,pm8917-mpp", "qcom,pm8921-mpp", "qcom,pm8941-mpp", + "qcom,pm8994-mpp", "qcom,pma8084-mpp", - reg: diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index 9496934528bd..ffadb7a371f6 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -19,6 +19,7 @@ Required Properties: - "renesas,pfc-r8a7791": for R8A7791 (R-Car M2-W) compatible pin-controller. - "renesas,pfc-r8a7793": for R8A7793 (R-Car M2-N) compatible pin-controller. - "renesas,pfc-r8a7794": for R8A7794 (R-Car E2) compatible pin-controller. + - "renesas,pfc-r8a7795": for R8A7795 (R-Car H3) compatible pin-controller. - "renesas,pfc-sh73a0": for SH73A0 (SH-Mobile AG5) compatible pin-controller. - reg: Base address and length of each memory resource used by the pin diff --git a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt index 391ef4be8d50..c68b9554561f 100644 --- a/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/rockchip,pinctrl.txt @@ -21,7 +21,8 @@ defined as gpio sub-nodes of the pinmux controller. Required properties for iomux controller: - compatible: one of "rockchip,rk2928-pinctrl", "rockchip,rk3066a-pinctrl" "rockchip,rk3066b-pinctrl", "rockchip,rk3188-pinctrl" - "rockchip,rk3288-pinctrl", "rockchip,rk3368-pinctrl" + "rockchip,rk3228-pinctrl", "rockchip,rk3288-pinctrl" + "rockchip,rk3368-pinctrl", "rockchip,rk3399-pinctrl" - rockchip,grf: phandle referencing a syscon providing the "general register files" diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt index 9d2a995293e6..6db16b90873a 100644 --- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -17,6 +17,7 @@ Required Properties: - "samsung,exynos4x12-pinctrl": for Exynos4x12 compatible pin-controller. - "samsung,exynos5250-pinctrl": for Exynos5250 compatible pin-controller. - "samsung,exynos5260-pinctrl": for Exynos5260 compatible pin-controller. + - "samsung,exynos5410-pinctrl": for Exynos5410 compatible pin-controller. - "samsung,exynos5420-pinctrl": for Exynos5420 compatible pin-controller. - "samsung,exynos7-pinctrl": for Exynos7 compatible pin-controller. diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt new file mode 100644 index 000000000000..7b4800cc251e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -0,0 +1,126 @@ +* STM32 GPIO and Pin Mux/Config controller + +STMicroelectronics's STM32 MCUs intregrate a GPIO and Pin mux/config hardware +controller. It controls the input/output settings on the available pins and +also provides ability to multiplex and configure the output of various on-chip +controllers onto these pads. + +Pin controller node: +Required properies: + - compatible: value should be one of the following: + (a) "st,stm32f429-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 + gpio-bank node (children). + - pins-are-numbered: Specify the subnodes are using numbered pinmux to + specify pins. + +GPIO controller/bank node: +Required properties: + - gpio-controller : Indicates this device is a GPIO controller + - #gpio-cells : Should be two. + The first cell is the pin number + The second one is the polarity: + - 0 for active high + - 1 for active low + - reg : The gpio address range, relative to the pinctrl range + - clocks : clock that drives this bank + - st,bank-name : Should be a name string for this bank as specified in + the datasheet + +Optional properties: + - reset: : Reference to the reset controller + +Example: +#include <dt-bindings/pinctrl/stm32f429-pinfunc.h> +... + + pin-controller { + #address-cells = <1>; + #size-cells = <1>; + compatible = "st,stm32f429-pinctrl"; + ranges = <0 0x40020000 0x3000>; + pins-are-numbered; + + gpioa: gpio@40020000 { + gpio-controller; + #gpio-cells = <2>; + reg = <0x0 0x400>; + resets = <&reset_ahb1 0>; + st,bank-name = "GPIOA"; + }; + ... + pin-functions nodes follow... + }; + +Contents of function subnode node: +---------------------------------- +Subnode format +A pinctrl node should contain at least one subnode representing the +pinctrl group available on the machine. Each subnode will list the +pins it needs, and how they should be configured, with regard to muxer +configuration, pullups, drive, output high/low and output speed. + + node { + pinmux = <PIN_NUMBER_PINMUX>; + GENERIC_PINCONFIG; + }; + +Required properties: +- pinmux: integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are defined in + dt-bindings/pinctrl/<soc>-pinfunc.h directly. + These defines are calculated as: + ((port * 16 + line) << 8) | function + With: + - port: The gpio port index (PA = 0, PB = 1, ..., PK = 11) + - line: The line offset within the port (PA0 = 0, PA1 = 1, ..., PA15 = 15) + - function: The function number, can be: + * 0 : GPIO + * 1 : Alternate Function 0 + * 2 : Alternate Function 1 + * 3 : Alternate Function 2 + * ... + * 16 : Alternate Function 15 + * 17 : Analog + +Optional properties: +- GENERIC_PINCONFIG: is the generic pinconfig options to use. + Available options are: + - bias-disable, + - bias-pull-down, + - bias-pull-up, + - drive-push-pull, + - drive-open-drain, + - output-low + - output-high + - slew-rate = <x>, with x being: + < 0 > : Low speed + < 1 > : Medium speed + < 2 > : Fast speed + < 3 > : High speed + +Example: + +pin-controller { +... + usart1_pins_a: usart1@0 { + pins1 { + pinmux = <STM32F429_PA9_FUNC_USART1_TX>; + bias-disable; + drive-push-pull; + slew-rate = <0>; + }; + pins2 { + pinmux = <STM32F429_PA10_FUNC_USART1_RX>; + bias-disable; + }; + }; +}; + +&usart1 { + pinctrl-0 = <&usart1_pins_a>; + pinctrl-names = "default"; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/power/act8945a-charger.txt b/Documentation/devicetree/bindings/power/act8945a-charger.txt new file mode 100644 index 000000000000..bea254c9d136 --- /dev/null +++ b/Documentation/devicetree/bindings/power/act8945a-charger.txt @@ -0,0 +1,35 @@ +Device-Tree bindings for charger of Active-semi ACT8945A Multi-Function Device + +Required properties: + - compatible: "active-semi,act8945a", please refer to ../mfd/act8945a.txt. + - active-semi,chglev-gpios: charge current level phandle with args + as described in ../gpio/gpio.txt. + +Optional properties: + - active-semi,check-battery-temperature: boolean to check the battery + temperature or not. + - active-semi,input-voltage-threshold-microvolt: unit: mV; + Specifies the charger's input over-voltage threshold value; + The value can be: 6600, 7000, 7500, 8000; default: 6600 + - active-semi,precondition-timeout: unit: minutes; + Specifies the charger's PRECONDITION safety timer setting value; + The value can be: 40, 60, 80, 0; If 0, it means to disable this timer; + default: 40. + - active-semi,total-timeout: unit: hours; + Specifies the charger's total safety timer setting value; + The value can be: 3, 4, 5, 0; If 0, it means to disable this timer; + default: 3. + +Example: + pmic@5b { + compatible = "active-semi,act8945a"; + reg = <0x5b>; + status = "okay"; + + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_charger_chglev>; + active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; + active-semi,input-voltage-threshold-microvolt = <6600>; + active-semi,precondition-timeout = <40>; + active-semi,total-timeout = <3>; + }; diff --git a/Documentation/devicetree/bindings/power/bq24257.txt b/Documentation/devicetree/bindings/power/bq24257.txt index 5c9d3940d07c..d693702c9c1e 100644 --- a/Documentation/devicetree/bindings/power/bq24257.txt +++ b/Documentation/devicetree/bindings/power/bq24257.txt @@ -1,21 +1,64 @@ -Binding for TI bq24257 Li-Ion Charger +Binding for TI bq24250/bq24251/bq24257 Li-Ion Charger Required properties: - compatible: Should contain one of the following: + * "ti,bq24250" + * "ti,bq24251" * "ti,bq24257" -- reg: integer, i2c address of the device. +- reg: integer, i2c address of the device. +- interrupt-parent: Should be the phandle for the interrupt controller. Use in + conjunction with "interrupts". +- interrupts: Interrupt mapping for GPIO IRQ (configure for both edges). Use in + conjunction with "interrupt-parent". - ti,battery-regulation-voltage: integer, maximum charging voltage in uV. -- ti,charge-current: integer, maximum charging current in uA. -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in uA). +- ti,charge-current: integer, maximum charging current in uA. +- ti,termination-current: integer, charge will be terminated when current in + constant-voltage phase drops below this value (in uA). + +Optional properties: +- pg-gpios: GPIO used for connecting the bq2425x device PG (Power Good) pin. + This pin is not available on all devices however it should be used if + possible as this is the recommended way to obtain the charger's input PG + state. If this pin is not specified a software-based approach for PG + detection is used. +- ti,current-limit: The maximum current to be drawn from the charger's input + (in uA). If this property is not specified, the input limit current is + set automatically using USB D+/D- signal based charger type detection. + If the hardware does not support the D+/D- based detection, a default + of 500,000 is used (=500mA) instead. +- ti,ovp-voltage: Configures the over voltage protection voltage (in uV). If + not specified a default of 6,5000,000 (=6.5V) is used. +- ti,in-dpm-voltage: Configures the threshold input voltage for the dynamic + power path management (in uV). If not specified a default of 4,360,000 + (=4.36V) is used. Example: bq24257 { compatible = "ti,bq24257"; reg = <0x6a>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_BOTH>; + + pg-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; ti,battery-regulation-voltage = <4200000>; ti,charge-current = <1000000>; ti,termination-current = <50000>; }; + +Example: + +bq24250 { + compatible = "ti,bq24250"; + reg = <0x6a>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_BOTH>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <500000>; + ti,termination-current = <50000>; + ti,current-limit = <900000>; + ti,ovp-voltage = <9500000>; + ti,in-dpm-voltage = <4440000>; +}; diff --git a/Documentation/devicetree/bindings/power/da9150-fg.txt b/Documentation/devicetree/bindings/power/da9150-fg.txt new file mode 100644 index 000000000000..00236fe3ea31 --- /dev/null +++ b/Documentation/devicetree/bindings/power/da9150-fg.txt @@ -0,0 +1,23 @@ +Dialog Semiconductor DA9150 Fuel-Gauge Power Supply bindings + +Required properties: +- compatible: "dlg,da9150-fuel-gauge" for DA9150 Fuel-Gauge Power Supply + +Optional properties: +- dlg,update-interval: Interval time (milliseconds) between battery level checks. +- dlg,warn-soc-level: Battery discharge level (%) where warning event raised. + [1 - 100] +- dlg,crit-soc-level: Battery discharge level (%) where critical event raised. + This value should be lower than the warning level. + [1 - 100] + + +Example: + + fuel-gauge { + compatible = "dlg,da9150-fuel-gauge"; + + dlg,update-interval = <10000>; + dlg,warn-soc-level = /bits/ 8 <15>; + dlg,crit-soc-level = /bits/ 8 <5>; + }; diff --git a/Documentation/devicetree/bindings/arm/exynos/power_domain.txt b/Documentation/devicetree/bindings/power/pd-samsung.txt index e151057d92f0..4e947372a693 100644 --- a/Documentation/devicetree/bindings/arm/exynos/power_domain.txt +++ b/Documentation/devicetree/bindings/power/pd-samsung.txt @@ -43,9 +43,8 @@ Example: mfc_pd: power-domain@10044060 { compatible = "samsung,exynos4210-pd"; reg = <0x10044060 0x20>; - clocks = <&clock CLK_FIN_PLL>, <&clock CLK_MOUT_SW_ACLK333>, - <&clock CLK_MOUT_USER_ACLK333>; - clock-names = "oscclk", "pclk0", "clk0"; + clocks = <&clock CLK_FIN_PLL>, <&clock CLK_MOUT_USER_ACLK333>; + clock-names = "oscclk", "clk0"; #power-domain-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/power/wakeup-source.txt b/Documentation/devicetree/bindings/power/wakeup-source.txt new file mode 100644 index 000000000000..963c6dfd484d --- /dev/null +++ b/Documentation/devicetree/bindings/power/wakeup-source.txt @@ -0,0 +1,71 @@ +Specifying wakeup capability for devices +============================================ + +Any device nodes +---------------- +Nodes that describe devices which has wakeup capability must contain an +"wakeup-source" boolean property. + +Also, if device is marked as a wakeup source, then all the primary +interrupt(s) can be used as wakeup interrupt(s). + +However if the devices have dedicated interrupt as the wakeup source +then they need to specify/identify the same using device specific +interrupt name. In such cases only that interrupt can be used as wakeup +interrupt. + +List of legacy properties and respective binding document +--------------------------------------------------------- + +1. "enable-sdio-wakeup" Documentation/devicetree/bindings/mmc/mmc.txt +2. "gpio-key,wakeup" Documentation/devicetree/bindings/input/gpio-keys{,-polled}.txt +3. "has-tpo" Documentation/devicetree/bindings/rtc/rtc-opal.txt +4. "isil,irq2-can-wakeup-machine" Documentation/devicetree/bindings/rtc/isil,isl12057.txt +5. "linux,wakeup" Documentation/devicetree/bindings/input/gpio-matrix-keypad.txt + Documentation/devicetree/bindings/mfd/tc3589x.txt + Documentation/devicetree/bindings/input/ads7846.txt +6. "linux,keypad-wakeup" Documentation/devicetree/bindings/input/qcom,pm8xxx-keypad.txt +7. "linux,input-wakeup" Documentation/devicetree/bindings/input/samsung-keypad.txt +8. "nvidia,wakeup-source" Documentation/devicetree/bindings/input/nvidia,tegra20-kbc.txt + +Examples +-------- + +1. With "wakeup" interrupt name + + device@10000 { + compatible = "vendor,device-id"; + reg = <0x10000 0x1000>; + interrupts = <0 19 4>, <0 21 4>, <0 22 4>; + interrupt-names = "ack", "err", "wakeup"; + wakeup-source; + }; + +2. Without "wakeup" interrupt name + + embedded-controller { + compatible = "google,cros-ec-i2c"; + reg = <0x1e>; + interrupts = <6 0>; + interrupt-parent = <&gpx1>; + pinctrl-names = "default"; + pinctrl-0 = <&ec_irq>; + wakeup-source; + }; + +3. Without interrupts + + gpio_keys { + compatible = "gpio-keys"; + #address-cells = <1>; + #size-cells = <0>; + + button@1 { + debounce_interval = <50>; + wakeup-source; + linux,code = <116>; + label = "POWER"; + gpios = <&iofpga_gpio0 0 0x4>; + }; + [....] + }; diff --git a/Documentation/devicetree/bindings/power_supply/axp20x_usb_power.txt b/Documentation/devicetree/bindings/power_supply/axp20x_usb_power.txt new file mode 100644 index 000000000000..862f4a49dc49 --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/axp20x_usb_power.txt @@ -0,0 +1,34 @@ +AXP20x USB power supply + +Required Properties: +-compatible: "x-powers,axp202-usb-power-supply" + +This node is a subnode of the axp20x PMIC. + +Example: + +axp209: pmic@34 { + compatible = "x-powers,axp209"; + reg = <0x34>; + interrupt-parent = <&nmi_intc>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <1>; + + regulators { + x-powers,dcdc-freq = <1500>; + + vdd_cpu: dcdc2 { + regulator-always-on; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1450000>; + regulator-name = "vdd-cpu"; + }; + + ... + }; + + usb-power-supply: usb-power-supply { + compatible = "x-powers,axp202-usb-power-supply"; + }; +}; diff --git a/Documentation/devicetree/bindings/power_supply/qcom_smbb.txt b/Documentation/devicetree/bindings/power_supply/qcom_smbb.txt new file mode 100644 index 000000000000..65b88fac854b --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/qcom_smbb.txt @@ -0,0 +1,131 @@ +Qualcomm Switch-Mode Battery Charger and Boost + +PROPERTIES +- compatible: + Usage: required + Value type: <stringlist> + Description: Must be one of: + - "qcom,pm8941-charger" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Description: Base address of registers for SMBB block + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Description: The format of the specifier is defined by the binding document + describing the node's interrupt parent. Must contain one + specifier for each of the following interrupts, in order: + - charge done + - charge fast mode + - charge trickle mode + - battery temperature ok + - battery present + - charger disconnected + - USB-in valid + - DC-in valid + +- interrupt-names: + Usage: required + Value type: <stringlist> + Description: Must contain the following list, strictly ordered: + "chg-done", + "chg-fast", + "chg-trkl", + "bat-temp-ok", + "bat-present", + "chg-gone", + "usb-valid", + "dc-valid" + +- qcom,fast-charge-current-limit: + Usage: optional (default: 1A, or pre-configured value) + Value type: <u32>; uA; range [100mA : 3A] + Description: Maximum charge current; May be clamped to safety limits. + +- qcom,fast-charge-low-threshold-voltage: + Usage: optional (default: 3.2V, or pre-configured value) + Value type: <u32>; uV; range [2.1V : 3.6V] + Description: Battery voltage limit above which fast charging may operate; + Below this value linear or switch-mode auto-trickle-charging + will operate. + +- qcom,fast-charge-high-threshold-voltage: + Usage: optional (default: 4.2V, or pre-configured value) + Value type: <u32>; uV; range [3.24V : 5V] + Description: Battery voltage limit below which fast charging may operate; + The fast charger will attempt to charge the battery to this + voltage. May be clamped to safety limits. + +- qcom,fast-charge-safe-voltage: + Usage: optional (default: 4.2V, or pre-configured value) + Value type: <u32>; uV; range [3.24V : 5V] + Description: Maximum safe battery voltage; May be pre-set by bootloader, in + which case, setting this will harmlessly fail. The property + 'fast-charge-high-watermark' will be clamped by this value. + +- qcom,fast-charge-safe-current: + Usage: optional (default: 1A, or pre-configured value) + Value type: <u32>; uA; range [100mA : 3A] + Description: Maximum safe battery charge current; May pre-set by bootloader, + in which case, setting this will harmlessly fail. The property + 'qcom,fast-charge-current-limit' will be clamped by this value. + +- qcom,auto-recharge-threshold-voltage: + Usage: optional (default: 4.1V, or pre-configured value) + Value type: <u32>; uV; range [3.24V : 5V] + Description: Battery voltage limit below which auto-recharge functionality + will restart charging after end-of-charge; The high cutoff + limit for auto-recharge is 5% above this value. + +- qcom,minimum-input-voltage: + Usage: optional (default: 4.3V, or pre-configured value) + Value type: <u32>; uV; range [4.2V : 9.6V] + Description: Input voltage level above which charging may operate + +- qcom,dc-current-limit: + Usage: optional (default: 100mA, or pre-configured value) + Value type: <u32>; uA; range [100mA : 2.5A] + Description: Default DC charge current limit + +- qcom,disable-dc: + Usage: optional (default: false) + Value type: boolean: <u32> or <empty> + Description: Disable DC charger + +- qcom,jeita-extended-temp-range: + Usage: optional (default: false) + Value type: boolean: <u32> or <empty> + Description: Enable JEITA extended temperature range; This does *not* + adjust the maximum charge voltage or current in the extended + temperature range. It only allows charging when the battery + is in the extended temperature range. Voltage/current + regulation must be done externally to fully comply with + the JEITA safety guidelines if this flag is set. + +EXAMPLE +charger@1000 { + compatible = "qcom,pm8941-charger"; + reg = <0x1000 0x700>; + interrupts = <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 4 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x14 1 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "chg-done", + "chg-fast", + "chg-trkl", + "bat-temp-ok", + "bat-present", + "chg-gone", + "usb-valid", + "dc-valid"; + + qcom,fast-charge-current-limit = <1000000>; + qcom,dc-charge-current-limit = <1000000>; +}; diff --git a/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt b/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt index 4f6a550184d0..3bf55757ceec 100644 --- a/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt +++ b/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt @@ -22,6 +22,9 @@ Optional properties : value must be between 128mA and 8.064A with a 128mA step resolution. The POR value is 0x1000h. This number is in mA (e.g. 8064), see the spec for more information about the InputCurrent (0x3fh) register. + - ti,external-control : Indicates that the charger is configured externally + and that the host should not attempt to enable/disable charging or set the + charge voltage/current. Example: diff --git a/Documentation/devicetree/bindings/power_supply/tps65217_charger.txt b/Documentation/devicetree/bindings/power_supply/tps65217_charger.txt new file mode 100644 index 000000000000..98d131acee95 --- /dev/null +++ b/Documentation/devicetree/bindings/power_supply/tps65217_charger.txt @@ -0,0 +1,12 @@ +TPS65217 Charger + +Required Properties: +-compatible: "ti,tps65217-charger" + +This node is a subnode of the tps65217 PMIC. + +Example: + + tps65217-charger { + compatible = "ti,tps65090-charger"; + }; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/fman.txt b/Documentation/devicetree/bindings/powerpc/fsl/fman.txt index 1fc5328c0651..55c2c03fc81e 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/fman.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/fman.txt @@ -315,6 +315,16 @@ PROPERTIES Value type: <phandle> Definition: A phandle for 1EEE1588 timer. +- pcsphy-handle + Usage required for "fsl,fman-memac" MACs + Value type: <phandle> + Definition: A phandle for pcsphy. + +- tbi-handle + Usage required for "fsl,fman-dtsec" MACs + Value type: <phandle> + Definition: A phandle for tbiphy. + EXAMPLE fman1_tx28: port@a8000 { @@ -340,6 +350,7 @@ ethernet@e0000 { reg = <0xe0000 0x1000>; fsl,fman-ports = <&fman1_rx8 &fman1_tx28>; ptp-timer = <&ptp-timer>; + tbi-handle = <&tbi0>; }; ============================================================================ @@ -415,6 +426,13 @@ PROPERTIES The settings and programming routines for internal/external MDIO are different. Must be included for internal MDIO. +For internal PHY device on internal mdio bus, a PHY node should be created. +See the definition of the PHY node in booting-without-of.txt for an +example of how to define a PHY (Internal PHY has no interrupt line). +- For "fsl,fman-mdio" compatible internal mdio bus, the PHY is TBI PHY. +- For "fsl,fman-memac-mdio" compatible internal mdio bus, the PHY is PCS PHY, + PCS PHY addr must be '0'. + EXAMPLE Example for FMan v2 external MDIO: @@ -425,12 +443,29 @@ mdio@f1000 { interrupts = <101 2 0 0>; }; +Example for FMan v2 internal MDIO: + +mdio@e3120 { + compatible = "fsl,fman-mdio"; + reg = <0xe3120 0xee0>; + fsl,fman-internal-mdio; + + tbi1: tbi-phy@8 { + reg = <0x8>; + device_type = "tbi-phy"; + }; +}; + Example for FMan v3 internal MDIO: mdio@f1000 { compatible = "fsl,fman-memac-mdio"; reg = <0xf1000 0x1000>; fsl,fman-internal-mdio; + + pcsphy6: ethernet-phy@0 { + reg = <0x0>; + }; }; ============================================================================= @@ -568,6 +603,7 @@ fman@400000 { cell-index = <0>; reg = <0xe0000 0x1000>; fsl,fman-ports = <&fman1_rx_0x8 &fman1_tx_0x28>; + tbi-handle = <&tbi5>; }; ethernet@e2000 { @@ -575,6 +611,7 @@ fman@400000 { cell-index = <1>; reg = <0xe2000 0x1000>; fsl,fman-ports = <&fman1_rx_0x9 &fman1_tx_0x29>; + tbi-handle = <&tbi6>; }; ethernet@e4000 { @@ -582,6 +619,7 @@ fman@400000 { cell-index = <2>; reg = <0xe4000 0x1000>; fsl,fman-ports = <&fman1_rx_0xa &fman1_tx_0x2a>; + tbi-handle = <&tbi7>; }; ethernet@e6000 { @@ -589,6 +627,7 @@ fman@400000 { cell-index = <3>; reg = <0xe6000 0x1000>; fsl,fman-ports = <&fman1_rx_0xb &fman1_tx_0x2b>; + tbi-handle = <&tbi8>; }; ethernet@e8000 { @@ -596,6 +635,7 @@ fman@400000 { cell-index = <4>; reg = <0xf0000 0x1000>; fsl,fman-ports = <&fman1_rx_0xc &fman1_tx_0x2c>; + tbi-handle = <&tbi9>; ethernet@f0000 { cell-index = <8>; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/mpc512x_lpbfifo.txt b/Documentation/devicetree/bindings/powerpc/fsl/mpc512x_lpbfifo.txt new file mode 100644 index 000000000000..b3b392fe1f61 --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/fsl/mpc512x_lpbfifo.txt @@ -0,0 +1,21 @@ +Freescale MPC512x LocalPlus Bus FIFO (called SCLPC in the Reference Manual) + +Required properties: +- compatible: should be "fsl,mpc512x-lpbfifo"; +- reg: should contain the offset and length of SCLPC register set; +- interrupts: should contain the interrupt specifier for SCLPC; syntax of an + interrupt client node is described in interrupt-controller/interrupts.txt; +- dmas: should contain the DMA specifier for SCLPC as described at + dma/dma.txt and dma/mpc512x-dma.txt; +- dma-names: should be "rx-tx"; + +Example: + + sclpc@10100 { + compatible = "fsl,mpc512x-lpbfifo"; + reg = <0x10100 0x50>; + interrupts = <7 0x8>; + dmas = <&dma0 26>; + dma-names = "rx-tx"; + }; + diff --git a/Documentation/devicetree/bindings/property-units.txt b/Documentation/devicetree/bindings/property-units.txt new file mode 100644 index 000000000000..12278d79f6c0 --- /dev/null +++ b/Documentation/devicetree/bindings/property-units.txt @@ -0,0 +1,39 @@ +Standard Unit Suffixes for Property names + +Properties which have a unit of measure are recommended to have a unit +suffix appended to the property name. The list below contains the +recommended suffixes. Other variations exist in bindings, but should not +be used in new bindings or added here. The inconsistency in the unit +prefixes is due to selecting the most commonly used variants. + +It is also recommended to use the units listed here and not add additional +unit prefixes. + +Time/Frequency +---------------------------------------- +-mhz : megahertz +-hz : Hertz (preferred) +-sec : seconds +-ms : milliseconds +-us : microseconds +-ns : nanoseconds + +Distance +---------------------------------------- +-mm : millimeters + +Electricity +---------------------------------------- +-microamp : micro amps +-ohms : Ohms +-micro-ohms : micro Ohms +-microvolt : micro volts + +Temperature +---------------------------------------- +-celsius : Degrees Celsius +-millicelsius : Degreee milli-Celsius + +Pressure +---------------------------------------- +-kpascal : kiloPascal diff --git a/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.txt b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.txt new file mode 100644 index 000000000000..d9254a6da5ed --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/brcm,bcm7038-pwm.txt @@ -0,0 +1,20 @@ +Broadcom BCM7038 PWM controller (BCM7xxx Set Top Box PWM controller) + +Required properties: + +- compatible: must be "brcm,bcm7038-pwm" +- reg: physical base address and length for this controller +- #pwm-cells: should be 2. See pwm.txt in this directory for a description + of the cells format +- clocks: a phandle to the reference clock for this block which is fed through + its internal variable clock frequency generator + + +Example: + + pwm: pwm@f0408000 { + compatible = "brcm,bcm7038-pwm"; + reg = <0xf0408000 0x28>; + #pwm-cells = <2>; + clocks = <&upg_fixed>; + }; diff --git a/Documentation/devicetree/bindings/pwm/lpc32xx-pwm.txt b/Documentation/devicetree/bindings/pwm/lpc32xx-pwm.txt index cfe1db3bb6e9..74b5bc5dd19a 100644 --- a/Documentation/devicetree/bindings/pwm/lpc32xx-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/lpc32xx-pwm.txt @@ -6,7 +6,12 @@ Required properties: Examples: -pwm@0x4005C000 { +pwm@4005c000 { compatible = "nxp,lpc3220-pwm"; - reg = <0x4005C000 0x8>; + reg = <0x4005c000 0x4>; +}; + +pwm@4005c004 { + compatible = "nxp,lpc3220-pwm"; + reg = <0x4005c004 0x4>; }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-berlin.txt b/Documentation/devicetree/bindings/pwm/pwm-berlin.txt new file mode 100644 index 000000000000..82cbe16fcbbc --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-berlin.txt @@ -0,0 +1,17 @@ +Berlin PWM controller + +Required properties: +- compatible: should be "marvell,berlin-pwm" +- reg: physical base address and length of the controller's registers +- clocks: phandle to the input clock +- #pwm-cells: should be 3. See pwm.txt in this directory for a description of + the cells format. + +Example: + +pwm: pwm@f7f20000 { + compatible = "marvell,berlin-pwm"; + reg = <0xf7f20000 0x40>; + clocks = <&chip_clk CLKID_CFG>; + #pwm-cells = <3>; +} diff --git a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt new file mode 100644 index 000000000000..f8f59baf6b67 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt @@ -0,0 +1,42 @@ +MediaTek display PWM controller + +Required properties: + - compatible: should be "mediatek,<name>-disp-pwm": + - "mediatek,mt8173-disp-pwm": found on mt8173 SoC. + - "mediatek,mt6595-disp-pwm": found on mt6595 SoC. + - reg: physical base address and length of the controller's registers. + - #pwm-cells: must be 2. See pwm.txt in this directory for a description of + the cell format. + - clocks: phandle and clock specifier of the PWM reference clock. + - clock-names: must contain the following: + - "main": clock used to generate PWM signals. + - "mm": sync signals from the modules of mmsys. + - pinctrl-names: Must contain a "default" entry. + - pinctrl-0: One property must exist for each entry in pinctrl-names. + See pinctrl/pinctrl-bindings.txt for details of the property values. + +Example: + pwm0: pwm@1401e000 { + compatible = "mediatek,mt8173-disp-pwm", + "mediatek,mt6595-disp-pwm"; + reg = <0 0x1401e000 0 0x1000>; + #pwm-cells = <2>; + clocks = <&mmsys CLK_MM_DISP_PWM026M>, + <&mmsys CLK_MM_DISP_PWM0MM>; + clock-names = "main", "mm"; + pinctrl-names = "default"; + pinctrl-0 = <&disp_pwm0_pins>; + }; + + backlight_lcd: backlight_lcd { + compatible = "pwm-backlight"; + pwms = <&pwm0 0 1000000>; + brightness-levels = < + 0 16 32 48 64 80 96 112 + 128 144 160 176 192 208 224 240 + 255 + >; + default-brightness-level = <9>; + power-supply = <&mt6397_vio18_reg>; + enable-gpios = <&pio 95 GPIO_ACTIVE_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt b/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt new file mode 100644 index 000000000000..5befb538db95 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-omap-dmtimer.txt @@ -0,0 +1,18 @@ +* OMAP PWM for dual-mode timers + +Required properties: +- compatible: Shall contain "ti,omap-dmtimer-pwm". +- ti,timers: phandle to PWM capable OMAP timer. See arm/omap/timer.txt for info + about these timers. +- #pwm-cells: Should be 3. See pwm.txt in this directory for a description of + the cells format. + +Optional properties: +- ti,prescaler: Should be a value between 0 and 7, see the timers datasheet + +Example: + pwm9: dmtimer-pwm@9 { + compatible = "ti,omap-dmtimer-pwm"; + ti,timers = <&timer9>; + #pwm-cells = <3>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt index ae0273e19506..cf6068b8e974 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt @@ -3,6 +3,8 @@ Allwinner sun4i and sun7i SoC PWM controller Required properties: - compatible: should be one of: - "allwinner,sun4i-a10-pwm" + - "allwinner,sun5i-a10s-pwm" + - "allwinner,sun5i-a13-pwm" - "allwinner,sun7i-a20-pwm" - reg: physical base address and length of the controller's registers - #pwm-cells: should be 3. See pwm.txt in this directory for a description of diff --git a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt new file mode 100644 index 000000000000..0822a083fc57 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt @@ -0,0 +1,26 @@ +* Renesas R-Car PWM Timer Controller + +Required Properties: +- compatible: should be "renesas,pwm-rcar" and one of the following. + - "renesas,pwm-r8a7778": for R-Car M1A + - "renesas,pwm-r8a7779": for R-Car H1 + - "renesas,pwm-r8a7790": for R-Car H2 + - "renesas,pwm-r8a7791": for R-Car M2-W + - "renesas,pwm-r8a7794": for R-Car E2 +- reg: base address and length of the registers block for the PWM. +- #pwm-cells: should be 2. See pwm.txt in this directory for a description of + the cells format. +- clocks: clock phandle and specifier pair. +- pinctrl-0: phandle, referring to a default pin configuration node. +- pinctrl-names: Set to "default". + +Example: R8A7790 (R-Car H2) PWM Timer node + + pwm0: pwm@e6e30000 { + compatible = "renesas,pwm-r8a7790", "renesas,pwm-rcar"; + reg = <0 0xe6e30000 0 0x8>; + #pwm-cells = <2>; + clocks = <&mstp5_clks R8A7790_CLK_PWM>; + pinctrl-0 = <&pwm0_pins>; + pinctrl-names = "default"; + }; diff --git a/Documentation/devicetree/bindings/regmap/regmap.txt b/Documentation/devicetree/bindings/regmap/regmap.txt index b494f8b8ef72..e98a9652ccc8 100644 --- a/Documentation/devicetree/bindings/regmap/regmap.txt +++ b/Documentation/devicetree/bindings/regmap/regmap.txt @@ -5,15 +5,18 @@ Index Device Endianness properties --------------------------------------------------- 1 BE 'big-endian' 2 LE 'little-endian' +3 Native 'native-endian' For one device driver, which will run in different scenarios above on different SoCs using the devicetree, we need one way to simplify this. -Required properties: -- {big,little}-endian: these are boolean properties, if absent - meaning that the CPU and the Device are in the same endianness mode, - these properties are for register values and all the buffers only. +Optional properties: +- {big,little,native}-endian: these are boolean properties, if absent + then the implementation will choose a default based on the device + being controlled. These properties are for register values and all + the buffers only. Native endian means that the CPU and device have + the same endianness. Examples: Scenario 1 : CPU in LE mode & device in LE mode. diff --git a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt index e91485d11241..6067d9830d07 100644 --- a/Documentation/devicetree/bindings/regulator/act8865-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/act8865-regulator.txt @@ -8,6 +8,8 @@ Required properties: Optional properties: - system-power-controller: Telling whether or not this pmic is controlling the system power. See Documentation/devicetree/bindings/power/power-controller.txt . +- active-semi,vsel-high: Indicates the VSEL pin is high. + If this property is missing, assume the VSEL pin is low(0). Optional input supply properties: - for act8600: @@ -49,6 +51,7 @@ Example: pmic: act8865@5b { compatible = "active-semi,act8865"; reg = <0x5b>; + active-semi,vsel-high; status = "disabled"; regulators { diff --git a/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt b/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt new file mode 100644 index 000000000000..5c80a7779552 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt @@ -0,0 +1,80 @@ +Device-Tree bindings for regulators of Active-semi ACT8945A Multi-Function Device + +Required properties: + - compatible: "active-semi,act8945a", please refer to ../mfd/act8945a.txt. + +Optional properties: +- active-semi,vsel-high: Indicates if the VSEL pin is set to logic-high. + If this property is missing, assume the VSEL pin is set to logic-low. + +Optional input supply properties: + - vp1-supply: The input supply for REG_DCDC1 + - vp2-supply: The input supply for REG_DCDC2 + - vp3-supply: The input supply for REG_DCDC3 + - inl45-supply: The input supply for REG_LDO1 and REG_LDO2 + - inl67-supply: The input supply for REG_LDO3 and REG_LDO4 + +Any standard regulator properties can be used to configure the single regulator. + +The valid names for regulators are: + REG_DCDC1, REG_DCDC2, REG_DCDC3, REG_LDO1, REG_LDO2, REG_LDO3, REG_LDO4. + +Example: + pmic@5b { + compatible = "active-semi,act8945a"; + reg = <0x5b>; + status = "okay"; + + active-semi,vsel-high; + + regulators { + vdd_1v35_reg: REG_DCDC1 { + regulator-name = "VDD_1V35"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + }; + + vdd_1v2_reg: REG_DCDC2 { + regulator-name = "VDD_1V2"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1300000>; + regulator-always-on; + }; + + vdd_3v3_reg: REG_DCDC3 { + regulator-name = "VDD_3V3"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vdd_fuse_reg: REG_LDO1 { + regulator-name = "VDD_FUSE"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <2500000>; + regulator-always-on; + }; + + vdd_3v3_lp_reg: REG_LDO2 { + regulator-name = "VDD_3V3_LP"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vdd_led_reg: REG_LDO3 { + regulator-name = "VDD_LED"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-always-on; + }; + + vdd_sdhc_1v8_reg: REG_LDO4 { + regulator-name = "VDD_SDHC_1V8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/anatop-regulator.txt b/Documentation/devicetree/bindings/regulator/anatop-regulator.txt index 758eae24082a..37c4ea076f88 100644 --- a/Documentation/devicetree/bindings/regulator/anatop-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/anatop-regulator.txt @@ -13,6 +13,7 @@ Optional properties: - anatop-delay-reg-offset: Anatop MFD step time register offset - anatop-delay-bit-shift: Bit shift for the step time register - anatop-delay-bit-width: Number of bits used in the step time register +- vin-supply: The supply for this regulator Any property defined as part of the core regulator binding, defined in regulator.txt, can also be used. diff --git a/Documentation/devicetree/bindings/regulator/arizona-regulator.txt b/Documentation/devicetree/bindings/regulator/arizona-regulator.txt new file mode 100644 index 000000000000..443564d7784f --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/arizona-regulator.txt @@ -0,0 +1,17 @@ +Cirrus Logic Arizona class audio SoCs + +These devices are audio SoCs with extensive digital capabilities and a range +of analogue I/O. + +This document lists regulator specific bindings, see the primary binding +document: + ../mfd/arizona.txt + +Optional properties: + - wlf,ldoena : GPIO specifier for the GPIO controlling LDOENA + +Optional subnodes: + - ldo1 : Initial data for the LDO1 regulator, as covered in + Documentation/devicetree/bindings/regulator/regulator.txt + - micvdd : Initial data for the MICVDD regulator, as covered in + Documentation/devicetree/bindings/regulator/regulator.txt diff --git a/Documentation/devicetree/bindings/regulator/hisilicon,hi655x-regulator.txt b/Documentation/devicetree/bindings/regulator/hisilicon,hi655x-regulator.txt new file mode 100644 index 000000000000..14cfdc564159 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/hisilicon,hi655x-regulator.txt @@ -0,0 +1,29 @@ +Hisilicon Hi655x Voltage regulators + +Note: +The Hi655x regulator control is managed by Hi655x PMIC. +So the node of this regulator must be child node of Hi655x +PMIC node. + +The driver uses the regulator core framework, so please also +take the bindings of regulator.txt for reference. + +The valid names for regulators are: + +LDO2_2V8 LDO7_SDIO LDO10_2V85 LDO13_1V8 LDO14_2V8 +LDO15_1V8 LDO17_2V5 LDO19_3V0 LDO21_1V8 LDO22_1V2 + +Example: + pmic: pmic@f8000000 { + compatible = "hisilicon,hi655x-pmic"; + ... + regulators { + ldo2: LDO2@a21 { + regulator-name = "LDO2_2V8"; + regulator-min-microvolt = <2500000>; + regulator-max-microvolt = <3200000>; + regulator-enable-ramp-delay = <120>; + }; + ... + } + } diff --git a/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt b/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt new file mode 100644 index 000000000000..8f14df9d1205 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/lm363x-regulator.txt @@ -0,0 +1,34 @@ +TI LMU LM363x regulator device tree bindings + +LM363x regulator driver supports LM3631 and LM3632. +LM3631 has five regulators and LM3632 supports three regulators. + +Required property: + - compatible: "ti,lm363x-regulator" + +Optional properties: + LM3632 has external enable pins for two LDOs. + - ti,lcm-en1-gpio: A GPIO specifier for Vpos control pin. + - ti,lcm-en2-gpio: A GPIO specifier for Vneg control pin. + +Child nodes: + LM3631 + - vboost + - vcont + - voref + - vpos + - vneg + + LM3632 + - vboost + - vpos + - vneg + + Optional properties of a child node: + Each sub-node should contain the constraints and initialization. + Please refer to [1]. + +Examples: Please refer to ti-lmu dt-bindings [2]. + +[1] ../regulator/regulator.txt +[2] ../mfd/ti-lmu.txt diff --git a/Documentation/devicetree/bindings/regulator/lp872x.txt b/Documentation/devicetree/bindings/regulator/lp872x.txt index 78183182dad9..ca58a68ffdf1 100644 --- a/Documentation/devicetree/bindings/regulator/lp872x.txt +++ b/Documentation/devicetree/bindings/regulator/lp872x.txt @@ -28,6 +28,7 @@ Optional properties: - ti,dvs-gpio: GPIO specifier for external DVS pin control of LP872x devices. - ti,dvs-vsel: DVS selector. 0 = SEL_V1, 1 = SEL_V2. - ti,dvs-state: initial DVS pin state. 0 = DVS_LOW, 1 = DVS_HIGH. + - enable-gpios: GPIO specifier for EN pin control of LP872x devices. Sub nodes for regulator_init_data LP8720 has maximum 6 nodes. (child name: ldo1 ~ 5 and buck) diff --git a/Documentation/devicetree/bindings/regulator/max77802.txt b/Documentation/devicetree/bindings/regulator/max77802.txt index 79e5476444f7..879e98d3b9aa 100644 --- a/Documentation/devicetree/bindings/regulator/max77802.txt +++ b/Documentation/devicetree/bindings/regulator/max77802.txt @@ -8,7 +8,28 @@ regulators that can be controlled over I2C. Following properties should be present in main device node of the MFD chip. -Optional node: +Optional properties: +- inb1-supply: The input supply for BUCK1 +- inb2-supply: The input supply for BUCK2 +- inb3-supply: The input supply for BUCK3 +- inb4-supply: The input supply for BUCK4 +- inb5-supply: The input supply for BUCK5 +- inb6-supply: The input supply for BUCK6 +- inb7-supply: The input supply for BUCK7 +- inb8-supply: The input supply for BUCK8 +- inb9-supply: The input supply for BUCK9 +- inb10-supply: The input supply for BUCK10 +- inl1-supply: The input supply for LDO8 and LDO15 +- inl2-supply: The input supply for LDO17, LDO27, LDO30 and LDO35 +- inl3-supply: The input supply for LDO3, LDO5, LDO6 and LDO7 +- inl4-supply: The input supply for LDO10, LDO11, LDO13 and LDO14 +- inl5-supply: The input supply for LDO9 and LDO19 +- inl6-supply: The input supply for LDO4, LDO21, LDO24 and LDO33 +- inl7-supply: The input supply for LDO18, LDO20, LDO28 and LDO29 +- inl9-supply: The input supply for LDO12, LDO23, LDO25, LDO26, LDO32 and LDO34 +- inl10-supply: The input supply for LDO1 and LDO2 + +Optional nodes: - regulators : The regulators of max77802 have to be instantiated under subnode named "regulators" using the following format. @@ -39,7 +60,7 @@ The possible values for "regulator-initial-mode" and "regulator-mode" are: 1: Normal regulator voltage output mode. 3: Low Power which reduces the quiescent current down to only 1uA -The list of valid modes are defined in the dt-bindings/clock/maxim,max77802.h +The valid modes list is defined in the dt-bindings/regulator/maxim,max77802.h header and can be included by device tree source files. The standard "regulator-mode" property can only be used for regulators that @@ -58,6 +79,8 @@ Example: #address-cells = <1>; #size-cells = <0>; + inb1-supply = <&parent_reg>; + regulators { ldo1_reg: LDO1 { regulator-name = "vdd_1v0"; diff --git a/Documentation/devicetree/bindings/regulator/pv88060.txt b/Documentation/devicetree/bindings/regulator/pv88060.txt new file mode 100644 index 000000000000..10a6dadc008e --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/pv88060.txt @@ -0,0 +1,124 @@ +* Powerventure Semiconductor PV88060 Voltage Regulator + +Required properties: +- compatible: "pvs,pv88060". +- reg: I2C slave address, usually 0x49. +- interrupts: the interrupt outputs of the controller +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name, with valid + values listed below. The content of each sub-node is defined by the + standard binding for regulators; see regulator.txt. + BUCK1, LDO1, LDO2, LDO3, LDO4, LDO5, LDO6, LDO7, SW1, SW2, SW3, SW4, + SW5, and SW6. + +Optional properties: +- Any optional property defined in regulator.txt + +Example + + pmic: pv88060@49 { + compatible = "pvs,pv88060"; + reg = <0x49>; + interrupt-parent = <&gpio>; + interrupts = <24 24>; + + regulators { + BUCK1 { + regulator-name = "buck1"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <4387500>; + regulator-min-microamp = <1496000>; + regulator-max-microamp = <4189000>; + regulator-boot-on; + }; + + LDO1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + LDO2 { + regulator-name = "ldo2"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + LDO3 { + regulator-name = "ldo3"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + LDO4 { + regulator-name = "ldo4"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + LDO5 { + regulator-name = "ldo5"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + LDO6 { + regulator-name = "ldo6"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + LDO7 { + regulator-name = "ldo7"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3350000>; + regulator-boot-on; + }; + + SW1 { + regulator-name = "sw1"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + }; + + SW2 { + regulator-name = "sw2"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-boot-on; + }; + + SW3 { + regulator-name = "sw3"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-boot-on; + }; + + SW4 { + regulator-name = "sw4"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-boot-on; + }; + + SW5 { + regulator-name = "sw5"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-boot-on; + }; + + SW6 { + regulator-name = "sw6"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + }; + }; + };
\ No newline at end of file diff --git a/Documentation/devicetree/bindings/regulator/pv88090.txt b/Documentation/devicetree/bindings/regulator/pv88090.txt new file mode 100644 index 000000000000..e52b2a95cdde --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/pv88090.txt @@ -0,0 +1,65 @@ +* Powerventure Semiconductor PV88090 Voltage Regulator + +Required properties: +- compatible: "pvs,pv88090". +- reg: I2C slave address, usually 0x48. +- interrupts: the interrupt outputs of the controller +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name, with valid + values listed below. The content of each sub-node is defined by the + standard binding for regulators; see regulator.txt. + BUCK1, BUCK2, BUCK3, LDO1, and LDO2. + +Optional properties: +- Any optional property defined in regulator.txt + +Example + + pmic: pv88090@48 { + compatible = "pvs,pv88090"; + reg = <0x48>; + interrupt-parent = <&gpio>; + interrupts = <24 24>; + + regulators { + BUCK1 { + regulator-name = "buck1"; + regulator-min-microvolt = < 600000>; + regulator-max-microvolt = <1393750>; + regulator-min-microamp = < 220000>; + regulator-max-microamp = <7040000>; + regulator-boot-on; + }; + + BUCK2 { + regulator-name = "buck2"; + regulator-min-microvolt = < 600000>; + regulator-max-microvolt = <1393750>; + regulator-min-microamp = <1496000>; + regulator-max-microamp = <4189000>; + }; + + BUCK3 { + regulator-name = "buck3"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1393750>; + regulator-min-microamp = <1496000>; + regulator-max-microamp = <4189000>; + regulator-boot-on; + }; + + LDO1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <4350000>; + regulator-boot-on; + }; + + LDO2 { + regulator-name = "ldo2"; + regulator-min-microvolt = < 650000>; + regulator-max-microvolt = <2225000>; + regulator-boot-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom,smd-rpm.txt b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt index e27f5c4c54fd..1f8d6f84b657 100644 --- a/Documentation/devicetree/bindings/soc/qcom,smd-rpm.txt +++ b/Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt @@ -1,27 +1,17 @@ -Qualcomm Resource Power Manager (RPM) over SMD +QCOM SMD RPM REGULATOR -This driver is used to interface with the Resource Power Manager (RPM) found in -various Qualcomm platforms. The RPM allows each component in the system to vote -for state of the system resources, such as clocks, regulators and bus -frequencies. +The Qualcomm RPM over SMD regulator is modelled as a subdevice of the RPM. +Because SMD is used as the communication transport mechanism, the RPM resides as +a subnode of the SMD. As such, the SMD-RPM regulator requires that the SMD and +RPM nodes be present. -- compatible: - Usage: required - Value type: <string> - Definition: must be one of: - "qcom,rpm-msm8974" +Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd.txt for +information pertaining to the SMD node. -- qcom,smd-channels: - Usage: required - Value type: <stringlist> - Definition: Shared Memory channel used for communication with the RPM +Please refer to Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt for +information regarding the RPM node. -= SUBDEVICES - -The RPM exposes resources to its subnodes. The below bindings specify the set -of valid subnodes that can operate on these resources. - -== Regulators +== Regulator Regulator nodes are identified by their compatible: @@ -30,7 +20,9 @@ Regulator nodes are identified by their compatible: Value type: <string> Definition: must be one of: "qcom,rpm-pm8841-regulators" + "qcom,rpm-pm8916-regulators" "qcom,rpm-pm8941-regulators" + "qcom,rpm-pma8084-regulators" - vdd_s1-supply: - vdd_s2-supply: @@ -48,6 +40,19 @@ Regulator nodes are identified by their compatible: - vdd_s1-supply: - vdd_s2-supply: - vdd_s3-supply: +- vdd_s4-supply: +- vdd_l1_l2_l3-supply: +- vdd_l4_l5_l6-supply: +- vdd_l7-supply: +- vdd_l8_l9_l10_l11_l12_l13_l14_l15_l16_l17_l18-supply: + Usage: optional (pm8916 only) + Value type: <phandle> + Definition: reference to regulator supplying the input pin, as + described in the data sheet + +- vdd_s1-supply: +- vdd_s2-supply: +- vdd_s3-supply: - vdd_l1_l3-supply: - vdd_l2_lvs1_2_3-supply: - vdd_l4_l11-supply: @@ -63,6 +68,35 @@ Regulator nodes are identified by their compatible: Definition: reference to regulator supplying the input pin, as described in the data sheet +- vdd_s1-supply: +- vdd_s2-supply: +- vdd_s3-supply: +- vdd_s4-supply: +- vdd_s5-supply: +- vdd_s6-supply: +- vdd_s7-supply: +- vdd_s8-supply: +- vdd_s9-supply: +- vdd_s10-supply: +- vdd_s11-supply: +- vdd_s12-supply: +- vdd_l1_l11-supply: +- vdd_l2_l3_l4_l27-supply: +- vdd_l5_l7-supply: +- vdd_l6_l12_l14_l15_l26-supply: +- vdd_l8-supply: +- vdd_l9_l10_l13_l20_l23_l24-supply: +- vdd_l16_l25-supply: +- vdd_l17-supply: +- vdd_l18-supply: +- vdd_l19-supply: +- vdd_l21-supply: +- vdd_l22-supply: + Usage: optional (pma8084 only) + Value type: <phandle> + Definition: reference to regulator supplying the input pin, as + described in the data sheet + The regulator node houses sub-nodes for each regulator within the device. Each sub-node is identified using the node's name, with valid values listed for each of the pmics below. @@ -70,11 +104,20 @@ of the pmics below. pm8841: s1, s2, s3, s4, s5, s6, s7, s8 +pm8916: + s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, + l14, l15, l16, l17, l18 + pm8941: s1, s2, s3, s4, l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, l21, l22, l23, l24, lvs1, lvs2, lvs3, 5vs1, 5vs2 +pma8084: + s1, s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, s12, l1, l2, l3, l4, l5, + l6, l7, l8, l9, l10, l11, l12, l13, l14, l15, l16, l17, l18, l19, l20, + l21, l22, l23, l24, l25, l26, l27, lvs1, lvs2, lvs3, lvs4, 5vs1 + The content of each sub-node is defined by the standard binding for regulators - see regulator.txt. @@ -114,4 +157,3 @@ see regulator.txt. }; }; }; - diff --git a/Documentation/devicetree/bindings/regulator/regulator-max77620.txt b/Documentation/devicetree/bindings/regulator/regulator-max77620.txt new file mode 100644 index 000000000000..b3c8ca672024 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/regulator-max77620.txt @@ -0,0 +1,200 @@ +Regulator DT binding for MAX77620 Power management IC from Maxim Semiconductor. + +Device has multiple DCDC(sd[0-3] and LDOs(ldo[0-8]). The input supply +of these regulators are defined under parent device node. +Details of regulator properties are defined as child node under +sub-node "regulators" which is child node of device node. + +Please refer file <Documentation/devicetree/bindings/regulator/regulator.txt> +for common regulator bindings used by client. + +Following are properties of parent node related to regulators. + +Optional properties: +------------------- +The input supply of regulators are the optional properties on the +parent device node. The input supply of these regulators are provided +through following properties: +in-sd0-supply: Input supply for SD0, INA-SD0 or INB-SD0 pins. +in-sd1-supply: Input supply for SD1. +in-sd2-supply: Input supply for SD2. +in-sd3-supply: Input supply for SD3. +in-ldo0-1-supply: Input supply for LDO0 and LDO1. +in-ldo2-supply: Input supply for LDO2. +in-ldo3-5-supply: Input supply for LDO3 and LDO5 +in-ldo4-6-supply: Input supply for LDO4 and LDO6. +in-ldo7-8-supply: Input supply for LDO7 and LDO8. + +Optional sub nodes for regulators under "regulators" subnode: +------------------------------------------------------------ +The subnodes name is the name of regulator and it must be one of: + sd[0-3], ldo[0-8] + +Each sub-node should contain the constraints and initialization +information for that regulator. The definition for each of these +nodes is defined using the standard binding for regulators found at +<Documentation/devicetree/bindings/regulator/regulator.txt>. + +Theres are also additional properties for SD/LDOs. These additional properties +are required to configure FPS configuration parameters for SDs and LDOs. +Please refer <devicetree/bindings/mfd/max77620.txt> for more detail of Flexible +Power Sequence (FPS). +Following are additional properties: + +- maxim,active-fps-source: FPS source for the regulators to get + enabled/disabled when system is in + active state. Valid values are: + - MAX77620_FPS_SRC_0, + FPS source is FPS0. + - MAX77620_FPS_SRC_1, + FPS source is FPS1 + - MAX77620_FPS_SRC_2 and + FPS source is FPS2 + - MAX77620_FPS_SRC_NONE. + Regulator is not controlled + by FPS events and it gets + enabled/disabled by register + access. + Absence of this property will leave + the FPS configuration register for that + regulator to default configuration. + +- maxim,active-fps-power-up-slot: Sequencing event slot number on which + the regulator get enabled when + master FPS input event set to HIGH. + Valid values are 0 to 7. + This is applicable if FPS source is + selected as FPS0, FPS1 or FPS2. + +- maxim,active-fps-power-down-slot: Sequencing event slot number on which + the regulator get disabled when master + FPS input event set to LOW. + Valid values are 0 to 7. + This is applicable if FPS source is + selected as FPS0, FPS1 or FPS2. + +- maxim,suspend-fps-source: This is same as property + "maxim,active-fps-source" but value + get configured when system enters in + to suspend state. + +- maxim,suspend-fps-power-up-slot: This is same as property + "maxim,active-fps-power-up-slot" but + this value get configured into FPS + configuration register when system + enters into suspend. + This is applicable if suspend state + FPS source is selected as FPS0, FPS1 or + +- maxim,suspend-fps-power-down-slot: This is same as property + "maxim,active-fps-power-down-slot" but + this value get configured into FPS + configuration register when system + enters into suspend. + This is applicable if suspend state + FPS source is selected as FPS0, FPS1 or + FPS2. + +Example: +-------- +#include <dt-bindings/mfd/max77620.h> +... +max77620@3c { + in-ldo0-1-supply = <&max77620_sd2>; + in-ldo7-8-supply = <&max77620_sd2>; + regulators { + sd0 { + regulator-name = "vdd-core"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1400000>; + regulator-boot-on; + regulator-always-on; + maxim,active-fps-source = <MAX77620_FPS_SRC_1>; + }; + + sd1 { + regulator-name = "vddio-ddr"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-boot-on; + maxim,active-fps-source = <MAX77620_FPS_SRC_0>; + }; + + sd2 { + regulator-name = "vdd-pre-reg"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <1350000>; + }; + + sd3 { + regulator-name = "vdd-1v8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + regulator-boot-on; + }; + + ldo0 { + regulator-name = "avdd-sys"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + regulator-boot-on; + }; + + ldo1 { + regulator-name = "vdd-pex"; + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <1050000>; + }; + + ldo2 { + regulator-name = "vddio-sdmmc3"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <3300000>; + }; + + ldo3 { + regulator-name = "vdd-cam-hv"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + }; + + ldo4 { + regulator-name = "vdd-rtc"; + regulator-min-microvolt = <1250000>; + regulator-max-microvolt = <1250000>; + regulator-always-on; + regulator-boot-on; + }; + + ldo5 { + regulator-name = "avdd-ts-hv"; + regulator-min-microvolt = <3000000>; + regulator-max-microvolt = <3000000>; + }; + + ldo6 { + regulator-name = "vdd-ts"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-always-on; + regulator-boot-on; + }; + + ldo7 { + regulator-name = "vdd-gen-pll-edp"; + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <1050000>; + regulator-always-on; + regulator-boot-on; + }; + + ldo8 { + regulator-name = "vdd-hdmi-dp"; + regulator-min-microvolt = <1050000>; + regulator-max-microvolt = <1050000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 24bd422cecd5..ecfc593cac15 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -11,6 +11,7 @@ Optional properties: - regulator-always-on: boolean, regulator should never be disabled - regulator-boot-on: bootloader/firmware enabled regulator - regulator-allow-bypass: allow the regulator to go into bypass mode +- regulator-allow-set-load: allow the regulator performance level to be configured - <name>-supply: phandle to the parent supply/regulator node - regulator-ramp-delay: ramp delay for regulator(in uV/uS) For hardware which supports disabling ramp rate, it should be explicitly @@ -43,6 +44,11 @@ Optional properties: any consumer request. - regulator-pull-down: Enable pull down resistor when the regulator is disabled. - regulator-over-current-protection: Enable over current protection. +- regulator-active-discharge: tristate, enable/disable active discharge of + regulators. The values are: + 0: Disable active discharge. + 1: Enable active discharge. + Absence of this property will leave configuration to default. Deprecated properties: - regulator-compatible: If a regulator chip contains multiple diff --git a/Documentation/devicetree/bindings/regulator/s5m8767-regulator.txt b/Documentation/devicetree/bindings/regulator/s5m8767-regulator.txt deleted file mode 100644 index 20191315e444..000000000000 --- a/Documentation/devicetree/bindings/regulator/s5m8767-regulator.txt +++ /dev/null @@ -1,163 +0,0 @@ -* Samsung S5M8767 Voltage and Current Regulator - -The Samsung S5M8767 is a multi-function device which includes voltage and -current regulators, rtc, charger controller and other sub-blocks. It is -interfaced to the host controller using a i2c interface. Each sub-block is -addressed by the host system using different i2c slave address. This document -describes the bindings for 'pmic' sub-block of s5m8767. - -Required properties: -- compatible: Should be "samsung,s5m8767-pmic". -- reg: Specifies the i2c slave address of the pmic block. It should be 0x66. - -- s5m8767,pmic-buck2-dvs-voltage: A set of 8 voltage values in micro-volt (uV) - units for buck2 when changing voltage using gpio dvs. Refer to [1] below - for additional information. - -- s5m8767,pmic-buck3-dvs-voltage: A set of 8 voltage values in micro-volt (uV) - units for buck3 when changing voltage using gpio dvs. Refer to [1] below - for additional information. - -- s5m8767,pmic-buck4-dvs-voltage: A set of 8 voltage values in micro-volt (uV) - units for buck4 when changing voltage using gpio dvs. Refer to [1] below - for additional information. - -- s5m8767,pmic-buck-ds-gpios: GPIO specifiers for three host gpio's used - for selecting GPIO DVS lines. It is one-to-one mapped to dvs gpio lines. - -[1] If none of the 's5m8767,pmic-buck[2/3/4]-uses-gpio-dvs' optional - property is specified, the 's5m8767,pmic-buck[2/3/4]-dvs-voltage' - property should specify atleast one voltage level (which would be a - safe operating voltage). - - If either of the 's5m8767,pmic-buck[2/3/4]-uses-gpio-dvs' optional - property is specified, then all the eight voltage values for the - 's5m8767,pmic-buck[2/3/4]-dvs-voltage' should be specified. - -Optional properties: -- interrupt-parent: Specifies the phandle of the interrupt controller to which - the interrupts from s5m8767 are delivered to. -- interrupts: Interrupt specifiers for two interrupt sources. - - First interrupt specifier is for 'irq1' interrupt. - - Second interrupt specifier is for 'alert' interrupt. -- s5m8767,pmic-buck2-uses-gpio-dvs: 'buck2' can be controlled by gpio dvs. -- s5m8767,pmic-buck3-uses-gpio-dvs: 'buck3' can be controlled by gpio dvs. -- s5m8767,pmic-buck4-uses-gpio-dvs: 'buck4' can be controlled by gpio dvs. - -Additional properties required if either of the optional properties are used: - -- s5m8767,pmic-buck234-default-dvs-idx: Default voltage setting selected from - the possible 8 options selectable by the dvs gpios. The value of this - property should be between 0 and 7. If not specified or if out of range, the - default value of this property is set to 0. - -- s5m8767,pmic-buck-dvs-gpios: GPIO specifiers for three host gpio's used - for dvs. The format of the gpio specifier depends in the gpio controller. - -Regulators: The regulators of s5m8767 that have to be instantiated should be -included in a sub-node named 'regulators'. Regulator nodes included in this -sub-node should be of the format as listed below. - - regulator_name { - ldo1_reg: LDO1 { - regulator-name = "VDD_ALIVE_1.0V"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - regulator-always-on; - regulator-boot-on; - op_mode = <1>; /* Normal Mode */ - }; - }; -The above regulator entries are defined in regulator bindings documentation -except these properties: - - op_mode: describes the different operating modes of the LDO's with - power mode change in SOC. The different possible values are, - 0 - always off mode - 1 - on in normal mode - 2 - low power mode - 3 - suspend mode - - s5m8767,pmic-ext-control-gpios: (optional) GPIO specifier for one - GPIO controlling this regulator (enable/disable); This is - valid only for buck9. - -The following are the names of the regulators that the s5m8767 pmic block -supports. Note: The 'n' in LDOn and BUCKn represents the LDO or BUCK number -as per the datasheet of s5m8767. - - - LDOn - - valid values for n are 1 to 28 - - Example: LDO1, LDO2, LDO28 - - BUCKn - - valid values for n are 1 to 9. - - Example: BUCK1, BUCK2, BUCK9 - -The bindings inside the regulator nodes use the standard regulator bindings -which are documented elsewhere. - -Example: - - s5m8767_pmic@66 { - compatible = "samsung,s5m8767-pmic"; - reg = <0x66>; - - s5m8767,pmic-buck2-uses-gpio-dvs; - s5m8767,pmic-buck3-uses-gpio-dvs; - s5m8767,pmic-buck4-uses-gpio-dvs; - - s5m8767,pmic-buck-default-dvs-idx = <0>; - - s5m8767,pmic-buck-dvs-gpios = <&gpx0 0 0>, /* DVS1 */ - <&gpx0 1 0>, /* DVS2 */ - <&gpx0 2 0>; /* DVS3 */ - - s5m8767,pmic-buck-ds-gpios = <&gpx2 3 0>, /* SET1 */ - <&gpx2 4 0>, /* SET2 */ - <&gpx2 5 0>; /* SET3 */ - - s5m8767,pmic-buck2-dvs-voltage = <1350000>, <1300000>, - <1250000>, <1200000>, - <1150000>, <1100000>, - <1000000>, <950000>; - - s5m8767,pmic-buck3-dvs-voltage = <1100000>, <1100000>, - <1100000>, <1100000>, - <1000000>, <1000000>, - <1000000>, <1000000>; - - s5m8767,pmic-buck4-dvs-voltage = <1200000>, <1200000>, - <1200000>, <1200000>, - <1200000>, <1200000>, - <1200000>, <1200000>; - - regulators { - ldo1_reg: LDO1 { - regulator-name = "VDD_ABB_3.3V"; - regulator-min-microvolt = <3300000>; - regulator-max-microvolt = <3300000>; - op_mode = <1>; /* Normal Mode */ - }; - - ldo2_reg: LDO2 { - regulator-name = "VDD_ALIVE_1.1V"; - regulator-min-microvolt = <1100000>; - regulator-max-microvolt = <1100000>; - regulator-always-on; - }; - - buck1_reg: BUCK1 { - regulator-name = "VDD_MIF_1.2V"; - regulator-min-microvolt = <950000>; - regulator-max-microvolt = <1350000>; - regulator-always-on; - regulator-boot-on; - }; - - vemmc_reg: BUCK9 { - regulator-name = "VMEM_VDD_2.8V"; - regulator-min-microvolt = <2800000>; - regulator-max-microvolt = <2800000>; - op_mode = <3>; /* Standby Mode */ - s5m8767,pmic-ext-control-gpios = <&gpk0 2 0>; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/regulator/samsung,s2mpa01.txt b/Documentation/devicetree/bindings/regulator/samsung,s2mpa01.txt new file mode 100644 index 000000000000..bae3c7f838cf --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/samsung,s2mpa01.txt @@ -0,0 +1,79 @@ +Binding for Samsung S2MPA01 regulator block +=========================================== + +This is a part of device tree bindings for S2M family multi-function devices. +More information can be found in bindings/mfd/sec-core.txt file. + +The S2MPA01 device provide buck and LDO regulators. + +To register these with regulator framework instantiate under main device node +a sub-node named "regulators" with more sub-nodes for each regulator using the +common regulator binding documented in: + - Documentation/devicetree/bindings/regulator/regulator.txt + + +Names of regulators supported by S2MPA01 device: + - LDOn + - valid values for n are 1 to 26 + - Example: LDO1, LD02, LDO26 + - BUCKn + - valid values for n are 1 to 10. + - Example: BUCK1, BUCK2, BUCK9 +Note: The 'n' in LDOn and BUCKn represents the LDO or BUCK number +as per the datasheet of device. + + +Optional properties of buck regulator nodes under "regulators" sub-node: + - regulator-ramp-delay: ramp delay in uV/us. May be 6250, 12500 + (default), 25000, or 50000. May be 0 for disabling the ramp delay on + BUCK{1,2,3,4}. + + In the absence of the regulator-ramp-delay property, the default ramp + delay will be used. + + Note: Some bucks share the ramp rate setting i.e. same ramp value + will be set for a particular group of bucks so provide the same + regulator-ramp-delay value for them. + Groups sharing ramp rate: + - buck{1,6}, + - buck{2,4}, + - buck{8,9,10}. + +Example: + + s2mpa01_pmic@66 { + compatible = "samsung,s2mpa01-pmic"; + reg = <0x66>; + + regulators { + ldo1_reg: LDO1 { + regulator-name = "VDD_ALIVE"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + }; + + ldo2_reg: LDO2 { + regulator-name = "VDDQ_MMC2"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + regulator-always-on; + }; + + buck1_reg: BUCK1 { + regulator-name = "vdd_mif"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + }; + + buck2_reg: BUCK2 { + regulator-name = "vdd_arm"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + regulator-ramp-delay = <50000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/samsung,s2mps11.txt b/Documentation/devicetree/bindings/regulator/samsung,s2mps11.txt new file mode 100644 index 000000000000..27a48bf1b185 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/samsung,s2mps11.txt @@ -0,0 +1,102 @@ +Binding for Samsung S2M family regulator block +============================================== + +This is a part of device tree bindings for S2M family multi-function devices. +More information can be found in bindings/mfd/sec-core.txt file. + +The S2MPS11/13/14/15 and S2MPU02 devices provide buck and LDO regulators. + +To register these with regulator framework instantiate under main device node +a sub-node named "regulators" with more sub-nodes for each regulator using the +common regulator binding documented in: + - Documentation/devicetree/bindings/regulator/regulator.txt + + +Names of regulators supported by different devices: + - LDOn + - valid values for n are: + - S2MPS11: 1 to 38 + - S2MPS13: 1 to 40 + - S2MPS14: 1 to 25 + - S2MPS15: 1 to 27 + - S2MPU02: 1 to 28 + - Example: LDO1, LDO2, LDO28 + - BUCKn + - valid values for n are: + - S2MPS11: 1 to 10 + - S2MPS13: 1 to 10 + - S2MPS14: 1 to 5 + - S2MPS15: 1 to 10 + - S2MPU02: 1 to 7 + - Example: BUCK1, BUCK2, BUCK9 +Note: The 'n' in LDOn and BUCKn represents the LDO or BUCK number +as per the datasheet of device. + + +Optional properties of the nodes under "regulators" sub-node: + - regulator-ramp-delay: ramp delay in uV/us. May be 6250, 12500, + 25000 (default) or 50000. + + Additionally S2MPS11 supports disabling ramp delay for BUCK{2,3,4,6} + by setting it to <0>. + + Note: On S2MPS11 some bucks share the ramp rate setting i.e. same ramp value + will be set for a particular group of bucks so provide the same + regulator-ramp-delay value for them. + Groups sharing ramp rate: + - buck{1,6}, + - buck{3,4}, + - buck{7,8,10}. + + - samsung,ext-control-gpios: On S2MPS14 the LDO10, LDO11 and LDO12 can be + configured to external control over GPIO. To turn this feature on this + property must be added to the regulator sub-node: + - samsung,ext-control-gpios: GPIO specifier for one GPIO + controlling this regulator (enable/disable) + Example: + LDO12 { + regulator-name = "V_EMMC_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + samsung,ext-control-gpios = <&gpk0 2 0>; + }; + + +Example: + + s2mps11_pmic@66 { + compatible = "samsung,s2mps11-pmic"; + reg = <0x66>; + + regulators { + ldo1_reg: LDO1 { + regulator-name = "VDD_ABB_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + ldo2_reg: LDO2 { + regulator-name = "VDD_ALIVE_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + }; + + buck1_reg: BUCK1 { + regulator-name = "vdd_mif"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + }; + + buck2_reg: BUCK2 { + regulator-name = "vdd_arm"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + regulator-ramp-delay = <50000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/samsung,s5m8767.txt b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.txt new file mode 100644 index 000000000000..093edda0c8df --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/samsung,s5m8767.txt @@ -0,0 +1,145 @@ +Binding for Samsung S5M8767 regulator block +=========================================== + +This is a part of device tree bindings for S5M family multi-function devices. +More information can be found in bindings/mfd/sec-core.txt file. + +The S5M8767 device provide buck and LDO regulators. + +To register these with regulator framework instantiate under main device node +a sub-node named "regulators" with more sub-nodes for each regulator using the +common regulator binding documented in: + - Documentation/devicetree/bindings/regulator/regulator.txt + + +Required properties of the main device node (the parent!): + - s5m8767,pmic-buck2-dvs-voltage: A set of 8 voltage values in micro-volt (uV) + units for buck2 when changing voltage using gpio dvs. Refer to [1] below + for additional information. + + - s5m8767,pmic-buck3-dvs-voltage: A set of 8 voltage values in micro-volt (uV) + units for buck3 when changing voltage using gpio dvs. Refer to [1] below + for additional information. + + - s5m8767,pmic-buck4-dvs-voltage: A set of 8 voltage values in micro-volt (uV) + units for buck4 when changing voltage using gpio dvs. Refer to [1] below + for additional information. + + - s5m8767,pmic-buck-ds-gpios: GPIO specifiers for three host gpio's used + for selecting GPIO DVS lines. It is one-to-one mapped to dvs gpio lines. + + [1] If none of the 's5m8767,pmic-buck[2/3/4]-uses-gpio-dvs' optional + property is specified, the 's5m8767,pmic-buck[2/3/4]-dvs-voltage' + property should specify atleast one voltage level (which would be a + safe operating voltage). + + If either of the 's5m8767,pmic-buck[2/3/4]-uses-gpio-dvs' optional + property is specified, then all the eight voltage values for the + 's5m8767,pmic-buck[2/3/4]-dvs-voltage' should be specified. + +Optional properties of the main device node (the parent!): + - s5m8767,pmic-buck2-uses-gpio-dvs: 'buck2' can be controlled by gpio dvs. + - s5m8767,pmic-buck3-uses-gpio-dvs: 'buck3' can be controlled by gpio dvs. + - s5m8767,pmic-buck4-uses-gpio-dvs: 'buck4' can be controlled by gpio dvs. + +Additional properties required if either of the optional properties are used: + + - s5m8767,pmic-buck234-default-dvs-idx: Default voltage setting selected from + the possible 8 options selectable by the dvs gpios. The value of this + property should be between 0 and 7. If not specified or if out of range, the + default value of this property is set to 0. + + - s5m8767,pmic-buck-dvs-gpios: GPIO specifiers for three host gpio's used + for dvs. The format of the gpio specifier depends in the gpio controller. + + +Names of regulators supported by S5M8767 device: + - LDOn + - valid values for n are 1 to 28 + - Example: LDO1, LDO2, LDO28 + - BUCKn + - valid values for n are 1 to 9. + - Example: BUCK1, BUCK2, BUCK9 +Note: The 'n' in LDOn and BUCKn represents the LDO or BUCK number +as per the datasheet of device. + + +Optional properties of the nodes under "regulators" sub-node: + - op_mode: describes the different operating modes of the LDO's with + power mode change in SOC. The different possible values are, + 0 - always off mode + 1 - on in normal mode + 2 - low power mode + 3 - suspend mode + - s5m8767,pmic-ext-control-gpios: (optional) GPIO specifier for one + GPIO controlling this regulator + (enable/disable); This is valid only + for buck9. + +Example: + + s5m8767_pmic@66 { + compatible = "samsung,s5m8767-pmic"; + reg = <0x66>; + + s5m8767,pmic-buck2-uses-gpio-dvs; + s5m8767,pmic-buck3-uses-gpio-dvs; + s5m8767,pmic-buck4-uses-gpio-dvs; + + s5m8767,pmic-buck-default-dvs-idx = <0>; + + s5m8767,pmic-buck-dvs-gpios = <&gpx0 0 0>, /* DVS1 */ + <&gpx0 1 0>, /* DVS2 */ + <&gpx0 2 0>; /* DVS3 */ + + s5m8767,pmic-buck-ds-gpios = <&gpx2 3 0>, /* SET1 */ + <&gpx2 4 0>, /* SET2 */ + <&gpx2 5 0>; /* SET3 */ + + s5m8767,pmic-buck2-dvs-voltage = <1350000>, <1300000>, + <1250000>, <1200000>, + <1150000>, <1100000>, + <1000000>, <950000>; + + s5m8767,pmic-buck3-dvs-voltage = <1100000>, <1100000>, + <1100000>, <1100000>, + <1000000>, <1000000>, + <1000000>, <1000000>; + + s5m8767,pmic-buck4-dvs-voltage = <1200000>, <1200000>, + <1200000>, <1200000>, + <1200000>, <1200000>, + <1200000>, <1200000>; + + regulators { + ldo1_reg: LDO1 { + regulator-name = "VDD_ABB_3.3V"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + op_mode = <1>; /* Normal Mode */ + }; + + ldo2_reg: LDO2 { + regulator-name = "VDD_ALIVE_1.1V"; + regulator-min-microvolt = <1100000>; + regulator-max-microvolt = <1100000>; + regulator-always-on; + }; + + buck1_reg: BUCK1 { + regulator-name = "VDD_MIF_1.2V"; + regulator-min-microvolt = <950000>; + regulator-max-microvolt = <1350000>; + regulator-always-on; + regulator-boot-on; + }; + + vemmc_reg: BUCK9 { + regulator-name = "VMEM_VDD_2.8V"; + regulator-min-microvolt = <2800000>; + regulator-max-microvolt = <2800000>; + op_mode = <3>; /* Standby Mode */ + s5m8767,pmic-ext-control-gpios = <&gpk0 2 0>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/tps65023.txt b/Documentation/devicetree/bindings/regulator/tps65023.txt new file mode 100644 index 000000000000..a4714e4da370 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/tps65023.txt @@ -0,0 +1,60 @@ +TPS65023 family of regulators + +Required properties: +- compatible: Must be one of the following. + "ti,tps65020", + "ti,tps65021", + "ti,tps65023", +- reg: I2C slave address +- regulators: list of regulators provided by this controller, must be named + after their hardware counterparts: VDCDC[1-3] and LDO[1-2] +- regulators: This is the list of child nodes that specify the regulator + initialization data for defined regulators. The definition for each of + these nodes is defined using the standard binding for regulators found at + Documentation/devicetree/bindings/regulator/regulator.txt. + +Each regulator is defined using the standard binding for regulators. + +Example: + + tps65023@48 { + compatible = "ti,tps65023"; + reg = <0x48>; + + regulators { + VDCDC1 { + regulator-name = "vdd_mpu"; + regulator-always-on; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + }; + + VDCDC2 { + regulator-name = "vdd_core"; + regulator-always-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + VDCDC3 { + regulator-name = "vdd_io"; + regulator-always-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + LDO1 { + regulator-name = "vdd_usb18"; + regulator-always-on; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + }; + + LDO2 { + regulator-name = "vdd_usb33"; + regulator-always-on; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/st-rproc.txt b/Documentation/devicetree/bindings/remoteproc/st-rproc.txt new file mode 100644 index 000000000000..1031bcd90a79 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/st-rproc.txt @@ -0,0 +1,41 @@ +STMicroelectronics Co-Processor Bindings +---------------------------------------- + +This binding provides support for adjunct processors found on ST SoCs. + +Co-processors can be controlled from the bootloader or the primary OS. If +the bootloader starts a co-processor, the primary OS must detect its state +and act accordingly. + +Required properties: +- compatible Should be one of: + "st,st231-rproc" + "st,st40-rproc" +- memory-region Reserved memory (See: ../reserved-memory/reserved-memory.txt) +- resets Reset lines (See: ../reset/reset.txt) +- reset-names Must be "sw_reset" and "pwr_reset" +- clocks Clock for co-processor (See: ../clock/clock-bindings.txt) +- clock-frequency Clock frequency to set co-processor at if the bootloader + hasn't already done so +- st,syscfg System configuration register which holds the boot vector + for the co-processor + 1st cell: Phandle to syscon block + 2nd cell: Boot vector register offset + +Example: + + audio_reserved: rproc@42000000 { + compatible = "shared-dma-pool"; + reg = <0x42000000 0x01000000>; + no-map; + }; + + st231-audio { + compatible = "st,st231-rproc"; + memory-region = <&audio_reserved>; + resets = <&softreset STIH407_ST231_AUD_SOFTRESET>; + reset-names = "sw_reset"; + clocks = <&clk_s_c0_flexgen CLK_ST231_AUD_0>; + clock-frequency = <600000000>; + st,syscfg = <&syscfg_core 0x228>; + }; diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt b/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt new file mode 100644 index 000000000000..e0b185a944ba --- /dev/null +++ b/Documentation/devicetree/bindings/reset/hisilicon,hi6220-reset.txt @@ -0,0 +1,34 @@ +Hisilicon System Reset Controller +====================================== + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +The reset controller registers are part of the system-ctl block on +hi6220 SoC. + +Required properties: +- compatible: may be "hisilicon,hi6220-sysctrl" +- reg: should be register base and length as documented in the + datasheet +- #reset-cells: 1, see below + +Example: +sys_ctrl: sys_ctrl@f7030000 { + compatible = "hisilicon,hi6220-sysctrl", "syscon"; + reg = <0x0 0xf7030000 0x0 0x2000>; + #clock-cells = <1>; + #reset-cells = <1>; +}; + +Specifying reset lines connected to IP modules +============================================== +example: + + uart1: serial@..... { + ... + resets = <&sys_ctrl PERIPH_RSTEN3_UART1>; + ... + }; + +The index could be found in <dt-bindings/reset/hisi,hi6220-resets.h>. diff --git a/Documentation/devicetree/bindings/hwrng/atmel-trng.txt b/Documentation/devicetree/bindings/rng/atmel-trng.txt index 4ac5aaa2d024..4ac5aaa2d024 100644 --- a/Documentation/devicetree/bindings/hwrng/atmel-trng.txt +++ b/Documentation/devicetree/bindings/rng/atmel-trng.txt diff --git a/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt b/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt new file mode 100644 index 000000000000..4b5ac600bfbd --- /dev/null +++ b/Documentation/devicetree/bindings/rng/brcm,bcm6368.txt @@ -0,0 +1,17 @@ +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"; + }; diff --git a/Documentation/devicetree/bindings/hwrng/brcm,iproc-rng200.txt b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt index e25a456664b9..e25a456664b9 100644 --- a/Documentation/devicetree/bindings/hwrng/brcm,iproc-rng200.txt +++ b/Documentation/devicetree/bindings/rng/brcm,iproc-rng200.txt diff --git a/Documentation/devicetree/bindings/rng/microchip,pic32-rng.txt b/Documentation/devicetree/bindings/rng/microchip,pic32-rng.txt new file mode 100644 index 000000000000..c6d1003befb7 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/microchip,pic32-rng.txt @@ -0,0 +1,17 @@ +* Microchip PIC32 Random Number Generator + +The PIC32 RNG provides a pseudo random number generator which can be seeded by +another true random number generator. + +Required properties: +- compatible : should be "microchip,pic32mzda-rng" +- reg : Specifies base physical address and size of the registers. +- clocks: clock phandle. + +Example: + + rng: rng@1f8e6000 { + compatible = "microchip,pic32mzda-rng"; + reg = <0x1f8e6000 0x1000>; + clocks = <&PBCLK5>; + }; diff --git a/Documentation/devicetree/bindings/hwrng/omap_rng.txt b/Documentation/devicetree/bindings/rng/omap_rng.txt index 6a62acd86953..6a62acd86953 100644 --- a/Documentation/devicetree/bindings/hwrng/omap_rng.txt +++ b/Documentation/devicetree/bindings/rng/omap_rng.txt diff --git a/Documentation/devicetree/bindings/rng/samsung,exynos-rng4.txt b/Documentation/devicetree/bindings/rng/samsung,exynos-rng4.txt new file mode 100644 index 000000000000..4ca8dd4d7e66 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/samsung,exynos-rng4.txt @@ -0,0 +1,17 @@ +Exynos Pseudo Random Number Generator + +Required properties: + +- compatible : Should be "samsung,exynos4-rng". +- 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. + +Example: + + rng@10830400 { + compatible = "samsung,exynos4-rng"; + reg = <0x10830400 0x200>; + clocks = <&clock CLK_SSS>; + clock-names = "secss"; + }; diff --git a/Documentation/devicetree/bindings/rng/st,rng.txt b/Documentation/devicetree/bindings/rng/st,rng.txt new file mode 100644 index 000000000000..35734bc282e9 --- /dev/null +++ b/Documentation/devicetree/bindings/rng/st,rng.txt @@ -0,0 +1,15 @@ +STMicroelectronics HW Random Number Generator +---------------------------------------------- + +Required parameters: +compatible : Should be "st,rng" +reg : Base address and size of IP's register map. +clocks : Phandle to device's clock (See: ../clocks/clock-bindings.txt) + +Example: + +rng@fee80000 { + compatible = "st,rng"; + reg = <0xfee80000 0x1000>; + clocks = <&clk_sysin>; +} diff --git a/Documentation/devicetree/bindings/rng/st,stm32-rng.txt b/Documentation/devicetree/bindings/rng/st,stm32-rng.txt new file mode 100644 index 000000000000..47f04176f93b --- /dev/null +++ b/Documentation/devicetree/bindings/rng/st,stm32-rng.txt @@ -0,0 +1,21 @@ +STMicroelectronics STM32 HW RNG +=============================== + +The STM32 hardware random number generator is a simple fixed purpose IP and +is fully separated from other crypto functions. + +Required properties: + +- compatible : Should be "st,stm32-rng" +- reg : Should be register base and length as documented in the datasheet +- interrupts : The designated IRQ line for the RNG +- clocks : The clock needed to enable the RNG + +Example: + + rng: rng@50060800 { + compatible = "st,stm32-rng"; + reg = <0x50060800 0x400>; + interrupts = <80>; + clocks = <&rcc 0 38>; + }; diff --git a/Documentation/devicetree/bindings/hwrng/timeriomem_rng.txt b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt index 6616d15866a3..6616d15866a3 100644 --- a/Documentation/devicetree/bindings/hwrng/timeriomem_rng.txt +++ b/Documentation/devicetree/bindings/rng/timeriomem_rng.txt diff --git a/Documentation/devicetree/bindings/rtc/alphascale,asm9260-rtc.txt b/Documentation/devicetree/bindings/rtc/alphascale,asm9260-rtc.txt new file mode 100644 index 000000000000..76ebca568db9 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/alphascale,asm9260-rtc.txt @@ -0,0 +1,19 @@ +* Alphascale asm9260 SoC Real Time Clock + +Required properties: +- compatible: Should be "alphascale,asm9260-rtc" +- reg: Physical base address of the controller and length + of memory mapped region. +- interrupts: IRQ line for the RTC. +- clocks: Reference to the clock entry. +- clock-names: should contain: + * "ahb" for the SoC RTC clock + +Example: +rtc0: rtc@800a0000 { + compatible = "alphascale,asm9260-rtc"; + reg = <0x800a0000 0x100>; + clocks = <&acc CLKID_AHB_RTC>; + clock-names = "ahb"; + interrupts = <2>; +}; diff --git a/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt b/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt new file mode 100644 index 000000000000..8e76f2648796 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt @@ -0,0 +1,18 @@ +* Dallas DS1390 SPI Serial Real-Time Clock + +Required properties: +- compatible: Should contain "dallas,ds1390". +- reg: SPI address for chip + +Optional properties: +- trickle-resistor-ohms : Selected resistor for trickle charger + Values usable for ds1390 are 250, 2000, 4000 + Should be given if trickle charger should be enabled +- trickle-diode-disable : Do not use internal trickle charger diode + Should be given if internal trickle charger diode should be disabled +Example: + ds1390: rtc@68 { + compatible = "dallas,ds1390"; + trickle-resistor-ohms = <250>; + reg = <0>; + }; diff --git a/Documentation/devicetree/bindings/rtc/epson,rx6110.txt b/Documentation/devicetree/bindings/rtc/epson,rx6110.txt new file mode 100644 index 000000000000..3dc313e01f77 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/epson,rx6110.txt @@ -0,0 +1,39 @@ +Epson RX6110 Real Time Clock +============================ + +The Epson RX6110 can be used with SPI or I2C busses. The kind of +bus depends on the SPISEL pin and can not be configured via software. + +I2C mode +-------- + +Required properties: + - compatible: should be: "epson,rx6110" + - reg : the I2C address of the device for I2C + +Example: + + rtc: rtc@32 { + compatible = "epson,rx6110" + reg = <0x32>; + }; + +SPI mode +-------- + +Required properties: + - compatible: should be: "epson,rx6110" + - reg: chip select number + - spi-cs-high: RX6110 needs chipselect high + - spi-cpha: RX6110 works with SPI shifted clock phase + - spi-cpol: RX6110 works with SPI inverse clock polarity + +Example: + + rtc: rtc@3 { + compatible = "epson,rx6110" + reg = <3> + spi-cs-high; + spi-cpha; + spi-cpol; + }; diff --git a/Documentation/devicetree/bindings/rtc/isil,isl12057.txt b/Documentation/devicetree/bindings/rtc/isil,isl12057.txt index 501c39ceae79..cf83e0940302 100644 --- a/Documentation/devicetree/bindings/rtc/isil,isl12057.txt +++ b/Documentation/devicetree/bindings/rtc/isil,isl12057.txt @@ -5,7 +5,7 @@ consisting of a compatible field, an address and possibly an interrupt line). Nonetheless, it also supports an option boolean property -("isil,irq2-can-wakeup-machine") to handle the specific use-case found +("wakeup-source") to handle the specific use-case found on at least three in-tree users of the chip (NETGEAR ReadyNAS 102, 104 and 2120 ARM-based NAS); On those devices, the IRQ#2 pin of the chip (associated with the alarm supported by the driver) is not connected @@ -22,9 +22,9 @@ Required properties supported by the device: Optional properties: - - "isil,irq2-can-wakeup-machine": mark the chip as a wakeup source, - independently of the availability of an IRQ line connected to the - SoC. + - "wakeup-source": mark the chip as a wakeup source, independently of + the availability of an IRQ line connected to the SoC. + (Legacy property supported: "isil,irq2-can-wakeup-machine") - "interrupt-parent", "interrupts": for passing the interrupt line of the SoC connected to IRQ#2 of the RTC chip. @@ -74,5 +74,5 @@ PMIC, allowing the device to be started based on configured alarm: isl12057: isl12057@68 { compatible = "isil,isl12057"; reg = <0x68>; - isil,irq2-can-wakeup-machine; + wakeup-source; }; diff --git a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt new file mode 100644 index 000000000000..ddef330d2709 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt @@ -0,0 +1,37 @@ +* Maxim DS3231 Real Time Clock + +Required properties: +see: Documentation/devicetree/bindings/i2c/trivial-devices.txt + +Optional property: +- #clock-cells: Should be 1. +- clock-output-names: + overwrite the default clock names "ds3231_clk_sqw" and "ds3231_clk_32khz". + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. Following indices are allowed: + - 0: square-wave output on the SQW pin + - 1: square-wave output on the 32kHz pin + +- interrupts: rtc alarm/event interrupt. When this property is selected, + clock on the SQW pin cannot be used. + +Example: + +ds3231: ds3231@51 { + compatible = "maxim,ds3231"; + reg = <0x68>; + #clock-cells = <1>; +}; + +device1 { +... + clocks = <&ds3231 0>; +... +}; + +device2 { +... + clocks = <&ds3231 1>; +... +}; diff --git a/Documentation/devicetree/bindings/rtc/microchip,pic32-rtc.txt b/Documentation/devicetree/bindings/rtc/microchip,pic32-rtc.txt new file mode 100644 index 000000000000..180b7144bfcc --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/microchip,pic32-rtc.txt @@ -0,0 +1,21 @@ +* Microchip PIC32 Real Time Clock and Calendar + +The RTCC keeps time in hours, minutes, and seconds, and one half second. It +provides a calendar in weekday, date, month, and year. It also provides a +configurable alarm. + +Required properties: +- compatible: should be: "microchip,pic32mzda-rtc" +- reg: physical base address of the controller and length of memory mapped + region. +- interrupts: RTC alarm/event interrupt +- clocks: clock phandle + +Example: + + rtc: rtc@1f8c0000 { + compatible = "microchip,pic32mzda-rtc"; + reg = <0x1f8c0000 0x60>; + interrupts = <166 IRQ_TYPE_EDGE_RISING>; + clocks = <&PBCLK6>; + }; diff --git a/Documentation/devicetree/bindings/rtc/pcf8563.txt b/Documentation/devicetree/bindings/rtc/pcf8563.txt new file mode 100644 index 000000000000..72f6d2c9665e --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/pcf8563.txt @@ -0,0 +1,25 @@ +* Philips PCF8563/Epson RTC8564 Real Time Clock + +Philips PCF8563/Epson RTC8564 Real Time Clock + +Required properties: +see: Documentation/devicetree/bindings/i2c/trivial-devices.txt + +Optional property: +- #clock-cells: Should be 0. +- clock-output-names: + overwrite the default clock name "pcf8563-clkout" + +Example: + +pcf8563: pcf8563@51 { + compatible = "nxp,pcf8563"; + reg = <0x51>; + #clock-cells = <0>; +}; + +device { +... + clocks = <&pcf8563>; +... +}; diff --git a/Documentation/devicetree/bindings/rtc/rtc-opal.txt b/Documentation/devicetree/bindings/rtc/rtc-opal.txt index af87e5ecac54..a1734e5cb75b 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-opal.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-opal.txt @@ -5,12 +5,13 @@ Required properties: - comapatible: Should be "ibm,opal-rtc" Optional properties: -- has-tpo: Decides if the wakeup is supported or not. +- wakeup-source: Decides if the wakeup is supported or not + (Legacy property supported: "has-tpo") Example: rtc { compatible = "ibm,opal-rtc"; - has-tpo; + wakeup-source; phandle = <0x10000029>; linux,phandle = <0x10000029>; }; diff --git a/Documentation/devicetree/bindings/rtc/s3c-rtc.txt b/Documentation/devicetree/bindings/rtc/s3c-rtc.txt index ac2fcd6ff4b8..1068ffce9f91 100644 --- a/Documentation/devicetree/bindings/rtc/s3c-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/s3c-rtc.txt @@ -14,6 +14,10 @@ Required properties: interrupt number is the rtc alarm interrupt and second interrupt number is the rtc tick interrupt. The number of cells representing a interrupt depends on the parent interrupt controller. +- clocks: Must contain a list of phandle and clock specifier for the rtc + and source clocks. +- clock-names: Must contain "rtc" and "rtc_src" entries sorted in the + same order as the clocks property. Example: @@ -21,4 +25,6 @@ Example: compatible = "samsung,s3c6410-rtc"; reg = <0x10070000 0x100>; interrupts = <44 0 45 0>; + clocks = <&clock CLK_RTC>, <&s2mps11_osc S2MPS11_CLK_AP>; + clock-names = "rtc", "rtc_src"; }; diff --git a/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt new file mode 100644 index 000000000000..bf2411f366e5 --- /dev/null +++ b/Documentation/devicetree/bindings/scsi/hisilicon-sas.txt @@ -0,0 +1,88 @@ +* HiSilicon SAS controller + +The HiSilicon SAS controller supports SAS/SATA. + +Main node required properties: + - compatible : value should be as follows: + (a) "hisilicon,hip05-sas-v1" for v1 hw in hip05 chipset + (b) "hisilicon,hip06-sas-v2" for v2 hw in hip06 chipset + - sas-addr : array of 8 bytes for host SAS address + - reg : Address and length of the SAS register + - 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 + - ctrl-clock-ena-reg : offset to controller clock enable register in ctrl reg + - queue-count : number of delivery and completion queues in the controller + - phy-count : number of phys accessible by the controller + - interrupts : For v1 hw: Interrupts for phys, completion queues, and fatal + sources; the interrupts are ordered in 3 groups, as follows: + - Phy interrupts + - Completion queue interrupts + - Fatal interrupts + Phy interrupts : Each phy has 3 interrupt sources: + - broadcast + - phyup + - abnormal + The phy interrupts are ordered into groups of 3 per phy + (broadcast, phyup, and abnormal) in increasing order. + Completion queue interrupts : each completion queue has 1 + interrupt source. + The interrupts are ordered in increasing order. + Fatal interrupts : the fatal interrupts are ordered as follows: + - ECC + - AXI bus + For v2 hw: Interrupts for phys, Sata, and completion queues; + the interrupts are ordered in 3 groups, as follows: + - Phy interrupts + - Sata interrupts + - Completion queue interrupts + Phy interrupts : Each controller has 2 phy interrupts: + - phy up/down + - channel interrupt + Sata interrupts : Each phy on the controller has 1 Sata + interrupt. The interrupts are ordered in increasing + order. + Completion queue interrupts : each completion queue has 1 + interrupt source. The interrupts are ordered in + increasing order. + +Optional main node properties: + - hip06-sas-v2-quirk-amt : when set, indicates that the v2 controller has the + "am-max-transmissions" limitation. + +Example: + sas0: sas@c1000000 { + compatible = "hisilicon,hip05-sas-v1"; + sas-addr = [50 01 88 20 16 00 00 0a]; + reg = <0x0 0xc1000000 0x0 0x10000>; + hisilicon,sas-syscon = <&pcie_sas>; + ctrl-reset-reg = <0xa60>; + ctrl-reset-sts-reg = <0x5a30>; + ctrl-clock-ena-reg = <0x338>; + queue-count = <32>; + phy-count = <8>; + dma-coherent; + interrupt-parent = <&mbigen_dsa>; + interrupts = <259 4>,<263 4>,<264 4>,/* phy0 */ + <269 4>,<273 4>,<274 4>,/* phy1 */ + <279 4>,<283 4>,<284 4>,/* phy2 */ + <289 4>,<293 4>,<294 4>,/* phy3 */ + <299 4>,<303 4>,<304 4>,/* phy4 */ + <309 4>,<313 4>,<314 4>,/* phy5 */ + <319 4>,<323 4>,<324 4>,/* phy6 */ + <329 4>,<333 4>,<334 4>,/* phy7 */ + <336 1>,<337 1>,<338 1>,/* cq0-2 */ + <339 1>,<340 1>,<341 1>,/* cq3-5 */ + <342 1>,<343 1>,<344 1>,/* cq6-8 */ + <345 1>,<346 1>,<347 1>,/* cq9-11 */ + <348 1>,<349 1>,<350 1>,/* cq12-14 */ + <351 1>,<352 1>,<353 1>,/* cq15-17 */ + <354 1>,<355 1>,<356 1>,/* cq18-20 */ + <357 1>,<358 1>,<359 1>,/* cq21-23 */ + <360 1>,<361 1>,<362 1>,/* cq24-26 */ + <363 1>,<364 1>,<365 1>,/* cq27-29 */ + <366 1>,<367 1>/* cq30-31 */ + <376 4>,/* fatal ecc */ + <381 4>;/* fatal axi */ + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/serial/8250.txt b/Documentation/devicetree/bindings/serial/8250.txt index 91d5ab0e60fc..936ab5b87324 100644 --- a/Documentation/devicetree/bindings/serial/8250.txt +++ b/Documentation/devicetree/bindings/serial/8250.txt @@ -14,7 +14,6 @@ Required properties: tegra132, or tegra210. - "nxp,lpc3220-uart" - "ralink,rt2880-uart" - - "ibm,qpace-nwp-serial" - "altr,16550-FIFO32" - "altr,16550-FIFO64" - "altr,16550-FIFO128" diff --git a/Documentation/devicetree/bindings/serial/brcm,bcm2835-aux-uart.txt b/Documentation/devicetree/bindings/serial/brcm,bcm2835-aux-uart.txt new file mode 100644 index 000000000000..b5cc6297cd1b --- /dev/null +++ b/Documentation/devicetree/bindings/serial/brcm,bcm2835-aux-uart.txt @@ -0,0 +1,18 @@ +* BCM2835 AUXILIAR UART + +Required properties: + +- compatible: "brcm,bcm2835-aux-uart" +- reg: The base address of the UART register bank. +- interrupts: A single interrupt specifier. +- clocks: Clock driving the hardware; used to figure out the baud rate + divisor. + +Example: + + uart1: serial@7e215040 { + compatible = "brcm,bcm2835-aux-uart"; + reg = <0x7e215040 0x40>; + interrupts = <1 29>; + clocks = <&aux BCM2835_AUX_CLOCK_UART>; + }; diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt index 35ae1fb3537f..ed94c217c98d 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt @@ -9,7 +9,7 @@ Optional properties: - fsl,uart-has-rtscts : Indicate the uart has rts and cts - fsl,irda-mode : Indicate the uart supports irda mode - fsl,dte-mode : Indicate the uart works in DTE mode. The uart works - is DCE mode by default. + in DCE mode by default. Note: Each uart controller should have an alias correctly numbered in "aliases" node. diff --git a/Documentation/devicetree/bindings/serial/ingenic,uart.txt b/Documentation/devicetree/bindings/serial/ingenic,uart.txt index c2d3b3abe7d9..02cb7fe59cb7 100644 --- a/Documentation/devicetree/bindings/serial/ingenic,uart.txt +++ b/Documentation/devicetree/bindings/serial/ingenic,uart.txt @@ -1,7 +1,8 @@ * Ingenic SoC UART Required properties: -- compatible : "ingenic,jz4740-uart" or "ingenic,jz4780-uart" +- compatible : "ingenic,jz4740-uart", "ingenic,jz4760-uart", + "ingenic,jz4775-uart" or "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. diff --git a/Documentation/devicetree/bindings/serial/mrvl,pxa-ssp.txt b/Documentation/devicetree/bindings/serial/mrvl,pxa-ssp.txt index 669b8140dd79..d10cc06c0c37 100644 --- a/Documentation/devicetree/bindings/serial/mrvl,pxa-ssp.txt +++ b/Documentation/devicetree/bindings/serial/mrvl,pxa-ssp.txt @@ -10,7 +10,6 @@ Required properties: mvrl,pxa168-ssp mrvl,pxa910-ssp mrvl,ce4100-ssp - mrvl,lpss-ssp - reg: The memory base - dmas: Two dma phandles, one for rx, one for tx diff --git a/Documentation/devicetree/bindings/serial/mtk-uart.txt b/Documentation/devicetree/bindings/serial/mtk-uart.txt index 2d47add34765..a833a016f656 100644 --- a/Documentation/devicetree/bindings/serial/mtk-uart.txt +++ b/Documentation/devicetree/bindings/serial/mtk-uart.txt @@ -2,15 +2,15 @@ Required properties: - compatible should contain: - * "mediatek,mt8135-uart" for MT8135 compatible UARTS + * "mediatek,mt2701-uart" for MT2701 compatible UARTS + * "mediatek,mt6580-uart" for MT6580 compatible UARTS + * "mediatek,mt6582-uart" for MT6582 compatible UARTS + * "mediatek,mt6589-uart" for MT6589 compatible UARTS + * "mediatek,mt6795-uart" for MT6795 compatible UARTS * "mediatek,mt8127-uart" for MT8127 compatible UARTS + * "mediatek,mt8135-uart" for MT8135 compatible UARTS * "mediatek,mt8173-uart" for MT8173 compatible UARTS - * "mediatek,mt6795-uart" for MT6795 compatible UARTS - * "mediatek,mt6589-uart" for MT6589 compatible UARTS - * "mediatek,mt6582-uart" for MT6582 compatible UARTS - * "mediatek,mt6580-uart" for MT6580 compatible UARTS - * "mediatek,mt6577-uart" for all compatible UARTS (MT8173, MT6795, - MT6589, MT6582, MT6580, MT6577) + * "mediatek,mt6577-uart" for MT6577 and all of the above - reg: The base address of the UART register bank. diff --git a/Documentation/devicetree/bindings/serial/pl011.txt b/Documentation/devicetree/bindings/serial/pl011.txt index cbae3d9a0278..77863aefe9ef 100644 --- a/Documentation/devicetree/bindings/serial/pl011.txt +++ b/Documentation/devicetree/bindings/serial/pl011.txt @@ -19,7 +19,7 @@ Optional properties: must correspond to the PCLK clocking the internal logic of the block. Just listing one clock (the first one) is deprecated. -- clocks-names: +- clock-names: When present, the first clock listed must be named "uartclk" and the second clock listed must be named "apb_pclk" diff --git a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt index a2114c217376..182777fac9a2 100644 --- a/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt +++ b/Documentation/devicetree/bindings/serial/qcom,msm-uartdm.txt @@ -26,6 +26,12 @@ Required properties: Optional properties: - dmas: Should contain dma specifiers for transmit and receive channels - dma-names: Should contain "tx" for transmit and "rx" for receive channels +- qcom,tx-crci: Identificator <u32> for Client Rate Control Interface to be + used with TX DMA channel. Required when using DMA for transmission + with UARTDM v1.3 and bellow. +- qcom,rx-crci: Identificator <u32> for Client Rate Control Interface to be + used with RX DMA channel. Required when using DMA for reception + with UARTDM v1.3 and bellow. Note: Aliases may be defined to ensure the correct ordering of the UARTs. The alias serialN will result in the UART being assigned port N. If any diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index e84b13a8eda3..528c3b90f23c 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -2,7 +2,7 @@ Required properties: - - compatible: Must contain one of the following: + - compatible: Must contain one or more of the following: - "renesas,scif-r7s72100" for R7S72100 (RZ/A1H) SCIF compatible UART. - "renesas,scifa-r8a73a4" for R8A73A4 (R-Mobile APE6) SCIFA compatible UART. @@ -15,16 +15,32 @@ Required properties: - "renesas,scifa-r8a7790" for R8A7790 (R-Car H2) SCIFA compatible UART. - "renesas,scifb-r8a7790" for R8A7790 (R-Car H2) SCIFB compatible UART. - "renesas,hscif-r8a7790" for R8A7790 (R-Car H2) HSCIF compatible UART. - - "renesas,scif-r8a7791" for R8A7791 (R-Car M2) SCIF compatible UART. - - "renesas,scifa-r8a7791" for R8A7791 (R-Car M2) SCIFA compatible UART. - - "renesas,scifb-r8a7791" for R8A7791 (R-Car M2) SCIFB compatible UART. - - "renesas,hscif-r8a7791" for R8A7791 (R-Car M2) HSCIF compatible UART. + - "renesas,scif-r8a7791" for R8A7791 (R-Car M2-W) SCIF compatible UART. + - "renesas,scifa-r8a7791" for R8A7791 (R-Car M2-W) SCIFA compatible UART. + - "renesas,scifb-r8a7791" for R8A7791 (R-Car M2-W) SCIFB compatible UART. + - "renesas,hscif-r8a7791" for R8A7791 (R-Car M2-W) HSCIF compatible UART. + - "renesas,scif-r8a7792" for R8A7792 (R-Car V2H) SCIF compatible UART. + - "renesas,hscif-r8a7792" for R8A7792 (R-Car V2H) HSCIF compatible UART. + - "renesas,scif-r8a7793" for R8A7793 (R-Car M2-N) SCIF compatible UART. + - "renesas,scifa-r8a7793" for R8A7793 (R-Car M2-N) SCIFA compatible UART. + - "renesas,scifb-r8a7793" for R8A7793 (R-Car M2-N) SCIFB compatible UART. + - "renesas,hscif-r8a7793" for R8A7793 (R-Car M2-N) HSCIF compatible UART. - "renesas,scif-r8a7794" for R8A7794 (R-Car E2) SCIF compatible UART. - "renesas,scifa-r8a7794" for R8A7794 (R-Car E2) SCIFA compatible UART. - "renesas,scifb-r8a7794" for R8A7794 (R-Car E2) SCIFB compatible UART. - "renesas,hscif-r8a7794" for R8A7794 (R-Car E2) HSCIF compatible UART. + - "renesas,scif-r8a7795" for R8A7795 (R-Car H3) SCIF compatible UART. + - "renesas,hscif-r8a7795" for R8A7795 (R-Car H3) HSCIF compatible UART. - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. - "renesas,scifb-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFB compatible UART. + - "renesas,rcar-gen1-scif" for R-Car Gen1 SCIF compatible UART, + - "renesas,rcar-gen2-scif" for R-Car Gen2 SCIF compatible UART, + - "renesas,rcar-gen3-scif" for R-Car Gen3 SCIF compatible UART, + - "renesas,rcar-gen2-scifa" for R-Car Gen2 SCIFA compatible UART, + - "renesas,rcar-gen2-scifb" for R-Car Gen2 SCIFB compatible UART, + - "renesas,rcar-gen1-hscif" for R-Car Gen1 HSCIF compatible UART, + - "renesas,rcar-gen2-hscif" for R-Car Gen2 HSCIF compatible UART, + - "renesas,rcar-gen3-hscif" for R-Car Gen3 HSCIF compatible UART, - "renesas,scif" for generic SCIF compatible UART. - "renesas,scifa" for generic SCIFA compatible UART. - "renesas,scifb" for generic SCIFB compatible UART. @@ -32,15 +48,26 @@ Required properties: - "renesas,sci" for generic SCI compatible UART. When compatible with the generic version, nodes must list the - SoC-specific version corresponding to the platform first followed by the - generic version. + SoC-specific version corresponding to the platform first, followed by the + family-specific and/or generic versions. - reg: Base address and length of the I/O registers used by the UART. - interrupts: Must contain an interrupt-specifier for the SCIx interrupt. - clocks: Must contain a phandle and clock-specifier pair for each entry in clock-names. - - clock-names: Must contain "sci_ick" for the SCIx UART interface clock. + - clock-names: Must contain "fck" for the SCIx UART functional clock. + Apart from the divided functional clock, there may be other possible + sources for the sampling clock, depending on SCIx variant. + On (H)SCI(F) and some SCIFA, an additional clock may be specified: + - "hsck" for the optional external clock input (on HSCIF), + - "sck" for the optional external clock input (on other variants). + On UARTs equipped with a Baud Rate Generator for External Clock (BRG) + (some SCIF and HSCIF), additional clocks may be specified: + - "brg_int" for the optional internal clock source for the frequency + divider (typically the (AXI or SHwy) bus clock), + - "scif_clk" for the optional external clock source for the frequency + divider (SCIF_CLK). Note: Each enabled SCIx UART should have an alias correctly numbered in the "aliases" node. @@ -56,12 +83,13 @@ Example: }; scifa0: serial@e6c40000 { - compatible = "renesas,scifa-r8a7790", "renesas,scifa"; + compatible = "renesas,scifa-r8a7790", + "renesas,rcar-gen2-scifa", "renesas,scifa"; reg = <0 0xe6c40000 0 64>; interrupt-parent = <&gic>; interrupts = <0 144 IRQ_TYPE_LEVEL_HIGH>; clocks = <&mstp2_clks R8A7790_CLK_SCIFA0>; - clock-names = "sci_ick"; + clock-names = "fck"; dmas = <&dmac0 0x21>, <&dmac0 0x22>; dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt index 289c40ed7470..12bbe9f22560 100644 --- a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt +++ b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt @@ -15,6 +15,9 @@ The supplying peripheral clock can also be handled, needing a second property Required elements: "baudclk", "apb_pclk" Optional properties: +- snps,uart-16550-compatible : reflects the value of UART_16550_COMPATIBLE + configuration parameter. Define this if your UART does not implement the busy + functionality. - resets : phandle to the parent reset controller. - reg-shift : quantity to shift the register offsets by. If this property is not present then the register offsets are not shifted. diff --git a/Documentation/devicetree/bindings/soc/bcm/raspberrypi,bcm2835-power.txt b/Documentation/devicetree/bindings/soc/bcm/raspberrypi,bcm2835-power.txt new file mode 100644 index 000000000000..30942cf7992b --- /dev/null +++ b/Documentation/devicetree/bindings/soc/bcm/raspberrypi,bcm2835-power.txt @@ -0,0 +1,47 @@ +Raspberry Pi power domain driver + +Required properties: + +- compatible: Should be "raspberrypi,bcm2835-power". +- firmware: Reference to the RPi firmware device node. +- #power-domain-cells: Should be <1>, we providing multiple power domains. + +The valid defines for power domain are: + + RPI_POWER_DOMAIN_I2C0 + RPI_POWER_DOMAIN_I2C1 + RPI_POWER_DOMAIN_I2C2 + RPI_POWER_DOMAIN_VIDEO_SCALER + RPI_POWER_DOMAIN_VPU1 + RPI_POWER_DOMAIN_HDMI + RPI_POWER_DOMAIN_USB + RPI_POWER_DOMAIN_VEC + RPI_POWER_DOMAIN_JPEG + RPI_POWER_DOMAIN_H264 + RPI_POWER_DOMAIN_V3D + RPI_POWER_DOMAIN_ISP + RPI_POWER_DOMAIN_UNICAM0 + RPI_POWER_DOMAIN_UNICAM1 + RPI_POWER_DOMAIN_CCP2RX + RPI_POWER_DOMAIN_CSI2 + RPI_POWER_DOMAIN_CPI + RPI_POWER_DOMAIN_DSI0 + RPI_POWER_DOMAIN_DSI1 + RPI_POWER_DOMAIN_TRANSPOSER + RPI_POWER_DOMAIN_CCP2TX + RPI_POWER_DOMAIN_CDP + RPI_POWER_DOMAIN_ARM + +Example: + +power: power { + compatible = "raspberrypi,bcm2835-power"; + firmware = <&firmware>; + #power-domain-cells = <1>; +}; + +Example for using power domain: + +&usb { + power-domains = <&power RPI_POWER_DOMAIN_USB>; +}; diff --git a/Documentation/devicetree/bindings/soc/dove/pmu.txt b/Documentation/devicetree/bindings/soc/dove/pmu.txt new file mode 100644 index 000000000000..edd40b796b74 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/dove/pmu.txt @@ -0,0 +1,56 @@ +Device Tree bindings for Marvell PMU + +Required properties: + - compatible: value should be "marvell,dove-pmu". + May also include "simple-bus" if there are child devices, in which + case the ranges node is required. + - reg: two base addresses and sizes of the PM controller and PMU. + - interrupts: single interrupt number for the PMU interrupt + - interrupt-controller: must be specified as the PMU itself is an + interrupt controller. + - #interrupt-cells: must be 1. + - #reset-cells: must be 1. + - domains: sub-node containing domain descriptions + +Optional properties: + - ranges: defines the address mapping for child devices, as per the + standard property of this name. Required when compatible includes + "simple-bus". + +Power domain descriptions are listed as child nodes of the "domains" +sub-node. Each domain has the following properties: + +Required properties: + - #power-domain-cells: must be 0. + +Optional properties: + - marvell,pmu_pwr_mask: specifies the mask value for PMU power register + - marvell,pmu_iso_mask: specifies the mask value for PMU isolation register + - resets: points to the reset manager (PMU node) and reset index. + +Example: + + pmu: power-management@d0000 { + compatible = "marvell,dove-pmu"; + reg = <0xd0000 0x8000>, <0xd8000 0x8000>; + interrupts = <33>; + interrupt-controller; + #interrupt-cells = <1>; + #reset-cells = <1>; + + domains { + vpu_domain: vpu-domain { + #power-domain-cells = <0>; + marvell,pmu_pwr_mask = <0x00000008>; + marvell,pmu_iso_mask = <0x00000001>; + resets = <&pmu 16>; + }; + + gpu_domain: gpu-domain { + #power-domain-cells = <0>; + marvell,pmu_pwr_mask = <0x00000004>; + marvell,pmu_iso_mask = <0x00000002>; + resets = <&pmu 18>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/fsl/rcpm.txt b/Documentation/devicetree/bindings/soc/fsl/rcpm.txt new file mode 100644 index 000000000000..e284e4e1ccd5 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/fsl/rcpm.txt @@ -0,0 +1,63 @@ +* Run Control and Power Management +------------------------------------------- +The RCPM performs all device-level tasks associated with device run control +and power management. + +Required properites: + - reg : Offset and length of the register set of the RCPM block. + - fsl,#rcpm-wakeup-cells : The number of IPPDEXPCR register cells in the + fsl,rcpm-wakeup property. + - compatible : Must contain a chip-specific RCPM block compatible string + and (if applicable) may contain a chassis-version RCPM compatible + string. Chip-specific strings are of the form "fsl,<chip>-rcpm", + such as: + * "fsl,p2041-rcpm" + * "fsl,p5020-rcpm" + * "fsl,t4240-rcpm" + + Chassis-version strings are of the form "fsl,qoriq-rcpm-<version>", + such as: + * "fsl,qoriq-rcpm-1.0": for chassis 1.0 rcpm + * "fsl,qoriq-rcpm-2.0": for chassis 2.0 rcpm + * "fsl,qoriq-rcpm-2.1": for chassis 2.1 rcpm + +All references to "1.0" and "2.0" refer to the QorIQ chassis version to +which the chip complies. +Chassis Version Example Chips +--------------- ------------------------------- +1.0 p4080, p5020, p5040, p2041, p3041 +2.0 t4240, b4860, b4420 +2.1 t1040, ls1021 + +Example: +The RCPM node for T4240: + rcpm: global-utilities@e2000 { + compatible = "fsl,t4240-rcpm", "fsl,qoriq-rcpm-2.0"; + reg = <0xe2000 0x1000>; + fsl,#rcpm-wakeup-cells = <2>; + }; + +* Freescale RCPM Wakeup Source Device Tree Bindings +------------------------------------------- +Required fsl,rcpm-wakeup property should be added to a device node if the device +can be used as a wakeup source. + + - fsl,rcpm-wakeup: Consists of a phandle to the rcpm node and the IPPDEXPCR + register cells. The number of IPPDEXPCR register cells is defined in + "fsl,#rcpm-wakeup-cells" in the rcpm node. The first register cell is + the bit mask that should be set in IPPDEXPCR0, and the second register + cell is for IPPDEXPCR1, and so on. + + Note: IPPDEXPCR(IP Powerdown Exception Control Register) provides a + mechanism for keeping certain blocks awake during STANDBY and MEM, in + order to use them as wake-up sources. + +Example: + lpuart0: serial@2950000 { + compatible = "fsl,ls1021a-lpuart"; + reg = <0x0 0x2950000 0x0 0x1000>; + interrupts = <GIC_SPI 80 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&sysclk>; + clock-names = "ipg"; + fsl,rcpm-wakeup = <&rcpm 0x0 0x40000000>; + }; diff --git a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt index c0511142b39c..e8f15e34027f 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/scpsys.txt @@ -17,9 +17,21 @@ Required properties: - reg: Address range of the SCPSYS unit - infracfg: must contain a phandle to the infracfg controller - clock, clock-names: clocks according to the common clock binding. - The clocks needed "mm" and "mfg". These are the - clocks which hardware needs to be enabled before - enabling certain power domains. + The clocks needed "mm", "mfg", "venc" and "venc_lt". + These are the clocks which hardware needs to be enabled + before enabling certain power domains. + +Optional properties: +- vdec-supply: Power supply for the vdec power domain +- venc-supply: Power supply for the venc power domain +- isp-supply: Power supply for the isp power domain +- mm-supply: Power supply for the mm power domain +- venc_lt-supply: Power supply for the venc_lt power domain +- audio-supply: Power supply for the audio power domain +- usb-supply: Power supply for the usb power domain +- mfg_async-supply: Power supply for the mfg_async power domain +- mfg_2d-supply: Power supply for the mfg_2d power domain +- mfg-supply: Power supply for the mfg power domain Example: @@ -30,7 +42,9 @@ Example: infracfg = <&infracfg>; clocks = <&clk26m>, <&topckgen CLK_TOP_MM_SEL>; - clock-names = "mfg", "mm"; + <&topckgen CLK_TOP_VENC_SEL>, + <&topckgen CLK_TOP_VENC_LT_SEL>; + clock-names = "mfg", "mm", "venc", "venc_lt"; }; Example consumer: diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt new file mode 100644 index 000000000000..a48049ccf6d0 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt @@ -0,0 +1,58 @@ +Qualcomm Resource Power Manager (RPM) over SMD + +This driver is used to interface with the Resource Power Manager (RPM) found in +various Qualcomm platforms. The RPM allows each component in the system to vote +for state of the system resources, such as clocks, regulators and bus +frequencies. + +The SMD information for the RPM edge should be filled out. See qcom,smd.txt for +the required edge properties. All SMD related properties will reside within the +RPM node itself. + += SUBDEVICES + +The RPM exposes resources to its subnodes. The rpm_requests node must be +present and this subnode may contain children that designate regulator +resources. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,rpm-apq8084" + "qcom,rpm-msm8916" + "qcom,rpm-msm8974" + +- qcom,smd-channels: + Usage: required + Value type: <string> + Definition: must be "rpm_requests" + +Refer to Documentation/devicetree/bindings/regulator/qcom,smd-rpm-regulator.txt +for information on the regulator subnodes that can exist under the rpm_requests. + +Example: + + soc { + apcs: syscon@f9011000 { + compatible = "syscon"; + reg = <0xf9011000 0x1000>; + }; + }; + + smd { + compatible = "qcom,smd"; + + rpm { + interrupts = <0 168 1>; + qcom,ipc = <&apcs 8 0>; + qcom,smd-edge = <15>; + + rpm_requests { + compatible = "qcom,rpm-msm8974"; + qcom,smd-channels = "rpm_requests"; + + ... + }; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smem.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smem.txt new file mode 100644 index 000000000000..9326cdf6e1b1 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smem.txt @@ -0,0 +1,57 @@ +Qualcomm Shared Memory Manager binding + +This binding describes the Qualcomm Shared Memory Manager, used to share data +between various subsystems and OSes in Qualcomm platforms. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be: + "qcom,smem" + +- memory-region: + Usage: required + Value type: <prop-encoded-array> + Definition: handle to memory reservation for main SMEM memory region. + +- qcom,rpm-msg-ram: + Usage: required + Value type: <prop-encoded-array> + Definition: handle to RPM message memory resource + +- hwlocks: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to a hwspinlock used to protect allocations from + the shared memory + += EXAMPLE +The following example shows the SMEM setup for MSM8974, with a main SMEM region +at 0xfa00000 and the RPM message ram at 0xfc428000: + + reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + smem_region: smem@fa00000 { + reg = <0xfa00000 0x200000>; + no-map; + }; + }; + + smem@fa00000 { + compatible = "qcom,smem"; + + memory-region = <&smem_region>; + qcom,rpm-msg-ram = <&rpm_msg_ram>; + + hwlocks = <&tcsr_mutex 3>; + }; + + soc { + rpm_msg_ram: memory@fc428000 { + compatible = "qcom,rpm-msg-ram"; + reg = <0xfc428000 0x4000>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt new file mode 100644 index 000000000000..5cc82b8353d8 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt @@ -0,0 +1,104 @@ +Qualcomm Shared Memory Point 2 Point binding + +The Shared Memory Point to Point (SMP2P) protocol facilitates communication of +a single 32-bit value between two processors. Each value has a single writer +(the local side) and a single reader (the remote side). Values are uniquely +identified in the system by the directed edge (local processor ID to remote +processor ID) and a string identifier. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,smp2p" + +- interrupts: + Usage: required + Value type: <prop-encoded-array> + Definition: one entry specifying the smp2p notification interrupt + +- qcom,ipc: + Usage: required + Value type: <prop-encoded-array> + 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 + - u32 representing offset to the register within the syscon + - u32 representing the ipc bit within the register + +- qcom,smem: + Usage: required + Value type: <u32 array> + Definition: two identifiers of the inbound and outbound smem items used + for this edge + +- qcom,local-pid: + Usage: required + Value type: <u32> + Definition: specifies the identfier of the local endpoint of this edge + +- qcom,remote-pid: + Usage: required + Value type: <u32> + Definition: specifies the identfier of the remote endpoint of this edge + += SUBNODES +Each SMP2P pair contain a set of inbound and outbound entries, these are +described in subnodes of the smp2p device node. The node names are not +important. + +- qcom,entry-name: + Usage: required + Value type: <string> + Definition: specifies the name of this entry, for inbound entries this + will be used to match against the remotely allocated entry + and for outbound entries this name is used for allocating + entries + +- interrupt-controller: + Usage: required for incoming entries + Value type: <empty> + Definition: marks the entry as inbound; the node should be specified + as a two cell interrupt-controller as defined in + "../interrupt-controller/interrupts.txt" + If not specified this node will denote the outgoing entry + +- #interrupt-cells: + Usage: required for incoming entries + Value type: <u32> + Definition: must be 2 - denoting the bit in the entry and IRQ flags + +- #qcom,state-cells: + Usage: required for outgoing entries + Value type: <u32> + Definition: must be 1 - denoting the bit in the entry + += EXAMPLE +The following example shows the SMP2P setup with the wireless processor, +defined from the 8974 apps processor's point-of-view. It encompasses one +inbound and one outbound entry: + +wcnss-smp2p { + compatible = "qcom,smp2p"; + qcom,smem = <431>, <451>; + + interrupts = <0 143 1>; + + qcom,ipc = <&apcs 8 18>; + + qcom,local-pid = <0>; + qcom,remote-pid = <4>; + + wcnss_smp2p_out: master-kernel { + qcom,entry-name = "master-kernel"; + + #qcom,state-cells = <1>; + }; + + wcnss_smp2p_in: slave-kernel { + qcom,entry-name = "slave-kernel"; + + interrupt-controller; + #interrupt-cells = <2>; + }; +}; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smsm.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smsm.txt new file mode 100644 index 000000000000..a6634c70850d --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smsm.txt @@ -0,0 +1,104 @@ +Qualcomm Shared Memory State Machine + +The Shared Memory State Machine facilitates broadcasting of single bit state +information between the processors in a Qualcomm SoC. Each processor is +assigned 32 bits of state that can be modified. A processor can through a +matrix of bitmaps signal subscription of notifications upon changes to a +certain bit owned by a certain remote processor. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,smsm" + +- qcom,ipc-N: + Usage: required + Value type: <prop-encoded-array> + Definition: three entries specifying the outgoing ipc bit used for + signaling the N:th remote processor + - phandle to a syscon node representing the apcs registers + - u32 representing offset to the register within the syscon + - u32 representing the ipc bit within the register + +- qcom,local-host: + Usage: optional + Value type: <u32> + Definition: identifier of the local processor in the list of hosts, or + in other words specifier of the column in the subscription + matrix representing the local processor + defaults to host 0 + +- #address-cells: + Usage: required + Value type: <u32> + Definition: must be 1 + +- #size-cells: + Usage: required + Value type: <u32> + Definition: must be 0 + += SUBNODES +Each processor's state bits are described by a subnode of the smsm device node. +Nodes can either be flagged as an interrupt-controller to denote a remote +processor's state bits or the local processors bits. The node names are not +important. + +- reg: + Usage: required + Value type: <u32> + Definition: specifies the offset, in words, of the first bit for this + entry + +- #qcom,state-cells: + Usage: required for local entry + Value type: <u32> + Definition: must be 1 - denotes bit number + +- interrupt-controller: + Usage: required for remote entries + Value type: <empty> + Definition: marks the entry as a interrupt-controller and the state bits + to belong to a remote processor + +- #interrupt-cells: + Usage: required for remote entries + Value type: <u32> + Definition: must be 2 - denotes bit number and IRQ flags + +- interrupts: + Usage: required for remote entries + Value type: <prop-encoded-array> + Definition: one entry specifying remote IRQ used by the remote processor + to signal changes of its state bits + + += EXAMPLE +The following example shows the SMEM setup for controlling properties of the +wireless processor, defined from the 8974 apps processor's point-of-view. It +encompasses one outbound entry and the outgoing interrupt for the wireless +processor. + +smsm { + compatible = "qcom,smsm"; + + #address-cells = <1>; + #size-cells = <0>; + + qcom,ipc-3 = <&apcs 8 19>; + + apps_smsm: apps@0 { + reg = <0>; + + #qcom,state-cells = <1>; + }; + + wcnss_smsm: wcnss@7 { + reg = <7>; + interrupts = <0 144 1>; + + interrupt-controller; + #interrupt-cells = <2>; + }; +}; diff --git a/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt b/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt new file mode 100644 index 000000000000..112756e11802 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt @@ -0,0 +1,46 @@ +* Rockchip Power Domains + +Rockchip processors include support for multiple power domains which can be +powered up/down by software based on different application scenes to save power. + +Required properties for power domain controller: +- compatible: Should be one of the following. + "rockchip,rk3288-power-controller" - for RK3288 SoCs. +- #power-domain-cells: Number of cells in a power-domain specifier. + Should be 1 for multiple PM domains. +- #address-cells: Should be 1. +- #size-cells: Should be 0. + +Required properties for power domain sub nodes: +- reg: index of the power domain, should use macros in: + "include/dt-bindings/power/rk3288-power.h" - for RK3288 type power domain. +- clocks (optional): phandles to clocks which need to be enabled while power domain + switches state. + +Example: + + power: power-controller { + compatible = "rockchip,rk3288-power-controller"; + #power-domain-cells = <1>; + #address-cells = <1>; + #size-cells = <0>; + + pd_gpu { + reg = <RK3288_PD_GPU>; + clocks = <&cru ACLK_GPU>; + }; + }; + +Node of a device using power domains must have a power-domains property, +containing a phandle to the power device node and an index specifying which +power domain to use. +The index should use macros in: + "include/dt-bindings/power/rk3288-power.h" - for rk3288 type power domain. + +Example of the node using power domain: + + node { + /* ... */ + power-domains = <&power RK3288_PD_GPU>; + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt index d8e8cdb733f9..d1ce21a4904d 100644 --- a/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt +++ b/Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt @@ -221,7 +221,6 @@ qmss: qmss@2a40000 { #size-cells = <1>; ranges; pdsp0@0x2a10000 { - firmware = "keystone/qmss_pdsp_acc48_k2_le_1_0_0_8.fw"; reg = <0x2a10000 0x1000>, <0x2a0f000 0x100>, <0x2a0c000 0x3c8>, diff --git a/Documentation/devicetree/bindings/soc/ti/wkup_m3_ipc.txt b/Documentation/devicetree/bindings/soc/ti/wkup_m3_ipc.txt new file mode 100644 index 000000000000..401550487ed6 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/ti/wkup_m3_ipc.txt @@ -0,0 +1,57 @@ +Wakeup M3 IPC Driver +===================== + +The TI AM33xx and AM43xx family of devices use a small Cortex M3 co-processor +(commonly referred to as Wakeup M3 or CM3) to help with various low power tasks +that cannot be controlled from the MPU, like suspend/resume and certain deep +C-states for CPU Idle. Once the wkup_m3_ipc driver uses the wkup_m3_rproc driver +to boot the wkup_m3, it handles communication with the CM3 using IPC registers +present in the SoC's control module and a mailbox. The wkup_m3_ipc exposes an +API to allow the SoC PM code to execute specific PM tasks. + +Wkup M3 Device Node: +==================== +A wkup_m3_ipc device node is used to represent the IPC registers within an +SoC. + +Required properties: +-------------------- +- compatible: Should be, + "ti,am3352-wkup-m3-ipc" for AM33xx SoCs + "ti,am4372-wkup-m3-ipc" for AM43xx SoCs +- reg: Contains the IPC register address space to communicate + with the Wakeup M3 processor +- interrupts: Contains the interrupt information for the wkup_m3 + interrupt that signals the MPU. +- ti,rproc: phandle to the wkup_m3 rproc node so the IPC driver + can boot it. +- mboxes: phandles used by IPC framework to get correct mbox + channel for communication. Must point to appropriate + mbox_wkupm3 child node. + +Example: +-------- +/* AM33xx */ + l4_wkup: l4_wkup@44c00000 { + ... + + scm: scm@210000 { + compatible = "ti,am3-scm", "simple-bus"; + reg = <0x210000 0x2000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x210000 0x2000>; + + ... + + wkup_m3_ipc: wkup_m3_ipc@1324 { + compatible = "ti,am3352-wkup-m3-ipc"; + reg = <0x1324 0x24>; + interrupts = <78>; + ti,rproc = <&wkup_m3>; + mboxes = <&mailbox &mbox_wkupm3>; + }; + + ... + }; + }; diff --git a/Documentation/devicetree/bindings/sound/adi,adau17x1.txt b/Documentation/devicetree/bindings/sound/adi,adau17x1.txt new file mode 100644 index 000000000000..8dbce0e18dda --- /dev/null +++ b/Documentation/devicetree/bindings/sound/adi,adau17x1.txt @@ -0,0 +1,24 @@ +Analog Devices ADAU1361/ADAU1461/ADAU1761/ADAU1961/ADAU1381/ADAU1781 + +Required properties: + + - compatible: Should contain one of the following: + "adi,adau1361" + "adi,adau1461" + "adi,adau1761" + "adi,adau1961" + "adi,adau1381" + "adi,adau1781" + + - reg: The i2c address. Value depends on the state of ADDR0 + and ADDR1, as wired in hardware. + +Examples: +#include <dt-bindings/sound/adau17x1.h> + + i2c_bus { + adau1361@38 { + compatible = "adi,adau1761"; + reg = <0x38>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/ak4554.c b/Documentation/devicetree/bindings/sound/ak4554.txt index 934fa02754b3..934fa02754b3 100644 --- a/Documentation/devicetree/bindings/sound/ak4554.c +++ b/Documentation/devicetree/bindings/sound/ak4554.txt diff --git a/Documentation/devicetree/bindings/sound/ak4613.txt b/Documentation/devicetree/bindings/sound/ak4613.txt new file mode 100644 index 000000000000..1783f9ef0930 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak4613.txt @@ -0,0 +1,27 @@ +AK4613 I2C transmitter + +This device supports I2C mode only. + +Required properties: + +- compatible : "asahi-kasei,ak4613" +- reg : The chip select number on the I2C bus + +Optional properties: +- asahi-kasei,in1-single-end : Boolean. Indicate input / output pins are single-ended. +- asahi-kasei,in2-single-end rather than differential. +- asahi-kasei,out1-single-end +- asahi-kasei,out2-single-end +- asahi-kasei,out3-single-end +- asahi-kasei,out4-single-end +- asahi-kasei,out5-single-end +- asahi-kasei,out6-single-end + +Example: + +&i2c { + ak4613: ak4613@0x10 { + compatible = "asahi-kasei,ak4613"; + reg = <0x10>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/ak4642.txt b/Documentation/devicetree/bindings/sound/ak4642.txt index 623d4e70ae11..340784db6808 100644 --- a/Documentation/devicetree/bindings/sound/ak4642.txt +++ b/Documentation/devicetree/bindings/sound/ak4642.txt @@ -7,7 +7,14 @@ Required properties: - compatible : "asahi-kasei,ak4642" or "asahi-kasei,ak4643" or "asahi-kasei,ak4648" - reg : The chip select number on the I2C bus -Example: +Optional properties: + + - #clock-cells : common clock binding; shall be set to 0 + - clocks : common clock binding; MCKI clock + - clock-frequency : common clock binding; frequency of MCKO + - clock-output-names : common clock binding; MCKO clock name + +Example 1: &i2c { ak4648: ak4648@0x12 { @@ -15,3 +22,16 @@ Example: reg = <0x12>; }; }; + +Example 2: + +&i2c { + ak4643: codec@12 { + compatible = "asahi-kasei,ak4643"; + reg = <0x12>; + #clock-cells = <0>; + clocks = <&audio_clock>; + clock-frequency = <12288000>; + clock-output-names = "ak4643_mcko"; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/atmel-classd.txt b/Documentation/devicetree/bindings/sound/atmel-classd.txt new file mode 100644 index 000000000000..549e701cb7a1 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/atmel-classd.txt @@ -0,0 +1,58 @@ +* Atmel ClassD driver under ALSA SoC architecture + +Required properties: +- compatible + Should be "atmel,sama5d2-classd". +- reg + Should contain ClassD registers location and length. +- interrupts + Should contain the IRQ line for the ClassD. +- dmas + One DMA specifiers as described in atmel-dma.txt and dma.txt files. +- dma-names + Must be "tx". +- clock-names + Tuple listing input clock names. + Required elements: "pclk", "gclk" and "aclk". +- clocks + Please refer to clock-bindings.txt. +- assigned-clocks + Should be <&classd_gclk>. +- assigned-clock-parents + Should be <&audio_pll_pmc>. + +Optional properties: +- pinctrl-names, pinctrl-0 + Please refer to pinctrl-bindings.txt. +- atmel,model + The user-visible name of this sound complex. + The default value is "CLASSD". +- atmel,pwm-type + PWM modulation type, "single" or "diff". + The default value is "single". +- atmel,non-overlap-time + Set non-overlapping time, the unit is nanosecond(ns). + There are four values, + <5>, <10>, <15>, <20>, the default value is <10>. + Non-overlapping will be disabled if not specified. + +Example: +classd: classd@fc048000 { + compatible = "atmel,sama5d2-classd"; + reg = <0xfc048000 0x100>; + interrupts = <59 IRQ_TYPE_LEVEL_HIGH 7>; + dmas = <&dma0 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) + | AT91_XDMAC_DT_PERID(47))>; + dma-names = "tx"; + clocks = <&classd_clk>, <&classd_gclk>, <&audio_pll_pmc>; + clock-names = "pclk", "gclk", "aclk"; + assigned-clocks = <&classd_gclk>; + assigned-clock-parents = <&audio_pll_pmc>; + + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_classd_default>; + atmel,model = "classd @ SAMA5D2-Xplained"; + atmel,pwm-type = "diff"; + atmel,non-overlap-time = <10>; +}; diff --git a/Documentation/devicetree/bindings/sound/atmel-pdmic.txt b/Documentation/devicetree/bindings/sound/atmel-pdmic.txt new file mode 100644 index 000000000000..e0875f17c229 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/atmel-pdmic.txt @@ -0,0 +1,55 @@ +* Atmel PDMIC driver under ALSA SoC architecture + +Required properties: +- compatible + Should be "atmel,sama5d2-pdmic". +- reg + Should contain PDMIC registers location and length. +- interrupts + Should contain the IRQ line for the PDMIC. +- dmas + One DMA specifiers as described in atmel-dma.txt and dma.txt files. +- dma-names + Must be "rx". +- clock-names + Required elements: + - "pclk" peripheral clock + - "gclk" generated clock +- clocks + Must contain an entry for each required entry in clock-names. + Please refer to clock-bindings.txt. +- atmel,mic-min-freq + The minimal frequency that the micphone supports. +- atmel,mic-max-freq + The maximal frequency that the micphone supports. + +Optional properties: +- pinctrl-names, pinctrl-0 + Please refer to pinctrl-bindings.txt. +- atmel,model + The user-visible name of this sound card. + The default value is "PDMIC". +- atmel,mic-offset + The offset that should be added. + The range is from -32768 to 32767. + The default value is 0. + +Example: + pdmic@f8018000 { + compatible = "atmel,sama5d2-pdmic"; + reg = <0xf8018000 0x124>; + interrupts = <48 IRQ_TYPE_LEVEL_HIGH 7>; + dmas = <&dma0 + (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) + | AT91_XDMAC_DT_PERID(50))>; + dma-names = "rx"; + clocks = <&pdmic_clk>, <&pdmic_gclk>; + clock-names = "pclk", "gclk"; + + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pdmic_default>; + atmel,model = "PDMIC @ sama5d2_xplained"; + atmel,mic-min-freq = <1000000>; + atmel,mic-max-freq = <3246000>; + atmel,mic-offset = <0x0>; + }; diff --git a/Documentation/devicetree/bindings/sound/cs4271.txt b/Documentation/devicetree/bindings/sound/cs4271.txt index e2cd1d7539e5..6e699ceabacd 100644 --- a/Documentation/devicetree/bindings/sound/cs4271.txt +++ b/Documentation/devicetree/bindings/sound/cs4271.txt @@ -33,12 +33,19 @@ Optional properties: Note that this is not needed in case the clocks are stable throughout the entire runtime of the codec. + - vd-supply: Digital power + - vl-supply: Logic power + - va-supply: Analog Power + Examples: codec_i2c: cs4271@10 { compatible = "cirrus,cs4271"; reg = <0x10>; reset-gpio = <&gpio 23 0>; + vd-supply = <&vdd_3v3_reg>; + vl-supply = <&vdd_3v3_reg>; + va-supply = <&vdd_3v3_reg>; }; codec_spi: cs4271@0 { diff --git a/Documentation/devicetree/bindings/sound/da7213.txt b/Documentation/devicetree/bindings/sound/da7213.txt new file mode 100644 index 000000000000..58902802d56c --- /dev/null +++ b/Documentation/devicetree/bindings/sound/da7213.txt @@ -0,0 +1,41 @@ +Dialog Semiconductor DA7213 Audio Codec bindings + +====== + +Required properties: +- compatible : Should be "dlg,da7213" +- reg: Specifies the I2C slave address + +Optional properties: +- clocks : phandle and clock specifier for codec MCLK. +- clock-names : Clock name string for 'clocks' attribute, should be "mclk". + +- dlg,micbias1-lvl : Voltage (mV) for Mic Bias 1 + [<1600>, <2200>, <2500>, <3000>] +- dlg,micbias2-lvl : Voltage (mV) for Mic Bias 2 + [<1600>, <2200>, <2500>, <3000>] +- dlg,dmic-data-sel : DMIC channel select based on clock edge. + ["lrise_rfall", "lfall_rrise"] +- dlg,dmic-samplephase : When to sample audio from DMIC. + ["on_clkedge", "between_clkedge"] +- dlg,dmic-clkrate : DMIC clock frequency (Hz). + [<1500000>, <3000000>] + +====== + +Example: + + codec_i2c: da7213@1a { + compatible = "dlg,da7213"; + reg = <0x1a>; + + clocks = <&clks 201>; + clock-names = "mclk"; + + dlg,micbias1-lvl = <2500>; + dlg,micbias2-lvl = <2500>; + + dlg,dmic-data-sel = "lrise_rfall"; + dlg,dmic-samplephase = "between_clkedge"; + dlg,dmic-clkrate = <3000000>; + }; diff --git a/Documentation/devicetree/bindings/sound/da7218.txt b/Documentation/devicetree/bindings/sound/da7218.txt new file mode 100644 index 000000000000..5ca5a709b6aa --- /dev/null +++ b/Documentation/devicetree/bindings/sound/da7218.txt @@ -0,0 +1,104 @@ +Dialog Semiconductor DA7218 Audio Codec bindings + +DA7218 is an audio codec with HP detect feature. + +====== + +Required properties: +- compatible : Should be "dlg,da7217" or "dlg,da7218" +- reg: Specifies the I2C slave address + +- VDD-supply: VDD power supply for the device +- VDDMIC-supply: VDDMIC power supply for the device +- VDDIO-supply: VDDIO power supply for the device + (See Documentation/devicetree/bindings/regulator/regulator.txt for further + information relating to regulators) + +Optional properties: +- interrupt-parent: Specifies the phandle of the interrupt controller to which + the IRQs from DA7218 are delivered to. +- interrupts: IRQ line info for DA7218 chip. + (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for + further information relating to interrupt properties) +- interrupt-names : Name associated with interrupt line. Should be "wakeup" if + interrupt is to be used to wake system, otherwise "irq" should be used. +- wakeup-source: Flag to indicate this device can wake system (suspend/resume). + +- clocks : phandle and clock specifier for codec MCLK. +- clock-names : Clock name string for 'clocks' attribute, should be "mclk". + +- dlg,micbias1-lvl-millivolt : Voltage (mV) for Mic Bias 1 + [<1200>, <1600>, <1800>, <2000>, <2200>, <2400>, <2600>, <2800>, <3000>] +- dlg,micbias2-lvl-millivolt : Voltage (mV) for Mic Bias 2 + [<1200>, <1600>, <1800>, <2000>, <2200>, <2400>, <2600>, <2800>, <3000>] +- dlg,mic1-amp-in-sel : Mic1 input source type + ["diff", "se_p", "se_n"] +- dlg,mic2-amp-in-sel : Mic2 input source type + ["diff", "se_p", "se_n"] +- dlg,dmic1-data-sel : DMIC1 channel select based on clock edge. + ["lrise_rfall", "lfall_rrise"] +- dlg,dmic1-samplephase : When to sample audio from DMIC1. + ["on_clkedge", "between_clkedge"] +- dlg,dmic1-clkrate-hz : DMic1 clock frequency (Hz). + [<1500000>, <3000000>] +- dlg,dmic2-data-sel : DMic2 channel select based on clock edge. + ["lrise_rfall", "lfall_rrise"] +- dlg,dmic2-samplephase : When to sample audio from DMic2. + ["on_clkedge", "between_clkedge"] +- dlg,dmic2-clkrate-hz : DMic2 clock frequency (Hz). + [<1500000>, <3000000>] +- dlg,hp-diff-single-supply : Boolean flag, use single supply for HP + (DA7217 only) + +====== + +Optional Child node - 'da7218_hpldet' (DA7218 only): + +Optional properties: +- dlg,jack-rate-us : Time between jack detect measurements (us) + [<5>, <10>, <20>, <40>, <80>, <160>, <320>, <640>] +- dlg,jack-debounce : Number of debounce measurements taken for jack detect + [<0>, <2>, <3>, <4>] +- dlg,jack-threshold-pct : Threshold level for jack detection (% of VDD) + [<84>, <88>, <92>, <96>] +- dlg,comp-inv : Boolean flag, invert comparator output +- dlg,hyst : Boolean flag, enable hysteresis +- dlg,discharge : Boolean flag, auto discharge of Mic Bias on jack removal + +====== + +Example: + + codec: da7218@1a { + compatible = "dlg,da7218"; + reg = <0x1a>; + interrupt-parent = <&gpio6>; + interrupts = <11 IRQ_TYPE_LEVEL_HIGH>; + wakeup-source; + + VDD-supply = <®_audio>; + VDDMIC-supply = <®_audio>; + VDDIO-supply = <®_audio>; + + clocks = <&clks 201>; + clock-names = "mclk"; + + dlg,micbias1-lvl-millivolt = <2600>; + dlg,micbias2-lvl-millivolt = <2600>; + dlg,mic1-amp-in-sel = "diff"; + dlg,mic2-amp-in-sel = "diff"; + + dlg,dmic1-data-sel = "lrise_rfall"; + dlg,dmic1-samplephase = "on_clkedge"; + dlg,dmic1-clkrate-hz = <3000000>; + dlg,dmic2-data-sel = "lrise_rfall"; + dlg,dmic2-samplephase = "on_clkedge"; + dlg,dmic2-clkrate-hz = <3000000>; + + da7218_hpldet { + dlg,jack-rate-us = <40>; + dlg,jack-debounce = <2>; + dlg,jack-threshold-pct = <84>; + dlg,hyst; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/da7219.txt b/Documentation/devicetree/bindings/sound/da7219.txt new file mode 100644 index 000000000000..cf61681826b6 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/da7219.txt @@ -0,0 +1,108 @@ +Dialog Semiconductor DA7219 Audio Codec bindings + +DA7219 is an audio codec with advanced accessory detect features. + +====== + +Required properties: +- compatible : Should be "dlg,da7219" +- reg: Specifies the I2C slave address + +- interrupt-parent : Specifies the phandle of the interrupt controller to which + the IRQs from DA7219 are delivered to. +- interrupts : IRQ line info for DA7219. + (See Documentation/devicetree/bindings/interrupt-controller/interrupts.txt for + further information relating to interrupt properties) + +- VDD-supply: VDD power supply for the device +- VDDMIC-supply: VDDMIC power supply for the device +- VDDIO-supply: VDDIO power supply for the device + (See Documentation/devicetree/bindings/regulator/regulator.txt for further + information relating to regulators) + +Optional properties: +- interrupt-names : Name associated with interrupt line. Should be "wakeup" if + interrupt is to be used to wake system, otherwise "irq" should be used. +- wakeup-source: Flag to indicate this device can wake system (suspend/resume). + +- clocks : phandle and clock specifier for codec MCLK. +- clock-names : Clock name string for 'clocks' attribute, should be "mclk". + +- dlg,micbias-lvl : Voltage (mV) for Mic Bias + [<1600>, <1800>, <2000>, <2200>, <2400>, <2600>] +- dlg,mic-amp-in-sel : Mic input source type + ["diff", "se_p", "se_n"] + +Deprecated properties: +- dlg,ldo-lvl : Required internal LDO voltage (mV) level for digital engine + (LDO unavailable in production HW so property no longer required). + +====== + +Child node - 'da7219_aad': + +Optional properties: +- dlg,micbias-pulse-lvl : Mic bias higher voltage pulse level (mV). + [<2800>, <2900>] +- dlg,micbias-pulse-time : Mic bias higher voltage pulse duration (ms) +- dlg,btn-cfg : Periodic button press measurements for 4-pole jack (ms) + [<2>, <5>, <10>, <50>, <100>, <200>, <500>] +- dlg,mic-det-thr : Impedance threshold for mic detection measurement (Ohms) + [<200>, <500>, <750>, <1000>] +- dlg,jack-ins-deb : Debounce time for jack insertion (ms) + [<5>, <10>, <20>, <50>, <100>, <200>, <500>, <1000>] +- dlg,jack-det-rate: Jack type detection latency (3/4 pole) + ["32ms_64ms", "64ms_128ms", "128ms_256ms", "256ms_512ms"] +- dlg,jack-rem-deb : Debounce time for jack removal (ms) + [<1>, <5>, <10>, <20>] +- dlg,a-d-btn-thr : Impedance threshold between buttons A and D + [0x0 - 0xFF] +- dlg,d-b-btn-thr : Impedance threshold between buttons D and B + [0x0 - 0xFF] +- dlg,b-c-btn-thr : Impedance threshold between buttons B and C + [0x0 - 0xFF] +- dlg,c-mic-btn-thr : Impedance threshold between button C and Mic + [0x0 - 0xFF] +- dlg,btn-avg : Number of 8-bit readings for averaged button measurement + [<1>, <2>, <4>, <8>] +- dlg,adc-1bit-rpt : Repeat count for 1-bit button measurement + [<1>, <2>, <4>, <8>] + +====== + +Example: + + codec: da7219@1a { + compatible = "dlg,da7219"; + reg = <0x1a>; + + interrupt-parent = <&gpio6>; + interrupts = <11 IRQ_TYPE_LEVEL_HIGH>; + + VDD-supply = <®_audio>; + VDDMIC-supply = <®_audio>; + VDDIO-supply = <®_audio>; + + clocks = <&clks 201>; + clock-names = "mclk"; + + dlg,ldo-lvl = <1200>; + dlg,micbias-lvl = <2600>; + dlg,mic-amp-in-sel = "diff"; + + da7219_aad { + dlg,btn-cfg = <50>; + dlg,mic-det-thr = <500>; + dlg,jack-ins-deb = <20>; + dlg,jack-det-rate = "32ms_64ms"; + dlg,jack-rem-deb = <1>; + + dlg,a-d-btn-thr = <0xa>; + dlg,d-b-btn-thr = <0x16>; + dlg,b-c-btn-thr = <0x21>; + dlg,c-mic-btn-thr = <0x3E>; + + dlg,btn-avg = <4>; + dlg,adc-1bit-rpt = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/fsl,asrc.txt b/Documentation/devicetree/bindings/sound/fsl,asrc.txt index b93362a570be..3e26a9478e57 100644 --- a/Documentation/devicetree/bindings/sound/fsl,asrc.txt +++ b/Documentation/devicetree/bindings/sound/fsl,asrc.txt @@ -25,6 +25,11 @@ Required properties: "mem" Peripheral access clock to access registers. "ipg" Peripheral clock to driver module. "asrck_<0-f>" Clock sources for input and output clock. + "spba" The spba clock is required when ASRC is placed as a + bus slave of the Shared Peripheral Bus and when two + or more bus masters (CPU, DMA or DSP) try to access + it. This property is optional depending on the SoC + design. - big-endian : If this property is absent, the little endian mode will be in use as default. Otherwise, the big endian diff --git a/Documentation/devicetree/bindings/sound/fsl,esai.txt b/Documentation/devicetree/bindings/sound/fsl,esai.txt index d3b6b5f48010..cd3ee5d84f03 100644 --- a/Documentation/devicetree/bindings/sound/fsl,esai.txt +++ b/Documentation/devicetree/bindings/sound/fsl,esai.txt @@ -27,6 +27,11 @@ Required properties: derive HCK, SCK and FS. "fsys" The system clock derived from ahb clock used to derive HCK, SCK and FS. + "spba" The spba clock is required when ESAI is placed as a + bus slave of the Shared Peripheral Bus and when two + or more bus masters (CPU, DMA or DSP) try to access + it. This property is optional depending on the SoC + design. - fsl,fifo-depth : The number of elements in the transmit and receive FIFOs. This number is the maximum allowed value for diff --git a/Documentation/devicetree/bindings/sound/fsl,spdif.txt b/Documentation/devicetree/bindings/sound/fsl,spdif.txt index b5ee32ee3706..4ca39ddc0417 100644 --- a/Documentation/devicetree/bindings/sound/fsl,spdif.txt +++ b/Documentation/devicetree/bindings/sound/fsl,spdif.txt @@ -27,6 +27,11 @@ Required properties: Transceiver Clock Diagram" of SoC reference manual. It can also be referred to TxClk_Source bit of register SPDIF_STC. + "spba" The spba clock is required when SPDIF is placed as a + bus slave of the Shared Peripheral Bus and when two + or more bus masters (CPU, DMA or DSP) try to access + it. This property is optional depending on the SoC + design. - big-endian : If this property is absent, the native endian mode will be in use as default, or the big endian mode diff --git a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt index a96774c194c8..ceaef5126989 100644 --- a/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/fsl-asoc-card.txt @@ -13,21 +13,28 @@ So having this generic sound card allows all Freescale SoC users to benefit from the simplification of a new card support and the capability of the wide sample rates support through ASRC. -Note: The card is initially designed for those sound cards who use I2S and - PCM DAI formats. However, it'll be also possible to support those non - I2S/PCM type sound cards, such as S/PDIF audio and HDMI audio, as long - as the driver has been properly upgraded. +Note: The card is initially designed for those sound cards who use AC'97, I2S + and PCM DAI formats. However, it'll be also possible to support those non + AC'97/I2S/PCM type sound cards, such as S/PDIF audio and HDMI audio, as + long as the driver has been properly upgraded. The compatible list for this generic sound card currently: + "fsl,imx-audio-ac97" + "fsl,imx-audio-cs42888" + "fsl,imx-audio-cs427x" + (compatible with CS4271 and CS4272) + "fsl,imx-audio-wm8962" (compatible with Documentation/devicetree/bindings/sound/imx-audio-wm8962.txt) "fsl,imx-audio-sgtl5000" (compatible with Documentation/devicetree/bindings/sound/imx-audio-sgtl5000.txt) + "fsl,imx-audio-wm8960" + Required properties: - compatible : Contains one of entries in the compatible list. @@ -59,6 +66,12 @@ Optional properties: - audio-asrc : The phandle of ASRC. It can be absent if there's no need to add ASRC support via DPCM. +Optional unless SSI is selected as a CPU DAI: + + - mux-int-port : The internal port of the i.MX audio muxer (AUDMUX) + + - mux-ext-port : The external port of the i.MX audio muxer + Example: sound-cs42888 { compatible = "fsl,imx-audio-cs42888"; diff --git a/Documentation/devicetree/bindings/sound/img,i2s-in.txt b/Documentation/devicetree/bindings/sound/img,i2s-in.txt new file mode 100644 index 000000000000..423265cfc3d6 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/img,i2s-in.txt @@ -0,0 +1,47 @@ +Imagination Technologies I2S Input Controller + +Required Properties: + + - compatible : Compatible list, must contain "img,i2s-in" + + - #sound-dai-cells : Must be equal to 0 + + - reg : Offset and length of the register set for the device + + - clocks : Contains an entry for each entry in clock-names + + - clock-names : Must include the following entry: + "sys" The system clock + + - dmas: Contains an entry for each entry in dma-names. + + - dma-names: Must include the following entry: + "rx" Single DMA channel used by all active I2S channels + + - img,i2s-channels : Number of I2S channels instantiated in the I2S in block + +Optional Properties: + + - interrupts : Contains the I2S in interrupts. Depending on + the configuration, there may be no interrupts, one interrupt, + or an interrupt per I2S channel. For the case where there is + one interrupt per channel, the interrupts should be listed + in ascending channel order + + - resets: Contains a phandle to the I2S in reset signal + + - reset-names: Contains the reset signal name "rst" + +Example: + +i2s_in: i2s-in@18100800 { + compatible = "img,i2s-in"; + reg = <0x18100800 0x200>; + interrupts = <GIC_SHARED 7 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&mdc 30 0xffffffff 0>; + dma-names = "rx"; + clocks = <&cr_periph SYS_CLK_I2S_IN>; + clock-names = "sys"; + img,i2s-channels = <6>; + #sound-dai-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/sound/img,i2s-out.txt b/Documentation/devicetree/bindings/sound/img,i2s-out.txt new file mode 100644 index 000000000000..0159415b3338 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/img,i2s-out.txt @@ -0,0 +1,51 @@ +Imagination Technologies I2S Output Controller + +Required Properties: + + - compatible : Compatible list, must contain "img,i2s-out" + + - #sound-dai-cells : Must be equal to 0 + + - reg : Offset and length of the register set for the device + + - clocks : Contains an entry for each entry in clock-names + + - clock-names : Must include the following entries: + "sys" The system clock + "ref" The reference clock + + - dmas: Contains an entry for each entry in dma-names. + + - dma-names: Must include the following entry: + "tx" Single DMA channel used by all active I2S channels + + - img,i2s-channels : Number of I2S channels instantiated in the I2S out block + + - resets: Contains a phandle to the I2S out reset signal + + - reset-names: Contains the reset signal name "rst" + +Optional Properties: + + - interrupts : Contains the I2S out interrupts. Depending on + the configuration, there may be no interrupts, one interrupt, + or an interrupt per I2S channel. For the case where there is + one interrupt per channel, the interrupts should be listed + in ascending channel order + +Example: + +i2s_out: i2s-out@18100A00 { + compatible = "img,i2s-out"; + reg = <0x18100A00 0x200>; + interrupts = <GIC_SHARED 13 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&mdc 23 0xffffffff 0>; + dma-names = "tx"; + clocks = <&cr_periph SYS_CLK_I2S_OUT>, + <&clk_core CLK_I2S>; + clock-names = "sys", "ref"; + img,i2s-channels = <6>; + resets = <&pistachio_reset PISTACHIO_RESET_I2S_OUT>; + reset-names = "rst"; + #sound-dai-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/sound/img,parallel-out.txt b/Documentation/devicetree/bindings/sound/img,parallel-out.txt new file mode 100644 index 000000000000..a3015d2a06e0 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/img,parallel-out.txt @@ -0,0 +1,44 @@ +Imagination Technologies Parallel Output Controller + +Required Properties: + + - compatible : Compatible list, must contain "img,parallel-out". + + - #sound-dai-cells : Must be equal to 0 + + - reg : Offset and length of the register set for the device. + + - dmas: Contains an entry for each entry in dma-names. + + - dma-names: Must include the following entry: + "tx" + + - clocks : Contains an entry for each entry in clock-names. + + - clock-names : Includes the following entries: + "sys" The system clock + "ref" The reference clock + + - resets: Contains a phandle to the parallel out reset signal + + - reset-names: Contains the reset signal name "rst" + +Optional Properties: + + - interrupts : Contains the parallel out interrupt, if present + +Example: + +parallel_out: parallel-out@18100C00 { + compatible = "img,parallel-out"; + reg = <0x18100C00 0x100>; + interrupts = <GIC_SHARED 19 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&mdc 16 0xffffffff 0>; + dma-names = "tx"; + clocks = <&cr_periph SYS_CLK_PAUD_OUT>, + <&clk_core CLK_AUDIO_DAC>; + clock-names = "sys", "ref"; + resets = <&pistachio_reset PISTACHIO_RESET_PRL_OUT>; + reset-names = "rst"; + #sound-dai-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/sound/img,pistachio-internal-dac.txt b/Documentation/devicetree/bindings/sound/img,pistachio-internal-dac.txt new file mode 100644 index 000000000000..4cc18fc0477e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/img,pistachio-internal-dac.txt @@ -0,0 +1,18 @@ +Pistachio internal DAC DT bindings + +Required properties: + + - compatible: "img,pistachio-internal-dac" + + - img,cr-top : Must contain a phandle to the top level control syscon + node which contains the internal dac control registers + + - VDD-supply : Digital power supply regulator (+1.8V or +3.3V) + +Examples: + +internal_dac: internal-dac { + compatible = "img,pistachio-internal-dac"; + img,cr-top = <&cr_top>; + VDD-supply = <&supply3v3>; +}; diff --git a/Documentation/devicetree/bindings/sound/img,spdif-in.txt b/Documentation/devicetree/bindings/sound/img,spdif-in.txt new file mode 100644 index 000000000000..aab9a81f7e13 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/img,spdif-in.txt @@ -0,0 +1,41 @@ +Imagination Technologies SPDIF Input Controller + +Required Properties: + + - compatible : Compatible list, must contain "img,spdif-in" + + - #sound-dai-cells : Must be equal to 0 + + - reg : Offset and length of the register set for the device + + - dmas: Contains an entry for each entry in dma-names. + + - dma-names: Must include the following entry: + "rx" + + - clocks : Contains an entry for each entry in clock-names + + - clock-names : Includes the following entries: + "sys" The system clock + +Optional Properties: + + - resets: Should contain a phandle to the spdif in reset signal, if any + + - reset-names: Should contain the reset signal name "rst", if a + reset phandle is given + + - interrupts : Contains the spdif in interrupt, if present + +Example: + +spdif_in: spdif-in@18100E00 { + compatible = "img,spdif-in"; + reg = <0x18100E00 0x100>; + interrupts = <GIC_SHARED 20 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&mdc 15 0xffffffff 0>; + dma-names = "rx"; + clocks = <&cr_periph SYS_CLK_SPDIF_IN>; + clock-names = "sys"; + #sound-dai-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/sound/img,spdif-out.txt b/Documentation/devicetree/bindings/sound/img,spdif-out.txt new file mode 100644 index 000000000000..470a5191e101 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/img,spdif-out.txt @@ -0,0 +1,44 @@ +Imagination Technologies SPDIF Output Controller + +Required Properties: + + - compatible : Compatible list, must contain "img,spdif-out" + + - #sound-dai-cells : Must be equal to 0 + + - reg : Offset and length of the register set for the device + + - dmas: Contains an entry for each entry in dma-names. + + - dma-names: Must include the following entry: + "tx" + + - clocks : Contains an entry for each entry in clock-names. + + - clock-names : Includes the following entries: + "sys" The system clock + "ref" The reference clock + + - resets: Contains a phandle to the spdif out reset signal + + - reset-names: Contains the reset signal name "rst" + +Optional Properties: + + - interrupts : Contains the parallel out interrupt, if present + +Example: + +spdif_out: spdif-out@18100D00 { + compatible = "img,spdif-out"; + reg = <0x18100D00 0x100>; + interrupts = <GIC_SHARED 21 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&mdc 14 0xffffffff 0>; + dma-names = "tx"; + clocks = <&cr_periph SYS_CLK_SPDIF_OUT>, + <&clk_core CLK_SPDIF>; + clock-names = "sys", "ref"; + resets = <&pistachio_reset PISTACHIO_RESET_SPDIF_OUT>; + reset-names = "rst"; + #sound-dai-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/sound/inno-rk3036.txt b/Documentation/devicetree/bindings/sound/inno-rk3036.txt new file mode 100644 index 000000000000..758de8e27561 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/inno-rk3036.txt @@ -0,0 +1,20 @@ +Inno audio codec for RK3036 + +Inno audio codec is integrated inside RK3036 SoC. + +Required properties: +- compatible : Should be "rockchip,rk3036-codec". +- reg : The registers of codec. +- clock-names : Should be "acodec_pclk". +- clocks : The clock of codec. +- rockchip,grf : The phandle of grf device node. + +Example: + + acodec: acodec-ana@20030000 { + compatible = "rk3036-codec"; + reg = <0x20030000 0x4000>; + rockchip,grf = <&grf>; + clock-names = "acodec_pclk"; + clocks = <&cru ACLK_VCODEC>; + }; diff --git a/Documentation/devicetree/bindings/sound/max9867.txt b/Documentation/devicetree/bindings/sound/max9867.txt new file mode 100644 index 000000000000..394cd4eb17ec --- /dev/null +++ b/Documentation/devicetree/bindings/sound/max9867.txt @@ -0,0 +1,17 @@ +max9867 codec + +This device supports I2C mode only. + +Required properties: + +- compatible : "maxim,max9867" +- reg : The chip select number on the I2C bus + +Example: + +&i2c { + max9867: max9867@0x18 { + compatible = "maxim,max9867"; + reg = <0x18>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/max98926.txt b/Documentation/devicetree/bindings/sound/max98926.txt new file mode 100644 index 000000000000..0b7f4e4d5f9a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/max98926.txt @@ -0,0 +1,32 @@ +max98926 audio CODEC + +This device supports I2C. + +Required properties: + + - compatible : "maxim,max98926" + + - vmon-slot-no : slot number used to send voltage information + or in inteleave mode this will be used as + interleave slot. + + - imon-slot-no : slot number used to send current information + + - interleave-mode : When using two MAX98926 in a system it is + possible to create ADC data that that will + overflow the frame size. Digital Audio Interleave + mode provides a means to output VMON and IMON data + from two devices on a single DOUT line when running + smaller frames sizes such as 32 BCLKS per LRCLK or + 48 BCLKS per LRCLK. + + - reg : the I2C address of the device for I2C + +Example: + +codec: max98926@1a { + compatible = "maxim,max98926"; + vmon-slot-no = <0>; + imon-slot-no = <2>; + reg = <0x1a>; +}; diff --git a/Documentation/devicetree/bindings/sound/mt8173-rt5650-rt5514.txt b/Documentation/devicetree/bindings/sound/mt8173-rt5650-rt5514.txt new file mode 100644 index 000000000000..e8b3c80c6fff --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8173-rt5650-rt5514.txt @@ -0,0 +1,15 @@ +MT8173 with RT5650 RT5514 CODECS + +Required properties: +- compatible : "mediatek,mt8173-rt5650-rt5514" +- mediatek,audio-codec: the phandles of rt5650 and rt5514 codecs +- mediatek,platform: the phandle of MT8173 ASoC platform + +Example: + + sound { + compatible = "mediatek,mt8173-rt5650-rt5514"; + mediatek,audio-codec = <&rt5650 &rt5514>; + mediatek,platform = <&afe>; + }; + diff --git a/Documentation/devicetree/bindings/sound/mt8173-rt5650.txt b/Documentation/devicetree/bindings/sound/mt8173-rt5650.txt new file mode 100644 index 000000000000..fe5a5ef1714d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8173-rt5650.txt @@ -0,0 +1,15 @@ +MT8173 with RT5650 CODECS + +Required properties: +- compatible : "mediatek,mt8173-rt5650" +- mediatek,audio-codec: the phandles of rt5650 codecs +- mediatek,platform: the phandle of MT8173 ASoC platform + +Example: + + sound { + compatible = "mediatek,mt8173-rt5650"; + mediatek,audio-codec = <&rt5650>; + mediatek,platform = <&afe>; + }; + diff --git a/Documentation/devicetree/bindings/sound/nau8825.txt b/Documentation/devicetree/bindings/sound/nau8825.txt new file mode 100644 index 000000000000..d3374231c871 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nau8825.txt @@ -0,0 +1,102 @@ +Nuvoton NAU8825 audio codec + +This device supports I2C only. + +Required properties: + - compatible : Must be "nuvoton,nau8825" + + - reg : the I2C address of the device. This is either 0x1a (CSB=0) or 0x1b (CSB=1). + +Optional properties: + - nuvoton,jkdet-enable: Enable jack detection via JKDET pin. + - nuvoton,jkdet-pull-enable: Enable JKDET pin pull. If set - pin pull enabled, + otherwise pin in high impedance state. + - nuvoton,jkdet-pull-up: Pull-up JKDET pin. If set then JKDET pin is pull up, otherwise pull down. + - nuvoton,jkdet-polarity: JKDET pin polarity. 0 - active high, 1 - active low. + + - nuvoton,vref-impedance: VREF Impedance selection + 0 - Open + 1 - 25 kOhm + 2 - 125 kOhm + 3 - 2.5 kOhm + + - nuvoton,micbias-voltage: Micbias voltage level. + 0 - VDDA + 1 - VDDA + 2 - VDDA * 1.1 + 3 - VDDA * 1.2 + 4 - VDDA * 1.3 + 5 - VDDA * 1.4 + 6 - VDDA * 1.53 + 7 - VDDA * 1.53 + + - nuvoton,sar-threshold-num: Number of buttons supported + - nuvoton,sar-threshold: Impedance threshold for each button. Array that contains up to 8 buttons configuration. SAR value is calculated as + SAR = 255 * MICBIAS / SAR_VOLTAGE * R / (2000 + R) + where MICBIAS is configured by 'nuvoton,micbias-voltage', SAR_VOLTAGE is configured by 'nuvoton,sar-voltage', R - button impedance. + Refer datasheet section 10.2 for more information about threshold calculation. + + - nuvoton,sar-hysteresis: Button impedance measurement hysteresis. + + - nuvoton,sar-voltage: Reference voltage for button impedance measurement. + 0 - VDDA + 1 - VDDA + 2 - VDDA * 1.1 + 3 - VDDA * 1.2 + 4 - VDDA * 1.3 + 5 - VDDA * 1.4 + 6 - VDDA * 1.53 + 7 - VDDA * 1.53 + + - nuvoton,sar-compare-time: SAR compare time + 0 - 500 ns + 1 - 1 us + 2 - 2 us + 3 - 4 us + + - nuvoton,sar-sampling-time: SAR sampling time + 0 - 2 us + 1 - 4 us + 2 - 8 us + 3 - 16 us + + - nuvoton,short-key-debounce: Button short key press debounce time. + 0 - 30 ms + 1 - 50 ms + 2 - 100 ms + 3 - 30 ms + + - nuvoton,jack-insert-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms + - nuvoton,jack-eject-debounce: number from 0 to 7 that sets debounce time to 2^(n+2) ms + + - clocks: list of phandle and clock specifier pairs according to common clock bindings for the + clocks described in clock-names + - clock-names: should include "mclk" for the MCLK master clock + +Example: + + headset: nau8825@1a { + compatible = "nuvoton,nau8825"; + reg = <0x1a>; + interrupt-parent = <&gpio>; + interrupts = <TEGRA_GPIO(E, 6) IRQ_TYPE_LEVEL_LOW>; + nuvoton,jkdet-enable; + nuvoton,jkdet-pull-enable; + nuvoton,jkdet-pull-up; + nuvoton,jkdet-polarity = <GPIO_ACTIVE_LOW>; + nuvoton,vref-impedance = <2>; + nuvoton,micbias-voltage = <6>; + // Setup 4 buttons impedance according to Android specification + nuvoton,sar-threshold-num = <4>; + nuvoton,sar-threshold = <0xc 0x1e 0x38 0x60>; + nuvoton,sar-hysteresis = <1>; + nuvoton,sar-voltage = <0>; + nuvoton,sar-compare-time = <0>; + nuvoton,sar-sampling-time = <0>; + nuvoton,short-key-debounce = <2>; + nuvoton,jack-insert-debounce = <7>; + nuvoton,jack-eject-debounce = <7>; + + clock-names = "mclk"; + clocks = <&tegra_car TEGRA210_CLK_CLK_OUT_2>; + }; diff --git a/Documentation/devicetree/bindings/sound/pcm1792a.txt b/Documentation/devicetree/bindings/sound/pcm179x.txt index 970ba1ed576f..436c2b247693 100644 --- a/Documentation/devicetree/bindings/sound/pcm1792a.txt +++ b/Documentation/devicetree/bindings/sound/pcm179x.txt @@ -1,6 +1,6 @@ -Texas Instruments pcm1792a DT bindings +Texas Instruments pcm179x DT bindings -This driver supports the SPI bus. +This driver supports both the I2C and SPI bus. Required properties: @@ -9,6 +9,11 @@ Required properties: For required properties on SPI, please consult Documentation/devicetree/bindings/spi/spi-bus.txt +Required properties on I2C: + + - reg: the I2C address + + Examples: codec_spi: 1792a@0 { @@ -16,3 +21,7 @@ Examples: spi-max-frequency = <600000>; }; + codec_i2c: 1792a@4c { + compatible = "ti,pcm1792a"; + reg = <0x4c>; + }; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index 1173395b5e5c..c7b29df4a963 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -1,13 +1,349 @@ Renesas R-Car sound +============================================= +* Modules +============================================= + +Renesas R-Car sound is constructed from below modules +(for Gen2 or later) + + SCU : Sampling Rate Converter Unit + - SRC : Sampling Rate Converter + - CMD + - CTU : Channel Transfer Unit + - MIX : Mixer + - DVC : Digital Volume and Mute Function + SSIU : Serial Sound Interface Unit + SSI : Serial Sound Interface + +See detail of each module's channels, connection, limitation on datasheet + +============================================= +* Multi channel +============================================= + +Multi channel is supported by Multi-SSI, or TDM-SSI. + + Multi-SSI : 6ch case, you can use stereo x 3 SSI + TDM-SSI : 6ch case, you can use TDM + +============================================= +* Enable/Disable each modules +============================================= + +See datasheet to check SRC/CTU/MIX/DVC connect-limitation. +DT controls enabling/disabling module. +${LINUX}/arch/arm/boot/dts/r8a7790-lager.dts can be good example. +This is example of + +Playback: [MEM] -> [SRC2] -> [DVC0] -> [SSIU0/SSI0] -> [codec] +Capture: [MEM] <- [DVC1] <- [SRC3] <- [SSIU1/SSI1] <- [codec] + + &rcar_sound { + ... + rcar_sound,dai { + dai0 { + playback = <&ssi0 &src2 &dvc0>; + capture = <&ssi1 &src3 &dvc1>; + }; + }; + }; + +You can use below. +${LINUX}/arch/arm/boot/dts/r8a7790.dts can be good example. + + &src0 &ctu00 &mix0 &dvc0 &ssi0 + &src1 &ctu01 &mix1 &dvc1 &ssi1 + &src2 &ctu02 &ssi2 + &src3 &ctu03 &ssi3 + &src4 &ssi4 + &src5 &ctu10 &ssi5 + &src6 &ctu11 &ssi6 + &src7 &ctu12 &ssi7 + &src8 &ctu13 &ssi8 + &src9 &ssi9 + +============================================= +* SRC (Sampling Rate Converter) +============================================= + + [xx]Hz [yy]Hz + ------> [SRC] ------> + +SRC can convert [xx]Hz to [yy]Hz. Then, it has below 2 modes + + Asynchronous mode: input data / output data are based on different clocks. + you can use this mode on Playback / Capture + Synchronous mode: input data / output data are based on same clocks. + This mode will be used if system doesn't have its input clock, + for example digital TV case. + you can use this mode on Playback + +------------------ +** Asynchronous mode +------------------ + +You need to use "renesas,rsrc-card" sound card for it. +example) + + sound { + compatible = "renesas,rsrc-card"; + ... + /* + * SRC Asynchronous mode setting + * Playback: + * All input data will be converted to 48kHz + * Capture: + * Inputed 48kHz data will be converted to + * system specified Hz + */ + convert-rate = <48000>; + ... + cpu { + sound-dai = <&rcar_sound>; + }; + codec { + ... + }; + }; + +------------------ +** Synchronous mode +------------------ + + > amixer set "SRC Out Rate" on + > aplay xxxx.wav + > amixer set "SRC Out Rate" 48000 + > amixer set "SRC Out Rate" 44100 + +============================================= +* CTU (Channel Transfer Unit) +============================================= + + [xx]ch [yy]ch + ------> [CTU] --------> + +CTU can convert [xx]ch to [yy]ch, or exchange outputed channel. +CTU conversion needs matrix settings. +For more detail information, see below + + Renesas R-Car datasheet + - Sampling Rate Converter Unit (SCU) + - SCU Operation + - CMD Block + - Functional Blocks in CMD + + Renesas R-Car datasheet + - Sampling Rate Converter Unit (SCU) + - Register Description + - CTUn Scale Value exx Register (CTUn_SVxxR) + + ${LINUX}/sound/soc/sh/rcar/ctu.c + - comment of header + +You need to use "renesas,rsrc-card" sound card for it. +example) + + sound { + compatible = "renesas,rsrc-card"; + ... + /* + * CTU setting + * All input data will be converted to 2ch + * as output data + */ + convert-channels = <2>; + ... + cpu { + sound-dai = <&rcar_sound>; + }; + codec { + ... + }; + }; + +Ex) Exchange output channel + Input -> Output + 1ch -> 0ch + 0ch -> 1ch + + example of using matrix + output 0ch = (input 0ch x 0) + (input 1ch x 1) + output 1ch = (input 0ch x 1) + (input 1ch x 0) + + amixer set "CTU Reset" on + amixer set "CTU Pass" 9,10 + amixer set "CTU SV0" 0,4194304 + amixer set "CTU SV1" 4194304,0 + + example of changing connection + amixer set "CTU Reset" on + amixer set "CTU Pass" 2,1 + +============================================= +* MIX (Mixer) +============================================= + +MIX merges 2 sounds path. You can see 2 sound interface on system, +and these sounds will be merged by MIX. + + aplay -D plughw:0,0 xxxx.wav & + aplay -D plughw:0,1 yyyy.wav + +You need to use "renesas,rsrc-card" sound card for it. +Ex) + [MEM] -> [SRC1] -> [CTU02] -+-> [MIX0] -> [DVC0] -> [SSI0] + | + [MEM] -> [SRC2] -> [CTU03] -+ + + sound { + compatible = "renesas,rsrc-card"; + ... + cpu@0 { + sound-dai = <&rcar_sound 0>; + }; + cpu@1 { + sound-dai = <&rcar_sound 1>; + }; + codec { + ... + }; + }; + + &rcar_sound { + ... + rcar_sound,dai { + dai0 { + playback = <&src1 &ctu02 &mix0 &dvc0 &ssi0>; + }; + dai1 { + playback = <&src2 &ctu03 &mix0 &dvc0 &ssi0>; + }; + }; + }; + +============================================= +* DVC (Digital Volume and Mute Function) +============================================= + +DVC controls Playback/Capture volume. + +Playback Volume + amixer set "DVC Out" 100% + +Capture Volume + amixer set "DVC In" 100% + +Playback Mute + amixer set "DVC Out Mute" on + +Capture Mute + amixer set "DVC In Mute" on + +Volume Ramp + amixer set "DVC Out Ramp Up Rate" "0.125 dB/64 steps" + amixer set "DVC Out Ramp Down Rate" "0.125 dB/512 steps" + amixer set "DVC Out Ramp" on + aplay xxx.wav & + amixer set "DVC Out" 80% // Volume Down + amixer set "DVC Out" 100% // Volume Up + +============================================= +* SSIU (Serial Sound Interface Unit) +============================================= + +There is no DT settings for SSIU, because SSIU will be automatically +selected via SSI. +SSIU can avoid some under/over run error, because it has some buffer. +But you can't use it if SSI was PIO mode. +In DMA mode, you can select not to use SSIU by using "no-busif" on DT. + + &ssi0 { + no-busif; + }; + +============================================= +* SSI (Serial Sound Interface) +============================================= + +** PIO mode + +You can use PIO mode which is for connection check by using. +Note: The system will drop non-SSI modules in PIO mode +even though if DT is selecting other modules. + + &ssi0 { + pio-transfer + }; + +** DMA mode without SSIU + +You can use DMA without SSIU. +Note: under/over run, or noise are likely to occur + + &ssi0 { + no-busif; + }; + +** PIN sharing + +Each SSI can share WS pin. It is based on platform. +This is example if SSI1 want to share WS pin with SSI0 + + &ssi1 { + shared-pin; + }; + +** Multi-SSI + +You can use Multi-SSI. +This is example of SSI0/SSI1/SSI2 (= for 6ch) + + &rcar_sound { + ... + rcar_sound,dai { + dai0 { + playback = <&ssi0 &ssi1 &ssi2 &src0 &dvc0>; + }; + }; + }; + +** TDM-SSI + +You can use TDM with SSI. +This is example of TDM 6ch. +Driver can automatically switches TDM <-> stereo mode in this case. + + rsnd_tdm: sound { + compatible = "simple-audio-card"; + ... + simple-audio-card,cpu { + /* system can use TDM 6ch */ + dai-tdm-slot-num = <6>; + sound-dai = <&rcar_sound>; + }; + simple-audio-card,codec { + ... + }; + }; + + +============================================= Required properties: +============================================= + - compatible : "renesas,rcar_sound-<soctype>", fallbacks "renesas,rcar_sound-gen1" if generation1, and "renesas,rcar_sound-gen2" if generation2 + "renesas,rcar_sound-gen3" if generation3 Examples with soctypes are: - "renesas,rcar_sound-r8a7778" (R-Car M1A) + - "renesas,rcar_sound-r8a7779" (R-Car H1) - "renesas,rcar_sound-r8a7790" (R-Car H2) - "renesas,rcar_sound-r8a7791" (R-Car M2-W) + - "renesas,rcar_sound-r8a7793" (R-Car M2-N) + - "renesas,rcar_sound-r8a7794" (R-Car E2) + - "renesas,rcar_sound-r8a7795" (R-Car H3) - reg : Should contain the register physical address. required register is SRU/ADG/SSI if generation1 @@ -30,6 +366,13 @@ Required properties: - rcar_sound,dai : DAI contents. The number of DAI subnode should be same as HW. see below for detail. +- #sound-dai-cells : it must be 0 if your system is using single DAI + it must be 1 if your system is using multi DAI + +Optional properties: +- #clock-cells : it must be 0 if your system has audio_clkout + it must be 1 if your system has audio_clkout0/1/2/3 +- clock-frequency : for all audio_clkout0/1/2/3 SSI subnode properties: - interrupts : Should contain SSI interrupt for PIO transfer @@ -52,7 +395,10 @@ DAI subnode properties: - playback : list of playback modules - capture : list of capture modules + +============================================= Example: +============================================= rcar_sound: sound@ec500000 { #sound-dai-cells = <1>; @@ -237,3 +583,86 @@ rcar_sound: sound@ec500000 { }; }; }; + +============================================= +Example: simple sound card +============================================= + + rsnd_ak4643: sound { + compatible = "simple-audio-card"; + + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&sndcodec>; + simple-audio-card,frame-master = <&sndcodec>; + + sndcpu: simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + }; + + sndcodec: simple-audio-card,codec { + sound-dai = <&ak4643>; + clocks = <&audio_clock>; + }; + }; + +&rcar_sound { + pinctrl-0 = <&sound_pins &sound_clk_pins>; + pinctrl-names = "default"; + + /* Single DAI */ + #sound-dai-cells = <0>; + + status = "okay"; + + rcar_sound,dai { + dai0 { + playback = <&ssi0 &src2 &dvc0>; + capture = <&ssi1 &src3 &dvc1>; + }; + }; +}; + +&ssi1 { + shared-pin; +}; + +============================================= +Example: simple sound card for TDM +============================================= + + rsnd_tdm: sound { + compatible = "simple-audio-card"; + + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&sndcodec>; + simple-audio-card,frame-master = <&sndcodec>; + + sndcpu: simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + dai-tdm-slot-num = <6>; + }; + + sndcodec: simple-audio-card,codec { + sound-dai = <&xxx>; + }; + }; + +============================================= +Example: simple sound card for Multi channel +============================================= + +&rcar_sound { + pinctrl-0 = <&sound_pins &sound_clk_pins>; + pinctrl-names = "default"; + + /* Single DAI */ + #sound-dai-cells = <0>; + + status = "okay"; + + rcar_sound,dai { + dai0 { + playback = <&ssi0 &ssi1 &ssi2 &src0 &dvc0>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt b/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt index 962748a8d919..255ece3043ad 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt @@ -4,8 +4,8 @@ Renesas Sampling Rate Convert Sound Card specifies audio DAI connections of SoC Required properties: -- compatible : "renesas,rsrc-card,<board>" - Examples with soctypes are: +- compatible : "renesas,rsrc-card{,<board>}" + Examples with boards are: - "renesas,rsrc-card" - "renesas,rsrc-card,lager" - "renesas,rsrc-card,koelsch" @@ -30,6 +30,7 @@ Optional subnode properties: - frame-inversion : bool property. Add this if the dai-link uses frame clock inversion. - convert-rate : platform specified sampling rate convert +- convert-channels : platform specified converted channel size (2 - 8 ch) - audio-prefix : see audio-routing - audio-routing : A list of the connections between audio components. Each entry is a pair of strings, the first being the connection's sink, diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt index 9b82c20b306b..6e86d8aa29b4 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt +++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt @@ -9,11 +9,10 @@ Required properties: - "rockchip,rk3066-i2s": for rk3066 - "rockchip,rk3188-i2s", "rockchip,rk3066-i2s": for rk3188 - "rockchip,rk3288-i2s", "rockchip,rk3066-i2s": for rk3288 + - "rockchip,rk3399-i2s", "rockchip,rk3066-i2s": for rk3399 - reg: physical base address of the controller and length of memory mapped region. - interrupts: should contain the I2S interrupt. -- #address-cells: should be 1. -- #size-cells: should be 0. - dmas: DMA specifiers for tx and rx dma. See the DMA client binding, Documentation/devicetree/bindings/dma/dma.txt - dma-names: should include "tx" and "rx". @@ -21,6 +20,8 @@ Required properties: - clock-names: should contain followings: - "i2s_hclk": clock for I2S BUS - "i2s_clk" : clock for I2S controller +- rockchip,playback-channels: max playback channels, if not set, 8 channels default. +- rockchip,capture-channels: max capture channels, if not set, 2 channels default. Example for rk3288 I2S controller: @@ -28,10 +29,10 @@ i2s@ff890000 { compatible = "rockchip,rk3288-i2s", "rockchip,rk3066-i2s"; reg = <0xff890000 0x10000>; interrupts = <GIC_SPI 85 IRQ_TYPE_LEVEL_HIGH>; - #address-cells = <1>; - #size-cells = <0>; dmas = <&pdma1 0>, <&pdma1 1>; dma-names = "tx", "rx"; clock-names = "i2s_hclk", "i2s_clk"; clocks = <&cru HCLK_I2S0>, <&cru SCLK_I2S0>; + rockchip,playback-channels = <8>; + rockchip,capture-channels = <2>; }; diff --git a/Documentation/devicetree/bindings/sound/rockchip-spdif.txt b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt new file mode 100644 index 000000000000..11046429a118 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rockchip-spdif.txt @@ -0,0 +1,44 @@ +* Rockchip SPDIF transceiver + +The S/PDIF audio block is a stereo transceiver that allows the +processor to receive and transmit digital audio via an coaxial cable or +a fibre cable. + +Required properties: + +- compatible: should be one of the following: + - "rockchip,rk3066-spdif" + - "rockchip,rk3188-spdif" + - "rockchip,rk3288-spdif" + - "rockchip,rk3366-spdif" + - "rockchip,rk3368-spdif" + - "rockchip,rk3399-spdif" +- reg: physical base address of the controller and length of memory mapped + region. +- interrupts: should contain the SPDIF interrupt. +- dmas: DMA specifiers for tx dma. See the DMA client binding, + Documentation/devicetree/bindings/dma/dma.txt +- dma-names: should be "tx" +- clocks: a list of phandle + clock-specifier pairs, one for each entry + in clock-names. +- clock-names: should contain following: + - "hclk": clock for SPDIF controller + - "mclk" : clock for SPDIF bus + +Required properties on RK3288: + - rockchip,grf: the phandle of the syscon node for the general register + file (GRF) + +Example for the rk3188 SPDIF controller: + +spdif: spdif@0x1011e000 { + compatible = "rockchip,rk3188-spdif", "rockchip,rk3066-spdif"; + reg = <0x1011e000 0x2000>; + interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>; + dmas = <&dmac1_s 8>; + dma-names = "tx"; + clock-names = "hclk", "mclk"; + clocks = <&cru HCLK_SPDIF>, <&cru SCLK_SPDIF>; + status = "disabled"; + #sound-dai-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5514.txt b/Documentation/devicetree/bindings/sound/rt5514.txt new file mode 100644 index 000000000000..e24436fc5ea9 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5514.txt @@ -0,0 +1,25 @@ +RT5514 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt5514". + +- reg : The I2C address of the device. + +Pins on the device (for linking into audio routes) for RT5514: + + * DMIC1L + * DMIC1R + * DMIC2L + * DMIC2R + * AMICL + * AMICR + +Example: + +codec: rt5514@57 { + compatible = "realtek,rt5514"; + reg = <0x57>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5616.txt b/Documentation/devicetree/bindings/sound/rt5616.txt new file mode 100644 index 000000000000..e41085818559 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5616.txt @@ -0,0 +1,32 @@ +RT5616 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt5616". + +- reg : The I2C address of the device. + +Optional properties: + +- clocks: The phandle of the master clock to the CODEC. + +- clock-names: Should be "mclk". + +Pins on the device (for linking into audio routes) for RT5616: + + * IN1P + * IN2P + * IN2N + * LOUTL + * LOUTR + * HPOL + * HPOR + +Example: + +codec: rt5616@1b { + compatible = "realtek,rt5616"; + reg = <0x1b>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5640.txt b/Documentation/devicetree/bindings/sound/rt5640.txt index bac4d9ac1edc..57fe64643050 100644 --- a/Documentation/devicetree/bindings/sound/rt5640.txt +++ b/Documentation/devicetree/bindings/sound/rt5640.txt @@ -12,9 +12,13 @@ Required properties: Optional properties: +- clocks: The phandle of the master clock to the CODEC +- clock-names: Should be "mclk" + - realtek,in1-differential - realtek,in2-differential - Boolean. Indicate MIC1/2 input are differential, rather than single-ended. +- realtek,in3-differential + Boolean. Indicate MIC1/2/3 input are differential, rather than single-ended. - realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin. @@ -24,9 +28,11 @@ Pins on the device (for linking into audio routes) for RT5639/RT5640: * DMIC2 * MICBIAS1 * IN1P - * IN1R + * IN1N * IN2P - * IN2R + * IN2N + * IN3P + * IN3N * HPOL * HPOR * LOUTL diff --git a/Documentation/devicetree/bindings/sound/rt5651.txt b/Documentation/devicetree/bindings/sound/rt5651.txt new file mode 100644 index 000000000000..3875233095f5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5651.txt @@ -0,0 +1,41 @@ +RT5651 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt5651". + +- reg : The I2C address of the device. + +Optional properties: + +- realtek,in2-differential + Boolean. Indicate MIC2 input are differential, rather than single-ended. + +- realtek,dmic-en + Boolean. true if dmic is used. + +Pins on the device (for linking into audio routes) for RT5651: + + * DMIC L1 + * DMIC R1 + * IN1P + * IN2P + * IN2N + * IN3P + * HPOL + * HPOR + * LOUTL + * LOUTR + * PDML + * PDMR + +Example: + +codec: rt5651@1a { + compatible = "realtek,rt5651"; + reg = <0x1a>; + realtek,dmic-en = "true"; + realtek,in2-diff = "false"; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5659.txt b/Documentation/devicetree/bindings/sound/rt5659.txt new file mode 100644 index 000000000000..5f79e7fde032 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5659.txt @@ -0,0 +1,75 @@ +RT5659/RT5658 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : One of "realtek,rt5659" or "realtek,rt5658". + +- reg : The I2C address of the device. + +- interrupts : The CODEC's interrupt output. + +Optional properties: + +- realtek,in1-differential +- realtek,in3-differential +- realtek,in4-differential + Boolean. Indicate MIC1/3/4 input are differential, rather than single-ended. + +- realtek,dmic1-data-pin + 0: dmic1 is not used + 1: using IN2N pin as dmic1 data pin + 2: using GPIO5 pin as dmic1 data pin + 3: using GPIO9 pin as dmic1 data pin + 4: using GPIO11 pin as dmic1 data pin + +- realtek,dmic2-data-pin + 0: dmic2 is not used + 1: using IN2P pin as dmic2 data pin + 2: using GPIO6 pin as dmic2 data pin + 3: using GPIO10 pin as dmic2 data pin + 4: using GPIO12 pin as dmic2 data pin + +- realtek,jd-src + 0: No JD is used + 1: using JD3 as JD source + +- realtek,ldo1-en-gpios : The GPIO that controls the CODEC's LDO1_EN pin. +- realtek,reset-gpios : The GPIO that controls the CODEC's RESET pin. + +Pins on the device (for linking into audio routes) for RT5659/RT5658: + + * DMIC L1 + * DMIC R1 + * DMIC L2 + * DMIC R2 + * IN1P + * IN1N + * IN2P + * IN2N + * IN3P + * IN3N + * IN4P + * IN4N + * HPOL + * HPOR + * SPOL + * SPOR + * LOUTL + * LOUTR + * MONOOUT + * PDML + * PDMR + * SPDIF + +Example: + +rt5659 { + compatible = "realtek,rt5659"; + reg = <0x1b>; + interrupt-parent = <&gpio>; + interrupts = <TEGRA_GPIO(W, 3) GPIO_ACTIVE_HIGH>; + realtek,ldo1-en-gpios = + <&gpio TEGRA_GPIO(V, 3) GPIO_ACTIVE_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5677.txt b/Documentation/devicetree/bindings/sound/rt5677.txt index f07078997f87..1b3c13d206ff 100644 --- a/Documentation/devicetree/bindings/sound/rt5677.txt +++ b/Documentation/devicetree/bindings/sound/rt5677.txt @@ -18,7 +18,7 @@ Required properties: Optional properties: - realtek,pow-ldo2-gpio : The GPIO that controls the CODEC's POW_LDO2 pin. -- realtek,reset-gpio : The GPIO that controls the CODEC's RESET pin. +- realtek,reset-gpio : The GPIO that controls the CODEC's RESET pin. Active low. - realtek,in1-differential - realtek,in2-differential diff --git a/Documentation/devicetree/bindings/sound/sun4i-codec.txt b/Documentation/devicetree/bindings/sound/sun4i-codec.txt new file mode 100644 index 000000000000..0dce690f78f5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sun4i-codec.txt @@ -0,0 +1,30 @@ +* Allwinner A10 Codec + +Required properties: +- compatible: must be either "allwinner,sun4i-a10-codec" or + "allwinner,sun7i-a20-codec" +- reg: must contain the registers location and length +- interrupts: must contain the codec interrupt +- dmas: DMA channels for tx and rx dma. See the DMA client binding, + Documentation/devicetree/bindings/dma/dma.txt +- dma-names: should include "tx" and "rx". +- clocks: a list of phandle + clock-specifer pairs, one for each entry + in clock-names. +- clock-names: should contain followings: + - "apb": the parent APB clock for this controller + - "codec": the parent module clock + +Optional properties: +- allwinner,pa-gpios: gpio to enable external amplifier + +Example: +codec: codec@01c22c00 { + #sound-dai-cells = <0>; + compatible = "allwinner,sun7i-a20-codec"; + reg = <0x01c22c00 0x40>; + interrupts = <0 30 4>; + clocks = <&apb0_gates 0>, <&codec_clk>; + clock-names = "apb", "codec"; + dmas = <&dma 0 19>, <&dma 0 19>; + dma-names = "rx", "tx"; +}; diff --git a/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt b/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt new file mode 100644 index 000000000000..13503aa505a9 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt @@ -0,0 +1,39 @@ +Allwinner Sony/Philips Digital Interface Format (S/PDIF) Controller + +The Allwinner S/PDIF audio block is a transceiver that allows the +processor to receive and transmit digital audio via an coaxial cable or +a fibre cable. +For now only playback is supported. + +Required properties: + + - compatible : should be one of the following: + - "allwinner,sun4i-a10-spdif": for the Allwinner A10 SoC + + - reg : Offset and length of the register set for the device. + + - interrupts : Contains the spdif interrupt. + + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. + + - dma-names : Two dmas have to be defined, "tx" and "rx". + + - clocks : Contains an entry for each entry in clock-names. + + - clock-names : Includes the following entries: + "apb" clock for the spdif bus. + "spdif" clock for spdif controller. + +Example: + +spdif: spdif@01c21000 { + compatible = "allwinner,sun4i-a10-spdif"; + reg = <0x01c21000 0x40>; + interrupts = <13>; + clocks = <&apb0_gates 1>, <&spdif_clk>; + clock-names = "apb", "spdif"; + dmas = <&dma 0 2>, <&dma 0 2>; + dma-names = "rx", "tx"; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/sound/tdm-slot.txt b/Documentation/devicetree/bindings/sound/tdm-slot.txt index 6a2c84247f91..34cf70e2cbc4 100644 --- a/Documentation/devicetree/bindings/sound/tdm-slot.txt +++ b/Documentation/devicetree/bindings/sound/tdm-slot.txt @@ -4,11 +4,15 @@ This specifies audio DAI's TDM slot. TDM slot properties: dai-tdm-slot-num : Number of slots in use. -dai-tdm-slot-width : Width in bits for each slot. +dai-tdm-slot-width : Width in bits for each slot. +dai-tdm-slot-tx-mask : Transmit direction slot mask, optional +dai-tdm-slot-rx-mask : Receive direction slot mask, optional For instance: dai-tdm-slot-num = <2>; dai-tdm-slot-width = <8>; + dai-tdm-slot-tx-mask = <0 1>; + dai-tdm-slot-rx-mask = <1 0>; And for each spcified driver, there could be one .of_xlate_tdm_slot_mask() to specify a explicit mapping of the channels and the slots. If it's absent @@ -18,3 +22,8 @@ tx and rx masks. For snd_soc_of_xlate_tdm_slot_mask(), the tx and rx masks will use a 1 bit for an active slot as default, and the default active bits are at the LSB of the masks. + +The explicit masks are given as array of integers, where the first +number presents bit-0 (LSB), second presents bit-1, etc. Any non zero +number is considered 1 and 0 is 0. snd_soc_of_xlate_tdm_slot_mask() +does not do anything, if either mask is set non zero value. diff --git a/Documentation/devicetree/bindings/sound/ti,ads117x.txt b/Documentation/devicetree/bindings/sound/ti,ads117x.txt new file mode 100644 index 000000000000..7db19b50865a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,ads117x.txt @@ -0,0 +1,11 @@ +Texas Intstruments ADS117x ADC + +Required properties: + + - compatible : "ti,ads1174" or "ti,ads1178" + +Example: + +ads1178 { + compatible = "ti,ads1178"; +}; diff --git a/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt b/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt new file mode 100644 index 000000000000..5d9cb84c661d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ti,pcm3168a.txt @@ -0,0 +1,48 @@ +Texas Instruments pcm3168a DT bindings + +This driver supports both SPI and I2C bus access for this codec + +Required properties: + + - compatible: "ti,pcm3168a" + + - clocks : Contains an entry for each entry in clock-names + + - clock-names : Includes the following entries: + "scki" The system clock + + - VDD1-supply : Digital power supply regulator 1 (+3.3V) + + - VDD2-supply : Digital power supply regulator 2 (+3.3V) + + - VCCAD1-supply : ADC power supply regulator 1 (+5V) + + - VCCAD2-supply : ADC power supply regulator 2 (+5V) + + - VCCDA1-supply : DAC power supply regulator 1 (+5V) + + - VCCDA2-supply : DAC power supply regulator 2 (+5V) + +For required properties on SPI/I2C, consult SPI/I2C device tree documentation + +Examples: + +i2c0: i2c0@0 { + + ... + + pcm3168a: audio-codec@44 { + compatible = "ti,pcm3168a"; + reg = <0x44>; + clocks = <&clk_core CLK_AUDIO>; + clock-names = "scki"; + VDD1-supply = <&supply3v3>; + VDD2-supply = <&supply3v3>; + VCCAD1-supply = <&supply5v0>; + VCCAD2-supply = <&supply5v0>; + VCCDA1-supply = <&supply5v0>; + VCCDA2-supply = <&supply5v0>; + pinctrl-names = "default"; + pinctrl-0 = <&dac_clk_pin>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/wlf,wm8974.txt b/Documentation/devicetree/bindings/sound/wlf,wm8974.txt new file mode 100644 index 000000000000..01d3a7c83419 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/wlf,wm8974.txt @@ -0,0 +1,15 @@ +WM8974 audio CODEC + +This device supports both I2C and SPI (configured with pin strapping +on the board). + +Required properties: + - compatible: "wlf,wm8974" + - reg: the I2C address or SPI chip select number of the device + +Examples: + +codec: wm8974@1a { + compatible = "wlf,wm8974"; + reg = <0x1a>; +}; diff --git a/Documentation/devicetree/bindings/sound/wm8994.txt b/Documentation/devicetree/bindings/sound/wm8994.txt index e045e90a0924..68c4e8d96bed 100644 --- a/Documentation/devicetree/bindings/sound/wm8994.txt +++ b/Documentation/devicetree/bindings/sound/wm8994.txt @@ -30,7 +30,7 @@ Optional properties: - #interrupt-cells: the number of cells to describe an IRQ, this should be 2. The first cell is the IRQ number. The second cell is the flags, encoded as the trigger masks from - Documentation/devicetree/bindings/interrupts.txt + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - clocks : A list of up to two phandle and clock specifier pairs - clock-names : A list of clock names sorted in the same order as clocks. diff --git a/Documentation/devicetree/bindings/sparc_sun_oracle_rng.txt b/Documentation/devicetree/bindings/sparc_sun_oracle_rng.txt new file mode 100644 index 000000000000..b0b211194c71 --- /dev/null +++ b/Documentation/devicetree/bindings/sparc_sun_oracle_rng.txt @@ -0,0 +1,30 @@ +HWRNG support for the n2_rng driver + +Required properties: +- reg : base address to sample from +- compatible : should contain one of the following + RNG versions: + - 'SUNW,n2-rng' for Niagara 2 Platform (SUN UltraSPARC T2 CPU) + - 'SUNW,vf-rng' for Victoria Falls Platform (SUN UltraSPARC T2 Plus CPU) + - 'SUNW,kt-rng' for Rainbow/Yosemite Falls Platform (SUN SPARC T3/T4), (UltraSPARC KT/Niagara 3 - development names) + more recent systems (after Oracle acquisition of SUN) + - 'ORCL,m4-rng' for SPARC T5/M5 + - 'ORCL,m7-rng' for SPARC T7/M7 + +Examples: +/* linux LDOM on SPARC T5-2 */ +Node 0xf029a4f4 + .node: f029a4f4 + rng-#units: 00000002 + compatible: 'ORCL,m4-rng' + reg: 0000000e + name: 'random-number-generator' + +/* solaris on SPARC M7-8 */ +Node 0xf028c08c + rng-#units: 00000003 + compatible: 'ORCL,m7-rng' + reg: 0000000e + name: 'random-number-generator' + +PS: see as well prtconfs.git by DaveM diff --git a/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.txt b/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.txt new file mode 100644 index 000000000000..8a18d71e6879 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/adi,axi-spi-engine.txt @@ -0,0 +1,31 @@ +Analog Devices AXI SPI Engine controller Device Tree Bindings + +Required properties: +- compatible : Must be "adi,axi-spi-engine-1.00.a"" +- reg : Physical base address and size of the register map. +- interrupts : Property with a value describing the interrupt + number. +- clock-names : List of input clock names - "s_axi_aclk", "spi_clk" +- clocks : Clock phandles and specifiers (See clock bindings for + details on clock-names and clocks). +- #address-cells : Must be <1> +- #size-cells : Must be <0> + +Optional subnodes: + Subnodes are use to represent the SPI slave devices connected to the SPI + master. They follow the generic SPI bindings as outlined in spi-bus.txt. + +Example: + + spi@@44a00000 { + compatible = "adi,axi-spi-engine-1.00.a"; + reg = <0x44a00000 0x1000>; + interrupts = <0 56 4>; + clocks = <&clkc 15 &clkc 15>; + clock-names = "s_axi_aclk", "spi_clk"; + + #address-cells = <1>; + #size-cells = <0>; + + /* SPI devices */ + }; diff --git a/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt b/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt new file mode 100644 index 000000000000..9887b0724759 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/brcm,bcm2835-aux-spi.txt @@ -0,0 +1,38 @@ +Broadcom BCM2835 auxiliar SPI1/2 controller + +The BCM2835 contains two forms of SPI master controller, one known simply as +SPI0, and the other known as the "Universal SPI Master"; part of the +auxiliary block. This binding applies to the SPI1/2 controller. + +Required properties: +- compatible: Should be "brcm,bcm2835-aux-spi". +- reg: Should contain register location and length for the spi block +- interrupts: Should contain shared interrupt of the aux block +- clocks: The clock feeding the SPI controller - needs to + point to the auxiliar clock driver of the bcm2835, + as this clock will enable the output gate for the specific + clock. +- cs-gpios: the cs-gpios (native cs is NOT supported) + see also spi-bus.txt + +Example: + +spi1@7e215080 { + compatible = "brcm,bcm2835-aux-spi"; + reg = <0x7e215080 0x40>; + interrupts = <1 29>; + clocks = <&aux_clocks BCM2835_AUX_CLOCK_SPI1>; + #address-cells = <1>; + #size-cells = <0>; + cs-gpios = <&gpio 18>, <&gpio 17>, <&gpio 16>; +}; + +spi2@7e2150c0 { + compatible = "brcm,bcm2835-aux-spi"; + reg = <0x7e2150c0 0x40>; + interrupts = <1 29>; + clocks = <&aux_clocks BCM2835_AUX_CLOCK_SPI2>; + #address-cells = <1>; + #size-cells = <0>; + cs-gpios = <&gpio 43>, <&gpio 44>, <&gpio 45>; +}; diff --git a/Documentation/devicetree/bindings/spi/icpdas-lp8841-spi-rtc.txt b/Documentation/devicetree/bindings/spi/icpdas-lp8841-spi-rtc.txt new file mode 100644 index 000000000000..852b651f3bc5 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/icpdas-lp8841-spi-rtc.txt @@ -0,0 +1,54 @@ +* ICP DAS LP-8841 SPI Controller for RTC + +ICP DAS LP-8841 contains a DS-1302 RTC. RTC is connected to an IO +memory register, which acts as an SPI master device. + +The device uses the standard MicroWire half-duplex transfer timing. +Master output is set on low clock and sensed by the RTC on the rising +edge. Master input is set by the RTC on the trailing edge and is sensed +by the master on low clock. + +Required properties: + +- #address-cells: should be 1 + +- #size-cells: should be 0 + +- compatible: should be "icpdas,lp8841-spi-rtc" + +- reg: should provide IO memory address + +Requirements to SPI slave nodes: + +- There can be only one slave device. + +- The spi slave node should claim the following flags which are + required by the spi controller. + + - spi-3wire: The master itself has only 3 wire. It cannor work in + full duplex mode. + + - spi-cs-high: DS-1302 has active high chip select line. The master + doesn't support active low. + + - spi-lsb-first: DS-1302 requires least significant bit first + transfers. The master only support this type of bit ordering. + + +Example: + +spi@901c { + #address-cells = <1>; + #size-cells = <0>; + compatible = "icpdas,lp8841-spi-rtc"; + reg = <0x901c 0x1>; + + rtc@0 { + compatible = "maxim,ds1302"; + reg = <0>; + spi-max-frequency = <500000>; + spi-3wire; + spi-lsb-first; + spi-cs-high; + }; +}; diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index 705075da2f10..aa005c1d10d9 100644 --- a/Documentation/devicetree/bindings/spi/sh-msiof.txt +++ b/Documentation/devicetree/bindings/spi/sh-msiof.txt @@ -10,6 +10,7 @@ Required properties: "renesas,msiof-r8a7792" (R-Car V2H) "renesas,msiof-r8a7793" (R-Car M2-N) "renesas,msiof-r8a7794" (R-Car E2) + "renesas,msiof-sh73a0" (SH-Mobile AG5) - reg : A list of offsets and lengths of the register sets for the device. If only one register set is present, it is to be used diff --git a/Documentation/devicetree/bindings/spi/spi-bus.txt b/Documentation/devicetree/bindings/spi/spi-bus.txt index bbaa857dd68f..42d595425dfb 100644 --- a/Documentation/devicetree/bindings/spi/spi-bus.txt +++ b/Documentation/devicetree/bindings/spi/spi-bus.txt @@ -61,6 +61,8 @@ contain the following properties. used for MOSI. Defaults to 1 if not present. - spi-rx-bus-width - (optional) The bus width(number of data wires) that used for MISO. Defaults to 1 if not present. +- spi-rx-delay-us - (optional) Microsecond delay after a read transfer. +- spi-tx-delay-us - (optional) Microsecond delay after a write transfer. Some SPI controllers and devices support Dual and Quad SPI transfer mode. It allows data in the SPI system to be transferred in 2 wires(DUAL) or 4 wires(QUAD). diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 6160ffbcb3d3..e43f4cf4cf35 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -2,9 +2,10 @@ Binding for MTK SPI controller Required properties: - compatible: should be one of the following. - - mediatek,mt8173-spi: for mt8173 platforms - - mediatek,mt8135-spi: for mt8135 platforms + - mediatek,mt2701-spi: for mt2701 platforms - mediatek,mt6589-spi: for mt6589 platforms + - mediatek,mt8135-spi: for mt8135 platforms + - mediatek,mt8173-spi: for mt8173 platforms - #address-cells: should be 1. @@ -29,8 +30,11 @@ Required properties: muxes clock, and "spi-clk" for the clock gate. Optional properties: +-cs-gpios: see spi-bus.txt. + - mediatek,pad-select: specify which pins group(ck/mi/mo/cs) spi - controller used, this value should be 0~3, only required for MT8173. + controller used. This is an array, the element value should be 0~3, + only required for MT8173. 0: specify GPIO69,70,71,72 for spi pins. 1: specify GPIO102,103,104,105 for spi pins. 2: specify GPIO128,129,130,131 for spi pins. @@ -49,7 +53,7 @@ spi: spi@1100a000 { <&topckgen CLK_TOP_SPI_SEL>, <&pericfg CLK_PERI_SPI0>; clock-names = "parent-clk", "sel-clk", "spi-clk"; - - mediatek,pad-select = <0>; + cs-gpios = <&pio 105 GPIO_ACTIVE_LOW>, <&pio 72 GPIO_ACTIVE_LOW>; + mediatek,pad-select = <1>, <0>; status = "disabled"; }; diff --git a/Documentation/devicetree/bindings/spi/spi-rockchip.txt b/Documentation/devicetree/bindings/spi/spi-rockchip.txt index 0c491bda4c65..1b14d69d8903 100644 --- a/Documentation/devicetree/bindings/spi/spi-rockchip.txt +++ b/Documentation/devicetree/bindings/spi/spi-rockchip.txt @@ -9,6 +9,7 @@ Required Properties: "rockchip,rk3066-spi" for rk3066. "rockchip,rk3188-spi", "rockchip,rk3066-spi" for rk3188. "rockchip,rk3288-spi", "rockchip,rk3066-spi" for rk3288. + "rockchip,rk3399-spi", "rockchip,rk3066-spi" for rk3399. - reg: physical base address of the controller and length of memory mapped region. - interrupts: The interrupt number to the cpu. The interrupt specifier format diff --git a/Documentation/devicetree/bindings/spi/spi-xilinx.txt b/Documentation/devicetree/bindings/spi/spi-xilinx.txt new file mode 100644 index 000000000000..c7b7856bd528 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-xilinx.txt @@ -0,0 +1,22 @@ +Xilinx SPI controller Device Tree Bindings +------------------------------------------------- + +Required properties: +- compatible : Should be "xlnx,xps-spi-2.00.a" or "xlnx,xps-spi-2.00.b" +- reg : Physical base address and size of SPI registers map. +- interrupts : Property with a value describing the interrupt + number. +- interrupt-parent : Must be core interrupt controller + +Optional properties: +- xlnx,num-ss-bits : Number of chip selects used. + +Example: + axi_quad_spi@41e00000 { + compatible = "xlnx,xps-spi-2.00.a"; + interrupt-parent = <&intc>; + interrupts = <0 31 1>; + reg = <0x41e00000 0x10000>; + xlnx,num-ss-bits = <0x1>; + }; + diff --git a/Documentation/devicetree/bindings/spi/ti_qspi.txt b/Documentation/devicetree/bindings/spi/ti_qspi.txt index 601a360531a5..cc8304aa64ac 100644 --- a/Documentation/devicetree/bindings/spi/ti_qspi.txt +++ b/Documentation/devicetree/bindings/spi/ti_qspi.txt @@ -15,14 +15,32 @@ Recommended properties: - spi-max-frequency: Definition as per Documentation/devicetree/bindings/spi/spi-bus.txt +Optional properties: +- syscon-chipselects: Handle to system control region contains QSPI + chipselect register and offset of that register. + Example: +For am4372: qspi: qspi@4b300000 { - compatible = "ti,dra7xxx-qspi"; - reg = <0x47900000 0x100>, <0x30000000 0x3ffffff>; + compatible = "ti,am4372-qspi"; + reg = <0x47900000 0x100>, <0x30000000 0x4000000>; reg-names = "qspi_base", "qspi_mmap"; #address-cells = <1>; #size-cells = <0>; spi-max-frequency = <25000000>; ti,hwmods = "qspi"; }; + +For dra7xx: +qspi: qspi@4b300000 { + compatible = "ti,dra7xxx-qspi"; + reg = <0x4b300000 0x100>, + <0x5c000000 0x4000000>, + reg-names = "qspi_base", "qspi_mmap"; + syscon-chipselects = <&scm_conf 0x558>; + #address-cells = <1>; + #size-cells = <0>; + spi-max-frequency = <48000000>; + ti,hwmods = "qspi"; +}; diff --git a/Documentation/devicetree/bindings/arm/rockchip/pmu-sram.txt b/Documentation/devicetree/bindings/sram/rockchip-pmu-sram.txt index 6b42fda306ff..6b42fda306ff 100644 --- a/Documentation/devicetree/bindings/arm/rockchip/pmu-sram.txt +++ b/Documentation/devicetree/bindings/sram/rockchip-pmu-sram.txt diff --git a/Documentation/devicetree/bindings/arm/rockchip/smp-sram.txt b/Documentation/devicetree/bindings/sram/rockchip-smp-sram.txt index d9416fb8db6f..800701ecffca 100644 --- a/Documentation/devicetree/bindings/arm/rockchip/smp-sram.txt +++ b/Documentation/devicetree/bindings/sram/rockchip-smp-sram.txt @@ -12,7 +12,7 @@ Required sub-node properties: - compatible : should be "rockchip,rk3066-smp-sram" The rest of the properties should follow the generic mmio-sram discription -found in ../../misc/sram.txt +found in Documentation/devicetree/bindings/sram/sram.txt Example: diff --git a/Documentation/devicetree/bindings/arm/exynos/smp-sysram.txt b/Documentation/devicetree/bindings/sram/samsung-sram.txt index 4a0a4f70a0ce..6bc474b2b885 100644 --- a/Documentation/devicetree/bindings/arm/exynos/smp-sysram.txt +++ b/Documentation/devicetree/bindings/sram/samsung-sram.txt @@ -15,7 +15,7 @@ Required sub-node properties: "samsung,exynos4210-sysram-ns" : for Non-secure SYSRAM The rest of the properties should follow the generic mmio-sram discription -found in ../../misc/sysram.txt +found in Documentation/devicetree/bindings/sram/sram.txt Example: diff --git a/Documentation/devicetree/bindings/misc/sram.txt b/Documentation/devicetree/bindings/sram/sram.txt index 36cbe5aea990..227e3a341af1 100644 --- a/Documentation/devicetree/bindings/misc/sram.txt +++ b/Documentation/devicetree/bindings/sram/sram.txt @@ -25,6 +25,11 @@ Required properties in the sram node: - ranges : standard definition, should translate from local addresses within the sram to bus addresses +Optional properties in the sram node: + +- no-memory-wc : the flag indicating, that SRAM memory region has not to + be remapped as write combining. WC is used by default. + Required properties in the area nodes: - reg : iomem address range, relative to the SRAM range @@ -33,6 +38,12 @@ Optional properties in the area nodes: - compatible : standard definition, should contain a vendor specific string in the form <vendor>,[<device>-]<usage> +- pool : indicates that the particular reserved SRAM area is addressable + and in use by another device or devices +- export : indicates that the reserved SRAM area may be accessed outside + of the kernel, e.g. by bootloader or userspace +- label : the name for the reserved partition, if omitted, the label + is taken from the node name excluding the unit address. Example: @@ -48,4 +59,14 @@ sram: sram@5c000000 { compatible = "socvendor,smp-sram"; reg = <0x100 0x50>; }; + + device-sram@1000 { + reg = <0x1000 0x1000>; + pool; + }; + + exported@20000 { + reg = <0x20000 0x20000>; + export; + }; }; diff --git a/Documentation/devicetree/bindings/soc/sunxi/sram.txt b/Documentation/devicetree/bindings/sram/sunxi-sram.txt index 067698112f5f..8d5665468fe7 100644 --- a/Documentation/devicetree/bindings/soc/sunxi/sram.txt +++ b/Documentation/devicetree/bindings/sram/sunxi-sram.txt @@ -16,7 +16,7 @@ SRAM nodes ---------- Each SRAM is described using the mmio-sram bindings documented in -Documentation/devicetree/bindings/misc/sram.txt +Documentation/devicetree/bindings/sram/sram.txt Each SRAM will have SRAM sections that are going to be handled by the SRAM controller as subnodes. These sections are represented following diff --git a/Documentation/devicetree/bindings/staging/ion/hi6220-ion.txt b/Documentation/devicetree/bindings/staging/ion/hi6220-ion.txt new file mode 100644 index 000000000000..c59e27c632c1 --- /dev/null +++ b/Documentation/devicetree/bindings/staging/ion/hi6220-ion.txt @@ -0,0 +1,31 @@ +Hi6220 SoC ION +=================================================================== +Required properties: +- compatible : "hisilicon,hi6220-ion" +- list of the ION heaps + - heap name : maybe heap_sys_user@0 + - heap id : id should be unique in the system. + - heap base : base ddr address of the heap,0 means that + it is dynamic. + - heap size : memory size and 0 means it is dynamic. + - heap type : the heap type of the heap, please also + see the define in ion.h(drivers/staging/android/uapi/ion.h) +------------------------------------------------------------------- +Example: + hi6220-ion { + compatible = "hisilicon,hi6220-ion"; + heap_sys_user@0 { + heap-name = "sys_user"; + heap-id = <0x0>; + heap-base = <0x0>; + heap-size = <0x0>; + heap-type = "ion_system"; + }; + heap_sys_contig@0 { + heap-name = "sys_contig"; + heap-id = <0x1>; + heap-base = <0x0>; + heap-size = <0x0>; + heap-type = "ion_system_contig"; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt new file mode 100644 index 000000000000..66223d561972 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt @@ -0,0 +1,63 @@ +* Thermal Monitoring Unit (TMU) on Freescale QorIQ SoCs + +Required properties: +- compatible : Must include "fsl,qoriq-tmu". The version of the device is + determined by the TMU IP Block Revision Register (IPBRR0) at + offset 0x0BF8. + Table of correspondences between IPBRR0 values and example chips: + Value Device + ---------- ----- + 0x01900102 T1040 +- reg : Address range of TMU registers. +- interrupts : Contains the interrupt for TMU. +- fsl,tmu-range : The values to be programmed into TTRnCR, as specified by + the SoC reference manual. The first cell is TTR0CR, the second is + TTR1CR, etc. +- fsl,tmu-calibration : A list of cell pairs containing temperature + calibration data, as specified by the SoC reference manual. + The first cell of each pair is the value to be written to TTCFGR, + and the second is the value to be written to TSCFGR. + +Example: + +tmu@f0000 { + compatible = "fsl,qoriq-tmu"; + reg = <0xf0000 0x1000>; + interrupts = <18 2 0 0>; + fsl,tmu-range = <0x000a0000 0x00090026 0x0008004a 0x0001006a>; + fsl,tmu-calibration = <0x00000000 0x00000025 + 0x00000001 0x00000028 + 0x00000002 0x0000002d + 0x00000003 0x00000031 + 0x00000004 0x00000036 + 0x00000005 0x0000003a + 0x00000006 0x00000040 + 0x00000007 0x00000044 + 0x00000008 0x0000004a + 0x00000009 0x0000004f + 0x0000000a 0x00000054 + + 0x00010000 0x0000000d + 0x00010001 0x00000013 + 0x00010002 0x00000019 + 0x00010003 0x0000001f + 0x00010004 0x00000025 + 0x00010005 0x0000002d + 0x00010006 0x00000033 + 0x00010007 0x00000043 + 0x00010008 0x0000004b + 0x00010009 0x00000053 + + 0x00020000 0x00000010 + 0x00020001 0x00000017 + 0x00020002 0x0000001f + 0x00020003 0x00000029 + 0x00020004 0x00000031 + 0x00020005 0x0000003c + 0x00020006 0x00000042 + 0x00020007 0x0000004d + 0x00020008 0x00000056 + + 0x00030000 0x00000012 + 0x00030001 0x0000001d>; +}; diff --git a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt index 332e625f6ed0..e5ee3f159893 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt @@ -1,8 +1,9 @@ * Renesas R-Car Thermal Required properties: -- compatible : "renesas,thermal-<soctype>", "renesas,rcar-thermal" - as fallback. +- compatible : "renesas,thermal-<soctype>", + "renesas,rcar-gen2-thermal" (with thermal-zone) or + "renesas,rcar-thermal" (without thermal-zone) as fallback. Examples with soctypes are: - "renesas,thermal-r8a73a4" (R-Mobile APE6) - "renesas,thermal-r8a7779" (R-Car H1) @@ -36,3 +37,35 @@ thermal@e61f0000 { 0xe61f0300 0x38>; interrupts = <0 69 IRQ_TYPE_LEVEL_HIGH>; }; + +Example (with thermal-zone): + +thermal-zones { + cpu_thermal: cpu-thermal { + polling-delay-passive = <1000>; + polling-delay = <5000>; + + thermal-sensors = <&thermal>; + + trips { + cpu-crit { + temperature = <115000>; + hysteresis = <0>; + type = "critical"; + }; + }; + cooling-maps { + }; + }; +}; + +thermal: thermal@e61f0000 { + compatible = "renesas,thermal-r8a7790", + "renesas,rcar-gen2-thermal", + "renesas,rcar-thermal"; + reg = <0 0xe61f0000 0 0x14>, <0 0xe61f0100 0 0x38>; + interrupts = <0 69 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&mstp5_clks R8A7790_CLK_THERMAL>; + power-domains = <&cpg_clocks>; + #thermal-sensor-cells = <0>; +}; diff --git a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt index ef802de4957a..08efe6bc2193 100644 --- a/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rockchip-thermal.txt @@ -1,7 +1,11 @@ * Temperature Sensor ADC (TSADC) on rockchip SoCs Required properties: -- compatible : "rockchip,rk3288-tsadc" +- compatible : should be "rockchip,<name>-tsadc" + "rockchip,rk3228-tsadc": found on RK3228 SoCs + "rockchip,rk3288-tsadc": found on RK3288 SoCs + "rockchip,rk3368-tsadc": found on RK3368 SoCs + "rockchip,rk3399-tsadc": found on RK3399 SoCs - reg : physical base address of the controller and length of memory mapped region. - interrupts : The interrupt number to the cpu. The interrupt specifier format @@ -12,6 +16,11 @@ Required properties: - resets : Must contain an entry for each entry in reset-names. See ../reset/reset.txt for details. - reset-names : Must include the name "tsadc-apb". +- pinctrl-names : The pin control state names; +- pinctrl-0 : The "init" pinctrl state, it will be set before device probe. +- pinctrl-1 : The "default" pinctrl state, it will be set after reset the + TSADC controller. +- pinctrl-2 : The "sleep" pinctrl state, it will be in for suspend. - #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description. - rockchip,hw-tshut-temp : The hardware-controlled shutdown temperature value. - rockchip,hw-tshut-mode : The hardware-controlled shutdown mode 0:CRU 1:GPIO. @@ -27,8 +36,10 @@ tsadc: tsadc@ff280000 { clock-names = "tsadc", "apb_pclk"; resets = <&cru SRST_TSADC>; reset-names = "tsadc-apb"; - pinctrl-names = "default"; - pinctrl-0 = <&otp_out>; + pinctrl-names = "init", "default", "sleep"; + pinctrl-0 = <&otp_gpio>; + pinctrl-1 = <&otp_out>; + pinctrl-2 = <&otp_gpio>; #thermal-sensor-cells = <1>; rockchip,hw-tshut-temp = <95000>; rockchip,hw-tshut-mode = <0>; diff --git a/Documentation/devicetree/bindings/thermal/ti_soc_thermal.txt b/Documentation/devicetree/bindings/thermal/ti_soc_thermal.txt index 0c9222d27fae..6299dd8de339 100644 --- a/Documentation/devicetree/bindings/thermal/ti_soc_thermal.txt +++ b/Documentation/devicetree/bindings/thermal/ti_soc_thermal.txt @@ -10,6 +10,8 @@ to the silicon temperature. Required properties: - compatible : Should be: + - "ti,omap34xx-bandgap" : for OMAP34xx bandgap + - "ti,omap36xx-bandgap" : for OMAP36xx bandgap - "ti,omap4430-bandgap" : for OMAP4430 bandgap - "ti,omap4460-bandgap" : for OMAP4460 bandgap - "ti,omap4470-bandgap" : for OMAP4470 bandgap @@ -25,6 +27,18 @@ to each bandgap version, because the mapping may change from soc to soc, apart of depending on available features. Example: +OMAP34xx: +bandgap { + reg = <0x48002524 0x4>; + compatible = "ti,omap34xx-bandgap"; +}; + +OMAP36xx: +bandgap { + reg = <0x48002524 0x4>; + compatible = "ti,omap36xx-bandgap"; +}; + OMAP4430: bandgap { reg = <0x4a002260 0x4 0x4a00232C 0x4>; diff --git a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt index 53a3029b7589..8ff54eb464dc 100644 --- a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt +++ b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt @@ -3,10 +3,13 @@ Mediatek MT6577, MT6572 and MT6589 Timers Required properties: - compatible should contain: - * "mediatek,mt6589-timer" for MT6589 compatible timers + * "mediatek,mt2701-timer" for MT2701 compatible timers * "mediatek,mt6580-timer" for MT6580 compatible timers - * "mediatek,mt6577-timer" for all compatible timers (MT6589, MT6580, - MT6577) + * "mediatek,mt6589-timer" for MT6589 compatible timers + * "mediatek,mt8127-timer" for MT8127 compatible timers + * "mediatek,mt8135-timer" for MT8135 compatible timers + * "mediatek,mt8173-timer" for MT8173 compatible timers + * "mediatek,mt6577-timer" for MT6577 and all above compatible timers - reg: Should contain location and length for timers register. - clocks: Clocks driving the timer hardware. This list should include two clocks. The order is system clock and as second clock the RTC clock. diff --git a/Documentation/devicetree/bindings/tty/serial/mvebu-uart.txt b/Documentation/devicetree/bindings/tty/serial/mvebu-uart.txt new file mode 100644 index 000000000000..6087defd9f93 --- /dev/null +++ b/Documentation/devicetree/bindings/tty/serial/mvebu-uart.txt @@ -0,0 +1,13 @@ +* Marvell UART : Non standard UART used in some of Marvell EBU SoCs (e.g., Armada-3700) + +Required properties: +- compatible: "marvell,armada-3700-uart" +- reg: offset and length of the register set for the device. +- interrupts: device interrupt + +Example: + serial@12000 { + compatible = "marvell,armada-3700-uart"; + reg = <0x12000 0x400>; + interrupts = <43>; + }; diff --git a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt new file mode 100644 index 000000000000..070baf4d7d97 --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt @@ -0,0 +1,58 @@ +* Qualcomm Technologies Inc Universal Flash Storage (UFS) PHY + +UFSPHY nodes are defined to describe on-chip UFS PHY hardware macro. +Each UFS PHY node should have its own node. + +To bind UFS PHY with UFS host controller, the controller node should +contain a phandle reference to UFS PHY node. + +Required properties: +- compatible : compatible list, contains "qcom,ufs-phy-qmp-20nm" + or "qcom,ufs-phy-qmp-14nm" according to the relevant phy in use. +- reg : should contain PHY register address space (mandatory), +- reg-names : indicates various resources passed to driver (via reg proptery) by name. + Required "reg-names" is "phy_mem". +- #phy-cells : This property shall be set to 0 +- vdda-phy-supply : phandle to main PHY supply for analog domain +- vdda-pll-supply : phandle to PHY PLL and Power-Gen block power supply +- clocks : List of phandle and clock specifier pairs +- clock-names : List of clock input name strings sorted in the same + order as the clocks property. "ref_clk_src", "ref_clk", + "tx_iface_clk" & "rx_iface_clk" are mandatory but + "ref_clk_parent" is optional + +Optional properties: +- vdda-phy-max-microamp : specifies max. load that can be drawn from phy supply +- vdda-pll-max-microamp : specifies max. load that can be drawn from pll supply +- vddp-ref-clk-supply : phandle to UFS device ref_clk pad power supply +- vddp-ref-clk-max-microamp : specifies max. load that can be drawn from this supply +- vddp-ref-clk-always-on : specifies if this supply needs to be kept always on + +Example: + + ufsphy1: ufsphy@0xfc597000 { + compatible = "qcom,ufs-phy-qmp-20nm"; + reg = <0xfc597000 0x800>; + reg-names = "phy_mem"; + #phy-cells = <0>; + vdda-phy-supply = <&pma8084_l4>; + vdda-pll-supply = <&pma8084_l12>; + vdda-phy-max-microamp = <50000>; + vdda-pll-max-microamp = <1000>; + clock-names = "ref_clk_src", + "ref_clk_parent", + "ref_clk", + "tx_iface_clk", + "rx_iface_clk"; + clocks = <&clock_rpm clk_ln_bb_clk>, + <&clock_gcc clk_pcie_1_phy_ldo >, + <&clock_gcc clk_ufs_phy_ldo>, + <&clock_gcc clk_gcc_ufs_tx_cfg_clk>, + <&clock_gcc clk_gcc_ufs_rx_cfg_clk>; + }; + + ufshc@0xfc598000 { + ... + phys = <&ufsphy1>; + phy-names = "ufsphy"; + }; diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index 53579197eca2..03c0e989e020 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -4,11 +4,18 @@ UFSHC nodes are defined to describe on-chip UFS host controllers. Each UFS controller instance should have its own node. Required properties: -- compatible : compatible list, contains "jedec,ufs-1.1" +- compatible : must contain "jedec,ufs-1.1", may also list one or more + of the following: + "qcom,msm8994-ufshc" + "qcom,msm8996-ufshc" + "qcom,ufshc" - interrupts : <interrupt mapping for UFS host controller IRQ> - reg : <registers mapping> Optional properties: +- phys : phandle to UFS PHY node +- phy-names : the string "ufsphy" when is found in a node, along + with "phys" attribute, provides phandle to UFS PHY node - vdd-hba-supply : phandle to UFS host controller supply regulator node - vcc-supply : phandle to VCC supply regulator node - vccq-supply : phandle to VCCQ supply regulator node @@ -54,4 +61,6 @@ Example: clocks = <&core 0>, <&ref 0>, <&iface 0>; clock-names = "core_clk", "ref_clk", "iface_clk"; freq-table-hz = <100000000 200000000>, <0 0>, <0 0>; + phys = <&ufsphy1>; + phy-names = "ufsphy"; }; diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index a057b75ba4b5..1084e2bcbe1c 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -2,7 +2,14 @@ Required properties: - compatible: should be one of: + "fsl,imx23-usb" "fsl,imx27-usb" + "fsl,imx28-usb" + "fsl,imx6q-usb" + "fsl,imx6sl-usb" + "fsl,imx6sx-usb" + "fsl,imx6ul-usb" + "fsl,imx7d-usb" "lsi,zevio-usb" "qcom,ci-hdrc" "chipidea,usb2" @@ -27,10 +34,6 @@ Optional properties: - vbus-supply: reference to the VBUS regulator - maximum-speed: limit the maximum connection speed to "full-speed". - tpl-support: TPL (Targeted Peripheral List) feature for targeted hosts -- fsl,usbmisc: (FSL only) phandler of non-core register device, with one - argument that indicate usb controller index -- disable-over-current: (FSL only) disable over current detect -- external-vbus-divider: (FSL only) enables off-chip resistor divider for Vbus - itc-setting: interrupt threshold control register control, the setting should be aligned with ITC bits at register USBCMD. - ahb-burst-config: it is vendor dependent, the required value should be @@ -41,11 +44,44 @@ Optional properties: - tx-burst-size-dword: it is vendor dependent, the tx burst size in dword (4 bytes), This register represents the maximum length of a the burst in 32-bit words while moving data from system memory to the USB - bus, changing this value takes effect only the SBUSCFG.AHBBRST is 0. + bus, the value of this property will only take effect if property + "ahb-burst-config" is set to 0, if this property is missing the reset + default of the hardware implementation will be used. - rx-burst-size-dword: it is vendor dependent, the rx burst size in dword (4 bytes), This register represents the maximum length of a the burst in 32-bit words while moving data from the USB bus to system memory, - changing this value takes effect only the SBUSCFG.AHBBRST is 0. + the value of this property will only take effect if property + "ahb-burst-config" is set to 0, if this property is missing the reset + default of the hardware implementation will be used. +- extcon: phandles to external connector devices. First phandle should point to + external connector, which provide "USB" cable events, the second should point + to external connector device, which provide "USB-HOST" cable events. If one + of the external connector devices is not required, empty <0> phandle should + be specified. +- phy-clkgate-delay-us: the delay time (us) between putting the PHY into + low power mode and gating the PHY clock. +- non-zero-ttctrl-ttha: after setting this property, the value of register + ttctrl.ttha will be 0x7f; if not, the value will be 0x0, this is the default + value. It needs to be very carefully for setting this property, it is + recommended that consult with your IC engineer before setting this value. + On the most of chipidea platforms, the "usage_tt" flag at RTL is 0, so this + property only affects siTD. + If this property is not set, the max packet size is 1023 bytes, and if + the total of packet size for pervious transactions are more than 256 bytes, + it can't accept any transactions within this frame. The use case is single + transaction, but higher frame rate. + If this property is set, the max packet size is 188 bytes, it can handle + more transactions than above case, it can accept transactions until it + considers the left room size within frame is less than 188 bytes, software + needs to make sure it does not send more than 90% + maximum_periodic_data_per_frame. The use case is multiple transactions, but + less frame rate. + +i.mx specific properties +- fsl,usbmisc: phandler of non-core register device, with one + argument that indicate usb controller index +- disable-over-current: disable over current detect +- external-vbus-divider: enables off-chip resistor divider for Vbus Example: @@ -62,4 +98,6 @@ Example: ahb-burst-config = <0x0>; tx-burst-size-dword = <0x10>; /* 64 bytes */ rx-burst-size-dword = <0x10>; + extcon = <0>, <&usb_id>; + phy-clkgate-delay-us = <400>; }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index fd132cbee70e..20a68bf2b4e7 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -4,9 +4,12 @@ Platform DesignWare HS OTG USB 2.0 controller Required properties: - compatible : One of: - brcm,bcm2835-usb: The DWC2 USB controller instance in the BCM2835 SoC. + - hisilicon,hi6220-usb: The DWC2 USB controller instance in the hi6220 SoC. - rockchip,rk3066-usb: The DWC2 USB controller instance in the rk3066 Soc; - "rockchip,rk3188-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3188 Soc; - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; + - "lantiq,arx100-usb": The DWC2 USB controller instance in Lantiq ARX SoCs; + - "lantiq,xrx200-usb": The DWC2 USB controller instance in Lantiq XRX SoCs; - snps,dwc2: A generic DWC2 USB controller with default parameters. - reg : Should contain 1 register range (address and length) - interrupts : Should contain 1 interrupt diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt new file mode 100644 index 000000000000..30361b32a460 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.txt @@ -0,0 +1,33 @@ +Xilinx SuperSpeed DWC3 USB SoC controller + +Required properties: +- compatible: Should contain "xlnx,zynqmp-dwc3" +- clocks: A list of phandles for the clocks listed in clock-names +- clock-names: Should contain the following: + "bus_clk" Master/Core clock, have to be >= 125 MHz for SS + operation and >= 60MHz for HS operation + + "ref_clk" Clock source to core during PHY power down + +Required child node: +A child node must exist to represent the core DWC3 IP block. The name of +the node is not important. The content of the node is defined in dwc3.txt. + +Example device node: + + usb@0 { + #address-cells = <0x2>; + #size-cells = <0x1>; + status = "okay"; + compatible = "xlnx,zynqmp-dwc3"; + clock-names = "bus_clk" "ref_clk"; + clocks = <&clk125>, <&clk125>; + ranges; + + dwc3@fe200000 { + compatible = "snps,dwc3"; + reg = <0x0 0xfe200000 0x40000>; + interrupts = <0x0 0x41 0x4>; + dr_mode = "host"; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 0815eac5b185..fb2ad0acedbd 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -1,6 +1,7 @@ synopsys DWC3 CORE -DWC3- USB3 CONTROLLER +DWC3- USB3 CONTROLLER. Complies to the generic USB binding properties + as described in 'usb/generic.txt' Required properties: - compatible: must be "snps,dwc3" @@ -35,11 +36,16 @@ Optional properties: LTSSM during USB3 Compliance mode. - snps,dis_u3_susphy_quirk: when set core will disable USB3 suspend phy. - snps,dis_u2_susphy_quirk: when set core will disable USB2 suspend phy. + - snps,dis_enblslpm_quirk: when set clears the enblslpm in GUSB2PHYCFG, + disabling the suspend signal to the PHY. - 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 - snps,hsphy_interface: High-Speed PHY interface selection between "utmi" for UTMI+ and "ulpi" for ULPI when the DWC_USB3_HSPHY_INTERFACE has value 3. + - snps,quirk-frame-length-adjustment: Value for GFLADJ_30MHZ field of GFLADJ + register for post-silicon frame length adjustment when the + fladj_30mhz_sdbnd signal is invalid or incorrect. This is usually a subnode to DWC3 glue to which it is connected. diff --git a/Documentation/devicetree/bindings/usb/mt8173-xhci.txt b/Documentation/devicetree/bindings/usb/mt8173-xhci.txt new file mode 100644 index 000000000000..b3a7ffa48852 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/mt8173-xhci.txt @@ -0,0 +1,51 @@ +MT8173 xHCI + +The device node for Mediatek SOC USB3.0 host controller + +Required properties: + - compatible : should contain "mediatek,mt8173-xhci" + - reg : specifies physical base address and size of the registers, + the first one for MAC, the second for IPPC + - interrupts : interrupt used by the controller + - power-domains : a phandle to USB power domain node to control USB's + mtcmos + - vusb33-supply : regulator of USB avdd3.3v + + - clocks : a list of phandle + clock-specifier pairs, one for each + entry in clock-names + - clock-names : must contain + "sys_ck": for clock of xHCI MAC + "wakeup_deb_p0": for USB wakeup debounce clock of port0 + "wakeup_deb_p1": for USB wakeup debounce clock of port1 + + - 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". + - vbus-supply : reference to the VBUS regulator; + - usb3-lpm-capable : supports USB3.0 LPM + +Example: +usb30: usb@11270000 { + compatible = "mediatek,mt8173-xhci"; + reg = <0 0x11270000 0 0x1000>, + <0 0x11280700 0 0x0100>; + interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; + clocks = <&topckgen CLK_TOP_USB30_SEL>, + <&pericfg CLK_PERI_USB0>, + <&pericfg CLK_PERI_USB1>; + clock-names = "sys_ck", + "wakeup_deb_p0", + "wakeup_deb_p1"; + phys = <&phy_port0 PHY_TYPE_USB3>, + <&phy_port1 PHY_TYPE_USB2>; + vusb33-supply = <&mt6397_vusb_reg>; + vbus-supply = <&usb_p1_vbus>; + usb3-lpm-capable; + mediatek,syscon-wakeup = <&pericfg>; + mediatek,wakeup-src = <1>; +}; diff --git a/Documentation/devicetree/bindings/usb/octeon-usb.txt b/Documentation/devicetree/bindings/usb/octeon-usb.txt new file mode 100644 index 000000000000..205c8d24d6e3 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/octeon-usb.txt @@ -0,0 +1,62 @@ +OCTEON/OCTEON+ USB BLOCK + +1) Main node + + Required properties: + + - compatible: must be "cavium,octeon-5750-usbn" + + - reg: specifies the physical base address of the USBN block and + the length of the memory mapped region. + + - #address-cells: specifies the number of cells needed to encode an + address. The value must be 2. + + - #size-cells: specifies the number of cells used to represent the size + of an address. The value must be 2. + + - ranges: specifies the translation between child address space and parent + address space. + + - clock-frequency: speed of the USB reference clock. Allowed values are + 12000000, 24000000 or 48000000. + + - cavium,refclk-type: type of the USB reference clock. Allowed values are + "crystal" or "external". + + - refclk-frequency: deprecated, use "clock-frequency". + + - refclk-type: deprecated, use "cavium,refclk-type". + +2) Child node + + The main node must have one child node which describes the built-in + USB controller. + + Required properties: + + - compatible: must be "cavium,octeon-5750-usbc" + + - reg: specifies the physical base address of the USBC block and + the length of the memory mapped region. + + - interrupts: specifies the interrupt number for the USB controller. + +3) Example: + + usbn: usbn@1180068000000 { + compatible = "cavium,octeon-5750-usbn"; + reg = <0x11800 0x68000000 0x0 0x1000>; + ranges; /* Direct mapping */ + #address-cells = <2>; + #size-cells = <2>; + clock-frequency = <12000000>; + cavium,refclk-type = "crystal"; + + usbc@16f0010000000 { + compatible = "cavium,octeon-5750-usbc"; + reg = <0x16f00 0x10000000 0x0 0x80000>; + interrupts = <0 56>; + }; + }; + diff --git a/Documentation/devicetree/bindings/usb/renesas_usb3.txt b/Documentation/devicetree/bindings/usb/renesas_usb3.txt new file mode 100644 index 000000000000..8d52766f07b9 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/renesas_usb3.txt @@ -0,0 +1,23 @@ +Renesas Electronics USB3.0 Peripheral driver + +Required properties: + - compatible: Must contain one of the following: + - "renesas,r8a7795-usb3-peri" + - reg: Base address and length of the register for the USB3.0 Peripheral + - interrupts: Interrupt specifier for the USB3.0 Peripheral + - clocks: clock phandle and specifier pair + +Example: + usb3_peri0: usb@ee020000 { + compatible = "renesas,r8a7795-usb3-peri"; + reg = <0 0xee020000 0 0x400>; + interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 328>; + }; + + usb3_peri1: usb@ee060000 { + compatible = "renesas,r8a7795-usb3-peri"; + reg = <0 0xee060000 0 0x400>; + interrupts = <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 327>; + }; diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index 7d48f63db44e..b6040563e51a 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -1,11 +1,21 @@ Renesas Electronics USBHS driver Required properties: - - compatible: Must contain one of the following: - - "renesas,usbhs-r8a7790" - - "renesas,usbhs-r8a7791" - - "renesas,usbhs-r8a7794" - - "renesas,usbhs-r8a7795" + - compatible: Must contain one or more of the following: + + - "renesas,usbhs-r8a7790" for r8a7790 (R-Car H2) compatible device + - "renesas,usbhs-r8a7791" for r8a7791 (R-Car M2-W) compatible device + - "renesas,usbhs-r8a7792" for r8a7792 (R-Car V2H) compatible device + - "renesas,usbhs-r8a7793" for r8a7793 (R-Car M2-N) compatible device + - "renesas,usbhs-r8a7794" for r8a7794 (R-Car E2) compatible device + - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device + - "renesas,rcar-gen2-usbhs" for R-Car Gen2 compatible device + - "renesas,rcar-gen3-usbhs" for R-Car Gen3 compatible device + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first followed + by the generic version. + - reg: Base address and length of the register for the USBHS - interrupts: Interrupt specifier for the USBHS - clocks: A list of phandle + clock specifier pairs @@ -22,7 +32,7 @@ Optional properties: Example: usbhs: usb@e6590000 { - compatible = "renesas,usbhs-r8a7790"; + compatible = "renesas,usbhs-r8a7790", "renesas,rcar-gen2-usbhs"; reg = <0 0xe6590000 0 0x100>; interrupts = <0 107 IRQ_TYPE_LEVEL_HIGH>; clocks = <&mstp7_clks R8A7790_CLK_HSUSB>; diff --git a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt b/Documentation/devicetree/bindings/usb/samsung-usbphy.txt deleted file mode 100644 index 33fd3543f3f8..000000000000 --- a/Documentation/devicetree/bindings/usb/samsung-usbphy.txt +++ /dev/null @@ -1,117 +0,0 @@ -SAMSUNG USB-PHY controllers - -** Samsung's usb 2.0 phy transceiver - -The Samsung's usb 2.0 phy transceiver is used for controlling -usb 2.0 phy for s3c-hsotg as well as ehci-s5p and ohci-exynos -usb controllers across Samsung SOCs. -TODO: Adding the PHY binding with controller(s) according to the under -development generic PHY driver. - -Required properties: - -Exynos4210: -- compatible : should be "samsung,exynos4210-usb2phy" -- reg : base physical address of the phy registers and length of memory mapped - region. -- clocks: Clock IDs array as required by the controller. -- clock-names: names of clock correseponding IDs clock property as requested - by the controller driver. - -Exynos5250: -- compatible : should be "samsung,exynos5250-usb2phy" -- reg : base physical address of the phy registers and length of memory mapped - region. - -Optional properties: -- #address-cells: should be '1' when usbphy node has a child node with 'reg' - property. -- #size-cells: should be '1' when usbphy node has a child node with 'reg' - property. -- ranges: allows valid translation between child's address space and parent's - address space. - -- The child node 'usbphy-sys' to the node 'usbphy' is for the system controller - interface for usb-phy. It should provide the following information required by - usb-phy controller to control phy. - - reg : base physical address of PHY_CONTROL registers. - The size of this register is the total sum of size of all PHY_CONTROL - registers that the SoC has. For example, the size will be - '0x4' in case we have only one PHY_CONTROL register (e.g. - OTHERS register in S3C64XX or USB_PHY_CONTROL register in S5PV210) - and, '0x8' in case we have two PHY_CONTROL registers (e.g. - USBDEVICE_PHY_CONTROL and USBHOST_PHY_CONTROL registers in exynos4x). - and so on. - -Example: - - Exynos4210 - - usbphy@125B0000 { - #address-cells = <1>; - #size-cells = <1>; - compatible = "samsung,exynos4210-usb2phy"; - reg = <0x125B0000 0x100>; - ranges; - - clocks = <&clock 2>, <&clock 305>; - clock-names = "xusbxti", "otg"; - - usbphy-sys { - /* USB device and host PHY_CONTROL registers */ - reg = <0x10020704 0x8>; - }; - }; - - -** Samsung's usb 3.0 phy transceiver - -Starting exynso5250, Samsung's SoC have usb 3.0 phy transceiver -which is used for controlling usb 3.0 phy for dwc3-exynos usb 3.0 -controllers across Samsung SOCs. - -Required properties: - -Exynos5250: -- compatible : should be "samsung,exynos5250-usb3phy" -- reg : base physical address of the phy registers and length of memory mapped - region. -- clocks: Clock IDs array as required by the controller. -- clock-names: names of clocks correseponding to IDs in the clock property - as requested by the controller driver. - -Optional properties: -- #address-cells: should be '1' when usbphy node has a child node with 'reg' - property. -- #size-cells: should be '1' when usbphy node has a child node with 'reg' - property. -- ranges: allows valid translation between child's address space and parent's - address space. - -- The child node 'usbphy-sys' to the node 'usbphy' is for the system controller - interface for usb-phy. It should provide the following information required by - usb-phy controller to control phy. - - reg : base physical address of PHY_CONTROL registers. - The size of this register is the total sum of size of all PHY_CONTROL - registers that the SoC has. For example, the size will be - '0x4' in case we have only one PHY_CONTROL register (e.g. - OTHERS register in S3C64XX or USB_PHY_CONTROL register in S5PV210) - and, '0x8' in case we have two PHY_CONTROL registers (e.g. - USBDEVICE_PHY_CONTROL and USBHOST_PHY_CONTROL registers in exynos4x). - and so on. - -Example: - usbphy@12100000 { - compatible = "samsung,exynos5250-usb3phy"; - reg = <0x12100000 0x100>; - #address-cells = <1>; - #size-cells = <1>; - ranges; - - clocks = <&clock 1>, <&clock 286>; - clock-names = "ext_xtal", "usbdrd30"; - - usbphy-sys { - /* USB device and host PHY_CONTROL registers */ - reg = <0x10040704 0x8>; - }; - }; diff --git a/Documentation/devicetree/bindings/usb/usb-device.txt b/Documentation/devicetree/bindings/usb/usb-device.txt new file mode 100644 index 000000000000..1c35e7b665e1 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-device.txt @@ -0,0 +1,28 @@ +Generic USB Device Properties + +Usually, we only use device tree for hard wired USB device. +The reference binding doc is from: +http://www.firmware.org/1275/bindings/usb/usb-1_0.ps + +Required properties: +- compatible: usbVID,PID. The textual representation of VID, 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 port number which this device is connecting to, the range + is 1-31. + +Example: + +&usb1 { + status = "okay"; + + #address-cells = <1>; + #size-cells = <0>; + + hub: genesys@1 { + compatible = "usb5e3,608"; + reg = <1>; + }; +} diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index 86f67f0886bc..6a17aa85c4d5 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -1,10 +1,23 @@ USB xHCI controllers Required properties: - - compatible: should be one of "generic-xhci", - "marvell,armada-375-xhci", "marvell,armada-380-xhci", - "renesas,xhci-r8a7790", "renesas,xhci-r8a7791" (deprecated: - "xhci-platform"). + - compatible: should be one or more of + + - "generic-xhci" for generic XHCI device + - "marvell,armada-375-xhci" for Armada 375 SoCs + - "marvell,armada-380-xhci" for Armada 38x SoCs + - "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,rcar-gen2-xhci" for a generic R-Car Gen2 compatible device + - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 compatible device + - "xhci-platform" (deprecated) + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first + followed by the generic version. + - reg: should contain address and length of the standard XHCI register set for the device. - interrupts: one XHCI interrupt should be described here. diff --git a/Documentation/devicetree/bindings/usb/usb3503.txt b/Documentation/devicetree/bindings/usb/usb3503.txt index 52493b1480e2..c1a0a9191d26 100644 --- a/Documentation/devicetree/bindings/usb/usb3503.txt +++ b/Documentation/devicetree/bindings/usb/usb3503.txt @@ -18,7 +18,8 @@ Optional properties: - refclk: Clock used for driving REFCLK signal (optional, if not provided the driver assumes that clock signal is always available, its rate is specified by REF_SEL pins and a value from the primary - reference clock frequencies table is used) + reference clock frequencies table is used). Use clocks and + clock-names in order to assign it - refclk-frequency: Frequency of the REFCLK signal as defined by REF_SEL pins (optional, if not provided, driver will not set rate of the REFCLK signal and assume that a value from the primary reference @@ -33,4 +34,6 @@ Examples: intn-gpios = <&gpx3 4 1>; reset-gpios = <&gpx3 5 1>; initial-mode = <1>; + clocks = <&clks 80>; + clock-names = "refclk"; }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 82d2ac97af74..787d4225c8ab 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -28,12 +28,15 @@ arm ARM Ltd. armadeus ARMadeus Systems SARL artesyn Artesyn Embedded Technologies Inc. asahi-kasei Asahi Kasei Corp. +atlas Atlas Scientific LLC atmel Atmel Corporation auo AU Optronics Corporation avago Avago Technologies avic Shanghai AVIC Optoelectronics Co., Ltd. axis Axis Communications AB +boe BOE Technology Group Co., Ltd. bosch Bosch Sensortec GmbH +boundary Boundary Devices Inc. brcm Broadcom Corporation buffalo Buffalo, Inc. calxeda Calxeda @@ -51,6 +54,7 @@ cirrus Cirrus Logic, Inc. cloudengines Cloud Engines, Inc. cnm Chips&Media, Inc. cnxt Conexant Systems, Inc. +compulab CompuLab Ltd. cortina Cortina Systems, Inc. cosmic Cosmic Circuits crystalfontz Crystalfontz America, Inc. @@ -68,6 +72,7 @@ dmo Data Modul AG ea Embedded Artists AB ebv EBV Elektronik edt Emerging Display Technologies +eeti eGalax_eMPIA Technology Inc elan Elan Microelectronic Corp. emmicro EM Microelectronic energymicro Silicon Laboratories (formerly Energy Micro AS) @@ -82,6 +87,7 @@ everspin Everspin Technologies, Inc. excito Excito fcs Fairchild Semiconductor firefly Firefly +focaltech FocalTech Systems Co.,Ltd fsl Freescale Semiconductor GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc. gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. @@ -101,11 +107,13 @@ himax Himax Technologies, Inc. hisilicon Hisilicon Limited. hit Hitachi Ltd. hitex Hitex Development Tools +holt Holt Integrated Circuits, Inc. honeywell Honeywell hp Hewlett Packard i2se I2SE GmbH ibm International Business Machines (IBM) idt Integrated Device Technologies, Inc. +ifi Ingenieurburo Fur Ic-Technologie (I/F/I) iom Iomega Corporation img Imagination Technologies Ltd. ingenic Ingenic Semiconductor @@ -115,10 +123,13 @@ intercontrol Inter Control Group invensense InvenSense Inc. isee ISEE 2007 S.L. isil Intersil +issi Integrated Silicon Solutions Inc. jedec JEDEC Solid State Technology Association karo Ka-Ro electronics GmbH keymile Keymile GmbH kinetic Kinetic Technologies +kosagi Sutajio Ko-Usagi PTE Ltd. +kyo Kyocera Corporation lacie LaCie lantiq Lantiq Semiconductor lenovo Lenovo Group Ltd. @@ -157,23 +168,28 @@ nuvoton Nuvoton Technology Corporation nvidia NVIDIA nxp NXP Semiconductors okaya Okaya Electric America, Inc. +olimex OLIMEX Ltd. onnn ON Semiconductor Corp. opencores OpenCores.org option Option NV ortustech Ortus Technology Co., Ltd. ovti OmniVision Technologies +ORCL Oracle Corporation panasonic Panasonic Corporation parade Parade Technologies Inc. pericom Pericom Technology Inc. phytec PHYTEC Messtechnik GmbH picochip Picochip Ltd plathome Plat'Home Co., Ltd. +plda PLDA pixcir PIXCIR MICROELECTRONICS Co., Ltd +pulsedlight PulsedLight, Inc powervr PowerVR (deprecated, use img) qca Qualcomm Atheros, Inc. qcom Qualcomm Technologies, Inc qemu QEMU, a generic and open source machine emulator and virtualizer qi Qi Hardware +qiaodian QiaoDian XianShi Corporation qnap QNAP Systems, Inc. radxa Radxa raidsonic RaidSonic Technology GmbH @@ -191,7 +207,10 @@ sbs Smart Battery System schindler Schindler seagate Seagate Technology PLC semtech Semtech Corporation +sgx SGX Sensortech sharp Sharp Corporation +si-en Si-En Technology Ltd. +sigma Sigma Designs, Inc. sil Silicon Image silabs Silicon Laboratories siliconmitus Silicon Mitus, Inc. @@ -210,11 +229,15 @@ sony Sony Corporation spansion Spansion Inc. sprd Spreadtrum Communications Inc. st STMicroelectronics +startek Startek ste ST-Ericsson stericsson ST-Ericsson +syna Synaptics Inc. synology Synology, Inc. +SUNW Sun Microsystems, Inc tbs TBS Technologies tcl Toby Churchill Ltd. +technologic Technologic Systems thine THine Electronics, Inc. ti Texas Instruments tlm Trusted Logic Mobility @@ -222,12 +245,16 @@ toradex Toradex AG toshiba Toshiba Corporation toumaz Toumaz tplink TP-LINK Technologies Co., Ltd. +tronfy Tronfy truly Truly Semiconductors Limited +upisemi uPI Semiconductor Corp. +urt United Radiant Technology Corporation usi Universal Scientific Industrial Co., Ltd. v3 V3 Semiconductor variscite Variscite Ltd. via VIA Technologies, Inc. virtio Virtual I/O Device Specification, developed by the OASIS consortium +vivante Vivante Corporation voipac Voipac Technologies s.r.o. wexler Wexler winbond Winbond Electronics corp. diff --git a/Documentation/devicetree/bindings/w1/omap-hdq.txt b/Documentation/devicetree/bindings/w1/omap-hdq.txt index fef794741bd1..913c5f91a0f9 100644 --- a/Documentation/devicetree/bindings/w1/omap-hdq.txt +++ b/Documentation/devicetree/bindings/w1/omap-hdq.txt @@ -1,11 +1,15 @@ * OMAP HDQ One wire bus master controller Required properties: -- compatible : should be "ti,omap3-1w" +- compatible : should be "ti,omap3-1w" or "ti,am4372-hdq" - reg : Address and length of the register set for the device - interrupts : interrupt line. - ti,hwmods : "hdq1w" +Optional properties: +- ti,mode: should be "hdq": HDQ mode "1w": one-wire mode. + If not specified HDQ mode is implied. + Example: - From omap3.dtsi @@ -14,4 +18,5 @@ Example: reg = <0x480b2000 0x1000>; interrupts = <58>; ti,hwmods = "hdq1w"; + ti,mode = "hdq"; }; diff --git a/Documentation/devicetree/bindings/watchdog/alphascale-asm9260.txt b/Documentation/devicetree/bindings/watchdog/alphascale-asm9260.txt new file mode 100644 index 000000000000..75b265a04047 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/alphascale-asm9260.txt @@ -0,0 +1,35 @@ +Alphascale asm9260 Watchdog timer + +Required properties: + +- compatible : should be "alphascale,asm9260-wdt". +- reg : Specifies base physical address and size of the registers. +- clocks : the clocks feeding the watchdog timer. See clock-bindings.txt +- clock-names : should be set to + "mod" - source for tick counter. + "ahb" - ahb gate. +- resets : phandle pointing to the system reset controller with + line index for the watchdog. +- reset-names : should be set to "wdt_rst". + +Optional properties: +- timeout-sec : shall contain the default watchdog timeout in seconds, + if unset, the default timeout is 30 seconds. +- alphascale,mode : three modes are supported + "hw" - hw reset (default). + "sw" - sw reset. + "debug" - no action is taken. + +Example: + +watchdog0: watchdog@80048000 { + compatible = "alphascale,asm9260-wdt"; + reg = <0x80048000 0x10>; + clocks = <&acc CLKID_SYS_WDT>, <&acc CLKID_AHB_WDT>; + clock-names = "mod", "ahb"; + interrupts = <55>; + resets = <&rst WDT_RESET>; + reset-names = "wdt_rst"; + timeout-sec = <30>; + alphascale,mode = "hw"; +}; diff --git a/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.txt b/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.txt new file mode 100644 index 000000000000..84122270be8f --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/brcm,bcm7038-wdt.txt @@ -0,0 +1,19 @@ +BCM7038 Watchdog timer + +Required properties: + +- compatible : should be "brcm,bcm7038-wdt" +- reg : Specifies base physical address and size of the registers. + +Optional properties: + +- clocks: The clock running the watchdog. If no clock is found the + driver will default to 27000000 Hz. + +Example: + +watchdog@f040a7e8 { + compatible = "brcm,bcm7038-wdt"; + clocks = <&upg_fixed>; + reg = <0xf040a7e8 0x16>; +}; diff --git a/Documentation/devicetree/bindings/watchdog/meson6-wdt.txt b/Documentation/devicetree/bindings/watchdog/meson-wdt.txt index 9200fc2d508c..ae70185d96e6 100644 --- a/Documentation/devicetree/bindings/watchdog/meson6-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/meson-wdt.txt @@ -2,7 +2,7 @@ Meson SoCs Watchdog timer Required properties: -- compatible : should be "amlogic,meson6-wdt" +- compatible : should be "amlogic,meson6-wdt" or "amlogic,meson8b-wdt" - reg : Specifies base physical address and size of the registers. Example: diff --git a/Documentation/devicetree/bindings/watchdog/mt7621-wdt.txt b/Documentation/devicetree/bindings/watchdog/mt7621-wdt.txt new file mode 100644 index 000000000000..c15ef0ef609f --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/mt7621-wdt.txt @@ -0,0 +1,12 @@ +Ralink Watchdog Timers + +Required properties: +- compatible: must be "mediatek,mt7621-wdt" +- reg: physical base address of the controller and length of the register range + +Example: + + watchdog@100 { + compatible = "mediatek,mt7621-wdt"; + reg = <0x100 0x10>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index af9eb5b8a253..6a00939a059a 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -2,7 +2,11 @@ Mediatek SoCs Watchdog timer Required properties: -- compatible : should be "mediatek,mt6589-wdt" +- compatible should contain: + * "mediatek,mt2701-wdt" for MT2701 compatible watchdog timers + * "mediatek,mt6589-wdt" for all compatible watchdog timers (MT2701, + MT6589) + - reg : Specifies base physical address and size of the registers. Example: diff --git a/Documentation/devicetree/bindings/watchdog/sigma,smp8642-wdt.txt b/Documentation/devicetree/bindings/watchdog/sigma,smp8642-wdt.txt new file mode 100644 index 000000000000..5b7ec2c707d8 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/sigma,smp8642-wdt.txt @@ -0,0 +1,18 @@ +Sigma Designs SMP86xx/SMP87xx watchdog + +Required properties: +- compatible: Should be "sigma,smp8642-wdt" +- reg: Specifies the physical address region +- clocks: Should be a phandle to the clock + +Optional properties: +- timeout-sec: watchdog timeout in seconds + +Example: + +watchdog@1fd00 { + compatible = "sigma,smp8642-wdt"; + reg = <0x1fd00 8>; + clocks = <&xtal_in_clk>; + timeout-sec = <30>; +}; diff --git a/Documentation/devicetree/bindings/watchdog/sp805-wdt.txt b/Documentation/devicetree/bindings/watchdog/sp805-wdt.txt new file mode 100644 index 000000000000..edc4f0ea54a3 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/sp805-wdt.txt @@ -0,0 +1,31 @@ +* ARM SP805 Watchdog Timer (WDT) Controller + +SP805 WDT is a ARM Primecell Peripheral and has a standard-id register that +can be used to identify the peripheral type, vendor, and revision. +This value can be used for driver matching. + +As SP805 WDT is a primecell IP, it follows the base bindings specified in +'arm/primecell.txt' + +Required properties: +- compatible : Should be "arm,sp805-wdt", "arm,primecell" +- reg : Base address and size of the watchdog timer registers. +- clocks : From common clock binding. + First clock is PCLK and the second is WDOGCLK. + WDOGCLK can be equal to or be a sub-multiple of the PCLK frequency. +- clock-names : From common clock binding. + Shall be "apb_pclk" for first clock and "wdog_clk" for the + second one. + +Optional properties: +- interrupts : Should specify WDT interrupt number. + +Examples: + + cluster1_core0_watchdog: wdt@c000000 { + compatible = "arm,sp805-wdt", "arm,primecell"; + reg = <0x0 0xc000000 0x0 0x1000>; + clocks = <&clockgen 4 3>, <&clockgen 4 3>; + clock-names = "apb_pclk", "wdog_clk"; + }; + diff --git a/Documentation/devicetree/bindings/watchdog/ts4800-wdt.txt b/Documentation/devicetree/bindings/watchdog/ts4800-wdt.txt new file mode 100644 index 000000000000..8f6caad4258d --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/ts4800-wdt.txt @@ -0,0 +1,25 @@ +Technologic Systems Watchdog + +Required properties: +- compatible: must be "technologic,ts4800-wdt" +- syscon: phandle / integer array that points to the syscon node which + describes the FPGA's syscon registers. + - phandle to FPGA's syscon + - offset to the watchdog register + +Optional property: +- timeout-sec: contains the watchdog timeout in seconds. + +Example: + +syscon: syscon@b0010000 { + compatible = "syscon", "simple-mfd"; + reg = <0xb0010000 0x3d>; + reg-io-width = <2>; + + wdt@e { + compatible = "technologic,ts4800-wdt"; + syscon = <&syscon 0xe>; + timeout-sec = <10>; + }; +} diff --git a/Documentation/devicetree/bindings/watchdog/ziirave-wdt.txt b/Documentation/devicetree/bindings/watchdog/ziirave-wdt.txt new file mode 100644 index 000000000000..3d878184ec3f --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/ziirave-wdt.txt @@ -0,0 +1,19 @@ +Zodiac RAVE Watchdog Timer + +Required properties: +- compatible: must be "zii,rave-wdt" +- reg: i2c slave address of device, usually 0x38 + +Optional Properties: +- timeout-sec: Watchdog timeout value in seconds. +- reset-duration-ms: Duration of the pulse generated when the watchdog times + out. Value in milliseconds. + +Example: + + watchdog@38 { + compatible = "zii,rave-wdt"; + reg = <0x38>; + timeout-sec = <30>; + reset-duration-ms = <30>; + }; diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 04d34f6a58f3..3f1437fbca6b 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -16,6 +16,7 @@ Table of Contents 2) Entry point for arch/powerpc 3) Entry point for arch/x86 4) Entry point for arch/mips/bmips + 5) Entry point for arch/sh II - The DT block format 1) Header @@ -316,6 +317,18 @@ it with special cases. This convention is defined for 32-bit systems only, as there are not currently any 64-bit BMIPS implementations. +5) Entry point for arch/sh +-------------------------- + + Device-tree-compatible SH bootloaders are expected to provide the physical + address of the device tree blob in r4. Since legacy bootloaders did not + guarantee any particular initial register state, kernels built to + inter-operate with old bootloaders must either use a builtin DTB or + select a legacy board option (something other than CONFIG_SH_DEVICE_TREE) + that does not use device tree. Support for the latter is being phased out + in favor of device tree. + + II - The DT block format ======================== diff --git a/Documentation/dmaengine/client.txt b/Documentation/dmaengine/client.txt index 11fb87ff6cd0..9e33189745f0 100644 --- a/Documentation/dmaengine/client.txt +++ b/Documentation/dmaengine/client.txt @@ -22,25 +22,14 @@ The slave DMA usage consists of following steps: Channel allocation is slightly different in the slave DMA context, client drivers typically need a channel from a particular DMA controller only and even in some cases a specific channel is desired. - To request a channel dma_request_channel() API is used. + To request a channel dma_request_chan() API is used. Interface: - struct dma_chan *dma_request_channel(dma_cap_mask_t mask, - dma_filter_fn filter_fn, - void *filter_param); - where dma_filter_fn is defined as: - typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); + struct dma_chan *dma_request_chan(struct device *dev, const char *name); - The 'filter_fn' parameter is optional, but highly recommended for - slave and cyclic channels as they typically need to obtain a specific - DMA channel. - - When the optional 'filter_fn' parameter is NULL, dma_request_channel() - simply returns the first channel that satisfies the capability mask. - - Otherwise, the 'filter_fn' routine will be called once for each free - channel which has a capability in 'mask'. 'filter_fn' is expected to - return 'true' when the desired DMA channel is found. + Which will find and return the 'name' DMA channel associated with the 'dev' + device. The association is done via DT, ACPI or board file based + dma_slave_map matching table. A channel allocated via this interface is exclusive to the caller, until dma_release_channel() is called. @@ -128,7 +117,7 @@ The slave DMA usage consists of following steps: transaction. For cyclic DMA, a callback function may wish to terminate the - DMA via dmaengine_terminate_all(). + DMA via dmaengine_terminate_async(). Therefore, it is important that DMA engine drivers drop any locks before calling the callback function which may cause a @@ -166,12 +155,29 @@ The slave DMA usage consists of following steps: Further APIs: -1. int dmaengine_terminate_all(struct dma_chan *chan) +1. int dmaengine_terminate_sync(struct dma_chan *chan) + int dmaengine_terminate_async(struct dma_chan *chan) + int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */ This causes all activity for the DMA channel to be stopped, and may discard data in the DMA FIFO which hasn't been fully transferred. No callback functions will be called for any incomplete transfers. + Two variants of this function are available. + + dmaengine_terminate_async() might not wait until the DMA has been fully + stopped or until any running complete callbacks have finished. But it is + possible to call dmaengine_terminate_async() from atomic context or from + within a complete callback. dmaengine_synchronize() must be called before it + is safe to free the memory accessed by the DMA transfer or free resources + accessed from within the complete callback. + + dmaengine_terminate_sync() will wait for the transfer and any running + complete callbacks to finish before it returns. But the function must not be + called from atomic context or from within a complete callback. + + dmaengine_terminate_all() is deprecated and should not be used in new code. + 2. int dmaengine_pause(struct dma_chan *chan) This pauses activity on the DMA channel without data loss. @@ -197,3 +203,20 @@ Further APIs: a running DMA channel. It is recommended that DMA engine users pause or stop (via dmaengine_terminate_all()) the channel before using this API. + +5. void dmaengine_synchronize(struct dma_chan *chan) + + Synchronize the termination of the DMA channel to the current context. + + This function should be used after dmaengine_terminate_async() to synchronize + the termination of the DMA channel to the current context. The function will + wait for the transfer and any running complete callbacks to finish before it + returns. + + If dmaengine_terminate_async() is used to stop the DMA channel this function + must be called before it is safe to free memory accessed by previously + submitted descriptors or to free any resources accessed within the complete + callback of previously submitted descriptors. + + The behavior of this function is undefined if dma_async_issue_pending() has + been called between dmaengine_terminate_async() and this function. diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt index 67d4ce4df109..122b7f4876bb 100644 --- a/Documentation/dmaengine/provider.txt +++ b/Documentation/dmaengine/provider.txt @@ -327,8 +327,24 @@ supported. * device_terminate_all - Aborts all the pending and ongoing transfers on the channel - - This command should operate synchronously on the channel, - terminating right away all the channels + - For aborted transfers the complete callback should not be called + - Can be called from atomic context or from within a complete + callback of a descriptor. Must not sleep. Drivers must be able + to handle this correctly. + - Termination may be asynchronous. The driver does not have to + wait until the currently active transfer has completely stopped. + See device_synchronize. + + * device_synchronize + - Must synchronize the termination of a channel to the current + context. + - Must make sure that memory for previously submitted + descriptors is no longer accessed by the DMA controller. + - Must make sure that all complete callbacks for previously + submitted descriptors have finished running and none are + scheduled to run. + - May sleep. + Misc notes (stuff that should be documented, but don't really know where to put them) diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 9de9813d0ec5..8ea834f6b289 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -165,7 +165,6 @@ mach-types.h machtypes.h map map_hugetlb -media mconf miboot* mk_elfconfig diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index 831a5363f6be..73b98dfbcea4 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -252,6 +252,11 @@ GPIO devm_gpiod_get_index_optional() devm_gpiod_get_optional() devm_gpiod_put() + devm_gpiochip_add_data() + devm_gpiochip_remove() + devm_gpio_request() + devm_gpio_request_one() + devm_gpio_free() IIO devm_iio_device_alloc() diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt index 07795ec51cde..9d9e47dfc013 100644 --- a/Documentation/driver-model/platform.txt +++ b/Documentation/driver-model/platform.txt @@ -63,6 +63,20 @@ runtime memory footprint: int platform_driver_probe(struct platform_driver *drv, int (*probe)(struct platform_device *)) +Kernel modules can be composed of several platform drivers. The platform core +provides helpers to register and unregister an array of drivers: + + int __platform_register_drivers(struct platform_driver * const *drivers, + unsigned int count, struct module *owner); + void platform_unregister_drivers(struct platform_driver * const *drivers, + unsigned int count); + +If one of the drivers fails to register, all drivers registered up to that +point will be unregistered in reverse order. Note that there is a convenience +macro that passes THIS_MODULE as owner parameter: + + #define platform_register_drivers(drivers, count) + Device Enumeration ~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-model/porting.txt b/Documentation/driver-model/porting.txt index 92d86f7271b4..453053f1661f 100644 --- a/Documentation/driver-model/porting.txt +++ b/Documentation/driver-model/porting.txt @@ -340,8 +340,10 @@ comparison: int (*match)(struct device * dev, struct device_driver * drv); -match should return '1' if the driver supports the device, and '0' -otherwise. +match should return positive value if the driver supports the device, +and zero otherwise. It may also return error code (for example +-EPROBE_DEFER) if determining that given driver supports the device is +not possible. When a device is registered, the bus's list of drivers is iterated over. bus->match() is called for each one until a match is found. diff --git a/Documentation/dvb/README.dvb-usb b/Documentation/dvb/README.dvb-usb index 8eb92264ee04..6f4b12f7b844 100644 --- a/Documentation/dvb/README.dvb-usb +++ b/Documentation/dvb/README.dvb-usb @@ -45,7 +45,7 @@ Supported devices See the LinuxTV DVB Wiki at www.linuxtv.org for a complete list of cards/drivers/firmwares: -http://www.linuxtv.org/wiki/index.php/DVB_USB +https://linuxtv.org/wiki/index.php/DVB_USB 0. History & News: 2005-06-30 - added support for WideView WT-220U (Thanks to Steve Chang) @@ -121,7 +121,7 @@ working. Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware you need for your device: -http://www.linuxtv.org/wiki/index.php/DVB_USB +https://linuxtv.org/wiki/index.php/DVB_USB 1.2. Compiling @@ -190,7 +190,7 @@ and watch another one. Patches, comments and suggestions are very very welcome. 3. Acknowledgements - Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for + Amaury Demol (Amaury.Demol@parrot.com) and Francois Kanounnikoff from DiBcom for providing specs, code and help, on which the dvb-dibusb, dib3000mb and dib3000mc are based. diff --git a/Documentation/dvb/faq.txt b/Documentation/dvb/faq.txt index 97b1373f2428..a0be92012877 100644 --- a/Documentation/dvb/faq.txt +++ b/Documentation/dvb/faq.txt @@ -76,7 +76,7 @@ Some very frequently asked questions about linuxtv-dvb the TuxBox CVS many interesting DVB applications and the dBox2 DVB source - http://www.linuxtv.org/downloads/ + https://linuxtv.org/downloads DVB Swiss Army Knife library and utilities http://www.nenie.org/misc/mpsys/ diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 91b43d2738c7..1a0a04125f71 100755 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -152,7 +152,7 @@ sub tda10046lifeview { sub av7110 { my $sourcefile = "dvb-ttpci-01.fw-261d"; - my $url = "http://www.linuxtv.org/downloads/firmware/$sourcefile"; + my $url = "https://linuxtv.org/downloads/firmware/$sourcefile"; my $hash = "603431b6259715a8e88f376a53b64e2f"; my $outfile = "dvb-ttpci-01.fw"; @@ -303,7 +303,7 @@ sub vp7049 { } sub dibusb { - my $url = "http://www.linuxtv.org/downloads/firmware/dvb-usb-dibusb-5.0.0.11.fw"; + my $url = "https://linuxtv.org/downloads/firmware/dvb-usb-dibusb-5.0.0.11.fw"; my $outfile = "dvb-dibusb-5.0.0.11.fw"; my $hash = "fa490295a527360ca16dcdf3224ca243"; @@ -351,7 +351,7 @@ sub nxt2004 { sub or51211 { my $fwfile = "dvb-fe-or51211.fw"; - my $url = "http://linuxtv.org/downloads/firmware/$fwfile"; + my $url = "https://linuxtv.org/downloads/firmware/$fwfile"; my $hash = "d830949c771a289505bf9eafc225d491"; checkstandard(); @@ -364,7 +364,7 @@ sub or51211 { sub cx231xx { my $fwfile = "v4l-cx231xx-avcore-01.fw"; - my $url = "http://linuxtv.org/downloads/firmware/$fwfile"; + my $url = "https://linuxtv.org/downloads/firmware/$fwfile"; my $hash = "7d3bb956dc9df0eafded2b56ba57cc42"; checkstandard(); @@ -376,7 +376,7 @@ sub cx231xx { } sub cx18 { - my $url = "http://linuxtv.org/downloads/firmware/"; + my $url = "https://linuxtv.org/downloads/firmware/"; my %files = ( 'v4l-cx23418-apu.fw' => '588f081b562f5c653a3db1ad8f65939a', @@ -450,7 +450,7 @@ sub mpc718 { } sub cx23885 { - my $url = "http://linuxtv.org/downloads/firmware/"; + my $url = "https://linuxtv.org/downloads/firmware/"; my %files = ( 'v4l-cx23885-avcore-01.fw' => 'a9f8f5d901a7fb42f552e1ee6384f3bb', @@ -472,7 +472,7 @@ sub cx23885 { } sub pvrusb2 { - my $url = "http://linuxtv.org/downloads/firmware/"; + my $url = "https://linuxtv.org/downloads/firmware/"; my %files = ( 'v4l-cx25840.fw' => 'dadb79e9904fc8af96e8111d9cb59320', @@ -494,7 +494,7 @@ sub pvrusb2 { sub or51132_qam { my $fwfile = "dvb-fe-or51132-qam.fw"; - my $url = "http://linuxtv.org/downloads/firmware/$fwfile"; + my $url = "https://linuxtv.org/downloads/firmware/$fwfile"; my $hash = "7702e8938612de46ccadfe9b413cb3b5"; checkstandard(); @@ -507,7 +507,7 @@ sub or51132_qam { sub or51132_vsb { my $fwfile = "dvb-fe-or51132-vsb.fw"; - my $url = "http://linuxtv.org/downloads/firmware/$fwfile"; + my $url = "https://linuxtv.org/downloads/firmware/$fwfile"; my $hash = "c16208e02f36fc439a557ad4c613364a"; checkstandard(); @@ -519,7 +519,7 @@ sub or51132_vsb { } sub bluebird { - my $url = "http://www.linuxtv.org/download/dvb/firmware/dvb-usb-bluebird-01.fw"; + my $url = "https://linuxtv.org/download/dvb/firmware/dvb-usb-bluebird-01.fw"; my $outfile = "dvb-usb-bluebird-01.fw"; my $hash = "658397cb9eba9101af9031302671f49d"; @@ -677,7 +677,7 @@ sub drxk_hauppauge_hvr930c { } sub drxk_terratec_h5 { - my $url = "http://www.linuxtv.org/downloads/firmware/"; + my $url = "https://linuxtv.org/downloads/firmware/"; my $hash = "19000dada8e2741162ccc50cc91fa7f1"; my $fwfile = "dvb-usb-terratec-h5-drxk.fw"; diff --git a/Documentation/dvb/readme.txt b/Documentation/dvb/readme.txt index 0b0380c91990..89965041a266 100644 --- a/Documentation/dvb/readme.txt +++ b/Documentation/dvb/readme.txt @@ -2,12 +2,12 @@ Linux Digital Video Broadcast (DVB) subsystem ============================================= The main development site and CVS repository for these -drivers is http://linuxtv.org/. +drivers is https://linuxtv.org. The developer mailing list linux-dvb is also hosted there, -see http://linuxtv.org/lists.php. Please check -the archive http://linuxtv.org/pipermail/linux-dvb/ -and the Wiki http://linuxtv.org/wiki/ +see https://linuxtv.org/lists.php. Please check +the archive https://linuxtv.org/pipermail/linux-dvb/ +and the Wiki https://linuxtv.org/wiki/ before asking newbie questions on the list. API documentation, utilities and test/example programs @@ -16,7 +16,7 @@ are available as part of the old driver package for Linux 2.4 We plan to split this into separate packages, but it's not been done yet. -http://linuxtv.org/downloads/ +https://linuxtv.org/downloads/ What's inside this directory: diff --git a/Documentation/edac.txt b/Documentation/edac.txt index 0cf27a3544a5..f89cfd85ae13 100644 --- a/Documentation/edac.txt +++ b/Documentation/edac.txt @@ -1,9 +1,13 @@ EDAC - Error Detection And Correction ===================================== -"bluesmoke" was the name for this device driver when it was "out-of-tree" -and maintained at sourceforge.net. When it was pushed into 2.6.16 for the -first time, it was renamed to 'EDAC'. +"bluesmoke" was the name for this device driver when it +was "out-of-tree" and maintained at sourceforge.net - +bluesmoke.sourceforge.net. That site is mostly archaic now and can be +used only for historical purposes. + +When the subsystem was pushed into 2.6.16 for the first time, it was +renamed to 'EDAC'. PURPOSE ------- @@ -744,6 +748,52 @@ exports one possible that some errors could be lost. With rdimm's, they display the contents of the registers +AMD64_EDAC REFERENCE DOCUMENTS USED +----------------------------------- +amd64_edac module is based on the following documents +(available from http://support.amd.com/en-us/search/tech-docs): + +1. Title: BIOS and Kernel Developer's Guide for AMD Athlon 64 and AMD + Opteron Processors + AMD publication #: 26094 + Revision: 3.26 + Link: http://support.amd.com/TechDocs/26094.PDF + +2. Title: BIOS and Kernel Developer's Guide for AMD NPT Family 0Fh + Processors + AMD publication #: 32559 + Revision: 3.00 + Issue Date: May 2006 + Link: http://support.amd.com/TechDocs/32559.pdf + +3. Title: BIOS and Kernel Developer's Guide (BKDG) For AMD Family 10h + Processors + AMD publication #: 31116 + Revision: 3.00 + Issue Date: September 07, 2007 + Link: http://support.amd.com/TechDocs/31116.pdf + +4. Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 15h + Models 30h-3Fh Processors + AMD publication #: 49125 + Revision: 3.06 + Issue Date: 2/12/2015 (latest release) + Link: http://support.amd.com/TechDocs/49125_15h_Models_30h-3Fh_BKDG.pdf + +5. Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 15h + Models 60h-6Fh Processors + AMD publication #: 50742 + Revision: 3.01 + Issue Date: 7/23/2015 (latest release) + Link: http://support.amd.com/TechDocs/50742_15h_Models_60h-6Fh_BKDG.pdf + +6. Title: BIOS and Kernel Developer's Guide (BKDG) for AMD Family 16h + Models 00h-0Fh Processors + AMD publication #: 48751 + Revision: 3.03 + Issue Date: 2/23/2015 (latest release) + Link: http://support.amd.com/TechDocs/48751_16h_bkdg.pdf + CREDITS: ======== diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 3fa450881ecb..2d485dea8cec 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -176,11 +176,47 @@ To use 'vim' with mutt: if you want to include the patch inline. (a)ttach works fine without "set paste". +You can also generate patches with 'git format-patch' and then use Mutt +to send them: + $ mutt -H 0001-some-bug-fix.patch + Config options: It should work with default settings. However, it's a good idea to set the "send_charset" to: set send_charset="us-ascii:utf-8" +Mutt is highly customizable. Here is a minimum configuration to start +using Mutt to send patches through Gmail: + +# .muttrc +# ================ IMAP ==================== +set imap_user = 'yourusername@gmail.com' +set imap_pass = 'yourpassword' +set spoolfile = imaps://imap.gmail.com/INBOX +set folder = imaps://imap.gmail.com/ +set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" +set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" +set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + +# ================ SMTP ==================== +set smtp_url = "smtp://username@smtp.gmail.com:587/" +set smtp_pass = $imap_pass +set ssl_force_tls = yes # Require encrypted connection + +# ================ Composition ==================== +set editor = `echo \$EDITOR` +set edit_headers = yes # See the headers when editing +set charset = UTF-8 # value of $LANG; also fallback for send_charset +# Sender, email address, and sign-off line must match +unset use_domain # because joe@localhost is just embarrassing +set realname = "YOUR NAME" +set from = "username@gmail.com" +set use_from = yes + +The Mutt docs have lots more information: + http://dev.mutt.org/trac/wiki/UseCases/Gmail + http://dev.mutt.org/doc/manual.html + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pine (TUI) @@ -220,7 +256,7 @@ to coerce it into behaving. Compose dialog. Please note that "external editor" requires that your editor must not - fork, or in other words, the editor must not return before closing. + fork, or in other words, the editor must not return before closing. You may have to pass additional flags or change the settings of your editor. Most notably if you are using gvim then you must pass the -f option to gvim by putting "/usr/bin/gvim -f" (if the binary is in diff --git a/Documentation/fault-injection/notifier-error-inject.txt b/Documentation/fault-injection/notifier-error-inject.txt index 09adabef513f..83d3f4e43e91 100644 --- a/Documentation/fault-injection/notifier-error-inject.txt +++ b/Documentation/fault-injection/notifier-error-inject.txt @@ -10,6 +10,7 @@ modules that can be used to test the following notifiers. * PM notifier * Memory hotplug notifier * powerpc pSeries reconfig notifier + * Netdevice notifier CPU notifier error injection module ----------------------------------- @@ -87,6 +88,30 @@ Possible pSeries reconfig notifier events to be failed are: * PSERIES_DRCONF_MEM_ADD * PSERIES_DRCONF_MEM_REMOVE +Netdevice notifier error injection module +---------------------------------------------- +This feature is controlled through debugfs interface +/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error + +Netdevice notifier events which can be failed are: + + * NETDEV_REGISTER + * NETDEV_CHANGEMTU + * NETDEV_CHANGENAME + * NETDEV_PRE_UP + * NETDEV_PRE_TYPE_CHANGE + * NETDEV_POST_INIT + * NETDEV_PRECHANGEMTU + * NETDEV_PRECHANGEUPPER + * NETDEV_CHANGEUPPER + +Example: Inject netdevice mtu change error (-22 == -EINVAL) + + # cd /sys/kernel/debug/notifier-error-inject/netdev + # echo -22 > actions/NETDEV_CHANGEMTU/error + # ip link set eth0 mtu 1024 + RTNETLINK answers: Invalid argument + For more usage examples ----------------------- There are tools/testing/selftests using the notifier error injection features diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index 14531da2fb54..703f5784bc90 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | ok | | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | diff --git a/Documentation/features/io/dma_map_attrs/arch-support.txt b/Documentation/features/io/dma_map_attrs/arch-support.txt deleted file mode 100644 index 51d0f1c02a3e..000000000000 --- a/Documentation/features/io/dma_map_attrs/arch-support.txt +++ /dev/null @@ -1,40 +0,0 @@ -# -# Feature name: dma_map_attrs -# Kconfig: HAVE_DMA_ATTRS -# description: arch provides dma_*map*_attrs() APIs -# - ----------------------- - | arch |status| - ----------------------- - | alpha: | ok | - | arc: | TODO | - | arm: | ok | - | arm64: | ok | - | avr32: | TODO | - | blackfin: | TODO | - | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | - | h8300: | ok | - | hexagon: | ok | - | ia64: | ok | - | m32r: | TODO | - | m68k: | TODO | - | metag: | TODO | - | microblaze: | ok | - | mips: | ok | - | mn10300: | TODO | - | nios2: | TODO | - | openrisc: | ok | - | parisc: | TODO | - | powerpc: | ok | - | s390: | ok | - | score: | TODO | - | sh: | ok | - | sparc: | ok | - | tile: | ok | - | um: | TODO | - | unicore32: | ok | - | x86: | ok | - | xtensa: | TODO | - ----------------------- diff --git a/Documentation/features/list-arch.sh b/Documentation/features/list-arch.sh index 6065124a072f..c16b5b595688 100755 --- a/Documentation/features/list-arch.sh +++ b/Documentation/features/list-arch.sh @@ -5,7 +5,7 @@ # (If no arguments are given then it will print the host architecture's status.) # -ARCH=${1:-$(arch | sed 's/x86_64/x86/' | sed 's/i386/x86/')} +ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/')} cd $(dirname $0) echo "#" diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index 76d39d66a5d7..4f66ec133951 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -33,7 +33,7 @@ | sh: | TODO | | sparc: | TODO | | tile: | ok | - | um: | TODO | + | um: | ok | | unicore32: | TODO | | x86: | ok | | xtensa: | TODO | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index e63316239938..4199ffecc0ff 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | .. | | arc: | TODO | | arm: | ok | - | arm64: | .. | + | arm64: | ok | | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index df384e3e845f..523f8307b9cd 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -7,7 +7,7 @@ | arch |status| ----------------------- | alpha: | TODO | - | arc: | .. | + | arc: | ok | | arm: | ok | | arm64: | ok | | avr32: | .. | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index af6816bccb43..df1d1f3c9af2 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | ok | | avr32: | TODO | | blackfin: | TODO | | c6x: | TODO | diff --git a/Documentation/features/vm/pmdp_splitting_flush/arch-support.txt b/Documentation/features/vm/pmdp_splitting_flush/arch-support.txt deleted file mode 100644 index 26f74b457e0b..000000000000 --- a/Documentation/features/vm/pmdp_splitting_flush/arch-support.txt +++ /dev/null @@ -1,40 +0,0 @@ -# -# Feature name: pmdp_splitting_flush -# Kconfig: __HAVE_ARCH_PMDP_SPLITTING_FLUSH -# description: arch supports the pmdp_splitting_flush() VM API -# - ----------------------- - | arch |status| - ----------------------- - | alpha: | TODO | - | arc: | TODO | - | arm: | ok | - | arm64: | ok | - | avr32: | TODO | - | blackfin: | TODO | - | c6x: | TODO | - | cris: | TODO | - | frv: | TODO | - | h8300: | TODO | - | hexagon: | TODO | - | ia64: | TODO | - | m32r: | TODO | - | m68k: | TODO | - | metag: | TODO | - | microblaze: | TODO | - | mips: | ok | - | mn10300: | TODO | - | nios2: | TODO | - | openrisc: | TODO | - | parisc: | TODO | - | powerpc: | ok | - | s390: | ok | - | score: | TODO | - | sh: | TODO | - | sparc: | TODO | - | tile: | TODO | - | um: | TODO | - | unicore32: | TODO | - | x86: | ok | - | xtensa: | TODO | - ----------------------- diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index aaaa21db6226..3de5434c857c 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -7,7 +7,7 @@ | arch |status| ----------------------- | alpha: | TODO | - | arc: | TODO | + | arc: | ok | | arm: | ok | | arm64: | ok | | avr32: | TODO | diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 06d443450f21..619af9bfdcb3 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -50,8 +50,7 @@ prototypes: int (*rename2) (struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); - const char *(*follow_link) (struct dentry *, void **); - void (*put_link) (struct inode *, void *); + const char *(*get_link) (struct dentry *, struct inode *, void **); void (*truncate) (struct inode *); int (*permission) (struct inode *, int, unsigned int); int (*get_acl)(struct inode *, int); @@ -83,8 +82,7 @@ rmdir: yes (both) (see below) rename: yes (all) (see below) rename2: yes (all) (see below) readlink: no -follow_link: no -put_link: no +get_link: no setattr: yes permission: no (may not block if called in rcu-walk mode) get_acl: no diff --git a/Documentation/filesystems/Makefile b/Documentation/filesystems/Makefile index 13483d192ebb..883010ce5e35 100644 --- a/Documentation/filesystems/Makefile +++ b/Documentation/filesystems/Makefile @@ -1,5 +1,3 @@ -subdir-y := configfs - # List of programs to build hostprogs-y := dnotify_test diff --git a/Documentation/filesystems/configfs/Makefile b/Documentation/filesystems/configfs/Makefile deleted file mode 100644 index be7ec5e67dbc..000000000000 --- a/Documentation/filesystems/configfs/Makefile +++ /dev/null @@ -1,3 +0,0 @@ -ifneq ($(CONFIG_CONFIGFS_FS),) -obj-m += configfs_example_explicit.o configfs_example_macros.o -endif diff --git a/Documentation/filesystems/configfs/configfs.txt b/Documentation/filesystems/configfs/configfs.txt index b40fec9d3f53..8ec9136aae56 100644 --- a/Documentation/filesystems/configfs/configfs.txt +++ b/Documentation/filesystems/configfs/configfs.txt @@ -51,15 +51,27 @@ configfs tree is always there, whether mounted on /config or not. An item is created via mkdir(2). The item's attributes will also appear at this time. readdir(3) can determine what the attributes are, read(2) can query their default values, and write(2) can store new -values. Like sysfs, attributes should be ASCII text files, preferably -with only one value per file. The same efficiency caveats from sysfs -apply. Don't mix more than one attribute in one attribute file. - -Like sysfs, configfs expects write(2) to store the entire buffer at -once. When writing to configfs attributes, userspace processes should -first read the entire file, modify the portions they wish to change, and -then write the entire buffer back. Attribute files have a maximum size -of one page (PAGE_SIZE, 4096 on i386). +values. Don't mix more than one attribute in one attribute file. + +There are two types of configfs attributes: + +* Normal attributes, which similar to sysfs attributes, are small ASCII text +files, with a maximum size of one page (PAGE_SIZE, 4096 on i386). Preferably +only one value per file should be used, and the same caveats from sysfs apply. +Configfs expects write(2) to store the entire buffer at once. When writing to +normal configfs attributes, userspace processes should first read the entire +file, modify the portions they wish to change, and then write the entire +buffer back. + +* Binary attributes, which are somewhat similar to sysfs binary attributes, +but with a few slight changes to semantics. The PAGE_SIZE limitation does not +apply, but the whole binary item must fit in single kernel vmalloc'ed buffer. +The write(2) calls from user space are buffered, and the attributes' +write_bin_attribute method will be invoked on the final close, therefore it is +imperative for user-space to check the return code of close(2) in order to +verify that the operation finished successfully. +To avoid a malicious user OOMing the kernel, there's a per-binary attribute +maximum buffer value. When an item needs to be destroyed, remove it with rmdir(2). An item cannot be destroyed if any other item has a link to it (via @@ -160,12 +172,6 @@ among other things. For that, it needs a type. struct configfs_item_operations { void (*release)(struct config_item *); - ssize_t (*show_attribute)(struct config_item *, - struct configfs_attribute *, - char *); - ssize_t (*store_attribute)(struct config_item *, - struct configfs_attribute *, - const char *, size_t); int (*allow_link)(struct config_item *src, struct config_item *target); int (*drop_link)(struct config_item *src, @@ -177,15 +183,14 @@ among other things. For that, it needs a type. struct configfs_item_operations *ct_item_ops; struct configfs_group_operations *ct_group_ops; struct configfs_attribute **ct_attrs; + struct configfs_bin_attribute **ct_bin_attrs; }; The most basic function of a config_item_type is to define what operations can be performed on a config_item. All items that have been allocated dynamically will need to provide the ct_item_ops->release() method. This method is called when the config_item's reference count -reaches zero. Items that wish to display an attribute need to provide -the ct_item_ops->show_attribute() method. Similarly, storing a new -attribute value uses the store_attribute() method. +reaches zero. [struct configfs_attribute] @@ -193,6 +198,8 @@ attribute value uses the store_attribute() method. char *ca_name; struct module *ca_owner; umode_t ca_mode; + ssize_t (*show)(struct config_item *, char *); + ssize_t (*store)(struct config_item *, const char *, size_t); }; When a config_item wants an attribute to appear as a file in the item's @@ -202,10 +209,36 @@ config_item_type->ct_attrs. When the item appears in configfs, the attribute file will appear with the configfs_attribute->ca_name filename. configfs_attribute->ca_mode specifies the file permissions. -If an attribute is readable and the config_item provides a -ct_item_ops->show_attribute() method, that method will be called +If an attribute is readable and provides a ->show method, that method will +be called whenever userspace asks for a read(2) on the attribute. If an +attribute is writable and provides a ->store method, that method will be +be called whenever userspace asks for a write(2) on the attribute. + +[struct configfs_bin_attribute] + + struct configfs_attribute { + struct configfs_attribute cb_attr; + void *cb_private; + size_t cb_max_size; + }; + +The binary attribute is used when the one needs to use binary blob to +appear as the contents of a file in the item's configfs directory. +To do so add the binary attribute to the NULL-terminated array +config_item_type->ct_bin_attrs, and the item appears in configfs, the +attribute file will appear with the configfs_bin_attribute->cb_attr.ca_name +filename. configfs_bin_attribute->cb_attr.ca_mode specifies the file +permissions. +The cb_private member is provided for use by the driver, while the +cb_max_size member specifies the maximum amount of vmalloc buffer +to be used. + +If binary attribute is readable and the config_item provides a +ct_item_ops->read_bin_attribute() method, that method will be called whenever userspace asks for a read(2) on the attribute. The converse -will happen for write(2). +will happen for write(2). The reads/writes are bufferred so only a +single read/write will occur; the attributes' need not concern itself +with it. [struct config_group] @@ -217,7 +250,8 @@ child item. struct config_item cg_item; struct list_head cg_children; struct configfs_subsystem *cg_subsys; - struct config_group **default_groups; + struct list_head default_groups; + struct list_head group_entry; }; void config_group_init(struct config_group *group); @@ -311,20 +345,10 @@ the subsystem must be ready for it. [An Example] The best example of these basic concepts is the simple_children -subsystem/group and the simple_child item in configfs_example_explicit.c -and configfs_example_macros.c. It shows a trivial object displaying and -storing an attribute, and a simple group creating and destroying these -children. - -The only difference between configfs_example_explicit.c and -configfs_example_macros.c is how the attributes of the childless item -are defined. The childless item has extended attributes, each with -their own show()/store() operation. This follows a convention commonly -used in sysfs. configfs_example_explicit.c creates these attributes -by explicitly defining the structures involved. Conversely -configfs_example_macros.c uses some convenience macros from configfs.h -to define the attributes. These macros are similar to their sysfs -counterparts. +subsystem/group and the simple_child item in +samples/configfs/configfs_sample.c. It shows a trivial object displaying +and storing an attribute, and a simple group creating and destroying +these children. [Hierarchy Navigation and the Subsystem Mutex] @@ -397,15 +421,15 @@ These automatic subgroups, or default groups, do not preclude other children of the parent group. If ct_group_ops->make_group() exists, other child groups can be created on the parent group directly. -A configfs subsystem specifies default groups by filling in the -NULL-terminated array default_groups on the config_group structure. -Each group in that array is populated in the configfs tree at the same +A configfs subsystem specifies default groups by adding them using the +configfs_add_default_group() function to the parent config_group +structure. Each added group is populated in the configfs tree at the same time as the parent group. Similarly, they are removed at the same time as the parent. No extra notification is provided. When a ->drop_item() method call notifies the subsystem the parent group is going away, it also means every default group child associated with that parent group. -As a consequence of this, default_groups cannot be removed directly via +As a consequence of this, default groups cannot be removed directly via rmdir(2). They also are not considered when rmdir(2) on the parent group is checking for children. diff --git a/Documentation/filesystems/configfs/configfs_example_explicit.c b/Documentation/filesystems/configfs/configfs_example_explicit.c deleted file mode 100644 index 1420233dfa55..000000000000 --- a/Documentation/filesystems/configfs/configfs_example_explicit.c +++ /dev/null @@ -1,483 +0,0 @@ -/* - * vim: noexpandtab ts=8 sts=0 sw=8: - * - * configfs_example_explicit.c - This file is a demonstration module - * containing a number of configfs subsystems. It explicitly defines - * each structure without using the helper macros defined in - * configfs.h. - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this program; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 021110-1307, USA. - * - * Based on sysfs: - * sysfs is Copyright (C) 2001, 2002, 2003 Patrick Mochel - * - * configfs Copyright (C) 2005 Oracle. All rights reserved. - */ - -#include <linux/init.h> -#include <linux/module.h> -#include <linux/slab.h> - -#include <linux/configfs.h> - - - -/* - * 01-childless - * - * This first example is a childless subsystem. It cannot create - * any config_items. It just has attributes. - * - * Note that we are enclosing the configfs_subsystem inside a container. - * This is not necessary if a subsystem has no attributes directly - * on the subsystem. See the next example, 02-simple-children, for - * such a subsystem. - */ - -struct childless { - struct configfs_subsystem subsys; - int showme; - int storeme; -}; - -struct childless_attribute { - struct configfs_attribute attr; - ssize_t (*show)(struct childless *, char *); - ssize_t (*store)(struct childless *, const char *, size_t); -}; - -static inline struct childless *to_childless(struct config_item *item) -{ - return item ? container_of(to_configfs_subsystem(to_config_group(item)), struct childless, subsys) : NULL; -} - -static ssize_t childless_showme_read(struct childless *childless, - char *page) -{ - ssize_t pos; - - pos = sprintf(page, "%d\n", childless->showme); - childless->showme++; - - return pos; -} - -static ssize_t childless_storeme_read(struct childless *childless, - char *page) -{ - return sprintf(page, "%d\n", childless->storeme); -} - -static ssize_t childless_storeme_write(struct childless *childless, - const char *page, - size_t count) -{ - unsigned long tmp; - char *p = (char *) page; - - tmp = simple_strtoul(p, &p, 10); - if ((*p != '\0') && (*p != '\n')) - return -EINVAL; - - if (tmp > INT_MAX) - return -ERANGE; - - childless->storeme = tmp; - - return count; -} - -static ssize_t childless_description_read(struct childless *childless, - char *page) -{ - return sprintf(page, -"[01-childless]\n" -"\n" -"The childless subsystem is the simplest possible subsystem in\n" -"configfs. It does not support the creation of child config_items.\n" -"It only has a few attributes. In fact, it isn't much different\n" -"than a directory in /proc.\n"); -} - -static struct childless_attribute childless_attr_showme = { - .attr = { .ca_owner = THIS_MODULE, .ca_name = "showme", .ca_mode = S_IRUGO }, - .show = childless_showme_read, -}; -static struct childless_attribute childless_attr_storeme = { - .attr = { .ca_owner = THIS_MODULE, .ca_name = "storeme", .ca_mode = S_IRUGO | S_IWUSR }, - .show = childless_storeme_read, - .store = childless_storeme_write, -}; -static struct childless_attribute childless_attr_description = { - .attr = { .ca_owner = THIS_MODULE, .ca_name = "description", .ca_mode = S_IRUGO }, - .show = childless_description_read, -}; - -static struct configfs_attribute *childless_attrs[] = { - &childless_attr_showme.attr, - &childless_attr_storeme.attr, - &childless_attr_description.attr, - NULL, -}; - -static ssize_t childless_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - struct childless *childless = to_childless(item); - struct childless_attribute *childless_attr = - container_of(attr, struct childless_attribute, attr); - ssize_t ret = 0; - - if (childless_attr->show) - ret = childless_attr->show(childless, page); - return ret; -} - -static ssize_t childless_attr_store(struct config_item *item, - struct configfs_attribute *attr, - const char *page, size_t count) -{ - struct childless *childless = to_childless(item); - struct childless_attribute *childless_attr = - container_of(attr, struct childless_attribute, attr); - ssize_t ret = -EINVAL; - - if (childless_attr->store) - ret = childless_attr->store(childless, page, count); - return ret; -} - -static struct configfs_item_operations childless_item_ops = { - .show_attribute = childless_attr_show, - .store_attribute = childless_attr_store, -}; - -static struct config_item_type childless_type = { - .ct_item_ops = &childless_item_ops, - .ct_attrs = childless_attrs, - .ct_owner = THIS_MODULE, -}; - -static struct childless childless_subsys = { - .subsys = { - .su_group = { - .cg_item = { - .ci_namebuf = "01-childless", - .ci_type = &childless_type, - }, - }, - }, -}; - - -/* ----------------------------------------------------------------- */ - -/* - * 02-simple-children - * - * This example merely has a simple one-attribute child. Note that - * there is no extra attribute structure, as the child's attribute is - * known from the get-go. Also, there is no container for the - * subsystem, as it has no attributes of its own. - */ - -struct simple_child { - struct config_item item; - int storeme; -}; - -static inline struct simple_child *to_simple_child(struct config_item *item) -{ - return item ? container_of(item, struct simple_child, item) : NULL; -} - -static struct configfs_attribute simple_child_attr_storeme = { - .ca_owner = THIS_MODULE, - .ca_name = "storeme", - .ca_mode = S_IRUGO | S_IWUSR, -}; - -static struct configfs_attribute *simple_child_attrs[] = { - &simple_child_attr_storeme, - NULL, -}; - -static ssize_t simple_child_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - ssize_t count; - struct simple_child *simple_child = to_simple_child(item); - - count = sprintf(page, "%d\n", simple_child->storeme); - - return count; -} - -static ssize_t simple_child_attr_store(struct config_item *item, - struct configfs_attribute *attr, - const char *page, size_t count) -{ - struct simple_child *simple_child = to_simple_child(item); - unsigned long tmp; - char *p = (char *) page; - - tmp = simple_strtoul(p, &p, 10); - if (!p || (*p && (*p != '\n'))) - return -EINVAL; - - if (tmp > INT_MAX) - return -ERANGE; - - simple_child->storeme = tmp; - - return count; -} - -static void simple_child_release(struct config_item *item) -{ - kfree(to_simple_child(item)); -} - -static struct configfs_item_operations simple_child_item_ops = { - .release = simple_child_release, - .show_attribute = simple_child_attr_show, - .store_attribute = simple_child_attr_store, -}; - -static struct config_item_type simple_child_type = { - .ct_item_ops = &simple_child_item_ops, - .ct_attrs = simple_child_attrs, - .ct_owner = THIS_MODULE, -}; - - -struct simple_children { - struct config_group group; -}; - -static inline struct simple_children *to_simple_children(struct config_item *item) -{ - return item ? container_of(to_config_group(item), struct simple_children, group) : NULL; -} - -static struct config_item *simple_children_make_item(struct config_group *group, const char *name) -{ - struct simple_child *simple_child; - - simple_child = kzalloc(sizeof(struct simple_child), GFP_KERNEL); - if (!simple_child) - return ERR_PTR(-ENOMEM); - - config_item_init_type_name(&simple_child->item, name, - &simple_child_type); - - simple_child->storeme = 0; - - return &simple_child->item; -} - -static struct configfs_attribute simple_children_attr_description = { - .ca_owner = THIS_MODULE, - .ca_name = "description", - .ca_mode = S_IRUGO, -}; - -static struct configfs_attribute *simple_children_attrs[] = { - &simple_children_attr_description, - NULL, -}; - -static ssize_t simple_children_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - return sprintf(page, -"[02-simple-children]\n" -"\n" -"This subsystem allows the creation of child config_items. These\n" -"items have only one attribute that is readable and writeable.\n"); -} - -static void simple_children_release(struct config_item *item) -{ - kfree(to_simple_children(item)); -} - -static struct configfs_item_operations simple_children_item_ops = { - .release = simple_children_release, - .show_attribute = simple_children_attr_show, -}; - -/* - * Note that, since no extra work is required on ->drop_item(), - * no ->drop_item() is provided. - */ -static struct configfs_group_operations simple_children_group_ops = { - .make_item = simple_children_make_item, -}; - -static struct config_item_type simple_children_type = { - .ct_item_ops = &simple_children_item_ops, - .ct_group_ops = &simple_children_group_ops, - .ct_attrs = simple_children_attrs, - .ct_owner = THIS_MODULE, -}; - -static struct configfs_subsystem simple_children_subsys = { - .su_group = { - .cg_item = { - .ci_namebuf = "02-simple-children", - .ci_type = &simple_children_type, - }, - }, -}; - - -/* ----------------------------------------------------------------- */ - -/* - * 03-group-children - * - * This example reuses the simple_children group from above. However, - * the simple_children group is not the subsystem itself, it is a - * child of the subsystem. Creation of a group in the subsystem creates - * a new simple_children group. That group can then have simple_child - * children of its own. - */ - -static struct config_group *group_children_make_group(struct config_group *group, const char *name) -{ - struct simple_children *simple_children; - - simple_children = kzalloc(sizeof(struct simple_children), - GFP_KERNEL); - if (!simple_children) - return ERR_PTR(-ENOMEM); - - config_group_init_type_name(&simple_children->group, name, - &simple_children_type); - - return &simple_children->group; -} - -static struct configfs_attribute group_children_attr_description = { - .ca_owner = THIS_MODULE, - .ca_name = "description", - .ca_mode = S_IRUGO, -}; - -static struct configfs_attribute *group_children_attrs[] = { - &group_children_attr_description, - NULL, -}; - -static ssize_t group_children_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - return sprintf(page, -"[03-group-children]\n" -"\n" -"This subsystem allows the creation of child config_groups. These\n" -"groups are like the subsystem simple-children.\n"); -} - -static struct configfs_item_operations group_children_item_ops = { - .show_attribute = group_children_attr_show, -}; - -/* - * Note that, since no extra work is required on ->drop_item(), - * no ->drop_item() is provided. - */ -static struct configfs_group_operations group_children_group_ops = { - .make_group = group_children_make_group, -}; - -static struct config_item_type group_children_type = { - .ct_item_ops = &group_children_item_ops, - .ct_group_ops = &group_children_group_ops, - .ct_attrs = group_children_attrs, - .ct_owner = THIS_MODULE, -}; - -static struct configfs_subsystem group_children_subsys = { - .su_group = { - .cg_item = { - .ci_namebuf = "03-group-children", - .ci_type = &group_children_type, - }, - }, -}; - -/* ----------------------------------------------------------------- */ - -/* - * We're now done with our subsystem definitions. - * For convenience in this module, here's a list of them all. It - * allows the init function to easily register them. Most modules - * will only have one subsystem, and will only call register_subsystem - * on it directly. - */ -static struct configfs_subsystem *example_subsys[] = { - &childless_subsys.subsys, - &simple_children_subsys, - &group_children_subsys, - NULL, -}; - -static int __init configfs_example_init(void) -{ - int ret; - int i; - struct configfs_subsystem *subsys; - - for (i = 0; example_subsys[i]; i++) { - subsys = example_subsys[i]; - - config_group_init(&subsys->su_group); - mutex_init(&subsys->su_mutex); - ret = configfs_register_subsystem(subsys); - if (ret) { - printk(KERN_ERR "Error %d while registering subsystem %s\n", - ret, - subsys->su_group.cg_item.ci_namebuf); - goto out_unregister; - } - } - - return 0; - -out_unregister: - for (i--; i >= 0; i--) - configfs_unregister_subsystem(example_subsys[i]); - - return ret; -} - -static void __exit configfs_example_exit(void) -{ - int i; - - for (i = 0; example_subsys[i]; i++) - configfs_unregister_subsystem(example_subsys[i]); -} - -module_init(configfs_example_init); -module_exit(configfs_example_exit); -MODULE_LICENSE("GPL"); diff --git a/Documentation/filesystems/configfs/configfs_example_macros.c b/Documentation/filesystems/configfs/configfs_example_macros.c deleted file mode 100644 index 327dfbc640a9..000000000000 --- a/Documentation/filesystems/configfs/configfs_example_macros.c +++ /dev/null @@ -1,446 +0,0 @@ -/* - * vim: noexpandtab ts=8 sts=0 sw=8: - * - * configfs_example_macros.c - This file is a demonstration module - * containing a number of configfs subsystems. It uses the helper - * macros defined by configfs.h - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * General Public License for more details. - * - * You should have received a copy of the GNU General Public - * License along with this program; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 021110-1307, USA. - * - * Based on sysfs: - * sysfs is Copyright (C) 2001, 2002, 2003 Patrick Mochel - * - * configfs Copyright (C) 2005 Oracle. All rights reserved. - */ - -#include <linux/init.h> -#include <linux/module.h> -#include <linux/slab.h> - -#include <linux/configfs.h> - - - -/* - * 01-childless - * - * This first example is a childless subsystem. It cannot create - * any config_items. It just has attributes. - * - * Note that we are enclosing the configfs_subsystem inside a container. - * This is not necessary if a subsystem has no attributes directly - * on the subsystem. See the next example, 02-simple-children, for - * such a subsystem. - */ - -struct childless { - struct configfs_subsystem subsys; - int showme; - int storeme; -}; - -static inline struct childless *to_childless(struct config_item *item) -{ - return item ? container_of(to_configfs_subsystem(to_config_group(item)), struct childless, subsys) : NULL; -} - -CONFIGFS_ATTR_STRUCT(childless); -#define CHILDLESS_ATTR(_name, _mode, _show, _store) \ -struct childless_attribute childless_attr_##_name = __CONFIGFS_ATTR(_name, _mode, _show, _store) -#define CHILDLESS_ATTR_RO(_name, _show) \ -struct childless_attribute childless_attr_##_name = __CONFIGFS_ATTR_RO(_name, _show); - -static ssize_t childless_showme_read(struct childless *childless, - char *page) -{ - ssize_t pos; - - pos = sprintf(page, "%d\n", childless->showme); - childless->showme++; - - return pos; -} - -static ssize_t childless_storeme_read(struct childless *childless, - char *page) -{ - return sprintf(page, "%d\n", childless->storeme); -} - -static ssize_t childless_storeme_write(struct childless *childless, - const char *page, - size_t count) -{ - unsigned long tmp; - char *p = (char *) page; - - tmp = simple_strtoul(p, &p, 10); - if (!p || (*p && (*p != '\n'))) - return -EINVAL; - - if (tmp > INT_MAX) - return -ERANGE; - - childless->storeme = tmp; - - return count; -} - -static ssize_t childless_description_read(struct childless *childless, - char *page) -{ - return sprintf(page, -"[01-childless]\n" -"\n" -"The childless subsystem is the simplest possible subsystem in\n" -"configfs. It does not support the creation of child config_items.\n" -"It only has a few attributes. In fact, it isn't much different\n" -"than a directory in /proc.\n"); -} - -CHILDLESS_ATTR_RO(showme, childless_showme_read); -CHILDLESS_ATTR(storeme, S_IRUGO | S_IWUSR, childless_storeme_read, - childless_storeme_write); -CHILDLESS_ATTR_RO(description, childless_description_read); - -static struct configfs_attribute *childless_attrs[] = { - &childless_attr_showme.attr, - &childless_attr_storeme.attr, - &childless_attr_description.attr, - NULL, -}; - -CONFIGFS_ATTR_OPS(childless); -static struct configfs_item_operations childless_item_ops = { - .show_attribute = childless_attr_show, - .store_attribute = childless_attr_store, -}; - -static struct config_item_type childless_type = { - .ct_item_ops = &childless_item_ops, - .ct_attrs = childless_attrs, - .ct_owner = THIS_MODULE, -}; - -static struct childless childless_subsys = { - .subsys = { - .su_group = { - .cg_item = { - .ci_namebuf = "01-childless", - .ci_type = &childless_type, - }, - }, - }, -}; - - -/* ----------------------------------------------------------------- */ - -/* - * 02-simple-children - * - * This example merely has a simple one-attribute child. Note that - * there is no extra attribute structure, as the child's attribute is - * known from the get-go. Also, there is no container for the - * subsystem, as it has no attributes of its own. - */ - -struct simple_child { - struct config_item item; - int storeme; -}; - -static inline struct simple_child *to_simple_child(struct config_item *item) -{ - return item ? container_of(item, struct simple_child, item) : NULL; -} - -static struct configfs_attribute simple_child_attr_storeme = { - .ca_owner = THIS_MODULE, - .ca_name = "storeme", - .ca_mode = S_IRUGO | S_IWUSR, -}; - -static struct configfs_attribute *simple_child_attrs[] = { - &simple_child_attr_storeme, - NULL, -}; - -static ssize_t simple_child_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - ssize_t count; - struct simple_child *simple_child = to_simple_child(item); - - count = sprintf(page, "%d\n", simple_child->storeme); - - return count; -} - -static ssize_t simple_child_attr_store(struct config_item *item, - struct configfs_attribute *attr, - const char *page, size_t count) -{ - struct simple_child *simple_child = to_simple_child(item); - unsigned long tmp; - char *p = (char *) page; - - tmp = simple_strtoul(p, &p, 10); - if (!p || (*p && (*p != '\n'))) - return -EINVAL; - - if (tmp > INT_MAX) - return -ERANGE; - - simple_child->storeme = tmp; - - return count; -} - -static void simple_child_release(struct config_item *item) -{ - kfree(to_simple_child(item)); -} - -static struct configfs_item_operations simple_child_item_ops = { - .release = simple_child_release, - .show_attribute = simple_child_attr_show, - .store_attribute = simple_child_attr_store, -}; - -static struct config_item_type simple_child_type = { - .ct_item_ops = &simple_child_item_ops, - .ct_attrs = simple_child_attrs, - .ct_owner = THIS_MODULE, -}; - - -struct simple_children { - struct config_group group; -}; - -static inline struct simple_children *to_simple_children(struct config_item *item) -{ - return item ? container_of(to_config_group(item), struct simple_children, group) : NULL; -} - -static struct config_item *simple_children_make_item(struct config_group *group, const char *name) -{ - struct simple_child *simple_child; - - simple_child = kzalloc(sizeof(struct simple_child), GFP_KERNEL); - if (!simple_child) - return ERR_PTR(-ENOMEM); - - config_item_init_type_name(&simple_child->item, name, - &simple_child_type); - - simple_child->storeme = 0; - - return &simple_child->item; -} - -static struct configfs_attribute simple_children_attr_description = { - .ca_owner = THIS_MODULE, - .ca_name = "description", - .ca_mode = S_IRUGO, -}; - -static struct configfs_attribute *simple_children_attrs[] = { - &simple_children_attr_description, - NULL, -}; - -static ssize_t simple_children_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - return sprintf(page, -"[02-simple-children]\n" -"\n" -"This subsystem allows the creation of child config_items. These\n" -"items have only one attribute that is readable and writeable.\n"); -} - -static void simple_children_release(struct config_item *item) -{ - kfree(to_simple_children(item)); -} - -static struct configfs_item_operations simple_children_item_ops = { - .release = simple_children_release, - .show_attribute = simple_children_attr_show, -}; - -/* - * Note that, since no extra work is required on ->drop_item(), - * no ->drop_item() is provided. - */ -static struct configfs_group_operations simple_children_group_ops = { - .make_item = simple_children_make_item, -}; - -static struct config_item_type simple_children_type = { - .ct_item_ops = &simple_children_item_ops, - .ct_group_ops = &simple_children_group_ops, - .ct_attrs = simple_children_attrs, - .ct_owner = THIS_MODULE, -}; - -static struct configfs_subsystem simple_children_subsys = { - .su_group = { - .cg_item = { - .ci_namebuf = "02-simple-children", - .ci_type = &simple_children_type, - }, - }, -}; - - -/* ----------------------------------------------------------------- */ - -/* - * 03-group-children - * - * This example reuses the simple_children group from above. However, - * the simple_children group is not the subsystem itself, it is a - * child of the subsystem. Creation of a group in the subsystem creates - * a new simple_children group. That group can then have simple_child - * children of its own. - */ - -static struct config_group *group_children_make_group(struct config_group *group, const char *name) -{ - struct simple_children *simple_children; - - simple_children = kzalloc(sizeof(struct simple_children), - GFP_KERNEL); - if (!simple_children) - return ERR_PTR(-ENOMEM); - - config_group_init_type_name(&simple_children->group, name, - &simple_children_type); - - return &simple_children->group; -} - -static struct configfs_attribute group_children_attr_description = { - .ca_owner = THIS_MODULE, - .ca_name = "description", - .ca_mode = S_IRUGO, -}; - -static struct configfs_attribute *group_children_attrs[] = { - &group_children_attr_description, - NULL, -}; - -static ssize_t group_children_attr_show(struct config_item *item, - struct configfs_attribute *attr, - char *page) -{ - return sprintf(page, -"[03-group-children]\n" -"\n" -"This subsystem allows the creation of child config_groups. These\n" -"groups are like the subsystem simple-children.\n"); -} - -static struct configfs_item_operations group_children_item_ops = { - .show_attribute = group_children_attr_show, -}; - -/* - * Note that, since no extra work is required on ->drop_item(), - * no ->drop_item() is provided. - */ -static struct configfs_group_operations group_children_group_ops = { - .make_group = group_children_make_group, -}; - -static struct config_item_type group_children_type = { - .ct_item_ops = &group_children_item_ops, - .ct_group_ops = &group_children_group_ops, - .ct_attrs = group_children_attrs, - .ct_owner = THIS_MODULE, -}; - -static struct configfs_subsystem group_children_subsys = { - .su_group = { - .cg_item = { - .ci_namebuf = "03-group-children", - .ci_type = &group_children_type, - }, - }, -}; - -/* ----------------------------------------------------------------- */ - -/* - * We're now done with our subsystem definitions. - * For convenience in this module, here's a list of them all. It - * allows the init function to easily register them. Most modules - * will only have one subsystem, and will only call register_subsystem - * on it directly. - */ -static struct configfs_subsystem *example_subsys[] = { - &childless_subsys.subsys, - &simple_children_subsys, - &group_children_subsys, - NULL, -}; - -static int __init configfs_example_init(void) -{ - int ret; - int i; - struct configfs_subsystem *subsys; - - for (i = 0; example_subsys[i]; i++) { - subsys = example_subsys[i]; - - config_group_init(&subsys->su_group); - mutex_init(&subsys->su_mutex); - ret = configfs_register_subsystem(subsys); - if (ret) { - printk(KERN_ERR "Error %d while registering subsystem %s\n", - ret, - subsys->su_group.cg_item.ci_namebuf); - goto out_unregister; - } - } - - return 0; - -out_unregister: - for (i--; i >= 0; i--) - configfs_unregister_subsystem(example_subsys[i]); - - return ret; -} - -static void __exit configfs_example_exit(void) -{ - int i; - - for (i = 0; example_subsys[i]; i++) - configfs_unregister_subsystem(example_subsys[i]); -} - -module_init(configfs_example_init); -module_exit(configfs_example_exit); -MODULE_LICENSE("GPL"); diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 463f595733e8..4f45f71149cb 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -105,7 +105,7 @@ a variable of type size_t. Boolean values can be placed in debugfs with: struct dentry *debugfs_create_bool(const char *name, umode_t mode, - struct dentry *parent, u32 *value); + struct dentry *parent, bool *value); A read on the resulting file will yield either Y (for non-zero values) or N, followed by a newline. If written to, it will accept either upper- or diff --git a/Documentation/filesystems/devpts.txt b/Documentation/filesystems/devpts.txt index 68dffd87f9b7..30d2fcb32f72 100644 --- a/Documentation/filesystems/devpts.txt +++ b/Documentation/filesystems/devpts.txt @@ -51,6 +51,15 @@ where 'ns_exec -cm /bin/bash' calls clone() with CLONE_NEWNS flag and execs /bin/bash in the child process. A pty created by the sshd is not visible in the original mount of /dev/pts. +Total count of pty pairs in all instances is limited by sysctls: +kernel.pty.max = 4096 - global limit +kernel.pty.reserve = 1024 - reserve for initial instance +kernel.pty.nr - current count of ptys + +Per-instance limit could be set by adding mount option "max=<count>". +This feature was added in kernel 3.4 together with sysctl kernel.pty.reserve. +In kernels older than 3.4 sysctl kernel.pty.max works as per-instance limit. + User-space changes ------------------ diff --git a/Documentation/filesystems/efivarfs.txt b/Documentation/filesystems/efivarfs.txt index c477af086e65..686a64bba775 100644 --- a/Documentation/filesystems/efivarfs.txt +++ b/Documentation/filesystems/efivarfs.txt @@ -14,3 +14,10 @@ filesystem. efivarfs is typically mounted like this, mount -t efivarfs none /sys/firmware/efi/efivars + +Due to the presence of numerous firmware bugs where removing non-standard +UEFI variables causes the system firmware to fail to POST, efivarfs +files that are not well-known standardized variables are created +as immutable files. This doesn't prevent removal - "chattr -i" will work - +but it does prevent this kind of failure from being accomplished +accidentally. diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index e2d5105b7214..e1c9f0849da6 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -102,7 +102,8 @@ background_gc=%s Turn on/off cleaning operations, namely garbage collection, triggered in background when I/O subsystem is idle. If background_gc=on, it will turn on the garbage collection and if background_gc=off, garbage collection - will be truned off. + will be turned off. If background_gc=sync, it will turn + on synchronous garbage collection running in background. Default value for this option is on. So garbage collection is on by default. disable_roll_forward Disable the roll-forward recovery routine @@ -144,10 +145,12 @@ extent_cache Enable an extent cache based on rb-tree, it can cache as many as extent which map between contiguous logical address and physical address per inode, resulting in increasing the cache hit ratio. Set by default. -noextent_cache Diable an extent cache based on rb-tree explicitly, see +noextent_cache Disable an extent cache based on rb-tree explicitly, see the above extent_cache mount option. noinline_data Disable the inline data feature, inline data feature is enabled by default. +data_flush Enable data flushing before checkpoint in order to + persist data of regular and symlink. ================================================================================ DEBUGFS ENTRIES @@ -191,7 +194,7 @@ Files in /sys/fs/f2fs/<devname> policy for garbage collection. Setting gc_idle = 0 (default) will disable this option. Setting gc_idle = 1 will select the Cost Benefit approach - & setting gc_idle = 2 will select the greedy aproach. + & setting gc_idle = 2 will select the greedy approach. reclaim_segments This parameter controls the number of prefree segments to be reclaimed. If the number of prefree @@ -297,7 +300,7 @@ The dump.f2fs shows the information of specific inode and dumps SSA and SIT to file. Each file is dump_ssa and dump_sit. The dump.f2fs is used to debug on-disk data structures of the f2fs filesystem. -It shows on-disk inode information reconized by a given inode number, and is +It shows on-disk inode information recognized by a given inode number, and is able to dump all the SSA and SIT entries into predefined files, ./dump_ssa and ./dump_sit respectively. diff --git a/Documentation/filesystems/gfs2-glocks.txt b/Documentation/filesystems/gfs2-glocks.txt index fcc79957be63..1fb12f9dfe48 100644 --- a/Documentation/filesystems/gfs2-glocks.txt +++ b/Documentation/filesystems/gfs2-glocks.txt @@ -5,7 +5,7 @@ This documents the basic principles of the glock state machine internals. Each glock (struct gfs2_glock in fs/gfs2/incore.h) has two main (internal) locks: - 1. A spinlock (gl_spin) which protects the internal state such + 1. A spinlock (gl_lockref.lock) which protects the internal state such as gl_state, gl_target and the list of holders (gl_holders) 2. A non-blocking bit lock, GLF_LOCK, which is used to prevent other threads from making calls to the DLM, etc. at the same time. If a @@ -82,8 +82,8 @@ rather than via the glock. Locking rules for glock operations: -Operation | GLF_LOCK bit lock held | gl_spin spinlock held ------------------------------------------------------------------ +Operation | GLF_LOCK bit lock held | gl_lockref.lock spinlock held +------------------------------------------------------------------------- go_xmote_th | Yes | No go_xmote_bh | Yes | No go_inval | Yes | No diff --git a/Documentation/filesystems/nfs/fault_injection.txt b/Documentation/filesystems/nfs/fault_injection.txt index 426d166089a3..f3a5b0a8ac05 100644 --- a/Documentation/filesystems/nfs/fault_injection.txt +++ b/Documentation/filesystems/nfs/fault_injection.txt @@ -49,13 +49,13 @@ forget_locks: forget_delegations: A delegation is used to assure the client that a file, or part of a file, has not changed since the delegation was awarded. Clearing this list will - force the client to reaquire its delegation before accessing the file + force the client to reacquire its delegation before accessing the file again. recall_delegations: Delegations can be recalled by the server when another client attempts to access a file. This test will notify the client that its delegation has - been revoked, forcing the client to reaquire the delegation before using + been revoked, forcing the client to reacquire the delegation before using the file again. diff --git a/Documentation/filesystems/nfs/nfs-rdma.txt b/Documentation/filesystems/nfs/nfs-rdma.txt index 906b6c233f62..1e6564545edf 100644 --- a/Documentation/filesystems/nfs/nfs-rdma.txt +++ b/Documentation/filesystems/nfs/nfs-rdma.txt @@ -218,7 +218,7 @@ NFS/RDMA Setup /vol0 192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash) The IP address(es) is(are) the client's IPoIB address for an InfiniBand - HCA or the cleint's iWARP address(es) for an RNIC. + HCA or the client's iWARP address(es) for an RNIC. NOTE: The "insecure" option must be used because the NFS/RDMA client does not use a reserved port. diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index 2d66ed688125..0b2883b17d4c 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -157,13 +157,16 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: both: use both BOOTP and RARP but not DHCP (old option kept for backwards compatibility) + if dhcp is used, the client identifier can be used by following + format "ip=dhcp,client-id-type,client-id-value" + Default: any <dns0-ip> IP address of first nameserver. Value gets exported by /proc/net/pnp which is often linked on embedded systems by /etc/resolv.conf. - <dns1-ip> IP address of secound nameserver. + <dns1-ip> IP address of second nameserver. Same as above. diff --git a/Documentation/filesystems/nfs/pnfs.txt b/Documentation/filesystems/nfs/pnfs.txt index 44a9f2493a88..8de578a98222 100644 --- a/Documentation/filesystems/nfs/pnfs.txt +++ b/Documentation/filesystems/nfs/pnfs.txt @@ -64,8 +64,8 @@ table which are called by the nfs-client pnfs-core to implement the different layout types. Files-layout-driver code is in: fs/nfs/filelayout/.. directory -Objects-layout-deriver code is in: fs/nfs/objlayout/.. directory -Blocks-layout-deriver code is in: fs/nfs/blocklayout/.. directory +Objects-layout-driver code is in: fs/nfs/objlayout/.. directory +Blocks-layout-driver code is in: fs/nfs/blocklayout/.. directory Flexfiles-layout-driver code is in: fs/nfs/flexfilelayout/.. directory objects-layout setup @@ -91,7 +91,7 @@ The API to the login script is as follows: Usage: $0 -u <URI> -o <OSDNAME> -s <SYSTEMID> Options: -u target uri e.g. iscsi://<ip>:<port> - (allways exists) + (always exists) (More protocols can be defined in the future. The client does not interpret this string it is passed unchanged as received from the Server) diff --git a/Documentation/filesystems/nfs/rpc-server-gss.txt b/Documentation/filesystems/nfs/rpc-server-gss.txt index 716f4be8e8b3..310bbbaf9080 100644 --- a/Documentation/filesystems/nfs/rpc-server-gss.txt +++ b/Documentation/filesystems/nfs/rpc-server-gss.txt @@ -57,7 +57,7 @@ the Kerberos tickets, that needs to be sent through the GSS layer in order to perform context establishment. B) It does not properly handle creds where the user is member of more -than a few housand groups (the current hard limit in the kernel is 65K +than a few thousand groups (the current hard limit in the kernel is 65K groups) due to limitation on the size of the buffer that can be send back to the kernel (4KiB). diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index 6db0e5d1da07..28091457b71a 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -1,4 +1,5 @@ -Written by: Neil Brown <neilb@suse.de> +Written by: Neil Brown +Please see MAINTAINERS file for where to send questions. Overlay Filesystem ================== diff --git a/Documentation/filesystems/path-lookup.md b/Documentation/filesystems/path-lookup.md new file mode 100644 index 000000000000..1b39e084a2b2 --- /dev/null +++ b/Documentation/filesystems/path-lookup.md @@ -0,0 +1,1297 @@ +<head> +<style> p { max-width:50em} ol, ul {max-width: 40em}</style> +</head> + +Pathname lookup in Linux. +========================= + +This write-up is based on three articles published at lwn.net: + +- <https://lwn.net/Articles/649115/> Pathname lookup in Linux +- <https://lwn.net/Articles/649729/> RCU-walk: faster pathname lookup in Linux +- <https://lwn.net/Articles/650786/> A walk among the symlinks + +Written by Neil Brown with help from Al Viro and Jon Corbet. + +Introduction +------------ + +The most obvious aspect of pathname lookup, which very little +exploration is needed to discover, is that it is complex. There are +many rules, special cases, and implementation alternatives that all +combine to confuse the unwary reader. Computer science has long been +acquainted with such complexity and has tools to help manage it. One +tool that we will make extensive use of is "divide and conquer". For +the early parts of the analysis we will divide off symlinks - leaving +them until the final part. Well before we get to symlinks we have +another major division based on the VFS's approach to locking which +will allow us to review "REF-walk" and "RCU-walk" separately. But we +are getting ahead of ourselves. There are some important low level +distinctions we need to clarify first. + +There are two sorts of ... +-------------------------- + +[`openat()`]: http://man7.org/linux/man-pages/man2/openat.2.html + +Pathnames (sometimes "file names"), used to identify objects in the +filesystem, will be familiar to most readers. They contain two sorts +of elements: "slashes" that are sequences of one or more "`/`" +characters, and "components" that are sequences of one or more +non-"`/`" characters. These form two kinds of paths. Those that +start with slashes are "absolute" and start from the filesystem root. +The others are "relative" and start from the current directory, or +from some other location specified by a file descriptor given to a +"xxx`at`" system call such as "[`openat()`]". + +[`execveat()`]: http://man7.org/linux/man-pages/man2/execveat.2.html + +It is tempting to describe the second kind as starting with a +component, but that isn't always accurate: a pathname can lack both +slashes and components, it can be empty, in other words. This is +generally forbidden in POSIX, but some of those "xxx`at`" system calls +in Linux permit it when the `AT_EMPTY_PATH` flag is given. For +example, if you have an open file descriptor on an executable file you +can execute it by calling [`execveat()`] passing the file descriptor, +an empty path, and the `AT_EMPTY_PATH` flag. + +These paths can be divided into two sections: the final component and +everything else. The "everything else" is the easy bit. In all cases +it must identify a directory that already exists, otherwise an error +such as `ENOENT` or `ENOTDIR` will be reported. + +The final component is not so simple. Not only do different system +calls interpret it quite differently (e.g. some create it, some do +not), but it might not even exist: neither the empty pathname nor the +pathname that is just slashes have a final component. If it does +exist, it could be "`.`" or "`..`" which are handled quite differently +from other components. + +[POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 + +If a pathname ends with a slash, such as "`/tmp/foo/`" it might be +tempting to consider that to have an empty final component. In many +ways that would lead to correct results, but not always. In +particular, `mkdir()` and `rmdir()` each create or remove a directory named +by the final component, and they are required to work with pathnames +ending in "`/`". According to [POSIX] + +> A pathname that contains at least one non- <slash> character and +> that ends with one or more trailing <slash> characters shall not +> be resolved successfully unless the last pathname component before +> the trailing <slash> characters names an existing directory or a +> directory entry that is to be created for a directory immediately +> after the pathname is resolved. + +The Linux pathname walking code (mostly in `fs/namei.c`) deals with +all of these issues: breaking the path into components, handling the +"everything else" quite separately from the final component, and +checking that the trailing slash is not used where it isn't +permitted. It also addresses the important issue of concurrent +access. + +While one process is looking up a pathname, another might be making +changes that affect that lookup. One fairly extreme case is that if +"a/b" were renamed to "a/c/b" while another process were looking up +"a/b/..", that process might successfully resolve on "a/c". +Most races are much more subtle, and a big part of the task of +pathname lookup is to prevent them from having damaging effects. Many +of the possible races are seen most clearly in the context of the +"dcache" and an understanding of that is central to understanding +pathname lookup. + +More than just a cache. +----------------------- + +The "dcache" caches information about names in each filesystem to +make them quickly available for lookup. Each entry (known as a +"dentry") contains three significant fields: a component name, a +pointer to a parent dentry, and a pointer to the "inode" which +contains further information about the object in that parent with +the given name. The inode pointer can be `NULL` indicating that the +name doesn't exist in the parent. While there can be linkage in the +dentry of a directory to the dentries of the children, that linkage is +not used for pathname lookup, and so will not be considered here. + +The dcache has a number of uses apart from accelerating lookup. One +that will be particularly relevant is that it is closely integrated +with the mount table that records which filesystem is mounted where. +What the mount table actually stores is which dentry is mounted on top +of which other dentry. + +When considering the dcache, we have another of our "two types" +distinctions: there are two types of filesystems. + +Some filesystems ensure that the information in the dcache is always +completely accurate (though not necessarily complete). This can allow +the VFS to determine if a particular file does or doesn't exist +without checking with the filesystem, and means that the VFS can +protect the filesystem against certain races and other problems. +These are typically "local" filesystems such as ext3, XFS, and Btrfs. + +Other filesystems don't provide that guarantee because they cannot. +These are typically filesystems that are shared across a network, +whether remote filesystems like NFS and 9P, or cluster filesystems +like ocfs2 or cephfs. These filesystems allow the VFS to revalidate +cached information, and must provide their own protection against +awkward races. The VFS can detect these filesystems by the +`DCACHE_OP_REVALIDATE` flag being set in the dentry. + +REF-walk: simple concurrency management with refcounts and spinlocks +-------------------------------------------------------------------- + +With all of those divisions carefully classified, we can now start +looking at the actual process of walking along a path. In particular +we will start with the handling of the "everything else" part of a +pathname, and focus on the "REF-walk" approach to concurrency +management. This code is found in the `link_path_walk()` function, if +you ignore all the places that only run when "`LOOKUP_RCU`" +(indicating the use of RCU-walk) is set. + +[Meet the Lockers]: https://lwn.net/Articles/453685/ + +REF-walk is fairly heavy-handed with locks and reference counts. Not +as heavy-handed as in the old "big kernel lock" days, but certainly not +afraid of taking a lock when one is needed. It uses a variety of +different concurrency controls. A background understanding of the +various primitives is assumed, or can be gleaned from elsewhere such +as in [Meet the Lockers]. + +The locking mechanisms used by REF-walk include: + +### dentry->d_lockref ### + +This uses the lockref primitive to provide both a spinlock and a +reference count. The special-sauce of this primitive is that the +conceptual sequence "lock; inc_ref; unlock;" can often be performed +with a single atomic memory operation. + +Holding a reference on a dentry ensures that the dentry won't suddenly +be freed and used for something else, so the values in various fields +will behave as expected. It also protects the `->d_inode` reference +to the inode to some extent. + +The association between a dentry and its inode is fairly permanent. +For example, when a file is renamed, the dentry and inode move +together to the new location. When a file is created the dentry will +initially be negative (i.e. `d_inode` is `NULL`), and will be assigned +to the new inode as part of the act of creation. + +When a file is deleted, this can be reflected in the cache either by +setting `d_inode` to `NULL`, or by removing it from the hash table +(described shortly) used to look up the name in the parent directory. +If the dentry is still in use the second option is used as it is +perfectly legal to keep using an open file after it has been deleted +and having the dentry around helps. If the dentry is not otherwise in +use (i.e. if the refcount in `d_lockref` is one), only then will +`d_inode` be set to `NULL`. Doing it this way is more efficient for a +very common case. + +So as long as a counted reference is held to a dentry, a non-`NULL` `->d_inode` +value will never be changed. + +### dentry->d_lock ### + +`d_lock` is a synonym for the spinlock that is part of `d_lockref` above. +For our purposes, holding this lock protects against the dentry being +renamed or unlinked. In particular, its parent (`d_parent`), and its +name (`d_name`) cannot be changed, and it cannot be removed from the +dentry hash table. + +When looking for a name in a directory, REF-walk takes `d_lock` on +each candidate dentry that it finds in the hash table and then checks +that the parent and name are correct. So it doesn't lock the parent +while searching in the cache; it only locks children. + +When looking for the parent for a given name (to handle "`..`"), +REF-walk can take `d_lock` to get a stable reference to `d_parent`, +but it first tries a more lightweight approach. As seen in +`dget_parent()`, if a reference can be claimed on the parent, and if +subsequently `d_parent` can be seen to have not changed, then there is +no need to actually take the lock on the child. + +### rename_lock ### + +Looking up a given name in a given directory involves computing a hash +from the two values (the name and the dentry of the directory), +accessing that slot in a hash table, and searching the linked list +that is found there. + +When a dentry is renamed, the name and the parent dentry can both +change so the hash will almost certainly change too. This would move the +dentry to a different chain in the hash table. If a filename search +happened to be looking at a dentry that was moved in this way, +it might end up continuing the search down the wrong chain, +and so miss out on part of the correct chain. + +The name-lookup process (`d_lookup()`) does _not_ try to prevent this +from happening, but only to detect when it happens. +`rename_lock` is a seqlock that is updated whenever any dentry is +renamed. If `d_lookup` finds that a rename happened while it +unsuccessfully scanned a chain in the hash table, it simply tries +again. + +### inode->i_mutex ### + +`i_mutex` is a mutex that serializes all changes to a particular +directory. This ensures that, for example, an `unlink()` and a `rename()` +cannot both happen at the same time. It also keeps the directory +stable while the filesystem is asked to look up a name that is not +currently in the dcache. + +This has a complementary role to that of `d_lock`: `i_mutex` on a +directory protects all of the names in that directory, while `d_lock` +on a name protects just one name in a directory. Most changes to the +dcache hold `i_mutex` on the relevant directory inode and briefly take +`d_lock` on one or more the dentries while the change happens. One +exception is when idle dentries are removed from the dcache due to +memory pressure. This uses `d_lock`, but `i_mutex` plays no role. + +The mutex affects pathname lookup in two distinct ways. Firstly it +serializes lookup of a name in a directory. `walk_component()` uses +`lookup_fast()` first which, in turn, checks to see if the name is in the cache, +using only `d_lock` locking. If the name isn't found, then `walk_component()` +falls back to `lookup_slow()` which takes `i_mutex`, checks again that +the name isn't in the cache, and then calls in to the filesystem to get a +definitive answer. A new dentry will be added to the cache regardless of +the result. + +Secondly, when pathname lookup reaches the final component, it will +sometimes need to take `i_mutex` before performing the last lookup so +that the required exclusion can be achieved. How path lookup chooses +to take, or not take, `i_mutex` is one of the +issues addressed in a subsequent section. + +### mnt->mnt_count ### + +`mnt_count` is a per-CPU reference counter on "`mount`" structures. +Per-CPU here means that incrementing the count is cheap as it only +uses CPU-local memory, but checking if the count is zero is expensive as +it needs to check with every CPU. Taking a `mnt_count` reference +prevents the mount structure from disappearing as the result of regular +unmount operations, but does not prevent a "lazy" unmount. So holding +`mnt_count` doesn't ensure that the mount remains in the namespace and, +in particular, doesn't stabilize the link to the mounted-on dentry. It +does, however, ensure that the `mount` data structure remains coherent, +and it provides a reference to the root dentry of the mounted +filesystem. So a reference through `->mnt_count` provides a stable +reference to the mounted dentry, but not the mounted-on dentry. + +### mount_lock ### + +`mount_lock` is a global seqlock, a bit like `rename_lock`. It can be used to +check if any change has been made to any mount points. + +While walking down the tree (away from the root) this lock is used when +crossing a mount point to check that the crossing was safe. That is, +the value in the seqlock is read, then the code finds the mount that +is mounted on the current directory, if there is one, and increments +the `mnt_count`. Finally the value in `mount_lock` is checked against +the old value. If there is no change, then the crossing was safe. If there +was a change, the `mnt_count` is decremented and the whole process is +retried. + +When walking up the tree (towards the root) by following a ".." link, +a little more care is needed. In this case the seqlock (which +contains both a counter and a spinlock) is fully locked to prevent +any changes to any mount points while stepping up. This locking is +needed to stabilize the link to the mounted-on dentry, which the +refcount on the mount itself doesn't ensure. + +### RCU ### + +Finally the global (but extremely lightweight) RCU read lock is held +from time to time to ensure certain data structures don't get freed +unexpectedly. + +In particular it is held while scanning chains in the dcache hash +table, and the mount point hash table. + +Bringing it together with `struct nameidata` +-------------------------------------------- + +[First edition Unix]: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s + +Throughout the process of walking a path, the current status is stored +in a `struct nameidata`, "namei" being the traditional name - dating +all the way back to [First Edition Unix] - of the function that +converts a "name" to an "inode". `struct nameidata` contains (among +other fields): + +### `struct path path` ### + +A `path` contains a `struct vfsmount` (which is +embedded in a `struct mount`) and a `struct dentry`. Together these +record the current status of the walk. They start out referring to the +starting point (the current working directory, the root directory, or some other +directory identified by a file descriptor), and are updated on each +step. A reference through `d_lockref` and `mnt_count` is always +held. + +### `struct qstr last` ### + +This is a string together with a length (i.e. _not_ `nul` terminated) +that is the "next" component in the pathname. + +### `int last_type` ### + +This is one of `LAST_NORM`, `LAST_ROOT`, `LAST_DOT`, `LAST_DOTDOT`, or +`LAST_BIND`. The `last` field is only valid if the type is +`LAST_NORM`. `LAST_BIND` is used when following a symlink and no +components of the symlink have been processed yet. Others should be +fairly self-explanatory. + +### `struct path root` ### + +This is used to hold a reference to the effective root of the +filesystem. Often that reference won't be needed, so this field is +only assigned the first time it is used, or when a non-standard root +is requested. Keeping a reference in the `nameidata` ensures that +only one root is in effect for the entire path walk, even if it races +with a `chroot()` system call. + +The root is needed when either of two conditions holds: (1) either the +pathname or a symbolic link starts with a "'/'", or (2) a "`..`" +component is being handled, since "`..`" from the root must always stay +at the root. The value used is usually the current root directory of +the calling process. An alternate root can be provided as when +`sysctl()` calls `file_open_root()`, and when NFSv4 or Btrfs call +`mount_subtree()`. In each case a pathname is being looked up in a very +specific part of the filesystem, and the lookup must not be allowed to +escape that subtree. It works a bit like a local `chroot()`. + +Ignoring the handling of symbolic links, we can now describe the +"`link_path_walk()`" function, which handles the lookup of everything +except the final component as: + +> Given a path (`name`) and a nameidata structure (`nd`), check that the +> current directory has execute permission and then advance `name` +> over one component while updating `last_type` and `last`. If that +> was the final component, then return, otherwise call +> `walk_component()` and repeat from the top. + +`walk_component()` is even easier. If the component is `LAST_DOTS`, +it calls `handle_dots()` which does the necessary locking as already +described. If it finds a `LAST_NORM` component it first calls +"`lookup_fast()`" which only looks in the dcache, but will ask the +filesystem to revalidate the result if it is that sort of filesystem. +If that doesn't get a good result, it calls "`lookup_slow()`" which +takes the `i_mutex`, rechecks the cache, and then asks the filesystem +to find a definitive answer. Each of these will call +`follow_managed()` (as described below) to handle any mount points. + +In the absence of symbolic links, `walk_component()` creates a new +`struct path` containing a counted reference to the new dentry and a +reference to the new `vfsmount` which is only counted if it is +different from the previous `vfsmount`. It then calls +`path_to_nameidata()` to install the new `struct path` in the +`struct nameidata` and drop the unneeded references. + +This "hand-over-hand" sequencing of getting a reference to the new +dentry before dropping the reference to the previous dentry may +seem obvious, but is worth pointing out so that we will recognize its +analogue in the "RCU-walk" version. + +Handling the final component. +----------------------------- + +`link_path_walk()` only walks as far as setting `nd->last` and +`nd->last_type` to refer to the final component of the path. It does +not call `walk_component()` that last time. Handling that final +component remains for the caller to sort out. Those callers are +`path_lookupat()`, `path_parentat()`, `path_mountpoint()` and +`path_openat()` each of which handles the differing requirements of +different system calls. + +`path_parentat()` is clearly the simplest - it just wraps a little bit +of housekeeping around `link_path_walk()` and returns the parent +directory and final component to the caller. The caller will be either +aiming to create a name (via `filename_create()`) or remove or rename +a name (in which case `user_path_parent()` is used). They will use +`i_mutex` to exclude other changes while they validate and then +perform their operation. + +`path_lookupat()` is nearly as simple - it is used when an existing +object is wanted such as by `stat()` or `chmod()`. It essentially just +calls `walk_component()` on the final component through a call to +`lookup_last()`. `path_lookupat()` returns just the final dentry. + +`path_mountpoint()` handles the special case of unmounting which must +not try to revalidate the mounted filesystem. It effectively +contains, through a call to `mountpoint_last()`, an alternate +implementation of `lookup_slow()` which skips that step. This is +important when unmounting a filesystem that is inaccessible, such as +one provided by a dead NFS server. + +Finally `path_openat()` is used for the `open()` system call; it +contains, in support functions starting with "`do_last()`", all the +complexity needed to handle the different subtleties of O_CREAT (with +or without O_EXCL), final "`/`" characters, and trailing symbolic +links. We will revisit this in the final part of this series, which +focuses on those symbolic links. "`do_last()`" will sometimes, but +not always, take `i_mutex`, depending on what it finds. + +Each of these, or the functions which call them, need to be alert to +the possibility that the final component is not `LAST_NORM`. If the +goal of the lookup is to create something, then any value for +`last_type` other than `LAST_NORM` will result in an error. For +example if `path_parentat()` reports `LAST_DOTDOT`, then the caller +won't try to create that name. They also check for trailing slashes +by testing `last.name[last.len]`. If there is any character beyond +the final component, it must be a trailing slash. + +Revalidation and automounts +--------------------------- + +Apart from symbolic links, there are only two parts of the "REF-walk" +process not yet covered. One is the handling of stale cache entries +and the other is automounts. + +On filesystems that require it, the lookup routines will call the +`->d_revalidate()` dentry method to ensure that the cached information +is current. This will often confirm validity or update a few details +from a server. In some cases it may find that there has been change +further up the path and that something that was thought to be valid +previously isn't really. When this happens the lookup of the whole +path is aborted and retried with the "`LOOKUP_REVAL`" flag set. This +forces revalidation to be more thorough. We will see more details of +this retry process in the next article. + +Automount points are locations in the filesystem where an attempt to +lookup a name can trigger changes to how that lookup should be +handled, in particular by mounting a filesystem there. These are +covered in greater detail in autofs4.txt in the Linux documentation +tree, but a few notes specifically related to path lookup are in order +here. + +The Linux VFS has a concept of "managed" dentries which is reflected +in function names such as "`follow_managed()`". There are three +potentially interesting things about these dentries corresponding +to three different flags that might be set in `dentry->d_flags`: + +### `DCACHE_MANAGE_TRANSIT` ### + +If this flag has been set, then the filesystem has requested that the +`d_manage()` dentry operation be called before handling any possible +mount point. This can perform two particular services: + +It can block to avoid races. If an automount point is being +unmounted, the `d_manage()` function will usually wait for that +process to complete before letting the new lookup proceed and possibly +trigger a new automount. + +It can selectively allow only some processes to transit through a +mount point. When a server process is managing automounts, it may +need to access a directory without triggering normal automount +processing. That server process can identify itself to the `autofs` +filesystem, which will then give it a special pass through +`d_manage()` by returning `-EISDIR`. + +### `DCACHE_MOUNTED` ### + +This flag is set on every dentry that is mounted on. As Linux +supports multiple filesystem namespaces, it is possible that the +dentry may not be mounted on in *this* namespace, just in some +other. So this flag is seen as a hint, not a promise. + +If this flag is set, and `d_manage()` didn't return `-EISDIR`, +`lookup_mnt()` is called to examine the mount hash table (honoring the +`mount_lock` described earlier) and possibly return a new `vfsmount` +and a new `dentry` (both with counted references). + +### `DCACHE_NEED_AUTOMOUNT` ### + +If `d_manage()` allowed us to get this far, and `lookup_mnt()` didn't +find a mount point, then this flag causes the `d_automount()` dentry +operation to be called. + +The `d_automount()` operation can be arbitrarily complex and may +communicate with server processes etc. but it should ultimately either +report that there was an error, that there was nothing to mount, or +should provide an updated `struct path` with new `dentry` and `vfsmount`. + +In the latter case, `finish_automount()` will be called to safely +install the new mount point into the mount table. + +There is no new locking of import here and it is important that no +locks (only counted references) are held over this processing due to +the very real possibility of extended delays. +This will become more important next time when we examine RCU-walk +which is particularly sensitive to delays. + +RCU-walk - faster pathname lookup in Linux +========================================== + +RCU-walk is another algorithm for performing pathname lookup in Linux. +It is in many ways similar to REF-walk and the two share quite a bit +of code. The significant difference in RCU-walk is how it allows for +the possibility of concurrent access. + +We noted that REF-walk is complex because there are numerous details +and special cases. RCU-walk reduces this complexity by simply +refusing to handle a number of cases -- it instead falls back to +REF-walk. The difficulty with RCU-walk comes from a different +direction: unfamiliarity. The locking rules when depending on RCU are +quite different from traditional locking, so we will spend a little extra +time when we come to those. + +Clear demarcation of roles +-------------------------- + +The easiest way to manage concurrency is to forcibly stop any other +thread from changing the data structures that a given thread is +looking at. In cases where no other thread would even think of +changing the data and lots of different threads want to read at the +same time, this can be very costly. Even when using locks that permit +multiple concurrent readers, the simple act of updating the count of +the number of current readers can impose an unwanted cost. So the +goal when reading a shared data structure that no other process is +changing is to avoid writing anything to memory at all. Take no +locks, increment no counts, leave no footprints. + +The REF-walk mechanism already described certainly doesn't follow this +principle, but then it is really designed to work when there may well +be other threads modifying the data. RCU-walk, in contrast, is +designed for the common situation where there are lots of frequent +readers and only occasional writers. This may not be common in all +parts of the filesystem tree, but in many parts it will be. For the +other parts it is important that RCU-walk can quickly fall back to +using REF-walk. + +Pathname lookup always starts in RCU-walk mode but only remains there +as long as what it is looking for is in the cache and is stable. It +dances lightly down the cached filesystem image, leaving no footprints +and carefully watching where it is, to be sure it doesn't trip. If it +notices that something has changed or is changing, or if something +isn't in the cache, then it tries to stop gracefully and switch to +REF-walk. + +This stopping requires getting a counted reference on the current +`vfsmount` and `dentry`, and ensuring that these are still valid - +that a path walk with REF-walk would have found the same entries. +This is an invariant that RCU-walk must guarantee. It can only make +decisions, such as selecting the next step, that are decisions which +REF-walk could also have made if it were walking down the tree at the +same time. If the graceful stop succeeds, the rest of the path is +processed with the reliable, if slightly sluggish, REF-walk. If +RCU-walk finds it cannot stop gracefully, it simply gives up and +restarts from the top with REF-walk. + +This pattern of "try RCU-walk, if that fails try REF-walk" can be +clearly seen in functions like `filename_lookup()`, +`filename_parentat()`, `filename_mountpoint()`, +`do_filp_open()`, and `do_file_open_root()`. These five +correspond roughly to the four `path_`* functions we met earlier, +each of which calls `link_path_walk()`. The `path_*` functions are +called using different mode flags until a mode is found which works. +They are first called with `LOOKUP_RCU` set to request "RCU-walk". If +that fails with the error `ECHILD` they are called again with no +special flag to request "REF-walk". If either of those report the +error `ESTALE` a final attempt is made with `LOOKUP_REVAL` set (and no +`LOOKUP_RCU`) to ensure that entries found in the cache are forcibly +revalidated - normally entries are only revalidated if the filesystem +determines that they are too old to trust. + +The `LOOKUP_RCU` attempt may drop that flag internally and switch to +REF-walk, but will never then try to switch back to RCU-walk. Places +that trip up RCU-walk are much more likely to be near the leaves and +so it is very unlikely that there will be much, if any, benefit from +switching back. + +RCU and seqlocks: fast and light +-------------------------------- + +RCU is, unsurprisingly, critical to RCU-walk mode. The +`rcu_read_lock()` is held for the entire time that RCU-walk is walking +down a path. The particular guarantee it provides is that the key +data structures - dentries, inodes, super_blocks, and mounts - will +not be freed while the lock is held. They might be unlinked or +invalidated in one way or another, but the memory will not be +repurposed so values in various fields will still be meaningful. This +is the only guarantee that RCU provides; everything else is done using +seqlocks. + +As we saw above, REF-walk holds a counted reference to the current +dentry and the current vfsmount, and does not release those references +before taking references to the "next" dentry or vfsmount. It also +sometimes takes the `d_lock` spinlock. These references and locks are +taken to prevent certain changes from happening. RCU-walk must not +take those references or locks and so cannot prevent such changes. +Instead, it checks to see if a change has been made, and aborts or +retries if it has. + +To preserve the invariant mentioned above (that RCU-walk may only make +decisions that REF-walk could have made), it must make the checks at +or near the same places that REF-walk holds the references. So, when +REF-walk increments a reference count or takes a spinlock, RCU-walk +samples the status of a seqlock using `read_seqcount_begin()` or a +similar function. When REF-walk decrements the count or drops the +lock, RCU-walk checks if the sampled status is still valid using +`read_seqcount_retry()` or similar. + +However, there is a little bit more to seqlocks than that. If +RCU-walk accesses two different fields in a seqlock-protected +structure, or accesses the same field twice, there is no a priori +guarantee of any consistency between those accesses. When consistency +is needed - which it usually is - RCU-walk must take a copy and then +use `read_seqcount_retry()` to validate that copy. + +`read_seqcount_retry()` not only checks the sequence number, but also +imposes a memory barrier so that no memory-read instruction from +*before* the call can be delayed until *after* the call, either by the +CPU or by the compiler. A simple example of this can be seen in +`slow_dentry_cmp()` which, for filesystems which do not use simple +byte-wise name equality, calls into the filesystem to compare a name +against a dentry. The length and name pointer are copied into local +variables, then `read_seqcount_retry()` is called to confirm the two +are consistent, and only then is `->d_compare()` called. When +standard filename comparison is used, `dentry_cmp()` is called +instead. Notably it does _not_ use `read_seqcount_retry()`, but +instead has a large comment explaining why the consistency guarantee +isn't necessary. A subsequent `read_seqcount_retry()` will be +sufficient to catch any problem that could occur at this point. + +With that little refresher on seqlocks out of the way we can look at +the bigger picture of how RCU-walk uses seqlocks. + +### `mount_lock` and `nd->m_seq` ### + +We already met the `mount_lock` seqlock when REF-walk used it to +ensure that crossing a mount point is performed safely. RCU-walk uses +it for that too, but for quite a bit more. + +Instead of taking a counted reference to each `vfsmount` as it +descends the tree, RCU-walk samples the state of `mount_lock` at the +start of the walk and stores this initial sequence number in the +`struct nameidata` in the `m_seq` field. This one lock and one +sequence number are used to validate all accesses to all `vfsmounts`, +and all mount point crossings. As changes to the mount table are +relatively rare, it is reasonable to fall back on REF-walk any time +that any "mount" or "unmount" happens. + +`m_seq` is checked (using `read_seqretry()`) at the end of an RCU-walk +sequence, whether switching to REF-walk for the rest of the path or +when the end of the path is reached. It is also checked when stepping +down over a mount point (in `__follow_mount_rcu()`) or up (in +`follow_dotdot_rcu()`). If it is ever found to have changed, the +whole RCU-walk sequence is aborted and the path is processed again by +REF-walk. + +If RCU-walk finds that `mount_lock` hasn't changed then it can be sure +that, had REF-walk taken counted references on each vfsmount, the +results would have been the same. This ensures the invariant holds, +at least for vfsmount structures. + +### `dentry->d_seq` and `nd->seq`. ### + +In place of taking a count or lock on `d_reflock`, RCU-walk samples +the per-dentry `d_seq` seqlock, and stores the sequence number in the +`seq` field of the nameidata structure, so `nd->seq` should always be +the current sequence number of `nd->dentry`. This number needs to be +revalidated after copying, and before using, the name, parent, or +inode of the dentry. + +The handling of the name we have already looked at, and the parent is +only accessed in `follow_dotdot_rcu()` which fairly trivially follows +the required pattern, though it does so for three different cases. + +When not at a mount point, `d_parent` is followed and its `d_seq` is +collected. When we are at a mount point, we instead follow the +`mnt->mnt_mountpoint` link to get a new dentry and collect its +`d_seq`. Then, after finally finding a `d_parent` to follow, we must +check if we have landed on a mount point and, if so, must find that +mount point and follow the `mnt->mnt_root` link. This would imply a +somewhat unusual, but certainly possible, circumstance where the +starting point of the path lookup was in part of the filesystem that +was mounted on, and so not visible from the root. + +The inode pointer, stored in `->d_inode`, is a little more +interesting. The inode will always need to be accessed at least +twice, once to determine if it is NULL and once to verify access +permissions. Symlink handling requires a validated inode pointer too. +Rather than revalidating on each access, a copy is made on the first +access and it is stored in the `inode` field of `nameidata` from where +it can be safely accessed without further validation. + +`lookup_fast()` is the only lookup routine that is used in RCU-mode, +`lookup_slow()` being too slow and requiring locks. It is in +`lookup_fast()` that we find the important "hand over hand" tracking +of the current dentry. + +The current `dentry` and current `seq` number are passed to +`__d_lookup_rcu()` which, on success, returns a new `dentry` and a +new `seq` number. `lookup_fast()` then copies the inode pointer and +revalidates the new `seq` number. It then validates the old `dentry` +with the old `seq` number one last time and only then continues. This +process of getting the `seq` number of the new dentry and then +checking the `seq` number of the old exactly mirrors the process of +getting a counted reference to the new dentry before dropping that for +the old dentry which we saw in REF-walk. + +### No `inode->i_mutex` or even `rename_lock` ### + +A mutex is a fairly heavyweight lock that can only be taken when it is +permissible to sleep. As `rcu_read_lock()` forbids sleeping, +`inode->i_mutex` plays no role in RCU-walk. If some other thread does +take `i_mutex` and modifies the directory in a way that RCU-walk needs +to notice, the result will be either that RCU-walk fails to find the +dentry that it is looking for, or it will find a dentry which +`read_seqretry()` won't validate. In either case it will drop down to +REF-walk mode which can take whatever locks are needed. + +Though `rename_lock` could be used by RCU-walk as it doesn't require +any sleeping, RCU-walk doesn't bother. REF-walk uses `rename_lock` to +protect against the possibility of hash chains in the dcache changing +while they are being searched. This can result in failing to find +something that actually is there. When RCU-walk fails to find +something in the dentry cache, whether it is really there or not, it +already drops down to REF-walk and tries again with appropriate +locking. This neatly handles all cases, so adding extra checks on +rename_lock would bring no significant value. + +`unlazy walk()` and `complete_walk()` +------------------------------------- + +That "dropping down to REF-walk" typically involves a call to +`unlazy_walk()`, so named because "RCU-walk" is also sometimes +referred to as "lazy walk". `unlazy_walk()` is called when +following the path down to the current vfsmount/dentry pair seems to +have proceeded successfully, but the next step is problematic. This +can happen if the next name cannot be found in the dcache, if +permission checking or name revalidation couldn't be achieved while +the `rcu_read_lock()` is held (which forbids sleeping), if an +automount point is found, or in a couple of cases involving symlinks. +It is also called from `complete_walk()` when the lookup has reached +the final component, or the very end of the path, depending on which +particular flavor of lookup is used. + +Other reasons for dropping out of RCU-walk that do not trigger a call +to `unlazy_walk()` are when some inconsistency is found that cannot be +handled immediately, such as `mount_lock` or one of the `d_seq` +seqlocks reporting a change. In these cases the relevant function +will return `-ECHILD` which will percolate up until it triggers a new +attempt from the top using REF-walk. + +For those cases where `unlazy_walk()` is an option, it essentially +takes a reference on each of the pointers that it holds (vfsmount, +dentry, and possibly some symbolic links) and then verifies that the +relevant seqlocks have not been changed. If there have been changes, +it, too, aborts with `-ECHILD`, otherwise the transition to REF-walk +has been a success and the lookup process continues. + +Taking a reference on those pointers is not quite as simple as just +incrementing a counter. That works to take a second reference if you +already have one (often indirectly through another object), but it +isn't sufficient if you don't actually have a counted reference at +all. For `dentry->d_lockref`, it is safe to increment the reference +counter to get a reference unless it has been explicitly marked as +"dead" which involves setting the counter to `-128`. +`lockref_get_not_dead()` achieves this. + +For `mnt->mnt_count` it is safe to take a reference as long as +`mount_lock` is then used to validate the reference. If that +validation fails, it may *not* be safe to just drop that reference in +the standard way of calling `mnt_put()` - an unmount may have +progressed too far. So the code in `legitimize_mnt()`, when it +finds that the reference it got might not be safe, checks the +`MNT_SYNC_UMOUNT` flag to determine if a simple `mnt_put()` is +correct, or if it should just decrement the count and pretend none of +this ever happened. + +Taking care in filesystems +--------------------------- + +RCU-walk depends almost entirely on cached information and often will +not call into the filesystem at all. However there are two places, +besides the already-mentioned component-name comparison, where the +file system might be included in RCU-walk, and it must know to be +careful. + +If the filesystem has non-standard permission-checking requirements - +such as a networked filesystem which may need to check with the server +- the `i_op->permission` interface might be called during RCU-walk. +In this case an extra "`MAY_NOT_BLOCK`" flag is passed so that it +knows not to sleep, but to return `-ECHILD` if it cannot complete +promptly. `i_op->permission` is given the inode pointer, not the +dentry, so it doesn't need to worry about further consistency checks. +However if it accesses any other filesystem data structures, it must +ensure they are safe to be accessed with only the `rcu_read_lock()` +held. This typically means they must be freed using `kfree_rcu()` or +similar. + +[`READ_ONCE()`]: https://lwn.net/Articles/624126/ + +If the filesystem may need to revalidate dcache entries, then +`d_op->d_revalidate` may be called in RCU-walk too. This interface +*is* passed the dentry but does not have access to the `inode` or the +`seq` number from the `nameidata`, so it needs to be extra careful +when accessing fields in the dentry. This "extra care" typically +involves using `ACCESS_ONCE()` or the newer [`READ_ONCE()`] to access +fields, and verifying the result is not NULL before using it. This +pattern can be see in `nfs_lookup_revalidate()`. + +A pair of patterns +------------------ + +In various places in the details of REF-walk and RCU-walk, and also in +the big picture, there are a couple of related patterns that are worth +being aware of. + +The first is "try quickly and check, if that fails try slowly". We +can see that in the high-level approach of first trying RCU-walk and +then trying REF-walk, and in places where `unlazy_walk()` is used to +switch to REF-walk for the rest of the path. We also saw it earlier +in `dget_parent()` when following a "`..`" link. It tries a quick way +to get a reference, then falls back to taking locks if needed. + +The second pattern is "try quickly and check, if that fails try +again - repeatedly". This is seen with the use of `rename_lock` and +`mount_lock` in REF-walk. RCU-walk doesn't make use of this pattern - +if anything goes wrong it is much safer to just abort and try a more +sedate approach. + +The emphasis here is "try quickly and check". It should probably be +"try quickly _and carefully,_ then check". The fact that checking is +needed is a reminder that the system is dynamic and only a limited +number of things are safe at all. The most likely cause of errors in +this whole process is assuming something is safe when in reality it +isn't. Careful consideration of what exactly guarantees the safety of +each access is sometimes necessary. + +A walk among the symlinks +========================= + +There are several basic issues that we will examine to understand the +handling of symbolic links: the symlink stack, together with cache +lifetimes, will help us understand the overall recursive handling of +symlinks and lead to the special care needed for the final component. +Then a consideration of access-time updates and summary of the various +flags controlling lookup will finish the story. + +The symlink stack +----------------- + +There are only two sorts of filesystem objects that can usefully +appear in a path prior to the final component: directories and symlinks. +Handling directories is quite straightforward: the new directory +simply becomes the starting point at which to interpret the next +component on the path. Handling symbolic links requires a bit more +work. + +Conceptually, symbolic links could be handled by editing the path. If +a component name refers to a symbolic link, then that component is +replaced by the body of the link and, if that body starts with a '/', +then all preceding parts of the path are discarded. This is what the +"`readlink -f`" command does, though it also edits out "`.`" and +"`..`" components. + +Directly editing the path string is not really necessary when looking +up a path, and discarding early components is pointless as they aren't +looked at anyway. Keeping track of all remaining components is +important, but they can of course be kept separately; there is no need +to concatenate them. As one symlink may easily refer to another, +which in turn can refer to a third, we may need to keep the remaining +components of several paths, each to be processed when the preceding +ones are completed. These path remnants are kept on a stack of +limited size. + +There are two reasons for placing limits on how many symlinks can +occur in a single path lookup. The most obvious is to avoid loops. +If a symlink referred to itself either directly or through +intermediaries, then following the symlink can never complete +successfully - the error `ELOOP` must be returned. Loops can be +detected without imposing limits, but limits are the simplest solution +and, given the second reason for restriction, quite sufficient. + +[outlined recently]: http://thread.gmane.org/gmane.linux.kernel/1934390/focus=1934550 + +The second reason was [outlined recently] by Linus: + +> Because it's a latency and DoS issue too. We need to react well to +> true loops, but also to "very deep" non-loops. It's not about memory +> use, it's about users triggering unreasonable CPU resources. + +Linux imposes a limit on the length of any pathname: `PATH_MAX`, which +is 4096. There are a number of reasons for this limit; not letting the +kernel spend too much time on just one path is one of them. With +symbolic links you can effectively generate much longer paths so some +sort of limit is needed for the same reason. Linux imposes a limit of +at most 40 symlinks in any one path lookup. It previously imposed a +further limit of eight on the maximum depth of recursion, but that was +raised to 40 when a separate stack was implemented, so there is now +just the one limit. + +The `nameidata` structure that we met in an earlier article contains a +small stack that can be used to store the remaining part of up to two +symlinks. In many cases this will be sufficient. If it isn't, a +separate stack is allocated with room for 40 symlinks. Pathname +lookup will never exceed that stack as, once the 40th symlink is +detected, an error is returned. + +It might seem that the name remnants are all that needs to be stored on +this stack, but we need a bit more. To see that, we need to move on to +cache lifetimes. + +Storage and lifetime of cached symlinks +--------------------------------------- + +Like other filesystem resources, such as inodes and directory +entries, symlinks are cached by Linux to avoid repeated costly access +to external storage. It is particularly important for RCU-walk to be +able to find and temporarily hold onto these cached entries, so that +it doesn't need to drop down into REF-walk. + +[object-oriented design pattern]: https://lwn.net/Articles/446317/ + +While each filesystem is free to make its own choice, symlinks are +typically stored in one of two places. Short symlinks are often +stored directly in the inode. When a filesystem allocates a `struct +inode` it typically allocates extra space to store private data (a +common [object-oriented design pattern] in the kernel). This will +sometimes include space for a symlink. The other common location is +in the page cache, which normally stores the content of files. The +pathname in a symlink can be seen as the content of that symlink and +can easily be stored in the page cache just like file content. + +When neither of these is suitable, the next most likely scenario is +that the filesystem will allocate some temporary memory and copy or +construct the symlink content into that memory whenever it is needed. + +When the symlink is stored in the inode, it has the same lifetime as +the inode which, itself, is protected by RCU or by a counted reference +on the dentry. This means that the mechanisms that pathname lookup +uses to access the dcache and icache (inode cache) safely are quite +sufficient for accessing some cached symlinks safely. In these cases, +the `i_link` pointer in the inode is set to point to wherever the +symlink is stored and it can be accessed directly whenever needed. + +When the symlink is stored in the page cache or elsewhere, the +situation is not so straightforward. A reference on a dentry or even +on an inode does not imply any reference on cached pages of that +inode, and even an `rcu_read_lock()` is not sufficient to ensure that +a page will not disappear. So for these symlinks the pathname lookup +code needs to ask the filesystem to provide a stable reference and, +significantly, needs to release that reference when it is finished +with it. + +Taking a reference to a cache page is often possible even in RCU-walk +mode. It does require making changes to memory, which is best avoided, +but that isn't necessarily a big cost and it is better than dropping +out of RCU-walk mode completely. Even filesystems that allocate +space to copy the symlink into can use `GFP_ATOMIC` to often successfully +allocate memory without the need to drop out of RCU-walk. If a +filesystem cannot successfully get a reference in RCU-walk mode, it +must return `-ECHILD` and `unlazy_walk()` will be called to return to +REF-walk mode in which the filesystem is allowed to sleep. + +The place for all this to happen is the `i_op->follow_link()` inode +method. In the present mainline code this is never actually called in +RCU-walk mode as the rewrite is not quite complete. It is likely that +in a future release this method will be passed an `inode` pointer when +called in RCU-walk mode so it both (1) knows to be careful, and (2) has the +validated pointer. Much like the `i_op->permission()` method we +looked at previously, `->follow_link()` would need to be careful that +all the data structures it references are safe to be accessed while +holding no counted reference, only the RCU lock. Though getting a +reference with `->follow_link()` is not yet done in RCU-walk mode, the +code is ready to release the reference when that does happen. + +This need to drop the reference to a symlink adds significant +complexity. It requires a reference to the inode so that the +`i_op->put_link()` inode operation can be called. In REF-walk, that +reference is kept implicitly through a reference to the dentry, so +keeping the `struct path` of the symlink is easiest. For RCU-walk, +the pointer to the inode is kept separately. To allow switching from +RCU-walk back to REF-walk in the middle of processing nested symlinks +we also need the seq number for the dentry so we can confirm that +switching back was safe. + +Finally, when providing a reference to a symlink, the filesystem also +provides an opaque "cookie" that must be passed to `->put_link()` so that it +knows what to free. This might be the allocated memory area, or a +pointer to the `struct page` in the page cache, or something else +completely. Only the filesystem knows what it is. + +In order for the reference to each symlink to be dropped when the walk completes, +whether in RCU-walk or REF-walk, the symlink stack needs to contain, +along with the path remnants: + +- the `struct path` to provide a reference to the inode in REF-walk +- the `struct inode *` to provide a reference to the inode in RCU-walk +- the `seq` to allow the path to be safely switched from RCU-walk to REF-walk +- the `cookie` that tells `->put_path()` what to put. + +This means that each entry in the symlink stack needs to hold five +pointers and an integer instead of just one pointer (the path +remnant). On a 64-bit system, this is about 40 bytes per entry; +with 40 entries it adds up to 1600 bytes total, which is less than +half a page. So it might seem like a lot, but is by no means +excessive. + +Note that, in a given stack frame, the path remnant (`name`) is not +part of the symlink that the other fields refer to. It is the remnant +to be followed once that symlink has been fully parsed. + +Following the symlink +--------------------- + +The main loop in `link_path_walk()` iterates seamlessly over all +components in the path and all of the non-final symlinks. As symlinks +are processed, the `name` pointer is adjusted to point to a new +symlink, or is restored from the stack, so that much of the loop +doesn't need to notice. Getting this `name` variable on and off the +stack is very straightforward; pushing and popping the references is +a little more complex. + +When a symlink is found, `walk_component()` returns the value `1` +(`0` is returned for any other sort of success, and a negative number +is, as usual, an error indicator). This causes `get_link()` to be +called; it then gets the link from the filesystem. Providing that +operation is successful, the old path `name` is placed on the stack, +and the new value is used as the `name` for a while. When the end of +the path is found (i.e. `*name` is `'\0'`) the old `name` is restored +off the stack and path walking continues. + +Pushing and popping the reference pointers (inode, cookie, etc.) is more +complex in part because of the desire to handle tail recursion. When +the last component of a symlink itself points to a symlink, we +want to pop the symlink-just-completed off the stack before pushing +the symlink-just-found to avoid leaving empty path remnants that would +just get in the way. + +It is most convenient to push the new symlink references onto the +stack in `walk_component()` immediately when the symlink is found; +`walk_component()` is also the last piece of code that needs to look at the +old symlink as it walks that last component. So it is quite +convenient for `walk_component()` to release the old symlink and pop +the references just before pushing the reference information for the +new symlink. It is guided in this by two flags; `WALK_GET`, which +gives it permission to follow a symlink if it finds one, and +`WALK_PUT`, which tells it to release the current symlink after it has been +followed. `WALK_PUT` is tested first, leading to a call to +`put_link()`. `WALK_GET` is tested subsequently (by +`should_follow_link()`) leading to a call to `pick_link()` which sets +up the stack frame. + +### Symlinks with no final component ### + +A pair of special-case symlinks deserve a little further explanation. +Both result in a new `struct path` (with mount and dentry) being set +up in the `nameidata`, and result in `get_link()` returning `NULL`. + +The more obvious case is a symlink to "`/`". All symlinks starting +with "`/`" are detected in `get_link()` which resets the `nameidata` +to point to the effective filesystem root. If the symlink only +contains "`/`" then there is nothing more to do, no components at all, +so `NULL` is returned to indicate that the symlink can be released and +the stack frame discarded. + +The other case involves things in `/proc` that look like symlinks but +aren't really. + +> $ ls -l /proc/self/fd/1 +> lrwx------ 1 neilb neilb 64 Jun 13 10:19 /proc/self/fd/1 -> /dev/pts/4 + +Every open file descriptor in any process is represented in `/proc` by +something that looks like a symlink. It is really a reference to the +target file, not just the name of it. When you `readlink` these +objects you get a name that might refer to the same file - unless it +has been unlinked or mounted over. When `walk_component()` follows +one of these, the `->follow_link()` method in "procfs" doesn't return +a string name, but instead calls `nd_jump_link()` which updates the +`nameidata` in place to point to that target. `->follow_link()` then +returns `NULL`. Again there is no final component and `get_link()` +reports this by leaving the `last_type` field of `nameidata` as +`LAST_BIND`. + +Following the symlink in the final component +-------------------------------------------- + +All this leads to `link_path_walk()` walking down every component, and +following all symbolic links it finds, until it reaches the final +component. This is just returned in the `last` field of `nameidata`. +For some callers, this is all they need; they want to create that +`last` name if it doesn't exist or give an error if it does. Other +callers will want to follow a symlink if one is found, and possibly +apply special handling to the last component of that symlink, rather +than just the last component of the original file name. These callers +potentially need to call `link_path_walk()` again and again on +successive symlinks until one is found that doesn't point to another +symlink. + +This case is handled by the relevant caller of `link_path_walk()`, such as +`path_lookupat()` using a loop that calls `link_path_walk()`, and then +handles the final component. If the final component is a symlink +that needs to be followed, then `trailing_symlink()` is called to set +things up properly and the loop repeats, calling `link_path_walk()` +again. This could loop as many as 40 times if the last component of +each symlink is another symlink. + +The various functions that examine the final component and possibly +report that it is a symlink are `lookup_last()`, `mountpoint_last()` +and `do_last()`, each of which use the same convention as +`walk_component()` of returning `1` if a symlink was found that needs +to be followed. + +Of these, `do_last()` is the most interesting as it is used for +opening a file. Part of `do_last()` runs with `i_mutex` held and this +part is in a separate function: `lookup_open()`. + +Explaining `do_last()` completely is beyond the scope of this article, +but a few highlights should help those interested in exploring the +code. + +1. Rather than just finding the target file, `do_last()` needs to open + it. If the file was found in the dcache, then `vfs_open()` is used for + this. If not, then `lookup_open()` will either call `atomic_open()` (if + the filesystem provides it) to combine the final lookup with the open, or + will perform the separate `lookup_real()` and `vfs_create()` steps + directly. In the later case the actual "open" of this newly found or + created file will be performed by `vfs_open()`, just as if the name + were found in the dcache. + +2. `vfs_open()` can fail with `-EOPENSTALE` if the cached information + wasn't quite current enough. Rather than restarting the lookup from + the top with `LOOKUP_REVAL` set, `lookup_open()` is called instead, + giving the filesystem a chance to resolve small inconsistencies. + If that doesn't work, only then is the lookup restarted from the top. + +3. An open with O_CREAT **does** follow a symlink in the final component, + unlike other creation system calls (like `mkdir`). So the sequence: + + > ln -s bar /tmp/foo + > echo hello > /tmp/foo + + will create a file called `/tmp/bar`. This is not permitted if + `O_EXCL` is set but otherwise is handled for an O_CREAT open much + like for a non-creating open: `should_follow_link()` returns `1`, and + so does `do_last()` so that `trailing_symlink()` gets called and the + open process continues on the symlink that was found. + +Updating the access time +------------------------ + +We previously said of RCU-walk that it would "take no locks, increment +no counts, leave no footprints." We have since seen that some +"footprints" can be needed when handling symlinks as a counted +reference (or even a memory allocation) may be needed. But these +footprints are best kept to a minimum. + +One other place where walking down a symlink can involve leaving +footprints in a way that doesn't affect directories is in updating access times. +In Unix (and Linux) every filesystem object has a "last accessed +time", or "`atime`". Passing through a directory to access a file +within is not considered to be an access for the purposes of +`atime`; only listing the contents of a directory can update its `atime`. +Symlinks are different it seems. Both reading a symlink (with `readlink()`) +and looking up a symlink on the way to some other destination can +update the atime on that symlink. + +[clearest statement]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 + +It is not clear why this is the case; POSIX has little to say on the +subject. The [clearest statement] is that, if a particular implementation +updates a timestamp in a place not specified by POSIX, this must be +documented "except that any changes caused by pathname resolution need +not be documented". This seems to imply that POSIX doesn't really +care about access-time updates during pathname lookup. + +[Linux 1.3.87]: https://git.kernel.org/cgit/linux/kernel/git/history/history.git/diff/fs/ext2/symlink.c?id=f806c6db77b8eaa6e00dcfb6b567706feae8dbb8 + +An examination of history shows that prior to [Linux 1.3.87], the ext2 +filesystem, at least, didn't update atime when following a link. +Unfortunately we have no record of why that behavior was changed. + +In any case, access time must now be updated and that operation can be +quite complex. Trying to stay in RCU-walk while doing it is best +avoided. Fortunately it is often permitted to skip the `atime` +update. Because `atime` updates cause performance problems in various +areas, Linux supports the `relatime` mount option, which generally +limits the updates of `atime` to once per day on files that aren't +being changed (and symlinks never change once created). Even without +`relatime`, many filesystems record `atime` with a one-second +granularity, so only one update per second is required. + +It is easy to test if an `atime` update is needed while in RCU-walk +mode and, if it isn't, the update can be skipped and RCU-walk mode +continues. Only when an `atime` update is actually required does the +path walk drop down to REF-walk. All of this is handled in the +`get_link()` function. + +A few flags +----------- + +A suitable way to wrap up this tour of pathname walking is to list +the various flags that can be stored in the `nameidata` to guide the +lookup process. Many of these are only meaningful on the final +component, others reflect the current state of the pathname lookup. +And then there is `LOOKUP_EMPTY`, which doesn't fit conceptually with +the others. If this is not set, an empty pathname causes an error +very early on. If it is set, empty pathnames are not considered to be +an error. + +### Global state flags ### + +We have already met two global state flags: `LOOKUP_RCU` and +`LOOKUP_REVAL`. These select between one of three overall approaches +to lookup: RCU-walk, REF-walk, and REF-walk with forced revalidation. + +`LOOKUP_PARENT` indicates that the final component hasn't been reached +yet. This is primarily used to tell the audit subsystem the full +context of a particular access being audited. + +`LOOKUP_ROOT` indicates that the `root` field in the `nameidata` was +provided by the caller, so it shouldn't be released when it is no +longer needed. + +`LOOKUP_JUMPED` means that the current dentry was chosen not because +it had the right name but for some other reason. This happens when +following "`..`", following a symlink to `/`, crossing a mount point +or accessing a "`/proc/$PID/fd/$FD`" symlink. In this case the +filesystem has not been asked to revalidate the name (with +`d_revalidate()`). In such cases the inode may still need to be +revalidated, so `d_op->d_weak_revalidate()` is called if +`LOOKUP_JUMPED` is set when the look completes - which may be at the +final component or, when creating, unlinking, or renaming, at the penultimate component. + +### Final-component flags ### + +Some of these flags are only set when the final component is being +considered. Others are only checked for when considering that final +component. + +`LOOKUP_AUTOMOUNT` ensures that, if the final component is an automount +point, then the mount is triggered. Some operations would trigger it +anyway, but operations like `stat()` deliberately don't. `statfs()` +needs to trigger the mount but otherwise behaves a lot like `stat()`, so +it sets `LOOKUP_AUTOMOUNT`, as does "`quotactl()`" and the handling of +"`mount --bind`". + +`LOOKUP_FOLLOW` has a similar function to `LOOKUP_AUTOMOUNT` but for +symlinks. Some system calls set or clear it implicitly, while +others have API flags such as `AT_SYMLINK_FOLLOW` and +`UMOUNT_NOFOLLOW` to control it. Its effect is similar to +`WALK_GET` that we already met, but it is used in a different way. + +`LOOKUP_DIRECTORY` insists that the final component is a directory. +Various callers set this and it is also set when the final component +is found to be followed by a slash. + +Finally `LOOKUP_OPEN`, `LOOKUP_CREATE`, `LOOKUP_EXCL`, and +`LOOKUP_RENAME_TARGET` are not used directly by the VFS but are made +available to the filesystem and particularly the `->d_revalidate()` +method. A filesystem can choose not to bother revalidating too hard +if it knows that it will be asked to open or create the file soon. +These flags were previously useful for `->lookup()` too but with the +introduction of `->atomic_open()` they are less relevant there. + +End of the road +--------------- + +Despite its complexity, all this pathname lookup code appears to be +in good shape - various parts are certainly easier to understand now +than even a couple of releases ago. But that doesn't mean it is +"finished". As already mentioned, RCU-walk currently only follows +symlinks that are stored in the inode so, while it handles many ext4 +symlinks, it doesn't help with NFS, XFS, or Btrfs. That support +is not likely to be long delayed. diff --git a/Documentation/filesystems/path-lookup.txt b/Documentation/filesystems/path-lookup.txt index 3571667c7105..9b8930f589d9 100644 --- a/Documentation/filesystems/path-lookup.txt +++ b/Documentation/filesystems/path-lookup.txt @@ -379,4 +379,4 @@ Papers and other documentation on dcache locking 2. http://lse.sourceforge.net/locking/dcache/dcache.html - +3. path-lookup.md in this directory. diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index f24d1b833957..f1b87d8aa2da 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -504,3 +504,24 @@ in your dentry operations instead. [mandatory] __fd_install() & fd_install() can now sleep. Callers should not hold a spinlock or other resources that do not allow a schedule. +-- +[mandatory] + any symlink that might use page_follow_link_light/page_put_link() must + have inode_nohighmem(inode) called before anything might start playing with + its pagecache. No highmem pages should end up in the pagecache of such + symlinks. That includes any preseeding that might be done during symlink + creation. __page_symlink() will honour the mapping gfp flags, so once + you've done inode_nohighmem() it's safe to use, but if you allocate and + insert the page manually, make sure to use the right gfp flags. +-- +[mandatory] + ->follow_link() is replaced with ->get_link(); same API, except that + * ->get_link() gets inode as a separate argument + * ->get_link() may be called in RCU mode - in that case NULL + dentry is passed +-- +[mandatory] + ->get_link() gets struct delayed_call *done now, and should do + set_delayed_call() where it used to set *cookie. + ->put_link() is gone - just give the destructor to set_delayed_call() + in ->get_link(). diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index d411ca63c8b6..7f5607a089b4 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -43,6 +43,7 @@ Table of Contents 3.7 /proc/<pid>/task/<tid>/children - Information about task children 3.8 /proc/<pid>/fdinfo/<fd> - Information about opened file 3.9 /proc/<pid>/map_files - Information about memory mapped files + 3.10 /proc/<pid>/timerslack_ns - Task timerslack value 4 Configuring procfs 4.1 Mount options @@ -140,7 +141,8 @@ Table 1-1: Process specific entries in /proc stat Process status statm Process memory status information status Process status in human readable form - wchan If CONFIG_KALLSYMS is set, a pre-decoded wchan + wchan Present with CONFIG_KALLSYMS=y: it shows the kernel function + symbol the task is blocked in - or "0" if not blocked. pagemap Page table stack Report full stack trace, enable via CONFIG_STACKTRACE smaps a extension based on maps, showing the memory consumption of @@ -168,12 +170,16 @@ read the file /proc/PID/status: VmLck: 0 kB VmHWM: 476 kB VmRSS: 476 kB + RssAnon: 352 kB + RssFile: 120 kB + RssShmem: 4 kB VmData: 156 kB VmStk: 88 kB VmExe: 68 kB VmLib: 1412 kB VmPTE: 20 kb VmSwap: 0 kB + HugetlbPages: 0 kB Threads: 1 SigQ: 0/28578 SigPnd: 0000000000000000 @@ -229,14 +235,21 @@ Table 1-2: Contents of the status files (as of 4.1) VmSize total program size VmLck locked memory size VmHWM peak resident set size ("high water mark") - VmRSS size of memory portions - VmData size of data, stack, and text segments - VmStk size of data, stack, and text segments + VmRSS size of memory portions. It contains the three + following parts (VmRSS = RssAnon + RssFile + RssShmem) + RssAnon size of resident anonymous memory + RssFile size of resident file mappings + RssShmem size of resident shmem memory (includes SysV shm, + mapping of tmpfs and shared anonymous mappings) + VmData size of private data segments + VmStk size of stack segments VmExe size of text segment VmLib size of shared library code VmPTE size of page table entries VmPMD size of second level page tables - VmSwap size of swap usage (the number of referred swapents) + VmSwap amount of swap used by anonymous private data + (shmem swap usage is not included) + HugetlbPages size of hugetlb memory portions Threads number of threads SigQ number of signals queued/max. number for queue SigPnd bitmap of pending signals for the thread @@ -262,7 +275,8 @@ Table 1-3: Contents of the statm files (as of 2.6.8-rc3) Field Content size total program size (pages) (same as VmSize in status) resident size of memory portions (pages) (same as VmRSS in status) - shared number of pages that are shared (i.e. backed by a file) + shared number of pages that are shared (i.e. backed by a file, same + as RssFile+RssShmem in status) trs number of pages that are 'code' (not including libs; broken, includes data segment) lrs number of pages of library (always 0 on 2.6) @@ -310,7 +324,7 @@ Table 1-4: Contents of the stat files (as of 2.6.30-rc7) blocked bitmap of blocked signals sigign bitmap of ignored signals sigcatch bitmap of caught signals - wchan address where process went to sleep + 0 (place holder, used to be the wchan address, use /proc/PID/wchan instead) 0 (place holder) 0 (place holder) exit_signal signal to send to parent thread on exit @@ -343,7 +357,7 @@ address perms offset dev inode pathname a7cb1000-a7cb2000 ---p 00000000 00:00 0 a7cb2000-a7eb2000 rw-p 00000000 00:00 0 a7eb2000-a7eb3000 ---p 00000000 00:00 0 -a7eb3000-a7ed5000 rw-p 00000000 00:00 0 [stack:1001] +a7eb3000-a7ed5000 rw-p 00000000 00:00 0 a7ed5000-a8008000 r-xp 00000000 03:00 4222 /lib/libc.so.6 a8008000-a800a000 r--p 00133000 03:00 4222 /lib/libc.so.6 a800a000-a800b000 rw-p 00135000 03:00 4222 /lib/libc.so.6 @@ -375,7 +389,6 @@ is not associated with a file: [heap] = the heap of the program [stack] = the stack of the main process - [stack:1001] = the stack of the thread with tid 1001 [vdso] = the "virtual dynamic shared object", the kernel system call handler @@ -383,10 +396,8 @@ is not associated with a file: The /proc/PID/task/TID/maps is a view of the virtual memory from the viewpoint of the individual tasks of a process. In this file you will see a mapping marked -as [stack] if that task sees it as a stack. This is a key difference from the -content of /proc/PID/maps, where you will see all mappings that are being used -as stack by all of those tasks. Hence, for the example above, the task-level -map, i.e. /proc/PID/task/TID/maps for thread 1001 will look like this: +as [stack] if that task sees it as a stack. Hence, for the example above, the +task-level map, i.e. /proc/PID/task/TID/maps for thread 1001 will look like this: 08048000-08049000 r-xp 00000000 03:00 8312 /opt/test 08049000-0804a000 rw-p 00001000 03:00 8312 /opt/test @@ -423,12 +434,15 @@ Private_Clean: 0 kB Private_Dirty: 0 kB Referenced: 892 kB Anonymous: 0 kB +AnonHugePages: 0 kB +Shared_Hugetlb: 0 kB +Private_Hugetlb: 0 kB Swap: 0 kB SwapPss: 0 kB KernelPageSize: 4 kB MMUPageSize: 4 kB -Locked: 374 kB -VmFlags: rd ex mr mw me de +Locked: 0 kB +VmFlags: rd ex mr mw me dw the first of these lines shows the same information as is displayed for the mapping in /proc/PID/maps. The remaining lines show the size of the mapping @@ -448,9 +462,17 @@ accessed. "Anonymous" shows the amount of memory that does not belong to any file. Even a mapping associated with a file may contain anonymous pages: when MAP_PRIVATE and a page is modified, the file page is replaced by a private anonymous copy. -"Swap" shows how much would-be-anonymous memory is also used, but out on -swap. -"SwapPss" shows proportional swap share of this mapping. +"AnonHugePages" shows the ammount of memory backed by transparent hugepage. +"Shared_Hugetlb" and "Private_Hugetlb" show the ammounts of memory backed by +hugetlbfs page which is *not* counted in "RSS" or "PSS" field for historical +reasons. And these are not included in {Shared,Private}_{Clean,Dirty} field. +"Swap" shows how much would-be-anonymous memory is also used, but out on swap. +For shmem mappings, "Swap" includes also the size of the mapped (and not +replaced by copy-on-write) part of the underlying shmem object out on swap. +"SwapPss" shows proportional swap share of this mapping. Unlike "Swap", this +does not take into account swapped out page of underlying shmem objects. +"Locked" indicates whether the mapping is locked in memory or not. + "VmFlags" field deserves a separate description. This member represents the kernel flags associated with the particular virtual memory area in two letter encoded manner. The codes are the following: @@ -474,7 +496,6 @@ manner. The codes are the following: ac - area is accountable nr - swap space is not reserved for the area ht - area uses huge tlb pages - nl - non-linear mapping ar - architecture specific flag dd - do not include area into core dump sd - soft-dirty flag @@ -797,7 +818,7 @@ by migrate-type and finishes with details on how many page blocks of each type exist. If min_free_kbytes has been tuned correctly (recommendations made by hugeadm -from libhugetlbfs http://sourceforge.net/projects/libhugetlbfs/), one can +from libhugetlbfs https://github.com/libhugetlbfs/libhugetlbfs/), one can make an estimate of the likely number of huge pages that can be allocated at a given point in time. All the "Movable" blocks should be allocatable unless memory has been mlock()'d. Some of the Reclaimable blocks should @@ -814,9 +835,6 @@ varies by architecture and compile options. The following is from a > cat /proc/meminfo -The "Locked" indicates whether the mapping is locked in memory or not. - - MemTotal: 16344972 kB MemFree: 13634064 kB MemAvailable: 14836172 kB @@ -835,6 +853,7 @@ Dirty: 968 kB Writeback: 0 kB AnonPages: 861800 kB Mapped: 280372 kB +Shmem: 644 kB Slab: 284364 kB SReclaimable: 159856 kB SUnreclaim: 124508 kB @@ -891,6 +910,7 @@ MemAvailable: An estimate of how much memory is available for starting new AnonPages: Non-file backed pages mapped into userspace page tables AnonHugePages: Non-file backed huge pages mapped into userspace page tables Mapped: files which have been mmaped, such as libraries + Shmem: Total memory used by shared memory (shmem) and tmpfs Slab: in-kernel data structures cache SReclaimable: Part of Slab, that might be reclaimed, such as caches SUnreclaim: Part of Slab, that cannot be reclaimed on memory pressure @@ -1598,16 +1618,16 @@ Documentation/accounting. --------------------------------------------------------------- When a process is dumped, all anonymous memory is written to a core file as long as the size of the core file isn't limited. But sometimes we don't want -to dump some memory segments, for example, huge shared memory. Conversely, -sometimes we want to save file-backed memory segments into a core file, not -only the individual files. +to dump some memory segments, for example, huge shared memory or DAX. +Conversely, sometimes we want to save file-backed memory segments into a core +file, not only the individual files. /proc/<pid>/coredump_filter allows you to customize which memory segments will be dumped when the <pid> process is dumped. coredump_filter is a bitmask of memory types. If a bit of the bitmask is set, memory segments of the corresponding memory type are dumped, otherwise they are not dumped. -The following 7 memory types are supported: +The following 9 memory types are supported: - (bit 0) anonymous private memory - (bit 1) anonymous shared memory - (bit 2) file-backed private memory @@ -1616,20 +1636,22 @@ The following 7 memory types are supported: effective only if the bit 2 is cleared) - (bit 5) hugetlb private memory - (bit 6) hugetlb shared memory + - (bit 7) DAX private memory + - (bit 8) DAX shared memory Note that MMIO pages such as frame buffer are never dumped and vDSO pages are always dumped regardless of the bitmask status. - Note bit 0-4 doesn't effect any hugetlb memory. hugetlb memory are only - effected by bit 5-6. + Note that bits 0-4 don't affect hugetlb or DAX memory. hugetlb memory is + only affected by bit 5-6, and DAX is only affected by bits 7-8. -Default value of coredump_filter is 0x23; this means all anonymous memory -segments and hugetlb private memory are dumped. +The default value of coredump_filter is 0x33; this means all anonymous memory +segments, ELF header pages and hugetlb private memory are dumped. If you don't want to dump all shared memory segments attached to pid 1234, -write 0x21 to the process's proc file. +write 0x31 to the process's proc file. - $ echo 0x21 > /proc/1234/coredump_filter + $ echo 0x31 > /proc/1234/coredump_filter When a new process is created, the process inherits the bitmask status from its parent. It is useful to set up coredump_filter before the program runs. @@ -1841,6 +1863,23 @@ time one can open(2) mappings from the listings of two processes and comparing their inode numbers to figure out which anonymous memory areas are actually shared. +3.10 /proc/<pid>/timerslack_ns - Task timerslack value +--------------------------------------------------------- +This file provides the value of the task's timerslack value in nanoseconds. +This value specifies a amount of time that normal timers may be deferred +in order to coalesce timers and avoid unnecessary wakeups. + +This allows a task's interactivity vs power consumption trade off to be +adjusted. + +Writing 0 to the file will set the tasks timerslack to the default value. + +Valid values are from 0 - ULLONG_MAX + +An application setting the value must have PTRACE_MODE_ATTACH_FSCREDS level +permissions on the task specified to change its timerslack_ns value. + + ------------------------------------------------------------------------------ Configuring procfs ------------------------------------------------------------------------------ diff --git a/Documentation/filesystems/sharedsubtree.txt b/Documentation/filesystems/sharedsubtree.txt index 32a173dd3158..8ccfbd55244b 100644 --- a/Documentation/filesystems/sharedsubtree.txt +++ b/Documentation/filesystems/sharedsubtree.txt @@ -123,7 +123,7 @@ replicas continue to be exactly same. 2d) A unbindable mount is a unbindable private mount - let's say we have a mount at /mnt and we make is unbindable + let's say we have a mount at /mnt and we make it unbindable # mount --make-unbindable /mnt @@ -197,13 +197,13 @@ replicas continue to be exactly same. namespaces are made first class objects with user API to associate/disassociate a namespace with userid, then each user could have his/her own namespace and tailor it to his/her - requirements. Offcourse its needs support from PAM. + requirements. This needs to be supported in PAM. D) Versioned files If the entire mount tree is visible at multiple locations, then - a underlying versioning file system can return different - version of the file depending on the path used to access that + an underlying versioning file system can return different + versions of the file depending on the path used to access that file. An example is: @@ -664,7 +664,7 @@ replicas continue to be exactly same. if one rbind mounts a tree within the same subtree 'n' times the number of mounts created is an exponential function of 'n'. Having unbindable mount can help prune the unneeded bind - mounts. Here is a example. + mounts. Here is an example. step 1: let's say the root tree has just two directories with diff --git a/Documentation/filesystems/sysfs-tagging.txt b/Documentation/filesystems/sysfs-tagging.txt index eb843e49c5a3..c7c8e6438958 100644 --- a/Documentation/filesystems/sysfs-tagging.txt +++ b/Documentation/filesystems/sysfs-tagging.txt @@ -17,13 +17,13 @@ the sysfs directory entries we ensure that we don't have conflicts in the directories and applications only see a limited set of the network devices. -Each sysfs directory entry may be tagged with zero or one -namespaces. A sysfs_dirent is augmented with a void *s_ns. If a -directory entry is tagged, then sysfs_dirent->s_flags will have a -flag between KOBJ_NS_TYPE_NONE and KOBJ_NS_TYPES, and s_ns will -point to the namespace to which it belongs. +Each sysfs directory entry may be tagged with a namespace via the +void *ns member of its kernfs_node. If a directory entry is tagged, +then kernfs_node->flags will have a flag between KOBJ_NS_TYPE_NONE +and KOBJ_NS_TYPES, and ns will point to the namespace to which it +belongs. -Each sysfs superblock's sysfs_super_info contains an array void +Each sysfs superblock's kernfs_super_info contains an array void *ns[KOBJ_NS_TYPES]. When a task in a tagging namespace kobj_nstype first mounts sysfs, a new superblock is created. It will be differentiated from other sysfs mounts by having its @@ -31,7 +31,7 @@ s_fs_info->ns[kobj_nstype] set to the new namespace. Note that through bind mounting and mounts propagation, a task can easily view the contents of other namespaces' sysfs mounts. Therefore, when a namespace exits, it will call kobj_ns_exit() to invalidate any -sysfs_dirent->s_ns pointers pointing to it. +kernfs_node->ns pointers pointing to it. Users of this interface: - define a type in the kobj_ns_type enumeration. diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 9494afb9476a..24da7b32c489 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -40,7 +40,7 @@ ancestors of object hierarchies; i.e. the subsystems the objects belong to. Sysfs internally stores a pointer to the kobject that implements a -directory in the sysfs_dirent object associated with the directory. In +directory in the kernfs_node object associated with the directory. In the past this kobject pointer has been used by sysfs to do reference counting directly on the kobject whenever the file is opened or closed. With the current sysfs implementation the kobject reference count is @@ -191,9 +191,10 @@ implementations: be called again, rearmed, to fill the buffer. - On write(2), sysfs expects the entire buffer to be passed during the - first write. Sysfs then passes the entire buffer to the store() - method. - + first write. Sysfs then passes the entire buffer to the store() method. + A terminating null is added after the data on stores. This makes + functions like sysfs_streq() safe to use. + When writing sysfs files, userspace processes should first read the entire file, modify the values it wishes to change, then write the entire buffer back. diff --git a/Documentation/filesystems/tmpfs.txt b/Documentation/filesystems/tmpfs.txt index 98ef55124158..d392e1505f17 100644 --- a/Documentation/filesystems/tmpfs.txt +++ b/Documentation/filesystems/tmpfs.txt @@ -17,10 +17,10 @@ RAM, where you have to create an ordinary filesystem on top. Ramdisks cannot swap and you do not have the possibility to resize them. Since tmpfs lives completely in the page cache and on swap, all tmpfs -pages currently in memory will show up as cached. It will not show up -as shared or something like that. Further on you can check the actual -RAM+swap use of a tmpfs instance with df(1) and du(1). - +pages will be shown as "Shmem" in /proc/meminfo and "Shared" in +free(1). Notice that these counters also include shared memory +(shmem, see ipcs(1)). The most reliable way to get the count is +using df(1) and du(1). tmpfs has the following uses: diff --git a/Documentation/filesystems/vfat.txt b/Documentation/filesystems/vfat.txt index ce1126aceed8..223c32171dcc 100644 --- a/Documentation/filesystems/vfat.txt +++ b/Documentation/filesystems/vfat.txt @@ -180,6 +180,16 @@ dos1xfloppy -- If set, use a fallback default BIOS Parameter Block <bool>: 0,1,yes,no,true,false +LIMITATION +--------------------------------------------------------------------- +* The fallocated region of file is discarded at umount/evict time + when using fallocate with FALLOC_FL_KEEP_SIZE. + So, User should assume that fallocated region can be discarded at + last close if there is memory pressure resulting in eviction of + the inode from the memory. As a result, for any dependency on + the fallocated region, user should make sure to recheck fallocate + after reopening the file. + TODO ---------------------------------------------------------------------- * Need to get rid of the raw scanning stuff. Instead, always use diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 8c6f07ad373a..b02a7d598258 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -350,8 +350,8 @@ struct inode_operations { int (*rename2) (struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); - const char *(*follow_link) (struct dentry *, void **); - void (*put_link) (struct inode *, void *); + const char *(*get_link) (struct dentry *, struct inode *, + struct delayed_call *); int (*permission) (struct inode *, int); int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); @@ -434,20 +434,19 @@ otherwise noted. readlink: called by the readlink(2) system call. Only required if you want to support reading symbolic links - follow_link: called by the VFS to follow a symbolic link to the + get_link: called by the VFS to follow a symbolic link to the inode it points to. Only required if you want to support symbolic links. This method returns the symlink body to traverse (and possibly resets the current position with nd_jump_link()). If the body won't go away until the inode is gone, nothing else is needed; if it needs to be otherwise - pinned, the data needed to release whatever we'd grabbed - is to be stored in void * variable passed by address to - follow_link() instance. - - put_link: called by the VFS to release resources allocated by - follow_link(). The cookie stored by follow_link() is passed - to this method as the last parameter; only called when - cookie isn't NULL. + pinned, arrange for its release by having get_link(..., ..., done) + do set_delayed_call(done, destructor, argument). + In that case destructor(argument) will be called once VFS is + done with the body you've returned. + May be called in RCU mode; that is indicated by NULL dentry + argument. If request can't be handled without leaving RCU mode, + have it return ERR_PTR(-ECHILD). permission: called by the VFS to check for access rights on a POSIX-like filesystem. diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt new file mode 100644 index 000000000000..ce3e84fa9023 --- /dev/null +++ b/Documentation/fpga/fpga-mgr.txt @@ -0,0 +1,171 @@ +FPGA Manager Core + +Alan Tull 2015 + +Overview +======== + +The FPGA manager core exports a set of functions for programming an FPGA with +an image. The API is manufacturer agnostic. All manufacturer specifics are +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. + + +API Functions: +============== + +To program the FPGA from a file or from a buffer: +------------------------------------------------- + + int fpga_mgr_buf_load(struct fpga_manager *mgr, u32 flags, + const char *buf, size_t count); + +Load the FPGA from an image which exists as a buffer in memory. + + int fpga_mgr_firmware_load(struct fpga_manager *mgr, u32 flags, + 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). + +For both these functions, flags == 0 for normal full reconfiguration or +FPGA_MGR_PARTIAL_RECONFIG for partial reconfiguration. If successful, the FPGA +ends up in operating mode. Return 0 on success or a negative error code. + + +To get/put a reference to a FPGA manager: +----------------------------------------- + + struct fpga_manager *of_fpga_mgr_get(struct device_node *node); + + void fpga_mgr_put(struct fpga_manager *mgr); + +Given a DT node, get an exclusive reference to a FPGA manager or release +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); + + void fpga_mgr_unregister(struct device *dev); + +Use of these two functions is described below in "How To Support a new FPGA +device." + + +How to write an image buffer to a supported FPGA +================================================ +/* Include to get the API */ +#include <linux/fpga/fpga-mgr.h> + +/* 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 = ... + +/* flags indicates whether to do full or partial reconfiguration */ +int flags = 0; + +int ret; + +/* Get exclusive control of FPGA manager */ +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + +/* Load the buffer to the FPGA */ +ret = fpga_mgr_buf_load(mgr, flags, buf, count); + +/* Release the FPGA manager */ +fpga_mgr_put(mgr); + + +How to write an image file to a supported FPGA +============================================== +/* Include to get the API */ +#include <linux/fpga/fpga-mgr.h> + +/* device node that specifies the FPGA manager to use */ +struct device_node *mgr_node = ... + +/* FPGA image is in this file which is in the firmware search path */ +const char *path = "fpga-image-9.rbf" + +/* flags indicates whether to do full or partial reconfiguration */ +int flags = 0; + +int ret; + +/* Get exclusive control of FPGA manager */ +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + +/* Get the firmware image (path) and load it to the FPGA */ +ret = fpga_mgr_firmware_load(mgr, flags, path); + +/* Release the FPGA manager */ +fpga_mgr_put(mgr); + + +How to support a new FPGA device +================================ +To add another FPGA manager, write a driver that implements a set of ops. The +probe function calls fpga_mgr_register(), such as: + +static const struct fpga_manager_ops socfpga_fpga_ops = { + .write_init = socfpga_fpga_ops_configure_init, + .write = socfpga_fpga_ops_configure_write, + .write_complete = socfpga_fpga_ops_configure_complete, + .state = socfpga_fpga_ops_state, +}; + +static int socfpga_fpga_probe(struct platform_device *pdev) +{ + struct device *dev = &pdev->dev; + struct socfpga_fpga_priv *priv; + int ret; + + priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* ... do ioremaps, get interrupts, etc. and save + them in priv... */ + + return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", + &socfpga_fpga_ops, priv); +} + +static int socfpga_fpga_remove(struct platform_device *pdev) +{ + fpga_mgr_unregister(&pdev->dev); + + return 0; +} + + +The ops will implement whatever device specific register writes are needed to +do the programming sequence for this particular FPGA. These ops return 0 for +success or negative error codes otherwise. + +The programming sequence is: + 1. .write_init + 2. .write (may be called once or multiple times) + 3. .write_complete + +The .write_init function will prepare the FPGA to receive the image data. + +The .write function writes a buffer to the FPGA. The buffer may be contain the +whole FPGA image or may be a smaller chunk of an FPGA image. In the latter +case, this function is called multiple times for successive chunks. + +The .write_complete function is called after all the image has been written +to put the FPGA into operating mode. + +The ops include a .state function which will read the hardware FPGA manager and +return a code of type enum fpga_mgr_states. It doesn't result in a change in +hardware state. diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index f59c43b6411b..86d3fa95fd12 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -21,8 +21,8 @@ exact way to do it depends on the GPIO controller providing the GPIOs, see the device tree bindings for your controller. GPIOs mappings are defined in the consumer device's node, in a property named -either <function>-gpios or <function>-gpio, where <function> is the function -the driver will request through gpiod_get(). For example: +<function>-gpios, where <function> is the function the driver will request +through gpiod_get(). For example: foo_device { compatible = "acme,foo"; @@ -31,9 +31,13 @@ the driver will request through gpiod_get(). For example: <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ - power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>; + power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; }; +Properties named <function>-gpio are also considered valid and old bindings use +it but are only supported for compatibility reasons and should not be used for +newer bindings since it has been deprecated. + This property will make GPIOs 15, 16 and 17 available to the driver under the "led" function, and GPIO 1 as the "power" GPIO: @@ -107,16 +111,13 @@ files that desire to do so need to include the following header: GPIOs are mapped by the means of tables of lookups, containing instances of the gpiod_lookup structure. Two macros are defined to help declaring such mappings: - GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags) - GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags) + GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags) + GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags) where - chip_label is the label of the gpiod_chip instance providing the GPIO - chip_hwnum is the hardware number of the GPIO within the chip - - dev_id is the identifier of the device that will make use of this GPIO. It - can be NULL, in which case it will be matched for calls to gpiod_get() - with a NULL device. - con_id is the name of the GPIO function from the device point of view. It can be NULL, in which case it will match any function. - idx is the index of the GPIO within the function. @@ -130,7 +131,9 @@ In the future, these flags might be extended to support more properties. Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. A lookup table can then be defined as follows, with an empty entry defining its -end: +end. The 'dev_id' field of the table is the identifier of the device that will +make use of these GPIOs. It can be NULL, in which case it will be matched for +calls to gpiod_get() with a NULL device. struct gpiod_lookup_table gpios_table = { .dev_id = "foo.0", diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index e000502fde20..05676fdacfe3 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -260,7 +260,7 @@ will be driven low. To summarize: -Function (example) active-low proporty physical line +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 diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 90d0f6aba7a6..bbeec415f406 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -62,6 +62,11 @@ Any debugfs dump method should normally ignore signals which haven't been requested as GPIOs. They can use gpiochip_is_requested(), which returns either NULL or the label associated with that GPIO when it was requested. +RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs +(like PM runtime) in its gpio_chip implementation (.get/.set and direction +control callbacks) if it is expected to call GPIO APIs from atomic context +on -RT (inside hard IRQ handlers and similar contexts). Normally this should +not be required. GPIO drivers providing IRQs --------------------------- @@ -73,6 +78,13 @@ The IRQ portions of the GPIO block are implemented using an irqchip, using the header <linux/irq.h>. So basically such a driver is utilizing two sub- systems simultaneously: gpio and irq. +RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs +(like PM runtime) as part of its irq_chip implementation on -RT. +- spinlock_t should be replaced with raw_spinlock_t [1]. +- If sleepable APIs have to be used, these can be done from the .irq_bus_lock() + and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks + on an irqchip. Create the callbacks if needed [2]. + GPIO irqchips usually fall in one of two categories: * CHAINED GPIO irqchips: these are usually the type that is embedded on @@ -93,6 +105,38 @@ GPIO irqchips usually fall in one of two categories: Chained GPIO irqchips typically can NOT set the .can_sleep flag on struct gpio_chip, as everything happens directly in the callbacks. + RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT. + As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used + in chained IRQ handler. + if required (and if it can't be converted to the nested threaded GPIO irqchip) + - chained IRQ handler can be converted to generic irq handler and this way + it will be threaded IRQ handler on -RT and hard IRQ handler on non-RT + (for example, see [3]). + Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled, + so IRQ core will complain if it will be called from IRQ handler which is + forced thread. The "fake?" raw lock can be used to W/A this problem: + + raw_spinlock_t wa_lock; + static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank) + unsigned long wa_lock_flags; + raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags); + generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit)); + raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags); + +* GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips", + but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is + performed by generic IRQ handler which is configured using request_irq(). + The GPIO irqchip will then end up calling something like this sequence in + its interrupt handler: + + static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id) + for each detected GPIO IRQ + generic_handle_irq(...); + + RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ + core will complain that generic_handle_irq() is called with IRQ enabled and + the same W/A as for "CHAINED GPIO irqchips" can be applied. + * NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any other GPIO irqchip residing on the other side of a sleeping bus. Of course such drivers that need slow bus traffic to read out IRQ status and similar, @@ -133,6 +177,13 @@ To use the helpers please keep the following in mind: the irqchip can initialize. E.g. .dev and .can_sleep shall be set up properly. +- Nominally set all handlers to handle_bad_irq() in the setup call and pass + handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is + expected for GPIO driver that irqchip .set_type() callback have to be called + before using/enabling GPIO IRQ. Then set the handler to handle_level_irq() + and/or handle_edge_irq() in the irqchip .set_type() callback depending on + what your controller supports. + It is legal for any IRQ consumer to request an IRQ from any irqchip no matter if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and irq_chip are orthogonal, and offering their services independent of each @@ -169,6 +220,31 @@ When implementing an irqchip inside a GPIO driver, these two functions should typically be called in the .startup() and .shutdown() callbacks from the irqchip. +Real-Time compliance for GPIO IRQ chips +--------------------------------------- + +Any provider of irqchips needs to be carefully tailored to support Real Time +preemption. It is desirable that all irqchips in the GPIO subsystem keep this +in mind and does the proper testing to assure they are real time-enabled. +So, pay attention on above " RT_FULL:" notes, please. +The following is a checklist to follow when preparing a driver for real +time-compliance: + +- ensure spinlock_t is not used as part irq_chip implementation; +- ensure that sleepable APIs are not used as part irq_chip implementation. + If sleepable APIs have to be used, these can be done from the .irq_bus_lock() + and .irq_bus_unlock() callbacks; +- Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used + from chained IRQ handler; +- Generic chained GPIO irqchips: take care about generic_handle_irq() calls and + apply corresponding W/A; +- Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq + handler if possible :) +- regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for + GPIO IRQ chip implementation; +- Test your driver with the appropriate in-kernel real time test cases for both + level and edge IRQs. + Requesting self-owned GPIO pins ------------------------------- @@ -190,3 +266,7 @@ gpiochip_free_own_desc(). These functions must be used with care since they do not affect module use count. Do not use the functions to request gpio descriptors not owned by the calling driver. + +[1] http://www.spinics.net/lists/linux-omap/msg120425.html +[2] https://lkml.org/lkml/2015/9/25/494 +[3] https://lkml.org/lkml/2015/9/25/495 diff --git a/Documentation/gpio/drivers-on-gpio.txt b/Documentation/gpio/drivers-on-gpio.txt index f6121328630f..14bf95a13bae 100644 --- a/Documentation/gpio/drivers-on-gpio.txt +++ b/Documentation/gpio/drivers-on-gpio.txt @@ -54,7 +54,7 @@ hardware descriptions such as device tree or ACPI: drivers for the I2C devices on the bus like any other I2C bus driver. - spi_gpio: drivers/spi/spi-gpio.c is used to drive an SPI bus (variable number - of wires, atleast SCK and optionally MISO, MOSI and chip select lines) using + of wires, at least SCK and optionally MISO, MOSI and chip select lines) using GPIO hammering (bitbang). It will appear as any other SPI bus on the system and makes it possible to connect drivers for SPI devices on the bus like any other SPI bus driver. For example any MMC/SD card can then be connected @@ -75,7 +75,7 @@ hardware descriptions such as device tree or ACPI: - gpio-wdt: drivers/watchdog/gpio_wdt.c is used to provide a watchdog timer that will periodically "ping" a hardware connected to a GPIO line by toggling - it from 1-to-0-to-1. If that hardware does not recieve its "ping" + it from 1-to-0-to-1. If that hardware does not receive its "ping" periodically, it will reset the system. - gpio-nand: drivers/mtd/nand/gpio.c is used to connect a NAND flash chip to @@ -91,5 +91,5 @@ usually connected directly to the flash. Use those instead of talking directly to the GPIOs using sysfs; they integrate with kernel frameworks better than your userspace code could. Needless to say, -just using the apropriate kernel drivers will simplify and speed up your +just using the appropriate kernel drivers will simplify and speed up your embedded hacking in particular by providing ready-made components. diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt index 0700b55637f5..aeab01aa4d00 100644 --- a/Documentation/gpio/sysfs.txt +++ b/Documentation/gpio/sysfs.txt @@ -20,14 +20,14 @@ userspace GPIO can be used to determine system configuration data that standard kernels won't know about. And for some tasks, simple userspace GPIO drivers could be all that the system really needs. -DO NOT ABUSE SYFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS. +DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS. PLEASE READ THE DOCUMENT NAMED "drivers-on-gpio.txt" IN THIS DOCUMENTATION DIRECTORY TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY. Paths in Sysfs -------------- -There are three kinds of entry in /sys/class/gpio: +There are three kinds of entries in /sys/class/gpio: - Control interfaces used to get userspace control over GPIOs; @@ -106,7 +106,7 @@ read-only attributes: "label" ... provided for diagnostics (not always unique) - "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1) + "ngpio" ... how many GPIOs this manages (N to N + ngpio - 1) Board documentation should in most cases cover what GPIOs are used for what purposes. However, those numbers are not always stable; GPIOs on diff --git a/Documentation/hw_random.txt b/Documentation/hw_random.txt index 026e237bbc87..fce1634907d0 100644 --- a/Documentation/hw_random.txt +++ b/Documentation/hw_random.txt @@ -3,7 +3,7 @@ Introduction: The hw_random framework is software that makes use of a special hardware feature on your CPU or motherboard, a Random Number Generator (RNG). The software has two parts: - a core providing the /dev/hw_random character device and its + a core providing the /dev/hwrng character device and its sysfs support, plus a hardware-specific driver that plugs into that core. @@ -14,7 +14,7 @@ Introduction: http://sourceforge.net/projects/gkernel/ - Those tools use /dev/hw_random to fill the kernel entropy pool, + Those tools use /dev/hwrng to fill the kernel entropy pool, which is used internally and exported by the /dev/urandom and /dev/random special files. @@ -32,13 +32,13 @@ Theory of operation: The rng-tools package uses such tests in "rngd", and lets you run them by hand with a "rngtest" utility. - /dev/hw_random is char device major 10, minor 183. + /dev/hwrng is char device major 10, minor 183. CLASS DEVICE. There is a /sys/class/misc/hw_random node with two unique attributes, "rng_available" and "rng_current". The "rng_available" attribute lists the hardware-specific drivers available, while "rng_current" lists the one which is currently - connected to /dev/hw_random. If your system has more than one + connected to /dev/hwrng. If your system has more than one RNG available, you may change the one used by writing a name from the list in "rng_available" into "rng_current". diff --git a/Documentation/hwmon/adm1275 b/Documentation/hwmon/adm1275 index d697229e3c18..791bc0bd91e6 100644 --- a/Documentation/hwmon/adm1275 +++ b/Documentation/hwmon/adm1275 @@ -14,6 +14,10 @@ Supported chips: Prefix: 'adm1276' Addresses scanned: - Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1276.pdf + * Analog Devices ADM1278 + Prefix: 'adm1278' + Addresses scanned: - + Datasheet: www.analog.com/static/imported-files/data_sheets/ADM1278.pdf * Analog Devices ADM1293/ADM1294 Prefix: 'adm1293', 'adm1294' Addresses scanned: - @@ -25,13 +29,15 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for Analog Devices ADM1075, ADM1275, -ADM1276, ADM1293, and ADM1294 Hot-Swap Controller and Digital Power Monitors. +This driver supports hardware monitoring for Analog Devices ADM1075, ADM1275, +ADM1276, ADM1278, ADM1293, and ADM1294 Hot-Swap Controller and Digital +Power Monitors. -ADM1075, ADM1275, ADM1276, ADM1293, and ADM1294 are hot-swap controllers that -allow a circuit board to be removed from or inserted into a live backplane. -They also feature current and voltage readback via an integrated 12 -bit analog-to-digital converter (ADC), accessed using a PMBus interface. +ADM1075, ADM1275, ADM1276, ADM1278, ADM1293, and ADM1294 are hot-swap +controllers that allow a circuit board to be removed from or inserted into +a live backplane. They also feature current and voltage readback via an +integrated 12 bit analog-to-digital converter (ADC), accessed using a +PMBus interface. The driver is a client driver to the core PMBus driver. Please see Documentation/hwmon/pmbus for details on PMBus client drivers. @@ -96,3 +102,14 @@ power1_reset_history Write any value to reset history. Power attributes are supported on ADM1075, ADM1276, ADM1293, and ADM1294. + +temp1_input Chip temperature. + Temperature attributes are only available on ADM1278. +temp1_max Maximum chip temperature. +temp1_max_alarm Temperature alarm. +temp1_crit Critical chip temperature. +temp1_crit_alarm Critical temperature high alarm. +temp1_highest Highest observed temperature. +temp1_reset_history Write any value to reset history. + + Temperature attributes are supported on ADM1278. diff --git a/Documentation/hwmon/htu21 b/Documentation/hwmon/htu21 deleted file mode 100644 index f39a215fb6ae..000000000000 --- a/Documentation/hwmon/htu21 +++ /dev/null @@ -1,46 +0,0 @@ -Kernel driver htu21 -=================== - -Supported chips: - * Measurement Specialties HTU21D - Prefix: 'htu21' - Addresses scanned: none - Datasheet: Publicly available at the Measurement Specialties website - http://www.meas-spec.com/downloads/HTU21D.pdf - - -Author: - William Markezana <william.markezana@meas-spec.com> - -Description ------------ - -The HTU21D is a humidity and temperature sensor in a DFN package of -only 3 x 3 mm footprint and 0.9 mm height. - -The devices communicate with the I2C protocol. All sensors are set to the -same I2C address 0x40, so an entry with I2C_BOARD_INFO("htu21", 0x40) can -be used in the board setup code. - -This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices -for details. - -sysfs-Interface ---------------- - -temp1_input - temperature input -humidity1_input - humidity input - -Notes ------ - -The driver uses the default resolution settings of 12 bit for humidity and 14 -bit for temperature, which results in typical measurement times of 11 ms for -humidity and 44 ms for temperature. To keep self heating below 0.1 degree -Celsius, the device should not be active for more than 10% of the time. For -this reason, the driver performs no more than two measurements per second and -reports cached information if polled more frequently. - -Different resolutions, the on-chip heater, using the CRC checksum and reading -the serial number are not supported yet. diff --git a/Documentation/hwmon/lm25066 b/Documentation/hwmon/lm25066 index b34c3de5c1bc..2cb20ebb234d 100644 --- a/Documentation/hwmon/lm25066 +++ b/Documentation/hwmon/lm25066 @@ -36,7 +36,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for National Semiconductor / TI LM25056, +This driver supports hardware monitoring for National Semiconductor / TI LM25056, LM25063, LM25066, LM5064, and LM5066 Power Management, Monitoring, Control, and Protection ICs. diff --git a/Documentation/hwmon/lm75 b/Documentation/hwmon/lm75 index 67691a0aa41d..ac95edfcd907 100644 --- a/Documentation/hwmon/lm75 +++ b/Documentation/hwmon/lm75 @@ -42,8 +42,8 @@ Supported chips: Addresses scanned: none Datasheet: Publicly available at the ST website http://www.st.com/internet/analog/product/121769.jsp - * Texas Instruments TMP100, TMP101, TMP105, TMP112, TMP75, TMP175, TMP275 - Prefixes: 'tmp100', 'tmp101', 'tmp105', 'tmp112', 'tmp175', 'tmp75', 'tmp275' + * Texas Instruments TMP100, TMP101, TMP105, TMP112, TMP75, TMP75C, TMP175, TMP275 + Prefixes: 'tmp100', 'tmp101', 'tmp105', 'tmp112', 'tmp175', 'tmp75', 'tmp75c', 'tmp275' Addresses scanned: none Datasheet: Publicly available at the Texas Instruments website http://www.ti.com/product/tmp100 @@ -51,6 +51,7 @@ Supported chips: http://www.ti.com/product/tmp105 http://www.ti.com/product/tmp112 http://www.ti.com/product/tmp75 + http://www.ti.com/product/tmp75c http://www.ti.com/product/tmp175 http://www.ti.com/product/tmp275 * NXP LM75B diff --git a/Documentation/hwmon/ltc2990 b/Documentation/hwmon/ltc2990 new file mode 100644 index 000000000000..c25211e90bdc --- /dev/null +++ b/Documentation/hwmon/ltc2990 @@ -0,0 +1,43 @@ +Kernel driver ltc2990 +===================== + +Supported chips: + * Linear Technology LTC2990 + Prefix: 'ltc2990' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc2990 + +Author: Mike Looijmans <mike.looijmans@topic.nl> + + +Description +----------- + +LTC2990 is a Quad I2C Voltage, Current and Temperature Monitor. +The chip's inputs can measure 4 voltages, or two inputs together (1+2 and 3+4) +can be combined to measure a differential voltage, which is typically used to +measure current through a series resistor, or a temperature. + +This driver currently uses the 2x differential mode only. In order to support +other modes, the driver will need to be expanded. + + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + + +Sysfs attributes +---------------- + +The "curr*_input" measurements actually report the voltage drop across the +input pins in microvolts. This is equivalent to the current through a 1mOhm +sense resistor. Divide the reported value by the actual sense resistor value +in mOhm to get the actual value. + +in0_input Voltage at Vcc pin in millivolt (range 2.5V to 5V) +temp1_input Internal chip temperature in millidegrees Celcius +curr1_input Current in mA across v1-v2 assuming a 1mOhm sense resistor. +curr2_input Current in mA across v3-v4 assuming a 1mOhm sense resistor. diff --git a/Documentation/hwmon/ltc3815 b/Documentation/hwmon/ltc3815 new file mode 100644 index 000000000000..eb7db2d13587 --- /dev/null +++ b/Documentation/hwmon/ltc3815 @@ -0,0 +1,61 @@ +Kernel driver ltc3815 +===================== + +Supported chips: + * Linear Technology LTC3815 + Prefix: 'ltc3815' + Addresses scanned: - + Datasheet: http://www.linear.com/product/ltc3815 + +Author: Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +LTC3815 is a Monolithic Synchronous DC/DC Step-Down Converter. + + +Usage Notes +----------- + +This driver does not probe for PMBus devices. You will have to instantiate +devices explicitly. + +Example: the following commands will load the driver for an LTC3815 +at address 0x20 on I2C bus #1: + +# modprobe ltc3815 +# echo ltc3815 0x20 > /sys/bus/i2c/devices/i2c-1/new_device + + +Sysfs attributes +---------------- + +in1_label "vin" +in1_input Measured input voltage. +in1_alarm Input voltage alarm. +in1_highest Highest input voltage. +in1_reset_history Reset input voltage history. + +in2_label "vout1". +in2_input Measured output voltage. +in2_alarm Output voltage alarm. +in2_highest Highest output voltage. +in2_reset_history Reset output voltage history. + +temp1_input Measured chip temperature. +temp1_alarm Temperature alarm. +temp1_highest Highest measured temperature. +temp1_reset_history Reset temperature history. + +curr1_label "iin". +curr1_input Measured input current. +curr1_highest Highest input current. +curr1_reset_history Reset input current history. + +curr2_label "iout1". +curr2_input Measured output current. +curr2_alarm Output current alarm. +curr2_highest Highest output current. +curr2_reset_history Reset output current history. diff --git a/Documentation/hwmon/max16064 b/Documentation/hwmon/max16064 index d59cc7829bec..265370f5cb82 100644 --- a/Documentation/hwmon/max16064 +++ b/Documentation/hwmon/max16064 @@ -13,7 +13,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for Maxim MAX16064 Quad Power-Supply +This driver supports hardware monitoring for Maxim MAX16064 Quad Power-Supply Controller with Active-Voltage Output Control and PMBus Interface. The driver is a client driver to the core PMBus driver. diff --git a/Documentation/hwmon/max31790 b/Documentation/hwmon/max31790 new file mode 100644 index 000000000000..855e62430da9 --- /dev/null +++ b/Documentation/hwmon/max31790 @@ -0,0 +1,37 @@ +Kernel driver max31790 +====================== + +Supported chips: + * Maxim MAX31790 + Prefix: 'max31790' + Addresses scanned: - + Datasheet: http://pdfserv.maximintegrated.com/en/ds/MAX31790.pdf + +Author: Il Han <corone.il.han@gmail.com> + + +Description +----------- + +This driver implements support for the Maxim MAX31790 chip. + +The MAX31790 controls the speeds of up to six fans using six independent +PWM outputs. The desired fan speeds (or PWM duty cycles) are written +through the I2C interface. The outputs drive "4-wire" fans directly, +or can be used to modulate the fan's power terminals using an external +pass transistor. + +Tachometer inputs monitor fan tachometer logic outputs for precise (+/-1%) +monitoring and control of fan RPM as well as detection of fan failure. +Six pins are dedicated tachometer inputs. Any of the six PWM outputs can +also be configured to serve as tachometer inputs. + + +Sysfs entries +------------- + +fan[1-12]_input RO fan tachometer speed in RPM +fan[1-12]_fault RO fan experienced fault +fan[1-6]_target RW desired fan speed in RPM +pwm[1-6]_enable RW regulator mode, 0=disabled, 1=manual mode, 2=rpm mode +pwm[1-6] RW fan target duty cycle (0-255) diff --git a/Documentation/hwmon/max34440 b/Documentation/hwmon/max34440 index 37cbf472a19d..f5b1fcaa9e4e 100644 --- a/Documentation/hwmon/max34440 +++ b/Documentation/hwmon/max34440 @@ -33,7 +33,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for Maxim MAX34440 PMBus 6-Channel +This driver supports hardware monitoring for Maxim MAX34440 PMBus 6-Channel Power-Supply Manager, MAX34441 PMBus 5-Channel Power-Supply Manager and Intelligent Fan Controller, and MAX34446 PMBus Power-Supply Data Logger. It also supports the MAX34460 and MAX34461 PMBus Voltage Monitor & Sequencers. diff --git a/Documentation/hwmon/max8688 b/Documentation/hwmon/max8688 index e78078638b91..ca233bec7a8a 100644 --- a/Documentation/hwmon/max8688 +++ b/Documentation/hwmon/max8688 @@ -13,7 +13,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for Maxim MAX8688 Digital Power-Supply +This driver supports hardware monitoring for Maxim MAX8688 Digital Power-Supply Controller/Monitor with PMBus Interface. The driver is a client driver to the core PMBus driver. Please see diff --git a/Documentation/hwmon/nsa320 b/Documentation/hwmon/nsa320 new file mode 100644 index 000000000000..fdbd6947799b --- /dev/null +++ b/Documentation/hwmon/nsa320 @@ -0,0 +1,53 @@ +Kernel driver nsa320_hwmon +========================== + +Supported chips: + * Holtek HT46R065 microcontroller with onboard firmware that configures + it to act as a hardware monitor. + Prefix: 'nsa320' + Addresses scanned: none + Datasheet: Not available, driver was reverse engineered based upon the + Zyxel kernel source + +Author: + Adam Baker <linux@baker-net.org.uk> + +Description +----------- + +This chip is known to be used in the Zyxel NSA320 and NSA325 NAS Units and +also in some variants of the NSA310 but the driver has only been tested +on the NSA320. In all of these devices it is connected to the same 3 GPIO +lines which are used to provide chip select, clock and data lines. The +interface behaves similarly to SPI but at much lower speeds than are normally +used for SPI. + +Following each chip select pulse the chip will generate a single 32 bit word +that contains 0x55 as a marker to indicate that data is being read correctly, +followed by an 8 bit fan speed in 100s of RPM and a 16 bit temperature in +tenths of a degree. + + +sysfs-Interface +--------------- + +temp1_input - temperature input +fan1_input - fan speed + +Notes +----- + +The access timings used in the driver are the same as used in the Zyxel +provided kernel. Testing has shown that if the delay between chip select and +the first clock pulse is reduced from 100 ms to just under 10ms then the chip +will not produce any output. If the duration of either phase of the clock +is reduced from 100 us to less than 15 us then data pulses are likely to be +read twice corrupting the output. The above analysis is based upon a sample +of one unit but suggests that the Zyxel provided delay values include a +reasonable tolerance. + +The driver incorporates a limit that it will not check for updated values +faster than once a second. This is because the hardware takes a relatively long +time to read the data from the device and when it does it reads both temp and +fan speed. As the most likely case for two accesses in quick succession is +to read both of these values avoiding a second read delay is desirable. diff --git a/Documentation/hwmon/ntc_thermistor b/Documentation/hwmon/ntc_thermistor index 1d4cc847c6fe..8b9ff23edc32 100644 --- a/Documentation/hwmon/ntc_thermistor +++ b/Documentation/hwmon/ntc_thermistor @@ -3,9 +3,9 @@ Kernel driver ntc_thermistor Supported thermistors from Murata: * Murata NTC Thermistors NCP15WB473, NCP18WB473, NCP21WB473, NCP03WB473, - NCP15WL333, NCP03WF104 + NCP15WL333, NCP03WF104, NCP15XH103 Prefixes: 'ncp15wb473', 'ncp18wb473', 'ncp21wb473', 'ncp03wb473', - 'ncp15wl333', 'ncp03wf104' + 'ncp15wl333', 'ncp03wf104', 'ncp15xh103' Datasheet: Publicly available at Murata Supported thermistors from EPCOS: diff --git a/Documentation/hwmon/pmbus b/Documentation/hwmon/pmbus index b397675e876d..dfd9c65996c0 100644 --- a/Documentation/hwmon/pmbus +++ b/Documentation/hwmon/pmbus @@ -43,7 +43,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for various PMBus compliant devices. +This driver supports hardware monitoring for various PMBus compliant devices. It supports voltage, current, power, and temperature sensors as supported by the device. diff --git a/Documentation/hwmon/scpi-hwmon b/Documentation/hwmon/scpi-hwmon new file mode 100644 index 000000000000..4cfcdf2d5eab --- /dev/null +++ b/Documentation/hwmon/scpi-hwmon @@ -0,0 +1,33 @@ +Kernel driver scpi-hwmon +======================== + +Supported chips: + * Chips based on ARM System Control Processor Interface + Addresses scanned: - + Datasheet: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0922b/index.html + +Author: Punit Agrawal <punit.agrawal@arm.com> + +Description +----------- + +This driver supports hardware monitoring for SoC's based on the ARM +System Control Processor (SCP) implementing the System Control +Processor Interface (SCPI). The following sensor types are supported +by the SCP - + + * temperature + * voltage + * current + * power + +The SCP interface provides an API to query the available sensors and +their values which are then exported to userspace by this driver. + +Usage Notes +----------- + +The driver relies on device tree node to indicate the presence of SCPI +support in the kernel. See +Documentation/devicetree/bindings/arm/arm,scpi.txt for details of the +devicetree node.
\ No newline at end of file diff --git a/Documentation/hwmon/zl6100 b/Documentation/hwmon/zl6100 index 33908a4d68ff..477a94b131ae 100644 --- a/Documentation/hwmon/zl6100 +++ b/Documentation/hwmon/zl6100 @@ -60,7 +60,7 @@ Author: Guenter Roeck <linux@roeck-us.net> Description ----------- -This driver supports hardware montoring for Intersil / Zilker Labs ZL6100 and +This driver supports hardware monitoring for Intersil / Zilker Labs ZL6100 and compatible digital DC-DC controllers. The driver is a client driver to the core PMBus driver. Please see diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index 82f48f774afb..1bba38dd2637 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -30,6 +30,9 @@ Supported adapters: * Intel BayTrail (SOC) * Intel Sunrise Point-H (PCH) * Intel Sunrise Point-LP (PCH) + * Intel DNV (SOC) + * Intel Broxton (SOC) + * Intel Lewisburg (PCH) Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index 2ac78ae1039d..bcf919d8625c 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -4,7 +4,7 @@ the /dev interface. You need to load module i2c-dev for this. Each registered i2c adapter gets a number, counting from 0. You can examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. -Alternatively, you can run "i2cdetect -l" to obtain a formated list of all +Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all i2c adapters present on your system at a given time. i2cdetect is part of the i2c-tools package. diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend index c8444ef82acf..04f8d8a9b817 100644 --- a/Documentation/i2c/slave-eeprom-backend +++ b/Documentation/i2c/slave-eeprom-backend @@ -7,8 +7,8 @@ This is a proof-of-concept backend which acts like an EEPROM on the connected I2C bus. The memory contents can be modified from userspace via this file located in sysfs: - /sys/bus/i2c/devices/<device-direcory>/slave-eeprom + /sys/bus/i2c/devices/<device-directory>/slave-eeprom As of 2015, Linux doesn't support poll on binary sysfs files, so there is no -notfication when another master changed the content. +notification when another master changed the content. diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.txt new file mode 100644 index 000000000000..f0add35cd52e --- /dev/null +++ b/Documentation/iio/iio_configfs.txt @@ -0,0 +1,93 @@ +Industrial IIO configfs support + +1. Overview + +Configfs is a filesystem-based manager of kernel objects. IIO uses some +objects that could be easily configured using configfs (e.g.: devices, +triggers). + +See Documentation/filesystems/configfs/configfs.txt for more information +about how configfs works. + +2. Usage + +In order to use configfs support in IIO we need to select it at compile +time via CONFIG_IIO_CONFIGFS config option. + +Then, mount the configfs filesystem (usually under /config directory): + +$ mkdir /config +$ mount -t configfs none /config + +At this point, all default IIO groups will be created and can be accessed +under /config/iio. Next chapters will describe available IIO configuration +objects. + +3. Software triggers + +One of the IIO default configfs groups is the "triggers" group. It is +automagically accessible when the configfs is mounted and can be found +under /config/iio/triggers. + +IIO software triggers implementation offers support for creating multiple +trigger types. A new trigger type is usually implemented as a separate +kernel module following the interface in include/linux/iio/sw_trigger.h: + +/* + * drivers/iio/trigger/iio-trig-sample.c + * sample kernel module implementing a new trigger type + */ +#include <linux/iio/sw_trigger.h> + + +static struct iio_sw_trigger *iio_trig_sample_probe(const char *name) +{ + /* + * This allocates and registers an IIO trigger plus other + * trigger type specific initialization. + */ +} + +static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt) +{ + /* + * This undoes the actions in iio_trig_sample_probe + */ +} + +static const struct iio_sw_trigger_ops iio_trig_sample_ops = { + .probe = iio_trig_sample_probe, + .remove = iio_trig_sample_remove, +}; + +static struct iio_sw_trigger_type iio_trig_sample = { + .name = "trig-sample", + .owner = THIS_MODULE, + .ops = &iio_trig_sample_ops, +}; + +module_iio_sw_trigger_driver(iio_trig_sample); + +Each trigger type has its own directory under /config/iio/triggers. Loading +iio-trig-sample module will create 'trig-sample' trigger type directory +/config/iio/triggers/trig-sample. + +We support the following interrupt sources (trigger types): + * hrtimer, uses high resolution timers as interrupt source + +3.1 Hrtimer triggers creation and destruction + +Loading iio-trig-hrtimer module will register hrtimer trigger types allowing +users to create hrtimer triggers under /config/iio/triggers/hrtimer. + +e.g: + +$ mkdir /config/triggers/hrtimer/instance1 +$ rmdir /config/triggers/hrtimer/instance1 + +Each trigger can have one or more attributes specific to the trigger type. + +3.2 "hrtimer" trigger types attributes + +"hrtimer" trigger type doesn't have any configurable attribute from /config dir. +It does introduce the sampling_frequency attribute to trigger directory. diff --git a/Documentation/infiniband/core_locking.txt b/Documentation/infiniband/core_locking.txt index e1678542279a..4b1f36b6ada0 100644 --- a/Documentation/infiniband/core_locking.txt +++ b/Documentation/infiniband/core_locking.txt @@ -15,7 +15,6 @@ Sleeping and interrupt context modify_ah query_ah destroy_ah - bind_mw post_send post_recv poll_cq @@ -31,7 +30,6 @@ Sleeping and interrupt context ib_modify_ah ib_query_ah ib_destroy_ah - ib_bind_mw ib_post_send ib_post_recv ib_req_notify_cq diff --git a/Documentation/input/rotary-encoder.txt b/Documentation/input/rotary-encoder.txt index 5737e3590adb..46a74f0c551a 100644 --- a/Documentation/input/rotary-encoder.txt +++ b/Documentation/input/rotary-encoder.txt @@ -9,8 +9,9 @@ peripherals with two wires. The outputs are phase-shifted by 90 degrees and by triggering on falling and rising edges, the turn direction can be determined. -Some encoders have both outputs low in stable states, whereas others also have -a stable state with both outputs high (half-period mode). +Some encoders have both outputs low in stable states, others also have +a stable state with both outputs high (half-period mode) and some have +a stable state in all steps (quarter-period mode). The phase diagram of these two outputs look like this: @@ -32,6 +33,9 @@ The phase diagram of these two outputs look like this: |<-->| one step (half-period mode) + |<>| + one step (quarter-period mode) + For more information, please see https://en.wikipedia.org/wiki/Rotary_encoder @@ -109,6 +113,7 @@ static struct rotary_encoder_platform_data my_rotary_encoder_info = { .inverted_a = 0, .inverted_b = 0, .half_period = false, + .wakeup_source = false, }; static struct platform_device rotary_encoder_device = { diff --git a/Documentation/input/userio.txt b/Documentation/input/userio.txt new file mode 100644 index 000000000000..0880c0f447a6 --- /dev/null +++ b/Documentation/input/userio.txt @@ -0,0 +1,70 @@ + The userio Protocol + (c) 2015 Stephen Chandler Paul <thatslyude@gmail.com> + Sponsored by Red Hat +-------------------------------------------------------------------------------- + +1. Introduction +~~~~~~~~~~~~~~~ + This module is intended to try to make the lives of input driver developers +easier by allowing them to test various serio devices (mainly the various +touchpads found on laptops) without having to have the physical device in front +of them. userio accomplishes this by allowing any privileged userspace program +to directly interact with the kernel's serio driver and control a virtual serio +port from there. + +2. Usage overview +~~~~~~~~~~~~~~~~~ + In order to interact with the userio kernel module, one simply opens the +/dev/userio character device in their applications. Commands are sent to the +kernel module by writing to the device, and any data received from the serio +driver is read as-is from the /dev/userio device. All of the structures and +macros you need to interact with the device are defined in <linux/userio.h> and +<linux/serio.h>. + +3. Command Structure +~~~~~~~~~~~~~~~~~~~~ + The struct used for sending commands to /dev/userio is as follows: + + struct userio_cmd { + __u8 type; + __u8 data; + }; + + "type" describes the type of command that is being sent. This can be any one +of the USERIO_CMD macros defined in <linux/userio.h>. "data" is the argument +that goes along with the command. In the event that the command doesn't have an +argument, this field can be left untouched and will be ignored by the kernel. +Each command should be sent by writing the struct directly to the character +device. In the event that the command you send is invalid, an error will be +returned by the character device and a more descriptive error will be printed +to the kernel log. Only one command can be sent at a time, any additional data +written to the character device after the initial command will be ignored. + To close the virtual serio port, just close /dev/userio. + +4. Commands +~~~~~~~~~~~ + +4.1 USERIO_CMD_REGISTER +~~~~~~~~~~~~~~~~~~~~~~~ + Registers the port with the serio driver and begins transmitting data back and +forth. Registration can only be performed once a port type is set with +USERIO_CMD_SET_PORT_TYPE. Has no argument. + +4.2 USERIO_CMD_SET_PORT_TYPE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Sets the type of port we're emulating, where "data" is the port type being +set. Can be any of the macros from <linux/serio.h>. For example: SERIO_8042 +would set the port type to be a normal PS/2 port. + +4.3 USERIO_CMD_SEND_INTERRUPT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Sends an interrupt through the virtual serio port to the serio driver, where +"data" is the interrupt data being sent. + +5. Userspace tools +~~~~~~~~~~~~~~~~~~ + The userio userspace tools are able to record PS/2 devices using some of the +debugging information from i8042, and play back the devices on /dev/userio. The +latest version of these tools can be found at: + + https://github.com/Lyude/ps2emu diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index 45fe78c58019..cc30b14791cb 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -122,7 +122,7 @@ Time, Waiting and Missing it ---------------------------- GPUs do most everything asynchronously, so we have a need to time operations and -wait for oustanding ones. This is really tricky business; at the moment none of +wait for outstanding ones. This is really tricky business; at the moment none of the ioctls supported by the drm/i915 get this fully right, which means there's still tons more lessons to learn here. @@ -146,7 +146,7 @@ still tons more lessons to learn here. ioctl restartable relative timeouts tend to be too coarse and can indefinitely extend your wait time due to rounding on each restart. Especially if your reference clock is something really slow like the display - frame counter. With a spec laywer hat on this isn't a bug since timeouts can + frame counter. With a spec lawyer hat on this isn't a bug since timeouts can always be extended - but users will surely hate you if their neat animations starts to stutter due to this. @@ -176,7 +176,7 @@ entails its own little set of pitfalls: * Ensure that you have sufficient insulation between different clients. By default pick a private per-fd namespace which forces any sharing to be done - explictly. Only go with a more global per-device namespace if the objects + explicitly. Only go with a more global per-device namespace if the objects are truly device-unique. One counterexample in the drm modeset interfaces is that the per-device modeset objects like connectors share a namespace with framebuffer objects, which mostly are not shared at all. A separate diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index df1b25eb8382..9369d3b0f09a 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -81,6 +81,9 @@ Code Seq#(hex) Include File Comments 0x22 all scsi/sg.h '#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem '$' 00-0F linux/perf_counter.h, linux/perf_event.h +'%' 00-0F include/uapi/linux/stm.h + System Trace Module subsystem + <mailto:alexander.shishkin@linux.intel.com> '&' 00-07 drivers/firewire/nosy-user.h '1' 00-1F <linux/timepps.h> PPS kit from Ulrich Windl <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/> @@ -149,6 +152,7 @@ Code Seq#(hex) Include File Comments 'K' all linux/kd.h 'L' 00-1F linux/loop.h conflict! 'L' 10-1F drivers/scsi/mpt2sas/mpt2sas_ctl.h conflict! +'L' 20-2F linux/lightnvm.h 'L' E0-FF linux/ppdd.h encrypted disk device driver <http://linux01.gwdg.de/~alatham/ppdd.html> 'M' all linux/soundcard.h conflict! @@ -315,6 +319,7 @@ Code Seq#(hex) Include File Comments <mailto:vgo@ratio.de> 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> 0xB3 00 linux/mmc/ioctl.h +0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h 0xCA 80-8F uapi/scsi/cxlflash_ioctl.h diff --git a/Documentation/isdn/00-INDEX b/Documentation/isdn/00-INDEX index e87e336f590e..2d1889b6c1fa 100644 --- a/Documentation/isdn/00-INDEX +++ b/Documentation/isdn/00-INDEX @@ -16,8 +16,6 @@ README.FAQ - general info for FAQ. README.HiSax - info on the HiSax driver which replaces the old teles. -README.act2000 - - info on driver for IBM ACT-2000 card. README.audio - info for running audio over ISDN. README.avmb1 @@ -34,14 +32,8 @@ README.hfc-pci - info on hfc-pci based cards. README.hysdn - info on driver for Hypercope active HYSDN cards -README.icn - - info on the ICN-ISDN-card and its driver. README.mISDN - info on the Modular ISDN subsystem (mISDN) -README.pcbit - - info on the PCBIT-D ISDN adapter and driver. -README.sc - - info on driver for Spellcaster cards. README.syncppp - info on running Sync PPP over ISDN. README.x25 diff --git a/Documentation/isdn/README.act2000 b/Documentation/isdn/README.act2000 deleted file mode 100644 index ce7115e7f4ce..000000000000 --- a/Documentation/isdn/README.act2000 +++ /dev/null @@ -1,104 +0,0 @@ -$Id: README.act2000,v 1.3 2000/08/06 09:22:51 armin Exp $ - -This document describes the ACT2000 driver for the -IBM Active 2000 ISDN card. - -There are 3 Types of this card available. A ISA-, MCA-, and PCMCIA-Bus -Version. Currently, only the ISA-Bus version of the card is supported. -However MCA and PCMCIA will follow soon. - -The ISA-Bus Version uses 8 IO-ports. The base port address has to be set -manually using the DIP switches. - -Setting up the DIP switches for the IBM Active 2000 ISDN card: - - Note: S5 and S6 always set off! - - S1 S2 S3 S4 Base-port - on on on on 0x0200 (Factory default) - off on on on 0x0240 - on off on on 0x0280 - off off on on 0x02c0 - on on off on 0x0300 - off on off on 0x0340 - on off off on 0x0380 - on on on off 0xcfe0 - off on on off 0xcfa0 - on off on off 0xcf60 - off off on off 0xcf20 - on on off off 0xcee0 - off on off off 0xcea0 - on off off off 0xce60 - off off off off Card disabled - -IRQ is configured by software. Possible values are: - - 3, 5, 7, 10, 11, 12, 15 and none (polled mode) - - -The ACT2000 driver may either be built into the kernel or as a module. -Initialization depends on how the driver is built: - -Driver built into the kernel: - - The ACT2000 driver can be configured using the commandline-feature while - loading the kernel with LILO or LOADLIN. It accepts the following syntax: - - act2000=b,p,i[,idstring] - - where - - b = Bus-Type (1=ISA, 2=MCA, 3=PCMCIA) - p = portbase (-1 means autoprobe) - i = Interrupt (-1 means use next free IRQ, 0 means polled mode) - - The idstring is an arbitrary string used for referencing the card - by the actctrl tool later. - - Defaults used, when no parameters given at all: - - 1,-1,-1,"" - - which means: Autoprobe for an ISA card, use next free IRQ, let the - ISDN linklevel fill the IdString (usually "line0" for the first card). - - If you like to use more than one card, you can use the program - "actctrl" from the utility-package to configure additional cards. - - Using the "actctrl"-utility, portbase and irq can also be changed - during runtime. The D-channel protocol is configured by the "dproto" - option of the "actctrl"-utility after loading the firmware into the - card's memory using the "actctrl"-utility. - -Driver built as module: - - The module act2000.o can be configured during modprobe (insmod) by - appending its parameters to the modprobe resp. insmod commandline. - The following syntax is accepted: - - act_bus=b act_port=p act_irq=i act_id=idstring - - where b, p, i and idstring have the same meanings as the parameters - described for the builtin version above. - - Using the "actctrl"-utility, the same features apply to the modularized - version as to the kernel-builtin one. (i.e. loading of firmware and - configuring the D-channel protocol) - -Loading the firmware into the card: - - The firmware is supplied together with the isdn4k-utils package. It - can be found in the subdirectory act2000/firmware/ - - Assuming you have installed the utility-package correctly, the firmware - will be downloaded into the card using the following command: - - actctrl -d idstring load /etc/isdn/bip11.btl - - where idstring is the Name of the card, given during insmod-time or - (for kernel-builtin driver) on the kernel commandline. If only one - ISDN card is used, the -d isdstrin may be omitted. - - For further documentation (adding more IBM Active 2000 cards), refer to - the manpage actctrl.8 which is included in the isdn4k-utils package. - diff --git a/Documentation/isdn/README.icn b/Documentation/isdn/README.icn deleted file mode 100644 index 13f833d4e910..000000000000 --- a/Documentation/isdn/README.icn +++ /dev/null @@ -1,148 +0,0 @@ -$Id: README.icn,v 1.7 2000/08/06 09:22:51 armin Exp $ - -You can get the ICN-ISDN-card from: - -Thinking Objects Software GmbH -Versbacher Röthe 159 -97078 Würzburg -Tel: +49 931 2877950 -Fax: +49 931 2877951 - -email info@think.de -WWW http:/www.think.de - - -The card communicates with the PC by two interfaces: - 1. A range of 4 successive port-addresses, whose base address can be - configured with the switches. - 2. A memory window with 16KB-256KB size, which can be setup in 16k steps - over the whole range of 16MB. Isdn4linux only uses a 16k window. - The base address of the window can be configured when loading - the lowlevel-module (see README). If using more than one card, - all cards are mapped to the same window and activated as needed. - -Setting up the IO-address dipswitches for the ICN-ISDN-card: - - Two types of cards exist, one with dip-switches and one with - hook-switches. - - 1. Setting for the card with hook-switches: - - (0 = switch closed, 1 = switch open) - - S3 S2 S1 Base-address - 0 0 0 0x300 - 0 0 1 0x310 - 0 1 0 0x320 (Default for isdn4linux) - 0 1 1 0x330 - 1 0 0 0x340 - 1 0 1 0x350 - 1 1 0 0x360 - 1 1 1 NOT ALLOWED! - - 2. Setting for the card with dip-switches: - - (0 = switch closed, 1 = switch open) - - S1 S2 S3 S4 Base-Address - 0 0 0 0 0x300 - 0 0 0 1 0x310 - 0 0 1 0 0x320 (Default for isdn4linux) - 0 0 1 1 0x330 - 0 1 0 0 0x340 - 0 1 0 1 0x350 - 0 1 1 0 0x360 - 0 1 1 1 NOT ALLOWED! - 1 0 0 0 0x308 - 1 0 0 1 0x318 - 1 0 1 0 0x328 - 1 0 1 1 0x338 - 1 1 0 0 0x348 - 1 1 0 1 0x358 - 1 1 1 0 0x368 - 1 1 1 1 NOT ALLOWED! - -The ICN driver may be built into the kernel or as a module. Initialization -depends on how the driver is built: - -Driver built into the kernel: - - The ICN driver can be configured using the commandline-feature while - loading the kernel with LILO or LOADLIN. It accepts the following syntax: - - icn=p,m[,idstring1[,idstring2]] - - where - - p = portbase (default: 0x320) - m = shared memory (default: 0xd0000) - - When using the ICN double card (4B), you MUST define TWO idstrings. - idstring must start with a character! There is no way for the driver - to distinguish between a 2B and 4B type card. Therefore, by supplying - TWO idstrings, you tell the driver that you have a 4B installed. - - If you like to use more than one card, you can use the program - "icnctrl" from the utility-package to configure additional cards. - You need to configure shared memory only once, since the icn-driver - maps all cards into the same address-space. - - Using the "icnctrl"-utility, portbase and shared memory can also be - changed during runtime. - - The D-channel protocol is configured by loading different firmware - into the card's memory using the "icnctrl"-utility. - - -Driver built as module: - - The module icn.o can be configured during "insmod'ing" it by - appending its parameters to the insmod-commandline. The following - syntax is accepted: - - portbase=p membase=m icn_id=idstring [icn_id2=idstring2] - - where p, m, idstring1 and idstring2 have the same meanings as the - parameters described for the kernel-version above. - - When using the ICN double card (4B), you MUST define TWO idstrings. - idstring must start with a character! There is no way for the driver - to distinguish between a 2B and 4B type card. Therefore, by supplying - TWO idstrings, you tell the driver that you have a 4B installed. - - Using the "icnctrl"-utility, the same features apply to the modularized - version like to the kernel-builtin one. - - The D-channel protocol is configured by loading different firmware - into the card's memory using the "icnctrl"-utility. - -Loading the firmware into the card: - - The firmware is supplied together with the isdn4k-utils package. It - can be found in the subdirectory icnctrl/firmware/ - - There are 3 files: - - loadpg.bin - Image of the bootstrap loader. - pc_1t_ca.bin - Image of firmware for german 1TR6 protocol. - pc_eu_ca.bin - Image if firmware for EDSS1 (Euro-ISDN) protocol. - - Assuming you have installed the utility-package correctly, the firmware - will be downloaded into the 2B-card using the following command: - - icnctrl -d Idstring load /etc/isdn/loadpg.bin /etc/isdn/pc_XX_ca.bin - - where XX is either "1t" or "eu", depending on the D-Channel protocol - used on your S0-bus and Idstring is the Name of the card, given during - insmod-time or (for kernel-builtin driver) on the kernel commandline. - - To load a 4B-card, the same command is used, except a second firmware - file is appended to the commandline of icnctrl. - - -> After downloading firmware, the two LEDs at the back cover of the card - (ICN-4B: 4 LEDs) must be blinking intermittently now. If a connection - is up, the corresponding led is lit continuously. - - For further documentation (adding more ICN-cards), refer to the manpage - icnctrl.8 which is included in the isdn4k-utils package. - diff --git a/Documentation/isdn/README.pcbit b/Documentation/isdn/README.pcbit deleted file mode 100644 index 5125002282e5..000000000000 --- a/Documentation/isdn/README.pcbit +++ /dev/null @@ -1,40 +0,0 @@ ------------------------------------------------------------------------------- - README file for the PCBIT-D Device Driver. ------------------------------------------------------------------------------- - -The PCBIT is a Euro ISDN adapter manufactured in Portugal by Octal and -developed in cooperation with Portugal Telecom and Inesc. -The driver interfaces with the standard kernel isdn facilities -originally developed by Fritz Elfert in the isdn4linux project. - -The common versions of the pcbit board require a firmware that is -distributed (and copyrighted) by the manufacturer. To load this -firmware you need "pcbitctl" available on the standard isdn4k-utils -package or in the pcbit package available in: - -ftp://ftp.di.fc.ul.pt/pub/systems/Linux/isdn - -Known Limitations: - -- The board reset procedure is at the moment incorrect and will only -allow you to load the firmware after a hard reset. - -- Only HDLC in B-channels is supported at the moment. There is no -current support for X.25 in B or D channels nor LAPD in B -channels. The main reason is that these two other protocol modes have, -to my knowledge, very little use. If you want to see them implemented -*do* send me a mail. - -- The driver often triggers errors in the board that I and the -manufacturer believe to be caused by bugs in the firmware. The current -version includes several procedures for error recovery that should -allow normal operation. Plans for the future include cooperation with -the manufacturer in order to solve this problem. - -Information/hints/help can be obtained in the linux isdn -mailing list (isdn4linux@listserv.isdn4linux.de) or directly from me. - -regards, - Pedro. - -<roque@di.fc.ul.pt> diff --git a/Documentation/isdn/README.sc b/Documentation/isdn/README.sc deleted file mode 100644 index 1153cd926059..000000000000 --- a/Documentation/isdn/README.sc +++ /dev/null @@ -1,281 +0,0 @@ -Welcome to Beta Release 2 of the combination ISDN driver for SpellCaster's -ISA ISDN adapters. Please note this release 2 includes support for the -DataCommute/BRI and TeleCommute/BRI adapters only and any other use is -guaranteed to fail. If you have a DataCommute/PRI installed in the test -computer, we recommend removing it as it will be detected but will not -be usable. To see what we have done to Beta Release 2, see section 3. - -Speaking of guarantees, THIS IS BETA SOFTWARE and as such contains -bugs and defects either known or unknown. Use this software at your own -risk. There is NO SUPPORT for this software. Some help may be available -through the web site or the mailing list but such support is totally at -our own option and without warranty. If you choose to assume all and -total risk by using this driver, we encourage you to join the beta -mailing list. - -To join the Linux beta mailing list, send a message to: -majordomo@spellcast.com with the words "subscribe linux-beta" as the only -contents of the message. Do not include a signature. If you choose to -remove yourself from this list at a later date, send another message to -the same address with the words "unsubscribe linux-beta" as its only -contents. - -TABLE OF CONTENTS ------------------ - 1. Introduction - 1.1 What is ISDN4Linux? - 1.2 What is different between this driver and previous drivers? - 1.3 How do I setup my system with the correct software to use - this driver release? - - 2. Basic Operations - 2.1 Unpacking and installing the driver - 2.2 Read the man pages!!! - 2.3 Installing the driver - 2.4 Removing the driver - 2.5 What to do if it doesn't load - 2.6 How to setup ISDN4Linux with the driver - - 3. Beta Change Summaries and Miscellaneous Notes - -1. Introduction ---------------- - -The revision 2 Linux driver for SpellCaster ISA ISDN adapters is built -upon ISDN4Linux available separately or as included in Linux 2.0 and later. -The driver will support a maximum of 4 adapters in any one system of any -type including DataCommute/BRI, DataCommute/PRI and TeleCommute/BRI for a -maximum of 92 channels for host. The driver is supplied as a module in -source form and needs to be complied before it can be used. It has been -tested on Linux 2.0.20. - -1.1 What Is ISDN4Linux - -ISDN4Linux is a driver and set of tools used to access and use ISDN devices -on a Linux platform in a common and standard way. It supports HDLC and PPP -protocols and offers channel bundling and MLPPP support. To use ISDN4Linux -you need to configure your kernel for ISDN support and get the ISDN4Linux -tool kit from our web site. - -ISDN4Linux creates a channel pool from all of the available ISDN channels -and therefore can function across adapters. When an ISDN4Linux compliant -driver (such as ours) is loaded, all of the channels go into a pool and -are used on a first-come first-served basis. In addition, individual -channels can be specifically bound to particular interfaces. - -1.2 What is different between this driver and previous drivers? - -The revision 2 driver besides adopting the ISDN4Linux architecture has many -subtle and not so subtle functional differences from previous releases. These -include: - - More efficient shared memory management combined with a simpler - configuration. All adapters now use only 16Kbytes of shared RAM - versus between 16K and 64K. New methods for using the shared RAM - allow us to utilize all of the available RAM on the adapter through - only one 16K page. - - Better detection of available upper memory. The probing routines - have been improved to better detect available shared RAM pages and - used pages are now locked. - - Decreased loading time and a wider range of I/O ports probed. - We have significantly reduced the amount of time it takes to load - the driver and at the same time doubled the number of I/O ports - probed increasing the likelihood of finding an adapter. - - We now support all ISA adapter models with a single driver instead - of separate drivers for each model. The revision 2 driver supports - the DataCommute/BRI, DataCommute/PRI and TeleCommute/BRI in any - combination up to a maximum of four adapters per system. - - On board PPP protocol support has been removed in favour of the - sync-PPP support used in ISDN4Linux. This means more control of - the protocol parameters, faster negotiation time and a more - familiar interface. - -1.3 How do I setup my system with the correct software to use - this driver release? - -Before you can compile, install and use the SpellCaster ISA ISDN driver, you -must ensure that the following software is installed, configured and running: - - - Linux kernel 2.0.20 or later with the required init and ps - versions. Please see your distribution vendor for the correct - utility packages. The latest kernel is available from - ftp://sunsite.unc.edu/pub/Linux/kernel/v2.0/ - - - The latest modules package (modules-2.0.0.tar.gz) from - ftp://sunsite.unc.edu/pub/Linux/kernel/modules-2.0.0.tar.gz - - - The ISDN4Linux tools available from - ftp://ftp.franken.de/pub/isdn4linux/v2.0/isdn4k-utils-2.0.tar.gz - This package may fail to compile for you so you can alternatively - get a pre-compiled version from - ftp://ftp.spellcast.com/pub/drivers/isdn4linux/isdn4k-bin-2.0.tar.gz - - -2. Basic Operations -------------------- - -2.1 Unpacking and installing the driver - - 1. As root, create a directory in a convenient place. We suggest - /usr/src/spellcaster. - - 2. Unpack the archive with : - tar xzf sc-n.nn.tar.gz -C /usr/src/spellcaster - - 3. Change directory to /usr/src/spellcaster - - 4. Read the README and RELNOTES files. - - 5. Run 'make' and if all goes well, run 'make install'. - -2.2 Read the man pages!!! - -Make sure you read the scctrl(8) and sc(4) manual pages before continuing -any further. Type 'man 8 scctrl' and 'man 4 sc'. - -2.3 Installing the driver - -To install the driver, type '/sbin/insmod sc' as root. sc(4) details options -you can specify but you shouldn't need to use any unless this doesn't work. - -Make sure the driver loaded and detected all of the adapters by typing -'dmesg'. - -The driver can be configured so that it is loaded upon startup. To do this, -edit the file "/etc/modules/'uname -f'/'uname -v'" and insert the driver name -"sc" into this file. - -2.4 Removing the driver - -To remove the driver, delete any interfaces that may exist (see isdnctrl(8) -for more on this) and then type '/sbin/rmmod sc'. - -2.5 What to do if it doesn't load - -If, when you try to install the driver, you get a message mentioning -'register_isdn' then you do not have the ISDN4Linux system installed. Please -make sure that ISDN support is configured in the kernel. - -If you get a message that says 'initialization of sc failed', then the -driver failed to detect an adapter or failed to find resources needed such -as a free IRQ line or shared memory segment. If you are sure there are free -resources available, use the insmod options detailed in sc(4) to override -the probing function. - -Upon testing, the following problem was noted, the driver would load without -problems, but the board would not respond beyond that point. When a check was -done with 'cat /proc/interrupts' the interrupt count for sc was 0. In the event -of this problem, change the BIOS settings so that the interrupts in question are -reserved for ISA use only. - - -2.6 How to setup ISDN4Linux with the driver - -There are three main configurations which you can use with the driver: - -A) Basic HDLC connection -B) PPP connection -C) MLPPP connection - -It should be mentioned here that you may also use a tty connection if you -desire. The Documentation directory of the isdn4linux subsystem offers good -documentation on this feature. - -A) 10 steps to the establishment of a basic HDLC connection ------------------------------------------------------------ - -- please open the isdn-hdlc file in the examples directory and follow along... - - This file is a script used to configure a BRI ISDN TA to establish a - basic HDLC connection between its two channels. Two network - interfaces are created and two routes added between the channels. - - i) using the isdnctrl utility, add an interface with "addif" and - name it "isdn0" - ii) add the outgoing and inbound telephone numbers - iii) set the Layer 2 protocol to hdlc - iv) set the eaz of the interface to be the phone number of that - specific channel - v) to turn the callback features off, set the callback to "off" and - the callback delay (cbdelay) to 0. - vi) the hangup timeout can be set to a specified number of seconds - vii) the hangup upon incoming call can be set on or off - viii) use the ifconfig command to bring up the network interface with - a specific IP address and point to point address - ix) add a route to the IP address through the isdn0 interface - x) a ping should result in the establishment of the connection - - -B) Establishment of a PPP connection ------------------------------------- - -- please open the isdn-ppp file in the examples directory and follow along... - - This file is a script used to configure a BRI ISDN TA to establish a - PPP connection between the two channels. The file is almost - identical to the HDLC connection example except that the packet - encapsulation type has to be set. - - use the same procedure as in the HDLC connection from steps i) to - iii) then, after the Layer 2 protocol is set, set the encapsulation - "encap" to syncppp. With this done, the rest of the steps, iv) to x) - can be followed from above. - - Then, the ipppd (ippp daemon) must be setup: - - xi) use the ipppd function found in /sbin/ipppd to set the following: - xii) take out (minus) VJ compression and bsd compression - xiii) set the mru size to 2000 - xiv) link the two /dev interfaces to the daemon - -NOTE: A "*" in the inbound telephone number specifies that a call can be -accepted on any number. - -C) Establishment of a MLPPP connection --------------------------------------- - -- please open the isdn-mppp file in the examples directory and follow along... - - This file is a script used to configure a BRI ISDN TA to accept a - Multi Link PPP connection. - - i) using the isdnctrl utility, add an interface with "addif" and - name it "ippp0" - ii) add the inbound telephone number - iii) set the Layer 2 protocol to hdlc and the Layer 3 protocol to - trans (transparent) - iv) set the packet encapsulation to syncppp - v) set the eaz of the interface to be the phone number of that - specific channel - vi) to turn the callback features off, set the callback to "off" and - the callback delay (cbdelay) to 0. - vi) the hangup timeout can be set to a specified number of seconds - vii) the hangup upon incoming call can be set on or off - viii) add a slave interface and name it "ippp32" for example - ix) set the similar parameters for the ippp32 interface - x) use the ifconfig command to bring-up the ippp0 interface with a - specific IP address and point to point address - xi) add a route to the IP address through the ippp0 interface - xii) use the ipppd function found in /sbin/ipppd to set the following: - xiii) take out (minus) bsd compression - xiv) set the mru size to 2000 - xv) add (+) the multi-link function "+mp" - xvi) link the two /dev interfaces to the daemon - -NOTE: To use the MLPPP connection to dial OUT to a MLPPP connection, change -the inbound telephone numbers to the outgoing telephone numbers of the MLPPP -host. - - -3. Beta Change Summaries and Miscellaneous Notes ------------------------------------------------- -When using the "scctrl" utility to upload firmware revisions on the board, -please note that the byte count displayed at the end of the operation may be -different from the total number of bytes in the "dcbfwn.nn.sr" file. Please -disregard the displayed byte count. - -It was noted that in Beta Release 1, the module would fail to load and result -in a segmentation fault when 'insmod'ed. This problem was created when one of -the isdn4linux parameters, (isdn_ctrl, data field) was filled in. In some -cases, this data field was NULL, and was left unchecked, so when it was -referenced... segv. The bug has been fixed around line 63-68 of event.c. - diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index 5a0f2bdc2cf9..52ef02b33da9 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -245,7 +245,7 @@ Linux カーネルソースツリーの中に含まれる、きれいにし、 自己参照方式で、索引がついた web 形式で、ソースコードを参照することが できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり ます- - http://lxr.linux.no/+trees + http://lxr.free-electrons.com/ 開発プロセス ----------------------- @@ -366,7 +366,6 @@ http://patchwork.kernel.org/ でリストされています。 に全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリ ポジトリが存在します- http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git - http://linux.f-seidel.de/linux-next/pmwiki/ このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン ラインカーネルにマージされるか、おおまかなの展望を提供します。-next @@ -441,7 +440,7 @@ MAINTAINERS ファイルにリストがありますので参照してくださ てこの状態を変えようとしないように。人々はそのようなことは好みません。 今までのメールでのやりとりとその間のあなたの発言はそのまま残し、 -"John Kernlehacker wrote ...:" の行をあなたのリプライの先頭行にして、 +"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、 メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで す。 diff --git a/Documentation/kasan.txt b/Documentation/kasan.txt index 0d32355a4c34..aa1e0c91e368 100644 --- a/Documentation/kasan.txt +++ b/Documentation/kasan.txt @@ -1,36 +1,34 @@ -Kernel address sanitizer -================ +KernelAddressSanitizer (KASAN) +============================== 0. Overview =========== -Kernel Address sanitizer (KASan) is a dynamic memory error detector. It provides +KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides a fast and comprehensive solution for finding use-after-free and out-of-bounds bugs. -KASan uses compile-time instrumentation for checking every memory access, -therefore you will need a gcc version of 4.9.2 or later. KASan could detect out -of bounds accesses to stack or global variables, but only if gcc 5.0 or later was -used to built the kernel. +KASAN uses compile-time instrumentation for checking every memory access, +therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is +required for detection of out-of-bounds accesses to stack or global variables. -Currently KASan is supported only for x86_64 architecture and requires that the -kernel be built with the SLUB allocator. +Currently KASAN is supported only for x86_64 architecture and requires the +kernel to be built with the SLUB allocator. 1. Usage -========= +======== To enable KASAN configure kernel with: CONFIG_KASAN = y -and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline/inline -is compiler instrumentation types. The former produces smaller binary the -latter is 1.1 - 2 times faster. Inline instrumentation requires a gcc version -of 5.0 or later. +and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and +inline are compiler instrumentation types. The former produces smaller binary +the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC +version 5.0 or later. Currently KASAN works only with the SLUB memory allocator. -For better bug detection and nicer report, enable CONFIG_STACKTRACE and put -at least 'slub_debug=U' in the boot cmdline. +For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. To disable instrumentation for specific files or directories, add a line similar to the following to the respective kernel Makefile: @@ -42,7 +40,7 @@ similar to the following to the respective kernel Makefile: KASAN_SANITIZE := n 1.1 Error reports -========== +================= A typical out of bounds access report looks like this: @@ -119,14 +117,16 @@ Memory state around the buggy address: ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb ================================================================== -First sections describe slub object where bad access happened. -See 'SLUB Debug output' section in Documentation/vm/slub.txt for details. +The header of the report discribe what kind of bug happened and what kind of +access caused it. It's followed by the description of the accessed slub object +(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and +the description of the accessed memory page. In the last section the report shows memory state around the accessed address. -Reading this part requires some more understanding of how KASAN works. +Reading this part requires some understanding of how KASAN works. -Each 8 bytes of memory are encoded in one shadow byte as accessible, -partially accessible, freed or they can be part of a redzone. +The state of each 8 aligned bytes of memory is encoded in one shadow byte. +Those 8 bytes can be accessible, partially accessible, freed or be a redzone. We use the following encoding for each shadow byte: 0 means that all 8 bytes of the corresponding memory region are accessible; number N (1 <= N <= 7) means that the first N bytes are accessible, and other (8 - N) bytes are not; @@ -139,7 +139,7 @@ the accessed address is partially accessible. 2. Implementation details -======================== +========================= From a high level, our approach to memory error detection is similar to that of kmemcheck: use shadow memory to record whether each byte of memory is safe diff --git a/Documentation/kbuild/Kconfig.recursion-issue-01 b/Documentation/kbuild/Kconfig.recursion-issue-01 new file mode 100644 index 000000000000..e8877db0461f --- /dev/null +++ b/Documentation/kbuild/Kconfig.recursion-issue-01 @@ -0,0 +1,57 @@ +# Simple Kconfig recursive issue +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# +# Test with: +# +# make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig +# +# This Kconfig file has a simple recursive dependency issue. In order to +# understand why this recursive dependency issue occurs lets consider what +# Kconfig needs to address. We iterate over what Kconfig needs to address +# by stepping through the questions it needs to address sequentially. +# +# * What values are possible for CORE? +# +# CORE_BELL_A_ADVANCED selects CORE, which means that it influences the values +# that are possible for CORE. So for example if CORE_BELL_A_ADVANCED is 'y', +# CORE must be 'y' too. +# +# * What influences CORE_BELL_A_ADVANCED ? +# +# As the name implies CORE_BELL_A_ADVANCED is an advanced feature of +# CORE_BELL_A so naturally it depends on CORE_BELL_A. So if CORE_BELL_A is 'y' +# we know CORE_BELL_A_ADVANCED can be 'y' too. +# +# * What influences CORE_BELL_A ? +# +# CORE_BELL_A depends on CORE, so CORE influences CORE_BELL_A. +# +# But that is a problem, because this means that in order to determine +# what values are possible for CORE we ended up needing to address questions +# regarding possible values of CORE itself again. Answering the original +# question of what are the possible values of CORE would make the kconfig +# tools run in a loop. When this happens Kconfig exits and complains about +# the "recursive dependency detected" error. +# +# Reading the Documentation/kbuild/Kconfig.recursion-issue-01 file it may be +# obvious that an easy to solution to this problem should just be the removal +# of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already +# since CORE_BELL_A depends on CORE. Recursive dependency issues are not always +# so trivial to resolve, we provide another example below of practical +# implications of this recursive issue where the solution is perhaps not so +# easy to understand. Note that matching semantics on the dependency on +# CORE also consist of a solution to this recursive problem. + +mainmenu "Simple example to demo kconfig recursive dependency issue" + +config CORE + tristate + +config CORE_BELL_A + tristate + depends on CORE + +config CORE_BELL_A_ADVANCED + tristate + depends on CORE_BELL_A + select CORE diff --git a/Documentation/kbuild/Kconfig.recursion-issue-02 b/Documentation/kbuild/Kconfig.recursion-issue-02 new file mode 100644 index 000000000000..b9fd56c4b57e --- /dev/null +++ b/Documentation/kbuild/Kconfig.recursion-issue-02 @@ -0,0 +1,63 @@ +# Cumulative Kconfig recursive issue +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# +# Test with: +# +# make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig +# +# The recursive limitations with Kconfig has some non intuitive implications on +# kconfig sematics which are documented here. One known practical implication +# of the recursive limitation is that drivers cannot negate features from other +# drivers if they share a common core requirement and use disjoint semantics to +# annotate those requirements, ie, some drivers use "depends on" while others +# use "select". For instance it means if a driver A and driver B share the same +# core requirement, and one uses "select" while the other uses "depends on" to +# annotate this, all features that driver A selects cannot now be negated by +# driver B. +# +# A perhaps not so obvious implication of this is that, if semantics on these +# core requirements are not carefully synced, as drivers evolve features +# they select or depend on end up becoming shared requirements which cannot be +# negated by other drivers. +# +# The example provided in Documentation/kbuild/Kconfig.recursion-issue-02 +# describes a simple driver core layout of example features a kernel might +# have. Let's assume we have some CORE functionality, then the kernel has a +# series of bells and whistles it desires to implement, its not so advanced so +# it only supports bells at this time: CORE_BELL_A and CORE_BELL_B. If +# CORE_BELL_A has some advanced feature CORE_BELL_A_ADVANCED which selects +# CORE_BELL_A then CORE_BELL_A ends up becoming a common BELL feature which +# other bells in the system cannot negate. The reason for this issue is +# due to the disjoint use of semantics on expressing each bell's relationship +# with CORE, one uses "depends on" while the other uses "select". Another +# more important reason is that kconfig does not check for dependencies listed +# under 'select' for a symbol, when such symbols are selected kconfig them +# as mandatory required symbols. For more details on the heavy handed nature +# of select refer to Documentation/kbuild/Kconfig.select-break +# +# To fix this the "depends on CORE" must be changed to "select CORE", or the +# "select CORE" must be changed to "depends on CORE". +# +# For an example real world scenario issue refer to the attempt to remove +# "select FW_LOADER" [0], in the end the simple alternative solution to this +# problem consisted on matching semantics with newly introduced features. +# +# [0] http://lkml.kernel.org/r/1432241149-8762-1-git-send-email-mcgrof@do-not-panic.com + +mainmenu "Simple example to demo cumulative kconfig recursive dependency implication" + +config CORE + tristate + +config CORE_BELL_A + tristate + depends on CORE + +config CORE_BELL_A_ADVANCED + tristate + select CORE_BELL_A + +config CORE_BELL_B + tristate + depends on !CORE_BELL_A + select CORE diff --git a/Documentation/kbuild/Kconfig.select-break b/Documentation/kbuild/Kconfig.select-break new file mode 100644 index 000000000000..365ceb3424b1 --- /dev/null +++ b/Documentation/kbuild/Kconfig.select-break @@ -0,0 +1,33 @@ +# Select broken dependency issue +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# +# Test with: +# +# make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.select-break menuconfig +# +# kconfig will not complain and enable this layout for configuration. This is +# currently a feature of kconfig, given select was designed to be heavy handed. +# Kconfig currently does not check the list of symbols listed on a symbol's +# "select" list, this is done on purpose to help load a set of known required +# symbols. Because of this use of select should be used with caution. An +# example of this issue is below. +# +# The option B and C are clearly contradicting with respect to A. +# However, when A is set, C can be set as well because Kconfig does not +# visit the dependencies of the select target (in this case B). And since +# Kconfig does not visit the dependencies, it breaks the dependencies of B +# (!A). + +mainmenu "Simple example to demo kconfig select broken dependency issue" + +config A + bool "CONFIG A" + +config B + bool "CONFIG B" + depends on !A + +config C + bool "CONFIG C" + depends on A + select B diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index 350f733bf2c7..c52856da0cad 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -393,3 +393,164 @@ config FOO depends on BAR && m limits FOO to module (=m) or disabled (=n). + +Kconfig recursive dependency limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you've hit the Kconfig error: "recursive dependency detected" you've run +into a recursive dependency issue with Kconfig, a recursive dependency can be +summarized as a circular dependency. The kconfig tools need to ensure that +Kconfig files comply with specified configuration requirements. In order to do +that kconfig must determine the values that are possible for all Kconfig +symbols, this is currently not possible if there is a circular relation +between two or more Kconfig symbols. For more details refer to the "Simple +Kconfig recursive issue" subsection below. Kconfig does not do recursive +dependency resolution; this has a few implications for Kconfig file writers. +We'll first explain why this issues exists and then provide an example +technical limitation which this brings upon Kconfig developers. Eager +developers wishing to try to address this limitation should read the next +subsections. + +Simple Kconfig recursive issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read: Documentation/kbuild/Kconfig.recursion-issue-01 + +Test with: + +make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig + +Cumulative Kconfig recursive issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read: Documentation/kbuild/Kconfig.recursion-issue-02 + +Test with: + +make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig + +Practical solutions to kconfig recursive issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developers who run into the recursive Kconfig issue have three options +at their disposal. We document them below and also provide a list of +historical issues resolved through these different solutions. + + a) Remove any superfluous "select FOO" or "depends on FOO" + b) Match dependency semantics: + b1) Swap all "select FOO" to "depends on FOO" or, + b2) Swap all "depends on FOO" to "select FOO" + +The resolution to a) can be tested with the sample Kconfig file +Documentation/kbuild/Kconfig.recursion-issue-01 through the removal +of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already +since CORE_BELL_A depends on CORE. At times it may not be possible to remove +some dependency criteria, for such cases you can work with solution b). + +The two different resolutions for b) can be tested in the sample Kconfig file +Documentation/kbuild/Kconfig.recursion-issue-02. + +Below is a list of examples of prior fixes for these types of recursive issues; +all errors appear to involve one or more select's and one or more "depends on". + +commit fix +====== === +06b718c01208 select A -> depends on A +c22eacfe82f9 depends on A -> depends on B +6a91e854442c select A -> depends on A +118c565a8f2e select A -> select B +f004e5594705 select A -> depends on A +c7861f37b4c6 depends on A -> (null) +80c69915e5fb select A -> (null) (1) +c2218e26c0d0 select A -> depends on A (1) +d6ae99d04e1c select A -> depends on A +95ca19cf8cbf select A -> depends on A +8f057d7bca54 depends on A -> (null) +8f057d7bca54 depends on A -> select A +a0701f04846e select A -> depends on A +0c8b92f7f259 depends on A -> (null) +e4e9e0540928 select A -> depends on A (2) +7453ea886e87 depends on A > (null) (1) +7b1fff7e4fdf select A -> depends on A +86c747d2a4f0 select A -> depends on A +d9f9ab51e55e select A -> depends on A +0c51a4d8abd6 depends on A -> select A (3) +e98062ed6dc4 select A -> depends on A (3) +91e5d284a7f1 select A -> (null) + +(1) Partial (or no) quote of error. +(2) That seems to be the gist of that fix. +(3) Same error. + +Future kconfig work +~~~~~~~~~~~~~~~~~~~ + +Work on kconfig is welcomed on both areas of clarifying semantics and on +evaluating the use of a full SAT solver for it. A full SAT solver can be +desirable to enable more complex dependency mappings and / or queries, +for instance on possible use case for a SAT solver could be that of handling +the current known recursive dependency issues. It is not known if this would +address such issues but such evaluation is desirable. If support for a full SAT +solver proves too complex or that it cannot address recursive dependency issues +Kconfig should have at least clear and well defined semantics which also +addresses and documents limitations or requirements such as the ones dealing +with recursive dependencies. + +Further work on both of these areas is welcomed on Kconfig. We elaborate +on both of these in the next two subsections. + +Semantics of Kconfig +~~~~~~~~~~~~~~~~~~~~ + +The use of Kconfig is broad, Linux is now only one of Kconfig's users: +one study has completed a broad analysis of Kconfig use in 12 projects [0]. +Despite its widespread use, and although this document does a reasonable job +in documenting basic Kconfig syntax a more precise definition of Kconfig +semantics is welcomed. One project deduced Kconfig semantics through +the use of the xconfig configurator [1]. Work should be done to confirm if +the deduced semantics matches our intended Kconfig design goals. + +Having well defined semantics can be useful for tools for practical +evaluation of depenencies, for instance one such use known case was work to +express in boolean abstraction of the inferred semantics of Kconfig to +translate Kconfig logic into boolean formulas and run a SAT solver on this to +find dead code / features (always inactive), 114 dead features were found in +Linux using this methodology [1] (Section 8: Threats to validity). + +Confirming this could prove useful as Kconfig stands as one of the the leading +industrial variability modeling languages [1] [2]. Its study would help +evaluate practical uses of such languages, their use was only theoretical +and real world requirements were not well understood. As it stands though +only reverse engineering techniques have been used to deduce semantics from +variability modeling languages such as Kconfig [3]. + +[0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf +[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf +[2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf +[3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf + +Full SAT solver for Kconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although SAT solvers [0] haven't yet been used by Kconfig directly, as noted in +the previous subsection, work has been done however to express in boolean +abstraction the inferred semantics of Kconfig to translate Kconfig logic into +boolean formulas and run a SAT solver on it [1]. Another known related project +is CADOS [2] (former VAMOS [3]) and the tools, mainly undertaker [4], which has +been introduced first with [5]. The basic concept of undertaker is to exract +variability models from Kconfig, and put them together with a propositional +formula extracted from CPP #ifdefs and build-rules into a SAT solver in order +to find dead code, dead files, and dead symbols. If using a SAT solver is +desirable on Kconfig one approach would be to evaluate repurposing such efforts +somehow on Kconfig. There is enough interest from mentors of existing projects +to not only help advise how to integrate this work upstream but also help +maintain it long term. Interested developers should visit: + +http://kernelnewbies.org/KernelProjects/kconfig-sat + +[0] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf +[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf +[2] https://cados.cs.fau.de +[3] https://vamos.cs.fau.de +[4] https://undertaker.cs.fau.de +[5] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index eda1eb1451a0..fe217c1c2f7f 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -631,7 +631,7 @@ between two versions of a file". * Name: "Cross-Referencing Linux" - URL: http://lxr.linux.no/source/ + URL: http://lxr.free-electrons.com/ Keywords: Browsing source code. Description: Another web-based Linux kernel source code browser. Lots of cross references to variables and functions. You can see @@ -696,18 +696,18 @@ Memory related patches, HOWTOs, links, mm developers... Don't miss it if you are interested in memory management development! - * Name: "Kernel Newbies IRC Channel" + * Name: "Kernel Newbies IRC Channel and Website" URL: http://www.kernelnewbies.org Keywords: IRC, newbies, channel, asking doubts. - Description: #kernelnewbies on irc.openprojects.net. From the web - page: "#kernelnewbies is an IRC network dedicated to the 'newbie' + Description: #kernelnewbies on irc.oftc.net. + #kernelnewbies is an IRC network dedicated to the 'newbie' kernel hacker. The audience mostly consists of people who are learning about the kernel, working on kernel projects or professional kernel hackers that want to help less seasoned kernel - people. [...] #kernelnewbies is on the Open Projects IRC Network, - try irc.openprojects.net or irc.<country>.openprojects.net as your - server and then /join #kernelnewbies". It also hosts articles, - documents, FAQs... + people. + #kernelnewbies is on the OFTC IRC Network. + Try irc.oftc.net as your server and then /join #kernelnewbies. + The kernelnewbies website also hosts articles, documents, FAQs... * Name: "linux-kernel mailing list archives and search engines" URL: http://vger.kernel.org/vger-lists.html diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 22a4b687ea5b..1f780d907718 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -167,7 +167,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. acpi= [HW,ACPI,X86,ARM64] Advanced Configuration and Power Interface - Format: { force | off | strict | noirq | rsdt } + Format: { force | off | strict | noirq | rsdt | + copy_dsdt } force -- enable ACPI if default was off off -- disable ACPI if default was on noirq -- do not use ACPI for IRQ routing @@ -192,6 +193,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. (e.g. thinkpad_acpi, sony_acpi, etc.) instead of the ACPI video.ko driver. + acpi_force_32bit_fadt_addr + force FADT to use 32 bit addresses rather than the + 64 bit X_* addresses. Some firmware have broken 64 + bit addresses for force ACPI ignore these and use + the older legacy 32 bit addresses. + acpica_no_return_repair [HW, ACPI] Disable AML predefined validation mechanism This mechanism can repair the evaluation result to make @@ -471,6 +478,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Change the amount of debugging information output when initialising the APIC and IO-APIC components. + apic_extnmi= [APIC,X86] External NMI delivery setting + Format: { bsp (default) | all | none } + bsp: External NMI is delivered only to CPU 0 + all: External NMIs are broadcast to all CPUs as a + backup of CPU 0 + none: External NMI is masked for all CPUs. This is + useful so that a dump capture kernel won't be + shot down by NMI + autoconf= [IPV6] See Documentation/networking/ipv6.txt. @@ -598,6 +614,16 @@ bytes respectively. Such letter suffixes can also be entirely omitted. cut the overhead, others just disable the usage. So only cgroup_disable=memory is actually worthy} + cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 + Format: { controller[,controller...] | "all" } + Like cgroup_disable, but only applies to cgroup v1; + the blacklisted controllers remain available in cgroup2. + + cgroup.memory= [KNL] Pass options to the cgroup memory controller. + Format: <string> + nosocket -- Disable socket memory accounting. + nokmem -- Disable kernel memory accounting. + checkreqprot [SELINUX] Set initial checkreqprot flag value. Format: { "0" | "1" } See security/selinux/Kconfig help text. @@ -651,7 +677,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. clearcpuid=BITNUM [X86] Disable CPUID feature X for the kernel. See - arch/x86/include/asm/cpufeature.h for the valid bit + arch/x86/include/asm/cpufeatures.h for the valid bit numbers. Note the Linux specific bits are not necessarily stable over kernel options, but the vendor specific ones should be. @@ -720,16 +746,17 @@ bytes respectively. Such letter suffixes can also be entirely omitted. uart[8250],io,<addr>[,options] uart[8250],mmio,<addr>[,options] + uart[8250],mmio16,<addr>[,options] uart[8250],mmio32,<addr>[,options] uart[8250],0x<addr>[,options] Start an early, polled-mode console on the 8250/16550 UART at the specified I/O port or MMIO address, switching to the matching ttyS device later. MMIO inter-register address stride is either 8-bit - (mmio) or 32-bit (mmio32). - If none of [io|mmio|mmio32], <addr> is assumed to be - equivalent to 'mmio'. 'options' are specified in the - same format described for ttyS above; if unspecified, + (mmio), 16-bit (mmio16), or 32-bit (mmio32). + If none of [io|mmio|mmio16|mmio32], <addr> is assumed + to be equivalent to 'mmio'. 'options' are specified in + the same format described for ttyS above; if unspecified, the h/w is not re-initialized. hvc<n> Use the hypervisor console device <n>. This is for @@ -789,8 +816,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. is passed, kernel could allocate physical memory region above 4G, that cause second kernel crash on system that require some amount of low memory, e.g. swiotlb - requires at least 64M+32K low memory. Kernel would - try to allocate 72M below 4G automatically. + requires at least 64M+32K low memory, also enough extra + low memory is needed to make sure DMA buffers for 32-bit + devices won't run out. Kernel would try to allocate at + at least 256M below 4G automatically. This one let user to specify own low range under 4G for second kernel instead. 0: to disable low allocation. @@ -929,11 +958,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. The filter can be disabled or changed to another driver later using sysfs. - drm_kms_helper.edid_firmware=[<connector>:]<file> - Broken monitors, graphic adapters and KVMs may - send no or incorrect EDID data sets. This parameter - allows to specify an EDID data set in the - /lib/firmware directory that is used instead. + drm_kms_helper.edid_firmware=[<connector>:]<file>[,[<connector>:]<file>] + Broken monitors, graphic adapters, KVMs and EDIDless + panels may send no or incorrect EDID data sets. + This parameter allows to specify an EDID data sets + in the /lib/firmware directory that are used instead. Generic built-in EDID data sets are used, if one of edid/1024x768.bin, edid/1280x1024.bin, edid/1680x1050.bin, or edid/1920x1080.bin is given @@ -942,7 +971,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. available in Documentation/EDID/HOWTO.txt. An EDID data set will only be used for a particular connector, if its name and a colon are prepended to the EDID - name. + name. Each connector may use a unique EDID data + set by separating the files with a comma. An EDID + data set with no connector name will be used for + any connectors not explicitly specified. dscc4.setup= [NET] @@ -971,6 +1003,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. 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. + cdns,<addr> Start an early, polled-mode console on a cadence serial port at the specified address. The cadence serial port @@ -992,10 +1028,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. unspecified, the h/w is not initialized. pl011,<addr> + pl011,mmio32,<addr> Start an early, polled-mode console on a pl011 serial port at the specified address. The pl011 serial port must already be setup and configured. Options are not - yet supported. + yet supported. If 'mmio32' is specified, then only + the driver will use only 32-bit accessors to read/write + the device registers. msm_serial,<addr> Start an early, polled-mode console on an msm serial @@ -1023,6 +1062,19 @@ bytes respectively. Such letter suffixes can also be entirely omitted. serial port must already be setup and configured. Options are not yet supported. + lpuart,<addr> + lpuart32,<addr> + Use early console provided by Freescale LP UART driver + found on Freescale Vybrid and QorIQ LS1021A processors. + A valid base address must be provided, and the serial + port must already be setup and configured. + + armada3700_uart,<addr> + Start an early, polled-mode console on the + Armada 3700 serial port at the specified + address. The serial port must already be setup + and configured. Options are not yet supported. + earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] earlyprintk=vga earlyprintk=efi @@ -1094,6 +1146,21 @@ bytes respectively. Such letter suffixes can also be entirely omitted. you are really sure that your UEFI does sane gc and fulfills the spec otherwise your board may brick. + efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] + Add arbitrary attribute to specific memory range by + updating original EFI memory map. + Region of memory which aa attribute is added to is + from ss to ss+nn. + If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 + is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) + attribute is added to range 0x100000000-0x180000000 and + 0x10a0000000-0x1120000000. + + Using this parameter you can do debugging of EFI memmap + related feature. For example, you can do debugging of + Address Range Mirroring feature even if your box + doesn't support it. + eisa_irq_edge= [PARISC,HW] See header of drivers/parisc/eisa.c. @@ -1246,6 +1313,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Format: <unsigned int> such that (rxsize & ~0x1fffc0) == 0. Default: 1024 + hardlockup_all_cpu_backtrace= + [KNL] Should the hard-lockup detector generate + backtraces on all cpus. + Format: <integer> + hashdist= [KNL,NUMA] Large hashes allocated during boot are distributed across NUMA nodes. Defaults on for 64-bit NUMA, off otherwise. @@ -1399,6 +1471,41 @@ bytes respectively. Such letter suffixes can also be entirely omitted. In such case C2/C3 won't be used again. idle=nomwait: Disable mwait for CPU C-states + ieee754= [MIPS] Select IEEE Std 754 conformance mode + Format: { strict | legacy | 2008 | relaxed } + Default: strict + + Choose which programs will be accepted for execution + based on the IEEE 754 NaN encoding(s) supported by + the FPU and the NaN encoding requested with the value + of an ELF file header flag individually set by each + binary. Hardware implementations are permitted to + support either or both of the legacy and the 2008 NaN + encoding mode. + + Available settings are as follows: + strict accept binaries that request a NaN encoding + supported by the FPU + legacy only accept legacy-NaN binaries, if supported + by the FPU + 2008 only accept 2008-NaN binaries, if supported + by the FPU + relaxed accept any binaries regardless of whether + supported by the FPU + + The FPU emulator is always able to support both NaN + encodings, so if no FPU hardware is present or it has + been disabled with 'nofpu', then the settings of + 'legacy' and '2008' strap the emulator accordingly, + 'relaxed' straps the emulator for both legacy-NaN and + 2008-NaN, whereas 'strict' enables legacy-NaN only on + legacy processors and both NaN encodings on MIPS32 or + MIPS64 CPUs. + + The setting for ABS.fmt/NEG.fmt instruction execution + mode generally follows that for the NaN encoding, + except where unsupported by hardware. + ignore_loglevel [KNL] Ignore loglevel setting - this will print /all/ kernel messages to the console. Useful for debugging. @@ -1406,6 +1513,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. could change it dynamically, usually by /sys/module/printk/parameters/ignore_loglevel. + ignore_rlimit_data + Ignore RLIMIT_DATA setting for data mappings, + print warning at first misuse. Can be changed via + /sys/module/kernel/parameters/ignore_rlimit_data. + ihash_entries= [KNL] Set number of hash buckets for inode cache. @@ -1553,6 +1665,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nosid disable Source ID checking no_x2apic_optout BIOS x2APIC opt-out request will be ignored + nopost disable Interrupt Posting iomem= Disable strict checking of access to MMIO memory strict regions from userspace. @@ -1591,6 +1704,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ip= [IP_PNP] See Documentation/filesystems/nfs/nfsroot.txt. + irqaffinity= [SMP] Set the default irq affinity mask + Format: + <cpu number>,...,<cpu number> + or + <cpu number>-<cpu number> + (must be a positive range in ascending order) + or a mixture + <cpu number>,...,<cpu number>-<cpu number> + irqfixup [HW] When an interrupt is not handled search all handlers for it. Intended to get systems with badly broken @@ -1654,7 +1776,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. keepinitrd [HW,ARM] - kernelcore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter + kernelcore= [KNL,X86,IA-64,PPC] + Format: nn[KMGTPE] | "mirror" + This parameter specifies the amount of memory usable by the kernel for non-movable allocations. The requested amount is spread evenly throughout all nodes in the system. The @@ -1670,6 +1794,14 @@ bytes respectively. Such letter suffixes can also be entirely omitted. use the HighMem zone if it exists, and the Normal zone if it does not. + Instead of specifying the amount of memory (nn[KMGTPE]), + you can specify "mirror" option. In case "mirror" + option is specified, mirrored (reliable) memory is used + for non-movable allocations and remaining memory is used + for Movable pages. nn[KMGTPE] and "mirror" are exclusive, + so you can NOT specify nn[KMGTPE] and "mirror" at the same + time. + kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. Format: <Controller#>[,poll interval] The controller # is the number of the ehci usb debug @@ -2314,11 +2446,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels Format: [panic,][nopanic,][num] Valid num: 0 or 1 - 0 - turn nmi_watchdog off - 1 - turn nmi_watchdog on + 0 - turn hardlockup detector in nmi_watchdog off + 1 - turn hardlockup detector in nmi_watchdog on When panic is specified, panic when an NMI watchdog timeout occurs (or 'nopanic' to override the opposite - default). + default). To disable both hard and soft lockup detectors, + please see 'nowatchdog'. This is useful when you use a panic=... timeout and need the box quickly up again. @@ -2469,6 +2602,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nointroute [IA-64] + noinvpcid [X86] Disable the INVPCID cpu feature. + nojitter [IA-64] Disables jitter checking for ITC timers. no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver @@ -2485,7 +2620,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nolapic_timer [X86-32,APIC] Do not use the local APIC timer. noltlbs [PPC] Do not use large page/tlb entries for kernel - lowmem mapping on PPC40x. + lowmem mapping on PPC40x and PPC8xx nomca [IA-64] Disable machine check abort handling @@ -2536,8 +2671,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. notsc [BUGS=X86-32] Disable Time Stamp Counter - nousb [USB] Disable the USB subsystem - nowatchdog [KNL] Disable both lockup detectors, i.e. soft-lockup and NMI watchdog (hard-lockup). @@ -2626,6 +2759,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. we can turn it on. on: enable the feature + page_poison= [KNL] Boot-time parameter changing the state of + poisoning on the buddy allocator. + off: turn off poisoning + on: turn on poisoning + panic= [KNL] Kernel behaviour on panic: delay <timeout> timeout > 0: seconds before rebooting timeout = 0: wait forever @@ -2694,10 +2832,16 @@ bytes respectively. Such letter suffixes can also be entirely omitted. hardware access methods are allowed. Use this if you experience crashes upon bootup and you suspect they are caused by the BIOS. - conf1 [X86] Force use of PCI Configuration - Mechanism 1. - conf2 [X86] Force use of PCI Configuration - Mechanism 2. + conf1 [X86] Force use of PCI Configuration Access + Mechanism 1 (config address in IO port 0xCF8, + data in IO port 0xCFC, both 32-bit). + conf2 [X86] Force use of PCI Configuration Access + Mechanism 2 (IO port 0xCF8 is an 8-bit port for + the function, IO port 0xCFA, also 8-bit, sets + bus number. The config space is then accessed + through ports 0xC000-0xCFFF). + See http://wiki.osdev.org/PCI for more info + on the configuration access mechanisms. noaer [PCIE] If the PCIEAER kernel config parameter is enabled, this kernel boot option can be used to disable the use of PCIE advanced error reporting. @@ -2939,6 +3083,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. may be specified. Format: <port>,<port>.... + ppc_strict_facility_enable + [PPC] This option catches any kernel floating point, + Altivec, VSX and SPE outside of regions specifically + allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). + There is some performance impact when enabling this. + print-fatal-signals= [KNL] debug: print fatal signals @@ -3011,9 +3161,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. raid= [HW,RAID] See Documentation/md.txt. - ramdisk_blocksize= [RAM] - See Documentation/blockdev/ramdisk.txt. - ramdisk_size= [RAM] Sizes of RAM disks in kilobytes See Documentation/blockdev/ramdisk.txt. @@ -3074,9 +3221,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. cache-to-cache transfer latencies. rcutree.rcu_fanout_leaf= [KNL] - Increase the number of CPUs assigned to each - leaf rcu_node structure. Useful for very large - systems. + Change the number of CPUs assigned to each + leaf rcu_node structure. Useful for very + large systems, which will choose the value 64, + and for NUMA systems with large remote-access + latencies, which will choose a value aligned + with the appropriate hardware boundaries. rcutree.jiffies_till_sched_qs= [KNL] Set required age in jiffies for a @@ -3254,18 +3404,35 @@ bytes respectively. Such letter suffixes can also be entirely omitted. rcutorture.verbose= [KNL] Enable additional printk() statements. + rcupdate.rcu_cpu_stall_suppress= [KNL] + Suppress RCU CPU stall warning messages. + + rcupdate.rcu_cpu_stall_timeout= [KNL] + Set timeout for RCU CPU stall warning messages. + rcupdate.rcu_expedited= [KNL] Use expedited grace-period primitives, for example, synchronize_rcu_expedited() instead of synchronize_rcu(). This reduces latency, but can increase CPU utilization, degrade real-time latency, and degrade energy efficiency. - - rcupdate.rcu_cpu_stall_suppress= [KNL] - Suppress RCU CPU stall warning messages. - - rcupdate.rcu_cpu_stall_timeout= [KNL] - Set timeout for RCU CPU stall warning messages. + No effect on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal= [KNL] + Use only normal grace-period primitives, + for example, synchronize_rcu() instead of + synchronize_rcu_expedited(). This improves + real-time latency, CPU utilization, and + energy efficiency, but can expose users to + increased grace-period latency. This parameter + overrides rcupdate.rcu_expedited. No effect on + CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal_after_boot= [KNL] + Once boot has completed (that is, after + rcu_end_inkernel_boot() has been invoked), use + only normal grace-period primitives. No effect + on CONFIG_TINY_RCU kernels. rcupdate.rcu_task_stall_timeout= [KNL] Set timeout in jiffies for RCU task stall warning @@ -3367,6 +3534,16 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ro [KNL] Mount root device read-only on boot + rodata= [KNL] + on Mark read-only kernel memory as read-only (default). + off Leave read-only kernel memory writable for debugging. + + rockchip.usb_uart + Enable the uart passthrough on the designated usb port + on Rockchip SoCs. When active, the signals of the + debug-uart get routed to the D+ and D- pins of the usb + port and the regular usb controller gets disabled. + root= [KNL] Root filesystem See name_to_dev_t comment in init/do_mounts.c. @@ -3404,6 +3581,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. sched_debug [KNL] Enables verbose scheduler debug messages. + schedstats= [KNL,X86] Enable or disable scheduled statistics. + Allowed values are enable and disable. This feature + incurs a small amount of overhead in the scheduler + but is useful for debugging and performance tuning. + skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate xtime_lock contention on larger systems, and/or RCU lock contention on all systems with CONFIG_MAXSMP set. @@ -3832,6 +4014,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. usbcore.usbfs_snoop= [USB] Set to log all usbfs traffic (default 0 = off). + usbcore.usbfs_snoop_max= + [USB] Maximum number of bytes to snoop in each URB + (default = 65536). + usbcore.blinkenlights= [USB] Set to cycle leds on hubs (default 0 = off). @@ -3852,6 +4038,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. USB_REQ_GET_DESCRIPTOR request in milliseconds (default 5000 = 5.0 seconds). + usbcore.nousb [USB] Disable the USB subsystem + usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. @@ -4072,6 +4260,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. or other driver-specific files in the Documentation/watchdog/ directory. + workqueue.watchdog_thresh= + If CONFIG_WQ_WATCHDOG is configured, workqueue can + warn stall conditions and dump internal state to + help debugging. 0 disables workqueue stall + detection; otherwise, it's the stall threshold + duration in seconds. The default value is 30 and + it can be updated at runtime by writing to the + corresponding sysfs file. + workqueue.disable_numa By default, all work items queued to unbound workqueues are affine to the NUMA nodes they're @@ -4096,6 +4293,17 @@ bytes respectively. Such letter suffixes can also be entirely omitted. The default value of this parameter is determined by the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. + workqueue.debug_force_rr_cpu + Workqueue used to implicitly guarantee that work + items queued without explicit CPU specified are put + on the local CPU. This guarantee is no longer true + and while local CPU is still preferred work items + may be put on foreign CPUs. This debug option + forces round-robin CPU selection to flush out + usages which depend on the now broken guarantee. + When enabled, memory and cache locality will be + impacted. + x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of default x2apic cluster mode on platforms supporting x2apic. diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt index f4cbfe0ba108..edec3a3e648d 100644 --- a/Documentation/kernel-per-CPU-kthreads.txt +++ b/Documentation/kernel-per-CPU-kthreads.txt @@ -90,7 +90,7 @@ BLOCK_SOFTIRQ: Do all of the following: from being initiated from tasks that might run on the CPU to be de-jittered. (It is OK to force this CPU offline and then bring it back online before you start your application.) -BLOCK_IOPOLL_SOFTIRQ: Do all of the following: +IRQ_POLL_SOFTIRQ: Do all of the following: 1. Force block-device interrupts onto some other CPU. 2. Initiate any block I/O and block-I/O polling on other CPUs. 3. Once your application has started, prevent CPU-hotplug operations diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index dc2ff8f611e0..5a81b394b3b5 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -1,6 +1,6 @@ NOTE: This is a version of Documentation/HOWTO translated into korean -This document is maintained by minchan Kim <minchan.kim@gmail.com> +This document is maintained by Minchan Kim <minchan@kernel.org> If you find any difference between this document and the original file or a problem with the translation, please contact the maintainer of this file. @@ -14,7 +14,7 @@ try to update the original English file first. Documentation/HOWTO 의 한글 번역입니다. -역자： 김민찬 <minchan.kim@gmail.com> +역자： 김민찬 <minchan@kernel.org> 감수： 이제이미 <jamee.lee@samsung.com> ================================== @@ -213,7 +213,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며 소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널 코드 저장소는 다음을 통하여 참조할 수 있다. - http://lxr.linux.no/+trees + http://lxr.free-electrons.com/ 개발 프로세스 @@ -222,16 +222,16 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과 서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인 브랜치들은 다음과 같다. - - main 3.x 커널 트리 - - 3.x.y - 안정된 커널 트리 - - 3.x -git 커널 패치들 + - main 4.x 커널 트리 + - 4.x.y - 안정된 커널 트리 + - 4.x -git 커널 패치들 - 서브시스템을 위한 커널 트리들과 패치들 - - 3.x - 통합 테스트를 위한 next 커널 트리 + - 4.x - 통합 테스트를 위한 next 커널 트리 -3.x 커널 트리 +4.x 커널 트리 --------------- -3.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v3.x/ +4.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 @@ -262,20 +262,20 @@ Andrew Morton의 글이 있다. 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 배포되는 것은 아니기 때문이다." -3.x.y - 안정 커널 트리 +4.x.y - 안정 커널 트리 ------------------------ -3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 3.x +3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x 커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을 포함한다. 이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며, 개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다. -어떤 3.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 3.x +어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x 커널이 현재의 안정 커널이다. -3.x.y는 "stable" 팀<stable@vger.kernel.org>에 의해 관리되며 거의 매번 격주로 +4.x.y는 "stable" 팀<stable@vger.kernel.org>에 의해 관리되며 거의 매번 격주로 배포된다. 커널 트리 문서들 내에 Documentation/stable_kernel_rules.txt 파일은 어떤 @@ -283,7 +283,7 @@ Andrew Morton의 글이 있다. 진행되는지를 설명한다. -3.x -git 패치들 +4.x -git 패치들 ------------------ git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의 커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며 @@ -312,13 +312,12 @@ Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인 대부분의 이러한 patchwork 사이트는 http://patchwork.kernel.org/ 또는 http://patchwork.ozlabs.org/ 에 나열되어 있다. -3.x - 통합 테스트를 위한 next 커널 트리 +4.x - 통합 테스트를 위한 next 커널 트리 ----------------------------------------- -서브시스템 트리들의 변경사항들은 mainline 3.x 트리로 들어오기 전에 통합 +서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합 테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 매일 받아가는 특수한 테스트 저장소가 존재한다: http://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git - http://linux.f-seidel.de/linux-next/pmwiki/ 이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이 가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를 diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/ko_KR/stable_api_nonsense.txt index 51f85ade4190..3ba10b11d556 100644 --- a/Documentation/ko_KR/stable_api_nonsense.txt +++ b/Documentation/ko_KR/stable_api_nonsense.txt @@ -1,7 +1,7 @@ NOTE: This is a version of Documentation/stable_api_nonsense.txt translated into korean -This document is maintained by barrios <minchan.kim@gmail.com> +This document is maintained by Minchan Kim <minchan@kernel.org> If you find any difference between this document and the original file or a problem with the translation, please contact the maintainer of this file. @@ -15,7 +15,7 @@ try to update the original English file first. Documentation/stable_api_nonsense.txt 의 한글 번역입니다. -역자： 김민찬 <minchan.kim@gmail.com> +역자： 김민찬 <minchan@kernel.org> 감수： 이제이미 <jamee.lee@samsung.com> ================================== diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt index a87d840bacfe..979eacae243d 100644 --- a/Documentation/kselftest.txt +++ b/Documentation/kselftest.txt @@ -54,10 +54,26 @@ To run the hotplug tests: - note that some tests will require root privileges. +Install selftests +================= + +You can use kselftest_install.sh tool installs selftests in default +location which is tools/testing/selftests/kselftest or an user specified +location. + +To install selftests in default location: + $ cd tools/testing/selftests + $ ./kselftest_install.sh + +To install selftests in an user specified location: + $ cd tools/testing/selftests + $ ./kselftest_install.sh install_dir + + Contributing new tests ====================== -In general, the rules for for selftests are +In general, the rules for selftests are * Do as much as you can if you're not root; diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt index 62261c04060a..d406d98339b2 100644 --- a/Documentation/leds/leds-class.txt +++ b/Documentation/leds/leds-class.txt @@ -52,6 +52,19 @@ above leaves scope for further attributes should they be needed. If sections of the name don't apply, just leave that section blank. +Brightness setting API +====================== + +LED subsystem core exposes following API for setting brightness: + + - led_set_brightness : it is guaranteed not to sleep, passing LED_OFF stops + blinking, + - led_set_brightness_sync : for use cases when immediate effect is desired - + it can block the caller for the time required for accessing + device registers and can sleep, passing LED_OFF stops hardware + blinking, returns -EBUSY if software blink fallback is enabled. + + Hardware accelerated blink of LEDs ================================== diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt index 568bbbacee91..5786ad2cd5e6 100644 --- a/Documentation/locking/lockstat.txt +++ b/Documentation/locking/lockstat.txt @@ -12,7 +12,7 @@ Because things like lock contention can severely impact performance. - HOW Lockdep already has hooks in the lock functions and maps lock instances to -lock classes. We build on that (see Documentation/lokcing/lockdep-design.txt). +lock classes. We build on that (see Documentation/locking/lockdep-design.txt). The graph below shows the relation between the lock functions and the various hooks therein. diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.txt index 619f2bb136a5..a2ef3a929bf1 100644 --- a/Documentation/locking/locktorture.txt +++ b/Documentation/locking/locktorture.txt @@ -52,6 +52,9 @@ torture_type Type of lock to torture. By default, only spinlocks will o "mutex_lock": mutex_lock() and mutex_unlock() pairs. + o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock() + pairs. Kernel must have CONFIG_RT_MUTEX=y. + o "rwsem_lock": read/write down() and up() semaphore pairs. torture_runnable Start locktorture at boot time in the case where the diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/lockup-watchdogs.txt index 22dd6af2e4bd..4a6e33e1af61 100644 --- a/Documentation/lockup-watchdogs.txt +++ b/Documentation/lockup-watchdogs.txt @@ -20,8 +20,9 @@ kernel mode for more than 10 seconds (see "Implementation" below for details), without letting other interrupts have a chance to run. Similarly to the softlockup case, the current stack trace is displayed upon detection and the system will stay locked up unless the default -behavior is changed, which can be done through a compile time knob, -"BOOTPARAM_HARDLOCKUP_PANIC", and a kernel parameter, "nmi_watchdog" +behavior is changed, which can be done through a sysctl, +'hardlockup_panic', a compile time knob, "BOOTPARAM_HARDLOCKUP_PANIC", +and a kernel parameter, "nmi_watchdog" (see "Documentation/kernel-parameters.txt" for details). The panic option can be used in combination with panic_timeout (this diff --git a/Documentation/md-cluster.txt b/Documentation/md-cluster.txt index 1b794369e03a..c100c7163507 100644 --- a/Documentation/md-cluster.txt +++ b/Documentation/md-cluster.txt @@ -3,7 +3,7 @@ The cluster MD is a shared-device RAID for a cluster. 1. On-disk format -Separate write-intent-bitmap are used for each cluster node. +Separate write-intent-bitmaps are used for each cluster node. The bitmaps record all writes that may have been started on that node, and may not yet have finished. The on-disk layout is: @@ -14,117 +14,161 @@ and may not yet have finished. The on-disk layout is: | bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits | | bm bits [3, contd] | | | -During "normal" functioning we assume the filesystem ensures that only one -node writes to any given block at a time, so a write -request will +During "normal" functioning we assume the filesystem ensures that only +one node writes to any given block at a time, so a write request will + - set the appropriate bit (if not already set) - commit the write to all mirrors - schedule the bit to be cleared after a timeout. -Reads are just handled normally. It is up to the filesystem to -ensure one node doesn't read from a location where another node (or the same +Reads are just handled normally. It is up to the filesystem to ensure +one node doesn't read from a location where another node (or the same node) is writing. 2. DLM Locks for management -There are two locks for managing the device: +There are three groups of locks for managing the device: 2.1 Bitmap lock resource (bm_lockres) - The bm_lockres protects individual node bitmaps. They are named in the - form bitmap001 for node 1, bitmap002 for node and so on. When a node - joins the cluster, it acquires the lock in PW mode and it stays so - during the lifetime the node is part of the cluster. The lock resource - number is based on the slot number returned by the DLM subsystem. Since - DLM starts node count from one and bitmap slots start from zero, one is - subtracted from the DLM slot number to arrive at the bitmap slot number. + The bm_lockres protects individual node bitmaps. They are named in + the form bitmap000 for node 1, bitmap001 for node 2 and so on. When a + node joins the cluster, it acquires the lock in PW mode and it stays + so during the lifetime the node is part of the cluster. The lock + resource number is based on the slot number returned by the DLM + subsystem. Since DLM starts node count from one and bitmap slots + start from zero, one is subtracted from the DLM slot number to arrive + at the bitmap slot number. + + The LVB of the bitmap lock for a particular node records the range + of sectors that are being re-synced by that node. No other + node may write to those sectors. This is used when a new nodes + joins the cluster. + +2.2 Message passing locks + + Each node has to communicate with other nodes when starting or ending + resync, and for metadata superblock updates. This communication is + managed through three locks: "token", "message", and "ack", together + with the Lock Value Block (LVB) of one of the "message" lock. + +2.3 new-device management + + A single lock: "no-new-dev" is used to co-ordinate the addition of + new devices - this must be synchronized across the array. + Normally all nodes hold a concurrent-read lock on this device. 3. Communication -Each node has to communicate with other nodes when starting or ending -resync, and metadata superblock updates. + Messages can be broadcast to all nodes, and the sender waits for all + other nodes to acknowledge the message before proceeding. Only one + message can be processed at a time. 3.1 Message Types - There are 3 types, of messages which are passed + There are six types of messages which are passed: - 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has been - updated, and the node must re-read the md superblock. This is performed - synchronously. + 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has + been updated, and the node must re-read the md superblock. This is + performed synchronously. It is primarily used to signal device + failure. - 3.1.2 RESYNC: informs other nodes that a resync is initiated or ended - so that each node may suspend or resume the region. + 3.1.2 RESYNCING: informs other nodes that a resync is initiated or + ended so that each node may suspend or resume the region. Each + RESYNCING message identifies a range of the devices that the + sending node is about to resync. This over-rides any pervious + notification from that node: only one ranged can be resynced at a + time per-node. + + 3.1.3 NEWDISK: informs other nodes that a device is being added to + the array. Message contains an identifier for that device. See + below for further details. + + 3.1.4 REMOVE: A failed or spare device is being removed from the + array. The slot-number of the device is included in the message. + + 3.1.5 RE_ADD: A failed device is being re-activated - the assumption + is that it has been determined to be working again. + + 3.1.6 BITMAP_NEEDS_SYNC: if a node is stopped locally but the bitmap + isn't clean, then another node is informed to take the ownership of + resync. 3.2 Communication mechanism The DLM LVB is used to communicate within nodes of the cluster. There are three resources used for the purpose: - 3.2.1 Token: The resource which protects the entire communication + 3.2.1 token: The resource which protects the entire communication system. The node having the token resource is allowed to communicate. - 3.2.2 Message: The lock resource which carries the data to + 3.2.2 message: The lock resource which carries the data to communicate. - 3.2.3 Ack: The resource, acquiring which means the message has been + 3.2.3 ack: The resource, acquiring which means the message has been acknowledged by all nodes in the cluster. The BAST of the resource - is used to inform the receive node that a node wants to communicate. + is used to inform the receiving node that a node wants to + communicate. The algorithm is: - 1. receive status + 1. receive status - all nodes have concurrent-reader lock on "ack". - sender receiver receiver - ACK:CR ACK:CR ACK:CR + sender receiver receiver + "ack":CR "ack":CR "ack":CR - 2. sender get EX of TOKEN - sender get EX of MESSAGE + 2. sender get EX on "token" + sender get EX on "message" sender receiver receiver - TOKEN:EX ACK:CR ACK:CR - MESSAGE:EX - ACK:CR + "token":EX "ack":CR "ack":CR + "message":EX + "ack":CR - Sender checks that it still needs to send a message. Messages received - or other events that happened while waiting for the TOKEN may have made - this message inappropriate or redundant. + Sender checks that it still needs to send a message. Messages + received or other events that happened while waiting for the + "token" may have made this message inappropriate or redundant. - 3. sender write LVB. - sender down-convert MESSAGE from EX to CW - sender try to get EX of ACK - [ wait until all receiver has *processed* the MESSAGE ] + 3. sender writes LVB. + sender down-convert "message" from EX to CW + sender try to get EX of "ack" + [ wait until all receivers have *processed* the "message" ] - [ triggered by bast of ACK ] - receiver get CR of MESSAGE + [ triggered by bast of "ack" ] + receiver get CR on "message" receiver read LVB receiver processes the message [ wait finish ] - receiver release ACK - - sender receiver receiver - TOKEN:EX MESSAGE:CR MESSAGE:CR - MESSAGE:CR - ACK:EX - - 4. triggered by grant of EX on ACK (indicating all receivers have processed - message) - sender down-convert ACK from EX to CR - sender release MESSAGE - sender release TOKEN - receiver upconvert to PR of MESSAGE - receiver get CR of ACK - receiver release MESSAGE + receiver releases "ack" + receiver tries to get PR on "message" + + sender receiver receiver + "token":EX "message":CR "message":CR + "message":CW + "ack":EX + + 4. triggered by grant of EX on "ack" (indicating all receivers + have processed message) + sender down-converts "ack" from EX to CR + sender releases "message" + sender releases "token" + receiver upconvert to PR on "message" + receiver get CR of "ack" + receiver release "message" sender receiver receiver - ACK:CR ACK:CR ACK:CR + "ack":CR "ack":CR "ack":CR 4. Handling Failures 4.1 Node Failure - When a node fails, the DLM informs the cluster with the slot. The node - starts a cluster recovery thread. The cluster recovery thread: + + When a node fails, the DLM informs the cluster with the slot + number. The node starts a cluster recovery thread. The cluster + recovery thread: + - acquires the bitmap<number> lock of the failed node - opens the bitmap - reads the bitmap of the failed node @@ -132,45 +176,143 @@ The algorithm is: - cleans the bitmap of the failed node - releases bitmap<number> lock of the failed node - initiates resync of the bitmap on the current node + md_check_recovery is invoked within recover_bitmaps, + then md_check_recovery -> metadata_update_start/finish, + it will lock the communication by lock_comm. + Which means when one node is resyncing it blocks all + other nodes from writing anywhere on the array. - The resync process, is the regular md resync. However, in a clustered + The resync process is the regular md resync. However, in a clustered environment when a resync is performed, it needs to tell other nodes of the areas which are suspended. Before a resync starts, the node - send out RESYNC_START with the (lo,hi) range of the area which needs - to be suspended. Each node maintains a suspend_list, which contains - the list of ranges which are currently suspended. On receiving - RESYNC_START, the node adds the range to the suspend_list. Similarly, - when the node performing resync finishes, it send RESYNC_FINISHED - to other nodes and other nodes remove the corresponding entry from - the suspend_list. + send out RESYNCING with the (lo,hi) range of the area which needs to + be suspended. Each node maintains a suspend_list, which contains the + list of ranges which are currently suspended. On receiving RESYNCING, + the node adds the range to the suspend_list. Similarly, when the node + performing resync finishes, it sends RESYNCING with an empty range to + other nodes and other nodes remove the corresponding entry from the + suspend_list. - A helper function, should_suspend() can be used to check if a particular - I/O range should be suspended or not. + A helper function, ->area_resyncing() can be used to check if a + particular I/O range should be suspended or not. 4.2 Device Failure + Device failures are handled and communicated with the metadata update - routine. + routine. When a node detects a device failure it does not allow + any further writes to that device until the failure has been + acknowledged by all other nodes. 5. Adding a new Device -For adding a new device, it is necessary that all nodes "see" the new device -to be added. For this, the following algorithm is used: + + For adding a new device, it is necessary that all nodes "see" the new + device to be added. For this, the following algorithm is used: 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues - ioctl(ADD_NEW_DISC with disc.state set to MD_DISK_CLUSTER_ADD) - 2. Node 1 sends NEWDISK with uuid and slot number + ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CLUSTER_ADD) + 2. Node 1 sends a NEWDISK message with uuid and slot number 3. Other nodes issue kobject_uevent_env with uuid and slot number (Steps 4,5 could be a udev rule) 4. In userspace, the node searches for the disk, perhaps using blkid -t SUB_UUID="" - 5. Other nodes issue either of the following depending on whether the disk - was found: + 5. Other nodes issue either of the following depending on whether + the disk was found: ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CANDIDATE and - disc.number set to slot number) + disc.number set to slot number) ioctl(CLUSTERED_DISK_NACK) - 6. Other nodes drop lock on no-new-devs (CR) if device is found - 7. Node 1 attempts EX lock on no-new-devs - 8. If node 1 gets the lock, it sends METADATA_UPDATED after unmarking the disk - as SpareLocal - 9. If not (get no-new-dev lock), it fails the operation and sends METADATA_UPDATED - 10. Other nodes get the information whether a disk is added or not - by the following METADATA_UPDATED. + 6. Other nodes drop lock on "no-new-devs" (CR) if device is found + 7. Node 1 attempts EX lock on "no-new-dev" + 8. If node 1 gets the lock, it sends METADATA_UPDATED after + unmarking the disk as SpareLocal + 9. If not (get "no-new-dev" lock), it fails the operation and sends + METADATA_UPDATED. + 10. Other nodes get the information whether a disk is added or not + by the following METADATA_UPDATED. + +6. Module interface. + + There are 17 call-backs which the md core can make to the cluster + module. Understanding these can give a good overview of the whole + process. + +6.1 join(nodes) and leave() + + These are called when an array is started with a clustered bitmap, + and when the array is stopped. join() ensures the cluster is + available and initializes the various resources. + Only the first 'nodes' nodes in the cluster can use the array. + +6.2 slot_number() + + Reports the slot number advised by the cluster infrastructure. + Range is from 0 to nodes-1. + +6.3 resync_info_update() + + This updates the resync range that is stored in the bitmap lock. + The starting point is updated as the resync progresses. The + end point is always the end of the array. + It does *not* send a RESYNCING message. + +6.4 resync_start(), resync_finish() + + These are called when resync/recovery/reshape starts or stops. + They update the resyncing range in the bitmap lock and also + send a RESYNCING message. resync_start reports the whole + array as resyncing, resync_finish reports none of it. + + resync_finish() also sends a BITMAP_NEEDS_SYNC message which + allows some other node to take over. + +6.5 metadata_update_start(), metadata_update_finish(), + metadata_update_cancel(). + + metadata_update_start is used to get exclusive access to + the metadata. If a change is still needed once that access is + gained, metadata_update_finish() will send a METADATA_UPDATE + message to all other nodes, otherwise metadata_update_cancel() + can be used to release the lock. + +6.6 area_resyncing() + + This combines two elements of functionality. + + Firstly, it will check if any node is currently resyncing + anything in a given range of sectors. If any resync is found, + then the caller will avoid writing or read-balancing in that + range. + + Secondly, while node recovery is happening it reports that + all areas are resyncing for READ requests. This avoids races + between the cluster-filesystem and the cluster-RAID handling + a node failure. + +6.7 add_new_disk_start(), add_new_disk_finish(), new_disk_ack() + + These are used to manage the new-disk protocol described above. + When a new device is added, add_new_disk_start() is called before + it is bound to the array and, if that succeeds, add_new_disk_finish() + is called the device is fully added. + + When a device is added in acknowledgement to a previous + request, or when the device is declared "unavailable", + new_disk_ack() is called. + +6.8 remove_disk() + + This is called when a spare or failed device is removed from + the array. It causes a REMOVE message to be send to other nodes. + +6.9 gather_bitmaps() + + This sends a RE_ADD message to all other nodes and then + gathers bitmap information from all bitmaps. This combined + bitmap is then used to recovery the re-added device. + +6.10 lock_all_bitmaps() and unlock_all_bitmaps() + + These are called when change bitmap to none. If a node plans + to clear the cluster raid's bitmap, it need to make sure no other + nodes are using the raid which is achieved by lock all bitmap + locks within the cluster, and also those locks are unlocked + accordingly. diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt deleted file mode 100644 index f552a75c0e70..000000000000 --- a/Documentation/media-framework.txt +++ /dev/null @@ -1,372 +0,0 @@ -Linux kernel media framework -============================ - -This document describes the Linux kernel media framework, its data structures, -functions and their usage. - - -Introduction ------------- - -The media controller API is documented in DocBook format in -Documentation/DocBook/media/v4l/media-controller.xml. This document will focus -on the kernel-side implementation of the media framework. - - -Abstract media device model ---------------------------- - -Discovering a device internal topology, and configuring it at runtime, is one -of the goals of the media framework. To achieve this, hardware devices are -modelled as an oriented graph of building blocks called entities connected -through pads. - -An entity is a basic media hardware building block. It can correspond to -a large variety of logical blocks such as physical hardware devices -(CMOS sensor for instance), logical hardware devices (a building block -in a System-on-Chip image processing pipeline), DMA channels or physical -connectors. - -A pad is a connection endpoint through which an entity can interact with -other entities. Data (not restricted to video) produced by an entity -flows from the entity's output to one or more entity inputs. Pads should -not be confused with physical pins at chip boundaries. - -A link is a point-to-point oriented connection between two pads, either -on the same entity or on different entities. Data flows from a source -pad to a sink pad. - - -Media device ------------- - -A media device is represented by a struct media_device instance, defined in -include/media/media-device.h. Allocation of the structure is handled by the -media device driver, usually by embedding the media_device instance in a -larger driver-specific structure. - -Drivers register media device instances by calling - - media_device_register(struct media_device *mdev); - -The caller is responsible for initializing the media_device structure before -registration. The following fields must be set: - - - dev must point to the parent device (usually a pci_dev, usb_interface or - platform_device instance). - - - model must be filled with the device model name as a NUL-terminated UTF-8 - string. The device/model revision must not be stored in this field. - -The following fields are optional: - - - serial is a unique serial number stored as a NUL-terminated ASCII string. - The field is big enough to store a GUID in text form. If the hardware - doesn't provide a unique serial number this field must be left empty. - - - bus_info represents the location of the device in the system as a - NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to - "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices, - the usb_make_path() function must be used. This field is used by - applications to distinguish between otherwise identical devices that don't - provide a serial number. - - - hw_revision is the hardware device revision in a driver-specific format. - When possible the revision should be formatted with the KERNEL_VERSION - macro. - - - driver_version is formatted with the KERNEL_VERSION macro. The version - minor must be incremented when new features are added to the userspace API - without breaking binary compatibility. The version major must be - incremented when binary compatibility is broken. - -Upon successful registration a character device named media[0-9]+ is created. -The device major and minor numbers are dynamic. The model name is exported as -a sysfs attribute. - -Drivers unregister media device instances by calling - - media_device_unregister(struct media_device *mdev); - -Unregistering a media device that hasn't been registered is *NOT* safe. - - -Entities, pads and links ------------------------- - -- Entities - -Entities are represented by a struct media_entity instance, defined in -include/media/media-entity.h. The structure is usually embedded into a -higher-level structure, such as a v4l2_subdev or video_device instance, -although drivers can allocate entities directly. - -Drivers initialize entities by calling - - media_entity_init(struct media_entity *entity, u16 num_pads, - struct media_pad *pads, u16 extra_links); - -The media_entity name, type, flags, revision and group_id fields can be -initialized before or after calling media_entity_init. Entities embedded in -higher-level standard structures can have some of those fields set by the -higher-level framework. - -As the number of pads is known in advance, the pads array is not allocated -dynamically but is managed by the entity driver. Most drivers will embed the -pads array in a driver-specific structure, avoiding dynamic allocation. - -Drivers must set the direction of every pad in the pads array before calling -media_entity_init. The function will initialize the other pads fields. - -Unlike the number of pads, the total number of links isn't always known in -advance by the entity driver. As an initial estimate, media_entity_init -pre-allocates a number of links equal to the number of pads plus an optional -number of extra links. The links array will be reallocated if it grows beyond -the initial estimate. - -Drivers register entities with a media device by calling - - media_device_register_entity(struct media_device *mdev, - struct media_entity *entity); - -Entities are identified by a unique positive integer ID. Drivers can provide an -ID by filling the media_entity id field prior to registration, or request the -media controller framework to assign an ID automatically. Drivers that provide -IDs manually must ensure that all IDs are unique. IDs are not guaranteed to be -contiguous even when they are all assigned automatically by the framework. - -Drivers unregister entities by calling - - media_device_unregister_entity(struct media_entity *entity); - -Unregistering an entity will not change the IDs of the other entities, and the -ID will never be reused for a newly registered entity. - -When a media device is unregistered, all its entities are unregistered -automatically. No manual entities unregistration is then required. - -Drivers free resources associated with an entity by calling - - media_entity_cleanup(struct media_entity *entity); - -This function must be called during the cleanup phase after unregistering the -entity. Note that the media_entity instance itself must be freed explicitly by -the driver if required. - -Entities have flags that describe the entity capabilities and state. - - MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type. - This can be used to report the default audio and video devices or the - default camera sensor. - -Logical entity groups can be defined by setting the group ID of all member -entities to the same non-zero value. An entity group serves no purpose in the -kernel, but is reported to userspace during entities enumeration. The group_id -field belongs to the media device driver and must not by touched by entity -drivers. - -Media device drivers should define groups if several entities are logically -bound together. Example usages include reporting - - - ALSA, VBI and video nodes that carry the same media stream - - lens and flash controllers associated with a sensor - -- Pads - -Pads are represented by a struct media_pad instance, defined in -include/media/media-entity.h. Each entity stores its pads in a pads array -managed by the entity driver. Drivers usually embed the array in a -driver-specific structure. - -Pads are identified by their entity and their 0-based index in the pads array. -Both information are stored in the media_pad structure, making the media_pad -pointer the canonical way to store and pass link references. - -Pads have flags that describe the pad capabilities and state. - - MEDIA_PAD_FL_SINK indicates that the pad supports sinking data. - MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data. - -One and only one of MEDIA_PAD_FL_SINK and MEDIA_PAD_FL_SOURCE must be set for -each pad. - -- Links - -Links are represented by a struct media_link instance, defined in -include/media/media-entity.h. Each entity stores all links originating at or -targeting any of its pads in a links array. A given link is thus stored -twice, once in the source entity and once in the target entity. The array is -pre-allocated and grows dynamically as needed. - -Drivers create links by calling - - media_entity_create_link(struct media_entity *source, u16 source_pad, - struct media_entity *sink, u16 sink_pad, - u32 flags); - -An entry in the link array of each entity is allocated and stores pointers -to source and sink pads. - -Links have flags that describe the link capabilities and state. - - MEDIA_LNK_FL_ENABLED indicates that the link is enabled and can be used - to transfer media data. When two or more links target a sink pad, only - one of them can be enabled at a time. - MEDIA_LNK_FL_IMMUTABLE indicates that the link enabled state can't be - modified at runtime. If MEDIA_LNK_FL_IMMUTABLE is set, then - MEDIA_LNK_FL_ENABLED must also be set since an immutable link is always - enabled. - - -Graph traversal ---------------- - -The media framework provides APIs to iterate over entities in a graph. - -To iterate over all entities belonging to a media device, drivers can use the -media_device_for_each_entity macro, defined in include/media/media-device.h. - - struct media_entity *entity; - - media_device_for_each_entity(entity, mdev) { - /* entity will point to each entity in turn */ - ... - } - -Drivers might also need to iterate over all entities in a graph that can be -reached only through enabled links starting at a given entity. The media -framework provides a depth-first graph traversal API for that purpose. - -Note that graphs with cycles (whether directed or undirected) are *NOT* -supported by the graph traversal API. To prevent infinite loops, the graph -traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH, -currently defined as 16. - -Drivers initiate a graph traversal by calling - - media_entity_graph_walk_start(struct media_entity_graph *graph, - struct media_entity *entity); - -The graph structure, provided by the caller, is initialized to start graph -traversal at the given entity. - -Drivers can then retrieve the next entity by calling - - media_entity_graph_walk_next(struct media_entity_graph *graph); - -When the graph traversal is complete the function will return NULL. - -Graph traversal can be interrupted at any moment. No cleanup function call is -required and the graph structure can be freed normally. - -Helper functions can be used to find a link between two given pads, or a pad -connected to another pad through an enabled link - - media_entity_find_link(struct media_pad *source, - struct media_pad *sink); - - media_entity_remote_pad(struct media_pad *pad); - -Refer to the kerneldoc documentation for more information. - - -Use count and power handling ----------------------------- - -Due to the wide differences between drivers regarding power management needs, -the media controller does not implement power management. However, the -media_entity structure includes a use_count field that media drivers can use to -track the number of users of every entity for power management needs. - -The use_count field is owned by media drivers and must not be touched by entity -drivers. Access to the field must be protected by the media device graph_mutex -lock. - - -Links setup ------------ - -Link properties can be modified at runtime by calling - - media_entity_setup_link(struct media_link *link, u32 flags); - -The flags argument contains the requested new link flags. - -The only configurable property is the ENABLED link flag to enable/disable a -link. Links marked with the IMMUTABLE link flag can not be enabled or disabled. - -When a link is enabled or disabled, the media framework calls the -link_setup operation for the two entities at the source and sink of the link, -in that order. If the second link_setup call fails, another link_setup call is -made on the first entity to restore the original link flags. - -Media device drivers can be notified of link setup operations by setting the -media_device::link_notify pointer to a callback function. If provided, the -notification callback will be called before enabling and after disabling -links. - -Entity drivers must implement the link_setup operation if any of their links -is non-immutable. The operation must either configure the hardware or store -the configuration information to be applied later. - -Link configuration must not have any side effect on other links. If an enabled -link at a sink pad prevents another link at the same pad from being enabled, -the link_setup operation must return -EBUSY and can't implicitly disable the -first enabled link. - - -Pipelines and media streams ---------------------------- - -When starting streaming, drivers must notify all entities in the pipeline to -prevent link states from being modified during streaming by calling - - media_entity_pipeline_start(struct media_entity *entity, - struct media_pipeline *pipe); - -The function will mark all entities connected to the given entity through -enabled links, either directly or indirectly, as streaming. - -The media_pipeline instance pointed to by the pipe argument will be stored in -every entity in the pipeline. Drivers should embed the media_pipeline structure -in higher-level pipeline structures and can then access the pipeline through -the media_entity pipe field. - -Calls to media_entity_pipeline_start() can be nested. The pipeline pointer must -be identical for all nested calls to the function. - -media_entity_pipeline_start() may return an error. In that case, it will -clean up any of the changes it did by itself. - -When stopping the stream, drivers must notify the entities with - - media_entity_pipeline_stop(struct media_entity *entity); - -If multiple calls to media_entity_pipeline_start() have been made the same -number of media_entity_pipeline_stop() calls are required to stop streaming. The -media_entity pipe field is reset to NULL on the last nested stop call. - -Link configuration will fail with -EBUSY by default if either end of the link is -a streaming entity. Links that can be modified while streaming must be marked -with the MEDIA_LNK_FL_DYNAMIC flag. - -If other operations need to be disallowed on streaming entities (such as -changing entities configuration parameters) drivers can explicitly check the -media_entity stream_count field to find out if an entity is streaming. This -operation must be done with the media_device graph_mutex held. - - -Link validation ---------------- - -Link validation is performed by media_entity_pipeline_start() for any -entity which has sink pads in the pipeline. The -media_entity::link_validate() callback is used for that purpose. In -link_validate() callback, entity driver should check that the properties of -the source pad of the connected entity and its own sink pad match. It is up -to the type of the entity (and in the end, the properties of the hardware) -what matching actually means. - -Subsystems should facilitate link validation by providing subsystem specific -helper functions to provide easy access for commonly needed information, and -in the end provide a way to use driver-specific callbacks. diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 2ba8461b0631..904ee42d078e 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -194,7 +194,7 @@ There are some minimal guarantees that may be expected of a CPU: (*) On any given CPU, dependent memory accesses will be issued in order, with respect to itself. This means that for: - WRITE_ONCE(Q, P); smp_read_barrier_depends(); D = READ_ONCE(*Q); + Q = READ_ONCE(P); smp_read_barrier_depends(); D = READ_ONCE(*Q); the CPU will issue the following memory operations: @@ -202,9 +202,9 @@ There are some minimal guarantees that may be expected of a CPU: and always in that order. On most systems, smp_read_barrier_depends() does nothing, but it is required for DEC Alpha. The READ_ONCE() - and WRITE_ONCE() are required to prevent compiler mischief. Please - note that you should normally use something like rcu_dereference() - instead of open-coding smp_read_barrier_depends(). + is required to prevent compiler mischief. Please note that you + should normally use something like rcu_dereference() instead of + open-coding smp_read_barrier_depends(). (*) Overlapping loads and stores within a particular CPU will appear to be ordered within that CPU. This means that for: @@ -617,16 +617,16 @@ case what's actually required is: However, stores are not speculated. This means that ordering -is- provided for load-store control dependencies, as in the following example: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); if (q) { WRITE_ONCE(b, p); } Control dependencies pair normally with other types of barriers. That -said, please note that READ_ONCE_CTRL() is not optional! Without the -READ_ONCE_CTRL(), the compiler might combine the load from 'a' with -other loads from 'a', and the store to 'b' with other stores to 'b', -with possible highly counterintuitive effects on ordering. +said, please note that READ_ONCE() is not optional! Without the +READ_ONCE(), the compiler might combine the load from 'a' with other +loads from 'a', and the store to 'b' with other stores to 'b', with +possible highly counterintuitive effects on ordering. Worse yet, if the compiler is able to prove (say) that the value of variable 'a' is always non-zero, it would be well within its rights @@ -636,15 +636,12 @@ as follows: q = a; b = p; /* BUG: Compiler and CPU can both reorder!!! */ -Finally, the READ_ONCE_CTRL() includes an smp_read_barrier_depends() -that DEC Alpha needs in order to respect control depedencies. - -So don't leave out the READ_ONCE_CTRL(). +So don't leave out the READ_ONCE(). It is tempting to try to enforce ordering on identical stores on both branches of the "if" statement as follows: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); if (q) { barrier(); WRITE_ONCE(b, p); @@ -658,7 +655,7 @@ branches of the "if" statement as follows: Unfortunately, current compilers will transform this as follows at high optimization levels: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); barrier(); WRITE_ONCE(b, p); /* BUG: No ordering vs. load from a!!! */ if (q) { @@ -688,7 +685,7 @@ memory barriers, for example, smp_store_release(): In contrast, without explicit memory barriers, two-legged-if control ordering is guaranteed only when the stores differ, for example: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); if (q) { WRITE_ONCE(b, p); do_something(); @@ -697,14 +694,14 @@ ordering is guaranteed only when the stores differ, for example: do_something_else(); } -The initial READ_ONCE_CTRL() is still required to prevent the compiler -from proving the value of 'a'. +The initial READ_ONCE() is still required to prevent the compiler from +proving the value of 'a'. In addition, you need to be careful what you do with the local variable 'q', otherwise the compiler might be able to guess the value and again remove the needed conditional. For example: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); if (q % MAX) { WRITE_ONCE(b, p); do_something(); @@ -717,7 +714,7 @@ If MAX is defined to be 1, then the compiler knows that (q % MAX) is equal to zero, in which case the compiler is within its rights to transform the above code into the following: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); WRITE_ONCE(b, p); do_something_else(); @@ -728,7 +725,7 @@ is gone, and the barrier won't bring it back. Therefore, if you are relying on this ordering, you should make sure that MAX is greater than one, perhaps as follows: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */ if (q % MAX) { WRITE_ONCE(b, p); @@ -745,7 +742,7 @@ of the 'if' statement. You must also be careful not to rely too much on boolean short-circuit evaluation. Consider this example: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); if (q || 1 > 0) WRITE_ONCE(b, 1); @@ -753,7 +750,7 @@ Because the first condition cannot fault and the second condition is always true, the compiler can transform this example as following, defeating control dependency: - q = READ_ONCE_CTRL(a); + q = READ_ONCE(a); WRITE_ONCE(b, 1); This example underscores the need to ensure that the compiler cannot @@ -767,7 +764,7 @@ x and y both being zero: CPU 0 CPU 1 ======================= ======================= - r1 = READ_ONCE_CTRL(x); r2 = READ_ONCE_CTRL(y); + r1 = READ_ONCE(x); r2 = READ_ONCE(y); if (r1 > 0) if (r2 > 0) WRITE_ONCE(y, 1); WRITE_ONCE(x, 1); @@ -796,11 +793,6 @@ site: https://www.cl.cam.ac.uk/~pes20/ppcmem/index.html. In summary: - (*) Control dependencies must be headed by READ_ONCE_CTRL(). - Or, as a much less preferable alternative, interpose - smp_read_barrier_depends() between a READ_ONCE() and the - control-dependent write. - (*) Control dependencies can order prior loads against later stores. However, they do -not- guarantee any other sort of ordering: Not prior loads against later loads, nor prior stores against @@ -816,14 +808,13 @@ In summary: between the prior load and the subsequent store, and this conditional must involve the prior load. If the compiler is able to optimize the conditional away, it will have also optimized - away the ordering. Careful use of READ_ONCE_CTRL() READ_ONCE(), - and WRITE_ONCE() can help to preserve the needed conditional. + away the ordering. Careful use of READ_ONCE() and WRITE_ONCE() + can help to preserve the needed conditional. (*) Control dependencies require that the compiler avoid reordering the - dependency into nonexistence. Careful use of READ_ONCE_CTRL() - or smp_read_barrier_depends() can help to preserve your control - dependency. Please see the Compiler Barrier section for more - information. + dependency into nonexistence. Careful use of READ_ONCE() or + atomic{,64}_read() can help to preserve your control dependency. + Please see the Compiler Barrier section for more information. (*) Control dependencies pair normally with other types of barriers. @@ -1664,17 +1655,18 @@ macro is a good place to start looking. SMP memory barriers are reduced to compiler barriers on uniprocessor compiled systems because it is assumed that a CPU will appear to be self-consistent, and will order overlapping accesses correctly with respect to itself. +However, see the subsection on "Virtual Machine Guests" below. [!] Note that SMP memory barriers _must_ be used to control the ordering of references to shared memory on SMP systems, though the use of locking instead is sufficient. Mandatory barriers should not be used to control SMP effects, since mandatory -barriers unnecessarily impose overhead on UP systems. They may, however, be -used to control MMIO effects on accesses through relaxed memory I/O windows. -These are required even on non-SMP systems as they affect the order in which -memory operations appear to a device by prohibiting both the compiler and the -CPU from reordering them. +barriers impose unnecessary overhead on both SMP and UP systems. They may, +however, be used to control MMIO effects on accesses through relaxed memory I/O +windows. These barriers are required even on non-SMP systems as they affect +the order in which memory operations appear to a device by prohibiting both the +compiler and the CPU from reordering them. There are some more advanced barrier functions: @@ -1682,8 +1674,8 @@ There are some more advanced barrier functions: (*) smp_store_mb(var, value) This assigns the value to the variable and then inserts a full memory - barrier after it, depending on the function. It isn't guaranteed to - insert anything more than a compiler barrier in a UP compilation. + barrier after it. It isn't guaranteed to insert anything more than a + compiler barrier in a UP compilation. (*) smp_mb__before_atomic(); @@ -1710,6 +1702,17 @@ There are some more advanced barrier functions: operations" subsection for information on where to use these. + (*) lockless_dereference(); + This can be thought of as a pointer-fetch wrapper around the + smp_read_barrier_depends() data-dependency barrier. + + This is also similar to rcu_dereference(), but in cases where + object lifetime is handled by some mechanism other than RCU, for + example, when the objects removed only when the system goes down. + In addition, lockless_dereference() is used in some data structures + that can be used both with and without RCU. + + (*) dma_wmb(); (*) dma_rmb(); @@ -1789,7 +1792,6 @@ The Linux kernel has a number of locking constructs: (*) mutexes (*) semaphores (*) R/W semaphores - (*) RCU In all cases there are variants on "ACQUIRE" operations and "RELEASE" operations for each construct. These operations all imply certain barriers: @@ -2947,6 +2949,23 @@ The Alpha defines the Linux kernel's memory barrier model. See the subsection on "Cache Coherency" above. +VIRTUAL MACHINE GUESTS +------------------- + +Guests running within virtual machines might be affected by SMP effects even if +the guest itself is compiled without SMP support. This is an artifact of +interfacing with an SMP host while running an UP kernel. Using mandatory +barriers for this use-case would be possible but is often suboptimal. + +To handle this case optimally, low-level virt_mb() etc macros are available. +These have the same effect as smp_mb() etc when SMP is enabled, but generate +identical code for SMP and non-SMP systems. For example, virtual machine guests +should use virt_mb() rather than smp_mb() when synchronizing against a +(possibly SMP) host. + +These are equivalent to smp_mb() etc counterparts in all other respects, +in particular, they do not control MMIO effects: to control +MMIO effects, use mandatory barriers. ============ EXAMPLE USES diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index ce2cfcf35c27..443f4b44ad97 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -256,10 +256,27 @@ If the memory block is offline, you'll read "offline". 5.2. How to online memory ------------ -Even if the memory is hot-added, it is not at ready-to-use state. -For using newly added memory, you have to "online" the memory block. +When the memory is hot-added, the kernel decides whether or not to "online" +it according to the policy which can be read from "auto_online_blocks" file: -For onlining, you have to write "online" to the memory block's state file as: +% cat /sys/devices/system/memory/auto_online_blocks + +The default is "offline" which means the newly added memory is not in a +ready-to-use state and you have to "online" the newly added memory blocks +manually. Automatic onlining can be requested by writing "online" to +"auto_online_blocks" file: + +% echo online > /sys/devices/system/memory/auto_online_blocks + +This sets a global policy and impacts all memory blocks that will subsequently +be hotplugged. Currently offline blocks keep their state. It is possible, under +certain circumstances, that some memory blocks will be added but will fail to +online. User space tools can check their "state" files +(/sys/devices/system/memory/memoryXXX/state) and try to online them manually. + +If the automatic onlining wasn't requested, failed, or some memory block was +offlined it is possible to change the individual block's state by writing to the +"state" file: % echo online > /sys/devices/system/memory/memoryXXX/state diff --git a/Documentation/mic/mic_overview.txt b/Documentation/mic/mic_overview.txt index 1a2f2c8ec59e..074adbdf83a4 100644 --- a/Documentation/mic/mic_overview.txt +++ b/Documentation/mic/mic_overview.txt @@ -12,10 +12,19 @@ for the X100 devices. Since it is a PCIe card, it does not have the ability to host hardware devices for networking, storage and console. We provide these devices -on X100 coprocessors thus enabling a self-bootable equivalent environment -for applications. A key benefit of our solution is that it leverages -the standard virtio framework for network, disk and console devices, -though in our case the virtio framework is used across a PCIe bus. +on X100 coprocessors thus enabling a self-bootable equivalent +environment for applications. A key benefit of our solution is that it +leverages the standard virtio framework for network, disk and console +devices, though in our case the virtio framework is used across a PCIe +bus. A Virtio Over PCIe (VOP) driver allows creating user space +backends or devices on the host which are used to probe virtio drivers +for these devices on the MIC card. The existing VRINGH infrastructure +in the kernel is used to access virtio rings from the host. The card +VOP driver allows card virtio drivers to communicate with their user +space backends on the host via a device page. Ring 3 apps on the host +can add, remove and configure virtio devices. A thin MIC specific +virtio_config_ops is implemented which is borrowed heavily from +previous similar implementations in lguest and s390. MIC PCIe card has a dma controller with 8 channels. These channels are shared between the host s/w and the card s/w. 0 to 3 are used by host @@ -28,13 +37,16 @@ The Symmetric Communication Interface (SCIF (pronounced as skiff)) is a low level communications API across PCIe currently implemented for MIC. More details are available at scif_overview.txt. +The Coprocessor State Management (COSM) driver on the host allows for +boot, shutdown and reset of Intel MIC devices. It communicates with a COSM +"client" driver on the MIC cards over SCIF to perform these functions. + Here is a block diagram of the various components described above. The virtio backends are situated on the host rather than the card given better single threaded performance for the host compared to MIC, the ability of the host to initiate DMA's to/from the card using the MIC DMA engine and the fact that the virtio block storage backend can only be on the host. - | +----------+ | +----------+ | Card OS | | | Host OS | +----------+ | +----------+ @@ -43,27 +55,26 @@ the fact that the virtio block storage backend can only be on the host. | Virtio| |Virtio | |Virtio| | |Virtio | |Virtio | |Virtio | | Net | |Console | |Block | | |Net | |Console | |Block | | Driver| |Driver | |Driver| | |backend | |backend | |backend | - +-------+ +--------+ +------+ | +---------+ +--------+ +--------+ + +---+---+ +---+----+ +--+---+ | +---------+ +----+---+ +--------+ | | | | | | | | | | |User | | | - | | | |------|------------|---------|------- - +-------------------+ |Kernel +--------------------------+ - | | | Virtio over PCIe IOCTLs | - | | +--------------------------+ -+-----------+ | | | +-----------+ -| MIC DMA | | +----------+ | +-----------+ | | MIC DMA | -| Driver | | | SCIF | | | SCIF | | | Driver | -+-----------+ | +----------+ | +-----------+ | +-----------+ - | | | | | | | -+---------------+ | +-----+-----+ | +-----+-----+ | +---------------+ -|MIC virtual Bus| | |SCIF HW Bus| | |SCIF HW BUS| | |MIC virtual Bus| -+---------------+ | +-----------+ | +-----+-----+ | +---------------+ - | | | | | | | - | +--------------+ | | | +---------------+ | - | |Intel MIC | | | | |Intel MIC | | - +---|Card Driver +----+ | | |Host Driver | | - +--------------+ | +----+---------------+-----+ - | | | + | | | |------|------------|--+------|------- + +---------+---------+ |Kernel | + | | | + +---------+ +---+----+ +------+ | +------+ +------+ +--+---+ +-------+ + |MIC DMA | | VOP | | SCIF | | | SCIF | | COSM | | VOP | |MIC DMA| + +---+-----+ +---+----+ +--+---+ | +--+---+ +--+---+ +------+ +----+--+ + | | | | | | | + +---+-----+ +---+----+ +--+---+ | +--+---+ +--+---+ +------+ +----+--+ + |MIC | | VOP | |SCIF | | |SCIF | | COSM | | VOP | | MIC | + |HW Bus | | HW Bus| |HW Bus| | |HW Bus| | Bus | |HW Bus| |HW Bus | + +---------+ +--------+ +--+---+ | +--+---+ +------+ +------+ +-------+ + | | | | | | | + | +-----------+--+ | | | +---------------+ | + | |Intel MIC | | | | |Intel MIC | | + | |Card Driver | | | | |Host Driver | | + +---+--------------+------+ | +----+---------------+-----+ + | | | +-------------------------------------------------------------+ | | | PCIe Bus | diff --git a/Documentation/mic/mpssd/mpss b/Documentation/mic/mpssd/mpss index 582aad4811ae..5fcf9fa4b082 100755 --- a/Documentation/mic/mpssd/mpss +++ b/Documentation/mic/mpssd/mpss @@ -35,7 +35,7 @@ exec=/usr/sbin/mpssd sysfs="/sys/class/mic" -mic_modules="mic_host mic_x100_dma scif" +mic_modules="mic_host mic_x100_dma scif vop" start() { @@ -119,10 +119,10 @@ stop() # Wait for the cards to go offline for f in $sysfs/* do - while [ "`cat $f/state`" != "offline" ] + while [ "`cat $f/state`" != "ready" ] do sleep 1 - echo -e "Waiting for "`basename $f`" to go offline" + echo -e "Waiting for "`basename $f`" to become ready" done done diff --git a/Documentation/mic/mpssd/mpssd.c b/Documentation/mic/mpssd/mpssd.c index 3c5c379fc29d..30fb842a976d 100644 --- a/Documentation/mic/mpssd/mpssd.c +++ b/Documentation/mic/mpssd/mpssd.c @@ -43,7 +43,7 @@ #include <linux/mic_common.h> #include <tools/endian.h> -static void init_mic(struct mic_info *mic); +static void *init_mic(void *arg); static FILE *logfp; static struct mic_info mic_list; @@ -116,19 +116,18 @@ static struct { .num = htole16(MIC_VRING_ENTRIES), }, #if GSO_ENABLED - .host_features = htole32( + .host_features = htole32( 1 << VIRTIO_NET_F_CSUM | 1 << VIRTIO_NET_F_GSO | 1 << VIRTIO_NET_F_GUEST_TSO4 | 1 << VIRTIO_NET_F_GUEST_TSO6 | - 1 << VIRTIO_NET_F_GUEST_ECN | - 1 << VIRTIO_NET_F_GUEST_UFO), + 1 << VIRTIO_NET_F_GUEST_ECN), #else .host_features = 0, #endif }; -static const char *mic_config_dir = "/etc/sysconfig/mic"; +static const char *mic_config_dir = "/etc/mpss"; static const char *virtblk_backend = "VIRTBLK_BACKEND"; static struct { struct mic_device_desc dd; @@ -192,7 +191,7 @@ tap_configure(struct mic_info *mic, char *dev) return ret; } - snprintf(ipaddr, IFNAMSIZ, "172.31.%d.254/24", mic->id); + snprintf(ipaddr, IFNAMSIZ, "172.31.%d.254/24", mic->id + 1); pid = fork(); if (pid == 0) { @@ -255,8 +254,7 @@ static int tun_alloc(struct mic_info *mic, char *dev) return err; } #if GSO_ENABLED - offload = TUN_F_CSUM | TUN_F_TSO4 | TUN_F_TSO6 | - TUN_F_TSO_ECN | TUN_F_UFO; + offload = TUN_F_CSUM | TUN_F_TSO4 | TUN_F_TSO6 | TUN_F_TSO_ECN; err = ioctl(fd, TUNSETOFFLOAD, offload); if (err < 0) { @@ -332,7 +330,6 @@ static struct mic_device_desc *get_device_desc(struct mic_info *mic, int type) return d; } mpsslog("%s %s %d not found\n", mic->name, __func__, type); - assert(0); return NULL; } @@ -352,7 +349,7 @@ static ssize_t sum_iovec_len(struct mic_copy_desc *copy) { ssize_t sum = 0; - int i; + unsigned int i; for (i = 0; i < copy->iovcnt; i++) sum += copy->iov[i].iov_len; @@ -375,7 +372,7 @@ static void disp_iovec(struct mic_info *mic, struct mic_copy_desc *copy, const char *s, int line) { - int i; + unsigned int i; for (i = 0; i < copy->iovcnt; i++) mpsslog("%s %s %d copy->iov[%d] addr %p len 0x%zx\n", @@ -415,6 +412,13 @@ mic_virtio_copy(struct mic_info *mic, int fd, return ret; } +static inline unsigned _vring_size(unsigned int num, unsigned long align) +{ + return ((sizeof(struct vring_desc) * num + sizeof(__u16) * (3 + num) + + align - 1) & ~(align - 1)) + + sizeof(__u16) * 3 + sizeof(struct vring_used_elem) * num; +} + /* * This initialization routine requires at least one * vring i.e. vr0. vr1 is optional. @@ -426,8 +430,9 @@ init_vr(struct mic_info *mic, int fd, int type, int vr_size; char *va; - vr_size = PAGE_ALIGN(vring_size(MIC_VRING_ENTRIES, - MIC_VIRTIO_RING_ALIGN) + sizeof(struct _mic_vring_info)); + vr_size = PAGE_ALIGN(_vring_size(MIC_VRING_ENTRIES, + MIC_VIRTIO_RING_ALIGN) + + sizeof(struct _mic_vring_info)); va = mmap(NULL, MIC_DEVICE_PAGE_END + vr_size * num_vq, PROT_READ, MAP_SHARED, fd, 0); if (MAP_FAILED == va) { @@ -439,25 +444,25 @@ init_vr(struct mic_info *mic, int fd, int type, set_dp(mic, type, va); vr0->va = (struct mic_vring *)&va[MIC_DEVICE_PAGE_END]; vr0->info = vr0->va + - vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN); + _vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN); vring_init(&vr0->vr, MIC_VRING_ENTRIES, vr0->va, MIC_VIRTIO_RING_ALIGN); mpsslog("%s %s vr0 %p vr0->info %p vr_size 0x%x vring 0x%x ", __func__, mic->name, vr0->va, vr0->info, vr_size, - vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN)); + _vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN)); mpsslog("magic 0x%x expected 0x%x\n", le32toh(vr0->info->magic), MIC_MAGIC + type); assert(le32toh(vr0->info->magic) == MIC_MAGIC + type); if (vr1) { vr1->va = (struct mic_vring *) &va[MIC_DEVICE_PAGE_END + vr_size]; - vr1->info = vr1->va + vring_size(MIC_VRING_ENTRIES, + vr1->info = vr1->va + _vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN); vring_init(&vr1->vr, MIC_VRING_ENTRIES, vr1->va, MIC_VIRTIO_RING_ALIGN); mpsslog("%s %s vr1 %p vr1->info %p vr_size 0x%x vring 0x%x ", __func__, mic->name, vr1->va, vr1->info, vr_size, - vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN)); + _vring_size(MIC_VRING_ENTRIES, MIC_VIRTIO_RING_ALIGN)); mpsslog("magic 0x%x expected 0x%x\n", le32toh(vr1->info->magic), MIC_MAGIC + type + 1); assert(le32toh(vr1->info->magic) == MIC_MAGIC + type + 1); @@ -466,16 +471,21 @@ done: return va; } -static void +static int wait_for_card_driver(struct mic_info *mic, int fd, int type) { struct pollfd pollfd; int err; struct mic_device_desc *desc = get_device_desc(mic, type); + __u8 prev_status; + if (!desc) + return -ENODEV; + prev_status = desc->status; pollfd.fd = fd; mpsslog("%s %s Waiting .... desc-> type %d status 0x%x\n", mic->name, __func__, type, desc->status); + while (1) { pollfd.events = POLLIN; pollfd.revents = 0; @@ -487,8 +497,13 @@ wait_for_card_driver(struct mic_info *mic, int fd, int type) } if (pollfd.revents) { - mpsslog("%s %s Waiting... desc-> type %d status 0x%x\n", - mic->name, __func__, type, desc->status); + if (desc->status != prev_status) { + mpsslog("%s %s Waiting... desc-> type %d " + "status 0x%x\n", + mic->name, __func__, type, + desc->status); + prev_status = desc->status; + } if (desc->status & VIRTIO_CONFIG_S_DRIVER_OK) { mpsslog("%s %s poll.revents %d\n", mic->name, __func__, pollfd.revents); @@ -499,6 +514,7 @@ wait_for_card_driver(struct mic_info *mic, int fd, int type) } } } + return 0; } /* Spin till we have some descriptors */ @@ -575,9 +591,16 @@ virtio_net(void *arg) __func__, strerror(errno)); continue; } - if (!(desc->status & VIRTIO_CONFIG_S_DRIVER_OK)) - wait_for_card_driver(mic, mic->mic_net.virtio_net_fd, - VIRTIO_ID_NET); + if (!(desc->status & VIRTIO_CONFIG_S_DRIVER_OK)) { + err = wait_for_card_driver(mic, + mic->mic_net.virtio_net_fd, + VIRTIO_ID_NET); + if (err) { + mpsslog("%s %s %d Exiting...\n", + mic->name, __func__, __LINE__); + break; + } + } /* * Check if there is data to be read from TUN and write to * virtio net fd if there is. @@ -786,10 +809,16 @@ virtio_console(void *arg) strerror(errno)); continue; } - if (!(desc->status & VIRTIO_CONFIG_S_DRIVER_OK)) - wait_for_card_driver(mic, - mic->mic_console.virtio_console_fd, - VIRTIO_ID_CONSOLE); + if (!(desc->status & VIRTIO_CONFIG_S_DRIVER_OK)) { + err = wait_for_card_driver(mic, + mic->mic_console.virtio_console_fd, + VIRTIO_ID_CONSOLE); + if (err) { + mpsslog("%s %s %d Exiting...\n", + mic->name, __func__, __LINE__); + break; + } + } if (console_poll[MONITOR_FD].revents & POLLIN) { copy.iov = iov0; @@ -897,7 +926,7 @@ add_virtio_device(struct mic_info *mic, struct mic_device_desc *dd) char path[PATH_MAX]; int fd, err; - snprintf(path, PATH_MAX, "/dev/mic%d", mic->id); + snprintf(path, PATH_MAX, "/dev/vop_virtio%d", mic->id); fd = open(path, O_RDWR); if (fd < 0) { mpsslog("Could not open %s %s\n", path, strerror(errno)); @@ -1048,8 +1077,9 @@ stop_virtblk(struct mic_info *mic) { int vr_size, ret; - vr_size = PAGE_ALIGN(vring_size(MIC_VRING_ENTRIES, - MIC_VIRTIO_RING_ALIGN) + sizeof(struct _mic_vring_info)); + vr_size = PAGE_ALIGN(_vring_size(MIC_VRING_ENTRIES, + MIC_VIRTIO_RING_ALIGN) + + sizeof(struct _mic_vring_info)); ret = munmap(mic->mic_virtblk.block_dp, MIC_DEVICE_PAGE_END + vr_size * virtblk_dev_page.dd.num_vq); if (ret < 0) @@ -1131,6 +1161,10 @@ write_status(int fd, __u8 *status) return ioctl(fd, MIC_VIRTIO_COPY_DESC, ©); } +#ifndef VIRTIO_BLK_T_GET_ID +#define VIRTIO_BLK_T_GET_ID 8 +#endif + static void * virtio_block(void *arg) { @@ -1297,12 +1331,7 @@ reset(struct mic_info *mic) mpsslog("%s: %s %d state %s\n", mic->name, __func__, __LINE__, state); - /* - * If the shutdown was initiated by OSPM, the state stays - * in "suspended" which is also a valid condition for reset. - */ - if ((!strcmp(state, "offline")) || - (!strcmp(state, "suspended"))) { + if (!strcmp(state, "ready")) { free(state); break; } @@ -1331,34 +1360,50 @@ get_mic_shutdown_status(struct mic_info *mic, char *shutdown_status) assert(0); }; -static int get_mic_state(struct mic_info *mic, char *state) +static int get_mic_state(struct mic_info *mic) { - if (!strcmp(state, "offline")) - return MIC_OFFLINE; - if (!strcmp(state, "online")) - return MIC_ONLINE; - if (!strcmp(state, "shutting_down")) - return MIC_SHUTTING_DOWN; - if (!strcmp(state, "reset_failed")) - return MIC_RESET_FAILED; - if (!strcmp(state, "suspending")) - return MIC_SUSPENDING; - if (!strcmp(state, "suspended")) - return MIC_SUSPENDED; - mpsslog("%s: BUG invalid state %s\n", mic->name, state); - /* Invalid state */ - assert(0); + char *state = NULL; + enum mic_states mic_state; + + while (!state) { + state = readsysfs(mic->name, "state"); + sleep(1); + } + mpsslog("%s: %s %d state %s\n", + mic->name, __func__, __LINE__, state); + + if (!strcmp(state, "ready")) { + mic_state = MIC_READY; + } else if (!strcmp(state, "booting")) { + mic_state = MIC_BOOTING; + } else if (!strcmp(state, "online")) { + mic_state = MIC_ONLINE; + } else if (!strcmp(state, "shutting_down")) { + mic_state = MIC_SHUTTING_DOWN; + } else if (!strcmp(state, "reset_failed")) { + mic_state = MIC_RESET_FAILED; + } else if (!strcmp(state, "resetting")) { + mic_state = MIC_RESETTING; + } else { + mpsslog("%s: BUG invalid state %s\n", mic->name, state); + assert(0); + } + + free(state); + return mic_state; }; static void mic_handle_shutdown(struct mic_info *mic) { #define SHUTDOWN_TIMEOUT 60 - int i = SHUTDOWN_TIMEOUT, ret, stat = 0; + int i = SHUTDOWN_TIMEOUT; char *shutdown_status; while (i) { shutdown_status = readsysfs(mic->name, "shutdown_status"); - if (!shutdown_status) + if (!shutdown_status) { + sleep(1); continue; + } mpsslog("%s: %s %d shutdown_status %s\n", mic->name, __func__, __LINE__, shutdown_status); switch (get_mic_shutdown_status(mic, shutdown_status)) { @@ -1377,94 +1422,110 @@ static void mic_handle_shutdown(struct mic_info *mic) i--; } reset: - ret = kill(mic->pid, SIGTERM); - mpsslog("%s: %s %d kill pid %d ret %d\n", - mic->name, __func__, __LINE__, - mic->pid, ret); - if (!ret) { - ret = waitpid(mic->pid, &stat, - WIFSIGNALED(stat)); - mpsslog("%s: %s %d waitpid ret %d pid %d\n", - mic->name, __func__, __LINE__, - ret, mic->pid); - } - if (ret == mic->pid) - reset(mic); + if (!i) + mpsslog("%s: %s %d timing out waiting for shutdown_status %s\n", + mic->name, __func__, __LINE__, shutdown_status); + reset(mic); } -static void * -mic_config(void *arg) +static int open_state_fd(struct mic_info *mic) { - struct mic_info *mic = (struct mic_info *)arg; - char *state = NULL; char pathname[PATH_MAX]; - int fd, ret; - struct pollfd ufds[1]; - char value[4096]; + int fd; snprintf(pathname, PATH_MAX - 1, "%s/%s/%s", MICSYSFSDIR, mic->name, "state"); fd = open(pathname, O_RDONLY); - if (fd < 0) { + if (fd < 0) mpsslog("%s: opening file %s failed %s\n", mic->name, pathname, strerror(errno)); - goto error; + return fd; +} + +static int block_till_state_change(int fd, struct mic_info *mic) +{ + struct pollfd ufds[1]; + char value[PAGE_SIZE]; + int ret; + + ufds[0].fd = fd; + ufds[0].events = POLLERR | POLLPRI; + ret = poll(ufds, 1, -1); + if (ret < 0) { + mpsslog("%s: %s %d poll failed %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + return ret; + } + + ret = lseek(fd, 0, SEEK_SET); + if (ret < 0) { + mpsslog("%s: %s %d Failed to seek to 0: %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + return ret; + } + + ret = read(fd, value, sizeof(value)); + if (ret < 0) { + mpsslog("%s: %s %d Failed to read sysfs entry: %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + return ret; + } + + return 0; +} + +static void * +mic_config(void *arg) +{ + struct mic_info *mic = (struct mic_info *)arg; + int fd, ret, stat = 0; + + fd = open_state_fd(mic); + if (fd < 0) { + mpsslog("%s: %s %d open state fd failed %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + goto exit; } do { - ret = lseek(fd, 0, SEEK_SET); - if (ret < 0) { - mpsslog("%s: Failed to seek to file start '%s': %s\n", - mic->name, pathname, strerror(errno)); - goto close_error1; - } - ret = read(fd, value, sizeof(value)); + ret = block_till_state_change(fd, mic); if (ret < 0) { - mpsslog("%s: Failed to read sysfs entry '%s': %s\n", - mic->name, pathname, strerror(errno)); - goto close_error1; + mpsslog("%s: %s %d block_till_state_change error %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + goto close_exit; } -retry: - state = readsysfs(mic->name, "state"); - if (!state) - goto retry; - mpsslog("%s: %s %d state %s\n", - mic->name, __func__, __LINE__, state); - switch (get_mic_state(mic, state)) { + + switch (get_mic_state(mic)) { case MIC_SHUTTING_DOWN: mic_handle_shutdown(mic); - goto close_error; - case MIC_SUSPENDING: - mic->boot_on_resume = 1; - setsysfs(mic->name, "state", "suspend"); - mic_handle_shutdown(mic); - goto close_error; - case MIC_OFFLINE: + break; + case MIC_READY: + case MIC_RESET_FAILED: + ret = kill(mic->pid, SIGTERM); + mpsslog("%s: %s %d kill pid %d ret %d\n", + mic->name, __func__, __LINE__, + mic->pid, ret); + if (!ret) { + ret = waitpid(mic->pid, &stat, + WIFSIGNALED(stat)); + mpsslog("%s: %s %d waitpid ret %d pid %d\n", + mic->name, __func__, __LINE__, + ret, mic->pid); + } if (mic->boot_on_resume) { setsysfs(mic->name, "state", "boot"); mic->boot_on_resume = 0; } - break; + goto close_exit; default: break; } - free(state); - - ufds[0].fd = fd; - ufds[0].events = POLLERR | POLLPRI; - ret = poll(ufds, 1, -1); - if (ret < 0) { - mpsslog("%s: poll failed %s\n", - mic->name, strerror(errno)); - goto close_error1; - } } while (1); -close_error: - free(state); -close_error1: + +close_exit: close(fd); -error: +exit: init_mic(mic); pthread_exit(NULL); } @@ -1477,15 +1538,15 @@ set_cmdline(struct mic_info *mic) len = snprintf(buffer, PATH_MAX, "clocksource=tsc highres=off nohz=off "); - len += snprintf(buffer + len, PATH_MAX - len, + len += snprintf(buffer + len, PATH_MAX, "cpufreq_on;corec6_off;pc3_off;pc6_off "); - len += snprintf(buffer + len, PATH_MAX - len, + len += snprintf(buffer + len, PATH_MAX, "ifcfg=static;address,172.31.%d.1;netmask,255.255.255.0", - mic->id); + mic->id + 1); setsysfs(mic->name, "cmdline", buffer); mpsslog("%s: Command line: \"%s\"\n", mic->name, buffer); - snprintf(buffer, PATH_MAX, "172.31.%d.1", mic->id); + snprintf(buffer, PATH_MAX, "172.31.%d.1", mic->id + 1); mpsslog("%s: IPADDR: \"%s\"\n", mic->name, buffer); } @@ -1541,8 +1602,6 @@ set_log_buf_info(struct mic_info *mic) close(fd); } -static void init_mic(struct mic_info *mic); - static void change_virtblk_backend(int x, siginfo_t *siginfo, void *p) { @@ -1553,8 +1612,16 @@ change_virtblk_backend(int x, siginfo_t *siginfo, void *p) } static void -init_mic(struct mic_info *mic) +set_mic_boot_params(struct mic_info *mic) +{ + set_log_buf_info(mic); + set_cmdline(mic); +} + +static void * +init_mic(void *arg) { + struct mic_info *mic = (struct mic_info *)arg; struct sigaction ignore = { .sa_flags = 0, .sa_handler = SIG_IGN @@ -1564,7 +1631,7 @@ init_mic(struct mic_info *mic) .sa_sigaction = change_virtblk_backend, }; char buffer[PATH_MAX]; - int err; + int err, fd; /* * Currently, one virtio block device is supported for each MIC card @@ -1577,12 +1644,38 @@ init_mic(struct mic_info *mic) * the MIC daemon. */ sigaction(SIGUSR1, &ignore, NULL); +retry: + fd = open_state_fd(mic); + if (fd < 0) { + mpsslog("%s: %s %d open state fd failed %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + sleep(2); + goto retry; + } + + if (mic->restart) { + snprintf(buffer, PATH_MAX, "boot"); + setsysfs(mic->name, "state", buffer); + mpsslog("%s restarting mic %d\n", + mic->name, mic->restart); + mic->restart = 0; + } + + while (1) { + while (block_till_state_change(fd, mic)) { + mpsslog("%s: %s %d block_till_state_change error %s\n", + mic->name, __func__, __LINE__, strerror(errno)); + sleep(2); + continue; + } + + if (get_mic_state(mic) == MIC_BOOTING) + break; + } mic->pid = fork(); switch (mic->pid) { case 0: - set_log_buf_info(mic); - set_cmdline(mic); add_virtio_device(mic, &virtcons_dev_page.dd); add_virtio_device(mic, &virtnet_dev_page.dd); err = pthread_create(&mic->mic_console.console_thread, NULL, @@ -1612,24 +1705,29 @@ init_mic(struct mic_info *mic) mic->name, mic->id, errno); break; default: - if (mic->restart) { - snprintf(buffer, PATH_MAX, "boot"); - setsysfs(mic->name, "state", buffer); - mpsslog("%s restarting mic %d\n", - mic->name, mic->restart); - mic->restart = 0; - } - pthread_create(&mic->config_thread, NULL, mic_config, mic); + err = pthread_create(&mic->config_thread, NULL, + mic_config, mic); + if (err) + mpsslog("%s mic_config pthread_create failed %s\n", + mic->name, strerror(err)); } + + return NULL; } static void start_daemon(void) { struct mic_info *mic; + int err; - for (mic = mic_list.next; mic != NULL; mic = mic->next) - init_mic(mic); + for (mic = mic_list.next; mic; mic = mic->next) { + set_mic_boot_params(mic); + err = pthread_create(&mic->init_thread, NULL, init_mic, mic); + if (err) + mpsslog("%s init_mic pthread_create failed %s\n", + mic->name, strerror(err)); + } while (1) sleep(60); diff --git a/Documentation/mic/mpssd/mpssd.h b/Documentation/mic/mpssd/mpssd.h index f5f18b15d9a0..8bd64944aacc 100644 --- a/Documentation/mic/mpssd/mpssd.h +++ b/Documentation/mic/mpssd/mpssd.h @@ -86,6 +86,7 @@ struct mic_info { int id; char *name; pthread_t config_thread; + pthread_t init_thread; pid_t pid; struct mic_console_info mic_console; struct mic_net_info mic_net; diff --git a/Documentation/misc-devices/apds990x.txt b/Documentation/misc-devices/apds990x.txt index d5408cade32f..454d95d623b3 100644 --- a/Documentation/misc-devices/apds990x.txt +++ b/Documentation/misc-devices/apds990x.txt @@ -30,7 +30,7 @@ lead to false interrupt, but that doesn't harm. ALS contains 4 different gain steps. Driver automatically selects suitable gain step. After each measurement, reliability of the results -is estimated and new measurement is trigged if necessary. +is estimated and new measurement is triggered if necessary. Platform data can provide tuned values to the conversion formulas if values are known. Otherwise plain sensor default values are used. diff --git a/Documentation/misc-devices/isl29003 b/Documentation/misc-devices/isl29003 index c4ff5f38e010..80b952fd32ff 100644 --- a/Documentation/misc-devices/isl29003 +++ b/Documentation/misc-devices/isl29003 @@ -29,7 +29,7 @@ Detection The ISL29003 does not have an ID register which could be used to identify it, so the detection routine will just try to read from the configured I2C -addess and consider the device to be present as soon as it ACKs the +address and consider the device to be present as soon as it ACKs the transfer. diff --git a/Documentation/misc-devices/lcd-panel-cgram.txt b/Documentation/misc-devices/lcd-panel-cgram.txt new file mode 100644 index 000000000000..7f82c905763d --- /dev/null +++ b/Documentation/misc-devices/lcd-panel-cgram.txt @@ -0,0 +1,24 @@ +Some LCDs allow you to define up to 8 characters, mapped to ASCII +characters 0 to 7. The escape code to define a new character is +'\e[LG' followed by one digit from 0 to 7, representing the character +number, and up to 8 couples of hex digits terminated by a semi-colon +(';'). Each couple of digits represents a line, with 1-bits for each +illuminated pixel with LSB on the right. Lines are numbered from the +top of the character to the bottom. On a 5x7 matrix, only the 5 lower +bits of the 7 first bytes are used for each character. If the string +is incomplete, only complete lines will be redefined. Here are some +examples : + + printf "\e[LG0010101050D1F0C04;" => 0 = [enter] + printf "\e[LG1040E1F0000000000;" => 1 = [up] + printf "\e[LG2000000001F0E0400;" => 2 = [down] + printf "\e[LG3040E1F001F0E0400;" => 3 = [up-down] + printf "\e[LG40002060E1E0E0602;" => 4 = [left] + printf "\e[LG500080C0E0F0E0C08;" => 5 = [right] + printf "\e[LG60016051516141400;" => 6 = "IP" + + printf "\e[LG00103071F1F070301;" => big speaker + printf "\e[LG00002061E1E060200;" => small speaker + +Willy + diff --git a/Documentation/misc-devices/max6875 b/Documentation/misc-devices/max6875 index 1e89ee3ccc1b..2f2bd0b17b5d 100644 --- a/Documentation/misc-devices/max6875 +++ b/Documentation/misc-devices/max6875 @@ -22,7 +22,7 @@ At reset, the MAX6875 reads the configuration EEPROM into its configuration registers. The chip then begins to operate according to the values in the registers. -The Maxim MAX6874 is a similar, mostly compatible device, with more intputs +The Maxim MAX6874 is a similar, mostly compatible device, with more inputs and outputs: vin gpi vout MAX6874 6 4 8 diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/misc-devices/mei/mei.txt index 91c1fa34f48b..2b80a0cd621f 100644 --- a/Documentation/misc-devices/mei/mei.txt +++ b/Documentation/misc-devices/mei/mei.txt @@ -231,15 +231,15 @@ IT knows when a platform crashes even when there is a hard failure on the host. The Intel AMT Watchdog is composed of two parts: 1) Firmware feature - receives the heartbeats and sends an event when the heartbeats stop. - 2) Intel MEI driver - connects to the watchdog feature, configures the - watchdog and sends the heartbeats. + 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature, + configures the watchdog and sends the heartbeats. -The Intel MEI driver uses the kernel watchdog API to configure the Intel AMT -Watchdog and to send heartbeats to it. The default timeout of the +The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure +the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the watchdog is 120 seconds. -If the Intel AMT Watchdog feature does not exist (i.e. the connection failed), -the Intel MEI driver will disable the sending of heartbeats. +If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate +on the me client bus and watchdog devices won't be exposed. Supported Chipsets diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.txt index 189bab09255a..caa555706f89 100644 --- a/Documentation/mmc/mmc-dev-attrs.txt +++ b/Documentation/mmc/mmc-dev-attrs.txt @@ -72,13 +72,3 @@ Note on raw_rpmb_size_mult: "raw_rpmb_size_mult" is a mutliple of 128kB block. RPMB size in byte is calculated by using the following equation: RPMB partition size = 128kB x raw_rpmb_size_mult - -SD/MMC/SDIO Clock Gating Attribute -================================== - -Read and write access is provided to following attribute. -This attribute appears only if CONFIG_MMC_CLKGATE is enabled. - - clkgate_delay Tune the clock gating delay with desired value in milliseconds. - -echo <desired delay> > /sys/class/mmc_host/mmcX/clkgate_delay diff --git a/Documentation/module-signing.txt b/Documentation/module-signing.txt index a78bf1ffa68c..696d5caf4fd8 100644 --- a/Documentation/module-signing.txt +++ b/Documentation/module-signing.txt @@ -254,7 +254,7 @@ signature checking is all done within the kernel. NON-VALID SIGNATURES AND UNSIGNED MODULES ========================================= -If CONFIG_MODULE_SIG_FORCE is enabled or enforcemodulesig=1 is supplied on +If CONFIG_MODULE_SIG_FORCE is enabled or module.sig_enforce=1 is supplied on the kernel command line, the kernel will only load validly signed modules for which it has a public key. Otherwise, it will also load modules that are unsigned. Any module for which the kernel has a key, but which proves to have diff --git a/Documentation/mtd/nand_ecc.txt b/Documentation/mtd/nand_ecc.txt index e129b2479ea8..f8c3284bf6a7 100644 --- a/Documentation/mtd/nand_ecc.txt +++ b/Documentation/mtd/nand_ecc.txt @@ -107,7 +107,7 @@ for (i = 0; i < 256; i++) if (i & 0x01) rp1 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1; else - rp0 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1; + rp0 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp0; if (i & 0x02) rp3 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp3; else @@ -127,7 +127,7 @@ for (i = 0; i < 256; i++) if (i & 0x20) rp11 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp11; else - rp10 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp10; + rp10 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp10; if (i & 0x40) rp13 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp13; else @@ -158,7 +158,7 @@ the values in any order. So instead of calculating all the bits individually, let us try to rearrange things. For the column parity this is easy. We can just xor the bytes and in the end filter out the relevant bits. This is pretty nice as it will bring -all cp calculation out of the if loop. +all cp calculation out of the for loop. Similarly we can first xor the bytes for the various rows. This leads to: @@ -271,11 +271,11 @@ to write our code in such a way that we process data in 32 bit chunks. Of course this means some modification as the row parity is byte by byte. A quick analysis: for the column parity we use the par variable. When extending to 32 bits -we can in the end easily calculate p0 and p1 from it. +we can in the end easily calculate rp0 and rp1 from it. (because par now consists of 4 bytes, contributing to rp1, rp0, rp1, rp0 -respectively) +respectively, from MSB to LSB) also rp2 and rp3 can be easily retrieved from par as rp3 covers the -first two bytes and rp2 the last two bytes. +first two MSBs and rp2 covers the last two LSBs. Note that of course now the loop is executed only 64 times (256/4). And note that care must taken wrt byte ordering. The way bytes are @@ -387,11 +387,11 @@ Analysis 2 The code (of course) works, and hurray: we are a little bit faster than the linux driver code (about 15%). But wait, don't cheer too quickly. -THere is more to be gained. +There is more to be gained. If we look at e.g. rp14 and rp15 we see that we either xor our data with rp14 or with rp15. However we also have par which goes over all data. This means there is no need to calculate rp14 as it can be calculated from -rp15 through rp14 = par ^ rp15; +rp15 through rp14 = par ^ rp15, because par = rp14 ^ rp15; (or if desired we can avoid calculating rp15 and calculate it from rp14). That is why some places refer to inverse parity. Of course the same thing holds for rp4/5, rp6/7, rp8/9, rp10/11 and rp12/13. @@ -419,12 +419,12 @@ with if (i & 0x20) rp15 ^= cur; and outside the loop added: - rp4 = par ^ rp5; - rp6 = par ^ rp7; - rp8 = par ^ rp9; - rp10 = par ^ rp11; - rp12 = par ^ rp13; - rp14 = par ^ rp15; + rp4 = par ^ rp5; + rp6 = par ^ rp7; + rp8 = par ^ rp9; + rp10 = par ^ rp11; + rp12 = par ^ rp13; + rp14 = par ^ rp15; And after that the code takes about 30% more time, although the number of statements is reduced. This is also reflected in the assembly code. @@ -524,12 +524,12 @@ THe code within the for loop was changed to: cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; cur = *bp++; tmppar ^= cur; rp6 ^= cur; - cur = *bp++; tmppar ^= cur; rp4 ^= cur; - cur = *bp++; tmppar ^= cur; rp10 ^= tmppar; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp10 ^= tmppar; - cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; rp8 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; rp8 ^= cur; cur = *bp++; tmppar ^= cur; rp6 ^= cur; rp8 ^= cur; - cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp8 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp8 ^= cur; cur = *bp++; tmppar ^= cur; rp8 ^= cur; cur = *bp++; tmppar ^= cur; rp4 ^= cur; rp6 ^= cur; @@ -537,7 +537,7 @@ THe code within the for loop was changed to: cur = *bp++; tmppar ^= cur; rp4 ^= cur; cur = *bp++; tmppar ^= cur; - par ^= tmppar; + par ^= tmppar; if ((i & 0x1) == 0) rp12 ^= tmppar; if ((i & 0x2) == 0) rp14 ^= tmppar; } @@ -548,8 +548,8 @@ to rp12 and rp14. While making the changes I also found that I could exploit that tmppar contains the running parity for this iteration. So instead of having: -rp4 ^= cur; rp6 = cur; -I removed the rp6 = cur; statement and did rp6 ^= tmppar; on next +rp4 ^= cur; rp6 ^= cur; +I removed the rp6 ^= cur; statement and did rp6 ^= tmppar; on next statement. A similar change was done for rp8 and rp10 @@ -593,22 +593,22 @@ The new code now looks like: cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; cur = *bp++; tmppar ^= cur; rp6 ^= cur; - cur = *bp++; tmppar ^= cur; rp4 ^= cur; - cur = *bp++; tmppar ^= cur; rp10 ^= tmppar; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp10 ^= tmppar; - notrp8 = tmppar; - cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; + notrp8 = tmppar; + cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; cur = *bp++; tmppar ^= cur; rp6 ^= cur; - cur = *bp++; tmppar ^= cur; rp4 ^= cur; + cur = *bp++; tmppar ^= cur; rp4 ^= cur; cur = *bp++; tmppar ^= cur; - rp8 = rp8 ^ tmppar ^ notrp8; + rp8 = rp8 ^ tmppar ^ notrp8; cur = *bp++; tmppar ^= cur; rp4_6 ^= cur; cur = *bp++; tmppar ^= cur; rp6 ^= cur; cur = *bp++; tmppar ^= cur; rp4 ^= cur; cur = *bp++; tmppar ^= cur; - par ^= tmppar; + par ^= tmppar; if ((i & 0x1) == 0) rp12 ^= tmppar; if ((i & 0x2) == 0) rp14 ^= tmppar; } @@ -700,7 +700,7 @@ Conclusion The gain when calculating the ecc is tremendous. Om my development hardware a speedup of a factor of 18 for ecc calculation was achieved. On a test on an embedded system with a MIPS core a factor 7 was obtained. -On a test with a Linksys NSLU2 (ARMv5TE processor) the speedup was a factor +On a test with a Linksys NSLU2 (ARMv5TE processor) the speedup was a factor 5 (big endian mode, gcc 4.1.2, -O3) For correction not much gain could be obtained (as bitflips are rare). Then again there are also much less cycles spent there. diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index df27a1a50776..415154a487d0 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -44,6 +44,8 @@ can.txt - documentation on CAN protocol family. cdc_mbim.txt - 3G/LTE USB modem (Mobile Broadband Interface Model) +checksum-offloads.txt + - Explanation of checksum offloads; LCO, RCO cops.txt - info on the COPS LocalTalk Linux driver cs89x0.txt diff --git a/Documentation/networking/batman-adv.txt b/Documentation/networking/batman-adv.txt index 58e49042fc20..1b5e7a7f2185 100644 --- a/Documentation/networking/batman-adv.txt +++ b/Documentation/networking/batman-adv.txt @@ -115,14 +115,17 @@ The "bat0" interface can be used like any other regular inter- face. It needs an IP address which can be either statically con- figured or dynamically (by using DHCP or similar services): -# NodeA: ifconfig bat0 192.168.0.1 -# NodeB: ifconfig bat0 192.168.0.2 +# NodeA: ip link set up dev bat0 +# NodeA: ip addr add 192.168.0.1/24 dev bat0 + +# NodeB: ip link set up dev bat0 +# NodeB: ip addr add 192.168.0.2/24 dev bat0 # NodeB: ping 192.168.0.1 Note: In order to avoid problems remove all IP addresses previ- ously assigned to interfaces now used by batman advanced, e.g. -# ifconfig eth0 0.0.0.0 +# ip addr flush dev eth0 LOGGING/DEBUGGING @@ -184,7 +187,7 @@ interfaces to the kernel module settings. For more information, please see the manpage (man batctl). -batctl is available on http://www.open-mesh.org/ +batctl is available on https://www.open-mesh.org/ CONTACT diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt index fd1a1aad49a9..6ab619fcc517 100644 --- a/Documentation/networking/can.txt +++ b/Documentation/networking/can.txt @@ -372,6 +372,15 @@ solution for a couple of reasons: 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 @@ -681,7 +690,7 @@ solution for a couple of reasons: addr.can_family = AF_CAN; addr.can_ifindex = ifr.ifr_ifindex; - connect(s, (struct sockaddr *)&addr, sizeof(addr)) + connect(s, (struct sockaddr *)&addr, sizeof(addr)); (..) @@ -1018,25 +1027,34 @@ solution for a couple of reasons: $ ip link set can0 type can help Usage: ip link set DEVICE type can - [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] | - [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1 - phase-seg2 PHASE-SEG2 [ sjw SJW ] ] - - [ loopback { on | off } ] - [ listen-only { on | off } ] - [ triple-sampling { on | off } ] - - [ restart-ms TIME-MS ] - [ restart ] - - Where: BITRATE := { 1..1000000 } - SAMPLE-POINT := { 0.000..0.999 } - TQ := { NUMBER } - PROP-SEG := { 1..8 } - PHASE-SEG1 := { 1..8 } - PHASE-SEG2 := { 1..8 } - SJW := { 1..4 } - RESTART-MS := { 0 | NUMBER } + [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] | + [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1 + phase-seg2 PHASE-SEG2 [ sjw SJW ] ] + + [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] | + [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1 + dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ] + + [ loopback { on | off } ] + [ listen-only { on | off } ] + [ triple-sampling { on | off } ] + [ one-shot { on | off } ] + [ berr-reporting { on | off } ] + [ fd { on | off } ] + [ fd-non-iso { on | off } ] + [ presume-ack { on | off } ] + + [ restart-ms TIME-MS ] + [ restart ] + + Where: BITRATE := { 1..1000000 } + SAMPLE-POINT := { 0.000..0.999 } + TQ := { NUMBER } + PROP-SEG := { 1..8 } + PHASE-SEG1 := { 1..8 } + PHASE-SEG2 := { 1..8 } + SJW := { 1..4 } + RESTART-MS := { 0 | NUMBER } - Display CAN device details and statistics: @@ -1178,7 +1196,55 @@ solution for a couple of reasons: The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall. N.B. CAN FD capable devices can also handle and send legacy CAN frames. - FIXME: Add details about the CAN FD controller configuration when available. + When configuring CAN FD capable CAN controllers an additional 'data' bitrate + has to be set. This bitrate for the data phase of the CAN FD frame has to be + at least the bitrate which was configured for the arbitration phase. This + second bitrate is specified analogue to the first bitrate but the bitrate + setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate, + dsample-point, dsjw or dtq and similar settings. When a data bitrate is set + within the configuration process the controller option "fd on" can be + specified to enable the CAN FD mode in the CAN controller. This controller + option also switches the device MTU to 72 (CANFD_MTU). + + The first CAN FD specification presented as whitepaper at the International + CAN Conference 2012 needed to be improved for data integrity reasons. + Therefore two CAN FD implementations have to be distinguished today: + + - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default) + - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper + + Finally there are three types of CAN FD controllers: + + 1. ISO compliant (fixed) + 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c) + 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD) + + The current ISO/non-ISO mode is announced by the CAN controller driver via + netlink and displayed by the 'ip' tool (controller option FD-NON-ISO). + The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for + switchable CAN FD controllers only. + + Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate: + + $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \ + dbitrate 4000000 dsample-point 0.8 fd on + $ ip -details link show can0 + 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \ + mode DEFAULT group default qlen 10 + link/can promiscuity 0 + can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 + bitrate 500000 sample-point 0.750 + tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1 + pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \ + brp-inc 1 + dbitrate 4000000 dsample-point 0.800 + dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1 + pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \ + dbrp-inc 1 + clock 80000000 + + Example when 'fd-non-iso on' is added on this switchable CAN FD adapter: + can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 6.7 Supported CAN hardware diff --git a/Documentation/networking/checksum-offloads.txt b/Documentation/networking/checksum-offloads.txt new file mode 100644 index 000000000000..de2a327766a7 --- /dev/null +++ b/Documentation/networking/checksum-offloads.txt @@ -0,0 +1,119 @@ +Checksum Offloads in the Linux Networking Stack + + +Introduction +============ + +This document describes a set of techniques in the Linux networking stack + to take advantage of checksum offload capabilities of various NICs. + +The following technologies are described: + * TX Checksum Offload + * LCO: Local Checksum Offload + * RCO: Remote Checksum Offload + +Things that should be documented here but aren't yet: + * RX Checksum Offload + * CHECKSUM_UNNECESSARY conversion + + +TX Checksum Offload +=================== + +The interface for offloading a transmit checksum to a device is explained + in detail in comments near the top of include/linux/skbuff.h. +In brief, it allows to request the device fill in a single ones-complement + checksum defined by the sk_buff fields skb->csum_start and + skb->csum_offset. The device should compute the 16-bit ones-complement + checksum (i.e. the 'IP-style' checksum) from csum_start to the end of the + packet, and fill in the result at (csum_start + csum_offset). +Because csum_offset cannot be negative, this ensures that the previous + value of the checksum field is included in the checksum computation, thus + it can be used to supply any needed corrections to the checksum (such as + the sum of the pseudo-header for UDP or TCP). +This interface only allows a single checksum to be offloaded. Where + encapsulation is used, the packet may have multiple checksum fields in + different header layers, and the rest will have to be handled by another + mechanism such as LCO or RCO. +No offloading of the IP header checksum is performed; it is always done in + software. This is OK because when we build the IP header, we obviously + have it in cache, so summing it isn't expensive. It's also rather short. +The requirements for GSO are more complicated, because when segmenting an + encapsulated packet both the inner and outer checksums may need to be + edited or recomputed for each resulting segment. See the skbuff.h comment + (section 'E') for more details. + +A driver declares its offload capabilities in netdev->hw_features; see + Documentation/networking/netdev-features for more. Note that a device + which only advertises NETIF_F_IP[V6]_CSUM must still obey the csum_start + and csum_offset given in the SKB; if it tries to deduce these itself in + hardware (as some NICs do) the driver should check that the values in the + SKB match those which the hardware will deduce, and if not, fall back to + checksumming in software instead (with skb_checksum_help or one of the + skb_csum_off_chk* functions as mentioned in include/linux/skbuff.h). This + is a pain, but that's what you get when hardware tries to be clever. + +The stack should, for the most part, assume that checksum offload is + supported by the underlying device. The only place that should check is + validate_xmit_skb(), and the functions it calls directly or indirectly. + That function compares the offload features requested by the SKB (which + may include other offloads besides TX Checksum Offload) and, if they are + not supported or enabled on the device (determined by netdev->features), + performs the corresponding offload in software. In the case of TX + Checksum Offload, that means calling skb_checksum_help(skb). + + +LCO: Local Checksum Offload +=========================== + +LCO is a technique for efficiently computing the outer checksum of an + encapsulated datagram when the inner checksum is due to be offloaded. +The ones-complement sum of a correctly checksummed TCP or UDP packet is + equal to the sum of the pseudo header, because everything else gets + 'cancelled out' by the checksum field. This is because the sum was + complemented before being written to the checksum field. +More generally, this holds in any case where the 'IP-style' ones complement + checksum is used, and thus any checksum that TX Checksum Offload supports. +That is, if we have set up TX Checksum Offload with a start/offset pair, we + know that _after the device has filled in that checksum_, the ones + complement sum from csum_start to the end of the packet will be equal to + _whatever value we put in the checksum field beforehand_. This allows us + to compute the outer checksum without looking at the payload: we simply + stop summing when we get to csum_start, then add the 16-bit word at + (csum_start + csum_offset). +Then, when the true inner checksum is filled in (either by hardware or by + skb_checksum_help()), the outer checksum will become correct by virtue of + the arithmetic. + +LCO is performed by the stack when constructing an outer UDP header for an + encapsulation such as VXLAN or GENEVE, in udp_set_csum(). Similarly for + the IPv6 equivalents, in udp6_set_csum(). +It is also performed when constructing an IPv4 GRE header, in + net/ipv4/ip_gre.c:build_header(). It is *not* currently performed when + constructing an IPv6 GRE header; the GRE checksum is computed over the + whole packet in net/ipv6/ip6_gre.c:ip6gre_xmit2(), but it should be + possible to use LCO here as IPv6 GRE still uses an IP-style checksum. +All of the LCO implementations use a helper function lco_csum(), in + include/linux/skbuff.h. + +LCO can safely be used for nested encapsulations; in this case, the outer + encapsulation layer will sum over both its own header and the 'middle' + header. This does mean that the 'middle' header will get summed multiple + times, but there doesn't seem to be a way to avoid that without incurring + bigger costs (e.g. in SKB bloat). + + +RCO: Remote Checksum Offload +============================ + +RCO is a technique for eliding the inner checksum of an encapsulated + datagram, allowing the outer checksum to be offloaded. It does, however, + involve a change to the encapsulation protocols, which the receiver must + also support. For this reason, it is disabled by default. +RCO is detailed in the following Internet-Drafts: +https://tools.ietf.org/html/draft-herbert-remotecsumoffload-00 +https://tools.ietf.org/html/draft-herbert-vxlan-rco-00 +In Linux, RCO is implemented individually in each encapsulation protocol, + and most tunnel types have flags controlling its use. For instance, VXLAN + has the flag VXLAN_F_REMCSUM_TX (per struct vxlan_rdst) to indicate that + RCO should be used when transmitting to a given remote destination. diff --git a/Documentation/networking/dsa/dsa.txt b/Documentation/networking/dsa/dsa.txt index aa9c1f9313cd..3b196c304b73 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.txt @@ -521,20 +521,17 @@ See Documentation/hwmon/sysfs-interface for details. Bridge layer ------------ -- port_join_bridge: bridge layer function invoked when a given switch port is +- port_bridge_join: bridge layer function invoked when a given switch port is added to a bridge, this function should be doing the necessary at the switch level to permit the joining port from being added to the relevant logical - domain for it to ingress/egress traffic with other members of the bridge. DSA - does nothing but calculate a bitmask of switch ports currently members of the - specified bridge being requested the join + domain for it to ingress/egress traffic with other members of the bridge. -- port_leave_bridge: bridge layer function invoked when a given switch port is +- port_bridge_leave: bridge layer function invoked when a given switch port is removed from a bridge, this function should be doing the necessary at the switch level to deny the leaving port from ingress/egress traffic from the remaining bridge members. When the port leaves the bridge, it should be aged out at the switch hardware for the switch to (re) learn MAC addresses behind - this port. DSA calculates the bitmask of ports still members of the bridge - being left + this port. - port_stp_update: bridge layer function invoked when a given switch port STP state is computed by the bridge layer and should be propagated to switch @@ -545,20 +542,15 @@ Bridge layer Bridge VLAN filtering --------------------- -- port_pvid_get: bridge layer function invoked when a Port-based VLAN ID is - queried for the given switch port - -- port_pvid_set: bridge layer function invoked when a Port-based VLAN ID needs - to be configured on the given switch port - - port_vlan_add: bridge layer function invoked when a VLAN is configured (tagged or untagged) for the given switch port - port_vlan_del: bridge layer function invoked when a VLAN is removed from the given switch port -- vlan_getnext: bridge layer function invoked to query the next configured VLAN - in the switch, i.e. returns the bitmaps of members and untagged ports +- port_vlan_dump: bridge layer function invoked with a switchdev callback + function that the driver has to call for each VLAN the given port is a member + of. A switchdev object is used to carry the VID and bridge flags. - port_fdb_add: bridge layer function invoked when the bridge wants to install a Forwarding Database entry, the switch hardware should be programmed with the diff --git a/Documentation/networking/e100.txt b/Documentation/networking/e100.txt index f862cf3aff34..42ddbd4b52a9 100644 --- a/Documentation/networking/e100.txt +++ b/Documentation/networking/e100.txt @@ -181,17 +181,3 @@ For general information, go to the Intel support website at: If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to e1000-devel@lists.sourceforge.net. - - -License -======= - -This software program is released under the terms of a license agreement -between you ('Licensee') and Intel. Do not use or load this software or any -associated materials (collectively, the 'Software') until you have carefully -read the full terms and conditions of the file COPYING located in this software -package. By loading or using the Software, you agree to the terms of this -Agreement. If you do not agree with the terms of this Agreement, do not install -or use the Software. - -* Other names and brands may be claimed as the property of others. diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 135581f015e1..96da119a47e7 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -596,9 +596,9 @@ skb pointer). All constraints and restrictions from bpf_check_classic() apply before a conversion to the new layout is being done behind the scenes! Currently, the classic BPF format is being used for JITing on most of the -architectures. Only x86-64 performs JIT compilation from eBPF instruction set, -however, future work will migrate other JIT compilers as well, so that they -will profit from the very same benefits. +architectures. x86-64, aarch64 and s390x perform JIT compilation from eBPF +instruction set, however, future work will migrate other JIT compilers as well, +so that they will profit from the very same benefits. Some core changes of the new internal format: diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt index 1700756af057..aa69ccc481db 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.txt @@ -7,11 +7,11 @@ Introduction The IEEE 802.15.4 working group focuses on standardization of bottom two layers: Medium Access Control (MAC) and Physical (PHY). And there are mainly two options available for upper layers: - - ZigBee - proprietary protocol from ZigBee Alliance - - 6LowPAN - IPv6 networking over low rate personal area networks + - ZigBee - proprietary protocol from the ZigBee Alliance + - 6LoWPAN - IPv6 networking over low rate personal area networks -The Linux-ZigBee project goal is to provide complete implementation -of IEEE 802.15.4 and 6LoWPAN protocols. IEEE 802.15.4 is a stack +The linux-wpan project goal is to provide a complete implementation +of the IEEE 802.15.4 and 6LoWPAN protocols. IEEE 802.15.4 is a stack of protocols for organizing Low-Rate Wireless Personal Area Networks. The stack is composed of three main parts: diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index ebe94f2cab98..d5df40c75aa4 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -335,6 +335,14 @@ tcp_keepalive_intvl - INTEGER after probes started. Default value: 75sec i.e. connection will be aborted after ~11 minutes of retries. +tcp_l3mdev_accept - BOOLEAN + Enables child sockets to inherit the L3 master device index. + Enabling this option allows a "global" listen socket to work + across L3 master domains (e.g., VRFs) with connected sockets + derived from the listen socket to be bound to the L3 domain in + which the packets originated. Only valid when the kernel was + compiled with CONFIG_NET_L3_MASTER_DEV. + tcp_low_latency - BOOLEAN If set, the TCP stack makes decisions that prefer lower latency as opposed to higher throughput. By default, this @@ -384,6 +392,14 @@ tcp_mem - vector of 3 INTEGERs: min, pressure, max Defaults are calculated at boot time from amount of available memory. +tcp_min_rtt_wlen - INTEGER + The window length of the windowed min filter to track the minimum RTT. + A shorter window lets a flow more quickly pick up new (higher) + minimum RTT when it is moved to a longer path (e.g., due to traffic + engineering). A longer window makes the filter more resistant to RTT + inflations such as transient congestion. The unit is seconds. + Default: 300 + tcp_moderate_rcvbuf - BOOLEAN If set, TCP performs receive buffer auto-tuning, attempting to automatically size the buffer (no greater than tcp_rmem[2]) to @@ -425,6 +441,15 @@ tcp_orphan_retries - INTEGER you should think about lowering this value, such sockets may consume significant resources. Cf. tcp_max_orphans. +tcp_recovery - INTEGER + This value is a bitmap to enable various experimental loss recovery + features. + + RACK: 0x1 enables the RACK loss detection for fast detection of lost + retransmissions and tail drops. + + Default: 0x1 + tcp_reordering - INTEGER Initial reordering level of packets in a TCP stream. TCP stack can then dynamically adjust flow reordering level @@ -569,7 +594,7 @@ tcp_fastopen - INTEGER tcp_syn_retries - INTEGER Number of times initial SYNs for an active TCP connection attempt - will be retransmitted. Should not be higher than 255. Default value + will be retransmitted. Should not be higher than 127. Default value is 6, which corresponds to 63seconds till the last retransmission with the current initial RTO of 1second. With this the final timeout for an active TCP connection attempt will happen after 127seconds. @@ -692,7 +717,7 @@ tcp_limit_output_bytes - INTEGER typical pfifo_fast qdiscs. tcp_limit_output_bytes limits the number of bytes on qdisc or device to reduce artificial RTT/cwnd and reduce bufferbloat. - Default: 131072 + Default: 262144 tcp_challenge_ack_limit - INTEGER Limits number of Challenge ACK sent per second, as recommended @@ -1191,6 +1216,19 @@ promote_secondaries - BOOLEAN promote a corresponding secondary IP address instead of removing all the corresponding secondary IP addresses. +drop_unicast_in_l2_multicast - BOOLEAN + Drop any unicast IP packets that are received in link-layer + multicast (or broadcast) frames. + This behavior (for multicast) is actually a SHOULD in RFC + 1122, but is disabled by default for compatibility reasons. + Default: off (0) + +drop_gratuitous_arp - BOOLEAN + Drop all gratuitous ARP frames, for example if there's a known + good ARP proxy on the network and such frames need not be used + (or in the case of 802.11, must not be used to prevent attacks.) + Default: off (0) + tag - INTEGER Allows you to write a number, which can be used as required. @@ -1199,7 +1237,8 @@ tag - INTEGER xfrm4_gc_thresh - INTEGER The threshold at which we will start garbage collecting for IPv4 destination cache entries. At twice this value the system will - refuse new allocations. + refuse new allocations. The value must be set below the flowcache + limit (4096 * number of online cpus) to take effect. igmp_link_local_mcast_reports - BOOLEAN Enable IGMP reports for link local multicast groups in the @@ -1524,6 +1563,15 @@ temp_prefered_lft - INTEGER Preferred lifetime (in seconds) for temporary addresses. Default: 86400 (1 day) +keep_addr_on_down - INTEGER + Keep all IPv6 addresses on an interface down event. If set static + global addresses with no expiration time are not flushed. + >0 : enabled + 0 : system default + <0 : disabled + + Default: 0 (addresses are removed) + max_desync_factor - INTEGER Maximum value for DESYNC_FACTOR, which is a random value that ensures that clients don't synchronize with each @@ -1635,6 +1683,19 @@ stable_secret - IPv6 address By default the stable secret is unset. +drop_unicast_in_l2_multicast - BOOLEAN + Drop any unicast IPv6 packets that are received in link-layer + multicast (or broadcast) frames. + + By default this is turned off. + +drop_unsolicited_na - BOOLEAN + Drop all unsolicited neighbor advertisements, for example if there's + a known good NA proxy on the network and such frames need not be used + (or in the case of 802.11, must not be used to prevent attacks.) + + By default this is turned off. + icmp/*: ratelimit - INTEGER Limit the maximal rates for sending ICMPv6 packets. @@ -1645,7 +1706,8 @@ ratelimit - INTEGER xfrm6_gc_thresh - INTEGER The threshold at which we will start garbage collecting for IPv6 destination cache entries. At twice this value the system will - refuse new allocations. + refuse new allocations. The value must be set below the flowcache + limit (4096 * number of online cpus) to take effect. IPv6 Update by: @@ -1704,6 +1766,25 @@ addip_enable - BOOLEAN Default: 0 +pf_enable - INTEGER + Enable or disable pf (pf is short for potentially failed) state. A value + of pf_retrans > path_max_retrans also disables pf state. That is, one of + both pf_enable and pf_retrans > path_max_retrans can disable pf state. + Since pf_retrans and path_max_retrans can be changed by userspace + application, sometimes user expects to disable pf state by the value of + pf_retrans > path_max_retrans, but occasionally the value of pf_retrans + or path_max_retrans is changed by the user application, this pf state is + enabled. As such, it is necessary to add this to dynamically enable + and disable pf state. See: + https://datatracker.ietf.org/doc/draft-ietf-tsvwg-sctp-failover for + details. + + 1: Enable pf. + + 0: Disable pf. + + Default: 1 + addip_noauth_enable - BOOLEAN Dynamic Address Reconfiguration (ADD-IP) requires the use of authentication to protect the operations of adding or removing new @@ -1780,7 +1861,9 @@ pf_retrans - INTEGER having to reduce path_max_retrans to a very low value. See: http://www.ietf.org/id/draft-nishida-tsvwg-sctp-failover-05.txt for details. Note also that a value of pf_retrans > path_max_retrans - disables this feature + disables this feature. Since both pf_retrans and path_max_retrans can + be changed by userspace application, a variable pf_enable is used to + disable pf state. Default: 0 diff --git a/Documentation/networking/ipvs-sysctl.txt b/Documentation/networking/ipvs-sysctl.txt index 3ba709531adb..e6b1c025fdd8 100644 --- a/Documentation/networking/ipvs-sysctl.txt +++ b/Documentation/networking/ipvs-sysctl.txt @@ -157,6 +157,16 @@ expire_quiescent_template - BOOLEAN persistence template if it is to be used to schedule a new connection and the destination server is quiescent. +ignore_tunneled - BOOLEAN + 0 - disabled (default) + not 0 - enabled + + If set, ipvs will set the ipvs_property on all packets which are of + unrecognized protocols. This prevents us from routing tunneled + protocols like ipip, which is useful to prevent rescheduling + packets that have been tunneled to the ipvs host (i.e. to prevent + ipvs routing loops when ipvs is also acting as a real server). + nat_icmp_send - BOOLEAN 0 - disabled (default) not 0 - enabled diff --git a/Documentation/networking/kcm.txt b/Documentation/networking/kcm.txt new file mode 100644 index 000000000000..3476ede5bc2c --- /dev/null +++ b/Documentation/networking/kcm.txt @@ -0,0 +1,285 @@ +Kernel Connection Mulitplexor +----------------------------- + +Kernel Connection Multiplexor (KCM) is a mechanism that provides a message based +interface over TCP for generic application protocols. With KCM an application +can efficiently send and receive application protocol messages over TCP using +datagram sockets. + +KCM implements an NxM multiplexor in the kernel as diagrammed below: + ++------------+ +------------+ +------------+ +------------+ +| KCM socket | | KCM socket | | KCM socket | | KCM socket | ++------------+ +------------+ +------------+ +------------+ + | | | | + +-----------+ | | +----------+ + | | | | + +----------------------------------+ + | Multiplexor | + +----------------------------------+ + | | | | | + +---------+ | | | ------------+ + | | | | | ++----------+ +----------+ +----------+ +----------+ +----------+ +| Psock | | Psock | | Psock | | Psock | | Psock | ++----------+ +----------+ +----------+ +----------+ +----------+ + | | | | | ++----------+ +----------+ +----------+ +----------+ +----------+ +| TCP sock | | TCP sock | | TCP sock | | TCP sock | | TCP sock | ++----------+ +----------+ +----------+ +----------+ +----------+ + +KCM sockets +----------- + +The KCM sockets provide the user interface to the muliplexor. All the KCM sockets +bound to a multiplexor are considered to have equivalent function, and I/O +operations in different sockets may be done in parallel without the need for +synchronization between threads in userspace. + +Multiplexor +----------- + +The multiplexor provides the message steering. In the transmit path, messages +written on a KCM socket are sent atomically on an appropriate TCP socket. +Similarly, in the receive path, messages are constructed on each TCP socket +(Psock) and complete messages are steered to a KCM socket. + +TCP sockets & Psocks +-------------------- + +TCP sockets may be bound to a KCM multiplexor. A Psock structure is allocated +for each bound TCP socket, this structure holds the state for constructing +messages on receive as well as other connection specific information for KCM. + +Connected mode semantics +------------------------ + +Each multiplexor assumes that all attached TCP connections are to the same +destination and can use the different connections for load balancing when +transmitting. The normal send and recv calls (include sendmmsg and recvmmsg) +can be used to send and receive messages from the KCM socket. + +Socket types +------------ + +KCM supports SOCK_DGRAM and SOCK_SEQPACKET socket types. + +Message delineation +------------------- + +Messages are sent over a TCP stream with some application protocol message +format that typically includes a header which frames the messages. The length +of a received message can be deduced from the application protocol header +(often just a simple length field). + +A TCP stream must be parsed to determine message boundaries. Berkeley Packet +Filter (BPF) is used for this. When attaching a TCP socket to a multiplexor a +BPF program must be specified. The program is called at the start of receiving +a new message and is given an skbuff that contains the bytes received so far. +It parses the message header and returns the length of the message. Given this +information, KCM will construct the message of the stated length and deliver it +to a KCM socket. + +TCP socket management +--------------------- + +When a TCP socket is attached to a KCM multiplexor data ready (POLLIN) and +write space available (POLLOUT) events are handled by the multiplexor. If there +is a state change (disconnection) or other error on a TCP socket, an error is +posted on the TCP socket so that a POLLERR event happens and KCM discontinues +using the socket. When the application gets the error notification for a +TCP socket, it should unattach the socket from KCM and then handle the error +condition (the typical response is to close the socket and create a new +connection if necessary). + +KCM limits the maximum receive message size to be the size of the receive +socket buffer on the attached TCP socket (the socket buffer size can be set by +SO_RCVBUF). If the length of a new message reported by the BPF program is +greater than this limit a corresponding error (EMSGSIZE) is posted on the TCP +socket. The BPF program may also enforce a maximum messages size and report an +error when it is exceeded. + +A timeout may be set for assembling messages on a receive socket. The timeout +value is taken from the receive timeout of the attached TCP socket (this is set +by SO_RCVTIMEO). If the timer expires before assembly is complete an error +(ETIMEDOUT) is posted on the socket. + +User interface +============== + +Creating a multiplexor +---------------------- + +A new multiplexor and initial KCM socket is created by a socket call: + + socket(AF_KCM, type, protocol) + + - type is either SOCK_DGRAM or SOCK_SEQPACKET + - protocol is KCMPROTO_CONNECTED + +Cloning KCM sockets +------------------- + +After the first KCM socket is created using the socket call as described +above, additional sockets for the multiplexor can be created by cloning +a KCM socket. This is accomplished by an ioctl on a KCM socket: + + /* From linux/kcm.h */ + struct kcm_clone { + int fd; + }; + + struct kcm_clone info; + + memset(&info, 0, sizeof(info)); + + err = ioctl(kcmfd, SIOCKCMCLONE, &info); + + if (!err) + newkcmfd = info.fd; + +Attach transport sockets +------------------------ + +Attaching of transport sockets to a multiplexor is performed by calling an +ioctl on a KCM socket for the multiplexor. e.g.: + + /* From linux/kcm.h */ + struct kcm_attach { + int fd; + int bpf_fd; + }; + + struct kcm_attach info; + + memset(&info, 0, sizeof(info)); + + info.fd = tcpfd; + info.bpf_fd = bpf_prog_fd; + + ioctl(kcmfd, SIOCKCMATTACH, &info); + +The kcm_attach structure contains: + fd: file descriptor for TCP socket being attached + bpf_prog_fd: file descriptor for compiled BPF program downloaded + +Unattach transport sockets +-------------------------- + +Unattaching a transport socket from a multiplexor is straightforward. An +"unattach" ioctl is done with the kcm_unattach structure as the argument: + + /* From linux/kcm.h */ + struct kcm_unattach { + int fd; + }; + + struct kcm_unattach info; + + memset(&info, 0, sizeof(info)); + + info.fd = cfd; + + ioctl(fd, SIOCKCMUNATTACH, &info); + +Disabling receive on KCM socket +------------------------------- + +A setsockopt is used to disable or enable receiving on a KCM socket. +When receive is disabled, any pending messages in the socket's +receive buffer are moved to other sockets. This feature is useful +if an application thread knows that it will be doing a lot of +work on a request and won't be able to service new messages for a +while. Example use: + + int val = 1; + + setsockopt(kcmfd, SOL_KCM, KCM_RECV_DISABLE, &val, sizeof(val)) + +BFP programs for message delineation +------------------------------------ + +BPF programs can be compiled using the BPF LLVM backend. For exmple, +the BPF program for parsing Thrift is: + + #include "bpf.h" /* for __sk_buff */ + #include "bpf_helpers.h" /* for load_word intrinsic */ + + SEC("socket_kcm") + int bpf_prog1(struct __sk_buff *skb) + { + return load_word(skb, 0) + 4; + } + + char _license[] SEC("license") = "GPL"; + +Use in applications +=================== + +KCM accelerates application layer protocols. Specifically, it allows +applications to use a message based interface for sending and receiving +messages. The kernel provides necessary assurances that messages are sent +and received atomically. This relieves much of the burden applications have +in mapping a message based protocol onto the TCP stream. KCM also make +application layer messages a unit of work in the kernel for the purposes of +steerng and scheduling, which in turn allows a simpler networking model in +multithreaded applications. + +Configurations +-------------- + +In an Nx1 configuration, KCM logically provides multiple socket handles +to the same TCP connection. This allows parallelism between in I/O +operations on the TCP socket (for instance copyin and copyout of data is +parallelized). In an application, a KCM socket can be opened for each +processing thread and inserted into the epoll (similar to how SO_REUSEPORT +is used to allow multiple listener sockets on the same port). + +In a MxN configuration, multiple connections are established to the +same destination. These are used for simple load balancing. + +Message batching +---------------- + +The primary purpose of KCM is load balancing between KCM sockets and hence +threads in a nominal use case. Perfect load balancing, that is steering +each received message to a different KCM socket or steering each sent +message to a different TCP socket, can negatively impact performance +since this doesn't allow for affinities to be established. Balancing +based on groups, or batches of messages, can be beneficial for performance. + +On transmit, there are three ways an application can batch (pipeline) +messages on a KCM socket. + 1) Send multiple messages in a single sendmmsg. + 2) Send a group of messages each with a sendmsg call, where all messages + except the last have MSG_BATCH in the flags of sendmsg call. + 3) Create "super message" composed of multiple messages and send this + with a single sendmsg. + +On receive, the KCM module attempts to queue messages received on the +same KCM socket during each TCP ready callback. The targeted KCM socket +changes at each receive ready callback on the KCM socket. The application +does not need to configure this. + +Error handling +-------------- + +An application should include a thread to monitor errors raised on +the TCP connection. Normally, this will be done by placing each +TCP socket attached to a KCM multiplexor in epoll set for POLLERR +event. If an error occurs on an attached TCP socket, KCM sets an EPIPE +on the socket thus waking up the application thread. When the application +sees the error (which may just be a disconnect) it should unattach the +socket from KCM and then close it. It is assumed that once an error is +posted on the TCP socket the data stream is unrecoverable (i.e. an error +may have occurred in in the middle of receiving a messssge). + +TCP connection monitoring +------------------------- + +In KCM there is no means to correlate a message to the TCP socket that +was used to send or receive the message (except in the case there is +only one attached TCP socket). However, the application does retain +an open file descriptor to the socket so it will be able to get statistics +from the socket which can be used in detecting issues (such as high +retransmissions on the socket). diff --git a/Documentation/networking/l2tp.txt b/Documentation/networking/l2tp.txt index c74434de2fa5..4650a00ed012 100644 --- a/Documentation/networking/l2tp.txt +++ b/Documentation/networking/l2tp.txt @@ -213,15 +213,12 @@ To create an L2TPv3 ethernet pseudowire between local host 192.168.1.1 and peer 192.168.1.2, using IP addresses 10.5.1.1 and 10.5.1.2 for the tunnel endpoints:- -# modprobe l2tp_eth -# modprobe l2tp_netlink - # ip l2tp add tunnel tunnel_id 1 peer_tunnel_id 1 udp_sport 5000 \ udp_dport 5000 encap udp local 192.168.1.1 remote 192.168.1.2 # ip l2tp add session tunnel_id 1 session_id 1 peer_session_id 1 -# ifconfig -a +# ip -s -d show dev l2tpeth0 # ip addr add 10.5.1.2/32 peer 10.5.1.1/32 dev l2tpeth0 -# ifconfig l2tpeth0 up +# ip li set dev l2tpeth0 up Choose IP addresses to be the address of a local IP interface and that of the remote system. The IP addresses of the l2tpeth0 interface can be diff --git a/Documentation/networking/mac80211-injection.txt b/Documentation/networking/mac80211-injection.txt index 3a930072b161..ec8f934c2eb2 100644 --- a/Documentation/networking/mac80211-injection.txt +++ b/Documentation/networking/mac80211-injection.txt @@ -28,6 +28,23 @@ radiotap headers and used to control injection: IEEE80211_RADIOTAP_F_TX_NOACK: frame should be sent without waiting for an ACK even if it is a unicast frame + * IEEE80211_RADIOTAP_RATE + + legacy rate for the transmission (only for devices without own rate control) + + * IEEE80211_RADIOTAP_MCS + + HT rate for the transmission (only for devices without own rate control). + Also some flags are parsed + + IEEE80211_TX_RC_SHORT_GI: use short guard interval + IEEE80211_TX_RC_40_MHZ_WIDTH: send in HT40 mode + + * IEEE80211_RADIOTAP_DATA_RETRIES + + number of retries when either IEEE80211_RADIOTAP_RATE or + IEEE80211_RADIOTAP_MCS was used + The injection code can also skip all other currently defined radiotap fields facilitating replay of captured radiotap headers directly. diff --git a/Documentation/networking/netlink_mmap.txt b/Documentation/networking/netlink_mmap.txt deleted file mode 100644 index 54f10478e8e3..000000000000 --- a/Documentation/networking/netlink_mmap.txt +++ /dev/null @@ -1,332 +0,0 @@ -This file documents how to use memory mapped I/O with netlink. - -Author: Patrick McHardy <kaber@trash.net> - -Overview --------- - -Memory mapped netlink I/O can be used to increase throughput and decrease -overhead of unicast receive and transmit operations. Some netlink subsystems -require high throughput, these are mainly the netfilter subsystems -nfnetlink_queue and nfnetlink_log, but it can also help speed up large -dump operations of f.i. the routing database. - -Memory mapped netlink I/O used two circular ring buffers for RX and TX which -are mapped into the processes address space. - -The RX ring is used by the kernel to directly construct netlink messages into -user-space memory without copying them as done with regular socket I/O, -additionally as long as the ring contains messages no recvmsg() or poll() -syscalls have to be issued by user-space to get more message. - -The TX ring is used to process messages directly from user-space memory, the -kernel processes all messages contained in the ring using a single sendmsg() -call. - -Usage overview --------------- - -In order to use memory mapped netlink I/O, user-space needs three main changes: - -- ring setup -- conversion of the RX path to get messages from the ring instead of recvmsg() -- conversion of the TX path to construct messages into the ring - -Ring setup is done using setsockopt() to provide the ring parameters to the -kernel, then a call to mmap() to map the ring into the processes address space: - -- setsockopt(fd, SOL_NETLINK, NETLINK_RX_RING, ¶ms, sizeof(params)); -- setsockopt(fd, SOL_NETLINK, NETLINK_TX_RING, ¶ms, sizeof(params)); -- ring = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0) - -Usage of either ring is optional, but even if only the RX ring is used the -mapping still needs to be writable in order to update the frame status after -processing. - -Conversion of the reception path involves calling poll() on the file -descriptor, once the socket is readable the frames from the ring are -processed in order until no more messages are available, as indicated by -a status word in the frame header. - -On kernel side, in order to make use of memory mapped I/O on receive, the -originating netlink subsystem needs to support memory mapped I/O, otherwise -it will use an allocated socket buffer as usual and the contents will be - copied to the ring on transmission, nullifying most of the performance gains. -Dumps of kernel databases automatically support memory mapped I/O. - -Conversion of the transmit path involves changing message construction to -use memory from the TX ring instead of (usually) a buffer declared on the -stack and setting up the frame header appropriately. Optionally poll() can -be used to wait for free frames in the TX ring. - -Structured and definitions for using memory mapped I/O are contained in -<linux/netlink.h>. - -RX and TX rings ----------------- - -Each ring contains a number of continuous memory blocks, containing frames of -fixed size dependent on the parameters used for ring setup. - -Ring: [ block 0 ] - [ frame 0 ] - [ frame 1 ] - [ block 1 ] - [ frame 2 ] - [ frame 3 ] - ... - [ block n ] - [ frame 2 * n ] - [ frame 2 * n + 1 ] - -The blocks are only visible to the kernel, from the point of view of user-space -the ring just contains the frames in a continuous memory zone. - -The ring parameters used for setting up the ring are defined as follows: - -struct nl_mmap_req { - unsigned int nm_block_size; - unsigned int nm_block_nr; - unsigned int nm_frame_size; - unsigned int nm_frame_nr; -}; - -Frames are grouped into blocks, where each block is a continuous region of memory -and holds nm_block_size / nm_frame_size frames. The total number of frames in -the ring is nm_frame_nr. The following invariants hold: - -- frames_per_block = nm_block_size / nm_frame_size - -- nm_frame_nr = frames_per_block * nm_block_nr - -Some parameters are constrained, specifically: - -- nm_block_size must be a multiple of the architectures memory page size. - The getpagesize() function can be used to get the page size. - -- nm_frame_size must be equal or larger to NL_MMAP_HDRLEN, IOW a frame must be - able to hold at least the frame header - -- nm_frame_size must be smaller or equal to nm_block_size - -- nm_frame_size must be a multiple of NL_MMAP_MSG_ALIGNMENT - -- nm_frame_nr must equal the actual number of frames as specified above. - -When the kernel can't allocate physically continuous memory for a ring block, -it will fall back to use physically discontinuous memory. This might affect -performance negatively, in order to avoid this the nm_frame_size parameter -should be chosen to be as small as possible for the required frame size and -the number of blocks should be increased instead. - -Ring frames ------------- - -Each frames contain a frame header, consisting of a synchronization word and some -meta-data, and the message itself. - -Frame: [ header message ] - -The frame header is defined as follows: - -struct nl_mmap_hdr { - unsigned int nm_status; - unsigned int nm_len; - __u32 nm_group; - /* credentials */ - __u32 nm_pid; - __u32 nm_uid; - __u32 nm_gid; -}; - -- nm_status is used for synchronizing processing between the kernel and user- - space and specifies ownership of the frame as well as the operation to perform - -- nm_len contains the length of the message contained in the data area - -- nm_group specified the destination multicast group of message - -- nm_pid, nm_uid and nm_gid contain the netlink pid, UID and GID of the sending - process. These values correspond to the data available using SOCK_PASSCRED in - the SCM_CREDENTIALS cmsg. - -The possible values in the status word are: - -- NL_MMAP_STATUS_UNUSED: - RX ring: frame belongs to the kernel and contains no message - for user-space. Approriate action is to invoke poll() - to wait for new messages. - - TX ring: frame belongs to user-space and can be used for - message construction. - -- NL_MMAP_STATUS_RESERVED: - RX ring only: frame is currently used by the kernel for message - construction and contains no valid message yet. - Appropriate action is to invoke poll() to wait for - new messages. - -- NL_MMAP_STATUS_VALID: - RX ring: frame contains a valid message. Approriate action is - to process the message and release the frame back to - the kernel by setting the status to - NL_MMAP_STATUS_UNUSED or queue the frame by setting the - status to NL_MMAP_STATUS_SKIP. - - TX ring: the frame contains a valid message from user-space to - be processed by the kernel. After completing processing - the kernel will release the frame back to user-space by - setting the status to NL_MMAP_STATUS_UNUSED. - -- NL_MMAP_STATUS_COPY: - RX ring only: a message is ready to be processed but could not be - stored in the ring, either because it exceeded the - frame size or because the originating subsystem does - not support memory mapped I/O. Appropriate action is - to invoke recvmsg() to receive the message and release - the frame back to the kernel by setting the status to - NL_MMAP_STATUS_UNUSED. - -- NL_MMAP_STATUS_SKIP: - RX ring only: user-space queued the message for later processing, but - processed some messages following it in the ring. The - kernel should skip this frame when looking for unused - frames. - -The data area of a frame begins at a offset of NL_MMAP_HDRLEN relative to the -frame header. - -TX limitations --------------- - -As of Jan 2015 the message is always copied from the ring frame to an -allocated buffer due to unresolved security concerns. -See commit 4682a0358639b29cf ("netlink: Always copy on mmap TX."). - -Example -------- - -Ring setup: - - unsigned int block_size = 16 * getpagesize(); - struct nl_mmap_req req = { - .nm_block_size = block_size, - .nm_block_nr = 64, - .nm_frame_size = 16384, - .nm_frame_nr = 64 * block_size / 16384, - }; - unsigned int ring_size; - void *rx_ring, *tx_ring; - - /* Configure ring parameters */ - if (setsockopt(fd, SOL_NETLINK, NETLINK_RX_RING, &req, sizeof(req)) < 0) - exit(1); - if (setsockopt(fd, SOL_NETLINK, NETLINK_TX_RING, &req, sizeof(req)) < 0) - exit(1) - - /* Calculate size of each individual ring */ - ring_size = req.nm_block_nr * req.nm_block_size; - - /* Map RX/TX rings. The TX ring is located after the RX ring */ - rx_ring = mmap(NULL, 2 * ring_size, PROT_READ | PROT_WRITE, - MAP_SHARED, fd, 0); - if ((long)rx_ring == -1L) - exit(1); - tx_ring = rx_ring + ring_size: - -Message reception: - -This example assumes some ring parameters of the ring setup are available. - - unsigned int frame_offset = 0; - struct nl_mmap_hdr *hdr; - struct nlmsghdr *nlh; - unsigned char buf[16384]; - ssize_t len; - - while (1) { - struct pollfd pfds[1]; - - pfds[0].fd = fd; - pfds[0].events = POLLIN | POLLERR; - pfds[0].revents = 0; - - if (poll(pfds, 1, -1) < 0 && errno != -EINTR) - exit(1); - - /* Check for errors. Error handling omitted */ - if (pfds[0].revents & POLLERR) - <handle error> - - /* If no new messages, poll again */ - if (!(pfds[0].revents & POLLIN)) - continue; - - /* Process all frames */ - while (1) { - /* Get next frame header */ - hdr = rx_ring + frame_offset; - - if (hdr->nm_status == NL_MMAP_STATUS_VALID) { - /* Regular memory mapped frame */ - nlh = (void *)hdr + NL_MMAP_HDRLEN; - len = hdr->nm_len; - - /* Release empty message immediately. May happen - * on error during message construction. - */ - if (len == 0) - goto release; - } else if (hdr->nm_status == NL_MMAP_STATUS_COPY) { - /* Frame queued to socket receive queue */ - len = recv(fd, buf, sizeof(buf), MSG_DONTWAIT); - if (len <= 0) - break; - nlh = buf; - } else - /* No more messages to process, continue polling */ - break; - - process_msg(nlh); -release: - /* Release frame back to the kernel */ - hdr->nm_status = NL_MMAP_STATUS_UNUSED; - - /* Advance frame offset to next frame */ - frame_offset = (frame_offset + frame_size) % ring_size; - } - } - -Message transmission: - -This example assumes some ring parameters of the ring setup are available. -A single message is constructed and transmitted, to send multiple messages -at once they would be constructed in consecutive frames before a final call -to sendto(). - - unsigned int frame_offset = 0; - struct nl_mmap_hdr *hdr; - struct nlmsghdr *nlh; - struct sockaddr_nl addr = { - .nl_family = AF_NETLINK, - }; - - hdr = tx_ring + frame_offset; - if (hdr->nm_status != NL_MMAP_STATUS_UNUSED) - /* No frame available. Use poll() to avoid. */ - exit(1); - - nlh = (void *)hdr + NL_MMAP_HDRLEN; - - /* Build message */ - build_message(nlh); - - /* Fill frame header: length and status need to be set */ - hdr->nm_len = nlh->nlmsg_len; - hdr->nm_status = NL_MMAP_STATUS_VALID; - - if (sendto(fd, NULL, 0, 0, &addr, sizeof(addr)) < 0) - exit(1); - - /* Advance frame offset to next frame */ - frame_offset = (frame_offset + frame_size) % ring_size; diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt index e839e7efc835..7ab9404a8412 100644 --- a/Documentation/networking/phy.txt +++ b/Documentation/networking/phy.txt @@ -267,13 +267,23 @@ Writing a PHY driver config_intr: Enable or disable interrupts remove: Does any driver take-down ts_info: Queries about the HW timestamping status + match_phy_device: used for Clause 45 capable PHYs to match devices + in package and ensure they are compatible hwtstamp: Set the PHY HW timestamping configuration rxtstamp: Requests a receive timestamp at the PHY level for a 'skb' txtsamp: Requests a transmit timestamp at the PHY level for a 'skb' set_wol: Enable Wake-on-LAN at the PHY level get_wol: Get the Wake-on-LAN status at the PHY level + link_change_notify: called to inform the core is about to change the + link state, can be used to work around bogus PHY between state changes read_mmd_indirect: Read PHY MMD indirect register write_mmd_indirect: Write PHY MMD indirect register + module_info: Get the size and type of an EEPROM contained in an plug-in + module + module_eeprom: Get EEPROM information of a plug-in module + get_sset_count: Get number of strings sets that get_strings will count + get_strings: Get strings from requested objects (statistics) + get_stats: Get the extended statistics from the PHY device Of these, only config_aneg and read_status are required to be assigned by the driver code. The rest are optional. Also, it is diff --git a/Documentation/networking/rds.txt b/Documentation/networking/rds.txt index e1a3d59bbe0f..9d219d856d46 100644 --- a/Documentation/networking/rds.txt +++ b/Documentation/networking/rds.txt @@ -19,9 +19,7 @@ to N*N if you use a connection-oriented socket transport like TCP. RDS is not Infiniband-specific; it was designed to support different transports. The current implementation used to support RDS over TCP as well -as IB. Work is in progress to support RDS over iWARP, and using DCE to -guarantee no dropped packets on Ethernet, it may be possible to use RDS over -UDP in the future. +as IB. The high-level semantics of RDS from the application's point of view are diff --git a/Documentation/networking/switchdev.txt b/Documentation/networking/switchdev.txt index 476df0496686..fad63136ee3e 100644 --- a/Documentation/networking/switchdev.txt +++ b/Documentation/networking/switchdev.txt @@ -115,7 +115,7 @@ Switch ID ^^^^^^^^^ The switchdev driver must implement the switchdev op switchdev_port_attr_get -for SWITCHDEV_ATTR_PORT_PARENT_ID for each port netdev, returning the same +for SWITCHDEV_ATTR_ID_PORT_PARENT_ID for each port netdev, returning the same physical ID for each port of a switch. The ID must be unique between switches on the same system. The ID does not need to be unique between switches on different systems. @@ -178,7 +178,7 @@ entries are installed, for example, using iproute2 bridge cmd: bridge fdb add ADDR dev DEV [vlan VID] [self] The driver should use the helper switchdev_port_fdb_xxx ops for ndo_fdb_xxx -ops, and handle add/delete/dump of SWITCHDEV_OBJ_PORT_FDB object using +ops, and handle add/delete/dump of SWITCHDEV_OBJ_ID_PORT_FDB object using switchdev_port_obj_xxx ops. XXX: what should be done if offloading this rule to hardware fails (for @@ -233,26 +233,27 @@ the bridge's FDB. It's possible, but not optimal, to enable learning on the device port and on the bridge port, and disable learning_sync. To support learning and learning_sync port attributes, the driver implements -switchdev op switchdev_port_attr_get/set for SWITCHDEV_ATTR_PORT_BRIDGE_FLAGS. -The driver should initialize the attributes to the hardware defaults. +switchdev op switchdev_port_attr_get/set for +SWITCHDEV_ATTR_PORT_ID_BRIDGE_FLAGS. The driver should initialize the attributes +to the hardware defaults. FDB Ageing ^^^^^^^^^^ -There are two FDB ageing models supported: 1) ageing by the device, and 2) -ageing by the kernel. Ageing by the device is preferred if many FDB entries -are supported. The driver calls call_switchdev_notifiers(SWITCHDEV_FDB_DEL, -...) to age out the FDB entry. In this model, ageing by the kernel should be -turned off. XXX: how to turn off ageing in kernel on a per-port basis or -otherwise prevent the kernel from ageing out the FDB entry? - -In the kernel ageing model, the standard bridge ageing mechanism is used to age -out stale FDB entries. To keep an FDB entry "alive", the driver should refresh -the FDB entry by calling call_switchdev_notifiers(SWITCHDEV_FDB_ADD, ...). The +The bridge will skip ageing FDB entries marked with NTF_EXT_LEARNED and it is +the responsibility of the port driver/device to age out these entries. If the +port device supports ageing, when the FDB entry expires, it will notify the +driver which in turn will notify the bridge with SWITCHDEV_FDB_DEL. If the +device does not support ageing, the driver can simulate ageing using a +garbage collection timer to monitor FBD entries. Expired entries will be +notified to the bridge using SWITCHDEV_FDB_DEL. See rocker driver for +example of driver running ageing timer. + +To keep an NTF_EXT_LEARNED entry "alive", the driver should refresh the FDB +entry by calling call_switchdev_notifiers(SWITCHDEV_FDB_ADD, ...). The notification will reset the FDB entry's last-used time to now. The driver should rate limit refresh notifications, for example, no more than once a -second. If the FDB entry expires, fdb_delete is called to remove entry from -the device. +second. (The last-used time is visible using the bridge -s fdb option). STP State Change on Port ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -260,7 +261,7 @@ STP State Change on Port Internally or with a third-party STP protocol implementation (e.g. mstpd), the bridge driver maintains the STP state for ports, and will notify the switch driver of STP state change on a port using the switchdev op -switchdev_attr_port_set for SWITCHDEV_ATTR_PORT_STP_UPDATE. +switchdev_attr_port_set for SWITCHDEV_ATTR_PORT_ID_STP_UPDATE. State is one of BR_STATE_*. The switch driver can use STP state updates to update ingress packet filter list for the port. For example, if port is @@ -277,8 +278,8 @@ Flooding L2 domain For a given L2 VLAN domain, the switch device should flood multicast/broadcast and unknown unicast packets to all ports in domain, if allowed by port's current STP state. The switch driver, knowing which ports are within which -vlan L2 domain, can program the switch device for flooding. The packet should -also be sent to the port netdev for processing by the bridge driver. The +vlan L2 domain, can program the switch device for flooding. The packet may +be sent to the port netdev for processing by the bridge driver. The bridge should not reflood the packet to the same ports the device flooded, otherwise there will be duplicate packets on the wire. @@ -297,11 +298,18 @@ packets up to the bridge driver for flooding. This is not ideal as the number of ports scale in the L2 domain as the device is much more efficient at flooding packets that software. +If supported by the device, flood control can be offloaded to it, preventing +certain netdevs from flooding unicast traffic for which there is no FDB entry. + IGMP Snooping ^^^^^^^^^^^^^ -XXX: complete this section - +In order to support IGMP snooping, the port netdevs should trap to the bridge +driver all IGMP join and leave messages. +The bridge multicast module will notify port netdevs on every multicast group +changed whether it is static configured or dynamically joined/leave. +The hardware implementation should be forwarding all registered multicast +traffic groups only to the configured ports. L3 Routing Offload ------------------ @@ -316,9 +324,9 @@ SWITCHDEV_OBJ_IPV[4|6]_FIB object using switchdev_port_obj_xxx ops. switchdev_port_obj_add is used for both adding a new FIB entry to the device, or modifying an existing entry on the device. -XXX: Currently, only SWITCHDEV_OBJ_IPV4_FIB objects are supported. +XXX: Currently, only SWITCHDEV_OBJ_ID_IPV4_FIB objects are supported. -SWITCHDEV_OBJ_IPV4_FIB object passes: +SWITCHDEV_OBJ_ID_IPV4_FIB object passes: struct switchdev_obj_ipv4_fib { /* IPV4_FIB */ u32 dst; @@ -369,3 +377,22 @@ The driver can monitor for updates to arp_tbl using the netevent notifier NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy to know when arp_tbl neighbor entries are purged from the port. + +Transaction item queue +^^^^^^^^^^^^^^^^^^^^^^ + +For switchdev ops attr_set and obj_add, there is a 2 phase transaction model +used. First phase is to "prepare" anything needed, including various checks, +memory allocation, etc. The goal is to handle the stuff that is not unlikely +to fail here. The second phase is to "commit" the actual changes. + +Switchdev provides an inftrastructure for sharing items (for example memory +allocations) between the two phases. + +The object created by a driver in "prepare" phase and it is queued up by: +switchdev_trans_item_enqueue() +During the "commit" phase, the driver gets the object by: +switchdev_trans_item_dequeue() + +If a transaction is aborted during "prepare" phase, switchdev code will handle +cleanup of the queued-up objects. diff --git a/Documentation/networking/vrf.txt b/Documentation/networking/vrf.txt index 031ef4a63485..d52aa10cfe91 100644 --- a/Documentation/networking/vrf.txt +++ b/Documentation/networking/vrf.txt @@ -90,7 +90,304 @@ or to specify the output device using cmsg and IP_PKTINFO. Limitations ----------- -VRF device currently only works for IPv4. Support for IPv6 is under development. - Index of original ingress interface is not available via cmsg. Will address soon. + +################################################################################ + +Using iproute2 for VRFs +======================= +VRF devices do *not* have to start with 'vrf-'. That is a convention used here +for emphasis of the device type, similar to use of 'br' in bridge names. + +1. Create a VRF + + To instantiate a VRF device and associate it with a table: + $ ip link add dev NAME type vrf table ID + + Remember to add the ip rules as well: + $ ip ru add oif NAME table 10 + $ ip ru add iif NAME table 10 + $ ip -6 ru add oif NAME table 10 + $ ip -6 ru add iif NAME table 10 + + Without the rules route lookups are not directed to the table. + + For example: + $ ip link add dev vrf-blue type vrf table 10 + $ ip ru add pref 200 oif vrf-blue table 10 + $ ip ru add pref 200 iif vrf-blue table 10 + $ ip -6 ru add pref 200 oif vrf-blue table 10 + $ ip -6 ru add pref 200 iif vrf-blue table 10 + + +2. List VRFs + + To list VRFs that have been created: + $ ip [-d] link show type vrf + NOTE: The -d option is needed to show the table id + + For example: + $ ip -d link show type vrf + 11: vrf-mgmt: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether 72:b3:ba:91:e2:24 brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 1 addrgenmode eui64 + 12: vrf-red: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether b6:6f:6e:f6:da:73 brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 10 addrgenmode eui64 + 13: vrf-blue: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether 36:62:e8:7d:bb:8c brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 66 addrgenmode eui64 + 14: vrf-green: <NOARP,MASTER,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + link/ether e6:28:b8:63:70:bb brd ff:ff:ff:ff:ff:ff promiscuity 0 + vrf table 81 addrgenmode eui64 + + + Or in brief output: + + $ ip -br link show type vrf + vrf-mgmt UP 72:b3:ba:91:e2:24 <NOARP,MASTER,UP,LOWER_UP> + vrf-red UP b6:6f:6e:f6:da:73 <NOARP,MASTER,UP,LOWER_UP> + vrf-blue UP 36:62:e8:7d:bb:8c <NOARP,MASTER,UP,LOWER_UP> + vrf-green UP e6:28:b8:63:70:bb <NOARP,MASTER,UP,LOWER_UP> + + +3. Assign a Network Interface to a VRF + + Network interfaces are assigned to a VRF by enslaving the netdevice to a + VRF device: + $ ip link set dev NAME master VRF-NAME + + On enslavement connected and local routes are automatically moved to the + table associated with the VRF device. + + For example: + $ ip link set dev eth0 master vrf-mgmt + + +4. Show Devices Assigned to a VRF + + To show devices that have been assigned to a specific VRF add the master + option to the ip command: + $ ip link show master VRF-NAME + + For example: + $ ip link show master vrf-red + 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vrf-red state UP mode DEFAULT group default qlen 1000 + link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff + 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vrf-red state UP mode DEFAULT group default qlen 1000 + link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff + 7: eth5: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master vrf-red state DOWN mode DEFAULT group default qlen 1000 + link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff + + + Or using the brief output: + $ ip -br link show master vrf-red + eth1 UP 02:00:00:00:02:02 <BROADCAST,MULTICAST,UP,LOWER_UP> + eth2 UP 02:00:00:00:02:03 <BROADCAST,MULTICAST,UP,LOWER_UP> + eth5 DOWN 02:00:00:00:02:06 <BROADCAST,MULTICAST> + + +5. Show Neighbor Entries for a VRF + + To list neighbor entries associated with devices enslaved to a VRF device + add the master option to the ip command: + $ ip [-6] neigh show master VRF-NAME + + For example: + $ ip neigh show master vrf-red + 10.2.1.254 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE + 10.2.2.254 dev eth2 lladdr 5e:54:01:6a:ee:80 REACHABLE + + $ ip -6 neigh show master vrf-red + 2002:1::64 dev eth1 lladdr a6:d9:c7:4f:06:23 REACHABLE + + +6. Show Addresses for a VRF + + To show addresses for interfaces associated with a VRF add the master + option to the ip command: + $ ip addr show master VRF-NAME + + For example: + $ ip addr show master vrf-red + 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vrf-red state UP group default qlen 1000 + link/ether 02:00:00:00:02:02 brd ff:ff:ff:ff:ff:ff + inet 10.2.1.2/24 brd 10.2.1.255 scope global eth1 + valid_lft forever preferred_lft forever + inet6 2002:1::2/120 scope global + valid_lft forever preferred_lft forever + inet6 fe80::ff:fe00:202/64 scope link + valid_lft forever preferred_lft forever + 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vrf-red state UP group default qlen 1000 + link/ether 02:00:00:00:02:03 brd ff:ff:ff:ff:ff:ff + inet 10.2.2.2/24 brd 10.2.2.255 scope global eth2 + valid_lft forever preferred_lft forever + inet6 2002:2::2/120 scope global + valid_lft forever preferred_lft forever + inet6 fe80::ff:fe00:203/64 scope link + valid_lft forever preferred_lft forever + 7: eth5: <BROADCAST,MULTICAST> mtu 1500 qdisc noop master vrf-red state DOWN group default qlen 1000 + link/ether 02:00:00:00:02:06 brd ff:ff:ff:ff:ff:ff + + Or in brief format: + $ ip -br addr show master vrf-red + eth1 UP 10.2.1.2/24 2002:1::2/120 fe80::ff:fe00:202/64 + eth2 UP 10.2.2.2/24 2002:2::2/120 fe80::ff:fe00:203/64 + eth5 DOWN + + +7. Show Routes for a VRF + + To show routes for a VRF use the ip command to display the table associated + with the VRF device: + $ ip [-6] route show table ID + + For example: + $ ip route show table vrf-red + prohibit default + broadcast 10.2.1.0 dev eth1 proto kernel scope link src 10.2.1.2 + 10.2.1.0/24 dev eth1 proto kernel scope link src 10.2.1.2 + local 10.2.1.2 dev eth1 proto kernel scope host src 10.2.1.2 + broadcast 10.2.1.255 dev eth1 proto kernel scope link src 10.2.1.2 + broadcast 10.2.2.0 dev eth2 proto kernel scope link src 10.2.2.2 + 10.2.2.0/24 dev eth2 proto kernel scope link src 10.2.2.2 + local 10.2.2.2 dev eth2 proto kernel scope host src 10.2.2.2 + broadcast 10.2.2.255 dev eth2 proto kernel scope link src 10.2.2.2 + + $ ip -6 route show table vrf-red + local 2002:1:: dev lo proto none metric 0 pref medium + local 2002:1::2 dev lo proto none metric 0 pref medium + 2002:1::/120 dev eth1 proto kernel metric 256 pref medium + local 2002:2:: dev lo proto none metric 0 pref medium + local 2002:2::2 dev lo proto none metric 0 pref medium + 2002:2::/120 dev eth2 proto kernel metric 256 pref medium + local fe80:: dev lo proto none metric 0 pref medium + local fe80:: dev lo proto none metric 0 pref medium + local fe80::ff:fe00:202 dev lo proto none metric 0 pref medium + local fe80::ff:fe00:203 dev lo proto none metric 0 pref medium + fe80::/64 dev eth1 proto kernel metric 256 pref medium + fe80::/64 dev eth2 proto kernel metric 256 pref medium + ff00::/8 dev vrf-red metric 256 pref medium + ff00::/8 dev eth1 metric 256 pref medium + ff00::/8 dev eth2 metric 256 pref medium + + +8. Route Lookup for a VRF + + A test route lookup can be done for a VRF by adding the oif option to ip: + $ ip [-6] route get oif VRF-NAME ADDRESS + + For example: + $ ip route get 10.2.1.40 oif vrf-red + 10.2.1.40 dev eth1 table vrf-red src 10.2.1.2 + cache + + $ ip -6 route get 2002:1::32 oif vrf-red + 2002:1::32 from :: dev eth1 table vrf-red proto kernel src 2002:1::2 metric 256 pref medium + + +9. Removing Network Interface from a VRF + + Network interfaces are removed from a VRF by breaking the enslavement to + the VRF device: + $ ip link set dev NAME nomaster + + Connected routes are moved back to the default table and local entries are + moved to the local table. + + For example: + $ ip link set dev eth0 nomaster + +-------------------------------------------------------------------------------- + +Commands used in this example: + +cat >> /etc/iproute2/rt_tables <<EOF +1 vrf-mgmt +10 vrf-red +66 vrf-blue +81 vrf-green +EOF + +function vrf_create +{ + VRF=$1 + TBID=$2 + # create VRF device + ip link add vrf-${VRF} type vrf table ${TBID} + + # add rules that direct lookups to vrf table + ip ru add pref 200 oif vrf-${VRF} table ${TBID} + ip ru add pref 200 iif vrf-${VRF} table ${TBID} + ip -6 ru add pref 200 oif vrf-${VRF} table ${TBID} + ip -6 ru add pref 200 iif vrf-${VRF} table ${TBID} + + if [ "${VRF}" != "mgmt" ]; then + ip route add table ${TBID} prohibit default + fi + ip link set dev vrf-${VRF} up + ip link set dev vrf-${VRF} state up +} + +vrf_create mgmt 1 +ip link set dev eth0 master vrf-mgmt + +vrf_create red 10 +ip link set dev eth1 master vrf-red +ip link set dev eth2 master vrf-red +ip link set dev eth5 master vrf-red + +vrf_create blue 66 +ip link set dev eth3 master vrf-blue + +vrf_create green 81 +ip link set dev eth4 master vrf-green + + +Interface addresses from /etc/network/interfaces: +auto eth0 +iface eth0 inet static + address 10.0.0.2 + netmask 255.255.255.0 + gateway 10.0.0.254 + +iface eth0 inet6 static + address 2000:1::2 + netmask 120 + +auto eth1 +iface eth1 inet static + address 10.2.1.2 + netmask 255.255.255.0 + +iface eth1 inet6 static + address 2002:1::2 + netmask 120 + +auto eth2 +iface eth2 inet static + address 10.2.2.2 + netmask 255.255.255.0 + +iface eth2 inet6 static + address 2002:2::2 + netmask 120 + +auto eth3 +iface eth3 inet static + address 10.2.3.2 + netmask 255.255.255.0 + +iface eth3 inet6 static + address 2002:3::2 + netmask 120 + +auto eth4 +iface eth4 inet static + address 10.2.4.2 + netmask 255.255.255.0 + +iface eth4 inet6 static + address 2002:4::2 + netmask 120 diff --git a/Documentation/nvdimm/nvdimm.txt b/Documentation/nvdimm/nvdimm.txt index 197a0b6b0582..e894de69915a 100644 --- a/Documentation/nvdimm/nvdimm.txt +++ b/Documentation/nvdimm/nvdimm.txt @@ -62,6 +62,12 @@ DAX: File system extensions to bypass the page cache and block layer to mmap persistent memory, from a PMEM block device, directly into a process address space. +DSM: Device Specific Method: ACPI method to to control specific +device - in this case the firmware. + +DCR: NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5. +It defines a vendor-id, device-id, and interface format for a given DIMM. + BTT: Block Translation Table: Persistent memory is byte addressable. Existing software may have an expectation that the power-fail-atomicity of writes is at least one sector, 512 bytes. The BTT is an indirection @@ -133,16 +139,16 @@ device driver: registered, can be immediately attached to nd_pmem. 2. BLK (nd_blk.ko): This driver performs I/O using a set of platform - defined apertures. A set of apertures will all access just one DIMM. - Multiple windows allow multiple concurrent accesses, much like + defined apertures. A set of apertures will access just one DIMM. + Multiple windows (apertures) allow multiple concurrent accesses, much like tagged-command-queuing, and would likely be used by different threads or different CPUs. The NFIT specification defines a standard format for a BLK-aperture, but the spec also allows for vendor specific layouts, and non-NFIT BLK - implementations may other designs for BLK I/O. For this reason "nd_blk" - calls back into platform-specific code to perform the I/O. One such - implementation is defined in the "Driver Writer's Guide" and "DSM + implementations may have other designs for BLK I/O. For this reason + "nd_blk" calls back into platform-specific code to perform the I/O. + One such implementation is defined in the "Driver Writer's Guide" and "DSM Interface Example". @@ -152,7 +158,7 @@ Why BLK? While PMEM provides direct byte-addressable CPU-load/store access to NVDIMM storage, it does not provide the best system RAS (recovery, availability, and serviceability) model. An access to a corrupted -system-physical-address address causes a cpu exception while an access +system-physical-address address causes a CPU exception while an access to a corrupted address through an BLK-aperture causes that block window to raise an error status in a register. The latter is more aligned with the standard error model that host-bus-adapter attached disks present. @@ -162,7 +168,7 @@ data could be interleaved in an opaque hardware specific manner across several DIMMs. PMEM vs BLK -BLK-apertures solve this RAS problem, but their presence is also the +BLK-apertures solve these RAS problems, but their presence is also the major contributing factor to the complexity of the ND subsystem. They complicate the implementation because PMEM and BLK alias in DPA space. Any given DIMM's DPA-range may contribute to one or more @@ -220,8 +226,8 @@ socket. Each unique interface (BLK or PMEM) to DPA space is identified by a region device with a dynamically assigned id (REGION0 - REGION5). 1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A - single PMEM namespace is created in the REGION0-SPA-range that spans - DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that + single PMEM namespace is created in the REGION0-SPA-range that spans most + of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that interleaved system-physical-address range is reclaimed as BLK-aperture accessed space starting at DPA-offset (a) into each DIMM. In that reclaimed space we create two BLK-aperture "namespaces" from REGION2 and @@ -230,13 +236,13 @@ by a region device with a dynamically assigned id (REGION0 - REGION5). 2. In the last portion of DIMM0 and DIMM1 we have an interleaved system-physical-address range, REGION1, that spans those two DIMMs as - well as DIMM2 and DIMM3. Some of REGION1 allocated to a PMEM namespace - named "pm1.0" the rest is reclaimed in 4 BLK-aperture namespaces (for + well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace + named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and "blk5.0". 3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1 - interleaved system-physical-address range (i.e. the DPA address below + interleaved system-physical-address range (i.e. the DPA address past offset (b) are also included in the "blk4.0" and "blk5.0" namespaces. Note, that this example shows that BLK-aperture namespaces don't need to be contiguous in DPA-space. @@ -252,15 +258,15 @@ LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API What follows is a description of the LIBNVDIMM sysfs layout and a corresponding object hierarchy diagram as viewed through the LIBNDCTL -api. The example sysfs paths and diagrams are relative to the Example +API. The example sysfs paths and diagrams are relative to the Example NVDIMM Platform which is also the LIBNVDIMM bus used in the LIBNDCTL unit test. LIBNDCTL: Context -Every api call in the LIBNDCTL library requires a context that holds the +Every API call in the LIBNDCTL library requires a context that holds the logging parameters and other library instance state. The library is based on the libabc template: -https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git/ +https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git LIBNDCTL: instantiate a new library context example @@ -409,7 +415,7 @@ Bit 31:28 Reserved LIBNVDIMM/LIBNDCTL: Region ---------------------- -A generic REGION device is registered for each PMEM range orBLK-aperture +A generic REGION device is registered for each PMEM range or BLK-aperture set. Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture sets on the "nfit_test.0" bus. The primary role of regions are to be a container of "mappings". A mapping is a tuple of <DIMM, @@ -509,7 +515,7 @@ At first glance it seems since NFIT defines just PMEM and BLK interface types that we should simply name REGION devices with something derived from those type names. However, the ND subsystem explicitly keeps the REGION name generic and expects userspace to always consider the -region-attributes for 4 reasons: +region-attributes for four reasons: 1. There are already more than two REGION and "namespace" types. For PMEM there are two subtypes. As mentioned previously we have PMEM where @@ -698,8 +704,8 @@ static int configure_namespace(struct ndctl_region *region, Why the Term "namespace"? - 1. Why not "volume" for instance? "volume" ran the risk of confusing ND - as a volume manager like device-mapper. + 1. Why not "volume" for instance? "volume" ran the risk of confusing + ND (libnvdimm subsystem) to a volume manager like device-mapper. 2. The term originated to describe the sub-devices that can be created within a NVME controller (see the nvme specification: @@ -774,13 +780,14 @@ block" needs to be destroyed. Note, that to destroy a BTT the media needs to be written in raw mode. By default, the kernel will autodetect the presence of a BTT and disable raw mode. This autodetect behavior can be suppressed by enabling raw mode for the namespace via the -ndctl_namespace_set_raw_mode() api. +ndctl_namespace_set_raw_mode() API. Summary LIBNDCTL Diagram ------------------------ -For the given example above, here is the view of the objects as seen by the LIBNDCTL api: +For the given example above, here is the view of the objects as seen by the +LIBNDCTL API: +---+ |CTX| +---------+ +--------------+ +---------------+ +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" | diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index b0e911e0e8f5..44558882aa60 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -999,7 +999,7 @@ from its probe routine to make runtime PM work for the device. It is important to remember that the driver's runtime_suspend() callback may be executed right after the usage counter has been decremented, because -user space may already have cuased the pm_runtime_allow() helper function +user space may already have caused the pm_runtime_allow() helper function unblocking the runtime PM of the device to run via sysfs, so the driver must be prepared to cope with that. diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 0784bc3a2ab5..7328cf85236c 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -371,6 +371,12 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: - increment the device's usage counter, run pm_runtime_resume(dev) and return its result + int pm_runtime_get_if_in_use(struct device *dev); + - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the + runtime PM status is RPM_ACTIVE and the runtime PM usage counter is + nonzero, increment the counter and return 1; otherwise return 0 without + changing the counter + void pm_runtime_put_noidle(struct device *dev); - decrement the device's usage counter diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.txt index 205c1b81625c..d5506ba0fef7 100644 --- a/Documentation/powerpc/cxl.txt +++ b/Documentation/powerpc/cxl.txt @@ -116,6 +116,8 @@ Work Element Descriptor (WED) User API ======== +1. AFU character devices + For AFUs operating in AFU directed mode, two character device files will be created. /dev/cxl/afu0.0m will correspond to a master context and /dev/cxl/afu0.0s will correspond to a slave @@ -362,6 +364,59 @@ read reserved fields: For future extensions and padding + +2. Card character device (powerVM guest only) + + In a powerVM guest, an extra character device is created for the + card. The device is only used to write (flash) a new image on the + FPGA accelerator. Once the image is written and verified, the + device tree is updated and the card is reset to reload the updated + image. + +open +---- + + Opens the device and allocates a file descriptor to be used with + the rest of the API. The device can only be opened once. + +ioctl +----- + +CXL_IOCTL_DOWNLOAD_IMAGE: +CXL_IOCTL_VALIDATE_IMAGE: + Starts and controls flashing a new FPGA image. Partial + reconfiguration is not supported (yet), so the image must contain + a copy of the PSL and AFU(s). Since an image can be quite large, + the caller may have to iterate, splitting the image in smaller + chunks. + + Takes a pointer to a struct cxl_adapter_image: + struct cxl_adapter_image { + __u64 flags; + __u64 data; + __u64 len_data; + __u64 len_image; + __u64 reserved1; + __u64 reserved2; + __u64 reserved3; + __u64 reserved4; + }; + + flags: + These flags indicate which optional fields are present in + this struct. Currently all fields are mandatory. + + data: + Pointer to a buffer with part of the image to write to the + card. + + len_data: + Size of the buffer pointed to by data. + + len_image: + Full size of the image. + + Sysfs Class =========== diff --git a/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c b/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c index 81fdd425ab3e..f7499d1c0415 100644 --- a/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c +++ b/Documentation/prctl/disable-tsc-ctxt-sw-stress-test.c @@ -74,7 +74,7 @@ static void rdtsctask(void) } -int main(int argc, char **argv) +int main(void) { int n_tasks = 100, i; diff --git a/Documentation/prctl/disable-tsc-on-off-stress-test.c b/Documentation/prctl/disable-tsc-on-off-stress-test.c index 4d83a27627f9..a06f027e9d16 100644 --- a/Documentation/prctl/disable-tsc-on-off-stress-test.c +++ b/Documentation/prctl/disable-tsc-on-off-stress-test.c @@ -78,7 +78,7 @@ static void task(void) } -int main(int argc, char **argv) +int main(void) { int n_tasks = 100, i; diff --git a/Documentation/prctl/disable-tsc-test.c b/Documentation/prctl/disable-tsc-test.c index 2541e65cb64b..8d494f7bebdb 100644 --- a/Documentation/prctl/disable-tsc-test.c +++ b/Documentation/prctl/disable-tsc-test.c @@ -57,7 +57,7 @@ static void sigsegv_cb(int sig) printf("rdtsc() == "); } -int main(int argc, char **argv) +int main(void) { int tsc_val = 0; diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt index 2216eb187c21..5962949944fd 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.txt @@ -23,6 +23,10 @@ Example: 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: @@ -119,6 +123,7 @@ Raw buffer as an escaped string: 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 @@ -234,6 +239,7 @@ UUID/GUID addresses: Passed by reference. dentry names: + %pd{,2,3,4} %pD{,2,3,4} @@ -244,6 +250,12 @@ dentry names: Passed by reference. +block_device names: + + %pg sda, sda1 or loop0p1 + + For printing name of block_device pointers. + struct va_format: %pV @@ -256,6 +268,8 @@ struct va_format: 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. @@ -284,6 +298,36 @@ bitmap and its derivatives such as cpumask and nodemask: 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 TP_printk() part + of a tracepoint. Instead, use the show_*_flags() functions from + <trace/events/mmflags.h>. + + 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. diff --git a/Documentation/ptp/testptp.c b/Documentation/ptp/testptp.c index 6c6247aaa7b9..5d2eae16f7ee 100644 --- a/Documentation/ptp/testptp.c +++ b/Documentation/ptp/testptp.c @@ -160,7 +160,8 @@ int main(int argc, char *argv[]) char *progname; - int i, c, cnt, fd; + unsigned int i; + int c, cnt, fd; char *device = DEVICE; clockid_t clkid; @@ -277,13 +278,15 @@ int main(int argc, char *argv[]) " %d external time stamp channels\n" " %d programmable periodic signals\n" " %d pulse per second\n" - " %d programmable pins\n", + " %d programmable pins\n" + " %d cross timestamping\n", caps.max_adj, caps.n_alarm, caps.n_ext_ts, caps.n_per_out, caps.pps, - caps.n_pins); + caps.n_pins, + caps.cross_timestamping); } } diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt index 39873ef41bf9..b9d9cc57be18 100644 --- a/Documentation/rbtree.txt +++ b/Documentation/rbtree.txt @@ -203,7 +203,7 @@ functions with the user provided augmentation callback when inserting and erasing nodes. C files implementing augmented rbtree manipulation must include -<linux/rbtree_augmented.h> instead of <linus/rbtree.h>. Note that +<linux/rbtree_augmented.h> instead of <linux/rbtree.h>. Note that linux/rbtree_augmented.h exposes some rbtree implementations details you are not expected to rely on; please stick to the documented APIs there and do not include <linux/rbtree_augmented.h> from header files diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index 2ee6ef9a6554..1f0c27049340 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt @@ -83,6 +83,8 @@ rfkill drivers that control devices that can be hard-blocked unless they also assign the poll_hw_block() callback (then the rfkill core will poll the device). Don't do this unless you cannot get the event in any other way. +RFKill provides per-switch LED triggers, which can be used to drive LEDs +according to the switch state (LED_FULL when blocked, LED_OFF otherwise). 5. Userspace support diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index 8446f1ea1410..ddc366026e00 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -157,6 +157,12 @@ wakealarm: The time at which the clock will generate a system wakeup 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. IOCTL INTERFACE --------------- diff --git a/Documentation/s390/zfcpdump.txt b/Documentation/s390/zfcpdump.txt index dc929be96016..b064aa59714d 100644 --- a/Documentation/s390/zfcpdump.txt +++ b/Documentation/s390/zfcpdump.txt @@ -15,19 +15,15 @@ the s390-tools package) to make the device bootable. The operator of a Linux system can then trigger a SCSI dump by booting the SCSI disk, where zfcpdump resides on. -The kernel part of zfcpdump is implemented as a debugfs file under "zcore/mem", -which exports memory and registers of the crashed Linux in an s390 -standalone dump format. It can be used in the same way as e.g. /dev/mem. The -dump format defines a 4K header followed by plain uncompressed memory. The -register sets are stored in the prefix pages of the respective CPUs. To build a -dump enabled kernel with the zcore driver, the kernel config option -CONFIG_CRASH_DUMP has to be set. When reading from "zcore/mem", the part of -memory, which has been saved by hardware is read by the driver via the SCLP -hardware interface. The second part is just copied from the non overwritten real -memory. - -Since kernel version 3.12 also the /proc/vmcore file can also be used to access -the dump. +The user space dump tool accesses the memory of the crashed system by means +of the /proc/vmcore interface. This interface exports the crashed system's +memory and registers in ELF core dump format. To access the memory which has +been saved by the hardware SCLP requests will be created at the time the data +is needed by /proc/vmcore. The tail part of the crashed systems memory which +has not been stashed by hardware can just be copied from real memory. + +To build a dump enabled kernel the kernel config option CONFIG_CRASH_DUMP +has to be set. To get a valid zfcpdump kernel configuration use "make zfcpdump_defconfig". diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt index f29fa550665a..ec0acf6acccd 100644 --- a/Documentation/scsi/st.txt +++ b/Documentation/scsi/st.txt @@ -2,7 +2,7 @@ This file contains brief information about the SCSI tape driver. The driver is currently maintained by Kai Mäkisara (email Kai.Makisara@kolumbus.fi) -Last modified: Sun Aug 29 18:25:47 2010 by kai.makisara +Last modified: Tue Feb 9 21:54:16 2016 by kai.makisara BASICS @@ -408,10 +408,15 @@ MTSETPART Moves the tape to the partition given by the argument at the specified by MTSEEK. MTSETPART is inactive unless MT_ST_CAN_PARTITIONS set. MTMKPART Formats the tape with one partition (argument zero) or two - partitions (the argument gives in megabytes the size of - partition 1 that is physically the first partition of the - tape). The drive has to support partitions with size specified - by the initiator. Inactive unless MT_ST_CAN_PARTITIONS set. + partitions (argument non-zero). If the argument is positive, + it specifies the size of partition 1 in megabytes. For DDS + drives and several early drives this is the physically first + partition of the tape. If the argument is negative, its absolute + value specifies the size of partition 0 in megabytes. This is + the physically first partition of many later drives, like the + LTO drives from LTO-5 upwards. The drive has to support partitions + with size specified by the initiator. Inactive unless + MT_ST_CAN_PARTITIONS set. MTSETDRVBUFFER Is used for several purposes. The command is obtained from count with mask MT_SET_OPTIONS, the low order bits are used as argument. @@ -569,7 +574,9 @@ Debugging code is now compiled in by default but debugging is turned off with the kernel module parameter debug_flag defaulting to 0. Debugging can still be switched on and off with an ioctl. To enable debug at module load time add debug_flag=1 to the module load options, the -debugging output is not voluminous. +debugging output is not voluminous. Debugging can also be enabled +and disabled by writing a '0' (disable) or '1' (enable) to the sysfs +file /sys/bus/scsi/drivers/st/debug_flag. If the tape seems to hang, I would be very interested to hear where the driver is waiting. With the command 'ps -l' you can see the state diff --git a/Documentation/security/Smack.txt b/Documentation/security/Smack.txt index 5e6d07fbed07..945cc633d883 100644 --- a/Documentation/security/Smack.txt +++ b/Documentation/security/Smack.txt @@ -255,6 +255,16 @@ unconfined the access permitted if it wouldn't be otherwise. Note that this is dangerous and can ruin the proper labeling of your system. It should never be used in production. +relabel-self + This interface contains a list of labels to which the process can + transition to, by writing to /proc/self/attr/current. + Normally a process can change its own label to any legal value, but only + if it has CAP_MAC_ADMIN. This interface allows a process without + CAP_MAC_ADMIN to relabel itself to one of labels from predefined list. + A process without CAP_MAC_ADMIN can change its label only once. When it + does, this list will be cleared. + The values are set by writing the desired labels, separated + by spaces, to the file or cleared by writing "-" to the file. If you are using the smackload utility you can add access rules in /etc/smack/accesses. They take the form: diff --git a/Documentation/security/keys-trusted-encrypted.txt b/Documentation/security/keys-trusted-encrypted.txt index e105ae97a4f5..324ddf5223b3 100644 --- a/Documentation/security/keys-trusted-encrypted.txt +++ b/Documentation/security/keys-trusted-encrypted.txt @@ -27,17 +27,26 @@ Usage: keyctl print keyid options: - keyhandle= ascii hex value of sealing key default 0x40000000 (SRK) - keyauth= ascii hex auth for sealing key default 0x00...i - (40 ascii zeros) - blobauth= ascii hex auth for sealed data default 0x00... - (40 ascii zeros) - blobauth= ascii hex auth for sealed data default 0x00... - (40 ascii zeros) - pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) - pcrlock= pcr number to be extended to "lock" blob - migratable= 0|1 indicating permission to reseal to new PCR values, - default 1 (resealing allowed) + keyhandle= ascii hex value of sealing key default 0x40000000 (SRK) + keyauth= ascii hex auth for sealing key default 0x00...i + (40 ascii zeros) + blobauth= ascii hex auth for sealed data default 0x00... + (40 ascii zeros) + blobauth= ascii hex auth for sealed data default 0x00... + (40 ascii zeros) + pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default) + pcrlock= pcr number to be extended to "lock" blob + migratable= 0|1 indicating permission to reseal to new PCR values, + default 1 (resealing allowed) + hash= hash algorithm name as a string. For TPM 1.x the only + allowed value is sha1. For TPM 2.x the allowed values + are sha1, sha256, sha384, sha512 and sm3-256. + policydigest= digest for the authorization policy. must be calculated + with the same hash algorithm as specified by the 'hash=' + option. + policyhandle= handle to an authorization policy session that defines the + same policy and with the same hash algorithm as was used to + seal the key. "keyctl print" returns an ascii hex copy of the sealed key, which is in standard TPM_STORED_DATA format. The key length for new keys are always in bytes. diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt index c9e7f4f223a5..8c183873b2b7 100644 --- a/Documentation/security/keys.txt +++ b/Documentation/security/keys.txt @@ -1049,12 +1049,12 @@ search a specific keyring, so using keyrings in this way is of limited utility. NOTES ON ACCESSING PAYLOAD CONTENTS =================================== -The simplest payload is just a number in key->payload.value. In this case, -there's no need to indulge in RCU or locking when accessing the payload. +The simplest payload is just data stored in key->payload directly. In this +case, there's no need to indulge in RCU or locking when accessing the payload. -More complex payload contents must be allocated and a pointer to them set in -key->payload.data. One of the following ways must be selected to access the -data: +More complex payload contents must be allocated and pointers to them set in the +key->payload.data[] array. One of the following ways must be selected to +access the data: (1) Unmodifiable key type. @@ -1092,6 +1092,13 @@ data: the payload. key->datalen cannot be relied upon to be consistent with the payload just dereferenced if the key's semaphore is not held. + Note that key->payload.data[0] has a shadow that is marked for __rcu + usage. This is called key->payload.rcu_data0. The following accessors + wrap the RCU calls to this element: + + rcu_assign_keypointer(struct key *key, void *data); + void *rcu_dereference_key(struct key *key); + =================== DEFINING A KEY TYPE @@ -1143,8 +1150,7 @@ The structure has a number of fields, some of which are mandatory: struct key_preparsed_payload { char *description; - void *type_data[2]; - void *payload; + union key_payload payload; const void *data; size_t datalen; size_t quotalen; @@ -1160,10 +1166,9 @@ The structure has a number of fields, some of which are mandatory: attached as a string to the description field. This will be used for the key description if the caller of add_key() passes NULL or "". - The method can attach anything it likes to type_data[] and payload. These - are merely passed along to the instantiate() or update() operations. If - set, the expiry time will be applied to the key if it is instantiated from - this data. + The method can attach anything it likes to payload. This is merely passed + along to the instantiate() or update() operations. If set, the expiry + time will be applied to the key if it is instantiated from this data. The method should return 0 if successful or a negative error code otherwise. @@ -1172,11 +1177,10 @@ The structure has a number of fields, some of which are mandatory: (*) void (*free_preparse)(struct key_preparsed_payload *prep); This method is only required if the preparse() method is provided, - otherwise it is unused. It cleans up anything attached to the - description, type_data and payload fields of the key_preparsed_payload - struct as filled in by the preparse() method. It will always be called - after preparse() returns successfully, even if instantiate() or update() - succeed. + otherwise it is unused. It cleans up anything attached to the description + and payload fields of the key_preparsed_payload struct as filled in by the + preparse() method. It will always be called after preparse() returns + successfully, even if instantiate() or update() succeed. (*) int (*instantiate)(struct key *key, struct key_preparsed_payload *prep); @@ -1197,6 +1201,11 @@ The structure has a number of fields, some of which are mandatory: It is safe to sleep in this method. + generic_key_instantiate() is provided to simply copy the data from + prep->payload.data[] to key->payload.data[], with RCU-safe assignment on + the first element. It will then clear prep->payload.data[] so that the + free_preparse method doesn't release the data. + (*) int (*update)(struct key *key, const void *data, size_t datalen); diff --git a/Documentation/serial/driver b/Documentation/serial/driver index c415b0ef4493..379468e12680 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -439,11 +439,13 @@ Modem control lines via GPIO Some helpers are provided in order to set/get modem control lines via GPIO. -mctrl_gpio_init(dev, idx): +mctrl_gpio_init(port, idx): This will get the {cts,rts,...}-gpios from device tree if they are present and request them, set direction etc, and return an allocated structure. devm_* functions are used, so there's no need to call mctrl_gpio_free(). + As this sets up the irq handling make sure to not handle changes to the + gpio input lines in your driver, too. mctrl_gpio_free(dev, gpios): This will free the requested gpios in mctrl_gpio_init(). @@ -458,3 +460,9 @@ mctrl_gpio_set(gpios, mctrl): mctrl_gpio_get(gpios, mctrl): This will update mctrl with the gpios values. + +mctrl_gpio_enable_ms(gpios): + Enables irqs and handling of changes to the ms lines. + +mctrl_gpio_disable_ms(gpios): + Disables irqs and handling of changes to the ms lines. diff --git a/Documentation/serial/tty.txt b/Documentation/serial/tty.txt index 973c8ad3f959..798cba82c762 100644 --- a/Documentation/serial/tty.txt +++ b/Documentation/serial/tty.txt @@ -39,8 +39,13 @@ TTY side interfaces: open() - Called when the line discipline is attached to the terminal. No other call into the line discipline for this tty will occur until it - completes successfully. Returning an error will - prevent the ldisc from being attached. Can sleep. + completes successfully. Should initialize any + state needed by the ldisc, and set receive_room + in the tty_struct to the maximum amount of data + the line discipline is willing to accept from the + driver with a single call to receive_buf(). + Returning an error will prevent the ldisc from + being attached. Can sleep. close() - This is called on a terminal when the line discipline is being unplugged. At the point of @@ -52,44 +57,54 @@ hangup() - Called when the tty line is hung up. No further calls into the ldisc code will occur. The return value is ignored. Can sleep. -write() - A process is writing data through the line - discipline. Multiple write calls are serialized - by the tty layer for the ldisc. May sleep. +read() - (optional) A process requests reading data from + the line. Multiple read calls may occur in parallel + and the ldisc must deal with serialization issues. + If not defined, the process will receive an EIO + error. May sleep. + +write() - (optional) A process requests writing data to the + line. Multiple write calls are serialized by the + tty layer for the ldisc. If not defined, the + process will receive an EIO error. May sleep. flush_buffer() - (optional) May be called at any point between open and close, and instructs the line discipline to empty its input buffer. -chars_in_buffer() - (optional) Report the number of bytes in the input - buffer. - set_termios() - (optional) Called on termios structure changes. The caller passes the old termios data and the current data is in the tty. Called under the termios semaphore so allowed to sleep. Serialized against itself only. -read() - Move data from the line discipline to the user. - Multiple read calls may occur in parallel and the - ldisc must deal with serialization issues. May - sleep. - -poll() - Check the status for the poll/select calls. Multiple - poll calls may occur in parallel. May sleep. +poll() - (optional) Check the status for the poll/select + calls. Multiple poll calls may occur in parallel. + May sleep. -ioctl() - Called when an ioctl is handed to the tty layer - that might be for the ldisc. Multiple ioctl calls - may occur in parallel. May sleep. +ioctl() - (optional) Called when an ioctl is handed to the + tty layer that might be for the ldisc. Multiple + ioctl calls may occur in parallel. May sleep. -compat_ioctl() - Called when a 32 bit ioctl is handed to the tty layer - that might be for the ldisc. Multiple ioctl calls - may occur in parallel. May sleep. +compat_ioctl() - (optional) Called when a 32 bit ioctl is handed + to the tty layer that might be for the ldisc. + Multiple ioctl calls may occur in parallel. + May sleep. Driver Side Interfaces: -receive_buf() - Hand buffers of bytes from the driver to the ldisc - for processing. Semantics currently rather - mysterious 8( +receive_buf() - (optional) Called by the low-level driver to hand + a buffer of received bytes to the ldisc for + processing. The number of bytes is guaranteed not + to exceed the current value of tty->receive_room. + All bytes must be processed. + +receive_buf2() - (optional) Called by the low-level driver to hand + a buffer of received bytes to the ldisc for + processing. Returns the number of bytes processed. + + If both receive_buf() and receive_buf2() are + defined, receive_buf2() should be preferred. write_wakeup() - May be called at any point between open and close. The TTY_DO_WRITE_WAKEUP flag indicates if a call diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 48148d6d9307..fc53ccd9a629 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -1910,6 +1910,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. - Default: 0x0000 ignore_ctl_error - Ignore any USB-controller regarding mixer interface (default: no) + autoclock - Enable auto-clock selection for UAC2 devices + (default: yes) + quirk_alias - Quirk alias list, pass strings like + "0123abcd:5678beef", which applies the existing + quirk for the device 5678:beef to a new device + 0123:abcd. This module supports multiple devices, autoprobe and hotplugging. @@ -1919,6 +1925,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. NB: ignore_ctl_error=1 may help when you get an error at accessing the mixer element such as URB error -22. This happens on some buggy USB device or the controller. + NB: quirk_alias option is provided only for testing / development. + If you want to have a proper support, contact to upstream for + adding the matching quirk in the driver code statically. Module snd-usb-caiaq -------------------- diff --git a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt b/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt new file mode 100644 index 000000000000..82744ac3513d --- /dev/null +++ b/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt @@ -0,0 +1,74 @@ +To support DP MST audio, HD Audio hdmi codec driver introduces virtual pin +and dynamic pcm assignment. + +Virtual pin is an extension of per_pin. The most difference of DP MST +from legacy is that DP MST introduces device entry. Each pin can contain +several device entries. Each device entry behaves as a pin. + +As each pin may contain several device entries and each codec may contain +several pins, if we use one pcm per per_pin, there will be many PCMs. +The new solution is to create a few PCMs and to dynamically bind pcm to +per_pin. Driver uses spec->dyn_pcm_assign flag to indicate whether to use +the new solution. + +PCM +=== +To be added + + +Jack +==== + +Presume: + - MST must be dyn_pcm_assign, and it is acomp (for Intel scenario); + - NON-MST may or may not be dyn_pcm_assign, it can be acomp or !acomp; + +So there are the following scenarios: + a. MST (&& dyn_pcm_assign && acomp) + b. NON-MST && dyn_pcm_assign && acomp + c. NON-MST && !dyn_pcm_assign && !acomp + +Below discussion will ignore MST and NON-MST difference as it doesn't +impact on jack handling too much. + +Driver uses struct hdmi_pcm pcm[] array in hdmi_spec and snd_jack is +a member of hdmi_pcm. Each pin has one struct hdmi_pcm * pcm pointer. + +For !dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] statically. + +For dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] +when monitor is hotplugged. + + +Build Jack +---------- + +- dyn_pcm_assign +Will not use hda_jack but use snd_jack in spec->pcm_rec[pcm_idx].jack directly. + +- !dyn_pcm_assign +Use hda_jack and assign spec->pcm_rec[pcm_idx].jack = jack->jack statically. + + +Unsolicited Event Enabling +-------------------------- +Enable unsolicited event if !acomp. + + +Monitor Hotplug Event Handling +------------------------------ +- acomp +pin_eld_notify() -> check_presence_and_report() -> hdmi_present_sense() -> +sync_eld_via_acomp(). +Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for +both dyn_pcm_assign and !dyn_pcm_assign + +- !acomp +Hdmi_unsol_event() -> hdmi_intrinsic_event() -> check_presence_and_report() -> +hdmi_present_sense() -> hdmi_prepsent_sense_via_verbs() +Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for dyn_pcm_assign. +Use hda_jack mechanism to handle jack events. + + +Others to be added later +======================== diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt deleted file mode 100644 index de8efbc7e4bd..000000000000 --- a/Documentation/sound/alsa/hda_codec.txt +++ /dev/null @@ -1,322 +0,0 @@ -Notes on Universal Interface for Intel High Definition Audio Codec ------------------------------------------------------------------- - -Takashi Iwai <tiwai@suse.de> - - -[Still a draft version] - - -General -======= - -The snd-hda-codec module supports the generic access function for the -High Definition (HD) audio codecs. It's designed to be independent -from the controller code like ac97 codec module. The real accessors -from/to the controller must be implemented in the lowlevel driver. - -The structure of this module is similar with ac97_codec module. -Each codec chip belongs to a bus class which communicates with the -controller. - - -Initialization of Bus Instance -============================== - -The card driver has to create struct hda_bus at first. The template -struct should be filled and passed to the constructor: - -struct hda_bus_template { - void *private_data; - struct pci_dev *pci; - const char *modelname; - struct hda_bus_ops ops; -}; - -The card driver can set and use the private_data field to retrieve its -own data in callback functions. The pci field is used when the patch -needs to check the PCI subsystem IDs, so on. For non-PCI system, it -doesn't have to be set, of course. -The modelname field specifies the board's specific configuration. The -string is passed to the codec parser, and it depends on the parser how -the string is used. -These fields, private_data, pci and modelname are all optional. - -The ops field contains the callback functions as the following: - -struct hda_bus_ops { - int (*command)(struct hda_codec *codec, hda_nid_t nid, int direct, - unsigned int verb, unsigned int parm); - unsigned int (*get_response)(struct hda_codec *codec); - void (*private_free)(struct hda_bus *); -#ifdef CONFIG_SND_HDA_POWER_SAVE - void (*pm_notify)(struct hda_codec *codec); -#endif -}; - -The command callback is called when the codec module needs to send a -VERB to the controller. It's always a single command. -The get_response callback is called when the codec requires the answer -for the last command. These two callbacks are mandatory and have to -be given. -The third, private_free callback, is optional. It's called in the -destructor to release any necessary data in the lowlevel driver. - -The pm_notify callback is available only with -CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs -to power up or may power down. The controller should check the all -belonging codecs on the bus whether they are actually powered off -(check codec->power_on), and optionally the driver may power down the -controller side, too. - -The bus instance is created via snd_hda_bus_new(). You need to pass -the card instance, the template, and the pointer to store the -resultant bus instance. - -int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp, - struct hda_bus **busp); - -It returns zero if successful. A negative return value means any -error during creation. - - -Creation of Codec Instance -========================== - -Each codec chip on the board is then created on the BUS instance. -To create a codec instance, call snd_hda_codec_new(). - -int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr, - struct hda_codec **codecp); - -The first argument is the BUS instance, the second argument is the -address of the codec, and the last one is the pointer to store the -resultant codec instance (can be NULL if not needed). - -The codec is stored in a linked list of bus instance. You can follow -the codec list like: - - struct hda_codec *codec; - list_for_each_entry(codec, &bus->codec_list, list) { - ... - } - -The codec isn't initialized at this stage properly. The -initialization sequence is called when the controls are built later. - - -Codec Access -============ - -To access codec, use snd_hda_codec_read() and snd_hda_codec_write(). -snd_hda_param_read() is for reading parameters. -For writing a sequence of verbs, use snd_hda_sequence_write(). - -There are variants of cached read/write, snd_hda_codec_write_cache(), -snd_hda_sequence_write_cache(). These are used for recording the -register states for the power-management resume. When no PM is needed, -these are equivalent with non-cached version. - -To retrieve the number of sub nodes connected to the given node, use -snd_hda_get_sub_nodes(). The connection list can be obtained via -snd_hda_get_connections() call. - -When an unsolicited event happens, pass the event via -snd_hda_queue_unsol_event() so that the codec routines will process it -later. - - -(Mixer) Controls -================ - -To create mixer controls of all codecs, call -snd_hda_build_controls(). It then builds the mixers and does -initialization stuff on each codec. - - -PCM Stuff -========= - -snd_hda_build_pcms() gives the necessary information to create PCM -streams. When it's called, each codec belonging to the bus stores -codec->num_pcms and codec->pcm_info fields. The num_pcms indicates -the number of elements in pcm_info array. The card driver is supposed -to traverse the codec linked list, read the pcm information in -pcm_info array, and build pcm instances according to them. - -The pcm_info array contains the following record: - -/* PCM information for each substream */ -struct hda_pcm_stream { - unsigned int substreams; /* number of substreams, 0 = not exist */ - unsigned int channels_min; /* min. number of channels */ - unsigned int channels_max; /* max. number of channels */ - hda_nid_t nid; /* default NID to query rates/formats/bps, or set up */ - u32 rates; /* supported rates */ - u64 formats; /* supported formats (SNDRV_PCM_FMTBIT_) */ - unsigned int maxbps; /* supported max. bit per sample */ - struct hda_pcm_ops ops; -}; - -/* for PCM creation */ -struct hda_pcm { - char *name; - struct hda_pcm_stream stream[2]; -}; - -The name can be passed to snd_pcm_new(). The stream field contains -the information for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and -capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions. The card driver -should pass substreams to snd_pcm_new() for the number of substreams -to create. - -The channels_min, channels_max, rates and formats should be copied to -runtime->hw record. They and maxbps fields are used also to compute -the format value for the HDA codec and controller. Call -snd_hda_calc_stream_format() to get the format value. - -The ops field contains the following callback functions: - -struct hda_pcm_ops { - int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec, - struct snd_pcm_substream *substream); - int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec, - struct snd_pcm_substream *substream); - int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec, - unsigned int stream_tag, unsigned int format, - struct snd_pcm_substream *substream); - int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec, - struct snd_pcm_substream *substream); -}; - -All are non-NULL, so you can call them safely without NULL check. - -The open callback should be called in PCM open after runtime->hw is -set up. It may override some setting and constraints additionally. -Similarly, the close callback should be called in the PCM close. - -The prepare callback should be called in PCM prepare. This will set -up the codec chip properly for the operation. The cleanup should be -called in hw_free to clean up the configuration. - -The caller should check the return value, at least for open and -prepare callbacks. When a negative value is returned, some error -occurred. - - -Proc Files -========== - -Each codec dumps the widget node information in -/proc/asound/card*/codec#* file. This information would be really -helpful for debugging. Please provide its contents together with the -bug report. - - -Power Management -================ - -It's simple: -Call snd_hda_suspend() in the PM suspend callback. -Call snd_hda_resume() in the PM resume callback. - - -Codec Preset (Patch) -==================== - -To set up and handle the codec functionality fully, each codec may -have a codec preset (patch). It's defined in struct hda_codec_preset: - - struct hda_codec_preset { - unsigned int id; - unsigned int mask; - unsigned int subs; - unsigned int subs_mask; - unsigned int rev; - const char *name; - int (*patch)(struct hda_codec *codec); - }; - -When the codec id and codec subsystem id match with the given id and -subs fields bitwise (with bitmask mask and subs_mask), the callback -patch is called. The patch callback should initialize the codec and -set the codec->patch_ops field. This is defined as below: - - struct hda_codec_ops { - int (*build_controls)(struct hda_codec *codec); - int (*build_pcms)(struct hda_codec *codec); - int (*init)(struct hda_codec *codec); - void (*free)(struct hda_codec *codec); - void (*unsol_event)(struct hda_codec *codec, unsigned int res); - #ifdef CONFIG_PM - int (*suspend)(struct hda_codec *codec, pm_message_t state); - int (*resume)(struct hda_codec *codec); - #endif - #ifdef CONFIG_SND_HDA_POWER_SAVE - int (*check_power_status)(struct hda_codec *codec, - hda_nid_t nid); - #endif - }; - -The build_controls callback is called from snd_hda_build_controls(). -Similarly, the build_pcms callback is called from -snd_hda_build_pcms(). The init callback is called after -build_controls to initialize the hardware. -The free callback is called as a destructor. - -The unsol_event callback is called when an unsolicited event is -received. - -The suspend and resume callbacks are for power management. -They can be NULL if no special sequence is required. When the resume -callback is NULL, the driver calls the init callback and resumes the -registers from the cache. If other handling is needed, you'd need to -write your own resume callback. There, the amp values can be resumed -via - void snd_hda_codec_resume_amp(struct hda_codec *codec); -and the other codec registers via - void snd_hda_codec_resume_cache(struct hda_codec *codec); - -The check_power_status callback is called when the amp value of the -given widget NID is changed. The codec code can turn on/off the power -appropriately from this information. - -Each entry can be NULL if not necessary to be called. - - -Generic Parser -============== - -When the device doesn't match with any given presets, the widgets are -parsed via th generic parser (hda_generic.c). Its support is -limited: no multi-channel support, for example. - - -Digital I/O -=========== - -Call snd_hda_create_spdif_out_ctls() from the patch to create controls -related with SPDIF out. - - -Helper Functions -================ - -snd_hda_get_codec_name() stores the codec name on the given string. - -snd_hda_check_board_config() can be used to obtain the configuration -information matching with the device. Define the model string table -and the table with struct snd_pci_quirk entries (zero-terminated), -and pass it to the function. The function checks the modelname given -as a module parameter, and PCI subsystem IDs. If the matching entry -is found, it returns the config field value. - -snd_hda_add_new_ctls() can be used to create and add control entries. -Pass the zero-terminated array of struct snd_kcontrol_new - -Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be -used for the entry of struct snd_kcontrol_new. - -The input MUX helper callbacks for such a control are provided, too: -snd_hda_input_mux_info() and snd_hda_input_mux_put(). See -patch_realtek.c for example. diff --git a/Documentation/sound/alsa/img,spdif-in.txt b/Documentation/sound/alsa/img,spdif-in.txt new file mode 100644 index 000000000000..8b7505785fa6 --- /dev/null +++ b/Documentation/sound/alsa/img,spdif-in.txt @@ -0,0 +1,49 @@ +The Imagination Technologies SPDIF Input controller contains the following +controls: + +name='IEC958 Capture Mask',index=0 + +This control returns a mask that shows which of the IEC958 status bits +can be read using the 'IEC958 Capture Default' control. + +name='IEC958 Capture Default',index=0 + +This control returns the status bits contained within the SPDIF stream that +is being received. The 'IEC958 Capture Mask' shows which bits can be read +from this control. + +name='SPDIF In Multi Frequency Acquire',index=0 +name='SPDIF In Multi Frequency Acquire',index=1 +name='SPDIF In Multi Frequency Acquire',index=2 +name='SPDIF In Multi Frequency Acquire',index=3 + +This control is used to attempt acquisition of up to four different sample +rates. The active rate can be obtained by reading the 'SPDIF In Lock Frequency' +control. + +When the value of this control is set to {0,0,0,0}, the rate given to hw_params +will determine the single rate the block will capture. Else, the rate given to +hw_params will be ignored, and the block will attempt capture for each of the +four sample rates set here. + +If less than four rates are required, the same rate can be specified more than +once + +name='SPDIF In Lock Frequency',index=0 + +This control returns the active capture rate, or 0 if a lock has not been +acquired + +name='SPDIF In Lock TRK',index=0 + +This control is used to modify the locking/jitter rejection characteristics +of the block. Larger values increase the locking range, but reduce jitter +rejection. + +name='SPDIF In Lock Acquire Threshold',index=0 + +This control is used to change the threshold at which a lock is acquired. + +name='SPDIF In Lock Release Threshold',index=0 + +This control is used to change the threshold at which a lock is released. diff --git a/Documentation/spi/.gitignore b/Documentation/spi/.gitignore deleted file mode 100644 index 4280576397e8..000000000000 --- a/Documentation/spi/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -spidev_fdx -spidev_test diff --git a/Documentation/spi/00-INDEX b/Documentation/spi/00-INDEX index a128fa835512..4644bf0d9832 100644 --- a/Documentation/spi/00-INDEX +++ b/Documentation/spi/00-INDEX @@ -10,13 +10,9 @@ pxa2xx - PXA2xx SPI master controller build by spi_message fifo wq spidev - Intro to the userspace API for spi devices -spidev_fdx.c - - spidev example file spi-lm70llp - Connecting an LM70-LLP sensor to the kernel via the SPI subsys. spi-sc18is602 - NXP SC18IS602/603 I2C-bus to SPI bridge spi-summary - (Linux) SPI overview. If unsure about SPI or SPI in Linux, start here. -spidev_test.c - - SPI testing utility. diff --git a/Documentation/spi/Makefile b/Documentation/spi/Makefile deleted file mode 100644 index efa255813e9d..000000000000 --- a/Documentation/spi/Makefile +++ /dev/null @@ -1,8 +0,0 @@ -# List of programs to build -hostprogs-y := spidev_test spidev_fdx - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -HOSTCFLAGS_spidev_test.o += -I$(objtree)/usr/include -HOSTCFLAGS_spidev_fdx.o += -I$(objtree)/usr/include diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx index 3352f97430e4..13a0b7fb192f 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx @@ -22,15 +22,10 @@ Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a found in include/linux/spi/pxa2xx_spi.h: struct pxa2xx_spi_master { - u32 clock_enable; u16 num_chipselect; u8 enable_dma; }; -The "pxa2xx_spi_master.clock_enable" field is used to enable/disable the -corresponding SSP peripheral block in the "Clock Enable Register (CKEN"). See -the "PXA2xx Developer Manual" section "Clocks and Power Management". - The "pxa2xx_spi_master.num_chipselect" field is used to determine the number of slave device (chips) attached to this SPI master. @@ -57,7 +52,6 @@ static struct resource pxa_spi_nssp_resources[] = { }; static struct pxa2xx_spi_master pxa_nssp_master_info = { - .clock_enable = CKEN_NSSP, /* NSSP Peripheral clock */ .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ .enable_dma = 1, /* Enables NSSP DMA */ }; diff --git a/Documentation/spi/spidev_fdx.c b/Documentation/spi/spidev_fdx.c deleted file mode 100644 index 0ea3e51292fc..000000000000 --- a/Documentation/spi/spidev_fdx.c +++ /dev/null @@ -1,158 +0,0 @@ -#include <stdio.h> -#include <unistd.h> -#include <stdlib.h> -#include <fcntl.h> -#include <string.h> - -#include <sys/ioctl.h> -#include <sys/types.h> -#include <sys/stat.h> - -#include <linux/types.h> -#include <linux/spi/spidev.h> - - -static int verbose; - -static void do_read(int fd, int len) -{ - unsigned char buf[32], *bp; - int status; - - /* read at least 2 bytes, no more than 32 */ - if (len < 2) - len = 2; - else if (len > sizeof(buf)) - len = sizeof(buf); - memset(buf, 0, sizeof buf); - - status = read(fd, buf, len); - if (status < 0) { - perror("read"); - return; - } - if (status != len) { - fprintf(stderr, "short read\n"); - return; - } - - printf("read(%2d, %2d): %02x %02x,", len, status, - buf[0], buf[1]); - status -= 2; - bp = buf + 2; - while (status-- > 0) - printf(" %02x", *bp++); - printf("\n"); -} - -static void do_msg(int fd, int len) -{ - struct spi_ioc_transfer xfer[2]; - unsigned char buf[32], *bp; - int status; - - memset(xfer, 0, sizeof xfer); - memset(buf, 0, sizeof buf); - - if (len > sizeof buf) - len = sizeof buf; - - buf[0] = 0xaa; - xfer[0].tx_buf = (unsigned long)buf; - xfer[0].len = 1; - - xfer[1].rx_buf = (unsigned long) buf; - xfer[1].len = len; - - status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer); - if (status < 0) { - perror("SPI_IOC_MESSAGE"); - return; - } - - printf("response(%2d, %2d): ", len, status); - for (bp = buf; len; len--) - printf(" %02x", *bp++); - printf("\n"); -} - -static void dumpstat(const char *name, int fd) -{ - __u8 lsb, bits; - __u32 mode, speed; - - if (ioctl(fd, SPI_IOC_RD_MODE32, &mode) < 0) { - perror("SPI rd_mode"); - return; - } - if (ioctl(fd, SPI_IOC_RD_LSB_FIRST, &lsb) < 0) { - perror("SPI rd_lsb_fist"); - return; - } - if (ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits) < 0) { - perror("SPI bits_per_word"); - return; - } - if (ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed) < 0) { - perror("SPI max_speed_hz"); - return; - } - - printf("%s: spi mode 0x%x, %d bits %sper word, %d Hz max\n", - name, mode, bits, lsb ? "(lsb first) " : "", speed); -} - -int main(int argc, char **argv) -{ - int c; - int readcount = 0; - int msglen = 0; - int fd; - const char *name; - - while ((c = getopt(argc, argv, "hm:r:v")) != EOF) { - switch (c) { - case 'm': - msglen = atoi(optarg); - if (msglen < 0) - goto usage; - continue; - case 'r': - readcount = atoi(optarg); - if (readcount < 0) - goto usage; - continue; - case 'v': - verbose++; - continue; - case 'h': - case '?': -usage: - fprintf(stderr, - "usage: %s [-h] [-m N] [-r N] /dev/spidevB.D\n", - argv[0]); - return 1; - } - } - - if ((optind + 1) != argc) - goto usage; - name = argv[optind]; - - fd = open(name, O_RDWR); - if (fd < 0) { - perror("open"); - return 1; - } - - dumpstat(name, fd); - - if (msglen) - do_msg(fd, msglen); - - if (readcount) - do_read(fd, readcount); - - close(fd); - return 0; -} diff --git a/Documentation/spi/spidev_test.c b/Documentation/spi/spidev_test.c deleted file mode 100644 index 135b3f592b83..000000000000 --- a/Documentation/spi/spidev_test.c +++ /dev/null @@ -1,318 +0,0 @@ -/* - * SPI testing utility (using spidev driver) - * - * Copyright (c) 2007 MontaVista Software, Inc. - * Copyright (c) 2007 Anton Vorontsov <avorontsov@ru.mvista.com> - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License. - * - * Cross-compile with cross-gcc -I/path/to/cross-kernel/include - */ - -#include <stdint.h> -#include <unistd.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <getopt.h> -#include <fcntl.h> -#include <sys/ioctl.h> -#include <linux/types.h> -#include <linux/spi/spidev.h> - -#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0])) - -static void pabort(const char *s) -{ - perror(s); - abort(); -} - -static const char *device = "/dev/spidev1.1"; -static uint32_t mode; -static uint8_t bits = 8; -static uint32_t speed = 500000; -static uint16_t delay; -static int verbose; - -uint8_t default_tx[] = { - 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, - 0x40, 0x00, 0x00, 0x00, 0x00, 0x95, - 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, - 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, - 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, - 0xF0, 0x0D, -}; - -uint8_t default_rx[ARRAY_SIZE(default_tx)] = {0, }; -char *input_tx; - -static void hex_dump(const void *src, size_t length, size_t line_size, char *prefix) -{ - int i = 0; - const unsigned char *address = src; - const unsigned char *line = address; - unsigned char c; - - printf("%s | ", prefix); - while (length-- > 0) { - printf("%02X ", *address++); - if (!(++i % line_size) || (length == 0 && i % line_size)) { - if (length == 0) { - while (i++ % line_size) - printf("__ "); - } - printf(" | "); /* right close */ - while (line < address) { - c = *line++; - printf("%c", (c < 33 || c == 255) ? 0x2E : c); - } - printf("\n"); - if (length > 0) - printf("%s | ", prefix); - } - } -} - -/* - * Unescape - process hexadecimal escape character - * converts shell input "\x23" -> 0x23 - */ -static int unescape(char *_dst, char *_src, size_t len) -{ - int ret = 0; - char *src = _src; - char *dst = _dst; - unsigned int ch; - - while (*src) { - if (*src == '\\' && *(src+1) == 'x') { - sscanf(src + 2, "%2x", &ch); - src += 4; - *dst++ = (unsigned char)ch; - } else { - *dst++ = *src++; - } - ret++; - } - return ret; -} - -static void transfer(int fd, uint8_t const *tx, uint8_t const *rx, size_t len) -{ - int ret; - - struct spi_ioc_transfer tr = { - .tx_buf = (unsigned long)tx, - .rx_buf = (unsigned long)rx, - .len = len, - .delay_usecs = delay, - .speed_hz = speed, - .bits_per_word = bits, - }; - - if (mode & SPI_TX_QUAD) - tr.tx_nbits = 4; - else if (mode & SPI_TX_DUAL) - tr.tx_nbits = 2; - if (mode & SPI_RX_QUAD) - tr.rx_nbits = 4; - else if (mode & SPI_RX_DUAL) - tr.rx_nbits = 2; - if (!(mode & SPI_LOOP)) { - if (mode & (SPI_TX_QUAD | SPI_TX_DUAL)) - tr.rx_buf = 0; - else if (mode & (SPI_RX_QUAD | SPI_RX_DUAL)) - tr.tx_buf = 0; - } - - ret = ioctl(fd, SPI_IOC_MESSAGE(1), &tr); - if (ret < 1) - pabort("can't send spi message"); - - if (verbose) - hex_dump(tx, len, 32, "TX"); - hex_dump(rx, len, 32, "RX"); -} - -static void print_usage(const char *prog) -{ - printf("Usage: %s [-DsbdlHOLC3]\n", prog); - puts(" -D --device device to use (default /dev/spidev1.1)\n" - " -s --speed max speed (Hz)\n" - " -d --delay delay (usec)\n" - " -b --bpw bits per word \n" - " -l --loop loopback\n" - " -H --cpha clock phase\n" - " -O --cpol clock polarity\n" - " -L --lsb least significant bit first\n" - " -C --cs-high chip select active high\n" - " -3 --3wire SI/SO signals shared\n" - " -v --verbose Verbose (show tx buffer)\n" - " -p Send data (e.g. \"1234\\xde\\xad\")\n" - " -N --no-cs no chip select\n" - " -R --ready slave pulls low to pause\n" - " -2 --dual dual transfer\n" - " -4 --quad quad transfer\n"); - exit(1); -} - -static void parse_opts(int argc, char *argv[]) -{ - while (1) { - static const struct option lopts[] = { - { "device", 1, 0, 'D' }, - { "speed", 1, 0, 's' }, - { "delay", 1, 0, 'd' }, - { "bpw", 1, 0, 'b' }, - { "loop", 0, 0, 'l' }, - { "cpha", 0, 0, 'H' }, - { "cpol", 0, 0, 'O' }, - { "lsb", 0, 0, 'L' }, - { "cs-high", 0, 0, 'C' }, - { "3wire", 0, 0, '3' }, - { "no-cs", 0, 0, 'N' }, - { "ready", 0, 0, 'R' }, - { "dual", 0, 0, '2' }, - { "verbose", 0, 0, 'v' }, - { "quad", 0, 0, '4' }, - { NULL, 0, 0, 0 }, - }; - int c; - - c = getopt_long(argc, argv, "D:s:d:b:lHOLC3NR24p:v", lopts, NULL); - - if (c == -1) - break; - - switch (c) { - case 'D': - device = optarg; - break; - case 's': - speed = atoi(optarg); - break; - case 'd': - delay = atoi(optarg); - break; - case 'b': - bits = atoi(optarg); - break; - case 'l': - mode |= SPI_LOOP; - break; - case 'H': - mode |= SPI_CPHA; - break; - case 'O': - mode |= SPI_CPOL; - break; - case 'L': - mode |= SPI_LSB_FIRST; - break; - case 'C': - mode |= SPI_CS_HIGH; - break; - case '3': - mode |= SPI_3WIRE; - break; - case 'N': - mode |= SPI_NO_CS; - break; - case 'v': - verbose = 1; - break; - case 'R': - mode |= SPI_READY; - break; - case 'p': - input_tx = optarg; - break; - case '2': - mode |= SPI_TX_DUAL; - break; - case '4': - mode |= SPI_TX_QUAD; - break; - default: - print_usage(argv[0]); - break; - } - } - if (mode & SPI_LOOP) { - if (mode & SPI_TX_DUAL) - mode |= SPI_RX_DUAL; - if (mode & SPI_TX_QUAD) - mode |= SPI_RX_QUAD; - } -} - -int main(int argc, char *argv[]) -{ - int ret = 0; - int fd; - uint8_t *tx; - uint8_t *rx; - int size; - - parse_opts(argc, argv); - - fd = open(device, O_RDWR); - if (fd < 0) - pabort("can't open device"); - - /* - * spi mode - */ - ret = ioctl(fd, SPI_IOC_WR_MODE32, &mode); - if (ret == -1) - pabort("can't set spi mode"); - - ret = ioctl(fd, SPI_IOC_RD_MODE32, &mode); - if (ret == -1) - pabort("can't get spi mode"); - - /* - * bits per word - */ - ret = ioctl(fd, SPI_IOC_WR_BITS_PER_WORD, &bits); - if (ret == -1) - pabort("can't set bits per word"); - - ret = ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits); - if (ret == -1) - pabort("can't get bits per word"); - - /* - * max speed hz - */ - ret = ioctl(fd, SPI_IOC_WR_MAX_SPEED_HZ, &speed); - if (ret == -1) - pabort("can't set max speed hz"); - - ret = ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed); - if (ret == -1) - pabort("can't get max speed hz"); - - printf("spi mode: 0x%x\n", mode); - printf("bits per word: %d\n", bits); - printf("max speed: %d Hz (%d KHz)\n", speed, speed/1000); - - if (input_tx) { - size = strlen(input_tx+1); - tx = malloc(size); - rx = malloc(size); - size = unescape((char *)tx, input_tx, size); - transfer(fd, tx, rx, size); - free(rx); - free(tx); - } else { - transfer(fd, default_tx, default_rx, sizeof(default_tx)); - } - - close(fd); - - return ret; -} diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index 3049a612291b..ffd4575ec9f2 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -93,7 +93,7 @@ format in the sign-off area: Also, some patches may have kernel version prerequisites. This can be specified in the following format in the sign-off area: - Cc: <stable@vger.kernel.org> # 3.3.x- + Cc: <stable@vger.kernel.org> # 3.3.x- The tag has the meaning of: git cherry-pick <this commit> diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.txt index 88152f214f48..302b5ed616a6 100644 --- a/Documentation/sysctl/fs.txt +++ b/Documentation/sysctl/fs.txt @@ -32,6 +32,8 @@ Currently, these files are in /proc/sys/fs: - nr_open - overflowuid - overflowgid +- pipe-user-pages-hard +- pipe-user-pages-soft - protected_hardlinks - protected_symlinks - suid_dumpable @@ -159,6 +161,27 @@ The default is 65534. ============================================================== +pipe-user-pages-hard: + +Maximum total number of pages a non-privileged user may allocate for pipes. +Once this limit is reached, no new pipes may be allocated until usage goes +below the limit again. When set to 0, no limit is applied, which is the default +setting. + +============================================================== + +pipe-user-pages-soft: + +Maximum total number of pages a non-privileged user may allocate for pipes +before the pipe size gets limited to a single page. Once this limit is reached, +new pipes will be limited to a single page in size for this user in order to +limit total memory usage, and trying to increase them using fcntl() will be +denied until usage goes below the limit again. The default value allows to +allocate up to 1024 pipes at their default size. When set to 0, no limit is +applied. + +============================================================== + protected_hardlinks: A long-standing class of security issues is the hardlink-based diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 6fccb69c03e7..57653a44b128 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -33,6 +33,7 @@ show up in /proc/sys/kernel: - domainname - hostname - hotplug +- hardlockup_all_cpu_backtrace - hung_task_panic - hung_task_check_count - hung_task_timeout_secs @@ -57,12 +58,15 @@ show up in /proc/sys/kernel: - panic_on_stackoverflow - panic_on_unrecovered_nmi - panic_on_warn +- perf_cpu_time_max_percent +- perf_event_paranoid - pid_max - powersave-nap [ PPC only ] - printk - printk_delay - printk_ratelimit - printk_ratelimit_burst +- pty ==> Documentation/filesystems/devpts.txt - randomize_va_space - real-root-dev ==> Documentation/initrd.txt - reboot-cmd [ SPARC only ] @@ -293,6 +297,17 @@ domain names are in general different. For a detailed discussion see the hostname(1) man page. ============================================================== +hardlockup_all_cpu_backtrace: + +This value controls the hard lockup detector behavior when a hard +lockup condition is detected as to whether or not to gather further +debug information. If enabled, arch-specific all-CPU stack dumping +will be initiated. + +0: do nothing. This is the default behavior. + +1: on detection capture more debug information. +============================================================== hotplug: @@ -539,6 +554,21 @@ the recommended setting is 60. ============================================================== +panic_on_io_nmi: + +Controls the kernel's behavior when a CPU receives an NMI caused by +an IO error. + +0: try to continue operation (default) + +1: panic immediately. The IO error triggered an NMI. This indicates a + serious system condition which could result in IO data corruption. + Rather than continuing, panicking might be a better choice. Some + servers issue this sort of NMI when the dump button is pushed, + and you can use this option to take a crash dump. + +============================================================== + panic_on_oops: Controls the kernel's behaviour when an oops or BUG is encountered. @@ -612,6 +642,17 @@ allowed to execute. ============================================================== +perf_event_paranoid: + +Controls use of the performance events system by unprivileged +users (without CAP_SYS_ADMIN). The default value is 1. + + -1: Allow use of (almost) all events by all users +>=0: Disallow raw tracepoint access by users without CAP_IOC_LOCK +>=1: Disallow CPU event access by users without CAP_SYS_ADMIN +>=2: Disallow kernel profiling by users without CAP_SYS_ADMIN + +============================================================== pid_max: @@ -733,6 +774,14 @@ rtsig-nr shows the number of RT signals currently queued. ============================================================== +sched_schedstats: + +Enables/disables scheduler statistics. Enabling this feature +incurs a small amount of overhead in the scheduler but is +useful for debugging and performance tuning. + +============================================================== + sg-big-buff: This file shows the size of the generic SCSI (sg) buffer. @@ -798,14 +847,13 @@ via the /proc/sys interface: Each write syscall must fully contain the sysctl value to be written, and multiple writes on the same sysctl file descriptor will rewrite the sysctl value, regardless of file position. - 0 - (default) Same behavior as above, but warn about processes that - perform writes to a sysctl file descriptor when the file position - is not 0. - 1 - Respect file position when writing sysctl strings. Multiple writes - will append to the sysctl value buffer. Anything past the max length - of the sysctl value buffer will be ignored. Writes to numeric sysctl - entries must always be at file position 0 and the value must be - fully contained in the buffer sent in the write syscall. + 0 - Same behavior as above, but warn about processes that perform writes + to a sysctl file descriptor when the file position is not 0. + 1 - (default) Respect file position when writing sysctl strings. Multiple + writes will append to the sysctl value buffer. Anything past the max + length of the sysctl value buffer will be ignored. Writes to numeric + sysctl entries must always be at file position 0 and the value must + be fully contained in the buffer sent in the write syscall. ============================================================== diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index a4482fceacec..cb0368459da3 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -42,6 +42,8 @@ Currently, these files are in /proc/sys/vm: - min_slab_ratio - min_unmapped_ratio - mmap_min_addr +- mmap_rnd_bits +- mmap_rnd_compat_bits - nr_hugepages - nr_overcommit_hugepages - nr_trim_pages (only if CONFIG_MMU=n) @@ -135,7 +137,7 @@ Contains, as a percentage of total available memory that contains free pages and reclaimable pages, the number of pages at which the background kernel flusher threads will start writing out dirty data. -The total avaiable memory is not equal to total system memory. +The total available memory is not equal to total system memory. ============================================================== @@ -170,7 +172,7 @@ Contains, as a percentage of total available memory that contains free pages and reclaimable pages, the number of pages at which a process which is generating disk writes will itself start writing out dirty data. -The total avaiable memory is not equal to total system memory. +The total available memory is not equal to total system memory. ============================================================== @@ -485,6 +487,33 @@ against future potential kernel bugs. ============================================================== +mmap_rnd_bits: + +This value can be used to select the number of bits to use to +determine the random offset to the base address of vma regions +resulting from mmap allocations on architectures which support +tuning address space randomization. This value will be bounded +by the architecture's minimum and maximum supported values. + +This value can be changed after boot using the +/proc/sys/vm/mmap_rnd_bits tunable + +============================================================== + +mmap_rnd_compat_bits: + +This value can be used to select the number of bits to use to +determine the random offset to the base address of vma regions +resulting from mmap allocations for applications run in +compatibility mode on architectures which support tuning address +space randomization. This value will be bounded by the +architecture's minimum and maximum supported values. + +This value can be changed after boot using the +/proc/sys/vm/mmap_rnd_compat_bits tunable + +============================================================== + nr_hugepages Change the minimum size of the hugepage pool. @@ -639,7 +668,7 @@ and don't use much of it. The default value is 0. See Documentation/vm/overcommit-accounting and -security/commoncap.c::cap_vm_enough_memory() for more information. +mm/mmap.c::__vm_enough_memory() for more information. ============================================================== @@ -774,6 +803,24 @@ performance impact. Reclaim code needs to take various locks to find freeable directory and inode objects. With vfs_cache_pressure=1000, it will look for ten times more freeable objects than there are. +============================================================= + +watermark_scale_factor: + +This factor controls the aggressiveness of kswapd. It defines the +amount of memory left in a node/system before kswapd is woken up and +how much memory needs to be free before kswapd goes back to sleep. + +The unit is in fractions of 10,000. The default value of 10 means the +distances between watermarks are 0.1% of the available memory in the +node/system. The maximum value is 1000, or 10% of memory. + +A high rate of threads entering direct reclaim (allocstall) or kswapd +going to sleep prematurely (kswapd_low_wmark_hit_quickly) can indicate +that the number of free pages kswapd maintains for latency reasons is +too small for the allocation bursts occurring in the system. This knob +can then be used to tune kswapd aggressiveness accordingly. + ============================================================== zone_reclaim_mode: diff --git a/Documentation/target/tcm_mod_builder.py b/Documentation/target/tcm_mod_builder.py index cda56df9b8a7..7d370c9b1450 100755 --- a/Documentation/target/tcm_mod_builder.py +++ b/Documentation/target/tcm_mod_builder.py @@ -203,8 +203,6 @@ def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += "#include <scsi/scsi_proto.h>\n\n" buf += "#include <target/target_core_base.h>\n" buf += "#include <target/target_core_fabric.h>\n" - buf += "#include <target/target_core_fabric_configfs.h>\n" - buf += "#include <target/configfs_macros.h>\n\n" buf += "#include \"" + fabric_mod_name + "_base.h\"\n" buf += "#include \"" + fabric_mod_name + "_fabric.h\"\n\n" @@ -283,19 +281,6 @@ def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += " struct " + fabric_mod_name + "_" + fabric_mod_port + ", " + fabric_mod_port + "_wwn);\n" buf += " kfree(" + fabric_mod_port + ");\n" buf += "}\n\n" - buf += "static ssize_t " + fabric_mod_name + "_wwn_show_attr_version(\n" - buf += " struct target_fabric_configfs *tf,\n" - buf += " char *page)\n" - buf += "{\n" - buf += " return sprintf(page, \"" + fabric_mod_name.upper() + " fabric module %s on %s/%s\"\n" - buf += " \"on \"UTS_RELEASE\"\\n\", " + fabric_mod_name.upper() + "_VERSION, utsname()->sysname,\n" - buf += " utsname()->machine);\n" - buf += "}\n\n" - buf += "TF_WWN_ATTR_RO(" + fabric_mod_name + ", version);\n\n" - buf += "static struct configfs_attribute *" + fabric_mod_name + "_wwn_attrs[] = {\n" - buf += " &" + fabric_mod_name + "_wwn_version.attr,\n" - buf += " NULL,\n" - buf += "};\n\n" buf += "static const struct target_core_fabric_ops " + fabric_mod_name + "_ops = {\n" buf += " .module = THIS_MODULE,\n" @@ -328,8 +313,6 @@ def tcm_mod_build_configfs(proto_ident, fabric_mod_dir_var, fabric_mod_name): buf += " .fabric_drop_wwn = " + fabric_mod_name + "_drop_" + fabric_mod_port + ",\n" buf += " .fabric_make_tpg = " + fabric_mod_name + "_make_tpg,\n" buf += " .fabric_drop_tpg = " + fabric_mod_name + "_drop_tpg,\n" - buf += "\n" - buf += " .tfc_wwn_attrs = " + fabric_mod_name + "_wwn_attrs,\n" buf += "};\n\n" buf += "static int __init " + fabric_mod_name + "_init(void)\n" diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt index 10f062ea6bc2..8c745c8931da 100644 --- a/Documentation/thermal/sysfs-api.txt +++ b/Documentation/thermal/sysfs-api.txt @@ -364,6 +364,7 @@ integral_cutoff accumulates error when temperature is above the desired temperature trip point. For more information see Documentation/thermal/power_allocator.txt + Unit: millidegree Celsius RW, Optional slope diff --git a/Documentation/timers/hpet.txt b/Documentation/timers/hpet.txt index 767392ffd31e..a484d2c109d7 100644 --- a/Documentation/timers/hpet.txt +++ b/Documentation/timers/hpet.txt @@ -1,9 +1,7 @@ High Precision Event Timer Driver for Linux The High Precision Event Timer (HPET) hardware follows a specification -by Intel and Microsoft which can be found at - - http://www.intel.com/hardwaredesign/hpetspec_1.pdf +by Intel and Microsoft, revision 1. Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision") and up to 32 comparators. Normally three or more comparators are provided, diff --git a/Documentation/timers/hpet_example.c b/Documentation/timers/hpet_example.c index 9a3e7012c190..3ab4993d85e0 100644 --- a/Documentation/timers/hpet_example.c +++ b/Documentation/timers/hpet_example.c @@ -49,7 +49,7 @@ struct hpet_command { int main(int argc, const char ** argv) { - int i; + unsigned int i; argc--; argv++; diff --git a/Documentation/trace/events-msr.txt b/Documentation/trace/events-msr.txt new file mode 100644 index 000000000000..78c383bf06aa --- /dev/null +++ b/Documentation/trace/events-msr.txt @@ -0,0 +1,37 @@ + +The x86 kernel supports tracing most MSR (Model Specific Register) accesses. +To see the definition of the MSRs on Intel systems please see the SDM +at http://www.intel.com/sdm (Volume 3) + +Available trace points: + +/sys/kernel/debug/tracing/events/msr/ + +Trace MSR reads + +read_msr + +msr: MSR number +val: Value written +failed: 1 if the access failed, otherwise 0 + + +Trace MSR writes + +write_msr + +msr: MSR number +val: Value written +failed: 1 if the access failed, otherwise 0 + + +Trace RDPMC in kernel + +rdpmc + +The trace data can be post processed with the postprocess/decode_msr.py script + +cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h + +to add symbolic MSR names. + diff --git a/Documentation/trace/events.txt b/Documentation/trace/events.txt index 75d25a1d6e42..c010be8c85d7 100644 --- a/Documentation/trace/events.txt +++ b/Documentation/trace/events.txt @@ -288,6 +288,24 @@ prev_pid == 0 # cat sched_wakeup/filter common_pid == 0 +5.4 PID filtering +----------------- + +The set_event_pid file in the same directory as the top events directory +exists, will filter all events from tracing any task that does not have the +PID listed in the set_event_pid file. + +# cd /sys/kernel/debug/tracing +# echo $$ > set_event_pid +# echo 1 > events/enabled + +Will only trace events for the current task. + +To add more PIDs without losing the PIDs already included, use '>>'. + +# echo 123 244 1 >> set_event_pid + + 6. Event triggers ================= diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index ef621d34ba5b..f52f297cb406 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt @@ -204,6 +204,12 @@ of ftrace. Here is a list of some of the key files: Have the function tracer only trace a single thread. + set_event_pid: + + Have the events only trace a task with a PID listed in this file. + Note, sched_switch and sched_wake_up will also trace events + listed in this file. + set_graph_function: Set a "trigger" function where tracing should start @@ -2437,6 +2443,23 @@ The following commands are supported: echo '!writeback*:mod:ext3' >> set_ftrace_filter + Mod command supports module globbing. Disable tracing for all + functions except a specific module: + + echo '!*:mod:!ext3' >> set_ftrace_filter + + Disable tracing for all modules, but still trace kernel: + + echo '!*:mod:*' >> set_ftrace_filter + + Enable filter only for kernel: + + echo '*write*:mod:!*' >> set_ftrace_filter + + Enable filter for module globbing: + + echo '*write*:mod:*snd*' >> set_ftrace_filter + - traceon/traceoff These commands turn tracing on and off when the specified functions are hit. The parameter determines how many times the diff --git a/Documentation/trace/intel_th.txt b/Documentation/trace/intel_th.txt new file mode 100644 index 000000000000..f7fc5ba5df8d --- /dev/null +++ b/Documentation/trace/intel_th.txt @@ -0,0 +1,99 @@ +Intel(R) Trace Hub (TH) +======================= + +Overview +-------- + +Intel(R) Trace Hub (TH) is a set of hardware blocks that produce, +switch and output trace data from multiple hardware and software +sources over several types of trace output ports encoded in System +Trace Protocol (MIPI STPv2) and is intended to perform full system +debugging. For more information on the hardware, see Intel(R) Trace +Hub developer's manual [1]. + +It consists of trace sources, trace destinations (outputs) and a +switch (Global Trace Hub, GTH). These devices are placed on a bus of +their own ("intel_th"), where they can be discovered and configured +via sysfs attributes. + +Currently, the following Intel TH subdevices (blocks) are supported: + - Software Trace Hub (STH), trace source, which is a System Trace + Module (STM) device, + - Memory Storage Unit (MSU), trace output, which allows storing + trace hub output in system memory, + - Parallel Trace Interface output (PTI), trace output to an external + debug host via a PTI port, + - Global Trace Hub (GTH), which is a switch and a central component + of Intel(R) Trace Hub architecture. + +Common attributes for output devices are described in +Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most +notable of them is "active", which enables or disables trace output +into that particular output device. + +GTH allows directing different STP masters into different output ports +via its "masters" attribute group. More detailed GTH interface +description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth. + +STH registers an stm class device, through which it provides interface +to userspace and kernelspace software trace sources. See +Documentation/tracing/stm.txt for more information on that. + +MSU can be configured to collect trace data into a system memory +buffer, which can later on be read from its device nodes via read() or +mmap() interface. + +On the whole, Intel(R) Trace Hub does not require any special +userspace software to function; everything can be configured, started +and collected via sysfs attributes, and device nodes. + +[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf + +Bus and Subdevices +------------------ + +For each Intel TH device in the system a bus of its own is +created and assigned an id number that reflects the order in which TH +devices were emumerated. All TH subdevices (devices on intel_th bus) +begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is +followed by device's name and an optional index. + +Output devices also get a device node in /dev/intel_thN, where N is +the Intel TH device id. For example, MSU's memory buffers, when +allocated, are accessible via /dev/intel_th0/msc{0,1}. + +Quick example +------------- + +# figure out which GTH port is the first memory controller: + +$ cat /sys/bus/intel_th/devices/0-msc0/port +0 + +# looks like it's port 0, configure master 33 to send data to port 0: + +$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33 + +# allocate a 2-windowed multiblock buffer on the first memory +# controller, each with 64 pages: + +$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode +$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages + +# enable wrapping for this controller, too: + +$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap + +# and enable tracing into this port: + +$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active + +# .. send data to master 33, see stm.txt for more details .. +# .. wait for traces to pile up .. +# .. and stop the trace: + +$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active + +# and now you can collect the trace from the device node: + +$ cat /dev/intel_th0/msc0 > my_stp_trace diff --git a/Documentation/trace/postprocess/decode_msr.py b/Documentation/trace/postprocess/decode_msr.py new file mode 100644 index 000000000000..0ab40e0db580 --- /dev/null +++ b/Documentation/trace/postprocess/decode_msr.py @@ -0,0 +1,37 @@ +#!/usr/bin/python +# add symbolic names to read_msr / write_msr in trace +# decode_msr msr-index.h < trace +import sys +import re + +msrs = dict() + +with open(sys.argv[1] if len(sys.argv) > 1 else "msr-index.h", "r") as f: + for j in f: + m = re.match(r'#define (MSR_\w+)\s+(0x[0-9a-fA-F]+)', j) + if m: + msrs[int(m.group(2), 16)] = m.group(1) + +extra_ranges = ( + ( "MSR_LASTBRANCH_%d_FROM_IP", 0x680, 0x69F ), + ( "MSR_LASTBRANCH_%d_TO_IP", 0x6C0, 0x6DF ), + ( "LBR_INFO_%d", 0xdc0, 0xddf ), +) + +for j in sys.stdin: + m = re.search(r'(read|write)_msr:\s+([0-9a-f]+)', j) + if m: + r = None + num = int(m.group(2), 16) + if num in msrs: + r = msrs[num] + else: + for er in extra_ranges: + if er[1] <= num <= er[2]: + r = er[0] % (num - er[1],) + break + if r: + j = j.replace(" " + m.group(2), " " + r + "(" + m.group(2) + ")") + print j, + + diff --git a/Documentation/trace/stm.txt b/Documentation/trace/stm.txt new file mode 100644 index 000000000000..ea035f9dbfd7 --- /dev/null +++ b/Documentation/trace/stm.txt @@ -0,0 +1,80 @@ +System Trace Module +=================== + +System Trace Module (STM) is a device described in MIPI STP specs as +STP trace stream generator. STP (System Trace Protocol) is a trace +protocol multiplexing data from multiple trace sources, each one of +which is assigned a unique pair of master and channel. While some of +these masters and channels are statically allocated to certain +hardware trace sources, others are available to software. Software +trace sources are usually free to pick for themselves any +master/channel combination from this pool. + +On the receiving end of this STP stream (the decoder side), trace +sources can only be identified by master/channel combination, so in +order for the decoder to be able to make sense of the trace that +involves multiple trace sources, it needs to be able to map those +master/channel pairs to the trace sources that it understands. + +For instance, it is helpful to know that syslog messages come on +master 7 channel 15, while arbitrary user applications can use masters +48 to 63 and channels 0 to 127. + +To solve this mapping problem, stm class provides a policy management +mechanism via configfs, that allows defining rules that map string +identifiers to ranges of masters and channels. If these rules (policy) +are consistent with what decoder expects, it will be able to properly +process the trace data. + +This policy is a tree structure containing rules (policy_node) that +have a name (string identifier) and a range of masters and channels +associated with it, located in "stp-policy" subsystem directory in +configfs. The topmost directory's name (the policy) is formatted as +the STM device name to which this policy applies and and arbitrary +string identifier separated by a stop. From the examle above, a rule +may look like this: + +$ ls /config/stp-policy/dummy_stm.my-policy/user +channels masters +$ cat /config/stp-policy/dummy_stm.my-policy/user/masters +48 63 +$ cat /config/stp-policy/dummy_stm.my-policy/user/channels +0 127 + +which means that the master allocation pool for this rule consists of +masters 48 through 63 and channel allocation pool has channels 0 +through 127 in it. Now, any producer (trace source) identifying itself +with "user" identification string will be allocated a master and +channel from within these ranges. + +These rules can be nested, for example, one can define a rule "dummy" +under "user" directory from the example above and this new rule will +be used for trace sources with the id string of "user/dummy". + +Trace sources have to open the stm class device's node and write their +trace data into its file descriptor. In order to identify themselves +to the policy, they need to do a STP_POLICY_ID_SET ioctl on this file +descriptor providing their id string. Otherwise, they will be +automatically allocated a master/channel pair upon first write to this +file descriptor according to the "default" rule of the policy, if such +exists. + +Some STM devices may allow direct mapping of the channel mmio regions +to userspace for zero-copy writing. One mappable page (in terms of +mmu) will usually contain multiple channels' mmios, so the user will +need to allocate that many channels to themselves (via the +aforementioned ioctl() call) to be able to do this. That is, if your +stm device's channel mmio region is 64 bytes and hardware page size is +4096 bytes, after a successful STP_POLICY_ID_SET ioctl() call with +width==64, you should be able to mmap() one page on this file +descriptor and obtain direct access to an mmio region for 64 channels. + +For kernel-based trace sources, there is "stm_source" device +class. Devices of this class can be connected and disconnected to/from +stm devices at runtime via a sysfs attribute. + +Examples of STM devices are Intel(R) Trace Hub [1] and Coresight STM +[2]. + +[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf +[2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html diff --git a/Documentation/ubsan.txt b/Documentation/ubsan.txt new file mode 100644 index 000000000000..f58215ef5797 --- /dev/null +++ b/Documentation/ubsan.txt @@ -0,0 +1,84 @@ +Undefined Behavior Sanitizer - UBSAN + +Overview +-------- + +UBSAN is a runtime undefined behaviour checker. + +UBSAN uses compile-time instrumentation to catch undefined behavior (UB). +Compiler inserts code that perform certain kinds of checks before operations +that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_* +function called to print error message. + +GCC has that feature since 4.9.x [1] (see -fsanitize=undefined option and +its suboptions). GCC 5.x has more checkers implemented [2]. + +Report example +--------------- + + ================================================================================ + UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 + shift exponent 32 is to large for 32-bit type 'unsigned int' + CPU: 0 PID: 0 Comm: swapper Not tainted 4.4.0-rc1+ #26 + 0000000000000000 ffffffff82403cc8 ffffffff815e6cd6 0000000000000001 + ffffffff82403cf8 ffffffff82403ce0 ffffffff8163a5ed 0000000000000020 + ffffffff82403d78 ffffffff8163ac2b ffffffff815f0001 0000000000000002 + Call Trace: + [<ffffffff815e6cd6>] dump_stack+0x45/0x5f + [<ffffffff8163a5ed>] ubsan_epilogue+0xd/0x40 + [<ffffffff8163ac2b>] __ubsan_handle_shift_out_of_bounds+0xeb/0x130 + [<ffffffff815f0001>] ? radix_tree_gang_lookup_slot+0x51/0x150 + [<ffffffff8173c586>] _mix_pool_bytes+0x1e6/0x480 + [<ffffffff83105653>] ? dmi_walk_early+0x48/0x5c + [<ffffffff8173c881>] add_device_randomness+0x61/0x130 + [<ffffffff83105b35>] ? dmi_save_one_device+0xaa/0xaa + [<ffffffff83105653>] dmi_walk_early+0x48/0x5c + [<ffffffff831066ae>] dmi_scan_machine+0x278/0x4b4 + [<ffffffff8111d58a>] ? vprintk_default+0x1a/0x20 + [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120 + [<ffffffff830b2240>] setup_arch+0x405/0xc2c + [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120 + [<ffffffff830ae053>] start_kernel+0x83/0x49a + [<ffffffff830ad120>] ? early_idt_handler_array+0x120/0x120 + [<ffffffff830ad386>] x86_64_start_reservations+0x2a/0x2c + [<ffffffff830ad4f3>] x86_64_start_kernel+0x16b/0x17a + ================================================================================ + +Usage +----- + +To enable UBSAN configure kernel with: + + CONFIG_UBSAN=y + +and to check the entire kernel: + + CONFIG_UBSAN_SANITIZE_ALL=y + +To enable instrumentation for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + + For a single file (e.g. main.o): + UBSAN_SANITIZE_main.o := y + + For all files in one directory: + UBSAN_SANITIZE := y + +To exclude files from being instrumented even if +CONFIG_UBSAN_SANITIZE_ALL=y, use: + + UBSAN_SANITIZE_main.o := n + and: + UBSAN_SANITIZE := n + +Detection of unaligned accesses controlled through the separate option - +CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support +unaligned accesses (CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS=y). One could +still enable it in config, just note that it will produce a lot of UBSAN +reports. + +References +---------- + +[1] - https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html +[2] - https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html diff --git a/Documentation/usb/authorization.txt b/Documentation/usb/authorization.txt index c069b6884c77..c7e985f05d8f 100644 --- a/Documentation/usb/authorization.txt +++ b/Documentation/usb/authorization.txt @@ -90,3 +90,34 @@ etc, but you get the idea. Anybody with access to a device gadget kit can fake descriptors and device info. Don't trust that. You are welcome. + +Interface authorization +----------------------- +There is a similar approach to allow or deny specific USB interfaces. +That allows to block only a subset of an USB device. + +Authorize an interface: +$ echo 1 > /sys/bus/usb/devices/INTERFACE/authorized + +Deauthorize an interface: +$ echo 0 > /sys/bus/usb/devices/INTERFACE/authorized + +The default value for new interfaces +on a particular USB bus can be changed, too. + +Allow interfaces per default: +$ echo 1 > /sys/bus/usb/devices/usbX/interface_authorized_default + +Deny interfaces per default: +$ echo 0 > /sys/bus/usb/devices/usbX/interface_authorized_default + +Per default the interface_authorized_default bit is 1. +So all interfaces would authorized per default. + +Note: +If a deauthorized interface will be authorized so the driver probing must +be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe + +For drivers that need multiple interfaces all needed interfaces should be +authroized first. After that the drivers should be probed. +This avoids side effects. diff --git a/Documentation/usb/chipidea.txt b/Documentation/usb/chipidea.txt index 3f848c1f2940..678741b0f213 100644 --- a/Documentation/usb/chipidea.txt +++ b/Documentation/usb/chipidea.txt @@ -7,8 +7,8 @@ with 2 Freescale i.MX6Q sabre SD boards. --------------------------------------- Select CONFIG_USB_OTG_FSM, rebuild kernel Image and modules. If you want to check some internal variables for otg fsm, -select CONFIG_USB_CHIPIDEA_DEBUG, there are 2 files which -can show otg fsm variables and some controller registers value: +mount debugfs, there are 2 files which can show otg fsm +variables and some controller registers value: cat /sys/kernel/debug/ci_hdrc.0/otg cat /sys/kernel/debug/ci_hdrc.0/registers @@ -26,16 +26,17 @@ cat /sys/kernel/debug/ci_hdrc.0/registers On B-device: echo 1 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req - if HNP polling is not supported, also need: - On A-device: - echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req - B-device should take host role and enumrate A-device. 4) A-device switch back to host. On B-device: echo 0 > /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req + or, by introducing HNP polling, B-Host can know when A-peripheral wish + to be host role, so this role switch also can be trigged in A-peripheral + 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. 5) Remove B-device(unplug micro B plug) and insert again in 10 seconds, diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt index b24d3ef89166..581960574889 100644 --- a/Documentation/usb/gadget-testing.txt +++ b/Documentation/usb/gadget-testing.txt @@ -434,7 +434,7 @@ On host: serialc -v <vendorID> -p <productID> -i<interface#> -a1 -s1024 \ where seriald and serialc are Felipe's utilities found here: -https://git.gitorious.org/usb/usb-tools.git master +https://github.com/felipebalbi/usb-tools.git master 12. PHONET function =================== @@ -579,6 +579,8 @@ The SOURCESINK function provides these attributes in its function directory: isoc_mult - 0..2 (hs/ss only) isoc_maxburst - 0..15 (ss only) bulk_buflen - buffer length + bulk_qlen - depth of queue for bulk + iso_qlen - depth of queue for iso Testing the SOURCESINK function ------------------------------- diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 4a15c90bc11d..0a94ffe17ab6 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -537,17 +537,18 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm. can write y/Y/1 or n/N/0 to the file to enable/disable USB2 hardware LPM manually. This is for test purpose mainly. - power/usb3_hardware_lpm + power/usb3_hardware_lpm_u1 + power/usb3_hardware_lpm_u2 When a USB 3.0 lpm-capable device is plugged in to a xHCI host which supports link PM, it will check if U1 and U2 exit latencies have been set in the BOS descriptor; if the check is is passed and the host supports USB3 hardware LPM, USB3 hardware LPM will be - enabled for the device and this file will be created. - The file holds a string value (enable or disable) - indicating whether or not USB3 hardware LPM is - enabled for the device. + enabled for the device and these files will be created. + The files hold a string value (enable or disable) + indicating whether or not USB3 hardware LPM U1 or U2 + is enabled for the device. USB Port Power Control ---------------------- diff --git a/Documentation/usb/usbdevfs-drop-permissions.c b/Documentation/usb/usbdevfs-drop-permissions.c new file mode 100644 index 000000000000..6b8da6ef0c9a --- /dev/null +++ b/Documentation/usb/usbdevfs-drop-permissions.c @@ -0,0 +1,120 @@ +#include <sys/ioctl.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <stdio.h> +#include <errno.h> +#include <string.h> +#include <inttypes.h> +#include <unistd.h> + +#include <linux/usbdevice_fs.h> + +/* For building without an updated set of headers */ +#ifndef USBDEVFS_DROP_PRIVILEGES +#define USBDEVFS_DROP_PRIVILEGES _IOW('U', 30, __u32) +#define USBDEVFS_CAP_DROP_PRIVILEGES 0x40 +#endif + +void drop_privileges(int fd, uint32_t mask) +{ + int res; + + res = ioctl(fd, USBDEVFS_DROP_PRIVILEGES, &mask); + if (res) + printf("ERROR: USBDEVFS_DROP_PRIVILEGES returned %d\n", res); + else + printf("OK: privileges dropped!\n"); +} + +void reset_device(int fd) +{ + int res; + + res = ioctl(fd, USBDEVFS_RESET); + if (!res) + printf("OK: USBDEVFS_RESET succeeded\n"); + else + printf("ERROR: reset failed! (%d - %s)\n", + -res, strerror(-res)); +} + +void claim_some_intf(int fd) +{ + int i, res; + + for (i = 0; i < 4; i++) { + res = ioctl(fd, USBDEVFS_CLAIMINTERFACE, &i); + if (!res) + printf("OK: claimed if %d\n", i); + else + printf("ERROR claiming if %d (%d - %s)\n", + i, -res, strerror(-res)); + } +} + +int main(int argc, char *argv[]) +{ + uint32_t mask, caps; + int c, fd; + + fd = open(argv[1], O_RDWR); + if (fd < 0) { + printf("Failed to open file\n"); + goto err_fd; + } + + /* + * check if dropping privileges is supported, + * bail on systems where the capability is not present + */ + ioctl(fd, USBDEVFS_GET_CAPABILITIES, &caps); + if (!(caps & USBDEVFS_CAP_DROP_PRIVILEGES)) { + printf("DROP_PRIVILEGES not supported\n"); + goto err; + } + + /* + * Drop privileges but keep the ability to claim all + * free interfaces (i.e., those not used by kernel drivers) + */ + drop_privileges(fd, -1U); + + printf("Available options:\n" + "[0] Exit now\n" + "[1] Reset device. Should fail if device is in use\n" + "[2] Claim 4 interfaces. Should succeed where not in use\n" + "[3] Narrow interface permission mask\n" + "Which option shall I run?: "); + + while (scanf("%d", &c) == 1) { + switch (c) { + case 0: + goto exit; + case 1: + reset_device(fd); + break; + case 2: + claim_some_intf(fd); + break; + case 3: + printf("Insert new mask: "); + scanf("%x", &mask); + drop_privileges(fd, mask); + break; + default: + printf("I don't recognize that\n"); + } + + printf("Which test shall I run next?: "); + } + +exit: + close(fd); + return 0; + +err: + close(fd); +err_fd: + return 1; +} diff --git a/Documentation/usb/usbip_protocol.txt b/Documentation/usb/usbip_protocol.txt new file mode 100644 index 000000000000..16b6fe27284c --- /dev/null +++ b/Documentation/usb/usbip_protocol.txt @@ -0,0 +1,358 @@ +PRELIMINARY DRAFT, MAY CONTAIN MISTAKES! +28 Jun 2011 + +The USB/IP protocol follows a server/client architecture. The server exports the +USB devices and the clients imports them. The device driver for the exported +USB device runs on the client machine. + +The client may ask for the list of the exported USB devices. To get the list the +client opens a TCP/IP connection towards the server, and sends an OP_REQ_DEVLIST +packet on top of the TCP/IP connection (so the actual OP_REQ_DEVLIST may be sent +in one or more pieces at the low level transport layer). The server sends back +the OP_REP_DEVLIST packet which lists the exported USB devices. Finally the +TCP/IP connection is closed. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | OP_REQ_DEVLIST | + | ----------------------------------------------> | + | | + | OP_REP_DEVLIST | + | <---------------------------------------------- | + | | + +Once the client knows the list of exported USB devices it may decide to use one +of them. First the client opens a TCP/IP connection towards the server and +sends an OP_REQ_IMPORT packet. The server replies with OP_REP_IMPORT. If the +import was successful the TCP/IP connection remains open and will be used +to transfer the URB traffic between the client and the server. The client may +send two types of packets: the USBIP_CMD_SUBMIT to submit an URB, and +USBIP_CMD_UNLINK to unlink a previously submitted URB. The answers of the +server may be USBIP_RET_SUBMIT and USBIP_RET_UNLINK respectively. + + virtual host controller usb host + "client" "server" + (imports USB devices) (exports USB devices) + | | + | OP_REQ_IMPORT | + | ----------------------------------------------> | + | | + | OP_REP_IMPORT | + | <---------------------------------------------- | + | | + | | + | USBIP_CMD_SUBMIT(seqnum = n) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = n) | + | <---------------------------------------------- | + | . | + | : | + | | + | USBIP_CMD_SUBMIT(seqnum = m) | + | ----------------------------------------------> | + | | + | USBIP_CMD_SUBMIT(seqnum = m+1) | + | ----------------------------------------------> | + | | + | USBIP_CMD_SUBMIT(seqnum = m+2) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = m) | + | <---------------------------------------------- | + | | + | USBIP_CMD_SUBMIT(seqnum = m+3) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = m+1) | + | <---------------------------------------------- | + | | + | USBIP_CMD_SUBMIT(seqnum = m+4) | + | ----------------------------------------------> | + | | + | USBIP_RET_SUBMIT(seqnum = m+2) | + | <---------------------------------------------- | + | . | + | : | + | | + | USBIP_CMD_UNLINK | + | ----------------------------------------------> | + | | + | USBIP_RET_UNLINK | + | <---------------------------------------------- | + | | + +The fields are in network (big endian) byte order meaning that the most significant +byte (MSB) is stored at the lowest address. + + +OP_REQ_DEVLIST: Retrieve the list of exported USB devices. + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 +-----------+--------+------------+--------------------------------------------------- + 2 | 2 | 0x8005 | Command code: Retrieve the list of exported USB + | | | devices. +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 + +OP_REP_DEVLIST: Reply with the list of exported USB devices. + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0. +-----------+--------+------------+--------------------------------------------------- + 2 | 2 | 0x0005 | Reply code: The list of exported USB devices. +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | 0x00000000 | Status: 0 for OK +-----------+--------+------------+--------------------------------------------------- + 8 | 4 | n | Number of exported devices: 0 means no exported + | | | devices. +-----------+--------+------------+--------------------------------------------------- + 0x0C | | | From now on the exported n devices are described, + | | | if any. If no devices are exported the message + | | | ends with the previous "number of exported + | | | devices" field. +-----------+--------+------------+--------------------------------------------------- + | 256 | | path: Path of the device on the host exporting the + | | | USB device, string closed with zero byte, e.g. + | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" + | | | The unused bytes shall be filled with zero + | | | bytes. +-----------+--------+------------+--------------------------------------------------- + 0x10C | 32 | | busid: Bus ID of the exported device, string + | | | closed with zero byte, e.g. "3-2". The unused + | | | bytes shall be filled with zero bytes. +-----------+--------+------------+--------------------------------------------------- + 0x12C | 4 | | busnum +-----------+--------+------------+--------------------------------------------------- + 0x130 | 4 | | devnum +-----------+--------+------------+--------------------------------------------------- + 0x134 | 4 | | speed +-----------+--------+------------+--------------------------------------------------- + 0x138 | 2 | | idVendor +-----------+--------+------------+--------------------------------------------------- + 0x13A | 2 | | idProduct +-----------+--------+------------+--------------------------------------------------- + 0x13C | 2 | | bcdDevice +-----------+--------+------------+--------------------------------------------------- + 0x13E | 1 | | bDeviceClass +-----------+--------+------------+--------------------------------------------------- + 0x13F | 1 | | bDeviceSubClass +-----------+--------+------------+--------------------------------------------------- + 0x140 | 1 | | bDeviceProtocol +-----------+--------+------------+--------------------------------------------------- + 0x141 | 1 | | bConfigurationValue +-----------+--------+------------+--------------------------------------------------- + 0x142 | 1 | | bNumConfigurations +-----------+--------+------------+--------------------------------------------------- + 0x143 | 1 | | bNumInterfaces +-----------+--------+------------+--------------------------------------------------- + 0x144 | | m_0 | From now on each interface is described, all + | | | together bNumInterfaces times, with the + | | | the following 4 fields: +-----------+--------+------------+--------------------------------------------------- + | 1 | | bInterfaceClass +-----------+--------+------------+--------------------------------------------------- + 0x145 | 1 | | bInterfaceSubClass +-----------+--------+------------+--------------------------------------------------- + 0x146 | 1 | | bInterfaceProtocol +-----------+--------+------------+--------------------------------------------------- + 0x147 | 1 | | padding byte for alignment, shall be set to zero +-----------+--------+------------+--------------------------------------------------- + 0xC + | | | The second exported USB device starts at i=1 + i*0x138 + | | | with the busid field. + m_(i-1)*4 | | | + +OP_REQ_IMPORT: Request to import (attach) a remote USB device. + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 +-----------+--------+------------+--------------------------------------------------- + 2 | 2 | 0x8003 | Command code: import a remote USB device. +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | 0x00000000 | Status: unused, shall be set to 0 +-----------+--------+------------+--------------------------------------------------- + 8 | 32 | | busid: the busid of the exported device on the + | | | remote host. The possible values are taken + | | | from the message field OP_REP_DEVLIST.busid. + | | | A string closed with zero, the unused bytes + | | | shall be filled with zeros. +-----------+--------+------------+--------------------------------------------------- + +OP_REP_IMPORT: Reply to import (attach) a remote USB device. + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 2 | 0x0100 | Binary-coded decimal USBIP version number: v1.0.0 +-----------+--------+------------+--------------------------------------------------- + 2 | 2 | 0x0003 | Reply code: Reply to import. +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | 0x00000000 | Status: 0 for OK + | | | 1 for error +-----------+--------+------------+--------------------------------------------------- + 8 | | | From now on comes the details of the imported + | | | device, if the previous status field was OK (0), + | | | otherwise the reply ends with the status field. +-----------+--------+------------+--------------------------------------------------- + | 256 | | path: Path of the device on the host exporting the + | | | USB device, string closed with zero byte, e.g. + | | | "/sys/devices/pci0000:00/0000:00:1d.1/usb3/3-2" + | | | The unused bytes shall be filled with zero + | | | bytes. +-----------+--------+------------+--------------------------------------------------- + 0x108 | 32 | | busid: Bus ID of the exported device, string + | | | closed with zero byte, e.g. "3-2". The unused + | | | bytes shall be filled with zero bytes. +-----------+--------+------------+--------------------------------------------------- + 0x128 | 4 | | busnum +-----------+--------+------------+--------------------------------------------------- + 0x12C | 4 | | devnum +-----------+--------+------------+--------------------------------------------------- + 0x130 | 4 | | speed +-----------+--------+------------+--------------------------------------------------- + 0x134 | 2 | | idVendor +-----------+--------+------------+--------------------------------------------------- + 0x136 | 2 | | idProduct +-----------+--------+------------+--------------------------------------------------- + 0x138 | 2 | | bcdDevice +-----------+--------+------------+--------------------------------------------------- + 0x139 | 1 | | bDeviceClass +-----------+--------+------------+--------------------------------------------------- + 0x13A | 1 | | bDeviceSubClass +-----------+--------+------------+--------------------------------------------------- + 0x13B | 1 | | bDeviceProtocol +-----------+--------+------------+--------------------------------------------------- + 0x13C | 1 | | bConfigurationValue +-----------+--------+------------+--------------------------------------------------- + 0x13D | 1 | | bNumConfigurations +-----------+--------+------------+--------------------------------------------------- + 0x13E | 1 | | bNumInterfaces + +USBIP_CMD_SUBMIT: Submit an URB + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 4 | 0x00000001 | command: Submit an URB +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | | seqnum: the sequence number of the URB to submit +-----------+--------+------------+--------------------------------------------------- + 8 | 4 | | devid +-----------+--------+------------+--------------------------------------------------- + 0xC | 4 | | direction: 0: USBIP_DIR_OUT + | | | 1: USBIP_DIR_IN +-----------+--------+------------+--------------------------------------------------- + 0x10 | 4 | | ep: endpoint number, possible values are: 0...15 +-----------+--------+------------+--------------------------------------------------- + 0x14 | 4 | | transfer_flags: possible values depend on the + | | | URB transfer type, see below +-----------+--------+------------+--------------------------------------------------- + 0x18 | 4 | | transfer_buffer_length +-----------+--------+------------+--------------------------------------------------- + 0x1C | 4 | | start_frame: specify the selected frame to + | | | transmit an ISO frame, ignored if URB_ISO_ASAP + | | | is specified at transfer_flags +-----------+--------+------------+--------------------------------------------------- + 0x20 | 4 | | number_of_packets: number of ISO packets +-----------+--------+------------+--------------------------------------------------- + 0x24 | 4 | | interval: maximum time for the request on the + | | | server-side host controller +-----------+--------+------------+--------------------------------------------------- + 0x28 | 8 | | setup: data bytes for USB setup, filled with + | | | zeros if not used +-----------+--------+------------+--------------------------------------------------- + 0x30 | | | URB data. For ISO transfers the padding between + | | | each ISO packets is not transmitted. + + + Allowed transfer_flags | value | control | interrupt | bulk | isochronous + -------------------------+------------+---------+-----------+----------+------------- + 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 + URB_DIR_MASK | 0x00000200 | yes | yes | yes | yes + + +USBIP_RET_SUBMIT: Reply for submitting an URB + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 4 | 0x00000003 | command +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | | seqnum: URB sequence number +-----------+--------+------------+--------------------------------------------------- + 8 | 4 | | devid +-----------+--------+------------+--------------------------------------------------- + 0xC | 4 | | direction: 0: USBIP_DIR_OUT + | | | 1: USBIP_DIR_IN +-----------+--------+------------+--------------------------------------------------- + 0x10 | 4 | | ep: endpoint number +-----------+--------+------------+--------------------------------------------------- + 0x14 | 4 | | status: zero for successful URB transaction, + | | | otherwise some kind of error happened. +-----------+--------+------------+--------------------------------------------------- + 0x18 | 4 | n | actual_length: number of URB data bytes +-----------+--------+------------+--------------------------------------------------- + 0x1C | 4 | | start_frame: for an ISO frame the actually + | | | selected frame for transmit. +-----------+--------+------------+--------------------------------------------------- + 0x20 | 4 | | number_of_packets +-----------+--------+------------+--------------------------------------------------- + 0x24 | 4 | | error_count +-----------+--------+------------+--------------------------------------------------- + 0x28 | 8 | | setup: data bytes for USB setup, filled with + | | | zeros if not used +-----------+--------+------------+--------------------------------------------------- + 0x30 | n | | URB data bytes. For ISO transfers the padding + | | | between each ISO packets is not transmitted. + +USBIP_CMD_UNLINK: Unlink an URB + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 4 | 0x00000002 | command: URB unlink command +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | | seqnum: URB sequence number to unlink: FIXME: is this so? +-----------+--------+------------+--------------------------------------------------- + 8 | 4 | | devid +-----------+--------+------------+--------------------------------------------------- + 0xC | 4 | | direction: 0: USBIP_DIR_OUT + | | | 1: USBIP_DIR_IN +-----------+--------+------------+--------------------------------------------------- + 0x10 | 4 | | ep: endpoint number: zero +-----------+--------+------------+--------------------------------------------------- + 0x14 | 4 | | seqnum: the URB sequence number given previously + | | | at USBIP_CMD_SUBMIT.seqnum field +-----------+--------+------------+--------------------------------------------------- + 0x30 | n | | URB data bytes. For ISO transfers the padding + | | | between each ISO packets is not transmitted. + +USBIP_RET_UNLINK: Reply for URB unlink + + Offset | Length | Value | Description +-----------+--------+------------+--------------------------------------------------- + 0 | 4 | 0x00000004 | command: reply for the URB unlink command +-----------+--------+------------+--------------------------------------------------- + 4 | 4 | | seqnum: the unlinked URB sequence number +-----------+--------+------------+--------------------------------------------------- + 8 | 4 | | devid +-----------+--------+------------+--------------------------------------------------- + 0xC | 4 | | direction: 0: USBIP_DIR_OUT + | | | 1: USBIP_DIR_IN +-----------+--------+------------+--------------------------------------------------- + 0x10 | 4 | | ep: endpoint number +-----------+--------+------------+--------------------------------------------------- + 0x14 | 4 | | status: This is the value contained in the + | | | urb->status in the URB completition handler. + | | | FIXME: a better explanation needed. +-----------+--------+------------+--------------------------------------------------- + 0x30 | n | | URB data bytes. For ISO transfers the padding + | | | between each ISO packets is not transmitted. diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html index 256f8efa992c..eaf948cf1ae7 100644 --- a/Documentation/video4linux/API.html +++ b/Documentation/video4linux/API.html @@ -9,7 +9,7 @@ <table border="0"> <tr> <td> - <a href="http://linuxtv.org/downloads/legacy/video4linux/API/V4L1_API.html">V4L original API</a> + <a href="https://linuxtv.org/downloads/legacy/video4linux/API/V4L1_API.html">V4L original API</a> </td> <td> Obsoleted by V4L2 API diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx index 9e57ce43c4f4..67209998a439 100644 --- a/Documentation/video4linux/CARDLIST.em28xx +++ b/Documentation/video4linux/CARDLIST.em28xx @@ -41,8 +41,8 @@ 40 -> Plextor ConvertX PX-TV100U (em2861) [093b:a005] 41 -> Kworld 350 U DVB-T (em2870) [eb1a:e350] 42 -> Kworld 355 U DVB-T (em2870) [eb1a:e355,eb1a:e357,eb1a:e359] - 43 -> Terratec Cinergy T XS (em2870) [0ccd:0043] - 44 -> Terratec Cinergy T XS (MT2060) (em2870) + 43 -> Terratec Cinergy T XS (em2870) + 44 -> Terratec Cinergy T XS (MT2060) (em2870) [0ccd:0043] 45 -> Pinnacle PCTV DVB-T (em2870) 46 -> Compro, VideoMate U3 (em2870) [185b:2870] 47 -> KWorld DVB-T 305U (em2880) [eb1a:e305] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index f4b395bdc090..335c24338859 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -193,3 +193,5 @@ 192 -> AverMedia AverTV Satellite Hybrid+FM A706 [1461:2055] 193 -> WIS Voyager or compatible [1905:7007] 194 -> AverMedia AverTV/505 [1461:a10a] +195 -> Leadtek Winfast TV2100 FM [107d:6f3a] +196 -> SnaZio* TVPVR PRO [1779:13cf] diff --git a/Documentation/video4linux/fimc.txt b/Documentation/video4linux/fimc.txt index e0c6b8bc4743..4fab231be52e 100644 --- a/Documentation/video4linux/fimc.txt +++ b/Documentation/video4linux/fimc.txt @@ -58,7 +58,7 @@ Not currently supported: 4.1. Media device interface The driver supports Media Controller API as defined at -http://linuxtv.org/downloads/v4l-dvb-apis/media_common.html +https://linuxtv.org/downloads/v4l-dvb-apis/media_common.html The media device driver name is "SAMSUNG S5P FIMC". The purpose of this interface is to allow changing assignment of FIMC instances @@ -83,11 +83,11 @@ undefined behaviour. 4.3. Capture video node The driver supports V4L2 Video Capture Interface as defined at: -http://linuxtv.org/downloads/v4l-dvb-apis/devices.html +https://linuxtv.org/downloads/v4l-dvb-apis/devices.html At the capture and mem-to-mem video nodes only the multi-planar API is supported. For more details see: -http://linuxtv.org/downloads/v4l-dvb-apis/planar-apis.html +https://linuxtv.org/downloads/v4l-dvb-apis/planar-apis.html 4.4. Camera capture subdevs diff --git a/Documentation/video4linux/omap4_camera.txt b/Documentation/video4linux/omap4_camera.txt index 25d9b40a4651..a6734aa77242 100644 --- a/Documentation/video4linux/omap4_camera.txt +++ b/Documentation/video4linux/omap4_camera.txt @@ -47,7 +47,7 @@ Tested platforms File list --------- drivers/staging/media/omap4iss/ -include/media/omap4iss.h +include/linux/platform_data/media/omap4iss.h References ---------- diff --git a/Documentation/video4linux/si4713.txt b/Documentation/video4linux/si4713.txt index 2e7392a4fee1..2ddc6b095a76 100644 --- a/Documentation/video4linux/si4713.txt +++ b/Documentation/video4linux/si4713.txt @@ -157,7 +157,7 @@ int main (int argc, char *argv[]) } The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under -include/media/si4713.h. +include/linux/platform_data/media/si4713.h. Stereo/Mono and RDS subchannels =============================== diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 5517db602f37..5e759cab4538 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -647,7 +647,6 @@ Or you can add specific controls to a handler: volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...); - v4l2_ctrl_add_ctrl(&radio_ctrl_handler, volume); What you should not do is make two identical controls for two handlers. For example: diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index 75d5c18d689a..fa41608ab2b4 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -295,16 +295,16 @@ module owner. This is done for you if you use the i2c helper functions. If integration with the media framework is needed, you must initialize the media_entity struct embedded in the v4l2_subdev struct (entity field) by -calling media_entity_init(): +calling media_entity_pads_init(), if the entity has pads: struct media_pad *pads = &my_sd->pads; int err; - err = media_entity_init(&sd->entity, npads, pads, 0); + err = media_entity_pads_init(&sd->entity, npads, pads); The pads array must have been previously initialized. There is no need to -manually set the struct media_entity type and name fields, but the revision -field must be initialized if needed. +manually set the struct media_entity function and name fields, but the +revision field must be initialized if needed. A reference to the entity will be automatically acquired/released when the subdev device node (if any) is opened/closed. @@ -695,12 +695,12 @@ difference is that the inode argument is omitted since it is never used. If integration with the media framework is needed, you must initialize the media_entity struct embedded in the video_device struct (entity field) by -calling media_entity_init(): +calling media_entity_pads_init(): struct media_pad *pad = &my_vdev->pad; int err; - err = media_entity_init(&vdev->entity, 1, pad, 0); + err = media_entity_pads_init(&vdev->entity, 1, pad); The pads array must have been previously initialized. There is no need to manually set the struct media_entity type and name fields. diff --git a/Documentation/video4linux/v4l2-pci-skeleton.c b/Documentation/video4linux/v4l2-pci-skeleton.c index 9c80c090e92d..79af0c041056 100644 --- a/Documentation/video4linux/v4l2-pci-skeleton.c +++ b/Documentation/video4linux/v4l2-pci-skeleton.c @@ -37,6 +37,7 @@ #include <media/v4l2-dv-timings.h> #include <media/v4l2-ctrls.h> #include <media/v4l2-event.h> +#include <media/videobuf2-v4l2.h> #include <media/videobuf2-dma-contig.h> MODULE_DESCRIPTION("V4L2 PCI Skeleton Driver"); @@ -162,7 +163,7 @@ static irqreturn_t skeleton_irq(int irq, void *dev_id) * minimum number: many DMA engines need a minimum of 2 buffers in the * queue and you need to have another available for userspace processing. */ -static int queue_setup(struct vb2_queue *vq, const struct v4l2_format *fmt, +static int queue_setup(struct vb2_queue *vq, unsigned int *nbuffers, unsigned int *nplanes, unsigned int sizes[], void *alloc_ctxs[]) { @@ -181,12 +182,12 @@ static int queue_setup(struct vb2_queue *vq, const struct v4l2_format *fmt, if (vq->num_buffers + *nbuffers < 3) *nbuffers = 3 - vq->num_buffers; + alloc_ctxs[0] = skel->alloc_ctx; - if (fmt && fmt->fmt.pix.sizeimage < skel->format.sizeimage) - return -EINVAL; + if (*nplanes) + return sizes[0] < skel->format.sizeimage ? -EINVAL : 0; *nplanes = 1; - sizes[0] = fmt ? fmt->fmt.pix.sizeimage : skel->format.sizeimage; - alloc_ctxs[0] = skel->alloc_ctx; + sizes[0] = skel->format.sizeimage; return 0; } @@ -507,7 +508,7 @@ static int skeleton_s_dv_timings(struct file *file, void *_fh, return -EINVAL; /* Return 0 if the new timings are the same as the current timings. */ - if (v4l2_match_dv_timings(timings, &skel->timings, 0)) + if (v4l2_match_dv_timings(timings, &skel->timings, 0, false)) return 0; /* diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index d9ecceea5a02..4d0542c5206b 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -401,10 +401,9 @@ Capability: basic Architectures: x86, ppc, mips Type: vcpu ioctl Parameters: struct kvm_interrupt (in) -Returns: 0 on success, -1 on error +Returns: 0 on success, negative on failure. -Queues a hardware interrupt vector to be injected. This is only -useful if in-kernel local APIC or equivalent is not used. +Queues a hardware interrupt vector to be injected. /* for KVM_INTERRUPT */ struct kvm_interrupt { @@ -414,7 +413,14 @@ struct kvm_interrupt { X86: -Note 'irq' is an interrupt vector, not an interrupt pin or line. +Returns: 0 on success, + -EEXIST if an interrupt is already enqueued + -EINVAL the the irq number is invalid + -ENXIO if the PIC is in the kernel + -EFAULT if the pointer is invalid + +Note 'irq' is an interrupt vector, not an interrupt pin or line. This +ioctl is useful if the in-kernel PIC is not used. PPC: @@ -1445,6 +1451,7 @@ struct kvm_irq_routing_entry { struct kvm_irq_routing_irqchip irqchip; struct kvm_irq_routing_msi msi; struct kvm_irq_routing_s390_adapter adapter; + struct kvm_irq_routing_hv_sint hv_sint; __u32 pad[8]; } u; }; @@ -1453,6 +1460,7 @@ struct kvm_irq_routing_entry { #define KVM_IRQ_ROUTING_IRQCHIP 1 #define KVM_IRQ_ROUTING_MSI 2 #define KVM_IRQ_ROUTING_S390_ADAPTER 3 +#define KVM_IRQ_ROUTING_HV_SINT 4 No flags are specified so far, the corresponding field must be set to zero. @@ -1476,6 +1484,10 @@ struct kvm_irq_routing_s390_adapter { __u32 adapter_id; }; +struct kvm_irq_routing_hv_sint { + __u32 vcpu; + __u32 sint; +}; 4.53 KVM_ASSIGN_SET_MSIX_NR (deprecated) @@ -1598,7 +1610,7 @@ provided event instead of triggering an exit. struct kvm_ioeventfd { __u64 datamatch; __u64 addr; /* legal pio/mmio address */ - __u32 len; /* 1, 2, 4, or 8 bytes */ + __u32 len; /* 0, 1, 2, 4, or 8 bytes */ __s32 fd; __u32 flags; __u8 pad[36]; @@ -1621,6 +1633,10 @@ to the registered address is equal to datamatch in struct kvm_ioeventfd. For virtio-ccw devices, addr contains the subchannel id and datamatch the virtqueue index. +With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, and +the kernel will ignore the length of guest write and may get a faster vmexit. +The speedup may only apply to specific architectures, but the ioeventfd will +work anyway. 4.60 KVM_DIRTY_TLB @@ -1774,7 +1790,7 @@ has been called, this interface is completely emulated within the kernel. To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the following algorithm: - - pause the vpcu + - pause the vcpu - read the local APIC's state (KVM_GET_LAPIC) - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1) - if so, issue KVM_NMI @@ -2491,8 +2507,9 @@ struct kvm_create_device { 4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR -Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device -Type: device ioctl, vm ioctl +Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, + KVM_CAP_VCPU_ATTRIBUTES for vcpu device +Type: device ioctl, vm ioctl, vcpu ioctl Parameters: struct kvm_device_attr Returns: 0 on success, -1 on error Errors: @@ -2517,8 +2534,9 @@ struct kvm_device_attr { 4.81 KVM_HAS_DEVICE_ATTR -Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device -Type: device ioctl, vm ioctl +Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, + KVM_CAP_VCPU_ATTRIBUTES for vcpu device +Type: device ioctl, vm ioctl, vcpu ioctl Parameters: struct kvm_device_attr Returns: 0 on success, -1 on error Errors: @@ -2561,6 +2579,8 @@ Possible features: Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only). - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 for the CPU. Depends on KVM_CAP_ARM_PSCI_0_2. + - KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU. + Depends on KVM_CAP_ARM_PMU_V3. 4.83 KVM_ARM_PREFERRED_TARGET @@ -2798,7 +2818,7 @@ Returns: = 0 on success, < 0 on generic error (e.g. -EFAULT or -ENOMEM), > 0 if an exception occurred while walking the page tables -Read or write data from/to the logical (virtual) memory of a VPCU. +Read or write data from/to the logical (virtual) memory of a VCPU. Parameters are specified via the following structure: @@ -3009,7 +3029,7 @@ len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0 and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq), which is the maximum number of possibly pending cpu-local interrupts. -4.90 KVM_SMI +4.96 KVM_SMI Capability: KVM_CAP_X86_SMM Architectures: x86 @@ -3019,6 +3039,87 @@ Returns: 0 on success, -1 on error Queues an SMI on the thread's vcpu. +4.97 KVM_CAP_PPC_MULTITCE + +Capability: KVM_CAP_PPC_MULTITCE +Architectures: ppc +Type: vm + +This capability means the kernel is capable of handling hypercalls +H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user +space. This significantly accelerates DMA operations for PPC KVM guests. +User space should expect that its handlers for these hypercalls +are not going to be called if user space previously registered LIOBN +in KVM (via KVM_CREATE_SPAPR_TCE or similar calls). + +In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest, +user space might have to advertise it for the guest. For example, +IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is +present in the "ibm,hypertas-functions" device-tree property. + +The hypercalls mentioned above may or may not be processed successfully +in the kernel based fast path. If they can not be handled by the kernel, +they will get passed on to user space. So user space still has to have +an implementation for these despite the in kernel acceleration. + +This capability is always enabled. + +4.98 KVM_CREATE_SPAPR_TCE_64 + +Capability: KVM_CAP_SPAPR_TCE_64 +Architectures: powerpc +Type: vm ioctl +Parameters: struct kvm_create_spapr_tce_64 (in) +Returns: file descriptor for manipulating the created TCE table + +This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit +windows, described in 4.62 KVM_CREATE_SPAPR_TCE + +This capability uses extended struct in ioctl interface: + +/* for KVM_CAP_SPAPR_TCE_64 */ +struct kvm_create_spapr_tce_64 { + __u64 liobn; + __u32 page_shift; + __u32 flags; + __u64 offset; /* in pages */ + __u64 size; /* in pages */ +}; + +The aim of extension is to support an additional bigger DMA window with +a variable page size. +KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift and +a bus offset of the corresponding DMA window, @size and @offset are numbers +of IOMMU pages. + +@flags are not used at the moment. + +The rest of functionality is identical to KVM_CREATE_SPAPR_TCE. + +4.98 KVM_REINJECT_CONTROL + +Capability: KVM_CAP_REINJECT_CONTROL +Architectures: x86 +Type: vm ioctl +Parameters: struct kvm_reinject_control (in) +Returns: 0 on success, + -EFAULT if struct kvm_reinject_control cannot be read, + -ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier. + +i8254 (PIT) has two modes, reinject and !reinject. The default is reinject, +where KVM queues elapsed i8254 ticks and monitors completion of interrupt from +vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its +interrupt whenever there isn't a pending interrupt from i8254. +!reinject mode injects an interrupt as soon as a tick arrives. + +struct kvm_reinject_control { + __u8 pit_reinject; + __u8 reserved[31]; +}; + +pit_reinject = 0 (!reinject mode) is recommended, unless running an old +operating system that uses the PIT for timing (e.g. Linux 2.4.x). + 5. The kvm_run structure ------------------------ @@ -3309,6 +3410,46 @@ Valid values for 'type' are: to ignore the request, or to gather VM memory core dump and/or reset/shutdown of the VM. + /* KVM_EXIT_IOAPIC_EOI */ + struct { + __u8 vector; + } eoi; + +Indicates that the VCPU's in-kernel local APIC received an EOI for a +level-triggered IOAPIC interrupt. This exit only triggers when the +IOAPIC is implemented in userspace (i.e. KVM_CAP_SPLIT_IRQCHIP is enabled); +the userspace IOAPIC should process the EOI and retrigger the interrupt if +it is still asserted. Vector is the LAPIC interrupt vector for which the +EOI was received. + + struct kvm_hyperv_exit { +#define KVM_EXIT_HYPERV_SYNIC 1 +#define KVM_EXIT_HYPERV_HCALL 2 + __u32 type; + union { + struct { + __u32 msr; + __u64 control; + __u64 evt_page; + __u64 msg_page; + } synic; + struct { + __u64 input; + __u64 result; + __u64 params[2]; + } hcall; + } u; + }; + /* KVM_EXIT_HYPERV */ + struct kvm_hyperv_exit hyperv; +Indicates that the VCPU exits into userspace to process some tasks +related to Hyper-V emulation. +Valid values for 'type' are: + KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about +Hyper-V SynIC state change. Notification is used to remap SynIC +event/message pages and to enable/disable SynIC messages/events processing +in userspace. + /* Fix the size of the union. */ char padding[256]; }; @@ -3627,6 +3768,26 @@ struct { KVM handlers should exit to userspace with rc = -EREMOTE. +7.5 KVM_CAP_SPLIT_IRQCHIP + +Architectures: x86 +Parameters: args[0] - number of routes reserved for userspace IOAPICs +Returns: 0 on success, -1 on error + +Create a local apic for each processor in the kernel. This can be used +instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the +IOAPIC and PIC (and also the PIT, even though this has to be enabled +separately). + +This capability also enables in kernel routing of interrupt requests; +when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type are +used in the IRQ routing table. The first args[0] MSI routes are reserved +for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes, +a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace. + +Fails if VCPU has already been created, or if the irqchip is already in the +kernel (i.e. KVM_CREATE_IRQCHIP has already been called). + 8. Other capabilities. ---------------------- @@ -3643,3 +3804,16 @@ available, means that that the kernel has an implementation of the H_RANDOM hypercall backed by a hardware random-number generator. If present, the kernel H_RANDOM handler can be enabled for guest use with the KVM_CAP_PPC_ENABLE_HCALL capability. + +8.2 KVM_CAP_HYPERV_SYNIC + +Architectures: x86 +This capability, if KVM_CHECK_EXTENSION indicates that it is +available, means that that the kernel has an implementation of the +Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is +used to support Windows Hyper-V based guest paravirt drivers(VMBus). + +In order to use SynIC, it has to be activated by setting this +capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this +will disable the use of APIC hardware virtualization even if supported +by the CPU, as it's incompatible with SynIC auto-EOI behavior. diff --git a/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt b/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt new file mode 100644 index 000000000000..38bca2835278 --- /dev/null +++ b/Documentation/virtual/kvm/arm/vgic-mapped-irqs.txt @@ -0,0 +1,187 @@ +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. diff --git a/Documentation/virtual/kvm/devices/arm-vgic.txt b/Documentation/virtual/kvm/devices/arm-vgic.txt index 3fb905429e8a..59541d49e15c 100644 --- a/Documentation/virtual/kvm/devices/arm-vgic.txt +++ b/Documentation/virtual/kvm/devices/arm-vgic.txt @@ -44,28 +44,29 @@ Groups: Attributes: The attr field of kvm_device_attr encodes two values: bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | - values: | reserved | cpu id | offset | + values: | reserved | vcpu_index | offset | All distributor regs are (rw, 32-bit) The offset is relative to the "Distributor base address" as defined in the GICv2 specs. Getting or setting such a register has the same effect as - reading or writing the register on the actual hardware from the cpu - specified with cpu id field. Note that most distributor fields are not - banked, but return the same value regardless of the cpu id used to access - the register. + reading or writing the register on the actual hardware from the cpu whose + index is specified with the vcpu_index field. Note that most distributor + fields are not banked, but return the same value regardless of the + vcpu_index used to access the register. Limitations: - Priorities are not implemented, and registers are RAZ/WI - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2. Errors: - -ENODEV: Getting or setting this register is not yet supported + -ENXIO: Getting or setting this register is not yet supported -EBUSY: One or more VCPUs are running + -EINVAL: Invalid vcpu_index supplied KVM_DEV_ARM_VGIC_GRP_CPU_REGS Attributes: The attr field of kvm_device_attr encodes two values: bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | - values: | reserved | cpu id | offset | + values: | reserved | vcpu_index | offset | All CPU interface regs are (rw, 32-bit) @@ -91,8 +92,9 @@ Groups: - Priorities are not implemented, and registers are RAZ/WI - Currently only implemented for KVM_DEV_TYPE_ARM_VGIC_V2. Errors: - -ENODEV: Getting or setting this register is not yet supported + -ENXIO: Getting or setting this register is not yet supported -EBUSY: One or more VCPUs are running + -EINVAL: Invalid vcpu_index supplied KVM_DEV_ARM_VGIC_GRP_NR_IRQS Attributes: diff --git a/Documentation/virtual/kvm/devices/s390_flic.txt b/Documentation/virtual/kvm/devices/s390_flic.txt index d1ad9d5cae46..e3e314cb83e8 100644 --- a/Documentation/virtual/kvm/devices/s390_flic.txt +++ b/Documentation/virtual/kvm/devices/s390_flic.txt @@ -88,6 +88,8 @@ struct kvm_s390_io_adapter_req { perform a gmap translation for the guest address provided in addr, pin a userspace page for the translated address and add it to the list of mappings + Note: A new mapping will be created unconditionally; therefore, + the calling code should avoid making duplicate mappings. KVM_S390_IO_ADAPTER_UNMAP release a userspace page for the translated address specified in addr diff --git a/Documentation/virtual/kvm/devices/vcpu.txt b/Documentation/virtual/kvm/devices/vcpu.txt new file mode 100644 index 000000000000..c04165868faf --- /dev/null +++ b/Documentation/virtual/kvm/devices/vcpu.txt @@ -0,0 +1,33 @@ +Generic vcpu interface +==================================== + +The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, +KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct +kvm_device_attr as other devices, but targets VCPU-wide settings and controls. + +The groups and attributes per virtual cpu, if any, are architecture specific. + +1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL +Architectures: ARM64 + +1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ +Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a + pointer to an int +Returns: -EBUSY: The PMU overflow interrupt is already set + -ENXIO: The overflow interrupt not set when attempting to get it + -ENODEV: PMUv3 not supported + -EINVAL: Invalid PMU overflow interrupt number supplied + +A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt +number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt +type must be same for each vcpu. As a PPI, the interrupt number is the same for +all vcpus, while as an SPI it must be a separate number per vcpu. + +1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT +Parameters: no additional parameter in kvm_device_attr.addr +Returns: -ENODEV: PMUv3 not supported + -ENXIO: PMUv3 not properly configured as required prior to calling this + attribute + -EBUSY: PMUv3 already initialized + +Request the initialization of the PMUv3. diff --git a/Documentation/virtual/kvm/devices/vm.txt b/Documentation/virtual/kvm/devices/vm.txt index 5542c4641a3c..a9ea8774a45f 100644 --- a/Documentation/virtual/kvm/devices/vm.txt +++ b/Documentation/virtual/kvm/devices/vm.txt @@ -37,7 +37,8 @@ Returns: -EFAULT if the given address is not accessible Allows userspace to query the actual limit and set a new limit for the maximum guest memory size. The limit will be rounded up to 2048 MB, 4096 GB, 8192 TB respectively, as this limit is governed by -the number of page table levels. +the number of page table levels. In the case that there is no limit we will set +the limit to KVM_S390_NO_MEM_LIMIT (U64_MAX). 2. GROUP: KVM_S390_VM_CPU_MODEL Architectures: s390 @@ -74,7 +75,7 @@ struct kvm_s390_vm_cpu_processor { KVM does not enforce or limit the cpu model data in any form. Take the information retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration -setups. Instruction interceptions triggered by additionally set facilitiy bits that +setups. Instruction interceptions triggered by additionally set facility bits that are not handled by KVM need to by imlemented in the VM driver code. Parameters: address of buffer to store/set the processor related cpu @@ -83,3 +84,55 @@ Returns: -EBUSY in case 1 or more vcpus are already activated (only in write -EFAULT if the given address is not accessible from kernel space -ENOMEM if not enough memory is available to process the ioctl 0 in case of success + +3. GROUP: KVM_S390_VM_TOD +Architectures: s390 + +3.1. ATTRIBUTE: KVM_S390_VM_TOD_HIGH + +Allows user space to set/get the TOD clock extension (u8). + +Parameters: address of a buffer in user space to store the data (u8) to +Returns: -EFAULT if the given address is not accessible from kernel space + -EINVAL if setting the TOD clock extension to != 0 is not supported + +3.2. ATTRIBUTE: KVM_S390_VM_TOD_LOW + +Allows user space to set/get bits 0-63 of the TOD clock register as defined in +the POP (u64). + +Parameters: address of a buffer in user space to store the data (u64) to +Returns: -EFAULT if the given address is not accessible from kernel space + +4. GROUP: KVM_S390_VM_CRYPTO +Architectures: s390 + +4.1. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_AES_KW (w/o) + +Allows user space to enable aes key wrapping, including generating a new +wrapping key. + +Parameters: none +Returns: 0 + +4.2. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_DEA_KW (w/o) + +Allows user space to enable dea key wrapping, including generating a new +wrapping key. + +Parameters: none +Returns: 0 + +4.3. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_AES_KW (w/o) + +Allows user space to disable aes key wrapping, clearing the wrapping key. + +Parameters: none +Returns: 0 + +4.4. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_DEA_KW (w/o) + +Allows user space to disable dea key wrapping, clearing the wrapping key. + +Parameters: none +Returns: 0 diff --git a/Documentation/virtual/kvm/locking.txt b/Documentation/virtual/kvm/locking.txt index d68af4dc3006..19f94a6b9bb0 100644 --- a/Documentation/virtual/kvm/locking.txt +++ b/Documentation/virtual/kvm/locking.txt @@ -166,3 +166,15 @@ Comment: The srcu read lock must be held while accessing memslots (e.g. MMIO/PIO address->device structure mapping (kvm->buses). The srcu index can be stored in kvm_vcpu->srcu_idx per vcpu if it is needed by multiple functions. + +Name: blocked_vcpu_on_cpu_lock +Type: spinlock_t +Arch: x86 +Protects: blocked_vcpu_on_cpu +Comment: This is a per-CPU lock and it is used for VT-d posted-interrupts. + When VT-d posted-interrupts is supported and the VM has assigned + devices, we put the blocked vCPU on the list blocked_vcpu_on_cpu + protected by blocked_vcpu_on_cpu_lock, when VT-d hardware issues + wakeup notification event since external interrupts from the + assigned devices happens, we will find the vCPU on the list to + wakeup. diff --git a/Documentation/virtual/kvm/mmu.txt b/Documentation/virtual/kvm/mmu.txt index 3a4d681c3e98..481b6a9c25d5 100644 --- a/Documentation/virtual/kvm/mmu.txt +++ b/Documentation/virtual/kvm/mmu.txt @@ -203,10 +203,10 @@ Shadow pages contain the following information: page cannot be destroyed. See role.invalid. parent_ptes: The reverse mapping for the pte/ptes pointing at this page's spt. If - parent_ptes bit 0 is zero, only one spte points at this pages and + parent_ptes bit 0 is zero, only one spte points at this page and parent_ptes points at this single spte, otherwise, there exists multiple sptes pointing at this page and (parent_ptes & ~0x1) points at a data - structure with a list of parent_ptes. + structure with a list of parent sptes. unsync: If true, then the translations in this page may not match the guest's translation. This is equivalent to the state of the tlb when a pte is @@ -358,7 +358,8 @@ In the first case there are two additional complications: - if CR4.SMEP is enabled: since we've turned the page into a kernel page, the kernel may now execute it. We handle this by also setting spte.nx. If we get a user fetch or read fault, we'll change spte.u=1 and - spte.nx=gpte.nx back. + spte.nx=gpte.nx back. For this to work, KVM forces EFER.NX to 1 when + shadow paging is in use. - if CR4.SMAP is disabled: since the page has been changed to a kernel page, it can not be reused when CR4.SMAP is enabled. We set CR4.SMAP && !CR0.WP into shadow page's role to avoid this case. Note, @@ -391,11 +392,11 @@ To instantiate a large spte, four constraints must be satisfied: write-protected pages - the guest page must be wholly contained by a single memory slot -To check the last two conditions, the mmu maintains a ->write_count set of +To check the last two conditions, the mmu maintains a ->disallow_lpage set of arrays for each memory slot and large page size. Every write protected page -causes its write_count to be incremented, thus preventing instantiation of +causes its disallow_lpage to be incremented, thus preventing instantiation of a large spte. The frames at the end of an unaligned memory slot have -artificially inflated ->write_counts so they can never be instantiated. +artificially inflated ->disallow_lpages so they can never be instantiated. Zapping all pages (page generation count) ========================================= diff --git a/Documentation/virtual/kvm/ppc-pv.txt b/Documentation/virtual/kvm/ppc-pv.txt index 319560646f32..e26115ce4258 100644 --- a/Documentation/virtual/kvm/ppc-pv.txt +++ b/Documentation/virtual/kvm/ppc-pv.txt @@ -110,7 +110,7 @@ Flags are passed to the host in the low 12 bits of the Effective Address. The following flags are currently available for a guest to expose: - MAGIC_PAGE_FLAG_NOT_MAPPED_NX Guest handles NX bits correclty wrt magic page + MAGIC_PAGE_FLAG_NOT_MAPPED_NX Guest handles NX bits correctly wrt magic page MSR bits ======== diff --git a/Documentation/vm/balance b/Documentation/vm/balance index c46e68cf9344..964595481af6 100644 --- a/Documentation/vm/balance +++ b/Documentation/vm/balance @@ -1,12 +1,14 @@ Started Jan 2000 by Kanoj Sarcar <kanoj@sgi.com> -Memory balancing is needed for non __GFP_WAIT as well as for non -__GFP_IO allocations. +Memory balancing is needed for !__GFP_ATOMIC and !__GFP_KSWAPD_RECLAIM as +well as for non __GFP_IO allocations. -There are two reasons to be requesting non __GFP_WAIT allocations: -the caller can not sleep (typically intr context), or does not want -to incur cost overheads of page stealing and possible swap io for -whatever reasons. +The first reason why a caller may avoid reclaim is that the caller can not +sleep due to holding a spinlock or is in interrupt context. The second may +be that the caller is willing to fail the allocation without incurring the +overhead of page reclaim. This may happen for opportunistic high-order +allocation requests that have order-0 fallback options. In such cases, +the caller may also wish to avoid waking kswapd. __GFP_IO allocation requests are made to prevent file system deadlocks. diff --git a/Documentation/vm/page_migration b/Documentation/vm/page_migration index 6513fe2d90b8..fea5c0864170 100644 --- a/Documentation/vm/page_migration +++ b/Documentation/vm/page_migration @@ -92,29 +92,26 @@ Steps: 2. Insure that writeback is complete. -3. Prep the new page that we want to move to. It is locked - and set to not being uptodate so that all accesses to the new - page immediately lock while the move is in progress. +3. Lock the new page that we want to move to. It is locked so that accesses to + this (not yet uptodate) page immediately lock while the move is in progress. -4. The new page is prepped with some settings from the old page so that - accesses to the new page will discover a page with the correct settings. - -5. All the page table references to the page are converted - to migration entries or dropped (nonlinear vmas). - This decrease the mapcount of a page. If the resulting - mapcount is not zero then we do not migrate the page. - All user space processes that attempt to access the page - will now wait on the page lock. +4. All the page table references to the page are converted to migration + entries. This decreases the mapcount of a page. If the resulting + mapcount is not zero then we do not migrate the page. All user space + processes that attempt to access the page will now wait on the page lock. -6. The radix tree lock is taken. This will cause all processes trying +5. The radix tree lock is taken. This will cause all processes trying to access the page via the mapping to block on the radix tree spinlock. -7. The refcount of the page is examined and we back out if references remain +6. The refcount of the page is examined and we back out if references remain otherwise we know that we are the only one referencing this page. -8. The radix tree is checked and if it does not contain the pointer to this +7. The radix tree is checked and if it does not contain the pointer to this page then we back out because someone else modified the radix tree. +8. The new page is prepped with some settings from the old page so that + accesses to the new page will discover a page with the correct settings. + 9. The radix tree is changed to point to the new page. 10. The reference count of the old page is dropped because the radix tree diff --git a/Documentation/vm/page_owner.txt b/Documentation/vm/page_owner.txt index 8f3ce9b3aa11..ffff1439076a 100644 --- a/Documentation/vm/page_owner.txt +++ b/Documentation/vm/page_owner.txt @@ -28,10 +28,11 @@ with page owner and page owner is disabled in runtime due to no enabling boot option, runtime overhead is marginal. If disabled in runtime, it doesn't require memory to store owner information, so there is no runtime memory overhead. And, page owner inserts just two unlikely branches into -the page allocator hotpath and if it returns false then allocation is -done like as the kernel without page owner. These two unlikely branches -would not affect to allocation performance. Following is the kernel's -code size change due to this facility. +the page allocator hotpath and if not enabled, then allocation is done +like as the kernel without page owner. These two unlikely branches should +not affect to allocation performance, especially if the static keys jump +label patching functionality is available. Following is the kernel's code +size change due to this facility. - Without page owner text data bss dec hex filename diff --git a/Documentation/vm/slub.txt b/Documentation/vm/slub.txt index b0c6d1bbb434..84652419bff2 100644 --- a/Documentation/vm/slub.txt +++ b/Documentation/vm/slub.txt @@ -8,7 +8,7 @@ SLUB can enable debugging only for selected slabs in order to avoid an impact on overall system performance which may make a bug more difficult to find. -In order to switch debugging on one can add a option "slub_debug" +In order to switch debugging on one can add an option "slub_debug" to the kernel command line. That will enable full debugging for all slabs. @@ -35,8 +35,8 @@ slub_debug=<Debug-Options>,<slab name> Enable options only for select slabs Possible debug options are - F Sanity checks on (enables SLAB_DEBUG_FREE. Sorry - SLAB legacy issues) + F Sanity checks on (enables SLAB_DEBUG_CONSISTENCY_CHECKS + Sorry SLAB legacy issues) Z Red zoning P Poisoning (object and padding) U User tracking (free and alloc) @@ -280,4 +280,63 @@ of other objects. slub_debug=FZ,dentry +Extended slabinfo mode and plotting +----------------------------------- + +The slabinfo tool has a special 'extended' ('-X') mode that includes: + - Slabcache Totals + - Slabs sorted by size (up to -N <num> slabs, default 1) + - Slabs sorted by loss (up to -N <num> slabs, default 1) + +Additionally, in this mode slabinfo does not dynamically scale sizes (G/M/K) +and reports everything in bytes (this functionality is also available to +other slabinfo modes via '-B' option) which makes reporting more precise and +accurate. Moreover, in some sense the `-X' mode also simplifies the analysis +of slabs' behaviour, because its output can be plotted using the +slabinfo-gnuplot.sh script. So it pushes the analysis from looking through +the numbers (tons of numbers) to something easier -- visual analysis. + +To generate plots: +a) collect slabinfo extended records, for example: + + while [ 1 ]; do slabinfo -X >> FOO_STATS; sleep 1; done + +b) pass stats file(-s) to slabinfo-gnuplot.sh script: + slabinfo-gnuplot.sh FOO_STATS [FOO_STATS2 .. FOO_STATSN] + +The slabinfo-gnuplot.sh script will pre-processes the collected records +and generates 3 png files (and 3 pre-processing cache files) per STATS +file: + - Slabcache Totals: FOO_STATS-totals.png + - Slabs sorted by size: FOO_STATS-slabs-by-size.png + - Slabs sorted by loss: FOO_STATS-slabs-by-loss.png + +Another use case, when slabinfo-gnuplot can be useful, is when you need +to compare slabs' behaviour "prior to" and "after" some code modification. +To help you out there, slabinfo-gnuplot.sh script can 'merge' the +`Slabcache Totals` sections from different measurements. To visually +compare N plots: + +a) Collect as many STATS1, STATS2, .. STATSN files as you need + while [ 1 ]; do slabinfo -X >> STATS<X>; sleep 1; done + +b) Pre-process those STATS files + slabinfo-gnuplot.sh STATS1 STATS2 .. STATSN + +c) Execute slabinfo-gnuplot.sh in '-t' mode, passing all of the +generated pre-processed *-totals + slabinfo-gnuplot.sh -t STATS1-totals STATS2-totals .. STATSN-totals + +This will produce a single plot (png file). + +Plots, expectedly, can be large so some fluctuations or small spikes +can go unnoticed. To deal with that, `slabinfo-gnuplot.sh' has two +options to 'zoom-in'/'zoom-out': + a) -s %d,%d overwrites the default image width and heigh + b) -r %d,%d specifies a range of samples to use (for example, + in `slabinfo -X >> FOO_STATS; sleep 1;' case, using + a "-r 40,60" range will plot only samples collected + between 40th and 60th seconds). + Christoph Lameter, May 30, 2007 +Sergey Senozhatsky, October 23, 2015 diff --git a/Documentation/vm/split_page_table_lock b/Documentation/vm/split_page_table_lock index 6dea4fd5c961..62842a857dab 100644 --- a/Documentation/vm/split_page_table_lock +++ b/Documentation/vm/split_page_table_lock @@ -54,8 +54,8 @@ everything required is done by pgtable_page_ctor() and pgtable_page_dtor(), which must be called on PTE table allocation / freeing. Make sure the architecture doesn't use slab allocator for page table -allocation: slab uses page->slab_cache and page->first_page for its pages. -These fields share storage with page->ptl. +allocation: slab uses page->slab_cache for its pages. +This field shares storage with page->ptl. PMD split lock only makes sense if you have more than two page table levels. diff --git a/Documentation/vm/transhuge.txt b/Documentation/vm/transhuge.txt index 8143b9e8373d..d9cb65cf5cfd 100644 --- a/Documentation/vm/transhuge.txt +++ b/Documentation/vm/transhuge.txt @@ -35,10 +35,10 @@ miss is going to run faster. == Design == -- "graceful fallback": mm components which don't have transparent - hugepage knowledge fall back to breaking a transparent hugepage and - working on the regular pages and their respective regular pmd/pte - mappings +- "graceful fallback": mm components which don't have transparent hugepage + knowledge fall back to breaking huge pmd mapping into table of ptes and, + if necessary, split a transparent hugepage. Therefore these components + can continue working on the regular pages or regular pte mappings. - if a hugepage allocation fails because of memory fragmentation, regular pages should be gracefully allocated instead and mixed in @@ -113,9 +113,26 @@ guaranteed, but it may be more likely in case the allocation is for a MADV_HUGEPAGE region. echo always >/sys/kernel/mm/transparent_hugepage/defrag +echo defer >/sys/kernel/mm/transparent_hugepage/defrag echo madvise >/sys/kernel/mm/transparent_hugepage/defrag echo never >/sys/kernel/mm/transparent_hugepage/defrag +"always" means that an application requesting THP will stall on allocation +failure and directly reclaim pages and compact memory in an effort to +allocate a THP immediately. This may be desirable for virtual machines +that benefit heavily from THP use and are willing to delay the VM start +to utilise them. + +"defer" means that an application will wake kswapd in the background +to reclaim pages and wake kcompact to compact memory so that THP is +available in the near future. It's the responsibility of khugepaged +to then install the THP pages later. + +"madvise" will enter direct reclaim like "always" but only for regions +that are have used madvise(MADV_HUGEPAGE). This is the default behaviour. + +"never" should be self-explanatory. + By default kernel tries to use huge zero page on read page fault. It's possible to disable huge zero page by writing 0 or enable it back by writing 1: @@ -170,6 +187,16 @@ A lower value leads to gain less thp performance. Value of max_ptes_none can waste cpu time very little, you can ignore it. +max_ptes_swap specifies how many pages can be brought in from +swap when collapsing a group of pages into a transparent huge page. + +/sys/kernel/mm/transparent_hugepage/khugepaged/max_ptes_swap + +A higher value can cause excessive swap IO and waste +memory. A lower value can prevent THPs from being +collapsed, resulting fewer pages being collapsed into +THPs, and lower memory access performance. + == Boot parameter == You can change the sysfs boot time defaults of Transparent Hugepage @@ -211,9 +238,23 @@ thp_collapse_alloc_failed is incremented if khugepaged found a range of pages that should be collapsed into one huge page but failed the allocation. -thp_split is incremented every time a huge page is split into base +thp_split_page is incremented every time a huge page is split into base pages. This can happen for a variety of reasons but a common reason is that a huge page is old and is being reclaimed. + This action implies splitting all PMD the page mapped with. + +thp_split_page_failed is is incremented if kernel fails to split huge + page. This can happen if the page was pinned by somebody. + +thp_deferred_split_page is incremented when a huge page is put onto split + queue. This happens when a huge page is partially unmapped and + splitting it would free up some memory. Pages on split queue are + going to be split under memory pressure. + +thp_split_pmd is incremented every time a PMD split into table of PTEs. + This can happen, for instance, when application calls mprotect() or + munmap() on part of huge page. It doesn't split huge page, only + page table entry. thp_zero_page_alloc is incremented every time a huge zero page is successfully allocated. It includes allocations which where @@ -264,10 +305,8 @@ is complete, so they won't ever notice the fact the page is huge. But if any driver is going to mangle over the page structure of the tail page (like for checking page->mapping or other bits that are relevant for the head page and not the tail page), it should be updated to jump -to check head page instead (while serializing properly against -split_huge_page() to avoid the head and tail pages to disappear from -under it, see the futex code to see an example of that, hugetlbfs also -needed special handling in futex code for similar reasons). +to check head page instead. Taking reference on any head/tail page would +prevent page from being split by anyone. NOTE: these aren't new constraints to the GUP API, and they match the same constrains that applies to hugetlbfs too, so any driver capable @@ -302,9 +341,9 @@ unaffected. libhugetlbfs will also work fine as usual. == Graceful fallback == Code walking pagetables but unware about huge pmds can simply call -split_huge_page_pmd(vma, addr, pmd) where the pmd is the one returned by +split_huge_pmd(vma, pmd, addr) where the pmd is the one returned by pmd_offset. It's trivial to make the code transparent hugepage aware -by just grepping for "pmd_offset" and adding split_huge_page_pmd where +by just grepping for "pmd_offset" and adding split_huge_pmd where missing after pmd_offset returns the pmd. Thanks to the graceful fallback design, with a one liner change, you can avoid to write hundred if not thousand of lines of complex code to make your code @@ -313,7 +352,8 @@ hugepage aware. If you're not walking pagetables but you run into a physical hugepage but you can't handle it natively in your code, you can split it by calling split_huge_page(page). This is what the Linux VM does before -it tries to swapout the hugepage for example. +it tries to swapout the hugepage for example. split_huge_page() can fail +if the page is pinned and you must handle this correctly. Example to make mremap.c transparent hugepage aware with a one liner change: @@ -325,14 +365,14 @@ diff --git a/mm/mremap.c b/mm/mremap.c return NULL; pmd = pmd_offset(pud, addr); -+ split_huge_page_pmd(vma, addr, pmd); ++ split_huge_pmd(vma, pmd, addr); if (pmd_none_or_clear_bad(pmd)) return NULL; == Locking in hugepage aware code == We want as much code as possible hugepage aware, as calling -split_huge_page() or split_huge_page_pmd() has a cost. +split_huge_page() or split_huge_pmd() has a cost. To make pagetable walks huge pmd aware, all you need to do is to call pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the @@ -341,47 +381,80 @@ created from under you by khugepaged (khugepaged collapse_huge_page takes the mmap_sem in write mode in addition to the anon_vma lock). If pmd_trans_huge returns false, you just fallback in the old code paths. If instead pmd_trans_huge returns true, you have to take the -mm->page_table_lock and re-run pmd_trans_huge. Taking the -page_table_lock will prevent the huge pmd to be converted into a -regular pmd from under you (split_huge_page can run in parallel to the +page table lock (pmd_lock()) and re-run pmd_trans_huge. Taking the +page table lock will prevent the huge pmd to be converted into a +regular pmd from under you (split_huge_pmd can run in parallel to the pagetable walk). If the second pmd_trans_huge returns false, you -should just drop the page_table_lock and fallback to the old code as -before. Otherwise you should run pmd_trans_splitting on the pmd. In -case pmd_trans_splitting returns true, it means split_huge_page is -already in the middle of splitting the page. So if pmd_trans_splitting -returns true it's enough to drop the page_table_lock and call -wait_split_huge_page and then fallback the old code paths. You are -guaranteed by the time wait_split_huge_page returns, the pmd isn't -huge anymore. If pmd_trans_splitting returns false, you can proceed to -process the huge pmd and the hugepage natively. Once finished you can -drop the page_table_lock. - -== compound_lock, get_user_pages and put_page == +should just drop the page table lock and fallback to the old code as +before. Otherwise you can proceed to process the huge pmd and the +hugepage natively. Once finished you can drop the page table lock. + +== Refcounts and transparent huge pages == + +Refcounting on THP is mostly consistent with refcounting on other compound +pages: + + - get_page()/put_page() and GUP operate in head page's ->_count. + + - ->_count in tail pages is always zero: get_page_unless_zero() never + succeed on tail pages. + + - map/unmap of the pages with PTE entry increment/decrement ->_mapcount + on relevant sub-page of the compound page. + + - map/unmap of the whole compound page accounted in compound_mapcount + (stored in first tail page). + +PageDoubleMap() indicates that ->_mapcount in all subpages is offset up by one. +This additional reference is required to get race-free detection of unmap of +subpages when we have them mapped with both PMDs and PTEs. + +This is optimization required to lower overhead of per-subpage mapcount +tracking. The alternative is alter ->_mapcount in all subpages on each +map/unmap of the whole compound page. + +We set PG_double_map when a PMD of the page got split for the first time, +but still have PMD mapping. The addtional references go away with last +compound_mapcount. split_huge_page internally has to distribute the refcounts in the head -page to the tail pages before clearing all PG_head/tail bits from the -page structures. It can do that easily for refcounts taken by huge pmd -mappings. But the GUI API as created by hugetlbfs (that returns head -and tail pages if running get_user_pages on an address backed by any -hugepage), requires the refcount to be accounted on the tail pages and -not only in the head pages, if we want to be able to run -split_huge_page while there are gup pins established on any tail -page. Failure to be able to run split_huge_page if there's any gup pin -on any tail page, would mean having to split all hugepages upfront in -get_user_pages which is unacceptable as too many gup users are -performance critical and they must work natively on hugepages like -they work natively on hugetlbfs already (hugetlbfs is simpler because -hugetlbfs pages cannot be split so there wouldn't be requirement of -accounting the pins on the tail pages for hugetlbfs). If we wouldn't -account the gup refcounts on the tail pages during gup, we won't know -anymore which tail page is pinned by gup and which is not while we run -split_huge_page. But we still have to add the gup pin to the head page -too, to know when we can free the compound page in case it's never -split during its lifetime. That requires changing not just -get_page, but put_page as well so that when put_page runs on a tail -page (and only on a tail page) it will find its respective head page, -and then it will decrease the head page refcount in addition to the -tail page refcount. To obtain a head page reliably and to decrease its -refcount without race conditions, put_page has to serialize against -__split_huge_page_refcount using a special per-page lock called -compound_lock. +page to the tail pages before clearing all PG_head/tail bits from the page +structures. It can be done easily for refcounts taken by page table +entries. But we don't have enough information on how to distribute any +additional pins (i.e. from get_user_pages). split_huge_page() fails any +requests to split pinned huge page: it expects page count to be equal to +sum of mapcount of all sub-pages plus one (split_huge_page caller must +have reference for head page). + +split_huge_page uses migration entries to stabilize page->_count and +page->_mapcount. + +We safe against physical memory scanners too: the only legitimate way +scanner can get reference to a page is get_page_unless_zero(). + +All tail pages has zero ->_count until atomic_add(). It prevent scanner +from geting reference to tail page up to the point. After the atomic_add() +we don't care about ->_count value. We already known how many references +with should uncharge from head page. + +For head page get_page_unless_zero() will succeed and we don't mind. It's +clear where reference should go after split: it will stay on head page. + +Note that split_huge_pmd() doesn't have any limitation on refcounting: +pmd can be split at any point and never fails. + +== Partial unmap and deferred_split_huge_page() == + +Unmapping part of THP (with munmap() or other way) is not going to free +memory immediately. Instead, we detect that a subpage of THP is not in use +in page_remove_rmap() and queue the THP for splitting if memory pressure +comes. Splitting will free up unused subpages. + +Splitting the page right away is not an option due to locking context in +the place where we can detect partial unmap. It's also might be +counterproductive since in many cases partial unmap unmap happens during +exit(2) if an THP crosses VMA boundary. + +Function deferred_split_huge_page() is used to queue page for splitting. +The splitting itself will happen when we get memory pressure via shrinker +interface. diff --git a/Documentation/vm/unevictable-lru.txt b/Documentation/vm/unevictable-lru.txt index 32ee3a67dba2..fa3b527086fa 100644 --- a/Documentation/vm/unevictable-lru.txt +++ b/Documentation/vm/unevictable-lru.txt @@ -531,83 +531,20 @@ map. try_to_unmap() is always called, by either vmscan for reclaim or for page migration, with the argument page locked and isolated from the LRU. Separate -functions handle anonymous and mapped file pages, as these types of pages have -different reverse map mechanisms. - - (*) try_to_unmap_anon() - - To unmap anonymous pages, each VMA in the list anchored in the anon_vma - must be visited - at least until a VM_LOCKED VMA is encountered. If the - page is being unmapped for migration, VM_LOCKED VMAs do not stop the - process because mlocked pages are migratable. However, for reclaim, if - the page is mapped into a VM_LOCKED VMA, the scan stops. - - try_to_unmap_anon() attempts to acquire in read mode the mmap semaphore of - the mm_struct to which the VMA belongs. If this is successful, it will - mlock the page via mlock_vma_page() - we wouldn't have gotten to - try_to_unmap_anon() if the page were already mlocked - and will return - SWAP_MLOCK, indicating that the page is unevictable. - - If the mmap semaphore cannot be acquired, we are not sure whether the page - is really unevictable or not. In this case, try_to_unmap_anon() will - return SWAP_AGAIN. - - (*) try_to_unmap_file() - linear mappings - - Unmapping of a mapped file page works the same as for anonymous mappings, - except that the scan visits all VMAs that map the page's index/page offset - in the page's mapping's reverse map priority search tree. It also visits - each VMA in the page's mapping's non-linear list, if the list is - non-empty. - - As for anonymous pages, on encountering a VM_LOCKED VMA for a mapped file - page, try_to_unmap_file() will attempt to acquire the associated - mm_struct's mmap semaphore to mlock the page, returning SWAP_MLOCK if this - is successful, and SWAP_AGAIN, if not. - - (*) try_to_unmap_file() - non-linear mappings - - If a page's mapping contains a non-empty non-linear mapping VMA list, then - try_to_un{map|lock}() must also visit each VMA in that list to determine - whether the page is mapped in a VM_LOCKED VMA. Again, the scan must visit - all VMAs in the non-linear list to ensure that the pages is not/should not - be mlocked. - - If a VM_LOCKED VMA is found in the list, the scan could terminate. - However, there is no easy way to determine whether the page is actually - mapped in a given VMA - either for unmapping or testing whether the - VM_LOCKED VMA actually pins the page. - - try_to_unmap_file() handles non-linear mappings by scanning a certain - number of pages - a "cluster" - in each non-linear VMA associated with the - page's mapping, for each file mapped page that vmscan tries to unmap. If - this happens to unmap the page we're trying to unmap, try_to_unmap() will - notice this on return (page_mapcount(page) will be 0) and return - SWAP_SUCCESS. Otherwise, it will return SWAP_AGAIN, causing vmscan to - recirculate this page. We take advantage of the cluster scan in - try_to_unmap_cluster() as follows: - - For each non-linear VMA, try_to_unmap_cluster() attempts to acquire the - mmap semaphore of the associated mm_struct for read without blocking. - - If this attempt is successful and the VMA is VM_LOCKED, - try_to_unmap_cluster() will retain the mmap semaphore for the scan; - otherwise it drops it here. - - Then, for each page in the cluster, if we're holding the mmap semaphore - for a locked VMA, try_to_unmap_cluster() calls mlock_vma_page() to - mlock the page. This call is a no-op if the page is already locked, - but will mlock any pages in the non-linear mapping that happen to be - unlocked. - - If one of the pages so mlocked is the page passed in to try_to_unmap(), - try_to_unmap_cluster() will return SWAP_MLOCK, rather than the default - SWAP_AGAIN. This will allow vmscan to cull the page, rather than - recirculating it on the inactive list. - - Again, if try_to_unmap_cluster() cannot acquire the VMA's mmap sem, it - returns SWAP_AGAIN, indicating that the page is mapped by a VM_LOCKED - VMA, but couldn't be mlocked. +functions handle anonymous and mapped file and KSM pages, as these types of +pages have different reverse map lookup mechanisms, with different locking. +In each case, whether rmap_walk_anon() or rmap_walk_file() or rmap_walk_ksm(), +it will call try_to_unmap_one() for every VMA which might contain the page. + +When trying to reclaim, if try_to_unmap_one() finds the page in a VM_LOCKED +VMA, it will then mlock the page via mlock_vma_page() instead of unmapping it, +and return SWAP_MLOCK to indicate that the page is unevictable: and the scan +stops there. + +mlock_vma_page() is called while holding the page table's lock (in addition +to the page lock, and the rmap lock): to serialize against concurrent mlock or +munlock or munmap system calls, mm teardown (munlock_vma_pages_all), reclaim, +holepunching, and truncation of file pages and their anonymous COWed pages. try_to_munlock() REVERSE MAP SCAN @@ -623,29 +560,15 @@ all PTEs from the page. For this purpose, the unevictable/mlock infrastructure introduced a variant of try_to_unmap() called try_to_munlock(). try_to_munlock() calls the same functions as try_to_unmap() for anonymous and -mapped file pages with an additional argument specifying unlock versus unmap +mapped file and KSM pages with a flag argument specifying unlock versus unmap processing. Again, these functions walk the respective reverse maps looking -for VM_LOCKED VMAs. When such a VMA is found for anonymous pages and file -pages mapped in linear VMAs, as in the try_to_unmap() case, the functions -attempt to acquire the associated mmap semaphore, mlock the page via -mlock_vma_page() and return SWAP_MLOCK. This effectively undoes the -pre-clearing of the page's PG_mlocked done by munlock_vma_page. - -If try_to_unmap() is unable to acquire a VM_LOCKED VMA's associated mmap -semaphore, it will return SWAP_AGAIN. This will allow shrink_page_list() to -recycle the page on the inactive list and hope that it has better luck with the -page next time. - -For file pages mapped into non-linear VMAs, the try_to_munlock() logic works -slightly differently. On encountering a VM_LOCKED non-linear VMA that might -map the page, try_to_munlock() returns SWAP_AGAIN without actually mlocking the -page. munlock_vma_page() will just leave the page unlocked and let vmscan deal -with it - the usual fallback position. +for VM_LOCKED VMAs. When such a VMA is found, as in the try_to_unmap() case, +the functions mlock the page via mlock_vma_page() and return SWAP_MLOCK. This +undoes the pre-clearing of the page's PG_mlocked done by munlock_vma_page. Note that try_to_munlock()'s reverse map walk must visit every VMA in a page's reverse map to determine that a page is NOT mapped into any VM_LOCKED VMA. -However, the scan can terminate when it encounters a VM_LOCKED VMA and can -successfully acquire the VMA's mmap semaphore for read and mlock the page. +However, the scan can terminate when it encounters a VM_LOCKED VMA. Although try_to_munlock() might be called a great many times when munlocking a large region or tearing down a large address space that has been mlocked via mlockall(), overall this is a fairly rare event. @@ -673,11 +596,6 @@ Some examples of these unevictable pages on the LRU lists are: (3) mlocked pages that could not be isolated from the LRU and moved to the unevictable list in mlock_vma_page(). - (4) Pages mapped into multiple VM_LOCKED VMAs, but try_to_munlock() couldn't - acquire the VMA's mmap semaphore to test the flags and set PageMlocked. - munlock_vma_page() was forced to let the page back on to the normal LRU - list for vmscan to handle. - shrink_inactive_list() also diverts any unevictable pages that it finds on the inactive lists to the appropriate zone's unevictable list. diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq index 884dc284b215..234522709a5f 100644 --- a/Documentation/w1/masters/omap-hdq +++ b/Documentation/w1/masters/omap-hdq @@ -44,3 +44,9 @@ e.g: insmod omap_hdq.ko W1_ID=2 inamod w1_bq27000.ko F_ID=2 +The driver also supports 1-wire mode. In this mode, there is no need to +pass slave ID as parameter. The driver will auto-detect slaves connected +to the bus using SEARCH_ROM procedure. 1-wire mode can be selected by +setting "ti,mode" property to "1w" in DT (see +Documentation/devicetree/bindings/w1/omap-hdq.txt for more details). +By default driver is in HDQ mode. diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.txt index d8b0d3367706..55120a055a14 100644 --- a/Documentation/watchdog/watchdog-kernel-api.txt +++ b/Documentation/watchdog/watchdog-kernel-api.txt @@ -44,17 +44,18 @@ The watchdog device structure looks like this: struct watchdog_device { int id; - struct cdev cdev; - struct device *dev; struct device *parent; + const struct attribute_group **groups; const struct watchdog_info *info; const struct watchdog_ops *ops; unsigned int bootstatus; unsigned int timeout; unsigned int min_timeout; unsigned int max_timeout; + struct notifier_block reboot_nb; + struct notifier_block restart_nb; void *driver_data; - struct mutex lock; + struct watchdog_core_data *wd_data; unsigned long status; struct list_head deferred; }; @@ -64,27 +65,32 @@ It contains following fields: /dev/watchdog0 cdev (dynamic major, minor 0) as well as the old /dev/watchdog miscdev. The id is set automatically when calling watchdog_register_device. -* cdev: cdev for the dynamic /dev/watchdog<id> device nodes. This - field is also populated by watchdog_register_device. -* dev: device under the watchdog class (created by watchdog_register_device). * parent: set this to the parent device (or NULL) before calling watchdog_register_device. +* groups: List of sysfs attribute groups to create when creating the watchdog + device. * info: a pointer to a watchdog_info structure. This structure gives some additional information about the watchdog timer itself. (Like it's unique name) * ops: a pointer to the list of watchdog operations that the watchdog supports. * timeout: the watchdog timer's timeout value (in seconds). * min_timeout: the watchdog timer's minimum timeout value (in seconds). * max_timeout: the watchdog timer's maximum timeout value (in seconds). +* reboot_nb: notifier block that is registered for reboot notifications, for + internal use only. If the driver calls watchdog_stop_on_reboot, watchdog core + will stop the watchdog on such notifications. +* restart_nb: notifier block that is registered for machine restart, for + internal use only. If a watchdog is capable of restarting the machine, it + should define ops->restart. Priority can be changed through + watchdog_set_restart_priority. * bootstatus: status of the device after booting (reported with watchdog WDIOF_* status bits). * driver_data: a pointer to the drivers private data of a watchdog device. This data should only be accessed via the watchdog_set_drvdata and watchdog_get_drvdata routines. -* lock: Mutex for WatchDog Timer Driver Core internal use only. +* wd_data: a pointer to watchdog core internal data. * status: this field contains a number of status bits that give extra information about the status of the device (Like: is the watchdog timer - running/active, is the nowayout bit set, is the device opened via - the /dev/watchdog interface or not, ...). + running/active, or is the nowayout bit set). * deferred: entry in wtd_deferred_reg_list which is used to register early initialized watchdogs. @@ -100,8 +106,9 @@ struct watchdog_ops { unsigned int (*status)(struct watchdog_device *); int (*set_timeout)(struct watchdog_device *, unsigned int); unsigned int (*get_timeleft)(struct watchdog_device *); - void (*ref)(struct watchdog_device *); - void (*unref)(struct watchdog_device *); + int (*restart)(struct watchdog_device *); + void (*ref)(struct watchdog_device *) __deprecated; + void (*unref)(struct watchdog_device *) __deprecated; long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long); }; @@ -110,20 +117,6 @@ driver's operations. This module owner will be used to lock the module when the watchdog is active. (This to avoid a system crash when you unload the module and /dev/watchdog is still open). -If the watchdog_device struct is dynamically allocated, just locking the module -is not enough and a driver also needs to define the ref and unref operations to -ensure the structure holding the watchdog_device does not go away. - -The simplest (and usually sufficient) implementation of this is to: -1) Add a kref struct to the same structure which is holding the watchdog_device -2) Define a release callback for the kref which frees the struct holding both -3) Call kref_init on this kref *before* calling watchdog_register_device() -4) Define a ref operation calling kref_get on this kref -5) Define a unref operation calling kref_put on this kref -6) When it is time to cleanup: - * Do not kfree() the struct holding both, the last kref_put will do this! - * *After* calling watchdog_unregister_device() call kref_put on the kref - Some operations are mandatory and some are optional. The mandatory operations are: * start: this is a pointer to the routine that starts the watchdog timer @@ -164,34 +157,23 @@ they are supported. These optional routines/operations are: (Note: the WDIOF_SETTIMEOUT needs to be set in the options field of the watchdog's info structure). * get_timeleft: this routines returns the time that's left before a reset. -* ref: the operation that calls kref_get on the kref of a dynamically - allocated watchdog_device struct. -* unref: the operation that calls kref_put on the kref of a dynamically - allocated watchdog_device struct. +* restart: this routine restarts the machine. It returns 0 on success or a + negative errno code for failure. * ioctl: if this routine is present then it will be called first before we do our own internal ioctl call handling. This routine should return -ENOIOCTLCMD if a command is not supported. The parameters that are passed to the ioctl call are: watchdog_device, cmd and arg. +The 'ref' and 'unref' operations are no longer used and deprecated. + The status bits should (preferably) be set with the set_bit and clear_bit alike bit-operations. The status bits that are defined are: * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device is active or not. When the watchdog is active after booting, then you should set this status bit (Note: when you register the watchdog timer device with this bit set, then opening /dev/watchdog will skip the start operation) -* WDOG_DEV_OPEN: this status bit shows whether or not the watchdog device - was opened via /dev/watchdog. - (This bit should only be used by the WatchDog Timer Driver Core). -* WDOG_ALLOW_RELEASE: this bit stores whether or not the magic close character - has been sent (so that we can support the magic close feature). - (This bit should only be used by the WatchDog Timer Driver Core). * WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog. If this bit is set then the watchdog timer will not be able to stop. -* WDOG_UNREGISTERED: this bit gets set by the WatchDog Timer Driver Core - after calling watchdog_unregister_device, and then checked before calling - any watchdog_ops, so that you can be sure that no operations (other then - unref) will get called after unregister, even if userspace still holds a - reference to /dev/watchdog To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog timer device) you can either: @@ -231,3 +213,18 @@ the device tree (if the module timeout parameter is invalid). Best practice is to set the default timeout value as timeout value in the watchdog_device and then use this function to set the user "preferred" timeout value. This routine returns zero on success and a negative errno code for failure. + +To disable the watchdog on reboot, the user must call the following helper: + +static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd); + +To change the priority of the restart handler the following helper should be +used: + +void watchdog_set_restart_priority(struct watchdog_device *wdd, int priority); + +User should follow the following guidelines for setting the priority: +* 0: should be called in last resort, has limited restart capabilities +* 128: default restart handler, use if no other handler is expected to be + available, and/or if restart is sufficient to restart the entire system +* 255: highest priority, will preempt all other restart handlers diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index 9f9ec9f76039..4e4b6f10d841 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -400,3 +400,7 @@ wm8350_wdt: nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- +sun4v_wdt: +timeout_ms: Watchdog timeout in milliseconds 1..180000, default=60000) +nowayout: Watchdog cannot be stopped once started +------------------------------------------------- diff --git a/Documentation/x86/early-microcode.txt b/Documentation/x86/early-microcode.txt index d62bea6796da..c956d99cf1de 100644 --- a/Documentation/x86/early-microcode.txt +++ b/Documentation/x86/early-microcode.txt @@ -40,3 +40,28 @@ cp ../microcode.bin kernel/x86/microcode/GenuineIntel.bin (or AuthenticAMD.bin) find . | cpio -o -H newc >../ucode.cpio cd .. cat ucode.cpio /boot/initrd-3.5.0.img >/boot/initrd-3.5.0.ucode.img + +Builtin microcode +================= + +We can also load builtin microcode supplied through the regular firmware +builtin method CONFIG_FIRMWARE_IN_KERNEL. 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" + +This basically means, you have the following tree structure locally: + +/lib/firmware/ +|-- amd-ucode +... +| |-- microcode_amd_fam15h.bin +... +|-- intel-ucode +... +| |-- 06-3a-09 +... + +so that the build system can find those files and integrate them into +the final kernel image. The early loader finds them and applies them. diff --git a/Documentation/x86/exception-tables.txt b/Documentation/x86/exception-tables.txt index 32901aa36f0a..e396bcd8d830 100644 --- a/Documentation/x86/exception-tables.txt +++ b/Documentation/x86/exception-tables.txt @@ -290,3 +290,38 @@ Due to the way that the exception table is built and needs to be ordered, only use exceptions for code in the .text section. Any other section will cause the exception table to not be sorted correctly, and the exceptions will fail. + +Things changed when 64-bit support was added to x86 Linux. Rather than +double the size of the exception table by expanding the two entries +from 32-bits to 64 bits, a clever trick was used to store addresses +as relative offsets from the table itself. The assembly code changed +from: + .long 1b,3b +to: + .long (from) - . + .long (to) - . + +and the C-code that uses these values converts back to absolute addresses +like this: + + ex_insn_addr(const struct exception_table_entry *x) + { + return (unsigned long)&x->insn + x->insn; + } + +In v4.6 the exception table entry was expanded with a new field "handler". +This is also 32-bits wide and contains a third relative function +pointer which points to one of: + +1) int ex_handler_default(const struct exception_table_entry *fixup) + This is legacy case that just jumps to the fixup code +2) int ex_handler_fault(const struct exception_table_entry *fixup) + This case provides the fault number of the trap that occurred at + entry->insn. It is used to distinguish page faults from machine + check. +3) int ex_handler_ext(const struct exception_table_entry *fixup) + This case is used for uaccess_err ... we need to set a flag + in the task structure. Before the handler functions existed this + case was handled by adding a large offset to the fixup to tag + it as special. +More functions can easily be added. diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt index 68ed3114c363..0965a71f9942 100644 --- a/Documentation/x86/x86_64/boot-options.txt +++ b/Documentation/x86/x86_64/boot-options.txt @@ -60,6 +60,8 @@ Machine check threshold to 1. Enabling this may make memory predictive failure analysis less effective if the bios sets thresholds for memory errors since we will not see details for all errors. + mce=recovery + Force-enable recoverable machine check code paths nomce (for compatibility with i386): same as mce=off diff --git a/Documentation/zh_CN/arm64/booting.txt b/Documentation/zh_CN/arm64/booting.txt index 7cd36af11e71..1145bf864082 100644 --- a/Documentation/zh_CN/arm64/booting.txt +++ b/Documentation/zh_CN/arm64/booting.txt @@ -6,8 +6,9 @@ communicating in English you can also ask the Chinese maintainer for help. Contact the Chinese maintainer if this translation is outdated or if there is a problem with the translation. -Maintainer: Will Deacon <will.deacon@arm.com> -Chinese maintainer: Fu Wei <wefu@redhat.com> +M: Will Deacon <will.deacon@arm.com> +zh_CN: Fu Wei <wefu@redhat.com> +C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 --------------------------------------------------------------------- Documentation/arm64/booting.txt 的中文翻译 @@ -15,12 +16,11 @@ Documentation/arm64/booting.txt 的中文翻译 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 译存在问题，请联系中文版维护者。 -本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 - 英文版维护者： Will Deacon <will.deacon@arm.com> 中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> 中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> 中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> +本文翻译提交时的 Git 检出点为： 1926e54f115725a9248d0c4c65c22acaf94de4c4 以下为正文 --------------------------------------------------------------------- @@ -33,9 +33,9 @@ Documentation/arm64/booting.txt 的中文翻译 本文档基于 Russell King 的 ARM 启动文档，且适用于所有公开发布的 AArch64 Linux 内核代码。 -AArch64 异常模型由多个异常级别（EL0 - EL3）组成，对于 EL0 和 EL1 -异常级有对应的安全和非安全模式。EL2 是系统管理级，且仅存在于 -非安全模式下。EL3 是最高特权级，且仅存在于安全模式下。 +AArch64 异常模型由多个异常级（EL0 - EL3）组成，对于 EL0 和 EL1 异常级 +有对应的安全和非安全模式。EL2 是系统管理级，且仅存在于非安全模式下。 +EL3 是最高特权级，且仅存在于安全模式下。 基于本文档的目的，我们将简单地使用‘引导装载程序’（‘boot loader’） 这个术语来定义在将控制权交给 Linux 内核前 CPU 上执行的所有软件。 @@ -56,9 +56,9 @@ AArch64 异常模型由多个异常级别（EL0 - EL3）组成，对于 EL0 和 必要性: 强制 引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 -这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有 -RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序 -设计者想到的匹配方法。） +这个操作的执行方式因设备而异。（它可能使用内部算法来自动定位和计算所有 +RAM，或可能使用对这个设备已知的 RAM 信息，还可能是引导装载程序设计者 +想到的任何合适的方法。） 2、设置设备树数据 @@ -66,10 +66,12 @@ RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何 必要性: 强制 -设备树数据块（dtb）必须 8 字节对齐，并位于从内核映像起始算起第一个 512MB -内，且不得跨越 2MB 对齐边界。这使得内核可以通过初始页表中的单个节描述符来 -映射此数据块。 +设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树 +数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意 +特定属性被映射的 2MB 区域内。 +注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下 +text_offset 字节处算起第一个 512MB 内。 3、解压内核映像 ------------- @@ -78,7 +80,7 @@ RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何 AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内核映像文件 （比如 Image.gz），则需要通过引导装载程序（使用 gzip 等）来进行解压。 -若引导装载程序没有实现这个需求，就要使用非压缩内核映像文件。 +若引导装载程序没有实现这个功能，就要使用非压缩内核映像文件。 4、调用内核映像 @@ -97,7 +99,7 @@ AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内 u64 res3 = 0; /* 保留 */ u64 res4 = 0; /* 保留 */ u32 magic = 0x644d5241; /* 魔数, 小端, "ARM\x64" */ - u32 res5; /* 保留 （用于 PE COFF 偏移） */ + u32 res5; /* 保留 （用于 PE COFF 偏移） */ 映像头注释： @@ -107,26 +109,36 @@ AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内 - code0/code1 负责跳转到 stext. - 当通过 EFI 启动时， 最初 code0/code1 被跳过。 - res5 是到 PE 文件头的偏移，而 PE 文件头含有 EFI 的启动入口点 （efi_stub_entry）。 - 当 stub 代码完成了它的使命，它会跳转到 code0 继续正常的启动流程。 + res5 是到 PE 文件头的偏移，而 PE 文件头含有 EFI 的启动入口点 + （efi_stub_entry）。当 stub 代码完成了它的使命，它会跳转到 code0 + 继续正常的启动流程。 - v3.17 之前，未明确指定 text_offset 的字节序。此时，image_size 为零， 且 text_offset 依照内核字节序为 0x80000。 - 当 image_size 非零，text_offset 为小端模式且是有效值，应被引导加载程序使用。 - 当 image_size 为零，text_offset 可假定为 0x80000。 + 当 image_size 非零，text_offset 为小端模式且是有效值，应被引导加载 + 程序使用。当 image_size 为零，text_offset 可假定为 0x80000。 - flags 域 (v3.17 引入) 为 64 位小端模式，其编码如下： 位 0: 内核字节序。 1 表示大端模式，0 表示小端模式。 - 位 1-63: 保留。 - -- 当 image_size 为零时，引导装载程序应该试图在内核映像末尾之后尽可能多地保留空闲内存 - 供内核直接使用。对内存空间的需求量因所选定的内核特性而异, 且无实际限制。 - -内核映像必须被放置在靠近可用系统内存起始的 2MB 对齐为基址的 text_offset 字节处，并从那里被调用。 -当前，对 Linux 来说在此基址以下的内存是无法使用的，因此强烈建议将系统内存的起始作为这个基址。 -从映像起始地址算起，最少必须为内核释放出 image_size 字节的空间。 - -任何提供给内核的内存（甚至在 2MB 对齐的基地址之前），若未从内核中标记为保留 + 位 1-2: 内核页大小。 + 0 - 未指定。 + 1 - 4K + 2 - 16K + 3 - 64K + 位 3-63: 保留。 + +- 当 image_size 为零时，引导装载程序应试图在内核映像末尾之后尽可能 + 多地保留空闲内存供内核直接使用。对内存空间的需求量因所选定的内核 + 特性而异, 并无实际限制。 + +内核映像必须被放置在靠近可用系统内存起始的 2MB 对齐为基址的 +text_offset 字节处，并从该处被调用。当前，对 Linux 来说在此基址以下的 +内存是无法使用的，因此强烈建议将系统内存的起始作为这个基址。2MB 对齐 +基址和内核映像起始地址之间的区域对于内核来说没有特殊意义，且可能被 +用于其他目的。 +从映像起始地址算起，最少必须准备 image_size 字节的空闲内存供内核使用。 + +任何提供给内核的内存（甚至在映像起始地址之前），若未从内核中标记为保留 (如在设备树（dtb）的 memreserve 区域），都将被认为对内核是可用。 在跳转入内核前，必须符合以下状态： @@ -147,13 +159,16 @@ AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内 - 高速缓存、MMU MMU 必须关闭。 - 指令缓存开启或关闭都可以。 + 指令缓存开启或关闭皆可。 已载入的内核映像的相应内存区必须被清理，以达到缓存一致性点（PoC）。 - 当存在系统缓存或其他使能缓存的一致性主控器时，通常需使用虚拟地址维护其缓存，而非 set/way 操作。 + 当存在系统缓存或其他使能缓存的一致性主控器时，通常需使用虚拟地址 + 维护其缓存，而非 set/way 操作。 遵从通过虚拟地址操作维护构架缓存的系统缓存必须被配置，并可以被使能。 - 而不通过虚拟地址操作维护构架缓存的系统缓存（不推荐），必须被配置且禁用。 + 而不通过虚拟地址操作维护构架缓存的系统缓存（不推荐），必须被配置且 + 禁用。 - *译者注：对于 PoC 以及缓存相关内容，请参考 ARMv8 构架参考手册 ARM DDI 0487A + *译者注：对于 PoC 以及缓存相关内容，请参考 ARMv8 构架参考手册 + ARM DDI 0487A - 架构计时器 CNTFRQ 必须设定为计时器的频率，且 CNTVOFF 必须设定为对所有 CPU @@ -169,13 +184,21 @@ AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内 在进入内核映像的异常级中，所有构架中可写的系统寄存器必须通过软件 在一个更高的异常级别下初始化，以防止在 未知 状态下运行。 - 对于拥有 GICv3 中断控制器的系统： - - 若当前在 EL3 ： + 对于拥有 GICv3 中断控制器并以 v3 模式运行的系统： + - 如果 EL3 存在： ICC_SRE_EL3.Enable (位 3) 必须初始化为 0b1。 ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b1。 - 若内核运行在 EL1： ICC_SRE_EL2.Enable (位 3) 必须初始化为 0b1。 ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b1。 + - 设备树（DT）或 ACPI 表必须描述一个 GICv3 中断控制器。 + + 对于拥有 GICv3 中断控制器并以兼容（v2）模式运行的系统： + - 如果 EL3 存在： + ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b0。 + - 若内核运行在 EL1： + ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b0。 + - 设备树（DT）或 ACPI 表必须描述一个 GICv2 中断控制器。 以上对于 CPU 模式、高速缓存、MMU、架构计时器、一致性、系统寄存器的 必要条件描述适用于所有 CPU。所有 CPU 必须在同一异常级别跳入内核。 diff --git a/Documentation/zh_CN/arm64/silicon-errata.txt b/Documentation/zh_CN/arm64/silicon-errata.txt new file mode 100644 index 000000000000..39477c75c4a4 --- /dev/null +++ b/Documentation/zh_CN/arm64/silicon-errata.txt @@ -0,0 +1,74 @@ +Chinese translated version of Documentation/arm64/silicon-errata.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon <will.deacon@arm.com> +zh_CN: Fu Wei <wefu@redhat.com> +C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 +--------------------------------------------------------------------- +Documentation/arm64/silicon-errata.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Will Deacon <will.deacon@arm.com> +中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> +中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> +中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> +本文翻译提交时的 Git 检出点为： 1926e54f115725a9248d0c4c65c22acaf94de4c4 + +以下为正文 +--------------------------------------------------------------------- + 芯片勘误和软件补救措施 + ================== + +作者: Will Deacon <will.deacon@arm.com> +日期: 2015年11月27日 + +一个不幸的现实：硬件经常带有一些所谓的“瑕疵（errata）”，导致其在 +某些特定情况下会违背构架定义的行为。就基于 ARM 的硬件而言，这些瑕疵 +大体可分为以下几类： + + A 类：无可行补救措施的严重缺陷。 + B 类：有可接受的补救措施的重大或严重缺陷。 + C 类：在正常操作中不会显现的小瑕疵。 + +更多资讯，请在 infocenter.arm.com （需注册）中查阅“软件开发者勘误 +笔记”（“Software Developers Errata Notice”）文档。 + +对于 Linux 而言，B 类缺陷可能需要操作系统的某些特别处理。例如，避免 +一个特殊的代码序列，或是以一种特定的方式配置处理器。在某种不太常见的 +情况下，为将 A 类缺陷当作 C 类处理，可能需要用类似的手段。这些手段被 +统称为“软件补救措施”，且仅在少数情况需要（例如，那些需要一个运行在 +非安全异常级的补救措施 *并且* 能被 Linux 触发的情况）。 + +对于尚在讨论中的可能对未受瑕疵影响的系统产生干扰的软件补救措施，有一个 +相应的内核配置（Kconfig）选项被加在 “内核特性（Kernel Features）”-> +“基于可选方法框架的 ARM 瑕疵补救措施（ARM errata workarounds via +the alternatives framework）"。这些选项被默认开启，若探测到受影响的CPU， +补丁将在运行时被使用。至于对系统运行影响较小的补救措施，内核配置选项 +并不存在，且代码以某种规避瑕疵的方式被构造（带注释为宜）。 + +这种做法对于在任意内核源代码树中准确地判断出哪个瑕疵已被软件方法所补救 +稍微有点麻烦，所以在 Linux 内核中此文件作为软件补救措施的注册表， +并将在新的软件补救措施被提交和向后移植（backported）到稳定内核时被更新。 + +| 实现者 | 受影响的组件 | 勘误编号 | 内核配置 | ++----------------+-----------------+-----------------+-------------------------+ +| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | +| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | +| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | +| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | +| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | +| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | +| ARM | Cortex-A57 | #852523 | N/A | +| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | +| | | | | +| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | +| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | diff --git a/Documentation/zh_CN/filesystems/sysfs.txt b/Documentation/zh_CN/filesystems/sysfs.txt index e230eaa33122..7d3b05edb8ce 100644 --- a/Documentation/zh_CN/filesystems/sysfs.txt +++ b/Documentation/zh_CN/filesystems/sysfs.txt @@ -61,7 +61,7 @@ Documentation/kobject.txt 文档以获得更多关于 kobject 接口的 内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的 共同祖先；例如：某些对象属于某个子系统。 -Sysfs 在与其目录关联的 sysfs_dirent 对象中内部保存一个指向实现 +Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现 目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于 kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject 引用计数只能通过 sysfs_schedule_callback() 函数直接修改。 diff --git a/Documentation/zh_CN/video4linux/v4l2-framework.txt b/Documentation/zh_CN/video4linux/v4l2-framework.txt index 2b828e631e31..698660b7f21f 100644 --- a/Documentation/zh_CN/video4linux/v4l2-framework.txt +++ b/Documentation/zh_CN/video4linux/v4l2-framework.txt @@ -289,13 +289,13 @@ struct v4l2_subdev_ops { 然后，你必须用一个唯一的名字初始化 subdev->name，并初始化模块的 owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。 -若需同媒体框架整合，你必须调用 media_entity_init() 初始化 v4l2_subdev +若需同媒体框架整合，你必须调用 media_entity_pads_init() 初始化 v4l2_subdev 结构体中的 media_entity 结构体（entity 域）： struct media_pad *pads = &my_sd->pads; int err; - err = media_entity_init(&sd->entity, npads, pads, 0); + err = media_entity_pads_init(&sd->entity, npads, pads); pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和 name 域，但如有必要，revision 域必须初始化。 @@ -596,13 +596,13 @@ void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd); v4l2_file_operations 结构体是 file_operations 的一个子集。其主要 区别在于：因 inode 参数从未被使用，它将被忽略。 -如果需要与媒体框架整合，你必须通过调用 media_entity_init() 初始化 +如果需要与媒体框架整合，你必须通过调用 media_entity_pads_init() 初始化 嵌入在 video_device 结构体中的 media_entity（entity 域）结构体： struct media_pad *pad = &my_vdev->pad; int err; - err = media_entity_init(&vdev->entity, 1, pad, 0); + err = media_entity_pads_init(&vdev->entity, 1, pad); pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和 name 域。 |
